File: doc.lisp

package info (click to toggle)
acl2 8.6%2Bdfsg-3
links: PTS
area: main
in suites: sid
size: 1,138,276 kB
sloc: lisp: 17,818,294; java: 125,359; python: 28,122; javascript: 23,458; cpp: 18,851; ansic: 11,569; perl: 7,678; xml: 5,591; sh: 3,978; makefile: 3,840; ruby: 2,633; yacc: 1,126; ml: 763; awk: 295; csh: 233; lex: 197; php: 178; tcl: 49; asm: 23; haskell: 17
file content (170649 lines) | stat: -rw-r--r-- 7,700,848 bytes
parent folder | download | duplicates (2)
; Documentation for the ACL2 Theorem Prover
; WARNING: GENERATED FILE, DO NOT HAND EDIT!
; The contents of this file are derived from ACL2 Community Book
; books/system/doc/acl2-doc.lisp.

; ACL2 Version 8.6 -- A Computational Logic for Applicative Common Lisp
; Copyright (C) 2024, Regents of the University of Texas

; This version of ACL2 is a descendent of ACL2 Version 1.9, Copyright
; (C) 1997 Computational Logic, Inc.  See the documentation topic NOTE-2-0.

; This program is free software; you can redistribute it and/or modify
; it under the terms of the LICENSE file distributed with ACL2.

; 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.

; Here are the original authors of books/system/doc/acl2-doc.lisp.
; Additional contributions may have been made to that file by members
; of the ACL2 community.

; Written by:  Matt Kaufmann               and J Strother Moore
; email:       Kaufmann@cs.utexas.edu      and Moore@cs.utexas.edu
; Department of Computer Science
; University of Texas at Austin
; Austin, TX 78701 U.S.A.

; WARNING: This file is generated from ACL2 Community Book
; books/system/doc/acl2-doc.lisp.  To edit ACL2 documentation modify
; that file, not this one!  Instructions are just above the in-package
; form in that book.

(in-package "ACL2")

(defconst *acl2-system-documentation* '
((&ALLOW-OTHER-KEYS (POINTERS)
                    "See [macro-args].")
 (&BODY (POINTERS) "See [macro-args].")
 (&KEY (POINTERS) "See [macro-args].")
 (&OPTIONAL (POINTERS)
            "See [macro-args].")
 (&REST (POINTERS) "See [macro-args].")
 (&WHOLE (POINTERS) "See [macro-args].")
 (*
  (NUMBERS ACL2-BUILT-INS)
  "Multiplication macro

  [47m*[0m is really a macro that expands to calls of the function [47m[binary-*][0m.
  So for example

    (* x y 4 z)

  represents the same term as

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

  See [binary-*].

  [47m*[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.


Subtopics

  [Binary-*]
      Multiplication function")
 (*ACL2-EXPORTS*
  (PACKAGES ACL2-BUILT-INS)
  "Symbols that are often imported into new [packages] to provide easy
  access to ACL2 functionality.

  When you define a new package for your own work with [defpkg], you
  will usually want to import many symbols from the [47m\"ACL2\"[0m package;
  for instance you will usually want to be able to use symbols like
  [defthm], [in-theory], [xargs], [state], etc., without an [47macl2::[0m
  prefix.

  The constant [47m*acl2-exports*[0m lists [47m1659[0m symbols, including most
  documented ACL2 system constants, functions, and macros.  You will
  typically also want to import many symbols from Common Lisp; see
  [*common-lisp-symbols-from-main-lisp-package*].

  Those who write code using built-in ACL2 functions (see
  [ACL2-built-ins]) may wish to import symbols into their package
  from the large list [47m[*ACL2-system-exports*][0m.

    (& &allow-other-keys &aux &body &key
       &optional &rest &whole * *acl2-exports*
       *common-lisp-specials-and-constants*
       *common-lisp-symbols-from-main-lisp-package*
       *df-pi* *main-lisp-package-name*
       *standard-chars* *standard-ci*
       *standard-co* *standard-oi*
       + - / /= 1+ 1- < <-on-others
       <= = > >= ?-fn @ a! abort! abort-soft
       abs access accumulated-persistence
       accumulated-persistence-oops
       acl2-count acl2-input-channel-package
       acl2-number-listp acl2-numberp
       acl2-oracle acl2-output-channel-package
       acl2-package acl2-unwind-protect
       acons active-or-non-runep active-runep
       add-binop add-custom-keyword-hint
       add-default-hints add-default-hints!
       add-global-stobj add-include-book-dir
       add-include-book-dir!
       add-invisible-fns add-ld-keyword-alias
       add-ld-keyword-alias!
       add-macro-alias add-macro-fn
       add-match-free-override add-nth-alias
       add-override-hints add-override-hints!
       add-pair add-pair-preserves-all-boundp
       add-suffix add-suffix-to-fn add-timers
       add-to-set add-to-set-eq add-to-set-eql
       add-to-set-equal adjust-ld-history
       alistp alistp-forward-to-true-listp
       all-attachments
       all-boundp all-boundp-preserves-assoc
       all-vars all-vars1 all-vars1-lst
       allocate-fixnum-range alpha-char-p
       alpha-char-p-forward-to-characterp
       alphorder always$ always$+
       and and-macro append append$ append$+
       apply$ apply$-guard apply$-lambda
       apply$-lambda-guard apply$-userfn
       aref1 aref2 args arities-okp arity
       array1p array1p-cons array1p-forward
       array1p-linear array2p array2p-cons
       array2p-forward array2p-linear
       aset1 aset1-trusted aset2 ash assert$
       assert* assert-event assign assoc
       assoc-add-pair assoc-eq assoc-eq-equal
       assoc-eq-equal-alistp assoc-equal
       assoc-keyword assoc-string-equal assoc2
       associativity-of-* associativity-of-+
       assume atom atom-listp
       atom-listp-forward-to-true-listp
       attach-stobj backchain-limit
       badge badge-userfn binary-*
       binary-+ binary-append binary-df*
       binary-df+ binary-df-log binary-df/
       bind-free bit bitp boole$ boolean-listp
       boolean-listp-cons boolean-listp-forward
       boolean-listp-forward-to-symbol-listp
       booleanp booleanp-characterp
       booleanp-compound-recognizer
       bounded-integer-alistp
       bounded-integer-alistp-forward-to-eqlable-alistp
       bounded-integer-alistp2
       boundp-global boundp-global1 break$
       break-on-error brr brr-evisc-tuple
       brr-near-missp brr@ build-state1 butlast
       caaaar caaadr caaar caadar caaddr
       caadr caar cadaar cadadr cadar caddar
       cadddr caddr cadr canonical-pathname
       car car-cdr-elim car-cons case
       case-list case-list-check case-match
       case-split case-split-limitations
       case-test cbd cdaaar cdaadr
       cdaar cdadar cdaddr cdadr cdar cddaar
       cddadr cddar cdddar cddddr cdddr cddr
       cdr cdr-cons cdrn ceiling certify-book
       certify-book! change char char-code
       char-code-code-char-is-identity
       char-code-linear char-downcase
       char-equal char-upcase char< char<=
       char> char>= character character-alistp
       character-listp character-listp-append
       character-listp-coerce
       character-listp-forward-to-eqlable-listp
       character-listp-remove-duplicates-eql
       character-listp-revappend
       character-listp-string-downcase-1
       character-listp-string-upcase1-1
       characterp characterp-char-downcase
       characterp-char-upcase characterp-nth
       characterp-page characterp-return
       characterp-rubout characterp-tab
       check-invariant-risk check-vars-not-free
       checkpoint-forced-goals
       checkpoint-summary-limit
       clause clear-memoize-statistics
       clear-memoize-table clear-memoize-tables
       close-input-channel close-output-channel
       close-trace-file closure code-char
       code-char-char-code-is-identity
       code-char-type coerce coerce-inverse-1
       coerce-inverse-2 coerce-object-to-state
       coerce-state-to-object collect$
       collect$+ comment community-books
       commutativity-of-* commutativity-of-+
       comp compare-objects completion-of-*
       completion-of-+ completion-of-<
       completion-of-car completion-of-cdr
       completion-of-char-code
       completion-of-code-char
       completion-of-coerce
       completion-of-complex
       completion-of-denominator
       completion-of-imagpart
       completion-of-intern-in-package-of-symbol
       completion-of-numerator
       completion-of-realpart
       completion-of-symbol-name
       completion-of-symbol-package-name
       completion-of-unary-/
       completion-of-unary-minus
       complex complex-0
       complex-definition complex-equal
       complex-implies1 complex-rationalp
       complex/complex-rationalp
       compress1 compress11 compress2
       compress21 compress211 concatenate
       cond cond-clausesp cond-macro
       conjugate cons cons-equal cons-subtrees
       cons-with-hint consp consp-assoc-equal
       constraint-info corollary
       count-keys cpu-core-count ctx ctxp
       current-package current-theory cw cw!
       cw!+ cw+ cw-gstack cw-gstack-for-subterm
       cw-gstack-for-subterm*
       cw-gstack-for-term cw-gstack-for-term*
       cw-print-base-radix cw-print-base-radix!
       d< declare defabbrev
       defabsstobj defabsstobj-missing-events
       defattach defattach-system
       default default-*-1 default-*-2
       default-+-1 default-+-2 default-<-1
       default-<-2 default-backchain-limit
       default-car default-cdr
       default-char-code default-coerce-1
       default-coerce-2 default-coerce-3
       default-compile-fns default-complex-1
       default-complex-2 default-defun-mode
       default-defun-mode-from-state
       default-denominator
       default-hints default-imagpart
       default-measure-function
       default-numerator default-print-prompt
       default-realpart default-ruler-extenders
       default-state-vars default-symbol-name
       default-symbol-package-name
       default-total-parallelism-work-limit
       default-unary-/ default-unary-minus
       default-verify-guards-eagerness
       default-well-founded-relation
       defaxiom defbadge defchoose defcong
       defconst defequiv defevaluator defexec
       define-pc-atomic-macro define-pc-help
       define-pc-macro define-pc-meta
       define-trusted-clause-processor
       deflabel deflock defmacro defmacro-last
       defmacro-untouchable defn defnd defpkg
       defproxy defrec defrefinement defstobj
       defstub deftheory deftheory-static
       defthm defthm-std defthmd
       defthy defttag defun defun$ defun-df
       defun-inline defun-notinline defun-nx
       defun-sk defun-std defund defund-inline
       defund-notinline defund-nx defuns
       defuns-std defwarrant delete-assoc
       delete-assoc-eq delete-assoc-equal
       delete-file$ delete-include-book-dir
       delete-include-book-dir! denominator
       df* df+ df- df-abs df-abs-fn df-acos
       df-acos-fn df-acosh df-acosh-fn df-asin
       df-asin-fn df-asinh df-asinh-fn df-atan
       df-atan-fn df-atanh df-atanh-fn df-cos
       df-cos-fn df-cosh df-cosh-fn df-exp
       df-exp-fn df-expt df-expt-fn df-log
       df-minus-1 df-pi df-rationalize df-round
       df-sin df-sin-fn df-sinh df-sinh-fn
       df-sqrt df-sqrt-fn df-string df-tan
       df-tan-fn df-tanh df-tanh-fn df/ df/=-fn
       df0 df1 df< df<-fn df<= df= df=-fn
       df> df>= dfp digit-char-p digit-to-char
       dimensions disable disable-forcing
       disable-immediate-force-modep
       disable-ubt disabledp disassemble$
       distributivity dmr-start dmr-stop do$
       doc doc! docs doppelganger-apply$-userfn
       doppelganger-badge-userfn double-rewrite
       doublet-listp dumb-occur dumb-occur-var
       duplicates e/d e0-ord-< e0-ordinalp
       ec-call eighth eliminate-destructors
       eliminate-irrelevance
       enable enable-forcing
       enable-immediate-force-modep
       encapsulate endp eq eql eqlable-alistp
       eqlable-alistp-forward-to-alistp
       eqlable-listp
       eqlable-listp-forward-to-atom-listp
       eqlablep eqlablep-recog
       equal equal-char-code er er-cmp er-hard
       er-hard? er-let* er-let*-cmp er-progn
       er-progn-cmp er-progn-fn er-progn-fn@par
       er-progn@par er-soft er-soft-logic ev$
       ev$-list evenp evens event evisc-tuple
       executable-counterpart-theory
       exists exit
       explain-giant-lambda-object explode-atom
       explode-nonnegative-integer expt
       expt-type-prescription-non-zero-base
       extend-pathname
       extend-pe-table extend-world
       extra-info f-boundp-global f-get-global
       f-put-global fast-alist-clean
       fast-alist-clean! fast-alist-fork
       fast-alist-fork! fast-alist-free
       fast-alist-free-on-exit fast-alist-len
       fast-alist-summary fc-report fertilize
       fgetprop fifth file-clock file-clock-p
       file-clock-p-forward-to-integerp
       file-length$
       file-write-date$ finalize-event-user
       first first-n-ac fix fix-pkg
       fix-true-list flet floor flush-compress
       flush-hons-get-hash-table-link fms fms!
       fms!-to-string fms-to-string fmt fmt!
       fmt!-to-string fmt-hard-right-margin
       fmt-soft-right-margin
       fmt-to-comment-window
       fmt-to-comment-window!
       fmt-to-comment-window!+
       fmt-to-comment-window+
       fmt-to-string fmt1
       fmt1! fmt1!-to-string fmt1-to-string
       fmx fmx!-cw fmx-cw fn-equal
       fncall-term forall force formula fourth
       from-df function-symbolp function-theory
       gag-mode gc$ gc-strategy gc-verbose
       gcs generalize get-check-invariant-risk
       get-command-sequence
       get-cpu-time get-defun-event get-dwp
       get-enforce-redundancy get-event-data
       get-global get-guard-checking
       get-in-theory-redundant-okp
       get-output-stream-string$
       get-persistent-whs get-real-time
       get-register-invariant-risk
       get-serialize-character
       get-slow-alist-action get-timer
       get-wormhole-status getenv$ getprop
       getprop-default getpropc getprops
       getprops1 global-table global-table-cars
       global-table-cars1 global-val
       good-bye granularity ground-zero gthm
       guard guard-obligation guard-theorem
       hands-off-lambda-objects-theory
       hard-error
       has-propsp has-propsp1 header help
       hide hist hons hons-acons hons-acons!
       hons-assoc-equal hons-clear hons-clear!
       hons-copy hons-copy-persistent
       hons-equal hons-equal-lite
       hons-get hons-resize hons-resize-fn
       hons-shrink-alist hons-shrink-alist!
       hons-summary hons-wash
       hons-wash! i-am-here i-close i-large
       i-limited i-small id idates identity
       if if* iff iff-implies-equal-implies-1
       iff-implies-equal-implies-2
       iff-implies-equal-not
       iff-is-an-equivalence ifix ignorable
       ignore illegal imagpart imagpart-complex
       immediate-force-modep implies
       improper-consp in-arithmetic-theory
       in-package in-tau-intervalp in-theory
       include-book incompatible incompatible!
       increment-file-clock increment-timer
       induct induction-depth-limit
       initialize-event-user
       int= integer integer-0 integer-1
       integer-abs integer-implies-rational
       integer-length integer-listp
       integer-listp-forward-to-rational-listp
       integer-range-p
       integer-step integerp intern
       intern$ intern-in-package-of-symbol
       intern-in-package-of-symbol-symbol-name
       intersection$
       intersection-eq intersection-equal
       intersection-theories intersectp
       intersectp-eq intersectp-equal
       inverse-of-* inverse-of-+
       invisible-fns-table irrelevant
       keyword-package keyword-value-listp
       keyword-value-listp-assoc-keyword
       keyword-value-listp-forward-to-true-listp
       keywordp keywordp-forward-to-symbolp
       known-package-alist known-package-alistp
       known-package-alistp-forward-to-true-list-listp-and-alistp
       kwote kwote-lst l< lambda
       lambda$ last last-cdr last-prover-steps
       ld ld-always-skip-top-level-locals
       ld-error-action
       ld-error-triples ld-evisc-tuple
       ld-history ld-history-entry-error-flg
       ld-history-entry-input
       ld-history-entry-stobjs-out
       ld-history-entry-stobjs-out/value
       ld-history-entry-user-data
       ld-history-entry-value
       ld-keyword-aliases
       ld-missing-input-ok ld-post-eval-print
       ld-pre-eval-filter ld-pre-eval-print
       ld-prompt ld-query-control-alist
       ld-redefinition-action ld-skip-proofsp
       ld-user-stobjs-modified-warning
       ld-verbose
       legal-case-clausesp len len-update-nth
       length let let* let-mbe lex-fix lexorder
       lexp list list$ list* list*-macro
       list-macro listp local logand
       logandc1 logandc2 logbitp logcount
       logeqv logic logic-fns-list-listp
       logic-fns-listp logic-fnsp
       logic-term-list-listp logic-term-listp
       logic-termp logior lognand lognor lognot
       logorc1 logorc2 logtest logxor loop$
       lower-case-p lower-case-p-char-downcase
       lower-case-p-forward-to-alpha-char-p
       lowest-terms lp macro-aliases
       macro-args macrolet magic-ev-fncall
       main-timer main-timer-type-prescription
       make make-character-list
       make-character-list-make-character-list
       make-event
       make-fast-alist make-fmt-bindings
       make-input-channel make-list
       make-list-ac make-mv-nths make-ord
       make-output-channel make-summary-data
       make-tau-interval make-var-lst
       make-var-lst1 make-wormhole-status
       makunbound-global max maximum-length
       may-need-slashes maybe-convert-to-mv
       maybe-flush-and-compress1
       mbe mbt mbt* member member-eq
       member-equal member-symbol-name
       memoize memoize-partial memoize-summary
       memsum meta-extract-contextual-fact
       meta-extract-formula
       meta-extract-global-fact
       meta-extract-global-fact+
       meta-extract-rw+-term mfc mfc-ancestors
       mfc-ap mfc-clause mfc-rdepth
       mfc-relieve-hyp mfc-rw mfc-rw+ mfc-ts
       mfc-type-alist mfc-unify-subst mfc-world
       min minimal-theory minusp mod mod-expt
       monitor monitor! monitored-runes more
       more! more-doc msg msgp must-be-equal
       mutual-recursion mutual-recursion-guardp
       mv mv-let mv-list mv-nth mv? mv?-let
       nat-listp natp near-misses needs-slashes
       never-memoize newline nfix nfix-list nil
       nil-is-not-circular ninth no-duplicatesp
       no-duplicatesp-eq no-duplicatesp-equal
       non-exec nonnegative-integer-quotient
       nonnegative-product nonzero-imagpart
       not nqthm-to-acl2 nth nth-0-cons
       nth-0-read-run-time-type-prescription
       nth-add1 nth-aliases nth-update-nth
       nthcdr null number-subtrees
       numerator o-finp o-first-coeff
       o-first-expt o-infp o-p o-rst
       o< o<= o> o>= observation observation-cw
       oddp odds ok-if old-and-new-event-data
       oops open-channel-listp open-channel1
       open-channel1-forward-to-true-listp-and-consp
       open-channels-p open-channels-p-forward
       open-input-channel
       open-input-channel-any-p
       open-input-channel-any-p1
       open-input-channel-p
       open-input-channel-p1
       open-input-channels
       open-output-channel open-output-channel!
       open-output-channel-any-p
       open-output-channel-any-p1
       open-output-channel-p
       open-output-channel-p1
       open-output-channels
       open-trace-file optimize
       or or-macro ordered-symbol-alistp
       ordered-symbol-alistp-add-pair
       ordered-symbol-alistp-add-pair-forward
       ordered-symbol-alistp-forward-to-symbol-alistp
       ordered-symbol-alistp-getprops
       ordered-symbol-alistp-remove1-assoc-eq
       otherwise our-digit-char-p
       override-hints p! pairlis$
       pairlis2 pand pargs partial-encapsulate
       partition-rest-and-keyword-args
       pbt pc pcb pcb!
       pcs pe pe! peek-char$ pf pkg-imports
       pkg-witness pl pl2 plet plist-worldp
       plist-worldp-forward-to-assoc-eq-equal-alistp
       plusp pointers pop-timer por position
       position-ac position-eq position-eq-ac
       position-equal position-equal-ac
       positive posp power-eval pprogn pr
       pr! preprocess prin1$ prin1-with-slashes
       prin1-with-slashes1 princ$ print-base-p
       print-cl-cache print-gv print-object$
       print-object$+ print-object$-fn
       print-object$-preserving-case
       print-rational-as-decimal
       print-timer profile prog2$ progn
       progn! progn$ program project-dir-alist
       proof-tree proofs-co proper-consp
       props prove pseudo-term-listp
       pseudo-term-listp-forward-to-true-listp
       pseudo-termp
       pso pso! psof psog pspv pstack
       puff puff* push-timer push-untouchable
       put-assoc put-assoc-eq put-assoc-eql
       put-assoc-equal put-global putprop
       quick-and-dirty-subsumption-replacement-step
       quit quote quotep
       quote~ r-eqlable-alistp r-symbol-alistp
       random$ rassoc rassoc-eq rassoc-equal
       ratio rational rational-implies1
       rational-implies2 rational-listp
       rational-listp-forward-to-true-listp
       rationalp rationalp-* rationalp-+
       rationalp-expt-type-prescription
       rationalp-implies-acl2-numberp
       rationalp-unary--
       rationalp-unary-/ read-acl2-oracle
       read-acl2-oracle-preserves-state-p1
       read-byte$ read-char$
       read-file-into-string read-file-listp
       read-file-listp-forward-to-true-list-listp
       read-file-listp1
       read-file-listp1-forward-to-true-listp-and-consp
       read-files read-files-p
       read-files-p-forward-to-read-file-listp
       read-idate
       read-object read-object-suppress
       read-object-with-case read-run-time
       read-run-time-preserves-state-p1
       readable-file
       readable-file-forward-to-true-listp-and-consp
       readable-files readable-files-listp
       readable-files-listp-forward-to-true-list-listp-and-alistp
       readable-files-p
       readable-files-p-forward-to-readable-files-listp
       real-listp
       real/rationalp realfix realpart
       realpart-complex realpart-imagpart-elim
       rebuild redef redef! redef+
       redef- redo-flat regenerate-tau-database
       rem remove remove-assoc
       remove-assoc-eq remove-assoc-equal
       remove-binop remove-custom-keyword-hint
       remove-default-hints
       remove-default-hints!
       remove-duplicates remove-duplicates-eq
       remove-duplicates-eql
       remove-duplicates-equal
       remove-eq remove-equal
       remove-global-stobj remove-guard-holders
       remove-invisible-fns
       remove-macro-alias remove-macro-fn
       remove-nth-alias remove-override-hints
       remove-override-hints!
       remove-untouchable remove1 remove1-assoc
       remove1-assoc-eq remove1-assoc-equal
       remove1-eq remove1-equal
       reset-fc-reporting reset-kill-ring
       reset-ld-specials reset-prehistory
       reset-print-control resize-list
       rest restore-memoization-settings
       retract-world
       retrieve return-last return-last-table
       revappend reverse revert-world
       rewrite-equiv rewrite-lambda-modep
       rewrite-lambda-objects-theory
       rewrite-quoted-constant
       rewrite-stack-limit rfix
       rize round runes-diff rw-cache satisfies
       save-and-clear-memoization-settings
       save-exec saving-event-data
       search second serialize-read
       serialize-write set-absstobj-debug
       set-accumulated-persistence
       set-backchain-limit
       set-bad-lisp-consp-memoize
       set-body set-bogus-defun-hints-ok
       set-bogus-measure-ok
       set-bogus-mutual-recursion-ok
       set-brr-evisc-tuple
       set-case-split-limitations
       set-cbd set-check-invariant-risk
       set-checkpoint-summary-limit
       set-compile-fns
       set-compiler-enabled set-debugger-enable
       set-default-backchain-limit
       set-default-hints set-default-hints!
       set-deferred-ttag-notes set-difference$
       set-difference-eq set-difference-equal
       set-difference-theories
       set-duplicate-keys-action
       set-duplicate-keys-action!
       set-dwp set-dwp!
       set-enforce-redundancy set-equalp-equal
       set-evisc-tuple set-fast-cert
       set-fc-criteria set-fc-report-on-the-fly
       set-fmt-hard-right-margin
       set-fmt-soft-right-margin set-gag-mode
       set-gc-strategy set-guard-checking
       set-guard-msg set-ignore-ok
       set-in-theory-redundant-okp
       set-induction-depth-limit
       set-induction-depth-limit!
       set-inhibit-er
       set-inhibit-er! set-inhibit-output-lst
       set-inhibit-warnings
       set-inhibit-warnings!
       set-inhibited-summary-types
       set-invisible-fns-table
       set-iprint set-irrelevant-formals-ok
       set-ld-always-skip-top-level-locals
       set-ld-error-action
       set-ld-error-triples set-ld-evisc-tuple
       set-ld-keyword-aliases
       set-ld-keyword-aliases!
       set-ld-missing-input-ok
       set-ld-post-eval-print
       set-ld-pre-eval-filter
       set-ld-pre-eval-print
       set-ld-prompt set-ld-query-control-alist
       set-ld-redefinition-action
       set-ld-skip-proofs set-ld-skip-proofsp
       set-ld-user-stobjs-modified-warning
       set-ld-verbose set-let*-abstraction
       set-let*-abstractionp
       set-match-free-default
       set-match-free-error
       set-measure-function
       set-non-linear set-non-linearp
       set-override-hints set-override-hints!
       set-parallel-execution
       set-persistent-whs-and-ephemeral-whs
       set-print-base set-print-base-radix
       set-print-case set-print-circle
       set-print-clause-ids set-print-escape
       set-print-gv-defaults set-print-length
       set-print-level set-print-lines
       set-print-radix set-print-readably
       set-print-right-margin
       set-proofs-co set-prover-step-limit
       set-raw-mode set-raw-mode-on
       set-raw-mode-on! set-raw-proof-format
       set-raw-warning-format
       set-register-invariant-risk
       set-rewrite-stack-limit
       set-ruler-extenders
       set-rw-cache-state set-rw-cache-state!
       set-serialize-character
       set-serialize-character-system
       set-skip-meta-termp-checks
       set-skip-meta-termp-checks!
       set-slow-alist-action
       set-splitter-output
       set-standard-co set-standard-oi
       set-state-ok set-table-guard
       set-tau-auto-mode set-temp-touchable-fns
       set-temp-touchable-vars set-timer
       set-total-parallelism-work-limit
       set-total-parallelism-work-limit-error
       set-trace-co set-trace-evisc-tuple
       set-verify-guards-eagerness
       set-w set-warnings-as-errors
       set-waterfall-parallelism
       set-waterfall-parallelism-hacks-enabled
       set-waterfall-parallelism-hacks-enabled!
       set-waterfall-printing
       set-well-founded-relation
       set-wormhole-data
       set-wormhole-entry-code
       set-write-acl2x setenv$ seventh
       sgetprop show-accumulated-persistence
       show-bdd show-bodies
       show-custom-keyword-hint-expansion
       show-fc-criteria signed-byte
       signed-byte-p signum simplify
       sixth skip-proofs sleep some-slashable
       spec-mv-let splitter-output
       stable-under-simplificationp
       standard-char standard-char-listp
       standard-char-listp-append
       standard-char-listp-forward-to-character-listp
       standard-char-p standard-char-p+
       standard-char-p-nth standard-co
       standard-oi standard-part standardp
       start-proof-tree state state-global-let*
       state-global-let*-cleanup
       state-global-let*-get-globals
       state-global-let*-put-globals
       state-p state-p+
       state-p-implies-and-forward-to-state-p1
       state-p1 state-p1-forward
       state-p1-update-main-timer
       state-p1-update-nth-2-world
       step-limit stobj-let stobj-table
       stop-proof-tree string string-alistp
       string-append string-append-lst
       string-downcase string-downcase1
       string-equal string-equal1
       string-is-not-circular string-listp
       string-upcase string-upcase1
       string< string<-irreflexive
       string<-l string<-l-asymmetric
       string<-l-irreflexive
       string<-l-transitive
       string<-l-trichotomy
       string<= string> string>=
       stringp stringp-symbol-package-name
       strip-cars strip-cdrs sublis sublis-fn
       sublis-fn-lst-simple sublis-fn-simple
       subseq subseq-list subsequencep
       subsetp subsetp-eq subsetp-equal
       subst substitute substitute-ac
       suitably-tamep-listp sum$ sum$+
       summary swap-stobjs symbol symbol-alistp
       symbol-alistp-forward-to-eqlable-alistp
       symbol-doublet-listp
       symbol-equality symbol-listp
       symbol-listp-forward-to-true-listp
       symbol-name
       symbol-name-intern-in-package-of-symbol
       symbol-name-lst symbol-package-name
       symbol< symbol<-asymmetric
       symbol<-irreflexive symbol<-transitive
       symbol<-trichotomy symbolp
       symbolp-intern-in-package-of-symbol
       sync-ephemeral-whs-with-persistent-whs
       synp
       syntactically-clean-lambda-objects-theory
       syntaxp sys-call sys-call* sys-call+
       sys-call-status t table table-alist
       take tamep tamep-functionp tamep-lambdap
       tau-data tau-database tau-interval-dom
       tau-interval-hi tau-interval-hi-rel
       tau-interval-lo tau-interval-lo-rel
       tau-intervalp tau-status tau-system tc
       tca tcp tenth term-list-listp term-listp
       term-order termination-theorem
       termp the the-check the-fixnum
       the-fixnum! the-number the-true-list
       theory theory-invariant thereis$
       thereis$+ third thm time$ time-tracker
       time-tracker-tau timer-alistp
       timer-alistp-forward-to-true-list-listp-and-symbol-alistp
       to-df to-dfp
       toggle-inhibit-er toggle-inhibit-er!
       toggle-inhibit-warning
       toggle-inhibit-warning! toggle-pc-macro
       top-level trace! trace$ trace*
       trace-co trans trans! trans* trans*-
       trans-eval trans-eval-default-warning
       trans-eval-no-warning
       trans1 translam translate-and-test
       trichotomy true-list-fix true-list-listp
       true-list-listp-forward-to-true-listp
       true-list-listp-forward-to-true-listp-assoc-equal
       true-listp
       true-listp-cadr-assoc-eq-for-open-channels-p
       true-listp-update-nth truncate trust-mfc
       ttag ttags-seen tthm type typed-io-listp
       typed-io-listp-forward-to-true-listp
       typespec-check u ubt ubt! ubt-prehistory
       ubt? ubu ubu! ubu? unary--
       unary-/ unary-df- unary-df-log unary-df/
       unary-function-symbol-listp unicity-of-0
       unicity-of-1 union$ union-eq union-equal
       union-theories universal-theory
       unmemoize unmonitor unquote
       unsave unsigned-byte unsigned-byte-p
       until$ until$+ untouchable-marker
       untrace$ untrans-table
       untranslate update-acl2-oracle
       update-acl2-oracle-preserves-state-p1
       update-file-clock
       update-global-table update-idates
       update-nth update-nth-array
       update-open-input-channels
       update-open-output-channels
       update-read-files
       update-user-stobj-alist
       update-user-stobj-alist1
       update-written-files
       upper-case-p upper-case-p-char-upcase
       upper-case-p-forward-to-alpha-char-p
       user-stobj-alist user-stobj-alist1 value
       value-cmp value-triple verbose-pstack
       verify verify-guard-implication
       verify-guards verify-guards+
       verify-guards-formula verify-termination
       w walkabout warning! warrant
       waterfall-parallelism waterfall-printing
       weak-ld-history-entry-p
       well-formed-lambda-objectp
       wet when$ when$+ with-brr-data with-cbd
       with-current-package with-fast-alist
       with-global-stobj with-guard-checking
       with-guard-checking-error-triple
       with-guard-checking-event
       with-live-state
       with-local-state with-local-stobj
       with-output with-output!
       with-output-lock with-prover-step-limit
       with-prover-step-limit!
       with-prover-time-limit
       with-serialize-character
       with-stolen-alist without-evisc
       wof world wormhole wormhole-data
       wormhole-entry-code wormhole-eval
       wormhole-p wormhole-statusp
       wormhole1 writable-file-listp
       writable-file-listp-forward-to-true-list-listp
       writable-file-listp1
       writable-file-listp1-forward-to-true-listp-and-consp
       write-byte$
       writeable-files writeable-files-p
       writeable-files-p-forward-to-writable-file-listp
       written-file
       written-file-forward-to-true-listp-and-consp
       written-file-listp
       written-file-listp-forward-to-true-list-listp-and-alistp
       written-files written-files-p
       written-files-p-forward-to-written-file-listp
       xargs xor xxxjoin zero zerop zip zp zpf)")
 (*COMMON-LISP-SYMBOLS-FROM-MAIN-LISP-PACKAGE*
  (PACKAGES ACL2-BUILT-INS)
  "Symbols that are often imported into new packages to provide easy
  access to Common Lisp functionality.

  When you define a new package for your own work with [defpkg], you
  will usually want to import many symbols from the [47m\"COMMON-LISP\"[0m
  package so that you can access them without a [47mcommon-lisp::[0m or
  [47macl2::[0m prefix.

  The constant [47m*common-lisp-symbols-from-main-lisp-package*[0m lists the
  [47m978[0m symbols of the [47mCOMMON-LISP[0m package found in {dpAns |
  http://dx.doi.org/10.1145/147135.147249}.  You will typically also
  want to import many symbols from ACL2; see [*ACL2-exports*].

    (&allow-other-keys *print-miser-width*
                       &aux *print-pprint-dispatch*
                       &body *print-pretty*
                       &environment *print-radix*
                       &key *print-readably* &optional
                       *print-right-margin* &rest *query-io*
                       &whole *random-state* * *read-base*
                       ** *read-default-float-format*
                       *** *read-eval* *break-on-signals*
                       *read-suppress* *compile-file-pathname*
                       *readtable* *compile-file-truename*
                       *standard-input* *compile-print*
                       *standard-output* *compile-verbose*
                       *terminal-io* *debug-io*
                       *trace-output* *debugger-hook*
                       + *default-pathname-defaults*
                       ++ *error-output* +++ *features*
                       - *gensym-counter* / *load-pathname*
                       // *load-print* /// *load-truename*
                       /= *load-verbose* 1+ *macroexpand-hook*
                       1- *modules* < *package*
                       <= *print-array* = *print-base*
                       > *print-case* >= *print-circle*
                       abort *print-escape* abs *print-gensym*
                       acons *print-length* acos *print-level*
                       acosh *print-lines* add-method adjoin
                       atom boundp adjust-array base-char
                       break adjustable-array-p base-string
                       broadcast-stream allocate-instance
                       bignum broadcast-stream-streams
                       alpha-char-p bit built-in-class
                       alphanumericp bit-and butlast
                       and bit-andc1 byte append bit-andc2
                       byte-position apply bit-eqv byte-size
                       apropos bit-ior caaaar apropos-list
                       bit-nand caaadr aref bit-nor
                       caaar arithmetic-error bit-not caadar
                       arithmetic-error-operands bit-orc1
                       caaddr arithmetic-error-operation
                       bit-orc2 caadr array bit-vector
                       caar array-dimension bit-vector-p
                       cadaar array-dimension-limit
                       bit-xor cadadr array-dimensions
                       block cadar array-displacement
                       boole caddar array-element-type
                       boole-1 cadddr array-has-fill-pointer-p
                       boole-2 caddr array-in-bounds-p
                       boole-and cadr array-rank
                       boole-andc1 call-arguments-limit
                       array-rank-limit boole-andc2 call-method
                       array-row-major-index boole-c1
                       call-next-method array-total-size
                       boole-c2 car array-total-size-limit
                       boole-clr case arrayp
                       boole-eqv catch ash boole-ior ccase
                       asin boole-nand cdaaar asinh boole-nor
                       cdaadr assert boole-orc1 cdaar assoc
                       boole-orc2 cdadar assoc-if boole-set
                       cdaddr assoc-if-not boole-xor cdadr
                       atan boolean cdar atanh both-case-p
                       cddaar cddadr clear-input copy-tree
                       cddar clear-output cos cdddar close cosh
                       cddddr clrhash count cdddr code-char
                       count-if cddr coerce count-if-not
                       cdr compilation-speed ctypecase
                       ceiling compile debug cell-error
                       compile-file decf cell-error-name
                       compile-file-pathname declaim
                       cerror compiled-function declaration
                       change-class compiled-function-p
                       declare char compiler-macro decode-float
                       char-code compiler-macro-function
                       decode-universal-time
                       char-code-limit complement defclass
                       char-downcase complex defconstant
                       char-equal complexp defgeneric
                       char-greaterp compute-applicable-methods
                       define-compiler-macro
                       char-int compute-restarts
                       define-condition char-lessp
                       concatenate define-method-combination
                       char-name concatenated-stream
                       define-modify-macro char-not-equal
                       concatenated-stream-streams
                       define-setf-expander char-not-greaterp
                       cond define-symbol-macro char-not-lessp
                       condition defmacro char-upcase conjugate
                       defmethod char/= cons defpackage
                       char< consp defparameter char<=
                       constantly defsetf char= constantp
                       defstruct char> continue deftype
                       char>= control-error defun character
                       copy-alist defvar characterp copy-list
                       delete check-type copy-pprint-dispatch
                       delete-duplicates cis copy-readtable
                       delete-file class copy-seq delete-if
                       class-name copy-structure delete-if-not
                       class-of copy-symbol delete-package
                       denominator eq deposit-field
                       eql describe equal describe-object
                       equalp destructuring-bind
                       error digit-char etypecase
                       digit-char-p eval directory eval-when
                       directory-namestring evenp disassemble
                       every division-by-zero exp do export
                       do* expt do-all-symbols extended-char
                       do-external-symbols fboundp do-symbols
                       fceiling documentation fdefinition
                       dolist ffloor dotimes fifth double-float
                       file-author double-float-epsilon
                       file-error double-float-negative-epsilon
                       file-error-pathname dpb file-length
                       dribble file-namestring dynamic-extent
                       file-position ecase file-stream
                       echo-stream file-string-length
                       echo-stream-input-stream file-write-date
                       echo-stream-output-stream
                       fill ed fill-pointer
                       eighth find elt find-all-symbols
                       encode-universal-time find-class
                       end-of-file find-if endp find-if-not
                       enough-namestring find-method
                       ensure-directories-exist find-package
                       ensure-generic-function find-restart
                       find-symbol get-internal-run-time
                       finish-output get-macro-character
                       first get-output-stream-string fixnum
                       get-properties flet get-setf-expansion
                       float get-universal-time float-digits
                       getf float-precision gethash
                       float-radix go float-sign graphic-char-p
                       floating-point-inexact handler-bind
                       floating-point-invalid-operation
                       handler-case floating-point-overflow
                       hash-table floating-point-underflow
                       hash-table-count floatp hash-table-p
                       floor hash-table-rehash-size fmakunbound
                       hash-table-rehash-threshold force-output
                       hash-table-size format hash-table-test
                       formatter host-namestring
                       fourth identity fresh-line
                       if fround ignorable ftruncate ignore
                       ftype ignore-errors funcall imagpart
                       function import function-keywords
                       in-package function-lambda-expression
                       incf functionp initialize-instance
                       gcd inline generic-function
                       input-stream-p gensym inspect
                       gentemp integer get integer-decode-float
                       get-decoded-time integer-length
                       get-dispatch-macro-character
                       integerp get-internal-real-time
                       interactive-stream-p
                       intern lisp-implementation-type
                       internal-time-units-per-second
                       lisp-implementation-version
                       intersection list invalid-method-error
                       list* invoke-debugger
                       list-all-packages invoke-restart
                       list-length invoke-restart-interactively
                       listen isqrt listp keyword load keywordp
                       load-logical-pathname-translations
                       labels load-time-value
                       lambda locally lambda-list-keywords
                       log lambda-parameters-limit
                       logand last logandc1 lcm
                       logandc2 ldb logbitp ldb-test logcount
                       ldiff logeqv least-negative-double-float
                       logical-pathname
                       least-negative-long-float
                       logical-pathname-translations
                       least-negative-normalized-double-float
                       logior
                       least-negative-normalized-long-float
                       lognand
                       least-negative-normalized-short-float
                       lognor
                       least-negative-normalized-single-float
                       lognot least-negative-short-float
                       logorc1 least-negative-single-float
                       logorc2 least-positive-double-float
                       logtest least-positive-long-float logxor
                       least-positive-normalized-double-float
                       long-float
                       least-positive-normalized-long-float
                       long-float-epsilon
                       least-positive-normalized-short-float
                       long-float-negative-epsilon
                       least-positive-normalized-single-float
                       long-site-name
                       least-positive-short-float loop
                       least-positive-single-float loop-finish
                       length lower-case-p let machine-instance
                       let* machine-type machine-version
                       mask-field macro-function
                       max macroexpand member macroexpand-1
                       member-if macrolet member-if-not
                       make-array merge make-broadcast-stream
                       merge-pathnames make-concatenated-stream
                       method make-condition method-combination
                       make-dispatch-macro-character
                       method-combination-error
                       make-echo-stream method-qualifiers
                       make-hash-table min make-instance
                       minusp make-instances-obsolete
                       mismatch make-list mod make-load-form
                       most-negative-double-float
                       make-load-form-saving-slots
                       most-negative-fixnum
                       make-method most-negative-long-float
                       make-package most-negative-short-float
                       make-pathname most-negative-single-float
                       make-random-state
                       most-positive-double-float
                       make-sequence most-positive-fixnum
                       make-string most-positive-long-float
                       make-string-input-stream
                       most-positive-short-float
                       make-string-output-stream
                       most-positive-single-float
                       make-symbol muffle-warning
                       make-synonym-stream multiple-value-bind
                       make-two-way-stream multiple-value-call
                       makunbound multiple-value-list
                       map multiple-value-prog1
                       map-into multiple-value-setq mapc
                       multiple-values-limit mapcan name-char
                       mapcar namestring mapcon nbutlast
                       maphash nconc mapl next-method-p
                       maplist nil nintersection package-error
                       ninth package-error-package
                       no-applicable-method package-name
                       no-next-method package-nicknames
                       not package-shadowing-symbols
                       notany package-use-list notevery
                       package-used-by-list notinline packagep
                       nreconc pairlis nreverse parse-error
                       nset-difference parse-integer
                       nset-exclusive-or parse-namestring
                       nstring-capitalize pathname
                       nstring-downcase pathname-device
                       nstring-upcase pathname-directory
                       nsublis pathname-host nsubst
                       pathname-match-p nsubst-if pathname-name
                       nsubst-if-not pathname-type nsubstitute
                       pathname-version nsubstitute-if
                       pathnamep nsubstitute-if-not
                       peek-char nth phase nth-value pi nthcdr
                       plusp null pop number position numberp
                       position-if numerator position-if-not
                       nunion pprint oddp pprint-dispatch
                       open pprint-exit-if-list-exhausted
                       open-stream-p pprint-fill
                       optimize pprint-indent or pprint-linear
                       otherwise pprint-logical-block
                       output-stream-p pprint-newline
                       package pprint-pop pprint-tab read-char
                       pprint-tabular read-char-no-hang
                       prin1 read-delimited-list
                       prin1-to-string read-from-string
                       princ read-line princ-to-string
                       read-preserving-whitespace
                       print read-sequence print-not-readable
                       reader-error print-not-readable-object
                       readtable print-object
                       readtable-case print-unreadable-object
                       readtablep probe-file
                       real proclaim realp prog realpart
                       prog* reduce prog1 reinitialize-instance
                       prog2 rem progn remf program-error
                       remhash progv remove provide
                       remove-duplicates psetf remove-if
                       psetq remove-if-not push remove-method
                       pushnew remprop quote rename-file
                       random rename-package random-state
                       replace random-state-p require rassoc
                       rest rassoc-if restart rassoc-if-not
                       restart-bind ratio restart-case
                       rational restart-name rationalize return
                       rationalp return-from read revappend
                       read-byte reverse room simple-bit-vector
                       rotatef simple-bit-vector-p
                       round simple-condition row-major-aref
                       simple-condition-format-arguments
                       rplaca simple-condition-format-control
                       rplacd simple-error
                       safety simple-string satisfies
                       simple-string-p sbit simple-type-error
                       scale-float simple-vector schar
                       simple-vector-p search simple-warning
                       second sin sequence single-float
                       serious-condition single-float-epsilon
                       set single-float-negative-epsilon
                       set-difference
                       sinh set-dispatch-macro-character
                       sixth set-exclusive-or
                       sleep set-macro-character slot-boundp
                       set-pprint-dispatch slot-exists-p
                       set-syntax-from-char slot-makunbound
                       setf slot-missing setq slot-unbound
                       seventh slot-value shadow software-type
                       shadowing-import software-version
                       shared-initialize some shiftf sort
                       short-float space short-float-epsilon
                       special short-float-negative-epsilon
                       special-operator-p short-site-name
                       speed signal sqrt signed-byte
                       stable-sort signum standard simple-array
                       standard-char simple-base-string
                       standard-char-p standard-class
                       sublis standard-generic-function subseq
                       standard-method subsetp standard-object
                       subst step subst-if storage-condition
                       subst-if-not store-value substitute
                       stream substitute-if stream-element-type
                       substitute-if-not stream-error
                       subtypep stream-error-stream
                       svref stream-external-format
                       sxhash streamp symbol
                       string symbol-function string-capitalize
                       symbol-macrolet string-downcase
                       symbol-name string-equal symbol-package
                       string-greaterp symbol-plist
                       string-left-trim symbol-value
                       string-lessp symbolp string-not-equal
                       synonym-stream string-not-greaterp
                       synonym-stream-symbol string-not-lessp t
                       string-right-trim tagbody string-stream
                       tailp string-trim tan string-upcase
                       tanh string/= tenth string< terpri
                       string<= the string= third string>
                       throw string>= time stringp trace
                       structure translate-logical-pathname
                       structure-class
                       translate-pathname structure-object
                       tree-equal style-warning truename
                       truncate values-list two-way-stream
                       variable two-way-stream-input-stream
                       vector two-way-stream-output-stream
                       vector-pop type vector-push type-error
                       vector-push-extend type-error-datum
                       vectorp type-error-expected-type
                       warn type-of warning typecase
                       when typep wild-pathname-p unbound-slot
                       with-accessors unbound-slot-instance
                       with-compilation-unit
                       unbound-variable with-condition-restarts
                       undefined-function
                       with-hash-table-iterator
                       unexport with-input-from-string unintern
                       with-open-file union with-open-stream
                       unless with-output-to-string unread-char
                       with-package-iterator unsigned-byte
                       with-simple-restart untrace with-slots
                       unuse-package with-standard-io-syntax
                       unwind-protect write
                       update-instance-for-different-class
                       write-byte
                       update-instance-for-redefined-class
                       write-char upgraded-array-element-type
                       write-line upgraded-complex-part-type
                       write-sequence upper-case-p
                       write-string use-package write-to-string
                       use-value y-or-n-p user-homedir-pathname
                       yes-or-no-p values zerop)")
 (*DF-PI* (POINTERS) "See [df].")
 (*STANDARD-CI*
  (IO ACL2-BUILT-INS)
  "An ACL2 character-based analogue of CLTL's [47m*standard-input*[0m

  The value of the ACL2 constant [47m*standard-ci*[0m is an open character
  input channel that is synonymous to Common Lisp's [47m*standard-input*[0m.

  ACL2 character input from [47m*standard-ci*[0m is actually obtained by
  reading [characters] from the stream named by Common Lisp's
  [47m*standard-input*[0m.  That is, by changing the setting of
  [47m*standard-input*[0m in raw Common Lisp you can change the source from
  which ACL2 reads on the channel [47m*standard-ci*[0m.  See
  [*standard-co*].")
 (*STANDARD-CO*
  (IO ACL2-BUILT-INS)
  "The ACL2 analogue of CLTL's [47m*standard-output*[0m

  The value of the ACL2 constant [47m*standard-co*[0m is an open character
  output channel that is synonymous to Common Lisp's
  [47m*standard-output*[0m.

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

  To see the value of this observation, consider the following.
  Suppose you write an ACL2 function which does character output to
  the constant channel [47m*standard-co*[0m.  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 [47m*standard-output*[0m to that stream, call your ACL2
  function, and then close the stream and restore [47m*standard-output*[0m
  to its nominal value.  Similar observations can be made about the
  two ACL2 input channels, [47m[*standard-oi*][0m and [47m[*standard-ci*][0m, which
  are analogues of [47m*standard-input*[0m.

  Another reason you might have for wanting to change the actual
  streams associated with [47m[*standard-oi*][0m and [47m*standard-co*[0m is to
  drive the ACL2 top-level loop, [47m[ld][0m, on alternative input and
  output streams.  This end can be accomplished easily within ACL2 by
  either calling [47m[ld][0m on the desired channels or file names or by
  resetting the ACL2 [47m[state][0m global variables [47m'[0m[47m[standard-oi][0m and
  [47m'[0m[47m[standard-co][0m which are used by [47m[ld][0m.  See [standard-oi] and see
  [standard-co].")
 (*STANDARD-OI*
  (IO ACL2-BUILT-INS)
  "An ACL2 object-based analogue of CLTL's [47m*standard-input*[0m

  The value of the ACL2 constant [47m*standard-oi*[0m is an open object input
  channel that is synonymous to Common Lisp's [47m*standard-input*[0m.

  ACL2 object input from [47m*standard-oi*[0m is actually obtained by reading
  from the stream named by Common Lisp's [47m*standard-input*[0m.  That is,
  by changing the setting of [47m*standard-input*[0m in raw Common Lisp you
  can change the source from which ACL2 reads on the channel
  [47m*standard-oi*[0m.  See [*standard-co*].")
 (+
  (NUMBERS ACL2-BUILT-INS)
  "Addition macro

  [47m+[0m is really a macro that expands to calls of the function [47m[binary-+][0m.
  So for example

    (+ x y 4 z)

  represents the same term as

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

  See [binary-+].

  [31;1mMacro: [0m<+>

    (defmacro + (&rest rst)
      (if rst (if (cdr rst)
                  (xxxjoin 'binary-+ rst)
                (cons 'binary-+
                      (cons 0 (cons (car rst) nil))))
        0))


Subtopics

  [Binary-+]
      Addition function")
 (-
  (NUMBERS ACL2-BUILT-INS)
  "Macro for subtraction and negation

  See [binary-+] for addition and see [unary--] for negation.

  Note that [47m-[0m represents subtraction as follows:

    (- x y)

  represents the same term as

    (+ x (- y))

  which is really

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

  Also note that [47m-[0m represents arithmetic negation as follows:

    (- x)

  expands to

    (unary-- x).

  [31;1mMacro: [0m<->

    (defmacro - (x &optional (y 'nil binary-casep))
     (if binary-casep (let ((y (if (and (consp y)
                                        (eq (car y) 'quote)
                                        (consp (cdr y))
                                        (acl2-numberp (car (cdr y)))
                                        (eq (cdr (cdr y)) nil))
                                   (car (cdr y))
                                 y)))
                        (if (acl2-numberp y)
                            (cons 'binary-+
                                  (cons (unary-- y) (cons x nil)))
                          (cons 'binary-+
                                (cons x
                                      (cons (cons 'unary-- (cons y nil))
                                            nil)))))
       (let ((x (if (and (consp x)
                         (eq (car x) 'quote)
                         (consp (cdr x))
                         (acl2-numberp (car (cdr x)))
                         (eq (cdr (cdr x)) nil))
                    (car (cdr x))
                  x)))
         (if (acl2-numberp x)
             (unary-- x)
           (cons 'unary-- (cons x nil))))))")
 (/
  (NUMBERS ACL2-BUILT-INS)
  "Macro for division and reciprocal

  See [binary-*] for multiplication and see [unary-/] for reciprocal.

  Note that [47m/[0m represents division as follows:

    (/ x y)

  represents the same term as

    (* x (/ y))

  which is really

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

  Also note that [47m/[0m represents reciprocal as follows:

    (/ x)

  expands to

    (unary-/ x).

  [47m/[0m is a Common Lisp macro.  See any Common Lisp documentation for more
  information.

  [31;1mMacro: [0m</>

    (defmacro / (x &optional (y 'nil binary-casep))
      (cond (binary-casep (list 'binary-* x (list 'unary-/ y)))
            (t (list 'unary-/ x))))")
 (/=
  (NUMBERS ACL2-BUILT-INS)
  "Test inequality of two numbers

  [47m(/= x y)[0m is logically equivalent to [47m(not (equal x y))[0m.

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

  For a discussion of the various ways to test against 0, See
  [zero-test-idioms].

  [47m/=[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m</=>

    (defun /= (x y)
      (declare (xargs :guard (and (acl2-numberp x)
                                  (acl2-numberp y))))
      (not (equal x y)))")
 (1+
  (NUMBERS ACL2-BUILT-INS)
  "Increment by 1

  [47m(1+ x)[0m is the same as [47m(+ 1 x)[0m.  See [+].

  [47m1+[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<1+>

    (defmacro 1+ (x) (list '+ 1 x))")
 (1-
  (NUMBERS ACL2-BUILT-INS)
  "Decrement by 1

  [47m(1- x)[0m is the same as [47m(- x 1)[0m.  See [-].

  [47m1-[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<1->

    (defmacro 1- (x) (list '- x 1))")
 (<
  (NUMBERS ACL2-BUILT-INS)
  "Less-than

  Completion Axiom ([47mcompletion-of-<[0m):

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

  [Guard] for [47m(< x y)[0m:

    (and (rationalp x) (rationalp y))

  Notice that like all arithmetic functions, [47m<[0m treats non-numeric
  inputs as [47m0[0m. Thus, the following are theorems.

    (thm (equal (< (fix x) y) (< x y)))
    (thm (equal (< x (fix y)) (< x y)))

  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.")
 (<=
  (NUMBERS ACL2-BUILT-INS)
  "Less-than-or-equal test

  [47m<=[0m is a macro, and [47m(<= x y)[0m expands to the same thing as [47m(not (< y
  x))[0m.  See [<].

  [47m<=[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<<=>

    (defmacro <= (x y)
      (list 'not (list '< y x)))")
 (=
  (NUMBERS EQUAL EQUALITY-VARIANTS ACL2-BUILT-INS)
  "Test equality of two numbers

  [47m(= x y)[0m is logically equivalent to [47m(equal x y)[0m.

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

  For a discussion of the various ways to test against 0, See
  [zero-test-idioms].

  [47m=[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<=>

    (defun = (x y)
      (declare (xargs :guard (and (acl2-numberp x)
                                  (acl2-numberp y))))
      (equal x y))")
 (>
  (NUMBERS ACL2-BUILT-INS)
  "Greater-than test

  [47m>[0m is a macro, and [47m(> x y)[0m expands to the same thing as [47m(< y x)[0m.  See
  [<].

  [47m>[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<>>

    (defmacro > (x y) (list '< y x))")
 (>=
  (NUMBERS ACL2-BUILT-INS)
  "Greater-than-or-equal test

  [47m>=[0m is a macro, and [47m(>= x y)[0m expands to the same thing as [47m(not (< x
  y))[0m.  See [<].

  [47m>=[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<>=>

    (defmacro >= (x y)
      (list 'not (list '< x y)))")
 (@
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Get the value of a global variable in [47m[state][0m

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

    General Form:
    (@ symbol)

  where [47msymbol[0m is any symbol to which you have [47m[assign][0med a global
  value.  This macro expands into [47m(f-get-global 'symbol state)[0m, which
  retrieves the stored value of the symbol.

  The macro [47mf-get-global[0m is closely related to [47m[@][0m: [47m(@ var)[0m
  macroexpands to [47m(f-get-global 'var state)[0m.

  The macro [47m[assign][0m makes it convenient to set the value of a symbol.
  The [47m:[0m[47m[ubt][0m operation has no effect on the [47mglobal-table[0m of [47m[state][0m.
  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.")
 (A!
  (LD)
  "To return to the top-level of ACL2's command loop

  When [47m(a!)[0m 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 `[47m#.[0m' for this purpose, but no longer; see
  [sharp-dot-reader].)

  If you are at an ACL2 prompt (as opposed to a raw Lisp break), then
  you may type [47m:a![0m in place of [47m(a!)[0m; see [keyword-commands].

  For a related feature that only pops up one level of [47m[ld][0m, see [47m[p!][0m.
  However, [47mp![0m behaves differently if you're typing to the interactive
  break caused by [break-rewrite].  Instead of popping up one level,
  [47mp![0m in break-rewrite prints a message and is otherwise a no-op.

  Logically speaking, [47m(a!) = nil[0m.  But imagine that it is defined in
  such a way that it causes a stack overflow or other resource
  exhaustion when called.")
 (ABORT!
  (LD)
  "To return to the top-level of ACL2's command loop

  This is an alias for [47ma![0m; see [a!].  For a related feature that only
  pops up one level, see [p!].")
 (ABORT-SOFT
  (MISCELLANEOUS)
  "Control how interrupts are handled in proofs

  ACL2 arranges by default that when a proof is interrupted (with
  [47mControl-C[0m), 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).

    ***********************************************
    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.
    ***********************************************

  This default behavior supports proper operation of the utility,
  [47m[redo-flat][0m, 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 [47m(assign abort-soft nil)[0m.  To restore the default
  behavior, evaluate [47m(assign abort-soft t)[0m.

  Remarks for system hackers.

    * An important effect of having evaluated [47m(assign abort-soft nil)[0m 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 [error-triple] whose error component is
      non-[47mnil[0m.

    * It may be preferable to bind [state] global [47mabort-soft[0m rather than to
      assign it globally.  See the implementation of [prove$]
      (specifically, the definition of [47mprove$-fn[0m in [community-book]
      [47mbooks/tools/prove-dollar.lisp[0m) for an example.")
 (ABOUT-ACL2
  (START-HERE)
  "General information About ACL2

  This is ACL2 Version 8.6, [copyright] (C) 2025, Regents of the
  University of Texas, authored by Matt Kaufmann and J Strother
  Moore.

  See the {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/}
  for additional information including tutorials, installation
  instructions, mailing lists, related publications, ACL2 workshops
  and seminars, acknowledgments, and other ACL2 releases.

  See [documentation] for how to access the ACL2 User's Manual.

  For statistics on ACL2 code size, see file [47mdoc/acl2-code-size.txt[0m.


Subtopics

  [Acknowledgments]
      Some contributors to the well-being of ACL2

  [ACL2-help]
      The acl2-help mailing list

  [Bibliography]
      Reports about ACL2

  [Building-ACL2]
      How to build an ACL2 executable

  [Common-lisp]
      Relation to Common Lisp, including deviations from the spec

  [Copyright]
      ACL2 copyright, license, sponsorship

  [Git-quick-start]
      Git quick start guide

  [Operational-semantics]
      Modeling State Machines

  [Pre-built-binary-distributions]
      Pre-built binary distributions of ACL2

  [Recursion-and-induction]
      Recursion and Induction

  [Release-notes]
      Pointers to what has changed

  [Soundness]
      Correctness property claimed for ACL2

  [Version]
      ACL2 Version Number")
 (ABOUT_MODELS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "About Models

  {IMAGE} (see [Models_of_Computer_Hardware_and_Software])

  ACL2 is used to construct mathematical models of computer hardware
  and software (i.e., ``digital systems'').

  {IMAGE}

  A [31;1mmathematical model[0m is a set of mathematical formulas used to
  predict the behavior of some artifact.

  The use of mathematical models allows [31;1mfaster[0m and [31;1mcheaper[0m delivery of
  [31;1mbetter[0m systems.

  Models need not be [31;1mcomplete[0m or [31;1mperfectly accurate[0m to be useful to the
  trained engineer.

  Click here (see [Models_in_Engineering]) for more discussion of these
  assertions in an engineering context.

  {IMAGE} (see [Models_of_Computer_Hardware_and_Software])")
 (ABOUT_THE_ACL2_HOME_PAGE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "About the ACL2 Home Page

  {IMAGE} (see [What_Is_ACL2{Q}])

  The {ACL2 Home Page | http://www.cs.utexas.edu/users/moore/acl2/} on
  the web contains links to demos, publications, mailing lists,
  installation instructions, and more --- and, especially, to the
  extensive {online documentation |
  https://www.cs.utexas.edu/users/moore/acl2/v8-6/acl2-doc.html#User's-Manual}
  for ACL2 and its libraries, known as ``books''.

  For example, to use the online documentation to find out about
  [rewrite] {ICON} (see [A_Tiny_Warning_Sign]) rules you could click
  on the link.  (If you do that, remember to use your browser's [31;1mBack
  Button[0m to come back here.)

  The tiny warning signs {ICON} (see [A_Tiny_Warning_Sign]) 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.

  At the end of the tours you will have a chance to revisit them
  quickly to explore alternative paths more fully.

  {IMAGE} (see [What_Is_ACL2{Q}])")
 (ABOUT_THE_ADMISSION_OF_RECURSIVE_DEFINITIONS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "About the Admission of Recursive Definitions

  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 [47m(APP X Y)[0m so that it was equal to [47m(NOT (APP X Y))[0m then we
  could prove anything.  The purported ``definition'' of [47mAPP[0m must
  have several properties to be admitted to the logic as a new axiom.

  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.

  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.

  For [47mapp[0m the measure is the ``size'' of the first argument, [47mx[0m, as
  determined by the primitive function [47m[ACL2-count][0m {ICON} (see
  [A_Tiny_Warning_Sign]).  The well-founded relation used in this
  example is [47m[o-p][0m {ICON} (see [A_Tiny_Warning_Sign]), which is the
  standard ordering on the ordinals less than ``epsilon naught.''
  These particular choices for [47mapp[0m 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 [47m[defun][0m {ICON} (see [A_Tiny_Warning_Sign]) command
  to specify the measure and relation.

  You should now return to the Walking Tour (see
  [Revisiting_the_Admission_of_App]).")
 (ABOUT_THE_PROMPT
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "About the Prompt

  The string ``[47mACL2 !>[0m'' is the ACL2 prompt.

  The prompt tells the user that an ACL2 [command] {ICON} (see
  [A_Tiny_Warning_Sign]) 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.

  An ACL2 command is generally a Lisp expression to be evaluated.
  There are some unusual commands (such as [47m:[0m[q] {ICON} (see
  [A_Tiny_Warning_Sign]) for [31;1mquitting[0m 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
  [47m[ld][0m {ICON} (see [A_Tiny_Warning_Sign]) (after Lisp's ``load'').

  When a command is read, all the symbols in it are converted to
  uppercase.  Thus, typing [47m(defun app ...)[0m is the same as typing
  [47m(DEFUN APP ...)[0m or [47m(defun App ...)[0m.  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.

  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 [47m\"ACL2\"[0m.  That means when we call [47mcar[0m, for
  example, we are invoking the standard definition of that symbol.
  If the packager were [47m\"JONES\"[0m then [47mcar[0m 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.

  A command like [31;1m(defun app (x y) ...)[0m causes ACL2 to evaluate the
  [defun] {ICON} (see [A_Tiny_Warning_Sign]) function on [31;1mapp[0m, [31;1m(x y)[0m
  and [31;1m...[0m.  When that command is evaluated it prints some information
  to the terminal explaining the processing of the proposed
  definition.  It returns the symbol [47mAPP[0m as its value, which is
  printed by the command interpreter.  (Actually, [47mdefun[0m is not a
  function but a macro (see [DEFMACRO]) {ICON} (see
  [A_Tiny_Warning_Sign]) which expands to a form that involves
  [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign]), a necessary
  precondition to printing output to the terminal and to ``changing''
  the set of axioms.  But we do not discuss this further here.)

  The [47mdefun[0m command is an example of a special kind of command called
  an ``event.'' [Events] {ICON} (see [A_Tiny_Warning_Sign]) are those
  commands that change the ``logical world'' by adding such things as
  axioms or theorems to ACL2's database.  See [world] {ICON} (see
  [A_Tiny_Warning_Sign]).  But not every command is an event command.

  A command like [31;1m(app '(1 2 3) '(4 5 6 7))[0m is an example of a
  non-event.  It is processed the same general way: the function [31;1mapp[0m
  is applied to the indicated arguments and the result is printed.
  The function [31;1mapp[0m does not print anything and does not change the
  ``world.''

  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 ``[history]'' {ICON} (see
  [A_Tiny_Warning_Sign]) commands.

  What does the ACL2 prompt tell us about the read-eval-print loop?
  The prompt ``[47mACL2 !>[0m'' tells us that the command will be read with
  [47m[current-package][0m {ICON} (see [A_Tiny_Warning_Sign]) set to [47m\"ACL2\"[0m,
  that guard checking (see [set-guard-checking] {ICON} (see
  [A_Tiny_Warning_Sign])) is on (``[47m![0m''), and that we are at the
  top-level (there is only one ``[47m>[0m'').  For more about the prompt,
  see [default-print-prompt] {ICON} (see [A_Tiny_Warning_Sign]).

  You should now return to the Walking Tour (see
  [Revisiting_the_Admission_of_App]).")
 (ABOUT_TYPES
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "About Types

  The universe of ACL2 objects includes objects of many different
  types.  For example, [47mt[0m is a ``symbol'' and 3 is an ``integer.''
  Roughly speaking the objects of ACL2 can be partitioned into the
  following types:

    * Numbers (see [Numbers_in_ACL2]) such as [47m3, -22/7, #c(3 5/2)[0m.

    * Characters (see [ACL2_Characters]) such as [47m#\\A, #\\a, #\\Space[0m.

    * Strings (see [ACL2_Strings]) such as [47m\"This is a string.\"[0m.

    * Symbols (see [ACL2_Symbols]) such as [47m'abc, 'smith::abc[0m.

    * Conses (or Ordered Pairs) (see [ACL2_Conses_or_Ordered_Pairs]) such
      as [47m'((a . 1) (b . 2))[0m.

  When proving theorems it is important to know the types of object
  returned by a term.  ACL2 uses a complicated heuristic algorithm,
  called [47m[type-set][0m {ICON} (see [A_Tiny_Warning_Sign]), to determine
  what types of objects a term may produce.  The user can more or
  less program the [47mtype-set[0m algorithm by proving [47m[type-prescription][0m
  {ICON} (see [A_Tiny_Warning_Sign]) rules.

  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 [47m(+ t 3)[0m which sums
  the symbol [47mt[0m 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 [47m(+ t 3)[0m) can arise.

  To make theorem proving easier in ACL2, the axioms actually define a
  value for such terms.  The value of [47m(+ t 3)[0m is 3; under the ACL2
  axioms, non-numeric arguments to [47m+[0m are treated as though they were
  0.

  You might immediately wonder about our claim that ACL2 is Common
  Lisp, since [47m(+ t 3)[0m is ``an error'' (and will sometimes even
  ``signal an error'') in Common Lisp.  It is to handle this problem
  that ACL2 has [31;1mguards[0m.  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.

  You should now return to the Walking Tour (see
  [Revisiting_the_Admission_of_App]).")
 (ABS
  (NUMBERS ACL2-BUILT-INS)
  "The absolute value of a real number

  [47m(Abs x)[0m is [47m-x[0m if [47mx[0m is negative and is [47mx[0m otherwise.

  The [guard] for [47mabs[0m requires its argument to be a rational ([real],
  in ACL2(r)) number.

  [47mAbs[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  From ``Common Lisp the Language'' page 205, we must not allow complex
  [47mx[0m as an argument to [47mabs[0m 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.

  [31;1mFunction: [0m<abs>

    (defun abs (x)
      (declare (xargs :guard (real/rationalp x)))
      (if (minusp x) (- x) x))")
 (ABSTRACT-STOBJ (POINTERS)
                 "See [defabsstobj].")
 (ACCESS
  (DEFREC ACL2-BUILT-INS)
  "Accessor macro for [defrec] structures.

  The [47maccess[0m macro is built into ACL2, and allows you to access
  particular fields from structures that have been introduced with
  [defrec].  For instance:

    (access employee x :name)

  would return the [47mname[0m field from the employee [47mx[0m.  See [defrec] for
  more information.")
 (ACCUMULATED-PERSISTENCE
  (DEBUGGING)
  "To get statistics on which [rune]s are being tried

    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.

  In summary, [47m(accumulated-persistence t)[0m turns on fresh statistics
  gathering for rules, [47m(accumulated-persistence nil)[0m turns it off,
  [47m(show-accumulated-persistence)[0m displays the statistics that were
  gathered, and [47m(accumulated-persistence-oops)[0m restores the
  statistics, if any, that were cleared by [47m(accumulated-persistence
  t)[0m or [47m(accumulated-persistence :all)[0m.

  In general, if the optional second argument of
  [47mshow-accumulated-persistence[0m is supplied as [47m:list[0m, 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 [47m(frames tries xrune)[0m.

  Note: [47mset-accumulated-persistence[0m is equivalent to
  [47maccumulated-persistence[0m.

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

  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.

  For other proof debugging utilities, see [break-rewrite],
  [with-brr-data], and [dmr].

  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

    ACL2 !>(accumulated-persistence t)

  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
  [47mshow-accumulated-persistence[0m, as described in detail below.  When
  accumulated persistence is turned off, with
  [47m(accumulated-persistence nil)[0m, the accumulation site is wiped out
  and the data in it is lost.

  The ``accumulated persistence'' of a [rune] is the number of [rune]s
  the system has attempted to apply (since accumulated persistence
  was last activated) while the given [rune] was being tried.

  Consider a [47m:[0m[47m[rewrite][0m rule named [47m[rune][0m.  For simplicity, let us
  imagine that [47m[rune][0m 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
  [47m[rune][0m by rewriting, and, if successful, then rewrite the
  right-hand side of the conclusion.  We say [47m[rune][0m 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 [loop-stopper].)  During that period of time other
  rules might be tried, e.g., to establish the hypotheses.  The rules
  tried while [47m[rune][0m is being tried are ``billed'' to [47m[rune][0m in the
  sense that they are being considered here only because of the
  demands of [47m[rune][0m.  Thus, if no other rules are tried during that
  period, the accumulated persistence of [47m[rune][0m is [47m1[0m --- we ``bill''
  [47m[rune][0m once for its own application attempt.  If, on the other
  hand, we tried [47m10[0m rules on behalf of that application of [47m[rune][0m,
  then [47m[rune][0m's accumulated persistence would be [47m11[0m.

  One way to envision accumulated persistence is to imagine that every
  time a [rune] is tried it is pushed onto a stack.  The rules tried
  on behalf of a given application of a [rune] are thus pushed and
  popped on the stack above that [rune].  A lot of work might be done
  on its behalf --- the stack above the [rune] grows and shrinks
  repeatedly as the search continues for a way to use the [rune].
  All the while, the [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 [rune] application is thus
  the number of stack frames built while that [rune] was on the
  stack.

  Note that accumulated persistence is tallied whether or not the
  attempt to apply a [rune] is successful.  Each of the rules tried
  on its behalf might have failed and the attempt to apply the [rune]
  might have also failed.  The ACL2 proof script would make no
  mention of the [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 [rune] and accumulated persistence is a
  measure of that time.

  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.

  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 [congruence] runes and, in some cases
  [executable-counterpart] runes. (For the latter, details are in a
  comment in the ACL2 source definition of function
  [47mprint-useless-runes[0m.)

  When the accumulated persistence totals are displayed by the function
  [47mshow-accumulated-persistence[0m we sort them so that the most
  expensive [rune]s are shown first.  We can sort according to one of
  three basic keys:

    :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

  The key simply determines the order in which the information is
  presented.  If no argument is supplied to
  [47mshow-accumulated-persistence[0m, [47m:frames[0m is used.

  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 [47m:[0m[47m[rewrite][0m 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
  [rune] is viewed as ``useful'' unless the attempt fails or the
  attempt is on the stack (as described above) for a [rune]
  application that ultimately fails.  A large number of ``useless''
  [47m:frames[0m or [47m:tries[0m along with correspondingly small ``useful''
  counts may suggest [rune]s to consider disabling (see [disable] and
  see [in-theory]).  Thus, here is a more complete list of the
  arguments that may be supplied to [47mshow-accumulated-persistence[0m.
  Suffixes ``s'', ``f'', and ``a'' are intended to suggest
  ``success'' (``useful''), ``failure'' (``useless''), and ``all''.

    :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''

  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.

    (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)

  To prove the [47m[thm][0m form, ACL2 attempts to rewrite [47m(concl x)[0m to true
  by applying rule [47mhyp-implies-concl[0m.  It then attempts to establish
  [47m(hyp x)[0m first by trying rule [47mbad-ax[0m, which fails, and second by
  trying rule [47mgood-ax[0m, which succeeds.  As expected, the report
  labels as ``useless'' the failure of the attempt to establish the
  hypothesis, [47m(bad x)[0m.

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

  Now consider the top-level application of rule [47mhyp-implies-concl[0m.
  Even though the above report shows the application of [47mbad-ax[0m as
  ``useless'', note that this rule was applied on behalf of the
  successful (``useful'') application of [47mhyp-implies-concl[0m, and hence
  is incorporated into the ``useful'' line for [47mhyp-implies-concl[0m, as
  follows.

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

  In summary: categorization of [47m:frames[0m as ``useful'' or ``useless'' is
  based on whether they support ``useful'' or ``useless'' [47m:tries[0m.

  See [useless-runes] for a way to speed up proofs by automatically
  turning off useless rules.

  Note that a [rune] with high accumulated persistence may not actually
  be the ``culprit.'' For example, suppose [47mrune1[0m is reported to have
  a [47m:ratio[0m of [47m101[0m, meaning that on the average a hundred and one
  frames were built each time [47mrune1[0m was tried.  Suppose [47mrune2[0m has a
  [47m:ratio[0m of [47m100[0m.  It could be that the attempt to apply [47mrune1[0m
  resulted in the attempted application of [47mrune2[0m and no other [rune].
  Thus, in some sense, [47mrune1[0m is ``cheap'' and [47mrune2[0m is the
  ``culprit'' even though it is reported as costing less than [47mrune1[0m.

  If a proof is aborted, then in general,
  [47m[show-accumulated-persistence][0m 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 [47m[show-accumulated-persistence][0m when such incomplete
  information is omitted, you can get this information by using
  argument [47m:frames-a[0m or [47m:tries-a[0m.

  There are other subtleties in how rune applications are tallied,
  documented elsewhere: see [accumulated-persistence-subtleties].

  We conclude with a discussion of ``enhanced'' statistics gathering,
  which is enabled by supplying [47maccumulated-persistence[0m the argument
  [47m:ALL[0m:

    (accumulated-persistence :all)

  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 [47mrn[0m is a [rune].  Then we
  prepend the keyword [47m:CONC[0m to [47mrn[0m to form what we call its
  ``conclusion xrune'', and for its [47mI[0m-th hypothesis we prepend [47m:HYP I[0m
  to [47mrn[0m to form its [47mI[0m-th ``hypothesis xrune.'' Here, ``xrune'' is
  pronounced ``ex rune'', and is mnemonic for ``extended rune.'' For
  example, if [47m(REWRITE FOO)[0m is a [rune] then [47m(:CONC REWRITE FOO)[0m is
  its conclusion xrune, and [47m(:HYP 2 REWRITE FOO)[0m is a hypothesis
  xrune corresponding to the second hypothesis of the corresponding
  rewrite rule.

  With [47m(accumulated-persistence :all)[0m, we instruct ACL2 to track not
  only runes but also xrunes.  Then, [47m(show-accumulated-persistence)[0m
  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.

    (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)

  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 [47m:frames[0m
  counts.  Rather, they serve as accumulation sites without
  contributing their [47m:tries[0m to any accumulation.  Consider for
  example the snippet below, taken from a report created with the
  [47m:merge[0m option (to be discussed further below), i.e., by evaluating
  the form [47m(show-accumulated-persistence :frames :merge)[0m.

    :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]
    --------------------------------

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

    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 !>

  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
  --- 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 type reasoning (see [TYPE-REASONING]),
  that is not done during rewriting of a hypothesis or the
  conclusion.

  Now suppose we have executed [47m(accumulated-persistence :all)[0m and
  attempted some proofs, and now we are ready to see statistics.  The
  form [47m(show-accumulated-persistence)[0m displays statistics exactly as
  described above, treating these extra xrunes just as though they
  are runes; similarly for the form [47m(show-accumulated-persistence
  KEY)[0m, for any legal [47mKEY[0m.  A second optional argument may however be
  supplied to [47mshow-accumulated-persistence[0m.  The default for that
  second argument is [47mt[0m, and a second argument of [47m:raw[0m is treated the
  same as [47mt[0m; 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 [47mnil[0m.  (This gives
  the same behavior as if we had started with the command
  [47m(accumulated-persistence t)[0m instead of the command
  [47m(accumulated-persistence :all)[0m.)  You may give a second argument of
  [47m:merge[0m, 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
  [47mPERM-MEM[0m example displayed above.  Finally, you may give a second
  argument of [47m:list[0m, which is equivalent to the default second
  argument of [47mt[0m, except that the results are printed as a list of
  entries [47m(frames tries xrune)[0m.

  We close by mentioning two aspects of enhanced statistics display for
  [47m:CONC[0m xrunes that have potential to be confusing.  First consider
  the following example.

      :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]
    --------------------------------

  It may be surprising that no data is displayed for the corresponding
  [47m:CONC[0m 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 [47m:frames[0m and
  [47m:tries[0m for the rune and the hypothesis xrune.  Note by the way,
  once again, that the hypothesis xrune does not contribute to any
  [47m:frames[0m count.

  Another reason not to see data displayed for a [47m:CONC[0m 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 [47m:CONC[0m xrune will add
  any useful insight.

  On a final note: [47m(show-accumulated-persistence :runes)[0m may be used
  simply to see a list of all [rune]s (or xrunes) displayed
  alphabetically.

  Users are encouraged to think about other meters we could install in
  ACL2 to help diagnose performance problems.


Subtopics

  [Accumulated-persistence-subtleties]
      Some subtle aspects of the counting done by
      [47m[accumulated-persistence][0m

  [Dmr]
      Dynamically monitor rewrites and other prover activity

  [Useless-runes]
      Speed up proofs by disabling useless [rune]s")
 (ACCUMULATED-PERSISTENCE-OOPS (POINTERS)
                               "See [accumulated-persistence].")
 (ACCUMULATED-PERSISTENCE-SUBTLETIES
  (ACCUMULATED-PERSISTENCE)
  "Some subtle aspects of the counting done by [47m[accumulated-persistence][0m

  In this topic we cover the overcounting of ``useful'' [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.

  [3mOvercounting of ``useful'' rune application attempts.[0m Not every
  [rune] application may be necessary for a proof's success.
  Consider for example:

    (thm (equal (car (cons a (cdr (cons b x))))
                a))

  Then [47mshow-accumulated-persistence[0m will tell us that [47m:[0m[47m[rewrite][0m rules
  [47mcar-cons[0m and [47mcdr-cons[0m each had one useful application.  However,
  the rule [47mcdr-cons[0m is used to simplify [47m(cdr (cons b x))[0m to [47mx[0m, and
  this simplification is unnecessary for the proof.  Indeed, the
  proof succeeds even when preceded by the event: [47m(in-theory (disable
  cdr-cons))[0m.  We thus see that a [rune] application labeled as
  ``useful'' may be simplifying a term that is not relevant to the
  proof.

  As of this writing, we consider every [47m:[0m[47m[forward-chaining][0m 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.

  [3mHow ``useless'' attempts can be critical for a proof's success.[0m The
  command [47m(accumulated-persistence :useless[0m) will list rules that did
  not contribute directly to the proof (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:

    ; 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

  The following event captures the rules described above.

    (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))))

  Now we can see that [47mp3-is-p4[0m is labeled as ``useless'', by evaluating
  these commands.

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

  If instead we first evaluate [47m(in-theory (disable p3-is-p4))[0m before
  the [47mthm[0m above, then the proof fails, even though [47mp3-is-p4[0m was
  labeled as ``useless''!

  Nevertheless, in general it is probably safe to disable rules
  reported as ``useless'' by [47m(show-accumulated-persistence :useless)[0m,
  and doing so may speed up a proof considerably.

  Remark. The example above suggests a surprising fact: on rare
  occasions, a proof may fail when you give an [47m:[0m[47m[in-theory][0m hint
  consisting of exactly the [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.

  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 --- in
  particular, while relieving a hypothesis or rewriting the
  right-hand side from the original rule application.  Recall that
  the implementation of [accumulated-persistence] keeps a stack of
  [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.

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

  Now suppose we consider the theorem [47m(mem a (list 1 2 3 a))[0m.  Each
  time the definition of [47mmem[0m is applied, a new stack frame is pushed.
  We avoid accumulating into the [47m:frames[0m count for that stack frame
  unless it is the topmost stack frame for that definition.
  Otherwise the final [47m:frames[0m 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 [47mmem[0m.")
 (ACKNOWLEDGMENTS
  (ABOUT-ACL2)
  "Some contributors to the well-being of ACL2

  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).

    * AMD, for providing significant time over several years for Matt
      Kaufmann to carry out ACL2 research, support, and development

    * Computational Logic, Inc. and its president, Don Good, where the
      first eight years of ACL2 development occurred

    * Centaur Technology

    * Collins Aerospace

    * DARPA

    * Digital Equipment Corporation

    * EDS, which provided some time for Matt Kaufmann's ACL2 work 1998-1999

    * ForrestHunt and, more generally, Warren A. Hunt, Jr. (see below)

    * IBM

    * Intel

    * Kestrel Institute

    * Kestrel Technology

    * NSF (see below)

    * ONR

    * SRC

    * Sun Microsystems

    * U.S. Army, in particular ARL

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

  Regarding DARPA support: We thank DARPA for approving release of the
  following documentation topics and support with ``DISTRIBUTION
  STATEMENT A. Approved for public release. Distribution is
  unlimited.''

    * [Recursion-and-induction] together with its subtopics and its answer
      key ([community-books] files [47mdemos/r-and-i-answer-key-input.lsp[0m
      and [47mdemos/r-and-i-answer-key-log.txt[0m)

    * [Gentle-introduction-to-ACL2-programming]

    * [Loop$-primer] together with its subtopics and its answer key
      ([community-books] files [47mlp6.lisp[0m, [47mlp8.lisp[0m, [47mlp12.lisp[0m,
      [47mlp14.lisp[0m, [47mlp17-11-lemma2.lisp[0m, and [47mlp17.lisp[0m)

    * [Start-here]

  Regarding NSF support:

    * 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.

    * 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.

  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.

  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 ``[state]'' and
  the most primitive [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.

  Bishop Brock was the heaviest early user of ACL2, and provided many
  suggestions for improvements.  In particular, the [47m:cases[0m and
  [47m:restrict[0m [hints] were his idea; he developed an early version of
  congruence-based reasoning for Nqthm; and he helped in the
  development of some early [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
  --- which required formalizing a commercial DSP in the untested
  ACL2 --- 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.

  John Cowles also helped in the development of some early [books]
  about arithmetic, and also provided valuable feedback and bug
  reports.

  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.

  Mike Smith helped develop the Emacs portion of the implementation of
  proof trees.

  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.

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

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

  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 [real].

  Rob Sumners has made numerous useful suggestions.  In particular, he
  has designed and implemented improvements for [stobj]s and been key
  in our development of locally-bound stobjs; see [note-2-6].

  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
  [extended-metafunctions].

  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 [ordinals].

  Jared Davis, Sol Swords, and David Rager have our gratitude for
  starting the {ACL2+Books repository |
  https://github.com/acl2/acl2/}.

  We thank David L. Rager for contributing an initial version of the
  support for [parallelism] in an experimental extension of ACL2.

  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 [hons-and-memoization].

  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
  [release-notes] detail such contributions as well as many
  suggestions from the community for improvements that we ultimately
  implemented.

  We also thank the contributors to the ACL2 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
  [books] (see [community-books]), and their interest in the ACL2
  project.

  [3mRegarding the documentation:[0m

      Bill Young wrote significant portions of the original [47macl2-tutorial[0m
      section of the ACL2 documentation, including what is now called
      [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 [documentation].

      Art Flatau helped develop the ACL2 markup language in which ACL2
      [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).

      Laura Lawless provided many hours of help in marking up appropriate
      parts of the [documentation] in typewriter font.

      Noah Friedman developed an Emacs tool that helped us insert
      ``invisible links'' into the [documentation], which improve the
      usability of that documentation under HTML readers such as
      Mosaic.

      Richard Stallman contributed a texinfo patch, to be found in the file
      [47mdoc/texinfo.tex[0m.

      Jared Davis created the [xdoc] system that is now the basis not only
      for the ACL2 system [documentation] (file
      [47mbooks/system/doc/acl2-doc.lisp[0m), but also for the
      [community-books] documentation.

  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.")
 (ACL2
  NIL
  "ACL2 documentation (system only, not including the community books)

  This is the ACL2 documentation.  For the ACL2+Books Manual, which
  that includes both the ACL2 documentation and the ACL2
  [community-books], see the {ACL2+Books Manual |
  http://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}.


Subtopics

  [Bdd]
      Ordered binary decision diagrams with rewriting

  [Books]
      [3mBooks[0m are files of ACL2 [events]---they are the main way to split up
      large ACL2 developments into separate modules.

  [Debugging]
      Tools for debugging failed or slow proofs, or misbehaving functions.

  [Documentation]
      Information about options for downloading and viewing the ACL2
      documentation, contributing documentation, and the available
      tools for documenting your own books.

  [Events]
      Functions that extend the logic

  [History]
      Functions to display or change contents of the logical [world]

  [Hons-and-memoization]
      Hash cons, function memoization, and applicative hash tables

  [Interfacing-tools]
      Libraries and tools for doing basic file i/o (see [STD/IO]), using
      raw Common Lisp libraries (see [QUICKLISP]), working with the
      operating system (see [OSLIB]), and interfacing with other
      programs (see [BRIDGE]).

  [Macros]
      Macros allow you to extend the syntax of ACL2.

  [Miscellaneous]
      A miscellany of documented functions and concepts (often cited in
      more accessible [documentation])

  [Operational-semantics]
      Modeling State Machines

  [Output-controls]
      Methods for controlling the output produced by the ACL2 prover

  [Parallelism]
      Experimental extension for parallel execution and proofs

  [Programming]
      Programming in ACL2

  [Proof-builder]
      An interactive tool for controlling ACL2's proof processes.

  [Real]
      ACL2(r) support for real numbers

  [Recursion-and-induction]
      Recursion and Induction

  [Rule-classes]
      Adding rules to the database

  [Start-here]
      Introductory information about ACL2

  [Theories]
      Sets of [rune]s to [enable]/[disable] in concert")
 (ACL2-AS-STANDALONE-PROGRAM
  (ACL2-TUTORIAL)
  "Calling ACL2 from another program

  ACL2 is intended for interactive use.  It is generally unrealistic to
  expect it to prove theorems fully automatically; see [the-method],
  and see [introduction-to-the-theorem-prover] for a more detailed
  tutorial.

  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.

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


Step 1

  Build a suitable ACL2 image by starting ACL2 and then executing the
  following forms.  In particular, these define a macro, [47mtry-thm[0m,
  that causes ACL2 to exit with an exit status indicating success or
  failure of a proof attempt.

    (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\")

  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

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

  by

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

  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).


Step 2

  Try a little test.  In that same directory try this:

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

  The exit status should be 0, indicating success.  Now try this:

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

  The exit status should be 1, indicating failure.


Step 3

  Create a shell script that automates Step 2, for example:

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


Step 4

  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 [47msystem-call[0m in ACL2
  source file [47macl2-init.lisp[0m.)

    (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)))

  Then here is a log:

    * (provable? '(equal x y))

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

    T
    *

  Certainly refinements are possible --- for example the above doesn't
  distinguish between unprovable and ill-formed input.  But it's a
  start.")
 (ACL2-BUILT-INS
  (PROGRAMMING)
  "''Catch-all'' topic for built-in ACL2 functions

  This [documentation] topic is a parent topic under which we include
  documentation for built-in functions, macros, and special forms
  that are typically used in [programming].  For others, including
  those typically used as top-level commands or those that create
  [events] ([47m[defun][0m, [47m[defmacro][0m, [47m[defthm][0m, 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.

  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,
  [introduction-to-programming-in-ACL2-for-those-who-know-lisp].

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


Subtopics

  [*]
      Multiplication macro

  [*ACL2-exports*]
      Symbols that are often imported into new [packages] to provide easy
      access to ACL2 functionality.

  [*common-lisp-symbols-from-main-lisp-package*]
      Symbols that are often imported into new packages to provide easy
      access to Common Lisp functionality.

  [*standard-ci*]
      An ACL2 character-based analogue of CLTL's [47m*standard-input*[0m

  [*standard-co*]
      The ACL2 analogue of CLTL's [47m*standard-output*[0m

  [*standard-oi*]
      An ACL2 object-based analogue of CLTL's [47m*standard-input*[0m

  [+]
      Addition macro

  [-]
      Macro for subtraction and negation

  [/]
      Macro for division and reciprocal

  [/=]
      Test inequality of two numbers

  [1+]
      Increment by 1

  [1-]
      Decrement by 1

  [<]
      Less-than

  [<=]
      Less-than-or-equal test

  [=]
      Test equality of two numbers

  [>]
      Greater-than test

  [>=]
      Greater-than-or-equal test

  [@]
      Get the value of a global variable in [47m[state][0m

  [Abs]
      The absolute value of a real number

  [Access]
      Accessor macro for [defrec] structures.

  [ACL2-count]
      A commonly used measure for justifying recursion

  [ACL2-number-listp]
      Recognizer for a true list of numbers

  [ACL2-numberp]
      Recognizer for numbers

  [Acons]
      Constructor for association lists

  [Add-to-set]
      Add a symbol to a list

  [Alist-keys-subsetp]
      Check that all keys of the alist belong to a given set

  [Alist-to-doublets]
      Convert an alist to a list of two-element lists

  [Alistp]
      Recognizer for association lists

  [Allocate-fixnum-range]
      Set aside fixnums in GCL

  [Alpha-char-p]
      Recognizer for alphabetic characters

  [Alphorder]
      Total order on atoms

  [And]
      Conjunction

  [Append]
      [concatenate] zero or more lists

  [Apply$]
      Apply a badged function or tame lambda to arguments

  [Aref1]
      Access the elements of a 1-dimensional array

  [Aref2]
      Access the elements of a 2-dimensional array

  [Arities-okp]
      check the arities of given function symbols

  [Arity]
      number of arguments of a function symbol

  [Array1p]
      Recognize a 1-dimensional array

  [Array2p]
      Recognize a 2-dimensional array

  [Aset1]
      Set the elements of a 1-dimensional array

  [Aset1-trusted]
      Set the elements of a 1-dimensional array without [invariant-risk]

  [Aset2]
      Set the elements of a 2-dimensional array

  [Ash]
      Arithmetic shift operation

  [Assert$]
      Cause a hard error if the given test is false

  [Assert*]
      Create a [guard] proof obligation that given test holds

  [Assign]
      Assign to a global variable in [47m[state][0m

  [Assoc]
      Look up key in association list

  [Assoc-keyword]
      Look up key in a [47m[keyword-value-listp][0m

  [Assoc-string-equal]
      Look up key, a string, in association list

  [Atom]
      Recognizer for atoms

  [Atom-listp]
      Recognizer for a true list of [atom]s

  [Binary-*]
      Multiplication function

  [Binary-+]
      Addition function

  [Binary-append]
      [concatenate] two lists

  [Bitp]
      A recognizer for the set of bits, {0,1}

  [Boole$]
      Perform a bit-wise logical operation on 2 two's complement integers

  [Boolean-listp]
      Recognizer for a true list of booleans

  [Booleanp]
      Recognizer for booleans

  [Break$]
      Cause an immediate Lisp break

  [Break-on-error]
      Break when encountering a hard or soft error caused by ACL2

  [Butlast]
      All but a final segment of a list

  [Caaaar]
      [47m[car][0m of the [47m[caaar][0m

  [Caaadr]
      [47m[car][0m of the [47m[caadr][0m

  [Caaar]
      [47m[car][0m of the [47m[caar][0m

  [Caadar]
      [47m[car][0m of the [47m[cadar][0m

  [Caaddr]
      [47m[car][0m of the [47m[caddr][0m

  [Caadr]
      [47m[car][0m of the [47m[cadr][0m

  [Caar]
      [47m[car][0m of the [47m[car][0m

  [Cadaar]
      [47m[car][0m of the [47m[cdaar][0m

  [Cadadr]
      [47m[car][0m of the [47m[cdadr][0m

  [Cadar]
      [47m[car][0m of the [47m[cdar][0m

  [Caddar]
      [47m[car][0m of the [47m[cddar][0m

  [Cadddr]
      [47m[car][0m of the [47m[cdddr][0m

  [Caddr]
      [47m[car][0m of the [47m[cddr][0m

  [Cadr]
      [47m[car][0m of the [47m[cdr][0m

  [Canonical-pathname]
      The true absolute filename, with soft links resolved

  [Car]
      Returns the first element of a non-empty list, else [47mnil[0m

  [Case]
      Conditional based on if-then-else using [47m[eql][0m

  [Case-match]
      Pattern matching or destructuring

  [Cbd]
      Connected book directory string

  [Cdaaar]
      [47m[cdr][0m of the [47m[caaar][0m

  [Cdaadr]
      [47m[cdr][0m of the [47m[caadr][0m

  [Cdaar]
      [47m[cdr][0m of the [47m[caar][0m

  [Cdadar]
      [47m[cdr][0m of the [47m[cadar][0m

  [Cdaddr]
      [47m[cdr][0m of the [47m[caddr][0m

  [Cdadr]
      [47m[cdr][0m of the [47m[cadr][0m

  [Cdar]
      [47m[cdr][0m of the [47m[car][0m

  [Cddaar]
      [47m[cdr][0m of the [47m[cdaar][0m

  [Cddadr]
      [47m[cdr][0m of the [47m[cdadr][0m

  [Cddar]
      [47m[cdr][0m of the [47m[cdar][0m

  [Cdddar]
      [47m[cdr][0m of the [47m[cddar][0m

  [Cddddr]
      [47m[cdr][0m of the [47m[cdddr][0m

  [Cdddr]
      [47m[cdr][0m of the [47m[cddr][0m

  [Cddr]
      [47m[cdr][0m of the [47m[cdr][0m

  [Cdr]
      Returns the second element of a [47m[cons][0m pair, else [47mnil[0m

  [Ceiling]
      Division returning an integer by truncating toward positive infinity

  [Change]
      Mutator macro for [defrec] structures.

  [Char]
      The [nth] element (zero-based) of a string

  [Char-code]
      The numeric code for a given character

  [Char-downcase]
      Turn upper-case [characters] into lower-case [characters]

  [Char-equal]
      Character equality without regard to case

  [Char-upcase]
      Turn lower-case [characters] into upper-case [characters]

  [Char<]
      Less-than test for [characters]

  [Char<=]
      Less-than-or-equal test for [characters]

  [Char>]
      Greater-than test for [characters]

  [Char>=]
      Greater-than-or-equal test for [characters]

  [Character-alistp]
      Recognizer for association lists with characters as keys

  [Character-listp]
      Recognizer for a true list of characters

  [Characterp]
      Recognizer for [characters]

  [Code-char]
      The character corresponding to a given numeric code

  [Coerce]
      Coerce a character list to a string and a string to a list

  [Comment]
      Variant of [47m[prog2$][0m to help debug evaluation failures during proofs

  [Comp]
      Compile some ACL2 functions

  [Comp-gcl]
      Compile some ACL2 functions leaving .c and .h files

  [Complex]
      Create an ACL2 number

  [Complex-rationalp]
      Recognizes complex rational numbers

  [Complex/complex-rationalp]
      Recognizer for complex numbers

  [Compress1]
      Remove irrelevant pairs from a 1-dimensional array

  [Compress2]
      Remove irrelevant pairs from a 2-dimensional array

  [Concatenate]
      Concatenate lists or strings together

  [Cond]
      Conditional based on if-then-else

  [Conjugate]
      Complex number conjugate

  [Cons]
      Pair and list constructor

  [Cons-count-bounded]
      Count the number of conses (up to a limit)

  [Cons-subtrees]
      Build a fast alist whose keys are the subtrees of X

  [Cons-with-hint]
      Alternative to [47m[cons][0m that tries to avoid consing when a suitable
      [47mcons[0m structure is provided as a hint.

  [Consp]
      Recognizer for [cons] pairs

  [Count]
      Count the number of occurrences of an item in a string or true-list

  [Count-keys]
      Count the number of keys in association list

  [Cpu-core-count]
      The number of cpu cores

  [Cw]
      Print to the comment window

  [Cw!]
      Print readably to the comment window

  [Cw!+]
      Print readably and uninhibited to the comment window

  [Cw+]
      Print uninhibited to the comment window

  [Cw-print-base-radix]
      Print to the comment window in a given print-base

  [Cw-print-base-radix!]
      Print to the comment window in a given print-base

  [Declare]
      Extra declarations that can occur in function definitions, [let]
      bindings, and so forth.

  [Default]
      Return the [47m:default[0m from the [header] of a 1- or 2-dimensional array

  [Defbadge]
      Issue a badge for a function so [47m[apply$][0m can evaluate with it

  [Defwarrant]
      Issue a warrant for a function so [47m[apply$][0m can use it in proofs

  [Delete-assoc]
      Deprecated version of [remove1-assoc]

  [Denominator]
      Divisor of a ratio in lowest terms

  [Df]
      Support for floating-point operations

  [Digit-char-p]
      The number, if any, corresponding to a given character

  [Digit-to-char]
      Map a digit to a character

  [Dimensions]
      Return the [47m:dimensions[0m from the [header] of a 1- or 2-dimensional
      array

  [Ec-call]
      Execute a call in the ACL2 logic instead of raw Lisp

  [Eighth]
      Eighth member of the list

  [Endp]
      Recognizer for empty lists

  [Eq]
      Equality of symbols

  [Eql]
      Test equality (of two numbers, symbols, or [characters])

  [Eqlable-alistp]
      Recognizer for a true list of pairs whose [47m[car][0ms are suitable for
      [47m[eql][0m

  [Eqlable-listp]
      Recognizer for a true list of objects each suitable for [47m[eql][0m

  [Eqlablep]
      The [guard] for the function [47m[eql][0m

  [Equal]
      True equality

  [Er]
      Print an error message and ``cause an error''

  [Er-hard]
      Print an error message and ``cause a hard error''

  [Er-hard?]
      Print an error message and ``cause a hard error''

  [Er-progn]
      Perform a sequence of state-changing ``error triples''

  [Er-soft]
      Print an error message and ``cause a soft error''

  [Error1]
      Print an error message and cause a ``soft error''

  [Evenp]
      Test whether an integer is even

  [Evens]
      The even-indexed members of a list

  [Explode-atom]
      Convert any [atom] into a [character-listp] that contains its
      printed representation, rendering numbers in your choice of
      print base.

  [Explode-nonnegative-integer]
      The list of [characters] in the radix-r form of a number

  [Expt]
      Exponential function

  [Extend-pathname]
      Extend a relative pathname to an absolute pathname

  [F-boundp-global]
      Check whether a global variable in [47m[state][0m has a value

  [F-get-global]
      Get the value of a global variable in [47m[state][0m

  [F-put-global]
      Assign to a global variable in [47m[state][0m

  [Fast-alist-clean]
      [47m(fast-alist-clean alist)[0m can be used to eliminate \"shadowed pairs\"
      from a fast alist.

  [Fast-alist-clean!]
      [47m(fast-alist-clean! alist)[0m is an alternative to [47m[fast-alist-clean][0m
      that produces a [normed] result.

  [Fast-alist-fork]
      [47m(fast-alist-fork alist ans)[0m can be used to eliminate \"shadowed
      pairs\" from an alist or to copy [fast-alists].

  [Fast-alist-fork!]
      [47m(fast-alist-fork! alist ans)[0m is an alternative to [47m[fast-alist-fork][0m
      that produces a [normed] result.

  [Fast-alist-free]
      [47m(fast-alist-free alist)[0m throws away the hash table associated with a
      fast alist.

  [Fast-alist-free-on-exit]
      Free a fast alist after the completion of some form.

  [Fast-alist-len]
      [47m(fast-alist-len alist)[0m counts the number of unique keys in a fast
      alist.

  [Fast-alist-summary]
      [47m(fast-alist-summary)[0m prints some basic statistics about any current
      fast alists.

  [Fifth]
      Fifth member of the list

  [First]
      First member of the list

  [Fix]
      Coerce to a number

  [Fix-true-list]
      Coerce to a true list

  [Flet]
      Local binding of function symbols

  [Floor]
      Division returning an integer by truncating toward negative infinity

  [Flush-compress]
      Flush the under-the-hood array for the given name

  [Flush-hons-get-hash-table-link]
      Deprecated feature

  [Fms]
      [47m(fms str alist co-channel state evisc) => state[0m

  [Fms!]
      [47m(fms! str alist co-channel state evisc) => state[0m

  [Fmt]
      Formatted printing

  [Fmt!]
      [47m(fmt! str alist co-channel state evisc) => state[0m

  [Fmt-to-comment-window]
      Print to the comment window

  [Fmt-to-comment-window!]
      Print readably to the comment window

  [Fmt-to-comment-window!+]
      Print readably and uninhibited to the comment window

  [Fmt-to-comment-window+]
      Print uninhibited to the comment window

  [Fmt1]
      [47m(fmt1 str alist col co-channel state evisc) => (mv col state)[0m

  [Fmt1!]
      [47m(fmt1! str alist col channel state evisc) => (mv col state)[0m

  [Fmx]
      [47m(fmx str &rest args) => state[0m

  [Fmx-cw]
      [47m(fmx-cw str &rest args) => state[0m

  [Formula]
      The formula of a name or [rune]

  [Fourth]
      Fourth member of the list

  [Gc$]
      Invoke the garbage collector

  [Gc-strategy]
      The garbage collection strategy

  [Get-cpu-time]
      Read elapsed cpu time

  [Get-internal-time]
      Runtime vs. realtime in ACL2 timings

  [Get-real-time]
      Read elapsed real time

  [Getenv$]
      Read an environment variable

  [Getprop]
      Access fast property lists

  [Getpropc]
      Access fast property lists

  [Good-bye]
      Quit entirely out of Lisp

  [Hard-error]
      Print an error message and stop execution

  [Header]
      Return the header of a 1- or 2-dimensional array

  [Hons]
      [47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m.

  [Hons-acons]
      [47m(hons-acons key val alist)[0m is the main way to create or extend
      [fast-alists].

  [Hons-acons!]
      [47m(hons-acons! key val alist)[0m is an alternative to [47m[hons-acons][0m that
      produces [normed], fast alists.

  [Hons-assoc-equal]
      [47m(hons-assoc-equal key alist)[0m is [31;1mnot fast[0m; it serves as the logical
      definition for [47m[hons-get][0m.

  [Hons-clear]
      [47m(hons-clear gc)[0m is a drastic garbage collection mechanism that
      clears out the underlying Hons Space.

  [Hons-clear!]
      A version of [47m[hons-clear][0m for [parallel] execution

  [Hons-copy]
      [47m(hons-copy x)[0m returns a [normed] object that is equal to X.

  [Hons-copy-persistent]
      [47m(hons-copy-persistent x)[0m returns a [normed] object that is equal to
      X and which will be re-normed after any calls to [47m[hons-clear][0m.

  [Hons-equal]
      [47m(hons-equal x y)[0m is a recursive equality check that optimizes when
      parts of its arguments are [normed].

  [Hons-get]
      [47m(hons-get key alist)[0m is the efficient lookup operation for
      [fast-alists].

  [Hons-resize]
      [47m(hons-resize ...)[0m can be used to manually adjust the sizes of the
      hash tables that govern which ACL2 Objects are considered
      [normed].

  [Hons-shrink-alist]
      Deprecated feature

  [Hons-shrink-alist!]
      Deprecated feature

  [Hons-summary]
      [47m(hons-summary)[0m prints basic information about the sizes of the
      tables in the current Hons Space.

  [Hons-wash]
      [47m(hons-wash)[0m is like [47m[gc$][0m but can also garbage collect [normed]
      objects (CCL and GCL Only).

  [Hons-wash!]
      A version of [47m[hons-wash][0m for [parallel] execution

  [Identity]
      The identity function

  [If]
      If-then-else function

  [Iff]
      Logical ``if and only if''

  [Ifix]
      Coerce to an integer

  [Illegal]
      Print an error message and stop execution

  [Imagpart]
      Imaginary part of a complex number

  [Implies]
      Logical implication

  [Improper-consp]
      Recognizer for improper (non-[47mnil[0m-terminated) non-empty lists

  [In-package]
      Select current package

  [In-tau-intervalp]
      Boolean membership in a tau interval

  [Int=]
      Test equality of two integers

  [Integer-length]
      Number of bits in two's complement integer representation

  [Integer-listp]
      Recognizer for a true list of integers

  [Integer-range-p]
      Recognizer for integers between two bounds.

  [Integerp]
      Recognizer for whole numbers

  [Intern]
      Create a new symbol in a given package

  [Intern$]
      Create a new symbol in a given package

  [Intern-in-package-of-symbol]
      Create a symbol with a given name

  [Intersection$]
      Elements common to the given lists

  [Intersectp]
      Test whether two lists intersect

  [Keyword-listp]
      Recognizer for true lists of keywords

  [Keyword-value-listp]
      Recognizer for true lists whose even-position elements are keywords

  [Keywordp]
      Recognizer for keywords

  [Kwote]
      Quote an arbitrary object

  [Kwote-lst]
      Quote an arbitrary true list of objects

  [Last]
      The last [47m[cons][0m (not element) of a list

  [Last-cdr]
      The last [47m[cdr][0m of a list

  [Last-prover-steps]
      The number of prover steps most recently taken

  [Len]
      Length of a list

  [Length]
      Length of a string or proper list

  [Let]
      Binding of lexically scoped (local) variables

  [Let*]
      Binding of lexically scoped (local) variables

  [Lexorder]
      Total order on ACL2 objects

  [List]
      Build a list

  [List$]
      Build a list

  [List*]
      Build a list

  [Listp]
      Recognizer for (not necessarily proper) lists

  [Logand]
      Bitwise logical `and' of zero or more integers

  [Logandc1]
      Bitwise logical `and' of two ints, complementing the first

  [Logandc2]
      Bitwise logical `and' of two ints, complementing the second

  [Logbitp]
      The [47mi[0mth bit of an integer

  [Logcount]
      Number of ``on'' bits in a two's complement number

  [Logeqv]
      Bitwise logical equivalence of zero or more integers

  [Logic-fns-list-listp]
      Recognizer for when a given list of lists of [term]s calls only
      [47m:[0m[47m[logic][0m-mode function symbols

  [Logic-fns-listp]
      Recognizer for when a given list of [term]s calls only [47m:[0m[47m[logic][0m-mode
      function symbols

  [Logic-fnsp]
      Recognizer for when a given [term] calls only [47m:[0m[47m[logic][0m-mode function
      symbols

  [Logic-term-list-listp]
      Recognizer for lists of lists of [term]s that call only
      [47m:[0m[47m[logic][0m-mode function symbols

  [Logic-term-listp]
      Recognizer for lists of [term]s that call only [47m:[0m[47m[logic][0m-mode
      function symbols

  [Logic-termp]
      Recognizer for [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols

  [Logior]
      Bitwise logical inclusive or of zero or more integers

  [Lognand]
      Bitwise logical `nand' of two integers

  [Lognor]
      Bitwise logical `nor' of two integers

  [Lognot]
      Bitwise not of a two's complement number

  [Logorc1]
      Bitwise logical inclusive or of two ints, complementing the first

  [Logorc2]
      Bitwise logical inclusive or of two ints, complementing the second

  [Logtest]
      Test if two integers share a `1' bit

  [Logxor]
      Bitwise logical exclusive or of zero or more integers

  [Loop$]
      Iteration with an analogue of the Common Lisp [47mloop[0m macro

  [Lower-case-p]
      Recognizer for lower case characters

  [Macrolet]
      Local binding of macro symbols

  [Make]
      Constructor macro for [defrec] structures.

  [Make-character-list]
      [coerce] to a list of characters

  [Make-fast-alist]
      [47m(make-fast-alist alist)[0m creates a fast-alist from the input alist,
      returning [47malist[0m itself or, in some cases, a new object equal to
      it.

  [Make-list]
      Make a list of a given size

  [Make-ord]
      A constructor for ordinals.

  [Make-tau-interval]
      Make a tau interval

  [Makunbound-global]
      Remove the value assigned to a global variable in [47m[state][0m

  [Max]
      The larger of two numbers

  [Maximum-length]
      Return the [47m:maximum-length[0m from the [header] of an array

  [Maybe-flush-and-compress1]
      Compress a one-dimensional array only if necessary

  [Mbe]
      Attach code for execution

  [Mbe1]
      Attach code for execution

  [Mbt]
      Introduce a test into the logic that, however, evaluates to [47mt[0m

  [Mbt*]
      Introduce a guard proof obligation

  [Member]
      Membership predicate

  [Merge-sort-lexorder]
      Sort a list

  [Min]
      The smaller of two numbers

  [Minusp]
      Test whether a number is negative

  [Mod]
      Remainder using [47m[floor][0m

  [Mod-expt]
      Exponential function

  [Msg]
      Construct a ``message'' suitable for the [47m~@[0m directive of [47m[fmt][0m

  [Msgp]
      Recognizer for a ``message''

  [Must-be-equal]
      Attach code for execution

  [Mv]
      Returning a multiple value

  [Mv-let]
      Calling multi-valued ACL2 functions

  [Mv-list]
      Converting [multiple-value] result to a single-value list

  [Mv-nth]
      The mv-nth element (zero-based) of a list

  [Mv?]
      Return one or more values

  [Mv?-let]
      Calling possibly multi-valued ACL2 functions

  [Nat-listp]
      Recognizer for a true list of natural numbers

  [Natp]
      A recognizer for the natural numbers

  [Nfix]
      Coerce to a natural number

  [Ninth]
      Ninth member of the list

  [No-duplicatesp]
      Check for duplicates in a list

  [Non-exec]
      Mark code as non-executable

  [Nonnegative-integer-quotient]
      Natural number division function

  [Not]
      Logical negation

  [Nth]
      The nth element (zero-based) of a list

  [Nthcdr]
      Final segment of a list

  [Null]
      Recognizer for the empty list

  [Number-subtrees]
      [47m(number-subtrees x)[0m returns the number of distinct subtrees of X, in
      the sense of [47m[equal][0m

  [Numerator]
      Dividend of a ratio in lowest terms

  [O-finp]
      Recognizes if an ordinal is finite

  [O-first-coeff]
      Returns the first coefficient of an ordinal

  [O-first-expt]
      The first exponent of an ordinal

  [O-infp]
      Recognizes if an ordinal is infinite

  [O-p]
      A recognizer for the ordinals up to epsilon-0

  [O-rst]
      Returns the rest of an infinite ordinal

  [O<]
      The well-founded less-than relation on ordinals up to [47mepsilon-0[0m

  [O<=]
      The less-than-or-equal relation for the ordinals

  [O>]
      The greater-than relation for the ordinals

  [O>=]
      The greater-than-or-equal relation for the ordinals

  [Observation]
      Print an observation

  [Oddp]
      Test whether an integer is odd

  [Odds]
      The odd-indexed members of a list

  [Open-output-channel!]
      When trust tags are needed to open output channels

  [Or]
      Disjunction

  [Packn]
      Build a symbol from a list

  [Packn-pos]
      Build a symbol in a specified package from a list

  [Pairlis$]
      Zipper together two lists

  [Pairlis-x1]
      Cons a given element to each member of a list

  [Pairlis-x2]
      Cons each element of a list with a given element

  [Pand]
      Parallel, Boolean version of [47m[and][0m

  [Pargs]
      Parallel evaluation of arguments in a function call

  [Pkg-witness]
      Return a specific symbol in the indicated package

  [Plet]
      Parallel version of [47m[let][0m

  [Plusp]
      Test whether a number is positive

  [Por]
      Parallel, Boolean version of [47m[or][0m

  [Pos-listp]
      Recognizer for a true list of positive integers

  [Position]
      Position of an item in a string or a list

  [Posp]
      A recognizer for the positive integers

  [Pprogn]
      Evaluate a sequence of forms that return [state]

  [Primitive]
      Primitive functions built into ACL2 without definitions

  [Princ$]
      Print an atom

  [Print-base-p]
      Recognizer for print bases that are understood by functions such as
      [explode-nonnegative-integer] and [explode-atom].

  [Print-object$]
      Print an object to an open object output channel

  [Print-object$+]
      Print an object to an open output channel in a specified manner

  [Prog2$]
      Execute two forms and return the value of the second one

  [Progn$]
      Execute a sequence of forms and return the value of the last one

  [Proofs-co]
      The proofs character output channel

  [Proper-consp]
      Recognizer for proper ([47mnil[0m-terminated) non-empty lists

  [Pseudo-term-listp]
      A predicate for recognizing lists of term-like s-expressions

  [Pseudo-termp]
      A predicate for recognizing term-like s-expressions

  [Put-assoc]
      Modify an association list by associating a value with a key

  [Putprop]
      Update fast property lists

  [Quote]
      Create a constant

  [R-eqlable-alistp]
      Recognizer for a true list of pairs whose [47m[cdr][0ms are suitable for
      [47m[eql][0m

  [R-symbol-alistp]
      Recognizer for association lists with symbols as values

  [Random$]
      Obtain a random value

  [Rassoc]
      Look up value in association list

  [Rational-listp]
      Recognizer for a true list of rational numbers

  [Rationalp]
      Recognizer for rational numbers (ratios and integers)

  [Read-ACL2-oracle]
      Pop the oracle field of the state

  [Read-run-time]
      Read elapsed runtime

  [Real-listp]
      ACL2(r) recognizer for a true list of real numbers

  [Real/rationalp]
      Recognizer for rational numbers (including real number in ACL2(r))

  [Realfix]
      Coerce to a real number

  [Realpart]
      Real part of a complex number

  [Rem]
      Remainder using [47m[truncate][0m

  [Remove]
      Remove all occurrences

  [Remove-assoc]
      Remove all pairs with a given key from an association list

  [Remove-duplicates]
      Remove duplicates from a string or a list

  [Remove1]
      Remove first occurrences, testing using [47m[eql][0m

  [Remove1-assoc]
      Remove the first pair with a given key from an association list

  [Resize-list]
      List resizer in support of [stobj]s

  [Rest]
      Rest ([47m[cdr][0m) of the list

  [Return-last]
      Return the last argument, perhaps with side effects

  [Revappend]
      Concatenate the [reverse] of one list to another

  [Reverse]
      Reverse a list or string

  [Rfix]
      Coerce to a rational number

  [Round]
      Division returning an integer by rounding off

  [Search]
      Search for a string or list in another string or list

  [Second]
      Second member of the list

  [Serialize-read]
      Read a serialized ACL2 object from a file

  [Serialize-write]
      Write an ACL2 object into a file

  [Set-difference$]
      Elements of one list that are not elements of another

  [Set-fmt-hard-right-margin]
      Set the right margin for formatted output

  [Set-fmt-soft-right-margin]
      Set the soft right margin for formatted output

  [Set-gc-strategy]
      Set the garbage collection strategy (CCL only)

  [Set-print-base]
      Control radix in which numbers are printed

  [Set-print-base-radix]
      Control radix in which numbers are printed and printing of the radix

  [Set-print-case]
      Control whether symbols are printed in upper case or in lower case

  [Set-print-radix]
      Control printing of the radix for numbers

  [Setenv$]
      Set an environment variable

  [Seventh]
      Seventh member of the list

  [Signed-byte-p]
      Recognizer for signed integers that fit in a specified bit width

  [Signum]
      Indicator for positive, negative, or zero

  [Sixth]
      Sixth member of the list

  [Spec-mv-let]
      Modification of [47m[mv-let][0m supporting speculative and parallel
      execution

  [Standard-char-listp]
      Recognizer for a true list of standard characters

  [Standard-char-p]
      Recognizer for standard characters

  [Standard-char-p+]
      Recognizer for standard characters whose guard is [47mt[0m

  [Standard-co]
      The character output channel to which [47m[ld][0m prints

  [Standard-oi]
      The standard object input ``channel''

  [State-global-let*]
      Bind [state] global variables

  [String]
      [coerce] to a string

  [String-alistp]
      Recognizer for association lists with strings as keys

  [String-append]
      [concatenate] two strings

  [String-downcase]
      In a given string, turn upper-case [characters] into lower-case

  [String-equal]
      String equality without regard to case

  [String-listp]
      Recognizer for a true list of strings

  [String-upcase]
      In a given string, turn lower-case [characters] into upper-case

  [String<]
      Less-than test for strings

  [String<=]
      Less-than-or-equal test for strings

  [String>]
      Greater-than test for strings

  [String>=]
      Less-than-or-equal test for strings

  [Stringp]
      Recognizer for strings

  [Strip-cars]
      Collect up all first components of pairs in a list

  [Strip-cdrs]
      Collect up all second components of pairs in a list

  [Sublis]
      Substitute an alist into a tree

  [Subseq]
      Subsequence of a string or list

  [Subsetp]
      Test if every [47m[member][0m of one list is a [47m[member][0m of the other

  [Subst]
      A single substitution into a tree

  [Substitute]
      Substitute into a string or a list, using [47m[eql][0m as test

  [Swap-stobjs]
      Swap two congruent [stobj]s

  [Symbol-alistp]
      Recognizer for association lists with symbols as keys

  [Symbol-listp]
      Recognizer for a true list of symbols

  [Symbol-name]
      The name of a symbol (a string)

  [Symbol-name-lst]
      Lift [47m[symbol-name][0m to lists

  [Symbol-package-name]
      The name of the package of a symbol (a string)

  [Symbol<]
      Less-than test for symbols

  [Symbolp]
      Recognizer for symbols

  [Sys-call]
      Make a system call to the host operating system

  [Sys-call*]
      Make a system call to the host OS, returning a status

  [Sys-call+]
      Make a system call to the host OS, returning status and output

  [Sys-call-status]
      Exit status from the preceding system call

  [Take]
      Initial segment (first n elements) of a list

  [Tenth]
      Tenth member of the list

  [Term-list-listp]
      recognizer for a list of [clause]s

  [Term-listp]
      recognizer for a list of quotations of terms and of [clause]s

  [Term-order]
      The ordering relation on terms used by ACL2

  [Termp]
      recognizer for the quotation of a [term]

  [The]
      Special form for execution efficiency or run-time type checks

  [The-number]
      Coerce an expected number to a number

  [The-true-list]
      Coerce an expected true list to a true list

  [Third]
      Third member of the list

  [Time$]
      Time the evaluation of a given form

  [Time-tracker]
      Display time spent during specified evaluation

  [Trace-co]
      The [trace] character output channel

  [True-list-fix]
      Coerce to a true list

  [True-list-listp]
      Recognizer for true (proper) lists of true lists

  [True-listp]
      Recognizer for proper ([47mnil[0m-terminated) lists

  [Truncate]
      Division returning an integer by truncating toward 0

  [Unary--]
      Arithmetic negation function

  [Unary-/]
      Reciprocal function

  [Union$]
      A list that contains exactly the elements of the given lists

  [Unquote]
      Obtain the object being quoted

  [Unsigned-byte-p]
      Recognizer for natural numbers that fit in a specified bit width

  [Update-nth]
      Modify a list by putting the given value at the given position

  [Update-nth-array]
      Update a stobj array

  [Upper-case-p]
      Recognizer for upper case characters

  [Value-triple]
      Compute a value, optionally checking that it is not [47mnil[0m

  [With-fast-alist]
      [47m(with-fast-alist name form)[0m causes [47mname[0m to be a fast alist for the
      execution of [47mform[0m.

  [With-global-stobj]
      Operate on a global single-threaded object

  [With-guard-checking]
      Suppress or enable guard-checking for a form

  [With-guard-checking-error-triple]
      Suppress or enable guard-checking for a form

  [With-guard-checking-event]
      Suppress or enable guard-checking for an event form

  [With-live-state]
      Allow a reference to [47mstate[0m in raw Lisp

  [With-local-state]
      Locally bind state

  [With-local-stobj]
      Locally bind a single-threaded object

  [With-output-lock]
      Provides a mutual-exclusion mechanism for performing output in
      parallel

  [With-serialize-character]
      Control output mode for [47mprint-object$[0m

  [With-stolen-alist]
      [47m(with-stolen-alist name form)[0m ensures that [47mname[0m is a fast alist at
      the start of the execution of [47mform[0m.  At the end of execution,
      it ensures that [47mname[0m is a fast alist if and only if it was
      originally.  That is, if [47mname[0m was not a fast alist originally,
      its hash table link is freed, and if it was a fast alist
      originally but its table was modified during the execution of
      [47mform[0m, that table is restored.  Note that any extended table
      created from the original fast alist during [47mform[0m must be
      manually freed.

  [Without-evisc]
      Print output in full

  [Xor]
      Logical ``exclusive or''

  [Zerop]
      Test an acl2-number against 0

  [Zip]
      Testing an ``integer'' against 0

  [Zp]
      Testing a ``natural'' against 0

  [Zpf]
      Testing a nonnegative fixnum against 0")
 (ACL2-COUNT
  (BASICS ACL2-BUILT-INS)
  "A commonly used measure for justifying recursion

  [47m(Acl2-count x)[0m returns a nonnegative integer that indicates the
  ``size'' of its argument [47mx[0m.

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

  [31;1mFunction: [0m<acl2-count>

    (defun acl2-count (x)
      (declare (xargs :guard t))
      (if (consp x)
          (+ 1 (acl2-count (car x))
             (acl2-count (cdr x)))
        (if (rationalp x)
            (if (integerp x)
                (integer-abs x)
              (+ (integer-abs (numerator x))
                 (denominator x)))
          (if (complex/complex-rationalp x)
              (+ 1 (acl2-count (realpart x))
                 (acl2-count (imagpart x)))
            (if (stringp x) (length x) 0)))))")
 (ACL2-CUSTOMIZATION
  (MISCELLANEOUS)
  "File of initial commands for ACL2 to run at [startup]

  ACL2 provides a mechanism to load automatically a so-called ``ACL2
  customization file,'' via [47m[ld][0m, the first time [47m[lp][0m is called in an
  ACL2 session.  ACL2 looks for this file as follows.

   1. If the host Lisp reads a non-empty value for the system's environment
      variable [47mACL2_CUSTOMIZATION[0m, 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:

        * If the customization file name is a relative pathname (see
          [pathname]), then the pathname is considered relative to
          the connected book directory (see [cbd]).

        * If this variable is not already defined, then its value is set to
          [47mNONE[0m when books are certified using [build::cert.pl] or
          other, legacy Make-based certification tools.

   2. Otherwise (empty environment variable value), file
      [47m\"acl2-customization.lsp\"[0m or [47m\"acl2-customization.lisp\"[0m on the
      connected book directory (see [cbd]), generally the current
      directory, is the customization file (in that order) if either
      exists.

   3. Otherwise file [47m\"acl2-customization.lsp\"[0m or [47m\"acl2-customization.lisp\"[0m
      on your home directory is the customization file (in that
      order), if either exists (except, this case is skipped on
      Windows operating systems.

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

  If the customization file exists, it is loaded with [47m[ld][0m using the
  usual default values for the [47m[ld][0m specials (see [ld]) except that
  [47m:ld-error-action[0m is [47m:error[0m.  If an error is encountered, then no
  subsequent forms in the file will be evaluated and ACL2 will quit
  immediately.

  To create a customization file it is recommended that you first give
  it a name other than [47m\"acl2-customization.lsp\"[0m or
  [47m\"acl2-customization.lisp\"[0m so that ACL2 does not try to include it
  prematurely when you next enter [47m[lp][0m.  Then, while in the
  uncustomized [47m[lp][0m, explicitly invoke [47m[ld][0m 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 [47m[ld][0m it automatically and then debug the new file by
  explicit calls to [47m[ld][0m.

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

  On the other hand, if you wish to prevent undoing commands from the
  customization file, see [reset-prehistory].

  Note that except on Windows-based systems, if there is a file
  [47macl2-init.lsp[0m in your home directory, then it will be loaded into
  raw Lisp when ACL2 is invoked.


Silent loading of ACL2 customization files

  When the environment variable [47mACL2_CUSTOMIZATION_QUIET[0m is set and not
  [47m\"\"[0m, there will generally be no output from ACL2 customization.  A
  special value of [47m\"all\"[0m for this variable will cause continued
  minimal output after startup, as explained in the following remark.

  Technical Remark.  For quiet loading of acl2-customization files,
  [47m[ld][0m specials are bound to the following values.

    ld-verbose = nil
    ld-pre-eval-print = :never
    ld-post-eval-print = nil
    ld-prompt = nil

  These [47mld[0m specials are returned to their normal values after loading
  an ACL2 customization file, with one exception: if
  [47mACL2_CUSTOMIZATION_QUIET[0m has value [47m\"ALL\"[0m (or [47m\"all\"[0m; the case is
  irrelevant), then those values are retained in the ACL2 loop even
  after customization completes.")
 (ACL2-DEFAULTS-TABLE
  (TABLE)
  "A [table] specifying certain defaults, e.g., the default [defun-mode]

    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

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

    :user

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

    :defun-mode

  the default [defun-mode], which must be [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m.  See
  [defun-mode] for a general discussion of [defun-mode]s.  The
  [47m:[0m[47m[defun-mode][0m key may be conveniently set by keyword commands
  naming the new [defun-mode], [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m.  See
  [program] and see [logic].

    :enforce-redundancy

  if [47mt[0m, cause ACL2 to insist that most events are redundant (see
  [redundant-events]); if [47m:warn[0m, cause a warning instead of an error
  for such non-redundant events; else, [47mnil[0m.  See
  [set-enforce-redundancy].

    :verify-guards-eagerness

  an integer between 0 and 3 indicating how eager the system is to
  verify the [guard]s of a [defun] event.  See
  [set-verify-guards-eagerness].

    :compile-fns

  When this key's value is [47mt[0m, functions are compiled when they are
  [47m[defun][0m'd; otherwise, the value is [47mnil[0m.  (Except, this key's value
  is ignored when explicit compilation is suppressed; see
  [compilation].)  To set the flag, see [set-compile-fns].

    :measure-function

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

    :well-founded-relation

  the default well-founded relation used by [47m[defun][0m when no
  [47m:well-founded-relation[0m is supplied in [47m[xargs][0m.  The default
  well-founded relation must be a function symbol, [47mrel[0m, of two
  arguments about which a [47m:well-founded-relation[0m rule has been
  proved.  See [well-founded-relation-rule].

    :bogus-defun-hints-ok

  When this key's value is [47mt[0m, ACL2 allows [47m:hints[0m and also [47m:measure[0m for
  nonrecursive function definitions.  Otherwise, the value is [47mnil[0m
  (the default) or [47m:warn[0m (which makes the check but merely warns when
  the check fails).  See [set-bogus-defun-hints-ok] and
  [set-bogus-measure-ok].

    :bogus-mutual-recursion-ok

  When this key's value is [47mt[0m, ACL2 skips the check that every function
  in a [47m[mutual-recursion][0m (or [47m[defuns][0m) ``clique'' calls at least one
  other function in that ``clique.'' Otherwise, the value is [47mnil[0m (the
  default) or [47m:warn[0m (which makes the check but merely warns when the
  check fails).  See [set-bogus-mutual-recursion-ok].

    :irrelevant-formals-ok

  When this key's value is [47mt[0m, the check for irrelevant formals is
  bypassed; otherwise, the value is the keyword [47mnil[0m (the default) or
  [47m:warn[0m (which makes the check but merely warns when the check
  fails).  See [irrelevant-formals] and see
  [set-irrelevant-formals-ok].

    :ignore-ok

  When this key's value is [47mt[0m, the check for ignored variables is
  bypassed; otherwise, the value is the keyword [47mnil[0m (the default) or
  [47m:warn[0m (which makes the check but merely warns when the check
  fails).  See [set-ignore-ok].

    :bdd-constructors

  This key's value is a list of function symbols used to define the
  notion of ``BDD normal form.'' See [bdd-algorithm] and see [hints].

    :ttag

  This key's value, when non-[47mnil[0m, allows certain operations that extend
  the trusted code base beyond what is provided by ACL2.  See
  [defttag].  See [defttag].

    :state-ok

  This key's value is either [47mt[0m or [47mnil[0m and indicates whether the user is
  aware of the syntactic restrictions on the variable symbol [47mSTATE[0m.
  See [set-state-ok].

    :backchain-limit

  This key's value is a list of two ``numbers.'' Either ``number'' may
  optionally be [47mnil[0m, which is treated like positive infinity.  The
  numbers control backchaining through hypotheses during
  [type-reasoning] and rewriting.  See [backchain-limit].

    :default-backchain-limit

  This key's value is a list of two ``numbers.'' Either ``number'' may
  optionally be [47mnil[0m, 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 [backchain-limit].

    :step-limit

  This key's value is either [47mnil[0m or a natural number not exceeding the
  value of [47m*default-step-limit*[0m.  If the value is [47mnil[0m or the value of
  [47m*default-step-limit*[0m, 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
  [set-prover-step-limit].

    :rewrite-stack-limit

  This key's value is a nonnegative integer less than [47m(expt 2 28)[0m.  It
  is used to limit the depth of calls of ACL2 rewriter functions.
  See [rewrite-stack-limit].

    :let*-abstractionp

  This key affects how the system displays subgoals.  The value is
  either [47mt[0m or [47mnil[0m.  When t, let* expressions are introduced before
  printing to eliminate common subexpressions.  The actual goal being
  worked on is unchanged.

    :case-split-limitations

  This key's value is a list of two ``numbers.'' Either ``number'' may
  optionally be [47mnil[0m, which is treated like positive infinity.  The
  numbers control how the system handles case splits in the
  simplifier.  See [set-case-split-limitations].

    :include-book-dir-alist

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

    :match-free-default

  This key's value is either [47m:all[0m, [47m:once[0m, or [47mnil[0m.  See
  [set-match-free-default].

    :match-free-override

  This key's value is a list of runes.  See [add-match-free-override].

    :match-free-override-nume

  This key's value is an integer used in the implementation of
  [add-match-free-override], so that only existing runes are affected
  by that event.

    :non-linearp

  This key's value is either [47mt[0m or [47mnil[0m and indicates whether the user
  wishes ACL2 to extend the linear arithmetic decision procedure to
  include non-linear reasoning.  See [non-linear-arithmetic].

    :tau-auto-modep

  This key's value is either [47mt[0m or [47mnil[0m and indicates whether the user
  wishes ACL2 to look for opportunities to create [47m:[0m[47m[tau-system][0m rules
  from all suitable [47mdefun[0ms and from all suitable [47mdefthm[0ms (with
  non-[47mnil[0m [47m:[0m[47m[rule-classes][0m).  See [set-tau-auto-mode].

    :ruler-extenders

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

    :memoize-ideal-okp

  This key's value must be either [47mt[0m, [47mnil[0m, or [47m:warn[0m.  If the value is
  [47mnil[0m or not present, then it is illegal by default to [memoize] a
  [47m:[0m[47m[logic][0m mode function that has not been [guard]-verified (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 [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 [47m:[0m[47m[program][0m mode function, so we allow you
  to override the default behavior by associating the value [47mt[0m or
  [47m:warn[0m with the key [47m:memoize-ideal-okp[0m, where with [47m:warn[0m you get a
  suitable warning.  Note that you can also allow memoization of
  ideal-mode functions by supplying argument [47m:ideal-okp[0m to your
  memoization event (see [memoize]), in which case the value of
  [47m:memoize-ideal-okp[0m in the [47macl2-defaults-table[0m is irrelevant.

    :check-invariant-risk

  For an explanation of this key, see [set-check-invariant-risk].

    :register-invariant-risk

  For an explanation of this key, see [set-register-invariant-risk].

    :in-theory-redundant-okp

  When this key's value is [47mt[0m, an [47m[in-theory][0m event may be redundant.
  See [47m[set-in-theory-redundant-okp][0m.

  Note: Unlike all other [table]s, [47macl2-defaults-table[0m can affect the
  soundness of the system.  The [table] mechanism therefore enforces
  on it a restriction not imposed on other [table]s: when [47m[table][0m is
  used to update the [47macl2-defaults-table[0m, the key and value must be
  variable-free forms.  Thus, while

    (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*))

  are all examples of legal [events] (assuming [47mcompute-mode[0m is a
  function of one non-[47m[state][0m argument that produces a [defun-mode]
  as its single value),

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

  is not legal because the value form is [47m[state][0m-sensitive.

  Consider for example the following three [events] which one might
  make into the text of a book.

    (in-package \"ACL2\")

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

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

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

  For similar reasons, [47m[table][0m [events] affecting [47macl2-defaults-table[0m
  are illegal within the scope of [47m[local][0m forms.  That is, the text

    (in-package \"ACL2\")

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

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

  is illegal because [47macl2-defaults-table[0m is changed locally.  If this
  text were acceptable as a book, then when the book was certified,
  [47mcrash-and-burn[0m would be processed in [47m:[0m[47m[program][0m mode, but when the
  certified book was included later, [47mcrash-and-burn[0m would have
  [47m:[0m[47m[logic][0m mode because the [47m[local][0m event would be skipped.

  The text

    (in-package \"ACL2\")

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

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

  is acceptable and defines [47mcrash-and-burn[0m in [47m:[0m[47m[program][0m mode, both
  during certification and subsequent inclusion.

  We conclude with important observations about the interaction of the
  [47macl2-defaults-table[0m with [47m[include-book][0m, [47m[certify-book][0m, and
  [47m[encapsulate][0m.  If the [47macl2-defaults-table[0m has value [47mV[0m and you
  evaluate a call of [47m[include-book][0m, [47m[certify-book][0m, or
  [47m[encapsulate][0m, then the [47macl2-defaults-table[0m has value [47mV[0m when that
  call returns.  Thus, if you want to set the [47macl2-defaults-table[0m in
  a way that persists, you need to do so using [command]s that are
  not inside [books].  It may be useful to set your favorite defaults
  in your [47m[ACL2-customization][0m file; see [ACL2-customization].

  ACL2 disallows (for logical reasons) setting of the
  [47macl2-defaults-table[0m in the context of [47mLOCAL[0m.  Often it is easy
  simply to avoid wrapping an [47macl2-defaults-table[0m event, or a macro
  that generates such an event, inside a [47mLOCAL[0m; after all, a local
  context is not useful when setting the [47macl2-defaults-table[0m, since
  that table is restored as discussed above upon completion of
  [47m[include-book][0m, [47m[certify-book][0m, and [47m[encapsulate][0m 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.

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

  ACL2 responds with the following error message.

    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.

  A solution is to use [47m[encapsulate][0m instead of (or in addition to)
  [47m[progn][0m, because [47m[encapsulate][0m establishes a new context that is
  not considered within a surrounding [47mLOCAL[0m.  For example, the
  following replacement for the form above is legal in a book.

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

  To see that this works, try creating a file [47m\"foo.lisp\"[0m whose first
  form is [47m(in-package \"ACL2\")[0m and whose only other form is the one
  displayed just above.  Then the command [47m(certify-book \"foo\" 0 t
  :ttags :all)[0m will successfully certify that book.")
 (ACL2-DOC
  (DOCUMENTATION)
  "A custom Emacs browser for reading ACL2 [documentation]

  As discussed elsewhere (see [documentation]), the web-based
  {ACL2+Books Manual |
  http://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}
  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 [47m:[0m[47m[doc][0m command, though documentation for
  [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 [47mmeta[0m key (or,
  probably the [47mcontrol[0m key), for example, [47mmeta-0 control-t g[0m or
  [47mcontrol-3 control-t /[0m.

  Note: If you are not happy with the way text is displayed with
  ACL2-Doc, see [xdoc::terminal].

  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 [47m<Return>[0m 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.

      [books]

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

  In order to use ACL2-Doc, load into Emacs the distributed file
  [47macl2-doc.el[0m from an appropriate directory; see [emacs].  This will
  happen automatically if you load [47memacs-acl2.el[0m from an appropriate
  directory; again, see [emacs].  Then to start the browser at the
  top-level topic, either execute the Emacs command

    meta-x acl2-doc

  or else type:

    Control-t g

  Thus, you can put the following form in your [47m.emacs[0m file if you want
  [47macl2-doc[0m to run automatically when Emacs starts up.

    (acl2-doc)

  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 [47m.emacs[0m file, [47m*acl2-doc-manual-name*[0m, 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
  [47mMeta-.[0m):

    Control-t .

  In each of the cases above, you will now be in a buffer called
  \"[47macl2-doc[0m\", 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 [47mControl-h
  m[0m while in that buffer.

    <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

  You can see the documentation for each of these in the usual way,
  using [47mControl-h k {key}[0m or [47mControl-h f {command}[0m.  Here is what you
  will find in each case if you do that.

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

  Selecting a Manual, Tags Files, and Custom Manuals

  ACL2-Doc can display the ACL2 User's Manual, which includes
  documentation for the ACL2 system but not for the
  [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 `[47mI[0m' command, as described briefly above.

  For the `[47m/[0m' and `[47mW[0m' 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 [47m\"TAGS\"[0m
  is used when these commands are given a prefix argument (to search
  only the ACL2 sources), and is generated when building the
  [47msaved_acl2[0m executable with `[47mmake[0m'.  Without a prefix argument the
  file [47m\"TAGS-acl2-doc\"[0m is used for searching both the ACL2 sources
  and the books, and is created automatically if you build the manual
  by certifying community book [47mbooks/doc/top.lisp[0m.  You can also
  build [47m\"TAGS-acl2-doc\"[0m by running the command
  [47mbin/make-tags-acl2-doc.sh[0m, or by building the ACL2 executable after
  setting variable [47mTAGS_ACL2_DOC[0m to a non-empty value other than [47mSKIP[0m
  either on the command line with `[47mmake[0m' or, for example, by putting
  one of the following forms in your [47m~/.cshrc[0m or [47m~/.bashrc[0m,
  respectively.

    setenv TAGS_ACL2_DOC t

    export TAGS_ACL2_DOC=t

  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 [47my[0m
  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.

  As mentioned above, you can give the `[47mI[0m' 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 `[47mcombined[0m' and `[47macl2-only[0m', 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 [47m~/.emacs[0m file
  before starting Emacs.  Here, [47mfilename[0m is the pathname of a file
  typically created by calling [xdoc::save-rendered].

    (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
     )

  For example, acl2-doc is initially built with the following two
  forms, which is why you can respond to the query mentioned above
  with `[47mcombined[0m' or `[47macl2-only[0m'.

    (extend-acl2-doc-manual-alist
     'combined
     (concat *acl2-sources-dir*
             \"books/system/doc/rendered-doc-combined.lsp\")
     'TOP
     \"ACL2+Books Manual\"
     \"http://www.cs.utexas.edu/users/moore/acl2/manuals/current/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\"))

  Note that the first of these forms specifies the location of the
  [47m\"TAGS-acl2-doc\"[0m and [47m\"TAGS\"[0m files mentioned above, but the second
  only specifies [47m\"TAGS\"[0m since the second form is for an ACL2-only
  manual (no books).

  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 [47m.emacs[0m
  file, where [47m'name[0m is the name a manual for which you have included
  a form [47m(extend-acl2-doc-manual-alist 'name ...)[0m in your [47m.emacs[0m
  file.

    (setq *acl2-doc-manual-name* 'name)

  Color

  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
  [47m.emacs[0m file) the Emacs variable [47m*acl2-doc-link-color*[0m to the
  desired link color, or to [47mnil[0m if you don't want the links to be in
  color.  For example:

    (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

  Notes

    * You might find that when you attempt to follow some-broken-link, you
      find yourself at the [broken-link] topic.  If you are using the
      ACL2 User's Manual rather than the ACL2+Books Manual, the
      reason might be that [47msome-broken-link[0m is documented in a book,
      not in the ACL2 system.  In that case, the [47mbroken-link[0m page
      will show you where to find that book; but if you want to read
      the documentation for [47msome-broken-link[0m in the ACL2-Doc browser,
      you can do so by switching to the ACL2+Books Manual.  See the [47mI[0m
      command, documented above.

    * Files with names ending in [47m.acl2-doc[0m will come up in ACL2-Doc mode.
      Thus, you may wish to save a file with that extension, for
      example [47mbookmarks.acl2-doc[0m, that contains your favorite
      bookmarks.  You may wish to use the history command ([47mH[0m) to
      obtain a list of names of visited topics, in order to create an
      initial such file.

    * 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:

        * Completion is carried out with the usual emacs ``[47mcompleting-read[0m'';
          thus, for example, the character `[47m?[0m' is a help key, so if
          you want that character as part of your topic name, prefix
          it with [47mcontrol-q[0m.  For example, after the `[47mg[0m' command you
          can go to the topic [47m[mv?][0m by typing the character sequence
          [47m<m,v,control-q ?>[0m.

        * To find completions that have package prefixes, type a colon (:) in
          the front, and completion will show matching topics.  For
          example, [47m\"g\"[0m followed by [47m\":rew\"[0m and then two tabs will
          show, at least in recent versions of Emacs, a list of
          topics that includes [47m\"ACL2-PC::REWRITE\"[0m.

    * Square brackets typically indicate documentation topic names, for
      example: [47m[acl2-doc][0m.  (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 \"[47m[acl2-doc][0m\": the default name of
      \"[47macl2-doc[0m\" is offered if the cursor is on either square
      bracket.  But links have some idiosyncrasies.

       1. Topic names, including links `[47m[..][0m' 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 [gl] in the ACL2+Books Manual.

              We call these structures [gl::symbolic-objects].

          The \"[47mgl[0m\" package prefix allows commands to pick up
          \"[47mgl::symbolic-objects[0m\" as the name to use as a default, so
          that for example, hitting [47m<Return>[0m 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.

              We call these structures symbolic-objects.

       2. Inside ACL2-Doc, topic names that originally contained spaces now
          have underscores in place of the spaces.  So for example,
          the topic [ACL2-tutorial] in the ACL2+Books Manual contains
          a link to the topic originally named as follows.
          [47m|Pages Written Especially for the Tours|[0m
          This link shows up in the ACL2-Doc browser as:
          [47m[Pages_Written_Especially_for_the_Tours][0m.

      Of course, the web-based browser avoids these idiosyncrasies (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.

    * 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:

       1. All topics whose names reside in the \"[47mACL2[0m\" package;

       2. All topics whose names reside in the \"[47mACL2-PC[0m\" package; and, for the
          ACL2+Books Manual,

       3. All other topics, sorted by [47m[symbol-name][0m and then by
          [47m[symbol-package-name][0m.

    * 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 {git version | https://github.com/acl2/acl2/}, 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 tarball for the latest
      ``bleeding edge'' copy |
      http://www.cs.utexas.edu/users/moore/acl2/manuals/current/rendered-doc-combined.lsp.gz}
      and extracting into directory [47msystem/doc/[0m of your community
      books directory.  Indeed, the system will do all this for you
      if you answer [47my[0m to that query.  Alternatively, you can insist
      on a download of a ``bleeding edge'' version by using the `[47mD[0m'
      command.  However, if you prefer to browse the ACL2 User's
      Manual (without the books), you can put the following form into
      your [47m~/.emacs[0m file, above the form that loads the code for
      ACL2-Doc (see above).

          (defvar *acl2-doc-manual-name* 'acl2-only)

      If you prefer to build [47mrendered-doc-combined.lsp[0m yourself, you can
      do so as follows.

       1. Build ACL2:

              make

       2. Build the file [47mbooks/system/doc/rendered-doc-combined.lsp[0m while
          standing in the [47mbooks/[0m directory, as follows.  If \"[47macl2[0m\"
          invokes the ACL2 executable that you just built, then you
          may omit \"[47mACL2=acl2[0m\" below; otherwise replace \"[47macl2[0m\" by a
          suitable executable.  On a multi-core machine you may wish
          to use [47m-j[0m, e.g., [47mmake -j 4 ...[0m.

              cd books
              make doc/top.cert USE_QUICKLISP=1 ACL2=acl2")
 (ACL2-DOC-SUMMARY
  (DOCUMENTATION)
  "Summary of [ACL2-doc] commands

  See [ACL2-doc] for information about the custom Emacs browser for
  viewing ACL2 [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, [47mControl-h m[0m.

    <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.")
 (ACL2-HELP
  (ABOUT-ACL2)
  "The acl2-help mailing list

  You can email questions about ACL2 usage to the acl2-help mailing
  list: [47macl2-help@utlists.utexas.edu[0m.  If you have more general
  questions about ACL2, for example, about projects completed using
  ACL2, you may prefer the acl2 mailing list,
  [47macl2@utlists.utexas.edu[0m, which tends to have wider distribution.

  The following mailing list pages include links to their archives.

    * acl2-help list:
      [47m{https://utlists.utexas.edu/sympa/info/acl2-help |
      https://utlists.utexas.edu/sympa/info/acl2-help}[0m

    * acl2 list:
      [47m{https://utlists.utexas.edu/sympa/info/acl2 |
      https://utlists.utexas.edu/sympa/info/acl2}[0m")
 (ACL2-NUMBER-LISTP
  (NUMBERS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of numbers

  The predicate [47macl2-number-listp[0m tests whether its argument is a true
  list of numbers.

  [31;1mFunction: [0m<acl2-number-listp>

    (defun acl2-number-listp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (eq l nil))
            (t (and (acl2-numberp (car l))
                    (acl2-number-listp (cdr l))))))")
 (ACL2-NUMBERP
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for numbers

  [47m(acl2-numberp x)[0m is true if and only if [47mx[0m is a number, i.e., a
  rational or complex rational number.")
 (ACL2-SEDAN
  (ACL2-TUTORIAL)
  "ACL2 Sedan interface

  Many successful ACL2 users run in a shell under Emacs; 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''.

  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
  [47mbooks/acl2s/distribution/acl2s-hooks/[0m.  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.")
 (ACL2-TUTORIAL
  (START-HERE)
  "Tutorial introduction to ACL2

  To learn about ACL2, read at least the following two links.

    * Industrial Applications of ACL2 (see [INTERESTING-APPLICATIONS]) (10
      minutes) to help you understand what sophisticated users can
      do;

    * A Flying Tour (see [A_Flying_Tour_of_ACL2]) (10 minutes) to get an
      overview of the system and what skills the user must have.

  Alternatively, or in addition, there are [talks] that you can peruse,
  many of them introductory in nature.

  If you want to learn [3mhow to use[0m ACL2, we recommend that you read a
  selection of the materials referenced below, depending on your
  learning style, and do suggested exercises.

    * A Walking Tour (see [A_Walking_Tour_of_ACL2]) (1 hour) provides an
      overview of the theorem prover.

    * The {Try ACL2 | http://tryacl2.org} web site provides interactive
      lessons to get you started using ACL2.

    * 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 [3mthink[0m!  It
      cites the necessary background pages on programming in ACL2 and
      on the logic and then instructs you in [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.

    * The book {Computer-Aided Reasoning: An Approach |
      http://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html}
      is worth a careful read, as you work exercises and learn
      [the-method].

    * Annotated ACL2 Scripts and Demos (see [ANNOTATED-ACL2-SCRIPTS])
      contains relatively elementary proof scripts that have been
      annotated to help train the newcomer.

    * Many files (``books'') in the ACL2 community books (see
      [community-books]) are extensively annotated.

    * An Alternative Introduction (see [ALTERNATIVE-INTRODUCTION])
      document, while largely subsumed by the Introduction to the
      Theorem Prover (see [INTRODUCTION-TO-THE-THEOREM-PROVER])
      mentioned above, still might be useful because it covers much
      of the tutorial material in a different way.

  At this point you are probably ready to use ACL2 on your own [3msmall[0m
  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!

  Note that ACL2 has a very supportive user network.  See the link to
  ``Mailing Lists'' on the {ACL2 home page |
  http://www.cs.utexas.edu/users/moore/acl2}.

  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.


Subtopics

  [ACL2-as-standalone-program]
      Calling ACL2 from another program

  [ACL2-sedan]
      ACL2 Sedan interface

  [Advanced-features]
      Some advanced features of ACL2

  [Alternative-introduction]
      Introduction to ACL2

  [Annotated-ACL2-scripts]
      Examples of ACL2 scripts

  [Emacs]
      Emacs support for ACL2

  [Interesting-applications]
      Some industrial examples of ACL2 use

  [Introduction-to-the-theorem-prover]
      How the theorem prover works --- level 0

  [Nqthm-to-ACL2]
      ACL2 analogues of Nqthm functions and commands

  [Pages_Written_Especially_for_the_Tours]
      Pages Written Especially for the Tours

  [Startup]
      How to start using ACL2; the ACL2 [command] loop

  [Talks]
      Some talks about ACL2

  [The-method]
      How to find proofs

  [Tidbits]
      Some basic hints for using ACL2

  [Tips]
      Some hints for using the ACL2 prover")
 (ACL2-UNWIND-PROTECT (POINTERS)
                      "See [system-utilities].")
 (ACL2-USER
  (PACKAGES)
  "A package the ACL2 user may prefer

  This package imports the standard Common Lisp symbols that ACL2
  supports and also a few symbols from package [47m\"ACL2\"[0m 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.

  This package imports the symbols listed in
  [47m*common-lisp-symbols-from-main-lisp-package*[0m, which contains
  hundreds of CLTL function and macro names including those supported
  by ACL2 such as [47m[cons][0m, [47m[car][0m, and [47m[cdr][0m.  It also imports the
  symbols in [47m*acl2-exports*[0m, which contains a few symbols that are
  frequently used while interacting with the ACL2 system, such as
  [47m[implies][0m, [47m[defthm][0m, and [47m[rewrite][0m.  It imports nothing else.

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

  If, while using [47m\"ACL2-USER\"[0m as the current package, you find that
  there are symbols from [47m\"ACL2\"[0m 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
  [47m[union-theories][0m and [47m[universal-theory][0m be imported?  Except for
  stabilizing on the ``frequently used'' names from [47m\"ACL2\"[0m, we intend
  never to define a symbol whose [47m[symbol-package-name][0m is
  [47m\"ACL2-USER\"[0m.")
 (ACL2P (POINTERS) "See [parallelism].")
 (ACL2P-KEY-CHECKPOINTS
  (PARALLEL-PROOF)
  "Key checkpoints in ACL2(p)

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

  For printing output, the parallel version of the waterfall follows
  the precedent of [47m[gag-mode][0m.  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
  [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.

  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 [hints]).  As an example, take the following form, which
  attempts to prove a non-theorem:

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

  With waterfall parallelism enabled, [47mSubgoal *1/2''[0m will be printed as
  a key checkpoint.  This is different from using [47m[gag-mode][0m while
  running the serial version of the waterfall, which skips printing
  the subgoal as a checkpoint.

  For those familiar with the ACL2 waterfall, we note that 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.")
 (ACL2R (POINTERS) "See [real].")
 (ACL2S (POINTERS) "See [ACL2-sedan].")
 (ACL2_AS_AN_INTERACTIVE_THEOREM_PROVER
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 as an Interactive Theorem Prover

  The ACL2 theorem prover finds proofs in the ACL2 logic.  It can be
  automatic.  But most often the user must help it.

  {IMAGE}

  The user usually guides ACL2 by suggesting that it first prove key
  [31;1mlemmas[0m.  Lemmas are just theorems used in the proofs of other
  theorems.")
 (ACL2_AS_AN_INTERACTIVE_THEOREM_PROVER_{CONT}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 as an Interactive Theorem Prover (cont)

  {IMAGE} (see [ACL2_System_Architecture])

  When ACL2 proves a lemma, it is converted into one or more [31;1mrules[0m and
  stored in a [31;1mdatabase[0m.  The theorem prover is [31;1mrule-driven[0m.  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.

  But it would be wrong to think that ACL2 [3mknows[0m the mathematical
  content of a formula just because it has proved it.  What ACL2
  knows --- all ACL2 knows --- is what is encoded in its rules.
  There are many types of rules (see [rule-classes] {ICON} (see
  [A_Tiny_Warning_Sign])).

  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!

  The way a formula is stored as a rule is entirely up to the user.
  That is, [31;1myou[0m determine how ACL2 should use each formula that it
  proves.

  The most common kind of rule is the [31;1mrewrite rule[0m.  It is so common
  that if you don't tell ACL2 how to store a formula, it stores it as
  a rewrite rule.

  {IMAGE} (see [ACL2_System_Architecture])")
 (ACL2_CHARACTERS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 Characters

  ACL2 accepts 256 distinct characters, which are the characters
  obtained by applying the function [47m[code-char][0m {ICON} (see
  [A_Tiny_Warning_Sign]) to each integer from 0 to 255.  Among these,
  Common Lisp designates certain ones as [47m*standard-characters*[0m,
  namely those of the form [47m(code-char n)[0m where n is from 33 to 126,
  together with [47m#\\Newline[0m and [47m#\\Space[0m.  The actual standard
  characters may be viewed by evaluating the constant expression
  [47m*standard-chars*[0m.

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

  The function [47m[characterp][0m {ICON} (see [A_Tiny_Warning_Sign])
  recognizes characters.  For more details, See [characters] {ICON}
  (see [A_Tiny_Warning_Sign]).")
 (ACL2_CONSES_OR_ORDERED_PAIRS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 Conses or Ordered Pairs

  The function [47m[cons][0m {ICON} (see [A_Tiny_Warning_Sign]) creates an
  ordered pair.  [47m[Car][0m {ICON} (see [A_Tiny_Warning_Sign]) and [47m[cdr][0m
  {ICON} (see [A_Tiny_Warning_Sign]) return the first and second
  components, respectively, of an ordered pair.  The function [47m[consp][0m
  {ICON} (see [A_Tiny_Warning_Sign]) recognizes ordered pairs.

  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 [programming] {ICON} (see [A_Tiny_Warning_Sign]) where we
  list all the ACL2 primitive functions.

  Here are some examples of list constants to suggest their syntax.

    '(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

  It is useful to distinguish ``proper'' conses from ``improper'' ones,
  the former being those cons trees whose right-most branch
  terminates with [47mnil[0m.  A ``true list'' (see [true-listp] {ICON} (see
  [A_Tiny_Warning_Sign])) is either [47mnil[0m or a proper cons.  [47m(A b c .
  7)[0m is an improper cons and hence not a true list.")
 (ACL2_IS_AN_UNTYPED_LANGUAGE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 is an Untyped Language

  The example

    ACL2 !>[31;1m(app '(a b c) 27)[0m
    (A B C . 27)

  illustrates the fact that ACL2's logic is untyped (click here (see
  [About_Types]) for a brief discussion of the typed versus untyped
  nature of the logic).

  The definition of [47mapp[0m makes no restriction of the arguments to lists.
  The definition says that if the first argument satisfies [47m[endp][0m
  {ICON} (see [A_Tiny_Warning_Sign]) then return the second argument.
  In this example, when [47mapp[0m has recursed three times down the [47mcdr[0m of
  its first argument, [47m'(a b c)[0m, it reaches the final [47mnil[0m, which
  satisfies [47mendp[0m, and so 27 is returned.  It is naturally consed into
  the emerging list as the function returns from successive recursive
  calls (since [47mcons[0m does not require its arguments to be lists,
  either).  The result is an ``improper'' list, [47m(a b c . 27)[0m.

  You can think of [47m(app x y)[0m as building a binary tree by replacing the
  right-most tip of the tree [47mx[0m with the tree [47my[0m.")
 (ACL2_STRINGS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 Strings

  Strings of ACL2 characters (see [ACL2_Characters]) 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 (\\).

  The function [47m[stringp][0m {ICON} (see [A_Tiny_Warning_Sign]) recognizes
  strings and [47m[char][0m {ICON} (see [A_Tiny_Warning_Sign]) will fetch
  the nth character of a string.  There are many other primitives for
  handling strings, such as [47m[string<][0m {ICON} (see
  [A_Tiny_Warning_Sign]) for comparing two strings lexicographically.
  We suggest you See [programming] {ICON} (see [A_Tiny_Warning_Sign])
  where we list all of the primitive ACL2 functions.  Alternatively,
  see any Common Lisp language documentation.")
 (ACL2_SYMBOLS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 Symbols

  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 [47mPLUS[0m and
  [47mSMITH::ABC[0m.  All function and variable names in ACL2 are symbols.
  When symbols are used as constants they must be quoted, as in
  [47m'PLUS[0m.

  The symbol [47mT[0m is commonly used as the Boolean ``true.'' The symbol [47mNIL[0m
  is commonly used both as the Boolean ``false'' and as the ``empty
  list.'' Despite sometimes being called the ``empty list'' [47mNIL[0m is a
  [31;1msymbol[0m not an ``empty cons.'' Unlike other symbols, [47mT[0m and [47mNIL[0m may
  be used as constants without quoting them.

  Usually, symbols are written as sequences of alphanumeric characters
  other than those denoting numbers.  Thus, [47mA12[0m, [47m+1A[0m and [47m1+[0m are
  symbols but [47m+12[0m is a number.  Roughly speaking, when symbols are
  read lower case characters are converted to upper case, so we
  frequently do not distinguish [47mABC[0m from [47mAbc[0m or [47mabc[0m.  Click here (see
  [Conversion]) 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, [47m|Abc|[0m is a symbol whose
  first character is capitalized and whose remaining characters are
  in lower case.  [47m|An odd duck|[0m is a symbol containing two #\\Space
  characters.  See any Common Lisp documentation for the syntactic
  rules for symbols.

  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 [symbol-package-name] {ICON} (see
  [A_Tiny_Warning_Sign]) and see [symbol-name] {ICON} (see
  [A_Tiny_Warning_Sign]).)  The symbol SMITH::ABC is said to be in
  package \"SMITH\" and to have the symbol name \"ABC\".  The symbol [47mABC[0m
  in package \"SMITH\" is generally not equal to the symbol [47mABC[0m 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 [defpkg] {ICON} (see
  [A_Tiny_Warning_Sign]).)  If the [47m[current-package][0m {ICON} (see
  [A_Tiny_Warning_Sign]) is \"SMITH\" then [47mSMITH::ABC[0m may be more
  briefly written as just [47mABC[0m.  [47m[Intern][0m {ICON} (see
  [A_Tiny_Warning_Sign]) ``creates'' a symbol of a given name in a
  given package.")
 (ACL2_SYSTEM_ARCHITECTURE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "ACL2 System Architecture

  {IMAGE} (see [Rewrite_Rules_are_Generated_from_DEFTHM_Events])

  {IMAGE}

  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.

  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 [books] {ICON}
  (see [A_Tiny_Warning_Sign]).

  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 [31;1mLemma Libraries and
  Utilities[0m {ICON} (see [A_Tiny_Warning_Sign]) link of the ACL2 home
  page.

  {IMAGE} (see [Rewrite_Rules_are_Generated_from_DEFTHM_Events])")
 (ACONS
  (ALISTS ACL2-BUILT-INS)
  "Constructor for association lists

  [47m(Acons key datum alist)[0m equals the result of consing the pair [47m(cons
  key datum)[0m to the front of the association list [47malist[0m.

  [47m(Acons key datum alist)[0m has a [guard] of [47m(alistp alist)[0m.  [47mAcons[0m is a
  Common Lisp function.  See any Common Lisp documentation for more
  information.

  [31;1mFunction: [0m<acons>

    (defun acons (key datum alist)
      (declare (xargs :guard (alistp alist)))
      (cons (cons key datum) alist))")
 (ACTIVE-OR-NON-RUNEP
  (THEORIES)
  "Require a [rune] to exist, and check that it is [enable]d

  This variant of [47mactive-runep[0m causes an error if its argument is not a
  [rune].  See [active-runep].")
 (ACTIVE-RUNEP
  (THEORIES)
  "Check that a [rune] exists and is [enable]d

    Example:
    (active-runep '(:rewrite left-to-right))

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

  where [47mrune[0m has the shape of a [rune].  This macro expands to an
  expression using the variables [47mens[0m and [47mstate[0m, and returns non-[47mnil[0m
  when the given rune exists and is [enable]d (according to the given
  ``enabled structure,'' [47mens[0m, and the current logical [world] of the
  given [47m[state][0m).  See [theory-invariant] for how this macro can be
  of use.

  When the optional argument is [47mnil[0m or is omitted, then although the
  argument is required to have the shape of a [rune], it need not be
  a rune.  For example, if there is no rewrite rule named
  [47mleft-to-right[0m, then [47m(active-runep '(:rewrite left-to-right))[0m will
  simply return [47mnil[0m.  If instead you'd like this call to cause an
  error, use a non-nil optional argument or, equivalently, use
  [47m[active-or-non-runep][0m.")
 (ADD-BINOP
  (MACROS)
  "Associate a function name with a macro name

  The form [47m(add-binop macro macro-fn)[0m is an abbreviation for the form
  [47m(add-macro-fn macro macro-fn t)[0m.  See [add-macro-fn].")
 (ADD-CUSTOM-KEYWORD-HINT
  (EVENTS)
  "Add a new custom keyword hint

    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)

  where [47m:key[0m is a [47m[keywordp][0m not among the primitive keyword hints
  listed in [47m*hint-keywords*[0m, the [47m:checker[0m argument is optional, and
  [47mterm1[0m and (if supplied) [47mterm2[0m are terms with certain free-variable
  and signature restrictions described below.  Henceforth, [47m:key[0m is
  treated as a custom keyword hint, e.g., the user can employ [47m:key[0m in
  hints to [47m[defthm][0m, such as:

    (defthm name ...
      :hints ((\"Subgoal *1/1'\" ... :key val ...))).

  Custom keyword hints are complicated.  To use them you must
  understand [47m[state][0m, multiple values (e.g., [47m[mv][0m and [47m[mv-let][0m),
  ACL2's notion of error triples (see [programming-with-state]), how
  to generate ``soft'' errors with [47m[er][0m, how to use [47m[fmt][0m-strings to
  control output, how to use computed hints (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.

  [47mTerm1[0m is called the ``generator'' term and [47mterm2[0m is called the
  ``checker'' term of the custom keyword hint [47m:key[0m.  Together they
  specify the semantics of the new custom keyword hint [47m:key[0m.  Roughly
  speaking, when a custom keyword hint is supplied by the user, as in

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

  the checker term is evaluated on [47mval[0m to check that [47mval[0m is of the
  expected shape.  Provided [47mval[0m 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
  [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.

  The generator, [47mterm1[0m, must have no free variables other than:

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

  Moreover, either [47mterm1[0m must evaluate to a single non-[stobj] value,
  or else it must be single-threaded in [47mstate[0m and have the standard
  [error-triple] output signature, [47m(mv * * state)[0m.

  The restrictions on the checker, [47mterm2[0m, are that it be
  single-threaded in [47mstate[0m, have the standard [error-triple] output
  signature, [47m(mv * * state)[0m, and have no free variables other than:

    (val world ctx state).

  For examples, see the community books directory [47mbooks/hints/[0m, in
  particular [47mbasic-tests.lisp[0m.

  To delete a previously added custom keyword hint, see
  [remove-custom-keyword-hint].

  The community book [47mhints/merge-hint.lisp[0m can be useful in writing
  custom keyword hints.  See the examples near the of the file.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.")
 (ADD-DEFAULT-HINTS
  (DEFAULT-HINTS)
  "Add to the default hints

    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)

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

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

  where [47mlst[0m is a list.  Generally speaking, the elements of [47mlst[0m should
  be suitable for use as [47m[computed-hints][0m.

  This event is completely analogous to [47m[set-default-hints][0m, the
  difference being that [47madd-default-hints[0m appends the indicated hints
  to the front of the list of default hints, so that they are tried
  first --- or, if [47mflg[0m is supplied and evaluates to other than [47mnil[0m,
  at the end of the list, so that they are tried last --- rather than
  [31;1mreplacing[0m 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 [set-default-hints], see
  [remove-default-hints], and see [default-hints].

  Finally, note that the effects of [47mset-default-hints[0m,
  [47m[add-default-hints][0m, and [47m[remove-default-hints][0m are [47m[local][0m 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 [47m[set-default-hints!][0m, [47m[add-default-hints!][0m, or
  [47m[remove-default-hints!][0m.

  For a related feature, which however is only for advanced system
  builders, see [override-hints].")
 (ADD-DEFAULT-HINTS!
  (DEFAULT-HINTS)
  "Add to the default hints non-[47m[local][0mly

  Please see [add-default-hints], which is the same as
  [47madd-default-hints![0m except that the latter is not [47m[local][0m to the
  [47m[encapsulate][0m or the book in which it occurs.  Probably
  [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 [47m[encapsulate][0m or book.")
 (ADD-DIVE-INTO-MACRO
  (DIVE-INTO-MACROS-TABLE)
  "Associate [proof-builder] diving function with macro name

    Examples:
    (add-dive-into-macro cat expand-address-cat)

  This feature is used so that the interactive [proof-builder]'s [47mDV[0m
  command and numeric diving commands (e.g., [47m3[0m) will dive properly
  into subterms.  Please see [dive-into-macros-table].")
 (ADD-GLOBAL-STOBJ
  (EVENTS STOBJ)
  "Add a global [stobj] with a given name

  See [stobj] for background on stobjs, and see [defstobj] and
  [defabsstobj] for further background.

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

    General Form:
    (add-global-stobj x state)

  where [47mx[0m evaluates to the name of a stobj that does not already have a
  global value, either because it was introduced by [47m[defstobj][0m or
  [47m[defabsstobj][0m with keyword value [47m:non-executable t[0m or because
  [47m[remove-global-stobj][0m was previously applied to that name.

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

  By default, [47mdefstobj[0m and [47mdefabsstobj[0m create a ``live'', mutable
  object for the given name that can be referenced at the top level,
  which we call a ``global'' stobj.  This is illustrated by the
  following log.

    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 !>

  However, the following log shows that we can introduce a stobj
  without creating a global stobj, by using the keyword value
  [47m:non-executable t[0m.

    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 !>

  The function [47madd-global-stobj[0m creates a global stobj for a given
  stobj name when one does not already exist.  Let's continue the log
  started immediately above.

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

  The function [47mremove-global-stobj[0m removes the indicated global stobj.
  We continue the log above.

    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 !>

  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.

    ACL2 !>(add-global-stobj 'st2 state)
     ST2
    ACL2 !>(fld2 st2)
    NIL
    ACL2 !>")
 (ADD-INCLUDE-BOOK-DIR
  (BOOKS-REFERENCE)
  "Link keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m

    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\"))

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs.  See [47m[add-include-book-dir!][0m for a corresponding
  non-[47m[local][0m event.

    General Form:
    (add-include-book-dir kwd dir)

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

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

  See [47m[project-dir-alist][0m 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 [47mproject-dir-alist[0m may also be
  bound by [47madd-include-book-dir[0m, but only if both bindings are to the
  same directory.

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

  This macro generates a [47m[table][0m event that updates the
  [47m[ACL2-defaults-table][0m and thus is automatically [local] to the book
  or [47m[encapsulate][0m event in which it occurs (and, it is thus illegal
  to call [47madd-include-book-dir[0m in an explicitly [47m[local][0m context).
  See [47m[add-include-book-dir!][0m for a corresponding non-[47m[local][0m event.

  As with [47m[add-include-book-dir!][0m, direct table updates are disallowed;
  you must use [47madd-include-book-dir[0m to add to the [47macl2-defaults-table[0m
  and [47m[delete-include-book-dir][0m to remove from it.")
 (ADD-INCLUDE-BOOK-DIR!
  (BOOKS-REFERENCE)
  "Non-[47m[local][0mly link keyword for [47m:dir[0m argument of [47m[ld][0m and
  [47m[include-book][0m

  This topic assumes familiarity with [add-include-book-dir], which has
  completely analogous syntax and semantics, except that
  [47madd-include-book-dir![0m is not [47m[local][0m to the [47m[encapsulate][0m or the
  book in which it occurs.  Probably [47m[add-include-book-dir][0m is to be
  preferred unless you have a good reason for wanting to export the
  effect of this event outside the enclosing [47m[encapsulate][0m or book.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

  This macro is essentially a [47m[table][0m event that updates the table
  [47minclude-book-dir!-table[0m, which associates keywords with absolute
  pathnames.  However, as with [47m[add-include-book-dir][0m, direct table
  updates are disallowed; you must use [47madd-include-book-dir![0m to add
  to the table and [47m[delete-include-book-dir!][0m to remove from the
  table.

  See [47m[project-dir-alist][0m 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 [47mproject-dir-alist[0m may also be
  bound by [47madd-include-book-dir![0m, but only if both bindings are to
  the same directory.

  It is illegal to call [47madd-include-book-dir![0m in a [47m[local][0m context.
  (If you are tempted to do that, consider using
  [47m[add-include-book-dir][0m instead.)  To understand this restriction,
  imagine a book that contains the following sequence of [events].

    (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))

  During the first (proof) pass of [47m[certify-book][0m, the book
  [47mpath/to/GOOD/dir/foo.lisp[0m will be included.  But on the second
  pass, the book [47mpath/to/BAD/dir/foo.lisp[0m will be included.  Now
  imagine that the ``good'' version contains the event [47m(defun f (x)
  x)[0m but the ``bad'' version instead contains the event [47m(defun f (x)
  (not x))[0m.  Then we can easily prove [47mnil[0m from the theorem [47mf-def[0m!
  Although it is likely that [book-hash] values could catch this
  error at [47m[include-book][0m time, we prefer not to rely on these for
  soundness.")
 (ADD-INVISIBLE-FNS
  (LOOP-STOPPER)
  "Make some unary functions invisible to the [loop-stopper] algorithm

    Examples:
    (add-invisible-fns binary-+ unary-- foo)
    (add-invisible-fns + unary-- foo)

  Each of the [events] above makes unary functions [47m[unary--][0m and [47mfoo[0m
  ``invisible'' for the purposes of applying permutative [47m:[0m[47m[rewrite][0m
  rules to [47m[binary-+][0m trees.  Thus, [47marg[0m and [47m(unary-- arg)[0m will be
  given the same weight and will be permuted so as to be adjacent.

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

  where [47mtop-fn[0m is a function symbol and the [47munary-fni[0m are unary
  function symbols, or more generally, these are all macro aliases
  for such function symbols (see [macro-aliases-table]).

  For more information see [invisible-fns-table].  Also see
  [set-invisible-fns-table], which explains how to set the entire
  table in a single event, and see [remove-invisible-fns].")
 (ADD-LD-KEYWORD-ALIAS (POINTERS)
                       "See [ld-keyword-aliases].")
 (ADD-LD-KEYWORD-ALIAS! (POINTERS)
                        "See [ld-keyword-aliases].")
 (ADD-MACRO-ALIAS
  (MACROS)
  "Associate a function name with a macro name

    Example:
    (add-macro-alias append binary-append)

  This example associates the function symbol [47m[binary-append][0m with the
  macro name [47m[append][0m.  As a result, the name [47m[append][0m may be used as
  a runic designator (see [theories]) by the various theory
  functions.  See [macro-aliases-table] for more details.  Also see
  [add-macro-fn] for an extension of this utility that also affects
  printing.

    General Form:
    (add-macro-alias macro-name function-name)

  This is a convenient way to add an entry to [47m[macro-aliases-table][0m.
  See [macro-aliases-table] and also see [remove-macro-alias].")
 (ADD-MACRO-FN
  (MACROS)
  "Associate a function name with a macro name

    Examples:
    (add-macro-fn append binary-append)
    (add-macro-fn append binary-append t)

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

    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)

  This is a convenient way to add an entry to [47m[macro-aliases-table][0m and
  at the same time extend the [47m[untrans-table][0m.  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 [47mfn[0m associated with macro name [47mmac[0m, then a call [47m(fn arg1 (fn
  arg2 (... (fn argk arg))))[0m will be displayed to the user as though
  the ``term'' were [47m(mac arg1 arg2 ... argk arg)[0m.  For a call [47m(f a1
  ... ak)[0m of a function symbol that is not binary, or the optional
  argument is not supplied as [47mt[0m, then the effect is simply to replace
  [47mf[0m by the corresponding macro symbol.  See [add-macro-alias], which
  is invoked on the first two arguments.  Also see
  [remove-macro-alias], see [untrans-table], and see
  [remove-macro-fn].")
 (ADD-MATCH-FREE-OVERRIDE
  (FREE-VARIABLES)
  "Set [47m:match-free[0m value to [47m:once[0m or [47m:all[0m in existing rules

    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).

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

  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: [47madd-match-free-override[0m is not relevant
  for [type-prescription] rules.)  The event [47m(add-match-free-override
  :once t)[0m has that effect.  Or at the other extreme, perhaps you
  want to specify all rules as [47m:all[0m rules except for some specific
  exceptions.  Then you can execute [47m(add-match-free-override :all t)[0m
  followed by, say, [47m(add-match-free-override :once (:rewrite foo)
  (:linear bar))[0m.

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

  where [47mflg[0m is [47m:once[0m or [47m:all[0m and the [47mrunei[0m are [47m[rune][0ms.  If [47m:clear[0m is
  specified then all rules will have the [47m:all[0m/[47m:once[0m behavior from
  when they were first stored.  The second general form causes all
  [rewrite] [linear], and [forward-chaining] rules to have the
  behavior specified by [47mflg[0m ([47m:all[0m or [47m:once[0m).  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 [47madd-match-free-override[0m events).

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

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

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It uses the [47m[ACL2-defaults-table][0m, and hence its effect
  is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs.

  [3mRemarks[0m

  Lists of the [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, and [47m:[0m[47m[forward-chaining][0m [rune]s
  whose behavior was originally [47m:once[0m or [47m:all[0m are returned by the
  following forms, respectively.

    (free-var-runes :once (w state))
    (free-var-runes :all  (w state))

  The form

    (match-free-override (w state))

  evaluates to a pair, whose [47m[car][0m is a number used by ACL2 to
  determine whether a [rune] is sufficiently old to be affected by
  the override, and whose [47m[cdr][0m is the list of [rune]s whose behavior
  is specified as [47m:once[0m by [47madd-match-free-override[0m; except, if no
  runes have been overridden, then the keyword [47m:clear[0m is returned.")
 (ADD-NTH-ALIAS
  (NTH-ALIASES-TABLE)
  "Associate one symbol with another for printing of [47m[nth][0m/[47m[update-nth][0m
  terms

    Example:
    (add-nth-alias st0 st)

  This example associates the symbol [47mst0[0m with the symbol [47mst[0m for
  purposes of printing certain terms of the form [47m(nth n st0)[0m and
  [47m(update-nth n val st0)[0m.

    General Form:
    (add-nth-alias alias-name name)

  This is a convenient way to add an entry to [47m[nth-aliases-table][0m.  See
  [nth-aliases-table] and also see [remove-nth-alias].")
 (ADD-OVERRIDE-HINTS
  (OVERRIDE-HINTS)
  "Add to the [override-hints]

  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 [47madd-override-hints[0m [events] are [local] to the [books]
  or [47mencapsulate[0m [events] in which they reside; see
  [add-override-hints!] to avoid that restriction.  Also see
  [set-override-hints] to set a new list of override-hints to it,
  ignoring the present list rather than adding to it.

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

  where [47mform[0m evaluates to a list of computed hint forms.  The effect of
  this event is to extend the current list of [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 [47m:at-end t[0m is specified, then the evaluation
  result is appended to the end of the current list.")
 (ADD-OVERRIDE-HINTS!
  (OVERRIDE-HINTS)
  "Add non-[local]ly to the [override-hints]

  [47mAdd-override-hints![0m is the same as [47m[add-override-hints][0m, except that
  the former is not [local] to [books] or [47m[encapsulate][0m [events] in
  which it occurs.  See [add-override-hints]; also see
  [set-override-hints].")
 (ADD-SUFFIX (POINTERS)
             "See [system-utilities].")
 (ADD-SUFFIX-TO-FN (POINTERS)
                   "See [system-utilities].")
 (ADD-TO-SET
  (LISTS SYMBOLS ACL2-BUILT-INS)
  "Add a symbol to a list

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

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

  The [guard] for a call of [47madd-to-set[0m depends on the test.  In all
  cases, the second argument must satisfy [47m[true-listp][0m.  If the test
  is [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m
  (see [eqlablep]) or the second argument must satisfy
  [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then either the first
  argument must be a symbol or the second argument must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47madd-to-set[0m and its variants:

      [47m(add-to-set-eq x lst)[0m is equivalent to [47m(add-to-set x lst :test 'eq)[0m;

      [47m(add-to-set-equal x lst)[0m is equivalent to [47m(add-to-set x lst :test
      'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47madd-to-set-equal[0m.")
 (ADD-TO-SET-EQ (POINTERS)
                "See [add-to-set].")
 (ADD-TO-SET-EQL (POINTERS)
                 "See [add-to-set].")
 (ADD-TO-SET-EQUAL (POINTERS)
                   "See [add-to-set].")
 (ADJUST-LD-HISTORY (POINTERS)
                    "See [ld-history].")
 (ADVANCED-FEATURES
  (ACL2-TUTORIAL PROGRAMMING)
  "Some advanced features of ACL2

  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 [documentation]
  topics.

  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 [obdd].  Others
  are already likely to be discovered when needed, such as [47m[getenv$][0m
  and perhaps [47m[double-rewrite][0m.  Some topics are referenced by
  documentation for others in the list, such as [47m[mbt][0m, which is
  referenced by [47m[mbe][0m.  Some utilities such as [47m[pstack][0m and
  [47m[verbose-pstack][0m seem too low-level to be worthy of inclusion
  below.

  For an extensive introduction to using the prover, which may include
  some aspects new to you, see [introduction-to-the-theorem-prover].
  A shorter topic contains highlights for efficient prover usage: see
  [tips].  Also 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.

  We now move on to the list.


Top-level commands and utilities:

    * See [a!] and see [p!] to abort or pop.

    * See [ACL2-customization] for initial commands to run at startup.

    * See [keyword-commands] for how keyword commands are processed.

    * See [ld] for many ways to control the top-level loop.

    * See [compilation] for a discussion of [47mset-compiler-enabled[0m and other
      compiler-related utilities.

    * For useful reader macros `[47m#![0m', `[47m#.[0m', and `[47m#u[0m', see
      [sharp-bang-reader], see [sharp-dot-reader], and see
      [sharp-u-reader].

    * To save and use an ACL2 executable, see [ACL2-as-standalone-program]
      and see [save-exec].

    * For utilities related to timing, see [time$], see
      [with-prover-time-limit], see [with-prover-step-limit], and see
      [set-prover-step-limit].

    * To query and manage the database, see [history] (which discusses many
      useful utilities, such as [47m:[0m[47m[pbt][0m and [47m:[0m[47m[pl][0m), and see
      [dead-events].

    * See [add-include-book-dir], [add-include-book-dir!], and
      [project-dir-alist] for linking keyword for [47m:dir[0m argument of
      [47m[ld][0m and [47m[include-book][0m.

    * See [rebuild] for a fast way to load a file without waiting for
      proofs.

    * For parallel certification, see [books-certification] for use of the
      [47m-j[0m option of `make'; also see [provisional-certification].


Some relatively less common events

    * See [reset-prehistory] to reset the prehistory.

    * See [assert-event] to assert that a given form returns a non-nil
      value.

    * See [defattach] to execute constrained functions using corresponding
      attached functions.

    * See [defun-sk] to define a function whose body has an outermost
      quantifier.

    * See [defchoose] to define a Skolem (witnessing) function.

    * See [set-verify-guards-eagerness] to specify when [guard]
      verification is tried by default.


Output and its control (see [io] for additional information)

    * See [with-output] to suppress or turn on specified output for an
      event.

    * See [evisc-table] for support for abbreviated output.

    * See [nth-aliases-table] for a table used to associate names for
      [47m[nth][0m/[47m[update-nth][0m printing.

    * See [output-to-file] to redirect output to a file.

    * See [print-control] to control ACL2 printing.

    * See [set-evisc-tuple] to control suppression of details when
      printing.

    * See [set-inhibit-output-lst] to control output by type.

    * See [set-iprint] to allow abbreviated output to be read back in.

    * See [set-print-base-radix] (also [set-print-base] and
      [set-print-radix]) to control the radix in which numbers are
      printed.

    * See [set-print-case] to control whether symbols are printed in upper
      case or in lower case.


On proving termination for definitions:

    * See [ordinals] for a discussion of ordinals in ACL2.

    * See [ruler-extenders] for a control on ACL2's termination and
      induction analyses.

    * See [induction-coarse-v-fine-grained] for a discussion of how a
      well-chosen setting for [ruler-extenders] can improve an
      induction scheme, especially for a function containing [47m[let][0m
      and [47m[let*][0m bindings that contain conditional recursive calls.

    * See [set-well-founded-relation] to set the default well-founded
      relation for termination analysis.

    * See [ACL2-sedan] for a related tool that provides extra automation
      for termination proofs.


Proof debugging and output control:

    * See [accumulated-persistence] to get statistics on which runes are
      being tried.

    * See [add-macro-fn] and see [add-macro-alias] to associate a function
      name with a macro name.

    * See [break-rewrite] for how to monitor rewrite rules.

    * See [dmr] for dynamic monitoring of rewriting and other prover
      activity.

    * See [forward-chaining-reports] to see reports about the forward
      chaining process.

    * See [guard-debug] and [measure-debug] to generate markers to indicate
      sources of [guard] and termination proof obligations.

    * See [proof-builder] for support for low-level interaction.

    * See [redo-flat] for redo on failure of a [47m[progn][0m, [47m[encapsulate][0m, or
      [47m[certify-book][0m.

    * See [set-gag-mode] and see [pso] to abbreviate or restore proof
      output.

    * See [set-inhibit-output-lst], see [set-inhibit-warnings], see
      [set-inhibit-er], and see [set-inhibited-summary-types] to
      inhibit various types of output.

    * See [set-raw-proof-format] to make proof output display lists of
      [rune]s and, optionally, clausal form for goals.

    * See [set-raw-warning-format] to make some warnings display in a
      ``raw'' s-expression format.

    * See [skip-proofs] to skip proofs for a given form.

    * See [with-brr-data] for finding the source of a term in prover
      output.


Program debugging:

    * See [break$] to cause an immediate Lisp break.

    * See [break-on-error] to break when encountering a hard or soft error
      caused by ACL2.

    * See [disassemble$] to disassemble a function.

    * See [print-gv] to print a form whose evaluation caused a guard
      violation.

    * See [profile] to turn on profiling for one function.

    * See [trace$] and see [open-trace-file] to [trace] function
      evaluations, possibly sending trace output to a file.

    * See [wet] to evaluate a form and print a subsequent error trace.


Programming and evaluation idioms, support, utilities

  (also see [programming] for more utilities, e.g., [47m[random$][0m).

    * See [arrays] and 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 [with-local-stobj] for a way to create local
      stobjs.

    * See [assert$] to cause a hard error if the given test is false.

    * See [canonical-pathname] to obtain the true absolute filename, with
      soft links resolved.

    * See [case-match] for a utility providing pattern matching and
      destructuring.

    * See [defpun] to define a tail-recursive function symbol.

    * See [ec-call] to execute a call in the ACL2 logic instead of raw
      Lisp.

    * See [er] to print an error message and ``cause an error''.

    * See [flet] and [macrolet] to provide local binding of function and
      macro names.

    * See [gc$] to invoke the garbage collector.

    * See [mbe] to attach code for execution.

    * See [mv-list] to convert a [multiple-value] result to a single-value
      list.

    * See [mv?] to return one or more values.

    * For non-executable code, see [defun-nx] and see [non-exec].

    * See [prog2$] and see [progn$] to execute two or more forms and return
      the value of the last one.

    * See [programming-with-state] for how to program using the von
      Neumannesque ACL2 [state] object.

    * See [top-level] to evaluate a top-level form as a function body.

    * See [with-guard-checking] to suppress or enable guard-checking for a
      form.

    * For ways to fake access to the state see [wormhole], see
      [with-local-state], see [cw], see [cw!], see
      [printing-to-strings], see [observation-cw], and (dangerous!)
      see [with-live-state].


Connecting with the underlying host Lisp, and doing other evil:

    * See [defttag] to introduce a trust tag (ttag).

    * See [defmacro-last] to define a macro that returns its last argument,
      but with side effects.

    * See [progn!] to evaluate forms that are not necessarily [events].

    * See [return-last] to return the last argument, perhaps with side
      effects.

    * See [set-raw-mode] to enter or exit ``raw mode,'' a raw Lisp
      environment.

    * See [sys-call], [sys-call+], and [sys-call*] to make a system call to
      the host operating system.


Macros and related utilities:

    * See [defabbrev] for a convenient form of macro definition for simple
      expansions.

    * See [macro-args] for the formals list of a macro definition (see
      [defmacro]).

    * See [make-event] for a sort of extension of [47m[defmacro][0m that allows
      access to the [state], by evaluating (expanding) a given form
      and then evaluate the result of that expansion.

    * See [trans], see [trans!], and see [trans1] to print the
      macroexpansion of a form.


Additional capabilities:

    * See [hons-and-memoization] for a discussion of the [hons-enabled]
      features providing hash cons, function memoization, and
      applicative hash tables.  In particular, see [memoize] for
      efficient function memoization and see [profile] for profiling.

    * See [real] for ACL2(r), which supports the real numbers.

    * See [parallelism] for ACL2(p), which supports parallel evaluation and
      proof.


Database control and query:

    * See [disabledp] to determine whether a given name or rune is
      disabled.

    * For redefinition support see [redef], see [redef!], see [redef+], see
      [redef-], and see [redefined-names].

    * See [table] for user-managed tables.

    * See [guard-formula-utilities] for how to view a guard proof
      obligation without doing the proof.


Prover control

    * For congruence-based reasoning see [defcong], see [congruence], see
      [equivalence], see [defequiv], and see [defrefinement].

    * For meta rules and [clause] processors see [meta], see
      [defevaluator], see [clause-processor], see
      [define-trusted-clause-processor] (for connecting with external
      tools, such as SAT solvers), and See [extended-metafunctions]
      (for [state] and context-sensitive metafunctions).

    * For theory control, see [theories] for detailed information, but in
      particular see [deftheory], see [theory-functions], see
      [in-arithmetic-theory] (and see [non-linear-arithmetic]), and
      see [theory-invariant].

    * See [hints] for a complete list of prover hints, including some of
      the more obscure ones such as [47m:restrict[0m, [47m:[0m[47m[clause-processor][0m,
      [47m:nonlinearp[0m, [47m:backchain-limit-rw[0m, [47m:reorder[0m, and [47m:backtrack[0m.
      Also see [hints-and-the-waterfall] for an explanation of how
      hints interact with the ACL2 proof process.  For other topics
      related to hints, see [override-hints], see
      [add-custom-keyword-hint], see [default-hints], and see
      [computed-hints] and [using-computed-hints].

    * See [bind-free] to bind [free-variables] of a [rewrite] or [linear]
      rule.

    * See [case-split] for a utility like [47m[force][0m that immediately splits
      the top-level goal on the indicated hypothesis.

    * See [case-split-limitations] for a way to the number of cases
      produced at once

    * See [default-backchain-limit] to specify the backchain limit for a
      rule.

    * See [force] for an identity function used to force a hypothesis.

    * See [otf-flg] for a way to push more than one initial subgoal for
      induction.

    * See [rule-classes] to add various kinds of rules to the database,
      including more unusual sorts such as [47m:[0m[47m[built-in-clause][0m rules
      and [47m:[0m[47m[induction][0m rules.

    * See [set-backchain-limit] to set the backchain-limit used by the
      type-set and rewriting mechanisms.

    * See [set-body] to set an alternate definition body for [47m:expand[0m
      [hints].

    * See [set-rewrite-stack-limit] to set the [rewrite] stack depth used
      by the rewriter.

    * See [syntaxp] to attach a heuristic filter on a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[meta][0m,
      or [47m:[0m[47m[linear][0m rule.


Subtopics

  [Invariant-risk]
      Potential slowdown for [program]-mode updates to [stobj]s or
      [arrays]

  [Program-wrapper]
      Avoiding expensive [guard] checks using [program]-mode functions

  [Set-check-invariant-risk]
      Affect certain [program]-mode updates to [stobj]s or [arrays]

  [Set-duplicate-keys-action]
      Control action for macro calls with duplicate keyword arguments

  [Set-register-invariant-risk]
      Avoid [invariant-risk] checking for specified functions")
 (ALIST-KEYS-SUBSETP
  (ALISTS ACL2-BUILT-INS)
  "Check that all keys of the alist belong to a given set

  The call [47m(alist-keys-subsetp alist keys)[0m returns [47mt[0m when each key of
  the given alist belongs to the given list of keys; else it returns
  [47mnil[0m.  This is Boolean-equivalent to [47m(subsetp-eq (strip-cars alist)
  keys)[0m, but it avoids consing up the keys of [47malist[0m.")
 (ALIST-TO-DOUBLETS
  (ALISTS ACL2-BUILT-INS)
  "Convert an alist to a list of two-element lists

  The call [47m(alist-to-doublets alist)[0m returns the result of replacing
  each pair [47m(x . y)[0m in the given alist by the two-element list [47m(x y)[0m.
  The order is preserved, i.e., the following is a theorem.

    (implies (and (natp i) (< i (len alist)))
             (equal (nth i (alist-to-doublets alist))
                    (let ((pair (nth i alist)))
                      (list (car pair) (cdr pair)))))")
 (ALISTP
  (ALISTS ACL2-BUILT-INS)
  "Recognizer for association lists

  [47m(alistp x)[0m is true if and only if [47mx[0m is a list of [47m[cons][0m pairs.

  [47m(alistp x)[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<alistp>

    (defun alistp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (eq l nil))
            (t (and (consp (car l))
                    (alistp (cdr l))))))")
 (ALISTS
  (PROGRAMMING)
  "Operations on association lists, which bind keys to values.


Subtopics

  [Acons]
      Constructor for association lists

  [Alist-keys-subsetp]
      Check that all keys of the alist belong to a given set

  [Alist-to-doublets]
      Convert an alist to a list of two-element lists

  [Alistp]
      Recognizer for association lists

  [Assoc]
      Look up key in association list

  [Assoc-string-equal]
      Look up key, a string, in association list

  [Character-alistp]
      Recognizer for association lists with characters as keys

  [Delete-assoc]
      Deprecated version of [remove1-assoc]

  [Eqlable-alistp]
      Recognizer for a true list of pairs whose [47m[car][0ms are suitable for
      [47m[eql][0m

  [Fast-alists]
      Alists with hidden hash tables for faster execution

  [Pairlis]
      See [pairlis$]

  [Pairlis$]
      Zipper together two lists

  [Pairlis-x1]
      Cons a given element to each member of a list

  [Pairlis-x2]
      Cons each element of a list with a given element

  [Put-assoc]
      Modify an association list by associating a value with a key

  [R-eqlable-alistp]
      Recognizer for a true list of pairs whose [47m[cdr][0ms are suitable for
      [47m[eql][0m

  [R-symbol-alistp]
      Recognizer for association lists with symbols as values

  [Rassoc]
      Look up value in association list

  [Remove-assoc]
      Remove all pairs with a given key from an association list

  [Remove1-assoc]
      Remove the first pair with a given key from an association list

  [String-alistp]
      Recognizer for association lists with strings as keys

  [Strip-cars]
      Collect up all first components of pairs in a list

  [Strip-cdrs]
      Collect up all second components of pairs in a list

  [Sublis]
      Substitute an alist into a tree

  [Symbol-alistp]
      Recognizer for association lists with symbols as keys")
 (ALL-ATTACHMENTS (POINTERS)
                  "See [system-utilities].")
 (ALL-CALLS (POINTERS)
            "See [system-utilities].")
 (ALL-FNNAMES (POINTERS)
              "See [system-utilities].")
 (ALL-FNNAMES-LST (POINTERS)
                  "See [system-utilities].")
 (ALL-FNNAMES1 (POINTERS)
               "See [system-utilities].")
 (ALL-VARS (POINTERS)
           "See [system-utilities].")
 (ALLOCATE-FIXNUM-RANGE
  (NUMBERS ACL2-BUILT-INS)
  "Set aside fixnums in GCL

  [47m(Allocate-fixnum-range fixnum-lo fixnum-hi)[0m causes Gnu Common Lisp
  (GCL), versions preceding 2.7, to create a persistent table for the
  integers between [47mfixnum-lo[0m and [47mfixnum-hi[0m (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, [47mfixnum-lo[0m
  and [47mfixnum-hi[0m should be fixnums.  On 32-bit machines it would be
  good for them to be of type [47m(signed-byte 30)[0m, with [47mfixnum-lo <=
  fixnum-hi[0m.

  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 [47mnil[0m.

  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
  [47mallocate-fixnum-range[0m is a no-op for those versions.")
 (ALPHA-CHAR-P
  (CHARACTERS ACL2-BUILT-INS)
  "Recognizer for alphabetic characters

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

  The [guard] for [47malpha-char-p[0m states that its argument is a character.

  [47mAlpha-char-p[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<alpha-char-p>

    (defun alpha-char-p (x)
      (declare (xargs :guard (characterp x)))
      (cond ((standard-char-p x)
             (and (member x
                          '(#\\a #\\b #\\c
                                #\\d #\\e #\\f #\\g #\\h #\\i #\\j #\\k #\\l #\\m
                                #\\n #\\o #\\p #\\q #\\r #\\s #\\t #\\u #\\v #\\w
                                #\\x #\\y #\\z #\\A #\\B #\\C #\\D #\\E #\\F #\\G
                                #\\H #\\I #\\J #\\K #\\L #\\M #\\N #\\O #\\P #\\Q
                                #\\R #\\S #\\T #\\U #\\V #\\W #\\X #\\Y #\\Z))
                  t))
            (t (alpha-char-p-non-standard x))))")
 (ALPHORDER
  (<< ACL2-BUILT-INS)
  "Total order on atoms

  [47mAlphorder[0m 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 [47mt[0m or [47mnil[0m and satisfies the following properties.

    * Antisymmetry: [47mXrY & YrX -> X=Y[0m

    * Transitivity: [47mXrY & YrZ -> XrZ[0m

    * Trichotomy: [47mXrY v YrX[0m

  Also see [lexorder], which extends [47malphorder[0m to all objects.

  [47m(Alphorder x y)[0m has a guard of [47m(and (atom x) (atom y))[0m.

  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.

  [31;1mFunction: [0m<alphorder>

    (defun alphorder (x y)
      (declare (xargs :guard (and (atom x) (atom y))))
      (cond ((real/rationalp x)
             (cond ((real/rationalp y) (<= x y))
                   (t t)))
            ((real/rationalp y) nil)
            ((complex/complex-rationalp x)
             (cond ((complex/complex-rationalp y)
                    (or (< (realpart x) (realpart y))
                        (and (= (realpart x) (realpart y))
                             (<= (imagpart x) (imagpart y)))))
                   (t t)))
            ((complex/complex-rationalp y) nil)
            ((characterp x)
             (cond ((characterp y)
                    (<= (char-code x) (char-code y)))
                   (t t)))
            ((characterp y) nil)
            ((stringp x)
             (cond ((stringp y) (and (string<= x y) t))
                   (t t)))
            ((stringp y) nil)
            (t (cond ((symbolp x)
                      (cond ((symbolp y) (not (symbol< y x)))
                            (t t)))
                     ((symbolp y) nil)
                     (t (bad-atom<= x y))))))")
 (ALTERNATIVE-INTRODUCTION
  (ACL2-TUTORIAL)
  "Introduction to ACL2

  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.

  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.

  [3mOVERVIEW[0m

  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.

  We assume that readers of the ACL2 [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.

  As a [31;1mlogic[0m, 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.

  As a [31;1mspecification language[0m, 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 [31;1mmodel[0m 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.

  ACL2 is a [31;1mcomputational[0m 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 [31;1mare[0m 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.

  ACL2 is a powerful, automated [31;1mtheorem prover[0m 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 ``[events],'' possibly
  grouped into ``[books],'' that can be replayed in ACL2.  Therefore,
  a proof can be independently validated by any ACL2 user.

  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
  ``[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 [events] building
  an appropriate theory and proof rules leading up to the proof of
  the desired result.  Also, ACL2 supports annotating a theorem with
  ``[hints]'' designed to guide the proof attempt.  By supplying
  appropriate [hints], the user can suggest proof strategies that the
  prover would not discover automatically.  There is a
  ``[proof-tree]'' facility (see [proof-tree]) that allows the user
  to [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.

  ACL2 can also be used in a more explicitly interactive mode.  The
  interactive [proof-builder] subsystem of ACL2 allows exploration of
  a proof on a fairly low level including expanding calls of selected
  function symbols, invoking specific [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.

  Because ACL2 is all of these things --- computational logic,
  specification language, [programming] system, and theorem prover
  --- 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.

  [3mABOUT THIS TUTORIAL[0m

  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:

      familiarize the new user with the most basic features of and modes of
      interaction with ACL2;

      familiarize her with the form of output of the system; and

      work through a graduated series of examples.

  The more knowledge the user brings to this system, the easier it will
  be to become proficient.  On one extreme: the [31;1mideal[0m 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:

      (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);

      (b) be convinced of the utility of formal modeling; and

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

  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.

  As we said in the introduction, ACL2 has various facets.  For
  example, it can be used as a Common Lisp [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.

  [3mGETTING STARTED[0m

  This section is an abridged version of what's available elsewhere;
  feel free to see [startup] for more details.

  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.

  When you start up ACL2, you'll probably find yourself inside the ACL2
  [command] loop, as indicated by the following [prompt].

    ACL2 !>

  If not, you should type [47m(LP)[0m.  See [lp], which has a lot more
  information about the ACL2 [command] loop.

  There are two ``modes'' for using ACL2, [47m:[0m[47m[logic][0m and [47m:[0m[47m[program][0m.
  When you begin ACL2, you will ordinarily be in the [47m:[0m[47m[logic][0m mode.
  This means that any new function defined is not only executable but
  also is axiomatically defined in the ACL2 logic.  (See [defun-mode]
  and see [default-defun-mode].)  Roughly speaking, [47m:[0m[47m[program][0m mode
  is available for using ACL2 as a [programming] language without
  some of the logical burdens necessary for formal reasoning.  In
  this tutorial we will assume that we always remain in [47m:[0m[47m[logic][0m mode
  and that our purpose is to write formal models of digital systems
  and to reason about them.

  Now, within the ACL2 [command] loop you can carry out various kinds
  of activities, including the following.  (We'll see examples later
  of many of these.)

      define new functions (see [defun]);

      execute functions on concrete data;

      pose and attempt to prove conjectures about previously defined
      functions (see [defthm]);

      query the ACL2 ``[world]'' or database (e.g., see [pe]); and

      numerous other things.

  In addition, there is extensive on-line [documentation], of which
  this tutorial introduction is a part.

  [3mINTERACTING WITH ACL2[0m

  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 [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 [47m\"*shell*\"[0m
  buffer.

  In some cases, processing succeeds and makes some change to the ACL2
  ``logical [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.

  One of the most common [events] in constructing a model is
  introducing new functions.  New functions are usually introduced
  using the [47m[defun][0m 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 [31;1mterminate[0m.  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 [well-founded-relation-rule].

  For example, suppose that we need a function that will append two
  lists together.  (We already have one in the ACL2 [47m[append][0m
  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):

    (defun my-app (x y)
      (if (atom x)
          y
        (cons (car x) (my-app x y))))

  The system responds with the following message:

    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.

  This means that the system could not find an expression involving the
  formal parameters [47mx[0m and [47my[0m 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 [prompt]; you don't type that):

    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

  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 [xargs].)

  The system output provides several pieces of information.

      The revised definition is acceptable.  The system realized that there
      is a particular measure (namely, [47m(acl2-count x)[0m) and a
      well-founded relation ([47mo<[0m) under which the arguments of [47mmy-app[0m
      get smaller in recursion.  Actually, the theorem prover proved
      several theorems to admit [47mmy-app[0m.  The main one was that when
      [47m(atom x)[0m is false the [47macl2-count[0m of [47m(cdr x)[0m is less than (in
      the [47mo<[0m sense) the [47macl2-count[0m of [47mx[0m.  [47m[Acl2-count][0m is the most
      commonly used measure of the ``size`` of an ACL2 object.  [47m[o<][0m
      is the ordering relation on ordinals less than epsilon-0.  On
      the natural numbers it is just ordinary ``<''.

      The observation printed about ``the type of MY-APP'' means that calls
      of the function [47mmy-app[0m will always return a value that is
      either a [cons] pair or is equal to the second parameter.

      The [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.

  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.

  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 [47m:[0m[47m[pe][0m command (see [pe]).
  For example,

    ACL2 !>:pe my-app
     L       73:x(DEFUN MY-APP (X Y)
                        (IF (ATOM X)
                            Y (CONS (CAR X) (MY-APP (CDR X) Y))))

  This displays the definition along with some other relevant
  information.  In this case, we know that this definition was
  processed in [47m:[0m[47m[logic][0m mode (the ``[47mL[0m'') and was the 73rd [command]
  processed in the current session.

  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,

    ACL2 !>(my-app '(0 1 2) '(3 4 5))
    (0 1 2 3 4 5)
    ACL2 !>(my-app nil nil)
    NIL
    ACL2 !>

  Now suppose we want to prove something about the function just
  introduced.  We conjecture, for example, that the length of the
  [append] of two lists is the sum of their lengths.  We can
  formulate this conjecture in the form of the following ACL2
  [47m[defthm][0m form.

    (defthm my-app-length
      (equal (len (my-app x y))
             (+ (len x) (len y))))

  First of all, how did we know about the functions [47mlen[0m and [47m[+][0m, etc.?
  The answer to that is somewhat unsatisfying --- we know them from
  our past experience in using Common Lisp and ACL2.  It's hard to
  know that a function such as [47mlen[0m exists without first knowing some
  Common Lisp.  If we'd guessed that the appropriate function was
  called [47m[length][0m (say, from our knowledge of Lisp) and tried [47m:pe
  length[0m, we would have seen that [47m[length][0m is defined in terms of
  [47mlen[0m, and we could have explored from there.  Luckily, you can write
  a lot of ACL2 functions without knowing too many of the primitive
  functions.

  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 [47mmy-app[0m shows that if [47mx[0m is not a [cons] pair, then
  [47m(my-app x y)[0m always returns [47my[0m, no matter what [47my[0m is.

  Thirdly, would it matter if we rewrote the lemma with the equality
  reversed, as follows?

    (defthm my-app-length2
      (equal (+ (len x) (len y))
             (len (my-app x y)))).

  The two are [31;1mlogically[0m 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 [rewrite] rule.
  (See [rule-classes].)  For a [rewrite] rule, a conclusion of the
  form [47m(EQUAL LHS RHS)[0m means to replace instances of the [47mLHS[0m by the
  appropriate instance of the [47mRHS[0m.  Presumably, it's better to
  [rewrite] [47m(len (my-app x y))[0m to [47m(+ (len x) (len y))[0m than the other
  way around.  The reason is that the system ``knows'' more about [47m[+][0m
  than it does about the new function symbol [47mmy-app[0m.

  So let's see if we can prove this lemma.  Submitting our preferred
  [47m[defthm][0m to ACL2 (do it!), we get the following interaction:

              --------------------------------------------------
    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), but
    modified to accommodate (MY-APP X Y).  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,
    namely, the measure (ACL2-COUNT X) is decreasing according to the
    relation O< (which is known to be well-founded on the domain
    recognized by O-P).  When applied to the goal at hand the
    above induction scheme produces the following 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
              --------------------------------------------------

  Wow, it worked!  In brief, the system first tried to [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.

  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 [47m:induction[0m hint (see [hints]).  In
  the case of the theorem above, the system inducts on the structure
  of [47mx[0m as suggested by the decomposition of [47mx[0m in both [47m(my-app x y)[0m
  and [47m(len x)[0m.  In the base case, we assume that [47mx[0m is not a [47m[consp][0m.
  In the inductive case, we assume that it is a [47m[consp][0m and assume
  that the conjecture holds for [47m(cdr x)[0m.

  There is a close connection between the analysis that goes on when a
  function like [47mmy-app[0m 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 [47mmy-app[0m because the
  ``size'' of the first argument [47mx[0m decreases in the recursive call.
  That tells us that when we need to prove something inductively
  about [47mmy-app[0m, 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 [induction] schema, taking several of them into
  account.  That's what's meant by ``merging'' the induction schemas.

  The proof involves two cases: the base case, and the inductive case.
  You'll notice that the subgoal numbers go [31;1mdown[0m rather than up, so
  you always know how many subgoals are left to process.  The base
  case ([47mSubgoal *1/2[0m) 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 [47municity-of-0[0m).
  You can always look at those with [47m:[0m[47m[pe][0m; but, in general, assume
  that there's a lot of simplification power under the hood that's
  not too important to understand fully.

  The inductive case ([47mSubgoal *1/1[0m) is also dispatched pretty easily.
  Here we assume the conjecture true for the [47m[cdr][0m 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 ([47mSubgoal *1/1'[0m).  Examining these gives you a pretty good idea
  of what's going on in the proof.

  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 [proof-tree] utility helps with monitoring an ongoing
  proof and jumping to designated locations in the proof (see
  [proof-tree]).  See [tips] for a number of useful pointers on using
  the theorem prover effectively.

  When the prover has successfully proved all subgoals, the proof is
  finished.  As with a [47m[defun][0m, a [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 [hints] locally that will influence the prover's
  behavior.  Proving this lemma ([47mmy-app-length[0m) is an example of the
  first.  Since this is a [rewrite] rule, whenever in a later proof
  an instance of the form [47m(LEN (MY-APP X Y))[0m is encountered, it will
  be rewritten to the corresponding instance of [47m(+ (LEN X) (LEN Y))[0m.
  Disabling the rule by executing the [command]

    (in-theory (disable my-app-length)),

  is an example of a global change to the behavior of the prover since
  this [rewrite] will not be performed subsequently (unless the rule
  is again [enable]d).  Finally, we can add a (local) [disable]
  ``hint'' to a [47m[defthm][0m, meaning to [disable] the lemma only in the
  proof of one or more subgoals.  For example:

    (defthm my-app-length-commutativity
      (equal (len (my-app x y))
             (len (my-app y x)))
      :hints ((\"Goal\" :in-theory (disable my-app-length))))

  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.

  By the way, to undo the previous event use [47m:u[0m (see [u]).  To undo
  back to some earlier event use [47m:ubt[0m (see [ubt]).  To view the
  current event use [47m:pe :here[0m.  To list several [events] use [47m:pbt[0m
  (see [pbt]).

  Notice the form of the hint in the previous example (see [hints]).
  It specifies a goal to which the hint applies.  [47m\"Goal\"[0m 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 [disable]d only for Subgoal 1.3.9, say, and a different
  function [enable]d only on Subgoal 5.2.8.  Overuse of such [hints]
  often suggests a poor global proof strategy.

  We now recommend that you visit [documentation] on additional
  examples.  See [annotated-ACL2-scripts].")
 (ALWAYS$ (POINTERS) "See [loop$].")
 (ALWAYS$+ (POINTERS) "See [loop$].")
 (ANALYZING_COMMON_LISP_MODELS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Analyzing Common Lisp Models

  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.

  In any Common Lisp you can confirm that

    (app '(A B) (app '(C D) '(E F)))

  and

    (app (app '(A B) '(C D)) '(E F)))

  both evaluate to the same thing, [47m(A B C D E F)[0m.

  But what distinguishes ACL2 (the logic) from applicative Common Lisp
  (the language) is that in ACL2 you can [31;1mprove[0m that the concatenation
  function [47mapp[0m is associative when its arguments are true-lists,
  whereas in Common Lisp all you can do is test that proposition.

  That is, in ACL2 it makes sense to say that the following formula is
  a ``theorem.''

    [31;1mTheorem[0m Associativity of App
    (implies (and (true-listp a)
                  (true-listp b))
             (equal (app (app a b) c)
                    (app a (app b c))))

  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.")
 (AND
  (BASICS ACL2-BUILT-INS)
  "Conjunction

  [47mAnd[0m is the macro for conjunctions.  [47mAnd[0m takes any number of
  arguments.  [47mAnd[0m returns [47mnil[0m if one of the arguments is [47mnil[0m, but
  otherwise returns the last argument.  If there are no arguments,
  [47mand[0m returns [47mt[0m.

  [47mAnd[0m is a Common Lisp macro.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<and>

    (defmacro and (&rest args)
      (and-macro args))

  [31;1mFunction: [0m<and-macro>

    (defun and-macro (lst)
      (declare (xargs :guard t))
      (if (consp lst)
          (if (consp (cdr lst))
              (list 'if
                    (car lst)
                    (and-macro (cdr lst))
                    nil)
            (car lst))
        t))")
 (ANNOTATED-ACL2-SCRIPTS
  (ACL2-TUTORIAL)
  "Examples of ACL2 scripts

  Beginning users may find these annotated scripts useful.  We suggest
  that you read these in the following order:

    [Tutorial1-Towers-of-Hanoi]
    [Tutorial2-Eights-Problem]
    [Tutorial3-Phonebook-Example]
    [Tutorial4-Defun-Sk-Example]
    [Tutorial5-Miscellaneous-Examples]

  You can also find useful demos in the [community-books] directory,
  [47mbooks/demos/[0m, and its subdirectories.

  The web page {Brief ACL2 Tutorial |
  http://www.cs.utexas.edu/users/moore/publications/tutorial/rev3.html}
  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 --- 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.

  See {Polishing Proofs Tutorial |
  http://www.cs.utexas.edu/users/moore/acl2/contrib/POLISHING-PROOFS-TUTORIAL.html}
  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 [books]).

  The {ACL2 Demo Given at TPHOLs 2008 |
  http://www.cs.utexas.edu/users/moore/publications/tutorial/kaufmann-TPHOLs08/index.html}
  by Matt Kaufmann includes scripts and a gzipped tar file containing
  the entire contents of the demos.

  The {sort equivalence demo |
  http://www.cs.utexas.edu/users/moore/publications/tutorial/sort-equivalence}
  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 [47mREADME[0m on that
  directory.  There is also a {gzipped tar file |
  http://www.cs.utexas.edu/users/moore/publications/tutorial/sort-equivalence.tgz}
  with all of these scripts.

  When you feel you have read enough examples, you might want to try
  the following very simple example on your own. (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 [cons] structures, with [atom]s
  at the leaves.  For example:

    ACL2 !>(fringe '((a . b) c . d))
    (A B C D)

  Next, define the notion of a ``leaf'' of a tree, i.e., a predicate
  [47mleaf-p[0m 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 [47mfringe[0m.  Finally, prove the following theorem, whose proof
  may well be automatic (i.e., not require any lemmas).

    (defthm leaf-p-iff-member-fringe
      (iff (leaf-p atm x)
           (member-equal atm (fringe x))))


Subtopics

  [Solution-to-simple-example]
      Solution to a simple example

  [Tutorial1-towers-of-hanoi]
      The Towers of Hanoi Example

  [Tutorial2-eights-problem]
      The Eights Problem Example

  [Tutorial3-phonebook-example]
      A Phonebook Specification

  [Tutorial4-defun-sk-example]
      Example of quantified notions

  [Tutorial5-miscellaneous-examples]
      Miscellaneous ACL2 examples")
 (AN_EXAMPLE_COMMON_LISP_FUNCTION_DEFINITION
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "An Example Common Lisp Function Definition

  {IMAGE} (see [An_Example_of_ACL2_in_Use])

  Consider the binary trees [47mx[0m and [47my[0m below.

  {IMAGE}

  In Lisp, [47mx[0m is written as the list [47m'(A B)[0m or, equivalently, as [47m'(A B .
  NIL)[0m.  Similarly, [47my[0m may be written [47m'(C D E)[0m.  Suppose we wish to
  replace the right-most tip of [47mx[0m by the entire tree [47my[0m.  This is
  denoted [47m(app x y)[0m, where [47mapp[0m stands for ``append''.

  {IMAGE}

  We can define [47mapp[0m with:

    [31;1m(defun app (x y)[0m                           [3m; Concatenate x and y.[0m
      [31;1m(declare (type (satisfies true-listp) x))[0m[3m; We expect x to end in NIL.[0m
      [31;1m(cond ((endp x) y)[0m                       [3m; If x is empty, return y.[0m
            [31;1m(t (cons (car x)[0m                   [3m; Else, copy first node[0m
                     [31;1m(app (cdr x) y)))))[0m       [3m;  and recur into next.[0m

  If you defined this function in some Common Lisp, then to run [47mapp[0m on
  the [47mx[0m and [47my[0m above you could then type

    (app '(A B) '(C D E))

  and Common Lisp will print the result [47m(A B C D E)[0m.

  {IMAGE} (see [An_Example_of_ACL2_in_Use])")
 (AN_EXAMPLE_OF_ACL2_IN_USE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "An Example of ACL2 in Use

  {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions])

  To introduce you to ACL2 we will consider the [47mapp[0m function discussed
  in the Common Lisp (see [Common_Lisp]) page, [31;1mexcept[0m we will omit
  for the moment the [31;1mdeclare[0m form, which in ACL2 is called a [31;1mguard[0m.

  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.

  Here is the definition again

    [31;1m(defun app (x y)[0m
      [31;1m(cond ((endp x) y)[0m
            [31;1m(t (cons (car x) [0m
                     [31;1m(app (cdr x) y)))))[0m

  The next few stops along the Walking Tour will show you

    * how to use the ACL2 documentation,

    * what happens when the above definition is submitted to ACL2,

    * what happens when you evaluate calls of [47mapp[0m,

    * what one simple theorem about [47mapp[0m looks like,

    * how ACL2 proves the theorem, and

    * how that theorem can be used in another proof.

  Along the way we will talk about the [31;1mdefinitional principle[0m, [31;1mtypes[0m,
  the ACL2 [31;1mread-eval-print loop[0m, and how the [31;1mtheorem prover[0m works.

  When we complete this part of the tour we will return briefly to the
  notion of [31;1mguards[0m and revisit several of the topics above in that
  context.

  {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions])")
 (APPEND
  (LISTS ACL2-BUILT-INS)
  "[concatenate] zero or more lists

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

  [47mAppend[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.  See [append-without-guard] for a version of
  [47mappend[0m that has a guard of [47mt[0m.

  [31;1mMacro: [0m<append>

    (defmacro append (&rest rst)
      (cond ((null rst) nil)
            ((null (cdr rst)) (car rst))
            (t (xxxjoin 'binary-append rst))))

  [31;1mFunction: [0m<binary-append>

    (defun binary-append (x y)
      (declare (xargs :guard (true-listp x)))
      (cond ((endp x) y)
            (t (cons (car x)
                     (binary-append (cdr x) y)))))


Subtopics

  [Binary-append]
      [concatenate] two lists")
 (APPEND$ (POINTERS) "See [loop$].")
 (APPEND$+ (POINTERS) "See [loop$].")
 (APPLY$
  (ACL2-BUILT-INS PROGRAMMING)
  "Apply a badged function or tame lambda to arguments

  We recommend that you read the paper {``Limited Second-Order
  Functionality in a First-Order Setting'' |
  http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by
  Matt Kaufmann and J Strother Moore for both motivation and
  foundational details.  You might also read
  [introduction-to-apply$]!

  This documentation starts with a [31;1mglossary[0m of terms.  Then we provide
  some [31;1mexamples[0m and present the [31;1mspecification[0m of [47mapply$[0m.  Next, we
  deal with issues related to [47mapply$[0m in [31;1mdefinitions[0m, [31;1mstating and
  proving theorems[0m, [31;1mguards and guard verification[0m, and [31;1mtop-level
  evaluation[0m.  Finally we exhibit the [31;1mformal definitions[0m [47mapply$[0m and
  some related concepts.  We have sprinkled in a little tutorial
  material for readability but have not provided much motivation for
  some design decisions.


Glossary

  Here is a brief glossary of terms used in the semantics of [47mapply$[0m.
  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!

    * [47mapply$[0m --- 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, [47mapply$[0m applies the
      function to the arguments and returns the result.  [47mApply$[0m is
      mutually recursive with [47m[apply$-lambda][0m, [47m[ev$][0m, and [47m[ev$-list][0m.
      [47mApply$[0m's ``badge'' (see below) is [47m(APPLY$-BADGE 2 1 :FN NIL)[0m
      its arity is 2, its ``out arity'' is 1 (i.e., it returns 1
      result), its first argument has ``ilk'' [47m:FN[0m and is thus treated
      as a ``function;'' its second argument has ilk [47mNIL[0m and is thus
      treated as an ordinary object.

    * [47m[badge][0m --- an object associated with some function symbols
      indicating that [47mapply$[0m 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 [ilk] of each argument position
      telling [47mapply$[0m how each argument is treated.  The ilks are [47m:FN[0m,
      [47m:EXPR[0m and [47mNIL[0m.  The association between a non-primitive
      function symbol and its badge is managed by [47m[warrant][0ms.  In
      proofs, [47mapply$[0m 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 [47mapply$[0md.  Badges are generated, when possible, by
      [47m[defwarrant][0m.  (Badges can be generated for [47m:[0m[47mprogram[0m mode
      functions by [47m[defbadge][0m, allowing [47mapply$[0m to handle such
      functions in top level evaluation not in proofs.)  Not every
      function symbol can have a badge.

    * compiled [47mLAMBDA[0m cache (or simply [3mcache[0m in this context) --- a cache
      in the raw Lisp under ACL2 that supports the application of
      [47mapply$[0m on well-formed, guard verified [47mLAMBDA[0m objects.  Later in
      this Glossary we define ``lambda expression,'' ``[47mLAMBDA[0m
      object,'' and ``lambda$ expression'' --- three similar looking
      phrases with very different meanings.  See [47m[print-cl-cache][0m for
      some details of the cache.

    * evaluation theory --- 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 [47m[defattach][0m was added, but it was
      changed with the introduction of [47mapply$[0m.  All [47m[warrant][0ms
      introduced by [47mdefwarrant[0m are assumed true in the evaluation
      theory but not in the proof theory.  This means ACL2 can
      execute calls of [47mapply$[0m that arise in the evaluation of
      top-level input, but ACL2 cannot evaluate all calls of [47mapply$[0m
      that arise in proofs unless the appropriate warrants are
      available as hypotheses.  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.

    * lambda expression --- an integral part of ACL2's formal term syntax,
      lambda expressions are the way [47mlet[0m expressions and other
      variable-binding idioms are translated into formal terms.
      Lambda expressions have nothing to do with [47mapply$[0m!  See
      [lambda] for a discussion of three confusingly similar but
      different concepts: lambda expressions, [47mLAMBDA[0m objects, and
      [47mlambda$[0m expressions.  Read carefully anytime you see the word
      ``lambda!''

    * [47mLAMBDA[0m object --- an ACL2 list constant, typically of the form
      [47m(LAMBDA vars body)[0m or [47m(LAMBDA vars dcl body)[0m that may be used
      as a ``function'' by [47mapply$[0m.  [47mApply$[0m treats any [47m[consp][0m object
      in its first argument position as though it were a [47mLAMBDA[0m
      object.  But it only gives sensible meanings to [tame] [47mLAMBDA[0m
      objects.  And only well-formed [47mLAMBDA[0m objects are executed
      efficiently.  But well-formed [47mLAMBDA[0m objects are hard to type
      by hand --- there are many constraints to keep in mind to
      guarantee well-formedness.  See [47m[well-formed-lambda-objectp][0m if
      you really want to see all the rules.  But that is generally
      unnecessary.  We [3mstrongly[0m recommend not entering [47mLAMBDA[0m objects
      as quoted constants, e.g., [47m'(LAMBDA (X) (+ 1 X))[0m --- which is
      actually ill-formed!  Instead, use [47m[lambda$][0m, as in [47m(lambda$
      (x) (+ 1 x))[0m.  See also [lambda] for some clarifications.

    * [47m[lambda$][0m expression --- an ACL2 macro that allows you to enter
      quoted well-formed [47mLAMBDA[0m objects into your terms by typing
      untranslated expressions that resemble lambda expressions.  The
      [47mlambda$[0m expression [47m(lambda$ (x) (+ 1 x))[0m essentially translates
      into the quoted [47mLAMBDA[0m object [47m'(LAMBDA (X) (BINARY-+ '1 X))[0m.
      We say ``essentially'' because [47mlambda$[0m always inserts a
      [47m(DECLARE (IGNORABLE v1 ... vn))[0m listing every formal and tags
      the body with a [47m[return-last][0m form that indicates it came from
      a translated [47mlambda$[0m. See also [lambda] for some
      clarifications.

    * [47m[scion][0m --- a function that is ancestrally dependent on [47mapply$[0m.  In
      the early days of [47mapply$[0m 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 [47mapply$[0ming 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 [47mapply$[0m is a scion whether or not it
      takes a ``function'' as an argument or maps over a domain.

    * [tame] --- the class of functions that [47mapply$[0m knows about; we
      actually talk about ``tame functions,'' ``tame [47mLAMBDA[0m
      objects,'' and ``tame expressions.'' The last are expressions
      that are evaluable by an interpreter named [47m[ev$][0m that is
      mutually-recursive with [47mapply$[0m.  [47mApply$[0m cannot handle all
      definable functions: ACL2 is first order and if [47mapply$[0m were
      able to ``handle'' certain functions the logic would be
      inconsistent.

    * [47m[warrant][0m --- a 0-ary predicate associated with some user-defined
      function symbols that must be a hypothesis of any theorem whose
      proof involves ``expanding'' [47mapply$[0m on such symbols; the
      warrant gives [47mapply$[0m ``permission'' to expand if the arguments
      to which the function is applied are appropriately [tame].  The
      warrant for a function specifies the function's [47m[badge][0m and how
      [47mapply$[0m behaves on the function symbol.  Warrants (and badges)
      are computed and introduced by the [47m[defwarrant][0m event.  Not all
      function symbols can be warranted.

  You will get a much better understanding of these concepts if you
  read the paper cited above.


Examples

  To illustrate [47mapply$[0m and some related concepts we need some
  user-defined functions.  We therefore imagine that the following
  events have been successfully admitted.

  [31;1mWe strongly recommend that you include the following book in any
  session in which you intend to use or reason about [47mapply$[0m[31;1m.[0m

    (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))))

  Note: [47mCollect$[0m is pre-defined in ACL2 because it is part of the
  support for the [47m[loop$][0m statement.

  [47mCollect$[0m and [47mfoldr[0m 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
  [3mscions of[0m [47mapply$[0m or simply [3mscions[0m: functions in which [47mapply$[0m is
  ancestral, i.e., functions that call [47mapply$[0m or call functions that
  call [47mapply$[0m, etc.  [47mRussell[0m is also a scion.  See [scion] for more.

  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
  [47m[defattach][0m), 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!

    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

  [47mApply$[0m doesn't always work the way you might want!

    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.

  [47m[Apply$-userfn][0m is the undefined function called by [47mapply$[0m when it
  is asked to apply a user-defined function symbol instead of a
  builtin function symbol.  The [47m[warrant][0m for [47mrussell[0m actually
  specifies the value of [47m(apply$-userfn 'russell ...)[0m under the
  [47m[tame][0mness requirements, and those requirements are violated above.
  This is necessary to preserve the consistency of the logic.
  Otherwise:

    (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!

  Top-level evaluation of [47mapply$[0m 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 [47m[lambda$][0m expressions (and user-typed quoted
  [47mLAMBDA[0m objects) that occur in positions of ilk [47m:FN[0m and are
  therefore destined for [47mapply$[0m.  But the translation checks can be
  defeated.  The [47mLAMBDA[0m object below contains a call of the undefined
  function [47mfoo[0m but the error is not caught at translation time; it is
  caught only when the form executed.

    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.

  Note the [3mbackquote[0m on the [47mLAMBDA[0m object.  This defeats the check of
  well-formedness because the [47mLAMBDA[0m object is not [47mquote[0md.  We could
  have equally written

    ACL2 !>(apply$ (list 'lambda '(x) (cons 'foo '(x))) '(5))

  with the same result.  There is nothing unsound about this.  [47mApply$[0m
  can take any objects as arguments.  But it won't always ``behave''
  as you might expect.  One way to explore the edge cases of [47mapply$[0m
  is to execute it on ill-formed input.  In addition, some theorems
  may require consing up a [47mLAMBDA[0m object in terms of objects used
  elsewhere in the theorem.  See example theorem [47m[3][0m below.

  A peculiar aspect of [47mLAMBDA[0m objects is that they can be written as
  legal ACL2 constants [3mbefore[0m they are well-formed [47mLAMBDA[0m objects,
  e.g., by referring to undefined functions, [47m:program[0m 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 [3mbecome[0m well-formed if the world is
  appropriately extended, e.g., the appropriate [47mdefun[0ms, [47mdefbadge[0ms,
  and [47mdefwarrant[0ms are made.  Perhaps worse, they can be well-formed
  and then [3mbecome[0m ill-formed by an undo.  So at runtime [47mapply$[0m has to
  check that the function symbol or [47mLAMBDA[0m object is appropriate.
  There is a sophisticated cache behind the execution machinery for
  [47mLAMBDA[0m objects in the evaluation theory.  See [47m[print-cl-cache][0m.

  Here are some theorems that can be proved about these concepts.  The
  last of the theorems shown below requires two lemmas, named
  [47mweird-little-lemma1[0m and [47mweird-little-lemma2[0m, shown in
  [47mbooks/projects/apply/report.lisp[0m.

  For a summary of how the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m
  [scion]s, see [rewriting-calls-of-apply$-ev$-and-loop$-scions].

    ; [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))))


Specification of APPLY$

  [31;1mWe strongly recommend that you include the following book in any
  session in which you intend to use or reason about [47mapply$[0m[31;1m.[0m

    (include-book \"projects/apply/top\" :dir :system)

    General Form:
    (apply$ fn args)

  where [47mfn[0m is some function symbol or [47mLAMBDA[0m object and [47margs[0m is a true
  list.  Informally, [47mapply$[0m applies the function named by the first
  argument to the appropriate number of elements taken from the
  second argument.  We might express this as:

    [31;1mNaive Specification (for a single-valued function):[0m
    (apply$ 'fn args) = (fn (nth 0 args) ... (nth (- n 1) args))

    [31;1mNaive Specification (for a multi-valued function):[0m
    (apply$ 'fn args) = (mv-list k (fn (nth 0 args) ... (nth (- n 1) args)))

  where [47mfn[0m is of arity [47mn[0m and [47mk[0m is the ``out arity'' of [47mfn[0m (the number
  of returned values).  [31;1mHowever[0m, these naive specifications are
  guaranteed only if either (i) [47mfn[0m is a function symbol that has a
  [47m[badge][0m and [47margs[0m satisfies the [tame]ness requirements of the
  badge, or (ii) [47mfn[0m is a well-formed [47mLAMBDA[0m object that returns 1
  result.  The tameness requirement is that if an element of [47margs[0m is
  in an argument position of [47mfn[0m with ilk [47m:FN[0m then the element must
  satisfy [47mtamep-functionp[0m and if the element is in an argument
  position of ilk [47m:EXPR[0m it must satisfy [47mtamep[0m.  See [47m[badge][0m for
  further discussion of condition (i).  As for (ii), rather than
  explain ``well-formed [47mLAMBDA[0m object'' here we encourage you to
  write [47m[lambda$][0m expressions when you want to [47mapply$[0m a [47mLAMBDA[0m
  object.

  The [ilk]s of [47mapply$[0m are [47m:FN[0m and [47mNIL[0m respectively, telling us that
  [47mapply$[0m treats its first argument as a ``function'' and its second
  as an ordinary object (never as a function).  Initially [47mapply$[0m and
  several functions used in the translation of [47mloop$[0m statements are
  the only symbols in ACL2 with an ilk of [47m:FN[0m.  However as
  [47m[defwarrant][0m is used successfully on [scion]s --- functions that
  somehow call [47mapply$[0m --- user-defined symbols can have ilk [47m:FN[0m too.

  [47mApply$[0m has a guard, namely [47m(apply$-guard fn args)[0m.  This is an
  exceptionally weak guard, requiring only that [47margs[0m be a true-list
  and, if [47mfn[0m is a cons --- which is automatically treated as a [47mLAMBDA[0m
  object --- the length of [47margs[0m be the length of the second element
  of [47mfn[0m.  We discuss [31;1mguards and guard verification[0m in a subsequent
  section.

  [31;1mNote for Experts[0m: Technically, [47mapply$[0m treats any [47mconsp[0m object as a
  [47mLAMBDA[0m object.  But the results are as you'd naively expect only if
  the object is a [tame] [47mLAMBDA[0m object.  However, we frequently write
  as though the object must be [3mwell-formed[0m, 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 [47mapply$[0m and the practical
  business of executing it.  The former involves the existence of a
  model, soundness, and the difficulty of proving theorems about
  [47mapply$[0m.  The latter involves the Common Lisp compiler.  We want the
  logical foundations to be simple to make it easier to reason about
  [47mapply$[0m, but the compiler imposes unavoidable and complicated
  restrictions.  The upshot is that the logical foundations assign
  meaning to [47mLAMBDA[0m objects that cannot be compiled.  Applying merely
  ``tame'' [47mLAMBDA[0ms is slower than applying ``well-formed'' ones.  In
  a sense, by acting like ``tame [47mLAMBDA[0m objects'' and ``well-formed
  [47mLAMBDA[0m objects'' are synonymous we're trying to trick you!  If you
  ever have occasion to formally express the restrictions on [47mapply$[0m
  in some theorem, use [47mtamep-functionp[0m.  But when you write concrete
  [47mLAMBDA[0m constants, try to keep them well-formed.  We encourage this
  by providing [47m[lambda$][0m and by enforcing full blown well-formedness
  checks --- not just tameness checks --- in translate on every
  quoted [47mLAMBDA[0m object entered in a [47m:FN[0m slot.  And we give you ways
  to circumvent these checks --- see
  [gratuitous-lambda-object-restrictions] --- if you really mean to
  supply ill-formed [47mLAMBDA[0m objects to [47m:FN[0m slots.

  Badges are assigned by [47m[defwarrant][0m, and also by [47m[defbadge][0m.  See
  [47m[badge][0m 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.

  Intuitively, the badge of [47mfn[0m tells [47mapply$[0m how each formal of [47mfn[0m is
  used in the definition of [47mfn[0m and there are only three ``ilks'' of
  use.  Ilk [47m:FN[0m means the formal is used exclusively as a function,
  meaning the formal can be passed into [47m:FN[0m slots of other functions
  and eventually reaches [47mapply$[0m, but it is never touched by other
  ACL2 functions.  Ilk [47m:EXPR[0m means the formal is used exclusively as
  an expression, meaning the formal may be passed into [47m:EXPR[0m slots of
  other functions and eventually reaches [47m[ev$][0m, but is never
  otherwise touched.  Finally, ilk [47mNIL[0m 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 [47m:FN[0m slots must satisfy [47mtamep-functionp[0m, actuals in [47m:EXPR[0m
  slots must satisfy [47mtamep[0m, and there are no requirements on actuals
  in ilk [47mNIL[0m slots.  For discussions of [47mtamep-functionp[0m and [47mtamep[0m see
  the topic [tame].

  Generally speaking, if you want to be able to [47mapply$[0m a function you
  should introduce it with [47m[defun][0m and then call [47m[defwarrant][0m on the
  function name, or use [47m[defun$][0m, which is a convenient abbreviation
  for the above sequence of events.  But [47mdefun$[0m only works for [47m:logic[0m
  mode functions because [47mdefwarrant[0m enforces that restriction.  If
  you want to [47mapply$[0m a [47m:program[0m mode function you should define it
  with [47mdefun[0m and then call [47mdefbadge[0m on its name.

  We summarize the specification of [47mapply$[0m with an example.  Consider

    (apply$ 'foldr
            '((1 2 3)     ; actual 1
              cons        ; actual 2
              (4 5 6)))   ; actual 3

  The badge of [47mfoldr[0m, computed by [47m(badge 'foldr)[0m, is [47m(APPLY$-BADGE 3 1
  NIL :FN NIL)[0m.  The arity is [47m3[0m, the out arity is 1 ([47mfoldr[0m is
  single-valued) and the ilks list is [47m(NIL :FN NIL)[0m.  Thus the first
  and third formals have ilk [47mNIL[0m and are treated as ordinary objects;
  the second formal has ilk [47m:FN[0m and is treated as a function.  Thus,
  the tameness requirement is that the second actual to a call of
  [47mfoldr[0m must satisfy [47mtamep-functionp[0m.  Referring to the specification
  above, we see that the [47mapply$[0m term has the ``naive specification''
  since [47mfoldr[0m has a badge, its out arity is 1, and its second actual,
  [47mcons[0m, satisfies [47mtamep-functionp[0m. That is,

    (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)

  The first equation above is just the naive specification of [47mapply$[0m
  and the second equation is just the definition of [47mfoldr[0m.

  Formals are classified by [47m[defwarrant][0m when it tries to compute the
  badge of a function.  What are the rules that lead to a formal
  being assigned ilk [47m:FN[0m, for example?  What does ilk [47m:FN[0m actually
  signify?

  Let [3mv[0m be the [3mi [0mth formal parameter of a badged function [3mfn[0m.  If the
  badge says that [3mv[0m has ilk [47m:FN[0m then we know that [3mv [0m is ``used as a
  function'' in the definition of [3mfn [0m, i.e., the value of [3mv [0m
  eventually makes its way into the first argument of [47mapply$[0m.
  Furthermore, [3mv [0m is never used any other way: every place [3mv [0m occurs
  in the body it is treated as a function.  And finally, in every
  recursive call of [3mfn [0m [3mv [0m is passed identically in the [3mi [0mth argument
  position of every recursive call.

  If the badge says that formal variable [3mv [0m has ilk [47m:EXPR[0m then it
  signifies analogous conditions except that instead of eventually
  getting into the first argument of [47mapply$[0m it eventually gets into
  the first argument of [47mev$[0m.  We say such formals are ``used as
  expressions.'' [47m[Ev$][0m is the natural notion of evaluation in this
  context: look up the values of variables in the alist argument to
  [47mev$[0m, return quoted constants, and otherwise [47mapply$[0m function symbols
  and [47mlambda[0m objects to the recursively obtained list of values
  returned by evaluating the actuals.  However, [47mev$[0m first checks that
  the expression is [47m[tamep][0m.

  If the badge says a formal [3mv [0m has ilk [47mNIL[0m in the definition of [3mfn [0m
  then [3mv [0m is [3mnever used [0m as a function or as an expression in the
  definition.

  It is the job of [47m[defwarrant][0m to analyze a definition and assign
  ilks, if possible.  But it may not be possible!  For example,

    (defun foo (x) (apply$ x (list x)))

  is such a definition.  The formal [47mx[0m is used as a function in its
  first occurrence but is not used as a function in its second.  Thus

    (defwarrant foo)

  will fail.

  When successful, [47m[defwarrant][0m also defines the [47m[warrant][0m function for
  the function it analyzed.  Warrants are crucial to stating and
  proving theorems about function symbols being applied with [47mapply$[0m.
  We illustrated warrants in the ``Examples'' section above and
  discuss them further in the section on ``Theorems Involving
  [47mApply$[0m'' below.  See also [47m[warrant][0m.

  [47mApply$[0m 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

    ACL2 !>:pe apply$

  The definition is mutually recursive with

    * [47m[apply$-lambda][0m: used by [47mapply$[0m to handle the case when the first
      argument to [47mapply$[0m is a [47mLAMBDA[0m object.

    * [47m[ev$][0m: used by [47mapply$-lambda[0m to evaluate the body of a [47mLAMBDA[0m object
      in an environment binding the object's formal variables to the
      actuals.

    * [47m[ev$-list][0m: used by [47mev$[0m to evaluate a list of expressions in an
      environment binding formals to actuals.

  [47mApply$[0m calls three undefined functions:

    * [47m[apply$-userfn][0m: used by [47mapply$[0m when it is asked to apply anything
      other than a [47mLAMBDA[0m object or a built-in function symbol.  In
      the evaluation theory, we attach a function to [47mapply$-userfn[0m
      that explicitly enforces the tameness requirements for each
      user-defined [47m:logic[0m mode function symbol that has had a badge
      computed by [47m[defwarrant][0m and, if those requirements are met,
      applies the corresponding function.  Magically, that attachment
      to [47mapply$-userfn[0m can also evaluate [47m:program[0m mode functions with
      badges created by [47m[defbadge][0m.  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 [47m:program[0m mode functions in the evaluation theory.  But in
      the proof theory [47mapply$-userfn[0m remains undefined.  The value of
      [47m(apply$-userfn 'fn ...)[0m, and thus of [47m(apply$ 'fn ...)[0m, is
      specified by a special hypothesis, called the ``warrant for
      [47mfn[0m.'' You can't prove anything interesting about the behavior
      of [47mapply$[0m on a user-defined function symbol [47mfn[0m unless the
      warrant for [47mfn[0m is a governing hypothesis.  We discuss warrants
      in [47m[warrant][0m.  See also [47m[defwarrant][0m.

    * [47muntame-apply$[0m: used by [47mapply$[0m when it is asked to deal with a
      situation in which tameness is violated.

    * [47muntame-ev$[0m: used by [47mev$[0m when it is asked to deal with a situation in
      which tameness is violated.


Definitions Involving on [47mApply$[0m

  In one sense, [47mapply$[0m is just an ordinary ACL2 function that takes two
  arguments and returns one result.  Like all ACL2 functions, [47mapply$[0m
  is untyped.  You can supply any two objects as arguments and the
  axioms tell you what the result is --- though sometimes the result
  is delivered by an undefined function.

  But in a deeper sense, if you want [47mapply$[0m to ``behave,'' and in
  particular if you want functions that use [47mapply$[0m 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 [47m:logic[0m mode
  function that you define to be processed by [47mdefwarrant[0m so that it
  gets a badge and warrant if at all possible and at least has a
  chance of being applied as expected by [47mapply$[0m.

  The macro [47mdefun$[0m is just an abbreviation for a [47mdefun[0m followed by a
  [47mdefwarrant[0m and it is easy to imagine the other ACL2 definitional
  idioms introduced in the ACL2 Community Books eventually being
  extended to include a subsequent [47mdefwarrant[0m.

  So the question becomes ``What rules must a [47mdefun[0m obey in order to be
  processed successfully by [47mdefwarrant[0m?'' The full answer is given in
  the documentation for [47m[defwarrant][0m.  But here are some guidelines
  to follow:

    * use [47m:logic[0m mode,

    * use a measure that either returns a natural number or a lexicographic
      combination of natural numbers as defined by the [47mllist[0m function
      in the Community Books at [47mbooks/ordinals/[0m,

    * make sure every function used in the definition has a badge,

    * ensure that every [47m:FN[0m slot in the body is occupied either by a formal
      parameter or a quoted, badged function symbol or [47m[lambda$][0m
      expression, and

    * ensure that no parameter occupying a [47m:FN[0m slot is ever used in a slot
      of any other ilk, and

    * ensure that every parameter passed into a [47m:FN[0m slot is passed into the
      same argument position in any recursive calls of the function
      being defined.

  You can certainly violate some of these rules and still get an
  admissible definition.  For example [47m(defun rus (x) (not (apply$ x
  (list x))))[0m is admissible and you can run it on some arguments,
  e.g., [47m(rus 'consp)[0m evaluates to [47mT[0m.  You can even prove [47m(equal (rus
  'consp) t)[0m.  But [47m(defwarrant rus)[0m fails because [47mrus[0m violates the
  rules.  So you will not be able to [47mapply$[0m [47m'rus[0m.

  [31;1mNote for Experts[0m: One may wonder why it is possible to warrant a
  function, [47mfn[0m, that calls badged but unwarranted functions.  Naively
  one might expect the semantics of [47m(apply$ 'fn args[0m would involve
  the [47mev$[0m of the body of [47mfn[0m and therefore require the successful
  application (via [47mapply$[0m) of subfunctions in the body.  But that
  expectation is incorrect.  The semantics of [47m(apply$ 'fn args)[0m as
  formalized by the warrant for [47mfn[0m says that (under restrictions on
  the tameness of the arguments) [47m(apply$ 'fn args)[0m is [47m(fn (car args)
  (cadr args) ...)[0m.


Theorems Involving [47mApply$[0m

  Because [47mapply$[0m is undefined on user-defined function symbols and
  warrant hypotheses specify the tameness requirements and value of
  [47mapply$[0m on such symbols, you can't prove much about the application
  of particular user-defined symbols unless you provide the
  corresponding warrants as hypotheses.

  To emphasize this point, suppose [47msq[0m has been introduced with [47mdefun$[0m
  as shown above, then the following top-level evaluation is
  possible:

    ACL2 !>(apply$ 'sq '(5))
    25

  You might expect to be able to prove the obvious little theorem

    (thm (equal (apply$ 'sq '(5)) 25))

  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 [47mLOCAL[0m problem mentioned in example theorem [47m[1][0m above and
  in [introduction-to-apply$].)  Logically, there is no connection
  between the symbol [47m'SQ[0m and the user-defined function [47msq[0m.  That
  connection is established by warrant.  All the necessary warrants
  must be explicitly provided as hypotheses by the user.

  The warranted version of the little theorem above is easily proved.

    (thm (implies (warrant sq) (equal (apply$ 'sq '(5)) 25)))

  Here [47m(warrant sq)[0m is just an abbreviation for a call of the 0-ary
  function symbol [47mapply$-warrant-sq[0m which is the name of the warrant
  for [47msq[0m.  [47mApply$-warrant-sq[0m is introduced when [47m(defwarrant sq)[0m
  completes successfully.  In particular, the following is a theorem:

      (warrant sq)
    <-->
      (force (apply$-warrant-sq))
    <-->
      (((badge 'SQ) = '(APPLY$-BADGE 1 1 . T))
       &
       ((apply$ 'SQ args) = (sq (car args))))

  Note that the [47m[warrant][0m macro [47m[force][0ms the warrants for the functions
  listed.  But logically [47mforce[0m is just the identity.

  Thus, the warrant for [47msq[0m specifies the value of [47m(badge 'sq)[0m and of
  [47m(apply$ 'sq ...)[0m.  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.

  If you try to prove the unwarranted version of the little theorem
  about [47m'sq[0m it fails in a forcing round with

    [1]Goal
    (APPLY$-WARRANT-SQ)

  This is a clear indication that you forgot to provide the warrant.

  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.  [3mThere is a model of
  [47mapply$[0m[3m and all of its scions that makes every warrant issued by
  [47mdefwarrant[0m[3m valid.[0m The proof of this is sketched in {``Limited
  Second-Order Functionality in a First-Order Setting'' |
  http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by
  Matt Kaufmann and J Strother Moore and fully fleshed out in the
  comment titled [47mEssay on Admitting a Model for Apply$ and the
  Functions that Use It[0m in the ACL2 source file [47mapply-raw.lisp[0m.

  So there are four lessons here:

  [31;1mLesson 1:[0m When stating theorems involving [47mapply$[0m or scions on
  concrete user-defined functions, provide as additional hypotheses
  the warrants for all user-defined functions that [47mapply$[0m will
  encounter during the proof.  This generally means you should add
  the hypothesis [47m(warrant [0m[3mfn1 fn2 ... fnk[0m[47m)[0m typically listing every
  function symbol that appears inside a quoted constant destined for
  [47mapply$[0m or [47mev$[0m in your conjecture.  In particular, you should
  include every quoted function symbol appearing in a [47m:FN[0m slot of
  [47mapply$[0m or any scion, including every function symbol appearing in
  the body of any [47mLAMBDA[0m object or [47mlambda$[0m term or any [47muntil[0m, [47mwhen[0m,
  or body expressions of [47mloop$[0ms.  (Macro expansion in [47mlambda$[0ms and
  [47mloop$[0ms may introduce function symbols not evident in the
  untranslated forms.  See [47m:[0m[47m[translam][0m and [47m:[0m[47m[trans][0m.)

  [31;1mLesson 2:[0m You need not worry that adding warrant hypotheses makes
  your theorems vacuously valid!  There is a model of [47mapply$[0m and all
  your scions in which all warrants are valid.

  [31;1mLesson 3:[0m If a proof involving [47mapply$[0m 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.)

  [31;1mLesson 4:[0m If a proof involving [47mapply$[0m 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
  [47mapply$[0m.  You have to identify which quoted function symbols are not
  being simplified or expanded.  Typically you'll see a checkpoint
  with a term like [47m(apply$ 'fn ...)[0m or [47m(ev$ '(fn ...)  ...)[0m that you
  expect would be expanded into an actual call of [47mfn[0m.  In that case,
  [47mfn[0m 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 [47mapply$[0m term slowed the
  proof-attempt down by several orders of magnitude.  Here are some
  questions you should ask yourself about [47mfn[0m.

    * Is [47mfn[0m defined and in [47m:logic[0m mode?  If [47mfn[0m is in [47m:program[0m mode it is
      treated by the prover as an undefined symbol.  You should try
      to convert it [47m:logic[0m mode with [47m[verify-termination][0m.

    * Is [47mfn[0m warranted?  If not, see [47m[defwarrant][0m.  If [47mfn[0m is warranted then
      it is possible [47mfn[0m is not the problem.  Maybe the warrant for [47mfn[0m
      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 [47mfn[0m was forced.  But you
      should ask whether forcing is disabled; see [47m[force][0m.

    * If you see [47m(apply$ 'fn ...)[0m then perhaps the rewrite rule [47mAPPLY$-fn[0m
      is disabled.  That rule is the one that forces the warrant for
      [47mfn[0m and it was proved when [47mfn[0m was warranted.

    * Consider how the rewriter handles [47mapply$[0m terms, by reading
      [rewriting-calls-of-apply$-ev$-and-loop$-scions] and inspecting
      the enabled/disabled status of the runes mentioned there.

  These issues are discussed further in the documentation for
  [47m[warrant][0m.

  An unfortunate implication of the need for warrants is highlighted
  during the proofs of measure conjectures while admitting new
  definitions.  Consider

    (defun$ my-cdr (x) (cdr x))

    (defun$ my-len (x)
      (if (endp x)
          0
          (+ 1 (my-len (apply$ 'my-cdr (list x))))))

  The definition of [47mmy-len[0m fails!  The reason is that without the
  warrant for [47mmy-cdr[0m 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 [47mapply$[0m --- and functions that use [47mapply$[0m --- in
  ``termination-critical'' roles.  By that we mean do not use [47mapply$[0m
  if its properties are important to proofs of your measure
  conjectures.  This is easy advice to implement in the case of
  [47mmy-len[0m, i.e., replace the recursive call above by [47m(my-len (my-cdr
  x))[0m.  However, in more sophisticated definitions, e.g., where a
  [47m[loop$][0m is being used in recursive calls and the [47mloop$[0m calls
  user-defined functions in its body, following this advice means
  replacing that [47mloop$[0ms by a recursive function.  That is unfortunate
  since the whole point of [47mloop$[0m is to avoid the introduction of such
  functions!  We hope to address this limitation in the future, e.g.,
  by making the definition of [47mmy-len[0m above be conditional on the
  warrant for [47mmy-cdr[0m.


Guards and Guard Verification

  As noted, [47mapply$[0m has a guard of [47m(apply$-guard fn args)[0m and is itself
  guard verified.  The guard is weak, basically requiring that [47mfn[0m
  either be a symbol or a [47mLAMBDA[0m object, that [47margs[0m be a true-list,
  and, when [47mfn[0m is a [47mLAMBDA[0m object, the length of the list of formals
  is equal to the length of [47margs[0m.  To verify the guards of a scion
  you must make sure these properties hold of every application of
  anything in a [47m:FN[0m slot.  Mainly you must make sure that every time
  a function object is [47mapply$[0md, it is applied to a list of the right
  length.

  Note also that [mixed-mode-functions], i.e., [47m:logic[0m mode functions
  that use [47m:program[0m mode functions in slots of [ilk] [47m:FN[0m or [47m:EXPR[0m,
  cannot be guard verified.

  But guards arise in another way in connection with [47mapply$[0m.  How does
  [47m(apply$ fn args)[0m behave when [47mfn[0m has guards?  The short answer is:
  logically speaking, [47mapply$[0m completely ignores guards.  Guards in
  ACL2 are ``extra-logical.''

  Let's define and warrant a well-guarded version of ``square'',

    (defun$ squ (n) (declare (xargs :guard (natp n))) (* n n))

  [47mSqu[0m is guard verified.  Now let's consider the little conjecture:

    (thm (implies (warrant squ) (equal (apply$ 'SQU (list x)) (* x x))))

  Do we need need to require [47m(natp x)[0m?  We would if the logical
  definition of [47mapply$[0m checked the guard of [47mfn[0m before interpreting
  it.  But it does not check.  It just behaves as specified above.
  So, regardless of whether the guard is satisfied or not, [47m(apply$
  'squ (list x))[0m naively expands (under the warrant) to [47m(squ x)[0m, from
  which the rest of the proof follows.

  However, now let's do a top-level evaluation of this [47mapply$[0m term:

    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).

  (Remember that ACL2's evaluation theory effectively assumes all
  warrants.)  What happened?  [47mApply$[0m expanded to [47m(SQU 'NAN)[0m and that
  caused the usual guard violation, given the default configuration
  of [47m[set-guard-checking][0m.

  A similar guard violation error is signaled if a guarded [47mLAMBDA[0m
  object is [47mapply$[0med to something violating its guard.

  But now consider

    (defun$ strange (x)
      (declare (xargs :guard t))
      (apply$ 'SQU (list x)))

  This succeeds and [47mstrange[0m is now a guard verified, warranted
  function, with a guard of [47mT[0m.  This might be surprising since (a)
  the guard of [47mstrange[0m tells us nothing about [47mx[0m, (b) [47mSQU[0m is applied
  to [47mx[0m, and (c) we know the guard of [47mSQU[0m requires its argument to be
  a [47mnatp[0m.  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 [47mapply$[0m itself,
  since the appropriate information is available.  But consider a
  call of an arbitrary user-defined scion, e.g., [47m(my-scion 'SQU x)[0m.
  To what arguments will [47mmy-scion[0m [47mapply$[0m [47mSQU[0m?  And how can the
  definition of [47mmy-scion[0m 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 [47mapply$[0m applies the function symbol executes it
  checks the guard of the symbol.

  Guard verification does not ignore guards of a quoted lambda object
  being [47mapply$[0med.  Thus, for example, while [47mstrange[0m can be guard
  verified,

    (defun$ stranger (x)
      (declare (xargs :guard t))
      (apply$ (lambda$ (e) (SQU e)) (list x)))

  cannot be guard verified, because guard verification tries to verify
  the guards of every [47mlambda[0m object in a [47m:FN[0m slot so that the [47mlambda[0m
  object can be marked as guard verified in the compiled [47mlambda[0m cache
  (see [47m[print-cl-cache][0m).  But guards of [47mlambda[0m objects must be
  verified independently of the context in which they are used.  To
  be specific, even

    (defun$ stranger (x)
      (declare (xargs :guard (natp x)))
      (apply$ (lambda$ (e) (SQU e)) (list x)))

  cannot be guard verified because the [47mlambda[0m object's guards are
  verified independently of the context.  The [47mlambda[0m object must
  carry its own guard, as in

    (defun$ stranger (x)
      (declare (xargs :guard (natp x)))
      (apply$ (lambda$ (e)
                (declare (xargs :guard (natp e)))
                (SQU e))
              (list x)))

  The last definition of stranger can be guard verified, the [47mlambda[0m
  object is so marked in the cache and compiled, and if that [47mlambda[0m
  object is used in any other context it is recognized as being guard
  verified.  The guard for that [47mlambda[0m is checked when the object is
  [47mapply$[0med but if the check approves then the body of the [47mlambda[0m is
  executed as compiled code without further guard checking.

  While [47mapply$[0m is not evident in a [47m[loop$][0m statement like

    (loop$ for e in lst collect (SQU e))

  similar treatment is given.  In particular, the [47mloop$[0m above cannot be
  guard verified but

    (loop$ for e in lst collect :guard (natp e) (SQU e))

  can be and is compiled into a Common Lisp [47mloop[0m.  Recall also from the
  [47m[loop$][0m documentation that the formal semantics of the above
  statement is essentially

    (collect$ (lambda$ (e)
                (declare (xargs :guard (natp e)))
                (SQU e))
              lst)

  so guard verification of the [47mloop$[0m also compiles and marks that
  [47mlambda[0m expression as guard verified.

  So now let's return to consideration of

    (defun$ strange (x)
      (declare (xargs :guard t))
      (apply$ 'SQU (list x)))

  which we've seen is guard verified despite the fact that [47mSQU[0m expects
  a natural number and will not necessarily be given one.  What
  happens when we call [47mstrange[0m on a non-natural?

    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).

  We see that we can provoke a guard violation with [47mstrange[0m even though
  it is guard verified with a guard of [47mT[0m.  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
  [q].)

  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 [47mT[0m 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 [47mapply$[0m calls [47msqu[0m above, even when running in raw
  Lisp, it actually calls the executable counterpart of [47msqu[0m, which
  checks guards at runtime and executes properly under the ACL2
  axioms.

    ACL2 !>(set-guard-checking :none)

    Turning off guard checking entirely.

    ACL2 >(strange 'nan)
    0

  The last evaluation can be explained by the fact that ACL2
  multiplication defaults non-numbers to 0.

  We discuss the evaluation of ground [47mapply$[0m terms in the evaluation
  theory further below.

  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.


Top-Level Evaluation of Apply$

  As noted, ACL2's evaluation theory implicitly assumes all warrants
  produced by [47m[defwarrant][0m.  See [guarantees-of-the-top-level-loop].
  Since top-level evaluation in ACL2 is conducted in the evaluation
  theory, ground calls of [47mapply$[0m --- whether literally in top-level
  input to the ACL2 read-eval-print loop or hidden inside scions
  called from the top-level --- can be evaluated on quoted warranted
  function symbols and [47m[lambda$][0m expressions --- provided the
  [tame]ness restrictions are met.  This is in contrast to
  opportunities for evaluation of ground [47mapply$[0m expressions arising
  in proofs, where warrant hypotheses must be explicit.

  In this section we focus on calls of [47mapply$[0m arising in the evaluation
  theory.  We start with a discussion of the use of [47mapply$[0m with
  warranted [47m:logic[0m mode functions.  We then describe how [47mapply$[0m
  handles badged [47m:program[0m mode functions.  Note that a mere badge is
  [3mnot[0m sufficient for evaluation when using [47mapply$[0m on a [47m:logic[0m mode
  function that is not warranted; see [47m[defbadge][0m and
  [guarantees-of-the-top-level-loop] for discussion of this case.  In
  short: evaluation involving [47m:logic[0m mode functions is expected to
  respect the evaluation theory, and while [47mdefwarrant[0m extends the
  evaluation theory appropriately, [47mdefbadge[0m does not.

  Evaluation of [47mapply$[0m terms in the evaluation theory respects guards
  on quoted function symbols and [47m[lambda$][0m expressions (which is to
  say, on the quoted well-formed [47mLAMBDA[0m objects that [47m[lambda$][0m
  produces).  So consider a call of [47mapply$[0m on [47mfn[0m and [47margs[0m in the
  evaluation theory, where [47mfn[0m is a warranted function symbol or a
  well-formed (and thus tame) [47mLAMBDA[0m object.  Here's what happens.
  Except where noted, the description below applies both to warranted
  [47m:logic[0m and badged [47m:program[0m mode functions.

  [47mApply$[0m determines whether [47mfn[0m's tameness restrictions are met by [47margs[0m.
  Tameness is a syntactic property and so can be checked.  If the
  function's tameness restrictions are not met, an error is caused.

  If the tameness restrictions are met, [47mapply$[0m determines whether [47mfn[0m
  has been guard verified.  In the case of function symbols this is a
  simple lookup on the property list of [47mfn[0m.  (Of course, this check
  fails for [47m:program[0m mode functions.)  In the case of [47mLAMBDA[0m objects
  it is a cache query (see [47m[print-cl-cache][0m) and if the query reveals
  that we have not yet tried to verify the guards of this [47mLAMBDA[0m
  object, [47mapply$[0m uses tau reasoning alone (see
  [introduction-to-the-tau-system]) to try to verify the guard
  conjectures.

  [31;1mNote:[0mAn important distinction between the runtime handling of
  function symbols versus [47mLAMBDA[0m objects by [47mapply$[0m is that function
  symbols can only be guard verified by prior events, e.g., the
  introductory [47m[defun][0m or a subsequent [47mverify-guards[0m, but [47mapply$[0m
  tries to verify the guards of [47mLAMBDA[0m objects [3mon the fly[0m!  The
  reason for this distinction is that we anticipate that many [47mLAMBDA[0m
  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
  [47mLAMBDA[0m object and that [47mLAMBDA[0m object may only be seen by the
  top-level evaluator.  We discuss this further in [47m[verify-guards][0m

  If [47mfn[0m is guard verified, [47mapply$[0m next checks whether [47mfn[0m's guard holds
  of the actuals in [47margs[0m.  This is done by evaluation of the compiled
  code for the guard on [47margs[0m.

  If the guard check of [47margs[0m succeeds, a compiled version of [47mfn[0m is
  applied to [47margs[0m.  If the check fails, a guard violation is signaled
  or else the application of [47mfn[0m to [47margs[0m is interpreted under the
  definitional axioms of [47mapply$[0m and [47mev$[0m, depending on how
  [47m[set-guard-checking][0m has been configured.

  Finally, if [47mfn[0m is not guard verified, the application of [47mfn[0m to [47margs[0m
  is interpreted under the definitional axioms of [47mapply$[0m and [47mev$[0m.

  We discuss the cache that supports [47mLAMBDA[0m application in
  [47m[print-cl-cache][0m.  See also the discussion of guard verification in
  [47m[lambda$][0m.  It should be noted that a [47mLAMBDA[0m object can also be
  guard verified using the [47m[verify-guards][0m event.  This brings the
  full power of the prover to bear on the guard verification of the
  [47mLAMBDA[0m object, instead of relying just on the tau system.

  Users are accustomed to executing [47m:program[0m 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
  [47m:program[0m 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 [47m:program[0m 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 [47m:program[0m 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
  [47m:program[0m 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 [47mapply$[0m to handle [47m:program[0m mode
  functions [3mprovided they have badges[0m.  Badges are critical because
  it means that execution of the functions won't ``go outside the
  sandbox.'' However, [47mapply$[0m runs [47m:program[0m mode functions in
  [47m[safe-mode][0m to ensure the functional substitutivity of [47mapply$[0m:
  identical calls must always yield identical results.

  It may seem counterintuitive that a top-level [47mapply$[0m of a [47m:logic[0m mode
  function cannot be executed unless [47mdefwarrant[0m has succeeded but a
  top-level [47mapply$[0m of a [47m:program[0m mode function can be executed.  As
  noted earlier, the reason is simple: execution of [47m:logic[0m mode
  functions is justified by the axioms of the evaluation theory while
  no such assurances are offered for [47m:program[0m mode functions.


Logical Definitions

  In the following definitions, [47mapply$-userfn[0m is an undefined function
  that is constrained by warrants to describe the tameness
  requirement and behavior of [47mapply$[0m on specific function symbols.
  The functions [47muntame-apply$[0m and [47muntame-ev$[0m are simply undefined
  functions for giving unspecified values when untame objects are
  being used.

  [31;1mFunction: [0m<apply$>

    (defun apply$ (fn args)
      (declare (xargs :guard (apply$-guard fn args)))
      (cond ((consp fn) (apply$-lambda fn args))
            ((apply$-primp fn)
             (apply$-prim fn args))
            ((eq fn 'badge) (badge (car args)))
            ((eq fn 'tamep) (tamep (car args)))
            ((eq fn 'tamep-functionp)
             (tamep-functionp (car args)))
            ((eq fn 'suitably-tamep-listp)
             (ec-call (suitably-tamep-listp (car args)
                                            (cadr args)
                                            (caddr args))))
            ((eq fn 'apply$)
             (if (tamep-functionp (car args))
                 (ec-call (apply$ (car args) (cadr args)))
               (untame-apply$ fn args)))
            ((eq fn 'ev$)
             (if (tamep (car args))
                 (ev$ (car args) (cadr args))
               (untame-apply$ fn args)))
            (t (apply$-userfn fn args))))

  [31;1mFunction: [0m<apply$-lambda>

    (defun apply$-lambda (fn args)
      (declare (xargs :guard (apply$-lambda-guard fn args)))
      (apply$-lambda-logical fn args))

  [31;1mMacro: [0m<apply$-lambda-logical>

    (defmacro apply$-lambda-logical (fn args)
     (declare (xargs :guard (symbolp fn)))
     (cons
        'ev$
        (cons (cons 'lambda-object-body
                    (cons fn 'nil))
              (cons (cons 'ec-call
                          (cons (cons 'pairlis$
                                      (cons (cons 'lambda-object-formals
                                                  (cons fn 'nil))
                                            (cons args 'nil)))
                                'nil))
                    'nil))))

  [31;1mFunction: [0m<ev$>

    (defun ev$ (x a)
      (declare (xargs :guard t))
      (cond ((not (tamep x)) (untame-ev$ x a))
            ((variablep x)
             (ec-call (cdr (ec-call (assoc-equal x a)))))
            ((fquotep x) (cadr x))
            ((eq (car x) 'if)
             (if (ev$ (cadr x) a)
                 (ev$ (caddr x) a)
               (ev$ (cadddr x) a)))
            ((eq (car x) 'apply$)
             (apply$ 'apply$
                     (list (cadr (cadr x))
                           (ev$ (caddr x) a))))
            ((eq (car x) 'ev$)
             (apply$ 'ev$
                     (list (cadr (cadr x))
                           (ev$ (caddr x) a))))
            (t (apply$ (car x) (ev$-list (cdr x) a)))))

  [31;1mFunction: [0m<ev$-list>

    (defun ev$-list (x a)
      (declare (xargs :guard t))
      (cond ((atom x) nil)
            (t (cons (ev$ (car x) a)
                     (ev$-list (cdr x) a)))))

  [31;1mFunction: [0m<apply$-guard>

    (defun apply$-guard (fn args)
      (declare (xargs :guard t))
      (if (atom fn)
          (true-listp args)
        (apply$-lambda-guard fn args)))

  [31;1mFunction: [0m<apply$-lambda-guard>

    (defun apply$-lambda-guard (fn args)
      (declare (xargs :guard t))
      (and (consp fn)
           (consp (cdr fn))
           (true-listp args)
           (equal (len (cadr fn)) (length args))))


Subtopics

  [Apply$-guard]
      The guard on [47mapply$[0m

  [Apply$-lambda]
      Used by [47mapply$[0m on [47mLAMBDA[0m objects

  [Apply$-lambda-guard]
      The guard on [47mapply$-lambda[0m

  [Apply$-userfn]
      Undefined function used by [47mapply$[0m on non-primitives

  [Badge]
      Syntactic requirements on a function symbol to be used by [47mapply$[0m

  [Badge-userfn]
      Undefined function used by [47mbadge[0m on non-primitives

  [Defbadge]
      Issue a badge for a function so [47m[apply$][0m can evaluate with it

  [Defun$]
      Define a function symbol and generate a warrant

  [Defwarrant]
      Issue a warrant for a function so [47m[apply$][0m can use it in proofs

  [Ev$]
      Evaluate a tame expression using [47mapply$[0m

  [Explain-giant-lambda-object]
      print data related to a large lambda object

  [Fn-equal]
      Equivalence relation on tame functions

  [Gratuitous-lambda-object-restrictions]
      Enforcement of logically unnecessary restrictions on [47m:FN[0m slots

  [Ilk]
      Indicator of how an argument is used

  [Introduction-to-apply$]
      Background knowledge on how to use [47m[apply$][0m, [47m[defwarrant][0m, etc.

  [L<]
      Ordering on naturals or lists of naturals

  [Lambda]
      Lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions

  [Lambda$]
      Lambda object constructor for use with [47mapply$[0m

  [Mixed-mode-functions]
      [47m:[0m[47m[logic][0m mode functions can [47m[apply$][0m [47m:[0m[47m[program][0m mode functions

  [Print-cl-cache]
      Information about the cache supporting [47mapply$[0m

  [Rewriting-calls-of-apply$-ev$-and-loop$-scions]
      How the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m terms

  [Scion]
      A function ancestrally dependent on [47mapply$[0m

  [Tame]
      Definitions of the various notions of tameness

  [Translam]
      Print the translation of a lambda$ expression

  [Warrant]
      Giving [47m[apply$][0m permission to handle a user-defined function in
      proofs

  [Well-formed-lambda-objectp]
      Predicate for recognizing well-formed [47mLAMBDA[0m objects")
 (APPLY$-GUARD
  (APPLY$)
  "The guard on [47mapply$[0m

  The guard on [47m(apply$ fn lst)[0m is [47m(apply$-guard fn lst)[0m which is
  extraordinarily weak.

  [31;1mFunction: [0m<apply$-guard>

    (defun apply$-guard (fn args)
      (declare (xargs :guard t))
      (if (atom fn)
          (true-listp args)
        (apply$-lambda-guard fn args)))

  where

  [31;1mFunction: [0m<apply$-lambda-guard>

    (defun apply$-lambda-guard (fn args)
      (declare (xargs :guard t))
      (and (consp fn)
           (consp (cdr fn))
           (true-listp args)
           (equal (len (cadr fn)) (length args))))

  This guard is just strong enough to allow the definitions of the
  functions in the [47mapply$[0m clique to be guard verified.  It does not
  guarantee that [47mfn[0m is tame or well-formed or that [47margs[0m satisfy the
  guard of [47mfn[0m.  The last condition is in fact impossible to state
  given the untyped nature of ACL2.  Thus, [47m(apply$ fn args)[0m has to
  check tameness, well-formedness, guard verified, and that [47mfn[0m's
  guard is satisfied by [47margs[0m when the [47mapply$[0m is executed in the
  evaluation theory.

  The issue of guards and guard verification of definitions involving
  [47mapply$[0m is further discussed in [47m[apply$][0m and in [47m[verify-guards][0m.")
 (APPLY$-LAMBDA
  (APPLY$)
  "Used by [47mapply$[0m on [47mLAMBDA[0m objects

  When [47mapply$[0m is given a [47mconsp[0m object as its first argument it treats
  it as a [47mLAMBDA[0m expression and calls this function to apply it.
  This function evaluates the body of the object with [47mev$[0m under an
  alist binding the formals of the object to the actuals.  See
  [47m[apply$][0m for details.")
 (APPLY$-LAMBDA-GUARD
  (APPLY$)
  "The guard on [47mapply$-lambda[0m

  The guard on [47m(apply$-lambda fn lst)[0m is [47m(apply$-lambda-guard fn lst)[0m
  which is extraordinarily weak.

  [31;1mFunction: [0m<apply$-lambda-guard>

    (defun apply$-lambda-guard (fn args)
      (declare (xargs :guard t))
      (and (consp fn)
           (consp (cdr fn))
           (true-listp args)
           (equal (len (cadr fn)) (length args))))

  This guard is just strong enough to allow the definitions of the
  functions in the [47mapply$[0m clique to be guard verified.  It does not
  guarantee that [47mfn[0m is [47mtame[0m or well-formed or that [47margs[0m satisfy the
  guard of [47mfn[0m.  The last condition is in fact impossible to state
  given the untyped nature of ACL2.  Thus, [47m(apply$ fn args)[0m has to
  check tameness, well-formedness, guard verified and that [47mfn[0m's guard
  is satisfied by [47margs[0m when the [47mapply$[0m is executed in the evaluation
  theory.

  The issue of guards and guard verification of definitions involving
  [47mapply$[0m is further discussed in [47m[apply$][0m and in [47m[verify-guards][0m.")
 (APPLY$-USERFN
  (APPLY$)
  "Undefined function used by [47mapply$[0m on non-primitives

  When [47mapply$[0m 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 [47mfn[0m is specified, if at
  all, by the [47m[warrant][0m for [47mfn[0m which must be available as a
  hypothesis in the formula being proved.  In the evaluation theory,
  [47mapply$-userfn[0m has an attachment that makes it behave as though all
  warrants are assumed.  See [47m[apply$][0m for details.")
 (APROPOS (POINTERS)
          "See [finding-documentation].")
 (ARCHITECTURE-OF-THE-PROVER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A simple overview of how the prover works

  Six built-in proof techniques are used by ACL2 to decompose the goal
  formula into subgoals.

    * [3msimplification[0m --- 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.

    * [3mdestructor elimination[0m --- getting rid of ``destructor terms'' like
      [47m(CAR X)[0m and [47m(CDR X)[0m by replacing a variable, e.g., [47mX[0m, by a
      ``constructor'' term, e.g., [47m(CONS A B)[0m.  But you can tell ACL2
      about new destructor/constructor combinations.

    * [3mfertilization[0m --- 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 [3mcross-fertilization[0m 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 [47m:do-not
      '(generalize)[0m, only full fertilization is applied.

    * [3mgeneralization[0m --- 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.

    * [3melimination of irrelevance[0m --- throwing away unnecessary hypotheses.
      This is a heuristic that prepares the goal for another
      induction.

    * [3minduction[0m --- 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.

  But you can add additional techniques, called [3mclause processors[0m.

  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 [3mapply[0m 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 [3mk[0m subgoals.

  The last outcome has a special case: if [3mk[0m is 0 then the technique
  proved the goal.  Whenever [3mk[0m is non-0, the process starts over
  again with simplification on each of the [3mk[0m 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.

  It runs until you or one of the proof techniques aborts the proof
  attempt or until all subgoals have been proved.

  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 [3mstable under simplification[0m.

  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.

  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
  [introduction-to-the-theorem-prover].

  The output of an unsuccessful proof attempt concludes with some [3mkey[0m
  [3mcheckpoints[0m which usually bear looking at.

  For more information about how ACL2 orchestrates its proof
  techniques, see [hints-and-the-waterfall].")
 (AREF1
  (ARRAYS ACL2-BUILT-INS)
  "Access the elements of a 1-dimensional array

    Example Form:
    (aref1 'delta1 a (+ i k))

    General Form:
    (aref1 name alist index)

  where [47mname[0m is a symbol, [47malist[0m is a 1-dimensional array and [47mindex[0m is a
  legal index into [47malist[0m.  This function returns the value associated
  with [47mindex[0m in [47malist[0m, or else the default value of the array.  See
  [arrays] for details.

  This function executes in virtually constant time if [47malist[0m is in fact
  the ``semantic value'' associated with [47mname[0m (see [arrays]).  When
  it is not, [47maref1[0m must do a linear search through [47malist[0m.  In that
  case the correct answer is returned but a [31;1mslow array[0m comment is
  printed to the comment window.  See [slow-array-warning].

  [31;1mFunction: [0m<aref1>

    (defun aref1 (name l n)
      (declare (xargs :guard (and (array1p name l)
                                  (integerp n)
                                  (>= n 0)
                                  (< n (car (dimensions name l))))))
      (let ((x (and (not (eq n :header)) (assoc n l))))
        (cond ((null x) (default name l))
              (t (cdr x)))))")
 (AREF2
  (ARRAYS ACL2-BUILT-INS)
  "Access the elements of a 2-dimensional array

    Example Form:
    (aref2 'delta1 a i j)

    General Form:
    (aref2 name alist i j)

  where [47mname[0m is a symbol, [47malist[0m is a 2-dimensional array and [47mi[0m and [47mj[0m
  are legal indices into [47malist[0m.  This function returns the value
  associated with [47m(i . j)[0m in [47malist[0m, or else the default value of the
  array.  See [arrays] for details.

  This function executes in virtually constant time if [47malist[0m is in fact
  the ``semantic value'' associated with [47mname[0m (see [arrays]).  When
  it is not, [47maref2[0m must do a linear search through [47malist[0m.  In that
  case the correct answer is returned but a [31;1mslow array[0m comment is
  printed to the comment window.  See [slow-array-warning].

  [31;1mFunction: [0m<aref2>

    (defun aref2 (name l i j)
      (declare (xargs :guard (and (array2p name l)
                                  (integerp i)
                                  (>= i 0)
                                  (< i (car (dimensions name l)))
                                  (integerp j)
                                  (>= j 0)
                                  (< j (cadr (dimensions name l))))))
      (let ((x (assoc2 i j l)))
        (cond ((null x) (default name l))
              (t (cdr x)))))")
 (ARGLISTP (POINTERS)
           "See [system-utilities].")
 (ARGS
  (DOCUMENTATION)
  "[47margs[0m, [47m[guard][0m, [47mtype[0m, [47m[constraint][0m, etc., of a function symbol

    Example:
    :args assoc-eq

  [47mArgs[0m 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 [guard] expression, the output
  [signature], the deduced type, the [constraint] (if any), and its
  [47m[badge][0m and [47m[warrant][0m, if any.")
 (ARITIES-OKP
  (ACL2-BUILT-INS)
  "check the arities of given function symbols

    Example:
    (arities-okp '((IF . 3) (CAR . 1) (CONS . 2)) (w state))

    General Form:
    (arities-okp alist w)

  where [47malist[0m is a [47m[symbol-alistp][0m and [47mw[0m is an ACL2 logical [world].
  The alist is presumed to pair [47m:[0m[47m[logic][0m-mode function symbols with
  arities.  The result is [47mt[0m or [47mnil[0m according to whether each symbol
  in the alist is a [47m:logic[0m-mode function symbol with the associated
  arity as its [47m[arity][0m in [47mw[0m.  See [well-formedness-guarantee].

  [31;1mFunction: [0m<arities-okp>

    (defun arities-okp (user-table w)
      (declare (xargs :guard (and (symbol-alistp user-table)
                                  (plist-worldp-with-formals w))))
      (cond ((endp user-table) t)
            (t (and (equal (arity (car (car user-table)) w)
                           (cdr (car user-table)))
                    (logicp (car (car user-table)) w)
                    (arities-okp (cdr user-table) w)))))")
 (ARITY
  (ACL2-BUILT-INS)
  "number of arguments of a function symbol

    Examples:
    (arity 'IF (w state))
    (arity '(LAMBDA (X) (CONS X X)) (w state))

    General Form:
    (arity fn w)

  where [47mfn[0m is a function symbol or a lambda expression and [47mw[0m is an ACL2
  logical [world].  The result is the number of arguments the
  function or lambda expression takes, or [47mnil[0m if the function symbol
  is not defined in [47mw[0m.

See [arity+] for a variant of [47marity[0m with a stronger [guard].")
 (ARRAY (POINTERS) "See [arrays].")
 (ARRAY1P
  (ARRAYS ACL2-BUILT-INS)
  "Recognize a 1-dimensional array

    Example Form:
    (array1p 'delta1 a)

    General Form:
    (array1p name alist)

  where [47mname[0m and [47malist[0m are arbitrary objects.  This function returns [47mt[0m
  if [47malist[0m is a 1-dimensional ACL2 array.  Otherwise it returns [47mnil[0m.
  The function operates in constant time if [47malist[0m is the semantic
  value of [47mname[0m.  See [arrays].

  [31;1mFunction: [0m<array1p>

    (defun array1p (name l)
     (declare (xargs :guard t))
     (and
      (symbolp name)
      (alistp l)
      (let ((header-keyword-list (cdr (assoc-eq :header l))))
       (and
        (keyword-value-listp header-keyword-list)
        (let
         ((dimensions
               (cadr (assoc-keyword :dimensions header-keyword-list)))
          (maximum-length
            (cadr (assoc-keyword :maximum-length header-keyword-list))))
         (and (true-listp dimensions)
              (equal (length dimensions) 1)
              (integerp (car dimensions))
              (integerp maximum-length)
              (< 0 (car dimensions))
              (< (car dimensions) maximum-length)
              (<= maximum-length
                  (array-maximum-length-bound))
              (bounded-integer-alistp l (car dimensions))))))))")
 (ARRAY2P
  (ARRAYS ACL2-BUILT-INS)
  "Recognize a 2-dimensional array

    Example Form:
    (array2p 'delta1 a)

    General Form:
    (array2p name alist)

  where [47mname[0m and [47malist[0m are arbitrary objects.  This function returns [47mt[0m
  if [47malist[0m is a 2-dimensional ACL2 array.  Otherwise it returns [47mnil[0m.
  The function operates in constant time if [47malist[0m is the semantic
  value of [47mname[0m.  See [arrays].

  [31;1mFunction: [0m<array2p>

    (defun array2p (name l)
     (declare (xargs :guard t))
     (and
      (symbolp name)
      (alistp l)
      (let ((header-keyword-list (cdr (assoc-eq :header l))))
       (and
        (keyword-value-listp header-keyword-list)
        (let
         ((dimensions
               (cadr (assoc-keyword :dimensions header-keyword-list)))
          (maximum-length
            (cadr (assoc-keyword :maximum-length header-keyword-list))))
         (and (true-listp dimensions)
              (equal (length dimensions) 2)
              (let ((d1 (car dimensions))
                    (d2 (cadr dimensions)))
                (and (integerp d1)
                     (integerp d2)
                     (integerp maximum-length)
                     (< 0 d1)
                     (< 0 d2)
                     (< (* d1 d2) maximum-length)
                     (<= maximum-length
                         (array-maximum-length-bound))
                     (bounded-integer-alistp2 l d1 d2)))))))))")
 (ARRAYS
  (PROGRAMMING)
  "ACL2 arrays and operations on them

  Below we begin a detailed presentation of ACL2 arrays.  ACL2's
  single-threaded objects (see [stobj]) provide a similar
  functionality that is generally more efficient when there are
  updates (writes), but is also more restrictive.

  See [arrays-example] for a brief introduction illustrating the use of
  ACL2 arrays.

  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.

  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.


The Logical Description of ACL2 Arrays

  An ACL2 1-dimensional array is an object that associates arbitrary
  objects with certain integers, called ``indices.'' Every array has
  a dimension, [47mdim[0m, which is a positive integer.  The indices of an
  array are the consecutive integers from [47m0[0m through [47mdim-1[0m.  To obtain
  the object associated with the index [47mi[0m in an array [47ma[0m, one uses
  [47m(aref1 name a i)[0m.  [47mName[0m is a symbol that is irrelevant to the
  semantics of [47m[aref1][0m 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 [47ma[0m but which associates [47mval[0m with index [47mi[0m,
  one uses [47m(aset1 name a i val)[0m.

  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 [47m[list][0m and [47m[cons][0m.
  However, there is a special ACL2 function, called [47m[compress1][0m, for
  speeding up access to the elements of such an alist.  We discuss
  [47m[compress1][0m later.

  One element of the alist must be the ``header'' of the array.  The
  [header] of a 1-dimensional array with dimension [47mdim[0m is of the
  form:

    (:HEADER :DIMENSIONS (dim)
             :MAXIMUM-LENGTH max
             :DEFAULT obj ; optional
             :NAME name   ; optional
             :ORDER order ; optional values are < (the default), >, or :none/nil
             ).

  [47mObj[0m may be any object and is called the ``default value'' of the
  array.  [47m[Max][0m must be an integer greater than [47mdim[0m.  [47mName[0m must be a
  symbol.  The [47m:[0m[47m[default][0m and [47m:name[0m entries are optional; if
  [47m:[0m[47m[default][0m is omitted, the default value is [47mnil[0m.  The function
  [47m[header][0m, when given a name and a 1- or 2-dimensional array,
  returns the [header] of the array.  The functions [47m[dimensions][0m,
  [47m[maximum-length][0m, and [47m[default][0m are similar and return the
  corresponding fields of the [header] of the array.  The role of the
  [47m:[0m[47m[dimensions][0m field is obvious: it specifies the legal indices into
  the array.  The roles played by the [47m:[0m[47m[maximum-length][0m and
  [47m:[0m[47m[default][0m fields are described below.

  Aside from the [header], the other elements of the alist must each be
  of the form [47m(i . val)[0m, where [47mi[0m is an integer and [47m0 <= i < dim[0m, and
  [47mval[0m is an arbitrary object.

  The [47m:order[0m field of the header is ignored for 2-dimensional arrays.
  For 1-dimensional arrays, it specifies the order of keys ([47mi[0m, above)
  when the array is compressed as with [47m[compress1][0m, as described
  below.  An [47m:order[0m of [47m:none[0m or [47mnil[0m specifies no reordering of the
  alist by [47m[compress1][0m, and an order of [47m>[0m specifies reordering by
  [47m[compress1][0m so that keys are in descending order.  Otherwise, the
  alist is reordered by [47m[compress1][0m so that keys are in ascending
  order.

  [47m(Aref1 name a i)[0m is [guard]ed so that [47mname[0m must be a symbol, [47ma[0m must
  be an array and [47mi[0m must be an index into [47ma[0m.  The value of [47m(aref1
  name a i)[0m is either [47m(cdr (assoc i a))[0m or else is the default value
  of [47ma[0m, depending on whether there is a pair in [47ma[0m whose [47m[car][0m is [47mi[0m.
  Note that [47mname[0m is irrelevant to the value of an [47m[aref1][0m expression.
  You might [47m:pe aref1[0m to see how simple the definition is.

  [47m(Aset1 name a i val)[0m is [guard]ed analogously to the [47m[aref1][0m
  expression.  The value of the [47m[aset1][0m expression is essentially
  [47m(cons (cons i val) a)[0m.  Again, [47mname[0m is irrelevant.  Note [47m(aset1
  name a i val)[0m is an array, [47ma'[0m, with the property that [47m(aref1 name
  a' i)[0m is [47mval[0m and, except for index [47mi[0m, all other indices into [47ma'[0m
  produce the same value as in [47ma[0m.  Note also that if [47ma[0m is viewed as
  an alist (which it is) the pair ``binding'' [47mi[0m to its old value is
  in [47ma'[0m but ``covered up'' by the new pair.  Thus, the length of an
  array grows by one when [47m[aset1][0m is done.

  Because [47m[aset1][0m covers old values with new ones, an array produced by
  a sequence of [47m[aset1][0m calls may have many irrelevant pairs in it.
  The function [47m[compress1][0m can remove these irrelevant pairs.  Thus,
  [47m(compress1 name a)[0m returns an array that is equivalent (vis-a-vis
  [47m[aref1][0m) to [47ma[0m but which may be shorter.  For technical reasons, the
  alist returned by [47m[compress1][0m may also list the pairs in a
  different order than listed in [47ma[0m.

  To prevent arrays from growing excessively long due to repeated
  [47m[aset1][0m operations, [47m[aset1][0m essentially calls [47m[compress1][0m on the
  new alist whenever the length of the new alist exceeds the
  [47m:[0m[47m[maximum-length][0m entry, [47m[max][0m, in the [header] of the array.  See
  the definition of [47m[aset1][0m (for example by using [47m:[0m[47m[pe][0m).  This is
  primarily just a mechanism for freeing up [47m[cons][0m space consumed
  while doing [47m[aset1][0m operations.  Note however that this [47m[compress1][0m
  call is replaced by a hard error if the header specifies an [47m:order[0m
  of [47m:none[0m or [47mnil[0m.

  This completes the logical description of 1-dimensional arrays.
  2-dimensional arrays are analogous.  The [47m:[0m[47m[dimensions][0m entry of the
  [header] of a 2-dimensional array should be [47m(dim1 dim2)[0m.  A pair of
  indices, [47mi[0m and [47mj[0m, is legal iff [47m0 <= i < dim1[0m and [47m0 <= j < dim2[0m.
  The [47m:[0m[47m[maximum-length][0m must be greater than [47mdim1*dim2[0m.  [47m[Aref2][0m,
  [47m[aset2][0m, and [47m[compress2][0m are like their counterparts but take an
  additional [47mindex[0m argument.  Finally, the pairs in a 2-dimensional
  array are of the form [47m((i . j) . val)[0m.


The Implementation of ACL2 Arrays

  Very informally speaking, the function [47m[compress1][0m ``creates'' an
  ACL2 array that provides fast access, while the function [47m[aref1][0m
  ``maintains'' fast access.  We now describe this informal idea more
  carefully.

  [47m[Aref1][0m is essentially [47m[assoc][0m.  If [47m[aref1][0m 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 [47m[aset1][0m calls done to create the array from the initial
  alist).  This is intolerable; arrays are ``supposed'' to provide
  constant-time access and change.

  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.''

  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.

  When [47m(compress1 name alist)[0m builds a new alist, [47ma'[0m, it sets the
  semantic value of [47mname[0m to that new alist.  Furthermore, it writes
  into a Common Lisp array all of the index/value pairs of [47ma'[0m,
  initializing unassigned indices with the default value.  In general
  this is a new array, which becomes the raw lisp array of [47mname[0m.
  However, if a raw lisp array is already associated with [47mname[0m and is
  at least as long as the dimension specified in the [header], then
  that array is reused and all indices out of range are ignored.
  (Such reuse can be avoided; see [flush-compress] for how to remove
  the existing association of a raw lisp array with a name.)  Either
  way, [47m[compress1][0m then returns [47ma'[0m, the semantic value, as its
  result, as required by the definition of [47m[compress1][0m.

  When [47m(aref1 name a i)[0m is invoked, [47m[aref1][0m first determines whether
  the semantic value of [47mname[0m is [47ma[0m (i.e., is [47m[eq][0m to the alist [47ma[0m).  If
  so, [47m[aref1][0m can determine the [47mi[0mth element of [47ma[0m by invoking Common
  Lisp's [47maref[0m function on the raw lisp array associated with name.
  Note that no linear search of the alist [47ma[0m is required; the
  operation is done in constant time and involves retrieval of two
  global variables, an [47m[eq][0m test and [47mjump[0m, 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 [47mname[0m has
  no semantic value or if it is different from [47ma[0m, then [47m[aref1][0m
  determines the answer by linear search of [47ma[0m as suggested by the
  [47massoc-like[0m definition of [47m[aref1][0m.  Thus, [47m[aref1][0m 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
  [47m[aset1][0m.

  When [47m(aset1 name a i val)[0m is invoked, [47m[aset1][0m does two [47m[cons][0mes to
  create the new array.  Call that array [47ma'[0m.  It will be returned as
  the answer.  (In this discussion we ignore the case in which
  [47m[aset1][0m does a [47m[compress1][0m.)  However, before returning, [47m[aset1][0m
  determines if [47mname[0m's semantic value is [47ma[0m.  If so, it makes the new
  semantic value of [47mname[0m be [47ma'[0m and it smashes the raw lisp array of
  [47mname[0m with [47mval[0m at index [47mi[0m, before returning [47ma'[0m as the result.  Thus,
  after doing an [47m[aset1][0m and obtaining a new semantic value [47ma'[0m, all
  [47m[aref1][0ms on that new array will be fast.  Any [47m[aref1][0ms on the old
  semantic value, [47ma[0m, will be slow.

  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 [47m(aref1 name a i)[0m, is ``fast''
  (constant-time) if the alist supplied, [47ma[0m, is the value returned by
  the most recently executed [47m[compress1][0m or [47m[aset1][0m on the name
  supplied.  In the functional expression of ``conventional'' array
  processing, all uses of an array are fast.

  The [47m:name[0m field of the [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
  [47m:name[0m and its primary value is that it allows the user, by
  inspecting the semantic value of the array --- the alist --- 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 [header] or that all [47maset[0ms
  used that name.  Such enforcement would be inefficient.


Some Programming Examples

  In the following examples we will use ACL2 ``global variables'' to
  hold several arrays.  See [@], and see [assign].

  Let the [47m[state][0m global variable [47ma[0m be the 1-dimensional compressed
  array of dimension [47m5[0m constructed below.

    ACL2 !>(assign a (compress1 'demo
                                '((:header :dimensions (5)
                                           :maximum-length 15
                                           :default uninitialized
                                           :name demo)
                                  (0 . zero))))

  Then [47m(aref1 'demo (@ a) 0)[0m is [47mzero[0m and [47m(aref1 'demo (@ a) 1)[0m is
  [47muninitialized[0m.

  Now execute

    ACL2 !>(assign b (aset1 'demo (@ a) 1 'one))

  Then [47m(aref1 'demo (@ b) 0)[0m is [47mzero[0m and [47m(aref1 'demo (@ b) 1)[0m is [47mone[0m.

  All of the [47m[aref1][0ms done so far have been ``fast.''

  Note that we now have two array objects, one in the global variable [47ma[0m
  and one in the global variable [47mb[0m.  [47mB[0m was obtained by assigning to
  [47ma[0m.  That assignment does not affect the alist [47ma[0m because this is an
  applicative language.  Thus, [47m(aref1 'demo (@ a) 1)[0m must [31;1mstill[0m be
  [47muninitialized[0m.  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 [47mdemo[0m is the array
  we are calling [47mb[0m.  To access the elements of [47ma[0m, [47m[aref1][0m must now do
  a linear search.  Any reference to [47ma[0m 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 [47mb[0m.

  Now let us define a function that counts how many times a given
  object, [47mx[0m, occurs in an array.  For simplicity, we will pass in the
  name and highest index of the array:

    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))))

  To determine how many times [47mzero[0m appears in [47m(@ b)[0m we can execute:

    ACL2 !>(cnt 'demo (@ b) 4 'zero)

  The answer is [47m1[0m.  How many times does [47muninitialized[0m appear in [47m(@ b)[0m?

    ACL2 !>(cnt 'demo (@ b) 4 'uninitialized)

  The answer is [47m3[0m, because positions [47m2[0m, [47m3[0m and [47m4[0m of the array contain
  that default value.

  Now imagine that we want to assign [47m'two[0m to index [47m2[0m and then count how
  many times the 2nd element of the array occurs in the array.  This
  specification is actually ambiguous.  In assigning to [47mb[0m we produce
  a new array, which we might call [47mc[0m.  Do we mean to count the
  occurrences in [47mc[0m of the 2nd element of [47mb[0m or the 2nd element of [47mc[0m?
  That is, do we count the occurrences of [47muninitialized[0m or the
  occurrences of [47mtwo[0m?  If we mean the former the correct answer is [47m2[0m
  (positions [47m3[0m and [47m4[0m are [47muninitialized[0m in [47mc[0m); if we mean the latter,
  the correct answer is [47m1[0m (there is only one occurrence of [47mtwo[0m in [47mc[0m).

  Below are ACL2 renderings of the two meanings, which we call [47m[former][0m
  and [47m[latter][0m.  (Warning: Our description of these examples, and of
  an example [47m[fast former][0m 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.)

    (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)))

  Note that in [47m[former][0m we create [47mc[0m in the second argument of the call
  to [47mcnt[0m (although we do not give it a name) and then refer to [47mb[0m in
  the fourth argument.  This is unconventional because the second
  reference to [47mb[0m in [47m[former][0m is no longer the semantic value of [47mdemo[0m.
  While ACL2 computes the correct answer, namely [47m2[0m, the execution of
  the [47m[aref1][0m expression in [47m[former][0m is done slowly.

  A conventional rendering with the same meaning is

    (let ((x (aref1 'demo (@ b) 2)))                           ; [fast former]
      (cnt 'demo (aset1 'demo (@ b) 2 'two) 4 x))

  which fetches the 2nd element of [47mb[0m before creating [47mc[0m by assignment.
  It is important to understand that [47m[former][0m and [47m[fast former][0m mean
  exactly the same thing: both count the number of occurrences of
  [47muninitialized[0m in [47mc[0m.  Both are legal ACL2 and both compute the same
  answer, [47m2[0m.  Indeed, we can symbolically transform [47m[fast former][0m
  into [47m[former][0m merely by substituting the binding of [47mx[0m for [47mx[0m in the
  body of the [47m[let][0m.  But [47m[fast former][0m can be evaluated faster than
  [47m[former][0m because all of the references to [47mdemo[0m use the then-current
  semantic value of [47mdemo[0m, which is [47mb[0m in the first line and [47mc[0m
  throughout the execution of the [47mcnt[0m in the second line.  [47m[Fast
  former][0m 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 [47m[fast former][0m because there
  is no way to refer to the 2nd element of the old value of [47mb[0m after
  smashing [47mb[0m unless it had been saved first.

  We turn now to [47m[latter][0m.  It is both clear and efficient.  It creates
  [47mc[0m by assignment to [47mb[0m and then it fetches the 2nd element of [47mc[0m, [47mtwo[0m,
  and proceeds to count the number of occurrences in [47mc[0m.  The answer
  is [47m1[0m.  [47m[Latter][0m is a good example of typical ACL2 array
  manipulation: after the assignment to [47mb[0m that creates [47mc[0m, [47mc[0m is used
  throughout.

  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 [47mb[0m as a ``global variable'':

    (cnt 'demo (aset 'demo b 2 'two) 4 (aref 'demo b 2))

  which sort of resembles [47m[former][0m but actually has the semantics of
  [47m[latter][0m because the [47mb[0m from which [47maref[0m fetches the 2nd element is
  not the same [47mb[0m used in the [47maset[0m!  The array [47mb[0m is destroyed by the
  [47maset[0m and [47mb[0m henceforth refers to the array produced by the [47maset[0m, as
  written more clearly in [47m[latter][0m.

  A Word of Warning: Users must exercise care when experimenting with
  [47m[former][0m, [47m[latter][0m and [47m[fast former][0m.  Suppose you have just
  created [47mb[0m with the assignment shown above,

    ACL2 !>(assign b (aset1 'demo (@ a) 1 'one))

  If you then evaluate [47m[former][0m in ACL2 it will complain that the
  [47m[aref1][0m is slow and compute the answer, as discussed.  Then suppose
  you evaluate [47m[latter][0m in ACL2.  From our discussion you might
  expect it to execute fast --- i.e., issue no complaint.  But in
  fact you will find that it complains repeatedly.  The problem is
  that the evaluation of [47m[former][0m changed the semantic value of [47mdemo[0m
  so that it is no longer [47mb[0m.  To try the experiment correctly you
  must make [47mb[0m be the semantic value of [47mdemo[0m again before the next
  example is evaluated.  One way to do that is to execute

    ACL2 !>(assign b (compress1 'demo (@ b)))

  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.

  This last assignment also illustrates a very common use of
  [47m[compress1][0m.  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.

  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 [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 [47m[compress1][0m, thereby gaining
  constant time access to it.

  ACL2's theorem prover uses this technique in connection with its
  implementation of the notion of whether a [rune] is [disable]d or
  not.  Associated with every [rune] is a unique integer [47mindex[0m,
  called its ``nume.'' When each rule is stored, the corresponding
  nume is stored as a component of the rule.  [Theories] are lists of
  [rune]s and membership in the ``current theory'' indicates that the
  corresponding rule is [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 [rune]s in the current theory into an
  alist that pairs the corresponding numes with [47mt[0m.  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 [enable]d.  The array is never modified during
  the proof, i.e., [47m[aset1][0m 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 [47m[assoc][0m
  after going to the trouble of mapping from a list of [rune]s to an
  alist of numes.  But because the alist of numes is an array, the
  ``apparently linear-time [47m[assoc][0m'' is more apparent than real; the
  operation is constant-time.


Subtopics

  [Aref1]
      Access the elements of a 1-dimensional array

  [Aref2]
      Access the elements of a 2-dimensional array

  [Array1p]
      Recognize a 1-dimensional array

  [Array2p]
      Recognize a 2-dimensional array

  [Arrays-example]
      An example illustrating ACL2 arrays

  [Aset1]
      Set the elements of a 1-dimensional array

  [Aset1-trusted]
      Set the elements of a 1-dimensional array without [invariant-risk]

  [Aset2]
      Set the elements of a 2-dimensional array

  [Compress1]
      Remove irrelevant pairs from a 1-dimensional array

  [Compress2]
      Remove irrelevant pairs from a 2-dimensional array

  [Default]
      Return the [47m:default[0m from the [header] of a 1- or 2-dimensional array

  [Dimensions]
      Return the [47m:dimensions[0m from the [header] of a 1- or 2-dimensional
      array

  [Flush-compress]
      Flush the under-the-hood array for the given name

  [Header]
      Return the header of a 1- or 2-dimensional array

  [Maximum-length]
      Return the [47m:maximum-length[0m from the [header] of an array

  [Maybe-flush-and-compress1]
      Compress a one-dimensional array only if necessary

  [Slow-array-warning]
      A warning or error issued when [arrays] are used inefficiently")
 (ARRAYS-EXAMPLE
  (ARRAYS)
  "An example illustrating ACL2 arrays

  The example below illustrates the use of ACL2 arrays.  It is not, of
  course, a substitute for the detailed explanations provided
  elsewhere (see [arrays], including subtopics).

    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 !>")
 (ASET1
  (ARRAYS ACL2-BUILT-INS)
  "Set the elements of a 1-dimensional array

    Example Form:
    (aset1 'delta1 a (+ i k) 27)

    General Form:
    (aset1 name alist index val)

  where [47mname[0m is a symbol, [47malist[0m is a 1-dimensional array named [47mname[0m,
  [47mindex[0m is a legal index into [47malist[0m, and [47mval[0m is an arbitrary object.
  See [arrays] for details.  Roughly speaking this function
  ``modifies'' [47malist[0m so that the value associated with [47mindex[0m is [47mval[0m.
  More precisely, it returns a new array, [47malist'[0m, of the same name
  and dimension as [47malist[0m that, under [47m[aref1][0m, is everywhere equal to
  [47malist[0m except at [47mindex[0m where the result is [47mval[0m.  That is, [47m(aref1
  name alist' i)[0m is [47m(aref1 name alist i)[0m for all legal indices [47mi[0m
  except [47mindex[0m, where [47m(aref1 name alist' i)[0m is [47mval[0m.

  In order to ``modify'' [47malist[0m, [47maset1[0m [47m[cons][0mes a new pair onto the
  front.  If the length of the resulting alist exceeds the
  [47m:[0m[47m[maximum-length][0m entry in the array [header], [47maset1[0m compresses the
  array as with [47m[compress1][0m.

  It is generally expected that the ``semantic value'' of [47mname[0m will be
  [47malist[0m (see [arrays]).  This function operates in virtually constant
  time whether this condition is true or not (unless the [47m[compress1][0m
  operation is required).  But the value returned by this function
  cannot be used efficiently by subsequent [47maset1[0m operations unless
  [47malist[0m is the semantic value of [47mname[0m when [47maset1[0m is executed.  Thus,
  if the condition is not true, [47maset1[0m prints a [31;1mslow array[0m warning to
  the comment window.  See [slow-array-warning].

  Note that [47m[aset1][0m is marked as having [47m[invariant-risk][0m, which can
  affect the execution of [47m:[0m[47m[program][0m-mode functions.  To get around
  this problem (but only with great care!), see [aset1-trusted].

  [31;1mFunction: [0m<aset1>

    (defun aset1 (name l n val)
      (declare (xargs :guard (and (array1p name l)
                                  (integerp n)
                                  (>= n 0)
                                  (< n (car (dimensions name l))))))
      (let ((l (cons (cons n val) l)))
        (cond ((> (length l) (maximum-length name l))
               (compress1 name l))
              (t l))))


Subtopics

  [Aset1-trusted]
      Set the elements of a 1-dimensional array without [invariant-risk]")
 (ASET1-TRUSTED
  (ARRAYS ACL2-BUILT-INS ASET1)
  "Set the elements of a 1-dimensional array without [invariant-risk]

    Example Form:
    (aset1-trusted 'delta1 a (+ i k) 27)

    General Form:
    (aset1-trusted name alist index val)

  This utility is identical to [47m[aset1][0m; in fact, it has the same guard.
  The difference is that it does not carry [invariant-risk].  Because
  of that, functions that call [47maset1-trusted[0m may suffer from
  invariant-risk but not be noted by the system as carrying
  invariant-risk.  Therefore, [47maset1-trusted[0m it is [untouchable] and
  should be used with great care.  If your system consists of
  [47m:[0m[47m[logic][0m-mode functions, then there is no reason to use
  [47maset1-trusted[0m, because only [47m:[0m[47m[program][0m-mode functions truly carry
  invariant-risk.

  [31;1mFunction: [0m<aset1-trusted>

    (defun aset1-trusted (name l n val)
      (declare (xargs :guard (and (array1p name l)
                                  (integerp n)
                                  (>= n 0)
                                  (< n (car (dimensions name l))))))
      (aset1 name l n val))")
 (ASET2
  (ARRAYS ACL2-BUILT-INS)
  "Set the elements of a 2-dimensional array

    Example Form:
    (aset2 'delta1 a i j 27)

    General Form:
    (aset2 name alist i j val)

  where [47mname[0m is a symbol, [47malist[0m is a 2-dimensional array named [47mname[0m, [47mi[0m
  and [47mj[0m are legal indices into [47malist[0m, and [47mval[0m is an arbitrary object.
  See [arrays] for details.  Roughly speaking this function
  ``modifies'' [47malist[0m so that the value associated with [47m(i . j)[0m is
  [47mval[0m.  More precisely, it returns a new array, [47malist'[0m, of the same
  name and dimension as [47malist[0m that, under [47m[aref2][0m, is everywhere
  equal to [47malist[0m except at [47m(i . j)[0m where the result is [47mval[0m.  That is,
  [47m(aref2 name alist' x y)[0m is [47m(aref2 name alist x y)[0m for all legal
  indices [47mx[0m [47my[0m except [47mi[0m and [47mj[0m where [47m(aref2 name alist' i j)[0m is [47mval[0m.

  In order to ``modify'' [47malist[0m, [47maset2[0m [47m[cons][0mes a new pair onto the
  front.  If the length of the resulting [47malist[0m exceeds the
  [47m:[0m[47m[maximum-length][0m entry in the array [header], [47maset2[0m compresses the
  array as with [47m[compress2][0m.

  It is generally expected that the ``semantic value'' of [47mname[0m will be
  [47malist[0m (see [arrays]).  This function operates in virtually constant
  time whether this condition is true or not (unless the [47m[compress2][0m
  operation is required).  But the value returned by this function
  cannot be used efficiently by subsequent [47maset2[0m operations unless
  [47malist[0m is the semantic value of [47mname[0m when [47maset2[0m is executed.  Thus,
  if the condition is not true, [47maset2[0m prints a [31;1mslow array[0m warning to
  the comment window.  See [slow-array-warning].

  [31;1mFunction: [0m<aset2>

    (defun aset2 (name l i j val)
      (declare (xargs :guard (and (array2p name l)
                                  (integerp i)
                                  (>= i 0)
                                  (< i (car (dimensions name l)))
                                  (integerp j)
                                  (>= j 0)
                                  (< j (cadr (dimensions name l))))))
      (let ((l (cons (cons (cons i j) val) l)))
        (cond ((> (length l) (maximum-length name l))
               (compress2 name l))
              (t l))))")
 (ASH
  (NUMBERS ACL2-BUILT-INS)
  "Arithmetic shift operation

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

  The [guard] for [47mash[0m requires that its arguments are integers.

  [47mAsh[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<ash>

    (defun ash (i c)
      (declare (xargs :guard (and (integerp i) (integerp c))))
      (floor (* (ifix i) (expt 2 c)) 1))")
 (ASSERT$
  (ERRORS ACL2-BUILT-INS)
  "Cause a hard error if the given test is false

    General Form:
    (assert$ test form)

  where [47mtest[0m returns a single value and [47mform[0m is arbitrary.
  Semantically, this call of [47massert$[0m is equivalent to [47mform[0m.  However,
  it causes a hard error if the value of [47mtest[0m is [47mnil[0m.  That hard
  error invokes the function [47m[illegal][0m, which has a [guard] that is
  equal to [47mnil[0m; so if you use [47massert$[0m in code for which you verify
  guards, then a proof obligation will be that the occurrence of [47mtest[0m
  is never [47mnil[0m.

  See also [47m[assert*][0m.  Both [47m[assert$][0m and [47m[assert*][0m create a [guard]
  proof obligation (when used in a definition made in [47m[logic][0m-mode).
  However, [47massert$[0m checks the assertion at runtime, while [47massert*[0m
  does not.

  Also see [assert-event] for an assertion-checking utility that is an
  [event].")
 (ASSERT*
  (ERRORS ACL2-BUILT-INS)
  "Create a [guard] proof obligation that given test holds

    General Form:
    (assert* test form)

  where [47mtest[0m returns a single value and [47mform[0m is arbitrary.
  Semantically, this call of [47massert*[0m is equivalent to [47mform[0m.  However,
  a [guard] proof obligation is created that [47mtest[0m holds, when used in
  a definition made in [47m[logic][0m-mode.

  For a related utility, see [assert$].  Both [47massert$[0m and [47massert*[0m
  create a [guard] proof obligation (when used in a definition made
  in [47m[logic][0m-mode).  However, [47massert$[0m checks the assertion at
  runtime, while [47massert*[0m does not.

  Also see [assert-event] for an assertion-checking utility that is an
  [event].

  [31;1mMacro: [0m<assert*>

    (defmacro assert* (test form)
      (cons 'and
            (cons (cons 'mbt* (cons test 'nil))
                  (cons form 'nil))))")
 (ASSERT-EVENT
  (EVENTS ERRORS)
  "Assert that a given form returns a non-[47mnil[0m value

  [47mAssert-event[0m provides a flexible way to check that evaluation of an
  expression returns a non-[47mnil[0m value, causing an error otherwise.
  Calls of [47massert-event[0m are [event] forms; thus, they may occur in
  [books] as well as [47m[encapsulate][0m and [47m[progn][0m events.  See also
  [assert!] and [assert!-stobj] for simple interfaces to
  [47massert-event[0m.  See [assert$] and [assert*] for assertion-checking
  utilities to use in programs.

  Basic calls of [47massert-event[0m will take just one argument, called an
  ``assertion'', which is a form that evaluates to a single value
  that is not a [stobj].  The following log shows a successful
  invocation --- one where the assertion evaluates to a non-[47mnil[0m
  value.

    ACL2 !>(assert-event (equal (+ 3 4) 7))
     :PASSED
    ACL2 !>

  Such a use of [47massert-event[0m 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 [47m:stobjs-out[0m, and
  keyword [47m:on-skip-proofs[0m can override the default behavior of
  ignoring assertions when proofs are being skipped.

    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
                  )

  where [47massertion[0m and [47mevent[0m are not evaluated but all the other
  arguments are evaluated, with the defaults shown above
  corresponding to values after evaluation.

  The following example illustrates all of the keyword arguments, which
  are documented below.

    (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))

  [47mAssert-event[0m is a macro whose expansion directly produces a call of
  the primitive event, [47mvalue-triple[0m, where: if a call of [47massert-event[0m
  specifies [47m:msg msg[0m, then the corresponding call of [47mvalue-triple[0m
  specifies [47m:check (or msg t)[0m.  But unlike [47mvalue-triple[0m, [47massert-event[0m
  can specify an event to evaluate when the assertion has non-[47mnil[0m
  value, using the [47m:event[0m keyword.  (You can get a sense of the
  [47mvalue-triple[0m call generated from an [47massert-event[0m call by using
  [47m:[0m[47m[trans1][0m on the [47massert-event[0m form.)  The remaining keyword
  arguments of [47massert-event[0m are also arguments of [47mvalue-triple[0m.  Here
  is a brief summary of the keyword arguments, but [31;1mNOTE[0m: see
  [value-triple] for more detailed explanations of keywords other
  than [47m:EVENT[0m.

  [47m:EVENT event[0m (default [47mnil[0m): When [47mevent[0m is not [47mnil[0m, it should be an
  [event], that is, a form that may be in a book or a call of
  [47m[encapsulate][0m or [47m[progn][0m.  If the assertion evaluates to a non-[47mnil[0m
  value (or to multiple values where the first value is not a stobj
  and is non-[47mnil[0m; see [47m:STOBJS-OUT[0m below), then [47mevent[0m is evaluated;
  otherwise the evaluation results in an error.

  [47m:CTX ctx[0m (default: [47m'assert-event[0m): context for error messages.

  [47m:MSG msg[0m (default: [47mt[0m): message to print when there is an error
  (equivalent to keyword argument [47m:CHECK[0m of [47m[value-triple][0m).

  [47m:ON-SKIP-PROOFS sp[0m (default: [47mnil[0m): supply [47mt[0m to evaluate the assertion
  even when skipping proofs (i.e., during [47m[include-book][0m or the
  second pass of an [47m[encapsulate][0m event, or after invoking
  [47m[set-ld-skip-proofsp][0m to skip proofs).

  [47m:SAFE-MODE safe-mode[0m (default: [47m:same[0m): provides backward
  compatibility, but is probably best ignored.

  [47m:STOBJS-OUT stobjs-out[0m (default: [47mnil[0m): specify [47m:auto[0m to allow any
  return, even with multiple values provided the first return value
  is not a [stobj]; or specify a list starting with [47mnil[0m,
  corresponding to the multiple values returned, with stobjs in stobj
  positions and [47mnil[0m elsewhere.  A [47mstobjs-out[0m of [47mnil[0m is treated as
  [47m(nil)[0m.  The first return value is the one checked to be non-[47mnil[0m
  with one exception: when an [error-triple] [47m(mv erp val state)[0m is
  returned, [47merp[0m must be [47mnil[0m and it is [47mval[0m that is checked to be
  non-[47mnil[0m.")
 (ASSERTIONS (POINTERS) "See [errors].")
 (ASSIGN
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Assign to a global variable in [47m[state][0m

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

    General Form:
    (assign symbol term)

  where [47msymbol[0m is any symbol (with certain enforced exclusions to avoid
  overwriting ACL2 system ``globals'') and [47mterm[0m is any ACL2 term that
  could be evaluated at the top-level.  [47mAssign[0m evaluates the term,
  stores the result as the value of the given symbol in the
  [47mglobal-table[0m of [47m[state][0m, 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.)  [47mAssign[0m is a
  macro that effectively expands to the more complicated but
  understandable:

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

  The macro [47mf-put-global[0m is closely related to [47m[assign][0m: [47m(assign var
  val)[0m macroexpands to [47m(f-put-global 'var val state)[0m.

  The macro [47m[@][0m gives convenient access to the value of such globals.
  The [47m:[0m[47m[ubt][0m operation has no effect on the [47mglobal-table[0m of [47m[state][0m.
  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.")
 (ASSOC
  (ALISTS ACL2-BUILT-INS)
  "Look up key in association list

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

  [47m(Assoc x alist)[0m is the first member of [47malist[0m whose [47m[car][0m is [47mx[0m, or [47mnil[0m
  if no such member exists.  The optional keyword, [47m:TEST[0m, has no
  effect logically, but provides the test (default [47m[eql][0m) used for
  comparing [47mx[0m with the [47m[car][0ms of successive elements of [47malist[0m.

  The [guard] for a call of [47massoc[0m depends on the test.  In all cases,
  the second argument must satisfy [47m[alistp][0m.  If the test is [47m[eql][0m,
  then either the first argument must be suitable for [47m[eql][0m (see
  [eqlablep]) or the second argument must satisfy [47m[eqlable-alistp][0m.
  If the test is [47m[eq][0m, then either the first argument must be a
  symbol or the second argument must satisfy [47m[symbol-alistp][0m.

  See [equality-variants] for a discussion of the relation between
  [47massoc[0m and its variants:

      [47m(assoc-eq x alist)[0m is equivalent to [47m(assoc x alist :test 'eq)[0m;

      [47m(assoc-equal x alist)[0m is equivalent to [47m(assoc x alist :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47massoc-equal[0m.

  [47mAssoc[0m is defined by Common Lisp.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<assoc-equal>

    (defun assoc-equal (x alist)
      (declare (xargs :guard (alistp alist)))
      (cond ((endp alist) nil)
            ((equal x (car (car alist)))
             (car alist))
            (t (assoc-equal x (cdr alist)))))")
 (ASSOC-EQ (POINTERS) "See [assoc].")
 (ASSOC-EQUAL (POINTERS) "See [assoc].")
 (ASSOC-KEYWORD
  (KEYWORD-VALUE-LISTP ACL2-BUILT-INS)
  "Look up key in a [47m[keyword-value-listp][0m

  If [47ml[0m is a list of even length of the form [47m(k1 a1 k2 a2 ... kn an)[0m,
  where each [47mki[0m is a keyword, then [47m(assoc-keyword key l)[0m is the first
  tail of [47ml[0m starting with [47mkey[0m if key is some [47mki[0m, and is [47mnil[0m
  otherwise.

  The [guard] for [47m(assoc-keyword key l)[0m is [47m(keyword-value-listp l)[0m.

  [31;1mFunction: [0m<assoc-keyword>

    (defun assoc-keyword (key l)
      (declare (xargs :guard (keyword-value-listp l)))
      (cond ((endp l) nil)
            ((eq key (car l)) l)
            (t (assoc-keyword key (cddr l)))))")
 (ASSOC-STRING-EQUAL
  (ALISTS ACL2-BUILT-INS)
  "Look up key, a string, in association list

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

  The [guard] for [47massoc-string-equal[0m requires that [47mx[0m is a string and
  [47malist[0m is an alist.

  [31;1mFunction: [0m<assoc-string-equal>

    (defun assoc-string-equal (str alist)
      (declare (xargs :guard (and (stringp str)
                                  (string-alistp alist))))
      (cond ((endp alist) nil)
            ((string-equal str (car (car alist)))
             (car alist))
            (t (assoc-string-equal str (cdr alist)))))")
 (ASSUME-TRUE-FALSE-AGGRESSIVE-P
  (REWRITE SYSTEM-ATTACHMENTS)
  "Control rewriter's use of the [type-alist] with [47mIF[0m calls

  This topic concerns an advanced control for the ACL2 prover.

  This zero-ary attachable system function controls the rewriter's use
  of the [type-alist] when diving into calls of [47mIF[0m.  By default, when
  ACL2 rewrites what amounts to [47m(if (or test1 test2) (if test1 _ x)
  _)[0m, the type-alist will fail to note that [47mtest2[0m is true when
  rewriting [47mx[0m.  Attach the function [47mconstant-t-function-arity-0[0m to
  strengthen the use of the type-alist so that [47mtest2[0m 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
  [47mconstant-nil-function-arity-0[0m to restore the default behavior.")
 (ATOM
  (CONSES ACL2-BUILT-INS)
  "Recognizer for atoms

  [47m(atom x)[0m is true if and only if [47mx[0m is an atom, i.e., not a [47m[cons][0m
  pair.

  [47mAtom[0m has a [guard] of [47mt[0m, and is a Common Lisp function.  See any
  Common Lisp documentation for more information.

  [31;1mFunction: [0m<atom>

    (defun atom (x)
      (declare (xargs :guard t))
      (not (consp x)))


Subtopics

  [Atom-listp]
      Recognizer for a true list of [atom]s")
 (ATOM-LISTP
  (ATOM LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of [atom]s

  The predicate [47matom-listp[0m tests whether its argument is a [47m[true-listp][0m
  of [atom]s, i.e., of non-conses.

  [31;1mFunction: [0m<atom-listp>

    (defun atom-listp (lst)
      (declare (xargs :guard t))
      (cond ((atom lst) (eq lst nil))
            (t (and (atom (car lst))
                    (atom-listp (cdr lst))))))")
 (ATTACH-STOBJ
  (DEFABSSTOBJ)
  "Attach an ``implementation [stobj]'' to an attachable stobj

  For an illustration of [47mattach-stobj[0m, see [community-books] directory
  [47mbooks/demos/attach-stobj/[0m, in particular file [47mREADME.txt[0m in that
  directory.

  This topic assumes familiarity with abstract [stobj]s; see
  [defabsstobj].  It documents a way to modify the foundation and
  primitives of an abstract [stobj], [47mgen[0m, that is introduced by
  [47mdefabsstobj[0m using the keyword argument [47m:attachable t[0m.  Such a stobj
  is called an [3mattachable[0m stobj.  Execution of its primitives can be
  provided by corresponding primitives of a specified abstract stobj,
  [47mimpl[0m, which we say is [3mattached to[0m [47mgen[0m (or: [47mimpl[0m is the
  [3mimplementation stobj attached to[0m [47mgen[0m); said differently, [47mgen[0m has
  [47mimpl[0m as an attachment.  That relationship is specified by the
  following

    General Form:
    (attach-stobj gen impl)

  where [47mgen[0m and [47mimpl[0m are symbols, [47mgen[0m is not currently the [name] of
  any [event] (function, macro, constant, stobj, etc.), and [47mimpl[0m is
  an abstract stobj.  A subsequent attempt to introduce [47mgen[0m as an
  attachable stobj will require [47mgen[0m and [47mimpl[0m to have [3mcorresponding
  logical skeletons[0m as described below.  In that case, the foundation
  of [47mgen[0m, as well as execution of the primitives of [47mgen[0m, will
  effectively be provided by [47mimpl[0m; details are below.

  In the General Form above, [47mimpl[0m is allowed to be [47mnil[0m, i.e., the event
  [47m(attach-stobj gen nil)[0m is legal, where it is still required that
  [47mgen[0m not be the name of any existing event.  The effect of this
  ``attachment'' of [47mnil[0m is to cancel the effect of any previous
  [47m(attach-stobj gen impl)[0m on any future introduction of [47mgen[0m.  Below,
  we assume the common case that [47mimpl[0m is not [47mnil[0m.

  Note that [47mimpl[0m may itself have an attachment, say, [47mimpl2[0m, in which
  case we say that [47mimpl2[0m is attached to [47mgen[0m.  If furthermore [47mimpl3[0m is
  attached to [47mimpl2[0m, then [47mimpl3[0m is said to be attached to [47mgen[0m; and so
  on.

  The guiding principle is that [47mgen[0m is modified by its attachment to
  [47mimpl[0m so that [47mgen[0m behaves exactly as [47mimpl[0m except for the names
  introduced and the [47m:non-executable[0m keyword.  Specifically, if [47mimpl[0m
  is attached to [47mgen[0m, then the following properties hold.  (See
  [defabsstobj] for the notion of a ``function spec'' and its
  ``completion''.)

    * Both [47mgen[0m and [47mimpl[0m are abstract stobjs, and moreover, [47mgen[0m is an
      attachable stobj.

    * [47mImpl[0m was introduced before the use of [47mattach-stobj[0m to attach [47mimpl[0m to
      [47mgen[0m, which took place before [47mgen[0m was introduced.

    * [47mGen[0m and [47mimpl[0m have corresponding logical skeletons (as defined below).
      In particular, each primitive of [47mgen[0m has the same logical
      meaning (i.e., the same [47m:logic[0m function) as the corresponding
      primitive of [47mimpl[0m.

    * For each primitive [47mp_gen[0m of [47mgen[0m and corresponding primitive [47mp_impl[0m of
      [47mimpl[0m, if [47m(p_impl . kwd-alist)[0m is the completion of the
      corresponding function spec for [47mp_impl[0m, then the function spec
      for [47mp_gen[0m is effectively given as [47m(p_gen . kwd-alist)[0m, with the
      following exception.  Each [47m:updater[0m keyword is replaced
      appropriately, as follows: if [47mkwd-alist[0m specifies [47m:updater
      u_impl[0m and primitive [47mu_gen[0m of [47mgen[0m corresponds to primitive
      [47mu_impl[0m of [47mimpl[0m, then [47m:updater u_impl[0m is replaced by [47m:updater
      u_gen[0m to obtain the effective function spec for [47mp_gen[0m.

    * The [47m:protect-default[0m and [47m:congruent-to[0m keyword arguments for [47mgen[0m are
      effectively those of [47mimpl[0m.

    * The [47m:non-executable[0m keyword argument for [47mgen[0m is unchanged by the
      attachment.

  As promised above, we now define when two [47mdefabsstobj[0m events have
  [3mcorresponding logical skeletons[0m, as follows.  The [47m:exports[0m 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
  [47m:logic[0m functions and, if one of them specifies [47m:updater u1[0m, then
  the other must specify [47m:updater u2[0m where [47mu1[0m and [47mu2[0m correspond.

  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 [47m:exec[0m primitive of the attachment
  (which is itself a macro call).  The trade-off is that when a
  function [47mF[0m is defined in the course of evaluating an [47m[include-book][0m
  event, then if the guard or body of [47mF[0m calls an attachable stobj
  primitive --- either directly or by way of inline functions or
  macroexpansion, and whether or not that stobj has an attachment ---
  then [47mF[0m 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 --- a function that does nothing more than call
  the primitive --- to avoid such recompilation at the cost of a
  runtime function call for each such primitive.  End of Remarks on
  Performance.

  Note that the notion of redundancy for [47mdefabsstobj[0m was not changed by
  support for the [47m:attachable[0m keyword.  As noted in the topic
  [redundant-events], a [47mdefabsstobj[0m event is redundant if there is
  already an identical such event in the logical [world].

  The [community-books] directory [47msystem/tests/attachable-stobjs/[0m has
  examples that use attachable stobjs.")
 (AUTO-INSTANCE (POINTERS)
                "See [defthm<w].")
 (A_FLYING_TOUR_OF_ACL2
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "A Flying Tour of ACL2

  {IMAGE} (see [About_the_ACL2_Home_Page])

  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.

  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.

    [31;1mThe Flight Plan[0m
    * This Documentation (see [About_the_ACL2_Home_Page])
    * What is ACL2? (see [What_Is_ACL2{Q}])
    * Mathematical Logic (see [What_is_a_Mathematical_Logic{Q}])
    * Mechanical Theorem Proving (see [What_is_a_Mechanical_Theorem_Prover{Q}])
    * Mathematical Models in General (see [About_Models])
    * Mathematical Models of Computing Machines (see [Models_of_Computer_Hardware_and_Software])
         Formalizing Models (see [A_Typical_State])
         Running Models (see [Running_Models])
         Symbolic Execution of Models (see [Symbolic_Execution_of_Models])
         Proving Theorems about Models (see [Proving_Theorems_about_Models])
    * Requirements of ACL2
         The User's Skills (see [What_is_Required_of_the_User{Q}])
         Training (see [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}])
         Host System (see [Other_Requirements])

  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.

  {IMAGE} (see [About_the_ACL2_Home_Page])")
 (A_SKETCH_OF_HOW_THE_REWRITER_WORKS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "A Sketch of How the Rewriter Works

  Below we show the first target term, extracted from the current
  conjecture.  Below it we show the associativity rule.

  {IMAGE}

  The variables of the rewrite rule are [31;1minstantiated[0m so that the
  [31;1mleft-hand side[0m of the rule matches the target:

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

  Then the target is [31;1mreplaced[0m by the instantiated [31;1mright-hand side[0m of
  the rule.

  Sometimes rules have [31;1mhypotheses[0m.  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 [31;1mbackchaining[0m.  If they all rewrite to true, then the
  target is replaced as above.

  We discuss the rewriter in more detail in the extended introduction
  to how to use the theorem prover, see
  [introduction-to-the-theorem-prover], which we will recommend you
  work through [31;1mafter[0m you have finished the two tours.")
 (A_TINY_WARNING_SIGN
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "A Tiny Warning Sign

  {IMAGE}

  This warning sign, which usually appears as ``{ICON}'', indicates
  that the link it marks takes you into ACL2's online documentation.

  The documentation is a vast graph of documented topics intended to
  help the [3muser[0m of ACL2 rather than the [3mpotential user[0m.  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.")
 (A_TRIVIAL_PROOF (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
                  "A Trivial Proof

  {IMAGE}")
 (A_TYPICAL_STATE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "A Typical State

  {IMAGE} (see [Functions_for_Manipulating_these_Objects])

  {IMAGE}

  Observe that the states in typical models talk about

    [31;1mbooleans[0m    [31;1mintegers[0m   [31;1mvectors[0m     [31;1mrecords[0m   [31;1mcaches[0m
    [31;1mbits[0m        [31;1msymbols[0m    [31;1marrays[0m      [31;1mstacks[0m    [31;1mfiles[0m
    [31;1mcharacters[0m  [31;1mstrings[0m    [31;1msequences[0m   [31;1mtables[0m    [31;1mdirectories[0m

  These objects are [31;1mdiscrete[0m rather than [31;1mcontinuous[0m; furthermore they
  are built incrementally or [31;1minductively[0m by repeatedly using
  primitive operations to put together smaller pieces.

  The functions we need to manipulate these objects do things like
  [31;1mconcatenate[0m, [31;1mreverse[0m, [31;1msort[0m, [31;1msearch[0m, [31;1mcount[0m, etc.

  {IMAGE} (see [Functions_for_Manipulating_these_Objects])")
 (A_WALKING_TOUR_OF_ACL2
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "A Walking Tour of ACL2

  {IMAGE} (see [Common_Lisp])

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

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

  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 --- provided they are not marked with the tiny
  warning sign ({ICON} (see [A_Tiny_Warning_Sign])).  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.

  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.

  {IMAGE} (see [Common_Lisp])")
 (BACKCHAIN-LIMIT
  (REWRITE META LINEAR TYPE-PRESCRIPTION)
  "Limiting the effort expended on relieving hypotheses

  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 [47m[case-split][0ms and [47m[force][0md hypotheses.)
  ACL2 typically establishes each hypothesis by backchaining ---
  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 [47m[backchain-limit][0m.

  Each hypothesis of a [47m[rewrite][0m, [47m[meta][0m, [47m[linear][0m, or
  [47m[type-prescription][0m rule is assigned a backchain-limit when the
  rule is stored.  By default, this limit is [47mnil[0m, denoting infinity
  (no limit).  However, the value used for the default may be set to
  a non-negative integer (or to [47mnil[0m) by the user; see
  [set-default-backchain-limit].  The default is overridden when a
  [47m:backchain-limit-lst[0m is supplied explicitly with the rule; 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.

  Moreover, the user may set global backchain-limits that limit the
  total backchaining depth.  See [set-backchain-limit].  One limit is
  for the use of [47m[rewrite][0m, [47m[meta][0m, and [47m[linear][0m rules, while the
  other limit is for so-called ``type reasoning'', which uses rules
  of class [47m[type-prescription][0m rules (see [type-reasoning]).  The two
  limits operate independently.  Below, we discuss the first kind of
  backchain limits, i.e., for other than [47m[type-prescription][0m rules,
  except as otherwise indicated; but the mechanism for those rules is
  similar.

  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
  [47m:set-backchain-limit 0[0m.

  Recall that there are two sorts of backchain limits: those applied to
  hypotheses of individual rules, as assigned by their
  [47m:[0m[47m[rule-classes][0m or else taken from the default (see
  [set-default-backchain-limit]); and the global limit, initially [47mnil[0m
  (no limit) but settable with [47m:[0m[47m[set-backchain-limit][0m.  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 [47mnil[0m but can
  be set using [47m:[0m[47m[set-backchain-limit][0m.  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.

  We illustrate with the following examples.

    ; 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)))

  Finally, we remark that to see the current global backchain-limits,
  issue the following commands.

    (backchain-limit wrld :ts) ; backchain limit for type-set reasoning
    (backchain-limit wrld :rewrite) ; backchain limit for rewriting


Subtopics

  [Set-backchain-limit]
      Sets the backchain-limit used by the type-set and rewriting
      mechanisms

  [Set-default-backchain-limit]
      Sets the default backchain-limit used when admitting a rule")
 (BACKCHAIN-LIMIT-RW
  (POINTERS)
  "See [hints] for information about the keyword [47m:backchain-limit-rw[0m.")
 (BACKCHAINING
  (RULE-CLASSES)
  "Attempting to relieve the hypotheses of a rule

  When the theorem prover attempts to apply a rule (e.g., a [rewrite]
  rule), it must relieve (prove) the hypotheses of that rule.  In the
  ACL2 community, this process of relieving hypotheses is called
  backchaining.

  There is no such thing as a backchaining or backward-chaining rule
  class (see [rule-classes]) in ACL2.")
 (BACKQUOTE
  (READER)
  "Variant of quotation introducing templates for data structures

  ACL2 supports the backquote ([47m`[0m) construct of Common Lisp.  See any
  Common Lisp documentation for details, for example, its {discussion
  in the Common Lisp HyperSpec |
  http://www.lispworks.com/documentation/HyperSpec/Body/02_df.htm}.
  Here we give only a brief introduction.

  Together with the use of comma ([47m,[0m) and comma-atsign ([47m,@[0m), backquote
  provides a variant of quote that supports an escape mechanism, as
  illustrated by the following examples.

    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 !>

  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 [47m[true-listp][0m) rather than inserting it.")
 (BACKTRACK
      (POINTERS)
      "See [hints] for information about the keyword [47m:backtrack[0m.")
 (BADGE
  (APPLY$)
  "Syntactic requirements on a function symbol to be used by [47mapply$[0m

  ``Badge'' is both the name of an ACL2 function and the name of a
  concept key to the [47m[apply$][0m machinery.  We discuss the function
  named [47mbadge[0m first.  The discussion also mentions the concept of
  warrants, which are easily confused with badges.  See the
  discussion of [31;1mBadges versus Warrants[0m at the top of [47mdefbadge[0m.  But
  roughly put, badges extend the ACL2 syntax and warrants extend the
  proof theory.  You'll need a badge for [47mfn[0m to allow the system to
  syntactically analyze [47m(apply$ 'fn ...)[0m.  You'll need a both a badge
  and a warrant for [47mfn[0m if you wish to reason about that term with
  ACL2.

  General Form:

    (badge fn)

  The argument, [47mfn[0m, is expected to be a function symbol.  If [47mfn[0m is one
  of about 800 ACL2 primitives (discussed below) or is a user-defined
  function successfully processed by either the event [47m[defbadge][0m or
  the event [47m[defwarrant][0m, the result is an object, called the
  ``badge'' of [47mfn[0m, which among other things specifies the [ilk] of
  each formal of [47mfn[0m.  Otherwise, an error is caused.  We explain
  below, where we define the concepts of the ``out arity,'' ``ilks,''
  and ``tameness requirements'' of [47mfn[0m's badge.

  A function symbol must have a badge in order to [47mapply$[0m 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.  [47mDefbadge[0m will
  assign a badge to a function symbol, if possible, and [47mdefwarrant[0m
  will assign both a badge (if the function symbol doesn't already
  have one) and a [47m[warrant][0m, if possible.  The macro [47m[defun$][0m is just
  an abbreviation for a [47mdefun[0m followed by a [47mdefwarrant[0m.  Almost all
  primitive system functions already have badges.

  The complete list of badged primitives can be seen by evaluating

    (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP
                    APPLY$ EV$)
            (strip-cars *badge-prim-falist*))

  [47mBadge[0m is a defined function in ACL2.  You can inspect its definition
  with

    ACL2 !>:pe badge

  and see that after handling the built-in symbols it defers to the
  undefined function [47m[badge-userfn][0m.  In the evaluation theory,
  [47mbadge-userfn[0m has an attachment that returns the badge computed by
  [47mdefbadge[0m or [47mdefwarrant[0m.  But in the proof theory, [47mbadge-userfn[0m is
  undefined and the [47m[warrant][0m for [47mfn[0m specifies the badge of [47mfn[0m.
  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.

  The rest of this documentation illustrates and explains what badges
  mean, starting with a few examples.

    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)

  The last example assumes that [47mfoldr[0m has been defined with

    (defun$ foldr (lst fn init)
      (if (endp lst)
          init
          (apply$ fn
                  (list (car lst)
                        (foldr (cdr lst) fn init)))))

  In general, badges have the form [47m(APPLY$-BADGE n k . ilks)[0m, where [47mn[0m
  is the arity of [47mfn[0m, [47mk[0m is the out arity (i.e., the number of results
  returned by [47mfn[0m) and [47milks[0m is either [47mT[0m or a list of [47mn[0m tokens.  Each
  token is either [47m:FN[0m, [47m:EXPR[0m, or [47mNIL[0m.

  The badge of [47mfn[0m, if any, is computed when the event [47m(defbadge fn)[0m or
  [47m(defwarrant fn)[0m completes successfully.  See [47m[defbadge][0m for a
  sketch of the algorithm used to compute badges.  Here though we are
  just concerned with how badges impact [47mapply$[0m.

  The [47milks[0m of a function, [47mfn[0m, determines the ``tameness requirements''
  mentioned in the specification of [47m[apply$][0m.  When the [47milks[0m
  component of [47mfn[0m's badge is a list, it has as many elements as there
  are formals to [47mfn[0m and each successive element is called the [3milk[0m of
  the corresponding formal.  For example, given the definition of
  [47mfoldr[0m above and the badge shown for it, the first and third
  formals, [47mlst[0m and [47minit[0m, each have ilk [47mNIL[0m and the second formal, [47mfn[0m,
  has ilk [47m:FN[0m.  In the special case that [47milks[0m is not a list it is [47mT[0m
  and we just say each formal has [3milk[0m [47mNIL[0m -- treating that [47mT[0m as a
  suitably long list of [47mNIL[0ms.

  Each non-[47mNIL[0m ilk imposes a [3mtameness requirement[0m on [47m(apply$ fn args)[0m.
  If a formal has ilk [47m:FN[0m the corresponding element of [47margs[0m must
  satisfy [47mtamep-functionp[0m.  If a formal has ilk [47m:EXPR[0m the
  corresponding element of [47margs[0m must satisfy [47mtamep[0m.  Ilk [47mNIL[0m imposes
  no requirement.  (Thus, if the [47milks[0m of [47mfn[0m's badge is [47mT[0m, as it is
  for [47mcons[0m for example, there is no tameness requirement at all.)
  See [tame] for a discussion of the various notions of tameness.

  Informally, if a formal's ilk is [47m:FN[0m, the corresponding element of
  [47margs[0m must be a tame function symbol or well-formed [47mLAMBDA[0m object.
  If a formal's ilk is [47m:EXPR[0m, the corresponding element of [47margs[0m must
  be a tame expression.

  If a formal has ilk [47m:FN[0m then you are allowed to put a [47m[lambda$][0m
  expression in that slot.  Any quoted [47mLAMBDA[0m object you explicitly
  write in such a slot must be well-formed (see
  [well-formed-lambda-objectp]).  Well-formedness can be hard to
  achieve in quoted hand-written [47mLAMBDA[0m objects; we recommend that
  you use [47mlambda$[0m!  But the restrictions on what can occupy a [47m:FN[0m
  slot are enforced when user input is translated into formal terms.
  It is possible to circumvent these syntactic checks without
  endangering soundness: axiomatically [47mapply$[0m puts no restrictions on
  its arguments, it just doesn't behave the way you might expect on
  ill-formed [47mLAMBDA[0m objects.  See
  [gratuitous-lambda-object-restrictions].

  [31;1mClarification[0m: The careful reader will note that the formal
  requirement on a [47m:FN[0m argument is that it must satisfy
  [47mtamep-functionp[0m.  Inspection of the definition of [47mtamep-functionp[0m
  reveals that the argument must either be badged symbol with ilks [47mT[0m
  or else be a tame [47mLAMBDA[0m object.  But in the informal description
  above we said that it must be a ``tame function symbol or a
  [3mwell-formed[0m [47mLAMBDA[0m 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 [47mapply$[0m and the practical
  business of executing it.  The former involves the existence of a
  model, soundness, and the difficulty of proving theorems about
  [47mapply$[0m.  The latter involves the Common Lisp compiler.  We want the
  logical foundations to be simple so we -- and you -- can reason
  about [47mapply$[0m, but the compiler imposes unavoidable and complicated
  restrictions.  The upshot is that the logical foundations assign
  meaning to [47mLAMBDA[0m objects that cannot be compiled.  Applying merely
  ``tame'' [47mLAMBDA[0ms is slower than applying ``well-formed'' ones.  In
  a sense by acting like ``tame [47mLAMBDA[0m objects'' and ``well-formed
  [47mLAMBDA[0m objects'' are the same thing we're trying to trick you!  If
  you ever have occasion to formally express the restrictions on
  [47mapply$[0m in some theorem, use [47mtamep-functionp[0m.  But when you write
  concrete [47mLAMBDA[0m constants, try to keep them well-formed.  We try to
  encourage this by providing [47m[lambda$][0m, which guarantees
  well-formedness at translate-time, and by implementing full
  well-formedness checks -- not just tameness checks -- on quoted
  [47mLAMBDA[0m objects in [47m:FN[0m slots.  And we give you ways to circumvent
  these checks -- see [gratuitous-lambda-object-restrictions] -- if
  you really mean to.")
 (BADGE-USERFN
  (APPLY$)
  "Undefined function used by [47mbadge[0m on non-primitives

  When [47m[badge][0m is given a non-primitive function symbol [47mfn[0m it calls
  this function to determine the badge of [47mfn[0m.  But this function is
  undefined.  In the proof theory, its value on a given function
  symbol [47mfn[0m is specified, if at all, by the [47m[warrant][0m for [47mfn[0m which
  must be available as a hypothesis in the formula being proved.  In
  the evaluation theory, [47mbadge-userfn[0m has an attachment that makes it
  behave as though all warrants are assumed.  See [47m[badge][0m for
  details.")
 (BASICS
  (PROGRAMMING)
  "Basic control structures for [programming] like [if] and [cond],
  binding operators like [let] and [flet], multiple-value constructs
  like [mv], and so forth.


Subtopics

  [ACL2-count]
      A commonly used measure for justifying recursion

  [And]
      Conjunction

  [Booleanp]
      Recognizer for booleans

  [Case]
      Conditional based on if-then-else using [47m[eql][0m

  [Case-match]
      Pattern matching or destructuring

  [Cond]
      Conditional based on if-then-else

  [Equal]
      True equality

  [Flet]
      Local binding of function symbols

  [Good-bye]
      Quit entirely out of Lisp

  [Identity]
      The identity function

  [If]
      If-then-else function

  [Iff]
      Logical ``if and only if''

  [Implies]
      Logical implication

  [Let]
      Binding of lexically scoped (local) variables

  [Let*]
      Binding of lexically scoped (local) variables

  [Macrolet]
      Local binding of macro symbols

  [Mv]
      Returning a multiple value

  [Mv-let]
      Calling multi-valued ACL2 functions

  [Not]
      Logical negation

  [Null]
      Recognizer for the empty list

  [Or]
      Disjunction

  [Progn$]
      Execute a sequence of forms and return the value of the last one

  [Quote]
      Create a constant

  [Return-last]
      Return the last argument, perhaps with side effects

  [Xor]
      Logical ``exclusive or''")
 (BDD
  (ACL2)
  "Ordered binary decision diagrams with rewriting

  Note.  The ACL2 bdd capability has been essentially superseded by GL;
  see [gl].

  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).

  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, [3mJournal of Automated Reasoning[0m (1994), pp.
  33--45.  (This paper also appears as Technical Report #84 from
  Computational Logic, Inc.)

  Further information about BDDs in ACL2 can be found in the subtopics
  of this [documentation] section.  In particular, see
  [bdd-introduction] for a good starting place that provides a number
  of examples.

  See [hints] for a description of [47m:bdd[0m hints.  For quick reference,
  here is an example; but only the [47m:vars[0m part of the hint is
  required, as explained in the documentation for [hints].  The
  values shown are the defaults.

    (:vars nil :bdd-constructors (cons) :prove t :literal :all)

  We suggest that you next visit the documentation topic
  [bdd-introduction].


Subtopics

  [Bdd-algorithm]
      Summary of the BDD algorithm in ACL2

  [Bdd-introduction]
      Examples illustrating the use of BDDs in ACL2

  [If*]
      For conditional rewriting with BDDs

  [Obdd]
      Ordered binary decision diagrams with rewriting

  [Show-bdd]
      Inspect failed BDD proof attempts")
 (BDD-ALGORITHM
  (BDD)
  "Summary of the BDD algorithm in ACL2

  The BDD algorithm in ACL2 uses a combination of manipulation of [47mIF[0m
  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.

  We recommend that you read the other documentation about BDDs in ACL2
  before reading the rather technical material that follows.  See
  [bdd].

  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.

  (A) [31;1mMathematical Considerations[0m

      (A1) BDD term order

      (A2) BDD-constructors and BDD terms, and their connection with
      aborting the BDD algorithm

      (A3) Canonical BDD terms

      (A4) A theorem stating the equivalence of provable and syntactic
      equality for canonical BDD terms

  (B) [31;1mAlgorithmic Considerations[0m

      (B1) BDD rules (rules used by the rewriting portion of the ACL2 BDD
      algorithm)

      (B2) Terms ``known to be Boolean''

      (B3) An ``IF-lifting'' operation used by the algorithm, as well as an
      iterative version of that operation

      (B4) The ACL2 BDD algorithm

      (B5) Soundness and Completeness of the ACL2 BDD algorithm

      (B6) Efficiency considerations

  (A) [31;1mMathematical Considerations[0m

  (A1) [3mBDD term order[0m

  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.

  (A2) [3mBDD-constructors[0m (assumed to be [47m'(cons)[0m) and [3mBDD terms[0m

  We take as given a list of function symbols that we call the
  ``BDD-constructors.'' By default, the only BDD-constructor is
  [47m[cons][0m, although it is legal to specify any list of function
  symbols as the BDD-constructors, either by using the
  [ACL2-defaults-table] (see [ACL2-defaults-table]) or by supplying a
  [47m:BDD-CONSTRUCTORS[0m hint (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 [47m'(cons)[0m.

  Roughly speaking, a [bdd] term is the sort of [term] produced by our
  BDD algorithm, namely a tree with all [47m[cons][0m nodes lying above all
  non-[47mCONS[0m nodes.  More formally, a [term] is said to be a [bdd] term
  if it contains [31;1mno[0m subterm of either of the following forms, where [47mf[0m
  is not [47mCONS[0m.

    (f ... (CONS ...) ...)

    (f ... 'x ...)  ; where (consp x) = t

  We will see that whenever the BDD algorithm attempts to create a
  [term] that is not a [bdd] term, it aborts instead.  Thus, whenever
  the algorithm completes without aborting, it creates a [bdd] term.

  (A3) [3mCanonical BDD terms[0m

  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 [47m(IF x y z)[0m:

      (a) [47mx[0m is a variable, and it precedes (in the BDD term order) every
      variable occurring in [47my[0m or [47mz[0m;

      (b) [47my[0m and [47mz[0m are syntactically distinct; and,

      (c) it is not the case that [47my[0m is [47mt[0m and [47mz[0m is [47mnil[0m.

  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 [47mIF[0m and [47mCONS[0m.  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).

  (A4) [3mProvably equal canonical BDD terms are identical[0m

  We believe that the following theorem and proof are routine
  extensions of a standard result and proof to terms that allow calls
  of [47mCONS[0m.

  [31;1mTheorem[0m.  Suppose that [47mt1[0m and [47mt2[0m are canonical BDD terms that contain
  no function symbols other than [47mIF[0m and [47mCONS[0m.  Also suppose that
  [47m(EQUAL t1 t2)[0m is a theorem.  Then [47mt1[0m and [47mt2[0m are syntactically
  identical.

  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 [47mt1[0m.  We must
  prove that [47mt2[0m is syntactically the same as [47mt1[0m.  Now it is clearly
  consistent that [47m(EQUAL t1 t2)[0m is false if [47mt2[0m is a call of [47mCONS[0m (to
  see this, simply let [47mt1[0m be an value that is not a [47mCONSP[0m).
  Similarly, [47mt2[0m cannot be a constant or a variable other than [47mt1[0m.
  The remaining possibility to rule out is that [47mt2[0m is of the form [47m(IF
  t3 t4 t5)[0m, since by assumption its function symbol must be [47mIF[0m or
  [47mCONS[0m and we have already handled the latter case.  Since [47mt2[0m is
  canonical, we know that [47mt3[0m is a variable.  Since [47m(EQUAL t1 t2)[0m is
  provable, i.e.,

    (EQUAL t1 (if t3 t4 t5))

  is provable, it follows that we may substitute either [47mt[0m or [47mnil[0m for [47mt3[0m
  into this equality to obtain two new provable equalities.  First,
  suppose that [47mt1[0m and [47mt3[0m are distinct variables.  Then these
  substitutions show that [47mt1[0m is provably equal to both [47mt4[0m and [47mt5[0m
  (since [47mt3[0m does not occur in [47mt4[0m or [47mt5[0m by property (a) above, as [47mt2[0m
  is canonical), and hence [47mt4[0m and [47mt5[0m are provably equal to each
  other, which implies by the inductive hypothesis that they are the
  same term --- and this contradicts the assumption that [47mt2[0m is
  canonical (property (b)).  Therefore [47mt1[0m and [47mt3[0m are the same
  variable, i.e., the equality displayed above is actually [47m(EQUAL t1
  (if t1 t4 t5))[0m.  Substituting [47mt[0m and then [47mnil[0m for [47mt1[0m into this
  provable equality lets us prove [47m(EQUAL t t4)[0m and [47m(EQUAL nil t5)[0m,
  which by the inductive hypothesis implies that [47mt4[0m is
  (syntactically) the term [47mt[0m and [47mt5[0m is [47mnil[0m.  That is, [47mt2[0m is [47m(IF t1 t
  nil)[0m, which contradicts the assumption that [47mt2[0m is canonical
  (property (c)).

  Next, suppose that at least one term is a call of [47mIF[0m.  Our first
  observation is that the other term is also a call of [47mIF[0m.  For if
  the other is a call of [47mCONS[0m, then they cannot be provably equal,
  because the former has no function symbols other than [47mIF[0m and hence
  is Boolean when all its variables are assigned Boolean values.
  Also, if the other is a constant, then both branches of the [47mIF[0m 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 [47mIF[0m; let us write them as follows.

    t0:  (IF t1 t2 t3)
    u0:  (IF u1 u2 u3)

  Note that [47mt1[0m and [47mu1[0m are variables, by property (a) of canonical BDD
  terms.  First we claim that [47mt1[0m does not strictly precede [47mu1[0m in the
  BDD term order.  For suppose [47mt1[0m does strictly precede [47mu1[0m.  Then
  property (a) of canonical BDD terms guarantees that [47mt1[0m does not
  occur in [47mu0[0m.  Hence, an argument much like one used above shows
  that [47mu0[0m is provably equal to both [47mt2[0m (substituting [47mt[0m for [47mt1[0m) and [47mt3[0m
  (substituting [47mnil[0m for [47mt1[0m), and hence [47mt2[0m and [47mt3[0m are provably equal.
  That implies that they are identical terms, by the inductive
  hypothesis, which then contradicts property (b) for [47mt0[0m.  Similarly,
  [47mu1[0m does not strictly precede [47mt1[0m in the BDD term order.  Therefore,
  [47mt1[0m and [47mu1[0m are the same variable.  By substituting [47mt[0m for this
  variable we see that [47mt2[0m and [47mu2[0m are provably equal, and hence they
  are equal by the inductive hypothesis.  Similarly, by substituting
  [47mnil[0m for [47mt1[0m (and [47mu1[0m) we see that [47mt3[0m and [47mu3[0m are provably, hence
  syntactically, equal.

  We have covered all cases in which at least one term is a variable or
  at least one term is a call of [47mIF[0m.  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 [47mCONS[0m and
  the other is a constant or a call of [47mCONS[0m.  The constant case is
  similar to the [47mCONS[0m case if the constant is a [47mCONSP[0m, so we omit it;
  while if the constant is not a [47mCONSP[0m then it is not provably equal
  to a call of [47mCONS[0m; in fact it is provably [3mnot[0m equal!

  So, we are left with a final case, in which canonical BDD terms [47m(CONS
  t1 t2)[0m and [47m(CONS u1 u2)[0m are provably equal, and we want to show
  that [47mt1[0m and [47mu1[0m are syntactically equal as are [47mt2[0m and [47mu2[0m.  These
  conclusions are easy consequences of the inductive hypothesis,
  since the ACL2 axiom [47mCONS-EQUAL[0m (which you can inspect using [47m:[0m[47m[pe][0m)
  shows that equality of the given terms is equivalent to the
  conjunction of [47m(EQUAL t1 t2)[0m and [47m(EQUAL u1 u2)[0m.  Q.E.D.

  (B) [31;1mAlgorithmic Considerations[0m

  (B1) [3mBDD rules[0m

  A rule of class [47m:[0m[47m[rewrite][0m (see [rule-classes]) is said to be a
  ``[bdd] rewrite rule'' if and only if it satisfies the following
  criteria.  (1) The rule is [enable]d.  (2) Its [equivalence]
  relation is [47m[equal][0m.  (3) It has no hypotheses.  (4) Its
  [47m:[0m[47m[loop-stopper][0m field is [47mnil[0m, 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 [rewrite]).  A rule of
  class [47m:[0m[47m[definition][0m (see [rule-classes]) is said to be a ``[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.

  Both BDD rewrite rules and BDD definition rules are said to be ``BDD
  rules.''

  (B2) [3mTerms ''known to be Boolean''[0m

  We apply the BDD algorithm in the context of a top-level goal to
  prove, namely, the goal at which the [47m:BDD[0m hint is attached.  As we
  run the BDD algorithm, we allow ourselves to say that a set of
  [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
  [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.

  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 [47mt1[0m is known to be Boolean then the
  algorithm simplifies [47m(IF t1 t nil)[0m to [47mt1[0m; see (iv) in the
  discussion immediately below.

  (B3) [3mIF-lifting[0m and the [3mIF-lifting-for-IF loop[0m

  Suppose that one has a [term] of the form [47m(f ... (IF test x y) ...)[0m,
  where [47mf[0m is a function symbol other than [47mCONS[0m.  Then we say that
  ``IF-lifting'' [47mtest[0m ``from'' this term produces the following term,
  which is provably equal to the given term.

    (if test
        (f ... x ...)  ; resulting true branch
        (f ... y ...)) ; resulting false branch

  Here, we replace each argument of [47mf[0m of the form [47m(IF test .. ..)[0m, for
  the same [47mtest[0m, in the same way.  In this case we say that
  ``IF-lifting applies to'' the given term, ``yielding the test''
  [47mtest[0m and with the ``resulting two branches'' displayed above.
  Whenever we apply IF-lifting, we do so for the available [47mtest[0m that
  is least in the BDD term order (see (A1) above).

  We consider arguments [47mv[0m of [47mf[0m that are ``known to be Boolean'' (see
  above) to be replaced by [47m(IF v t nil)[0m for the purposes of
  IF-lifting, i.e., before IF-lifting is applied.

  There is one special case, however, for IF-lifting.  Suppose that the
  given term is of the form [47m(IF v y z)[0m where [47mv[0m 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 [47my[0m nor [47mz[0m
  is of the form [47m(IF v W1 W2)[0m for that same [47mv[0m.  Then IF-lifting does
  not apply to the given term.

  We may now describe the IF-lifting-for-IF loop, which applies to
  terms of the form [47m(IF test tbr fbr)[0m where the algorithm has already
  produced [47mtest[0m, [47mtbr[0m, and [47mfbr[0m.  First, if [47mtest[0m is [47mnil[0m then we return
  [47mfbr[0m, while if [47mtest[0m is a non-[47mnil[0m constant or a call of [47mCONS[0m then we
  return [47mtbr[0m.  Otherwise, we see if IF-lifting applies.  If
  IF-lifting does not apply, then we return [47m(IF test tbr fbr)[0m.
  Otherwise, we apply IF-lifting to obtain a term of the form [47m(IF x y
  z)[0m, by lifting out the appropriate test.  Now we recursively apply
  the IF-lifting-for-IF loop to the term [47m(IF x y z)[0m, unless any of
  the following special cases apply.

      (i) If [47my[0m and [47mz[0m are the same term, then return [47my[0m.

      (ii) Otherwise, if [47mx[0m and [47mz[0m are the same term, then replace [47mz[0m by [47mnil[0m
      before recursively applying IF-lifting-for-IF.

      (iii) Otherwise, if [47mx[0m and [47my[0m are the same term and [47my[0m is known to be
      Boolean, then replace [47my[0m by [47mt[0m before recursively applying
      IF-lifting-for-IF.

      (iv) If [47mz[0m is [47mnil[0m and either [47mx[0m and [47my[0m are the same term or [47mx[0m is ``known
      to be Boolean'' and [47my[0m is [47mt[0m, then return [47mx[0m.

  NOTE: When a variable [47mx[0m is known to be Boolean, it is easy to see
  that the form [47m(IF x t nil)[0m is always reduced to [47mx[0m by this
  algorithm.

  (B4) [3mThe ACL2 BDD algorithm[0m

  We are now ready to present the BDD algorithm for ACL2.  It is given
  an ACL2 [term], [47mx[0m, as well as an association list [47mva[0m that maps
  variables to terms, including all variables occurring in [47mx[0m.  We
  maintain the invariant that whenever a variable is mapped by [47mva[0m to
  a term, that term has already been constructed by the algorithm,
  except: initially [47mva[0m 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 [term]
  that is not a [bdd] term (as defined above in (A2)), it aborts
  instead.  Thus, whenever the algorithm completes without aborting,
  it creates a [bdd] term.

      If [47mx[0m is a variable, return the result of looking it up in [47mva[0m.

      If [47mx[0m is a constant, return [47mx[0m.

      If [47mx[0m is of the form [47m(IF test tbr fbr)[0m, then first run the algorithm
      on [47mtest[0m with the given [47mva[0m to obtain [47mtest'[0m.  If [47mtest'[0m is [47mnil[0m,
      then return the result [47mfbr'[0m of running the algorithm on [47mfbr[0m
      with the given [47mva[0m.  If [47mtest'[0m is a constant other than [47mnil[0m, or
      is a call of [47mCONS[0m, then return the result [47mtbr'[0m of running the
      algorithm on [47mtbr[0m with the given [47mva[0m.  If [47mtbr[0m is identical to
      [47mfbr[0m, return [47mtbr[0m.  Otherwise, return the result of applying the
      IF-lifting-for-IF loop (described above) to the term [47m(IF test'
      tbr' fbr')[0m.

      If [47mx[0m is of the form [47m(IF* test tbr fbr)[0m, then compute the result
      exactly as though [47m[if][0m were used rather than [47m[if*][0m, except that
      if [47mtest'[0m is not a constant or a call of [47mCONS[0m (see paragraph
      above), then abort the BDD computation.  Informally, the tests
      of [47m[if*][0m terms are expected to ``resolve.'' NOTE: This
      description shows how [47m[if*][0m can be used to implement
      conditional rewriting in the BDD algorithm.

      If [47mx[0m is a [47mLAMBDA[0m expression [47m((LAMBDA vars body) . args)[0m (which often
      corresponds to a [47m[let][0m term; see [let]), then first form an
      alist [47mva'[0m by binding each [47mv[0m in [47mvars[0m to the result of running
      the algorithm on the corresponding member of [47margs[0m, with the
      current alist [47mva[0m.  Then, return the result of the algorithm on
      [47mbody[0m in the alist [47mva'[0m.

      Otherwise, [47mx[0m is of the form [47m(f x1 x2 ... xn)[0m, where [47mf[0m is a function
      symbol other than [47m[if][0m or [47m[if*][0m.  In that case, let [47mxi'[0m be the
      result of running the algorithm on [47mxi[0m, for [47mi[0m from 1 to [47mn[0m, using
      the given alist [47mva[0m.  First there are a few special cases.  If [47mf[0m
      is [47m[equal][0m then we return [47mt[0m if [47mx1'[0m is syntactically identical
      to [47mx2'[0m (where this test is very fast; see (B6) below); we
      return [47mx1'[0m if it is known to be Boolean and [47mx2'[0m is [47mt[0m; and
      similarly, we return [47mx2'[0m if it is known to be Boolean and [47mx1'[0m
      is [47mt[0m.  Next, if each [47mxi'[0m is a constant and the
      [47m:[0m[47m[executable-counterpart][0m of [47mf[0m is enabled, then the result is
      obtained by computation.  Next, if [47mf[0m is [47m[booleanp][0m and [47mx1'[0m is
      known to be Boolean, [47mt[0m is returned.  Otherwise, we proceed as
      follows, first possibly swapping the arguments if they are out
      of (the BDD term) order and if [47mf[0m is known to be commutative
      (see below).  If a BDD rewrite rule (as defined above) matches
      the term [47m(f x1'... xn')[0m, then the most recently stored such
      rule is applied.  If there is no such match and [47mf[0m is a
      BDD-constructor, then we return [47m(f x1'... xn')[0m.  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 [47m(f x1'... xn')[0m.
      Otherwise we apply IF-lifting to [47m(f x1'... xn')[0m to obtain a
      term [47m(IF test tbr fbr)[0m; but we aren't done yet.  Rather, we run
      the BDD algorithm (using the same alist) on [47mtbr[0m and [47mfbr[0m to
      obtain terms [47mtbr'[0m and [47mfbr'[0m, and we return [47m(IF test tbr' fbr')[0m
      unless [47mtbr'[0m is syntactically identical to [47mfbr'[0m, in which case
      we return [47mtbr'[0m.

  When is it the case that, as said above, ``[47mf[0m is known to be
  commutative''?  This happens when an enabled rewrite rule is of the
  form [47m(EQUAL (f X Y) (f Y X))[0m.  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 [47m(+ x 1)[0m.
  Other than that situation, one cannot expect to predict accurately
  when the arguments of commutative operators will be swapped.

  (B5) Soundness and Completeness of the ACL2 BDD algorithm

  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.

  [31;1mClaim[0m (Soundness).  If the ACL2 BDD algorithm runs to completion on
  an input term [47mt0[0m, then it produces a result that is provably equal
  to [47mt0[0m.

  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.

  Let us start our discussion of completeness by recalling the theorem
  proved above in (A4).

  [31;1mTheorem[0m.  Suppose that [47mt1[0m and [47mt2[0m are canonical BDD terms that contain
  no function symbols other than [47mIF[0m and [47mCONS[0m.  Also suppose that
  [47m(EQUAL t1 t2)[0m is a theorem.  Then [47mt1[0m and [47mt2[0m are syntactically
  identical.

  Below we show how this theorem implies the following completeness
  property of the ACL2 BDD algorithm.  We continue to assume that
  [47mCONS[0m is the only BDD-constructor.

  [31;1mClaim[0m (Completeness).  Suppose that [47mt1[0m and [47mt2[0m 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 [47mIF[0m and [47mCONS[0m.  Then the
  algorithm returns the same term for both [47mt1[0m and [47mt2[0m, and the
  algorithm reduces [47m(EQUAL t1 t2)[0m to [47mt[0m.

  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 [47mu1[0m and [47mu2[0m obtained by
  running the algorithm on [47mt1[0m and [47mt2[0m, respectively, are provably
  equal to [47mt1[0m and [47mt2[0m, respectively, by the Soundness Claim.  It
  follows that [47mu1[0m and [47mu2[0m are provably equal to each other.  Since
  these terms contain no function symbols other than [47mIF[0m or [47mCONS[0m, by
  hypothesis, the Claim now follows from the Theorem above together
  with the following lemma.

  [31;1mLemma[0m.  Suppose that the result of running the ACL2 BDD algorithm on
  a top-level term [47mt0[0m is a term [47mu0[0m that contains only the function
  symbols [47mIF[0m and [47mCONS[0m, where all variables of [47mt0[0m are known to be
  Boolean.  Then [47mu0[0m is a canonical BDD term.

  Proof: left to the reader.  Simply follow the definition of the
  algorithm, with a separate argument for the IF-lifting-for-IF loop.

  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
  [47mboolean-listp-forward[0m (you can see it using [47m:[0m[47m[pe][0m) to try to
  establish this assumption, if your theorem has a form such as the
  following.

    (let ((x (list x0 x1 ...))
          (y (list y0 y1 ...)))
      (implies (and (boolean-listp x)
                    (boolean-listp y))
               ...))

  Moreover, the [47m:BDD[0m hint can be used to force the prover to abort if
  it cannot check that the indicated variables are known to be
  Boolean; see [hints].

  Finally, consider the effect in practice of the assumption that the
  terms resulting from application of the algorithm contain calls of
  [47mIF[0m and [47mCONS[0m only.  Typical use of BDDs in ACL2 takes place in a
  theory (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 [47m(CONS a x)[0m, while another may say
  how to expand when that argument is [47mnil[0m).  (See for example the
  rules [47mappend-cons[0m and [47mappend-nil[0m in the documentation for [47m[if*][0m.)
  We leave it to future work to formulate a theorem that guarantees
  that the BDD algorithm produces terms containing calls only of [47mIF[0m
  and [47mCONS[0m assuming a suitably ``complete'' collection of rewrite
  rules.

  (B6) [3mEfficiency considerations[0m

  Following Bryant's algorithm, we use a graph representation of
  [term]s created by the BDD algorithm's computation.  This
  representation enjoys some important properties.

      (Time efficiency) The test for syntactic equality of BDD terms is
      very fast.

      (Space efficiency) Equal BDD data structures are stored identically
      in memory.

  [3mImplementation note.[0m The representation actually uses a sort of hash
  table for BDD terms that is implemented as an ACL2 1-dimensional
  array.  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 [bdd] for the reference.")
 (BDD-INTRODUCTION
  (BDD)
  "Examples illustrating the use of BDDs in ACL2

  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 [if*].

  Let us begin with a really simple example.  (We will explain the [47m:bdd[0m
  hint [47m(:vars nil)[0m below.)

    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 !>

  The [47m:bdd[0m hint [47m(:vars nil)[0m 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.

  Here is a more interesting example.

    (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)))))

  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 [47m:bdd[0m hint!  This observation is a bit misleading
  perhaps, since the theorem for arbitrary [47mx[0m,

    (thm
     (implies (boolean-listp x)
              (equal (v-not (v-not x)) x)))

  only takes about 1.5 times as long as the [47m:bdd[0m 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.

  Finally, consider the preceding example, with a [47m:bdd[0m hint of (say)
  [47m(:vars nil)[0m, but with the rewrite rule [47mv-not-cons[0m above disabled.
  In that case, the proof fails, as we see below.  That is because
  the BDD algorithm in ACL2 uses hypothesis-free [47m:[0m[rewrite] rules,
  [47m:[0m[47m[executable-counterpart][0m[47ms[0m, and nonrecursive definitions, but it
  does not use recursive definitions.

  Notice that when we issue the [47m(show-bdd)[0m command, the system's
  response clearly shows that we need a rewrite rule for simplifying
  terms of the form [47m(v-not (cons ...))[0m.

    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 !>

  The term that has caused the BDD algorithm to abort is thus [47m(V-NOT
  X)[0m, where [47mX[0m has the value [47m(LIST X0 X1 X2 X3 X4 X5 ...)[0m, i.e., [47m(CONS
  X0 (LIST X1 X2 X3 X4 X5 ...))[0m.  Thus, we see the utility of
  introducing a rewrite rule to simplify terms of the form [47m(V-NOT
  (CONS ...))[0m.  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 [47m(show-bdd)[0m and use the result as advice that suggests the
  left hand side of a rewrite rule.

  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 [47mshow-bdd[0m 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 [47mx[0m is
  bound to the 4-element list [47m(list x0 x1 x2 x3)[0m.

    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 !>

  See [if*] for another example.")
 (BIBLIOGRAPHY
  (ABOUT-ACL2)
  "Reports about ACL2

  The ACL2 home page includes a {list of notes and reports about ACL2 |
  http://www.cs.utexas.edu/users/moore/publications/acl2-papers.html}.")
 (BINARY-*
  (* ACL2-BUILT-INS)
  "Multiplication function

  Completion Axiom ([47mcompletion-of-*[0m):

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

  [Guard] for [47m(binary-* x y)[0m:

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

  Notice that like all arithmetic functions, [47mbinary-*[0m treats
  non-numeric inputs as [47m0[0m.

  Calls of the macro [47m[*][0m expand to calls of [47mbinary-*[0m; see [*].")
 (BINARY-+
  (+ ACL2-BUILT-INS)
  "Addition function

  Completion Axiom ([47mcompletion-of-+[0m):

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

  [Guard] for [47m(binary-+ x y)[0m:

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

  Notice that like all arithmetic functions, [47mbinary-+[0m treats
  non-numeric inputs as [47m0[0m. Thus, the following are theorems.

    (thm (equal (+ (fix x) y) (+ x y)))
    (thm (equal (+ x (fix y)) (+ x y)))

  Calls of the macro [47m[+][0m expand to calls of [47mbinary-+[0m; see [+].")
 (BINARY-APPEND
  (APPEND ACL2-BUILT-INS)
  "[concatenate] two lists

  This binary function implements [47m[append][0m, which is a macro in ACL2.
  See [append]

  The [guard] for [47mbinary-append[0m requires the first argument to be a
  [47m[true-listp][0m.

  [31;1mFunction: [0m<binary-append>

    (defun binary-append (x y)
      (declare (xargs :guard (true-listp x)))
      (cond ((endp x) y)
            (t (cons (car x)
                     (binary-append (cdr x) y)))))")
 (BINARY-DF* (POINTERS) "See [df].")
 (BINARY-DF+ (POINTERS) "See [df].")
 (BINARY-DF-LOG (POINTERS) "See [df].")
 (BINARY-DF/ (POINTERS) "See [df].")
 (BIND-FREE
  (REWRITE LINEAR DEFINITION)
  "To bind free variables of a rewrite, definition, or linear rule

    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)))))

  General Forms:

    (BIND-FREE term var-list)
    (BIND-FREE term t)
    (BIND-FREE term)

  A rule which uses a [47mbind-free[0m hypothesis has similarities to both a
  rule which uses a [47m[syntaxp][0m hypothesis and to a [47m:[0m[47m[meta][0m rule.
  [47mBind-free[0m is like [47m[syntaxp][0m, in that it logically always returns [47mt[0m
  but may affect the application of a [47m:[0m[47m[rewrite][0m,
  [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[definition][0m, or [47m:[0m[47m[linear][0m rule when
  it is called at the top-level of a hypothesis.  It is like a
  [47m:[0m[47m[meta][0m rule, in that it allows the user to perform transformations
  of terms under programmatic control.

  Note that a [47mbind-free[0m 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
  [47mbind-free[0m, the user should be familiar with [47m[syntaxp][0m 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.  [47m[Trans][0m can be used to view this internal form.

  Just as for a [47m[syntaxp][0m hypothesis, there are two basic types of
  [47mbind-free[0m hypotheses.  The simpler type of [47mbind-free[0m hypothesis may
  be used as the nth hypothesis in a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, or
  [47m:[0m[47m[linear][0m rule whose [47m:[0m[47m[corollary][0m is [47m(implies (and hyp1 ... hypn
  ... hypk) (equiv lhs rhs))[0m provided [47mterm[0m is a term, [47mterm[0m contains
  at least one variable, and every variable occurring freely in [47mterm[0m
  occurs freely in [47mlhs[0m or in some [47mhypi[0m, [47mi<n[0m.  In addition, [47mterm[0m must
  not use any stobjs.  Later below we will describe the second type,
  an [3mextended[0m [47mbind-free[0m hypothesis, which is similar except that it
  may use [47m[state][0m and [47m[mfc][0m.  Whether simple or extended, a [47mbind-free[0m
  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.

  We begin our description of [47mbind-free[0m by examining the first example
  above in some detail.

  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

    (DEFTHM THE-HARD-WAY-2-1
       (EQUAL (EQUAL (+ A X B)
                     (+ X C))
              (EQUAL (+ A B)
                     (FIX C))))

  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.)

  Consider the following definitions and theorem:

    (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)))))

  How is this rule applied to the following term?

    (equal (+ 3 (expt a n) (foo a c))
           (+ (bar b) (expt a n)))

  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 [47m:[0m[47m[trans][0m
  one can see that the term is stored internally as

    (equal (binary-+ '3
                     (binary-+ (expt a n) (foo a c)))
           (binary-+ (bar b) (expt a n))).

  When ACL2 attempts to apply [47mcancel-matching-addends-equal[0m 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:

    ((LHS . (binary-+ '3
                       (binary-+ (expt a n) (foo a c))))
     (RHS . (binary-+ (bar b) (expt a n)))).

  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:

    (RATIONALP (binary-+ '3
                          (binary-+ (expt a n) (foo a c)))).

  Let us assume that the first two hypotheses rewrite to [47mt[0m.  How do we
  relieve the [47mbind-free[0m hypothesis?  Just as for a [47m[syntaxp][0m
  hypothesis, ACL2 evaluates [47m(find-match-in-plus-nests lhs rhs)[0m in an
  environment where [47mlhs[0m and [47mrhs[0m are instantiated as determined by the
  substitution.  In this case we evaluate

    (FIND-MATCH-IN-PLUS-NESTS '(binary-+ '3
                                          (binary-+ (expt a n) (foo a c)))
                              '(binary-+ (bar b) (expt a n))).

  Observe that, just as in the case of a [47m[syntaxp][0m hypothesis, we
  substitute the quotation of the variables bindings into the term to
  be evaluated.  See [syntaxp] for the reasons for this.  The result
  of this evaluation, [47m((X . (EXPT A N)))[0m, is then used to extend the
  substitution alist:

    ((X . (EXPT A N))
     (LHS . (binary-+ '3
                       (binary-+ (expt a n) (foo a c))))
     (RHS . (binary-+ (bar b) (expt a n)))),

  and this extended substitution determines
  [47mcancel-matching-addends-equal[0m's result:

    (EQUAL (+ (- X) LHS) (+ (- X) RHS))
    ==>
    (EQUAL (+ (- (EXPT A N)) 3 (EXPT A N) (FOO A C))
           (+ (- (EXPT A N)) (BAR B) (EXPT A N))).

  Question: What is the internal form of this result?
  Hint: Use [47m:[0m[47m[trans][0m.

  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 [47mx[0m, under programmatic control.  Note that other mechanisms
  such as the binding of [free-variables] may also extend the
  substitution alist.

  Just as for a [47m[syntaxp][0m test, a [47mbind-free[0m form signals failure by
  returning [47mnil[0m.  However, while a [47m[syntaxp][0m test signals success by
  returning true, a [47mbind-free[0m 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 --- 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 [47mterm[0m 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.

  There is also a second, optional, [47mvar-list[0m argument to a [47mbind-free[0m
  hypothesis.  If provided, it must be either [47mt[0m, [47mnil[0m, or a non-empty
  list of variables.  If it is not provided, it defaults to [47mt[0m; and it
  is also treated as [47mt[0m if the value provided is [47mnil[0m.  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 [47mterm[0m: 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 [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 [47mvar-list[0m is [47mt[0m (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.

  An extended [47mbind-free[0m hypothesis is similar to the simple type
  described above, but it uses two additional variables, [47mmfc[0m and
  [47mstate[0m, 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 [47mterm[0m: first [47mmfc[0m, then [47mstate[0m.  These two variables give
  access to the functions [47mmfc-[0mxxx; see [extended-metafunctions].  As
  described there, [47mmfc[0m is bound to the so-called metafunction-context
  and [47mstate[0m to ACL2's [47m[state][0m.  See [bind-free-examples] for examples
  of the use of these extended [47mbind-free[0m hypotheses.

  [31;1mSECTION[0m: Returning a list of alists.

  As promised above, we conclude with a discussion of the case that
  evaluation of the [47mbind-free[0m term produces a list of alists, [47mx[0m,
  rather than a single alist.  In this case each member [47mb[0m of [47mx[0m is
  considered in turn, starting with the first and proceeding through
  the list.  Each such [47mb[0m is handled exactly as discussed above, as
  though it were the result of evaluating the [47mbind-free[0m term.  Thus,
  each [47mb[0m extends the current variable binding alist, and all
  remaining hypotheses are then relieved, as though [47mb[0m had been the
  value obtained by evaluating the [47mbind-free[0m term.  As soon as one
  such [47mb[0m leads to successful relieving of all remaining hypotheses,
  the process of relieving hypotheses concludes, so no further
  members of [47mx[0m are considered.

  We illustrate with a simple pedagogical example.  First introduce
  functions [47mp1[0m and [47mp2[0m such that a rewrite rule specifies that [47mp2[0m
  implies [47mp1[0m, but with a free variable.

    (defstub p1 (x) t)
    (defstub p2 (x y) t)

    (defaxiom p2-implies-p1
      (implies (p2 x y)
               (p1 x)))

  If we add the following axiom, then [47m(p1 x)[0m follows logically for all
  [47mx[0m.

    (defaxiom p2-instance
      (p2 v (cons v 4)))

  Unfortunately, evaluation of [47m(thm (p1 a))[0m fails, because ACL2 fails
  to bind the free variable [47my[0m in order to apply the rule [47mp2-instance[0m.

  Let's define a function that produces a list of alists, each binding
  the variable [47my[0m.  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.

    (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)))))

  The following rewrite rule uses [47mbind-free[0m to return a list of
  candidate alists binding [47my[0m.

    (defthm p2-implies-p1-better
      (implies (and (bind-free (my-alists x)
                               (y)) ; the second argument, (y), is optional
                    (p2 x y))
               (p1 x)))

  Now the proof succeeds for [47m(thm (p1 a))[0m.  Why?  When ACL2 applies the
  [47mrewrite[0m rule [47mp2-implies-p1-better[0m, it evaluates [47mmy-alists[0m, as we
  can see from the following [trace], to bind [47my[0m in three different
  alists.

    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.

  The first alist, binding [47my[0m to [47m(cons a '3)[0m, fails to allow the
  hypothesis [47m(p2 x y)[0m to be proved.  But the next binding of [47my[0m, to
  [47m(cons a '4)[0m, succeeds: then the current binding alist is [47m((x . a)
  (y . (cons a '4)))[0m, for which the hypothesis [47m(p2 x y)[0m rewrites to
  true using the rewrite rule [47mp2-instance[0m.


Subtopics

  [Bind-free-examples]
      Examples pertaining to [47m[bind-free][0m hypotheses")
 (BIND-FREE-EXAMPLES
  (BIND-FREE)
  "Examples pertaining to [47m[bind-free][0m hypotheses

  See [bind-free] for a basic discussion of the use of [47mbind-free[0m to
  control rewriting.

  Note that the examples below all illustrate the common case in which
  a [47mbind-free[0m hypothesis generates a binding alist.  See [bind-free],
  in particular the final section, for a discussion of the case that
  instead a list of binding alists is generated.

  We give examples of the use of [47m[bind-free][0m hypotheses from the
  perspective of a user interested in reasoning about arithmetic, but
  it should be clear that [47m[bind-free][0m can be used for many other
  purposes also.

  EXAMPLE 1: Cancel a common factor.

    (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)))))

  EXAMPLE 2: Pull integer summand out of floor.  Note: This example has
  an [3mextended[0m [47m[bind-free][0m hypothesis, which uses the term
  [47m(find-int-in-sum sum mfc state)[0m.

    (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)))))

  EXAMPLE 3: Simplify terms such as (equal (+ a (* a b)) 0)

    (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))))")
 (BITP
  (NUMBERS ACL2-BUILT-INS)
  "A recognizer for the set of bits, {0,1}

  [47mBitp[0m returns [47mt[0m if and only its argument is [47m0[0m or [47m1[0m, and [47mnil[0m otherwise.

  Note that this is a predicate form of the [type-spec] declaration
  [47m(TYPE BIT b)[0m.

  [31;1mFunction: [0m<bitp>

    (defun bitp (x)
      (declare (xargs :guard t))
      (or (eql x 0) (eql x 1)))")
 (BODY (POINTERS)
       "See [system-utilities].")
 (BOOK-COMPILED-FILE
  (BOOKS-REFERENCE)
  "Creating and loading of compiled and expansion files for [books]

  An effect of [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 [guard] for a discussion; also see
  [compilation].

  By default, the [47m[certify-book][0m command compiles the book that it
  certifies.  see [certify-book] for how to control this behavior.

  By default, the [47m[include-book][0m 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
  [47m:load-compiled-file t[0m is specified by the [47m[include-book][0m form), and
  its existence is required in order for [47m[include-book][0m to create a
  book's compiled file, as described below.

  Most users can skip the remainder of this documentation topic, which
  addresses the uncommon activity of using [47m[include-book][0m to compile
  books.

  [47mInclude-book[0m can be made to compile a book by supplying its keyword
  argument [47m:load-compiled-file[0m the value [47m:comp[0m.  However, a compiled
  file can only be produced if there is already an [3mexpansion file[0m
  that is at least as recent as the book's [certificate].  Such a
  file, whose name happens to be the result of concatenating the
  string [47m\"@expansion.lsp\"[0m to the book's filename after removing the
  [47m\".lisp\"[0m suffix, is created by [47m[certify-book][0m when state global
  variable [47m'save-expansion-file[0m has a non-[47mnil[0m value.  That will be
  the case if ACL2 started up when environment variable
  [47mACL2_SAVE_EXPANSION[0m was [47mt[0m (or any value that is not the empty
  string and whose [47m[string-upcase][0m is not [47m\"NIL\"[0m), until the time (if
  any) that [47m'save-expansion-file[0m is assigned a different value by the
  user.  In most respects, the [47m:comp[0m setting is treated exactly the
  same as [47m:warn[0m; 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.

  One can thus, for example, compile books for several different host
  Lisps --- 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 ``[47mmake regression[0m'' in the
  [47macl2-sources/[0m directory, after setting environment variable
  [47mACL2_SAVE_EXPANSION[0m to [47mt[0m, and then moving to the [47mbooks[0m directory
  and executing the appropriate `make' commands to compile the books
  (targets [47mfasl[0m, [47mo[0m, and so on, according to the compiled file
  extension for the host Lisp).

  We conclude by saying more about the [47m:load-compiled-file[0m argument of
  [47m[include-book][0m.  We assume that [state] global [47m'compiler-enabled[0m
  has a non-[47mnil[0m value; otherwise [47m:load-compiled-file[0m is always
  treated as [47mnil[0m.

  We do not consider raw mode below (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 [47m:load-compiled-file[0m argument is [47mnil[0m,
  or for each of the expansion and compiled files, either it does not
  exist or it is out of date with respect to the [47m.cert[0m file).

  The [47m:load-compiled-file[0m argument is not recursive: calls of
  [47minclude-book[0m that are inside the book supplied to [47minclude-book[0m use
  their own [47m:load-compiled-file[0m arguments.  However, those subsidiary
  [47minclude-book[0m calls can nevertheless be sensitive to the
  [47m:load-compiled-file[0m arguments of enclosing [47minclude-book[0m calls, as
  follows.  If [47m:load-compiled-file[0m has value [47mt[0m, then every subsidiary
  [47minclude-book[0m 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 [47m[include-book][0m 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 [47m[include-book][0m is aborted for which keyword argument
  [47m:load-compiled-file[0m has value [47mt[0m, then an error occurs.

  When loading a book's compiled file or expansion file, [47mFILE[0m, it is
  possible to encounter an [47m[include-book][0m form for a book that has no
  suitable compiled file or expansion file.  In that case, the load
  of [47mFILE[0m is aborted at that point.  Similarly, the load of [47mFILE[0m is
  aborted in the case that this [47minclude-book[0m form has a suitable
  compiled file or expansion file whose load is itself aborted.
  Thus, whenever any [47minclude-book[0m aborts, so do all of its parent
  [47minclude-book[0ms, up the chain.  Such an abort causes an error when
  the [47minclude-book[0m form specifies a [47m:load-compiled-file[0m value of [47mt[0m.")
 (BOOK-CONTENTS
  (BOOKS-TOUR)
  "Restrictions on the forms inside [books]

    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))))

  The first form in a book must be [47m(in-package \"pkg\")[0m where [47m\"pkg\"[0m 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.,
  [47m[defun][0ms, [47m[defthm][0ms, etc., some of which may be marked [47m[local][0m.
  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 ``[47m[local][0m'' and
  ``non-local'' [events] of a book.

  Because [47m[in-package][0m is not an embedded event form, the only
  [47m[in-package][0m in a book is the initial one.  Because [47m[defpkg][0m is not
  an embedded event form, a book can never contain a [47m[defpkg][0m form.
  Because [47m[include-book][0m is an embedded event form, [books] may
  contain references to other [books].  This makes [books] structured
  objects.

  When the forms in a book are read from the file, they are read with
  [47m[current-package][0m set to the package named in the [47m[in-package][0m form
  at the top of the file.  The effect of this is that all symbols are
  [intern]ed in that package, except those whose packages are given
  explicitly with the ``::'' notation.  For example, if a book begins
  with [47m(in-package \"ACL2-X\")[0m and then contains the form

    (defun fn (x)
      (acl2::list 'car x))

  then [47m[defun][0m, [47mfn[0m, [47mx[0m, and [47m[car][0m are all [intern]ed in the [47m\"ACL2-X\"[0m
  package.  I.e., it is as though the following form were read
  instead:

    (acl2-x::defun acl2-x::fn (acl2-x::x)
        (acl2::list 'acl2-x::car acl2-x::x)).

  Of course, [47macl2-x::defun[0m would be the same symbol as [47macl2::defun[0m if
  the [47m\"ACL2-X\"[0m package imported [47macl2::defun[0m.

  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 [books] are completely avoided.  This permits the
  construction of useful logical [world]s by the successive inclusion
  of many [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 [47mlocal[0m; see [local].

  How does [47m[include-book][0m know the definitions of the packages used in
  a book, since [47m[defpkg][0ms cannot be among the forms?  More generally,
  how do we know that the forms in a book will be admissible in the
  host logical [world] of an [47m[include-book][0m?  See [certificate] for
  answers to these questions.")
 (BOOK-EXAMPLE
  (BOOKS-TOUR)
  "How to create, certify, and use a simple book

  Suppose you have developed a sequence of admissible [events] which
  you want to turn into a book.  We call this ``publishing'' the
  book.  This note explains how to do that.

  A key idea of [books] is that they are ``incremental'' in the sense
  that when you include a book in a host logical [world], the [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
  [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 [books] and
  packages have a very tenuous formal connection (every book must
  start with an [47m[in-package][0m), 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.

  Just to be concrete, let's suppose you have already gotten ACL2 to
  accept the following sequence of [command]s, starting in the ACL2
  initial [state].

    (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)))

  Observe that the first form above defines a package (which imports
  the symbols defined in CLTL such as [47m[if][0m and [47m[cons][0m and the symbols
  used to [command] ACL2 such as [47m[defun][0m and [47m[defthm][0m).  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: [47m[defun][0ms and [47m[defthm][0ms in this case.

  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 [world] --- although
  you might, of course, start your sequence of [events] with some
  [47m[include-book][0ms to build a more elaborate [world].

  The first step towards publishing a book containing the results above
  is to create a file that starts with the [47m[in-package][0m and then
  contains the rest of the forms.  Let's call that file
  [47m\"my-book.lisp\"[0m.  The name is unimportant, except it must end with
  [47m\".lisp\"[0m.  If there are [events] that you do not wish to be
  available to the user of the book --- e.g., lemmas you proved on
  your way toward proving the main ones --- you may so mark them by
  enclosing them in [47m[local][0m forms.  See [local].  Let us suppose you
  wish to hide [47mrev-app-hack[0m above.  You may also add standard Lisp
  comments to the file.  The final content of [47m\"my-book.lisp\"[0m might
  be:

    ; 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)))

  The file shown above [31;1mis[0m 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 [world]s.  Observe that
  the [47m[defpkg][0m 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.

  Since a book is just a source file typed by the user, ACL2 provides a
  mechanism for checking that the [events] are all admissible and
  then marking the file as checked.  This is called certification.
  To certify [47m\"my-book.lisp\"[0m you should first get into ACL2 with an
  initial [world].  Then, define the package needed by the book, by
  typing the following [47m[defpkg][0m to the ACL2 [prompt]:

    ACL2 !>(defpkg \"ACL2-MY-BOOK\"
                   (union-eq *common-lisp-symbols-from-main-lisp-package*
                             *acl2-exports*))

  Then execute the [command]:

    ACL2 !>(certify-book \"my-book\" 1 t) ; the `t' is in fact the default

  Observe that you do not type the [47m\".lisp\"[0m part of the file name.  For
  purposes of [books], the book's name is [47m\"my-book\"[0m and by the time
  all is said and done, there will be several extensions in addition
  to the [47m\".lisp\"[0m extension associated with it.

  The [47m1[0m tells [47m[certify-book][0m that you acknowledge that there is one
  command in this ``certification [world]'' (namely the [47m[defpkg][0m).
  To use the book, any prospective host [world] must be extended by
  the addition of whatever [command]s occurred before certification.
  It would be a pity to certify a book in a [world] containing junk
  because that junk will become the ``[portcullis]'' guarding
  entrance to the book.  The [47mt[0m above tells [47m[certify-book][0m that you
  wish to compile [47m\"my-book.lisp\"[0m also (but see [compilation] for an
  exception).  [47m[Certify-book][0m makes many checks but by far the most
  important and time-consuming one is that it ``proves'' every event
  in the file.

  When [47m[certify-book][0m is done it will have created two new files.  The
  first will be called [47m\"my-book.cert\"[0m and contains the
  ``[certificate]'' attesting to the admissibility of the [events] in
  [47m\"my-book.lisp\"[0m.  The [certificate] contains the [47m[defpkg][0m and any
  other forms necessary to construct the certification [world].  It
  also contains so-called [book-hash] values that are used to help
  you keep track of which version of [47m\"my-book.lisp\"[0m was certified.

  The second file that may be created by [47m[certify-book][0m is the compiled
  version of [47m\"my-book.lisp\"[0m and will have a name that is assigned by
  the host compiler (e.g., [47m\"my-book.o\"[0m in GCL, [47m\"my-book.fasl\"[0m in
  SBCL).  [47m[Certify-book][0m will also load this object file.  When
  [47m[certify-book][0m is done, you may throw away the logical [world] it
  created, for example by executing the [command] [47m:u[0m.

  To use the book later in any ACL2 session, just execute the event
  [47m(include-book \"my-book\")[0m.  This will do the necessary [47m[defpkg][0m,
  load the non-[47m[local][0m [events] in [47m\"my-book.lisp\"[0m and then may load
  the compiled code for the non-local functions defined in that file.
  Checks are made to ensure that the [certificate] file exists and
  describes the version of [47m\"my-book.lisp\"[0m 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 [compilation] for an exception).

  Since [47m[include-book][0m is itself an event, you may put such forms into
  other [books].  Thus it is possible for the inclusion of a single
  book to lead to the inclusion of many others.  The [book-hash]
  information maintained in [certificate]s helps deal with the
  version control problem of the referenced [books].  I.e., if this
  version of [47m\"my-book\"[0m is used during the certification of
  [47m\"your-book\"[0m, then the [certificate] for [47m\"your-book\"[0m includes the
  book-hash for this version of [47m\"my-book\"[0m.  If a later [47m(include-book
  \"your-book\")[0m finds a version of [47m\"my-book\"[0m 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 [47m[include-book][0m event,
  even for a book that appears to have a valid [certificate] (they
  can be forged, after all).  (See [certificate] for further
  discussion.)

  This concludes the example of how to create, certify and use a book.
  If you wish, you could now review the [documentation] for
  book-related topics (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
  [documentation] of [books].  See [book-name], following the pointer
  given at the conclusion.")
 (BOOK-HASH
  (BOOKS)
  "Assigning ``often unique'' fingerprints to [books]

  ACL2 provides a [3mcertification[0m process for recording into a
  [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 ([47m.lisp[0m file),
  its file size (in bytes) and its write-date.

  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 [checksum].  Nevertheless, the (default) use
  of book-hash alists may be worthwhile, in spite of the decreased
  security, because of faster times for [47m[certify-book][0m and
  [47m[include-book][0m when using book-hash alists instead of checksums.
  If you want to use checksums, however, there are these two ways to
  do so.

    * Before starting ACL2, set environment variable [47mACL2_BOOK_HASH_ALISTP[0m
      to [47mNIL[0m (or [47mnil[0m; actually it suffices that [47m[string-upcase][0m
      applied to the indicated string is [47m\"NIL\"[0m).  A common way to get
      this effect is to supply the argument [47mACL2_BOOK_HASH_ALISTP=NIL[0m
      with your [47m\"make\"[0m command.

    * After starting ACL2, set [state] global variable [47mbook-hash-alistp[0m to
      [47mnil[0m, e.g.: [47m(assign book-hash-alistp nil)[0m.  (Set this variable
      to [47mt[0m to revert to the default behavior: [47m(assign
      book-hash-alistp t)[0m.)

  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 [certificate]
  itself.  (Book-hash alists also ignore [portcullis] [command]s and
  the corresponding [47m.acl2x[0m file, if any (see [set-write-ACL2x]); but
  we don't exploit these facts in this example.)  We start with the
  following book, [47m\"foo.lisp\"[0m.

    (in-package \"ACL2\")
    (make-event '(defun foo (x) (cons x x)))

  Now start ACL2 and run these commands.

    (assign book-hash-alistp t) ; a no-op, by default
    (certify-book \"foo\")
    (read-file \"foo.cert\" state)
    (quit)

  Next, replace the contents of [47m\"foo.cert\"[0m by the values in the list
  printed by the [47mread-file[0m form above (hence, without the outer
  parentheses).  Further edit that file by twice changing [47m(cons x x)[0m
  to [47mx[0m.  Also, update the write-date on the compiled file, e.g. with
  [47mtouch foo.dx64fsl[0m, if you want to avoid a warning.  Then submit
  [47m(include-book \"foo\")[0m.  We get the following contradictory behavior,
  without any warnings.

    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 !>

  For more information about connections between book-hash values and
  certification status, see [book-hash-mismatch].


Subtopics

  [Book-hash-mismatch]
      Deeming a book uncertified because of a [book-hash] mismatch")
 (BOOK-HASH-MISMATCH
  (BOOK-HASH)
  "Deeming a book uncertified because of a [book-hash] mismatch

  When [47m[include-book][0m is invoked, the specified book may be considered
  uncertified by ACL2 because its [book-hash] --- which by default is
  an alist specifying the book's size and write-date, but could be a
  checksum --- 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.

    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.

  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
  [47mfoo.lisp[0m stored into [47mfoo.cert[0m was 516310554.  But then [47mfoo.lisp[0m was
  edited (in this case, by adding a single newline character), and
  ACL2 complained because at [47minclude-book[0m time it computed a
  different book-hash for that book.

  The mismatch might occur on a book that is being included while
  including a superior book.  For example, suppose that the act of
  evaluating [47m(include-book \"bk1\")[0m triggers evaluation of the event
  [47m(include-book \"bk2\")[0m from [47mbk1.lisp[0m, which similarly in turn causes
  evaluation of the event [47m(include-book \"bk3\")[0m from [47mbk2.lisp[0m.  Now
  certify [47mbk3.lisp[0m, then [47mbk2.lisp[0m, and finally [47mbk1.lisp[0m.  So far, so
  good.  But now suppose we edit the lowest-level book, [47mbk3.lisp[0m.  We
  will likely get a warning (or error, if during book certification)
  such as the one displayed above when evaluating [47m(include-book
  \"bk1\")[0m, complaining that the book-hash for [47mbk3.lisp[0m has changed ---
  followed by warnings complaining about inclusions of uncertified
  books by superior books.

  There are several ways for a book-hash in a [47m.cert[0m 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 [47minclude-book[0m time; see [book-hash].

  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 [47m.cert[0m files.  The following example
  works fine, because there is no such conflict: the book [47m\"sub\"[0m is
  associated with a book-hash checksum in [47msub.cert[0m, which provides
  that same checksum as the book-hash value for [47m\"sub\"[0m in [47mtop.cert[0m;
  and the book [47m\"top\"[0m is associated with a book-hash alist in
  [47mtop.cert[0m.

    (certify-book \"sub\")
    (u)
    (assign book-hash-alistp t)
    (certify-book \"top\") ; contains the event (include-book \"sub\")
    (u)
    (include-book \"top\") ; no problem!

  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 [47m\"sub\"[0m in [47mtop.cert[0m, but at [47minclude-book[0m time the
  book-hash for [47m\"sub\"[0m in [47msub.cert[0m is an alist, not a checksum.

    (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\")

  That said, ACL2 does not care about the current value of state global
  [47mbook-hash-alistp[0m at [47minclude-book[0m time.  For example, the following
  works without error: ACL2 sees the checksum stored in [47msub.cert[0m, so
  at [47minclude-book[0m time it computes a checksum for the book [47m\"sub\"[0m, not
  an alist, even though [47m'book-hash-alistp[0m has value [47mt[0m.

    (assign book-hash-alistp nil)
    (certify-book \"foo\")
    (assign book-hash-alistp t)
    (include-book \"foo\")

  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, [47m\"foo.lisp\"[0m, containing the
  event [47m(include-book \"tools/remove-hyps\" :dir :system)[0m.  Suppose we
  have ACL2 executables [47macl2-cksum[0m and [47macl2-alist[0m, in different ACL2
  directories.  Also suppose that we have certified (disjoint copies
  of) the [community-books] with each of these ACL2 executables,
  where we used [47mACL2_BOOK_HASH_ALISTP=NIL[0m in our [47m\"make\"[0m command with
  [47macl2-cksum[0m but not with [47macl2-alist[0m.  Now suppose we certify
  [47m\"foo.lisp\"[0m using [47macl2-cksum[0m but then, in a session with [47macl2-alist[0m,
  we include that same book.  Then we will see a warning beginning as
  displayed below.  It complains that the book-hash required of
  [47mbooks/tools/remove-hyps.cert[0m according to [47mfoo.cert[0m --- which was
  created using [47macl2-cksum[0m --- differs from the book-hash in the
  [47m.cert[0m file of the copy of that book that is under the directory of
  the currently running ACL2, [47macl2-alist[0m.

    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;")
 (BOOK-MAKEFILES (POINTERS)
                 "See [books-certification].")
 (BOOK-NAME
  (BOOKS-TOUR)
  "Conventions associated with book-names

    Examples:
    \"list-processing\"
    \"/usr/home/smith/my-arith\"

  A [3mbook-name[0m is typically a string constant that represents a file.
  (Much later below we discuss other book-names that are not strings,
  namely, [sysfile]s; but till then we consider only strings.)  We
  elaborate book names by concatenating the ``connected book
  directory'' (see [cbd]) string on the left and perhaps a [47m\".lisp\"[0m
  ``extension'' on the right.  However, the connected book directory
  is not added if the book-name itself already represents an absolute
  file name.  Furthermore, [47m[include-book][0m and [47m[certify-book][0m
  temporarily reset the connected book directory to be the directory
  of the book being processed.  This allows [47m[include-book][0m forms to
  use relative pathnames without explicit mention of the enclosing
  book's directory.

  You may wish to read elsewhere for details of ACL2 file name
  conventions (see [pathname]), for a discussion of the filename that
  is the result of the elaboration described here (see
  [full-book-name]), and for details of the concept of the connected
  book directory (see [cbd]).  For details of how [47m[include-book][0m (see
  [include-book]) and [47m[certify-book][0m (see [certify-book]) use these
  concepts, see below.

  Often a book-name is simply the familiar name of the file.  (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 [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 [47m[include-book][0m.  For
  example, [47m[include-book][0m uses the [47m\".lisp\"[0m, [47m\".cert\"[0m and possibly a
  compiled file extension (like [47m\".fasl\"[0m) of the book-name.

  A book-name is elaborated into a [full-book-name] by [47m[include-book][0m
  and [47m[certify-book][0m.  This elaboration is sensitive to the
  ``connected book directory.'' The connected book directory is an
  absolute filename string (see [pathname]) that is part of the ACL2
  [47m[state][0m.  (You may wish to see [cbd] and to see [set-cbd] --- 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.

  Note that it is possible that the book-name includes some partial
  specification of the directory.  For example, if the connected book
  directory is [47m\"/usr/home/smith/\"[0m then the book-name
  [47m\"project/task-1/arith\"[0m is a book-name that will be elaborated to

    \"/usr/home/smith/project/task-1/arith.lisp\".

  Observe that while the [events] in this [47m\"arith\"[0m book are being
  processed the connected book directory will temporarily be set to

    \"/usr/home/smith/project/task-1/\".

  Thus, if the book requires other [books], e.g.,

    (include-book \"naturals\")

  then it is not necessary to specify the directory on which they
  reside provided that directory is the same as the superior book.

  This inheritance of the connected book directory and its use to
  elaborate the names of inferior [books] makes it possible to move
  [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 [books] to different
  filesystems that use a different operating system than the one
  under which the original certification was performed.

  The [47m\".cert\"[0m extension of a book, if it exists, is presumed to contain
  the most recent [certificate] for the book.  See [certificate] (or,
  if you are on the guided tour, wait until the tour gets there).

  Finally we mention another kind of book-name: a [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
  [certificate] files, but is rarely visible to users.  If you run
  across a sysfile and want to understand more about it, see
  [sysfile].

  See [book-contents] to continue the guided tour.")
 (BOOKDATA
  (BOOKS)
  "Write small files with meta-data about certified [books]

  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 [community-books] directory
  [47mbooks/tools/book-conflicts/[0m 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.

  If the book has the name [47mBK[0m, then the output file is named
  [47mBK__bookdata.out[0m.  That file is generated in the same directory as
  [47mBK[0m, by certifying [47mBK[0m when [state] global [47m'write-bookdata[0m has a
  non-[47mnil[0m value, for example as follows.

    (assign write-bookdata t)
    (certify-book \"BK\" ...)

  Alternatively, one may set environment variable [47mACL2_WRITE_BOOKDATA[0m
  to any non-empty value to cause [47mBK__bookdata.out[0m to be written,
  with one exception, namely: when the value of state global
  [47mwrite-bookdata[0m is [47m:never[0m.

  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.

     (\"...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
    )

  The first entry in the form will always be the [full-book-name] of
  the certified book, [47mBK[0m, possibly in [sysfile] format.

  Subsequent values in the form are based on [events] introduced by
  including [47mBK[0m.  For various values of [47mxxx[0m as described below,
  [47mport-[0m[3mxxx[0m[47m-val[0m is a list of values corresponding to [events]
  introduced in the certification [world] for [47mBK[0m (see [portcullis]),
  and [3mxxx[0m[47m-val[0m is a list of values corresponding to [events]
  introduced non-[47m[local][0mly by [47mBK[0m.  These lists include only
  ``top-level'' events, not those that are introduced by a book
  included either in [47mBK[0m or its certification world.

  [47mPkgs-val[0m 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 [47mpkgs-val[0m and [47mport-pkgs-val[0m.  Both
  [47mport-book-val[0m and [47mbook-val[0m are lists of [full-book-name]s of
  included books.  The values associated with the other keywords are,
  themselves, association lists (see [alistp]) such that each key is
  a package name, which is associated with a list of [symbol-name]s
  for symbols in that package that are introduced for that keyword.
  For example, [47mfns-val[0m may be the alist

    ((\"ACL2\" \"F1\" \"F2\")
     (\"MY-PKG\" \"G1\" \"G2\"))

  if the function symbols introduced in the book are [47mF1[0m and [47mF2[0m in the
  [47m\"ACL2\"[0m package, as well as [47mG1[0m and [47mG2[0m in the [47m\"MY-PKG\"[0m package.

  We next explain what kinds of symbols are introduced for each keyword
  [47m:xxx[0m.  Each such symbol would be associated with either the keyword
  [47m:port-xxx[0m or the keyword [47m:xxx[0m depending respectively on whether the
  symbol is introduced at the top level of the certification world
  for [47mBK[0m or [47mBK[0m itself.

    [47m:CONSTS[0m
      constant symbol introduced by [47mdefconst[0m
    [47m:FNS[0m
      function symbol: introduced by [47mdefun[0m, [47mdefuns[0m, or [47mdefchoose[0m; or
      constrained (by an [47m[encapsulate][0m event)
    [47m:LABELS[0m
      symbol introduced by [47mdeflabel[0m
    [47m:MACROS[0m
      macro name introduced by [47mdefmacro[0m
    [47m:STOBJS[0m
      [47mstobj[0m name introduced by [47mdefstobj[0m or [47mdefabsstobj[0m
    [47m:THEORIES[0m
      theory name introduced by [47mdeftheory[0m
    [47m:THMS[0m
      theorem name, which may be introduced by [47mdefthm[0m or a macro call
      expanding to a call of [47mdefthm[0m, such as see [defequiv] or
      [47mdefaxiom[0m; but may be introduced by [47m[defpkg][0m, for example, with
      name [47m\"MYPKG-PACKAGE\"[0m if the package name is [47m\"MYPKG\"[0m

  Our hope is that people in the ACL2 community will generate and use
  this data to improve the ACL2 [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 [47m{DIR}[0m 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
  [47mmake[0m options like [47m-j 8[0m and [47mmake[0m variable settings like
  [47mACL2={DIR}/my-saved_acl2[0m; see [books-certification] for details.

    make regression-fresh \\
    ACL2_CUSTOMIZATION={DIR}/acl2-customization-files/bookdata.lisp")
 (BOOKS
  (ACL2)
  "[3mBooks[0m are files of ACL2 [events]---they are the main way to split up
  large ACL2 developments into separate modules.

  This [documentation] topic is about ACL2 {source code |
  https://en.wikipedia.org/wiki/Source_code} files.  However, there
  are also {traditional, paper books |
  http://www.cs.utexas.edu/users/moore/publications/acl2-papers.html#Books}
  published about ACL2 and its applications.

  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 [3mcommunity
  books[0m, which provide useful tools and lemmas to build upon.  See
  [community-books] for more information, including how to
  contribute.


Introduction

  A [31;1mbook[0m is a file of ACL2 forms.  Books are prepared entirely by the
  user of the system, i.e., they are [3msource files[0m not [3mobject files[0m.
  Some of the forms in a book are marked [47m[local][0m and the others are
  considered ``non-local.''

  [47m[Include-book][0m lets you load a book into any ACL2 [world].  A
  successful [47minclude-book[0m extends the logic of the host [world] by
  adding just the non-local [events] in the book.  Ordinarily, you
  might include a variety of books to load all of their definitions
  and rules.

  Successful book inclusion is consistency preserving, provided that
  the book itself is consistent, as discussed later.  However,
  [47m[include-book][0m assumes the [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!

  [47m[Certify-book][0m lets you [3mcertify[0m a book to guarantee that its
  successful inclusion is consistency preserving.  During
  certification, both the [47m[local][0m and non-local forms are processed.
  This lets you mark as [47m[local][0m any [events] you need for
  certification, but that you want to hide from users of the
  book---e.g., the hacks, crocks, and kludges on the way to a good
  set of [rewrite] rules.

  Certification can also compile (see [COMPILATION]) 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.

  Extensive [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 [book-example].


Subtopics

  [Book-hash]
      Assigning ``often unique'' fingerprints to [books]

  [Bookdata]
      Write small files with meta-data about certified [books]

  [Books-reference]
      Reference guide for ACL2 functionality related to books, e.g.,
      [include-book], [certify-book], [cbd], etc.

  [Books-tour]
      The [3mguided tour[0m of concepts related to ACL2 [books].

  [Community-books]
      Libraries of ACL2 [books] developed by the ACL2 community.

  [Project-dir-alist]
      Support for moving project directories (also [47m:dir[0m arguments)

  [Sysfile]
      File representation using ACL2 project directories

  [Uncertified-books]
      Invalid [certificate]s and uncertified [books]")
 (BOOKS-CERTIFICATION
  (COMMUNITY-BOOKS)
  "Instructions for certifying the ACL2 [community-books].

  The Community Books (see [COMMUNITY-BOOKS]) provides a [47mmake[0m system,
  which is recommended for certifying a specified subset of those
  books from the [47mbooks/[0m directory of your ACL2 distribution.
  Alternate instructions are however available for certifying from
  the top-level directory (see [books-certification-alt]).

  Below are instructions for certifying various sets of books.  They
  all have the following form in common.  Note: If there is a
  suitable [47m\"acl2\"[0m executable on your Unix [47mPATH[0m --- for example, if
  the [47mbin[0m subdirectory of the main ACL2 directory is on your [47mPATH[0m, so
  that [47mbin/acl2[0m may be your executable --- then you can omit
  [47m\"ACL2=...\"[0m below.

    cd /path/to/acl2-sources/books
    make ACL2=/path/to/acl2-sources/saved_acl2 ...

  For example, the section ``A Full Build'', below, says to do the
  following if you would like to make a change to the
  [community-books] (where the [47m-j[0m argument is optional).

    $ cd /path/to/acl2-sources/books
    $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 all

  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 [47m**[0m; for example, if output is redirected to a log
  file [47mmake-regression.log[0m, then the following should provide no
  output.

    fgrep -a '**' make-regression.log

  Unusual books that create output in the log file should not produce
  the string [47m**[0m except upon failure.

  By default, [47mmake[0m commands for certifying books take advantage of
  files [47m*@useless-runes.lsp[0m.  See [useless-runes].


Prerequisites

  We assume that you have already downloaded and installed ACL2 as per
  the {ACL2 installation instructions |
  http://www.cs.utexas.edu/users/moore/acl2/v8-6/HTML/installation/installation.html}
  on the ACL2 home page.

  We assume you know the path to your ACL2 executable.  Typically this
  is a script named [47msaved_acl2[0m in your [47macl2-sources[0m directory.

  We assume the ACL2 [community-books] are installed in the [47mbooks/[0m
  subdirectory of your ACL2 distribution, as is the case when you
  have followed the ACL2 installation instructions above.

  The instructions below are suitable for ACL2 and all of its
  experimental extensions, e.g., ACL2(p) and ACL2(r).

  It may be preferable to avoid being logged in as root, since
  developers do not test as root and at least one community book
  ([47mbooks/oslib/tests/copy.lisp[0m) has failed to certify when logged in
  as root.


A Basic Build

  Before ACL2 Version 6.4, building the Community Books could take
  several hours.  Now, the default [47mmake[0m target in [47mbooks/GNUmakefile[0m,
  called [47mbasic[0m, is much faster --- it excludes many books and
  certifies only books listed below, which tend to be widely used.
  [31;1mWARNING[0m: the [47mbasic[0m target of [47mbooks/GNUmakefile[0m is insufficient for
  validating changes that will go into the [community-books]; for
  that, use the [47mall[0m target.

    * arithmetic

    * arithmetic-3

    * arithmetic-5

    * [ihs]

    * misc

    * tools (mostly)

    * [std]

    * [xdoc] (in part)

    * data-structures

  To certify these books, you should be able to run [47mmake[0m as follows.
  The [47m-j 2[0m 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 [47m-j 4[0m instead, and so on.

    $ cd /path/to/acl2-sources/books
    $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 basic

  If you configure your [47mPATH[0m so that you can launch ACL2 by typing
  [47macl2[0m, then you may omit the [47mACL2=...[0m part.


Certifying Additional Books

  We expect that most ACL2 users will want to certify at least the
  [47mbasic[0m 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 [31;1mmuch faster[0m to simply tell [47mmake[0m to build the books you
  actually want to use.

  There are [47mmake[0m targets corresponding to most directory names.  For
  instance, to build the books under [47mcoi[0m and [47mrtl[0m and [47mcgen[0m, you can
  run:

    $ cd /path/to/acl2-sources/books
    $ make ACL2=/path/to/acl2-sources/saved_acl2 coi rtl cgen -j 2

  For finer grained control, you can name individual books.  This works
  particularly well for libraries that have [47mtop[0m books.  For instance,
  if you want the [47mrtl/rel9[0m library, you could run:

    $ cd /path/to/acl2-sources/books
    $ make ACL2=/path/to/acl2-sources/saved_acl2 rtl/rel9/lib/top.cert -j 2


Books that Require ACL2 Extensions

  Some books require experimental extensions to ACL2, such as ACL2(p)
  (see [parallelism]) or ACL2(r) (see [real]).  Other books require
  certain additional software.

  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
  [47mmake[0m should explain which books are being excluded and why.

  These kinds of book requirements are controlled by special
  [build::cert_param] comments.


Books that Require Quicklisp

  Some books, especially [interfacing-tools] like [oslib] and the ACL2
  [bridge], require certain Common Lisp libraries.

  These libraries are now bundled with ACL2 via [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 [47mUSE_QUICKLISP=0[0m
  in your [47mmake[0m command.

  Using Quicklisp should definitely work if the host Lisp is CCL or
  SBCL.  (Note however that certification of [books] that use
  Quicklisp may require [47mopenssl[0m 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 [31;1mnot[0m work for
  GCL (at least as of 2018).


Books that Require Additional Software

  Some other books based on [satlink] and [gl] require a SAT solver,
  typically Glucose, to be installed; 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.


Building the manual

  If you just want to get a copy of the ACL2+Books manual for local
  viewing, you probably [31;1mdon't need to build it yourself[0m because you
  can just {download | download/} a copy.  If for some reason you do
  want to build the manual yourself, you should be able to do so as
  follows, provided you have installed glucose.  (That requirement
  might be eliminated in the future.)

    $ cd /path/to/acl2-sources/books
    $ make manual -j 4

  Building the manual should work on at least CCL and SBCL on Linux and
  Mac OS X.  It [31;1mmay not work[0m for some other OS/Lisp combinations.  In
  particular, building the manual requires some features from [oslib]
  and [quicklisp] that may not be available on some other Lisps.

  The resulting web-based manual may be found in:

    acl2-sources/books/doc/manual/index.html

  See also [ACL2-doc] for details about how to build your own
  Emacs-based manual, and [xdoc::save] for general information about
  how to build and distribute custom XDOC manuals, e.g., manuals that
  additionally include your own unreleased books.


A Full Build

  Building all of the books can take hours and is [31;1musually unnecessary[0m.
  That said, it is easy to do: just run [47mmake all[0m, for example as
  follows.  (But as noted above, you may omit [47m\"ACL2=...\"[0m if a
  suitable executable named [47macl2[0m is on your Unix [47mPATH[0m, such as
  [47mbin/acl2[0m.)

    $ cd /path/to/acl2-sources/books
    $ make ACL2=/path/to/acl2-sources/saved_acl2 -j 2 all

  This includes a few books that are quite slow to certify.  You can
  exclude those by replacing ``[47mall[0m'' by ``[47mregression[0m'' in the command
  above.


Cleaning Up

  If you want to delete generated files, you can run [47mmake clean[0m to
  remove certificates, compiled files, and build logs.

  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 [47mbuild/clean.pl[0m script.  This will delete, starting from
  your current directory, recursively, all certificates, logs,
  compiled files, etc.

  Note that [47mmake clean[0m doesn't remove some files, e.g., [xdoc] manuals.
  To remove everything, try [47mmake moreclean[0m.


Debugging Failed Certifications

  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 [47m[bookname].cert.out[0m
  file.  For instance:

    ;; 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 ---

  Some other notes/tips:

    * Make sure the ACL2 image you run is the same as the one listed as
      ACL2 in those environment variables!

    * You may wish to set the environment variables for only the duration
      of your ACL2 session by using the \"env\" command.

    * You may wish to edit some of the commands for better debugging
      purposes; e.g. you may modify the [set-inhibit-output-lst]
      command, or insert a [set-debugger-enable] command, etc.

    * If you don't want your session to exit after a successful
      certification, replace the last form [47m(er-progn (time$
      (certify-book ...[0m with just the [47m(time$ (certify-book ...))[0m
      part.


Further Resources

  The build system is largely based on [build::cert.pl].  There is
  considerable documentation about [47mcert.pl[0m, and we highly recommend
  using it to manage your own ACL2 projects.

  The main build script is [47mbooks/GNUmakefile[0m.  There are many comments
  at the start of this file, and you can also inspect it to see what
  targets are available.

  Please feel absolutely free to contact the [ACL2-help] mailing list
  with any questions about building the community books.


Subtopics

  [Books-certification-alt]
      Alternate instructions for certifying the [community-books], from
      the perspective of the [47macl2-sources[0m directory.

  [Books-certification-classic]
      Classic ACL2 `make'-based certification of [books]

  [Provisional-certification]
      Certify a book in stages for improved book-level parallelism")
 (BOOKS-CERTIFICATION-ALT
  (BOOKS-CERTIFICATION)
  "Alternate instructions for certifying the [community-books], from the
  perspective of the [47macl2-sources[0m directory.

  WARNING: Parts of this documentation are probably obsolete, but parts
  are still relevant.  See [books-certification] as the primary
  source of information on how to certify the [community-books].

  For background on the ACL2 community books, 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
  [47mbooks/GNUmakefile[0m, in the community books, for more about ``Credits
  and History'', and for additional technical details not covered in
  this topic.

  For more information about installing ACL2, see the {ACL2
  installation instructions |
  http://www.cs.utexas.edu/users/moore/acl2/v8-6/HTML/installation/installation.html}.
  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
  [books-certification-classic].

  [31;1mThe Basics[0m

  We make the following assumptions.

    * Gnu `make' is available on your system via the `make' command (rather
      than some other flavor of `make').  (Execute `[47mmake --version[0m to
      verify this.)

    * You have built or obtained an ACL2 executable.

    * The ACL2 [community-books] are installed in the [47mbooks/[0m subdirectory
      of your ACL2 distribution, as is the case when you have
      followed the standard installation instructions.

  Note: All commands shown below are issued in the top-level (ACL2
  sources) directory of your ACL2 distribution.

  By default the ACL2 executable is file [47msaved_acl2[0m 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.

    make regression

  Better yet, save a log file in case there are problems, for example
  as follows.

    (make regression) >& make-regression.log

  or perhaps better yet:

    (time nice make regression) >& make-regression.log

  For the sake of brevity, below we'll skip mentioning any of `[47mtime[0m',
  `[47mnice[0m', or `[47m>& make-regression.log[0m'.  But saving a log file, in
  particular, is useful in case you encounter problems to report.

  If you fetched the community books using git, then you will have a
  directories such [47mbooks/workshops/[0m that is not necessary for
  certifying the most widely-included books.  You can certify just
  such books as follows.

    (time nice make basic) >& make-basic.log

  Whether you use target `[47mregression[0m' or target `[47mbasic[0m', then for each
  book [47mfoo.lisp[0m whose certification is attempted, a file [47mfoo.cert.out[0m
  in the same directory will contain the output from the book's
  certification attempt.

  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 [47m-j[0m.  For
  example, if you have 8 hardware threads then you might want to
  issue the following command.

    make regression -j 8

  [31;1mSpecifying the ACL2 Executable[0m

  If your ACL2 executable is not file [47msaved_acl2[0m in the ACL2 sources
  directory, then you will need to specify that executable.  You can
  do that by setting variable [47mACL2[0m, 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 [47mmy-acl2[0m is on
  your [47mPATH[0m in a Unix-like environment (e.g., linux or MacOS) and
  that [47mmy-saved_acl2[0m is just a pathname relative to your ACL2 sources
  directory, which is not on your path.

    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

  [31;1mCleaning[0m

  You can delete files generated by book certification (including [47m.cert[0m
  files, [47m.out[0m files, compiled files, and more) by issuing the
  following command (again, in your ACL2 sources directory).

    make clean-books

  Alternatively, if you want to cause such deletion and then do a
  regression, simply replace the `[47mregression[0m' target by
  `[47mregression-fresh[0m.

  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
  [47mDIR[0m is a pathname of your [47mbooks[0m directory.

    DIR/clean.pl

  For example, to clean up generated files under [47mbooks/arithmetic[0m, you
  could do the following.

    cd books/arithmetic
    ../clean.pl
    cd - # to return to the ACL2 sources directory, if you wish to do so

  [31;1mRestricting to Specific Directories and Books[0m

  You can specify which books you want certified by using any or all of
  the variables [47mEXCLUDED_PREFIXES[0m, [47mACL2_BOOK_CERTS[0m, or
  [47mACL2_BOOK_DIRS[0m.  First, the set of desired [47m.cert[0m files is
  restricted to those that do not start with any string that is one
  of the words in the value of [47mEXCLUDED_PREFIXES[0m.  Then
  [47mACL2_BOOK_CERTS[0m and [47mACL2_BOOK_DIRS[0m, if supplied, specify which
  books should be certified, as illustrated by the following example.

    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 \\
      \"

  Then all book in directories [47msymbolic[0m and [47mpaco[0m will be certified, as
  will the books [47mworkshops/2006/cowles-gamboa-euclid/Euclid/ed6a.lisp[0m
  and [47mworkshops/2006/cowles-gamboa-euclid/Euclid/ed4bb.lisp[0m.  Note
  that all pathnames should be relative to your community books
  directory; in particular, they should not be absolute pathnames.
  Also notice the [47m.cert[0m extension used in files supplied for
  [47mACL2_BOOK_CERTS[0m.

  Alternatively, you may wish to invoke [47mbooks/cert.pl[0m while standing in
  a directory under which you want to certify books.  This will
  certify not only those books, but all supporting books --- even
  those not under the current directory --- that do not have
  up-to-date [47m.cert[0m files.  The following is a simple command to
  invoke that will certify all books in the current directory, where
  if the [47mbooks/[0m directory is not on your path, you will need to
  provide a suitable filename, e.g. [47m../../cert.pl[0m or
  [47m~/acl2/books/cert.pl[0m.

    cert.pl -j 4 *.lisp

  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 [provisional-certification]), and
  `make'-level parallelism (in this case specifying four parallel
  processes).

    cert.pl --pcert-all -j 4 `find . -name '*.lisp'`

  Note that with this approach, unlike classic ACL2 `make'-based
  certification (see [books-certification-classic], out-of-date [47m.cert[0m
  files that are not under the current directory will also be built.
  For documentation of [47mcert.pl[0m invoke:

    cert.pl -h

  See the top of [47mcert.pl[0m for authorship and copyright information.

  Finally, we give a brief summary of how to use so-called ``classic
  ACL2 `make'-based certification'' for community books; 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
  [47mACL2_BOOK_DIRS[0m for the ``modern'' way to accomplish the same thing.

  Many community book directories have a [47mMakefile[0m.  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 ([47mmake clean[0m) is optional.

    make clean
    (time nice make -j 8 ACL2=my-acl2)

  [31;1mACL2 Customization Files[0m

  By default, your acl2-customization file (see [ACL2-customization])
  is ignored by all flavors of ``[47mmake regression[0m''.  However, you can
  specify the use of an acl2-customization file by setting the value
  of environment variable [47mACL2_CUSTOMIZATION[0m to the empty string,
  indicating a default such file, or to the desired absolute
  pathname.  For example:

    make regression ACL2_CUSTOMIZATION=''
    make regression ACL2_CUSTOMIZATION='~/acl2-customization.lisp'

  [31;1mRegressions for Variants of ACL2[0m

  The discussion above also pertains to using ACL2(p) (see [parallel])
  or ACL2(r) (see [real]), in which case the default is [47msaved_acl2p[0m
  or [47msaved_acl2r[0m respectively, rather than [47msaved_acl2[0m.  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
  [waterfall-parallelism-for-book-certification].

  [31;1mProvisional Certification[0m

  To use provisional certification (see [provisional-certification]),
  supply [47mACL2_PCERT=t[0m with your `make' command.  Here is an example.

    time nice make regression -j 4 ACL2_BOOK_DIRS=deduction ACL2_PCERT=t

  [31;1mMiscellany[0m

  Other control of the certification process may be found by perusing
  community books file [47mbooks/make_cert[0m.  In particular, the [47mINHIBIT[0m
  variable may be set to a call of [47m[set-inhibit-output-lst][0m, for
  example as follows to obtain the output one would get by default in
  an (interactive) ACL2 session.

    time nice make regression -j 4 ACL2_BOOK_DIRS=arithmetic \\
      INHIBIT='(set-inhibit-output-lst proof-tree)'

  [31;1mTroubleshooting[0m

  If you run into problems, you can get help by joining the [47macl2-help[0m
  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.")
 (BOOKS-CERTIFICATION-CLASSIC
  (BOOKS-CERTIFICATION)
  "Classic ACL2 `make'-based certification of [books]

  This [documentation] topic explains an approach to certifying
  directories of books, which we call ``classic ACL2 `make'-based
  certification''.

  Warning: The capability described in this section might be replaced
  at any time by a capability based on corresponding support for
  community books (see [books-certification]).  If you think that
  would be a hardship, please contact the ACL2 implementors.

  This topic discusses a way to certify a directory of books other than
  the ACL2 community books.  See [books-certification] for how to
  certify the set of ACL2 community [books].  There is also a section
  in that [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.

  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 installation instructions, that you install
  the ACL2 community books in the [47mbooks/[0m subdirectory of your ACL2
  distribution.  We will refer below to that directory as [47mBOOKS[0m.

  In summary: to use `make' to certify [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 `[47m-j[0m flag
  `make'-level parallelism by specifying the number of concurrent
  processes.  For example:

    make -j 4

  For each book [47mfoo.lisp[0m, a file [47mfoo.out[0m in the same directory as
  [47mfoo.lisp[0m will contain the output from the corresponding
  certification attempt.  If you have previously executed such a
  command, then you might first want to delete [certificate] files
  and other generated files by executing the following command.

    make clean

  Note that when you run `make', then by default, the first error will
  cause the process to stop.  You can use [47mmake -i[0m to force `make' to
  ignore errors, thus continuing past them.  Or, use [47mmake -k[0m to keep
  going, but skipping certification for any book that includes
  another whose certification has failed.

  By default, your acl2-customization file (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 [47mACL2_CUSTOMIZATION[0m to the empty string,
  indicating a default such file, or to the desired absolute
  pathname.  For example:

    make ACL2_CUSTOMIZATION=''
    make ACL2_CUSTOMIZATION='~/acl2-customization.lisp'

  We now discuss how to create makefiles to support `make' commands as
  discussed above.

  First we give five steps for creating a [47mMakefile[0m 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).

      1. Include the file [47mMakefile-generic[0m from the [47mbooks/[0m subdirectory of
      your ACL2 sources directory, but first perhaps define the
      variable `[47mACL2[0m'.  Consider the following example.

        ACL2 ?= /Users/john_doe/acl2/acl2-sources/saved_acl2
        include /Users/john_doe/acl2/acl2-sources/books/Makefile-generic

      In this example, you can omit the first line, because the default
      ACL2 executable is file [47msaved_acl2[0m in the directory immediately
      above the directory of the specified [47mMakefile-generic[0m file.
      Indeed, that is the common case.  Note the use of [47m?=[0m instead of
      [47m=[0m or [47m:=[0m, so that [47mACL2[0m can instead be defined by the environment
      or provided on the command line as part of the `make' command.

      2. (Optional; usually skipped.)  Set the [47mINHIBIT[0m variable if you want
      to see more than the [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 `[47minclude[0m'
      lines.

        INHIBIT = (assign inhibit-output-lst (list (quote proof-tree)))

      For other values to use for [47mINHIBIT[0m, see [set-inhibit-output-lst] and
      see the original setting of [47mINHIBIT[0m in [47mbooks/Makefile-generic[0m.

      3. Specify the books to be certified.  Normally, every file with
      extension [47m.lisp[0m will be a book that you want to certify, in
      which case you can skip this step.  Otherwise, put a line in
      your [47mMakefile[0m after the ones above that specifies the books to
      be certified.  The following example, from an old version of
      community books file [47mbooks/finite-set-theory/osets/Makefile[0m,
      should make this clear.

        BOOKS = computed-hints fast instance map membership outer primitives \\
                quantify set-order sets sort

      But better yet, use the extension [47m.lsp[0m for any Lisp or ACL2 files
      that are not to be certified, so that the definition of [47mBOOKS[0m
      can be omitted.

      4. Create [47m.acl2[0m files for books that are to be certified in other
      than the initial ACL2 world (see [portcullis]).  For example,
      if you look in community books file
      [47mbooks/arithmetic/equalities.acl2[0m you will see [47m[defpkg][0m forms
      followed by a [47m[certify-book][0m command, because it was determined
      that [47m[defpkg][0m forms were necessary in the certification world
      in order to certify the [47mequalities[0m book.  In general, for each
      [47m<book-name>.lisp[0m whose certification requires a non-initial
      certification world, you will need a corresponding
      [47m<book-name>.acl2[0m file that ends with the appropriate
      [47m[certify-book][0m command.

      You also have the option of creating a file [47mcert.acl2[0m that has a
      special role.  When file [47m<book-name>.lisp[0m is certified, if
      there is no file [47m<book-name>.acl2[0m but there is a file
      [47mcert.acl2[0m, then [47mcert.acl2[0m will be used as [47m<book-name>.acl2[0m
      would have been used, as described in the preceding paragraph,
      except that the appropriate [47m[certify-book][0m command will be
      generated automatically.  Thus, no [47mcertify-book[0m command should
      occur in [47mcert.acl2[0m.

      It is actually allowed to put raw lisp forms in a [47m.acl2[0m file
      (presumably preceded by [47m:q[0m or [47m(value :q)[0m and followed by [47m(lp)[0m).
      But this is not recommended (see [q]); we make no guarantees
      about certification performed any time after raw Lisp has been
      entered in the ACL2 session.

      5. Generally, the next step is to include the following line after
      the `[47minclude[0m' of [47mMakefile-generic[0m (see the first step above).

        -include Makefile-deps

      This will cause `make' to create and then include a file
      [47mMakefile-deps[0m that contains ``dependency'' lines needed by
      `make'.  If those dependencies are somehow flawed, it may be
      because you have [47m[include-book][0m forms that are not truly
      including books, for example in multi-line comments ([47m#|..|#[0m).
      These will be ignored if preceded by a semicolon ([47m;[0m), or if you
      add a line break after ``[47minclude-book[0m.'' But instead of adding
      the `[47m-include[0m' line above, you can create dependency lines
      yourself by running the command

        make dependencies

      and pasting the result into the end of your [47mMakefile[0m, and editing as
      you see fit.

  This concludes the basic instructions for creating a [47mMakefile[0m in a
  directory including books.  Here are some other capabilities
  offered by community books file [47mbooks/Makefile-subdirs[0m.  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 [provisional-certification].

  [31;1mSubdirectory Support[0m

  There is support for using `make' to certify books in subdirectories.
  Consider the following example.

    DIRS = pass1 bind-free floor-mod
    include ../Makefile-subdirs

  This indicates that we are to run `make' in subdirectories [47mpass1/[0m,
  [47mbind-free/[0m, and [47mfloor-mod/[0m of the current directory.

  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
  [47mbooks/arithmetic-3/Makefile[0m contains the following lines.

    arith-top: top all
    all: top

    DIRS = pass1 bind-free floor-mod
    include ../Makefile-subdirs
    include ../Makefile-generic

    -include Makefile-deps

  The `[47mtop[0m' target is defined in [47m../Makefile-subdirs[0m to call `make' in
  each subdirectory specified in [47mDIRS[0m.  We have set the default
  target in the example above to a new name, [47marith-top[0m, that makes
  that [47mtop[0m target before making the `[47mall[0m' target which, in turn, is
  the default target in any [47mMakefile-generic[0m, and is responsible for
  certifying books in the current directory as discussed in the five
  steps displayed above.

  Use [47mMakefile-psubdirs[0m instead of [47mMakefile-subdirs[0m if certification of
  a book in a subdirectory never depends on certification of a book
  in a different subdirectory, because then the [47m-j[0m option of `make'
  can allow subdirectories to be processed in parallel.

  [31;1mCleaning Up[0m

  We note that there is a [47mclean[0m target.  Thus,

    make clean

  will remove generated files including [47m.cert[0m, [47m.out[0m files, and compiled
  files.

  [31;1mSystem Books[0m

  An environment variable [47mACL2_SYSTEM_BOOKS[0m 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.

  The environment variable [47mACL2_SYSTEM_BOOKS[0m can be set to the
  top-level directory of the ACL2 community books.  A Unix-style
  pathname, typically ending in [47mbooks/[0m or [47mbooks[0m, 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:

    export ACL2_SYSTEM_BOOKS
    ACL2_SYSTEM_BOOKS=/home/acl2/v3-2/acl2-sources/books

  However, you can also set [47mACL2_SYSTEM_BOOKS[0m as a `make' variable, by
  setting it in your [47mMakefile[0m before the first target definition,
  e.g.:

    ACL2_SYSTEM_BOOKS ?= /home/acl2/v3-2/acl2-sources/books

  [31;1mCompilation Support[0m

  The file [47mbooks/Makefile-generic[0m provides support for compiling books
  that are already certified (but 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 [47m.o[0m
  extension.  Now suppose you would like to compile the books for
  Allegro Common Lisp, whose compiled files have the [47m.fasl[0m extension.
  The following command will work if you have included
  [47mbooks/Makefile-generic[0m in your [47mMakefile[0m.

    make fasl

  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).

  If you run into problems, you can get help by joining the [47macl2-help[0m
  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.")
 (BOOKS-REFERENCE
  (BOOKS)
  "Reference guide for ACL2 functionality related to books, e.g.,
  [include-book], [certify-book], [cbd], etc.


Subtopics

  [Add-include-book-dir]
      Link keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m

  [Add-include-book-dir!]
      Non-[47m[local][0mly link keyword for [47m:dir[0m argument of [47m[ld][0m and
      [47m[include-book][0m

  [Book-compiled-file]
      Creating and loading of compiled and expansion files for [books]

  [Cbd]
      Connected book directory string

  [Certify-book]
      How to produce a [certificate] for a book

  [Certify-book-debug]
      Some possible ways to work around [47m[certify-book][0m failures

  [Delete-include-book-dir]
      Unlink keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m

  [Delete-include-book-dir!]
      Non-[47m[local][0mly unlink keyword for [47m:dir[0m argument of [47m[ld][0m and
      [47m[include-book][0m

  [Full-book-name]
      Book naming conventions assumed by ACL2

  [Include-book]
      Load the [events] in a file

  [Pathname]
      Introduction to filename conventions in ACL2

  [Set-cbd]
      To set the connected book directory

  [Set-write-ACL2x]
      Cause [47m[certify-book][0m to write out a [47m.acl2x[0m file

  [With-cbd]
      To bind the connected book directory

  [With-current-package]
      To bind the [current-package]")
 (BOOKS-TOUR
  (BOOKS)
  "The [3mguided tour[0m of concepts related to ACL2 [books].

  The tour begins with [book-example].


Subtopics

  [Book-contents]
      Restrictions on the forms inside [books]

  [Book-example]
      How to create, certify, and use a simple book

  [Book-name]
      Conventions associated with book-names

  [Certificate]
      A file specifying validity of a given book

  [Certify-book]
      How to produce a [certificate] for a book

  [Include-book]
      Load the [events] in a file

  [Keep]
      How we know if [47m[include-book][0m read the correct files

  [Portcullis]
      The gate guarding the entrance to a certified book")
 (BOOLE$
  (NUMBERS ACL2-BUILT-INS)
  "Perform a bit-wise logical operation on 2 two's complement integers

  When integers [47mx[0m and [47my[0m are viewed in their two's complement
  representation, [47m(boole$ op x y)[0m returns the result of applying the
  bit-wise logical operation specified by [47mop[0m.  The following table is
  adapted from documentation for the analogous Common Lisp function
  {boole |
  http://www.lispworks.com/documentation/HyperSpec/Body/f_boole.htm}
  in the {Common Lisp Hyperspec |
  http://www.lispworks.com/documentation/HyperSpec/}.  Note that the
  values of [47mop[0m for [47mboole$[0m are ACL2 constants, rather than
  corresponding values of [47mop[0m for the Common Lisp function [47mboole[0m.

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

  The guard of [47mboole$[0m specifies that [47mop[0m is the value of one of the
  constants above and that [47mx[0m and [47my[0m are integers.

  See any Common Lisp documentation for analogous information about
  Common Lisp function [47mboole[0m.

  [31;1mFunction: [0m<boole$>

    (defun boole$ (op i1 i2)
      (declare (type (integer 0 15) op)
               (type integer i1 i2))
      (cond ((eql op *boole-1*) i1)
            ((eql op *boole-2*) i2)
            ((eql op *boole-and*) (logand i1 i2))
            ((eql op *boole-andc1*)
             (logandc1 i1 i2))
            ((eql op *boole-andc2*)
             (logandc2 i1 i2))
            ((eql op *boole-c1*) (lognot i1))
            ((eql op *boole-c2*) (lognot i2))
            ((eql op *boole-clr*) 0)
            ((eql op *boole-eqv*) (logeqv i1 i2))
            ((eql op *boole-ior*) (logior i1 i2))
            ((eql op *boole-nand*) (lognand i1 i2))
            ((eql op *boole-nor*) (lognor i1 i2))
            ((eql op *boole-orc1*) (logorc1 i1 i2))
            ((eql op *boole-orc2*) (logorc2 i1 i2))
            ((eql op *boole-set*) 1)
            ((eql op *boole-xor*) (logxor i1 i2))
            (t 0)))")
 (BOOLEAN-LISTP
  (BOOLEANP LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of booleans

  The predicate [47mboolean-listp[0m tests whether its argument is a
  [47m[true-listp][0m of objects each or which satisfies [47m[booleanp][0m, i.e.,
  is [47mt[0m or [47mnil[0m.

  [31;1mFunction: [0m<boolean-listp>

    (defun boolean-listp (lst)
      (declare (xargs :guard t))
      (cond ((atom lst) (eq lst nil))
            (t (and (or (eq (car lst) t) (eq (car lst) nil))
                    (boolean-listp (cdr lst))))))")
 (BOOLEANP
  (BASICS ACL2-BUILT-INS)
  "Recognizer for booleans

  [47m(Booleanp x)[0m is [47mt[0m if [47mx[0m is [47mt[0m or [47mnil[0m, and is [47mnil[0m otherwise.

  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?

  [31;1mFunction: [0m<booleanp>

    (defun booleanp (x)
      (declare (xargs :guard t))
      (if (eq x t) t (eq x nil)))


Subtopics

  [Boolean-listp]
      Recognizer for a true list of booleans")
 (BOUNDERS
  (TAU-SYSTEM)
  "Intervals, bounder functions, and bounder correctness

    [3mBounder Forms 1 and 2[0m:
    (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 [3mtarget[0m
                                    (bounder-fn i1 ...))))

  where [3mtarget[0m is either [47m(fn x1 ... y1 ...)[0m or [47m(mv-nth 'n (fn x1 ... y1
  ...))[0m, depending on whether we are in the [3mForm 1[0m or [3mForm 2[0m case,
  respectively.  However, the shape above is meant just as a
  reminder.  Details are given below.

  This topic first explains the basic shape of [3mBounder Form 1[0m.  Then it
  illustrates [3mBounder Form 2[0m.  Finally, it deals briefly with proving
  bounder correctness theorems.  The community book
  [47mtau-bounders/elementary-bounders[0m contains bounders for various
  elementary functions including [47m[+][0m, [47m[*][0m, [47m[/][0m, [47m[floor][0m, [47m[mod][0m,
  [47m[logand][0m, [47m[lognot][0m, [47m[logior][0m, [47m[logorc1][0m, [47m[logeqv][0m, [47m[logxor][0m, and
  [47m[ash][0m.  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.

  A bounder correctness theorem establishes that [47mbounder-fn[0m is a
  ``bounder'' for the function [47mfn[0m.  That means that when trying to
  compute a tau for a call of [47mfn[0m (or, in the case of [3mForm 2[0m, for the
  [47mn[0mth component of the multiple-value vector returned by a call of
  [47mfn[0m) the tau system can call [47mbounder-fn[0m on the intervals containing
  certain arguments of [47mfn[0m.

  Let us start with an example.  Let [47mfn[0m be the addition function, [47m+[0m
  (actually, [47m[binary-+][0m).  Consider the target term [47m(+ x y)[0m and
  contemplate the question: if you know intervals containing [47mx[0m and [47my[0m,
  say [47mintx[0m and [47minty[0m 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 [47mintx[0m and [47minty[0m.  The lower bound of the answer interval
  is the sum of the lower bounds of [47mintx[0m and [47minty[0m, and the lower
  relation is the stronger of the lower relations of [47mintx[0m and [47minty[0m.
  Analogous comments define the upper bound and relation of the
  answer interval.  So for example, if [47mx[0m is an [47mINTEGERP[0m such that [47m0
  <= x <= 10[0m and [47my[0m is a [47mRATIONALP[0m such that [47m0 < y <= 20[0m, then [47m(+ x y)[0m
  is a [47mRATIONALP[0m such that [47m0 < (+ x y) <= 30[0m.

  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 [47mbounder-for-+[0m that returns the answer
  interval described, given [47mintx[0m and [47minty[0m.

  Then the following [3mBounder Form 1[0m formula establishes the correctness
  of [47mbounder-for-+[0m and allows the tau system to use it to produce
  bounds in the tau computed for [47m+[0m-expressions:

    (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))))

  For example, suppose we have a formula with the following hypotheses

    (and (integerp a)
         (<= 0 a)
         (<= a 10)
         (rationalp b)
         (< 0 b)
         (<= b 20))

  and suppose the tau system encounters the term [47m(+ a b)[0m.  When the
  term is encountered, the tau for [47ma[0m would include an [47mINTEGERP[0m
  interval such that [47m0 <= a <= 10[0m and the tau for [47mb[0m would include a
  [47mRATIONALP[0m interval such that [47m0 < b <= 20[0m.  In its most primitive
  configuration, the tau system would only know that the tau for [47m(+ a
  b)[0m includes the recognizer [47mRATIONALP[0m (and all that it is known to
  imply).  But after the bounder theorem above is proved and
  available as a [47m:tau-system[0m rule the tau system would infer that [47m(+
  a b)[0m was in the [47mRATIONALP[0m interval such that [47m0 < (+ a b) <= 30[0m.

  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.

  It is sometimes useful to restrict the domains of the intervals to be
  considered.  For example, in bounding [47m*[0m-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).

  If we were to define [47mbounder-for-*[0m so that it works correctly to
  bound [47m*[0m-expressions, but only for integer or rational arguments,
  its correctness theorem would be:

    (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))))

  In this case, [47mbounder-for-*[0m would be applied to the intervals for [47mx[0m
  and [47my[0m only if those intervals were over the integers or the
  rationals.

  The above theorem for [47mbounder-for-*[0m begins to suggest the general
  form of a bounder theorem and we will use it to explain the general
  form.

  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.)

  Part (a) introduces some distinct ``interval variables,'' here called
  ``ivars,'' that are known to denote intervals; for the example
  above, the ivars are [47mintx[0m and [47minty[0m.  Each hypothesis in part (a) is
  of the form [47m(TAU-INTERVALP ivar)[0m.

  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 [47m(EQUAL (TAU-INTERVAL-DOM ivar) 'dom)[0m,
  where [47mivar[0m is one of the interval variables and [47mdom[0m is one of
  [47mINTEGERP[0m, [47mRATIONALP[0m, [47mACL2-NUMBERP[0m, or [47mNIL[0m.  It is not necessary to
  restrict every interval variable.  Indeed, part (b) may be empty,
  as in the theorem for [47mbounder-for-+[0m above.

  Part (c) consists of a set of [47m(IN-TAU-INTERVALP avar ivar)[0m hypotheses
  where each [47mavar[0m is a variable and no two hypotheses in part (c) use
  the same [47mavar[0m or [47mivar[0m.  We call the set of all such [47mavar[0m 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.

  Part (d) introduces the name of the bounder function, here
  [47mbounder-for-*[0m, and the order of its ivar arguments.  We see that
  [47mbounder-for-*[0m takes two arguments and they correspond, in order, to
  the intervals containing [47mx[0m and [47my[0m.  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
  [47m[tau-intervalp][0m or [47m[in-tau-intervalp][0m.

  Part (e) introduces the name of the function being bounded, here [47m*[0m,
  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.

  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.

  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,
  [47mbounder-for-*[0m takes its arguments in the opposite order, and the
  theorem includes an additional conclusion.

    (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))

  [3mNote on why bounder forms allow additional conjuncts in the
  conclusion[0m: 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 [47mINTEGERP[0m or otherwise restricted.
  We allow such ``unnecessary'' conclusions simply to save the user
  the burden of stating multiple theorems.

  [3mAn Illustration of Bounder Form 2[0m: Suppose [47m(quad i)[0m is defined so
  that truncates the integer [47mi[0m to the largest multiple of 4 weakly
  below [47mi[0m and, additionally, returns the remainder.  For example,
  [47m(quad 26)[0m returns [47m(mv 24 2)[0m.  Then here are bounders for each of
  its return values:

    (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))))

  Note that the bounders assume [47mi[0m is an [47mINTEGERP[0m and return the
  universal interval when [47mi[0m is not a natural.

  As noted in the discussion below about how to prove bounder
  correctness theorems, proving these bounders correct will require
  an arithmetic book, e.g.,

    (include-book \"arithmetic-5/top\" :dir :system)

  Here then are two bounder correctness theorems of [3mForm 2[0m:

    (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)

  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

    (equal (tau-interval-dom (quad-bounds-0 i)) 'INTEGERP)

  so that we can keep [47mquad-bounds-0[0m disabled to allow us to use
  [47mquad-bounds-0-correct[0m as a [47m:rewrite[0m 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 [47m:rule-classes[0m above with

    :rule-classes
     ((:rewrite)
      (:forward-chaining :trigger-terms ((quad-bounds-0 i))))

  Since the theorem is being stored as some kind of rule and since it
  satisfies the [3mBounder Form 2[0m shape, it will additionally be stored
  as a [47m:tau-system[0m rule.

  [3mNote on proving bounder theorems[0m: 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 [47m(< (fn x y) (g (tau-interval-hi int1)
  int2))[0m.  But tau deals with inequalities relating terms to
  constants, e.g., [47m(< ... 16)[0m.  A bounder theorem is a sort of
  ``metatheorem'' about [3mhow to construct[0m 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!

  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

    (LOGXOR x y) = (LOGNOT (LOGEQV x y))

  an interval for bounding [47mLOGXOR[0m can be constructed by composing the
  constructions of intervals for [47mLOGEQV[0m and [47mLOGNOT[0m.  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.

  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 [47m[make-tau-interval][0m, e.g.,

    (equal (tau-interval-dom (make-tau-interval dom lo-rel lo hi-rel hi)) dom)

  and then disable those functions to avoid seeing excessive [47mcar[0ms and
  [47mcdr[0ms.

  When dealing with bounders defined in the direct, arithmetic style,
  we tend to keep [47m[tau-intervalp][0m and [47m[in-tau-intervalp][0m enabled so
  they unfold and expose the algebra.

  When dealing with bounders defined compositionally in terms of other
  verified bounders, we tend to keep [47m[tau-intervalp][0m and
  [47m[in-tau-intervalp][0m disabled so we can rely on the previously proved
  bounder theorems as rewrite and forward chaining rules.

  Note that this last remark means that when you prove bounder
  correctness theorems you should include corollaries that are useful
  [47m:rewrite[0m and possibly [47m:forward-chaining[0m 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
  [47mbounder-for-*[0m we would include [47m(:forward-chaining :trigger-terms
  ((tau-bounder-expt2 int2)))[0m and let the [47min-tau-intervalp[0m hypotheses
  select the free variables [47mx[0m and [47my[0m.")
 (BREAK$
  (ERRORS ACL2-BUILT-INS)
  "Cause an immediate Lisp break

  ACL2 users are generally advised to avoid breaking into raw Lisp.
  Advanced users may, on occasion, see the need to do so.  Evaluating
  [47m(break$)[0m will have that effect.  (Exception: [47mbreak$[0m is disabled
  after evaluation of [47m(set-debugger-enable :never)[0m; see
  [set-debugger-enable].)  [47mBreak$[0m returns [47mnil[0m.  Note that upon
  returning to the ACL2 read-eval-print loop (for example, using [47m:q[0m
  if the host Lisp is CCL), one will be at the top level even if one
  had been inside a recursive call of [47m[ld][0m or a [wormhole].

  [31;1mFunction: [0m<break$>

    (defun break$ nil
      (declare (xargs :guard t))
      nil)")
 (BREAK-LEMMA
  (BREAK-REWRITE)
  "A quick introduction to breaking rewrite rules in ACL2

    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

  ACL2 does not support Nqthm's [47mbreak-lemma[0m 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 [break-rewrite] facility.  See
  [break-rewrite] and all of its associated [47m:[0m[47m[doc][0m topics for
  details.  The following basic steps are required.

  (1) To enable the ``break rewrite'' feature, you must first execute

    ACL2 !>:brr t

  at the top-level of ACL2.  Equivalently, evaluate [47m(brr t)[0m.
  [Break-rewrite] stays enabled until you disable it with [47m(brr nil)[0m.
  When [break-rewrite] is enabled the ACL2 rewriter will run slower
  than normal but you will be able to [monitor] the attempts to apply
  specified rules.

  (2) Decide what [rune]s (see [rune]) you wish to [monitor].  For
  example, you might want to know why [47m(:rewrite lemma12 . 2)[0m 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 [47mlemma12[0m.

  The command

    ACL2 !>:monitor (:rewrite lemma12 . 2) t

  will install an ``unconditional'' break point on that rule.  The
  ``[47mt[0m'' 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 [47mt[0m is replaced by an
  expression that evaluates to non-[47mnil[0m when you wish for a break to
  occur.  See [monitor].  The above keyword command is, of course,
  equivalent to

    ACL2 !>(monitor '(:rewrite lemma12 . 2) t)

  which you may also type.  You may install breaks on as many rules as
  you wish.  You must use [47m[monitor][0m on each rule.  You may also
  change the break condition on a rule with [47m[monitor][0m.  Use
  [47m[unmonitor][0m (see [unmonitor]) to remove a rule from the list of
  [monitor]ed rules.

  (3) Then try the proof again.  When a [monitor]ed rule is tried by
  the rewriter you will enter an interactive break, called
  [break-rewrite].  See [break-rewrite] for a detailed description.
  Very simply, [break-rewrite] lets you inspect the context of the
  attempted application both before and after the attempt.  When
  [break-rewrite] is entered it will print out the ``target'' term
  being rewritten.  If you type [47m:go[0m [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 [brr-commands].

  (4) When you have finished using the [break-rewrite] feature you
  should disable it to speed up the rewriter.  You can disable it
  with

    ACL2 !>:brr nil

  The list of [monitor]ed rules and their break conditions persists but
  is ignored.  If you enable [break-rewrite] later, the list of
  [monitor]ed rules will be displayed and will be used again by
  rewrite.

  You should disable the [break-rewrite] feature whenever you are not
  intending to use it, even if the list of [monitor]ed rules is
  empty, because the rewriter is slowed down as long as
  [break-rewrite] is enabled.

  If you get a stack overflow, see [cw-gstack].")
 (BREAK-ON-ERROR
  (TRACE ACL2-BUILT-INS)
  "Break when encountering a hard or soft error caused by ACL2

    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

  Evaluation of [47m(break-on-error :all)[0m generates a suitable [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 [47m(Break-on-error t)[0m, or equivalently,
  [47m(break-on-error)[0m, is similar except that certain errors are ignored
  when inside the theorem prover; this is probably preferable, in
  general, to [47m(break-on-error :all)[0m.  Finally, evaluation of
  [47m(break-on-error nil)[0m removes those traces.

  [31;1mRemarks[0m.

    * The argument, if supplied, is evaluated and must evaluate to [47mt[0m, [47mnil[0m,
      or [47m:all[0m.

    * For technical reasons, you may see breaks or error messages more than
      once.

    * It is an error to call [47mbreak-on-error[0m while in [raw-mode].

    * [47mBreak-on-error[0m is implemented using ACL2 [47m[trace!][0m, which is a version
      of [47m[trace$][0m that uses a [ttag] and hence generates a ``[47mTTAG
      NOTE[0m'' message.  You can use [47m:[0m[47m[trans1][0m to see the [47mtrace![0m call
      generated by a given call of [47mbreak-on-error[0m.  Evaluate [47m(trace$)[0m
      if you want to see the current trace specs.

  You are of course welcome to define your own version of
  [47mbreak-on-error[0m by modifying a copy of the source definition (search
  for ``[47m(defmacro break-on-error)[0m'' in ACL2 source file
  [47mother-events.lisp[0m).  Please feel free to send your version of
  [47mbreak-on-error[0m to the ACL2 implementors, to consider for inclusion
  into ACL2.

  Also see [set-debugger-enable] for how to get raw-Lisp backtrace
  information when an error occurs as a result of [47mbreak-on-error[0m, or
  even of a raw Lisp error, by calling [47mset-debugger-enable[0m with
  argument [47m:bt[0m, [47m:bt-break[0m, or [47m:break-bt[0m.  Note that for ACL2 errors
  (as opposed to raw Lisp errors), i.e. errors affected by
  [47mbreak-on-error[0m, all three of those keyword values are treated
  equivalently (and, all are ignored for non-ANSI GCL; see
  [set-debugger-enable]).")
 (BREAK-REWRITE
  (DEBUGGING)
  "A version of the ACL2 rewriter with interactive breaks

  ACL2 allows the user to [monitor] the application of [rewrite],
  [definition], and [linear] rules.  When the rewriter is about to
  try to apply an [47m[enable][0md [monitor]ed rule, it can trigger an
  interactive break managed by a version of the rewriter called
  ``break-rewrite''.  These breaks can be caused by

    * failure of a rewrite rule's equivalence relation to be a known
      refinement of the permitted relations,

    * failure of a rule's triggering pattern to match the target term while
      ``almost'' matching,

    * failure to relieve the hypotheses of the rule, or

    * failure of any of several heuristic checks to prevent looping in the
      rewriter.

  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, [47m[ld][0m, on a ``[wormhole] [state]'' (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 [brr-commands].  Interactive breaks occur only if
  the [47mbreak-rewrite[0m utility is turned on (see [47m[brr][0m), a monitored
  rune is being considered by the rewriter, and the break conditions
  specified in the monitor are satisfied (see [47m[monitor][0m).

  The following utilities can also be helpful for proof [debugging].

    * [47m[Dmr][0m (Dynamically Monitor Rewrites) allows you to watch progress of
      the rewriter in real time.

    * The [proof-builder] allows you to interactively construct a proof.

    * [47m[with-brr-data][0m helps you to find the source of a term in prover
      output.

  To abort from inside break-rewrite at any time, execute [47m:[0m[47m[a!][0m.

  Output from break-rewrite is abbreviated by default, but that can be
  changed.  See [set-brr-evisc-tuple].

  When the break-rewrite facility is turned on (see [47m[brr][0m), the
  rewriter performs more sluggishly than when break-rewrite is turned
  off.  Therefore if you have done [47m(brr t)[0m to debug a rewriting
  problem, we recommend that you do [47m(brr nil)[0m after the situation is
  remedied and you resume normal proof development.

  For further information, see the related [47m:[0m[47m[doc][0m topics listed below.

  [3mAdvice to Developers and Maintainers of ACL2[0m: If you intend to modify
  break-rewrite, we strongly urge you to read the Essay on
  Break-Rewrite in the source code file [47mrewrite.lisp[0m.  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.

  It is possible to cause the ACL2 rewriter to [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-[47mnil[0m, an interactive read-eval-print loop is entered.

  Break-rewrite permits the user to inspect the current [state] by
  evaluating break-rewrite commands.  Type [47m:help[0m 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,
  [47m[ld][0m, on a certain [state] and the break-rewrite commands are
  simply aliases provided by [47mld-keyword-aliases[0m [table] (see
  [ld-keyword-aliases]).  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 [documentation], print [events], and even
  define functions and prove theorems.  However, the ``certain
  [state]'' upon which [47m[ld][0m was called is a ``wormhole state'' (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 [state] being used by
  rewrite and when break-rewrite exits the [wormhole] closes and the
  [state] ``produced'' by break-rewrite disappears.  For example, all
  invocations of [47m[trace$][0m and [47m[untrace$][0m that are made during such a
  break are undone when proceeding from that break (including when
  proceeding via the [47m:eval[0m 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.

  There are however exceptions to this loss of state when exiting a
  break.  One exception pertains to iprinting (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 [47m[brr-evisc-tuple][0m while inside break-rewrite: the
  effects persist.  See [47m[set-brr-evisc-tuple][0m.

  When you enter break-rewrite a simple herald is printed such as:

    (3 Breaking (:rewrite lemma12) on (delta a (+ 1 j)):

  The integer after the open parenthesis indicates the depth of nested
  break-rewrite calls.  In this discussion we use [47m3[0m 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.

  You then will see the break-rewrite [prompt]:

    3 ACL2 !>

  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.

  You may type arbitrary commands as in the top-level ACL2 loop.  For
  example, you might type:

    3 ACL2 !>:help

  or

    3 ACL2 !>:pe lemma12

  Exceptions are that [47m:[0m[47m[ubt][0m and related commands such as [47m:[0m[47m[ubu][0m, as
  well as [47m[puff][0m and [47m[puff*][0m, are only allowed to touch [command]s
  issued after entering the interactive break.  (Technical detail:
  that is because [47m[disable-ubt][0m is invoked when entering the break.)

  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:

    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

  The output of the [47m:path[0m 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 [47mequal[0m).
  All rewrite frames (including the attempt to apply a given rewrite
  rule) will display the current [geneqv] (the sense of equivalence
  the rewriter is obligated to maintain) unless the geneqv denotes
  just the [47mequal[0mity relation.

  At this point in the interaction the system has not yet tried to
  apply the [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 [47m:ok[0m, [47m:go[0m, and
  [47m:eval[0m.

    :ok

  exits break-rewrite without further interaction at the current depth.
  When break-rewrite exits it prints ``[47m3)[0m'' (actually, of course, the
  current depth!), closing the parenthesis that opened the current
  depth, [47m3[0m, interaction.  However, between your typing the [47m:ok[0m
  command and the exit from depth [47m3[0m you may well see deeper
  break-rewrite breaks --- triggered by any of your monitored runes
  --- as the rewriter tries to apply the lemma that prompted the
  current depth [47m3[0m break.

    :go

  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
  [47m:target[0m term was rewritten to, and if not why the rule was not
  applicable.

    :eval

  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 [47m:go[0m)
  is printed, followed by the [prompt] for additional user input for
  the current depth [47m3[0m.

  Generally speaking, [47m:ok[0m and [47m:go[0m are used when the break in question
  is routine or uninteresting and [47m:eval[0m 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 [47m:target[0m of the current break-rewrite is the term in
  question, you would usually [47m:eval[0m 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
  [47m:[0m[47m[type-alist][0m and perhaps the [linear-arithmetic] [47m:pot-list[0m of
  governing assumptions or why some hypothesis of the rule could not
  be established.

  It is often the case that when you are in break-rewrite you wish to
  change the set of [monitor]ed [rune]s.  This can be done by using
  [47m:[0m[47m[monitor][0m and [47m:[0m[47m[unmonitor][0m as noted above.  For example, you might
  want to [monitor] a certain rule, say [47mhyp-reliever[0m, just when it is
  being used while attempting to apply another rule, say [47mmain-lemma[0m.
  Typically then you would [monitor] [47mmain-lemma[0m at the ACL2
  top-level, start the proof-attempt, and then in the break-rewrite
  in which [47mmain-lemma[0m is about to be tried, you would install a
  [monitor] on [47mhyp-reliever[0m.  If you then [47m:eval[0m and get a break on
  [47mhyp-reliever[0m you will know it is being used under the attempt to
  apply [47mmain-lemma[0m.

  However, when the rewriter leaves this attempt to apply [47mmain-lemma[0m,
  [47mhyp-reliever[0m will no longer be monitored.  That is, the list of
  monitored runes is maintained as a local variable of break-rewrite.
  See [47m[monitored-runes][0m.

  [47m:Ok![0m, [47m:go![0m, and [47m:eval![0m are just like their counterparts ([47m:ok[0m, [47m:go[0m,
  and [47m:eval[0m, 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.

  [47m:Ok$[0m, [47m:go$[0m, and [47m:eval$[0m are similar but take an additional argument
  which must be a list of runic designators (or a single designator).
  See [rune].  Two examples the use of [47m:eval$[0m are

    3 ACL2 !>:eval$ hyp-reliever

  and

    3 ACL2 !>:eval$ (hyp-reliever (:definition foo))

  The second command above is exactly equivalent to

    3 ACL2 !>:monitor hyp-reliever t
    3 ACL2 !>:monitor (:definition foo) t
    3 ACL2 !>:eval

  Analogous remarks apply to [47m:go$[0m and [47m:ok$[0m.  If you want to specify
  more sophisticated break criteria (rather than just [47m:condition t[0m)
  you must use the [47m:monitor[0m command explicitly before proceeding.

  Thus, there are nine ways to proceed from the initial entry into
  break-rewrite although we often speak as though there are two, [47m:ok[0m
  and [47m:eval[0m, and leave the others implicit.  We group [47m:go[0m with [47m:ok[0m
  because in all their flavors they exit break-rewrite without
  further interaction (at the current depth).  All the flavors of
  [47m:eval[0m require further interaction after the rule has been tried.

  You are not permitted to ``re-[47m:eval[0m'' a rule.  That is, after issuing
  the [47m:eval[0m 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 [47m:ok[0m or [47m:go[0m, or
  abort.

  To abort a proof attempt and return to the top-level of ACL2 you may
  at any time type [47m(a!)[0m followed by a carriage return or,
  equivalently (if you are not in a raw Lisp break) use the keyword
  command [47m:a![0m.  See [a!].

  We now address ourselves to the post-[47m:eval[0m interaction with
  break-rewrite.  As noted, post-[47m:eval[0m 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 [47m:eval[0m, namely [47m:wonp[0m, [47m:rewritten-rhs[0m or (for [linear] rules)
  [47m:poly-list[0m, and [47m:failure-reason[0m.  In addition, by using [47m[brr@][0m 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 [monitor] for
  examples.  In this connection we point out the macro form [47m(ok-if
  term)[0m.  See [ok-if].  This command exits break-rewrite if [47mterm[0m
  evaluates to non-[47mnil[0m 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 [47m:eval[0m is
  [47m:ok[0m or [47m:go[0m or the use of [47m[ok-if][0m.

  Note that when inside break-rewrite, all [history] commands, such as
  [47m:[0m[47m[pe][0m, show the [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 [hints] supplied
  for the proof specify [47m(\"Subgoal 3\" :in-theory (disable foo))[0m for
  some rule [47mfoo[0m, then [47m:[0m[47m[pe][0m will indicate that [47mfoo[0m is [disable]d:
  even though [47mfoo[0m may be enabled globally, it is shown as disabled
  because it is disabled during Subgoal 3.  See subtopics of
  [history] for a list of all such history commands.  In addition to
  those commands, the function [47m[disabledp][0m is also evaluated inside
  break-rewrite with respect to the current enabled state of the
  prover.

  We have not discussed ``near-miss'' 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 ``almost'' matches
  according to the criteria.  See [47m[monitor][0m for a discussion of
  near-miss break criteria.  But for example, if [47mmain-lemma[0m rewrites
  the term [47m(f (g (h x) y) x)[0m and you've installed a monitor on it
  like this:

    :monitor main-lemma (:abstraction (f (g u v) w))

  then if the rewriter encountered the target term [47m(F (G (MUMBLE A) B)
  C)[0m it would cause a near-miss break because the pattern of
  [47mmain-lemma[0m does not match the target but the specified abstraction
  of the pattern does match the target.

  You interact with a near-miss break just like the breaks described
  above, except some commands (e.g., [47m:eval[0m) 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.

  The rest of this [documentation] discusses a few implementation
  details of break-rewrite and may not be interesting to the typical
  user.

  There is no ACL2 function named break-rewrite --- 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 [47mnear-miss-brkpt1[0m, [47mbrkpt1[0m and [47mbrkpt2[0m.
  As previously noted, break-rewrite is [47m[ld][0m operating on a
  [wormhole] [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 [state].  The answer is that it
  cannot.  Nothing can be communicated through a [wormhole].  In
  fact, the break point handlers are each calls of [47m[ld][0m running on
  [wormhole] [state]s.  They maintain a state machine inside the
  wormhole.  For example, [47mbrkpt1[0m is called by rewrite after a
  successful match, if the monitored [47m:condition[0m is true, an
  interactive break occurs.  Upon an [47m:ok[0m or [47m:eval[0m, 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 [47mbrkpt2[0m is called.
  [47mBrkpt2[0m then uses the state information in the wormhole to decide
  whether to interact or not.

  This helps explain why the rewriter behaves more sluggishly when [47m(brr
  t)[0m 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 [47m(brr nil)[0m.

  This design causes certain anomalies that might be troubling.

  Suppose you are inside a depth [47m3[0m break before [47m:evaling[0m a rule (i.e.,
  you're in the [47mbrkpt1[0m [wormhole] [state]) you define some function,
  [47mfoo[0m.  Suppose then you [47m:eval[0m the rule and eventually control
  returns to the depth [47m3[0m break (i.e., now you're in the [47mbrkpt2[0m
  [wormhole] [state] with the results of the application in it).  You
  will discover that [47mfoo[0m is no longer defined!  That is because the
  [wormhole] [state] created during your pre-[47m:eval[0m interaction is
  lost when we exit the [wormhole] to resume the proof attempt.  The
  post-[47m:eval[0m [wormhole] [state] is in fact identical to the initial
  pre-[47m:eval[0m [state] (except for the results of the application)
  because [47m[rewrite][0m did not change the external [state] and both
  [wormhole] [state]s are copies of it.  A similar issue occurs with
  the use of [trace] utilities: all effects of calling [47m[trace$][0m and
  [47m[untrace$][0m are erased when you proceed from a break in the
  break-rewrite loop.

  See the subtopics listed below to learn more about [47mbreak-rewrite[0m.


Subtopics

  [Break-lemma]
      A quick introduction to breaking rewrite rules in ACL2

  [Brr]
      To enable or disable the breaking of rewrite rules

  [Brr-commands]
      [Break-Rewrite] Commands

  [Brr-near-missp]
      attachable function for determining ``near misses''

  [Brr@]
      To access context sensitive information within [47m[break-rewrite][0m

  [Cw-gstack]
      Debug a rewriting loop or stack overflow

  [Dmr]
      Dynamically monitor rewrites and other prover activity

  [Geneqv]
      the rewriter's generated equivalence relation

  [Monitor]
      To monitor attempted applications of certain rules by the rewriter

  [Monitor!]
      A quiet combination of [47m[monitor][0m and [47m[brr][0m

  [Monitored-runes]
      Print the [monitor]ed [rune]s and their break conditions

  [Ok-if]
      Conditional exit from [47mbreak-rewrite[0m

  [Refinement-failure]
      what to do when a rewrite rule fails the refinement check

  [Unmonitor]
      To stop monitoring a rule name

  [Why-brr]
      An explanation of why ACL2 has an explicit [47m[brr][0m mode

  [Windows-installation]
      Installing ACL2 on Windows

  [With-brr-data]
      Finding the source of a term in prover output")
 (BREAKS
  (ERRORS)
  "Common Lisp breaks

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

    ACL2 !>

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

  If a break occurs, for example because of a bug in ACL2 or a user
  interrupt, the break will run a Common Lisp read-eval-print loop,
  not an ACL2 read-eval-print loop.  This may not be obvious if the
  [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.

  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 [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.

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

  However, you may be able to quit from the break in the normal Lisp
  manner (as with [47m:q[0m in GCL or CCL, [47m:reset[0m in Allegro CL, and [47mq[0m 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 [47m[brr][0m
  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.")
 (BROKEN-LINK
  (DOCUMENTATION)
  "Placeholder for link to documentation that resides in the community
  books

  You may have attempted to access information about the ACL2
  [community-books] while looking at the ACL2 User's Manual, which
  contains [documentation] only about the ACL2 [3msystem[0m, and does not
  include documentation from the [community-books].  Please point
  your browser at the {ACL2+Books Manual |
  http://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}
  (or if browsing in [ACL2-Doc], switch to that manual with meta-0 I)
  to access the desired topic.

  If you want information about the book where your missing topic is
  defined, see [broken-link-table].


Subtopics

  [Broken-link-table]
      Map [documentation] topics to the community books that define them")
 (BROKEN-LINK-TABLE
  (BROKEN-LINK)
  "Map [documentation] topics to the community books that define them

  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

    (b* \"[books]/std/util/bstar.lisp\")

  signifies that the topic [47mB*[0m is documented in the community book
  [47mstd/util/bstar.lisp[0m.

      ((*acl2-system-exports* \"[books]/system/acl2-system-exports.lisp\")
       (<< \"[books]/misc/total-order.lisp\")
       (acl2s::acl2s-installation \"[books]/acl2s/installation.lisp\")
       (add-io-pairs \"[books]/std/util/add-io-pairs.lisp\")
       (algebra \"[books]/doc/more-topics.lisp\")
       (append-without-guard \"[books]/std/lists/flatten.lisp\")
       (oslib::argv \"[books]/oslib/argv-logic.lisp\")
       (arith-equivs \"[books]/std/basic/arith-equiv-defs.lisp\")
       (arithmetic \"[books]/doc/more-topics.lisp\")
       (arithmetic-1 \"[books]/arithmetic/top.lisp\")
       (arithmetic/natp-posp \"[books]/arithmetic/natp-posp.lisp\")
       (arity+ \"[books]/std/system/arity-plus.lisp\")
       (assert! \"[books]/std/testing/assert-bang.lisp\")
       (assert!-stobj \"[books]/std/testing/assert-bang-stobj.lisp\")
       (b* \"[books]/std/util/bstar.lisp\")
       (bit-vectors \"[books]/doc/more-topics.lisp\")
       (bridge \"[books]/centaur/bridge/top.lisp\")
       (oslib::catpath \"[books]/oslib/catpath.lisp\")
       (build::cert.pl \"[books]/build/doc.lisp\")
       (build::cert_param \"[books]/build/doc.lisp\")
       (cgen \"[books]/acl2s/cgen/top.lisp\")
       (checkpoint-list \"[books]/kestrel/utilities/checkpoints-doc.lisp\")
       (consideration \"[books]/hints/consider-hint.lisp\")
       (build::custom-certify-book-commands \"[books]/build/doc.lisp\")
       (std::defaggregate \"[books]/std/util/defaggregate.lisp\")
       (defconsts \"[books]/std/util/defconsts.lisp\")
       (defdata \"[books]/acl2s/defdata/top.lisp\")
       (define \"[books]/std/util/define.lisp\")
       (defmac \"[books]/misc/defmac.lisp\")
       (defmacroq \"[books]/kestrel/utilities/defmacroq.lisp\")
       (fty::defprod \"[books]/centaur/fty/top.lisp\")
       (defpun \"[books]/misc/defpun.lisp\")
       (defthm<w \"[books]/kestrel/utilities/auto-instance.lisp\")
       (defthmg \"[books]/tools/defthmg.lisp\")
       (acl2s::defunc \"[books]/acl2s/defunc.lisp\")
       (defxdoc \"[books]/xdoc/topics.lisp\")
       (getopt-demo::demo2 \"[books]/centaur/getopt/demo2.lisp\")
       (developers-guide \"[books]/system/doc/developers-guide.lisp\")
       (developers-guide-utilities
            \"[books]/system/doc/developers-guide.lisp\")
       (do-not-hint \"[books]/tools/do-not.lisp\")
       (easy-simplify-term \"[books]/tools/easy-simplify.lisp\")
       (er-soft+ \"[books]/kestrel/utilities/er-soft-plus.lisp\")
       (final-cdr \"[books]/std/lists/final-cdr.lisp\")
       (fty \"[books]/centaur/fty/top.lisp\")
       (getopt \"[books]/centaur/getopt/top.lisp\")
       (gl \"[books]/centaur/gl/doc.lisp\")
       (hacker \"[books]/hacking/hacking-xdoc.lisp\")
       (ihs \"[books]/ihs/ihs-doc-topic.lisp\")
       (include-raw \"[books]/tools/include-raw.lisp\")
       (install-not-normalized \"[books]/misc/install-not-normalized.lisp\")
       (list-equiv \"[books]/std/lists/equiv.lisp\")
       (list-fix \"[books]/std/lists/list-fix.lisp\")
       (logbitp-reasoning \"[books]/centaur/bitops/equal-by-logbitp.lisp\")
       (make-flag \"[books]/tools/flag.lisp\")
       (make-termination-theorem
            \"[books]/kestrel/utilities/make-termination-theorem.lisp\")
       (xdoc::markup \"[books]/xdoc/topics.lisp\")
       (memoized-prover-fns \"[books]/tools/memoize-prover-fns.lisp\")
       (must-fail \"[books]/std/testing/must-fail.lisp\")
       (str::nat-to-dec-string \"[books]/std/strings/decimal.lisp\")
       (non-parallel-book \"[books]/std/system/non-parallel-book.lisp\")
       (note-6-4-books \"[books]/doc/relnotes.lisp\")
       (note-6-5-books \"[books]/doc/relnotes.lisp\")
       (note-7-0-books \"[books]/doc/relnotes.lisp\")
       (note-7-1-books \"[books]/doc/relnotes.lisp\")
       (note-7-2-books \"[books]/doc/relnotes.lisp\")
       (note-8-0-books \"[books]/doc/relnotes.lisp\")
       (note-8-1-books \"[books]/doc/relnotes.lisp\")
       (note-8-2-books \"[books]/doc/relnotes.lisp\")
       (note-8-3-books \"[books]/doc/relnotes.lisp\")
       (note-8-4-books \"[books]/doc/relnotes.lisp\")
       (note-8-5-books \"[books]/doc/relnotes.lisp\")
       (note-8-6-books \"[books]/doc/relnotes.lisp\")
       (str::numbers \"[books]/std/strings/top.lisp\")
       (open-trace-file! \"[books]/tools/open-trace-file-bang.lisp\")
       (oracle-timelimit \"[books]/tools/oracle-timelimit.lisp\")
       (oslib \"[books]/oslib/top-logic.lisp\")
       (patbind-the \"[books]/std/util/bstar.lisp\")
       (build::pre-certify-book-commands \"[books]/build/doc.lisp\")
       (xdoc::preprocessor \"[books]/xdoc/topics.lisp\")
       (str::pretty \"[books]/std/strings/pretty.lisp\")
       (str::pretty-printing \"[books]/std/strings/pretty.lisp\")
       (profile-acl2 \"[books]/centaur/memoize/old/profile.lisp\")
       (profile-all \"[books]/centaur/memoize/old/profile.lisp\")
       (prove$ \"[books]/tools/prove-dollar.lisp\")
       (quicklisp \"[books]/quicklisp/top.lisp\")
       (release-notes-books \"[books]/doc/relnotes.lisp\")
       (removable-runes \"[books]/tools/removable-runes.lisp\")
       (remove-hyps \"[books]/tools/remove-hyps.lisp\")
       (rewrite$ \"[books]/tools/rewrite-dollar.lisp\")
       (rewrite-equiv-hint \"[books]/coi/util/rewrite-equiv.lisp\")
       (rtl \"[books]/rtl/rel11/lib/doc.lisp\")
       (run-script \"[books]/tools/run-script.lisp\")
       (satlink::sat-solver-options \"[books]/centaur/satlink/top.lisp\")
       (satlink \"[books]/centaur/satlink/top.lisp\")
       (xdoc::save \"[books]/xdoc/topics.lisp\")
       (xdoc::save-rendered \"[books]/xdoc/topics.lisp\")
       (xdoc::save-rendered-event \"[books]/xdoc/topics.lisp\")
       (set-max-mem \"[books]/centaur/misc/memory-mgmt-logic.lisp\")
       (spacewalk \"[books]/centaur/misc/spacewalk.lisp\")
       (std \"[books]/std/top.lisp\")
       (std/io \"[books]/std/io/top.lisp\")
       (std/strings \"[books]/std/strings/top.lisp\")
       (std/util \"[books]/std/util/top.lisp\")
       (std::strict-list-recognizers \"[books]/std/util/deflist-base.lisp\")
       (subseq-list \"[books]/std/lists/subseq.lisp\")
       (xdoc::terminal \"[books]/xdoc/topics.lisp\")
       (trans-eval-error-triple
            \"[books]/kestrel/utilities/trans-eval-error-triple.lisp\")
       (trans-eval-state
            \"[books]/kestrel/utilities/trans-eval-error-triple.lisp\")
       (unsound-read \"[books]/std/io/unsound-read.lisp\")
       (untranslate-patterns \"[books]/misc/untranslate-patterns.lisp\")
       (use-trivial-ancestors-check
            \"[books]/tools/trivial-ancestors-check.lisp\")
       (build::using-extended-acl2-images \"[books]/build/doc.lisp\")
       (with-raw-mode \"[books]/hacking/hacking-xdoc.lisp\")
       (with-redef-allowed \"[books]/hacking/hacking-xdoc.lisp\")
       (with-timeout \"[books]/acl2s/cgen/with-timeout.lisp\")
       (without-subsumption \"[books]/tools/without-subsumption.lisp\")
       (working-with-packages \"[books]/doc/practices.lisp\")
       (write-list \"[books]/misc/file-io-doc.lisp\")
       (xdoc \"[books]/xdoc/topics.lisp\"))")
 (BRR
  (BREAK-REWRITE)
  "To enable or disable the breaking of rewrite rules

    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)

  where [47mflg[0m and the optional [47mquietp[0m argument evaluate to [47mt[0m or [47mnil[0m.
  This function modifies [47m[state][0m so that the attempted application of
  certain rewrite rules are ``broken.'' ``[47mBrr[0m'' stands for
  ``break-rewrite'' and can be thought of as a mode with two
  settings.  The normal mode is ``disabled.''

  For a more thorough introduction to the break rewrite system see
  [break-rewrite].  For a related proof debugging utility see
  [with-brr-data].

  When [47mbrr[0m 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 [47mbrr[0m breaks via [47m[brr-commands][0m.

  The rules monitored are selected by using the [47m[monitor][0m and
  [47m[unmonitor][0m 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 [monitor] and see
  [unmonitor].

  Even if a non-empty set of rules has been selected, no breaks will
  occur unless [47mbrr[0m mode is enabled.  Thus, the first time in a
  session that you wish to monitor a rewrite rule, use [47m:brr[0m [47mt[0m to
  enable [47mbrr[0m mode.  Thereafter you may select runes to be monitored
  with [47m[monitor][0m and [47m[unmonitor][0m with the effect that whenever
  monitored rules are tried (and their break conditions are met) an
  interactive break will occur.  Be advised that when [47mbrr[0m 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 --- regardless of what runes are
  monitored --- by disabling [47mbrr[0m mode with [47m:brr[0m [47mnil[0m.

  Why isn't [47mbrr[0m mode disabled automatically when no runes are
  monitored?  More generally, why does ACL2 have [47mbrr[0m mode at all?
  Why not just test whether there are monitored runes?  If you care
  about the answers, see [why-brr].

  BRR Mode, Console Interrupts, and Subsidiary Prover Calls: If the
  system is operating in [47mbrr[0m mode and you break into raw Lisp (as by
  causing a console interrupt or happening upon a signaled Lisp
  error; see [breaks]), you can return to the ACL2 top-level, outside
  any break-rewrite environment, by executing [47m([0m[47m[abort!][0m[47m)[0m.  Otherwise,
  the normal way to quit from such a raw Lisp break (for example [47m:q[0m
  in GCL, [47m:reset[0m in Allegro CL, and [47mq[0m 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 [47m[brr-commands][0m), 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 [47md[0m, you invoke the theorem prover
  recursively as by typing a [47m[thm][0m or [47m[defthm][0m or [47m[defun][0m command to
  break-rewrite, recursive breaks may occur with depths starting at
  [47md+1[0m.  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.


Subtopics

  [Brr-evisc-tuple]
      Determines partial suppression of output from [brr-commands]

  [Set-brr-evisc-tuple]
      Set the [47m[brr-evisc-tuple][0m")
 (BRR-COMMANDS
  (BREAK-REWRITE)
  "[Break-Rewrite] Commands

  Below is a list of commonly used [break-rewrite] keyword commands.
  These are only defined within the breaks caused by [47m[monitor][0ms on
  runes in the process of being considered by the ACL2 rewriter.
  These breaks interact with you from within a [47m[wormhole][0m and are
  handled by [47m[ld][0m (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.

  Many break commands display terms, e.g., the target being rewritten,
  and ``large'' terms are ``eviscerated'' (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 [brr-evisc-tuple].  The notation
  ``[47m:ancestors[+][0m'' below indicates that the [47m:ancestors[0m command may
  print abbreviate terms but the [47m:ancestors+[0m command does not.

    :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)

  The form [47m([0m[47m[brr@][0m[47m :cmd)[0m, 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 [47m[monitor][0m.

  Since you're actually in a general read-eval-print loop when
  interacting with [break-rewrite] you may type the usual ACL2
  commands like [47m:[0m[47m[pbt][0m or [47m:[0m[47m[pe][0m or even [47m[defun][0m and [47m[defthm][0m.  You
  cannot modify [stobj]s or files from within the break.  However,
  all [state] changes you cause from within [break-rewrite] are lost
  when you exit or [47m:eval[0m the rule.

  Note that if you are breaking on a [monitor]ed [linear] rule, several
  of the commands listed above do not apply: [47m:lhs[0m, [47m:rhs[0m,
  [47m:initial-ttree[0m, and [47m:final-ttree[0m.  The pattern used to fire a
  linear rule is found with the command [47m:max-term[0m.  In addition,
  [47m:rewritten-rhs[0m also does not apply to linear rules, but instead,
  [47m:poly-list[0m 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.

  See the discussion of form [2] [47m:[0m[47m[rewrite-quoted-constant][0m rules for
  an explanation of the swapped meanings of ``[47m:lhs[0m'' and ``[47m:rhs[0m.''

  The commands [47m:eval$[0m, [47m:go$[0m, and [47m:ok$[0m take an argument, called runes,
  which may be a list of runes and/or runic designators (see [rune])
  or a single rune or runic designator.  For each rune in runes,
  these commands execute [47m:[0m[47m[monitor][0m rune [47mt[0m, and then execute [47m:eval[0m,
  [47m:go[0m or [47m:ok[0m as appropriate.

  This is useful if you want to monitor the use of a ``secondary'' rune
  only during the attempt to apply a ``primary'' rune: install the
  monitor on the secondary rune inside the break caused by the
  primary rune.  In the case of [47m:eval$[0m, 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 [47m[monitored-runes][0m.  However, when you
  exit that break [47mmonitored-runes[0m will be restored to its earlier
  value.  In the case of [47mgo$[0m and [47mok$[0m, no interactive break occurs
  after the primary rune has been applied.

  Similar remarks apply to [47m:eval![0m, [47m:go![0m, and [47m:ok![0m except they first
  [47m:[0m[47m[unmonitor][0m [47m:all[0m, before proceeding with the appropriate [47m:eval[0m,
  [47m:go[0m, or [47m:ok[0m.  These commands are useful if you want no breaks to
  occur while attempting to apply the rune that caused the current
  break.

  Recall (from the discussion of [47m[monitor][0ms) 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 [47m[monitor][0m.

  Note: If you use commands that change the monitored runes during a
  break, e.g., [47m[monitor][0m, [47m[unmonitor][0m, or [47m:eval![0m, [47m:eval$[0m, etc., then
  abort during the recursion, the list of monitored runes will not
  necessarily be restored to its original top-level setting.")
 (BRR-EVISC-TUPLE
  (BRR EVISC-TUPLE)
  "Determines partial suppression of output from [brr-commands]

  See [evisc-tuple] for relevant background on ``evisceration'':
  eliding of subexpressions during printing.  Also see
  [break-rewrite] for background on the break-rewrite loop.

    General Form:
    (brr-evisc-tuple state)

  The value of this function is used as the evisceration tuple by
  [brr-commands].  The value can be changed with
  [47m[set-brr-evisc-tuple][0m or the more general [47m[set-evisc-tuple][0m.

  A special value, [47m:default[0m, is legal for this evisc-tuple, and is its
  initial value.  In that case the actual evisc-tuple used during
  output from [brr-commands] --- which we call the [3meffective value[0m of
  the [47mbrr-evisc-tuple[0m --- is the value of the evisc-tuple for terms.
  See [set-evisc-tuple], in particular, the discussion of the [47m:term[0m
  site for setting evisc-tuples.

  Think of [47mbrr-evisc-tuple[0m as a true global variable, not a locally
  bound variable of break-rewrite.  In particular, if you set the
  [47mbrr-evisc-tuple[0m inside a break-rewrite interactive break and
  eventually exit that break --- either to enter a deeper break or
  return to a shallower break or to the ACL2 top-level --- the
  [47mbrr-evisc-tuple[0m will retain its chronologically most recent
  setting.

  The [47mbrr-evisc-tuple[0m is used when [break-rewrite] prints its banner
  opening or closing a break on some monitored rune and when certain
  [brr-commands] print their results.

  When you're in a break-rewrite break, you're actually dealing with
  the read-eval-print loop managed by [47m[ld][0m.  It prints its results
  using the [47m[ld-evisc-tuple][0m, while [47m[brr-commands][0m use
  [47mbrr-evisc-tuple[0m.  This can cause some confusion.

  For example, suppose you have set the [47mbrr-evisc-tuple[0m to [47m(evisc-tuple
  2 3 nil nil)[0m so break-rewrite banners and brr-commands only print
  to depth 2 and length 3.  Suppose the target term is [47m(F (G (H 1)) 2
  3 4 5 6 7)[0m.  Then the following interaction with break-rewrite
  could occur:

    3 ACL2 >:target
    (F (G #) 2 ...)
    3 ACL2 >(make-list 10)
    (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)

  You might ask ``Given that the [47mbrr-evisc-tuple[0m limits the print
  length to [47m3[0m, which I see when I print [47m:target[0m, how come the
  [47mmake-list[0m showed all 10 elements?'' The answer is that the
  [47mbrr-command[0m [47m:target[0m actually printed the target with the
  [47mbrr-evisc-tuple[0m and returned [47m(value :invisible)[0m which [47mld[0m's
  read-eval-print loop doesn't print.  But the [47mmake-list[0m returned a
  list of length ten and the read-eval-print loop printed it using
  the [47m[ld-evisc-tuple][0m.

  Another issue relating [47mbrr-evisc-tuple[0m and [47mld-evisc-tuple[0m is that
  while [47mbrr-evisc-tuple[0m is a true global, retaining its
  chronologically most recently set value at all depths of
  break-rewrite, [47mld-evisc-tuple[0m is locally bound by break-rewrite
  (actually, by the [47mld[0m in [47mwormhole[0m) and so sees its value restored as
  break-rewrite ascends back toward the top-level of ACL2.


Subtopics

  [Set-brr-evisc-tuple]
      Set the [47m[brr-evisc-tuple][0m")
 (BRR-NEAR-MISSP
  (BREAK-REWRITE)
  "attachable function for determining ``near misses''

  This is a system function that determine whether a failed match of a
  monitored rule constitutes a near miss.

  [31;1mNote:[0mThis function is attachable (see [defattach]).

    General Form:
    (brr-near-missp msgp lemma target rcnst criteria-alist)

  where msgp is [47mt[0m or [47mnil[0m, [47mlemma[0m is the ACL2 record representing a
  [47m[monitor][0med [47m:rewrite[0m rule or [47m:linear[0m rule, [47mtarget[0m is a term to
  which the rewriter tried to apply the rule but failed to match the
  pattern in the lemma, [47mrcnst[0m is the rewrite constant at the time of
  the attempt, and [47mcriteria-alist[0m is a symbol-alist associated with
  the rule in [47m[monitored-runes][0m.

  The function determines whether the pattern of the lemma ``almost''
  matches the target, i.e., whether a ``near miss'' has occurred.
  The function is only called if the exact match failed.  The
  built-in version of this function checks the criteria described in
  [47m[monitor][0m.  If a near miss has occurred, the result is either [47mt[0m or
  a message (see [47m[msg][0m) object describing the near miss.  If a near
  miss did not occur, the result is [47mnil[0m.  See the source code for
  [47mbuilt-in-brr-near-missp[0m for details of how the built-in version of
  this function operates.")
 (BRR@
  (BREAK-REWRITE)
  "To access context sensitive information within [47m[break-rewrite][0m

    Example:
    (brr@ :target)      ; the term being rewritten
    (brr@ :unify-subst) ; the unifying substitution

    General Form:
    (brr@ :symbol)

  where [47m:symbol[0m is one of the keywords displayed below.  This utility
  may be most useful for system hackers; see [brr-commands] for
  queries that are more at a user level.  In particular, keywords
  marked below with [47m*[0m 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 [term].

    :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.

  In general [47mbrr@-expressions[0m are used in break conditions, the
  expressions that determine whether interactive breaks occur when
  [monitor]ed [rune]s are applied.  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 [47ma[0m is known to be a [47m[consp][0m.  Such conditions can
  be expressed using ACL2 system functions and the information
  provided by [47mbrr@[0m.  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 [47mbrr@[0m provides access to the [47m*[0m'd data.")
 (BUILDING-ACL2
  (ABOUT-ACL2)
  "How to build an ACL2 executable

  This topic summarizes steps for building an ACL2 executable.  For
  more details see the {ACL2 installation page |
  https://www.cs.utexas.edu/users/moore/acl2/current/HTML/installation/installation.html}.

  To build an ACL2 executable, submit the following command while
  standing in the main ACL2 directory, where [47m<my-lisp>[0m invokes your
  Lisp executable (default: [47mccl[0m).

    make LISP=<my-lisp>

  You should find \"Initialization SUCCEEDED.\" near the end of the log.
  Note: There may be ACL2 warnings, for example: \"ACL2 Warning
  [Skip-proofs] in....\".  These may be safely ignored.

  Note that you will want to certify [books] in order to take full
  advantage of ACL2.  See [books-certification].

  See [save-exec] for how to build an ACL2 executable from a state
  resulting from the running of specified [command]s.


Subtopics

  [Ccl-installation]
      Installing Clozure Common Lisp (CCL)

  [Sbcl-installation]
      Installing Steel Bank Common Lisp (SBCL)

  [Sbcl-installation-brief]
      Installing Steel Bank Common Lisp (SBCL)")
 (BUILT-IN-CLAUSE
  (RULE-CLASSES)
  "To build a [clause] into the simplifier

  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.

    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)

  A [47m:built-in-clause[0m rule can be built from any formula other than
  propositional tautologies.  Roughly speaking, the system uses the
  list of built-in [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.''

  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
  [47m:built-in-clause[0m ACL2 flattens the [47m[implies][0m and [47m[and][0m structure of
  the [47m:[0m[47m[corollary][0m 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.

  The example above (regardless of the definition of [47mabl[0m) will build in
  two clauses,

    {(not (true-listp x))
     (equal x nil)
     (< (acl2-count (abl x)) (acl2-count x))}

  and

    {(not (true-listp x))
     (equal nil x)
     (< (acl2-count (abl x)) (acl2-count x))}.

  We now give more background.

  Recall that a clause is a set of terms, implicitly representing the
  disjunction of the terms.  Clause [47mc1[0m is ``subsumed'' by clause [47mc2[0m
  if some instance of [47mc2[0m is a subset [47mc1[0m.

  For example, let [47mc1[0m be

    {(not (consp l))
     (equal a (car l))
     (< (acl2-count (cdr l)) (acl2-count l))}.

  Then [47mc1[0m is subsumed by [47mc2[0m, shown below,

    {(not (consp x))
     ; second term omitted here
     (< (acl2-count (cdr x)) (acl2-count x))}

  because we can instantiate [47mx[0m in [47mc2[0m with [47ml[0m to obtain a subset of [47mc1[0m.

  Observe that [47mc1[0m is the clausal form of

    (implies (and (consp l)
                  (not (equal a (car l))))
             (< (acl2-count (cdr l)) (acl2-count l))),

  [47mc2[0m is the clausal form of

    (implies (consp l)
             (< (acl2-count (cdr l)) (acl2-count l)))

  and the subsumption property just means that [47mc1[0m follows trivially
  from [47mc2[0m by instantiation.

  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 --- 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 [47m[defun][0m'd
  functions and (4) as a filter on the clauses generated to verify
  the guards of a function.

  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.

  The attentive user might have noticed that there are some recursive
  schemes, e.g., recursion by [47m[cdr][0m after testing [47m[consp][0m, 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 [47m[cdr][0m
  recursion after a [47m[consp][0m test is added to the set of built-in
  clauses.  (That clause is [47mc2[0m above.)

  Note that only a subsumption check is made; no rewriting or
  simplification is done.  Thus, if we want the system to ``know''
  that [47m[cdr][0m recursion is ok after a negative [47m[atom][0m test (which, by
  the definition of [47m[atom][0m, is the same as a [47m[consp][0m 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

    {(not (integerp x))
     (< 0 x)
     (= x 0)
     (< (acl2-count (+ -1 x)) (acl2-count x))}

  and the commuted version

    {(not (integerp x))
     (< 0 x)
     (= 0 x)
     (< (acl2-count (+ -1 x)) (acl2-count x))}

  so that the user need not worry whether to write [47m(= x 0)[0m or [47m(= 0 x)[0m
  in definitions.

  [47m:built-in-clause[0m rules added by the user can be enabled and disabled.")
 (BUTLAST
  (LISTS ACL2-BUILT-INS)
  "All but a final segment of a list

  [47m(Butlast l n)[0m is the list obtained by removing the last [47mn[0m elements
  from the true list [47ml[0m.  The following are theorems.

    (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)))))

  For related functions, see [take] and see [nthcdr].

  The [guard] for [47m(butlast l n)[0m requires that [47mn[0m is a nonnegative
  integer and [47mlst[0m is a true list.

  [47mButlast[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.  Note: In Common Lisp the second argument of
  [47mbutlast[0m is optional, but in ACL2 it is required.

  [31;1mFunction: [0m<butlast>

    (defun butlast (lst n)
      (declare (xargs :guard (and (true-listp lst)
                                  (integerp n)
                                  (<= 0 n))))
      (let ((lng (len lst)) (n (nfix n)))
        (if (<= lng n)
            nil
          (take (- lng n) lst))))")
 (BY (POINTERS)
     "See [hints] for information about the keyword [47m:by[0m.")
 (CAAAAR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[caaar][0m

  See any Common Lisp documentation for details.")
 (CAAADR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[caadr][0m

  See any Common Lisp documentation for details.")
 (CAAAR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[caar][0m

  See any Common Lisp documentation for details.")
 (CAADAR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cadar][0m

  See any Common Lisp documentation for details.")
 (CAADDR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[caddr][0m

  See any Common Lisp documentation for details.")
 (CAADR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cadr][0m

  See any Common Lisp documentation for details.")
 (CAAR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[car][0m

  See any Common Lisp documentation for details.")
 (CADAAR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cdaar][0m

  See any Common Lisp documentation for details.")
 (CADADR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cdadr][0m

  See any Common Lisp documentation for details.")
 (CADAR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cdar][0m

  See any Common Lisp documentation for details.")
 (CADDAR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cddar][0m

  See any Common Lisp documentation for details.")
 (CADDDR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cdddr][0m

  See any Common Lisp documentation for details.")
 (CADDR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cddr][0m

  See any Common Lisp documentation for details.")
 (CADR
  (CONSES ACL2-BUILT-INS)
  "[47m[car][0m of the [47m[cdr][0m

  See any Common Lisp documentation for details.")
 (CALLING-LD-IN-BAD-CONTEXTS
  (LD)
  "Errors caused by calling [47m[ld][0m in inappropriate contexts

  The macro [47m[ld][0m 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 [47m[ld][0m during
  the process of loading a compiled file for a book, so that is an
  error.

  Specifically: ACL2 will cause an error in the following two
  circumstances:

    * when calling [47m[ld][0m inside [47m[progn!][0m unless state global [47mld-okp[0m is first
      set to [47mt[0m, e.g., using [47m(assign ld-okp t)[0m; also,

    * when calling [47mld[0m while inside raw Lisp, e.g., when loading a compiled
      file during an invocation of [47m[include-book][0m.

  Consider for example the following book, where file [47mconst.lsp[0m
  contains the single form [47m(defconst *foo* '(a b))[0m after its initial
  [47m[in-package][0m form.

    (in-package \"ACL2\")
    (defttag t)
    (progn! (ld \"const.lsp\"))

  An attempt to certify this book as follows

    (certify-book \"const-wrapper\" 0 t :ttags :all)

  will cause an error:

    ACL2 Error in LD:  It is illegal to call LD in this context.  See :DOC
    calling-ld-in-bad-contexts.

  However, that error can be avoided by expanding the [47m[progn!][0m call as
  follows.

    (progn! (assign ld-okp t)
            (ld \"const.lsp\"))

  Now certification succeeds; however, any subsequent call of
  [47m[include-book][0m will fail to load the compiled file for the book.
  Again, that is necessary because of how ACL2 is designed; in this
  case, the [47m[ld][0m 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 [certify-book] and [include-book].

  Note that it is legal to put a definition such as the following into
  a book, where [47mld[0m is called in the body of a function; the two
  conditions above do not prohibit this.

    (defun foo (state)
      (declare (xargs :guard t :stobjs state :mode :program))
      (ld '((defun h (x) x)) :ld-user-stobjs-modified-warning t))

  One can then include the book, evaluate [47m(foo state)[0m, and then
  evaluate calls of [47mh[0m.")
 (CANONICAL-PATHNAME
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "The true absolute filename, with soft links resolved

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

  The specification of [47m(canonical-pathname fname dir-p state)[0m when
  [47mdir-p[0m is not [47mnil[0m is similar, except that if the specified file
  exists but is not a directory, then the result is [47mnil[0m.

  The function [47mcanonical-pathname[0m has a guard of [47mt[0m, though the second
  argument must be the ACL2 [47m[state][0m.  This function is introduced
  with the following properties.

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

  We use the qualifier ``generally'', above, because there is no
  guarantee that the filename will be canonical without soft links,
  though we expect this to be true in practice.  ACL2 attempts to
  compute the desired result and then checks that the input and
  result have the same Common Lisp ``[47mtruename[0m''.  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
  [47mnil[0m in this case if [47mdir-p[0m is true.")
 (CAR
  (CONSES ACL2-BUILT-INS)
  "Returns the first element of a non-empty list, else [47mnil[0m

  Completion Axiom ([47mcompletion-of-car[0m):

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

  [Guard]:

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

  Notice that in the ACL2 logic, [47mcar[0m returns [47mnil[0m for every [atom].")
 (CASE (BASICS ACL2-BUILT-INS)
  "Conditional based on if-then-else using [47m[eql][0m

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

  is the same as

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

  which in turn is the same as

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

  Notice the quotations that appear in the example above: [47m'(:character
  foo)[0m and [47m'bar[0m.  Indeed, a [47mcase[0m expression expands to a [47m[cond][0m
  expression in which each tested form is quoted, and [47m[eql][0m is used
  to test equality, as described below..

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

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

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

  where each [47mxi[0m is either [47m[eqlablep][0m or a true list of [47m[eqlablep][0m
  objects.  The final [47motherwise[0m or [47mt[0m case is optional; if neither is
  present, then an equivalent expression results from adding the
  final case [47m(t nil)[0m.

  As suggested above, each case [47m(xi val-i)[0m generates an if-then-else
  expression as follows.  If [47mxi[0m is a non-nil atom (i.e., [47mxi[0m is not
  [47mnil[0m or a cons pair), then that case generates the expression [47m(if
  (eql expr (quote xi)) vali ...)[0m where `[47m...[0m' denotes the expression
  generated by the rest of the cases.  If however [47mxi[0m is a list, then
  instead the generated expression is [47m(if (member expr (quote xi))
  vali ...)[0m.  The final case [47m(t val-k+1)[0m or [47m(otherwise val-k+1)[0m
  generates [47mval-k+1[0m.  Note that [47mt[0m and [47motherwise[0m here must be in the
  [47m\"ACL2\"[0m package.  Also note that to compare [47mexpr[0m with [47mnil[0m, you
  should write the case as [47m((nil) val-i)[0m rather than [47m(nil val-i)[0m ---
  and similarly for [47mt[0m or [47motherwise[0m --- that is, put the symbol in a
  list.

  [47mCase[0m is defined in Common Lisp.  See any Common Lisp documentation
  for more information.")
 (CASE-MATCH (BASICS ACL2-BUILT-INS)
  "Pattern matching or destructuring

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

  where [47mx[0m is a symbol, the [47mpati[0m are structural patterns as described
  below, each ``[47mdcli ...[0m'' indicates 0 or more [47m[declare][0m forms, and
  the [47mbodyi[0m are terms.  The legal [47mdeclare[0m forms are the same as for
  [47m[let][0m: [47mignore[0m, [47mignorable[0m, and [47mtype[0m.  Return the value(s) of the
  [47mbodyi[0m corresponding to the first [47mpati[0m matching [47mx[0m, or [47mnil[0m if none
  matches.

  Pattern Language:
  With the few special exceptions described below, matching requires
  that the [47m[cons][0m structure of [47mx[0m be isomorphic to that of the
  pattern, down to the [atom]s in the pattern.  Non-symbol [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 [47mx[0m.  Variables that occur
  more than once must match the same ([47m[equal][0m) structure in every
  occurrence.

    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.

  Some examples are shown below.

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

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

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

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

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

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

  Note that [47mcase-match[0m returns [47mnil[0m if no [47mpati[0m matches.  Thus if we must
  return [47m7[0m in that case, we have to add as the final pattern the [47m&[0m,
  which always matches anything.

  Technical point: The symbol [47msym[0m referenced by the symbol [47m!sym[0m is in
  the same package as [47m!sym[0m but with the leading exclamation point
  character, [47m\\#![0m, removed from the [47m[symbol-name][0m of [47m!sym[0m.")
 (CASE-SPLIT
  (REWRITE LINEAR TYPE-PRESCRIPTION
           DEFINITION META FORWARD-CHAINING)
  "Like force but immediately splits the top-level goal on the
  hypothesis

  [47mCase-split[0m is a variant of [47m[force][0m, which has similar special
  treatment in hypotheses of rules for the same [rule-classes] as for
  [47mforce[0m (see [force]).  This treatment takes place for rule classes
  [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[meta][0m
  (actually in that case, the result of evaluating the hypothesis
  metafunction call), and [47m:[0m[47m[forward-chaining][0m.

  When a hypothesis of a conditional rule (of one of the classes listed
  above) has the form [47m(case-split hyp)[0m it is logically equivalent to
  [47mhyp[0m.  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 [47mhyp[0m 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 [47mhyp[0m is assumed false.  (There are
  exceptions, noted below.)

  For example, given the rule

    (defthm p1->p2
      (implies (case-split (p1 x))
               (p2 x)))

  then an attempt to prove

    (implies (p3 x) (p2 (car x)))

  can give rise to a single subgoal:

    (IMPLIES (AND (NOT (P1 (CAR X))) (P3 X))
             (P2 (CAR X))).

  Unlike [47m[force][0m, [47mcase-split[0m does not delay the ``false case'' to a
  forcing round but tackles it more or less immediately.

  The special ``split'' treatment of [47mcase-split[0m can be disabled by
  disabling forcing: see [force] for a discussion of disabling
  forcing, and also see [disable-forcing].  Finally, we should
  mention that the rewriter is never willing to split when there is
  an [47m[if][0m term present in the goal being simplified.  Since [47m[and][0m
  terms and [47m[or][0m terms are merely abbreviations for [47m[if][0m terms, they
  also prevent splitting.  Note that [47m[if][0m terms are ultimately
  eliminated using the ordinary flow of the proof (but see
  [set-case-split-limitations]), so [47mcase-split[0m will ultimately
  function as intended.

  When in the interactive [proof-builder], [47mcase-split[0m behaves like
  [47mforce[0m.

  [31;1mFunction: [0m<case-split>

    (defun case-split (x)
      (declare (xargs :guard t))
      x)")
 (CASE-SPLIT-LIMITATIONS
  (MISCELLANEOUS)
  "Limiting the number of immediate subgoals

    Examples:
    ACL2 !>(case-split-limitations (w state))
    (500 100)

  With the setting above, which is the default, [47mclausify[0m will not try
  subsumption/replacement if more than 500 [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 [47mIF[0m calls in those
  literals.

  The following example illustrates how the latter restriction ---
  specifically, not rewriting subsequent literals to avoid further
  case splits --- can work.  We define a (rather nonsensical)
  function whose body introduces several cases.

    (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)

  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:

    ; 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))

  That simplification is reflected in the value printed (as an
  implication) for Goal' in the output, below.  If we omit the call
  of [47m[set-case-split-limitations][0m above, then we get 64 cases, from
  opening up the calls of [47mf1[0m and splitting on the variables [47ma[0m, [47mb[0m, [47md[0m,
  [47me[0m, [47mg[0m, and [47mh[0m.  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.

    [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)).

  Why, though, are there 13 cases, even though the limit was specified
  as 10?  Initially, the first literal [47m(EQUAL (F1 A B C) XXX)[0m 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 --- 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.

  In short: the first time a literal splits into enough cases so that
  the accumulated number of cases exceeds the limit, rewriting stops
  --- but that last split can put us significantly past the limit
  specified.

  See [set-case-split-limitations] for a more general discussion.")
 (CASES (POINTERS)
        "See [hints] for information about the keyword [47m:cases[0m.")
 (CBD
  (BOOKS-REFERENCE PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Connected book directory string

    Example:
    ACL2 !>:cbd
    \"/usr/home/smith/\"

  The connected book directory (``cbd'') is a string ending with the [47m/[0m
  character that specifies a directory as an absolute pathname.  (See
  [pathname] for a discussion of file naming conventions.)  When
  utilities that take a filename argument, such as [47m[include-book][0m,
  are given a relative pathname, it is elaborated into an absolute
  pathname, essentially by appending the connected book directory
  string to the left and [47m\".lisp\"[0m to the right.  (This absolute
  pathname is actually canonical when elaborating book names.  For
  more details on book names, see [book-name] and also see
  [full-book-name].)  Furthermore, [47m[include-book][0m and [47m[ld][0m
  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 [set-cbd] for
  how to set the connected book directory string.

  Note that the cbd is used for elaborating every [pathname] argument,
  not just a pathname that represents a book.  (Technical remark:
  Some utilities, such as [47m[open-input-channel][0m, use the cbd
  indirectly as follows.  That utility uses the Common Lisp utility,
  [47mopen[0m, which knows nothing about the cbd.  However, ACL2 arranges
  that the Lisp global [47m*default-pathname-defaults*[0m always has the cbd
  as its value, and Lisp uses that global to elaborate relative
  pathnames much as ACL2 uses the cbd.)

    General Form:
    (cbd)

  This is a macro that expands into a term involving the single free
  variable [47m[state][0m.  It returns the connected book directory string.

  For example, if the [47mcbd[0m is [47m\"/usr/home/smith/\"[0m then the [book-name]
  [47m\"project/task-1/arith\"[0m is elaborated using the [47mcbd[0m to the
  [full-book-name] [47m\"/usr/home/smith/project/task-1/arith.lisp\"[0m, which
  is what [include-book] opens to read the source text for the book.

  The [47mcbd[0m may be changed using [47m[set-cbd][0m.

  As noted above, during the processing of the [events] in a book,
  [47m[include-book][0m sets the [47mcbd[0m to be the directory string of the
  [full-book-name] of the book; similarly for [47m[ld][0m.  Thus, if the [47mcbd[0m
  is [47m\"/usr/home/smith/\"[0m then during the processing of [events] by

    (include-book \"project/task-1/arith\")

  the [47mcbd[0m will be set to [47m\"/usr/home/smith/project/task-1/\"[0m.  Note that
  if [47m\"arith\"[0m recursively includes a sub-book, say [47m\"naturals\"[0m, that
  resides on the same directory, the [47m[include-book][0m event for it may
  omit the specification of that directory.  For example, [47m\"arith\"[0m
  might contain the event

    (include-book \"naturals\").

  In general, suppose we have a superior book and several inferior
  [books] which are included by [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.

  We call this a ``relative'' as opposed to ``absolute'' naming.  The
  use of relative naming is preferred because it permits [books] (and
  their accompanying inferiors) to be moved between directories while
  maintaining their [certificate]s and utility.  Certified [books]
  that reference inferiors by absolute file names are unusable (and
  rendered uncertified) if the inferiors are moved to new
  directories.")
 (CCL-INSTALLATION
  (BUILDING-ACL2)
  "Installing Clozure Common Lisp (CCL)

  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.

    * [ccl-installation-linux-brief]

    * [ccl-installation-mac-brief]

    * [ccl-installation-linux-elaborate]

    * [ccl-installation-mac-elaborate]

  You may prefer instead to look at the {CCL Releases |
  https://github.com/Clozure/ccl/releases} 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 [47mCCL_DEFAULT_DIRECTORY[0m).

  One of the links listed above should generally suffice.  But if you
  would like additional information on CCL installation and
  implementation, see [ccl-installation-extra].


Subtopics

  [Ccl-installation-extra]
      Clozure Common Lisp (CCL) installation and implementation details

  [Ccl-installation-linux-brief]
      Installing Clozure Common Lisp (CCL) on Linux (brief version)

  [Ccl-installation-linux-elaborate]
      Installing Clozure Common Lisp (CCL) on Linux (elaborate version)

  [Ccl-installation-mac-brief]
      Installing Clozure Common Lisp (CCL) on Mac (brief version)

  [Ccl-installation-mac-elaborate]
      Installing Clozure Common Lisp (CCL) on Mac (elaborate version)")
 (CCL-INSTALLATION-EXTRA
  (CCL-INSTALLATION)
  "Clozure Common Lisp (CCL) installation and implementation details

  [31;1mNOTE[0m: See {the Clozure CL releases page |
  https://github.com/Clozure/ccl/releases/} for the latest
  information, which may supersede some of what is included below.

  This topic, contributed by Warren A. Hunt, Jr., extends the basic
  information given in [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 {this page |
  https://github.com/Clozure/ccl/releases/}.

  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.

  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.

  The various stack sizes are set when creating a thread with code in
  [47mCCL::MAKE-PROCESS[0m and [47mCCL::PROCESS-RUN-FUNCTION[0m, and they set the
  three stack sizes of the initial listener thread that is created
  when CCL starts.

  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.

  The temp stack is used for dynamic-extent objects.  This might need
  need to be larger than the default.

  The control stack is used to run C and binary code; it would be
  surprising to need to increase its size.

  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.

    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

  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.


MacOS Build Instructions:

    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

  Rebuild C-based, Lisp kernel

  To rebuild the Lisp-code part of the kernel, do...

    cd lisp-kernel/darwinx8664 ; make ; cd ../..

  Unlike for FreeBSD and Linux, we exclude ``:full t'' from the
  ``rebuild-ccl'' command just below Matt Emerson (a CCL expert)
  writes:

      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.

      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.

  To avoid this, rebuild the lisp with (rebuild-ccl :clean t) instead.
  Do not specify ``[47m:full t[0m''.  Since you have already built the lisp
  kernel, you gain nothing from ``[47m:full t[0m'' doing it again.  So, once
  the C-based, Lisp kernel is built, then do:

    echo \"(in-package :ccl) (rebuild-ccl :verbose t :clean t)\" | \\
          ./dx86cl64 -n |& tee ./ccl-build-compile.log

  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:

      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.

  Thus, we recommend you re-build (compile) the Lisp code again.

    echo \"(in-package :ccl) (rebuild-ccl :verbose t :clean t)\" | \\
          ./dx86cl64 -n |& tee ./ccl-build-compile-2.log

  Finally, one may specialize the final image by:

    cat configure-ccl.lisp | ./dx86cl64 -n |& tee ~/ccl-build-specialize.log

  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''.


FreeBSD Build Instructions:

  The FreeBSD build instructions are similar to the MacOS build
  instruction, but the names are changed appropriately.

    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

  Rebuild C-based Lisp kernel

    cd lisp-kernel/freebsdx8664 ; make ; cd ../..

  To rebuild the Lisp-code part of the kernel, do...

    echo \"(in-package :ccl) (rebuild-ccl :full t :verbose t :clean t)\" | \\
          ./fx86cl64 -n |& tee ./ccl-build-compile.log

  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.

  Matt Emerson recommends building the Lisp code a second time; see the
  ``MacOS Build Instructions'' above for his rationale.

    echo \"(in-package :ccl) (rebuild-ccl :full t :verbose t :clean t)\" | \\
          ./fx86cl64 -n |& tee ./ccl-build-compile-2.log

  Finally, one may specialize the final image by:

    cat ~/a/scripts/configure-ccl.lisp | ./fx86cl64 -n |& tee ~/ccl-build-specialize.log

  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.


configure-ccl.lisp

  Sample ``configure-ccl.lisp'' file for 64-bit implementation:

    (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\")
      )")
 (CCL-INSTALLATION-LINUX-BRIEF
  (CCL-INSTALLATION)
  "Installing Clozure Common Lisp (CCL) on Linux (brief version)

  [31;1mNOTE:[0m See {the Clozure CL releases page |
  https://github.com/Clozure/ccl/releases/} for the latest
  information, which probably supersedes what is included below.

  See [ccl-installation] for introductory remarks.  The instructions
  below describe how to install CCL on Linux.  For more elaborate
  ``cookbook'' instructions see [ccl-installation-linux-elaborate].

  [31;1mNote[0m: Linux users may need to install m4.

  Fetch CCL from GitHub into a fresh subdirectory, [47mccl/[0m.

    git clone https://github.com/Clozure/ccl

  Next fetch and extract a development snapshot in the new [47mccl[0m
  directory.  [31;1mWARNING.[0m The version below is current as of this
  writing (November, 2023), but see
  {https://github.com/Clozure/ccl/releases/ |
  https://github.com/Clozure/ccl/releases/} for the latest snapshots;
  in particular, [47m\"v1.12.2\"[0m below could change, e.g., to [47m\"v1.12.3\"[0m or
  [47m\"v1.13\"[0m.

    cd ccl
    wget https://github.com/Clozure/ccl/releases/download/v1.12.2/linuxx86.tar.gz
    tar xfz linuxx86.tar.gz

  Rebuild and quit, twice.

    echo '(rebuild-ccl :full t)' | ./lx86cl64
    echo '(rebuild-ccl :full t)' | ./lx86cl64

  Create the following executable script, which you will probably want
  to name [47m\"ccl\"[0m, where [47m<DIR>[0m is the absolute pathname (without using
  ``[47m~[0m'') of the directory in which you issued the ``[47mgit clone[0m''
  command.  Place this script wherever you wish, though putting it in
  a directory on your Unix [47mPATH[0m might be helpful (since then you can
  invoke it as, say [47m\"ccl\"[0m).

    #!/bin/sh

    export CCL_DEFAULT_DIRECTORY=<DIR>/ccl
    ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 \"$@\"

  You're done!  (Note however that certification of [books] that use
  [Quicklisp] may require [47mopenssl[0m to be installed if it is not
  already on your system.)")
 (CCL-INSTALLATION-LINUX-ELABORATE
  (CCL-INSTALLATION)
  "Installing Clozure Common Lisp (CCL) on Linux (elaborate version)

  [31;1mNOTE:[0m See {the Clozure CL releases page |
  https://github.com/Clozure/ccl/releases/} for the latest
  information, which may well supersede what is included below.

  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
  [ccl-installation-linux-brief].

  [31;1mNote[0m: Linux users may need to install m4.

  First fetch CCL from GitHub as follows.  (You may prefer to use ``[47mgit
  pull[0m'' if you previously did this step.  In that case you probably
  won't want to do the optional renaming of the directory, mentioned
  below.)

    # 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

  Next fetch and extract a development snapshot in the new [47mccl[0m
  directory.  [31;1mWARNING.[0m The version below is current as of this
  writing (November, 2023), but see
  {https://github.com/Clozure/ccl/releases/ |
  https://github.com/Clozure/ccl/releases/} for the latest snapshots;
  in particular, [47m\"v1.12.2\"[0m below could change, e.g., to [47m\"v1.12.3\"[0m or
  [47m\"v1.13\"[0m.

    wget https://github.com/Clozure/ccl/releases/download/v1.12.2/linuxx86.tar.gz
    tar xfz linuxx86.tar.gz

  Rebuild and quit, twice.

    echo '(rebuild-ccl :full t)' | ./lx86cl64
    echo '(rebuild-ccl :full t)' | ./lx86cl64

  Create an executable script like the following.  You might want to
  call it ``[47mccl[0m'' 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.

    #!/bin/sh

    export CCL_DEFAULT_DIRECTORY=/projects/acl2/lisps/ccl/2017-12-07-6be8298fe5/ccl
    ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 \"$@\"

  Now ensure that your script is executable, e.g.:

    chmod +x my-script

  You're done!  (Note however that certification of [books] that use
  [Quicklisp] may require [47mopenssl[0m to be installed if it is not
  already on your system.)")
 (CCL-INSTALLATION-MAC-BRIEF
  (CCL-INSTALLATION)
  "Installing Clozure Common Lisp (CCL) on Mac (brief version)

  [31;1mNOTE:[0m See {the Clozure CL releases page |
  https://github.com/Clozure/ccl/releases/} for the latest
  information, which probably supersedes what is included below.

  See [ccl-installation] for introductory remarks.  The instructions
  below describe how to install CCL on a Mac (Darwin).  For more
  elaborate ``cookbook'' instructions see
  [ccl-installation-mac-elaborate].

  Fetch CCL from GitHub into a fresh subdirectory, [47mccl/[0m.

    git clone https://github.com/Clozure/ccl

  Next fetch and extract a development snapshot in the new [47mccl[0m
  directory.  [31;1mWARNING.[0m The version below is current as of this
  writing (November, 2023), but see
  {https://github.com/Clozure/ccl/releases/ |
  https://github.com/Clozure/ccl/releases/} for the latest snapshots;
  in particular, [47m\"v1.12.2\"[0m below could change, e.g., to [47m\"v1.12.3\"[0m or
  [47m\"v1.13\"[0m.

    cd ccl
    curl -O -L https://github.com/Clozure/ccl/releases/download/v1.12.2/darwinx86.tar.gz
    tar xfz darwinx86.tar.gz

  Rebuild the lisp kernel by hand before trying to rebuild the lisp.

    cd lisp-kernel/darwinx8664; make clean; make
    cd -

  Rebuild and quit, twice.

    echo '(rebuild-ccl :clean t)' | ./dx86cl64
    echo '(rebuild-ccl :clean t)' | ./dx86cl64

  Create the following executable script, which you will probably want
  to name [47m\"ccl\"[0m, where [47m<DIR>[0m is the absolute pathname (without using
  ``[47m~[0m'') of the directory in which you issued the ``[47mgit clone[0m''
  command.  Place this script wherever you wish, though putting it in
  a directory on your Unix [47mPATH[0m might be helpful (since then you can
  invoke it as, say [47m\"ccl\"[0m).

    #!/bin/sh

    export CCL_DEFAULT_DIRECTORY=<DIR>/ccl
    ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 \"$@\"

  You're done!  (Note however that certification of [books] that use
  [Quicklisp] may require [47mopenssl[0m to be installed if it is not
  already on your system.)")
 (CCL-INSTALLATION-MAC-ELABORATE
  (CCL-INSTALLATION)
  "Installing Clozure Common Lisp (CCL) on Mac (elaborate version)

  [31;1mNOTE:[0m See {the Clozure CL releases page |
  https://github.com/Clozure/ccl/releases/} for the latest
  information, which may well supersede what is included below.

  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 [ccl-installation-mac-brief].

  First fetch CCL from GitHub as follows.  (You may prefer to use ``[47mgit
  pull[0m'' if you previously did this step.  In that case you probably
  won't want to do the optional renaming of the directory, mentioned
  below.)

    # 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

  Next fetch and extract a development snapshot in the new [47mccl[0m
  directory.  [31;1mWARNING.[0m The version below is current as of this
  writing (November, 2023), but see
  {https://github.com/Clozure/ccl/releases/ |
  https://github.com/Clozure/ccl/releases/} for the latest snapshots;
  in particular, [47m\"v1.12.2\"[0m below could change, e.g., to [47m\"v1.12.3\"[0m or
  [47m\"v1.13\"[0m.

    curl -L -O https://github.com/Clozure/ccl/releases/download/v1.12.2/darwinx86.tar.gz
    tar xfz darwinx86.tar.gz

  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).

    cd lisp-kernel/darwinx8664; make clean; make
    cd -

  Rebuild and quit, twice.

    echo '(rebuild-ccl :clean t)' | ./dx86cl64
    echo '(rebuild-ccl :clean t)' | ./dx86cl64

  Create an executable script like the following.  You might want to
  call it ``[47mccl[0m'' 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.

    #!/bin/sh

    export CCL_DEFAULT_DIRECTORY=/projects/acl2/lisps/ccl/2017-12-07-6be8298fe5/ccl
    ${CCL_DEFAULT_DIRECTORY}/scripts/ccl64 \"$@\"

  Now ensure that your script is executable, e.g.:

    chmod +x my-script

  You're done!  (Note however that certification of [books] that use
  [Quicklisp] may require [47mopenssl[0m to be installed if it is not
  already on your system.)")
 (CCL-UPDATES (POINTERS)
              "See [ccl-installation].")
 (CDAAAR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[caaar][0m

  See any Common Lisp documentation for details.")
 (CDAADR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[caadr][0m

  See any Common Lisp documentation for details.")
 (CDAAR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[caar][0m

  See any Common Lisp documentation for details.")
 (CDADAR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cadar][0m

  See any Common Lisp documentation for details.")
 (CDADDR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[caddr][0m

  See any Common Lisp documentation for details.")
 (CDADR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cadr][0m

  See any Common Lisp documentation for details.")
 (CDAR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[car][0m

  See any Common Lisp documentation for details.")
 (CDDAAR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cdaar][0m

  See any Common Lisp documentation for details.")
 (CDDADR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cdadr][0m

  See any Common Lisp documentation for details.")
 (CDDAR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cdar][0m

  See any Common Lisp documentation for details.")
 (CDDDAR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cddar][0m

  See any Common Lisp documentation for details.")
 (CDDDDR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cdddr][0m

  See any Common Lisp documentation for details.")
 (CDDDR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cddr][0m

  See any Common Lisp documentation for details.")
 (CDDR
  (CONSES ACL2-BUILT-INS)
  "[47m[cdr][0m of the [47m[cdr][0m

  See any Common Lisp documentation for details.")
 (CDR
  (CONSES ACL2-BUILT-INS)
  "Returns the second element of a [47m[cons][0m pair, else [47mnil[0m

  Completion Axiom ([47mcompletion-of-cdr[0m):

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

  [Guard]:

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

  Notice that in the ACL2 logic, [47mcdr[0m returns [47mnil[0m for every [atom].")
 (CEILING
  (NUMBERS ACL2-BUILT-INS)
  "Division returning an integer by truncating toward positive infinity

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

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

  The [guard] for [47m(ceiling i j)[0m requires that [47mi[0m and [47mj[0m are rational
  ([real], in ACL2(r)) numbers and [47mj[0m is non-zero.

  [47mCeiling[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.  However, note that unlike Common Lisp, the
  ACL2 [47mceiling[0m function returns only a single value,

  [31;1mFunction: [0m<ceiling>

    (defun ceiling (i j)
      (declare (xargs :guard (and (real/rationalp i)
                                  (real/rationalp j)
                                  (not (eql j 0)))))
      (let* ((q (* i (/ j)))
             (n (numerator q))
             (d (denominator q)))
        (cond ((= d 1) n)
              ((>= n 0)
               (+ (nonnegative-integer-quotient n d)
                  1))
              (t (- (nonnegative-integer-quotient (- n)
                                                  d))))))")
 (CERTIFICATE
  (BOOKS-TOUR)
  "A file specifying validity of a given book

  A book, say [47m\"arith\"[0m, is said to have a ``certificate'' if there is a
  file named [47m\"arith.cert\"[0m.  Certificates are created by the function
  [47m[certify-book][0m and inspected by [47m[include-book][0m.  [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.

  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 [version] number.

  The presence of a ``valid'' certificate file for a book attests to
  two things: all of the [events] of the book are admissible in a
  certain extension of the initial ACL2 logic, and the non-[47m[local][0m
  [events] of the book are independent of the [47m[local][0m ones (see
  [local-incompatibility]).  In addition, the certificate contains
  the [command]s used to construct the [world] in which certification
  occurred.  Among those [command]s, of course, are the [47m[defpkg][0ms
  defining the packages used in the book.  When a book is included
  into a host [world], that [world] is first extended by the
  [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 [world].

  [3mSecurity:[0m

  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.  [Book-hash] values
  are used to help detect such problems, but provide imperfect
  security: two different files can have the same book-hash.

  Therefore, from the strictly logical point of view, one must consider
  even the inclusion of certified [books] as placing a burden on the
  user:

      The non-erroneous inclusion of a certified book is consistency
      preserving provided (a) the objects read by [47m[include-book][0m from
      the certificate were the objects written there by a
      [47m[certify-book][0m and (b) the forms read by [47m[include-book][0m from
      the book itself are the forms read by the corresponding
      [47m[certify-book][0m.

  We say that a given execution of [47m[include-book][0m is ``certified'' if a
  certificate file for the book is present and well-formed and the
  [book-hash] information contained within it supports the conclusion
  that the [events] read by the [47m[include-book][0m are the ones checked
  by [47m[certify-book][0m.  When an uncertified [47m[include-book][0m 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 [books].
  These burdens are easier to live with if you protect your [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 [io] primitives to
  fabricate an inconsistent book and the corresponding certificate.

  Note that part (a) of the burden described above implies, in
  particular, that there are no guarantees when a certificate is
  copied.  When [books] are renamed (as by copying them), it is
  recommended that their certificates be removed and the [books] be
  recertified.  The expectation is that recertification will go
  through without a hitch if relative [pathname]s are used.  See
  [pathname], which is not on the guided tour.

  Certificates contain a [portcullis] and a [keep], each documented
  later in this guided tour through [books].  We mention here two
  other parts, which we do not document elsewhere because we view
  them as implementation details: an [47mexpansion-alist[0m, which records
  [47m[make-event][0m expansions; and [47mcert-data[0m, which contains logical
  information associated with the book.  (Those curious about
  [47mcert-data[0m are invited to look at the ``Essay on Cert-data'' in the
  source code.)

  See [portcullis] to continue the guided tour through [books].


Subtopics

  [Checksum]
      Assigning ``often unique'' integers to files and objects")
 (CERTIFY-BOOK
  (BOOKS-REFERENCE BOOKS-TOUR)
  "How to produce a [certificate] for a book

  Also see [certificate] for information about the [47m\".cert\"[0m file
  produced by [47mcertify-book[0m, in particular for information about the
  use of [book-hash] values to help ensure that the corresponding
  book has not been modified since certification.  See
  [certify-book-debug] for some potential remedies for failures of
  [47mcertify-book[0m.

    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]
                  )

  where [47mbook-name[0m is a book filename, [47mk[0m is used to indicate your
  approval of the ``certification [world],'' and [47mcompile-flg[0m can
  control whether the book is to be compiled.  The defaults for
  [47mcompile-flg[0m, [47mskip-proofs-okp[0m, [47macl2x[0m, [47mwrite-port[0m, [47mpcert[0m,
  [47m:useless-runes[0m, and [47m:write-event-data[0m can be affected by
  environment variables.  All of these arguments are described in
  detail below, except for [47m:pcert[0m, [47m:useless-runes[0m, and
  [47m:write-event-data[0m: see [provisional-certification],
  [useless-runes], and [saving-event-data], respectively, for the
  effects of these three arguments and related environment variables,
  as we ignore those effects in the present topic.

  NOTE: If a given book includes some books (see [include-book]), then
  those included books need to be certified before the given book is
  certified.  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 --- all in the
  proper order, and with parallelism by using the [47m-j[0m option.

  Certification occurs in some logical [world], called the
  ``certification [world].'' That [world] must contain the [47m[defpkg][0ms
  needed to read and execute the forms in the book.  The [command]s
  necessary to recreate that [world] from the ACL2 initial [world]
  are called the ``[portcullis] commands,'' and will be copied into
  the [certificate] created for the book.  Those [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
  [world]) are correctly defined.  Note that Step 1 of [47mcertify-book[0m
  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 [47mFOO::X[0m, but the package \"FOO\" is not currently
  defined.  Then an error message will likely complain either about a
  missing package [47m\"FOO\"[0m, or about a symbol [47mFOO::X[0m that is ``not in
  any of the packages known to ACL2.'' A solution is to define the
  package \"FOO\", perhaps directly using [47m[defpkg][0m or by including a
  book that defines this package, before attempting the
  certification.

  The certified book will be more often usable if the certification
  [world] is kept to a minimal extension of the ACL2 initial [world]
  (for example, to prevent name clashes with functions defined in
  other books, or to avoid including undesired rules).
  Alternatively, use [47m[local][0m [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 [world]
  (e.g., with [47m:ubt 1[0m or by just starting a new ACL2 run), then define
  the desired packages (directly with [47m[defpkg][0m or by including books
  that define the packages), and finally invoke [47mcertify-book[0m.

  The [47mk[0m argument to [47mcertify-book[0m has default value [47m0[0m, and it must be
  either a nonnegative integer or else the symbol [47m?[0m in any package.
  If [47mk[0m is an integer, then it must be the number of [command]s that
  have been executed after the initial ACL2 [world] to create the
  [world] in which [47mcertify-book[0m was called.  One way to obtain this
  number is by doing [47m:pbt :start[0m to see all the [command]s back to
  the first one.

  Otherwise, [47mk[0m is [47m?[0m (or any symbol whose [47m[symbol-name][0m is [47m\"?\"[0m).  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 [world] may be as
  expected.

  We next describe the meaning of [47mcompile-flg[0m and how it defaults.  If
  explicit compilation has been suppressed by [47m(set-compiler-enabled
  nil state)[0m, then [47mcompile-flg[0m is coerced to [47mnil[0m; see [compilation].
  Otherwise [47mcompile-flg[0m may be given the value of [47mt[0m (or [47m:all[0m, which
  is equivalent to [47mt[0m except during provisional certification; see
  [provisional-certification]), indicating that the book is to be
  compiled, or else [47mnil[0m.  (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
  [47mcompile-flg[0m is not supplied (or is [47m:default[0m) then it is treated as
  [47mt[0m.  Note that the value [47m:all[0m is equivalent to [47mt[0m except for during
  the Convert procedure of provisional certification; see
  [provisional-certification].

  Two keyword arguments, [47m:defaxioms-okp[0m and [47m:skip-proofs-okp[0m, determine
  how the system handles the inclusion of [47m[defaxiom][0m events and
  [47m[skip-proofs][0m events, respectively, in the book.  The value [47mt[0m
  allows such events, but prints a warning message.  The value [47mnil[0m
  causes an error if such an event is found.  [47mNil[0m is the default
  unless keyword argument [47m:acl2x t[0m is provided and state global
  [47m'write-acl2x[0m is a cons (see [set-write-ACL2x]), in which case the
  default is [47mt[0m.

  The keyword argument [47m:ttags[0m may normally be omitted.  A few
  constructs, used for example if you are building your own system
  based on ACL2, may require it.  See [defttag] for an explanation of
  this argument.

  When book [47mB[0m is certified with value [47mt[0m (the default, unless the value
  used for [47mpcert[0m is non-[47mnil[0m) for keyword argument [47m:write-port[0m, a file
  [47mB.port[0m is written by certification process.  This file contains all
  of the [portcullis] [command]s for [47mB[0m, i.e., all user commands
  present in the ACL2 logical [world] at the time [47mcertify-book[0m is
  called.  If [47mB.lisp[0m later becomes uncertified, say because [events]
  from that file or an included book have been edited, then
  [47m(include-book \"B\")[0m will consult [47mB.port[0m to evaluate forms in that
  file before evaluating the events in [47mB.lisp[0m.  On the other hand,
  [47mB.port[0m is ignored when including [47mB[0m if [47mB[0m is certified.

  If you use [guard]s, please note [47mcertify-book[0m is executed as though
  [47m(set-guard-checking t)[0m has been evaluated; see
  [set-guard-checking].  If you want to run with different
  guard-checking, consider using [47mld[0m instead, or in addition; see
  [ld].

  For a general discussion of books, see [books].  [47mCertify-book[0m is akin
  to what we have historically called a ``proveall'': all the forms
  in the book are ``proved'' to guarantee their admissibility.  More
  precisely, [47mcertify-book[0m (1) reads the forms in the book, confirming
  that the appropriate packages are defined in the certification
  [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 [embedded-event-form]); (3) may roll back the logical [world]
  (how far? --- see below) and perform an [47m[include-book][0m to check for
  [47m[local][0m incompatibilities (see [local-incompatibility]); (4) writes
  a [certificate] recording not only that the book was certified but
  also recording the [command]s necessary to recreate the
  certification [world] (so the appropriate packages can be defined
  when the book is included in other [world]s) and a [book-hash] for
  each of the [books] involved (see [certificate]); and (5) compiles
  the book if so directed (and then loads the object file in that
  case).

  [47mCertify-book[0m is a macro that returns an [error-triple], where success
  is indicated by an error component of [47mnil[0m and has the effect of
  extending the [world] with a corresponding [47m[include-book][0m event.
  If you don't want the included book's [events] in your present
  [world], simply execute [47m:[0m[47m[u][0m.

  Remark.  Step (3) above mentions rolling back the logical [world] to
  check for local incompatibilities.  This process is skipped if no
  [local] event is encountered.  Otherwise, the world is rolled back
  through the first local event past the boot-strap world --- see
  [local-incompatibility] --- 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
  [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.

  A utility is provided to assist in debugging failures of
  [47mcertify-book[0m; see [redo-flat].)

  [47mCertify-book[0m requires that the default [defun-mode] (see
  [default-defun-mode]) be [47m:[0m[47m[logic][0m when certification is attempted.
  If the mode is not [47m:[0m[47m[logic][0m, an error is signaled.

  An error will occur if [47mcertify-book[0m 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 [certificate] file.

  If you have a certified book that has remained unchanged for some
  time you might well not remember the appropriate [47m[defpkg][0ms for it,
  though they are stored in the [certificate] file and (by default)
  also in the [47m.port[0m file.  If you begin to change the book, don't
  throw away its [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 [47m.port[0m file, as
  it will provide the [portcullis] commands when including the book
  as an uncertified book; see [include-book].

  When [47mcertify-book[0m is directed to produce a compiled file, it calls
  the Common Lisp function [47mcompile-file[0m on the original source file.
  This creates a compiled file with an extension known to ACL2, e.g.,
  if the book is named [47m\"my-book\"[0m then the source file is
  [47m\"my-book.lisp\"[0m and the compiled file under GCL will be [47m\"my-book.o\"[0m
  while under SBCL it will be [47m\"my-book.fasl\"[0m.  The compiled file is
  then loaded.  When [47m[include-book][0m is used later on [47m\"my-book\"[0m 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 [compilation] and loading is that the functions defined in
  the book execute faster.  See [guard] for a discussion of the
  issues, and if you want more details about [books] and compilation,
  see [book-compiled-file].

  When [47mcertify-book[0m is directed not to produce a compiled file, it will
  delete any existing compiled file for the book, so as not to
  mislead [47m[include-book][0m into loading the now outdated compiled file.
  Otherwise, [47mcertify-book[0m 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 [state] global variable
  [47m'save-expansion-file[0m has been set, presumably by a system
  developer, to a non-[47mnil[0m value; see [book-compiled-file] for more
  information about this issue, including the role of environment
  variable [47mACL2_SAVE_EXPANSION[0m.

  After execution of a [47mcertify-book[0m form, the value of
  [47m[ACL2-defaults-table][0m is restored to what it was immediately before
  that [47mcertify-book[0m form was executed.  See [ACL2-defaults-table].

  Those who use the relatively advanced features of trust tags (see
  [defttag]) and [47m[make-event][0m may wish to know how to create a
  [certificate] file that avoids dependence on trust tags that are
  used only during [47m[make-event][0m expansion.  For this, including
  documentation of the [47m:acl2x[0m and [47m:ttagsx[0m keyword arguments for
  [47mcertify-book[0m, see [set-write-ACL2x].

  This completes the tour through the [documentation] of [books].


Subtopics

  [Certify-book!]
      A variant of [47m[certify-book][0m

  [Certify-book-debug]
      Some possible ways to work around [47m[certify-book][0m failures

  [Fast-cert]
      A mode for faster, but possibly unsound, book certification

  [Useless-runes]
      Speed up proofs by disabling useless [rune]s")
 (CERTIFY-BOOK!
  (CERTIFY-BOOK)
  "A variant of [47m[certify-book][0m

    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)

  where [47mbook-name[0m is a book filename, [47mk[0m is a nonnegative integer used
  to indicate the ``certification [world],'' and [47mcompile-flg[0m
  indicates whether you wish to compile the (functions in the) book.

  This [command] is identical to [47m[certify-book][0m, except that the second
  argument [47mk[0m may not be [47mt[0m in [47mcertify-book![0m and if [47mk[0m exceeds the
  current [command] number, then an appropriate [47m[ubt!][0m will be
  executed first.  See [certify-book] and see [ubt!].")
 (CERTIFY-BOOK-DEBUG
  (CERTIFY-BOOK BOOKS-REFERENCE)
  "Some possible ways to work around [47m[certify-book][0m failures

  This topic provides some ideas for how to deal with [47m[certify-book][0m
  failures.  Ideally, this topic will continue to grow over time.

  Stack overflows may show up as follows.

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Stack overflow on value stack.
    ***********************************************

  When this occurs during book certification, it could be during an
  attempt to handle large objects, in particular by the [serialize]
  writer or by a [memoize]d version of the check for ``bad'' objects.
  These two potential causes can be remedied by first evaluating the
  following forms, respectively.

    (set-serialize-character-system nil state)
    (set-bad-lisp-consp-memoize nil)

  If the large object is in an event in the book under certification,
  then you may need to avoid printing it, as follows.

    (set-inhibit-output-lst '(proof-tree event))

  Other failures of [47mcertify-book[0m 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!")
 (CERTIFY-BOOK-FAILURE (POINTERS)
                       "See [certify-book-debug].")
 (CERTIFYING-BOOKS (POINTERS)
                   "See [books-certification].")
 (CHANGE
  (DEFREC ACL2-BUILT-INS)
  "Mutator macro for [defrec] structures.

  The [47mchange[0m macro is built into ACL2, and allows you to \"modify\"
  instances of structures that have been introduced with [defrec].
  Of course, since ACL2 is applicative, the original structure is not
  actually changed---instead, a new structure is constructed, copying
  some fields from the original structure and installing new values
  for other fields.

  For instance, suppose we first use [make] to create an employee
  structure, e.g.,:

    (defconst *jimmy* (make employee :name \"Jimmy\"
                                     :salary 0
                                     :position \"Unpaid Intern\")

  Then we can use [47mchange[0m to mutate this structure, e.g.,:

    (change employee *jimmy* :salary 300000
                             :position \"Vice President\")

  Produces a new [47memployee[0m structure where the [47mname[0m is still \"Jimmy\",
  but where the [47msalary[0m and [47mposition[0m have been updated to 300000 and
  \"Vice President\", respectively.

  See [defrec] for more information.")
 (CHAR
  (STRINGS CHARACTERS ACL2-BUILT-INS)
  "The [nth] element (zero-based) of a string

  [47m(Char s n)[0m is the [47mn[0mth element of [47ms[0m, zero-based.  If [47mn[0m is greater than
  or equal to the length of [47ms[0m, then [47mchar[0m returns [47mnil[0m.

  [47m(Char s n)[0m has a [guard] that [47mn[0m is a non-negative integer and [47ms[0m is a
  [47m[stringp][0m.

  [47mChar[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<char>

    (defun char (s n)
      (declare (xargs :guard (and (stringp s)
                                  (integerp n)
                                  (>= n 0)
                                  (< n (length s)))))
      (nth n (coerce s 'list)))")
 (CHAR-CODE
  (CHARACTERS NUMBERS ACL2-BUILT-INS)
  "The numeric code for a given character

  This function maps a character to its code, for example: [47m(char-code
  #\\A)[0m evaluates to [47m65[0m.  See [47m[code-char][0m for a sort of inverse
  function, which maps a code to the corresponding character.

  Completion Axiom ([47mcompletion-of-char-code[0m):

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

  [Guard] for [47m(char-code x)[0m:

    (characterp x)

  This function maps all non-characters to [47m0[0m.")
 (CHAR-DOWNCASE
  (CHARACTERS ACL2-BUILT-INS)
  "Turn upper-case [characters] into lower-case [characters]

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

  The [guard] for [47mchar-downcase[0m states that its argument is a
  character.

  [47mChar-downcase[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<char-downcase>

    (defun char-downcase (x)
      (declare (xargs :guard (characterp x)))
      (cond ((standard-char-p x)
             (let ((pair (assoc x
                                '((#\\A . #\\a)
                                  (#\\B . #\\b)
                                  (#\\C . #\\c)
                                  (#\\D . #\\d)
                                  (#\\E . #\\e)
                                  (#\\F . #\\f)
                                  (#\\G . #\\g)
                                  (#\\H . #\\h)
                                  (#\\I . #\\i)
                                  (#\\J . #\\j)
                                  (#\\K . #\\k)
                                  (#\\L . #\\l)
                                  (#\\M . #\\m)
                                  (#\\N . #\\n)
                                  (#\\O . #\\o)
                                  (#\\P . #\\p)
                                  (#\\Q . #\\q)
                                  (#\\R . #\\r)
                                  (#\\S . #\\s)
                                  (#\\T . #\\t)
                                  (#\\U . #\\u)
                                  (#\\V . #\\v)
                                  (#\\W . #\\w)
                                  (#\\X . #\\x)
                                  (#\\Y . #\\y)
                                  (#\\Z . #\\z)))))
               (cond (pair (cdr pair)) (t x))))
            (t (char-downcase-non-standard x))))")
 (CHAR-EQUAL
  (CHARACTERS ACL2-BUILT-INS)
  "Character equality without regard to case

  For [characters] [47mx[0m and [47my[0m, [47m(char-equal x y)[0m is true if and only if [47mx[0m
  and [47my[0m are the same except perhaps for their case.

  The [guard] on [47mchar-equal[0m states that its arguments are both
  [characters].

  [47mChar-equal[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<char-equal>

    (defun char-equal (x y)
      (declare (xargs :guard (and (characterp x) (characterp y))))
      (eql (char-downcase x)
           (char-downcase y)))")
 (CHAR-UPCASE
  (CHARACTERS ACL2-BUILT-INS)
  "Turn lower-case [characters] into upper-case [characters]

  [47m(Char-upcase x)[0m is equal to [47m#\\A[0m when [47mx[0m is [47m#\\a[0m, [47m#\\B[0m when [47mx[0m is [47m#\\b[0m,
  ..., and [47m#\\Z[0m when [47mx[0m is [47m#\\z[0m, and is [47mx[0m for any other character.

  The [guard] for [47mchar-upcase[0m states that its argument is a character.

  [47mChar-upcase[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<char-upcase>

    (defun char-upcase (x)
      (declare (xargs :guard (characterp x)))
      (cond ((standard-char-p x)
             (let ((pair (assoc x
                                '((#\\a . #\\A)
                                  (#\\b . #\\B)
                                  (#\\c . #\\C)
                                  (#\\d . #\\D)
                                  (#\\e . #\\E)
                                  (#\\f . #\\F)
                                  (#\\g . #\\G)
                                  (#\\h . #\\H)
                                  (#\\i . #\\I)
                                  (#\\j . #\\J)
                                  (#\\k . #\\K)
                                  (#\\l . #\\L)
                                  (#\\m . #\\M)
                                  (#\\n . #\\N)
                                  (#\\o . #\\O)
                                  (#\\p . #\\P)
                                  (#\\q . #\\Q)
                                  (#\\r . #\\R)
                                  (#\\s . #\\S)
                                  (#\\t . #\\T)
                                  (#\\u . #\\U)
                                  (#\\v . #\\V)
                                  (#\\w . #\\W)
                                  (#\\x . #\\X)
                                  (#\\y . #\\Y)
                                  (#\\z . #\\Z)))))
               (cond (pair (cdr pair)) (t x))))
            (t (char-upcase-non-standard x))))")
 (CHAR<
  (CHARACTERS ACL2-BUILT-INS)
  "Less-than test for [characters]

  [47m(char< x y)[0m is true if and only if the character code of [47mx[0m is less
  than that of [47my[0m.  See [char-code].

  The [guard] for [47mchar<[0m specifies that its arguments are [characters].

  [47mChar<[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<char<>

    (defun char< (x y)
      (declare (xargs :guard (and (characterp x) (characterp y))))
      (< (char-code x) (char-code y)))")
 (CHAR<=
  (CHARACTERS ACL2-BUILT-INS)
  "Less-than-or-equal test for [characters]

  [47m(char<= x y)[0m is true if and only if the character code of [47mx[0m is less
  than or equal to that of [47my[0m.  See [char-code].

  The [guard] for [47mchar<=[0m specifies that its arguments are [characters].

  [47mChar<=[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<char<=>

    (defun char<= (x y)
      (declare (xargs :guard (and (characterp x) (characterp y))))
      (<= (char-code x) (char-code y)))")
 (CHAR>
  (CHARACTERS ACL2-BUILT-INS)
  "Greater-than test for [characters]

  [47m(char> x y)[0m is true if and only if the character code of [47mx[0m is greater
  than that of [47my[0m.  See [char-code].

  The [guard] for [47mchar>[0m specifies that its arguments are [characters].

  [47mChar>[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<char>>

    (defun char> (x y)
      (declare (xargs :guard (and (characterp x) (characterp y))))
      (> (char-code x) (char-code y)))")
 (CHAR>=
  (CHARACTERS ACL2-BUILT-INS)
  "Greater-than-or-equal test for [characters]

  [47m(char>= x y)[0m is true if and only if the character code of [47mx[0m is
  greater than or equal to that of [47my[0m.  See [char-code].

  The [guard] for [47mchar>=[0m specifies that its arguments are [characters].

  [47mChar>=[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<char>=>

    (defun char>= (x y)
      (declare (xargs :guard (and (characterp x) (characterp y))))
      (>= (char-code x) (char-code y)))")
 (CHARACTER-ALISTP
  (CHARACTERS ALISTS ACL2-BUILT-INS)
  "Recognizer for association lists with characters as keys

  [47m(Character-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of
  the form [47m(cons key val)[0m where [47mkey[0m is a [47m[characterp][0m.

  [31;1mFunction: [0m<character-alistp>

    (defun character-alistp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (eq x nil))
            (t (and (consp (car x))
                    (characterp (car (car x)))
                    (character-alistp (cdr x))))))")
 (CHARACTER-ENCODING
  (IO)
  "How bytes are parsed into characters

  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
  [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 [3mcharacter encoding[0m, that is, a
  mapping that associates one or more bytes with each legal
  character.

  In order to help guarantee the portability of files (including
  [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.

  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

    (setq save-buffer-coding-system 'iso-8859-1)

  before saving the buffer into a file.  This will happen automatically
  for users who load distributed file [47memacs-acl2.el[0m (from a suitable
  directory; see [emacs]) into their Emacs sessions.

  For an example of character encodings in action, see the community
  book [47mbooks/misc/character-encoding-test.lisp[0m.")
 (CHARACTER-LISTP
  (CHARACTERS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of characters

  The predicate [47mcharacter-listp[0m tests whether its argument is a true
  list of [characters].

  [31;1mFunction: [0m<character-listp>

    (defun character-listp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (equal l nil))
            (t (and (characterp (car l))
                    (character-listp (cdr l))))))")
 (CHARACTERP
  (CHARACTERS ACL2-BUILT-INS)
  "Recognizer for [characters]

  [47m(characterp x)[0m is true if and only if [47mx[0m is a character.  Note that
  ACL2 supports characters with ASCII codes between 0 and 255.  See
  also [code-char] and [char-code].")
 (CHARACTERS
  (PROGRAMMING)
  "Characters in ACL2 and operations on them

  ACL2 accepts 256 distinct characters, which are the characters
  obtained by applying the function [47m[code-char][0m to each integer from
  [47m0[0m to [47m255[0m.  Among these, Common Lisp designates certain ones as
  [3mstandard characters[0m, namely those of the form [47m(code-char n)[0m where [47mn[0m
  is from [47m33[0m to [47m126[0m, together with [47m#\\Newline[0m and [47m#\\Space[0m.  The actual
  standard characters may be viewed by evaluating the [47m[defconst][0m
  [47m*standard-chars*[0m.

  To be more precise, Common Lisp does not specify the precise
  relationship between [47m[code-char][0m 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
  [47m[char-code][0ms [47m32[0m, [47m9[0m, [47m10[0m, [47m12[0m, [47m127[0m, and [47m13[0m.

  [47m[Code-char][0m has an inverse, [47m[char-code][0m.  Thus, when [47m[char-code][0m is
  applied to an ACL2 character, [47mc[0m, it returns a number [47mn[0m between [47m0[0m
  and [47m255[0m inclusive such that [47m(code-char n)[0m = [47mc[0m.

  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.

  [3mThe Character Reader[0m

  ACL2 supports the `[47m#\\[0m' notation for characters provided by Common
  Lisp, with some restrictions.  First of all, for every character [47mc[0m,
  the notation

    #\\c

  may be used to denote the character object [47mc[0m.  That is, the user may
  type in this notation and ACL2 will read it as denoting the
  character object [47mc[0m.  In this case, the character immediately
  following [47mc[0m must be one of the following ``terminating
  characters'': a Tab, a Newline, a Page character, a space, or one
  of the characters:

    \"  '  (  )  ;  `  ,

  Other than the notation above, ACL2 accepts alternate notation for
  five characters.

    #\\Space
    #\\Tab
    #\\Newline
    #\\Page
    #\\Rubout
    #\\Return

  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 [47m#\\[0m syntax for entering
  characters other than that described above.

  Finally, we note that it is our intention that any object printed by
  ACL2's top-level-loop may be read back into ACL2.  Please notify
  the implementors if you find a counterexample to this claim.


Subtopics

  [Alpha-char-p]
      Recognizer for alphabetic characters

  [Char]
      The [nth] element (zero-based) of a string

  [Char-code]
      The numeric code for a given character

  [Char-downcase]
      Turn upper-case [characters] into lower-case [characters]

  [Char-equal]
      Character equality without regard to case

  [Char-upcase]
      Turn lower-case [characters] into upper-case [characters]

  [Char<]
      Less-than test for [characters]

  [Char<=]
      Less-than-or-equal test for [characters]

  [Char>]
      Greater-than test for [characters]

  [Char>=]
      Greater-than-or-equal test for [characters]

  [Character-alistp]
      Recognizer for association lists with characters as keys

  [Character-listp]
      Recognizer for a true list of characters

  [Characterp]
      Recognizer for [characters]

  [Code-char]
      The character corresponding to a given numeric code

  [Coerce]
      Coerce a character list to a string and a string to a list

  [Digit-char-p]
      The number, if any, corresponding to a given character

  [Digit-to-char]
      Map a digit to a character

  [Explode-atom]
      Convert any [atom] into a [character-listp] that contains its
      printed representation, rendering numbers in your choice of
      print base.

  [Explode-nonnegative-integer]
      The list of [characters] in the radix-r form of a number

  [Lower-case-p]
      Recognizer for lower case characters

  [Make-character-list]
      [coerce] to a list of characters

  [Standard-char-listp]
      Recognizer for a true list of standard characters

  [Standard-char-p]
      Recognizer for standard characters

  [Standard-char-p+]
      Recognizer for standard characters whose guard is [47mt[0m

  [Upper-case-p]
      Recognizer for upper case characters")
 (CHECK-INVARIANT-RISK (POINTERS)
                       "See [set-check-invariant-risk].")
 (CHECK-SUM (POINTERS) "See [checksum].")
 (CHECK-VARS-NOT-FREE
  (MACROS)
  "Avoid variable capture in macro calls

  [47mCheck-vars-not-free[0m 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 [47mcheck-vars-not-free[0m can be useful.

    (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))))

  One might expect [47mf1[0m and [47mf2[0m to be the same function, since the only
  change seems to be from the choices of formal parameters.  However,
  consider these evaluations.

    ACL2 !>(f1 '(a b c d e f) 3)
    T
    ACL2 !>(f2 '(a b c d e f) 3)
    NIL
    ACL2 !>

  The problem becomes clear if we expand the macro call in the body of
  [47mf2[0m.

    ACL2 !>:trans1 (has-length lst (* 2 k))
     (LET ((K (LEN LST))) (EQUAL K (* 2 K)))
    ACL2 !>

  We see that when expanding the call of the macro [47mhas-length[0m in the
  body of [47mf2[0m, the substitution of [47m(* 2 k)[0m for [47m,n[0m causes [47mk[0m to
  be``captured'' by the binding of [47mk[0m to [47m(len lst)[0m.

  The macro [47mcheck-vars-not-free[0m is designed to enforce that no such
  capture takes place.  An improved definition of [47mhas-length[0m is as
  follows, since it insists that the variable [47mk[0m must not appear in
  the term that replaces [47m,n[0m.

    (defmacro has-length (x n)
      `(let ((k (len ,x)))
         (equal k (check-vars-not-free (k) ,n))))

  Now, the attempt to define [47mf2[0m as above causes an error.

    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 !>

  The error message shows that the check performed by
  [47mcheck-vars-not-free[0m has failed, because the variable [47mk[0m occurs in
  the expression [47m(* 2 k)[0m.  More precisely, what is checked is that [47mk[0m
  does not occur in the translation to a [term] of the expression [47m(*
  2 k)[0m, namely, [47m(binary-* '2 k)[0m.

  The general form of a call of [47mcheck-vars-not-free[0m is

    (check-vars-not-free (var_1 ... var_n) expr)

  where [47mvar_1[0m, ..., [47mvar_n[0m are variables and [47mexpr[0m is an expression.
  This call is equivalent to [47mexpr[0m --- indeed, there is no effect on
  the code generated when using this call in place of [47mexpr[0m --- but
  ACL2 requires that the indicated variables do not occur free in the
  translation of [47mexpr[0m to a term.")
 (CHECKPOINT-FORCED-GOALS
  (PROOF-TREE)
  "Cause forcing goals to be checkpointed in proof trees

    Example forms:
    (checkpoint-forced-goals t)
    (checkpoint-forced-goals nil)

  Also see [proof-tree].

  By default, goals are not marked as checkpoints by a proof tree
  display (as described elsewhere; see [proof-tree]) merely because
  they [force] some hypotheses, thus possibly contributing to a
  forcing round.  However, some users may want such behavior, which
  will occur once the command [47m(checkpoint-forced-goals[0m [47mt[0m) has been
  executed.  To return to the default behavior, use the command
  [47m(checkpoint-forced-goals nil)[0m.")
 (CHECKPOINT-SUMMARY-LIMIT
  (SUMMARY SET-GAG-MODE)
  "Control printing of key checkpoints upon a proof's failure

  See [set-checkpoint-summary-limit] for a discussion of the
  checkpoint-summary-limit.  Evaluation of the form
  [47m(checkpoint-summary-limit)[0m produces the current
  checkpoint-summary-limit, and can be invoked with the keyword hack
  (see [keyword-commands]).  For example:

    ACL2 !>:checkpoint-summary-limit
    (NIL . 3)
    ACL2 !>")
 (CHECKSUM
  (CERTIFICATE)
  "Assigning ``often unique'' integers to files and objects

  See [book-hash] for a discussion of how ACL2 can use checksums
  (though not by default) to increase security in the [books]
  mechanism.

  A [3mchecksum[0m is an integer in some fixed range computed from the
  printed representation of an object, e.g., the sum, modulo [47m2**32[0m,
  of the ascii codes of all the [characters] in the printed
  representation.

  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 [47mt[0m).  So you try to design a checksum
  algorithm that maps similar looking objects far apart, in the hopes
  that corruptions and counterfeits --- which appear to be similar to
  the object --- have different 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.

  The basic checksum algorithm in ACL2 is called [47mcheck-sum-obj[0m, 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.")
 (CLAUSE
  (MISCELLANEOUS)
  "A representation of prover goals

  In ACL2, a [3mclause[0m is a list of [term]s, and the meaning of a clause
  is the ACL2 disjunction of those terms where a term [47mp[0m is considered
  ``false'' if ``[47mp[0m = [47mnil[0m'' and is true otherwise.  The elements of a
  clause are called ``literals,'' even though they are just terms.
  For example the goal [47m(IMPLIES (AND p q) r)[0m is internally
  represented as the clause [47m((NOT p) (NOT q) r)[0m.  The literals of
  that clause are the terms [47m(NOT p)[0m, [47m(NOT q)[0m, and [47mr[0m.

  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
  [term]).

  To be precise, suppose that [47m(L1 .. Lk M)[0m is a clause containing at
  least two literals.  ACL2 proof output displays that clause as an
  implication; this is called ``prettyifying a clause''.  Below, [47m~Li[0m
  denotes the [3mnegation[0m of [47mLi[0m in the following sense: if [47mLi[0m is of the
  form [47m(NOT P)[0m then [47m~Li[0m designates [47mP[0m, and otherwise [47m~Li[0m designates
  [47m(NOT Li)[0m.

      [31;1mPrettyifying a clause with at least two literals[0m

        (L1 .. Lk M)

      transforms it to the term

        (IMPLIES (AND ~L1 ~L2 ... ~Lk)
                 M).

  Of course, the disjunction represented by the clause is
  propositionally equivalent to the resulting call of [47mIMPLIES[0m.

  It is sometimes helpful to understand that ACL2's proof processes all
  operate on clauses.  In particular, proof output --- obtained when
  [gag-mode] is turned off or when using [47m:[0m[47m[pso][0m or related utilities
  --- may include a parenthetical remark as follows.  [31;1mWARNING[0m: This
  parenthetical remark is printed only by the main simplifier, not by
  the preprocessor (see [simple]).

    This simplifies (dropping false conclusion; see :DOC clause), using ....

  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.

    (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))))

  The proof attempt starts as follows.

    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)).

  The change from [47mGoal'[0m to [47mGoal''[0m may be jarring because the
  ``conclusion'' --- the second argument of the displayed [47mIMPLIES[0m
  call --- 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.

  A moment's reflection shows that because of the rule [47mFOO-CONSP[0m, [47mGoal'[0m
  is equivalent to

    (IMPLIES (AND (CONSP X)
                  (INTEGERP (CAR X))
                  (<= 0 (CAR X)))
             NIL).

  And a little more reflection shows that the term above is
  propositionally equivalent to [47mGoal''[0m above.

  But this may make more sense if we consider the clauses on which the
  prover operated.  Here are the clauses for [47mGoal'[0m and [47mGoal''[0m; the
  corresponding [47mIMPLIES[0m terms displayed above are obtained by
  prettyifying the respective clauses (in the sense of
  ``prettyifying'' discussed above).

    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))

  For each of these clauses, the third literal, [47m(< (CAR X) '0)[0m, is just
  the negation of the (untranslated) [term], [47m(<= 0 (CAR X))[0m, shown in
  the prover output.

  Recall that a clause represents the disjunction of its literals.
  Since the last literal of [47mGoal'[0m, [47m(NOT (FOO X))[0m, rewrote to [47mNIL[0m
  using the rule [47mFOO-CONSP[0m, it was dropped when creating [47mGoal''[0m:
  after all, [47m(OR P NIL)[0m is propositionally equivalent to [47mP[0m.  So in
  [47mGoal''[0m the last literal is [47m(< (CAR X) '0)[0m.  Therefore, the
  conclusion of each [47mIMPLIES[0m term obtained by prettyifying the clause
  has changed from [47m(NOT (FOO X))[0m to [47m(< (CAR X) '0)[0m.

  Finally, note that although ``dropping false conclusion'' 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.

    (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)

  The output includes the following.

    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)).

  We see that the conclusion was false, hence dropped, in Subgoal 1,
  but remained in Subgoal 2.")
 (CLAUSE-IDENTIFIER
  (GOAL-SPEC)
  "The internal form of a [goal-spec]

  To each goal-spec, [47mstr[0m, there corresponds a [clause]-identifier
  produced by [47m(parse-clause-id str)[0m.  For example,

    (parse-clause-id \"[2]Subgoal *4.5.6/7.8.9'''\")

  returns [47m((2 4 5 6) (7 8 9) . 3)[0m.

  The function [47mstring-for-tilde-@-clause-id-phrase[0m inverts
  [47mparse-clause-id[0m in the sense that given a clause identifier it
  returns the corresponding goal-spec.

  As noted in the documentation for [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
  [47mparse-clause-id[0m converts goal-specs into clause identifiers, which
  are cons-trees containing natural numbers (and if [47m:OR[0m [hints] are
  used, they may also contain symbols of the form [47mDn[0m where [47mn[0m is a
  natural number, e.g., [47mD23[0m.)

  Examples of goal-specs and their corresponding clause identifiers are
  shown below.

                 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

  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.

  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.)")
 (CLAUSE-PROCESSOR
  (RULE-CLASSES)
  "Make or apply a [47m:clause-processor[0m rule (goal-level simplifier)

  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.

  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 [47mevl0[0m in the hypothesis need not be the same as its
  second argument in the conclusion.

    ; 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)

  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
  [47mbooks/clause-processors/[0m; see file [47mReadme.lsp[0m in that directory.

  Also 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 --- hence
  not constrained by virtue of being introduced in the [signature] of
  an [47m[encapsulate][0m --- and must respect [stobj], [df], and output
  arity restrictions.  For example, something like [47m(car (mv ...))[0m is
  illegal; also see [signature].

  INTRODUCTION

  A [47m:clause-processor[0m rule installs a simplifier at the level of goals,
  where a goal is represented as a [clause]: a list of [term]s that
  is implicitly viewed as a disjunction (the application of [47m[or][0m).
  For example, if ACL2 prints a goal in the form [47m(implies (and p q)
  r)[0m, then the clause might be the one-element list containing the
  internal representation of this term --- [47m(implies (if p q 'nil) r)[0m
  --- but more likely, the corresponding clause is [47m((not p) (not q)
  r)[0m.  Note that the members of a clause are [3mtranslated[0m terms; see
  [term] and [47m[termp][0m.  For example, they do not contain calls of the
  macro [47mAND[0m, and constants are quoted.  The result of running a
  clause-processor must be a list of legal clauses; see [meta] for a
  discussion of translated terms, and for related discussion about
  ``forbidden'' function symbols, [set-skip-meta-termp-checks].

  The recognizer for a clause is the function [47m[term-listp][0m and the
  recognizer for a list of clauses is [47m[term-list-listp][0m.

  Note that clause-processor simplifiers are similar to metafunctions,
  and similar efficiency considerations apply.  See [meta], in
  particular the discussion on how to ``make a metafunction maximally
  efficient.''

  Unlike rules of class [47m:[0m[47m[meta][0m, rules of class [47m:clause-processor[0m must
  be applied by explicit [47m:clause-processor[0m [hints]; they are not
  applied automatically (unless by way of computed hints; see
  [computed-hints]).  But [47m:clause-processor[0m 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.

  We begin with a simple illustrative example: a clause-processor that
  assumes an alleged fact (named [47mterm[0m in the example) and creates a
  separate goal to prove that fact.  We can extend the hypotheses of
  the current goal (named [47mcl[0m 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 [47mterm[0m 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).

    (defun note-fact-clause-processor (cl term)
      (declare (xargs :guard t)) ; optional, for better efficiency
      (list (cons (list 'not term)
                  cl)
            (list term)))

  As with [47m:[0m[47m[meta][0m rules, we need to introduce a suitable evaluator; see
  [defevaluator] if you want details.  Since we expect to reason
  about the function [47m[not][0m, because of its role in
  [47mnote-fact-clause-processor[0m as defined above, we include [47mNOT[0m in the
  set of functions known to this evaluator.  We also include [47mIF[0m, as
  is often a good idea.

    (defevaluator evl0 evl0-list
      ((not x) (if x y z)))

  ACL2 can now prove the following theorem automatically.  (This is the
  example displayed at the outset of this [documentation] topic.)  Of
  course, [47m:clause-processor[0m rules about clause-processor functions
  less trivial than [47mnote-fact-clause-processor[0m may require lemmas to
  be proved first!  The function [47mdisjoin[0m takes a clause and returns
  its disjunction (the result of applying [47m[or][0m to its members), and
  [47mconjoin-clauses[0m applies [47mdisjoin[0m to every element of a given list of
  clauses and then conjoins (applies [47mAND[0m) to the corresponding list
  of resulting terms.

    (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)

  Now let us submit a silly but illustrative example theorem to ACL2,
  to show how a corresponding [47m:clause-processor[0m hint is applied.  The
  hint says to apply the clause-processor function,
  [47mnote-fact-clause-processor[0m, to the current goal clause and a ``user
  hint'' as the second argument of that function, in this case [47m(equal
  a a)[0m.  Thus, a specific variable, [47mclause[0m, is always bound to the
  current goal clause for the evaluation of the [47m:clause-processor[0m
  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 [47mnote-fact-clause-processor[0m is applied
  to two arguments: the current clause, which is the one-element list
  [47m((equal (car (cons x y)) x))[0m, and the user hint, [47m(equal a a)[0m.

    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 !>

  That concludes our introduction to clause-processor rules and hints.
  We turn now to detailed documentation.

  DETAILED DOCUMENTATION

  The [signature] of a clause-processor function, [47mCL-PROC[0m, must have
  one of the following forms.  Here, each [47mst_i[0m is a [stobj] (possibly
  [47m[state][0m) while the other parameters and results are not stobjs (see
  [stobj]).  Note that there need not be input stobjs in [3] ---
  i.e., [47mk[0m can be 0 --- and even if there are, there need not be
  output stobjs.  In most ways [3] and [3+] are treated similarly;
  see [make-summary-data] for a discussion of the form of [47md[0m in [3+]
  and, more generally, for how [3+] differs from [3] by enhancing the
  [summary].

    [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))

  We call [47mcl-list[0m the [3mclauses-result[0m.  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 [47mnil[0m.

  We next discuss the legal forms of [47m:clause-processor[0m rules, followed
  below by a discussion of [47m:clause-processor[0m [hints].  In the
  discussion below, we use lower-case names to represent specific
  symbols, for example [47mimplies[0m, and also to represent [stobj] names;
  and we use upper-case names to represent arbitrary pieces of syntax
  (which we will describe), for example, [47mCL[0m.

  If a [47m:[0m[47m[rule-classes][0m specification includes [47m:clause-processor[0m, 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 [47m[world][0m
  to help prove the rule; see [meta-extract] for explanation of this
  advanced feature.)

    ; 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))

  Here [47mEVL[0m is a known evaluator; [47mCL[0m and [47mA[0m are distinct non-stobj
  variables; and [47m<CL-LIST>[0m is an expression representing the clauses
  returned by the clause-processor function [47mCL-PROC[0m, whose form
  depends on the [signature] of that function, as follows.  Typically
  [47mB[0m is [47mA[0m, but it can be any term (useful when generalization is
  occurring; see the example ``Test generalizing alist'' in community
  book [47mbooks/clause-processors/basic-examples.lisp[0m).  For cases [1]
  and [2] above, [47m<CL-LIST>[0m is of the form [47m(CL-PROC CL)[0m or [47m(CL-PROC CL
  HINT)[0m, respectively, where in the latter case [47mHINT[0m is a non-stobj
  variable distinct from the variables [47mCL[0m and [47mA[0m.  For cases [3] and
  [3+], [47m<CL-LIST>[0m is the result of wrapping the function
  [47mclauses-result[0m around a call of [47mCL-PROC[0m:

    (clauses-result (CL-PROC CL HINT ...))

  Logically, [47mclauses-result[0m returns the [47m[cadr][0m if the [47m[car][0m is [47mNIL[0m, and
  otherwise (for the error case) returns a list containing the empty
  (false) clause.  So in the non-error case, [47mclauses-result[0m picks out
  the second result, denoted [47mcl-list[0m in [3] and [3+] above, and in
  the error case the implication above trivially holds.

  In the above theorem, we are asked to prove [47m(EVL (disjoin CL) A)[0m
  assuming that the conjunction of all clauses produced by the clause
  processor evaluates to a non-[47mnil[0m value under some alist [47mB[0m.  In
  fact, we can choose [47mB[0m so as to allow us to assume evaluations of
  the generated clauses over many different alists.  This technique
  is discussed in the community book
  [47mbooks/clause-processors/multi-env-trick.lisp[0m, which introduces some
  macros that may be helpful in accomplishing proofs of this type.

  The clause-processor function, [47mCL[0m, must have a guard that ACL2 can
  trivially prove from the hypotheses that the first argument of [47mCL[0m
  is known to be a [47mpseudo-term-listp[0m and any [stobj] arguments are
  assumed to satisfy their stobj predicates.

  Next we specify the legal forms for [47m:clause-processor[0m [hints].  The
  basic form is [47m:clause-processor TERM[0m, such that the translation of
  [47mTERM[0m to a legal ACL2 term yields a call of a clause-processor
  function [47m(CL-PROC clause)[0m or [47m(CL-PROC clause HINT ...)[0m, where [47mHINT[0m
  is a term whose only non-stobj free variable (if any) is the
  symbol, [47mclause[0m.  Note that the first argument of the call is
  literally the variable, [47mclause[0m.  Recall that at the time the
  :clause-processor hint is applied to the clausal form [47mCL[0m of the
  current subgoal, [47mclause[0m is bound to [47mCL[0m; moreover, any stobj names
  will be bound to the corresponding stobjs.

  But there are two additional general forms for [47m:clause-processor[0m
  hints, which may viewed as abbreviations for the basic form
  discussed above.  The first additional general form, which we call
  the ``[47m:function[0m form'', includes the following two classes of
  expressions.

    :clause-processor (:function F)
    :clause-processor (:function F :hint HINT)

  The first of these [47m:function[0m forms abbreviates the following hint,
  where either [47mF[0m is a macro-alias for the function symbol [47mCL-PROC[0m
  (see [add-macro-alias]), and otherwise [47mCL-PROC[0m is just the function
  symbol [47mF[0m.

    :clause-processor (CL-PROC clause)

  Similarly the second of the [47m:function[0m forms above abbreviates the
  following, where [47mCL-PROC[0m is as above and the output signature of
  [47mCL-PROC[0m is [47m(nil nil st_1 ... st_k)[0m.

    :clause-processor (CL-PROC clause HINT st_1 ... st_k)

  Besides the ``[47m:function[0m form'', there is one more additional general
  form for [47m:clause-processor[0m hint: a symbol, as follows.

    :clause-processor F

  This expands to a basic form as follows, depending on [47mF[0m.

    * If [47mF[0m is a macro with one required argument or a function symbol with
      one argument:
      [47m:clause-processor (F clause)[0m

    * If [47mF[0m is a macro with two required arguments or a function symbol with
      two arguments:
      [47m:clause-processor (F clause nil)[0m

    * If [47mF[0m is a function symbol with inputs of the form [3] or [3+] above,
      that is, with input signature [47m(nil nil st_1 ... st_k)[0m:
      [47m:clause-processor (F clause nil st_1 ... st_k)[0m

  For examples of these syntactic forms, see community book
  [47mbooks/clause-processors/basic-examples.lisp[0m).  We turn now to
  discussion of when a [47m:clause-processor[0m hint causes an abort.

  A [47m:clause-processor[0m hint causes the proof to abort if the
  clauses-result is not a list of clauses, i.e., a list of
  (translated) [term] lists in the current logical [world].  This
  test is done explicitly every time a clause processor is run unless
  a [47m:[0m[47m[well-formedness-guarantee][0m has been provided with the
  [47m:clause-processor[0m rule or [47m[set-skip-meta-termp-checks][0m has been
  used with an active trust tag to skip the check at the user's risk.

  The proof also aborts when the clause-processor function returns at
  least two values and the first value returned --- the ``[47merp[0m'' value
  from cases [3] and [3+] above --- is not [47mnil[0m.  In that case, [47merp[0m 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
  [47m(fmt ~@0 (list (cons #\\0 erp)) ...)[0m (see [fmt]).  Otherwise, a
  non-[47mnil[0m [47merp[0m value causes a generic error message to be printed.

  If there is no error as above, but the [47mCL-PROC[0m 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 [hints-and-the-waterfall]).

  You can see all current [47m:clause-processor[0m rules by issuing the
  following command: [47m(print-clause-processor-rules)[0m.

  The following paper discusses ACL2 clause-processors at a high level
  suitable for a non-ACL2 audience:

      M. Kaufmann, J S. Moore, S. Ray, and E. Reeber, ``Integrating
      External Deduction Tools with ACL2.'' [3mJournal of Applied Logic[0m
      (Special Issue: Empirically Successful Computerized Reasoning),
      Volume 7, Issue 1, March 2009, pp. 3--25.  Also published
      online (DOI [47m10.1016/j.jal.2007.07.002[0m).  Preliminary version
      in: Proceedings of the 6th International Workshop on the
      Implementation of Logics (IWIL 2006) (C. Benzmueller, B.
      Fischer, and G. Sutcliffe, editors), {CEUR Workshop Proceedings
      Vol. 212 | http://ceur-ws.org/Vol-212/}, Phnom Penh, Cambodia,
      pp. 7--26, November 2006.


Subtopics

  [Make-summary-data]
      Return summary data from a [clause-processor] function

  [Meta-extract]
      Meta reasoning using valid terms extracted from context or [world]

  [Set-skip-meta-termp-checks]
      Skip output checks for [meta] functions and [clause-processor]s

  [Set-skip-meta-termp-checks!]
      Skip output checks non-[local]ly for [meta] functions and
      [clause-processor]s")
 (CLEAR-MEMOIZE-STATISTICS
  (MEMOIZE)
  "Clears all profiling info displayed by [47m([0m[47m[memoize-summary][0m[47m)[0m

  Logically, this function just returns [47mnil[0m.  It clears all profiling
  info displayed by [47m([0m[47m[memoize-summary][0m[47m)[0m

  [31;1mFunction: [0m<clear-memoize-statistics>

    (defun clear-memoize-statistics nil
      (declare (xargs :guard t))
      nil)")
 (CLEAR-MEMOIZE-TABLE
  (MEMOIZE)
  "Forget values remembered for the given function

  This function returns its argument, [47mfn[0m, unchanged.  The values
  memoized for [47mfn[0m are forgotten.

  [31;1mFunction: [0m<clear-memoize-table>

    (defun clear-memoize-table (fn)
      (declare (xargs :guard t))
      fn)")
 (CLEAR-MEMOIZE-TABLES
  (MEMOIZE)
  "Forget values remembered for all the memoized functions

  [47mClear-memoize-tables[0m is a logical no-op.  All memoized values are
  forgotten.  It returns [47mnil[0m, invoking [47m[clear-memoize-table][0m for each
  memoized function.

  [31;1mFunction: [0m<clear-memoize-tables>

    (defun clear-memoize-tables nil
      (declare (xargs :guard t))
      nil)")
 (CLOSE-INPUT-CHANNEL (POINTERS)
                      "See [io].")
 (CLOSE-OUTPUT-CHANNEL (POINTERS)
                       "See [io].")
 (CLOSE-TRACE-FILE
  (TRACE)
  "Stop redirecting trace output to a file

    General Form:
    (close-trace-file) ; trace output is no longer redirected to a file

  Output from [47m[trace$][0m normally goes to the screen, or more precisely,
  [47m[standard-co][0m.  It can be redirected to a file; see
  [open-trace-file].  Use [47mclose-trace-file[0m to redirect trace output
  to [47m[standard-co][0m.")
 (CODE-CHAR
  (CHARACTERS NUMBERS ACL2-BUILT-INS)
  "The character corresponding to a given numeric code

  This function maps a numeric code to the corresponding character, for
  example: [47m(code-char 65)[0m evaluates to [47m#\\A[0m.  See [47m[char-code][0m for a
  sort of inverse function, which maps a character to its code.

  Completion Axiom ([47mcompletion-of-code-char[0m):

    (equal (code-char x)
           (if (and (integerp x)
                    (>= x 0)
                    (< x 256))
               (code-char x)
             (code-char 0)))

  [Guard] for [47m(code-char x)[0m:

    (and (integerp x)
         (>= x 0)
         (< x 256))

  ACL2 supports 8-bit [characters].  Inputs not between [47m0[0m and [47m255[0m are
  treated as [47m0[0m.")
 (COERCE
  (STRINGS CHARACTERS ACL2-BUILT-INS)
  "Coerce a character list to a string and a string to a list

  Completion Axiom ([47mcompletion-of-coerce[0m):

    (equal (coerce x y)
           (cond
            ((equal y 'list)
             (if (stringp x)
                 (coerce x 'list)
               nil))
            (t
             (coerce (make-character-list x) 'string))))

  [Guard] for [47m(coerce x y)[0m:

    (if (equal y 'list)
        (stringp x)
      (if (equal y 'string)
          (character-listp x)
        nil))

  Also see community book [47mbooks/misc/fast-coerce.lisp[0m, contributed by
  Jared Davis, for a version of [47mcoerce[0m that may be faster for Common
  Lisp implementations other than CCL 1.3 or later, if the second
  argument is [47m'list[0m (for coercing a string to a list).

  Logical Note

  The function [47mcoerce[0m can be viewed as the constructor for strings.  As
  discussed in Section 7 of \"{A Precise Description of the ACL2 Logic
  | http://www.cs.utexas.edu/users/moore/publications/km97a.pdf}\"
  (Matt Kaufmann and J Moore, April, 1998), a string may be built by
  coercing its list of characters: for example, [47m\"abc\"[0m is [47m(coerce
  '(#\\a #\\b #\\c) 'string)[0m.  More precisely, [47m\"abc\"[0m is an abbreviation
  for [47m(coerce '(#\\a #\\b #\\c) 'string)[0m, where even more pedantically,
  [47m'(#\\a #\\b #\\c)[0m is an abbreviation for [47m(cons '#\\a (cons '#\\b (cons
  '#\\c 'nil)))[0m.")
 (COHERENCE (POINTERS)
            "See [wormhole-status].")
 (COLLECT$ (POINTERS) "See [loop$].")
 (COLLECT$+ (POINTERS) "See [loop$].")
 (COMMA (POINTERS) "See [backquote].")
 (COMMA-ATSIGN (POINTERS)
               "See [backquote].")
 (COMMAND
  (HISTORY)
  "Forms you type at the top-level, but...

  ...the word ``command'' usually refers to a top-level form whose
  evaluation produces a new logical [world].

    Typical commands are:
    (defun foo (x) (cons x x))
    (defthm consp-foo (consp (foo x)))
    (defrec pair (hd . tl) nil)

  The first two forms are examples of commands that are in fact
  primitive [events].  See [events].  [47mDefrec[0m, on the other hand, is a
  macro that expands into a [47m[progn][0m of several primitive [events].
  In general, a [world] extending command generates one or more
  [events].

  Both [events] and commands leave landmarks on the [world] that enable
  us to determine how the given [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 [command-descriptor].")
 (COMMAND-DESCRIPTOR
  (HISTORY)
  "An object describing a particular [command] typed by the user

    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.

  The recorded [history] of your interactions with the top-level ACL2
  [command] loop is marked by the [command]s you typed that changed
  the logical [world].  Each such [command] generated one or more
  [events], since the only way for you to change the logical [world]
  is to execute an event function.  See [command] and see [events].
  We divide [history] into ``[command] blocks,'' grouping together
  each [world] changing [command] and its [events].  A ``[command]
  descriptor'' is an object that can be used to describe a particular
  [command] in the [history] of the ongoing session.

  Each [command] is assigned a unique integer called its ``[command]
  number'' which indicates the [command]'s position in the
  chronological ordering of all of the [command]s ever executed in
  this session (including those executed to initialize the system).
  We assign the number 1 to the first [command] you type to ACL2.  We
  assign 2 to the second and so on.  The non-positive integers are
  assigned to ``prehistoric'' [command]s, i.e., the [command]s used
  to initialize the ACL2 system: 0 is the last [command] of the
  initialization, -1 is the one before that, etc.

  The legal [command] descriptors are described below.  We use [47mn[0m to
  denote any integer, [47msym[0m to denote any logical name (see
  [logical-name]), and [47mcd[0m to denote, recursively, any [command]
  descriptor.

     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.")
 (COMMAND-LINE
  (INTERFACING-TOOLS)
  "Handling of command-line arguments when ACL2 is invoked

  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 [save-exec].


Subtopics

  [Save-exec]
      Save an executable image and a wrapper script")
 (COMMENT
  (HIDE ACL2-BUILT-INS)
  "Variant of [47m[prog2$][0m to help debug evaluation failures during proofs

  Semantically, [47m(comment x y)[0m equals [47my[0m; the value of [47mx[0m is ignored.
  Thus [47mcomment[0m is much like [47m[prog2$][0m.  However, when you see a call
  of [47mcomment[0m in ACL2 proof output, it will likely be under a call of
  [47m[hide][0m, with information that may be helpful in understanding why
  the call of [47mhide[0m was inserted.  Below we illustrate the various
  ways in which ACL2 may replace a term [47mtm[0m by [47m(hide (comment \"...\"
  tm))[0m.  (On occasion you will simply see [47m(hide tm)[0m; such cases are
  not discussed here.)

  Also see [hide] for further discussion of how to avoid such proof
  failures, and for how to keep the prover from inserting a [47mcomment[0m
  call under a call of [47m[hide][0m.


Evaluation during rewriting

  Forms:

    (HIDE (COMMENT \"Failed attempt to call constrained function <fn>\" <term>))
    (HIDE (COMMENT \"Failed attempt to call non-executable function <fn>\" <term>))

  Consider the following example.

    (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)))

  Note that the [definition] of [47mh[0m is disabled, but its
  [executable-counterpart] is not.  The proof attempt fails for the
  [47m[thm][0m call, indicating the checkpoint shown below.

    *** Key checkpoint at the top level: ***

    Goal'
    (EQUAL
     (HIDE
       (COMMENT \"Failed attempt to call constrained function F;
    see :DOC comment\"
                (H 3)))
     '(3 . 3))

  The first argument of [47mequal[0m is logically just [47m(h 3)[0m.  But the [47mcomment[0m
  and [47mhide[0m wrappers are telling us that evaluation of [47m(h 3)[0m failed
  because it led to a call of the constrained function [47mf[0m.  It is easy
  to see why in this case, by looking at the definitions, where [47mh[0m
  calls [47mg[0m, which calls [47mf[0m.  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 [47m[break$][0m call using [47m[trace$][0m, like this (here,
  shown using host Lisp CCL).

    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 ..]]

  This output from Lisp is quite low-level, but reading from the bottom
  up provides the following sequence of events.

    * 4. Call [47mh[0m with argument list [47m(3)[0m.

    * 3. Call the [executable-counterpart] of [47mh[0m.

    * 2. Call the [executable-counterpart] of [47mg[0m.

    * 1. Attempt to call the constrained function, [47mf[0m.

  An easy way to avoid this proof failure is to avoid execution of
  calls of [47mh[0m and [47mg[0m, as follows.

    (thm (equal (h 3) '(3 . 3))
         :hints ((\"Goal\" :in-theory (disable (:e g) (:e h)))))

  (It actually suffices to disable only [47m(:e h)[0m, but the workings of the
  ACL2 rewriter are out of scope here.)

  If the offending function (here, [47mf[0m) is introduced as [non-executable]
  rather than constrained, in particular if that function is defined
  using [47m[defun-nx][0m or [47m[defund-nx][0m, then in the first argument of
  comment you will see ``non-executable'' instead of ``constrained''.


Evaluation during substitution

  Form:

    (HIDE
     (COMMENT
      \"Failed attempt (during substitution) to call constrained function <fn>;
    see :DOC comment\"
      <term>))

  Consider how ACL2 approaches the proof of the non-theorem below.

    (defstub foo (x) t)
    (defund bar (x) (foo x))
    (thm (implies (equal x 3) (equal (bar x) yyy)))

  The prover attacks the [47m[thm][0m event by substituting the constant [47m'3[0m
  for [47mx[0m, which results in an attempt to evaluate [47m(bar 3)[0m.  This
  evaluation fails because [47mbar[0m calls the undefined function [47mfoo[0m.  The
  checkpoint is as follows.

    (EQUAL
     (HIDE
      (COMMENT
         \"Failed attempt (during substitution) to call constrained function FOO;
    see :DOC comment\"
         (BAR 3)))
     YYY)


Failure to expand using a rule

  Form:

    (HIDE (COMMENT \"Unable to expand using the rule <name>;
    see :DOC comment\"
                   <term>))

  Consider how ACL2 approaches the proof for the second event below.

    (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)))

  The checkpoint is as follows.  What happened is that the rule
  [47mnth-open[0m had a hypothesis that was false when an attempt was made
  to apply it to the term [47m(nth i y)[0m.

    (IMPLIES
     (NOT (CONSP Y))
     (EQUAL
      (HIDE (COMMENT \"Unable to expand using the rule NTH-OPEN;
    see :DOC comment\"
                     (NTH I Y)))
      ZZZ))


Failure due to disabled or missing warrants

  Forms:

    (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>))

  The first of these forms may appear when an attempt to evaluate a
  call of [47m[apply$][0m fails because a necessary [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 [disable]d.
  In the following example, the attempt to simplify the call of
  [47mapply$[0m in the theorem ultimately leads to an attempt to evaluate a
  call of [47m[ev$][0m, which ultimately fails because it leads to a call to
  evaluate [47m(apply$ 'bar '(3))[0m [47mbar[0m.  That call causes an error because
  the warrant is unavailable since the rule [47mapply$-bar[0m is disabled,
  hence cannot rewrite a term [47m(apply$ 'bar args)[0m to [47m(bar (car args))[0m.

    (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$))))

  The checkpoint in the proof for the [47mthm[0m just above is as follows.

    (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))

  Similarly, if we instead submit the following event, we see the other
  such message, in this case about a false warrant.

    (thm (implies (not (warrant bar))
                  (equal (apply$ '(lambda (y) (bar y)) '(3)) 3))
         :hints ((\"Goal\" :in-theory (disable ev$))))

  Here is the resulting checkpoint.

    (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))

  Our final example illustrates a failure due to forcing being
  disabled.  The use of [47m[loop$][0m in the definition of [47mbar[0m expands to
  create a call of [47m[ev$][0m, which cannot be simplified during the proof
  of the [47m[thm][0m below because the necessary warrant hypothesis is
  missing and cannot be forced, since forcing is disabled (see also
  [disable-forcing]).

    (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)))))

  Here is the resulting checkpoint.

    (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))")
 (COMMON-LISP
  (ABOUT-ACL2)
  "Relation to Common Lisp, including deviations from the spec

  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 [guard]).

  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.

  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 [47mnil[0m or non-[47mnil[0m.  However, in ACL2
  these functions are assumed to return [47mnil[0m or [47mt[0m.  For details, see
  [generalized-booleans].

  The execution of forms with [47m:[0m[47m[program][0m mode functions can result in
  calls of functions on arguments that do not satisfy their [guard]s.
  In practice, this simply causes hard Lisp errors.  But in principle
  one could imagine a damaged Lisp image that operates incorrectly.
  See [defun-mode-caveat].

  The Common Lisp spec, specifically Section {Section 3.2.2.3 |
  http://www.lispworks.com/documentation/HyperSpec/Body/03_bbc.htm}
  of the {Common Lisp Hyperspec |
  http://www.lispworks.com/documentation/HyperSpec/Front}, allows for
  undefined results when a function is ``multiply defined'' in a
  compiled file.  ACL2 allows redundant [47m[defun][0ms in a book, and in
  general [books] are compiled by [47mcertify-book[0m (but see
  [certify-book] and see [compilation] for how to control such
  compilation).  Moreover, ACL2 provides a redefinition capability
  (see [ld-redefinition-action] and 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.


Subtopics

  [Defun-mode-caveat]
      Potential soundness issue for functions with [defun-mode] [47m:[0m[47m[program][0m

  [Escape-to-common-lisp]
      Escaping to Common Lisp

  [Generalized-booleans]
      Potential soundness issues related to ACL2 predicates

  [Raw-lisp-error]
      Raw lisp errors")
 (COMMON_LISP
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Common Lisp

  {IMAGE} (see [An_Example_Common_Lisp_Function_Definition])

  The logic of ACL2 is based on Common Lisp.

  Common Lisp is the standard list processing programming language.  It
  is documented in: Guy L. Steele, {[31;1mCommon Lisp The Language[0m |
  https://www.cs.cmu.edu/Groups/AI/html/cltl/cltl2.html}, Digital
  Press, 12 Crosby Drive, Bedford, MA 01730, 1990.

  ACL2 formalizes only a subset of Common Lisp.  It includes such
  familiar Lisp functions as [47mcons[0m, [47mcar[0m and [47mcdr[0m for creating and
  manipulating list structures, various arithmetic primitives such as
  [47m+[0m, [47m*[0m, [47mexpt[0m and [47m<=[0m, and [47mintern[0m and [47msymbol-name[0m for creating and
  manipulating symbols.  Control primitives include [47mcond[0m, [47mcase[0m and
  [47mif[0m, as well as function call, including recursion.  New functions
  are defined with [47mdefun[0m and macros with [47mdefmacro[0m.  See [programming]
  {ICON} (see [A_Tiny_Warning_Sign]) for a list of the Common Lisp
  primitives supported by ACL2.

  ACL2 supports five of Common Lisp's datatypes:

  * the precisely represented, unbounded numbers (integers, rationals,
  and the complex numbers with rational components, called the
  ``complex rationals'' here),

  * the characters with ASCII codes between 0 and 255

  * strings of such characters

  * symbols (including packages)

  * conses

  ACL2 is a large subset of the first-order [31;1mapplicative[0m part of Common
  Lisp.  (Roughly speaking, a language is applicative if it follows
  the rules of function application.  For example, [47mf(x)[0m must be equal
  to [47mf(x)[0m, which means, among other things, that the value of [47mf[0m must
  not be affected by ``global variables'' and the object [47mx[0m must not
  change over time.)  It does not support higher-order features of
  Common Lisp, like functional objects and [47mapply[0m.  It does not
  support Common Lisp primitives that have side-effects such as [47msetq[0m,
  [47msetf[0m, 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.

  {IMAGE} (see [An_Example_Common_Lisp_Function_Definition])")
 (COMMON_LISP_AS_A_MODELING_LANGUAGE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Common Lisp as a Modeling Language

  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 [47mapp[0m, please proceed.  Otherwise click
  here (see [Common_Lisp]) for an exceedingly brief introduction to
  Common Lisp and then come [31;1mback[0m here.

  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 [31;1mrun[0m the operations and relations
  you define.  That is, you can execute the functions on concrete
  data to see what results your formulas produce.

  If you define the function [47mapp[0m as shown above and then type

    (app '(A B) '(C D E))

  in any Common Lisp, the answer will be computed and will be [47m(A B C D
  E)[0m.

  The [31;1mexecutable[0m nature of Common Lisp and thus of ACL2 is very handy
  when producing models.

  But executability is not enough for a modeling language because the
  purpose of models is to permit analysis.

  Click here (see [Analyzing_Common_Lisp_Models]) to continue.")
 (COMMUNITY-BOOK (POINTERS)
                 "See [community-books].")
 (COMMUNITY-BOOKS
  (BOOKS)
  "Libraries of ACL2 [books] developed by the ACL2 community.

  ACL2 [books] are files of ACL2 [events] like definitions and
  theorems.

  The ACL2 [31;1mCommunity Books[0m 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.

  From the {github ACL2 project | https://github.com/acl2/acl2/} web
  site you can:

    * Download the Community Books;

    * Learn how to contribute books to the ACL2 community; and

    * Obtain updates between ACL2 releases.

  See [git-quick-start] for information about how to download the
  ``bleeding edge'' ACL2 system and community books.

  The community books are also available with ACL2 releases.  See the
  ``Installing'' link from the {ACL2 home page |
  http://www.cs.utexas.edu/users/moore/acl2/}.


Subtopics

  [Books-certification]
      Instructions for certifying the ACL2 [community-books].")
 (COMP
  (COMPILATION EVENTS ACL2-BUILT-INS)
  "Compile some ACL2 functions

  NOTE: [47mComp[0m is a no-op if explicit compilation is suppressed; see
  [compilation].  The documentation here assumes that this is not the
  case.  See [evaluation] for background on executable-counterpart
  and submitted functions.

    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)

  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 [evaluation].  If guards
  have not been verified, then only the executable-counterpart will
  be evaluated; see [evaluation] and see [guards-and-evaluation], in
  particular the section titled ``Guards and evaluation V: efficiency
  issues''.

  Thus, if you are not verifying [guard]s and you want the benefit of
  Lisp compilation for speed and space efficiency, then you may want
  to place the form [47m(comp :exec)[0m in your [books].

  Generally it is not necessary to place the form [47m(comp t)[0m, or the form
  [47m(comp :raw)[0m, in a book, because [47m[certify-book][0m compiles the raw
  Lisp definitions anyhow, by default.  But you may wish to put [47m(comp
  t)[0m or [47m(comp fn1 fn2 ... fnk)[0m 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.

  As suggested by the examples above, if a function specifier is of the
  form [47m(:raw fn)[0m, then [47mfn[0m will be compiled in raw Common Lisp but its
  corresponding executable-counterpart definition will not be
  compiled; and for [47m(:exec fn)[0m, it's the other way around.

  The use of [47m:comp[0m may create various files whose names start with
  ``[47mTMP*[0m'', but it then deletes them.  If you want to save these
  files, evaluate [47m(assign keep-tmp-files t)[0m.

  Also see [set-compile-fns] for a way to compile each function as it
  is defined.  But note that [47mset-compile-fns[0m is ignored during
  [47m[include-book][0m.

  Note that if functions are traced (see [trace$]), then [47mcomp[0m 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 [47m:comp[0m, the
  resulting traced function will be compiled as well unless you
  specified [47m:compile nil[0m in your trace spec; and after you untrace
  the function it will definitely run compiled.

  We conclude with a technical remark only for those who use trust tags
  to write raw Lisp code.  [47m:Comp[0m 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 [47m(@
  logic-fns-with-raw-code)[0m and [47m(@ program-fns-with-raw-code)[0m.  [47m:Comp[0m
  skips compilation for functions that are already compiled, as is
  typically the case when you redefine functions in raw Lisp using
  [include-raw].  But if you define interpreted (as opposed to
  compiled) functions with raw Lisp code, say by using trust tags
  (see [defttag]) and [47m[progn!][0m, then you are advised to add all such
  symbols to one of the lists stored in the two [state] globals
  above: to [47mlogic-fns-with-raw-code[0m if the function symbol is in
  [47m:[0m[47m[logic][0m mode, else to [47mprogram-fns-with-raw-code[0m.  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 [47mcompile[0m 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
  [remove-untouchable]).

    (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))")
 (COMP-GCL
  (COMPILATION ACL2-BUILT-INS)
  "Compile some ACL2 functions leaving .c and .h files

  [47mComp-gcl[0m 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
  [47m[comp][0m, and has the same basic functionality (see [comp]), but has
  two additional effects.  First, files [47m\"TMP.lisp\"[0m and [47m\"TMP1.lisp\"[0m
  are always created, even when a single function is specified.
  Second, [47mcomp-gcl[0m always leaves files [47m\"TMP.c\"[0m, [47m\"TMP.h\"[0m, [47m\"TMP1.c\"[0m,
  and [47m\"TMP1.h\"[0m when compilation is complete.")
 (COMPARE-OBJECTS
  (DEBUGGING)
  "show differences between two ACL2 objects

  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.

    General Form:
    (compare-objects x y)

  where [47mx[0m and [47my[0m are two (almost) arbitrary objects but which must both
  be [47mcons[0m trees for the comparison to be non-trivial.  The output
  (described below) might be confusing if either object contains
  keywords of the form [47m:<|s...|>[0m, where the ellipsis is the decimal
  representation of a natural number.  For example, the output would
  be confusing if [47mx[0m or [47my[0m contained [47m:|<s1>|[0m because [47mcompare-objects[0m
  inserts tokens like that to mark differences.

  [47mCompare-objects[0m walks through both objects to detect where
  corresponding substructures first differ.  It replaces differences
  by the keyword symbols [47m:|<s1>|[0m, [47m:|<s2>|[0m, [47m:|<s3>|[0m, ..., which we
  call ``placeholders.'' It then assembles a ``legend'' that displays
  triplets of the form [47m(si xi yi)[0m where [47msi[0m is a placeholder marking a
  position in the common superstructure of both [47mx[0m and [47my[0m and [47mxi[0m and [47myi[0m
  are the substructures of [47mx[0m and [47my[0m, respectively, at that position
  that differ.  [47mCompare-objects[0m returns a list consisting of the
  ``common object'' showing the shared superstructure and the legend.

  For example,

    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))))

  By the way, the [47mbrr[0m command [47m:[0m[47m[explain-near-miss][0m sometimes calls
  [47mcompare-objects[0m to show the differences between two unequal quoted
  constants involved in a mismatch.  When [47m:explain-near-miss[0m
  prettyprints the output of [47mcompare-object[0m it does so with an
  [47m[evisc-tuple][0m that simplifies the placeholders.  [47m:Explain-near-miss[0m
  would display the second example above as

    ((:OBJ '(F <s1> <s2> (G X '(A B C . <s3>))))
     (:LEGEND ((<s1> X Y) (<s2> Y X) (<s3> NIL D)))).

  [47mCompare-objects[0m might be especially helpful when looking at big
  [47mlambda[0m objects as produced by translating and rewriting [47m[loop$][0m
  expressions.  For example, below we use [47mcompare-objects[0m to discover
  where two large [47mDO$[0m terms differ.

     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))))

  [47mCompare-objects[0m tells us that a position [47m:|<s1>|[0m the first term calls
  [47mASSOC-EQ-SAFE[0m while the second one calls [47mASSOC-EQ[0m.")
 (COMPILATION
  (PROGRAMMING)
  "Compiling ACL2 functions

  ACL2 has several mechanisms to speed up the evaluation of function
  calls by [3mcompiling[0m functions: see [comp], see [set-compile-fns],
  and 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.

  The [47m[state][0m global variable [47m'compiler-enabled[0m 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
  [47mACL2_COMPILER_DISABLED[0m in distributed file [47mGNUmakefile[0m.)  The value
  of [47m'compiler-enabled[0m, as returned by [47m(@ compiler-enabled)[0m, can be
  [47mt[0m, [47m:books[0m, or [47mnil[0m.  If the value is [47mnil[0m, then [47m[include-book][0m and
  [47m[certify-book][0m coerce their arguments [47m:load-compile-file[0m and
  [47mcompile-flg[0m arguments (respectively) to [47mnil[0m.  Otherwise, the value
  is [47m:books[0m or [47mt[0m and there is no such coercion; but if the value is
  not [47mt[0m, then [47m[comp][0m and [47m[set-compile-fns][0m 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.

  However, you may have reason to want to change the above (default)
  behavior.  To enable compilation by default for [47m[certify-book][0m and
  [47m[include-book][0m but not for [47m[comp][0m or [47m[set-compile-fns][0m:

    (set-compiler-enabled :books state)

  To enable compilation not only as above but also for [47m[comp][0m and
  [47m[set-compile-fns][0m:

    (set-compiler-enabled t state)

  To suppress compilation and loading of compiled files by
  [47m[include-book][0m (for example, if you get a raw Lisp error such as
  ``Wrong FASL version''):

    (set-compiler-enabled nil state)

  Remark for users of [47m[make-event][0m.  If [47mset-compiler-enabled[0m is invoked
  during [47mmake-event[0m expansion, its effect on [47m[state][0m global variable
  [47m'compiler-enabled[0m will persist after evaluation completes for that
  [47mmake-event[0m form.  So for example, one might use the following idiom
  in a book so that for all books included on behalf of a given
  [47m[include-book][0m form, no compiled files are loaded, but (optionally)
  no such effect takes place for later [47minclude-book[0m forms in that
  book.

    (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)

  Upon completion of an invocation of [47m[include-book][0m or [47m[certify-book][0m,
  the value of [47m[state][0m global variable [47m'compiler-enabled[0m is restored
  to the value it had immediately before that invocation.

  See [book-compiled-file] for more discussion about compilation and
  [books].

  We close with a discussion of a feature that allows control over the
  loading of [47m.port[0m files in close analogy to how loading of compiled
  files is controlled by [47mset-compiler-enabled[0m, as described above.
  (See [uncertified-books] for a discussion of [47m.port[0m files.)  A
  [state] global variable, [47m'port-file-enabled[0m exists for this
  purpose, and it is set as follows.

    (set-port-file-enabled t state)   ; permit loading of .port files (default)
    (set-port-file-enabled nil state) ; skip loading of .port files

  Just as described above for state global [47mcompiler-enabled[0m, the value
  of [47m'port-file-enabled[0m persists after [47m[make-event][0m expansion and is
  restored after [47m[certify-book][0m and [47m[include-book][0m.  The idiom
  displayed above, for avoiding loading of compiled files, can be
  modified or extended in the obvious way to avoid loading of [47m.port[0m
  files.


Subtopics

  [Comp]
      Compile some ACL2 functions

  [Comp-gcl]
      Compile some ACL2 functions leaving .c and .h files

  [Disassemble$]
      Disassemble a function

  [Set-compile-fns]
      Have each function compiled as you go along.

  [Set-compiler-enabled]
      Disable [compilation].

  [The]
      Special form for execution efficiency or run-time type checks")
 (COMPILING-ACL2P
  (PARALLELISM)
  "Compiling ACL2(p)

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].
  See [parallelism-tutorial] for an introduction to parallel
  programming in ACL2.

  You can build an experimental version of ACL2 that supports parallel
  execution in the following host Common Lisp implementations:

      * CCL (OpenMCL)

      * Lispworks 6.0

      * SBCL with threads (feature [47m:sb-thread[0m)

  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 [47mt[0m, and the value of [47mLISP[0m (shown here as
  [47mccl[0m) is any Lisp executable on which one can build ACL2(p) (see
  [parallelism]).

    make ACL2_PAR=t LISP=ccl

  So for example, to make an executable image and also documentation
  (which will appear in subdirectories [47mdoc/EMACS[0m and [47mdoc/HTML[0m), using
  the Lisp executable [47mccl[0m:

    make large DOC ACL2_PAR=t LISP=ccl")
 (COMPLEX
  (NUMBERS ACL2-BUILT-INS)
  "Create an ACL2 number

    Examples:
    (complex x 3) ; x + 3i, where i is the principal square root of -1
    (complex x y) ; x + yi
    (complex x 0) ; same as x, for rational numbers x

  The function [47mcomplex[0m takes two rational number arguments and returns
  an ACL2 number.  This number will be of type [47m(complex rational)[0m [as
  defined in the Common Lisp language], except that if the second
  argument is zero, then [47mcomplex[0m returns its first argument.  The
  function [47m[complex-rationalp][0m is a recognizer for complex rational
  numbers, i.e. for ACL2 numbers that are not rational numbers.

  The reader macro [47m#C[0m (which is the same as [47m#c[0m) provides a convenient
  way for typing in complex numbers.  For explicit rational numbers [47mx[0m
  and [47my[0m, [47m#C(x y)[0m is read to the same value as [47m(complex x y)[0m.

  The functions [47m[realpart][0m and [47m[imagpart][0m return the real and imaginary
  parts (respectively) of a complex (possibly rational) number.  So
  for example, [47m(realpart #C(3 4)) = 3[0m, [47m(imagpart #C(3 4)) = 4[0m,
  [47m(realpart 3/4) = 3/4[0m, and [47m(imagpart 3/4) = 0[0m.

  The following built-in axiom may be useful for reasoning about
  complex numbers.

    (defaxiom complex-definition
      (implies (and (real/rationalp x)
                    (real/rationalp y))
               (equal (complex x y)
                      (+ x (* #c(0 1) y))))
      :rule-classes nil)

  A completion axiom that shows what [47mcomplex[0m returns on arguments
  violating its [guard] (which says that both arguments are rational
  numbers) is the following, named [47mcompletion-of-complex[0m.

    (equal (complex x y)
           (complex (if (rationalp x) x 0)
                    (if (rationalp y) y 0)))")
 (COMPLEX-RATIONALP
  (NUMBERS ACL2-BUILT-INS)
  "Recognizes complex rational numbers

    Examples:
    (complex-rationalp 3)       ; nil, as 3 is rational, not complex rational
    (complex-rationalp #c(3 0)) ; nil, since #c(3 0) is the same as 3
    (complex-rationalp t)       ; nil
    (complex-rationalp #c(3 1)) ; t, as #c(3 1) is the complex number 3 + i

  See [complex] for more about complex rationals in ACL2.")
 (COMPLEX/COMPLEX-RATIONALP
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for complex numbers

  For most ACL2 users, this is a macro abbreviating [47mcomplex-rationalp[0m;
  see [complex-rationalp].  In ACL2(r) (see [real]), a complex number
  [47mx[0m may have irrational real and imaginary parts.  This macro
  abbreviates the predicate [47mcomplexp[0m in ACL2(r), which holds for such
  [47mx[0m.  Most ACL2 users can ignore this macro and use
  [47m[complex-rationalp][0m instead.  Some community books use
  [47mcomplex/complex-rationalp[0m so that they are suitable for ACL2(r) as
  well.")
 (COMPOUND-RECOGNIZER
  (RULE-CLASSES)
  "Make a rule used by the typing mechanism

  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.

    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)

  Before presenting the General Forms, we start with a motivating
  example: the second [47m[defthm][0m form above, which provides a nice
  example of a [47m:compound-recognizer[0m rule that is built into ACL2.  To
  see how this rule might be useful, consider the following
  (admittedly very simple) [events].

    (defun triple (x)
      (* 3 x))

    (defthm triple-preserves-integerp
      (implies (integerp x)
               (integerp (triple x))))

    (in-theory (disable triple natp))

  If the above [47m:compound-recognizer[0m rule is disabled, then the
  following trivial theorem fails as shown; we explain below.

    (thm (implies (natp x)
                  (integerp (triple x)))
      :hints ((\"Goal\" :in-theory (disable natp-compound-recognizer))))

  The problem is that when ACL2 tries to rewrite the term [47m(integerp
  (triple x))[0m using the [47m:[0m[47m[rewrite][0m rule [47mtriple-preserves-integerp[0m, it
  needs to rewrite the hypothesis [47m(integerp x)[0m to [47mt[0m, but instead what
  is known is [47m(natp x)[0m.  If we remove the hint, then the proof
  succeeds because the above [47m:compound-recognizer[0m rule tells ACL2
  that when assuming [47m(natp x)[0m to be true, it should actually assume
  both [47m(integerp x)[0m and [47m(<= 0 x)[0m to be true.

    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)

  where [47mfn[0m is a Boolean valued function of one argument, [47mx[0m is a
  variable symbol, and the system can deduce some restriction on the
  primitive type of [47mx[0m from the assumption that [47mconcl[0m holds.  The last
  restriction is vague but one way to understand it is to strengthen
  it a little to ``and [47mconcl[0m is a non-tautological disjunction of the
  primitive type recognizers listed below.''

  The primitive ACL2 types and a suitable primitive recognizing
  expression for each are listed below.

    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)

  Thus, since the naturals comprise the types [47mzero[0m, [47mone[0m, and [47mpositive
  integers > 1[0m, a suitable [47mconcl[0m to recognize the naturals would be

    (or (equal x 0)
        (equal x 1)
        (and (integerp x) (> x 1)))

  However, it turns out that we also permit [47m(and (integerp x) (>= x
  0))[0m, i.e. [47mconcl[0m doesn't literally need to be formed as a direct
  disjunction of terms from the table above.

  Similarly, the true-lists could be specified by

    (or (equal x nil)
        (and (consp x)
             (true-listp x)))

  but we in fact allow [47m(true-listp x)[0m 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.

  There are essentially four forms of [47m:compound-recognizer[0m 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.

  Consider form (1), [47m(implies (fn x) concl)[0m.  The effect of such a rule
  is that when the rewriter assumes [47m(fn x)[0m true, as it would while
  diving through [47m(if (fn x) xxx ...)[0m to rewrite [47mxxx[0m, it restricts the
  type of [47mx[0m as specified by [47mconcl[0m.  For example, if [47mconcl[0m is the term
  [47m(integerp x)[0m, then when rewriting [47mxxx[0m, [47mx[0m will be assumed to be an
  integer.  However, when assuming [47m(fn x)[0m false, as necessary in [47m(if
  (fn x) ... xxx)[0m, the rule permits no additional assumptions about
  the type of [47mx[0m.  For example, if [47mfn[0m is [47mprimep[0m, i.e., the predicate
  that recognizes prime numbers, then [47m(implies (primep x) (and
  (integerp x) (>= x 0)))[0m is a compound recognizer rule of the first
  form.  When [47m(primep x)[0m is assumed true, the rewriter gains the
  additional information that [47mx[0m is a natural number.  When [47m(primep x)[0m
  is assumed false, no additional information is gained --- since [47mx[0m
  may be a non-prime natural or may not even be a natural.

  Form (2) is the symmetric case, when assuming [47m(fn x)[0m false permits
  type restrictions on [47mx[0m but assuming [47m(fn x)[0m true permits no such
  restrictions.  For example, if we defined [47mexprp[0m to be the
  recognizer for well-formed expressions for some language in which
  all symbols, numbers, character objects and strings were
  well-formed --- e.g., the well-formedness rules only put
  restrictions on expressions represented by [47m[consp][0ms --- then the
  theorem [47m(implies (not (exprp x)) (consp x))[0m is a rule of the second
  form.  Assuming [47m(exprp x)[0m true tells us nothing about the type of
  [47mx[0m; assuming it false tells us [47mx[0m is a [47m[consp][0m.

  Forms (3) and (4), which are really equivalent, address themselves to
  the case where one type may be deduced from [47m(fn x)[0m 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

    (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)))

  Finally, rules of forms (5) and (6) address the case where [47mfn[0m
  recognizes all and only the objects whose type is described.  In
  these cases, [47mfn[0m is really just a new name for some ``compound
  recognizers.'' The classic example is [47m(booleanp x)[0m, which is just a
  handy combination of two primitive types:

    (iff (booleanp x) (or (equal x t) (equal x nil))).

  Often it is best to disable [47mfn[0m after proving that it is a compound
  recognizer, since otherwise the term [47m(fn x)[0m will be expanded and
  thus disappear.

  Every time you prove a new compound recognizer rule about [47mfn[0m it
  overrides all previously proved compound recognizer rules about [47mfn[0m.
  Thus, if you want to establish the type implied by [47m(fn x)[0m and you
  want to establish the type implied by [47m(not (fn x))[0m, 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.

  Compound recognizer rules can be disabled with the effect that older
  rules about [47mfn[0m, if any, are exposed.

  If you prove more than one compound recognizer rule for a function,
  you may see a [31;1mwarning[0m 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.

  Compound recognizer rules are similar to [47m:[0m[47m[forward-chaining][0m 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 [47m:[0m[47m[forward-chaining][0m 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 type reasoning (see
  [TYPE-REASONING]) is done.

  All that said, compound recognizer rules are a rather fancy,
  specialized mechanism.  It may be more appropriate to create
  [47m:[0m[47m[forward-chaining][0m rules instead of [47m:compound-recognizer[0m rules.")
 (COMPRESS1
  (ARRAYS ACL2-BUILT-INS)
  "Remove irrelevant pairs from a 1-dimensional array

    Example Form:
    (compress1 'delta1 a)

    General Form:
    (compress1 name alist)

  where [47mname[0m is a symbol and [47malist[0m is a 1-dimensional array, generally
  named [47mname[0m.  See [arrays] for details.  Logically speaking, this
  function can remove irrelevant pairs from [47malist[0m, possibly
  shortening it.  The function returns a new array, [47malist'[0m, with the
  same [47m[header][0m (including name and dimension) as [47malist[0m, that, under
  [47m[aref1][0m, is everywhere equal to [47malist[0m.  That is, [47m(aref1 name alist'
  i)[0m is [47m(aref1 name alist i)[0m, for all legal indices [47mi[0m.  [47mAlist'[0m may be
  shorter than [47malist[0m and the non-irrelevant pairs may occur in a
  different order than in [47malist[0m.

  Practically speaking, this function plays an important role in the
  efficient implementation of [47m[aref1][0m.  In addition to creating the
  new array, [47malist'[0m, [47mcompress1[0m makes that array the ``semantic
  value'' of [47mname[0m and allocates a raw lisp array to [47mname[0m.  For each
  legal index, [47mi[0m, that raw lisp array contains [47m(aref1 name alist' i)[0m
  in slot [47mi[0m.  Thus, subsequent [47m[aref1][0m operations can be executed in
  virtually constant time provided they are given [47mname[0m and the [47malist'[0m
  returned by the most recently executed [47mcompress1[0m or [47m[aset1][0m on
  [47mname[0m.  See [arrays].

  In general, [47mcompress1[0m returns an alist whose [47m[cdr][0m is an association
  list whose keys are nonnegative integers in ascending order.
  However, if the [47m[header][0m specifies an [47m:order[0m of [47m>[0m then the keys
  will occur in descending order; and if the [47m:order[0m is [47m:none[0m or [47mnil[0m
  then the keys will not be sorted and the header may appear anywhere
  (even more than once), i.e., [47mcompress1[0m is logically the identity
  function (though it still attaches an array under the hood).  Note
  however that a [47m[compress1][0m call is replaced by a hard error if the
  header specifies an [47m:order[0m of [47m:none[0m or [47mnil[0m and the array's length
  exceeds the [47m[maximum-length][0m field of its [47m[header][0m.

  We close with a remark concerning efficiency in the case that the
  [47m:ORDER[0m specified by the given [array]'s [header] is [47m<[0m or [47m>[0m and the
  alist is properly ordered: header occurring only first, then
  ascending (for [47m:ORDER <[0m) or descending (for [47m:ORDER >[0m) order of
  indices, with no value in the alist equal to the [47m:DEFAULT[0m specified
  by the header.  In particular, this can cut the time to run
  [47mcompress1[0m on an alist containing only the header by more than half.

  [31;1mFunction: [0m<compress1>

    (defun compress1 (name l)
     (declare (xargs :guard (array1p name l)))
     (case (array-order (header name l))
      (< (cons (header name l)
               (compress11 name l 0 (car (dimensions name l))
                           (default name l))))
      (> (cons (header name l)
               (reverse (compress11 name l 0 (car (dimensions name l))
                                    (default name l)))))
      (t
       (prog2$
        (and
         (> (length l) (maximum-length name l))
         (hard-error
          'compress1
          \"Attempted to compress a one-dimensional array named ~
                            ~x0 whose header specifies :ORDER ~x1 and whose ~
                            length, ~x2, exceeds its maximum-length, ~x3.\"
          (list (cons #\\0 name)
                (cons #\\1 nil)
                (cons #\\2 (length l))
                (cons #\\3 (maximum-length name l)))))
        l))))")
 (COMPRESS2
  (ARRAYS ACL2-BUILT-INS)
  "Remove irrelevant pairs from a 2-dimensional array

    Example Form:
    (compress2 'delta1 a)

    General Form:
    (compress2 name alist)

  where [47mname[0m is a symbol and [47malist[0m is a 2-dimensional array, generally
  named [47mname[0m.  See [arrays] for details.  Logically speaking, this
  function removes irrelevant pairs from [47malist[0m, possibly shortening
  it.  The function returns a new array, [47malist'[0m, with the same
  [47m[header][0m (including name and dimension) as [47malist[0m, that, under
  [47m[aref2][0m, is everywhere equal to [47malist[0m.  That is, [47m(aref2 name alist'
  i j)[0m is [47m(aref2 name alist i j)[0m, for all legal indices [47mi[0m and [47mj[0m.
  [47mAlist'[0m may be shorter than [47malist[0m and the non-irrelevant pairs may
  occur in a different order in [47malist'[0m than in [47malist[0m.

  Practically speaking, this function plays an important role in the
  efficient implementation of [47m[aref2][0m.  In addition to creating the
  new array, [47malist'[0m, [47mcompress2[0m makes that array the ``semantic
  value'' of [47mname[0m and allocates a raw lisp array to [47mname[0m.  For all
  legal indices, [47mi[0m and [47mj[0m, that raw lisp array contains [47m(aref2 name
  alist' i j)[0m in slot [47mi[0m,[47mj[0m.  Thus, subsequent [47m[aref2][0m operations can
  be executed in virtually constant time provided they are given [47mname[0m
  and the [47malist'[0m returned by the most recently executed [47mcompress2[0m or
  [47m[aset2][0m on [47mname[0m.  See [arrays].

  [31;1mFunction: [0m<compress2>

    (defun compress2 (name l)
      (declare (xargs :guard (array2p name l)))
      (cons (header name l)
            (compress21 name l 0 (car (dimensions name l))
                        (cadr (dimensions name l))
                        (default name l))))")
 (COMPUTED-HINT (POINTERS)
                "See [computed-hints].")
 (COMPUTED-HINTS
  (HINTS)
  "Computing advice to the theorem proving process

    General Form of :hints:
    (hint1 hint2 ... hintk)

  Each element, hinti, must be either a common hint or a computed hint.

  A common hint is of the form

    (goal-spec :key1 val1 ... :keyn valn)

  where [47mgoal-spec[0m is as specified in [goal-spec] and each [47m:keyi[0m and
  [47mvali[0m is as specified in [hints].  Among the ``common hints'' we
  include both the primitive hints and user-defined custom keyword
  hints (see [custom-keyword-hints]).

  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:

  (a) the only free variables allowed in the term are [47mID[0m, [47mCLAUSE[0m,
  [47mWORLD[0m, [47mSTABLE-UNDER-SIMPLIFICATIONP[0m, [47mHIST[0m, [47mPSPV[0m, [47mCTX[0m, and [47m[state][0m;

  (b) the output signature of the term is either [47m(MV * * STATE)[0m, which
  is to be treated as an error triple (see below), or is [47m*[0m, denoting
  a single non-[stobj] value; and

  (c) in the former case of (b) above, the term is single-threaded in
  [47m[state][0m.

  If a computed hint is a function symbol [47mfn[0m, whose arity n is
  therefore three, four, or seven, then it is treated as the term
  resulting from applying that [47mfn[0m to the first n variables shown in
  (a) above.  Notice that it must then return a single non-[stobj]
  value, not an error triple, since [47mstate[0m is not one of the first
  seven variables shown in (a).

  Note: Error triples are an ACL2 idiom for implementing ``errors'';
  see [error-triple].  If a computation returns [47m(mv erp val state)[0m in
  a context in which ACL2 is respecting the error triple convention
  (see [ld-error-triples] and see [ld-error-action]), then an error
  is deemed to have occurred if [47merp[0m is non-[47mnil[0m.  The computation is
  expected to have printed an appropriate error message to [47m[state][0m
  and further computation is aborted.  On the other hand, if a
  computation returns an error triple in which [47merp[0m is nil, then
  ``value'' of the computation is taken to be the second component,
  [47mval[0m, of the triple (along with the possibly modified [47m[state][0m), and
  computation continues.  For more information about programming with
  error triples, see [programming-with-state].

  The function symbol cases are treated as abbreviations of the term
  [47m(fn ID CLAUSE WORLD)[0m, [47m(fn ID CLAUSE WORLD
  STABLE-UNDER-SIMPLIFICATIONP)[0m, or [47m(fn ID CLAUSE WORLD
  STABLE-UNDER-SIMPLIFICATIONP HIST PSPV CTX)[0m as appropriate for the
  arity of [47mfn[0m.  (Note that this tells you which argument of [47mfn[0m is
  which.)  Moreover, in these cases the value returned must be a
  single ordinary (non-[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
  [using-computed-hints-8].

  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, [47mval[0m
  and a new state, [47m[state][0m.  Any changes to those parts of [47m[state][0m
  that affect logical soundness are undone; more specifically, the
  values of symbols (sometimes called ``state global variables'') in
  the list [47m*protected-system-state-globals*[0m in the global table of
  the state (see [state]) are restored when changed during
  evaluation.  The value, [47mval[0m, of a non-erroneous computed hint
  calculation is either [47mnil[0m, which means the computed hint did not
  apply to the subgoal in question, or it is an alternating list of
  [47m:keyi vali[0m pairs as specified in [hints].  With one exception,
  those new hints are applied to the given subgoal as though the user
  had typed them explicitly.

  The exception is that the first keyword in the returned [47mval[0m is
  allowed to be [47m:COMPUTED-HINT-REPLACEMENT[0m.  Its value should be [47mnil[0m,
  [47mt[0m, or a list of terms.  If this keyword is not present, the default
  value of [47mnil[0m is provided.  We explain [47m:COMPUTED-HINT-REPLACEMENT[0m
  below.

  The evaluation of a hint term is done with guard checking turned off
  (see [set-guard-checking]); e.g., the form [47m(car 23)[0m in a computed
  hint returns [47mnil[0m as per the axioms.

  When a non-[47mnil[0m value is returned, the keyword/value pairs (other than
  the optional [47m:COMPUTED-HINT-REPLACEMENT[0m) 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
  [47m[er][0m, 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.

  The purpose of the [47m:COMPUTED-HINT-REPLACEMENT[0m keyword and its value,
  [47mchr[0m, is to change the list of hints.  If [47mchr[0m is [47mnil[0m, 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 [47mchr[0m is [47mt[0m, 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, [47mchr[0m 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 [47mchr[0m 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 [47m:in-theory[0m and
  [47m:expand[0m hints, which appear in the computed hint will continue to
  take effect even when [47mchr[0m is [47mnil[0m.  This might give one the false
  impression that a removed computed hint still hangs around.  See
  [hints-and-the-waterfall] for a more detailed discussion about how
  [47m:in-theory[0m and other hints are handled in the waterfall.

  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.

  Only the first hint applicable to a goal, as specified in the
  user-supplied list of [47m:hints[0m followed by the [47m[default-hints-table][0m,
  will be applied to that goal.  (For an advanced exception, see
  [override-hints].)

  It remains only to describe the bindings of the free variables.

  Suppose the theorem prover is working on a [clause] named by some
  [47m[goal-spec][0m, e.g., \"Subgoal *1/2'''\".  Corresponding to the printed
  [47mgoal-spec[0m is an internal data structure called a ``clause
  identifier'' id.  See [clause-identifier].

  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.

  In the case of a computed hint, the variable [47mID[0m is bound to the
  clause id, the variable [47mCLAUSE[0m is bound to the (translated form of
  the) clause, and the variable [47mWORLD[0m is bound to the current ACL2
  world.  The variable [47mSTABLE-UNDER-SIMPLIFICATIONP[0m is bound to [47mt[0m or
  [47mnil[0m.  It is bound to [47mt[0m 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 [47m:use[0m hint) only
  when the goal in question has stabilized.  If a hint is provided,
  the processing of the clause starts over with simplification.

  As for [47mCTX[0m and [47m[state][0m, they are provided so that you can pass them
  to the [47m[er][0m macro to print error messages.

  The remaining variables, [47mHIST[0m and [47mPSPV[0m are not documented yet.  Only
  users familiar with the internals of ACL2 are likely to need them
  or understand their values.

  For some instruction about how to use computed hints, see
  [using-computed-hints].


Subtopics

  [Using-computed-hints]
      How to use computed hints")
 (CONCATENATE
  (LISTS STRINGS ACL2-BUILT-INS)
  "Concatenate lists or strings together

    Examples:
    (concatenate 'string \"ab\" \"cd\" \"ef\")     ; equals \"abcdef\"
    (concatenate 'string \"ab\")               ; equals \"ab\"
    (concatenate 'list '(a b) '(c d) '(e f)) ; equals '(a b c d e f)
    (concatenate 'list)                      ; equals nil

    General Form:
    (concatenate result-type x1 x2 ... xn)

  where [47mn >= 0[0m and either: [47mresult-type[0m is [47m'[0m[47m[string][0m and each [47mxi[0m is a
  string; or [47mresult-type[0m is [47m'[0m[47m[list][0m and each [47mxi[0m is a true list.
  [47mConcatenate[0m simply concatenates its arguments to form the result
  string or list.  Also see [append] and see [string-append].  (The
  latter immediately generates a call to [47mconcatenate[0m when applied to
  strings.)

  Note: We do *not* try to comply with the Lisp language's insistence
  that [47mconcatenate[0m 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 [47mconcatenate[0m; we merely provide a definition for
  it.

  [47mConcatenate[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.

  [31;1mMacro: [0m<concatenate>

    (defmacro concatenate (result-type &rest sequences)
      (declare (xargs :guard (or (equal result-type ''string)
                                 (equal result-type ''list))))
      (cond ((equal result-type ''string)
             (cond ((and sequences (cdr sequences)
                         (null (cddr sequences)))
                    (list 'string-append
                          (car sequences)
                          (cadr sequences)))
                   (t (list 'string-append-lst
                            (cons 'list sequences)))))
            ((endp sequences) nil)
            (t (cons 'append
                     (append sequences (list nil))))))")
 (COND
  (BASICS ACL2-BUILT-INS)
  "Conditional based on if-then-else

  [47mCond[0m is the construct for IF, THEN, ELSE IF, ...  The test is against
  [47mnil[0m.  The argument list for [47mcond[0m is a list of ``cond clauses'',
  each of which is a list.  In ACL2, cond clauses must have length 1
  or 2.

    ; 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))

  The results above were obtained by typing [47m:trans1[0m followed by the
  form in the ACL2 loop, and then hitting [47m<RETURN>[0m.  See [trans1].
  You can experiment in this way to see other such examples.

  [47mCond[0m is a Common Lisp macro.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<cond>

    (defmacro cond (&rest clauses)
      (declare (xargs :guard (cond-clausesp clauses)))
      (cond-macro clauses))

  [31;1mFunction: [0m<cond-macro>

    (defun cond-macro (clauses)
      (declare (xargs :guard (cond-clausesp clauses)))
      (if (consp clauses)
          (if (and (eq (car (car clauses)) t)
                   (eq (cdr clauses) nil))
              (if (cdr (car clauses))
                  (car (cdr (car clauses)))
                (car (car clauses)))
            (if (cdr (car clauses))
                (list 'if
                      (car (car clauses))
                      (car (cdr (car clauses)))
                      (cond-macro (cdr clauses)))
              (list 'or
                    (car (car clauses))
                    (cond-macro (cdr clauses)))))
        nil))")
 (CONGRUENCE
  (RULE-CLASSES)
  "The relations to maintain while simplifying arguments

  See [rule-classes] for a general discussion of rule classes and how
  they are used to build rules from formulas.  An example
  [47m:[0m[47m[corollary][0m formula from which a rule of class [47m:congruence[0m might
  be built, assuming that [47mset-equal[0m is a known [equivalence]
  relation, is:

    Example:
    (defthm set-equal-implies-iff-memb-2
      (implies (set-equal x y)
               (iff (memb e x) (memb e y)))
      :rule-classes :congruence)

  Also see [defcong] and see [equivalence].

  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 [patterned-congruence].

    General Form:
    (implies (equiv1 xk xk-equiv)
             (equiv2 (fn x1... xk       ...xn)
                     (fn x1... xk-equiv ...xn)))

  where [47mequiv1[0m and [47mequiv2[0m are known equivalence relations, [47mfn[0m is an
  [47mn-ary[0m function symbol other than [47mif[0m, and the [47mxi[0m and [47mxk-equiv[0m are
  all distinct variables.  The effect of such a rule is to record
  that the [47mequiv2[0m-equivalence of [47mfn[0m-expressions can be maintained if,
  while rewriting the [47mkth[0m argument position, [47mequiv1[0m-equivalence is
  maintained.  See [equivalence] for a general discussion of the
  issues.  We say that [47mequiv2[0m, above, is the ``outside equivalence''
  in the rule and [47mequiv1[0m is the ``inside equivalence for the [47mk[0mth
  argument.''

  The macro form [47m(defcong equiv1 equiv2 (fn x1 ... x1) k)[0m is an
  abbreviation for a [47m[defthm][0m of rule-class [47m:congruence[0m that attempts
  to establish that [47mequiv2[0m is maintained by maintaining [47mequiv1[0m in
  [47mfn[0m's [47mk[0mth argument.  The [47m[defcong][0m macro automatically generates the
  general formula shown above.  See [defcong].

  The [47mmemb[0m example above tells us that [47m(memb e x)[0m is propositionally
  equivalent to [47m(memb e y)[0m, provided [47mx[0m and [47my[0m are [47mset-equal[0m.  The
  outside equivalence is [47m[iff][0m and the inside equivalence for the
  second argument is [47mset-equal[0m.  If we see a [47mmemb[0m expression in a
  propositional context, e.g., as a literal of a [clause] or test of
  an [47m[if][0m (but not, for example, as an argument to [47m[cons][0m), we can
  rewrite its second argument maintaining [47mset-equality[0m.  For example,
  a rule stating the commutativity of [47m[append][0m (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 [refinement].

  All known congruence rules about a given outside equivalence and [47mfn[0m
  can be used independently.  That is, consider two congruence rules
  with the same outside equivalence, [47mequiv[0m, and about the same
  function [47mfn[0m.  Suppose one says that [47mequiv1[0m is the inside
  equivalence for the first argument and the other says [47mequiv2[0m is the
  inside equivalence for the second argument.  Then [47m(fn a b)[0m is [47mequiv[0m
  [47m(fn a' b')[0m provided [47ma[0m is [47mequiv1[0m to [47ma'[0m and [47mb[0m is [47mequiv2[0m to [47mb'[0m.  This
  is an easy consequence of the transitivity of [47mequiv[0m.  It permits
  you to think independently about the inside equivalences.

  Furthermore, it is possible that more than one inside equivalence for
  a given argument slot will maintain a given outside equivalence.
  For example, [47m(length a)[0m is equal to [47m(length a')[0m if [47ma[0m and [47ma'[0m are
  related either by [47mlist-equal[0m or by [47m[string-equal][0m.  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 [geneqv] for a discussion
  of how generated equivalence relations are derived using congruence
  rules and how generated equivalence relations are represented.

  Congruence rules can be [disable]d.  For example, if you have two
  different inside equivalences for a given argument position and you
  find that the [47m:[0m[47m[rewrite][0m rules for one are unexpectedly preventing
  the application of the desired rule, you can disable the rule that
  introduced the unwanted inside equivalence.

  [31;1mNOTE[0m 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 [enable]d.  Congruence rules that are
  used only in this way will therefore not appear in the [summary].

  [3mRemark on Replacing IFF by EQUAL.[0m 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:

    (defcong equiv1 iff (fn x y) 2)

  which is shorthand for the following:

    (defthm equiv1-implies-iff-fn-2
           (implies (equiv1 y y-equiv)
                    (iff (fn x y) (fn x y-equiv)))
           :rule-classes (:congruence))

  The warning is telling you that ACL2 was able to deduce that [47mfn[0m
  always returns a Boolean, and hence a trivial but useful
  consequence is obtained by replacing [47m[iff][0m by [47m[equal][0m ---

    (defcong equiv1 equal (fn x y) 2)

  --- which is shorthand for the following:

    (defthm equiv1-implies-equal-fn-2
           (implies (equiv1 y y-equiv)
                    (equal (fn x y) (fn x y-equiv)))
           :rule-classes (:congruence))

  If you have difficulty proving the latter directly, you can derive it
  from the former by giving a suitable hint, minimally as follows.

    (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)))))

  By heeding this warning, you may avoid unnecessary [47m[double-rewrite][0m
  warnings later.  We now explain why, but see [double-rewrite] for
  relevant background material.

  For example, suppose you have proved the ``[47miff[0m'' version of the
  congruence rule above, and later you submit the following rewrite
  rule.

    (defthm equal-list-perm
      (implies (equiv1 x y)
               (fn x y)))

  Since [47mfn[0m is known to return a Boolean, ACL2 performs an optimization
  that stores this rule as though it were the following.

    (defthm equal-list-perm
      (implies (equiv1 x y)
               (equal (fn x y) t)))

  Thus, if ACL2's rewriter sees a term [47m(fn a b)[0m in a context where the
  equivalence relation [47m[iff][0m is not being maintained, then it cannot
  use rule [47mequiv1-implies-iff-fn-2[0m, so it rewrites argument [47ma[0m without
  the benefit of knowing that it suffices to maintain [47mequiv1[0m; and
  then it caches the result.  When ACL2 subsequently attempts to
  relieve the hypothesis [47m(equiv1 x y)[0m, it will rewrite [47mx[0m simply by
  returning the rewritten value of [47ma[0m from the result cache.  This is
  unfortunate if [47ma[0m could have been rewritten more completely under
  maintenance of the equivalence relation [47mequiv1[0m --- which is legal
  in the hypothesis since [47ma[0m is an argument of [47mequiv1[0m, which is an
  [equivalence] relation.  The user who observes the warning from
  rule [47mequiv1-implies-iff-fn-2[0m, and replaces it with
  [47mequiv1-implies-equal-fn-2[0m, will avoid this unfortunate case.")
 (CONJOIN (POINTERS)
          "See [system-utilities].")
 (CONJOIN2 (POINTERS)
           "See [system-utilities].")
 (CONJUGATE
  (NUMBERS ACL2-BUILT-INS)
  "Complex number conjugate

  [47mConjugate[0m takes an ACL2 number as an argument, and returns its
  complex conjugate (i.e., the result of negating its imaginary
  part.).

  [47mConjugate[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<conjugate>

    (defun conjugate (x)
      (declare (xargs :guard (acl2-numberp x)))
      (complex (realpart x) (- (imagpart x))))")
 (CONS
  (CONSES ACL2-BUILT-INS)
  "Pair and list constructor

  [47m(cons x y)[0m is a pair whose first component is [47mx[0m and second component
  is [47my[0m.  If [47my[0m is a list, then [47m(cons x y)[0m is a list that has an
  additional element [47mx[0m on the front.")
 (CONS-COUNT-BOUNDED
  (CONSES ACL2-BUILT-INS)
  "Count the number of conses (up to a limit)

  The call [47m(cons-count-bounded x)[0m returns the number of cons nodes in [47mx[0m
  (without accounting for sharing), but truncated above by the value
  of [47m(fn-count-evg-max-val)[0m, which is 200,000 as of this writing.")
 (CONS-SUBTREES
  (FAST-ALISTS ACL2-BUILT-INS)
  "Build a fast alist whose keys are the subtrees of X

  [47m(cons-subtrees x nil)[0m builds a fast alist that associates each
  subtree of X with T, without duplication.

  [31;1mFunction: [0m<cons-subtrees>

    (defun cons-subtrees (x al)
      (declare (xargs :guard t))
      (cond ((atom x) al)
            ((hons-get x al) al)
            (t (cons-subtrees (car x)
                              (cons-subtrees (cdr x)
                                             (hons-acons x t al))))))")
 (CONS-TERM (POINTERS)
            "See [system-utilities].")
 (CONS-TERM* (POINTERS)
             "See [system-utilities].")
 (CONS-WITH-HINT
  (CONSES ACL2-BUILT-INS)
  "Alternative to [47m[cons][0m that tries to avoid consing when a suitable
  [47mcons[0m structure is provided as a hint.

  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 [hons] for a way to share [cons]
  structures; however, [47mcons-with-hint[0m is likely much cheaper than
  [47mhons[0m and hence can be useful for reducing consing without the
  overhead of [47mhons[0m.

  Logically [47m(cons-with-hint x y hint)[0m is just [47m(cons x y)[0m; [47mhint[0m is
  completely irrelevant and ignored.  We generally expect that
  [47mcons-with-hint[0m will just be left [enable]d, so you should never
  have to reason about it.

  But [47mcons-with-hint[0m has a special raw Common Lisp definition that
  tries to avoid consing by using your [47mhint[0m.  Specifically: if [47mhint[0m
  is the cons [47m(x . y)[0m, then [47mhint[0m is returned without creating a new
  cons.  Equality checking against [47mx[0m and [47my[0m is done using [47m[eql][0m, which
  makes it a fast but incomplete check for equality.

  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.

  For instance, consider a function like [47m[remove-equal][0m, which updates
  a list by removing all copies of some element from it.  The
  definition of [47mremove-equal[0m is as follows (in the logic; it has a
  slightly different definition in raw Lisp).

  [31;1mFunction: [0m<remove-equal>

    (defun remove-equal (x l)
      (declare (xargs :guard (true-listp l)))
      (cond ((endp l) nil)
            ((equal x (car l))
             (remove-equal x (cdr l)))
            (t (cons (car l)
                     (remove-equal x (cdr l))))))

  You can see that if [47ml[0m doesn't have any copies of [47mx[0m, this function
  will essentially make a fresh copy of the whole list [47mx[0m.  That could
  waste a lot of memory when [47mx[0m is long.  The choice was made to
  define [47mremove-equal[0m ``under the hood'' to call Common Lisp's
  function, [47mremove[0m; but it is easy to write a new version of
  [47mremove-equal[0m that uses [47mcons-with-hint[0m:

    (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)))))

  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:

    :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))))

  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):

    ? (let ((x '(a b c d e))) (eq x (remove-equal-with-hint 3 x)))
    T
    ?

  Note that ACL2 asks Lisp to inline calls of [47mcons-with-hint[0m, so there
  will likely be no function call overhead for using [47mcons-with-hint[0m.")
 (CONSERVATIVITY-OF-DEFCHOOSE
  (DEFCHOOSE)
  "Proof of conservativity of [47m[defchoose][0m

  This documentation topic provides underlying theory.  It is of
  theoretical interest only; it has no relationship to the effective
  use of ACL2.

  The argument below for the conservativity of [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--203).

  Our basic idea is to take a (countable) first-order structure for
  ACL2, M, together with a function symbol, f, introduced by
  [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.

  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 [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.

  Preliminaries.  We write s[p<-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<-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
  ``-|''.

  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.

  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.

    (defchoose g <bound-vars> <free-vars> <body>)

  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.

    <body> -> (LET <bound-vars> = g(<free-vars>) in <body>)

  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).

  Below, we will carry out a so-called [3mforcing[0m 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.

  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.

  We start by defining a partial order P as follows.  Let Nb and Nf be
  the lengths of <bound-vars> and <free-vars>, 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.

    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 is ordered by subset, i.e., we say that p2 [3mextends[0m p1 if p1 is a
  subset (not necessarily proper) of p2 (more precisely, M |=
  subsetp-equal(p1,p2)).

  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.

    (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))))

  and define an inverse function on alists as follows.

    (defun inverse (fn)
      (if (endp fn)
          nil
        (cons (cons (cdar fn) (caar fn))
              (inverse (cdr fn)))))

  Then P may instead be defined to consist of those fn for which
  nat-function-p(fn) & 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).

  End of Remark.

  Next we present the relevant forcing concepts from model theory.

  A [3mdense[0m 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 [3mgeneric[0m
  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.

  For p \\in P, we say that a subset D of P is [3mdense beyond[0m 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.

  Proposition 1.  For any partial order P and countable collection Ds
  of dense subsets of P, there is a Ds-generic subset of P.

  Proof.  Let Ds = {D0,D1,D2,...}.  Define a sequence <p_0,p_1,...>
  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. -|

  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 --- for example, we
  can Goedel number all terms and then all formulas --- hence, Df is
  countable.

  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).

  So now we have fixed M, P, Df, G, and g0, where G is Df-generic.

  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.

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

  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.)

      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:

        (forall p1 \\in P extending p)
         (exists p2 \\in P extending p1) phi'(p2).

      p ||- ~phi is: (forall p' \\in P extending p) ~(p' ||- phi)

      p ||- phi_1 & phi_2 is: (p ||- phi_1) & (p ||- phi_2)

      p ||- (exists x) phi is: (exists x) (p ||- phi)

  We will need the following definition later.

  Definition.  p ||-w phi (p [3mweakly forces[0m phi) is an abbreviation for
  p ||- ~~phi.

  The following exercises were suggested by John Cowles as a means for
  gaining familiarity with the definition of forcing.

  Exercise 1. Consider the formula (phi_1 OR phi_2) as an abbreviation
  for ~(~phi_1 & ~phi_2), Show that p ||- (phi_1 OR phi_2) is
  equivalent to the following.

    (forall p' \\in P extending p) (exists p'' \\in P extending p')
     ((p'' ||- phi_1) OR (p'' ||- phi_2))

  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.

    (forall x)
     (forall p1 \\in P extending p)
      (exists p2 \\in P extending p1) (p2 ||- phi).

  Exercise 3. Prove that p ||-w phi is equivalent to the following.

    (forall p' \\in P extending p)
     (exists p'' \\in P extending p') (p'' ||- phi).

  Exercise 4. Let phi be a formula of L[g].  Prove: M |= (p ||-
  phi)[s[p<-p0]] implies M |= (p ||-w phi)[s[p<-p0]].

  Exercise 5. Let phi be a formula of L[g].  Prove: M |= (p ||-
  ~phi)[s[p<-p0]] iff M |= (p ||-w ~phi)[s[p<-p0]].

  [End of exercises.]

  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.

  Proposition 3. For any formula phi of L[g], {p0: M |= ((p ||- phi) OR
  (p ||- ~phi))[s[p<-p0]]]} is a dense subset of P, which (since it
  is first-order definable with parameters in M) intersects G. -|

  The following proposition is easily proved by a structural induction
  on phi, and is left to the reader.

  Proposition 4. Let phi be a formula of L[g].  Suppose p0 \\in P, p1
  \\in P,
  M |= (p ||- phi)[s[p<-p0]],
  and p1 extends p0.  Then
  M |= (p ||- phi)[s[p<-p1]]. -|

  We will also need the following.

  Proposition 5. The following is dense for any finite set S of
  Nf-tuples: {p \\in P: for some <x_1 ... x_Nf> \\in S, (list x_1 ...
  x_Nf) \\in strip-cars(p)}.  Thus, the function g0 is a total
  function. -|

  The next lemma tells us that the sentences true in M[G] are those
  that are forced by an element of G.

  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<-p0]].

  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.

    (*)   For all p0 \\in G such that p0 \\in D*,
          M[G] |= phi[s] iff M |= (p ||- phi)[s[p<-p0]].

  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:

    M[G] |= phi[s]  iff  M |= phi'(p)[s[p<-p0]]

  Moreover, because p0 \\in D* it is clear that this holds if p0 is
  replaced by an arbitrary extension of p0.  Then (*) easily follows.

  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.

  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<-p0]].  By Proposition 3, there is p0 \\in G
  for which M |= (p ||- ~phi)[s[p<-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<-p0]].  It follows that there is no p1
  \\in G for which M |= (p ||- ~phi)[s[p<-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<-p2]], contradicting (by definition of forcing) M |= (p
  ||- ~phi)[s[p<-p1]] since p2 extends p1.

  The case (phi_1 & 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.

  Finally, the case (exists x) phi follows trivially from the inductive
  hypothesis. -|

  Truth Lemma Corollary.  The Truth Lemma holds with ||-w replacing
  ||-.

  Proof.  This is clear by applying the Truth Lemma to ~~phi. -|

  Here is our main theorem.  Recall that all first-order theories in
  our ACL2 context satisfy the e0-induction scheme.

  Theorem.  M[G] satisfies e0-induction.

  Proof.  We consider an arbitrary instance of e0-induction in L[g],
  stated using a strict well-founded relation <| and a formula phi.
  We write phi(y) to indicate that y may be among the free variables
  of phi, and phi(y<-x) to denote the result of substituting x for y
  in phi.

    theta:   (forall y) [((forall x <| y) phi(y<-x)) -> phi(y)]
          -> (forall y) phi(y)

  Our goal is to prove that theta holds in M[G].

  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.

  Consider the following set D.

    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)}.

  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 <|-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 <| 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 <|-minimality of y0.

  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 <| y0, p0 ||-w phi(y1).  By the
  Truth Lemma and its corollary, since p0 \\in G we have:

    (1)   M[G] |= ~phi(y0).
    (2)   For all y1 <| y0, M[G] |= phi(y1).

  It follows that the antecedent of theta is false in M[G], as
  witnessed by y = y0; thus M[G] |= theta. -|

  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)).

    (defchoose foo (y) (x)
      (implies (natp x) (natp y)))

  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 => 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.")
 (CONSES
  (PROGRAMMING)
  "A [31;1mcons[0m is an ordered pair.  In ACL2, data structures like [lists],
  [alists], etc., are made up of conses.


Subtopics

  [Atom]
      Recognizer for atoms

  [Caaaar]
      [47m[car][0m of the [47m[caaar][0m

  [Caaadr]
      [47m[car][0m of the [47m[caadr][0m

  [Caaar]
      [47m[car][0m of the [47m[caar][0m

  [Caadar]
      [47m[car][0m of the [47m[cadar][0m

  [Caaddr]
      [47m[car][0m of the [47m[caddr][0m

  [Caadr]
      [47m[car][0m of the [47m[cadr][0m

  [Caar]
      [47m[car][0m of the [47m[car][0m

  [Cadaar]
      [47m[car][0m of the [47m[cdaar][0m

  [Cadadr]
      [47m[car][0m of the [47m[cdadr][0m

  [Cadar]
      [47m[car][0m of the [47m[cdar][0m

  [Caddar]
      [47m[car][0m of the [47m[cddar][0m

  [Cadddr]
      [47m[car][0m of the [47m[cdddr][0m

  [Caddr]
      [47m[car][0m of the [47m[cddr][0m

  [Cadr]
      [47m[car][0m of the [47m[cdr][0m

  [Car]
      Returns the first element of a non-empty list, else [47mnil[0m

  [Cdaaar]
      [47m[cdr][0m of the [47m[caaar][0m

  [Cdaadr]
      [47m[cdr][0m of the [47m[caadr][0m

  [Cdaar]
      [47m[cdr][0m of the [47m[caar][0m

  [Cdadar]
      [47m[cdr][0m of the [47m[cadar][0m

  [Cdaddr]
      [47m[cdr][0m of the [47m[caddr][0m

  [Cdadr]
      [47m[cdr][0m of the [47m[cadr][0m

  [Cdar]
      [47m[cdr][0m of the [47m[car][0m

  [Cddaar]
      [47m[cdr][0m of the [47m[cdaar][0m

  [Cddadr]
      [47m[cdr][0m of the [47m[cdadr][0m

  [Cddar]
      [47m[cdr][0m of the [47m[cdar][0m

  [Cdddar]
      [47m[cdr][0m of the [47m[cddar][0m

  [Cddddr]
      [47m[cdr][0m of the [47m[cdddr][0m

  [Cdddr]
      [47m[cdr][0m of the [47m[cddr][0m

  [Cddr]
      [47m[cdr][0m of the [47m[cdr][0m

  [Cdr]
      Returns the second element of a [47m[cons][0m pair, else [47mnil[0m

  [Cons]
      Pair and list constructor

  [Cons-count-bounded]
      Count the number of conses (up to a limit)

  [Cons-with-hint]
      Alternative to [47m[cons][0m that tries to avoid consing when a suitable
      [47mcons[0m structure is provided as a hint.

  [Consp]
      Recognizer for [cons] pairs

  [Listp]
      Recognizer for (not necessarily proper) lists

  [Subst]
      A single substitution into a tree")
 (CONSP
  (CONSES ACL2-BUILT-INS)
  "Recognizer for [cons] pairs

  [47m(consp x)[0m is true if and only if [47mx[0m is a [cons] pair.")
 (CONSTRAINT
  (ENCAPSULATE)
  "Restrictions on certain functions introduced in [47m[encapsulate][0m
  [events]

  Suppose that a given theorem, [47mthm[0m, is to be functionally instantiated
  using a given functional substitution, [47malist[0m.  (See
  [lemma-instance], or for an example, see
  [functional-instantiation-example].)  What is the set of proof
  obligations generated?  It is the set obtained by applying [47malist[0m to
  all terms, [47mtm[0m, such that (a) [47mtm[0m mentions some function symbol in
  the domain of [47malist[0m, and (b) either (i) [47mtm[0m is the ``constraint''
  (see below) on a function symbol ancestral in [47mthm[0m or in some
  [47m[defaxiom][0m or (ii) [47mtm[0m is the body of a [47m[defaxiom][0m.  Here, a
  function symbol is ``ancestral'' in [47mthm[0m if either it occurs in [47mthm[0m,
  or it occurs in the definition of some function symbol that occurs
  in [47mthm[0m, and so on.

  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 [constraint-info].

  In a certain sense, function symbols are introduced in essentially
  two ways.  The most common way is to use [47m[defun][0m (or when there is
  mutual recursion, [47m[mutual-recursion][0m or [47m[defuns][0m).  There is also a
  mechanism for introducing ``witness functions''; see [defchoose].
  The documentation for these [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.

  However, when a function symbol is introduced in the scope of an
  [47m[encapsulate][0m event, its constraints may differ from the
  definitional axioms introduced for it.  For example, suppose that a
  function's definition is [47m[local][0m to the [47m[encapsulate][0m; that is,
  suppose the function is introduced in the [signature] of the
  [47m[encapsulate][0m.  Then its constraints include, at the least, those
  non-[47m[local][0m theorems and definitions in the [47m[encapsulate][0m that
  mention the function symbol.

  Actually, it will follow from the discussion below that if the
  [signature] is empty for an [47m[encapsulate][0m, then the constraint on
  each of its new function symbols is exactly the definitional axiom
  introduced for it.  Intuitively, we view such [47mencapsulates[0m just as
  we view [47m[include-book][0m [events].  But the general case, where the
  [signature] is not empty, is more complicated.

  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 [47m[encapsulate][0m 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 [events] as being
  ``lifted'' out of the [47m[encapsulate][0m, resulting in a possibly
  smaller [47m[encapsulate][0m, which becomes the target of the algorithm
  described in the first cut.

  At the end of this note we present an example showing why a more
  naive approach is unsound.

  Finally, before we start our ``first cut,'' we note that any
  information you want ``exported'' outside an [47m[encapsulate][0m event
  must be there as an explicit definition or theorem.  For example,
  even if a function [47mfoo[0m has output type [47m(mv t t)[0m in its [signature],
  the system will not know [47m(true-listp (foo x))[0m merely on account of
  this information.  Thus, if you are using functions like [47mfoo[0m
  (constrained [47m[mv][0m functions), then you may find it useful to prove
  (inside the [47mencapsulate[0m, to be exported) a [47m:[0m[47m[type-prescription][0m
  rule for the constrained function, for example, the
  [47m:[0m[47m[type-prescription][0m rule [47m(true-listp (foo x))[0m.

  [3mFirst cut at constraint-assigning algorithm.[0m Consider the set of
  formulas introduced by all [events] in the scope of an
  [47m[encapsulate][0m:

    * for every [47m[defthm][0m and [47m[defaxiom][0m event, include its formula as well
      as the formulas of all its corollaries;

    * for every [47m[defun][0m event, include the formula that equates the body
      with the application of the function applied to the formals;

    * for every [47mdefchoose[0m event, include the axiom that it adds (see
      [defchoose]);

    * and so on, including axioms added by [47m[defpkg][0m and (recursively) any
      subsidiary [47mencapsulate[0m events.

  Then quite simply, all such formulas are conjoined, and each function
  symbol introduced by the [47m[encapsulate][0m is assigned that conjunction
  as its constraint.

  Clearly this is a rather severe algorithm.  Let us consider two
  possible optimizations in an informal manner before presenting our
  second cut.

  Consider the (rather artificial) event below.  The function [47mbefore1[0m
  does not refer at all, even indirectly, to the locally-introduced
  function [47msig-fn[0m, so it is unfortunate to saddle it with constraints
  about [47msig-fn[0m.

    (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)))
     )

  We would like to imagine moving the definition of [47mbefore1[0m to just in
  front of this [47m[encapsulate][0m, as follows.

    (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)))
     )

  Thus, we will only assign the constraint [47m(consp (sig-fn x))[0m, from the
  theorem [47msig-fn-prop[0m, to the function [47msig-fn[0m, not to the function
  [47mbefore1[0m.

  More generally, suppose an event in an [47m[encapsulate][0m event does not
  mention any function symbol in the [signature] of the
  [47m[encapsulate][0m, nor any function symbol that mentions any such
  function symbol, and so on.  (We might say that no function symbol
  from the [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 [47m[encapsulate][0m.  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 [47msig-fn-prop[0m introduces no constraints on function
  [47mbefore1[0m.

  Once this first optimization is performed, we have in mind a set of
  ``constrained functions.'' These are the functions introduced in
  the [47m[encapsulate][0m that would remain after moving some of them in
  front, as indicated above.  Consider the collection of all formulas
  introduced by the [47m[encapsulate][0m, except the definitional axioms,
  that mention these constrained functions.  So for example, in the
  event below, no such formula mentions the function symbol [47mafter1[0m.

    (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))
     )

  We can see that there is really no harm in imagining that we move the
  definition of [47mafter1[0m out of the [47m[encapsulate][0m, to just after the
  [47m[encapsulate][0m.

  Many subtle aspects of this rearrangement process have been omitted.
  For example, suppose the function [47mfn[0m uses [47msig-fn[0m, the latter being
  a function in the signature of the encapsulation.  Suppose a
  formula about [47mfn[0m is proved in the encapsulation.  Then from the
  discussion above [47mfn[0m 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 [47mfn[0m
  constrained?  The reason is that the theorem proved about [47mfn[0m may
  impose or express constraints on [47msig-fn[0m.  That is, the theorem
  proved about [47mfn[0m may depend upon properties of the witness used for
  [47msig-fn[0m.  Here is a simple example:

    (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)))

  In this example, there are no [47m[defthm][0m events that mention [47msig-fn[0m
  explicitly.  One might therefore conclude that it is completely
  unconstrained.  But the witness we chose for it always returns an
  integer.  The function [47mfn[0m uses [47msig-fn[0m and we prove that [47mfn[0m always
  returns true.  Of course, the proof of this theorem depends upon
  the properties of the witness for [47msig-fn[0m, even though those
  properties were not explicitly ``called out'' in theorems proved
  about [47msig-fn[0m.  It would be unsound to move [47mfn-always-true[0m after the
  encapsulate.  It would also be unsound to constrain [47msig-fn[0m to
  satisfy just [47mfn-always-true[0m without including in the constraint the
  relation between [47msig-fn[0m and [47mfn[0m.  Hence both [47msig-fn[0m and [47mfn[0m 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 [47mfn[0m as well as the property
  that [47mfn[0m always returns true.  Suppose, later, one proved a theorem
  about [47msig-fn[0m and wished to functionally instantiate it.  Then one
  must also functionally instantiate [47mfn[0m, even if it is not involved
  in the theorem, because it is only through [47mfn[0m that [47msig-fn[0m inherits
  its constrained properties.

  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 [47msig-fn[0m above would be well-advised to use
  the following instead:

    (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)))

  Note that [47msig-fn[0m is constrained merely to be an integer.  It is the
  only constrained function.  Now [47mfn[0m is introduced after the
  encapsulation, as a simple function that uses [47msig-fn[0m.  We prove
  that [47mfn[0m always returns true, but this fact does not constrain
  [47msig-fn[0m.  Future uses of [47msig-fn[0m do not have to consider [47mfn[0m at all.

  Sometimes it is necessary to introduce a function such as [47mfn[0m within
  the [47mencapsulate[0m merely to state the key properties of the undefined
  function [47msig-fn[0m.  But that is unusual and the user should
  understand that both functions are being constrained.

  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, [3mexcept the definitional axioms[0m, 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 [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 [47msig-fn[0m and
  introduced [47mfn[0m within the encapsulation, [47mfn[0m was constrained because
  we proved the formula [47mfn-always-true[0m within the encapsulation.  Had
  we not proved [47mfn-always-true[0m within the encapsulation, [47mfn[0m 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 [3madmission[0m 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 [infected-constraints] and see [subversive-recursions].

  (Aside: The definition of [47mfn[0m in the first encapsulation above that
  defines [47mfn[0m, i.e., the encapsulation with [47mfn-always-true[0m inside, is
  subversive because the call of the macro [47m[and][0m expands to a call of
  [47mIF[0m that governs a recursive call of [47mfn[0m, in this case:

    (defun fn (lst)
      (if (endp lst)
          t
          (if (integerp (sig-fn (car lst)))
              (fn (cdr lst))
            nil))).

  If we switch the order of conjuncts in [47mfn[0m, then the definition of [47mfn[0m
  is no longer subversive, but it still ``infects'' the constraint
  generated for the encapsulation, hence for [47msig-fn[0m, because
  [47mfn-always-true[0m blocks the definition of [47mfn[0m from being moved back
  (to after the encapsulation).  Also see [infected-constraints].  If
  we both switch the order of conjuncts and drop [47mfn-always-true[0m from
  the encapsulation, then the definition of [47mfn[0m is in essence moved
  back to after the encapsulation, and the constraint for [47msig-fn[0m no
  longer includes the definition of [47mfn[0m.  End of aside.)

  Another aspect we have not discussed is what happens to nested
  encapsulations when each introduces constrained functions.  We say
  an [47mencapsulate[0m event is ``trivial'' if it introduces no constrained
  functions, i.e., if its list of signatures is [47mnil[0m.  Trivial
  encapsulations are just a way to wrap up a collection of events
  into a single event.

  From the foregoing discussion we see we are interested in exactly how
  we can ``rearrange'' the events in a non-trivial encapsulation ---
  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.

  [3mSecond cut at constraint-assigning algorithm.[0m 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-[47mlocal[0m
  events of such an [47mencapsulate[0m, assuming that they satisfy the
  restriction of using no locally defined function symbols other than
  the signature functions.  Given such an [47mencapsulate[0m 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
  [47m[encapsulate][0m 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 [47mencapsulate[0m together
  with all function symbols defined in the [47mencapsulate[0m and mentioned
  in the constraint is called the ``constrained functions.'' Assign
  the constraint to each of the constrained functions.  Move, to just
  after the [47mencapsulate[0m, the definitions of all function symbols
  defined in the [47mencapsulate[0m that have been omitted from the
  constraint.

  Implementation note.  In the implementation we do not actually move
  [events], but we create constraints that pretend that we did.

  Here is an example illustrating our constraint-assigning algorithm.
  It builds on the preceding examples.

    (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)))
     )

  Only the functions [47msig-fn[0m and [47mduring[0m receive extra constraints.  The
  functions [47mbefore1[0m and [47mbefore2[0m are viewed as moving in front of the
  [47m[encapsulate][0m, as is the theorem [47mbefore2-prop[0m.  The functions
  [47mafter1[0m and [47mafter2[0m are viewed as being moved past the [47m[encapsulate][0m.
  The implementation reports the following.

    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)))))

  Notice that the formula [47m(consp (during x))[0m is not a conjunct of the
  constraint.  During the first pass of the [47mencapsulate[0m, this formula
  is stored as a [47m:[0m[47m[type-prescription][0m rule deduced during the
  definition of the function [47mduring[0m.  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
  [47mputprop-type-prescription-lst[0m.)

  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
  [47m[encapsulate][0m, 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.

    (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))))))))

  Under the simple approach we have in mind, [47mbar[0m is constrained to
  satisfy both its definition and [47mbar-prop[0m because [47mbar[0m mentions a
  function declared in the signature list of the encapsulation.  In
  fact, [47mbar[0m is so-constrained in the ACL2 semantics of encapsulation
  and the first two events above (the [47mencapsulate[0m and the consequence
  that [47mfoo[0m must be the identity function) are actually admissible.
  But under the simple approach to assigning constraints, [47mfoo[0m is
  unconstrained because no theorem about it is exported.  Under that
  approach, [47mouch![0m is provable because [47mfoo[0m can be instantiated in
  [47mfoo-id[0m to a function other than the identity function.

  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 [47mfoo[0m not only the definition of [47mbar[0m, which mentions
  [47mfoo[0m explicitly, but also [47mabc[0m, which has [47mfoo[0m as an ancestor.

    (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))))))))


Subtopics

  [Constraint-info]
      Obtaining the [constraint] on a function symbol")
 (CONSTRAINT-INFO
  (SYSTEM-UTILITIES CONSTRAINT)
  "Obtaining the [constraint] on a function symbol

  For a function symbol, [47mfn[0m, and a logical [world], [47mwrld[0m --- for
  example, the current world, [47m(w state)[0m --- evaluation of the form
  [47m(constraint-info fn wrld)[0m returns [47m(mv flg c)[0m, where [47mc[0m is the list
  of [constraint]s on [47mfn[0m (implicitly conjoined), and [47mflg[0m is [47mnil[0m if [47mfn[0m
  is a defined function and otherwise is a function symbol with that
  same list of constraints (possibly [47mfn[0m itself).  See [constraint]
  for relevant background.

  We illustrate with the following example.

    (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))))

  Then we can see the results of [47mconstraint-info[0m on each introduced
  function symbol, as follows.

    ACL2 !>(let ((wrld (w state)))
              (list
               'result
               'f1 (mv-let (flg1 c1) (constraint-info 'f1 wrld) (list flg1 c1))
               'f2 (mv-let (flg2 c2) (constraint-info 'f2 wrld) (list flg2 c2))
               'f3 (mv-let (flg3 c3) (constraint-info 'f3 wrld) (list flg3 c3))
               'f4 (mv-let (flg4 c4) (constraint-info 'f4 wrld) (list flg4 c4))))
    (RESULT F1
            (F1 ((EQUAL (F4 X) (F3 X))
                 (EQUAL (F1 X) (F4 X))))
            F2 (NIL (EQUAL (F2 X) (F1 X)))
            F3
            (F1 ((EQUAL (F4 X) (F3 X))
                 (EQUAL (F1 X) (F4 X))))
            F4
            (F1 ((EQUAL (F4 X) (F3 X))
                 (EQUAL (F1 X) (F4 X)))))
    ACL2 !>

  Notice that the flag (first result) for [47mf2[0m is [47mnil[0m, because even
  though the definition of [47mf2[0m is lexically inside the [47mencapsulate[0m, it
  doesn't affect the constraints because it can be safely moved to
  just after the [47mencapsulate[0m.  However, the definition of [47mf4[0m does
  affect (or ``infect''; see [subversive-recursions]) the
  constraints: it can't be moved to after the [47mencapsulate[0m because of
  the [47mdefthm[0m after it.

  Also see [constraint].  For more details, see comments in the
  definition of [47mconstraint-info[0m in the ACL2 source code.")
 (CONTEXT (POINTERS) "See [ctx].")
 (CONTEXT-MESSAGE-PAIR
  (KESTREL-UTILITIES SYSTEM-UTILITIES-NON-BUILT-IN)
  "A common ACL2 programming idiom: [error-triple]s without [state]

  [3mContext-message pairs[0m are of the form [47m(mv erp val)[0m, where there are
  the following two cases: the first indicates a successful
  computation and the second indicates an error.

    * [31;1mNormal case[0m: [47merp[0m is [47mnil[0m and [47mval[0m is what we call the ``value'' of that
      context-message pair.

    * [31;1mError case[0m: [47merp[0m is not [47mnil[0m.  [47mVal[0m may be [47mnil[0m; otherwise [47mval[0m is a
      message (see [msgp]) suitable for printing with [47m[fmt][0m and
      related functions using the [47m~@[0m directive, and [47merp[0m is a context
      suitable for error messages (see [ctx]).  A convention
      generally observed (for example, by ACL2 system function
      [47mcmp-to-error-triple[0m, which converts a context-message pair to
      an [error-triple] that may be printed in the error case) is
      when [47merp[0m and [47mval[0m are both non-[47mnil[0m, then [47merp[0m is not [47mt[0m.

  To see how this works let us consider the ACL2 source function,
  [47mtranslate-cmp[0m, 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 [term].  The log below first shows a successful
  translation, returning multiple values [47m(mv nil (binary-+ x '3))[0m,
  thus illustrating the ``Normal case'' above, where the first value
  returned (the error indicator) is [47mnil[0m 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 [47mtranslate-cmp[0m; the examples are merely to illustrate
  programming with context-message pairs, not to explain
  [47mtranslate-cmp[0m!

    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 !>

  The following macros are useful when programming with context-message
  pairs.

    * [47m(value-cmp x)[0m: same as [47m(mv nil x)[0m.  Example:

          ACL2 !>(value-cmp (* 3 4))
          (NIL 12)
          ACL2 !>

    * [47m(er-cmp ctx str &rest args)[0m: Return [47m(mv ctx msg)[0m where [47mmsg[0m is formed
      from [47mstr[0m and [47margs[0m.  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 !>

    * [47m(er-let*-cmp alist body)[0m: Analogue of [47m[er-let*][0m for context-message
      pairs.  So, it evaluates the bindings in [47malist[0m much as
      [47m[let*][0m-bindings would be evaluated, but where each expression
      should return a context-message pair and so should [47mbody[0m.  If
      any of those expression evaluations returns a pair with a
      non-nil first value, then that pair is returned.  Otherwise,
      [47mbody[0m --- which should return a context-message pair --- is
      evaluated with respect to the resulting bindings.  Examples
      (refer to previous examples that use [47mtranslate-cmp[0m):

          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 !>

    * [47m(er-progn-cmp form1 ... formk)[0m: Each [47mformi[0m should evaluate to a
      context-message pair.  If any of these evaluations produces a
      pair with a non-[47mnil[0m first component (thus indicating an error),
      return that pair.  Otherwise return the context-message pair
      produced by evaluating [47mformk[0m.  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 !>")
 (CONVERSION
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Conversion to Uppercase

  When symbols are read by Common Lisp they are converted to upper
  case.  Note carefully that this remark applies to the characters in
  [3msymbols[0m.  The characters in strings are not converted upper case.

  To type a symbol containing lower case characters you can enclose the
  symbol in vertical bars, as in [47m|AbC|[0m or you can put a ``backslash''
  before each lower case character you wish to preserve, as in [47mA\\bC[0m.
  [47m|AbC|[0m and [47mA\\bC[0m are two different ways of writing the same symbol
  (just like 2/4 and 1/2 are two different ways of writing the same
  rational and 123 and 0123 are two different ways to write the same
  natural number).  The symbol has three characters in its name, the
  middle one of which is a lower case b.")
 (COPYRIGHT
  (ABOUT-ACL2)
  "ACL2 copyright, license, sponsorship

  This topic provides information about copyright, license, authorship,
  and sponsorship of the ACL2 system.  For information about
  copyright and authorship of [documentation], see
  [documentation-copyright], which notes that there are many
  documentation authors.

  ACL2 Version 8.6 --- A Computational Logic for Applicative Common
  Lisp

  Copyright (C) 2025, Regents of the University of Texas

  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.

  This program is free software; you can redistribute it and/or modify
  it under the terms of the LICENSE file distributed with ACL2.

  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.

  Written by: Matt Kaufmann and J Strother Moore
  email: Kaufmann@cs.utexas.edu and Moore@cs.utexas.edu
  Department of Computer Science
  University of Texas at Austin
  Austin, TX 78712 U.S.A.

  Please also see [acknowledgments].


Subtopics

  [Documentation-copyright]
      Copyright and authorship of documentation")
 (COROLLARY
  (RULE-CLASSES)
  "The corollary formula of a [rune]

  See [formula].  This is a low-level system function at the present
  time.  See [pr] and see [pr!] instead.  Also see [rule-classes] for
  the use of the symbol [47m:corollary[0m in specifying a rule class.")
 (CORROBORATING_MODELS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Corroborating Models

  {IMAGE} (see [Models_of_Computer_Hardware_and_Software])

  After producing a model, it must be [31;1mcorroborated[0m 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.

  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.

  Because nature is not formal, we cannot [31;1mprove[0m that our models of it
  are correct.  All we can do is test our models against nature's
  behavior.

  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.

  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.

  There are several morals here.

  [31;1mModels need not be complete to be useful.[0m

  [31;1mModels need not be perfectly accurate to be useful.[0m

  [31;1mThe user of a model must understand its limitations.[0m

  {IMAGE} (see [Models_of_Computer_Hardware_and_Software])")
 (COUNT
  (LISTS STRINGS ACL2-BUILT-INS)
  "Count the number of occurrences of an item in a string or true-list

    Example Forms:
    (count #\\D \"DabcDefcDe\")                 ; = 3
    (count #\\D \"DabcDefcDe\" :start 1)        ; = 2
    (count #\\D \"DabcDefcDe\" :start 1 :end 5) ; = 1
    (count #\\D \"DabcDefcDe\" :start 1 :end 4) ; = 0
    (count #\\z \"DabcDefcDe\")                 ; = 0
    (count '(a b) '(17 (a b) 23 (a b) (c d)))   ; = 2

    General Form:
    (count item sequence &key start end)

  [47m(Count item sequence)[0m returns the number of times [47mitem[0m occurs in
  [47msequence[0m.  The [guard] for calls of [47mcount[0m (which is actually a
  macro in ACL2) specifies that [47msequence[0m is a string or a true-list,
  and that [47mstart[0m, which defaults to 0, and [47mend[0m, which defaults to the
  length of [47msequence[0m, are valid indices into sequence.

  See any Common Lisp documentation for more information about [47mcount[0m,
  which is a Common Lisp utility.  At this time ACL2 does not support
  keyword arguments for [47mcount[0m other than [47m:start[0m and [47m:end[0m; we may add
  support for the [47m:from-end[0m keyword upon request.

  [31;1mMacro: [0m<count>

    (defmacro count (item sequence &key (start '0) end)
      (cons 'count-fn
            (cons item
                  (cons sequence
                        (cons start (cons end 'nil))))))")
 (COUNT-KEYS
  (STOBJ ACL2-BUILT-INS)
  "Count the number of keys in association list

  [47m(Count-keys al)[0m returns the number of distinct keys in an association
  list.

  [47mCount-keys[0m has a guard of [47mt[0m.  This function is called in the body of
  function, [47m<h>-count[0m where [47m<h>[0m is a hash-table field of a [stobj].
  See [defstobj].

  [31;1mFunction: [0m<hons-remove-assoc>

    (defun hons-remove-assoc (k x)
      (declare (xargs :guard t))
      (if (atom x)
          nil
        (if (and (consp (car x))
                 (not (equal k (caar x))))
            (cons (car x)
                  (hons-remove-assoc k (cdr x)))
          (hons-remove-assoc k (cdr x)))))

  [31;1mFunction: [0m<count-keys>

    (defun count-keys (al)
      (declare (xargs :guard t))
      (if (atom al)
          0
        (if (consp (car al))
            (+ 1
               (count-keys (hons-remove-assoc (caar al) (cdr al))))
          (count-keys (cdr al)))))")
 (COURSE-MATERIALS
  (DOCUMENTATION)
  "Some ACL2 course materials

  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 {Matt Kaufmann | mailto:kaufmann@cs.utexas.edu} and
  {J Strother Moore | mailto:moore@cs.utexas.edu} if you have
  additional such links to contribute; or if you are a contributor to
  the ACL2 [community-books], please feel free to add them yourself.

    * 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 ``Recursion and Induction'' in the Department of
      Computer Science of the University of Texas at Austin.

    * {Courses taught by Pete Manolios |
      https://www.ccs.neu.edu/home/pete/teaching.html}, which use the
      ACL2 Sedan (ACL2s) (see [ACL2-SEDAN]), including {one taught at
      Northeastern in Spring 2020 |
      https://www.ccs.neu.edu/home/pete/courses/Logic-and-Computation/2020-Spring/}

    * The following two interfaces to ACL2 support the teaching of ACL2 to
      undergraduates:

        * The ACL2 Sedan (ACL2s) (see [ACL2-SEDAN])

        * {DrACuLa | http://dracula-lang.github.io/index.html}

    * John Cowles, {COSC5010: Formalizing the JVM in ACL2 |
      http://www.cs.uwyo.edu/~cowles/jvm-acl2/}, Univ. of Wyoming

    * Links to some of Warren Hunt's courses, many of which use ACL2, may
      be found {here |
      http://www.cs.utexas.edu/users/hunt/class/index.html}.

    * Links to some of J Moore's courses, many of which use ACL2, may be
      found {here |
      http://www.cs.utexas.edu/users/moore/classes/index.html}.")
 (CPU-CORE-COUNT
  (PARALLELISM ACL2-BUILT-INS)
  "The number of cpu cores

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

  Unless the ACL2 executable supports parallel execution (see
  [parallelism]), this function returns [47m(mv 1 state)[0m.  Otherwise:

  [47m(Cpu-core-count state)[0m returns [47m(mv core-count state)[0m, where
  [47mcore-count[0m is determined as follows.  If environment variable
  [47mACL2_CORE_COUNT[0m has a non-empty value, then that value should
  represent a positive integer (else an error occurs), which is the
  returned [47mcore-count[0m.  Otherwise, the returned [47mcore-count[0m may be
  obtained from the underlying Common Lisp implementation, else as a
  positive integer value from [state] global variable [47m'cpu-core-count[0m
  (see [assign]).  Otherwise an error occurs.

    Example:
    (cpu-core-count state) ==> (mv 4 state)

  [47mCpu-core-count[0m has the following logical definition.

  [31;1mFunction: [0m<cpu-core-count>

    (defun cpu-core-count (state)
      (declare (xargs :stobjs state :guard t))
      (mv-let (nullp val state)
              (read-acl2-oracle state)
        (declare (ignore nullp))
        (mv val state)))")
 (CTX
  (ERRORS)
  "Context object for error messages

  Calls of [47m[er][0m, such as [47m(er soft ctx ...)[0m, take a context argument,
  typically called [47mctx[0m, for the initial part of the message: [47m\"ACL2
  Error in\"[0m.  If [47mctx[0m is [47mnil[0m, only [47m\"ACL2 Error:\"[0m is printed for that
  initial part of the message.  Otherwise, the string printed after
  [47m\"in\"[0m depends on the form of that context, as follows.  (See [ctxp]
  for the definition of a valid context.)

    * If [47mctx[0m is a symbol, print it with [47m[fmt][0m using [47m\"~x\"[0m.

    * If [47mctx[0m is a pair whose [47mcar[0m is a symbol, use [47m[fmt][0m to print [47m\"(~x0 ~x1
      ...)\"[0m, with [47m#\\0[0m and [47m#\\1[0m bound respectively to the [47mcar[0m and [47mcdr[0m
      of [47mctx[0m.  [31;1mException[0m: if the [47mcar[0m is a member of the value of
      constant [47m*fmt-ctx-spacers*[0m, then a space is printed after the
      left parenthesis.  That explains why there is a space, for
      example, in [47m\"( DEFUN\"[0m in error messages starting with:

          ACL2 Error in ( DEFUN FOO ...):

    * Otherwise, print [47mctx[0m with [47mfmt[0m using [47m\"~@\"[0m.")
 (CTXP
  (ERRORS)
  "Recognizer for context objects for error messages

  See [ctx] for relevant background.  The function [47mctxp[0m returns [47mt[0m when
  [47mctx[0m is a valid context according to the definition below (also see
  [msgp]), else [47mnil[0m.

  [31;1mFunction: [0m<ctxp>

    (defun ctxp (x)
      (declare (xargs :guard t))
      (or (symbolp x)
          (and (consp x) (symbolp (car x)))
          (msgp x)))")
 (CURRENT-PACKAGE
  (LD)
  "The package used for reading and printing

  [47mCurrent-package[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(current-package state)[0m and the updater is [47m(set-current-package val
  state)[0m, or more conventionally, [47m(in-package val)[0m.  The value of
  [47mcurrent-package[0m 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 [47m[defpkg][0m by the user.

  When printing symbols, the package prefix is displayed if it is not
  the [47mcurrent-package[0m and may be optionally displayed otherwise.
  Thus, if [47mcurrent-package[0m is [47m\"ACL2\"[0m then the symbol [47m'ACL2::SYMB[0m may
  be printed as [47mSYMB[0m or [47mACL2::SYMB[0m, while [47m'MY-PKG::SYMB[0m must be
  printed as [47mMY-PKG::SYMB[0m.  But if [47mcurrent-package[0m is [47m\"MY-PKG\"[0m then
  the former symbol must be printed as [47mACL2::SYMB[0m while the latter
  may be printed as [47mSYMB[0m.

  In Common Lisp, [47mcurrent-package[0m also affects how objects are read
  from character streams.  Roughly speaking, read and print are
  inverses if the [47mcurrent-package[0m is fixed, so reading from a stream
  produced by printing an object must produce an equal object.

  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 [47mcurrent-package[0m.
  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
  [3mdeus ex machina[0m (``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 [3mdeus ex machina[0m determines what
  sequence of calls to [47mread-object[0m will occur in the future and what
  the [47mcurrent-package[0m 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 [47m*current-package*[0m
  bound appropriately for each.

  A simple rule suffices to make sane file [io] possible: before you
  read an object from an object channel to a file created by printing
  to a character channel, make sure the [47mcurrent-package[0m at read-time
  is the same as it was at print-time.")
 (CURRENT-THEORY
  (THEORIES THEORY-FUNCTIONS)
  "Currently [enable]d rules as of logical name

    Examples:
    (current-theory :here)
    (current-theory 'lemma3)

  See [logical-name].

    General Form:
    (current-theory logical-name)

  Returns the current theory as it existed immediately after the
  introduction of [47m[logical-name][0m provided it is evaluated in an
  environment in which the variable symbol WORLD is bound to the
  current ACL2 logical world, [47m(w state)[0m.  Thus,

    ACL2 !>(current-theory :here)

  will cause an (unbound variable) error while

    ACL2 !>(let ((world (w state))) (current-theory :here))

  will return the current theory in world.

  See [theories] and see [logical-name] for a discussion of theories in
  general and why the commonly used ``theory functions'' such as
  [47mcurrent-theory[0m are really macros that expand into terms involving
  the variable [47mworld[0m.

  The theory returned by [47mcurrent-theory[0m is in fact the theory selected
  by the [47m[in-theory][0m event most recently preceding logical name,
  extended by the rules introduced up through [47m[logical-name][0m.

  You may experience a fencepost problem in deciding which logical name
  to use.  [47m[Deflabel][0m can always be used to mark unambiguously for
  future reference a particular point in the development of your
  theory.  The order of [events] in the vicinity of an [47m[encapsulate][0m
  is confusing.  See [encapsulate].

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].")
 (CUSTOM-KEYWORD-HINTS
  (HINTS)
  "User-defined hints

  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 [47mbooks/hints/[0m, in particular
  [47mbasic-tests.lisp[0m.


Subtopics

  [Show-custom-keyword-hint-expansion]
      Print out custom keyword hints when they are expanded")
 (CW
  (IO ACL2-BUILT-INS)
  "Print to the comment window

  [47mCw[0m is a macro that expands to a function whose guard is [47mt[0m.  For a
  guarded variant of [47mcw[0m, see [fmx-cw].  For variants of [47mcw[0m that
  provide readable output (suffix [47m\"!\"[0m) and are never inhibited
  (suffix [47m\"+\"[0m), see [cw!], [cw+], and [cw!+].  For corresponding
  functions see [fmt-to-comment-window], [fmt-to-comment-window!],
  [fmt-to-comment-window+], and [fmt-to-comment-window!+].

  Example:

    (cw \"The goal is ~x0 and the alist is ~x1.~%\"
        (untranslate term t nil)
        unify-subst)

  Logically, this expression is equivalent to [47mnil[0m.  However, it has the
  effect of first printing to the so-called ``comment window'' the
  [47m[fmt][0m string as indicated.  Thus, [47mcw[0m is like [47mfmt[0m (see [fmt]) except
  in four important ways.  First, it is a macro whose calls expand to
  calls of a [47m:[0m[47m[logic][0m mode function.  Second, it neither takes nor
  returns the ACL2 [47m[state][0m; logically [47mcw[0m simply returns [47mnil[0m, although
  it prints to a [3mcomment window[0m that just happens to share the
  terminal screen with the standard character output [47m[*standard-co*][0m.
  Third, its [47mfmt[0m args are positional references, so that for example

    (cw \"Answers: ~x0 and ~x1\" ans1 ans2)

  prints in the same manner as:

    (fmt \"Answers: ~x0 and ~x1\"
         (list (cons #\\0 ans1) (cons #\\1 ans2))
         *standard-co* state nil)

  And finally, output from [47mcw[0m is suppressed if the [47mCOMMENT[0m type of
  output is suppressed; see [set-inhibit-output-lst].

  Typically, calls of [47mcw[0m are embedded in [47m[prog2$][0m forms, e.g.,

    (prog2$ (cw ...)
            (mv a b c))

  which has the side-effect of printing to the comment window and
  logically returning [47m(mv a b c)[0m.

    General Form:
    (cw fmt-string arg1 arg2 ... argn)

  where n is between 0 and 9 (inclusive).  The macro uses
  [47m[fmt-to-comment-window][0m, passing it the column [47m0[0m and [evisc-tuple]
  [47mnil[0m, after assembling the appropriate alist binding the [47m[fmt][0m vars
  #\\0 through #\\9; see [fmt].  If you want

    (a) more than 10 vars,
    (b) vars other than the digit chars,
    (c) a different column, or
    (d) a different evisc-tuple,

  then call [47m[fmt-to-comment-window][0m instead.

  Finally, we discuss another way to create formatted output that also
  avoids the need to pass in the ACL2 [47m[state][0m.  The idea is to use
  wormholes; see [wormhole].  Below is a function you can write,
  along with some calls, providing an illustration of this approach.

    (defun my-fmt-to-comment-window (str alist)
      (wormhole 'my-fmt-to-comment-window
                '(lambda (whs) whs)
                (list str alist)
                '(pprogn
                  (fms (car (@ wormhole-input))
                       (cadr (@ wormhole-input))
                       *standard-co*
                       state
                       nil)
                  (value :q))
                :ld-verbose nil
                :ld-error-action :return ; harmless return on error
                :ld-prompt nil))

    ; A non-erroneous call:
    (my-fmt-to-comment-window \"Here is ~x0 for your inspection~%\"
                              (list (cons #\\0 'foo)))

    ; An error inside the fmt string (unbound fmt var); note that even
    ; with the error, the wormhole is exited.
    (my-fmt-to-comment-window \"Here is ~x1 for your inspection~%\"
                              (list (cons #\\0 'foo)))

    ; A guard violation in the binding; note that even with the error,
    ; the wormhole is exited.
    (my-fmt-to-comment-window \"Here is ~x0 for your inspection~%\"
                              (list (cons #\\0 (car 'foo))))


Subtopics

  [Cw!]
      Print readably to the comment window

  [Cw!+]
      Print readably and uninhibited to the comment window

  [Cw+]
      Print uninhibited to the comment window

  [Fmt-to-comment-window]
      Print to the comment window

  [Fmt-to-comment-window!]
      Print readably to the comment window

  [Fmt-to-comment-window!+]
      Print readably and uninhibited to the comment window

  [Fmt-to-comment-window+]
      Print uninhibited to the comment window")
 (CW!
  (CW IO ACL2-BUILT-INS)
  "Print readably to the comment window

  See [cw] for important background.

  This is nearly the same as [47m[cw][0m, but [47mcw![0m avoids inserting backslash
  (\\) characters when forced to print past the right margin.  Use [47mcw![0m
  if you want to be able to read the forms back in.")
 (CW!+
  (CW IO ACL2-BUILT-INS)
  "Print readably and uninhibited to the comment window

  See [cw] for important background.

  This is nearly the same as [47m[cw][0m, but [47mcw+[0m always produces readable
  output (like [47m[cw!][0m), even when the [47mCOMMENT[0m output type is inhibited
  (like [47m[cw+][0m).")
 (CW+
  (CW IO ACL2-BUILT-INS)
  "Print uninhibited to the comment window

  See [cw] for important background.

  This is nearly the same as [47m[cw][0m, but [47mcw+[0m always produces output, even
  when the [47mCOMMENT[0m output type is inhibited (see
  [set-inhibit-output-lst]).")
 (CW-GSTACK
  (BREAK-REWRITE DEBUGGING)
  "Debug a rewriting loop or stack overflow

  After [break-rewrite] is enabled (with [47m:[0m[47m[brr][0m[47m t[0m or in the scope of
  [47m[with-brr-data][0m), [47mcw-gstack[0m can be invoked to show a stack
  backtrace when a proof is interrupted (because of control-c or
  because of a loop).

    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)

  where [47m:frames[0m and [47m:evisc-tuple[0m are optional, but if they are
  supplied, their values are evaluated.  The value of [47mframes[0m should
  be either a natural number or a list of two natural numbers, the
  first less than the second; and the value of [47mevisc-tuple[0m should be
  an evisc-tuple (see [evisc-tuple]).  If [47m:evisc-tuple[0m is omitted,
  then by default, substructures deeper than 3 are replaced by ``[47m#[0m''
  and those longer than 4 are replaced by ``[47m...[0m'', and terms of the
  form [47m(hide ...)[0m are printed as [47m<hidden>[0m; this behavior can be
  changed by setting the [47m:TERM[0m [evisc-tuple] (see [set-evisc-tuple]).
  Also see [set-iprint] for an alternative to printing ``[47m#[0m'' and
  ``[47m...[0m''.

  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
  [set-rewrite-stack-limit] for a way to avoid stack overflows caused
  by rewriter loops.)

  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.

  Suggestion: Once you have found the loop and fixed it, you should
  execute the ACL2 command [47m:[0m[47m[brr][0m[47m nil[0m, so that you don't slow down
  subsequent proof attempts.")
 (CW-GSTACK-FOR-SUBTERM (POINTERS)
                        "See [with-brr-data].")
 (CW-GSTACK-FOR-SUBTERM* (POINTERS)
                         "See [with-brr-data].")
 (CW-GSTACK-FOR-TERM (POINTERS)
                     "See [with-brr-data].")
 (CW-GSTACK-FOR-TERM* (POINTERS)
                      "See [with-brr-data].")
 (CW-PRINT-BASE-RADIX
  (IO ACL2-BUILT-INS)
  "Print to the comment window in a given print-base

  See [47m[cw][0m for relevant background.  This variant of [47mcw[0m requires
  specification of a print-base and, optionally, a print-radix (see
  [set-print-base], [set-print-radix], and [set-print-base-radix]).

  The following examples show that [47mcw-print-base-radix[0m is just like
  [47m[cw][0m, 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.

    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)

  where all arguments of this macro are evaluated; [47mprint-base[0m is a
  legal print-base as recognized by [47m[print-base-p][0m;
  [47mprint-base/print-radix[0m is a cons whose car is a legal print-base;
  [47mfmt-string[0m is a string suitable for passing to [47m[fmt][0m; and [47marg1[0m
  through [47margn[0m (where n is at most 9) are corresponding arguments for
  [47mfmt-string[0m.  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
  [47m[set-print-base-radix][0m, while in the second general form, it is the
  cdr.")
 (CW-PRINT-BASE-RADIX!
  (IO ACL2-BUILT-INS)
  "Print to the comment window in a given print-base

  This is nearly the same as [47m[cw-print-base-radix][0m, but
  [47mcw-print-base-radix![0m avoids inserting backslash (\\) characters when
  forced to print past the right margin.  Use [47mcw-print-base-radix![0m if
  you want to be able to read the forms back in.")
 (D< (POINTERS) "See [l<].")
 (DEAD-EVENTS
  (DEBUGGING)
  "Using proof supporters to identify dead code and unused theorems

  Below, when we talk about ``an event [47mA[0m'', we mean an event whose name
  is [47mA[0m.

  When event [47mA[0m is used in a proof performed to admit event [47mB[0m that you
  submit to ACL2, we say that [47mA[0m is a ``proof-supporter'' of [47mB[0m.  ACL2
  stores an association list such that for every event [47mB[0m with at
  least one proof-supporter, [47mB[0m is associated with a list of all of
  its proof-supporters, sorted by [47m[symbol<][0m.  The following form
  evaluates to that alist, which is called the
  ``proof-supporters-alist''.

    (global-val 'proof-supporters-alist (w state))

  By ``used in a proof'' above, we mean: applied as a rule or supplied
  explicitly via [hints] of type [47m:use[0m, [47m:by[0m, or [47m:clause-processor[0m.
  That is, the [events] ``used in a proof'' for admitting an event [47mE[0m
  are those listed in the [summary] printed at the conclusion of
  admitting [47mE[0m.

  Note that if proofs are skipped when admitting event [47mE[0m, say because
  the last admission of [47mE[0m was done by [47m[include-book][0m (or
  [47mcertify-book[0m, which ends with an [47m[include-book][0m), then there will
  be no entry in that alist for [47mE[0m.  (An exception is made however for
  [47m[encapsulate][0m [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 [47m[ld][0m rather than [47m[include-book][0m or [47m[certify-book][0m 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.

  The case for [47m[encapsulate][0m is slightly tricky.  Consider an example
  of the following form.

    A ; event preceding the encapsulate
    (encapsulate
     ()
     B
     (local C) ; uses A and B in a proof
     D ; uses C in a proof
     )

  At the conclusion of this [47m[encapsulate][0m event, the
  proof-supporters-alist associates [47mD[0m with [47mA[0m and [47mB[0m, but not [47mC[0m (which
  has disappeared, since it is [local]).

  Note that this sort of ``transitive closure'' operation is only
  performed when necessary due to the disappearance of [local]
  [events].  For example, if we replace [47m(local C)[0m above by just [47mC[0m,
  then [47mD[0m is associated in the proof-supporters-alist only with [47mC[0m, not
  with [47mA[0m or [47mB[0m.  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:

  A community book, [47mbooks/tools/dead-events.lisp[0m, 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 [47m[ld][0m to process the events, with proofs,
  in a book intended to prove theorems [47mMAIN-1[0m and [47mMAIN-2[0m.  (Remember,
  [47m[certify-book][0m will not save such information.)  Suppose
  furthermore that the book begins with some [47m[include-book][0m forms
  followed by [47m(deflabel book-start)[0m.  You could evaluate this form:

    (dead-events '(main-1 main-2) :start 'book-start)

  The result is a list of events that you probably can delete from the
  book without causing any proofs to fail.  See the [47mdead-events.lisp[0m
  book for further documentation.

  You might also find the code in the above book to be helpful for
  writing your own utilities based on the proof-supporters-alist.")
 (DEALING-WITH-KEY-COMBINATIONS-OF-FUNCTION-SYMBOLS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "How to get rid of key combinations of function symbols

  Suppose [47mREV[0m reverses a list, [47mMEMBER[0m checks that its first argument is
  an element of its second, and [47mSQUARES-PLUS-3P[0m 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?

  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 [3msimplify[0m that
  one subterm.

    (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)))?

  The experienced ACL2 user will stop reading at the second hypothesis!

    (MEMBER (+ 3 (* I I)) (REV X))

  The combination of [47mMEMBER[0m and [47mREV[0m can be simplified.  The question
  ``is [47me[0m a member of [47m(REV x)[0m'' can be answered by asking ``is [47me[0m a
  member of [47mx[0m''.  The two questions are equivalent.  This insight
  comes from your intuition about the [3msemantics[0m of [47mREV[0m --- it just
  reorders the elements but doesn't add or delete any.  The second
  question is simpler since it doesn't mention [47mREV[0m, 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.

  You might formalize this insight as

    (equal (member e (rev x))
           (member e x))

  But this conjecture is [3mnot[0m a theorem, because [47m(member e x)[0m returns
  the [47mcdr[0m of [47mx[0m that begins with [47me[0m, not just a Boolean ([47mt[0m or [47mnil[0m)
  indicating whether [47me[0m is an element of [47mx[0m.  The location of the first
  [47me[0m in [47m(rev x)[0m is generally different than the location in [47mx[0m.  So
  when we say the two questions are ``equivalent'' we don't mean they
  are equal.  We mean that they're propositionally equivalent: both
  [47mnil[0m or both non-[47mnil[0m.  This sense of equivalence is called ``if and
  only if'' and is checked by the function [47miff[0m.

  So our intuitive insight can be phrased as this theorem:

    (iff (member e (rev x))
         (member e x))

  Suggesting that this formulation of the insight is ``obvious'' begs
  many questions.  Mathematically, we could have avoided [47miff[0m and just
  written two implications:

    (and (implies (member e x) (member e (rev x)))
         (implies (member e (rev x)) (member e x))).

  or

    (and (implies (member e x) (member e (rev x)))
         (implies (not (member e x))  (not (member e (rev x))))).

  Or we could have used [47miff[0m but ``oriented'' it the other way:

    (iff (member e x)
         (member e (rev x)))

  We choose to write

    (iff (member e (rev x))
         (member e x))

  because of [3mour knowledge of how ACL2 turns formulas into rules![0m

  We deal with this at greater length later.  But just to drive the
  point home, if we issue the command:

    (defthm member-rev
      (iff (member e (rev x))
           (member e x)))

  ACL2 will build in a rule that causes every propositional occurrence
  of [47m(MEMBER e (REV x))[0m to be replaced by [47m(MEMBER e x)[0m.  (By
  ``propositional occurrence'' we mean an occurrence in which the
  value is tested, as by [47mIF[0m or the propositional connectives.
  Remember, one might use [47mmember[0m to determine the location of an
  element too.)

  Note carefully: [3mif you do not tell ACL2 how to make a rule[0m 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,
  [47m(iff [0m[3malpha[0m [3mbeta[0m[47m)[0m makes ACL2 replace [3malpha[0m by [3mbeta[0m.

  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 [3mprogramming[0m 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.

  Had we proved the same equivalence, but with the [47miff[0m commuted, we
  would be giving ACL2 [3mbad advice[0m.  We would be telling it ``replace
  instances of [47m(MEMBER e x)[0m by the corresponding instances of [47m(MEMBER
  e (REV x))[0m''!  If ACL2 had that rule and ever tried to simplify any
  [47mmember[0m expression, e.g., [47m(MEMBER A B)[0m, it would get into an
  infinite loop, e.g., producing the following sequence of
  transformations:

    (MEMBER A B)
    (MEMBER A (REV B))
    (MEMBER A (REV (REV B)))
    ...

  until it eventually exhausted some resource.

  Recall that we entertained the idea of phrasing our insight about
  [47mmember[0m and [47mrev[0m with implications rather than [47miff[0m.  Generally
  speaking, implications produce weaker rules --- rules that apply
  less often.  We discuss that later.

  Now suppose we've proved [47mmember-rev[0m, oriented so as to rewrite
  [47m(member e (rev x))[0m to [47m(member e x)[0m, 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, [47mmember-rev[0m, will hit it.
  It will transform the formula to:

    (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)))?

  and then that will collapse to [47mT[0m, since the [47mIMPLIES[0m has contradictory
  hypotheses (note the last hypothesis above).

  By proving [47mmember-rev[0m 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 [47mmember-rev[0m 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.

  This example illustrates that purely [3mlocal[0m thinking --- looking for
  simplifiable combinations of function symbols --- 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.

  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.

  If you have been reading the tutorial introduction to the theorem
  prover, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-key-checkpoints].")
 (DEALING-WITH-TAU-PROBLEMS
  (INTRODUCTION-TO-THE-TAU-SYSTEM)
  "Some advice on dealing with problems caused by the tau system

  For background on the tau system, 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.

  We discuss the rather limited means of dealing with these problems
  here.  In [future-work-related-to-the-tau-system] we list some
  major inadequacies of the tau system.

  If the tau system contributes to a proof, the [rune]
  [47m(:[0m[47m[executable-counterpart][0m[47m tau-system)[0m will be listed among the
  Rules in the [Summary].  However, merely by being attempted the tau
  system can slow down proofs in which it makes no contribution.

  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

    (in-theory (disable (tau-system)))  ; (:executable-counterpart tau-system)

  or locally with a subgoal specific hint:

    ...
    :hints ((\"...subgoal id...\" :in-theory (disable (tau-system))))

  Conducting a proof with and without the participation of the tau
  system can help you determine whether tau reasoning is helping or
  hurting.

  [3mDealing with Slowdowns[0m

  The [47m[time-tracker][0m 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 [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?

  There are two common causes of slowdown in the tau system.  The first
  stems from the system's use of [47m:[0m[47m[executable-counterpart][0ms 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 [47m0[0m, [47mT[0m, and [47mNIL[0m,
  although different models may stress other constants.  To
  understand why [47mNIL[0m for example is frequently tested, if the test of
  an [47mIF[0m-expression is computed to have tau [3ms[0m then the next question
  we ask is ``does [47mnil[0m satisfy [3ms[0m?''

  You may determine whether the tau system is spending time executing
  tau predicates by observing the rewriter --- see [dmr] --- or by
  interrupting the system and getting a backtrace (see
  [set-debugger-enable]).

  If excessive time is being spent in a tau predicate, a draconian
  solution is to disable the [47m:[0m[47m[executable-counterpart][0m of that
  predicate, for example in either of these equivalent ways.  The tau
  system does not execute disabled [47m:[0m[47m[executable-counterpart][0ms.

    (in-theory (disable (:executable-counterpart foo)))
    (in-theory (disable (foo)))

  In either case above, you may prefer to provide local [47m:[0m[47m[in-theory][0m
  [47m:[0m[47m[hints][0m rather than [47m:in-theory[0m [events].

  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.

  A more sophisticated solution is to make the tau system record values
  of the [47m:[0m[47m[logic][0m-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 [3mEval[0m form of [47m:[0m[47m[tau-system][0m
  rules.

    (defthm lemma
      (and (foo 0)
           (foo 17)
           (foo t)
           (not (foo '(a b c))))
      :rule-classes :tau-system)

  It might be difficult to determine [3mwhich[0m constants are being
  repeatedly tested, although tracing ([47m[trace$][0m) suspected tau
  predicates will show what they are being called on.

  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 [47mtau.lisp[0m, immediately after the definition of the
  system function [47mev-fncall-w-tau-recog[0m, 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.

  The second main cause of slowdowns by the tau system is that the
  system contains ``too many'' conjunctive rules (see the [3mConjunctive[0m
  form in [47m[tau-system][0m).  Unfortunately, we have no tools for either
  identifying the problem or addressing it!  That said, let us tell
  you what we do know!

  Conjunctive rules are used to ``complete'' each tau as it is built.
  Referring to the [47mweekdayp[0m example in [47m[tau-system][0m, if a tau is
  constructed that recognizes weekdays but not [47mMON[0m, [47mTUE[0m, [47mTHU[0m, or [47mFRI[0m,
  it is completed by adding that the tau recognizes (only) [47mWED[0m.  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).

  To learn what conjunctive rules there are in your system, evaluate

    (assoc 'tau-conjunctive-rules (tau-database (w state)))

  Perhaps by sending the implementors that list, we can think of ways
  to index the conjunctive rules to save time.

  [3mDealing with Misapplied Hints[0m

  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
  [47m(:executable-counterpart tau-system)[0m) or change the legacy hints to
  use the new subgoal names.")
 (DEBUGGING
  (TOP ACL2)
  "Tools for debugging failed or slow proofs, or misbehaving functions.


Subtopics

  [Accumulated-persistence]
      To get statistics on which [rune]s are being tried

  [Break-rewrite]
      A version of the ACL2 rewriter with interactive breaks

  [Compare-objects]
      show differences between two ACL2 objects

  [Cw-gstack]
      Debug a rewriting loop or stack overflow

  [Dead-events]
      Using proof supporters to identify dead code and unused theorems

  [Disassemble$]
      Disassemble a function

  [Dmr]
      Dynamically monitor rewrites and other prover activity

  [Efficiency]
      Efficiency considerations

  [Explain-near-miss]
      show why a rule's pattern and the :target do not match

  [Failed-forcing]
      How to deal with a proof [failure] in a forcing round

  [Failure]
      How to deal with a failure to admit an event

  [Forward-chaining-reports]
      To see reports about the forward chaining process

  [Guard-debug]
      Generate markers to indicate sources of [guard] proof obligations

  [Invariant-risk]
      Potential slowdown for [program]-mode updates to [stobj]s or
      [arrays]

  [Measure-debug]
      Generate markers to indicate sources of [measure] proof obligations

  [Near-misses]
      Approximate event name matches

  [Nil-goal]
      How to proceed when the prover generates a goal of [47mNIL[0m

  [Print-gv]
      Print a form whose evaluation caused a guard violation

  [Proof-builder]
      An interactive tool for controlling ACL2's proof processes.

  [Proof-tree]
      Proof tree displays

  [Pstack]
      Seeing what the prover is up to

  [Quick-and-dirty-subsumption-replacement-step]
      (advanced topic) controlling a heuristic in the prover's clausifier

  [Redo-flat]
      Redo on failure of a [47m[progn][0m, [47m[encapsulate][0m, or [47m[certify-book][0m

  [Set-check-invariant-risk]
      Affect certain [program]-mode updates to [stobj]s or [arrays]

  [Set-debugger-enable]
      Control whether Lisp errors and breaks invoke the Lisp debugger

  [Set-guard-msg]
      Specify what is printed when a [guard] is violated

  [Set-print-gv-defaults]
      Set default keyword values for [47m[print-gv][0m

  [Set-register-invariant-risk]
      Avoid [invariant-risk] checking for specified functions

  [Splitter]
      Reporting of rules whose application may have caused case splits

  [Tail-biting]
      Rewriting a true term to [47mNIL[0m

  [Time-tracker]
      Display time spent during specified evaluation

  [Trace]
      Tracing functions in ACL2

  [Type-prescription-debugging]
      Improve a built-in [type-prescription] rule

  [Walkabout]
      Explore an ACL2 cons tree

  [With-brr-data]
      Finding the source of a term in prover output")
 (DECLARATION (POINTERS)
              "See [declare].")
 (DECLARE
  (PROGRAMMING ACL2-BUILT-INS)
  "Extra declarations that can occur in function definitions, [let]
  bindings, and so forth.

  Common Lisp provides a declaration mechanism that allows the
  programmer to explain additional information to the compiler.  For
  instance:

    * 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.

    * The programmer might declare that some variable is [47mignore[0md.  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.

  ACL2 supports the above kinds of declarations, and also adds its own
  kinds of declarations for specifying things like the [guard]s and
  [measure]s of functions, as described in [xargs].

  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.


Usage

  Examples:

    (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)))))))

  General Form:

    (declare d1 ... dn)

  where, in ACL2, each [47mdi[0m is of one of the following forms:

    [47m(ignore v1 ... vn)[0m
      where each [47mvi[0m 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 [set-ignore-ok].
    [47m(ignorable v1 ... vn)[0m
      where each [47mvi[0m 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 [set-ignore-ok].
    [47m(irrelevant v1 ... vn)[0m
      where each [47mvi[0m is a formal parameter declared at the top level of a
      surrounding [47m[defun][0m form, as shown below.  See
      [irrelevant-formals] for more information.
    [47m(type type-spec v1 ... vn)[0m
      where each [47mvi[0m is a variable introduced in the immediately superior
      lexical environment and [47mtype-spec[0m is a type specifier (as
      described in the documentation for [type-spec]).  This
      declaration can be useful for optimizing Common Lisp execution
      speed.  See also [the].
    [47m(xargs :key1 val1 ... :keyn valn)[0m
      where the legal values of the keys and values are described in the
      documentation for [xargs].  These declarations are only allowed
      at the top level of definitions ([47m[defun][0m and [47m[defmacro][0m, as
      shown below), and convey information such as the [guard] and
      [measure] for a function.
    [47m(optimize ...)[0m
      for example, [47m(optimize (safety 3))[0m.  This is allowed only at the top
      level of [47m[defun][0m forms and is probably only rarely of any
      interest.  See any Common Lisp documentation for more
      information.

  Declarations in ACL2 may occur only where [47mdcl[0m occurs in the following
  display (not including lambda objects, discussed later below, and
  not showing documentation strings here, which are essentially
  ignored by ACL2)):

    * [47m(DEFUN name args dcl ... dcl body)[0m

    * [47m(DEFMACRO name args dcl ... dcl body)[0m

    * [47m(LET ((v1 t1) ...) dcl ... dcl body)[0m

    * [47m(MV-LET (v1 ...) term dcl ... dcl body)[0m

    * [47m(FLET ((name args dcl ... dcl body) ...))[0m

    * [47m(MACROLET ((name args dcl ... dcl body) ...))[0m

  Each of the cases above permits certain declarations, as follows.

    * [47mDEFUN[0m: [47m(ignore ignorable irrelevant type optimize xargs)[0m

    * [47mDEFMACRO[0m: [47m(ignore ignorable type xargs)[0m

    * [47mLET[0m: [47m(ignore ignorable type)[0m

    * [47mMV-LET[0m: [47m(ignore ignorable type)[0m

    * [47mFLET[0m: [47m(ignore ignorable type)[0m

    * [47mMACROLET[0m: [47m(ignore ignorable type)[0m

  Of course, declarations are permitted in macro calls to the extent
  that they are permitted in the macroexpansions.  For example,
  [47mdeclare[0m forms generated by calls of [47m[let*][0m and [47m[case-match][0m may
  wind up in corresponding [47m[let][0m forms in the macroexpansions, where
  they would be subject to the restrictions on [47mdeclare[0m forms for [47mlet[0m
  shown just above.

  Also see [lambda] for discussion of lambda objects and their legal
  [47mdeclare[0m forms.

  [47mDeclare[0m is defined in Common Lisp.  See any Common Lisp documentation
  for more information.


Subtopics

  [Declare-stobjs]
      Declaring a formal parameter name to be a single-threaded object

  [Set-ignore-ok]
      Allow unused formals and locals without an [47mignore[0m or [47mignorable[0m
      declaration

  [Set-irrelevant-formals-ok]
      Allow irrelevant formals in definitions

  [Type-spec]
      Type specifiers can be used in Common Lisp type declarations and
      [the] forms, and may result in improved efficiency of
      execution.

  [Xargs]
      Extra arguments, for example to give [hints] to [47m[defun][0m")
 (DECLARE-STOBJS
  (STOBJ DECLARE)
  "Declaring a formal parameter name to be a single-threaded object

  When a [47m[defun][0m uses one of its formals as a single-threaded object
  ([stobj]), the [47mdefun[0m [3mmust[0m include a declaration that the formal is
  to be so used.  An exception is the formal ``[47m[state][0m,'' which if
  not declared as explained below, may still be used provided an
  appropriate global ``declaration'' is issued: see [set-state-ok].

  If the formal in question is [47mcounters[0m then an appropriate declaration
  is

    (declare (xargs :stobjs counters))

  or, more generally,

    (declare (xargs :stobjs (... counters ...)))

  where all the single-threaded formals are listed.

  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
  [47m[defstobj][0m.

  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.

  The obvious question arises: Why does ACL2 insist that you declare
  stobj names before using them in [47mdefun[0ms if you can only declare
  names that have already been defined with [47mdefstobj[0m?  What would go
  wrong if a formal were treated as a single-threaded object if and
  only if it had already been so defined?

  Suppose that one user, say Jones, creates a book in which [47mcounters[0m is
  defined as a single-threaded object.  Suppose another user, Smith,
  creates a book in which [47mcounters[0m 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 [47mcounters[0m as single-threaded.  But if
  Brown includes Smith's book first, the argument is treated as
  ordinary.

  ACL2 insists on the declaration to ensure that the definition is
  processed the same way no matter what the context.")
 (DEFABBREV
  (MACROS EVENTS PROGRAMMING)
  "A convenient form of macro definition for simple expansions

    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)

  where [47mname[0m is a new function symbol, the [47mvi[0m are distinct variable
  symbols, and [47mbody[0m is a term.  The [47mdecli[0m, if supplied, should be
  legal [47mdeclare[0m forms; see [declare].  [47mDoc-string[0m, if non-[47mnil[0m, is an
  optional string that can provide documentation but is essentially
  ignored by ACL2.

  Roughly speaking, the [47mdefabbrev[0m event is akin to defining [47mf[0m so that
  [47m(f v1 ... vn) = body[0m.  But rather than do this by adding a new
  axiom, [47mdefabbrev[0m defines [47mf[0m to be a macro so that [47m(f a1 ... an)[0m
  expands to [47mbody[0m, with the ``formals,'' [47mvi[0m, replaced by the
  ``actuals,'' [47mai[0m.

  For example, if [47msnoc[0m is defined as shown in the first example above,
  then [47m(snoc (+ i j) temp)[0m is just an abbreviation for

    (append temp (list (+ i j))).

  In order to generate efficiently executable Lisp code, the macro that
  [47mdefabbrev[0m introduces uses a [47m[let][0m to bind the ``formals'' to the
  ``actuals.'' Consider the second example above.  Logically
  speaking, [47m(sq (ack i j))[0m is an abbreviation for [47m(* (ack i j) (ack i
  j))[0m.  But in fact the macro for [47msq[0m introduced by [47mdefabbrev[0m actually
  arranges for [47m(sq (ack i j))[0m to expand to:

    (let ((x (ack i j)))
      (* x x))

  which executes more efficiently than [47m(* (ack i j) (ack i j))[0m.

  In the theorem prover, the [47mlet[0m above expands to

    ((lambda (x) (* x x)) (ack i j))

  and thence to [47m(* (ack i j) (ack i j))[0m.

  It is important to note that the term in [47mbody[0m should not contain a
  call of [47mname[0m --- i.e., [47mdefabbrev[0m should not be used in place of
  [47mdefun[0m when the function is recursive.  ACL2 will not complain when
  the [47mdefabbrev[0m 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 [47mname[0m.

  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 [47m[let][0m.  This may lead to some
  errors or unexpected inefficiencies during evaluation if the body
  contains any conditionally evaluated forms like [47mcond[0m, [47mcase[0m, or [47mif[0m.
  Consider the following example.

    (defabbrev foo (x y)
      (if (test x) (bar y) nil))

  Notice a typical one-step expansion of a call of [47mfoo[0m (see [trans1]):

    ACL2 !>:trans1 (foo expr1 expr2)
     (LET ((X EXPR1) (Y EXPR2))
          (IF (TEST X) (BAR Y) NIL))
    ACL2 !>

  Now imagine that [47mexpr2[0m is a complicated expression whose evaluation
  is intended only when the predicate [47mtest[0m holds of [47mexpr1[0m.  The
  expansion above suggests that [47mexpr2[0m will always be evaluated by the
  call [47m(foo expr1 expr2)[0m, which may be inefficient (since perhaps we
  only need that value when [47mtest[0m is true of [47mexpr1[0m).  The evaluation
  of [47mexpr2[0m may even cause an error, for example in [47m:[0m[47m[program][0m mode if
  the expression [47mexpr2[0m has been constructed in a manner that could
  cause a guard violation unless [47mtest[0m holds of [47mexpr1[0m.")
 (DEFABSSTOBJ (EVENTS STOBJ)
  "Define a new abstract single-threaded object

  We assume familiarity with single-threaded objects; see [stobj] and
  see [defstobj].  The event [47mdefabsstobj[0m defines a so-called
  ``abstract stobj'', a notion we introduce briefly now and then
  explain in more depth below.

  Recall that a [defstobj] event produces logical definitions for
  several functions: a recognizer, which characterizes the [stobj] in
  terms of lists; a creator, which produces an initial suitable list
  structure; and field accessors and updaters, defined in terms of
  [47m[nth][0m and [47m[update-nth][0m.  [47mDefabsstobj[0m 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, [47mdefabsstobj[0m establishes interface functions, or
  ``exports'', on a new stobj that is a copy of an existing stobj,
  its ``foundation'', which is either [3mconcrete[0m (introduced by
  [47m[defstobj][0m) or [3mabstract[0m (introduced by [47mdefabsstobj[0m).

  We begin below with an introduction to abstract [stobj]s.  We then
  explain the [47m[defabsstobj][0m event by way of an example.  We conclude
  by giving summary documentation for the [47mdefabsstobj[0m event.

  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 {ACL2
  Workshop 2013 | http://www.cs.uwyo.edu/~ruben/acl2-13}.

  [31;1mINTRODUCTION[0m

  We start with a brief review of [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.

  Recall that single-threaded objects, or [stobj]s, provide a way for
  ACL2 users to stay within the ACL2 logic --- where every data
  object is an atom or a [47m[cons][0m of data objects --- while obtaining
  the benefits of fast evaluation through destructive updates.
  Consider for example this very simple event.

    (defstobj st fld)

  This event introduces a recognizer, [47mstp[0m, and a creator, [47mcreate-st[0m,
  for a data structure consisting of a single field accessed and
  updated by functions [47mfld[0m and [47mupdate-fld[0m, 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,
  [47mstp[0m 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 [47m[defstobj][0m 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.)

  Here are the logical definition and the executable definition,
  respectively, that are introduced for the field accessor, [47mfld[0m,
  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, [47msvref[0m.  (You can see all the logical and executable
  definitions by evaluating the form [47m(trace$ defstobj-axiomatic-defs
  defstobj-raw-defs)[0m before evaluating the [47m[defstobj][0m form.)

    ; 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))

  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.

    ; 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 ...))))
    ...

  But there are at least two potential difficulties in using stobjs as
  described above.

   1. When [47mfoo[0m is executed on concrete data in the ACL2 loop, the guard
      check may be expensive because [47m(good-stp st)[0m is expensive.

   2. Reasoning about [47mfoo[0m (using rules like [47mfoo-is-correct[0m above) involves
      proving hypotheses of invariance theorems, which may be
      complicated for the user to manage or slow for the theorem
      prover.

  The [47mdefabsstobj[0m 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 [47m[defstobj][0m or [47mdefabsstobj[0m event.  The
  [47mdefabsstobj[0m event specifies a logical ([47m:LOGIC[0m) and an executable
  ([47m:EXEC[0m) definition for each primitive operation, or ``stobj
  primitive'', involving that stobj.  As is the case for [47m[defstobj][0m,
  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).

  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 [47mst$c0[0m suggests
  a foundational (``concrete'') stobj for an abstract stobj named [47mst[0m,
  whose abstract stobj recognizer is [47mst$ap[0m, and so on.  End of
  Remark.

  We can picture a sequence of updates to an abstract stobj and its
  foundational stobj.  Initially in this picture, [47mst$a0[0m and [47mst$c0[0m are
  an abstract stobj and its foundation (respectively).  Then an
  update, [47mu1[0m, is applied with [47m:LOGIC[0m and [47m:EXEC[0m functions [47mu$a1[0m and
  [47mu$c1[0m, respectively.  The resulting abstract and foundational stobj,
  [47mst$a1[0m and [47mst$c1[0m, correspond as before.  Then a second update, [47mu2[0m,
  is applied with [47m:LOGIC[0m and [47m:EXEC[0m functions [47mu$a2[0m and [47mu$c2[0m,
  respectively --- again preserving the correspondence.  And so on.

    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)

  We conclude this introduction with some remarks about implementation.
  Consider an abstract stobj [47mst[0m with corresponding foundation [47mst$c[0m.
  The live stobjs for [47mst[0m and [47mst$c[0m have the same structure, but are
  distinct arrays.  Indeed, the raw Lisp creator function for [47mst$c[0m is
  called to create a new initial live stobj for [47mst[0m.  As we will see
  below, reads and writes in raw Lisp to the live stobj for [47mst[0m are
  ultimately performed using the primitive accessors and updaters
  defined for [47mst$c[0m.  One might think of the live stobjs for [47mst[0m and
  [47mst$c[0m as being congruent stobjs (see [defstobj]), except that the
  stobjs themselves are not truly congruent: in particular, the stobj
  primitives introduced for [47mst[0m may be applied to [47mst[0m, but field
  updaters of [47mst$c[0m may not.  As one might expect, the [47m:EXEC[0m function
  for an exported function is applied to the live stobj for [47mst[0m in raw
  Lisp.

  [31;1mEXAMPLE[0m

  We present examples, with detailed comments intended to explain
  abstract stobjs, in two community books:
  [47mbooks/demos/defabsstobj-example-1.lisp[0m and
  [47mbooks/demos/defabsstobj-example-2.lisp[0m.  In this section we outline
  the first of these.  We suggest that after you finish this
  [documentation] topic, you read through those two books.  There are
  other books [47mbooks/dmeos/defabsstobj-example-*.lisp[0m that may be
  helpful to read; in particular,
  [47mbooks/demos/defabsstobj-example-5.lisp[0m illustrates building an
  abstract stobj on top of another abstract stobj (as its so-called
  ``foundation'', as described below).

  Here is the first of two closely related [47mdefabsstobj[0m [events] from
  the book [47mdefabsstobj-example-1.lisp[0m, 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 [47mdefabsstobj[0m, and that you will learn the remainder when
  you see error messages.  For example, we do not say in the comments
  below that every [47m:LOGIC[0m and [47m:EXEC[0m function must be
  [guard]-verified, but that is indeed a requirement.

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

  Note that all stobj primitives (recognizer, creator, and exported
  functions) are defined in the ACL2 loop in terms of their [47m:LOGIC[0m
  functions and in raw Lisp in terms of their [47m:EXEC[0m functions.  In
  the ACL2 loop, a [47m[defun][0m form defines a function, while in raw
  Lisp, a [47m[defmacro][0m 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 [47m(trace$
  defabsstobj-axiomatic-defs defabsstobj-raw-defs)[0m before evaluating
  the [47m[defstobj][0m form.)

    ; 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))

  The definitions are made similarly for exported functions.  [Guard]s
  are derived from their [47m:LOGIC[0m functions as follows.  Consider the
  exported function [47mupdate[0m in our example.  Its [47m:LOGIC[0m function,
  [47mupdate$a[0m, has formals [47m(k val st$a)[0m and the following guard.

    (and (and (integerp k) (<= 0 k) (<= k 49))
         (and (integerp val) (<= 0 val))
         (st$ap st$a)
         (mem$c-entryp val))

  The formals of [47mupdate[0m are obtained by starting with the formals of
  its [47m:EXEC[0m function, [47mupdate-mem$ci[0m --- which are [47m(i v st$c)[0m --- and
  replacing the foundational stobj name [47mst$c[0m by the new stobj name
  [47mst[0m.  The formals of [47mupdate[0m are thus [47m(i v st)[0m.  The guard for [47mupdate[0m
  is obtained in two steps.  The first step is to substitute the
  formals of [47mupdate[0m for the formals of [47mupdate$a[0m in the guard for
  [47mupdate$a[0m, to obtain the following.

    (and (and (integerp i) (<= 0 i) (<= i 49))
         (and (integerp v) (<= 0 v))
         (st$ap st)
         (mem$c-entryp v))

  The second step is to replace, for each new stobj primitive [47mp[0m, the
  [47m:LOGIC[0m function for [47mp[0m by [47mp[0m itself.  The only [47m:LOGIC[0m function
  occurring in the formula just above is [47mst$ap[0m, which is the [47m:LOGIC[0m
  function for [47mstp[0m.  The guard for [47mupdate[0m is thus as follows.

    (and (and (integerp i) (<= 0 i) (<= i 49))
         (and (integerp v) (<= 0 v))
         (stp st)
         (mem$c-entryp v))

  Note that the [47m:EXEC[0m version of an abstract [stobj] export must not
  include the abstract stobj name among its formals.

  We turn now to the proof obligations, as promised above.  There are
  three types: [47m:CORRESPONDENCE[0m, [47m:PRESERVED[0m, and [47m:GUARD-THM[0m.  All
  required lemmas may be printed simply by defining the necessary
  [47m:LOGIC[0m and [47m:EXEC[0m functions and then submitting the [47mdefabsstobj[0m
  event.  (To advanced users: also see [defabsstobj-missing-events]
  for a utility that returns the required formulas in translated
  form.)  Although the [47mdefabsstobj[0m event will fail if the required
  lemmas have not been proved, first it will print the [47m[defthm][0m forms
  that must be admitted in order to complete submission of the
  [47mdefabsstobj[0m event.  (Note that although those theorems are stated
  exactly in the form expected by the system, you are welcome to
  supply whatever [47m:[0m[47m[rule-classes][0m you prefer, even though the system
  creates [47m:rule-classes nil[0m by default.)

  The detailed theory explaining the need for these lemmas may be found
  in ACL2 source file [47mother-events.lisp[0m, 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.

  We start with the [47m:CORRESPONDENCE[0m 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 [47m:CORR-FN[0m.  We start with the [47m:CREATOR[0m
  function where the statement is quite simple, stating that the
  [47m:CORR-FN[0m holds initially.

    (defthm create-st{correspondence}
      (st$corr (create-st$c) (create-st$a)))

  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
  [47m:LOGIC[0m and [47m:EXEC[0m functions for the exported function.  Hypotheses
  include the [47m:CORR-FN[0m correspondence followed by the [guard] for the
  [47m:LOGIC[0m function, which is stated in terms of the formal parameters
  of the [47m:EXEC[0m function except using the abstract stobj (here, [47mst[0m) in
  place of the foundational stobj (here, [47mst$c[0m).  The conclusion uses
  the [47m:EXEC[0m formals, modified in the call of the [47m:LOGIC[0m function
  (here, [47mlookup$a[0m) to use the abstract stobj, as in the hypotheses.

    (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)

  By contrast, if the exported function returns the new abstract stobj,
  then the conclusion uses the correspondence function instead of
  [47mEQUAL[0m, as in the following.

    (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)

  For exported functions that return multiple values, such conclusions
  are conjoined together over the returned values.

  The [47m:PRESERVED[0m 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 [guard]
  verification, by assuming that the recognizer always holds.  The
  [47m:PRESERVED[0m lemma for the [47m:CREATOR[0m shows that the recognizer holds
  initially.

    (defthm create-st{preserved}
      (st$ap (create-st$a)))

  Here is a typical such lemma, for the exported function [47mupdate[0m.  Note
  that there is no such lemma for [47mlookup[0m, since [47mlookup[0m does not
  return [47mst[0m.

    (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))))

  Finally, we consider the [47m:GUARD-THM[0m lemmas.  These serve to guarantee
  that the [guard] holds for each call of an [47m:EXEC[0m 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 [47m:LOGIC[0m function, guard verification shows
  that each call of the [47m:LOGIC[0m function for an exported function
  satisfies that function's guard.  But why is this true for raw Lisp
  evaluation using live stobjs, where the [47m:EXEC[0m function is called
  for an exported function?  The [47m:GUARD-THM[0m lemmas provide the
  answer, as they state that if the [47m:LOGIC[0m function's guard holds,
  then the [47m:EXEC[0m 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 [47m:CORR[0m
  function, together with the guard of the [47m:LOGIC[0m function; and the
  conclusion comes from the guard of the [47m:EXEC[0m function.

    (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)

  We conclude this EXAMPLE section by showing a short form for the
  [47mdefabsstobj[0m form displayed above.

    (defabsstobj st
      :exports ((lookup :exec mem$ci)
                (update :exec update-mem$ci)
                misc update-misc))

  [31;1mSUMMARY DOCUMENTATION[0m

  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 [47m:exports[0m keyword is required.

    (defabsstobj st
      :foundation foundation
      :recognizer recognizer
      :creator creator
      :corr-fn corr-fn
      :congruent-to congruent-to
      :non-executable non-executable
      :protect-default protect-default
      :attachable att
      :exports (e1 ... ek))

  The keyword argument [47m:EXPORTS[0m must be supplied, and missing or [47mnil[0m
  keyword arguments have defaults as indicated below.  All arguments
  must satisfy the conditions below.

  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

    (fn [47m:kwd1[0m val1 ... [47m:kwdn[0m valn),

  that is, a symbol followed by a [47m[keyword-value-listp][0m.  We view the
  case of a symbol, [47ms[0m, as the function spec [47m(s)[0m, 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
  [47mcar[0m, and that function symbol and each keyword value must be a
  guard-verified function symbol; and moreover, the [47m:EXEC[0m function
  must not include the new abstract stobj name, [47mst[0m, among its
  formals.

  We are ready to describe the arguments of [47mdefabsstobj[0m.

      [47mSt[0m is a symbol, which names the new abstract stobj.

      [47mFoundation[0m is the name of an existing stobj, which may have been
      introduced either with [47m[defstobj][0m or with [47mdefabsstobj[0m.

      [47mRecognizer[0m is a function spec (for the recognizer function).  The
      valid keywords are [47m:LOGIC[0m and [47m:EXEC[0m.  The default for
      [47mrecognizer[0m is obtained by adding the suffix [47m\"P\"[0m to [47mname[0m.  The
      default value for [47m:LOGIC[0m is formed by adding the suffix [47m\"$AP\"[0m
      to [47mrecognizer[0m; for [47m:EXEC[0m, by adding the suffix [47m\"$CP\"[0m.  The
      [47m:EXEC[0m function must be the recognizer for the foundational
      stobj (which can be specified using the [47m:FOUNDATION[0m keyword).

      [47mCreator[0m is a function spec (for the creator function).  The valid
      keywords are [47m:LOGIC[0m and [47m:EXEC[0m.  The default for [47mcreator[0m is
      obtained by adding the prefix [47m\"CREATE-\"[0m to [47mname[0m.  The default
      value for [47m:LOGIC[0m is formed by adding the suffix [47m\"$A\"[0m to
      [47mcreator[0m; for [47m:EXEC[0m, by adding the suffix [47m\"$C\"[0m.  The [47m:EXEC[0m
      function must be the creator for the foundational stobj (which
      can be specified using the [47m:FOUNDATION[0m keyword).

      [47mCorr-fn[0m is a known function symbol that takes two arguments (for the
      correspondence theorems).  The default for [47mcorr-fn[0m is obtained
      by adding the suffix [47m\"$CORR\"[0m to [47mname[0m.

      [47mCongruent-to[0m should either be [47mnil[0m (the default) or the name of an
      abstract stobj previously introduced (by [47m[defabsstobj][0m).  In
      the latter case, the current and previous abstract stobj should
      have the same foundational stobj (not merely congruent
      foundational stobjs), and their [47m:EXPORTS[0m fields should have the
      same length and also correspond, as follows: the ith export of
      each should have the same [47m:LOGIC[0m and [47m:EXEC[0m symbols.  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.

      [47mNon-executable[0m should either be [47mnil[0m (the default) or [47mt[0m.  When [47mt[0m, a
      global stobj is not created for the given name; see [defstobj],
      Section ``Specifying Non-executable Stobjs'', for details, as
      the meaning of [47m:non-executable[0m is the same for [47mdefabsstobj[0m as
      it is for [47mdefstobj[0m.

      [47mProtect-default[0m should either be [47mnil[0m (the default) or [47mt[0m.  It provides
      the value of keyword [47m:PROTECT[0m for each member of [47mexports[0m that
      does not explicitly specify [47m:PROTECT[0m.  See the discussion of
      [47mexports[0m below.

      [47mAttachable[0m should be [47mnil[0m (the default) or [47mt[0m.  See [attach-stobj] for
      a discussion of this keyword.

      An important aspect of the [47mcongruent-to[0m parameter is that if it is
      not [47mnil[0m, then the checks for lemmas --- [47m{CORRESPONDENCE}[0m,
      [47m{GUARD-THM}[0m, and [47m{PRESERVED}[0m --- are omitted.  Thus, the values
      of keyword [47m:CORR-FN[0m, and the values of keywords
      [47m:CORRESPONDENCE[0m, [47m:GUARD-THM[0m, and [47m:PRESERVED[0m in each export (as
      we discuss next), are irrelevant; they are not inferred and
      they need not be supplied.

      The value of [47m:EXPORTS[0m is a non-empty true list.  Each [47mei[0m is a
      function spec (for an exported function).  The valid keywords
      are [47m:LOGIC[0m, [47m:EXEC[0m, [47m:CORRESPONDENCE[0m, and [47m:GUARD-THM[0m, [47m:PROTECT[0m,
      [47m:UPDATER[0m, and also [47m:PRESERVED[0m if and only if the specified
      [47m:EXEC[0m function returns the foundational stobj.  The default
      values for all of these keywords except [47m:UPDATER[0m and [47m:PROTECT[0m
      are obtained by respectively adding the suffix [47m\"$A\"[0m [47m\"$C\"[0m,
      [47m\"{CORRESPONDENCE}\"[0m, [47m\"{GUARD-THM}\"[0m, or [47m\"{PRESERVED}\"[0m.  For
      [47m:PROTECT[0m, the default is [47mnil[0m unless the [47mdefabsstobj[0m event
      specifies [47m:PROTECT-DEFAULT t[0m.  If [47m:UPDATER upd[0m is supplied and
      [47mupd[0m is not [47mnil[0m, then function exported by the function spec is
      a child stobj accessor whose corresponding updater is [47mupd[0m; see
      the discussion of [47m:UPDATER[0m in [nested-stobjs].

  Not shown is the keyword, [47m:MISSING[0m; the effect of [47m:missing t[0m is to
  turn the call of [47mdefabsstobj[0m into a corresponding call of
  [47m[defabsstobj-missing-events][0m.

  Note that a [47mdefabsstobj[0m event will fail if the required lemmas ---
  that is, those for valid keywords [47m:CORRESPONDENCE[0m, [47m:GUARD-THM[0m, and
  [47m:PRESERVED[0m --- have not been proved, unless proofs are being
  skipped.  The exemption when skipping proofs allows the supporting
  lemmas to be [47m[local][0m to [books] and [47m[encapsulate][0m [events].  If the
  [47m[ld][0m special [47m[ld-skip-proofsp][0m is [47mt[0m, then the missing [events] are
  printed with a warning before the [47mdefabsstobj[0m event is admitted;
  but if [47mld-skip-proofsp[0m is the symbol [47mINCLUDE-BOOK[0m, then that
  warning is omitted.  (Also see [skip-proofs] and see
  [ld-skip-proofsp].)  If however proofs are not being skipped, then
  the [47mdefabsstobj[0m event will fail after printing the missing events.
  Advanced users may wish to see [defabsstobj-missing-events] for a
  utility that returns a data structure containing the missing
  lemmas.

  Let [47mst[0m be an abstract stobj with corresponding foundational stobj
  [47mst$c[0m.  Let [47mf[0m be an exported function for [47mst[0m and let [47mf$a[0m and [47mf$c[0m be
  the corresponding [47m:LOGIC[0m and [47m:EXEC[0m functions, respectively.  The
  formals of [47mf[0m are obtained by taking the formals of [47mf$c[0m and
  replacing [47mst$c[0m by [47mst[0m.  The [guard] for [47mf[0m is derived as follows from
  the guard of [47mf$a[0m.  First, the formals of [47mf$a[0m are replaced by the
  formals of [47mf[0m in the guard of [47mf$a[0m, to obtain a term we denote here
  as [47mguard-pre[0m.  Now for each exported function symbol [47mg[0m of [47mst[0m with
  corresponding [47m:LOGIC[0m function [47mg$a[0m, form a functional substitution
  by consing [47mg$a[0m with [47mg[0m.  Finally, apply that functional substitution
  to [47mguard-pre[0m; the result is the guard of [47mf[0m.  That guard must
  satisfy the usual conditions of a guard: thus, it must return a
  single non-[stobj] value and satisfy normal syntactic restrictions,
  including single-threadedness in its handling of stobjs.

  [47mRemark[0m.  Because of how guards are created for exported functions,
  and in particular because [47m:LOGIC[0m functions are replaced as
  discussed above, a good discipline is to define [47m:LOGIC[0m functions
  that are not intended for general use, but are intended only for
  use as [47m:LOGIC[0m functions of corresponding stobj primitives.  For
  example, suppose that you use [47mlength[0m as the [47m:LOGIC[0m function for
  some stobj primitive, [47mf[0m (as opposed to using your own function,
  say, [47mfoo-length[0m or [47mfoo$a[0m).  Then every call of [47mlength[0m will be
  replaced by [47mf[0m when creating the guard of a stobj primitive from the
  guard of its [47m:LOGIC[0m function.  This might not be what you intended
  if you were using [47mlength[0m in that guard simply to compute the length
  of an ordinary list.

  Additional restrictions include the following.

    * All exported function names must be new (unless redefinition is on;
      see [ld-redefinition-action]), and there must be no duplicates
      among them.

    * The foundational stobj name must be a formal parameter of the [47m:EXEC[0m
      function of every function spec, except for the [47m:CREATOR[0m
      function spec.

    * The [47m:LOGIC[0m and [47m:EXEC[0m function for a function spec must agree on both
      the number of inputs and the number of outputs.

    * The foundational stobj must not be a [declare]d stobj of the [47m:LOGIC[0m
      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 [47mdefabsstobj[0m.)

    * The [47m:PROTECT[0m 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 [47m:PROTECT t[0m in the function
      spec, or by providing [47mdefabsstobj[0m keyword argument
      [47m:PROTECT-DEFAULT t[0m at the top level, in order to restore the
      required atomicity.  The above explanation is probably all you
      need to know about [47m:PROTECT[0m, but just below is a more complete
      explanation for those who desire it.  Further information is
      also available if you need it; see [set-absstobj-debug], and
      see the example uses of these keywords in community book
      [47mbooks/demos/defabsstobj-example-2.lisp[0m.

  For those who are interested, here is a more detailed discussion of
  [47m:PROTECT[0m and [47m:PROTECT-DEFAULT[0m, as promised above.  It applies to
  any function spec for an export (hence not to the [47m:CREATOR[0m function
  spec).  If the [47m:EXEC[0m 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 ---
  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 [47m:EXEC[0m
  function ``appears capable of modifying the foundational stobj,
  [47m<stobj_name>[0m, non-atomically.'' That message also explains how to
  eliminate this error: provide [47m:PROTECT t[0m for the function spec.
  Alternatively, all function specs without an explicit [47m:PROTECT[0m
  keyword can be implicitly supplied [47m:PROTECT t[0m by supplying the
  value [47mt[0m for the [47m:PROTECT-DEFAULT[0m keyword parameter of the
  [47mdefabsstobj[0m event.  However, beware that when [47m:PROTECT[0m is [47mt[0m, the
  generated raw Lisp code runs slightly less efficiently --- though
  perhaps with negligible efficiency loss if the [47m:EXEC[0m function is
  not trivial.  Community books
  [47mbooks/demos/defabsstobj-example-3.lisp[0m and
  [47mbooks/demos/defabsstobj-example-4.lisp[0m provide related information.
  Also see [set-absstobj-debug] for a potentially dangerous way to
  eliminate that inefficiency using argument [47m:ignore[0m.

  We conclude with some remarks.

  Unlike [47m[defstobj][0m, there is no [47m:renaming[0m argument.  Instead, the
  scheme described above provides a flexible way to assign names.
  Also unlike [47m[defstobj][0m, there is no [47m:inline[0m or [47m:non-memoizable[0m
  argument; [47m:inline[0m is essentially t, in the sense that stobj
  primitives are macros in raw Lisp; and the [47m:non-memoizable[0m argument
  is derived implicitly, to agree with non-memoizability of the
  foundational stobj.

  Those who use [hons-enabled] features, including function memoization
  (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.


Subtopics

  [Attach-stobj]
      Attach an ``implementation [stobj]'' to an attachable stobj

  [Illegal-state]
      Illegal ACL2 state

  [Set-absstobj-debug]
      Get more information when atomic update fails for an abstract stobj")
 (DEFABSSTOBJ-MISSING-EVENTS
  (EVENTS)
  "Obtain the [events] needed to admit a [47m[defabsstobj][0m event

  We assume familiarity with [47m[defabsstobj][0m.  [47mDefabsstobj-missing-events[0m
  is a macro is for advanced users (who, for example, understand the
  role of the [47mtranslate[0m and [47muntranslate[0m functions), who want
  programmatic access to the [47m[defthm][0m events required to admit a
  specific [47mdefabsstobj[0m event.

  This macro has the same syntax as [47m[defabsstobj][0m --- to use it, just
  replace a call of [47m[defabsstobj][0m by a call of
  [47mdefabsstobj-missing-events[0m on the same arguments.  The result is an
  error triple [47m(mv erp val state)[0m.  If [47merp[0m is [47mnil[0m, then [47mval[0m is the
  list of all objects [47m(name formula . old-formula)[0m, where a [47m[defthm][0m
  event named [47mname[0m remains to be admitted whose translated formula is
  [47mformula[0m, and where [47mold-formula[0m is [47mnil[0m unless the indicated event
  already exists (hence with a different formula), in which case
  [47mold-formula[0m is the existing translated formula.

  To build a [47m[defthm][0m event from the above value, [47mval[0m, we suggest
  evaluating a form like [47m(untranslate formula t (w state))[0m.")
 (DEFATTACH
  (EVENTS)
  "Execute constrained functions using corresponding attached functions

    General Forms:
    (defattach f g)   ; single attach or, if g is nil, unattach
    (defattach (f1 g1 :kwd val ...)
               ...
               (fk gk :kwd' val' ...)
               :kwd'' val'' ...)

  where each indicated keyword-value pair is optional and each keyword
  is in the list [47m(:hints :instructions :otf-flg :attach :skip-checks
  :system-ok)[0m.  More details are in the ``Syntax and Semantics''
  section below.

  A related utility can cause a function call to be evaluated using an
  alternate, provably equal function.  See [memoize], option [47m:INVOKE[0m.

  This [documentation] topic is organized into the following sections:

    * Introductory Example.

    * Syntax and Semantics of Defattach.

    * Three Primary Uses of Defattach.

    * Miscellaneous Remarks, with discussion of possible user errors.

  Please see [encapsulate] if you intend to use [47mdefattach[0m but are not
  already familiar with the use of [47mencapsulate[0m to introduce
  constrained functions.  It may also be helpful to see [evaluation].

  See community book [47mbooks/misc/defattach-example.lisp[0m for a small
  example.  it illustrates how [47mdefattach[0m may be used to build
  something like ``higher-order'' programs, in which constrained
  functions may be refined to different executable functions.  More
  uses of [47mdefattach[0m may be found in the ACL2 source code,
  specifically, file [47mboot-strap-pass-2-a.lisp[0m.


Introductory Example.

  We begin with a short log illustrating the use of [47mdefattach[0m.  Notice
  that after evaluating the event [47m(defattach f g)[0m, a call of the
  constrained function [47mf[0m is evaluated by instead calling [47mg[0m on the
  arguments.

    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 !>


Syntax and Semantics of Defattach.

  The log above shows that the event [47m(defattach f g)[0m allows [47mg[0m to be
  used for evaluating calls of [47mf[0m.  From a logical perspective, the
  evaluation takes place in the addition to the current session of an
  ``attachment equation'' axiom (universally quantified over all [47mx[0m)
  for each [47mdefattach[0m event:

    (equal (f x) (g x)) ;;; attachment equation axiom for (defattach f g)

  Below we explain [47mdefattach[0m 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 [47m[defaxiom][0m [events] from the
  user.  This guarantee is a consequence of a more general guarantee:
  an ACL2 logical [world] exists in which (loosely speaking) the
  attachment equation for [47m(defattach f g)[0m, as [47m(defun f (...) (g
  ...))[0m, takes the place of the original defining event for [47mf[0m, for
  each [47mdefattach[0m event.  This more general guarantee holds even if
  there are [47m[defaxiom][0m events, though as explained below, no function
  symbol that syntactically supports a [47mdefaxiom[0m 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.''

    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 ...)

  where each indicated keyword-value pair is optional and each keyword
  is in the list [47m(:hints :instructions :otf-flg :attach :skip-checks
  :system-ok)[0m.  We distinguish between keywords within the [47m(fi gi
  :kwdi1 vali1 ...)[0m, which we call [3mguard keywords[0m, and keywords at
  the top level, shown above as [47m:kwd1 val1 ...[0m, which we call
  [3mtop-level keywords[0m.

    * The guard keywords are in the list [47m(:hints :instructions :otf-flg
      :attach)[0m.  The [47m:[0m[47m[hints][0m, [47m:[0m[47m[instructions][0m, and [47m:[0m[47m[otf-flg][0m
      keywords in [47m(fi gi ...)[0m are used in the proofs of the guard
      proof obligation for the attachment of [47mgi[0m to [47mfi[0m.  They have
      their usual values and meanings, as when used (for example) in
      [47m[defthm][0m [47m[events][0m.  The value of each [47m:attach[0m keyword is either
      [47mt[0m or [47mnil[0m.  We discuss the [47m:attach[0m keyword later in this
      [documentation] topic.

    * The top-level keywords [47m:hints[0m, [47m:instructions[0m, and [47m:otf-flg[0m are used
      in the constraint proof obligations just as described above for
      the guard proof obligations.  When [47m:attach[0m is used as a
      top-level keyword, its value serves as a default for entries
      [47m(fi gi ...)[0m that do not specify [47m:attach[0m.  [47m:Skip-checks[0m and
      [47m:system-ok[0m are described below.

  No keyword may occur twice in the same context: that is, neither
  twice as a guard keyword in the same [47m(fi gi ...)[0m entry, nor twice
  as a top-level keyword.  Moreover, [47m:instructions[0m may not occur in
  the same context with [47m:hints[0m or [47m:otf-flg[0m.

  The argument [47m:skip-checks t[0m enables easy experimentation with
  [47mdefattach[0m, by permitting use of [47m:[0m[47m[program][0m mode functions and the
  skipping of semantic checks.  Also permitted is [47m:skip-checks nil[0m
  (the default) and [47m:skip-checks :cycles[0m, 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 [47m:skip-checks[0m is
  non-[47mnil[0m; indeed, a trust tag is then required (see [defttag]).
  Note that the interaction of [memoization] and attachments is not
  tracked for attachments introduced with a non-[47mnil[0m value of
  [47m:skip-checks[0m.  For more discussion of [47m:skip-checks t[0m, see
  [defproxy]; we do not discuss [47m:skip-checks[0m further, here.

  The argument [47m:system-ok t[0m allows attachment to system functions.
  Without this argument, the [47mdefattach[0m event will fail if any [47mfi[0m is a
  built-in ACL2 function.  Rather than supplying this argument
  directly, it is recommended to use [47m[defattach-system][0m, which has
  the same syntax as [47mdefattach[0m with two exceptions: it adds
  [47m:system-ok t[0m automatically, that is, [47m:system-ok[0m is implicit; and it
  expands to a [47m[local][0m call of [47mdefattach[0m.  The latter is important so
  that the attachment does not affect system behavior outside a book
  containing the [47mdefattach[0m event.  Of course, if it is truly intended
  to affect such behavior, the argument [47m:system-ok t[0m may be given
  directly to [47mdefattach[0m, without a surrounding use of [47mlocal[0m.

  The first General Form above is simply an abbreviation for the form
  [47m(defattach (f g))[0m, which is an instance of the second General Form
  above.  For the second General Form we say that [47mgi[0m is ``attached
  to'' [47mfi[0m (by the [47mdefattach[0m event) if [47mgi[0m is not [47mnil[0m, and otherwise we
  say that [47mfi[0m is ``unattached'' (by the [47mdefattach[0m event).  It is also
  convenient to refer to [47m<fi,gi>[0m as an ``attachment pair'' (of the
  event) if [47mgi[0m is not [47mnil[0m.  We may refer to the set of [47mfi[0m as the
  ``attachment nest'' of each [47mfi[0m.

  We start with a brief introduction to the first General Form in the
  case that [47mg[0m is not [47mnil[0m.  This form arranges that during evaluation,
  with exceptions noted below, every call of the constrained function
  symbol [47mf[0m will in essence be replaced by a call of the function
  symbol [47mg[0m on the same arguments.  We may then refer to [47mg[0m as the
  ``attachment of'' [47mf[0m, or say that ``[47mg[0m is attached to [47mf[0m.'' Notable
  exceptions, where we do not use attachments during evaluation, are
  for macroexpansion, evaluation of [47m[defconst][0m and [47m[defpkg][0m terms,
  evaluation during [47m[table][0m events, some [stobj] operations including
  all updates (see [STOBJ]), 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 [47m[prog2$][0m and, more generally, the next-to-last (i.e.,
  second) argument of [47m[return-last][0m when its first argument is not of
  the form [47m'm[0m for some macro, [47mm[0m.

  To see why attachments are disallowed during evaluation of ground
  terms during proofs (except for the [47m[prog2$][0m and [47m[return-last][0m
  cases mentioned above), consider the following example.

    (defstub f (x) t)
    (defun g (x) (+ 3 x))
    (defattach f g)

  If the form [47m(f 2)[0m is submitted at the ACL2 prompt, the result will be
  [47m5[0m because the attachment [47mg[0m of [47mf[0m is called on the argument, [47m2[0m.
  However, during a proof the term [47m(f 2)[0m will not be simplified to [47m5[0m,
  since that would be unsound, as there are no axioms about [47mf[0m that
  would justify such a simplification.

  For the case that [47mg[0m is [47mnil[0m in the first General Form above, the
  result is the removal of the existing attachment to [47mf[0m, if any.
  After this removal, calls of [47mf[0m will once again cause errors saying
  that ``ACL2 cannot ev the call of undefined function [47mf[0m ...''.  In
  this case not only is the previous attachment to [47mf[0m removed;
  moreover, for every function symbol [47mf'[0m in the attachment nest of [47mf[0m
  in the [47mdefattach[0m event that introduced the existing attachment to
  [47mf[0m, then [47mf'[0m is unattached.  (An example near the end of this
  [documentation] topic shows why this unattachment needs to be
  done.) Such removal takes place before the current [47mdefattach[0m is
  processed, but is restored if the new event fails to be admitted.

  We focus henceforth on the second General Form.  There must be at
  least one attachment, i.e., [47mi[0m must be at least 1.  All keywords are
  optional; their role is described below.  The [47mfi[0m must be distinct
  constrained function symbols, that is, function symbols all
  introduced in [signature]s of [47m[encapsulate][0m [events] (or macros
  such as [47m[defstub][0m that generate [47m[encapsulate][0m events).  Each
  non-[47mnil[0m [47mgi[0m is a [47m:[0m[47m[logic][0m-mode function symbol that has had its
  guards verified, with the same [signature] as [47mfi[0m (though formal
  parameters for [47mfi[0m and [47mgi[0m may have different names).  (Note: The
  macro [47mdefattach![0m, defined in community book
  [47mbooks/misc/defattach-bang[0m, 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 [47mfi[0m, as described above for
  the first General Form, and then to attach each [47mgi[0m to [47mfi[0m.

  Proof obligations must be checked before making attachments.  For
  this discussion we assume that each [47mgi[0m is non-[47mnil[0m (otherwise first
  remove all attachment pairs [47m<fi,gi>[0m for which [47mgi[0m is nil).  Let [47ms[0m be
  the functional substitution mapping each [47mfi[0m to [47mgi[0m.  For any term [47mu[0m,
  we write [47mu\\s[0m for the result of applying [47ms[0m to [47mu[0m; that is, [47mu\\s[0m is the
  ``functional instance'' obtained by replacing each [47mfi[0m by [47mgi[0m in [47mu[0m.
  Let [47mG_fi[0m and [47mG_gi[0m be the guards of [47mfi[0m and [47mgi[0m, respectively.  Let
  [47mG_fi'[0m be the result of replacing each formal of [47mfi[0m by the
  corresponding formal of [47mgi[0m in [47mG_fi[0m.  ACL2 first proves, for each [47mi[0m
  (in order), the formula [47m(implies G_fi' G_gi)\\s[0m.  If this sequence
  of proofs succeeds, then the remaining formula to prove is the
  functional instance [47mC\\s[0m of the conjunction [47mC[0m of the constraints on
  the symbols [47mfi[0m; see [constraint].  This last proof obligation is
  thus similar to the one generated by functional instantiation (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 [lemma-instance]).  Thus, you will likely avoid
  some proofs with the sequence

    (defattach f g)
    (defattach f nil)
    (defattach f g)
    (defattach f nil)
    ...

  rather than the sequence:

    (defattach f g)
    :u
    (defattach f g)
    :u
    ...

  It remains to describe an ordering check.  We begin with the
  following motivating example.

    (defstub f (x) t) ; constrained function with no constraints
    (defun g (x) (declare (xargs :guard t)) (not (f x)))
    (defattach f g) ; ILLEGAL!

  Were the above [47mdefattach[0m event to succeed, the evaluation theory
  (discussed above) would be inconsistent: [47m(f x)[0m equals [47m(g x)[0m by the
  new attachment equation, which in turn equals [47m(not (f x))[0m by
  definition of [47mg[0m.  The evaluation would therefore be meaningless.
  Also, from a practical perspective, there would be an infinite loop
  resulting from any call of [47mf[0m.

  We consider a function symbol [47mg[0m to be an [3mextended immediate ancestor
  of[0m a function symbol [47mf[0m if either of the following two criteria is
  met: (a) [47mg[0m occurs in the formula that introduces [47mf[0m (i.e.,
  definition body or constraint) and [47mg[0m is introduced by an event
  different from (earlier than) the event introducing [47mf[0m; or (b) [47mg[0m is
  attached to [47mf[0m.  We also consider [47mg[0m to be an extended immediate
  ancestor of [47mf[0m if there are function symbols [47mf'[0m and [47mg'[0m that are
  introduced in the same events as [47mf[0m and [47mg[0m, respectively (such as the
  same [47m[mutual-recursion][0m or the same [47m[encapsulate][0m with non-empty
  signatures), such that [47mg'[0m is an extended immediate ancestor of [47mf'[0m
  in the sense above.  For a proposed [47mdefattach[0m 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 [47mdefattach[0m events.

  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'' --- function symbols introduced by the same event
  --- as siblings are considered equivalent for purposes of the
  acyclicity check.


Three Primary Uses of Defattach.

  We anticipate three uses of [47mdefattach[0m:

   1. Constrained function execution

   2. Sound modification of the ACL2 system

   3. Program refinement

  We discuss these in turn.

   1. The example at the beginning of this [documentation] illustrates
      constrained function execution.

   2. ACL2 is written essentially in itself.  Thus, there is an opportunity
      to attach to system functions.  For example, encapsulated
      function [47mtoo-many-ifs-post-rewrite[0m, in the ACL2 source code,
      receives an attachment of [47mtoo-many-ifs-post-rewrite-builtin[0m,
      which implements a heuristic used in the rewriter.  See
      [system-attachments].  To find all such examples, search the
      source code for the string `-builtin'.
      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.

   3. Recall that for an attachment pair [47m<f,g>[0m, a proof obligation is
      (speaking informally) that [47mg[0m satisfies the constraint on [47mf[0m.
      Yet more informally speaking, [47mg[0m is ``more defined'' than [47mf[0m; we
      can think of [47mg[0m as ``refining'' [47mf[0m.  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.


Miscellaneous Remarks, with discussion of possible user errors.

  We conclude with remarks on some details.

  A [47mdefattach[0m event is never redundant (see [redundant-events]); in
  that sense it is analogous to [47m[in-theory][0m.

  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 [47mtoo-many-ifs-post-rewrite[0m
  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 [evaluator-restrictions] for a discussion of that
  restriction, and see [transparent-functions] for a device that can
  relax the restriction (while imposing additional requirements on
  attachments).

  For an attachment pair [47m<f,g>[0m, evaluation of [47mf[0m never consults the
  [guard] of [47mf[0m.  Rather, control passes to [47mg[0m, whose guard is checked
  if necessary.  The proof obligation related to guards, as described
  above, guarantees that any legal call of [47mf[0m is also a legal call of
  [47mg[0m.  Thus for guard-verified code that results in calls of [47mf[0m in raw
  Lisp, it is sound to replace these calls with corresponding calls
  of [47mg[0m.

  [47mDefattach[0m events are illegal inside any [47m[encapsulate][0m event with a
  non-empty [signature] unless they are [local] to the [47m[encapsulate][0m.

  (Of interest only to users of [47m[apply$][0m.)  Special handling is applied
  when attempting to attach to a so-called [3mwarrant[0m, which is produced
  by an application of [47m[defwarrant][0m (or [47m[defun$][0m).  In that case it
  is legal to attach the function [47mtrue-apply$-warrant[0m to the warrant,
  without any proof obligation.  This attachment is actually
  performed automatically by [47mdefwarrant[0m, so users (even users of
  [47mapply$[0m) need not deal explicitly with such attachments.  However,
  these attachments make warrants executable in the loop; for
  example, after [47m(defwarrant foo)[0m, [47m(warrant foo)[0m will evaluate to [47mt[0m
  in the loop.

  We next discuss a restriction based on a notion of a function symbol
  syntactically supporting an event.  Function symbol [47mf[0m is [3mancestral[0m
  in event [47mE[0m if either [47mf[0m occurs in [47mE[0m, or (recursively) [47mf[0m occurs in an
  event [47mE'[0m that introduces some function symbol [47mg[0m that is ancestral
  in [47mE[0m.  We require that no function symbol ancestral in the formula
  of a [47m[defaxiom][0m 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 [47mnil[0m!

    (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)

  The form [47m(all-attachments (w state))[0m evaluates to the list of all
  attachments except in two cases: [warrant]s, and attachments
  introduced with a non-[47mnil[0m value of [47m:skip-checks[0m.  To obtain the
  attachment to a function symbol [47mFN[0m, without the above restrictions
  and with value [47mnil[0m if there is no attachment to [47mFN[0m: [47m(cdr
  (attachment-pair 'FN (w state)))[0m.

  Next we discuss the [47m:ATTACH[0m keyword.  There is rarely if ever a
  reason to specify [47m:ATTACH T[0m, but the following (admittedly
  contrived) example shows why it may be necessary to specify [47m:ATTACH
  NIL[0m.  First we introduce three new function symbols.

    (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))))

  Now suppose we want to attach the function [47m[ACL2-numberp][0m to both [47mf[0m
  and [47mh[0m.

    (defattach (f acl2-numberp) (h acl2-numberp))

  Such an attempt fails, because the following constraint is generated
  but is not a theorem: [47m(EQUAL (ACL2-NUMBERP X) (G X))[0m.  Clearly we
  also need to attach to [47mg[0m as well.

    (defattach (f acl2-numberp) (h acl2-numberp) (g acl2-numberp))

  But this fails for a different reason, as explained by the error
  message:

    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.

  That is: logically, we need to attach [47macl2-numberp[0m to [47mg[0m, but we
  cannot actually attach to [47mg[0m because it was not introduced with
  [47m[encapsulate][0m (it was introduced with [47m[defun][0m).  So we specify
  [47m:ATTACH NIL[0m for the attachment to [47mg[0m, saying that no actual
  attachment should be made to the code for [47mg[0m, even though for
  logical purposes we should consider that [47mg[0m has been given the
  indicated attachment.

    (defattach (f acl2-numberp) (h acl2-numberp) (g acl2-numberp :attach nil))

  Finally, we can check that [47mf[0m, [47mg[0m, and [47mh[0m execute as expected.

    ACL2 !>(assert-event (and (f 3)
                       (not (f t))
                       (g 3)
                       (not (g t))
                       (h 3)
                       (not (h t))))
     :PASSED
    ACL2 !>

  The advanced feature, [47m[with-global-stobj][0m, imposes certain
  restrictions on a [47mdefattach[0m event.  You can probably ignore this
  point unless you get an error pertaining to [47mwith-global-stobj[0m.  For
  relevant documentation see [with-global-stobj], specifically the
  section on ``Constrained Functions and Defattach''.

  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.

    (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))

  The second [47mdefattach[0m erases the existing attachment pair [47m<f1,four>[0m
  before installing the new attachment pairs [47m<f1,five>[0m and [47m<f3,five>[0m.
  After the second defattach, both [47m(f1)[0m and [47m(f3)[0m evaluate to 5.  Now
  suppose that the attachment pair [47m<f2,four>[0m were not erased.  Then
  we would have [47m(f1)[0m evaluating to 5 and [47m(f2)[0m evaluating to 4,
  contradicting the constraint [47mf2=f1[0m.  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 [47mf2=f1[0m.


Subtopics

  [Defattach-system]
      Attach to built-in, system-level, constrained functions

  [Ignored-attachment]
      Why attachments are sometimes not used

  [System-attachments]
      System-level algorithms that users can modify with attachments")
 (DEFATTACH-SYSTEM
  (DEFATTACH)
  "Attach to built-in, system-level, constrained functions

  For background on attachments, see [defattach].  The macro
  [47mdefattach-system[0m is a convenient way to attach to built-in
  functions.  The event [47m(defattach f g)[0m will fail if [47mf[0m is built into
  ACL2.  This failure can be overcome by specifying top-level keyword
  argument [47m:system-ok t[0m, for example: [47m(defattach (f g) :system-ok t)[0m.
  However, rather than supplying this argument directly, it is
  recommended to use [47mdefattach-system[0m, which has the same syntax as
  [47mdefattach[0m with two exceptions: it adds [47m:system-ok t[0m automatically,
  that is, [47m:system-ok[0m is implicit; and it expands to a [47m[local][0m call
  of [47mdefattach[0m.  The latter is important so that the attachment does
  not affect system behavior outside a book containing the [47mdefattach[0m
  event.  Of course, if it is truly intended to affect such behavior,
  the argument [47m:system-ok t[0m may be given directly to [47mdefattach[0m,
  without a surrounding use of [47mlocal[0m.

  See [system-attachments] for discussion of system attachments.  Also
  see [efficiency] for how to use attachments to modify the prover's
  behavior.")
 (DEFAULT
  (ARRAYS ACL2-BUILT-INS)
  "Return the [47m:default[0m from the [header] of a 1- or 2-dimensional array

    Example Form:
    (default 'delta1 a)

    General Form:
    (default name alist)

  where [47mname[0m is an arbitrary object and [47malist[0m is a 1- or 2-dimensional
  array.  This function returns the contents of the [47m:default[0m field of
  the [header] of [47malist[0m.  When [47m[aref1][0m or [47m[aref2][0m is used to obtain a
  value for an index (or index pair) not bound in [47malist[0m, the default
  value is returned instead.  Thus, the array [47malist[0m may be thought of
  as having been initialized with the default value.  [47mdefault[0m
  operates in virtually constant time if [47malist[0m is the semantic value
  of [47mname[0m.  See [arrays].

  [31;1mFunction: [0m<default>

    (defun default (name l)
      (declare (xargs :guard (or (array1p name l) (array2p name l))))
      (cadr (assoc-keyword :default (cdr (header name l)))))")
 (DEFAULT-BACKCHAIN-LIMIT
  (RULE-CLASSES)
  "Specifying the backchain limit for a rule

  See [backchain-limit].

  The initial value is [47m(nil nil)[0m.  To inspect the current value (as
  explained elsewhere; see [backchain-limit]):

    (default-backchain-limit wrld :ts) ; for type-set reasoning
    (default-backchain-limit wrld :rewrite) ; for rewriting")
 (DEFAULT-DEFUN-MODE
  (MISCELLANEOUS)
  "The default [defun-mode] of [47m[defun][0m'd functions

  When a [47m[defun][0m is processed and no [47m:mode[0m [47mxarg[0m is supplied, the
  function [47mdefault-defun-mode[0m is used.  To find the default
  [defun-mode] of the current ACL2 [world], type [47m(default-defun-mode
  (w state))[0m.  See [defun-mode] for a discussion of [defun-mode]s.
  To change the default [defun-mode] of the ACL2 [world], type one of
  the keywords [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m.

  The default ACL2 [prompt] displays the current default [defun-mode]
  by showing the character [47mp[0m for [47m:[0m[47m[program][0m mode, and omitting it for
  [47m:[0m[47m[logic][0m mode; see [default-print-prompt].  The default
  [defun-mode] may be changed using the keyword [command]s [47m:[0m[47m[program][0m
  and [47m:[0m[47m[logic][0m, which are equivalent to the [command]s [47m(program)[0m and
  [47m(logic)[0m.  Each of these names is documented separately: see
  [program] and see [logic].  The default [defun-mode] is stored in
  the [table] [47m[ACL2-defaults-table][0m and hence may also be changed by
  a [47m[table][0m [command].  See [table] and also see
  [ACL2-defaults-table].  Both mode-changing [command]s are [events].

  While [events] that change the default [defun-mode] are permitted
  within an [47m[encapsulate][0m or the text of a book, their effects are
  [47m[local][0m in scope to the duration of the encapsulation or inclusion.
  For example, if the default [defun-mode] is [47m:[0m[47m[logic][0m and a book is
  included that contains the event [47m(program)[0m, then subsequent
  [events] within the book are processed with the default
  [defun-mode] [47m:[0m[47m[program][0m; but when the [47m[include-book][0m event
  completes, the default [defun-mode] will still be [47m:[0m[47m[logic][0m.
  [Command]s that change the default [defun-mode] are not permitted
  inside [47m[local][0m forms.")
 (DEFAULT-HINTS
  (HINTS)
  "A list of hints added to every proof attempt

    Examples:
    ACL2 !>(default-hints (w state))
    ((computed-hint-1 clause)
     (computed-hint-2 clause stable-under-simplificationp))

  The value returned by this function is appended to the right of any
  explicitly provided :[hints] argument of every [47m[defthm][0m, [47m[thm][0m, and
  [47m[defun][0m event, and similarly for the [47m:guard-hints[0m argument of
  [47mdefun[0m, and, for ACL2(r), the [47m:std-hints[0m argument.

  See [set-default-hints] for a more general discussion.  Advanced
  users only: see [override-hints] for an advanced variant of default
  hints that are not superseded by [47m:[0m[47m[hints][0m arguments.


Subtopics

  [Add-default-hints]
      Add to the default hints

  [Add-default-hints!]
      Add to the default hints non-[47m[local][0mly

  [Default-hints-table]
      A [table] used to provide [hints] for proofs

  [Remove-default-hints]
      Remove from the default hints

  [Remove-default-hints!]
      Remove from the default hints non-[47m[local][0mly

  [Set-default-hints]
      Set the default hints

  [Set-default-hints!]
      Set the default hints non-[47m[local][0mly")
 (DEFAULT-HINTS-TABLE
  (DEFAULT-HINTS)
  "A [table] used to provide [hints] for proofs

  Please see [set-default-hints], see [add-default-hints], and see
  [remove-default-hints] for how to use this table.  For
  completeness, we mention here that under the hood, these events all
  update the [47mdefault-hints-table[0m by updating its key, [47mt[0m, for example
  as follows.

    (table default-hints-table t
           '((computed-hint-1 clause)
             (computed-hint-2 clause
                              stable-under-simplificationp)))

  The use of default hints is explained elsewhere; see
  [set-default-hints].

  Advanced users only: see [override-hints] for an advanced variant of
  default hints.")
 (DEFAULT-PRINT-PROMPT
  (LD)
  "The default [prompt] printed by [47m[ld][0m

    Example prompt:
    ACL2 p!s>

  The [prompt] printed by ACL2 displays the current package, followed
  by a space, followed by zero or more of the three [characters] as
  specified below, followed by the character [47m[>][0m printed one or more
  times, reflecting the number of recursive calls of [47m[ld][0m.  The three
  [characters] in the middle are as follows:

    p     ; when (default-defun-mode (w state)) is :program
    !     ; when guard checking is on
    s     ; when (ld-skip-proofsp state) is t

  See [default-defun-mode], see [set-guard-checking], and see
  [ld-skip-proofsp].

  Also see [ld-prompt] to see how to install your own [prompt].

  Here are some examples with [47mld-skip-proofsp nil[0m.

    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

  Here are some examples with [47m[default-defun-mode][0m of [47m:[0m[47m[logic][0m.

    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

  Finally, here is the prompt in raw mode (see [set-raw-mode]),
  regardless of the settings above:

    ACL2 P>")
 (DEFAULT-RULER-EXTENDERS
  (RULERS)
  "The default [ruler-extenders] for [47m[defun][0m'd functions

  When a [47m[defun][0m is processed and no [47m:ruler-extenders[0m [47mxarg[0m is supplied,
  the function [47mdefault-ruler-extenders[0m is used to obtain the current
  ruler-extenders; see [rulers].  To find the default ruler-extenders
  of the current ACL2 [world], type [47m(default-ruler-extenders (w
  state))[0m.

  While [events] that change the default ruler-extenders are permitted
  within an [47m[encapsulate][0m or the text of a book, their effects are
  [47m[local][0m in scope to the duration of the encapsulation or inclusion.
  See [default-defun-mode] for an analogous discussion for
  defun-modes.")
 (DEFAULT-STATE-VARS (POINTERS)
                     "See [system-utilities].")
 (DEFAULT-TOTAL-PARALLELISM-WORK-LIMIT
  (PARALLEL-PROOF)
  "For ACL2(p): returns the default value for global
  [47mtotal-parallelism-work-limit[0m

  See [set-total-parallelism-work-limit].")
 (DEFAULT-VERIFY-GUARDS-EAGERNESS (POINTERS)
                                  "See [set-verify-guards-eagerness].")
 (DEFAXIOM (EVENTS)
  "Add an axiom

  WARNING: We strongly recommend that you not add axioms.  If at all
  possible you should use [47m[defun][0m or [47m[mutual-recursion][0m to define new
  concepts recursively or use [47m[encapsulate][0m 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 [47m[skip-proofs][0m 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!

    Example:
    (defaxiom sbar (equal t nil)
              :rule-classes nil)

    General Form:
    (defaxiom name term
             :rule-classes rule-classes)

  where [47mname[0m is a new symbolic name (see [name]), [47mterm[0m is a term
  intended to be a new axiom, and [47mrule-classes[0m is a legal value for
  [47m:rule-classes[0m (see [rule-classes]).  The keyword argument is
  optional.  If [47m:[0m[47m[rule-classes][0m is not supplied, the list [47m(:rewrite)[0m
  is used; if you wish the axiom to generate no rules, specify
  [47m:[0m[47m[rule-classes][0m [47mnil[0m.")
 (DEFBADGE
  (APPLY$ ACL2-BUILT-INS)
  "Issue a badge for a function so [47m[apply$][0m can evaluate with it

  It is best to be somewhat familiar with the documentation of [47m[apply$][0m
  before reading this topic.

  Before using [47mdefbadge[0m or a utility like [47m[defun$][0m that relies on it:

    (include-book \"projects/apply/top\" :dir :system)


Badges versus Warrants

  It is easy to confuse [badge]s, which are issued by [47mdefbadge[0m, with
  [warrant]s, which are issued by [47m[defwarrant][0m.  Badges and warrants
  are necessary to ACL2's support of [47m[apply$][0m 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
  [47mapply$[0m is not allowed to handle certain functions such as the
  [47mrussell[0m function illustrated in [47m[introduction-to-apply$][0m.  But to
  determine whether a newly defined function is allowed to be known
  to [47mapply$[0m, 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
  ``[47mlocal[0m 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
  [31;1mLesson 12[0m of [introduction-to-apply$]).

  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 [47m[apply$][0m'd, which are treated like expressions to be
  [47m[ev$][0m'd, and which are treated like ordinary ACL2 objects to be
  [47mcar[0m'd, [47mcdr[0m'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 [47mapply$[0m on the symbol.

  [47mDefbadge[0m analyzes the definition of a function and constructs the
  badge if possible.  [47mDefbadge[0m does not affect the logic --- no
  definitions or axioms are added.  [47mDefbadge[0m can analyze both
  [47m:program[0m mode functions and [47m:logic[0m mode functions.  [47mDefwarrant[0m, on
  the other hand, can only analyze [47m:logic[0m mode functions because it
  must inspect the measure used to justify the termination of the
  function and, if it is successful, it adds a [47m:logic[0m mode definition
  of the warrant to the logic.  This definition links the symbol to
  the function via [47mbadge[0m and [47mapply$[0m and if the warrant is a
  hypothesis of a conjecture then the prover ``knows'' about the
  linkage.

  Both [47mdefbadge[0m and [47mdefwarrant[0m affect the top-level read-eval-print
  loop because that loop treats [47m:program[0m and [47m:logic[0m functions
  differently so that it can (a) allow [47m:program[0m mode terms to be
  evaluated to carry out commands such as [47m[defun][0m and [47m[defthm][0m, query
  the world or build and test prototypes, and (b) allow [47m:logic[0m mode
  terms to be evaluated while guaranteeing a certain correspondence
  with what can be proved.  See [guarantees-of-the-top-level-loop].


Requirements of [47mDefbadge[0m

    General Form:
    (defbadge fn)

  where [47mfn[0m is a defined function name in either [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m
  mode.  This command analyzes the body of [47mfn[0m to determine whether it
  satisfies certain stringent syntactic conditions discussed below.
  If the conditions are not met, [47mdefbadge[0m signals an error.
  Otherwise, it records a [badge] for [47mfn[0m.  Badges record the input
  and output arities of [47mfn[0m and specify which arguments are
  ``functions'' that may be applied with [47mapply$[0m, which are
  ``expressions'' that may be evaluated with [47m[ev$][0m, and which are
  neither.  The conditions checked are sufficient to allow [47m[apply$][0m
  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 [47mapply$[0m on [47mfn[0m --- or even to evaluate such a call if [47mfn[0m is
  in [47m:[0m[47m[logic][0m mode, as discussed above --- [47mfn[0m will need a [warrant]
  as issued by [47m[defwarrant][0m.  [47mDefbadge[0m does not issue warrants, just
  badges.  [47mDefwarrant[0m can issue both badges and warrants.

  The first condition on [47mfn[0m is that it must be a defined function
  symbol.  Since [47mfn[0m must be defined it may not be a constrained
  function such as one introduced by [47m[defchoose][0m or [47m[encapsulate][0m.
  In addition, [47mfn[0m may not be one of a very few ``blacklisted''
  symbols (see the value of [47m*blacklisted-apply$-fns*[0m) like [47m[sys-call][0m
  (which requires a trust tag) or an [untouchable].  (For technical
  reasons, untouchables are disallowed even if they are on
  [47mtemp-touchable-fns[0m; see [47m[remove-untouchable][0m.)

  The other conditions depend on whether [47m[apply$][0m is reachable from [47mfn[0m.
  That is, can a call of [47mfn[0m lead to a call of [47mapply$[0m?  If [47mapply$[0m is
  not reachable from [47mfn[0m, then there are no more conditions on [47mfn[0m.  A
  badge for [47mfn[0m is computed and stored.  We are more precise about
  ``reachability'' later.

  If [47mapply$[0m is reachable from [47mfn[0m, then there are additional conditions
  that must be checked.  First, [47mfn[0m must not have been introduced with
  [47m[mutual-recursion][0m.  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
  [47mfn[0m, except [47mfn[0m itself, must already have a badge.  Finally, [47mfn[0m must
  respect certain conventions regarding its use of [47m[apply$][0m and other
  [scion]s.  The basic idea of this last restriction is to make sure
  that [47mapply$[0m is always called on a ``known'' function symbol or
  [47m[lambda][0m object.  This restriction is enforced by checking the
  following conditions:

  [3m(a)[0m It must be possible for each formal of [47mfn[0m to be assigned one of
  three [ilk]s, [47m:FN[0m, [47m:EXPR[0m, or [47mNIL[0m, as described below.  The basic
  idea is that a formal can be assigned ilk [47m:FN[0m (or ilk [47m:EXPR[0m) iff it
  is sometimes passed into a [47m:FN[0m (or [47m:EXPR[0m) slot in the body of [47mfn[0m
  and is never passed into any other kind of slot.  A formal can be
  be assigned ilk [47mNIL[0m iff it is never passed into a slot of ilk [47m:FN[0m
  or [47m:EXPR[0m, i.e., if it is used exclusively as an ``ordinary''
  object.  We are more precise below.

  [3m(b)[0m Every [47m:FN[0m and [47m:EXPR[0m slot of every function called in the body of
  [47mfn[0m is occupied either by a formal of [47mfn[0m of the same ilk or, in the
  case of calls of functions other than [47mfn[0m, a quoted [tame] function
  symbol or quoted tame (preferably well-formed) [47mLAMBDA[0m object.  (See
  [47m[well-formed-lambda-objectp][0m.)

  This completes the list of restrictions imposed by [47mdefbadge[0m.


Discussion and Examples

  Note that if [47mapply$[0m is not reachable from [47mfn[0m, the restrictions
  imposed on [47mfn[0m are comparatively generous.  Such a [47mfn[0m could be
  badged and warranted despite being defined mutually recursively or
  in terms of unbadged or even unbadgeable functions.  Basically, if
  [47mfn[0m doesn't depend on [47mapply$[0m there is no danger that some argument
  of [47mfn[0m will be treated like a function object or an expression.

  After a successful [47mdefbadge[0m event for [47mfn[0m, the function [47m[badge][0m will
  return the computed badge (when executed in the top-level loop) and
  [47m[apply$][0m will be able to accept the [47mfn[0m as a functional argument.
  Here is an annotated script.  First, carry out these two events,
  defining [47mfoldr[0m as a [47m:program[0m mode function.

    (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)))))

  Note the [47mapply$[0m call in the definition.  We see that [47mfoldr[0m treats its
  middle argument, [47mfn[0m, as a function of arity 2.  We can run [47mfoldr[0m,
  even without assigning a badge to [47mfoldr[0m, as long as we supply a
  badged function symbol of arity 2 as the middle argument.  Since
  the ACL2 primitive [47mcons[0m has a badge and has arity 2, we can use it:

    ACL2 !>(foldr '(a b c) 'cons '(d e f))
    (A B C D E F)

  Since [47mfoldr[0m has arity 3, we can try to apply it to a list of three
  things.

    (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.

  However, we can use [47mdefbadge[0m to compute and store the badge for
  [47mfoldr[0m.  The badge says [47mfoldr[0m has input arity 3, output arity 1, and
  treats its middle argument as a function.  We can recover the badge
  by calling the function [47m[badge][0m.  We can successfully apply [47mfoldr[0m.
  We can even use it in a [47mlambda[0m expression that we pass as the
  middle argument to [47mfoldr[0m.

    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)


The ``Reachability'' Test

  We now clarify the test that we colloquially described above as
  whether [47mapply$[0m is reachable from [47mfn[0m.  The actual test is whether
  [47mapply$-userfn[0m is ancestral in [47mfn[0m.  That is, does [47mfn[0m call
  [47mapply$-userfn[0m, or a function that calls [47mapply$-userfn[0m, or a
  function that calls a function that calls [47mapply$-userfn[0m, etc.

  Since the only system functions that call [47mapply$-userfn[0m are [47mapply$[0m,
  [47mev$[0m, and [warrant]s, and since it is very unusual for a
  user-defined function to call directly [47mapply$-userfn[0m, [47mev$[0m, or
  warrants, we think of this test colloquially as whether [47mapply$[0m is
  ancestral in [47mfn[0m.

  The test and the onerous conditions imposed when [47mapply$[0m is reachable
  is crucial to the soundness of the ACL2 proof theory.  We discuss
  this further in the background material for [47m[apply$][0m, including
  {``Limited Second-Order Functionality in a First-Order Setting'' |
  http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by
  Matt Kaufmann and J Strother Moore and offer a fully fleshed out
  metalevel proof that [47mapply$[0m and all [47m:logic[0m-mode scions can be
  modeled in the comment titled [47mEssay on Admitting a Model for Apply$
  and the Functions that Use It[0m in the ACL2 source file
  [47mapply-raw.lisp[0m.

  But badges are more concerned with syntax (and, for [47m:program[0m mode
  functions, evaluation) than the proof theory.  Even if we convert
  [47mfoldr[0m to [47m:logic[0m mode we cannot prove anything interesting about
  what happens when it is applied with [47mapply$[0m.  We can't even prove
  that [47mfoldr[0m has a badge or what that badge is!

    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 ********

  In order to prove anything nontrivial about [47mfoldr[0m's badge or behavior
  under [47mapply$[0m we need the [47m[warrant][0m for [47mfoldr[0m.  Warrants are issued
  by [47m[defwarrant][0m.  If we execute (defwarrant foldr) and then amend
  the failed [47mthm[0m commands above by adding [47m(warrant foldr)[0m as a
  hypothesis, both amended formulas are provable.


How Ilks Are Assigned

  If a formal variable (or its slot among the actuals) has an ilk of
  [47m:FN[0m then the variable is ``used as a function'' in the sense that
  it might eventually reach the first argument of a call of [47mapply$[0m
  and is never passed into an ``ordinary'' slot like those for [47mcons[0m.
  Similarly, an ilk of [47m:EXPR[0m means the variable is ``used as an
  expression'' and may eventually reach the first argument of [47mev$[0m.
  An ilk of [47mNIL[0m means the variable is never used as a function or an
  expression.  The correctness of this algorithm is crucial to the
  safe evaluation of [47mapply$[0m on user-defined function symbols.  It
  also is crucial to the termination argument justifying the
  consistency of the proof theory created if and when [47mfn[0m is
  warranted.

  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 [47m:FN[0m is [47mapply$[0m
  and the only function with a slot of ilk [47m:EXPR[0m is [47mev$[0m.  In both
  functions it is the first argument slot that is so distinguished.
  All other ACL2 primitives that use [47mapply$[0m or [47mev$[0m, e.g., [47mcollect$[0m,
  are defined, admissible, badged, and warranted under the same
  conditions user-defined functions are.

  Let [3mv [0m be the [3mi [0mth formal parameter of a defined function [3mfn[0m.  Then
  the ilk of [3mv [0m is [47m:FN[0m iff the value of [3mv [0m eventually makes its way
  into the first argument of [47mapply$[0m, either in the definition of [47mfn[0m
  or in some function ancestral to (i.e., eventually called by) [47mfn[0m.
  Another way to say this is that there is an occurrence of [3mv [0m in a
  slot of ilk [47m:FN[0m.  Furthermore, [3mv [0m is never used any other way:
  every place [3mv [0m occurs in the body of [3mfn [0m is in a slot of ilk [47m:FN[0m.
  And finally, in every recursive call of [3mfn [0m, [3mv [0m is passed
  identically in the [3mi [0mth argument position of the call.  We say such
  a [3mv [0m is ``used (exclusively) as a function.''

  The [3mi [0mth formal variable [3mv [0m has ilk [47m:EXPR[0m under analogous conditions
  except that instead of eventually getting into the first argument
  of [47mapply$[0m it eventually gets into the first argument of [47mev$[0m.  We
  say such a [3mv [0m is ``used (exclusively) as an expression.'' Note:
  [47m[ev$][0m is the natural notion of expression evaluation in this
  context: look up the values of variables in the alist argument to
  [47mev$[0m, return quoted constants, and otherwise [47mapply$[0m function symbols
  and [47mLAMBDA[0m objects to the recursively obtained list of values
  returned by evaluating the actuals.  However, [47mev$[0m first checks that
  the expression is [47m[tamep][0m.

  The [3mi [0mth formal variable [3mv [0m has ilk [47mNIL[0m if it never occurs in a [47m:FN[0m
  slot and never occurs in an [47m:EXPR[0m slot.  We say such a [3mv [0m is ``used
  (exclusively) as an ordinary object.''")
 (DEFCHOOSE
  (EVENTS)
  "Define a Skolem (witnessing) function

    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),

  where [47mfn[0m is the symbol you wish to define and is a new symbolic name
  (see [name]), [47m(bound-var1 ... bound-varn)[0m is a list of distinct
  `bound' variables (see below), [47m(free-var1 ... free-vark)[0m is the
  list of formal parameters of [47mfn[0m and is disjoint from the bound
  variables, and [47mbody[0m is a term.  The use of [47mlambda-list[0m keywords
  (such as [47m&optional[0m) is not allowed.  The [47m:strengthen[0m keyword
  argument is optional; if supplied, it must be [47mt[0m or [47mnil[0m.

  The system treats [47mfn[0m very much as though it were declared in the
  [signature] of an [47m[encapsulate][0m event, with a single axiom exported
  as described below.  If you supply a [47m:use[0m hint (see [hints]), [47m:use
  fn[0m, it will refer to that axiom.  No rule (of class [47m:[0m[47m[rewrite][0m or
  otherwise; see [rule-classes]) is created for [47mfn[0m.

  [47mDefchoose[0m is only executed in [defun-mode] [47m:[0m[47m[logic][0m; see
  [defun-mode].  Also see [defun-sk].

  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 [47m:strengthen[0m is [47mnil[0m, which is the default.  We
  deal with the case [47m:strengthen t[0m at the end.

  The effect of the form

    (defchoose fn bound-var (free-var1 ... free-vark)
      body)

  is to introduce a new function symbol, [47mfn[0m, with formal parameters
  [47m(free-var1 ... free-vark)[0m.  Now consider the following axiom, which
  states that [47mfn[0m picks a value of [47mbound-var[0m so that the body will be
  true, if such a value exists:

    (1)   (implies body
                   (let ((bound-var (fn free-var1 ... free-vark)))
                     body))

  This axiom is ``clearly conservative'' under the conditions expressed
  above: the function [47mfn[0m simply picks out a ``witnessing'' value of
  [47mbound-var[0m if there is one.  For a rigorous statement and proof of
  this conservativity claim, see [conservativity-of-defchoose].

  Next consider the case that there is more than one bound variable,
  i.e., there is more than one bound-var in the following.

    (defchoose fn
               (bound-var1 ... bound-varn)
               (free-var1 ... free-vark)
               body)

  Then [47mfn[0m returns a multiple value with [47mn[0m components, and formula (1)
  above is expressed using [47m[mv-let][0m as follows:

    (implies body
             (mv-let (bound-var1 ... bound-varn)
                     (fn free-var1 ... free-vark)
                     body))

  We now discuss the case that [47m:strengthen t[0m is supplied.  For
  simplicity we return to our simplest case, with [47mdefchoose[0m applied
  to function [47mfn[0m, a single free variable [47my[0m, and a single bound
  variable [47mbound-var[0m.  The idea is that if we pick the ``smallest''
  witnessing [47mbound-var[0m for two different free variables [47my[0m and [47my1[0m,
  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 [47mdefchoose-constraint-extra[0m for more details.)  Below,
  [47mbody1[0m is the result of replacing [47my[0m by [47my1[0m in [47mbody[0m.

    (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))))

  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.

    (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))))))

  If there is more than one bound variable, then (2) is modified in
  complete analogy to (1) to use [47m[mv-let][0m in place of [47m[let][0m.

  Comment for logicians: As we point out in the documentation for
  [47m[defun-sk][0m, [47mdefchoose[0m is ``appropriate,'' by which we mean that it
  is conservative, even in the presence of [47mepsilon-0[0m induction.  For
  a proof, See [conservativity-of-defchoose].


Subtopics

  [Conservativity-of-defchoose]
      Proof of conservativity of [47m[defchoose][0m")
 (DEFCONG
  (EVENTS)
  "Prove [congruence] rule

  [47mDefcong[0m is used to prove that one [equivalence] relation preserves
  another in a given argument position of a given function.

    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))

  See [congruence] and also see [equivalence].

    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)

  where [47mequiv1[0m and [47mequiv2[0m are known [equivalence] relations; [47mterm[0m is a
  call of a function [47mfn[0m, other than [47mif[0m, on the correct number of
  distinct variable arguments, [47m(fn x1 ... xn)[0m; [47mk[0m is a positive
  integer less than or equal to the arity of [47mfn[0m; [47mpackage[0m, if
  supplied, is one of [47m:current[0m, [47m:equiv1[0m, [47m:equiv2[0m, [47m:function[0m or
  [47m:legacy[0m; [47mevent-name[0m, if supplied, is a symbol; and other arguments
  are as specified in the documentation for [47m[defthm][0m.  The [47mdefcong[0m
  macro expands into a call of [47m[defthm][0m.  The name of the [47m[defthm][0m
  event is [47mequiv1-implies-equiv2-fn-k[0m, unless an [47m:event-name[0m keyword
  argument is supplied, in which case [47mevent-name[0m is used.  The
  package of symbols generated, such as variables and [47m[defthm][0m names,
  is determined by the [47mpackage[0m argument: if it is not supplied or its
  value is [47m:current[0m, then the [47m[current-package][0m is used; if its value
  is [47m:equiv1[0m or [47m:legacy[0m, then the package of [47m:equiv1[0m is used; if its
  value is [47m:equiv2[0m, then the package of [47m:equiv2[0m is used; and if its
  value is [47m:function[0m, then the package of [47mfn[0m is used.  The term of
  the theorem is

    (implies (equiv1 xk yk)
             (equiv2 (fn x1... xk ...xn)
                     (fn x1... yk ...xn))).

  The rule-class [47m:[0m[47m[congruence][0m is added to the [47m[rule-classes][0m
  specified, if it is not already there.  All other arguments to the
  generated [47m[defthm][0m form are as specified by the keyword arguments
  above.

  NOTE: In normal usage, [47mdefcong[0m can only create classic [congruence]
  rules, not [patterned-congruence] rules.  However, if [47mfn[0m is a
  macro, it's possible for a patterned congruence rule to be
  generated, depending on what [47mterm[0m expands to.

  For example, the following produces a shallow patterned congruence
  rule:

    (defun f (x y) (and x y))
    (defmacro g (x) `(f ,x t))
    (defcong iff equal (g x) 1)"
)
 (DEFCONST (EVENTS PROGRAMMING)
  "Define a constant

    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)

  where [47mname[0m is a symbol beginning and ending with the character [47m*[0m and
  [47mterm[0m is a variable-free term that is evaluated to determine the
  value of the constant.

  There are two restrictions on [47mterm[0m aside from it being variable-free.
  Both restrictions relate to ancestral uses of [47m[apply$][0m in [47mterm[0m,
  i.e., uses of [47mapply$[0m by [47mterm[0m or any function that might be called
  during the evaluation of [47mterm[0m.  First, only badged primitive
  functions may be applied.  See [badge] for a way to obtain the
  complete list of badged primitives.  Second, [47mloop$[0m and [47mlambda$[0m may
  not be used anywhere in the ancestry of term.  See
  [47mignored-attachment[0m and [47mprohibition-of-loop$-and-lambda$[0m for more
  discussion.

  When a constant symbol is used as a [term], ACL2 replaces it by its
  value; see [term].

  Note that [47mdefconst[0m uses so-called [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 [defconsts] instead.  Also see
  [using-tables-efficiently] for an analogous issue with [47m[table][0m
  events.

  It may be of interest to note that [47mdefconst[0m is implemented at the
  lisp level using [47mdefparameter[0m, as opposed to [47mdefconstant[0m.
  (Implementation note: this is important for proper support of
  undoing and redefinition.)

  We close with a technical remark, perhaps of interest only who make
  use of the [hons-enabled] features of ACL2.  For an event of the
  form [47m(defconst *C* (quote OBJ))[0m, i.e., [47m(defconst *C* 'OBJ)[0m, then
  the value associated with [47m*C*[0m is [47mOBJ[0m; that is, the value of [47m*C*[0m is
  [47m[eq][0m to the actual object [47mOBJ[0m occurring in the [47mdefconst[0m form.  So
  for example, if [47m[make-event][0m is used to generate such a [47mdefconst[0m
  event, as it is in the two books mentioned above, and [47mOBJ[0m is a fast
  alist (see [fast-alists]), then the value of [47m*C*[0m is a fast alist.
  This guarantee disappears if the term in the [47mdefconst[0m form is not a
  quoted object, i.e., if it is not of the form [47m(quote OBJ)[0m.


Subtopics

  [Ignored-attachment]
      Why attachments are sometimes not used

  [Prohibition-of-loop$-and-lambda$]
      Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms

  [Sharp-dot-reader]
      Read-time evaluation of constants")
 (DEFEQUIV
  (EVENTS)
  "Prove that a function is an [equivalence] relation

    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))

  See [equivalence].

    General Form:
    (defequiv equiv
      :package package
      :event-name event-name
      :rule-classes rule-classes
      :instructions instructions
      :hints hints
      :otf-flg otf-flg)

  where [47mequiv[0m is a function symbol of arity 2; [47mpackage[0m, if supplied, is
  one of [47m:current[0m, [47m:equiv[0m or [47m:legacy[0m; [47mevent-name[0m, if supplied, is a
  symbol; and all other arguments are as specified in the
  documentation for [47m[defthm][0m.  The [47mdefequiv[0m macro expands into a call
  of [47m[defthm][0m.  The name of the [47m[defthm][0m is [47mequiv-is-an-equivalence[0m,
  unless an [47m:event-name[0m keyword argument is supplied, in which case
  [47mevent-name[0m is used.  The package of symbols generated, such as
  variables and [47m[defthm][0m names, is determined by the [47mpackage[0m
  argument: if it is not supplied or its value is [47m:current[0m, then the
  [47m[current-package][0m is used; if its value is [47m:equiv[0m or [47m:legacy[0m (which
  are treated identically), then the package of [47m:equiv[0m is used.  All
  other arguments to the generated [47m[defthm][0m form are as specified by
  the other keyword arguments above.  The rule-class [47m:[0m[47m[equivalence][0m
  is added to the [rule-classes] specified, if it is not already
  there.  The term generated for the [47m[defthm][0m event states that [47mequiv[0m
  is Boolean, reflexive, symmetric, and transitive.")
 (DEFEVALUATOR
  (EVENTS)
  "Introduce an evaluator function

    Example:
    (defevaluator evl evl-list
      ((length x) (member-equal x y)))

  See [meta].

    General Form:
    (defevaluator ev ev-list
       ((g1 x1 ... xn_1)
        ...
        (gk x1 ... xn_k))
       :namedp flg)       ; [optional keyword argument]

  where [47mev[0m and [47mev-list[0m are new function symbols and [47mg1[0m, ..., [47mgk[0m are old
  function symbols with the indicated number of formals, i.e., each
  [47mgi[0m has [47mn_i[0m formals.  If the [47m:namedp[0m keyword argument is provided,
  its value should be Boolean.  If not provided, the default value
  for [47mflg[0m is [47mnil[0m.

  This function provides a convenient way to constrain [47mev[0m and [47mev-list[0m
  to be mutually-recursive evaluator functions for the symbols [47mg1[0m,
  ..., [47mgk[0m.  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 [meta] for a discussion of metafunctions.

  If the [47m:namedp[0m [47mflg[0m is [47mnil[0m (the default) constraints have names of the
  form [3mev[0m[47m-CONSTRAINT-[0m[3mi[0m, e.g., [47mEV-CONSTRAINT-0[0m, [47mEV-CONSTRAINT-1[0m, etc.
  If [47mflg[0m is non-[47mnil[0m, the constraints are named more mnemonically,
  e.g., [47mEV-OF-VARIABLE[0m, [47mEV-OF-REVAPPEND-CALL[0m, etc.  We illustrate the
  [47m:namedp t[0m names below.

  [47mDefevaluator[0m executes an [47m[encapsulate][0m after generating the
  appropriate [47m[defun][0m and [47m[defthm][0m events.  Perhaps the easiest way
  to understand what [47mdefevaluator[0m does is to execute the keyword
  command

    :trans1 (defevaluator evl evl-list ((length x) (member-equal x y)))

  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 [47m:[0m[47m[trans1][0m can be edited by adding hints, then submitted
  directly.

  Formally, [47mev[0m is said to be an ``evaluator function for [47mg1[0m, ..., [47mgk[0m,
  with mutually-recursive counterpart [47mev-list[0m'' iff [47mev[0m and [47mev-list[0m
  are constrained functions satisfying just the [constraint]s
  discussed below.

  [47mEv[0m and [47mev-list[0m must satisfy [constraint]s (0)-(7) and (k) below.
  When [47m:namedp nil[0m is supplied, the [3mi[0m in the generated constraint
  names are the parenthesized numbers below.  When [47m:namedp t[0m is
  supplied, the mnemonic names are those shown in brackets below.

    (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).

  [47mDefevaluator[0m defines suitable witnesses for [47mev[0m and [47mev-list[0m, proves
  the theorems about them, and constrains [47mev[0m and [47mev-list[0m
  appropriately.  We expect [47mdefevaluator[0m 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 [47m*defevaluator-form-base-theory*[0m.

  (Aside: (3) above may seem surprising, since the bindings of [47ma[0m are
  not included in the environment that is used to evaluate the lambda
  body, [47m(caddar x)[0m.  However, ACL2 lambda expressions are all [3mclosed[0m:
  in [47m(lambda (v1 ... vn) body)[0m, the only free variables in [47mbody[0m are
  among the [47mvi[0m.  See [term].)

  Acknowledgment: We thank Sol Swords and Jared Davis for their
  community book [47mtools/defevaluator-fast.lisp[0m, which provided the
  model on which the current [47mdefevaluator[0m is based.  The original
  [47mdefevaluator[0m was very inefficient, e.g., taking thousands of times
  longer than the current one on an evaluator interpreting 800
  function symbols.  We refactored their [47mdefevaluator-fast[0m (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 [47m:namedp[0m.")
 (DEFEXEC
  (EVENTS MBE)
  "Attach a terminating executable function to a definition

  Suppose you define a function [47m(fn x)[0m with a [guard] of [47m(good-input-p
  x)[0m, and you know that when the guard holds, the measure decreases
  on each recursive call.  Unfortunately, the definitional principle
  (see [defun]) ignores the guard.  For example, if the definition
  has the form

    (defun fn (x)
      (declare (xargs :guard (good-input-p x)))
      (if (not-done-yet x)
          (... (fn (destr x)) ...)
        ...))

  then in order to admit this definition, ACL2 must prove the
  appropriate formula asserting that [47m(destr x)[0m is ``smaller than'' [47mx[0m
  under the assumption [47m(not-done-yet x)[0m but without the assumption
  [47m(good-input-p x)[0m, even if [47m(not-done-yet x)[0m is true.  In essence, it
  may be necessary to submit instead the following definition.

    (defun fn (x)
      (declare (xargs :guard (good-input-p x)))
      (if (good-input-p x)
          (if (not-done-yet x)
              (... (fn (destr x)) ...)
            ...)
        nil)

  But it is unfortunate that when calls of [47mfn[0m are evaluated, for
  example when [47mfn[0m is applied to an explicit constant during a proof,
  then a call of [47mgood-input-p[0m must now be evaluated on each recursive
  call.

  Fortunately, [47mdefexec[0m provides a way to keep the execution efficient.
  For the example above we could use the following form.

    (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)) ...)
                    ...)))

  Here ``[47m[mbe][0m'' stands for ``must be equal'' and, roughly speaking,
  its call above is logically equal to the [47m:logic[0m form but is
  evaluated using the [47m:exec[0m form when the guard holds.  See [mbe].
  The effect is thus to define [47mfn[0m as shown in the [47m[defun][0m form above,
  but to cause execution of [47mfn[0m using the [47m:exec[0m body.  The use of
  [47mdefexec[0m instead of [47m[defun][0m in the example above causes a
  termination proof to be performed, in order to guarantee that
  evaluation always theoretically terminates, even when using the
  [47m:exec[0m form for evaluation.

    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))))))

  The above example macroexpands to the following.

    (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)))))))

  Notice that in the example above, the [47m:[0m[47m[hints][0m in the [47m[local][0m
  definition of [47mF[0m are inherited from the [47m:hints[0m in the [47m[xargs][0m of the
  [47mdefexec[0m form.  We discuss such inheritance below.

  CAVEAT: Termination is not considered for calls of [47m[mbe][0m under the
  top-level call.  Moreover, the [47m:exec[0m part of an [47m[mbe][0m call under
  the [47m:logic[0m part of any superior [47mmbe[0m call is completely ignored.

    General Form:
    (defexec fn (var1 ... varn)
      dcl ... dcl ; optionally, also one documentation string, as for defun
      (mbe :LOGIC logic-body
           :EXEC  exec-body))

  where the syntax is identical to the syntax of [47m[defun][0m where the body
  is a call of [47mmbe[0m, with the exceptions described below.  Thus, [47mfn[0m is
  the symbol you wish to define and is a new symbolic name and [47m(var1
  ... varn)[0m is its list of formal parameters (see [name]).  The first
  exception is that at least one [47mdcl[0m (i.e., [47m[declare][0m form) must
  specify a [47m:guard[0m, [47mguard[0m.  The second exception is that one of the
  [47mdcl[0ms is allowed to contain an element of the form [47m(exec-xargs ...)[0m.
  The [47mexec-xargs[0m form, if present, must specify a non-empty
  [47m[keyword-value-listp][0m each of whose keys is one of [47m:test[0m,
  [47m:default-value[0m, or one of the standard [47m[xargs][0m keys of [47m:measure[0m,
  [47m:ruler-extenders[0m, [47m:well-founded-relation[0m, [47m:hints[0m [47m:stobjs[0m, or [47m:dfs[0m.
  Any of these standard [47mxargs[0m keys that is present in an [47mxargs[0m of
  some [47mdcl[0m but is not specified in the (possibly nonexistent)
  [47mexec-xargs[0m form is considered to be specified in the [47mexec-xargs[0m
  form, as illustrated in the example above for [47m:hints[0m.  (So for
  example, if you want [47m:hints[0m in the final, non-local definition but
  not in the local definition, then specify the [47m:hints[0m in the [47mxargs[0m
  but specify [47m:hints nil[0m in the [47mexec-xargs[0m.)  If [47m:test[0m is specified
  and not [47mnil[0m, let [47mtest[0m be its value; otherwise let [47mtest[0m default to
  [47mguard[0m.  If [47m:default-value[0m is specified, let [47mdefault-value[0m be its
  value; else [47mdefault-value[0m is [47mnil[0m.  [47mDefault-value[0m should have the
  same [signature] as [47mexec-body[0m; otherwise the [47mdefexec[0m form will fail
  to be admitted.

  The above General Form's macroexpansion is of the form [47m(PROGN encap
  final-def)[0m, where [47mencap[0m and [47mfinal-def[0m are as follows.  [47mFinal-def[0m is
  simply the result of removing the [47mexec-xargs[0m declaration (if any)
  from its [47m[declare][0m form, and is the result of evaluating the given
  [47mdefexec[0m form, since [47mencap[0m is of the following form.

    ; 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))

  The purpose of [47mencap[0m is to ensure that the executable version of [47mname[0m
  terminates on all arguments.  Thus, [47mlocal-def[0m and [47mlocal-thm[0m are as
  follows, where the [47mxargs[0m of the [47m[declare][0m form are the result of
  adding [47m:VERIFY-GUARDS NIL[0m to the result of removing the [47m:test[0m and
  (optional) [47m:default-value[0m from the [47mexec-xargs[0m.

    ; 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)

  We claim that if the above [47mlocal-def[0m and [47mlocal-thm[0m are admitted, then
  all evaluations of calls of [47mfn[0m terminate.  The concern is that the
  use of [47m[mbe][0m in [47mfinal-def[0m allows for the use of [47mexec-body[0m for a
  call of [47mfn[0m, as well as for subsequent recursive calls, when [47mguard[0m
  holds and assuming that the guards have been verified for
  [47mfinal-def[0m.  However, by [47mlocal-thm[0m we can conclude in this case that
  [47mtest[0m holds, in which case the call of [47mfn[0m may be viewed as a call of
  the version of [47mfn[0m defined in [47mlocal-def[0m.  Moreover, since guards
  have been verified for [47mfinal-def[0m, then guards hold for subsequent
  evaluation of [47mexec-body[0m, and in particular for recursive calls of
  [47mfn[0m, which can thus continue to be viewed as calls using [47mlocal=def[0m.")
 (DEFINDUCTOR
  (LOOP$-RECURSION)
  "Create an induction scheme for a [47mloop$[0m-recursive function

  [47mDefinductor[0m is a utility provided as part of the community book
  [47mprojects/apply/top[0m, which should be included in any session dealing
  with [47m[apply$][0m, [47m[loop$][0m, or [47m[loop$-recursion][0m.  [47m(Definductor fn)[0m
  attempts to create an induction scheme appropriate for the
  previously defined [47mloop$[0m-recursive function [47mfn[0m and prove an
  [47m:[0m[47m[induction][0m rule so that certain calls of [47mfn[0m suggest that
  induction.

  [31;1mWarning:[0m [47mDefinductor[0m currently handles a very small class of
  [47mloop$[0m-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 [47mloop$[0ms and [47mloop$[0m-recursion.

    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)

  where [47mname[0m is the name of a previously admitted [47mloop$[0m-recursive
  function satisfying the restrictions listed below.  When successful
  it defines a function named [47mname-INDUCTOR[0m that suggests an
  induction scheme that is supposedly appropriate for [47mname[0m, admits it
  with a silent proof of its measure theorems, and then proves an
  [47m:[0m[47minduction[0m rule to associate that scheme with calls of [47mname[0m.  When
  omitted, the optional keyword arguments [47mmeasure[0m,
  [47mwell-founded-relation[0m, and [47mruler-extenders[0m default to the measure,
  well-founded relation, and ruler-extender settings used in the
  admittance of [47mname[0m.  The keyword argument [47mhints[0m defaults to [47mnil[0m.
  Note that an appropriate choice of [47mruler-extenders[0m can improve some
  induction schemes.  See [induction-coarse-v-fine-grained].


Restrictions

  The given function, [47mname[0m, must satisfy the following restrictions.
  [31;1mNote:[0m Because we anticipate this utility being further developed in
  the near future this list may not correspond to the latest
  implementation!

    * [47mName[0m must be a symbol naming a previously admitted [47mloop$[0m-recursive
      function.

    * Every recursive [47mloop$[0m in the body of [47mname[0m -- that is, every [47mloop$[0m
      that calls [47mname[0m recursively in the [47mwhen[0m, [47muntil[0m, or [47mbody[0m clauses
      of the [47mloop$[0m -- must have as its target(s) distinct measured
      variables or [47mcdr[0m-nests around such variables.

    * Every recursive [47mloop$[0m must use [47mIN[0m-iteration, not [47mON[0m- or
      [47mFROM/TO/BY[0m-iteration.

  While [47mdefinductor[0m can handle [47mloop$[0m containing multiple [47mAS[0m clauses
  (with targets as described above), it cannot handle [47mloop$[0m such as

    (loop$ for v in (target x) ...)
    (loop$ for v on x ...)
    (loop$ for i from 1 to max ...)

  To see the inductor function generated, type [47m:pe name-INDUCTOR[0m.  To
  see examples of the use of [47mdefinductor[0m inspect the book
  [47mprojects/apply/definductor-tests.lisp[0m.  To see the definition of
  [47mdefinductor[0m, see [47mprojects/apply/definductor.lisp[0m.

  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
  [47mdefun[0m in the event of failure to admit it, and trying to expand the
  class of [47mloop$[0m-recursive functions that can be successfully
  handled.  We have not yet even looked at inductions for [47mON[0m [47mloop$[0ms
  and [47mFROM/TO/BY[0m [47mloop$[0ms, so that might be easy.  Induction for [47mloop$[0ms
  over arbitrary target expressions may be infeasible!  We just need
  more examples of [47mloop$[0m-recursive functions and successful
  (hand-written) induction hints for them.")
 (DEFINE-PC-HELP
  (PROOF-BUILDER)
  "Define a macro command whose purpose is to print something

    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)

  This defines a macro command named [47mname[0m, as explained further below.
  The [47mbody[0m should (after removing optional declarations) be a form
  that returns [47mstate[0m as its single value.  Typically, it will just
  print something.

  What [47m(define-pc-help name args &rest body)[0m really does is to create a
  call of [47mdefine-pc-macro[0m that defines [47mname[0m to take arguments [47margs[0m,
  to have the declarations indicated by all but the last form in
  [47mbody[0m, and to have a body that (via [47mpprogn[0m) first executes the form
  in the last element of body and then returns a call to the command
  [47mskip[0m (which will return [47m(mv nil t state)[0m).")
 (DEFINE-PC-MACRO
  (PROOF-BUILDER)
  "Define a proof-builder macro command

  A call of [47mdefine-pc-macro[0m defines a sort of macro, which is a tactic
  that generates [proof-builder] instructions.  This topic contains
  basic information about how to use this utility.  For somewhat
  sophisticated, but commented, examples, see the [community-book]
  [47mbooks/kestrel/utilities/proof-builder-macros.lisp[0m and associated
  tests in the same directory, [47mproof-builder-macros-tests.lisp[0m.

  We begin with the following example.

    (define-pc-macro ib (&optional term)
      (value
       (if term
           `(then (induct ,term) bash)
         `(then induct bash))))

  The example above captures a common paradigm: one attempts to prove
  the current goal by inducting and then simplifying the resulting
  goals.  (See [proof-builder-commands] for documentation of the
  command [47mthen[0m, which is itself a pc-macro command, and commands
  [47minduct[0m and [47mbash[0m.)  Rather than issuing [47m(then induct bash)[0m, or worse
  yet issuing [47minduct[0m and then issuing [47mbash[0m for each resulting goal,
  the above definition of [47mib[0m would let you issue [47mib[0m and get the same
  effect.

    General Form:
    (define-pc-macro cmd args dcl ... dcl body)

  where [47mcmd[0m is the name of the pc-macro that you want to define, [47margs[0m
  is its list of formal parameters.  [47mArgs[0m may include lambda-list
  keywords [47m&optional[0m and [47m&rest[0m; see [macro-args], but note that here,
  [47margs[0m may not include [47m&key[0m or [47m&whole[0m.

  The value of [47mbody[0m should be an [error-triple], of the form [47m(mv erp
  xxx state)[0m for some [47merp[0m and [47mxxx[0m.  If [47merp[0m is [47mnil[0m, then [47mxxx[0m is handed
  off to the interactive proof-builder's instruction interpreter.
  Otherwise, evaluation typically halts.")
 (DEFINE-PC-META
  (PROOF-BUILDER)
  "Define a proof-builder meta command

  Built-in meta commands of the interactive [proof-builder] include
  [47mundo[0m and [47mrestore[0m, and others ([47mlisp[0m, [47mexit[0m, and [47msequence[0m); see
  [proof-builder-commands].  The advanced proof-builder user can
  define these as well.  See ACL2 source file [47mproof-builder-b.lisp[0m
  for examples, and contact the ACL2 implementors if those examples
  do not provide sufficient documentation.")
 (DEFINE-TRUSTED-CLAUSE-PROCESSOR
  (EVENTS)
  "Define a trusted (unverified) goal-level simplifier

  This [documentation] assumes familiarity with [47m:clause-processor[0m
  rules; see [clause-processor].  Briefly put, a [3mclause-processor[0m is
  a user-defined function that takes as input the ACL2 representation
  of a goal --- a [clause] --- and returns a list of goals (i.e., a
  list of clauses).  A [47m:clause-processor[0m rule is a way to inform ACL2
  that a clause-processor has been proved correct and now may be
  specified in [47m:clause-processor[0m [hints].

  Here we describe a utility, [47mdefine-trusted-clause-processor[0m, that
  provides another way to inform ACL2 that a function is to be
  considered a clause-processor that can be specified in a
  [47m:clause-processor[0m hint.  You can find examples of correct and
  incorrect use of this utility in community book
  [47mbooks/clause-processors/basic-examples[0m.

  Consider the simple example already presented for [47m:clause-processor[0m
  rules (again, see [clause-processor]), for a simple
  clause-processor named [47mnote-fact-clause-processor[0m.  Instead of
  introducing an evaluator and proving a correctness theorem with
  [47m:rule-classes :clause-processor[0m, we can simply inform ACL2 that we
  trust the function [47mnote-fact-clause-processor[0m to serve as a
  clause-processor.

    (define-trusted-clause-processor
      note-fact-clause-processor
      nil
      :ttag my-ttag)

  A non-nil [47m:ttag[0m argument generates a [47m[defttag][0m 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
  [47m[defttag][0m event will be [local] to the
  [47mdefine-trusted-clause-processor[0m event; that is, its effect will
  disappear after the [47mdefine-trusted-clause-processor[0m event
  completes.  This point becomes clear if one understands that a call
  of [47mdefine-trusted-clause-processor[0m expands to a call of
  [47m[encapsulate][0m, and a [47m[defttag][0m event is essentially [local] within
  any [47m[encapsulate][0m event, as is any event that sets the
  [47m[ACL2-defaults-table][0m.  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.

  Now that the event displayed above has established
  [47mnote-fact-clause-processor[0m as a (trusted) clause-processor, we can
  use it in a [47m:clause-processor[0m hint, for example as follows.  Notice
  that the output is identical to that for the corresponding example
  presented for the verified case (see [clause-processor]), except
  that the word ``verified'' has been replaced by the word
  ``trusted''.

    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 !>

  Indeed, if one runs this example first and subsequently verifies the
  clause-processor, one will see the word ``trusted'' change to
  ``verified''.

  The general form is as follows.

    (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
      )

  We discussed the [47m:ttag[0m argument above, and we will discuss the
  [47msupporters[0m and [47m:partial-theory[0m arguments later below.  Let us turn
  our attention to the [47mlabel[0m argument and its ramifications for
  undoing and redundancy.

  As mentioned above, a successful [47mdefine-trusted-clause-processor[0m
  event results in an [47m[encapsulate][0m event.  If the [47m:label[0m argument is
  supplied with a non-[47mnil[0m value [47mL[0m, or if [47m:label[0m is omitted and [47mL[0m is
  the result of adding the suffix [47m\"$LABEL\"[0m to [47mcl-proc[0m, then the event
  [47m(deflabel L)[0m will be included under the resulting [47mencapsulate[0m form.
  Thus, you will be able to undo this [47mdefine-trusted-clause-processor[0m
  with [47m:[0m[47m[ubt][0m[47m L[0m.  Also, because of the criteria for redundant
  encapsulate events (see [redundant-encapsulate]), the entire form
  is considered redundant (skipped) if it is identical to one already
  executed in the current ACL2 [world], with one exception: if
  [47m:partial-theory[0m is [47mnil[0m or omitted, and also [47m:label nil[0m is supplied
  explicitly, then the event will not be redundant.  If the event is
  not redundant, then [47mcl-proc[0m must not already be designated as a
  trusted clause-processor.

  Note that [47mcl-proc[0m may be defined either in [47m:program[0m-mode or
  [47m:logic[0m-mode.

  The [47msupporters[0m 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, [47m[local][0m 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 [clause-processor] documentation topic.  Below we
  discuss an additional reason that [47msupporters[0m is critical for
  soundness, in the case of dependent clause-processors.

  (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
  [47msupporters[0m argument serves both purposes.)

  [31;1mDependent clause-processors and promised encapsulates[0m: The
  [47m:partial-theory[0m argument

  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 [47m[sys-call][0m to implement a
  [47m:[0m[47m[program][0m-mode function in ACL2 that can invoke that simulator.
  (This has been changed to [47m[sys-call*][0m since [47msys-call[0m cannot invoke
  the OS during proofs; 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 [47m:partial-theory[0m argument provides a
  way to write merely some of the [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''
  [47mencapsulate[0m, for example by exporting the full definition.

  If a trusted clause-processor is introduced with a non-[47mnil[0m
  [47m:partial-theory[0m argument, we call it a ``dependent''
  clause-processor, because its correctness is dependent on the
  constraints implicitly introduced by the [47m:partial-theory[0m
  [47mencapsulate[0m form.  The implicit constraints should logically imply
  the constraints actually introduced by the explicit [47mencapsulate[0m,
  but they should also be sufficient to justify every possible
  invocation of the clause-processor in a [47m:clause-processor[0m hint.
  The user of a [47mdefine-trusted-clause-processor[0m form is making a
  guarantee --- or, is relying on a guarantee provided by the writer
  of that form --- that in principle, there exists a so-called
  ``promised encapsulate'': an [47mencapsulate[0m form with the same
  [signature] as the [47m:partial-theory[0m [47mencapsulate[0m form associated with
  the trusted clause-processor, but whose constraints introduced are
  the aforementioned implicit constraints.

  There are several additional requirements on a [47m:partial-theory[0m
  argument.  First, it must be an [47m[encapsulate][0m event with non-empty
  [signature].  Moreover, the functions introduced by that event must
  be exactly those specified in the signature, and no more.  And
  further still, the [47mdefine-trusted-clause-processor[0m form cannot be
  executed inside any [47m[encapsulate][0m form with non-empty [signature];
  we can think of this situation as attempting to associate more than
  one [47mencapsulate[0m with the functions introduced in the inner
  [47mencapsulate[0m.

  Moreover, soundness depends on inclusion of enough function symbols
  in the [47msupporters[0m argument, as follows.  Let [47mS[0m be the set of
  specified [47msupporters[0m augmented by the set of function symbols
  either introduced by, or in a property exported by, the
  [47m:partial-theory[0m argument, which we call the ``promised
  encapsulate''.  Then every function symbol constrained by the
  promised encapsulate is in [47mS[0m.

  The [47m:partial-theory[0m event will (in essence) be executed as part of
  the evaluation of the [47mdefine-trusted-clause-processor[0m form.  Again,
  a critical obligation rests on the user who provides a
  [47m:partial-theory[0m: there must exist (in principle at least) a
  corresponding promised encapsulate form with the same [signature]
  that could logically be admitted, whenever the above
  [47mdefine-trusted-clause-processor[0m form is evaluated successfully,
  that justifies the designation of [47mcl-proc[0m as a clause-processor.
  See also the paper mentioned above for more about promised
  encapsulates.  A key consequence is that the [constraint]s are
  unknown for the functions introduced in (the signature of) a
  [47m:partial-theory[0m [47m[encapsulate][0m form.  Thus, functional instantiation
  (see [functional-instantiation-example]) is disabled for function
  in the signature of a [47m:partial-theory[0m form.

  [31;1mA remark on the underlying implementation[0m

  You can see all of the current trusted clause-processors by issuing
  the command [47m(table trusted-cl-proc-table)[0m.  The resulting alist
  associates each trusted clause-processor with its supporters.

  Note that [47mdefine-trusted-clause-processor[0m is actually a macro that
  generates (among other things) a [47mtable[0m event for extending
  [47mtrusted-cl-proc-table[0m.  You are invited to use [47m:[0m[47m[trans1][0m to see
  expansions of calls of this macro.  In particular, you can see that
  the [47m:partial-theory[0m argument results in an [47mencapsulate[0m event that
  includes a call of the form [47m(set-unknown-constraints-supporters f1
  ... fk)[0m, which in effect makes that call of [47mencapsulate[0m into a call
  of [47mpartial-encapsulate[0m with supporters [47m(f1 ... fk)[0m.  See
  [partial-encapsulate].

  [31;1mA technique for using raw Lisp to define a trusted clause-processor[0m

  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 [47macl2-my-prove below[0m, 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 [47mnil[0m using a
  [47m:functional-instance[0m [47m:use[0m 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 [47mhint-to-termlist[0m or [47mdisjoin-clause-segments-to-clause[0m,
  which this example assumes are defined elsewhere; their meanings
  are not important for this example.

    (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)
      )")
 (DEFINED-CONSTANT (POINTERS)
                   "See [system-utilities].")
 (DEFINITION
  (RULE-CLASSES)
  "Make a rule that acts like a function definition

  See [rule-classes] for a general discussion of rule classes and how
  they are used to build rules from formulas.  An example
  [47m:[0m[47m[corollary][0m formula from which a [47m:definition[0m rule might be built
  is:

    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))

  where [47mequiv[0m is an equivalence relation and [47mfn[0m is a function symbol
  other than [47m[if][0m, [47m[hide][0m, [47m[force][0m or [47m[case-split][0m.  Such rules allow
  ``alternative'' definitions of [47mfn[0m 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''.

  Consider the general form above.  Generalized definitions are stored
  much as [47m:[0m[47m[rewrite][0m rules for the function ``defined,'' [47mfn[0m above,
  but the procedure for applying them is a little different.  During
  rewriting, instances of [47m(fn a1 ... an)[0m are replaced by
  corresponding instances of [47mbody[0m provided the [47mhyp[0ms can be
  established, as for a [47m:[0m[47m[rewrite][0m rule; but when applying a
  [47m:definition[0m rule, the result of rewriting [47mbody[0m 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 [47mfn[0m in the rewritten body have arguments that
  already occur in the goal conjecture.  The second is that the
  ``controlling'' arguments to [47mfn[0m are simpler in the rewritten body.

  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.

  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 [47m:clique[0m and [47m:controller-alist[0m fields of the [47m:definition[0m rule
  class.

  The [47m:clique[0m field is the list of function symbols to be considered
  recursive calls of [47mfn[0m.  In the case of a non-recursive definition,
  the [47m:clique[0m field is empty; in a singly recursive definition, it
  should consist of the singleton list containing [47mfn[0m; otherwise it
  should be a list of all of the functions in the mutually recursive
  clique with this definition of [47mfn[0m.

  If the [47m:clique[0m field is not provided it defaults to [47mnil[0m if [47mfn[0m does
  not occur as a function symbol in [47mbody[0m and it defaults to the
  singleton list containing [47mfn[0m otherwise.  Thus, [47m:clique[0m 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.

  The [47m:controller-alist[0m is an alist that maps each function symbol in
  the [47m:clique[0m to a mask specifying which arguments are considered
  controllers.  The mask for a given member of the clique, [47mfn[0m, must
  be a list of [47mt[0m's and [47mnil[0m's of length equal to the arity of [47mfn[0m.  A [47mt[0m
  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.

  If the [47m:controller-alist[0m is omitted it can sometimes be defaulted
  automatically by the system.  If the [47m:clique[0m is [47mnil[0m, the
  [47m:controller-alist[0m defaults to [47mnil[0m.  If the [47m:clique[0m is a singleton
  containing [47mfn[0m, the [47m:controller-alist[0m defaults to the controller
  alist computed by [47m(defun fn args body)[0m.  (The user can obtain some
  control over this analysis by setting the default ruler-extenders;
  see [rulers].)  If the [47m:clique[0m contains more than one function, the
  user must supply the [47m:controller-alist[0m 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.

  For example, suppose [47mfn1[0m and [47mfn2[0m 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 [47m:definition[0m rule.  These two theorems would exhibit
  equations ``defining'' [47mfn1[0m and [47mfn2[0m 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 [47m:definition[0m rules
  should specify the [47m:clique[0m [47m(fn1 fn2)[0m and should specify a suitable
  [47m:controller-alist[0m.  If, for example, the new definition of [47mfn1[0m is
  controlled by its first argument and the new definition of [47mfn2[0m is
  controlled by its second and third (and they each take three
  arguments) then a suitable [47m:controller-alist[0m would be [47m((fn1 t nil
  nil) (fn2 nil t t))[0m.  The order of the pairs in the alist is
  unimportant, but there must be a pair for each function in the
  clique.

  Inappropriate heuristic advice via [47m:clique[0m and [47m:controller-alist[0m can
  cause ``infinite expansion'' of generalized definitions, but cannot
  render ACL2 unsound.

  Note that the actual definition of [47mfn1[0m has the runic name
  [47m(:definition fn1)[0m.  The runic name of the alternative definition is
  [47m(:definition lemma)[0m, where [47mlemma[0m is the name given to the event
  that created the generalized [47m:definition[0m rule.  This allows
  theories to switch between various ``definitions'' of the
  functions.

  By default, a [47m:definition[0m rule establishes the so-called ``body'' of
  a function.  The body is used by [47m:expand[0m [hints], and it is also
  used heuristically by the theorem prover's preprocessing (the
  initial simplification using ``simple'' rules that is controlled by
  the [47mpreprocess[0m symbol in [47m:do-not[0m [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 [47mexpand[0m, [47mx[0m, and [47mx-dumb[0m
  commands of the interactive [proof-builder].

  See [rule-classes] for a discussion of the optional field
  [47m:install-body[0m of [47m:definition[0m rules, which controls whether a
  [47m:definition[0m rule is used as described in the paragraph above.  Note
  that even if [47m:install-body nil[0m is supplied, the rewriter will still
  rewrite with the [47m:definition[0m 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
  [47m:expand[0m hints as described in the preceding paragraph.  Also see
  [set-body] and see [show-bodies] for how to change the body of a
  function symbol.

  Note only that if you prove a definition rule for function [47mfoo[0m, say,
  [47mfoo-new-def[0m, you will need to refer to that definition as
  [47mfoo-new-def[0m or as [47m(:DEFINITION foo-new-def)[0m.  That is because a
  [47m:definition[0m rule does not change the meaning of the symbol [47mfoo[0m for
  [47m:use[0m [hints], nor does it change the meaning of the symbol [47mfoo[0m in
  theory expressions; see [theories], in particular the discussion
  there of runic designators.  Similarly [47m:[0m[47m[pe][0m [47mfoo[0m and [47m:[0m[47m[pf][0m [47mfoo[0m will
  still show the original definition of [47mfoo[0m.

  The definitional principle, [47m[defun][0m, actually adds [47m:definition[0m rules.
  Thus the handling of generalized definitions is exactly the same as
  for ``real'' definitions because no distinction is made in the
  implementation.  Suppose [47m(fn x y)[0m is [47m[defun][0m'd to be [47mbody[0m.  Note
  that [47m[defun][0m (or [47m[defuns][0m or [47m[mutual-recursion][0m) can compute the
  clique for [47mfn[0m from the syntactic presentation and it can compute
  the controllers from the termination analysis.  Provided the
  definition is admissible, [47m[defun][0m adds the [47m:definition[0m rule [47m(equal
  (fn x y) body)[0m.


Subtopics

  [Bind-free]
      To bind free variables of a rewrite, definition, or linear rule

  [Case-split]
      Like force but immediately splits the top-level goal on the
      hypothesis

  [Force]
      Identity function used to force a hypothesis

  [Set-body]
      Set the definition body

  [Show-bodies]
      Show the potential definition bodies

  [Simple]
      [47m:[0m[47m[definition][0m and [47m:[0m[47m[rewrite][0m rules used in preprocessing

  [Syntaxp]
      Attach a heuristic filter on a rule")
 (DEFLABEL
  (EVENTS)
  "Build a landmark

    Examples:
    (deflabel interp-section)

    General Form:
    (deflabel name)

  where [47mname[0m is a new symbolic name (see [name]).  By virtue of the
  fact that [47mdeflabel[0m is an event, it marks the current [history] with
  the [47mname[0m.  For example, you may wish to undo back through some
  label or compute a theory expression (see [theories]) in terms of
  some labels.  [47mDeflabel[0m [events] are never considered redundant.
  See [redundant-events].")
 (DEFLOCK
  (PARALLEL-PROGRAMMING)
  "Define a wrapper macro that provides mutual exclusion in ACL2(p)

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel evaluation and proof; see [parallelism].

    Example Form:
    (deflock *my-lock*)

    General Form:
    (deflock *symbol*)

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

  A call of this macro generates a definition of another macro, named
  [47mwith-<modified-lock-symbol>[0m, where [47m<modified-lock-symbol>[0m is the
  given symbol with the leading and trailing [47m*[0m characters removed.
  This newly defined macro will guarantee mutually exclusive
  execution when called in the body of the raw Lisp definition of a
  function, as is typically the case for [guard]-verified functions,
  for [47m:[0m[47m[program][0m mode functions, and for calls of macro [47m[top-level][0m.
  (See [guard-evaluation-table] for details of how raw Lisp code
  might not be invoked when guard-checking (see [set-guard-checking])
  has value [47m:none[0m or [47m:all[0m.)  Note that this macro is also simply the
  identity when invoked directly in the top-level loop; see
  [top-level] for a way to avoid this issue, and see
  [parallelism-at-the-top-level] for a general discussion of this
  issue for calls of [parallelism] primitives.

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

  Note that a call of [47mdeflock[0m expands into the application of [47mprogn[0m to
  two events, as illustrated below.

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

  Thus, [47mdeflock[0m forms are legal embedded event forms (see
  [embedded-event-form]) for [books] as well as [47m[encapsulate][0m and
  [47m[progn][0m [events].

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

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

    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)

  where [47mname[0m is a new symbolic name (see [name]), [47mmacro-args[0m specifies
  the formal parameters of the macro, and [47mbody[0m is a term whose only
  free variables are the [47mmacro-args[0m.  The formal parameters can be
  specified in a much more general way than is allowed by ACL2
  [47m[defun][0m [events]; see [macro-args] for a description of keyword
  ([47m&key[0m) and optional ([47m&optional[0m) parameters as well as other
  so-called ``lambda-list keywords'', [47m&rest[0m and [47m&whole[0m.  Each [47mdcl[0m is
  an optional declaration (see [declare]) except that the only
  [47m[xargs][0m keyword permitted by [47mdefmacro[0m is [47m:[0m[47m[guard][0m.

  One documentation string may be included between the list of formal
  parameters and the body, but it is essentially ignored by ACL2.
  See [documentation] for a discussion of documentation in ACL2.

  There are two restrictions on [47mbody[0m aside from it simply being a term
  in [47mmacro-args[0m.  Both restrictions relate to ancestral uses of
  [47m[apply$][0m in [47mbody[0m, i.e., uses of [47mapply$[0m by [47mbody[0m or any function that
  might be called during the evaluation of [47mbody[0m.  First, only badged
  primitive functions may be applied.  See [badge] for a way to
  obtain the complete list of badged primitives.  Second, [47mloop$[0m and
  [47mlambda$[0m may not be used anywhere in the ancestry of [47mbody[0m.  See
  [47mignored-attachment[0m and [47mprohibition-of-loop$-and-lambda$[0m for more
  discussion.  Note: It is permitted for the value of body to mention
  [47mapply$[0m, [47mloop$[0m, and [47mlambda$[0m.

  For compute-intensive applications, see [defmac], which can speed up
  macroexpansion by introducing an auxiliary [47mdefun[0m.  For a variant of
  [47mdefmacro[0m that automatically quotes arguments by default, but
  provides a way for calls to evaluate specified arguments, see
  [defmacroq].

  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 [trans].  When a form whose [47m[car][0m is [47mname[0m
  arises as the form is read in, the arguments are bound as described
  in CLTL pp. 60 and 145, the [guard] is checked, and then the [47mbody[0m
  is evaluated.  The result is used in place of the original form.

  In ACL2, macros do not have access to the ACL2 state, [47m[state][0m.  (If
  [47m[state][0m or any user-defined stobj (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 [47m[state][0m or other
  single-threaded objects (see [stobj]) or variables not among the
  macro's arguments.  See the [47mgit[0m example above.  For a related
  utility that does have access to the ACL2 [state], see
  [make-event].


Subtopics

  [Defmacro-untouchable]
      Define an ``untouchable'' macro

  [Ignored-attachment]
      Why attachments are sometimes not used

  [Prohibition-of-loop$-and-lambda$]
      Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms"
)
 (DEFMACRO-LAST
  (EVENTS)
  "Define a macro that returns its last argument, but with side effects

  This is an advanced feature that requires a trust tag.  For
  explanation, including an example, see [return-last].")
 (DEFMACRO-UNTOUCHABLE
  (MACROS EVENTS PROGRAMMING DEFMACRO)
  "Define an ``untouchable'' macro

  Strictly speaking, macros cannot be untouchable the way functions are
  untouchable; see [push-untouchable].  However, one can define a
  macro that is, in effect, untouchable, by using
  [47mdefmacro-untouchable[0m to introduce a trivial untouchable function
  into the definition.  Consider for example the following
  definition.

    (defmacro-untouchable mac (x)
      (list 'consp x))

  Let's look at the single-step macroexpansion of a call of the
  newly-defined macro, [47mmac[0m.

    ACL2 !>:trans1 (mac (f a))
     (PROG2$ (UNTOUCHABLE-MARKER 'MAC)
             (CONSP (F A)))
    ACL2 !>

  We see that this expansion is just as if we had used [47m[defmacro][0m
  instead of [47mdefmacro-untouchable[0m, except that a [47m[prog2$][0m wrapper
  lays down a call of [47muntouchable-marker[0m, which is a built-in
  untouchable function.  In effect, that call makes the macro, [47mmac[0m,
  untouchable.

  Of course, you are welcome to write your own variant of
  [47mdefmacro-untouchable[0m, introducing your own untouchable function.
  The result would presumably be roughly equivalent to using
  [47mdefmacro-untouchable[0m; but using [47mdefmacro-untouchable[0m has two
  advantages.  One advantage is that calls of a macro introduced with
  [47mdefmacro-untouchable[0m should have no Lisp execution overhead caused
  by the use of [47m[prog2$][0m or [47muntouchable-marker[0m, because of special
  handling provided by ACL2 for such calls of [47mprog2$[0m as well as
  inlining of [47muntouchable-marker[0m.  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 [47mdefmacro-untouchable[0m as the source of the error.")
 (DEFN
  (DEFUN EVENTS)
  "Definition with [guard] [47mt[0m

  [47mDefn[0m is [47m[defun][0m with [guard] [47mt[0m.

  [47mdefn[0m expands to a [47m[defun][0m with an added [47m(declare (xargs :guard t))[0m.
  If an explicit guard is supplied to [47mdefn[0m, it is conjoined to the
  added [47mt[0m guard, according to [47m[defun][0m's treatment of multiple guard
  declarations.")
 (DEFND
  (DEFUN EVENTS)
  "[disable]d definition with [guard] [47mt[0m

  [47mDefnd[0m is [47m[defund][0m with [guard] [47mt[0m.

  [47mdefnd[0m expands to a [47m[defund][0m with an added [47m(declare (xargs :guard t))[0m.
  If an explicit guard is supplied to [47mdefnd[0m, it is conjoined to the
  added [47mt[0m guard, according to [47m[defun][0m's treatment of multiple guard
  declarations.")
 (DEFPKG
  (EVENTS PACKAGES PROGRAMMING)
  "Define a new symbol package

    Example:
    (defpkg \"MY-PKG\"
            (union-eq *acl2-exports*
                      *common-lisp-symbols-from-main-lisp-package*))

    General Form:
    (defpkg \"name\" term doc-string)

  where [47m\"name\"[0m is a non-empty string, none of whose characters is lower
  case, that names the package to be created; [47mterm[0m is a variable-free
  expression that evaluates to a list of symbols, where no two
  distinct symbols in the list may have the same [47m[symbol-name][0m, to be
  imported into the newly created package; and [47mdoc-string[0m, if
  non-[47mnil[0m, 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.

  (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 [47m[defpkg][0m events added
  by ACL2 to the [portcullis] of a book's [certificate]; see
  [hidden-death-package].)

  There are two restrictions on [47mterm[0m aside from those mentioned above.
  Both restrictions relate to ancestral uses of [47m[apply$][0m in [47mterm[0m,
  i.e., uses of [47mapply$[0m by [47mterm[0m or any function that might be called
  during the evaluation of [47mterm[0m.  First, only badged primitive
  functions may be applied.  See [badge] for a way to obtain the
  complete list of badged primitives.  Second, [47mloop$[0m and [47mlambda$[0m may
  not be used anywhere in the ancestry of term.  See
  [47mignored-attachment[0m and [47mprohibition-of-loop$-and-lambda$[0m for more
  discussion.

  [47mDefpkg[0m forms can be entered at the top-level of the ACL2 [command]
  loop.  They should not occur in [books] (see [certify-book]).

  After a successful [47mdefpkg[0m it is possible to ``intern'' a string into
  the package using [47m[intern-in-package-of-symbol][0m.  The result is a
  symbol that is in the indicated package, provided the imports allow
  it.  For example, suppose [47m'my-pkg::abc[0m is a symbol whose
  [47m[symbol-package-name][0m is [47m\"MY-PKG\"[0m.  Suppose further that the
  imports specified in the [47mdefpkg[0m for [47m\"MY-PKG\"[0m do not include a
  symbol whose [47m[symbol-name][0m is [47m\"XYZ\"[0m.  Then

    (intern-in-package-of-symbol \"XYZ\" 'my-pkg::abc)

  returns a symbol whose [47m[symbol-name][0m is [47m\"XYZ\"[0m and whose
  [47m[symbol-package-name][0m is [47m\"MY-PKG\"[0m.  On the other hand, if the
  imports to the [47mdefpkg[0m does include a symbol with the name [47m\"XYZ\"[0m,
  say in the package [47m\"LISP\"[0m, then

    (intern-in-package-of-symbol \"XYZ\" 'my-pkg::abc)

  returns that symbol (which is uniquely determined by the restriction
  on the imports list above).  See [intern-in-package-of-symbol].

  Upon admission of a [47mdefpkg[0m event, the function [47mpkg-imports[0m is
  extended to compute a list of all symbols imported into the given
  package, without duplicates.  If [47m\"MY-PKG\"[0m is the name of the new
  package and [47msymb[0m is the symbol returned by [47m(intern (concatenate
  'string \"MY-PKG\" \"-PACKAGE\") \"ACL2\")[0m, then [47msymb[0m denotes the
  [rewrite] rule added for the package.  For example, here is a
  display of that rule for the event [47m(defpkg \"MY-PKG\" '(a b))[0m.

    ACL2 !>:pl (pkg-imports \"MY-PKG\")

    (:REWRITE MY-PKG-PACKAGE)
      New term: '(A B)
      Hypotheses: <none>
      Equiv: EQUAL
      Substitution: NIL

    ....

  [47mDefpkg[0m 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 [47mmake-package[0m or [47mimport[0m.  Currently, ACL2
  does not support exporting at all.

  The Common Lisp function [47m[intern][0m is weakly supported by ACL2; see
  [intern].  A more general form of that function is also provided:
  see [intern$].

  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 [47mdefpkg[0m that is subsequently undone, the host lisp
  system will contain the created package even after the undo.
  Because ACL2 hangs onto [world]s after they have been undone, e.g.,
  to implement [47m:[0m[47m[oops][0m 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 [47mname[0m is
  allowed to be the name of an existing package if that package was
  created by an undone [47mdefpkg[0m and the newly proposed set of imports
  is identical to the old one.  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 [47mname[0m is allowed to be the name of an
  existing package if the package was created by a [47mdefpkg[0m with
  identical set of imports.  That is, it is permissible to execute
  ``redundant'' [47mdefpkg[0m [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.

  Note that [47mdefpkg[0m performs evaluation in so-called [safe-mode], which
  can slow down evaluation significantly but checks [guard]s on
  [primitive]s.

  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 [47mfoo::bar[0m is a symbol whose
  [47m[symbol-package-name][0m is [47m\"FOO\"[0m, not [47m\"foo\"[0m), we simply disallow
  them.

  NOTE: Also see [managing-ACL2-packages] for contributed documentation
  on managing ACL2 packages.


Subtopics

  [Hidden-death-package]
      Handling [47m[defpkg][0m [events] that are [47m[local][0m

  [Hidden-defpkg]
      Handling defpkg events that are local

  [Ignored-attachment]
      Why attachments are sometimes not used

  [Prohibition-of-loop$-and-lambda$]
      Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms")
 (DEFPROXY
  (EVENTS)
  "Define a non-executable [47m:[0m[47m[program][0m-mode function for attachment

  This event is provided for those who want to experiment with
  [47m[defattach][0m using [47m:[0m[47m[program][0m mode functions, and without proof
  obligations or constraints on cycles in the extended ancestors
  graph; see [defattach].  If you merely want to define a stub or a
  non-executable function, see [defstub] or see [defun-nx],
  respectively.

  See community book [47mbooks/misc/defproxy-test.lisp[0m for an extended (but
  simple) example.

    Example Forms:
    (defproxy subr1 (* *) => *)
    (defproxy add-hash (* * hashtable) => (mv * hashtable))

    General Form:
    (defproxy name args-sig => output-sig)

  where [47mname[0m is a new function symbol and [47m(name . args-sig) =>
  output-sig)[0m is a signature; see [signature].

  The macro [47mdefproxy[0m provides a convenient way to introduce a
  ``proxy'': a [47m:program[0m mode function that can be given attachments
  for execution (see [defattach]), assuming that there is an active
  trust tag (see [defttag]).  Thus, a [47mdefproxy[0m call expands to a
  [47m[defun][0m form with the following [47m[xargs][0m [47m[declare][0m form:
  [47m:non-executable :program[0m.  Note that [47m[verify-termination][0m is not
  permitted for such a function.  However, it is permitted to put the
  proxy function into [47m:[0m[47m[logic][0m mode by use of an [47m[encapsulate][0m event;
  indeed, this is the way to ``upgrade'' an attachment so that the
  normal checks are performed and no trust tag is necessary.

  In order to take advantage of a [47m[defproxy][0m form, one provides a
  subsequent [47mdefattach[0m form to attach an executable function to the
  [47mdefproxy[0m-introduced function.  When [47m:skip-checks t[0m is provided in a
  [47m[defattach][0m form, the usual checks for [47mdefattach[0m [events] are
  skipped, including proof obligations and the check that the
  extended ancestor relation has no cycles (see [defattach]).  There
  must be an active trust tag (see [defttag]) in order to use
  [47m:skip-checks t[0m.  In that case the use of [47m:skip-checks t[0m is
  permitted; but note that its use is in fact required if a
  [47m:[0m[47m[program][0m mode function is involved, and even if a [47m:[0m[47m[logic][0m mode
  function is involved that has not been [guard]-verified.

  The following log shows a simple use of defproxy.

    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 !>

  One can replace this attachment with one that uses [47m:[0m[47m[logic][0m mode
  functions and does not skip checks.  The idea is to reintroduce the
  proxy function using an [47m[encapsulate][0m form, which does not require
  redefinition (see [ld-redefinition-action]) to be enabled, and
  either to put the attachment into [47m:[0m[47m[logic][0m mode with the [guard]
  verified, as we do in the example below, or else to attach to a
  different [guard]-verified [47m:[0m[47m[logic][0m mode function.

    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 !>

  We close with some remarks on the checking of [guard]s in the case
  that [47m[defattach][0m has been called with keyword argument [47m:skip-checks
  t[0m.  We illustrate with examples, where we assume an attachment pair
  [47m(f . g)[0m created by an event [47m(defattach ... (f g) ... :skip-checks t
  ...)[0m.  A good model for the treatment of [47m:skip-checks t[0m is
  dependent on whether [47mf[0m was introduced with [47mdefproxy[0m or with
  [47m[encapsulate][0m: for [47mdefproxy[0m, the normal guard-related checks are
  treated as skipped, while for [47m[encapsulate][0m, they are assumed to
  hold.

  First suppose that [47mf[0m was introduced using [47mdefproxy[0m, and consider the
  following example.

    (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)

  If we try to evaluate the form [47m(f 3)[0m in ACL2, then the
  executable-counterpart of [47mf[0m is invoked (see [evaluation]).  It
  calls the executable-counterpart of [47mg[0m, which calls the
  executable-counterpart of [47m[car][0m, which in turn checks the [guard]
  of [47m[car][0m and causes a guard violation error (unless we first turn
  off guard-checking; see [set-guard-checking]).

    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 !>

  Little changes if we modify the example above by strengthening the
  guard of [47mg[0m.

    (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)

  The result of evaluating [47m(f 3)[0m is as before, except that this time
  the guard violation occurs at the time that [47mg[0m is called.

    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 !>

  Now consider a slight variation of the example just above, in which [47mf[0m
  is introduced using [47m[encapsulate][0m instead of using [47mdefproxy[0m.

    (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)

  Since [47mf[0m was introduced by [47m[encapsulate][0m instead of by [47mdefproxy[0m, ACL2
  assumes that the usual guard properties hold.  In particular, it
  assumes that (informally speaking) the guard of [47mf[0m implies the guard
  of [47mg[0m; 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.

    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 !>

  If you replace [47mg[0m by its definition in the first example of this
  series, i.e. with a guard (implicitly) of [47mt[0m, you will see the same
  error, this time because the [47m[defattach][0m event assumed that [47mg[0m was
  guard-verified.")
 (DEFREC
  (EVENTS)
  "Introduce a record structure, like a [47mstruct[0m in C.

  The [47mdefrec[0m macro is built into ACL2 and is frequently used in the
  ACL2 sources to define basic kinds of structures.


Better Alternatives to Defrec

  While [47mdefrec[0m may be a reasonable choice for writing [program]-mode
  code, most users would likely be better served by using one of the
  many, richer alternatives to [defrec] that are available in various
  books.  See for instance macros such as:

    * The [std::defaggregate] macro from [std/util],

    * The [defdata] macro,

    * The [fty::defprod] macro from the [fty] library, and

    * The [47mdata-structures/structures[0m book.

  A major reason to favor these macros over [47mdefrec[0m 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 [47m(employee->position x)[0m instead of [47m(cdddr x)[0m.

  Another reason is that [47mdefrec[0m does not support putting constraints on
  the fields of your structure.  For instance, you might want to have
  an [47memployee[0m structure where the [47mname[0m field is always a string.  You
  can't do this with [47mdefrec[0m, but any of the above macros support it.

  Some of the above macros also have other useful features, e.g.,
  integration with [b*], support for [xdoc] documentation, and so
  forth.


Usage

  A typical use of [47mdefrec[0m might look like this:

    (defrec employee             ;; name of the structure
      (name salary . position)   ;; fields of the structure
      nil)                       ;; \"cheap\" flag

  This will result in the introduction of:

    * A \"weak\" recognizer function, [47mweak-employee-p[0m, which recognizes cons
      structures that have the right shape.  We call the recognizer
      [3mweak[0m because it doesn't impose any constraints on the fields,
      e.g., there is no requirement that the [47mname[0m of an employee must
      be a string or that the [47msalary[0m must be a number.

    * A [make] macro that can be used like this:

          (make employee :name \"Jimmy\"
                         :salary 0
                         :position \"Unpaid Intern\")

    * A [change] macro that can be used like this:

          (let ((jimmy (make-employee :name \"Jimmy\" ...)))
            (change employee jimmy :salary 300000
                                   :position \"Vice President\"))

    * Suitable [access] macros that can be used like this:

          (let ((jimmy (make-employee :name \"Jimmy\" ...)))
            (access employee jimmy :name))


Subtopics

  [Access]
      Accessor macro for [defrec] structures.

  [Change]
      Mutator macro for [defrec] structures.

  [Make]
      Constructor macro for [defrec] structures.")
 (DEFREFINEMENT
  (EVENTS)
  "Prove that [47mequiv1[0m refines [47mequiv2[0m

    Example:
    (defrefinement equiv1 equiv2)

    is an abbreviation for
    (defthm equiv1-refines-equiv2
      (implies (equiv1 x y) (equiv2 x y))
      :rule-classes (:refinement))

  See [refinement].

    General Form:
    (defrefinement equiv1 equiv2
      :package package
      :event-name event-name
      :rule-classes rule-classes
      :instructions instructions
      :hints hints
      :otf-flg otf-flg)

  where [47mequiv1[0m and [47mequiv2[0m are known [equivalence] relations; [47mpackage[0m,
  if supplied, is one of [47m:current[0m, [47m:equiv1[0m, [47m:equiv2[0m or [47m:legacy[0m;
  [47mevent-name[0m, if supplied, is a symbol; and all other arguments are
  as specified in the documentation for [47m[defthm][0m.  The [47mdefrefinement[0m
  macro expands into a call of [47m[defthm][0m.  The name of the [47m[defthm][0m
  event is [47mequiv1-refines-equiv2[0m, unless an [47m:event-name[0m keyword
  argument is supplied, in which case [47mevent-name[0m is used as the name.
  The [47mpackage[0m of symbols generated, such as variables and [47m[defthm][0m
  names, is determined by the [47mpackage[0m argument: if it is not supplied
  or its value is [47m:current[0m, then the [47m[current-package][0m is used; if
  its value is [47m:equiv1[0m or [47m:legacy[0m, then the package of [47m:equiv1[0m is
  used; if its value is [47m:equiv2[0m, then the package of [47m:equiv2[0m is used.
  The rule-class [47m:[0m[47m[refinement][0m is added to the [47m[rule-classes][0m
  specified, if it is not already there.  All other arguments to the
  generated [47m[defthm][0m form are as specified by the other keyword
  arguments above.  The term generated for the [47m[defthm][0m event states
  that [47mequiv1[0m refines [47mequiv2[0m.")
 (DEFSTOBJ (EVENTS STOBJ)
  "Define a new single-threaded object

  Note: Novices are advised to avoid [47mdefstobj[0m, perhaps instead using
  community books [std::defaggregate] or
  [47mbooks/data-structures/structures.lisp[0m.  At the least, consider
  using [47m([0m[47m[set-verify-guards-eagerness][0m[47m 0)[0m to avoid [guard]
  verification.  On the other hand, after you learn to use [47mdefstobj[0m,
  see [defabsstobj] for another way to introduce single-threaded
  objects.

    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)

  where [47mname[0m is a new symbol; each [47mfieldi[0m is a symbol; each [47mtypei[0m is
  either a type-indicator (a [47m[type-spec][0m or [stobj] name), of the
  form [47m(ARRAY type-indicator (max))[0m, or of one of the forms
  [47m(HASH-TABLE test)[0m, [47m(HASH-TABLE test size)[0m, [47m(HASH-TABLE test size
  type-indicator)[0m, [47m(STOBJ-TABLE)[0m, or [47m(STOBJ-TABLE size)[0m; each [47mvali[0m is
  an object satisfying [47mtypei[0m; and each [47mbi[0m is [47mt[0m or [47mnil[0m.  Pairs
  [47m:element-type etypei[0m, [47m:initially vali[0m, and [47m:resizable bi[0m may be
  omitted; more on this below.  The [47m:renaming doublets[0m argument is
  optional and allows the user to override the default function names
  introduced by this event.  The [47m:inline flg[0m 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 [47m:congruent-to old-stobj-name[0m argument specifies an
  existing stobj with exactly the same structure, and is discussed
  below.  The optional [47m:non-memoizable nm-flg[0m and [47m:non-executable
  ne-flg[0m Boolean arguments are ignored when [47mnm-flg[0m and [47mne-flg[0m are
  [47mnil[0m, but otherwise: the former instructs ACL2 to lay down faster
  code for functions that return the new stobj but disallows
  [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 [47mfieldi[0m, [47mtypei[0m, [47mvali[0m, and on [47mdoublets[0m below.  We recommend that
  you read about single-threaded objects (stobjs) in ACL2 before
  proceeding; see [stobj].

  The effect of this event is to introduce a new single-threaded object
  (i.e., a ``[stobj]''), named [47mname[0m, and the associated recognizers,
  creator, accessors, updaters, constants.  For fields of [47mARRAY[0m type,
  this event also introduces length and resize functions.  For fields
  of [47mHASH-TABLE[0m type, this event also introduces boundp, get?,
  remove, count, clear, and initialization functions.  Fields of
  [47mSTOBJ-TABLE[0m type introduce those functions as well except for the
  get? function.


The Single-Threaded Object Introduced

  The [47mdefstobj[0m event effectively introduces a new ``live stobj''
  object, named [47mname[0m, which has as its initial logical value a list
  of [47mk[0m elements, where [47mk[0m 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.

  The elements are listed in the same order in which the field
  descriptors appear.  If the [47m:type[0m of a field is [47m(ARRAY
  type-indicator (max))[0m then [47mmax[0m is a non-negative integer or a
  symbol introduced by [47m[defconst][0m) whose value is a non-negative
  integer, and the corresponding element of the stobj is initially of
  length specified by [47mmax[0m.  If the [47m:type[0m of a field is [47m(HASH-TABLE
  test)[0m or [47m(HASH-TABLE test size)[0m, or [47m(HASH-TABLE test size
  type-indicator)[0m, then: [47mtest[0m is one of the symbols [47mEQ[0m, [47mEQL[0m,
  [47mHONS-EQUAL[0m, or [47mEQUAL[0m; [47msize[0m, if supplied as above or in [47m(STOBJ-TABLE
  size)[0m, is nil (handled the same as when size is omitted) or a
  natural number; and [47mtype-indicator[0m 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 [47m[hons-copy][0m is first applied to the key in the [47mHONS-EQUAL[0m
  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.)

  If the value of [47m:type[0m is of the form [47m(ARRAY type-indicator (max))[0m,
  [47m(HASH-TABLE test size type-indicator)[0m, or just [47mtype-indicator[0m, then
  [47mtype-indicator[0m is typically a type-spec; see [type-spec].  However,
  [47mtype-indicator[0m can also be the name of a stobj that was previously
  introduced (by [47mdefstobj[0m or [47m[defabsstobj][0m).  We ignore this ``nested
  stobj'' case below; see [nested-stobjs] for a discussion of stobjs
  within stobjs.

  A field with a [47mSTOBJ-TABLE[0m type is logically an association list
  whose keys are [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
  [stobj-table] for relevant discussion.

  Below, we refer to [3mscalar types[0m as stobj field types that are neither
  array types, hash-table types, nor stobj-table types.  Now consider
  the keyword value [47m:initially val[0m for a stobj field.  If the stobj
  field is of scalar type, then [47mval[0m is the initial value of the
  field.  For an array type [47m(ARRAY type-indicator (max))[0m, [47mval[0m is the
  initial value of the elements in the corresponding array.  For a
  [47mHASH-TABLE[0m type, [47mval[0m 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 [47m:initially[0m keyword is illegal for
  fields of [47mSTOBJ-TABLE[0m type.

  Note that the actual representation of the stobj in the underlying
  Lisp may be quite different; see [stobj-example-2].  For the moment
  we focus primarily on the logical aspects of the object.

  In addition, the [47mdefstobj[0m event introduces functions for recognizing
  and creating the stobj and for recognizing, accessing, and updating
  its fields.  For fields of [47mARRAY[0m type, length and resize functions
  are also introduced; see [defstobj-element-type] for discussion of
  the [47m:element-type[0m keyword that may be provided for performance .
  For fields of [47mHASH-TABLE[0m or [47mSTOBJ-TABLE[0m type, this event also
  introduces boundp, get? ([47mHASH-TABLE[0m types only), remove, count,
  clear, and initialization functions, as discussed below.  Constants
  are introduced that correspond to the accessor functions.


Restrictions on the Field Descriptions in Defstobj

  Each field descriptor is of the form:

    (fieldi :TYPE typei :INITIALLY vali)

  Note that the type and initial value are given in ``keyword
  argument'' format and may be given in either order.  The [47mtypei[0m and
  [47mvali[0m ``arguments'' are not evaluated.  If omitted, the type
  defaults to [47mt[0m (unrestricted) and the initial value defaults to [47mnil[0m.

  Each [47mtypei[0m must be either a [47m[type-spec][0m or else a list of the form
  [47m(ARRAY type-spec (max))[0m, [47m(HASH-TABLE test)[0m, [47m(HASH-TABLE test size)[0m,
  [47m(HASH-TABLE test size type-spec)[0m, [47m(STOBJ-TABLE)[0m, or [47m(STOBJ-TABLE
  size)[0m.  (Again, we are ignoring the case of nested stobjs,
  discussed elsewhere (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 [stobj-table]).  Examples of legal [47mtypei[0m
  are:

    (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)

  The [47mtypei[0m describes the objects which are expected to occupy the
  given field.  Those objects in [47mfieldi[0m should satisfy [47mtypei[0m.  We are
  more precise below about what we mean by ``expected.'' Below we
  present the restrictions on [47mtypei[0m and [47mvali[0m.

  Remark on [47mSATISFIES[0m.  As suggested above, each type indicator may be
  a legal [type-spec].  But for a type-spec [47m(SATISFIES pred)[0m, not
  only must [47mpred[0m be unary --- it also must be a [guard]-verified
  [47m:[0m[47m[logic][0m mode function whose guard is [47mt[0m.  For example, since the
  guard of [47m[evenp][0m specifies an integer, the type-spec [47m(SATISFIES
  evenp)[0m is not legal for a stobj field.  However, the following is
  legal.

    (defun my-evenp (x)
      (declare (xargs :guard t))
      (and (integerp x) (evenp x)))
    (defstobj st (fld :type (satisfies my-evenp) :initially 4))


Scalar Types

  We first discuss types that are neither array types, hash-table
  types, nor stobj-table types.  We call these ``scalar types.''

  When [47mtypei[0m is a [47m[type-spec][0m it restricts the contents, [47mx[0m, of [47mfieldi[0m
  according to the ``meaning'' formula given in the table for
  [47m[type-spec][0m.  For example, the first [47mtypei[0m 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.

  The initial value, [47mvali[0m, of a field description may be any ACL2
  object but must satisfy [47mtypei[0m.  Note that [47mvali[0m is not a form to be
  evaluated but an object.  A form that evaluates to [47mvali[0m could be
  written [47m'vali[0m, but [47mdefstobj[0m does not expect you to write the quote
  mark.  For example, the field description

    (days-off :initially (saturday sunday))

  describes a field named [47mdays-off[0m whose initial value is the list
  consisting of the two symbols [47mSATURDAY[0m and [47mSUNDAY[0m.  In particular,
  the initial value is NOT obtained by applying the function [47msaturday[0m
  to the variable [47msunday[0m!  Had we written

    (days-off :initially '(saturday sunday))

  it would be equivalent to writing

    (days-off :initially (quote (saturday sunday)))

  which would initialize the field to a list of length two, whose first
  element is the symbol [47mquote[0m and whose second element is a list
  containing the symbols [47msaturday[0m and [47msunday[0m.


Array Types

  When [47mtypei[0m is of the form [47m(ARRAY type-spec (max))[0m, the field is
  supposed to be a list of items, initially of length specified by
  [47mmax[0m, each of which satisfies the indicated [47mtype-spec[0m.  [47mMax[0m must be
  a non-negative integer or a defined constant evaluating to a
  non-negative integer.  Thus, each of

    (ARRAY (SIGNED-BYTE 31) (16))
    (ARRAY (SIGNED-BYTE 31) (*c*)) ; given previous event (defconst *c* 16)

  restricts the field to be a list of integers, initially of length 16,
  where each integer in the list is a [47m(SIGNED-BYTE 31)[0m.  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 [47mmax[0m.
  Note that the value of [47mmax[0m must be less than the Common Lisp
  constant [47marray-dimension-limit[0m, and also (though this presumably
  follows) less than the Common Lisp constant [47marray-total-size-limit[0m.

  Note also that the [47mARRAY[0m type requires that the [47mmax[0m 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.

  For array fields, the initial value [47mvali[0m must be an object satisfying
  the [47m[type-spec][0m of the [47mARRAY[0m description.  The initial value of the
  field is a list of [47mmax[0m repetitions of [47mvali[0m.

  Array fields can be ``resized,'' that is, their lengths can be
  changed, if [47m:resizable t[0m is supplied as shown in the example and
  General Form above.  The new length must satisfy the same
  restriction as does [47mmax[0m, as described above.  Each array field in a
  [47mdefstobj[0m 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 [47m:resizable t[0m was supplied with the field
  when the [47mdefstobj[0m was introduced and otherwise causes an error.  If
  [47m:resizable t[0m was supplied and the resize function specifies a new
  length [47mk[0m, then: if [47mk[0m is less than the existing array length, the
  array is shortened simply by dropping elements with index at least
  [47mk[0m; otherwise, the array is extended to length [47mk[0m by mapping the new
  indices to the initial value (supplied by [47m:initially[0m, else default
  [47mnil[0m).

  Array resizing is relatively slow, so we recommend using it somewhat
  sparingly.

  See [defstobj-element-type] for how the [47m:element-type[0m field may help
  with performance.


Hash-table Types

  When [47mtypei[0m is of the form [47m(HASH-TABLE test size type-spec)[0m, where
  [47msize[0m and [47mtype-spec[0m are optional, the field is logically an
  association list, initially empty, accessed using function
  [47m[hons-assoc-equal][0m (which is convenient simply because it has a
  guard of [47mt[0m, as opposed to other flavors of [47m[assoc][0m).  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 [47mtest[0m: thus if [47mtest[0m is [47m[equal][0m then
  there is no restriction on keys; if [47mtest[0m is [47m[eq][0m or [47m[eql][0m then the
  keys must be symbols or satisfy [47m[eqlablep][0m, respectively; and if
  [47mtest[0m is [47m[hons-equal][0m then there is no restriction on keys, but each
  proposed key is [47m[hons][0med in raw Lisp before it is used (whether for
  access or update) and before it is put into the underlying hash
  table.  The [47msize[0m defaults to [47mnil[0m, and if supplied, it must be
  either [47mnil[0m or a non-negative integer, or else a defined constant
  evaluating to [47mnil[0m 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.

  For a hash-table field, the [47m:initially[0m keyword specifies a default
  rather than an initial value: it provides the value (default [47mnil[0m)
  returned by an accessor when a given key is not bound.

  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:

    * a ``boundp'' function to check whether a given key is bound;

    * a ``get?'' function that, for a given key, returns two values [47m(mv val
      boundp)[0m, where: if the given key is bound then [47mval[0m is its value
      and [47mboundp[0m is [47mt[0m, else [47mval[0m is as specified by the [47m:initially[0m
      keyword ([47mnil[0m by default) and [47mboundp[0m is [47mnil[0m;

    * a ``remove'' function for removing a given key;

    * a ``count'' function that returns the number of (distinct) bound
      keys;

    * a ``clear'' function that creates a new empty hash table (and
      logically, the empty alist);

    * 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, [47m(make-hash-table)[0m, that
      creates a hash table.

  The clear and init functions both use the [47msize[0m argument, if supplied
  and not [47mnil[0m, of the type of the field supplied in the [47mdefstobj[0m
  event.  If a non-[47mnil[0m [47msize[0m argument was not supplied in that type,
  then the size of the hash table depends on the host Lisp.


Stobj-table Types

  As noted above, these are not discussed much here; see [stobj-table].


The Default Function Names

  To recap, in

    (defstobj name
              (field1 :type type1 :initially val1)
              ...
              (fieldk :type typek :initially valk)
              :renaming doublets
              :doc doc-string
              :inline inline-flag)

  [47mname[0m must be a new symbol, each [47mfieldi[0m must be a symbol, each [47mtypei[0m
  must be a [47m[type-spec][0m or [47m(ARRAY type-spec (max))[0m, and each [47mvali[0m
  must be an object satisfying [47mtypei[0m.

  Roughly speaking, for each [47mfieldi[0m, a [47mdefstobj[0m 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.

  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 [47mmax[0m.  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.

  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 [stobj-table] for a
  discussion of stobj-table types, which are largely ignored below.

  These functions --- 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 --- have ``default names.'' The default names
  depend on the field name, [47mfieldi[0m, and on whether the field is an
  array field, a hash-table field, or neither (i.e., a scalar field).
  For clarity, suppose [47mfieldi[0m is named [47mc[0m. The default names are shown
  below in calls, which also indicate the arities of the functions.
  In the expressions, we use [47mx[0m as the object to be recognized by
  field recognizers, [47mi[0m as an array index or the size of a resized
  array, [47mk[0m as a key (for the logical association list or raw-Lisp
  hash table associated with the field), [47mv[0m as the ``new value'' to be
  installed by an updater, and [47mname[0m as the single-threaded object.

                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)

  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 [with-local-stobj].  If
  the single-threaded object is named [47mname[0m, then the default names
  and arities are as shown below.

    top recognizer     (nameP x)
    creator            (CREATE-name)

  For example, the event

    (DEFSTOBJ $S
      (X :TYPE INTEGER :INITIALLY 0)
      (A :TYPE (ARRAY (INTEGER 0 9) (3)) :INITIALLY 9)
      (H :TYPE (HASH-TABLE EQ)))

  introduces a stobj named [47m$S[0m.  The stobj has three fields: [47mX[0m, [47mA[0m, and
  [47mH[0m.  The [47mA[0m field is an array and the [47mA[0m field is a hash table.  The [47mX[0m
  field contains an integer and is initially 0.  The [47mA[0m field contains
  a list of integers, each between 0 and 9, inclusive.  Initially,
  each of the three elements of the [47mA[0m field is 9.

  This event introduces the following sequence of definitions:

    (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

  For the last of these, the values of [47mHT-SIZE[0m, [47mREHASH-SIZE[0m, and
  [47mREHASH-THRESHOLD[0m are passed to the [47m:size[0m, [47m:rehash-size[0m, and
  [47m:reash-threshold[0m arguments (respectively) of a call of
  [47mmake-hash-table[0m in raw Lisp.  The [47m:test[0m argument of this function
  is the one specified in the [47m:type[0m specified in the [47mdefstobj[0m event
  for the field, in this case [47mEQ[0m from the type [47m(HASH-TABLE EQ)[0m; note
  however that if the [47m:type[0m specifies the test [47mHONS-EQUAL[0m, then the
  [47m:test[0m is [47mEQL[0m.


Avoiding the Default Function Names

  If you do not like the default names listed above you may use the
  optional [47m:renaming[0m doublets to substitute names of your own
  choosing.  Each element of [47mdoublets[0m should be of the form [47m(fn1
  fn2)[0m, where [47mfn1[0m is a default name and [47mfn2[0m is your choice for that
  name.

  For example

    (DEFSTOBJ $S
      (X :TYPE INTEGER :INITIALLY 0)
      (A :TYPE (ARRAY (INTEGER 0 9) (3)) :INITIALLY 9)
      :renaming ((X XACCESSOR) (CREATE-$S MAKE$S)))

  introduces the following definitions

    (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

  Note that even though the renaming doublets substitutes ``[47mXACCESSOR[0m''
  for ``[47mX[0m'' the updater for the [47mX[0m field is still called ``[47mUPDATE-X[0m.''
  That is because the renaming is applied to the default function
  names, not to the field descriptors in the event.

  Use of the [47m:renaming[0m doublets may be necessary to avoid name clashes
  between the default names and pre-existing function symbols.


Constants

  [47mDefstobj[0m events also introduce constant definitions (see [defconst]).
  One constant is introduced for each accessor function by prefixing
  and suffixing a `[47m*[0m' 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 [47ma[0m, [47mb[0m, and [47mc[0m, in that order,
  then the following constant definitions are introduced.

    (defconst *a* 0)
    (defconst *b* 1)
    (defconst *c* 2)

  These constants are used for certain calls of [47m[nth][0m and [47m[update-nth][0m
  that are displayed to the user in proof output.  For example, for
  stobj [47mst[0m with accessor functions [47ma[0m, [47mb[0m, and [47mc[0m, in that order, the
  term [47m(nth '2 st)[0m would be printed during a proof as [47m(nth *c* st)[0m.
  Also see [term], in particular the discussion there of untranslated
  terms, and see [nth-aliases-table].


Inspecting the Effects of a Defstobj

  Because the stobj functions are introduced as ``sub-events'' of the
  [47mdefstobj[0m the history commands [47m:[0m[47m[pe][0m and [47m:[0m[47m[pc][0m will not print the
  definitions of these functions but will print the superior [47mdefstobj[0m
  event.  To see the definitions of these functions use the history
  command [47m:[0m[47m[pcb!][0m.

  To see an s-expression containing the definitions that constitute the
  raw Lisp implementation of the event, evaluate the form

    (nth 4 (global-val 'cltl-command (w state)))

  [3mimmediately after[0m the [47mdefstobj[0m event has been processed.  Those
  functions that contain [47m(DECLARE (STOBJ-INLINE-FN T))[0m will generate
  [47m[defabbrev][0m forms because the [47m:inline[0m keyword of [47mdefstobj[0m was
  supplied the value [47mt[0m.  The rest will generate [47m[defun][0m forms.

  A [47mdefstobj[0m is considered redundant only if it is syntactically
  identical to a previously executed [47mdefstobj[0m.  Note that a redundant
  [47mdefstobj[0m does not reset the [stobj] fields to their initial values.


Performance

  The [47m:inline[0m 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 [47m:inline t[0m 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.

  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 [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 [47m:inline
  t[0m.

  It can also improve performance to specify [47m:non-memoizable t[0m, which
  disallows memoization but therefore avoids the cost of certain
  ``flushing'' operations.

  See [defstobj-element-type] for performance considerations pertaining
  to the [47m:element-type[0m field.


Specifying Congruent Stobjs

  Two stobjs are may be considered to be ``congruent'' if they have the
  same structure, that is, their [47mdefstobj[0m events are identical when
  ignoring field names.  In particular, every stobj is congruent to
  itself.  In order to tell ACL2 that a new stobj [47mst2[0m is indeed to be
  considered as congruent to an existing stobj [47mst1[0m, the [47mdefstobj[0m
  event introducing [47mst2[0m is given the keyword argument [47m:congruent-to
  st1[0m.  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 [47mst3[0m is [47m:congruent-to st2[0m, then [47mst1[0m, [47mst2[0m, and [47mst3[0m will all be
  congruent to each other.

  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 [47mst1[0m is replaced by [47mst2[0m at an argument position,
  and if [47mst1[0m is returned in the output [signature] of the function,
  then [47mst2[0m is returned in place of [47mst1[0m.

  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
  [47mbooks/misc/congruent-stobjs-test.lisp[0m.

    (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)))

  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.

    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 !>


Specifying Non-executable Stobjs

  As noted above, if keyword argument [47m:non-executable t[0m is specified
  then no global stobj for the given name is created.  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, [47mst[0m.  Then by using
  [47m:non-executable t[0m to introduce [47mst[0m, you avoid allocating memory for
  [47mst[0m that you never intend to use.  Similarly, you can avoid
  allocating such memory when your intended use of [47mst[0m is only as a
  local stobj (see [with-local-stobj]) or as the type of a stobj
  field of another stobj.  But see [add-global-stobj] and
  [remove-global-stobj] for utilities that change whether or not
  there is a global stobj for a given name.


Subtopics

  [Defstobj-element-type]
      Specify the element type for a [stobj] array field")
 (DEFSTOBJ-ELEMENT-TYPE
  (DEFSTOBJ)
  "Specify the element type for a [stobj] array field

  This topic assumes familiarity with the [47m[defstobj][0m event.  It
  documents the [47m:element-type[0m keyword for a stobj array field.  Note
  that [47m:element-type[0m is only supported for stobj array fields, not
  other sorts of stobj fields.

  Consider a stobj array field with [47m:type[0m of the form [47m(array etype
  (n))[0m, for example, [47m(array bit (8))[0m.  Logically, this ``array'' is a
  list, each of whose elements has the indicated type, [47metype[0m --- in
  our example, the type, [47mbit[0m (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 [47mbit[0m.  But it would also be legal to specify a weaker type.
  In particular, the type [47mt[0m is a legal type for every object, and
  this can be specified by including [47m:element-type t[0m in your stobj
  array field.

  Perhaps surprisingly, Lisp code may run faster when the element type
  in a raw Lisp array is [47mt[0m rather than a more restrictive type.  The
  [47m:element-type[0m of a stobj array field may be specified to be [47mt[0m to
  give this behavior, by using [47m:element-type t[0m.  You can do your own
  experiments to decide whether that is helpful, in particular by
  considering [community-book] [47mbooks/demos/element-type.lisp[0m.  That
  file starts with the following events and then times reading and
  writing the stobj array.

    (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)

  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 [47m:element-type t[0m with read-intensive applications when
  using CCL.  Results may be very different without the use of
  [47m:inline t[0m, and of course these results may not be indicative of
  your own experience with various applications, Lisps, and operating
  systems.

    (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).

  Currently the legal values for [47m:element-type[0m are [47mt[0m and the default
  value, which is the element type specified in the [47m:type[0m field of
  the stobj array field specification.  This could change if
  experiments suggest something different.")
 (DEFSTUB
  (EVENTS)
  "Stub-out a function symbol

    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

  where [47mname[0m is a new function symbol, and [47m(i1 ... ik)[0m, [47moutputs[0m, [47m:kwdi[0m,
  and [47mvali[0m must be as follows, respectively.

    * [3mNew style:[0m [47m((name i1 ... ik) => outputs :kwd1 val1 ... :kwdn valn)[0m is
      a valid new-style [signature].

    * [3mOld style:[0m [47m(name (i1 ... ik) outputs :kwd1 val1 ... :kwdn valn)[0m is a
      valid old-style [signature].

  Also see [signature].  Note that [47m(i1 ... ik)[0m is the list of formal
  parameters of the newly-defined function symbol, [47mname[0m.

  Note that while the [47mdefstub[0m syntax resembles a [signature], it is
  different: [47mname[0m occurs outside the parentheses containing [47m(i1 ...
  ik)[0m in the [47mdefstub[0m syntax, but inside in the signature syntax.

  A [47mdefstub[0m macro call expands into an [47m[encapsulate][0m event (see
  [encapsulate]).  Thus, no axioms are available about [47mname[0m but it
  may be used wherever a function of the given signature is
  permitted.  Exception: if [47moutputs[0m is of the form [47m(mv ...)[0m, then a
  [47m:[0m[47m[type-prescription][0m rule is introduced stating that [47mname[0m returns a
  value satisfying [47m[true-listp][0m.")
 (DEFTHEORY
  (EVENTS THEORIES)
  "Define a theory (to [enable] or [disable] a set of rules)

    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)

  where [47mname[0m is a new symbolic name (see [name]), [47mterm[0m is a term that
  when evaluated will produce a theory (see [theories]), and [47mflg[0m is
  expected to be Boolean.  Except for the variable [47m[world][0m, [47mterm[0m must
  contain no free variables.  [47mTerm[0m is evaluated with [47m[world][0m bound to
  the current world (see [world]) and the resulting theory is then
  converted to a [3mrunic theory[0m (see [theories]) and associated with
  [47mname[0m.  Henceforth, this runic theory is returned as the value of
  the theory expression [47m(theory name)[0m.

  The value returned is the length of the resulting theory.  For
  example, in the following, the theory associated with [47m'FOO[0m has 60
  [rune]s as of ACL2 Version 8.6:

    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 !>

  Note that the theory being defined depends on the context.  For
  example, consider the following (contrived) example book.

    (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))))

  At the time [47mfoo-property[0m is proved admissible during book
  certification (see [certify-book]), the [47m[local][0m [47m[in-theory][0m event
  has previously been evaluated, so the [definition] of [47mfoo[0m is
  [enable]d.  Thus, the [47m:in-theory[0m hint on [47mfoo-property[0m will [enable]
  [47mfoo[0m, and the theorem proves.  HOWEVER, when the book is later
  included (see [include-book]), the [47m[local][0m event is skipped, so the
  definition of [47mfoo[0m is [disable]d at the time the [theory] [47mmy-theory[0m
  is defined.  Hence, unlike the case for the admissibility pass of
  the book's certification, that theory does not include the
  definition of [47mfoo[0m when the book is included.

  There is, however, a way to ensure that a [theory] defined in a book
  is the same at [47m[include-book][0m time as it was during the
  admissibility pass of the book's certification; see
  [deftheory-static].

  Note that a [47mdeftheory[0m event is never redundant unless [47m:redundant-okp
  t[0m is specified, which supports a limited form of redundancy.  See
  [redundant-events].


Subtopics

  [Defthy]
      Define a theory (to [enable] or [disable] a set of rules)")
 (DEFTHEORY-STATIC
  (EVENTS THEORIES)
  "Define a `static' theory (to [enable] or [disable] a set of rules)

  This macro provides a variant of [47m[deftheory][0m, such that the resulting
  theory is the same at [47m[include-book][0m time as it was at
  [47m[certify-book][0m time.

  We assume that the reader is familiar with [theories]; see
  [deftheory].  We begin here by illustrating how [47mdeftheory-static[0m
  differs from [47m[deftheory][0m.  Suppose for example that the following
  events are the first two events in a book, where that book is
  certified in the initial ACL2 [world] (see [ground-zero]).

    (deftheory my-theory
      (current-theory :here))
    (deftheory-static my-static-theory
      (current-theory :here))

  Now suppose we include that book after executing the following event.

    (in-theory (disable car-cons))

  Suppose that later we execute [47m(in-theory (theory 'my-theory))[0m.  Then
  the rule [47mcar-cons[0m will be disabled, because it was disabled at the
  time the expression [47m(current-theory :here)[0m was evaluated when
  processing the [47mdeftheory[0m of [47mmy-theory[0m while including the book.
  However, if we execute [47m(in-theory (theory 'my-static-theory))[0m, then
  the rule [47mcar-cons[0m will be enabled, because the value of the theory
  [47mmy-static-theory[0m was saved at the time the book was certified.

    General Form:
    (deftheory-static name term)

  The arguments are handled the same as for [47m[deftheory][0m.  Thus, [47mname[0m is
  a new symbolic name (see [name]), and [47mterm[0m is a term that when
  evaluated will produce a theory (see [theories]).  Except for the
  variable [47m[world][0m, [47mterm[0m must contain no free variables.  [47mTerm[0m is
  evaluated with [47m[world][0m bound to the current world (see [world]) and
  the resulting theory is then converted to a [3mrunic theory[0m (see
  [theories]) and associated with [47mname[0m.  Henceforth, this runic
  theory is returned as the value of the theory expression [47m(theory
  name)[0m.

  As for [47m[deftheory][0m, the value returned is the length of the resulting
  theory.

  We conclude with an optional discussion about the implementation of
  [47mdeftheory-static[0m, for those familiar with [47m[make-event][0m.  The
  following macroexpansion of the [47mdeftheory-static[0m form above shows
  how this works (see [trans1]).

    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 !>

  The idea is that upon evaluation of this [47mmake-event[0m form, the first
  step is to evaluate the indicated [47m[let][0m expression to obtain a form
  [47m(deftheory my-theory '(...))[0m, where ``[47m(...)[0m'' is a list of all
  [rune]s in current theory.  If this form is in a book being
  certified, then the resulting [47mdeftheory[0m form is stored in the
  book's certificate, and is used when the book is included later.")
 (DEFTHM (EVENTS)
  "Prove and name a theorem

    Examples:
    (defthm assoc-of-app
            (equal (app (app a b) c)
                   (app a (app b c))))

  The following nonsensical example illustrates all the optional
  arguments but is illegal because not all combinations are
  permitted.  See [hints] for a complete list of [hints].

    (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)

  where [47mname[0m is a new symbolic name (see [name]), [47mterm[0m is a term
  alleged to be a theorem, and [47m[rule-classes][0m, [47m[instructions][0m,
  [47m[hints][0m, and [47m[otf-flg][0m are as described in their respective
  [documentation].  The keyword arguments above are all optional,
  however you may not supply both [47m:[0m[47m[instructions][0m and [47m:[0m[47m[hints][0m, since
  one drives the interactive [proof-builder] and the other drives the
  theorem prover.  If [47m:[0m[47m[rule-classes][0m is not specified, the list
  [47m(:rewrite)[0m is used; if you wish the theorem to generate no rules,
  specify [47m:[0m[47m[rule-classes][0m [47mnil[0m.

  When ACL2 processes a [47mdefthm[0m event, it first tries to prove the
  [term] using the indicated hints (see [hints]) or [instructions]
  (see [proof-builder]).  If it is successful, it stores the rules
  described by the rule-classes (see [rule-classes]), proving the
  necessary corollaries.


Subtopics

  [Defthmd]
      Prove and name a theorem and then disable it

  [Otf-flg]
      Allow more than one initial subgoal to be pushed for induction")
 (DEFTHMD (DEFTHM EVENTS)
  "Prove and name a theorem and then disable it

  Use [47mdefthmd[0m instead of [47m[defthm][0m 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 [47m:[0m[47m[in-theory][0m.  Specifically, the form

    (defthmd NAME TERM ...)

  expands to the following, except that some output is inhibited for
  the [47m[in-theory][0m and [47m[value-triple][0m [events]:

    (progn
      (defthm NAME TERM ...)
      (in-theory (disable NAME))
      (value-triple '(:defthmd NAME))).

  [47mDefthmd[0m events are generally not redundant, because the generated
  [47m[in-theory][0m event is not redundant.  This default can be changed;
  see [set-in-theory-redundant-okp].

  See [defthm] for documentation of [47mdefthm[0m.")
 (DEFTHY
  (EVENTS THEORIES DEFTHEORY)
  "Define a theory (to [enable] or [disable] a set of rules)

  See [deftheory].  The [47mdefthy[0m macro is simply a convenient macro for
  [47mdeftheory[0m that supports a limited notion of redundancy; see
  [redundant-events].  Specifically: a call [47m(defthy name expr)[0m
  expands to the corresponding event [47m(deftheory name expr
  :redundant-okp t)[0m.")
 (DEFTTAG
  (INTERFACING-TOOLS EVENTS)
  "Introduce a trust tag (ttag)

  [31;1mIntroduction[0m.  This event is intended for advanced users who, in
  essence, want to build extensions of ACL2.  The typical intended
  use is to create [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:

    <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>

  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, [47m[sys-call][0m
  can be used in an unsafe way, for example to overwrite files, or
  worse; see [sys-call] for a frightening example from Bob Boyer.
  The following example shows that the function [47m[sys-call][0m is
  restricted by default, but can be called after installing an active
  trust tag.

    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 !>

  Of course, using [47m[sys-call][0m with the Linux command [47mpwd[0m 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 [events] into a book that is to be certified.

    (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)

  We can certify this book with a specification that [47m:pwd-ttag[0m is a
  legal trust tag:

    (certify-book \"pwd\" 0 t :ttags (:pwd-ttag))

  One can now use this book by executing [47m[include-book][0m with keyword
  parameter [47m:ttags (:pwd-ttag)[0m and then calling function
  [47mprint-working-dir[0m:

    (include-book \"pwd\" :ttags (:pwd-ttag))
    (print-working-dir) ; working directory is printed to terminal

  [31;1mDetailed documentation.[0m

    General Form:
    (defttag tag-name)

  where [47mtag-name[0m is a symbol.

  Note however that if [47mtag-name[0m is not [47mnil[0m, then it is converted to a
  ``corresponding [keyword]'': a symbol in the [47m\"KEYWORD\"[0m package with
  the same [47m[symbol-name][0m as [47mtag-name[0m.  Thus, for example, [47m(defttag
  foo)[0m is equivalent to [47m(defttag :foo)[0m.  Moreover, a non-[47mnil[0m symbol
  with a [47m[symbol-name][0m of [47m\"NIL\"[0m is illegal for trust tags; thus, for
  example, [47m(defttag :nil)[0m is illegal.

  This event introduces or removes a so-called active trust tag (or
  ``ttag'', pronounced ``tee tag'').  An active ttag is a [keyword]
  symbol that is associated with potentially unsafe evaluation.  For
  example, calls of [47m[sys-call][0m are illegal unless there is an active
  trust tag.  An active trust tag can be installed using a [47mdefttag[0m
  event.  If one introduces an active ttag and then writes
  definitions that contain calls of [47m[sys-call][0m, 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 [books]; a book's [certificate] contains a list of ttags
  that are active in that book, or in a book that is included
  (possibly [local]ly), or in a book included in a book that is
  included (either inclusion being potentially [local]), and so on.
  We explain all this in more detail below.

  [47m(Defttag :tag-name)[0m is essentially equivalent to

    (table acl2-defaults-table :ttag :tag-name)

  and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs; see [ACL2-defaults-table].  We say more about the
  scope of [47mdefttag[0m forms below.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless executes the above [47m[table][0m event and hence changes
  the ACL2 logical [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 [47m:tag-name[0m (unless
  deferred; see [set-deferred-ttag-notes]).

  [31;1mActive ttags.[0m Suppose [47mtag-name[0m names a non-[47mnil[0m symbol.  Then [47m(defttag
  :tag-name)[0m sets [47m:tag-name[0m to be the (unique) ``active ttag.'' There
  must be an active ttag in order for there to be any mention of
  certain functions, including [47m[sys-call][0m; evaluate the form
  [47m(strip-cars *ttag-fns*)[0m to see the full list of such symbols.  The
  macro [47m[progn!][0m similarly requires an active ttag.  On the other
  hand, [47m(defttag nil)[0m removes the active ttag, if any; there is then
  no active ttag.  The scope of a [47mdefttag[0m form in a book being
  certified or included is limited to subsequent forms in the same
  book before the next [47mdefttag[0m (if any) in that book.  Similarly, if
  a [47mdefttag[0m form is evaluated in the top-level loop, then its effect
  is limited to subsequent forms in the top-level loop before the
  next [47mdefttag[0m in the top-level loop (if any).  Moreover,
  [47m[certify-book][0m is illegal when a ttag is active; of course, in such
  a circumstance one can execute [47m(defttag nil)[0m in order to allow book
  certification.

  [31;1mTtag notes and the ``certifier.''[0m When a [47mdefttag[0m is executed with an
  argument other than [47mnil[0m, output is printed, starting on a fresh
  line with: [47mTTAG NOTE[0m.  For example:

    ACL2 !>(defttag :foo)

    TTAG NOTE: Adding ttag :FOO from the top level loop.
     :FOO
    ACL2 !>

  If the [47mdefttag[0m occurs in an included book, the message looks like
  this.

    TTAG NOTE (for included book): Adding ttag :FOO from file /u/smith/acl2/my-book.lisp.

  The ``[47mTTAG NOTE[0m'' 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 [3mdefttag[0m events.  In a sense, [3mdefttag[0m
  events can allow you to define your own system on top of ACL2 (for
  example, see [progn!]).  So in order for someone else (who we might
  call the ``certifier'') to be confident that your collection of
  [books] is meaningful, that certifier should certify all the
  user-supplied books from scratch and check either that no [47m:ttags[0m
  were supplied to [47m[certify-book][0m, or else look for every [47mTTAG NOTE[0m
  in the standard output in order to locate all [47mdefttag[0m [events] with
  non-[47mnil[0m tag name.  In this way, the certifier can in principle
  decide whether to be satisfied that those [47mdefttag[0m events did not
  allow inappropriate forms in the user-supplied books.

  In order to eliminate much of the output from [47mTTAG NOTE[0ms, see
  [set-deferred-ttag-notes].  Note however that the resulting
  security is somewhat less; therefore, a [47mTTAG NOTE[0m is printed when
  invoking [47mset-deferred-ttag-notes[0m to defer printing of ttag notes.

  [31;1mAllowed ttags when certifying and including books.[0m A [47mdefttag[0m 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 [47m[certify-book][0m and [47m[include-book][0m, the set of
  allowed ttags may be restricted according to the [47m:ttags[0m keyword
  argument.  If this argument is [47mnil[0m then no ttag is allowed, so a
  [47mdefttag[0m call will fail during book certification or inclusion in
  this case.  This restriction applies even to [47mdefttag[0m forms already
  evaluated in the so-called certification [world] at the time
  [47m[certify-book][0m is called.  But note that [47m(defttag nil)[0m is always
  legal.

  A [47m:ttags[0m argument of [47m[certify-book][0m and [47m[include-book][0m can have value
  [47m:all[0m, 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 [47minclude-book[0m, an omitted [47m:ttags[0m
  argument or an argument of [47m:default[0m is treated as [47m:all[0m, except that
  warnings will occur when the book's [certificate] includes ttags;
  but for [47mcertify-book[0m, an omitted [47mttags[0m argument is treated as [47mnil[0m.
  Otherwise, if the [47m:ttags[0m argument is supplied but not [47m:all[0m, then
  its value is a true list of ttag specifications, each having one of
  the following forms, where [47msym[0m is a non-[47mnil[0m symbol which is treated
  as the corresponding [keyword].

      (1) [47m:sym[0m

      (2) [47m(:sym)[0m

      (3) [47m(:sym x1 x2 ... xk)[0m, where k > 0 and each [47mxi[0m is a string, except
      that one [47mxi[0m may be [47mnil[0m.

  In Case (1), [47m(defttag :sym)[0m 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 [47m(defttag :sym)[0m to occur in an unlimited number of books.
  For case (3) the [47mxi[0m specify where [47m(defttag :sym)[0m may occur, as
  follows.  The case that [47mxi[0m is [47mnil[0m refers to the top-level loop,
  while all other [47mxi[0m are filenames, where the [47m\".lisp\"[0m extension is
  optional and relative pathnames are considered to be relative to
  the connected book directory (see [cbd]).  Note that the
  restrictions on [47m(defttag :sym)[0m apply equally to any equivalent for
  based on the notion of ``corresponding keyword'' discussed above,
  e.g., [47m(defttag acl2::sym)[0m.

  An error message, as shown below, illustrates how ACL2 enforces the
  notion of allowed ttags.  Suppose that you call [47m[certify-book][0m with
  argument [47m:ttags (:foo)[0m, where you have already executed [47m(defttag
  :foo)[0m in the certification world (i.e., before calling
  [47m[certify-book][0m).  Then ACL2 immediately associates the ttag [47m:foo[0m
  with [47mnil[0m, where again, [47mnil[0m refers to the top-level loop.  If ACL2
  then encounters [47m(defttag foo)[0m inside that book, you will get the
  following error (using the book's absolute pathname, as shown):

    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.

  In general the structure displayed by the error message, which is
  [47m((:FOO NIL))[0m 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 [47m(:FOO NIL)[0m, meaning that ttag [47m:FOO[0m is
  only allowed at the top level (as represented by [47mNIL[0m).

  [31;1mAssociating ttags with books and with the top-level loop.[0m When a book
  is certified, each form [47m(defttag tag)[0m that is encountered for
  non-[47mnil[0m [47mtag[0m in that book or an included book is recorded in the
  generated [certificate], which associates the keyword corresponding
  to [47mtag[0m with the [full-book-name] of the book containing that
  [47mdefttag[0m.  If such a [47mdefttag[0m form is encountered outside a book,
  hence in the [portcullis] of the book being certified or one of its
  included books, then that keyword is associated with [47mnil[0m in the
  generated [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 [local]ly included books.

  For examples of ways to take advantage of ttags, see [hacker],
  [include-raw], [quicklisp], and more generally [interfacing-tools].
  See also [ttags-seen], [progn!], [remove-untouchable],
  [set-raw-mode], and [sys-call].


Subtopics

  [Push-untouchable]
      Add name or list of names to the list of untouchable symbols

  [Remove-untouchable]
      Remove names from lists of untouchable symbols

  [Set-deferred-ttag-notes]
      Modify the verbosity of [47mTTAG NOTE[0m printing

  [Set-raw-mode]
      Enter or exit ``raw mode,'' a raw Lisp environment

  [Set-raw-mode-on]
      Enter ``raw mode,'' a raw Lisp environment (requires trust tag)

  [Set-raw-mode-on!]
      Enter ``raw mode,'' a raw Lisp environment (adds trust tag)

  [Untouchable]
      Function symbols and state globals that cannot be referenced")
 (DEFUN
  (EVENTS PROGRAMMING)
  "Define a function symbol

    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)

  where [47mfn[0m is the symbol you wish to define and is a new symbolic name
  (see [name]), [47m(var1 ... varn)[0m is its list of formal parameters (see
  [name]), and [47mbody[0m is its body.  The definitional axiom is logically
  admissible provided certain restrictions are met.  These are
  sketched below.

  See also [mutual-recursion] for how to use [47mdefun[0m to make mutually
  recursive definitions, including discussion of how the [47m[xargs][0m
  [declaration]s in one [47mdefun[0m may affect the other definitions.

  Note that ACL2 does not support the use of [47mlambda-list[0m keywords (such
  as [47m&optional[0m) 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 [defmacro].

  The [3mdeclarations[0m (see [declare]), [47mdcl[0m, are optional.  If more than
  one [47mdcl[0m form appears, they are effectively grouped together as one.
  Perhaps the most commonly used ACL2 specific declaration is of the
  form [47m(declare (xargs :guard g :measure m))[0m.  This declaration in
  the [47mdefun[0m of some function [47mfn[0m has the effect of making the
  ``[guard]'' for [47mfn[0m be the term [47mg[0m and the ``measure'' be the term [47mm[0m.
  The notion of ``measure'' is crucial to ACL2's definitional
  principle.  The notion of ``guard'' is not, and is discussed
  elsewhere; see [verify-guards] and see
  [set-verify-guards-eagerness].  Note that a [47m:measure[0m is not allowed
  for a non-recursive definition unless it is part of a
  [47m[mutual-recursion][0m (exception: a measure of [47mnil[0m is treated as
  though the [47mmeasure[0m was omitted); moreover, if a [47m:measure[0m is
  supplied, then it must be a legal term.  Apart from these
  restrictions, the [47m:measure[0m is ignored in [47m:[0m[47m[program][0m mode; see
  [defun-mode].

  One documentation string may be included between the list of formal
  parameters and the body, but it is essentially ignored by ACL2.
  See [documentation] for a discussion of documentation in ACL2.

  We now briefly discuss the ACL2 definitional principle, using the
  following definition form which is offered as a more or less
  generic example.

    (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))))

  Note that in our generic example, [47mfn[0m has just two arguments, [47mx[0m and [47my[0m,
  the [guard] and measure terms involve both of them, and the body is
  a simple case split on [47m(test x y)[0m leading to a ``non-recursive''
  branch, [47m(stop x y)[0m, and a ``recursive'' branch.  In the recursive
  branch, [47mfn[0m is called after ``decrementing'' [47mx[0m to [47m(d x)[0m 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.

  Provided this definition is admissible under the logic, as outlined
  below, it adds the following axiom to the logic.

    Defining Axiom:
    (fn x y)
      =
    (if (test x y)
        (stop x y)
      (step (fn (d x) y)))

  Note that the [guard] of [47mfn[0m has no bearing on this logical axiom.

  This defining axiom is actually implemented in the ACL2 system by a
  [47m:[0m[47m[definition][0m rule, namely

    (equal (fn x y)
           (if (test a b)
               (stop a b)
             (step (fn (d a) b)))).

  See [definition] for a discussion of how definition rules are
  applied.  Roughly speaking, the rule causes certain instances of
  [47m(fn x y)[0m to be replaced by the corresponding instances of the body
  above.  This is called ``opening up'' [47m(fn x y)[0m.  The instances of
  [47m(fn x y)[0m opened are chosen primarily by heuristics which determine
  that the recursive calls of [47mfn[0m in the opened body (after
  simplification) are more desirable than the unopened call of [47mfn[0m.

  This discussion has assumed that the definition of [47mfn[0m was admissible.
  Exactly what does that mean?  First, [47mfn[0m must be a previously
  unaxiomatized function symbol (however, see
  [ld-redefinition-action]).  Second, the formal parameters must be
  distinct variable names.  Third, the [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.

  The final conditions on admissibility concern the termination of the
  recursion.  Roughly put, all applications of [47mfn[0m must terminate.  In
  particular, there must exist a binary relation, [47mrel[0m, and some unary
  predicate [47mmp[0m such that [47mrel[0m is well-founded on objects satisfying
  [47mmp[0m, the measure term [47mm[0m must always produce something satisfying [47mmp[0m,
  and the measure term must decrease according to [47mrel[0m in each
  recursive call, under the hypothesis that all the tests ruling the
  call are satisfied (see [rulers]).  By the meaning of
  well-foundedness, we know there are no infinitely descending chains
  of successively [47mrel[0m-smaller [47mmp[0m-objects.  Thus, the recursion must
  terminate.

  The default well-founded relation is [47m[o<][0m, an ``ordinal less-than''
  relation (discussed further below) that reduces to ordinary [47m<[0m on
  the natural numbers.  The default measure term is [47m(acl2-count var)[0m,
  where [47mvar[0m 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.

  The only primitive well-founded relation in ACL2 is [47m[o<][0m, which is
  known to be well-founded on the [47m[o-p][0ms.  For the proof of
  well-foundedness, see [proof-of-well-foundedness].  However it is
  possible to add new well-founded relations.  For details, see
  [well-founded-relation].  We discuss later how to specify which
  well-founded relation is selected by [47mdefun[0m and in the present
  discussion we assume, without loss of generality, that it is [47m[o<][0m
  on the [47m[o-p][0ms.

  For example, for our generic definition of [47mfn[0m above, with measure
  term [47m(m x y)[0m, two theorems must be proved.  The first establishes
  that [47mm[0m produces an ordinal:

    (o-p (m x y)).

  The second shows that [47mm[0m decreases in the (only) recursive call of [47mfn[0m:

    (implies (not (test x y))
             (o< (m (d x) y) (m x y))).

  Observe that in the latter formula we must show that the ``[47mm[0m-size''
  of [47m(d x)[0m and [47my[0m is ``smaller than'' the [47mm[0m-size of [47mx[0m and [47my[0m, provided
  the test, [47m(test x y)[0m, in the body fails, thus leading to the
  recursive call [47m(fn (d x) y)[0m.

  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, [47m[o<][0m is just the
  familiar ``less than'' relation ([47m[<][0m).  Thus, it is very common to
  use a measure [47mm[0m that returns a nonnegative integer, for then [47m(o-p
  (m x y))[0m becomes a simple conjecture about the type of [47mm[0m and the
  second formula above becomes a conjecture about the less-than
  relationship of nonnegative integer arithmetic.

  The most commonly used measure function is [47m[ACL2-count][0m, which
  computes a nonnegative integer size for all ACL2 objects.  See
  [ACL2-count].

  Probably the most common recursive scheme in Lisp [programming] is
  when some formal is supposed to be a list and in the recursive call
  it is replaced by its [47m[cdr][0m.  For example, [47m(test x y)[0m might be
  simply [47m(atom x)[0m and [47m(d x)[0m might be [47m(cdr x)[0m.  In that case,
  [47m(acl2-count x)[0m is a suitable measure because the [47m[ACL2-count][0m of a
  [47m[cons][0m is strictly larger than the [47m[ACL2-count][0ms of its [47m[car][0m and
  [47m[cdr][0m.  Thus, ``recursion by [47m[car][0m'' and ``recursion by [47m[cdr][0m'' are
  trivially admitted if [47m[ACL2-count][0m is used as the measure and the
  definition protects every recursive call by a test insuring that
  the decremented argument is a [47m[consp][0m.  Similarly, ``recursion by
  [47m[1-][0m'' in which a positive integer formal is decremented by one in
  recursion, is also trivially admissible.  See [built-in-clause] to
  extend the class of trivially admissible recursive schemes.

  We now turn to the question of which well-founded relation [47mdefun[0m
  uses.  It should first be observed that [47mdefun[0m must actually select
  both a relation (e.g., [47m[o<][0m) and a domain predicate (e.g., [47m[o-p][0m)
  on which that relation is known to be well-founded.  But, as noted
  elsewhere (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.

  The [47m[xargs][0m field of a [47m[declare][0m permits the explicit specification
  of any known well-founded relation with the keyword
  [47m:well-founded-relation[0m.  An example is given below.  If the [47m[xargs][0m
  for a [47mdefun[0m specifies a well-founded relation, that relation and
  its associated domain predicate are used in generating the
  termination conditions for the definition.

  If no [47m:well-founded-relation[0m is specified, [47mdefun[0m uses the
  [47m:well-founded-relation[0m specified in the [47m[ACL2-defaults-table][0m.  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 [47m[o<][0m (with domain
  predicate [47m[o-p][0m).

  This completes the brief sketch of the ACL2 definitional principle.
  Optionally, 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 [induction-coarse-v-fine-grained]
  for a discussion of how well-chosen rulers can affect the induction
  scheme.

  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 [47m[if][0m (or which macroexpand to such an
  expression).  In those cases you may wish to supply the following
  to [47m[xargs][0m: [47m:normalize nil[0m.  This is an advanced feature that turns
  off certain simplification of [definition] bodies and [guard]s;
  [normalize].

  When a [47mdefun[0m form is submitted, ACL2 sometimes computes and stores a
  [type-prescription] rule for the function.  See
  [type-prescription-debugging] for relevant discussion.

  The following example illustrates all of the available declarations,
  but it is completely nonsensical and it shows only a few of the
  many [47m:xargs[0m keywords.  See [xargs] for a complete list of [47m:xargs[0m
  keywords; also see [hints].

    (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))


Subtopics

  [Defn]
      Definition with [guard] [47mt[0m

  [Defnd]
      [disable]d definition with [guard] [47mt[0m

  [Defun$]
      Define a function symbol and generate a warrant

  [Defun-inline]
      Define a potentially inlined function symbol and associated macro

  [Defun-mode]
      Determines whether a function definition is a logical act

  [Defun-notinline]
      Define a not-to-be-inlined function symbol and associated macro

  [Defun-nx]
      Define a non-executable function symbol

  [Defund]
      Define a function symbol and then disable it

  [Defund-inline]
      Define a potentially disabled, inlined function symbol and
      associated macro

  [Defund-notinline]
      Define a disabled, not-to-be-inlined function symbol and associated
      macro

  [Defund-nx]
      Define a disabled non-executable function symbol

  [Mutual-recursion]
      Define some mutually recursive functions

  [Rulers]
      Control for ACL2's termination and induction analyses

  [Set-bogus-defun-hints-ok]
      Allow unnecessary [47m(xargs :hints ...)[0m and [measure]s.

  [Set-bogus-measure-ok]
      Allow unnecessary [measure]s and [47m(xargs :hints ...)[0m.

  [Set-ignore-ok]
      Allow unused formals and locals without an [47mignore[0m or [47mignorable[0m
      declaration

  [Set-irrelevant-formals-ok]
      Allow irrelevant formals in definitions

  [Set-measure-function]
      Set the default measure function symbol

  [Set-well-founded-relation]
      Set the default well-founded relation

  [Xargs]
      Extra arguments, for example to give [hints] to [47m[defun][0m"
)
 (DEFUN$
  (DEFUN EVENTS APPLY$)
  "Define a function symbol and generate a warrant

  [47mDefun$[0m is just a macro that expands to the obvious [47m[defun][0m followed
  by [47m[defwarrant][0m.")
 (DEFUN-INLINE
  (DEFUN EVENTS)
  "Define a potentially inlined function symbol and associated macro

  You may be able to improve performance by replacing an event [47m(defun f
  ...)[0m with a corresponding event [47m(defun-inline f ...)[0m, in order to
  encourage the host Lisp compiler to inline calls of [47mf[0m.

    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)

  satisfying the same requirements as in the General Form for [47m[defun][0m.
  The effect is to define a macro [47mfn[0m and a function [47mfn$inline[0m (i.e.,
  a symbol in the same package as [47mfn[0m but whose [47m[symbol-name][0m has the
  suffix [47m\"$INLINE\"[0m, such that each call of [47mfn[0m expands to a call of
  the function symbol [47mfn$inline[0m on the same arguments.  Moreover,
  [47m[table][0m [events] are generated that allow the use of [47mfn[0m in [theory]
  expressions to represent [47mfn$inline[0m and that cause any untranslated
  (user-level) call of [47mfn$inline[0m to be printed as the corresponding
  call of [47mfn[0m.  The documentation string is an optional string that
  can provide documentation but is essentially ignored by ACL2.

  A form [47m(defun-inline f ...)[0m actually defines a function named
  [47mf$inline[0m and a corresponding macro named [47mf[0m whose calls expand to
  calls of [47mf$inline[0m, while providing the illusion that there is just
  the ``function'' [47mf[0m.  For example, the Example Form above
  macroexpands in one step to the following form.

    (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))))))

  Note that the above call of [47m[add-macro-fn][0m generates the
  aforementioned two table events (see [add-macro-fn]), which provide
  the illusion that we are just defining a function [47mlng[0m, as you can
  see in the following log: [47mlng[0m appears rather than [47mlng$inline[0m.

    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 ..]

  Under the hood, ACL2 arranges that every function symbol with suffix
  [47m\"$INLINE\"[0m is presented to the compiler as one whose calls we would
  prefer to inline.  Technically: the Common Lisp form [47m(declaim
  (inline f$inline))[0m is generated for a function symbol [47mf$inline[0m
  before that symbol's definition is submitted.  However, the Common
  Lisp spec explicitly avoids requiring that the compiler respect
  this [47mdeclaim[0m form.  Fortunately, Common Lisp implementations often
  do respect it.

  Also see [defund-inline], see [defun-notinline], and see
  [defund-notinline].

  [3mRemarks[0m.

  (1) None of these macros (including [47mdefun-inline[0m) is supported for
  use inside a [47m[mutual-recursion][0m.

  (2) Every function symbol defined in ACL2 whose [47m[symbol-name][0m has the
  suffix [47m\"$INLINE\"[0m is proclaimed to be inline; similarly for
  [47m\"$NOTINLINE\"[0m and notinline.  These restrictions are explained in a
  comment in the ACL2 source definition of macro [47mdefun-inline[0m.

  (3) No special treatment for inlining (or notinlining) is given for
  function symbols locally defined by [47m[flet][0m, with two exceptions:
  when explicitly declared [47minline[0m or [47mnotinline[0m by the [47mflet[0m 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
  [local]).

  (4) The function symbol actually being defined by [47m(defun-inline foo
  ...)[0m is [47mfoo$inline[0m.  As mentioned above, one can be oblivious to
  this fact when writing [theory] expressions or perusing prover
  output.  However, for other purposes (for example, [47m[verify-guards][0m
  and [47m[defabsstobj][0m [47m:exports[0m) you will need to supply the name of the
  function symbol rather than the name of the macro; e.g., for the
  above form [47m(defun-inline foo ...)[0m, you may subsequently issue the
  event [47m(verify-guards foo$inline)[0m but not [47m(verify-guards foo)[0m.

  (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 [47m[include-book][0m
  with argument [47m:load-compiled-file :comp[0m.  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.  This may be fixed in a future release if someone
  complains."
)
 (DEFUN-MODE
  (DEFUN)
  "Determines whether a function definition is a logical act

  Two ``[defun-mode]s'' are supported, [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m.
  Roughly speaking, [47m:[0m[47m[program][0m mode allows you to prototype a
  function for execution without any proof burdens, while [47m:[0m[47m[logic][0m
  mode allows you to add a new definitional axiom to the logic.  The
  system comes up in [47m:[0m[47m[logic][0m mode.  Execution of functions whose
  [defun-mode] is [47m:[0m[47m[program][0m may render ACL2 unsound!  See
  [defun-mode-caveat].

  Note that calls of [47m[local][0m and of many [events] are skipped in
  [47m:program[0m mode; see [program].

  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 [47m:logic[0m mode.
  (However, see [defun-mode-lambdas] for some clarification
  concerning [47m[apply$][0m.)  But the most challenging restriction is that
  the system must prove that the recursion in the new definition
  terminates.

  Because ACL2 is a [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 --- 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.

  Thus, ACL2 introduces the idea of the ``[defun-mode]'' of a function.
  The [47m:mode[0m keyword of [47m[defun][0m's [47m[declare][0m [47mxarg[0m allows you to specify
  the [defun-mode] of a given definition.  If no [47m:mode[0m keyword is
  supplied, the default [defun-mode] is used; see
  [default-defun-mode].

  There are two [defun-mode]s, each of which is written as a keyword:

  [47m:[0m[47m[program][0m --- logically undefined but executable outside deductive
  contexts.

  [47m:[0m[47m[logic][0m --- axiomatically defined as per the ACL2 definitional
  principle.

  It is possible to change the [defun-mode] of a function from
  [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m.  We discuss this below.

  We think of functions having [47m:[0m[47m[program][0m mode as ``dangerous''
  functions, while functions having [47m:[0m[47m[logic][0m mode are ``safe.'' The
  only requirement enforced on [47m:[0m[47m[program][0m mode functions is the
  syntactic one: each definition must be well-formed ACL2.  Naively
  speaking, if a [47m:[0m[47m[program][0m 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 [47m:[0m[47m[program][0m mode execution
  is faulty because it ignores the damage that might be caused by
  ``mis-guarded'' functions.  See [defun-mode-caveat].

  We therefore implicitly describe an imagined implementation of
  [defun-mode]s that is safe and, we think, effective.  But please
  see [defun-mode-caveat].

  The default [defun-mode] is [47m:[0m[47m[logic][0m.  This means that when you
  [47m[defun][0m a function the system will try to prove termination.  If
  you wish to introduce a function of a different [defun-mode] use
  the [47m:mode[0m [47m[xargs][0m keyword.  Below we show [47mfact[0m introduced as a
  function in [47m:[0m[47m[program][0m mode.

    (defun fact (n)
      (declare (xargs :mode :program))
      (if (or (not (integerp n)) (= n 0))
          1
        (* n (fact (1- n)))))

  No axiom is added to the logic as a result of this definition.  By
  introducing [47mfact[0m in [47m:[0m[47m[program][0m mode we avoid the burden of a
  termination proof, while still having the option of executing the
  function.  For example, you can type

    ACL2 !>(fact 3)

  and get the answer [47m6[0m.  If you type [47m(fact -1)[0m you will get a hard lisp
  error due to ``infinite recursion.''

  However, the ACL2 theorem prover knows no axioms about [47mfact[0m.  In
  particular, if the term [47m(fact 3)[0m arises in a proof, the theorem
  prover is unable to deduce that it is [47m6[0m.  From the perspective of
  the theorem prover it is as though [47mfact[0m were an undefined function
  symbol of arity [47m1[0m.  Thus, modulo certain important issues (see
  [defun-mode-caveat]), the introduction of this function in
  [47m:[0m[47m[program][0m mode does not imperil the soundness of the system ---
  despite the fact that the termination argument for [47mfact[0m was omitted
  --- because nothing of interest can be proved about [47mfact[0m.  Indeed,
  we do not allow [47mfact[0m to be used in logical contexts such as
  conjectures submitted for proof.

  It is possible to convert a function from [47m:[0m[47m[program][0m mode to [47m:[0m[47m[logic][0m
  mode at the cost of proving that it is admissible.  This can be
  done by invoking

    (verify-termination fact)

  which is equivalent to submitting the [47m[defun][0m of [47mfact[0m, again, but in
  [47m:[0m[47m[logic][0m mode.

    (defun fact (n)
      (declare (xargs :mode :logic))
      (if (or (not (integerp n)) (= n 0))
          1
        (* n (fact (1- n)))))

  This particular event will fail because the termination argument
  requires that [47mn[0m be nonnegative.  A repaired [47m[defun][0m, for example
  with [47m[=][0m replaced by [47m[<=][0m, will succeed, and an axiom about [47mfact[0m
  will henceforth be available.

  Technically, [47m[verify-termination][0m submits a redefinition of the
  [47m:[0m[47m[program][0m mode function.  This is permitted, even when
  [47m[ld-redefinition-action][0m is [47mnil[0m, because the new definition is
  identical to the old (except for its [47m:mode[0m and, possibly, other
  non-logical properties).

  See [guard] for a discussion of how to restrict the execution of
  functions.  [Guard]s may be ``verified'' for functions in [47m:[0m[47m[logic][0m
  mode; see [verify-guards].


Subtopics

  [Defun-mode-lambdas]
      :program mode functions in [47m[lambda][0m objects

  [Logic]
      To set the default [defun-mode] to [47m:logic[0m

  [Program]
      To set the default [defun-mode] to [47m:[0m[47m[program][0m")
 (DEFUN-MODE-CAVEAT
  (COMMON-LISP)
  "Potential soundness issue for functions with [defun-mode] [47m:[0m[47m[program][0m

  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 [47m:[0m[47m[program][0m mode functions, the soundness concerns
  expressed below apply to all raw Lisp errors.

  Technically speaking, in the current implementation, the execution of
  functions having [defun-mode] [47m:[0m[47m[program][0m 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.

  See [defun-mode] for a discussion of [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.

  For discussion of a different soundness issue that is also related to
  function execution, see [generalized-booleans].

  The execution of a function having [defun-mode] [47m:[0m[47m[program][0m may
  violate Common Lisp [guard]s on the subroutines used.  (This may be
  true even for calls of a function on arguments that satisfy its
  [guard], because ACL2 has not verified that its [guard] is
  sufficient to protect its subroutines.)  When a [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.

  For example, suppose you make the following [47m[defun][0m:

    (defun crash (i)
      (declare (xargs :mode :program :guard (integerp i)))
      (car i))

  Note that the declared guard does not in fact adequately protect the
  subroutines in the body of [47mcrash[0m; indeed, satisfying the guard to
  [47mcrash[0m will guarantee that the [47m[car][0m expression is in violation of
  its guard.  Because this function is admitted in [47m:[0m[47m[program][0m-mode,
  no checks are made concerning the suitability of the guard.
  Furthermore, in the current ACL2 implementation, [47mcrash[0m is executed
  directly in Common Lisp.  Thus if you call [47mcrash[0m on an argument
  satisfying its guard you will cause an erroneous computation to
  take place.

    ACL2 !>(crash 7)

    Error: Caught fatal error [memory may be damaged]
    ...

  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.

  THUS, HAVING A FUNCTION WITH [defun-mode] [47m:[0m[47m[program][0m IN YOUR SYSTEM
  ABSOLVES US, THE ACL2 IMPLEMENTORS, FROM RESPONSIBILITY FOR THE
  SOUNDNESS OF OUR SYSTEM.

  Furthermore

  ACL2 DOES NOT YET PROVIDE ANY MEANS OF REGAINING ASSURANCES OF
  SOUNDNESS AFTER THE INTRODUCTION OF A FUNCTION IN [47m:[0m[47m[program][0m MODE,
  EVEN IF IT IS ULTIMATELY CONVERTED TO [47m:[0m[47m[logic][0m MODE (since its
  execution could have damaged the system in a way that makes it
  possible to verify its termination and [guard]s unsoundly).

  Finally,

  THE VAST MAJORITY OF ACL2 SYSTEM CODE IS IN [47m:[0m[47m[program][0m MODE AND SO
  ALL BETS ARE OFF FROM BEFORE YOU START!

  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
  [47m:[0m[47m[logic][0m mode.  We think it very unlikely that a mis-guarded
  function in [47m:[0m[47m[program][0m 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 [47m:[0m[47m[program][0m mode.  In that imagined implementation, code
  using functions having [47m:[0m[47m[program][0m 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 [47m:[0m[47m[program][0m mode, use them as convenient and
  perhaps ultimately introduce some of them in [47m:[0m[47m[logic][0m 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 [47m:[0m[47m[program][0m MODE!")
 (DEFUN-MODE-LAMBDAS
  (DEFUN-MODE)
  ":program mode functions in [47m[lambda][0m objects

  A rough rule-of-thumb is that all functions mentioned in a [47m:[0m[47m[logic][0m
  mode [47m[defun][0m must themselves be in [47m:logic[0m mode.  If [47mprgm[0m is a
  [47m:[0m[47m[program][0m mode function then [47m(defun fn (x) (prgm x))[0m is illegal.
  But there are situations (always involving [47m[apply$][0m) in which
  [47m:program[0m mode function symbols are allowed to be mentioned in
  [47m:logic[0m mode [47m[defun][0ms.  We explain here.

  Here are two example terms that mention the badged (see [47m[defbadge][0m)
  [47m:program[0m mode symbol [47mprgm[0m.

    (apply$ (lambda$ (e) (prgm e)) (list x))

    (loop$ for e in lst collect (prgm e))

  Are such terms permitted in the [47mdefun[0m of a [47m:logic[0m mode function?  The
  answer is complicated because it depends on whether the [47mdefun[0m is
  [47m[loop$][0m recursive and whether the [47mdefun[0m will also try to verify the
  [47m[guard][0ms of [47mfn[0m.

  First, a [47m:logic[0m mode function may [47mapply$[0m a quoted [47m:program[0m mode
  symbol, whether guards are being verified or not.  For example,
  [47m(apply$ 'prgm args)[0m is legal.  Here [47mprgm[0m is just a quoted symbol.
  Since [47mprgm[0m is a [47m:program[0m mode symbol, there are no axioms about it,
  so during proofs such a call of [47mapply$[0m is not evaluated or
  expanded.  If this form is evaluated at the top-level -- where
  [47m:program[0m mode functions are evaluable -- [47mapply$[0m checks the guards
  of [47mprgm[0m just as it would before any [47m:program[0m mode function is
  called.

  The situation is more complicated for use of [47m:program[0m mode functions
  in forms like [47m[lambda$][0m, well-formed quoted [47m[lambda][0m objects, and
  [47m[loop$][0m.  The reason is that in guard-verified code, these forms
  are generally executed via compiled code and that requires that the
  [47mloop$[0m and [47mlambda[0m objects be Common Lisp compliant, which in turn
  implies they must be analyzable by the prover.  Since formally
  [47mloop$[0ms are understood as calls of [scion]s on [47mlambda$[0m expressions
  it suffices for us to discuss the [47mlambda$[0m case alone.  Well-formed
  quoted [47mLAMBDA[0m objects are treated the same way.

  So again, suppose you're defining a [47m:logic[0m mode function [47mfn[0m.  Suppose
  [47mfn[0m is not [47mloop$[0m recursive and guards are not being verified during
  the [47mdefun[0m.  Then badged [47m:program[0m mode symbols may be used [47mlambda$[0m
  forms in the definition of [47mfn[0m.

  If [47mfn[0m is [47mloop$[0m recursive, i.e., [47m:[0m[47m[loop$-recursion][0m [47mt[0m is declared,
  then all symbols used as functions in [47mlambda$[0m forms must be in
  [47m:logic[0m mode.  The reason is that the measure conjectures generated
  must be in [47m:logic[0m mode to be provable.

  If [47mfn[0m is to be guard-verified, then all symbols used as functions in
  [47mlambda$[0m forms must be in [47m:logic[0m mode.  The reason is that the guard
  conjectures must be in [47m:logic[0m mode to be provable.

  When a [47m:program[0m function is permitted in a [47m:logic[0m 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

    (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)))

  but the last event will print:

    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.

  Uses of [47mprgm[0m in quoted well-formed [47mLAMBDA[0m objects, [47mlambda$[0m forms, and
  [47mloop$[0m forms will cause similar warning messages to be printed.")
 (DEFUN-NOTINLINE
  (DEFUN EVENTS)
  "Define a not-to-be-inlined function symbol and associated macro

  See [defun-inline] for an analogous utility that supports inlining.
  The present utility is probably far less useful; it tells the
  compiler [3mnot[0m to inline calls of the function being defined.  Also
  see [defund-notinline] for a variant of this event that disables
  the newly-defined function symbol.

  Under the hood, [47m(defun-inline f ...)[0m and [47m(defun-notinline f ...)[0m
  cause evaluation of Common Lisp forms [47m(declaim (inline f$inline))[0m
  and [47m(declaim (notinline f$notinline))[0m, respectively.  According to
  the Common Lisp spec, the compiler need not respect the first of
  these (for [47minline[0m), but it must respect the second of these (for
  [47mnotinline[0m).  Fortunately, Common Lisp implementations often do
  respect the first of these as well.")
 (DEFUN-NX
  (DEFUN EVENTS)
  "Define a non-executable function symbol

    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))

  The macro [47mdefun-nx[0m introduces definitions using the [47m[defun][0m macro,
  always in [47m:[0m[47m[logic][0m 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 [stobj]) and
  multiple-values passing (see [mv] and see [mv-let]).  After such a
  definition is admitted, the usual syntactic rules for [47m[state][0m and
  user-defined [stobj]s are relaxed for calls of the function it
  defines.  Also 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.

  The syntax of [47mdefun-nx[0m is identical to that of [47m[defun][0m.  A form

    (defun-nx name (x1 ... xk) ... body)

  generates the following definition.

    (defun name (x1 ... xk)
      (declare (xargs :non-executable t :mode :logic))
      ...
      (prog2$ (throw-nonexec-error 'name (list x1 ... xk))
              body))

  But [47mdefun-nx[0m does two other things.  Before executing the [47mdefun[0m form
  displayed above, ACL2 arranges that [47mstate[0m is allowed as a formal
  parameter, by first introducing [47m(set-state-ok t)[0m in a way that is
  [local] to the generated event.  After executing the [47mdefun[0m, the
  [executable-counterpart] [rune] for [47mname[0m is [disable]d.  You can
  evaluate [47m:trans1 (defun-nx ...)[0m for your [47mdefun-nx[0m form to see its
  single-step macroexpansion.

  Note that because of the insertion of the above call of
  [47mthrow-nonexec-error[0m, no formal is ignored when using [47mdefun-nx[0m.

  During proofs, the error is silent; it is ``caught'' by the proof
  mechanism and generally results in the introduction of a call of
  [47m[hide][0m during a proof.  If an error message is produced by
  evaluating a call of the function on a list of arguments that
  includes [47mstate[0m or user-defined [47m[stobj][0ms, these arguments will be
  shown as symbols such as [47m|<state>|[0m in the error message.  In the
  case of a user-defined stobj bound by [47m[with-local-stobj][0m or
  [47m[stobj-let][0m, the symbol printed will include the suffix [47m{instance}[0m,
  for example, [47m|<st>{instance}|[0m.

  It is harmless to include [47m:non-executable t[0m in your own [47m[xargs][0m
  [47m[declare][0m form; [47mdefun-nx[0m will still lay down its own such
  declaration, but ACL2 can tolerate the duplication.

  Note that [47m[defund-nx][0m is also available.  It is essentially identical
  to [47mdefun-nx[0m except that as with [47m[defund][0m, [47mdefund-nx[0m leaves the
  definition [rune] disabled for the new function symbol.

  If you use guards (see [guard]), please be aware that even though
  syntactic restrictions are relaxed for [47mdefun-nx[0m, guard verification
  proceeds exactly as for [47m[defun][0m.  If you want ACL2 to skip a form
  for purposes of generating guard proof obligations, use the macro
  [47m[non-exec][0m, which generates a call of [47mthrow-nonexec-error[0m that
  differs somewhat from the one displayed above.  See [non-exec].

  See [defun] for documentation of [47mdefun[0m.")
 (DEFUN-SK
  (EVENTS)
  "Define a function whose body has an outermost quantifier

    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)

  where [47mfn[0m is the symbol you wish to define and is a new symbolic
  [name], [47m(var1 ... varn)[0m is its list of formal parameters, the
  optional [47mdcl_i[0m forms are [47m[declare][0m forms, and [47mbody[0m is its body,
  which must be quantified as described below.  The other arguments
  are explained below.

  For a simple example, see [defun-sk-example].  For a more elaborate
  example, see [Tutorial4-Defun-Sk-Example].  See
  [quantifier-tutorial] for a careful beginner's introduction that
  takes you through typical kinds of quantifier-based reasoning in
  ACL2.  Also see [quantifiers] for an example illustrating how the
  use of recursion, rather than explicit quantification with
  [47mdefun-sk[0m, may be preferable.

  Below we describe the [47mdefun-sk[0m event precisely.  First, let us
  consider the examples above.  The first example, again, is:

    (defun-sk exists-x-p0-and-q0 (y z)
      (exists x
              (and (p0 x y z)
                   (q0 x y z))))

  It is intended to represent the predicate with formal parameters [47my[0m
  and [47mz[0m that holds when for some [47mx[0m, [47m(and (p0 x y z) (q0 x y z))[0m
  holds.  In fact [47mdefun-sk[0m is a macro, and the call above adds the
  following two [events], as shown just below.  The first event
  guarantees that if this new predicate holds of [47my[0m and [47mz[0m, then the
  term shown, [47m(exists-x-p0-and-q0-witness y z)[0m, is an example of the
  [47mx[0m that is therefore supposed to exist.  (Intuitively, we are
  axiomatizing [47mexists-x-p0-and-q0-witness[0m to pick a witness if there
  is one.  We comment below on the use of [47m[defun-nx][0m; for now,
  consider [47mdefun-nx[0m to be [47m[defun][0m.)  Conversely, the second event
  below guarantees that if there is any [47mx[0m for which the term in
  question holds, then the new predicate does indeed hold of [47my[0m and [47mz[0m.

    (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)))

  Now let us look at the third example from the introduction above:

    (defun-sk forall-x-y-p0-and-q0 (z)
      (forall (x y)
              (and (p0 x y z)
                   (q0 x y z))))

  The intention is to introduce a new predicate [47m(forall-x-y-p0-and-q0
  z)[0m which states that the indicated conjunction holds of all [47mx[0m and
  all [47my[0m together with the given [47mz[0m.  This time, the axioms introduced
  are as shown below.  The first event guarantees that if the
  application of function [47mforall-x-y-p0-and-q0-witness[0m to [47mz[0m picks out
  values [47mx[0m and [47my[0m for which the given term [47m(and (p0 x y z) (q0 x y z))[0m
  holds, then the new predicate [47mforall-x-y-p0-and-q0[0m holds of [47mz[0m.
  Conversely, the (contrapositive of) the second axiom guarantees
  that if the new predicate holds of [47mz[0m, then the given term holds for
  all choices of [47mx[0m and [47my[0m (and that same [47mz[0m).

    (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))))

  The examples above suggest the critical property of [47mdefun-sk[0m: it
  indeed does introduce the quantified notions that it claims to
  introduce.

  Notice that the [47m[defthm][0m event just above, [47mforall-x-y-p0-and-q0-necc[0m,
  may not be of optimal form as a rewrite rule.  Users sometimes find
  that when the quantifier is [47mforall[0m, 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:

    (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))))

  ACL2 will turn this into one [47m:[0m[47m[rewrite][0m rule for each conjunct, [47m(p0 x
  y z)[0m and [47m(q0 x y z)[0m, with hypothesis [47m(forall-x-y-p0-and-q0 z)[0m in
  each case.  In order to get this effect, use [47m:rewrite :direct[0m, in
  this case as follows.

    (defun-sk forall-x-y-p0-and-q0 (z)
      (forall (x y)
              (and (p0 x y z)
                   (q0 x y z)))
      :rewrite :direct)

  We now turn to a detailed description of [47mdefun-sk[0m, starting with a
  discussion of its arguments as shown in the \"General Form\" above.

  The third argument, [47mbody[0m, must be of the form

    (Q bound-vars term)

  where: [47mQ[0m is the symbol [47m[forall][0m or [47m[exists][0m, in the \"ACL2\" package;
  [47mbound-vars[0m is a variable or true list of variables disjoint from
  [47m(var1 ... varn)[0m and not including [47m[state][0m; and [47mterm[0m is a term.  The
  case that [47mbound-vars[0m is a single variable [47mv[0m is treated exactly the
  same as the case that [47mbound-vars[0m is [47m(v)[0m.

  The result of this event is to introduce a ``Skolem function,'' whose
  name is the keyword argument [47mskolem-name[0m if that is supplied, and
  otherwise is the result of modifying [47mfn[0m by suffixing \"-WITNESS\" to
  its name.  The following definition (or a corresponding rule; see
  the discussion of [47m:constrain[0m below) and one of the following two
  theorems (as indicated) are introduced for [47mskolem-name[0m and [47mfn[0m in
  the case that [47mbound-vars[0m (see above) is a single variable [47mv[0m.  The
  name of the [47m[defthm][0m event may be supplied as the value of the
  keyword argument [47m:thm-name[0m; if it is not supplied, then it is the
  result of modifying [47mfn[0m by suffixing \"-SUFF\" to its name in the case
  that the quantifier is [47m[exists][0m, and \"-NECC\" in the case that the
  quantifier is [47m[forall][0m.

    (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))))

  In the [47mforall[0m case, however, the keyword pair [47m:rewrite :direct[0m may be
  supplied after the body of the [47mdefun-sk[0m form, in which case the
  contrapositive of the above form is used instead:

    (defthm fn-necc ;in case the quantifier is FORALL
      (implies (fn var1 ... varn)
               term))

  This is often a better choice for the \"-NECC\" rule, provided ACL2 can
  parse [47mterm[0m as a [47m:[0m[47m[rewrite][0m rule.  A second possible value of the
  [47m:rewrite[0m argument of [47mdefun-sk[0m is [47m:default[0m, which gives the same
  behavior as when [47m:rewrite[0m is omitted.  Otherwise, the value of
  [47m:rewrite[0m should be the term to use as the body of the [47mfn-necc[0m
  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 [47mdefun-sk[0m may of course be weaker than they would be
  otherwise.  Finally, note that the [47m:rewrite[0m keyword argument for
  [47mdefun-sk[0m only makes sense if the quantifier is [47mforall[0m; it is thus
  illegal if the quantifier is [47mexists[0m.  Enough said about [47m:rewrite[0m!

  In the case that [47mbound-vars[0m is a list of at least two variables, say
  [47m(bv1 ... bvk)[0m, the definition above (with no keywords) is the
  following instead, but the theorem remains unchanged.

    (defun-nx fn (var1 ... varn)
      (mv-let (bv1 ... bvk)
              (skolem-name var1 ... varn)
              term))

  In order to emphasize that the last element of the list, [47mbody[0m, is a
  term, [47mdefun-sk[0m checks that the symbols [47m[forall][0m and [47m[exists][0m do not
  appear anywhere in it.  However, on rare occasions one might
  deliberately choose to violate this convention, presumably because
  [47m[forall][0m or [47m[exists][0m is being used as a variable or because a macro
  call will be eliminating ``calls of'' [47m[forall][0m and [47m[exists][0m.  In
  these cases, the keyword argument [47mquant-ok[0m may be supplied a
  non-[47mnil[0m value.  Then [47mdefun-sk[0m will permit [47m[forall][0m and [47m[exists][0m in
  the body, but it will still cause an error if there is a real
  attempt to use these symbols as quantifiers.

  The use of [47m[defun-nx][0m above, rather than [47m[defun][0m, 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 [defun-nx].  Normally
  that is not a problem, since these notions involve quantifiers.
  But if you prefer that [47m[defun][0m be used instead of [47mdefun-nx[0m, you can
  arrange that using [47m[declare][0m forms, given as the [47mdcl_i[0m as shown
  above.  These will become the [47mdeclare[0m forms in the generated
  [47m[defun][0m.  If the [47m[xargs][0m [declaration] form [47m:non-executable nil[0m is
  supplied, then [47m[defun][0m will be used in place of [47m[defun-nx][0m.

  [Guard] verification is performed for [47mdefun-sk[0m events under the same
  conditions as for [47mdefun[0m events.  (An exception, ignored here but
  discussed in a later paragraph below, occurs when keyword argument
  [47m:constrain t[0m is supplied.)  Thus, by default, guard verification
  will be attempted exactly when at least one of [47mtype[0m, [47m:guard[0m, or
  [47m:verify-guards t[0m is specified in a declaration (that is, in some
  [47mdcl_i[0m.  This default behavior can be modified just as it is for
  [47mdefun[0m; see [47m[set-verify-guards-eagerness][0m.  Technical note: such
  guard verification is implemented through a generated call of
  [47m[verify-guards][0m after the [47mencapsulate[0m that surrounds the
  definitions introduced; use [47m:[0m[47m[trans1][0m to see the expansion.

  [47mDefun-sk[0m is a macro implemented using [47m[defchoose][0m.  Hence, it should
  only be executed in [defun-mode] [47m:[0m[47m[logic][0m; see [defun-mode] and see
  [defchoose].  You can use the command [47m:[0m[47m[pcb!][0m to see the event
  generated by a call of the [47mdefun-sk[0m macro.  If you want to watch
  the subsidiary events (including the [47mdefchoose[0m event) as they are
  being executed, use keyword option [47m:verbose t[0m.

  An advanced feature is argument [47m:strengthen t[0m, which generates the
  extra constraint that is generated for the corresponding [47mdefchoose[0m
  event; see [defchoose].  The name of that generated theorem will be
  obtained by adding the suffix [47m\"-STRENGTHEN\"[0m to the function symbol
  being defined, in the same package.

  If you find that the rewrite rules introduced with a particular use
  of [47mdefun-sk[0m are not ideal, even when using the [47m:rewrite[0m keyword
  discussed above (in the [47mforall[0m case), then at least two reasonable
  courses of action are available for you.  Perhaps the best option
  is to prove the [47m[rewrite][0m rules you want.  If you see a pattern for
  creating rewrite rules from your [47mdefun-sk[0m events, you might want to
  write a macro that executes a [47mdefun-sk[0m followed by one or more
  [47m[defthm][0m events.  Another option is to write your own variant of
  the [47mdefun-sk[0m macro, say, [47mmy-defun-sk[0m, for example by modifying a
  copy of the definition of [47mdefun-sk[0m from the ACL2 sources.

  There is one more keyword argument not explained above: [47m:constrain[0m.
  The default is [47mnil[0m; otherwise this argument must be a symbol, which
  we call [47mname-def[0m, except that in the case of [47mt[0m, [47mname-def[0m is
  obtained by adding the suffix [47m\"-DEFINITION\"[0m to [47mfn[0m.  For a non-[47mnil[0m
  [47m:constrain[0m argument, this [47mname-def[0m is the name of a rule of class
  [47m:[0m[47m[definition][0m that equates [47m(fn var1 ... varn)[0m with the body of the
  definition of [47mfn[0m.  Furthermore, in this case of a non-[47mnil[0m
  [47m:constrain[0m value the definition of [47mfn[0m is local to the surrounding
  [47mencapsulate[0m, which contains a signature for [47mfn[0m.  As usual, the
  simplest way to see the effects of [47m:constrain[0m may be to apply
  [47m:trans1[0m to your [47mdefun-sk[0m form.  Note that constraining the function
  can make it possible to attach to it (see [defattach]) and to
  introduce it as a [guard]-verified function.  Also note that when
  [47m:constrain t[0m is specified: the guard of [47mfn[0m will automatically be [47mt[0m,
  no guard verification will be performed, and [47mfn[0m will nevertheless
  be a guard-verified (and constrained) function.

  If you want to represent nested quantifiers, you can use more than
  one [47mdefun-sk[0m event.  For example, in order to represent

    (forall x (exists y (p x y z)))

  you can use [47mdefun-sk[0m twice, for example as follows.

    (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)))

  Some distracting and unimportant warnings are inhibited during
  [47mdefun-sk[0m.

  Note for ACL2(r) users (see [real]): In ACL2(r), the keyword
  [47m:CLASSICALP[0m is also supported.  Its legal values are [47mt[0m (the
  default) and [47mnil[0m, and it determines whether or not (respectively)
  ACL2(r) will consider [47mfn[0m to be a classical function.  It must be
  the case that the value is [47mt[0m (perhaps implicitly, by default) if
  and only if [47mbody[0m is classical.

  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 [conservativity-of-defchoose] for a technical
  argument that justifies the logical conservativity of the
  [47m[defchoose][0m 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--203).


Subtopics

  [Defun-sk-example]
      A simple example using [47m[defun-sk][0m

  [Exists]
      Existential quantifier

  [Forall]
      Universal quantifier

  [Quantifier-tutorial]
      A Beginner's Guide to Reasoning about Quantification in ACL2

  [Quantifiers]
      Issues about quantification in ACL2"
)
 (DEFUN-SK-EXAMPLE
  (DEFUN-SK)
  "A simple example using [47m[defun-sk][0m

  For a more thorough, systematic beginner's introduction to
  quantification in ACL2, see [quantifier-tutorial].

  The following example illustrates how to do proofs about functions
  defined with [47m[defun-sk][0m.  The events below can be put into a
  certifiable book (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 [47m[defun-sk][0m events.  But it illustrates the
  formulas that are generated by [47m[defun-sk][0m, and how to use them.
  Thanks to Julien Schmaltz for presenting this example as a
  challenge.

    (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))))))))")
 (DEFUND
  (DEFUN EVENTS)
  "Define a function symbol and then disable it

  Use [47mdefund[0m instead of [47m[defun][0m when you want to [disable] a function
  immediately after its definition in [47m:[0m[47m[logic][0m mode.  This macro has
  been provided for users who prefer working in a mode where
  functions are only enabled when explicitly directed by
  [47m:[0m[47m[in-theory][0m.  Specifically, the form

    (defund NAME FORMALS ...)

  expands to the following, except that some output is inhibited for
  the [47m[in-theory][0m event:

    (progn
      (defun NAME FORMALS ...)
      (in-theory (disable NAME))
      (value-triple '(:defund NAME))).

  Only the [47m:[0m[47m[definition][0m rule and, for recursively defined functions,
  the [47m:[0m[47m[induction][0m rule are disabled for the function.  In
  particular, [47mdefund[0m does not disable either the [47m:[0m[47m[type-prescription][0m
  or the [47m:[0m[47m[executable-counterpart][0m rule.

  If the function is defined in [47m:[0m[47m[program][0m mode, either because the
  [default-defun-mode] is [47m:[0m[47m[program][0m or because [47m:mode :program[0m has
  been specified in an [47m[xargs][0m form of a [47m[declare][0m form, then no
  [47m[in-theory][0m event is executed.  (More precisely, [47m[in-theory][0m events
  are ignored when the [default-defun-mode] is [47m:[0m[47m[program][0m, and if
  [47m:mode :program[0m is specified then [47mdefund[0m does not generate an
  [47m[in-theory][0m event.)

  [47mDefund[0m events are generally not redundant, because the generated
  [47m[in-theory][0m event is not redundant.  This default can be changed;
  see [set-in-theory-redundant-okp].

  See [defun] for documentation of [47mdefun[0m."
)
 (DEFUND-INLINE
  (DEFUN EVENTS)
  "Define a potentially disabled, inlined function symbol and associated
  macro

  [47mDefund-inline[0m is a variant of [47m[defun-inline][0m, the difference being
  that [47mdefund-inline[0m disables the newly-defined function symbol.  See
  [defun-inline].")
 (DEFUND-NOTINLINE
  (DEFUN EVENTS)
  "Define a disabled, not-to-be-inlined function symbol and associated
  macro

  [47mDefund-notinline[0m is a variant of [47m[defun-notinline][0m, the difference
  being that [47mdefund-notinline[0m disables the newly-defined function
  symbol.  See [defun-notinline].")
 (DEFUND-NX
  (DEFUN EVENTS)
  "Define a disabled non-executable function symbol

  Use [47mdefund-nx[0m instead of [47m[defun-nx][0m when you want to [disable] the
  definition of a function symbol immediately after defining it in
  [47m:[0m[47m[logic][0m mode.  In all other respects, [47mdefund-nx[0m has the same
  behavior as [47mdefun-nx[0m; See [defun-nx] for details.  Also see
  [defund].")
 (DEFUNS
  (MUTUAL-RECURSION)
  "An alternative to [47m[mutual-recursion][0m

    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)

  is equivalent to

    (MUTUAL-RECURSION
      (DEFUN . defuns-tuple1)
      ...
      (DEFUN . defuns-tuplen))

  In fact, [47mdefuns[0m is the more primitive of the two and
  [47m[mutual-recursion][0m is just a macro that expands to a call of [47mdefuns[0m
  after stripping off the [47m[defun][0m at the [47m[car][0m of each argument to
  [47m[mutual-recursion][0m.  We provide and use [47m[mutual-recursion][0m rather
  than [47mdefuns[0m because by leaving the [47m[defun][0ms in place,
  [47m[mutual-recursion][0m forms can be processed by the Emacs [47mtags[0m
  program.  See [mutual-recursion].")
 (DEFWARRANT
  (APPLY$ ACL2-BUILT-INS)
  "Issue a warrant for a function so [47m[apply$][0m can use it in proofs

  It is best to be somewhat familiar with the documentation of [47m[apply$][0m
  before reading this topic.

  Before using [47mdefwarrant[0m or a utility like [47m[defun$][0m that relies on it:

    (include-book \"projects/apply/top\" :dir :system)

  Several lemmas in that book are necessary for [47mdefwarrant[0m to prove the
  theorems it must prove.


Badges versus Warrants

  It is easy to confuse [badge]s, which are issued by [47m[defbadge][0m, with
  [warrant]s, which are issued by [47mdefwarrant[0m.  See the first section
  of [47m[defbadge][0m for an extended discussion.


Requirements of [47mDefwarrant[0m

    General Form:
    (defwarrant fn)

  where [47mfn[0m is a defined function name.  This command analyzes the body
  of [47mfn[0m 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 [47m(apply$ 'fn
  ...)[0m.  The syntactic conditions include those of [47m[defbadge][0m, which
  [47mdefwarrant[0m essentially invokes if [47mfn[0m is a [47m:[0m[47m[logic][0m mode function
  that is not already badged.  But below we describe all the
  conditions checked by [47mdefwarrant[0m since many users use [47mdefwarrant[0m to
  issue both a badge and a warrant.

  Basic conditions include that [47mfn[0m is in [47m:[0m[47m[logic][0m-mode and that its
  justification (i.e., the measure, well-founded relation, and domain
  predicate used to admit [47mfn[0m) be expressible without any reference to
  [47m[apply$][0m, [47m[ev$][0m, or [47m[apply$-userfn][0m.

  [47mDefwarrant[0m imposes some additional conditions on [47mfn[0m, but exactly what
  those conditions are depends on a certain ``reachability'' test
  detailed in the section titled [31;1mThe ``Reachability'' Test[0m in
  [47m[defbadge][0m.  Roughly speaking the test is whether [47mapply$[0m is
  ancestral in [47mfn[0m, meaning [47mapply$[0m is somehow involved in the
  definition of [47mfn[0m or the functions it calls.

  If the reachability test succeeds --- colloquially, if [47mfn[0m depends on
  [47mapply$[0m --- then [47mdefwarrant[0m imposes the following additional
  conditions in order to issue a warrant.

  [3m(a)[0m If [47mfn[0m is recursive it must not be part of a mutually recursive
  clique and its measure must be of type [47m[natp][0m or be a lexicographic
  combination of natural numbers as defined by the [47mllist[0m function in
  the Community Books at [47mbooks/ordinals/[0m.

  [3m(b)[0m Every function called in the body of [47mfn[0m, except [47mfn[0m itself, must
  already have a [badge] and a warrant.  If some subfunction doesn't
  already have a badge, [47mdefwarrant[0m will call [47m[defbadge][0m and signal an
  error if that fails.  If some subfunction doesn't already have a
  warrant, [47mdefwarrant[0m will signal an error and suggest that you call
  [47mdefwarrant[0m on the offending subfunction first.  [47mDefwarrant[0m will
  continue to fail until all subfunctions have badges and warrants.

  [3m(c)[0m It must be possible for each formal of [47mfn[0m to be assigned one of
  three [ilk]s, [47m:FN[0m, [47m:EXPR[0m, or [47mNIL[0m, as described below.  The basic
  idea is that a formal can be assigned ilk [47m:FN[0m (or ilk [47m:EXPR[0m) iff it
  is sometimes passed into a [47m:FN[0m (or [47m:EXPR[0m) slot in the body of [47mfn[0m
  and is never passed into any other kind of slot.  A formal can be
  be assigned ilk [47mNIL[0m iff it is never passed into a slot of ilk [47m:FN[0m
  or [47m:EXPR[0m, i.e., if it is used as an ``ordinary'' object.  We are
  more precise below.

  [3m(d)[0m Every [47m:FN[0m and [47m:EXPR[0m slot of every function called in the body of
  [47mfn[0m is occupied either by a formal of [47mfn[0m of the same ilk or, in the
  case of calls of functions other than [47mfn[0m, a quoted [tame] function
  symbol or quoted tame (preferably well-formed) [47mLAMBDA[0m object.

  This completes the list of additional restrictions imposed by
  [47mdefwarrant[0m on [47mfn[0m, when [47mapply$[0m is reachable from [47mfn[0m.

  If the reachability test fails --- colloquially, if [47mfn[0m does not
  depend on [47mapply$[0m --- then [47mdefwarrant[0m just checks that [47mfn[0m does not
  call any of a few functions that [47mapply$[0m is prohibited from running.
  Among those blacklisted functions are [47m[sys-call][0m and other
  functions requiring a trust tag.  For a list of the blacklisted
  functions see the value of [47m*blacklisted-apply$-fns*[0m.

  Note that the restrictions imposed on functions from which [47mapply$[0m
  cannot be reached are comparatively generous.  If [47mfn[0m does not
  depend on [47mapply$[0m then [47mfn[0m can be warranted despite (a) being defined
  mutually recursively or with an arbitrary ordinal measure, or (b)
  calling unbadged or unbadgeable functions.  [47mDefwarrant[0m can be
  relaxed in this case because the warrant constrains [47m(apply$ 'fn
  ...)[0m to be [47m(fn ...)[0m and [47mfn[0m is a well-defined [47m:logic[0m mode function
  that is independent of [47mapply$[0m.  Thus, in the model of [47mapply$[0m that
  justifies the whole [47mapply$[0m story, the handling of [47mfn[0m is just a base
  case.  The situation would be more restrictive if the warrant
  constrained [47m(apply$ 'fn ...)[0m to evaluate the body of [47mfn[0m with [47m[ev$][0m
  which would possibly raise termination issues.

  Regardless of whether [47mapply$[0m is reachable, if the requisite
  conditions are not met, [47mdefwarrant[0m causes an error.

  If the requisite conditions are met, [47mdefwarrant[0m obtains or constructs
  the [badge] for [47mfn[0m, setting the arity and out arity appropriately
  and setting the ilks field to the list of computed ilks (or to [47mT[0m if
  every formal has ilk [47mNIL[0m).  The generated badge is stored for the
  future use of [47mdefwarrant[0m.  See [47m[defbadge][0m for a brief discussion of
  how ilks are computed.

  Furthermore, [47mdefwarrant[0m generates the [47m[warrant][0m for [47mfn[0m.  The name of
  that 0-ary function will be [47mAPPLY$-WARRANT-fn[0m.  Calls of [47m[apply$][0m
  on [47m'fn[0m in proof attempts can only be simplified if the warrant
  hypothesis, [47m(APPLY$-WARRANT-fn)[0m, [3maka[0m ``the warrant,'' is among the
  hypotheses of the conjecture being proved.  The warrant specifies
  the values of both [47m(badge 'fn)[0m and [47m(apply$ 'fn ...)[0m, including the
  tameness requirements imposed on [47mapply$[0m.  (The warrant explicitly
  specifies the values of [47m[badge-userfn][0m and [47m[apply$-userfn][0m and then
  [47m[defwarrant][0m proves rewrite rules to make calls of [47mbadge[0m and [47mapply$[0m
  simplify accordingly.)

  If a warrant is issued for [47mfn[0m, then [47mdefwarrant[0m 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 [47mbadge[0m
  and [47mapply$[0m to be evaluated in the evaluation theory (but not in the
  proof theory).  See [47m[warrant][0m for details.

  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.  [3mThere is a model of
  [47mapply$[0m[3m and all of its [47m[scion][0m[3ms that makes every warrant issued by
  [47mdefwarrant[0m[3m valid.[0m The proof of this is sketched in {``Limited
  Second-Order Functionality in a First-Order Setting'' |
  http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by
  Matt Kaufmann and J Strother Moore and fully fleshed out in the
  comment titled [47mEssay on Admitting a Model for Apply$ and the
  Functions that Use It[0m in the ACL2 source file [47mapply-raw.lisp[0m.

  [47mDefwarrant[0m also proves that [47m[fn-equal][0m is a congruence relation for
  each [47m:FN[0m position of [47mfn[0m.


Subtopics

  [Fn-equal]
      Equivalence relation on tame functions")
 (DELETE-ASSOC
      (ALISTS ACL2-BUILT-INS)
      "Deprecated version of [remove1-assoc]

  See [remove1-assoc].")
 (DELETE-FILE$
  (IO)
  "Delete a file

  This analogue of the Common Lisp function, [47mdelete-file[0m, uses that
  function under the hood to delete a given file.  It returns [47m(mv t
  state)[0m if deletion succeeds and [47m(mv nil state)[0m otherwise.  The
  [47m[guard][0m of [47mdelete-file$[0m requires that the first argument is a
  string; the second argument is the ACL2 [47m[state][0m.  The logical
  definition does not actually look at the file and hence is not
  useful for reasoning.

  [31;1mFunction: [0m<delete-file$>

    (defun delete-file$ (file state)
      (declare (xargs :guard (stringp file)
                      :stobjs state))
      (declare (ignore file))
      (mv-let (erp val state)
              (read-acl2-oracle state)
        (declare (ignore val))
        (mv (null erp) state)))")
 (DELETE-INCLUDE-BOOK-DIR
  (BOOKS-REFERENCE)
  "Unlink keyword for [47m:dir[0m argument of [47m[ld][0m and [47m[include-book][0m

    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)

  where [47mkwd[0m is a [47m[keywordp][0m.  The effect of this event is to modify the
  meaning of the [47m:dir[0m keyword argument of [47m[include-book][0m and [47m[ld][0m as
  indicated by the example above, namely by removing association of a
  directory with the indicated keyword for purposes of the [47m:dir[0m
  argument of [47m[include-book][0m and [47m[ld][0m.  See [47m[add-include-book-dir][0m
  for how to associate a new directory with a keyword.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

  This macro is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs; see [add-include-book-dir] for a discussion of
  this aspect of both macros.  For non-local associations of keywords
  with directories, see [add-include-book-dir!] and
  [delete-include-book-dir!].  Note that [47mdelete-include-book-dir[0m may
  only be used to remove keywords added by calls of
  [47m[add-include-book-dir][0m, and [47m[delete-include-book-dir!][0m may only be
  used to remove keywords added by calls of [47m[add-include-book-dir!][0m")
 (DELETE-INCLUDE-BOOK-DIR!
  (BOOKS-REFERENCE)
  "Non-[47m[local][0mly unlink keyword for [47m:dir[0m argument of [47m[ld][0m and
  [47m[include-book][0m

  Please see [delete-include-book-dir], which has completely analogous
  syntax and semantics, but is used for removing associations
  previously placed by [47m[add-include-book-dir][0m.  By contrast,
  [47mdelete-include-book-dir![0m removes associations previously placed by
  [47m[add-include-book-dir!][0m.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

  This macro is essentially a [47m[table][0m event that updates the table
  [47minclude-book-dir!-table[0m, which associates keywords with absolute
  pathnames.  However, as with [47m[delete-include-book-dir][0m, direct
  table updates are disallowed; you must use [47mdelete-include-book-dir![0m
  to remove from the table and [47m[add-include-book-dir!][0m to add to the
  table.

  It is illegal to call [47mdelete-include-book-dir![0m in a [47m[local][0m context.
  For an explanation, see [add-include-book-dir!].")
 (DENOMINATOR
  (NUMBERS ACL2-BUILT-INS)
  "Divisor of a ratio in lowest terms

  Completion Axiom ([47mcompletion-of-denominator[0m):

    (equal (denominator x)
           (if (rationalp x)
               (denominator x)
             1))

  [Guard] for [47m(denominator x)[0m:

    (rationalp x)")
 (DF
  (NUMBERS ACL2-BUILT-INS)
  "Support for floating-point operations

  ACL2 supports computation that uses floating-point operations.  The
  basic arithmetic operations ([47m+[0m, [47m-[0m, [47m*[0m, and [47m/[0m) 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.

  All floating-point computations performed by Common Lisp for ACL2 use
  [3mdouble-floats[0m, that is, double-precision floating-point numbers.
  Computation with other precisions (including single-precision) is
  not supported by ACL2.

  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 [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.)

  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
  [community-book], [47mbooks/demos/floating-point-input.lsp[0m.  We
  conclude in Section 9 with remarks for system programmers.

  This topic is written for ACL2 users.  Implementation-level remarks
  for developers may be found in a comment in the ACL2 sources
  entitled ``Essay on Support for Floating-point (double-float, df)
  Operations in ACL2''.


Section 1: Introduction

  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 [3mdf expressions[0m, or [3mdfs[0m for short.  ACL2 may also say
  that such an expression ``returns a result of shape :DF''.

  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
  [3mrepresentable[0m 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 [47m(to-df 3/2)[0m is provably equal to the
  constant 3/2 in the logic, even though evaluation of [47m(to-df 3/2)[0m 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.

    (defun f1 (x)
      (declare (type double-float x))
      (df- x))

  ACL2 admits this definition so that [47mf1[0m is a [guard]-verified
  function.  The operation [47mdf-[0m is essentially just the negative
  operation ([47m-[0m), except that [47mdf-[0m is to be applied only to df
  expressions; this is enforced based on the [47mdouble-float[0m type
  declaration.  Let's look at what happens when we [trace] [47mf1[0m;
  discussion follows.  In the following example, [47mf1[0m is applied to the
  df expression [47m(to-df 3/2)[0m; the expression [47m(f1 3/2)[0m would be illegal
  for top-level evaluation because, as noted above, [47mf1[0m expects a df
  expression,

    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 !>

  Initially, the function [47mto-df[0m is applied to 3/2.  The result is
  logically still 3/2, not 1.5, because the [3mexecutable-counterpart[0m
  for [47mto-df[0m returns an ACL2 value, not a Common Lisp value.  (See
  [evaluation] for background on executable-counterparts and
  corresponding raw Lisp functions.)  Then 3/2 is passed to the
  executable-counterpart for [47mf1[0m.  The [guard] of [47mf1[0m holds on 3/2
  (we'll discuss guards later), so evaluation passes from the
  executable-counterpart for [47mf1[0m to the raw Lisp function for [47mf1[0m after
  converting 3/2 to a Common Lisp double-precision floating-point
  number, 1.5.  Then [47mdf-[0m, which is essentially just [47m-[0m in raw Lisp, is
  applied to obtain -1.5, which is returned by raw-Lisp [47mf1[0m.  Then the
  executable-counterpart for [47mf1[0m converts -1.5 to the corresponding
  ACL2 object, the rational -3/2, which is ultimately returned to the
  top-level loop.

  Remark.  The astute reader may have noticed that the
  executable-counterpart for [47mto-df[0m did not call the raw Lisp function
  for [47mto-df[0m.  That is because [47mto-df[0m is actually a macro in raw Lisp.


Section 2: Challenges for supporting floating-point operations in
ACL2

  In this section we motivate ACL2 restrictions pertaining to
  floating-point numbers, which are addressed in the section after
  this one.

  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 [evaluation] of
  [guard]-verified code.

  [31;1mProblem #1[0m: Addition isn't associative on floating-point numbers.

  We see that immediately with the following raw Lisp examples.

    ? (+ 0.1 (+ 0.2 0.3))
    0.6
    ? (+ (+ 0.1 0.2) 0.3)
    0.6000000000000001
    ?

  Yet ACL2 has the following axiom.

  [31;1mDefinition: [0m<associativity-of-+>

    (defaxiom associativity-of-+
      (equal (+ (+ x y) z) (+ x (+ y z))))

  So we can't simply apply [47m+[0m to floating-point numbers in ACL2, because
  [guard]-verified code leads to raw Lisp computations that would
  violate this axiom.

  [31;1mProblem #2[0m: Functions [47mEQUAL[0m and [47m=[0m are logically the same in ACL2 but
  not in raw Lisp.

  The following succeeds.

    (thm (equal (equal x y)
                (= x y)))

  Yet the following log shows that raw Lisp can violate that property
  if we allow double-floats.  (In Common Lisp, [47m=[0m compares numeric
  values while [47mEQUAL[0m distinguishes between rationals and floats and
  even between floating-point numbers 0.0 and -0.0.)

    ? (equal 1 1.0)
    NIL
    ? (= 1 1.0)
    T
    ? (equal 0.0 (- 0.0))
    NIL
    ? (= 0.0 (- 0.0))
    T
    ?


Section 3: How the challenges are addressed

  The following three principles guide support for floating-point
  computations in ACL2.

    * (A) Treat floating-point values as rationals.

    * (B) Put syntactic limitations on floating-point operations.

    * (C) Use [partial-encapsulate] to axiomatize floating-point operations
      while supporting evaluation.

  Let's look at these in turn.

  [31;1m(A) Treat floating-point values as rationals.[0m

  The ACL2 logic does not include floating-point numbers.  Rather,
  certain rational numbers can be [3mrepresented by[0m double-precision
  floating-point numbers, known as double-floats, during
  computations.  We can say that a double-float [3mrepresents[0m a
  corresponding rational number.  Certain expressions denote such
  [3mrepresentable[0m rational numbers.  Those are called [3mdf expressions[0m
  and we say more about them in our discussion of (B), below.

  The predicate [47mdfp[0m 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 [47m1.01100 * 2^30[0m.  For example, 1/4 is representable but
  1/3 is not.

    ACL2 !>(dfp 1/4) ; represented by the double-float, 0.25d0
    T
    ACL2 !>(dfp 1/3) ; not represented by a double-float
    NIL
    ACL2 !>

  ACL2 provides [47m#d[0m notation (see [sharp-d-reader]) as a way to read
  floating-point notation as a representable rational, illustrated as
  follows.

    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
    ?

  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.

  [31;1m(B) Put syntactic limitations on floating-point operations.[0m

  Here we briefly discuss syntactic restrictions based on the notion
  mentioned above of [3mdf expression[0m, or [3mdf[0m 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.

  Let us return to the following example.  It uses [47mdf-[0m, which is the
  negative operation on dfs; that is, [47m(df- x)[0m is analogous to [47m(- x)[0m,
  but [47mdf-[0m operates on a df and returns a df.

    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 !>

  Notice the signature shown above for [47mf1[0m:

    (F1 :DF) => :DF

  This means that the input of [47mf1[0m must be a df expression and [47mf1[0m
  returns a df expression.  ACL2 determines that the input must be a
  df by virtue of the declaration, [47m(type double-float x)[0m.  Calls of
  [47mf1[0m are determined to be dfs because the body of [47mf1[0m, [47m(df- x)[0m, 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 [stobj]s may notice some similarity to
  the syntactic restrictions on stobjs.

  The following example illustrates the requirement that the input of
  [47mf1[0m be a df.

    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 !>

  That error can be avoided by converting the input (a rational
  constant) to a suitable df using the primitive, [47mto-df[0m (discussed
  later).

    ACL2 !>(f1 (to-df 3))
    #d-3.0
    ACL2 !>

  Notice that the result is displayed using [47m#d[0m notation.  But remember
  that there are no actual floating-point objects in ACL2; [47mf1[0m returns
  a rational logically, namely -3.  However, since the input
  expression is a df, ACL2 prints the evaluation result using [47m#d[0m
  notation.  (This is analogous to the special printing of [47m<state>[0m
  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: [47m(thm (equal (f1
  (to-df 3)) -3))[0m.

  The tracking of dfs avoids Problem #1 above, that addition isn't
  associative on floating-point numbers.  That's because ACL2 does
  not allow [47m+[0m to be applied to a df, as illustrated by the following
  example, which complains that the [47m+[0m operation is being supplied a
  df, namely the call of [47mf1[0m.  The notion ``a result of shape :DF'' is
  synonymous with ``df''.

    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 !>

  There is however an operation [47mdf+[0m that can be applied to [47m:DF[0m
  expressions.

    ACL2 !>(df+ (to-df 5) (f1 (to-df 3)))
    #d2.0
    ACL2 !>

  In fact [47mdf+[0m automatically converts its arguments satisfying [47mdfp[0m to be
  dfs, so the following is also legal since [47m5[0m is converted to [47m(to-df
  5)[0m.

    ACL2 !>(df+ 5 (f1 (to-df 3)))
    #d2.0
    ACL2 !>

  But [47mdf+[0m is not associative; the following fails, as it should.

    (thm ; FAILS!
     (implies (and (dfp x) (dfp y) (dfp z))
              (equal (df+ (df+ x y) z)
                     (df+ x (df+ y z)))))

  We return now to Problem #2, that the functions [47mEQUAL[0m and [47m=[0m are
  logically the same in ACL2 but not in raw Lisp, as seen by
  evaluation in raw Lisp, where [47m(equal 1 1.0)[0m evaluates to [47mnil[0m but [47m(=
  1 1.0)[0m evaluates to [47mt[0m.  This problem is avoided by our syntactic
  tracking of df expressions.  The following example shows that [47mequal[0m
  cannot be called on a df expression.

    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 !>

  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.)

    ACL2 !>(df= (df+ #d1.2 #d3.4) (df+ #d3.4 #d1.2))
    T
    ACL2 !>

  [31;1m(C) Use [partial-encapsulate] to axiomatize floating-point operations
  while supporting evaluation.[0m

  Next we consider how ACL2 introduces the [3mdf primitives[0m, 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 {relevant quote
  from the Common Lisp HyperSpec |
  http://www.lispworks.com/documentation/lw71/CLHS/Body/v_featur.htm}
  about the presence of a raw Lisp ``feature'', [47m:ieee-floating-point[0m.

    If present, indicates that the implementation purports to conform to
    the requirements of IEEE Standard for Binary Floating-Point
    Arithmetic.

  ACL2 checks at build time that this feature is present.  However,
  that IEEE standard specifies results of operations with respect to
  a [3mrounding mode[0m.  Probably most or all Common Lisp implementations
  use [3mround to nearest even[0m as their rounding mode, but this is not
  guaranteed.  We work around this problem to some extent by
  introducing a constrained rounding function, [47mdf-round[0m, and using it
  to define the rational function primitives: addition ([47mdf+[0m),
  subtraction ([47mdf-[0m), multiplication ([47mdf*[0m), and division ([47mdf/[0m).
  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,
  [47mdf-sin[0m.  Over time some of those constraints may be strengthened,
  or they may even be replaced by definitions in terms of [47mdf-round[0m.

  Even though the df primitives are constrained (except for the
  rational primitive functions, which are defined in terms of the
  constrained function [47mdf-round[0m), ACL2 can evaluate their calls, even
  during proofs.  This is arranged by introducing them with
  [47m[partial-encapsulate][0m, which allows some of the constraints to be
  implicit; see [47m[partial-encapsulate][0m.  The implicit constraints are
  based on computation; for example, when ACL2 admits the event [47m(thm
  (equal (df-sin 0) 0))[0m, an implicit constraint guarantees [47m(equal
  (df-sin 0) 0)[0m.  There are also explicit constraints, which for
  example allow ACL2 to prove [47m(dfp (df-sin x))[0m.  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
  [47mpartial-encapsulate[0m event that introduces [47mdf-round[0m in ACL2 source
  file [47mfloat-a.lisp[0m.

  ACL2 arranges for the host Lisp to evaluate calls of df primitives in
  [guard]-verified) and [47m:[0m[program]-mode code.  For example, such
  evaluation of a [47mdf-sin[0m call leads to a call of [47msin[0m in Common Lisp.
  The following log illustrates this point and is discussed below.

    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 !>

  We see at ``[47m1>[0m'' that evaluation arranged to pass a (representable)
  rational number (roughly, \\pi/2) to the executable-counterpart for
  [47mf2[0m (again, for relevant background see [evaluation]).  But at
  ``[47m2>[0m'', where evaluation was passed to the raw Lisp function for
  [47mf2[0m, that rational value was converted to the corresponding
  double-float value, which raw Lisp evaluation passed to the Common
  Lisp function [47msin[0m, at ``[47m3>[0m''.  Common Lisp then returned 1.0 for
  the raw Lisp applications of [47msin[0m and [47mf2[0m, so that finally, the
  executable-counterpart for [47mf2[0m returned the rational number, 1.
  That value was displayed using [47m#d[0m notation because a call of [47mf2[0m is
  a df.

  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.

    When a collection of books is certified (see [certify-book]), the
    same environment --- in particular the Lisp implementation and
    operating system --- should be used for all of these books, even
    those included during certification.

  Otherwise there is a soundness issue.  One might prove, say, [47m(equal
  (df-sin 1) A)[0m and [47m(equal (df-sin 1) B)[0m for distinct (but close by)
  numeric values [47mA[0m and [47mB[0m in two different books, certified with ACL2
  executables built on different Lisps, and then include those two
  books to prove a contradiction.


Section 4: Syntactic Restrictions

  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
  [47mtranslate11[0m: a df is an expression whose translation is made with
  stobjs-out equal to [47m(:DF)[0m, and the arguments of a function call are
  those in a [47m:DF[0m position with respect to that function symbol's
  stobjs-in.)

  These syntactic restrictions are not applied in theorem and
  non-executable contexts, in particular not within [defthm], [thm],
  and [47m[defun-nx][0m events and not within a call of [47m[non-exec][0m.  Below
  we focus on restrictions for a [47m[defun][0m event, including its body,
  guard, and measure; but these restrictions also apply to [47m[defmacro][0m
  events, [47m[defconst][0m events, and top-level evaluation.

  Certain variables may be specified as dfs at the top level in the
  case of [47mdefun[0m events but not in other cases.  For a [47mdefun[0m event,
  the [3mdeclared dfs[0m consist of all variables [47mvi[0m listed either in a
  [47m[declare][0m form [47m(type double-float v1 ... vk)[0m or an [47m[xargs][0m
  declaration [47m:dfs (v1 ... vk)[0m.  If [47mk[0m is [47m1[0m then one may write [47m:dfs v1[0m
  to abbreviate [47m:dfs (v1)[0m.  These declared dfs are the [3mknown df
  variables[0m at the top level of the user-supplied body, guard, and
  measure of [47mf[0m.  The rules below indicate, for a set [47mV[0m of known df
  variables, when an expression is a df with respect to [47mV[0m; and these
  rules also speak to legality of certain expressions.

  Before presenting those rules, we extend the notion of a df
  expression (again, df for short) to that of a [3mdf{i} expression[0m
  ([3mdf{i}[0m 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 [47m(mv (to-df x) (df- y) 17)[0m 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.

  Here are the rules promised above.  They are not complete; for
  example, they do not cover [47m[stobj-let][0m expressions.  But those and
  other cases should present no surprises in practice.  Let [47mu[0m be a
  user-supplied term (that is, an [3muntranslated[0m term; see [term]).

    * If [47mu[0m is a variable, then [47mu[0m is a df with respect to [47mV[0m if and only if
      it is in [47mV[0m.

    * If [47mu[0m is a constant symbol then it is not a df (with respect to any
      set).

    * If [47mu[0m is a [47m[lambda][0m expression, then [47mu[0m is a df with respect to [47mV[0m if
      and only if the corresponding [47m[let][0m expression is a df with
      respect to [47mV[0m.

    * If [47mu[0m is a macro call [47m(m t1 ... tn)[0m, then [47mu[0m is a df with respect to [47mV[0m
      if and only if the single-step macroexpansion of [47mu[0m is a df with
      respect to [47mV[0m.

    * Suppose [47mu[0m is the term [47m(f t1 ... tn)[0m where [47mf[0m is a function symbol.  It
      is required that [47mti[0m is a df with respect to [47mV[0m if and only if
      the [47mi[0mth formal of [47mf[0m is a declared df of [47mf[0m.  An exception to
      that requirement is when [47mf[0m is [47mdfp[0m, in which case the only
      restriction on [47mt1[0m is that it is not a stobj name.  If [47mf[0m returns
      a single value then [47mu[0m is a df (respectively, df{i}) with
      respect to [47mV[0m if and only if the body of [47mf[0m is a df
      (respectively, df{i}) with respect to [47mV[0m.

    * Consider [47m(let ((x1 e1) ... (xk ek)) dcl1 ... dclm body)[0m.  The rules
      apply to each [47mei[0m with respect to [47mV[0m, but for [47mbody[0m the rules
      apply with respect to the following new set of known dfs.
      First, remove all [47mxi[0m from [47mV[0m except when [47mxi[0m is declared as a df
      in one of the [47mdcli[0m with a [47mdouble-float[0m type declaration.  For
      any [47mxi[0m not so declared, ACL2 guesses whether or not [47mei[0m is a df
      with respect to [47mV[0m.  If the guess is ``yes'' then add [47mxi[0m as a
      known df, and if the guess is ``no'' 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) [47mei[0m as a non-df and, if that fails, it
      treats [47mei[0m 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.)

    * For [47m(mv-let (x1 ... xk) mv-expr dcl1 ... dclm body)[0m, the rules apply
      to [47mmv-expr[0m and to [47mbody[0m, but for [47mbody[0m the known dfs are modified
      as follows.  ACL2 attempts to determine those i <= k for which
      [47mmv-expr[0m is a df{i} expression.  (Optional technical note for
      those familiar with ACL2 source function [47mtranslate11[0m: ACL2
      attempts to determine suitable stobjs-out for translation of
      [47mmv-expr[0m.)  Then to obtain the known dfs for [47mbody[0m, each [47mxi[0m is
      initially removed from [47mV[0m except for those [declare]d in some
      [47mdcli[0m as having type [47mdouble-float[0m, and then those [47mxi[0m for which
      [47mmv-expr[0m is a df{i} expression are added back as known dfs for
      translation of [47mbody[0m.

  Note that ACL2 features that naturally traffic in ordinary ACL2
  values may disallow uses of df expressions (much as they disallow
  uses of [stobj]s).  Here are a few examples.

    * A [table] guard must return an ordinary value, not a df.

    * A [clause-processor] must return an ordinary value (and perhaps
      stobjs in the multiple-values case; see [clause-processor]).

    * A [theory] expression, as well as the argument of [47m[defconst][0m,
      [47m[defpkg][0m, [47m[syntaxp][0m, or [47m[bind-free][0m, must return an ordinary
      value, not a df.


Section 5: Guards

  When a [47m[defun][0m event defines a function, the [guard] for that
  function asserts that [47mdfp[0m holds for each declared df.  Here's an
  example

    (defun df-10/x (x)
      (declare (xargs :guard (not (df= 0 x))
                      :dfs x))
      (df/ 10 x))

  The generated guard is [47m(and (dfp x) (not (df= 0 x)))[0m.  Note that [47m(dfp
  x)[0m precedes [47m(not (df= 0 x))[0m: the conjuncts generated from the [47m:dfs[0m
  always precede those that come from [47m:guard[0m specifications.

  Instead of specifying declared dfs using [47m:dfs[0m [47m[xargs][0m, a better
  approach (see Section 7: Remarks on performance) is to use
  [47mdouble-float[0m [47m[type][0m declarations.  Here's a variant of the example
  above that uses this approach; it too is admitted by ACL2.

    (defun df-10/x (x)
      (declare (xargs :guard (not (df= 0 x)))
               (type double-float x))
      (df/ 10 x))

  Technical remark (feel free to skip it).  There is a subtlety here.
  Unlike [47m:dfs[0m specifications, any [type] declarations are conjoined
  with [47m:guard[0m specifications in the order of appearance of each.
  (This is a general aspect of ACL2, not specific to [47mdouble-float[0m
  types.)  So in the example above, the guard is essentially [47m(and
  (not (df= 0 x)) (dfp x))[0m.  It may be surprising that [47m(df= 0 x)[0m can
  itself be guard-verified without the assumption of [47m(dfp x)[0m.  The
  reason is that ACL2 figures out that [47mx[0m is a declared df, and
  deduces that since this is legal code, we know that [47m(dfp x)[0m is
  true.


Section 6: Df primitives

  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.

    * Recognizers and conversion functions

    * Basic arithmetic operations

    * Other operations

  In each case, we display a function's signature (as in the example of
  [47mf2[0m above) and describe its functionality.  You can of course use
  [47m:[0m[47m[pe][0m to see its logical definition.

  But first we discuss a class of convenient macros.

  [4mCorresponding df-friendly macros[0m

  Before we document the df primitive functions, we describe
  corresponding macros that automatically convert certain constants
  to df expressions by using a [47mto-df[0m wrapper.  We call such a macro
  the ``corresponding df-friendly macro'' for the given function.
  Below, we show how that works for [47mbinary-df+[0m and its corresponding
  df-friendly macro, [47mdf+[0m.  The same relationship holds for other df
  primitive functions and their corresponding df-friendly macros.

  Consider the following examples of adding two dfs with the function
  [47mbinary-df+[0m.

    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 !>

  The arguments to [47mbinary-df+[0m must be dfs, so it is illegal to remove
  any call of [47mto-df[0m above.  For example, all of the following cause
  errors.

   1. [47m(binary-df+ 3 1/2)[0m [3m; 3 and 1/2 are not dfs[0m

   2. [47m(let ((x (to-df 3))) (binary-df+ x 1/2))[0m [3m; 1/2 is not a df[0m

   3. [47m(let ((x 3)) (binary-df+ x (to-df 1/2)))[0m [3m; x is not a df[0m

  However, [47mbinary-df+[0m has a corresponding df-friendly macro, [47mdf+[0m.  That
  macro expands to a call of [47mbinary-df[0m with a call of [47mto-df[0m wrapped
  around every constant numeric argument that satisfies [47mdfp[0m.  The
  following calls show expansions of [47mdf+[0m calls that correspond to
  calls from the first two examples above.

    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 !>

  So, evaluation succeeds for those two uses of [47mdf+[0m in place of
  [47mbinary-df+[0m.

    ACL2 !>(df+ 3 1/2)
    #d3.5
    ACL2 !>(let ((x (to-df 3))) (df+ x 1/2))
    #d3.5
    ACL2 !>

  The third example still fails, however, since [47mdf+[0m only wraps [47mto-df[0m
  around constants.

    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 !>

  Note that a constant value is only supplied a [47mto-df[0m wrapper when it
  satisfies [47mdfp[0m, that is, it is a representable rational, as
  illustrated by the following example.

    ACL2 !>:trans1 (df+ 1/3 1/4)
     (BINARY-DF+ 1/3 (TO-DF 1/4))
    ACL2 !>

  The focus above has been on numeric constants, but symbolic constants
  that start and end with the `[47m*[0m' character, like [47m*c*[0m, are treated
  somewhat similarly.  Such an argument of a df-friendly macro is
  given a [47mto-df[0m wrapper as well as an assertion that [47mdfp[0m holds.
  Suppose for example that we submit the following two events.

    (defconst *good* 1/4) ; 1/4 satisfies dfp.
    (defconst *bad* 1/3)  ; 1/3 does not satisfy dfp.

  Here is how those arguments are treated when supplied to a
  df-friendly macro.

    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 !>

  Indeed, evaluation of [47m(df+ *good* *bad*)[0m results in an assertion
  failure.

    HARD ACL2 ERROR in ASSERT$:  Assertion failed:
    (ASSERT$ (DFP C) (TO-DF C))

  But logically, [47m[assert$][0m returns its second argument, so ACL2 can
  prove the following.

    (equal (df+ *good* *bad*)
           (binary-df+ *good* (to-df *bad*)))

  [4mRecognizers and conversion functions[0m

  [47m(from-df :DF) => *[0m
  Converts a df to a numerically equivalent ordinary value.

  [47m(to-df *) => :DF[0m
  Converts an ordinary value to a nearby df.  This is the identity on
  any rational that is representable by a floating-point number.

  [47m(to-dfp *) => *[0m
  This is logically the same as [47mto-df[0m, but it returns an ordinary
  value rather than a df.

  [47m(dfp {* or :DF}) => *[0m
  Recognizes rationals that can be represented by Lisp double-floats;
  so, always true when applied to a df.  The logical definition of
  [47m(dfp x)[0m is [47m(and (rationalp x) (= (to-df x) x))[0m.

  [47m(df-round *) => *[0m
  Constrained, non-executable rounding function, which converts a
  rational to a nearby value that satisfies [47mdfp[0m.  It is used in the
  definitions of the basic arithmetic operations.

  [47m(df-string :DF) => *[0m
  Produces the floating-point representation, as a string, of the
  given df value.  Examples:

    ACL2 !>(df-string (to-df 1/4))
    \"0.25\"
    ACL2 !>(df-string (to-df 1/3))
    \"0.3333333333333333\"
    ACL2 !>

  [47m(df-rationalize-fn :DF) => *[0m
  Calls the Common Lisp function, [47mrationalize[0m, which the Common Lisp
  HyperSpec says ``returns a rational that approximates the float to
  the accuracy of the underlying floating-point representation.'' The
  idea is to produce a ``pretty'' rational that approximates the
  given df, as illustrated by the following example.

    ACL2 !>(from-df (to-df 1/10))
    3602879701896397/36028797018963968
    ACL2 !>(df-rationalize (to-df 1/10))
    1/10
    ACL2 !>

  [47m(rize *) => *[0m
  This is a variant of [47mdf-rationalize[0m that operates on rationals
  instead of dfs, as shown by the following extension of the example
  just above.

    ACL2 !>(rize 3602879701896397/36028797018963968)
    1/10
    ACL2 !>

  [4mBasic arithmetic operations[0m

  [47m(binary-df+ :df :df) => :df[0m
  Adds the two given dfs.
  Corresponding df-friendly macro: [47m(df+ x y )[0m

  [47m(binary-df* :df :df) => :df[0m
  Multiplies the two given dfs.
  Corresponding df-friendly macro: [47m(df* x y )[0m

  NOTE: Both [47mdf+[0m and [47mdf*[0m are binary, unlike [47m+[0m and [47m*[0m.  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.

    ? (+ .1 .2 .3)
    0.6000000000000001
    ? (+ .1 (+ .2 .3))
    0.6
    ?

  [47m(binary-df/ :df :df) => :df[0m
  Divides the two given dfs, where the second should be non-zero.
  Corresponding df-friendly macro: [47m(df/ x y )[0m

  [47m(unary-df- :df) => :df[0m
  Takes the negative of the given df.
  Corresponding df-friendly macro: [47m(df- x)[0m

  [47m(unary-df/ :df) => :df[0m
  Takes the reciprocal of the given non-zero df.
  Corresponding df-friendly macro: [47m(df/ x)[0m

  Also provided is a binary version of the macro [47mdf-[0m.  The expansion of
  [47m(df- term1 term2)[0m is essentially [47m(df+ term1 (df- term2))[0m.

  These functions are all defined by applying [47mdf-round[0m to the exact
  mathematical result.  Here are their definitions in the ACL2 logic.

  [31;1mFunction: [0m<binary-df+>

    (defun binary-df+ (x y)
      (declare (xargs :guard (and (dfp x) (dfp y))))
      (df-round (+ x y)))

  [31;1mFunction: [0m<binary-df*>

    (defun binary-df* (x y)
      (declare (xargs :guard (and (dfp x) (dfp y))))
      (df-round (* x y)))

  [31;1mFunction: [0m<binary-df/>

    (defun binary-df/ (x y)
      (declare (xargs :guard (and (dfp x) (dfp y) (not (= y 0)))))
      (df-round (/ x y)))

  [31;1mFunction: [0m<unary-df->

    (defun unary-df- (x)
      (declare (xargs :guard (dfp x)))
      (df-round (- x)))

  [31;1mFunction: [0m<unary-df/>

    (defun unary-df/ (x)
      (declare (xargs :guard (and (dfp x) (not (= x 0)))))
      (df-round (/ x)))

  We include the following as a basic arithmetic operation (though some
  may argue with that classification).

  [47m(df-abs-fn :df) => :df[0m
  Return the absolute value of the df input, as a df.
  Corresponding df-friendly macro: [47m(df-abs x)[0m

  [4mOther operations[0m

  These are listed alphabetically.  They include the square root
  function and common transcendental functions.  The first two are
  logarithm functions.

  [47m(binary-df-log :df :df) => :df[0m
  Takes the log, where the first argument is the base.
  Corresponding df-friendly macro: [47m(df-log x y)[0m

  [47m(unary-df-log :df) => :df[0m
  Takes the natural log (log base [47me[0m) of the given df.
  Corresponding df-friendly macro: [47m(df-log x)[0m

  The following zero-ary functions return floating-point constants.

  [47m(df-pi) => :df[0m
  Returns a df approximation to \\pi.
  The constant [47m*df-pi*[0m is defined to be the corresponding rational:
  [47m(defconst *df-pi* (from-df (df-pi)))[0m.

  [47m(df0) => :df[0m
  Returns a df logically equal to 0.

  [47m(df1) => :df[0m
  Returns a df logically equal to 1.

  [47m(df-minus-1) => :df[0m
  Returns a df logically equal to -1.

  The remaining functions are listed in alphabetic order.  Each has a
  name of the form [47mdf-NAME-fn[0m where [47mNAME[0m is the name of a
  corresponding Common Lisp function.  Each takes a df argument
  except for [47mexpt[0m, which takes two df arguments, and each returns a
  df argument.  The guards require not only [47mdfp[0m of each argument but
  the extra conditions as shown below.  Each has a corresponding
  df-friendly macro, [47mdf-NAME[0m.

* [47m(df-acos-fn x)[0m ; guard extra: [47m(df<= (df-abs-fn x) 1)[0m

* [47m(df-acosh-fn x)[0m

* [47m(df-asin-fn x)[0m

* [47m(df-asinh-fn x)[0m

* [47m(df-atan-fn x)[0m

* [47m(df-atanh-fn x)[0m ; guard extra: [47m(df< (df-abs x) 1)[0m

* [47m(df-cos-fn x)[0m

* [47m(df-cosh-fn x)[0m

* [47m(df-exp-fn x)[0m

* [47m(df-expt-fn x y)[0m ; guard extra: [47m(or (df< 0 x) (and (df= 0 x) (df< 0
y)))[0m

* [47m(df-sin-fn x)[0m

* [47m(df-sinh-fn x)[0m

* [47m(df-sqrt-fn x)[0m ; guard extra: [47m(df<= 0 x)[0m

* [47m(df-tan-fn x)[0m ; guard extra: [47m(not (df= (df-cos-fn x) 0))[0m

* [47m(df-tanh-fn x)[0m ; guard extra: [47m(not (df= (df-cosh-fn x) 0))[0m


Section 7: Remarks on performance

  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.

  [4mInlining of df primitives[0m

  Suppose we start ACL2 and then submit the following forms, which
  define [47mg1[0m in raw Lisp and provide its assembly code.

    (defun g1 (x y) (declare (type double-float x y)) (df< x y))
    (disassemble 'g1)

  If we repeat this experiment in a new ACL2 session except that we
  replace [47mdf<[0m with [47m<[0m, 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 [47mdf<[0m.
  To understand why, first observe that macroexpansion replaces [47mdf<[0m
  by [47mdf<-fn[0m; then observe that the ACL2 sources include a [47mdeclaim[0m
  form that declares [47mdf<-fn[0m to be inline.  All the df primitive
  functions are similarly declared inline except for [47mto-df[0m, which we
  discuss next.  Of course, these inlined raw Lisp functions (and
  macro) cannot generally be [trace]d.

  [4m[47mTo-df[0m[4m[0m[4m is a macro in raw Lisp[0m

  Although [47mto-df[0m 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.

    (defun add3 (x) (declare (type double-float x)) (df+ 3 x))

  We can see the translation of that [47mdf+[0m call as follows.

    ACL2 !>(body 'add3 nil (w state))
    (BINARY-DF+ (TO-DF '3) X)
    ACL2 !>

  Since [47mbinary-df+[0m is inlined in raw Lisp (see above), its call above
  essentially equivalent in raw lisp to [47m(+ (TO-DF '3) X)[0m.  But it
  would be unfortunate to call to-df at runtime, even if [47mto-df[0m were
  an inlined function.

  However, [47mto-df[0m is a macro that expands away its call on a rational
  argument or quoted rational argument.

    ? (macroexpand-1 '(TO-DF '3))
    3.0
    T
    ?

  A key performance tip is that a [47mdefun[0m form should [declare] dfs with
  a type declaration rather than an [47mxargs :dfs[0m declaration.  Here are
  examples.

  [4mType declarations are probably preferred[0m

  This observation is not really specific to the use of dfs.  Common
  Lisp compilers can sometimes take advantage of [47mtype[0m [declaration]s,
  but they never take advantage of [47mxargs[0m declarations (because those
  are ignored by the compiler).  So just as one may get better
  performance with a declaration [47m(type (integer 0 *) x)[0m than with
  [47m(xargs :guard (natp x))[0m, one may get better performance with
  (declare (type double-float x)) than with [47m(xargs :dfs x)[0m.


Section 8: More examples

  This section, which forms the remainder of this topic, is a synopsis
  of [community-books] file [47mbooks/demos/floating-point-input.lsp[0m.  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
  [47mbooks/demos/floating-point-log.txt[0m (generated by the [run-script]
  utility) may be worth a look.

  Here are the contents of that file (quoting from a comment near its
  top).

    ;;; 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

  We now hit some highlights of each of those sections that may not
  have been adequately covered above.  See
  [47mbooks/demos/floating-point-input.lsp[0m for more details, e.g., the
  use of either [47mE[0m or [47mD[0m as an exponent marker.

  [3m;;; \"Floats\" as rationals[0m

    (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))))))

  [3m;;; Overflow and underflow[0m

    #d1E310 ; Lisp error (overflow)

    #d1E-500 ; 0 (underflow)
    (to-df #d1E-500) ; #d0.0 (underflow)

  [3m;;; An assertion macro[0m

      This section just defines a macro, [47ma-e[0m, which checks that its input
      is true in two ways: by direct evaluation and by proof.

  [3m;;; Df-rationalize and rize[0m

    (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

  [3m;;; More on dfp & to-df (recognizer & generator for representables)[0m

    (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

  [3m;;; Fun with pi[0m

    (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)

  [3m;;; No support for complex floats[0m

    (to-df #c(0 1)) ; guard violation (expects a rational)

  [3m;;; Examples with defined functions[0m

      This section of [47mbooks/demos/floating-point-input.lsp[0m has several
      examples that are worth reading if you have difficulties
      defining functions that traffic in dfs.  In particular, it
      shows how to use [47mTHE[0m (see [the]) with a [47mdouble-float[0m
      [type-spec] to assist ACL2 with its syntax checking.

  [3m;;; Examples focused on ec-call[0m

      The example below shows the need to add a [47m:dfs[0m argument to [47m[ec-call][0m
      when the call returns a df.  See this section in
      [47mbooks/demos/floating-point-input.lsp[0m for additional discussion
      and examples.

    (defun f6 (x)
      (declare (xargs :guard (rationalp x)))
      (ec-call (unary-df- (to-df x))
               :dfs-in '(t)
               :dfs-out '(t)))

  [3m;;; We can't prove much[0m

      This section of [47mbooks/demos/floating-point-input.lsp[0m gives some
      examples of what can be proved about df operations and what
      cannot be proved.

  [3m;;; Df stobj fields[0m

    (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))

  [3m;;; Arrays of double-floats[0m

    (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)))

  [3m;;; DO loop$ expressions[0m

      This section of [47mbooks/demos/floating-point-input.lsp[0m continues using
      the stobj from the preceding section to show how [47mDO[0m [47m[loop$][0m
      expressions can operate on a stobj array.

  [3m;;; FOR loop$ expressions[0m

    ; 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)))))

  [3m;;; Stobj-let (nested stobjs)[0m

      This section of [47mbooks/demos/floating-point-input.lsp[0m shows that the
      [47m[stobj-let][0m utility works properly with dfs.

  [3m;;; Using apply$ with dfs[0m

    ; 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. ..]]

  [3m;;; Encapsulate and signatures[0m

    (encapsulate
      (((f16 *) => :df :formals (x) :guard (rationalp x)))
      (local (defun f16 (x)
               (declare (ignore x))
               (to-df 0))))

    (defstub f19 (:df) => (mv :df :df))

  [3m;;; Memoization[0m

    ; Memoization works fine with dfs; the subtleties when memoizing with stobjs
    ; don't apply to dfs.

  [3m;;; Miscellany[0m

    ; 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.

  [3m;;; Check consistency with values produced in raw Lisp[0m

    ; This section has tests to check that ACL2 evaluation with dfs agrees with
    ; corresponding Common Lisp evaluation on double-floats.


Section 9: Remarks for system programmers

  Probably most ACL2 users should skip this section.  But those who use
  ACL2 system utilities (see for example [system-utilities] and
  [programming-with-state]) may find some remarks here to be useful.

  The functions [47mtranslate[0m, [47mtranslate1[0m, [47mtranslate-cmp[0m, and
  [47mtranslate1-cmp[0m all convert a user-level [term] to a translated
  term.  Each of these assumes that no free variable of the
  user-level term is a df.  The function [47mtranslate1-cmp+[0m has an extra
  argument, [47mknown-dfs[0m, that is a list of free variables that are to
  be considered to be dfs.


Subtopics

  [Fp]
      Floating-point and ACL2")
 (DF* (POINTERS) "See [df].")
 (DF+ (POINTERS) "See [df].")
 (DF- (POINTERS) "See [df].")
 (DF-ABS (POINTERS) "See [df].")
 (DF-ABS-FN (POINTERS) "See [df].")
 (DF-ACOS (POINTERS) "See [df].")
 (DF-ACOS-FN (POINTERS) "See [df].")
 (DF-ACOSH (POINTERS) "See [df].")
 (DF-ACOSH-FN (POINTERS) "See [df].")
 (DF-ASIN (POINTERS) "See [df].")
 (DF-ASIN-FN (POINTERS) "See [df].")
 (DF-ASINH (POINTERS) "See [df].")
 (DF-ASINH-FN (POINTERS) "See [df].")
 (DF-ATAN (POINTERS) "See [df].")
 (DF-ATAN-FN (POINTERS) "See [df].")
 (DF-ATANH (POINTERS) "See [df].")
 (DF-ATANH-FN (POINTERS) "See [df].")
 (DF-COS (POINTERS) "See [df].")
 (DF-COS-FN (POINTERS) "See [df].")
 (DF-COSH (POINTERS) "See [df].")
 (DF-COSH-FN (POINTERS) "See [df].")
 (DF-EXP (POINTERS) "See [df].")
 (DF-EXP-FN (POINTERS) "See [df].")
 (DF-EXPT (POINTERS) "See [df].")
 (DF-EXPT-FN (POINTERS) "See [df].")
 (DF-LOG (POINTERS) "See [df].")
 (DF-MINUS-1 (POINTERS) "See [df].")
 (DF-PI (POINTERS) "See [df].")
 (DF-RATIONALIZE (POINTERS) "See [df].")
 (DF-ROUND (POINTERS) "See [df].")
 (DF-SIN (POINTERS) "See [df].")
 (DF-SIN-FN (POINTERS) "See [df].")
 (DF-SINH (POINTERS) "See [df].")
 (DF-SINH-FN (POINTERS) "See [df].")
 (DF-SQRT (POINTERS) "See [df].")
 (DF-SQRT-FN (POINTERS) "See [df].")
 (DF-STRING (POINTERS) "See [df].")
 (DF-TAN (POINTERS) "See [df].")
 (DF-TAN-FN (POINTERS) "See [df].")
 (DF-TANH (POINTERS) "See [df].")
 (DF-TANH-FN (POINTERS) "See [df].")
 (DF/ (POINTERS) "See [df].")
 (DF/=-FN (POINTERS) "See [df].")
 (DF0 (POINTERS) "See [df].")
 (DF1 (POINTERS) "See [df].")
 (DF< (POINTERS) "See [df].")
 (DF<-FN (POINTERS) "See [df].")
 (DF<= (POINTERS) "See [df].")
 (DF= (POINTERS) "See [df].")
 (DF=-FN (POINTERS) "See [df].")
 (DF> (POINTERS) "See [df].")
 (DF>= (POINTERS) "See [df].")
 (DFP (POINTERS) "See [df].")
 (DIGIT-CHAR-P
  (CHARACTERS ACL2-BUILT-INS)
  "The number, if any, corresponding to a given character

  [47m(digit-char-p ch)[0m is the integer corresponding to the character [47mch[0m in
  base [47m10[0m.  For example, [47m(digit-char-p #\\3)[0m is equal to the integer
  [47m3[0m.  More generally, an optional second argument specifies the radix
  (default [47m10[0m, as indicated above).

  The [guard] for [47mdigit-char-p[0m (more precisely, for the function
  [47mour-digit-char-p[0m 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.

  [47mDigit-char-p[0m 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.

  [31;1mMacro: [0m<digit-char-p>

    (defmacro digit-char-p (ch &optional (radix '10))
      (cons 'our-digit-char-p
            (cons ch (cons radix 'nil))))

  [31;1mFunction: [0m<our-digit-char-p>

    (defun our-digit-char-p (ch radix)
      (declare (xargs :guard (and (characterp ch)
                                  (integerp radix)
                                  (<= 2 radix)
                                  (<= radix 36))))
      (let ((l (assoc ch
                      '((#\\0 . 0)
                        (#\\1 . 1)
                        (#\\2 . 2)
                        (#\\3 . 3)
                        (#\\4 . 4)
                        (#\\5 . 5)
                        (#\\6 . 6)
                        (#\\7 . 7)
                        (#\\8 . 8)
                        (#\\9 . 9)
                        (#\\a . 10)
                        (#\\b . 11)
                        (#\\c . 12)
                        (#\\d . 13)
                        (#\\e . 14)
                        (#\\f . 15)
                        (#\\g . 16)
                        (#\\h . 17)
                        (#\\i . 18)
                        (#\\j . 19)
                        (#\\k . 20)
                        (#\\l . 21)
                        (#\\m . 22)
                        (#\\n . 23)
                        (#\\o . 24)
                        (#\\p . 25)
                        (#\\q . 26)
                        (#\\r . 27)
                        (#\\s . 28)
                        (#\\t . 29)
                        (#\\u . 30)
                        (#\\v . 31)
                        (#\\w . 32)
                        (#\\x . 33)
                        (#\\y . 34)
                        (#\\z . 35)
                        (#\\A . 10)
                        (#\\B . 11)
                        (#\\C . 12)
                        (#\\D . 13)
                        (#\\E . 14)
                        (#\\F . 15)
                        (#\\G . 16)
                        (#\\H . 17)
                        (#\\I . 18)
                        (#\\J . 19)
                        (#\\K . 20)
                        (#\\L . 21)
                        (#\\M . 22)
                        (#\\N . 23)
                        (#\\O . 24)
                        (#\\P . 25)
                        (#\\Q . 26)
                        (#\\R . 27)
                        (#\\S . 28)
                        (#\\T . 29)
                        (#\\U . 30)
                        (#\\V . 31)
                        (#\\W . 32)
                        (#\\X . 33)
                        (#\\Y . 34)
                        (#\\Z . 35)))))
        (cond ((and l (< (cdr l) radix)) (cdr l))
              (t nil))))")
 (DIGIT-TO-CHAR
  (CHARACTERS ACL2-BUILT-INS)
  "Map a digit to a character

    Example:
    ACL2 !>(digit-to-char 8)
    #\\8

  For an integer [47mn[0m from 0 to 15, [47m(digit-to-char n)[0m is the character
  corresponding to [47mn[0m in hex notation, using uppercase letters for
  digits exceeding 9.  If [47mn[0m is in the appropriate range, that result
  is of course also the binary, octal, and decimal digit.

  The [guard] for [47mdigit-to-char[0m requires its argument to be an integer
  between 0 and 15, inclusive.

  [31;1mFunction: [0m<digit-to-char>

    (defun digit-to-char (n)
      (declare (xargs :guard (and (integerp n) (<= 0 n) (<= n 15))))
      (case n
        (1 #\\1)
        (2 #\\2)
        (3 #\\3)
        (4 #\\4)
        (5 #\\5)
        (6 #\\6)
        (7 #\\7)
        (8 #\\8)
        (9 #\\9)
        (10 #\\A)
        (11 #\\B)
        (12 #\\C)
        (13 #\\D)
        (14 #\\E)
        (15 #\\F)
        (otherwise #\\0)))")
 (DIMENSIONS
  (ARRAYS ACL2-BUILT-INS)
  "Return the [47m:dimensions[0m from the [header] of a 1- or 2-dimensional
  array

    Example Form:
    (dimensions 'delta1 a)

    General Form:
    (dimensions name alist)

  where [47mname[0m is arbitrary and [47malist[0m is a 1- or 2-dimensional array.
  This function returns the dimensions list of the array [47malist[0m.  That
  list will either be of the form [47m(dim1)[0m or [47m(dim1 dim2)[0m, depending on
  whether [47malist[0m is a 1- or 2-dimensional array.  [47mDim1[0m and [47mdim2[0m will
  be integers and each exceed by 1 the maximum legal corresponding
  index.  Thus, if [47mdimensions[0m returns, say, [47m'(100)[0m for an array [47ma[0m
  named [47m'delta1[0m, then [47m(aref1 'delta1 a 99)[0m is legal but [47m(aref1
  'delta1 a 100)[0m violates the [guard]s on [47m[aref1][0m.  [47mDimensions[0m
  operates in virtually constant time if [47malist[0m is the semantic value
  of [47mname[0m.  See [arrays].

  [31;1mFunction: [0m<dimensions>

    (defun dimensions (name l)
      (declare (xargs :guard (or (array1p name l) (array2p name l))))
      (cadr (assoc-keyword :dimensions (cdr (header name l)))))")
 (DISABLE
  (THEORIES THEORY-FUNCTIONS)
  "Deletes names from current theory

    Example:
    (disable fact (:e fact) associativity-of-app)

    General Form:
    (disable name1 name2 ... namek)

  where each [47mnamei[0m is a runic designator; 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
  [rune]s and you will probably regret printing it.

  For related utilities, see [enable] and see [e/d].

  The standard way to ``disable'' a fixed set of names, is as follows;
  see [hints] and see [in-theory].

    :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)))

  Note that all the names are implicitly quoted.  If you wish to
  disable a computed list of names, [47mlst[0m, use the theory expression
  [47m(set-difference-theories (current-theory :here) lst)[0m.")
 (DISABLE-FORCING
  (FORCE)
  "To disallow forced case-splits

    General Form:
    ACL2 !>:disable-forcing   ; disallow forced case splits

  See [force] and see [case-split] for a discussion of forced case
  splits, which are inhibited by this command.

  [47mDisable-forcing[0m is actually a macro that [disable]s the
  [executable-counterpart] of the function symbol [47mforce[0m; see [force].
  When you want to use [hints] to turn off forced case splits, use a
  form such as one of the following (these are equivalent).

    :in-theory (disable (:executable-counterpart force))
    :in-theory (disable (force))

  The following example shows how this works.  First evaluate these
  forms.

    (defstub f1 (x) t)
    (defstub f2 (x) t)
    (defaxiom ax (implies (case-split (f2 x)) (f1 x)))
    (thm (f1 x))

  You will see the application of the rule, [47max[0m, in the proof of the
  [47m[thm][0m call above.  However, if you first evaluate
  [47m(disable-forcing)[0m, then there will be no application of [47max[0m.  To
  restore forced case splitting, see [enable-forcing].")
 (DISABLE-IMMEDIATE-FORCE-MODEP
  (FORCE)
  "[force]d hypotheses are not attacked immediately

    General Form:
    ACL2 !>:disable-immediate-force-modep

  This event causes ACL2 to delay [force]d hypotheses to the next
  forcing round, rather than attacking them immediately.  See
  [immediate-force-modep].  Or for more basic information, first see
  [force] for a discussion of [force]d case splits.

  Disable-immediate-force-modep is a macro that [disable]s the
  [executable-counterpart] of the function symbol
  [47m[immediate-force-modep][0m.  When you want to [disable] this mode in
  [hints], use a form such as one of the following (these are
  equivalent).

    :in-theory (disable (:executable-counterpart immediate-force-modep))
    :in-theory (disable (immediate-force-modep))")
 (DISABLE-UBT
  (HISTORY)
  "Make it illegal to undo back through the current [command]

  The utility [47mdisable-ubt[0m is probably only relevant to those who write
  ACL2-based tools, in particular using [wormhole]s.  Its initial
  application (and perhaps still its only application) is to arrange
  that inside the [break-rewrite] interactive loop, it is impossible
  to undo the [ld-keyword-aliases] supporting the [brr-commands].

    General Forms:

    :disable-ubt
    (disable-ubt)     ; same as above
    (disable-ubt arg) ; same as above if arg is not nil or :disable-ubt

  where [47marg[0m is evaluated, and if it is supplied and its value is
  neither [47mnil[0m nor [47m:disable-ubt[0m, then its value satisfies [47m[msgp][0m.  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 [47mdisable-ubt[0m: a [command]
  that executes it cannot be undone.

    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 !>

  [47mDisable-ubt[0m is similar to [47m(reset-prehistory t)[0m, as both establish a
  barrier to undoing.  However, for history commands such as [47m:[0m[47m[pcb][0m,
  command numbers are not changed by [47mdisable-ubt[0m.  Like
  [47m[reset-prehistory][0m, [47mdisable-ubt[0m is never [redundant].")
 (DISABLEDP
  (THEORIES)
  "Determine whether a given name or rune is disabled

    Examples:

    :disabledp foo   ; returns a list of all disabled runes whose base
                     ; symbol is foo (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

  Also see [pr], which gives much more information about the rules
  associated with a given event.

  [47mDisabledp[0m takes one argument, which is a symbol, a [rune], or a runic
  abbreviation such as [47m(:d append)[0m (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 [rune]) or, if the event named is a [47m[defmacro][0m event, then the
  list of disabled runes associated with the function corresponding
  to that macro name, if any (see [macro-aliases-table]).  In the
  other cases, where the argument is a [rune] or a runic abbreviation
  for a rune, [47mdisabledp[0m returns [47mt[0m if the rune is disabled, and [47mnil[0m
  otherwise.

  Remark for users of the [break-rewrite] utility.  Inside the [47m:[0m[47m[brr][0m
  loop, the computation performed by [47mdisabledp[0m 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 [hints] supplied for the
  proof specify [47m(\"Subgoal 3\" :in-theory (disable foo))[0m, then [47mdisabled[0m
  will return the runes associated with [47mfoo[0m, regardless of whether or
  not those runes are disabled globally.")
 (DISASSEMBLE$
  (COMPILATION DEBUGGING)
  "Disassemble a function

  The macro [47mdisassemble$[0m provides a convenient interface to the
  underlying [47mdisassemble[0m 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 [macro-aliases-table]), then it prints
  assembly code for that function symbol instead.

  [47mDisassemble$[0m works by including the community book
  [47mbooks/misc/disassemble.lisp[0m, which defines the supporting function
  [47mdisassemble$-fn[0m, and then by calling that function.  Note that the
  arguments to [47mdisassemble$[0m are evaluated.  Also note that
  [47mdisassemble$[0m 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 [47mdisassemble$-fn[0m directly.

    Example Forms:

    (disassemble$ 'foo)
    (disassemble$ 'foo :recompile t)

    General Forms:
    (disassemble$ form)
    (disassemble$ form :recompile flg)

  where [47mform[0m evaluates to a function symbol or a macro alias for a
  function symbol and [47mflg[0m evaluates to any value.  If [47mflg[0m is [47mnil[0m,
  then the existing definition of that function symbol is
  disassembled.  But if [47mflg[0m is supplied and has a value other than
  [47mnil[0m or [47m:default[0m, and if that function symbol is defined in the ACL2
  loop (not merely in raw Lisp; for example, 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 [47mflg[0m is omitted or has the value [47m:default[0m
  --- i.e., in the default case --- then recompilation may take place
  or not, depending on the host Lisp.  The values of [47m(@ host-lisp)[0m
  for which recompilation takes place by default may be found by
  looking at the above book, or by including it and evaluating the
  constant [47m*host-lisps-that-recompile-by-default*[0m.  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).")
 (DISJOIN (POINTERS)
          "See [system-utilities].")
 (DISJOIN2 (POINTERS)
           "See [system-utilities].")
 (DIVE-INTO-MACROS-TABLE
  (PROOF-BUILDER ACL2-PC::DV)
  "Right-associated function information for the [proof-builder]

    Examples:
    ACL2 !>(dive-into-macros-table (w state))
    ((CAT . EXPAND-ADDRESS-CAT)
     (LXOR . EXPAND-ADDRESS-LXOR)

  This table associates macro names with functions used by the
  interactive [proof-builder]'s [47mDV[0m and numeric diving commands (e.g.,
  [47m3[0m) in order to dive properly into subterms.  See [proof-builder],
  in particular the documentation for [47mDV[0m.

  This table can be extended easily.  See [add-dive-into-macro] and
  also see [remove-dive-into-macro].

  The symbol associated with a macro should be a function symbol taking
  four arguments, in this order:

    * [47mcar-addr[0m
          the first number in the list given to the interactive
          [proof-builder]'s [47mDV[0m command

    * [47mraw-term[0m
          the untranslated term into which we will dive

    * [47mterm[0m
          the translated term into which we will dive

    * [47mwrld[0m
          the current ACL2 logical [world]

  The function will normally return a list of positive integers,
  representing the (one-based) address for diving into [47mterm[0m that
  corresponds to the single-address dive into [47mraw-term[0m by
  [47mcar-address[0m.  However, it can return [47m(cons str alist)[0m, where [47mstr[0m is
  a string suitable for [47m[fmt][0m and [47margs[0m is the corresponding alist for
  [47m[fmt][0m.

  Referring to the example above, [47mexpand-address-cat[0m would be such a
  function, which will be called on [47mraw-term[0m values that are calls of
  [47mcat[0m.  See the community book [47mbooks/misc/rtl-untranslate.lisp[0m for
  the definition of such a function.

  See [table] for a general discussion of tables.


Subtopics

  [Add-dive-into-macro]
      Associate [proof-builder] diving function with macro name

  [Remove-dive-into-macro]
      Removes association of [proof-builder] diving function with macro
      name")
 (DMR
  (DEBUGGING BREAK-REWRITE ACCUMULATED-PERSISTENCE)
  "Dynamically monitor rewrites and other prover activity

  In addition to utilities that allow you to set breakpoints or print
  rewriting information to the screen --- see [break-rewrite] (also
  see related utility [with-brr-data]) --- 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.

  The dmr utility can be extremely helpful for expensive proofs,
  especially when ACL2 is not providing any output to the terminal.
  The [break-rewrite] and [47m[accumulated-persistence][0m 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.

  The Emacs portion of this utility is already loaded if you load the
  distributed Emacs file [47memacs-acl2.el[0m from a suitable directory; see
  [emacs].  Otherwise, load into Emacs the file [47mmonitor.el[0m 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'':

    Control-t 1

  But first you will need to enable monitoring at the ACL2 level:

    (dmr-start)

  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 [47m\"acl2-dmr-<user_name>\"[0m) is not
  visible, Emacs monitoring is turned off.  You can also turn off
  Emacs monitoring explicitly, with:

    Control-t 2

  At the ACL2 level you can disable monitoring as follows:

    (dmr-stop)

  [3mInterpreting the dmr buffer display.[0m

  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,
  [47mbooks/workshops/2004/legato/support/proof-by-generalization-mult.lisp[0m.

     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)

  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
  [47mWP-ZCOEF-G-MULTIPLIES[0m.  Lines 1 and 2 show the [clause]
  simplification process invokes the rewriter on the 18th literal.
  (Recall that a clause is a disjunction of literals; for example the
  clause [47m{(NOT A), (NOT B), C}[0m would be displayed as [47m(IMPLIES (AND A
  B) C)[0m.)  This 18th literal mentioned on line 2 is a function call
  [47m(f arg1 ...)[0m, and ``[47margument(s) 1[0m'' indicates that the rewriter,
  which works inside-out, is considering the first argument
  (``[47marg1[0m'').  Thus the display could instead have shown the
  following.

    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

  But it saved space to combine lines 2 and 3.  Line 4 suggests that
  the above [47marg1[0m is a function call that has been opened up because
  of an [47m:expand[0m hint or, perhaps, an expansion directed explicitly by
  the prover (as can happen during induction).  The annotation
  ``[47margument(s) 3|2[0m'' 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 [47mterm7[0m (since it is the
  one to be considered on line 7).

  Now consider the next two lines:

       7. Applying (:DEFINITION WP-ZCOEF-G)
    *  8. Rewriting (to simplify) the rewritten body; argument(s) 2|1|2|2

  Line 7 is saying that [47mterm7[0m (defined above) is modified by applying
  the definition of [47mWP-ZCOEF-G[0m to it.  Line 8 then says that the body
  of this definition has been rewritten (with its formals bound to
  the actuals from [47mterm7[0m) 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 (``[47m*[0m'') 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 [47m(:DEFINITION WP-ZCOEF-G)[0m is expensive.
  (Also 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.

  Finally let us consider line 13 and the two lines below it.  The
  phrase [47m\"'Applying (:REWRITE MOD-ZERO . 2)\"[0m 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.

  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 [47mt[0m).  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 [47mSIMPLIFY-CLAUSE[0m (shown line 1 above).  If
  the indentation is at least the value of raw Lisp variable
  [47m*dmr-indent-max*[0m (by default, 20), then the indentation is
  restricted to that column, but ACL2 prints [47m{n}[0m where n is the
  column that would have been used for indentation if there were no
  maximum.

  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 (``[47m*[0m'') 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.

  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.

  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 [47m/tmp[0m.  Except, you can probably hack around that
  restriction by changing [47m*dmr-file-name*[0m in ACL2 (in raw Lisp) and
  correspondingly in Emacs file [47mmonitor.el[0m.

  More generally, advanced users are welcome to search for the string

    User-settable dmr variables

  in ACL2 files [47minterface-raw.lisp[0m and [47memacs/monitor.el[0m in order to
  customize their dmr environments.

  In order to update the dmr file with the latest stack information,
  interrupt ACL2 and then evaluate: [47m(dmr-flush)[0m.  In order to support
  resumption of the interrupted proof (assuming your host Common Lisp
  supports resumption), evaluation of [47m(dmr-start)[0m will automatically
  enable the debugger if it is not already enabled and not fully
  disabled with value [47m:never[0m (see [set-debugger-enable]).  If such
  automatic enabling takes place, then [47m(dmr-stop)[0m will restore the
  old setting of the debugger unless, after [47m(dmr-start)[0m enables the
  debugger but before [47m(dmr-stop)[0m is called, you call
  [47m[set-debugger-enable][0m (or more precisely: function
  [47mset-debugger-enable-fn[0m is called).

  Note for users of the experimental extension ACL2(p) (see
  [parallelism]): when waterfall-parallelism has been set to a
  non-[47mnil[0m value (see [set-waterfall-parallelism]), statistics about
  parallel execution are printed instead of the usual information.")
 (DO$
  (LOOP$ DO-LOOP$)
  "Definition of [47mdo$[0m

  [47mDo$[0m is the logical function that interprets [47mdo[0m [47mloop$[0ms.  See
  [do-loop$] for a discussion of [47mdo$[0m.

  The function takes six arguments but only the first five are relevant
  to its logical value.

    * [47mmeasure-fn[0m --- a [47m[lambda][0m object that computes the measure that
      supposedly decreases (under [47m[l<][0m) on each iteration of the
      [47mdo-fn[0m and is checked after each iteration,

    * [47malist[0m --- an alist that binds the variable symbols used in the body
      and [47mfinally[0m clause (if any) to their values,

    * [47mdo-fn[0m --- a [47mlambda[0m 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 [47mreturn[0m was executed), and a new [47malist[0m,

    * [47mfinally-fn[0m--- a [47mlambda[0m object that computes the value of the [47mfinally[0m
      clause, and

    * [47mvalues[0m --- the output signature of the value to be returned if the
      [47mmeasure[0m fails to decrease.

  [31;1mFunction: [0m<do$>

    (defun do$ (measure-fn alist do-fn finally-fn values dolia)
     (declare (xargs :guard (and (apply$-guard measure-fn '(nil))
                                 (apply$-guard do-fn '(nil))
                                 (apply$-guard finally-fn '(nil))
                                 (weak-dolia-p dolia))))
     (let* ((triple (true-list-fix (apply$ do-fn (list alist))))
            (exit-token (car triple))
            (val (cadr triple))
            (new-alist (caddr triple)))
      (cond
       ((eq exit-token :return) val)
       ((eq exit-token :loop-finish)
        (let*
         ((triple (true-list-fix (apply$ finally-fn (list new-alist))))
          (exit-token (car triple))
          (val (cadr triple)))
         (if (eq exit-token :return) val nil)))
       ((l< (lex-fix (apply$ measure-fn (list new-alist)))
            (lex-fix (apply$ measure-fn (list alist))))
        (do$ measure-fn new-alist
             do-fn finally-fn values dolia))
       (t
        (prog2$
         (let
           ((all-stobj-names
                 (true-list-fix (access dolia dolia :all-stobj-names)))
            (untrans-measure (access dolia dolia :untrans-measure))
            (untrans-do-loop$ (access dolia dolia :untrans-do-loop$)))
          (er
           hard? 'do$
           \"The measure, ~x0, used in the do loop$ ~
                    statement~%~Y12~%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~%~Y32.~|After the execution of the do body the alist ~
                    was~%~Y42.~|Before the execution of the body the measure ~
                    was~%~x5.~|After the execution of the body the measure ~
                    was~%~x6.~|~%Logically, in this situation the do$ returns the ~
                    value of a term whose output signature is ~x7, 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.\"
           untrans-measure untrans-do-loop$ nil
           (eviscerate-do$-alist alist all-stobj-names)
           (eviscerate-do$-alist new-alist all-stobj-names)
           (apply$ measure-fn (list alist))
           (apply$ measure-fn (list new-alist))
           values))
         (loop$-default-values values new-alist))))))

  The last argument is only relevant in the error message printed if
  the [47mdo$[0m fails to terminate and that message is not part of the
  returned value.")
 (DO-LOOP$
  (LOOP$)
  "Iteration with [47m[loop$][0m using local variables and [stobj]s

  This topic assumes that you have read the introduction to [47mloop$[0m
  expressions in ACL2; see [loop$].  Here we give more complete
  documentation on [47mDO[0m [47mloop$[0m expressions, beginning with an informal
  introduction based largely on examples and then continuing with
  detailed syntax and semantics.  For a discussion of proofs about
  [47mloop$[0ms, see [stating-and-proving-lemmas-about-loop$s].

  More examples of [47m[loop$][0m expressions, including [47mDO[0m [47mloop$[0ms, may be
  found in [community-book] [47mprojects/apply/loop-tests.lisp[0m.


INFORMAL INTRODUCTION

  The most basic [47mDO[0m [47mloop$[0m expressions have the following form.

    (loop$ WITH v1 = a1
           ...
           WITH vn = an
           DO body)

  [31;1mA Basic Example[0m

  The example [47mloop$[0m expression below initially stores the list [47m(a b c)[0m
  in the variable [47mx[0m and [47mnil[0m in the variable [47my[0m.  Then it iterates,
  repeatedly popping the first element of [47mx[0m onto [47my[0m until [47mx[0m is empty.
  Then it returns the final value of [47my[0m.

    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 !>

  This example illustrates the basic operation of [47mDO[0m [47mloop$[0m expressions.

    * Initially, variables are initialized according to the [47mWITH[0m clauses:
      for each binding [47mWITH Vi = Ei[0m, we say that [47mVi[0m is a [3m[47mWITH[0m[3m-bound
      variable[0m, and [47mVi[0m is initially bound to the value of [47mEi[0m.

        * In this example, [47mx[0m is initially bound to the list [47m(a b c)[0m and [47my[0m is
          initially bound to [47mnil[0m.

    * Then, the [3mloop body[0m --- i.e., the term after the [47mDO[0m keyword --- is
      repeatedly evaluated.  An update to [47mWITH[0m-bound variable [47mVj[0m
      occurs whenever an expression [47m(setq Vj Ej)[0m is encountered while
      evaluating the loop body, binding [47mVj[0m to the value of [47mEj[0m (which
      may reference the current values of [47mWITH[0m-bound variables).

        * In this example, as long is [47mx[0m is a cons, [47my[0m is assigned to [47m(cons (car
          x) y)[0m and then [47mx[0m is assigned to the [47mcdr[0m of its current
          value.

    * Ultimately an expression [47m(RETURN E)[0m should be encountered, in which
      case the value of [47mE[0m is returned --- where as before, [47mE[0m may
      reference the current values of [47mWITH[0m-bound variables.

        * In this example, when [47mx[0m is not a cons (and hence is, in fact, [47mnil[0m),
          the current value of [47my[0m is returned as the value of the
          [47mloop$[0m expression.  By this point each element of the
          initial value of [47mx[0m has been pushed onto [47my[0m, so the value [47m(c
          b a)[0m is returned.

  Note that [47mprogn[0m is permitted as shown, to connect a sequence of
  expressions.  Indeed, that is how more than one assignment is
  accomplished; unlike Common Lisp, the [47mDO[0m keyword is followed by
  exactly one expression, so [47mDO expr1 expr2[0m is illegal in ACL2 but [47mDO
  (progn expr1 expr2)[0m is fine.

  Also note that the [47mWITH[0m-bound variables are initialized sequentially:
  later bindings may reference values of earlier ones, for example as
  follows.

    ACL2 !>(loop$ with x = (* 3 4) with y = (* 10 x) do (return (list y)))
    (120)
    ACL2 !>

  See [lp-section-14] of the [47mLoop$[0m Primer for some exercises in writing
  and executing [47mDO[0m [47mLoop$[0ms (with answers in a Community Book).  But
  remember to come back here when you get to the end of that section.

  [31;1mParallel Assignment Using [47mMv-setq[0m[31;1m[0m

  ACL2 also supports parallel assignment to two or more variables,
  using [47mmv-setq[0m.  The following is equivalent to the example
  immediately above.

    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 !>

  Thus, the first argument of an [47mmv-setq[0m 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 --- ``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
  [47m(mv-setq vars expr)[0m are the same as for [47m(mv-let vars expr ...)[0m.

  [31;1mThe [47mFINALLY[0m[31;1m Clause[0m

  We have seen the [47mloop$[0m keywords [47mWITH[0m and [47mDO[0m.  A third [47mloop$[0m keyword,
  [47mFINALLY[0m, is also supported.  Here is a variant of the preceding
  example that illustrates the use of [47mFINALLY[0m.  The iteration stops
  with the [47m(loop-finish)[0m form this time, rather than with a call of
  [47mreturn[0m.  Execution of [47m(loop-finish)[0m passes control to the [47mFINALLY[0m
  clause, which is executed just like the [47mDO[0m body but with a single
  pass, thus determining the value of the [47mloop$[0m --- in this example,
  returning the final value of [47my[0m.

    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 !>

  This example illustrates that [47m(loop-finish)[0m terminates the iteration,
  passing control to the [47mFINALLY[0m clause if there is one.  The [47mFINALLY[0m
  clause is evaluated under the current bindings of the [47mWITH[0m-bound
  variables, just as a [47mDO[0m body is executed (but with a single pass
  rather than iteration).

  The value returned by a [47mDO[0m [47mloop$[0m expression is [47mnil[0m when no [47mreturn[0m
  expression is evaluated (or more generally, a suitable value
  consistent with the [47m:VALUES[0m keyword discussed below).  Here is an
  example, which illustrates an error that may be easy to commit.

    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 !>

  Presumably the intention was to return the length of [47my[0m, which in this
  case would be 3.  But then the [47mFINALLY[0m clause should have been
  [47m(return (length y))[0m.

  [31;1mThe [47m:VALUES[0m[31;1m Keyword[0m

  The [47m:VALUES[0m keyword is necessary for a [47mloop$[0m expression that returns
  a [double-float], a [stobj] or [multiple-value]s.  When the [47m:VALUES[0m
  keyword is used, the syntax is [47m:VALUES (v0 ... vk)[0m, where each [47mvi[0m
  is either [47mnil[0m, [47m:df[0m, or a stobj name. [47m:VALUES (nil)[0m denotes return
  of a single ordinary value; [47m:VALUES (s)[0m denotes return of a single
  value that is a stobj named [47ms[0m; and [47m:VALUES (v0 ... vk)[0m for k > 0
  denotes return of k+1 values, where [47mvi[0m is [47mnil[0m if the ith returned
  value is an ordinary value, [47m:DF[0m if the ith returned value is a
  double-float, and otherwise [47mvi[0m 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 [47mdo$[0m 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 [47mnil[0m if [47mvi[0m is [47mnil[0m, is [47m#d0.0[0m if [47mvi[0m is [47m:DF[0m, and
  is the last latched value of the named stobj otherwise. No stobj
  name may be duplicated, and [47m:VALUES[0m must appear between the [47mDO[0m loop
  keyword and the [47mDO[0m body.  Let's look at an example.

  Below we introduce a [stobj] and add a [warrant] for its accessor and
  updater.  Warrants are necessary for functions called in [47mDO[0m bodies
  and [47mFINALLY[0m clauses in order for those forms to be evaluated.  See
  [loop$] for a discussion of the necessity of such warrants.  The
  two [47mloop$[0m expressions are similar in nature to those above, first
  without and then with a [47mFINALLY[0m clause; also see the discussion
  below.  All forms below complete successfully.

    (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)))

  These loops are similar to those we saw earlier, but this time, when
  we pop values from [47mx[0m they go into a stobj.  Since we return that
  stobj, [47mst[0m, the [47m:VALUES[0m is [47m(st)[0m.  The fifth argument of the call of
  [47mdo$[0m generated from these [47mloop$[0ms is [47m'(st)[0m.  One might expect [47m:VALUES[0m
  to be [47mst[0m instead, but [47m:VALUES[0m is always a list; when a single value
  is returned, [47m:VALUES[0m is a one-element list.  Thus, the default for
  [47m:VALUES[0m is [47m(nil)[0m.

  Notice that the examples above apply [47msetq[0m to [47mst[0m.  This illustrates
  that a variable assigned by [47msetq[0m or [47mmv-setq[0m must either be declared
  in a [47mWITH[0m clause or be a known stobj.  Of course, here [47mst[0m is a
  known stobj.  In fact, stobjs are not allowed to be declared in
  [47mWITH[0m clauses (and that is not necessary for assigning to them).

  [31;1mThe [47mOF-TYPE[0m[31;1m Keyword[0m

  So far our examples have all involved [47mloop$[0m expressions that are
  evaluated directed at the ACL2 prompt.  These do not require the
  [47mOF-TYPE[0m keyword described in this section.  But [47mloop$[0m expressions
  may also appear in definitions.  When these definitions are to be
  [guard]-verified, [47mOF-TYPE[0m keyword may be critical.

  Consider the following example, which searches for an even number in
  a given list of integers, returning [47mt[0m if one is found and else [47mnil[0m.
  As usual, we start by including the usual book for reasoning about
  [47mloop$[0m.

    (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))))))

  We see that the expression immediately following [47mOF-TYPE[0m is a legal
  [type-spec], in this case expressing that [47m(integer-listp temp)[0m
  holds for every value of [47mtemp[0m during execution of the [47mloop$[0m.  Let's
  see why this use of [47mOF-TYPE[0m is necessary.  When it is omitted,
  guard verification fails with the following top-level checkpoints.

    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))))

  To understand these checkpoints we need to understand a bit about how
  ACL2 gives a semantics to [47mDO[0m [47mloop$[0m expressions (as we explain in
  more detail in the section on Semantics below).  In the ACL2 logic,
  a [47mDO[0m [47mloop$[0m expression is represented as a transformation on an
  association list, named [47malist[0m, that assigns values to every
  variable in the expression.  This alist is transformed by each
  iteration through the loop.

  The value of the variable [47mtemp[0m in [47malist[0m is [47m(assoc-eq-safe 'temp
  alist)[0m, where [47massoc-eq-safe[0m is just a variant of [47m[assoc][0m whose
  guard makes no requirements on the alist.  The first checkpoint
  above (Subgoal 1.2) thus says that if the value of [47mtemp[0m is not a
  cons, then it's [47mnil[0m.  That requirement comes from the expression,
  [47m(endp temp)[0m, since the guard of [47m[endp][0m is that its argument is a
  cons or [47mnil[0m.  The second checkpoint (Subgoal 1.1) says that if the
  value of [47mtemp[0m is a cons, then its [47mcar[0m is an integer.  That
  requirement comes from the expression [47m(evenp (car temp))[0m, since the
  guard for [47m[evenp][0m requires its argument to be an integer.

  When we add the restriction provided by the [47mOF-TYPE[0m keyword that [47mtemp[0m
  satisfies [47m[integer-listp][0m, the checkpoints each get the added
  hypothesis [47m(integer-listp (cdr (assoc-eq-safe 'temp alist)))[0m.  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 [47mhas-evenp[0m specifies [47m(integer-listp x)[0m and
  [47mtemp[0m is initially assigned to [47mx[0m.  Importantly, use of the [47mOF-TYPE[0m
  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 [47m(endp temp)[0m and [47m(evenp (car temp))[0m are false,
  and also assuming that [47mtemp[0m satisfies [47minteger-listp[0m --- where here,
  [47mtemp[0m is [47m(cdr (assoc-eq-safe 'temp alist))[0m --- then [47m(cdr temp[0m)
  satisfies [47minteger-listp[0m.  ACL2 discharges this requirement
  automatically.

  [31;1mThe [47m:GUARD[0m[31;1m Keyword[0m

  Consider the following definition, which is identical to the one for
  [47mhas-evenp[0m displayed above except that instead of using the [47mOF-TYPE[0m
  keyword, it uses the [47m:GUARD[0m keyword.

    (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))))))

  This definition is accepted by ACL2 for much the same reason that the
  preceding one was accepted.  The difference is that while the
  [47mOF-TYPE[0m keyword adds a requirement at every assignment of the
  variable, the [47m:GUARD[0m imposes the invariant that when the guard
  holds entering the [47mloop$[0m body, it also holds when the [47mloop$[0m body is
  next entered.  Thus we see the following in the [47mGoal[0m generated for
  the guard conjecture, where [47mnew-alist[0m is let-bound (not shown here)
  to the result of updating [47malist[0m after one iteration through the
  loop, and where [47m(equal exit-flg nil)[0m indicates that another
  iteration is pending (because neither a [47mreturn[0m nor a [47mloop-finish[0m
  was executed).

    (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)))))

  The [47m:guard[0m is generally ignored when it is within the definition's
  body for a guard-verified or a [47m:[0m[47m[program][0m-mode function.  The
  reason is that in these cases, the [47mloop$[0m expression is converted to
  a Common Lisp [47mloop[0m expression.  (There are exceptions involving
  [47m[set-guard-checking][0m and [invariant-risk].)  However, in other
  cases the [47m:guard[0m is checked at runtime.  Consider the following
  example.

    (defun f (lst)
      (loop$ with x = lst
             do
             :guard (consp x)
             (cond ((consp x)
                    (setq x (cdr x)))
                   (t (return x)))))

  Here we see a runtime guard violation.

    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 !>

  As noted in the preceding section (on ``The [47mOF-TYPE[0m Keyword''), a
  call of [47mdo$[0m transforms an alist with each iteration through the
  loop.  The alist initially binds the symbol [47mX[0m to the list [47m(A B C
  D)[0m, and each iteration modifies that binding by [47mcdr[0ming the value of
  [47mX[0m, until finally that value is [47mnil[0m --- and then a guard check fails
  for the value of [47mX[0m, i.e., [47m(CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))[0m is
  [47mnil[0m.

  A more detailed explanation may be found in the final section,
  ``Semantics''.

  [31;1mThe [47m:MEASURE[0m[31;1m Keyword[0m

  The discussion above doesn't address the obvious possibility that a
  [47mDO[0m [47mloop$[0m 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 [47m(defwarrant princ$)[0m has been
  evaluated.

    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 !>

  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 [47m<[0m.  In general, the measure decreases in the sense of [47mL<[0m when
  [47mlex-fix[0m is applied to each argument; see [L<].

  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 [47m100[0m 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.

    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 in TOP-LEVEL:  Evaluation aborted.  To debug see :DOC print-
    gv, see :DOC trace, and see :DOC wet.

    ACL2 !>

  Presumably the following is what was intended.

    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 !>

  In fact, the [47m:MEASURE[0m can be omitted in this case; ACL2 is able to
  guess [47m(ACL2-COUNT X)[0m.

  [Guard] verification requires a proof that the measure does indeed go
  down in the sense of [47mL<[0m, after applying [47mlex-fix[0m to the arguments;
  see [L<].  Fortunately, guard verification takes advantage of
  information specified by [47mOF-TYPE[0m and [47m:GUARD[0m keywords.  For example,
  the following two definitions are admitted (after the usual initial
  [47minclude-book[0m form), even though termination would not be provable
  without the [47mOF-TYPE[0m expression in the first and the DO body's
  [47m:GUARD[0m in the second; consider the case that [47mn[0m is -1.

    (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)))))

  [31;1mA More Complex Example[0m

  We conclude with an example presented in the documentation for
  [47m[loop$][0m that illustrates all the features above.  Notice that the
  [47m:GUARD[0m keyword may appear not only in the [47mDO[0m body but also in the
  [47mFINALLY[0m clause, to specify that the indicated guard holds upon
  entry to the [47mFINALLY[0m clause.  Here we assume that we have already
  evaluated not only the usual [47minclude-book[0m form, but also the
  [47mdefstobj[0m and [47mdefwarrant[0m forms above.

    (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))))

  Notice that any variables bound above the [47mloop$[0m may appear in it, for
  example, the formal parameters of this function.  But only
  variables that are [47mWITH[0m-bound or declared as [stobj]s may be
  assigned with [47msetq[0m or [47mmv-setq[0m.  The [47m:GUARD[0m of [47m(stp st)[0m is
  necessary, because ACL2 does not automatically infer that stobj
  recognizer calls hold inside [47mloop$[0m expressions the way it does in
  ordinary bodies of [47m[defun][0m forms.

  We can evaluate the function above, as in the following example.

    ACL2 !>(test-loop$ 3 8 st)
    ((FROM 3 TO 8 IS 5 STEPS AND FLD = 7)
     <st>)
    ACL2 !>


SYNTAX

    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)

  where much of that is optional: ``[47mOF-TYPE speci[0m'', ``[47m= initi[0m'' (when
  ``[47mOF-TYPE speci[0m'' is present), ``[47m:MEASURE m[0m'', the two ``[47m:GUARD[0m
  ...'' clauses, ``[47m:VALUES v[0m'', and ``[47mFINALLY fin-body[0m''.  If the
  [47m:MEASURE[0m is omitted, ACL2 tries to guess a likely measure using the
  same heuristic it does with recursive [47m[defun][0ms.  If [47m:VALUES[0m is
  omitted then [47mv[0m defaults to [47m(nil)[0m; it indicates the shape of the
  return value for the [47mloop$[0m expression.

  [47mDo-body[0m must be a cons, not an atom, as must each of the following
  that is supplied: [47mm[0m, [47mdo-guard[0m, [47mv[0m, [47mfin-guard[0m, and [47mfin-body[0m.

  All ACL2 function symbols in the measure [47mm[0m and the two bodies must be
  [badge]d so [47m[apply$][0m can handle them.  Furthermore, they must be
  [warrant]ed if proofs are to be done about them or if they are in
  [logic] mode and are called during evaluation.

  The [47mdo-body[0m and [47mfin-body[0m positions are to be what we call ``DO-body
  term''.  [31;1mThese are not, in general, normal ACL2 terms!  They allow
  restricted uses of [47mRETURN[0m[31;1m, [47mPROGN[0m[31;1m, [47mSETQ[0m[31;1m, [47mMV-SETQ[0m[31;1m, and [47mLOOP-FINISH[0m[31;1m as
  described below.[0m In the descriptions below we ignore the
  distinctions between translated and untranslated terms; see
  [term]).  As usual, the restrictions on return values apply only to
  code, not to terms occurring in theorem statements.

    * Every ordinary term that returns a single, non-stobj value

    * An [47mIF[0m 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

    * A [47mLET[0m, [47mLET*[0m, or [47mMV-LET[0m expression, subject to the following
      restrictions (unless the term is an ordinary term).

        * The terms in the bindings are all ordinary terms.

        * The body is a DO-body term.

        * No variable bound in the bindings is [47mWITH[0m-bound, a known [stobj], or
          a variable occurring free in the surrounding DO loop$
          expression.

    * [47m(PROGN term1 term2 ... termk)[0m, where each [47mtermi[0m is a DO-body term;
      also [47m(PROG2 term1 term2)[0m in that case

    * [47m(RETURN term)[0m, where [47mterm[0m is an ordinary term

    * [47m(LOOP-FINISH)[0m, but only in a DO body, not in a [47mFINALLY[0m clause

    * [47m(SETQ var term)[0m, where the variable [47mvar[0m is declared in a [47mWITH[0m
      declaration or is a stobj name, and [47mterm[0m is an ordinary term
      that returns a single value, that value being a stobj of type
      [47mvar[0m if [47mvar[0m is a stobj

    * [47m(MV-SETQ (var0 ... varn) term)[0m for two or more distinct variables
      [47mvari[0m, where each [47mvari[0m is declared in a [47mWITH[0m declaration or is a
      stobj name, and [47mterm[0m is an ordinary term that returns n+1
      values, where if [47mvari[0m is a stobj then the ith value returned is
      of that type

  Notice that in code, where restrictions on return values are in
  force, no stobj may be let-bound in a [47mDO[0m body or [47mFINALLY[0m clause.
  This is due not only to the explicit restriction above for [47mLET[0m,
  [47mLET*[0m, and [47mMV-LET[0m expressions, but also due to the first condition
  above, on ordinary terms returning a single, non-stobj value.

  We conclude this section by discussing some syntactic restrictions.

  The following restriction applies to [47mloop$[0m expressions meeting the
  following two conditions: [47m:VALUES[0m specifies other than the default
  of [47m(NIL)[0m, and there is at least one [47mloop-finish[0m expression in the
  [47mloop$[0m body.  In that case, there must be a [47mFINALLY[0m clause that ACL2
  recognizes as always executing a [47mreturn[0m call.  This makes sense,
  since in Common Lisp, the value returned by a [47mloop[0m is [47mnil[0m when
  ``falling through'' without executing a [47mreturn[0m; but [47mnil[0m would
  violate the specified [47m:VALUES[0m in the case above.

  As noted above, assignments with [47msetq[0m and [47mmv-setq[0m may only set stobj
  variables and variables declared using [47mWITH[0m.  This restriction
  applies to the innermost [47mloop$[0m that contains the assignment.  The
  following, for example, is illegal because the [47mWITH[0m declaration for
  [47mx[0m is not in the [47mloop$[0m immediately above the assignment to [47mx[0m with
  [47msetq[0m.

    (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)))))))))

  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.

    (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)))))))))

  Every [47mreturn[0m expression in the DO body and (if present) [47mFINALLY[0m
  clause must return a value or [multiple-value]s consistent with
  what is specified by the [47m:VALUES[0m 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.

  It is illegal for a [47mloop$[0m expression to be in the scope of function
  bindings of an [47m[flet][0m or [47m[macrolet][0m expression.

  As noted above, the measure, body, and [47mFINALLY[0m clauses of a DO [47mloop$[0m
  must be fully [badge]d.

  In a function call, it is illegal for a LOOP$ expression to occur in
  a slot whose [ilk] is not [47mnil[0m.


SEMANTICS

  Consider again the initial example in the Informal Introduction
  above.

    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 !>

  We have seen that after initializing variables using [47mWITH[0m clauses,
  each iteration of a [47mDO[0m [47mloop$[0m updates those variables by evaluating
  the body of the loop (i.e., the term after the [47mDO[0m keyword), until a
  [47mreturn[0m expression is executed to return the current value of a term
  --- in this case, the current value of the term, [47my[0m.

  Of course, [47mprogn[0m and [47mreturn[0m 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 [47mloop$[0m
  expression above.  We discuss it below.

    (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.
    )

  The display above is approximate; in particular, it hides some
  logically irrelevant clutter such as [47m[declare][0m forms and it shows
  only arguments of [47mdo$[0m relevant to our discussion of the example
  above.  Also, the display employs user-level syntax (i.e., an
  [3muntranslated term[0m; see [term]).  See also the subsection of
  [47m[lambda$][0m entitled ``About [47mLambda$[0ms and Prover Output.''

  The definition of [47mdo$[0m is given later in this topic, for those who
  care to explore it, but this discussion is intended to be
  self-contained.  [47mDo$[0m operates by maintaining an alist that maps
  variables to values, for all variables referenced in the [47mloop$[0m
  expression --- though only variables that are declared in [47mWITH[0m
  clauses or are stobjs may be modified.  This alist is updated on
  each iteration by calling [47m[apply$][0m on the ``Body Function'' above,
  producing a 3-element list [47m(exit-token val new-alist)[0m.  If
  [47mexit-token[0m is [47m:RETURN[0m then [47mval[0m is returned.  But if [47mexit-token[0m is
  [47mnil[0m, then [47mdo$[0m is called recursively with [47mnew-alist[0m as its alist
  argument.

  To see [47mdo$[0m in action one can submit the following forms.  Here the
  body of [47mf[0m is just the [47mloop$[0m expression shown above.  Notice that [47mf[0m
  is not [guard]-verified; after submitting [47m(verify-guards f)[0m the
  [47mloop$[0m expression is evaluated as a Common Lisp [47mloop[0m call rather
  than using [47mdo$[0m, so there would be no [trace] output.  Don't worry
  about having a precise understanding of the fancy calls of
  [47m[trace!][0m; the comments there should suffice.

    (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)

  Here is the trace output from the final call of [47mf[0m above; analysis
  follows.

    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 !>

  First consider the calls of [47mdo$[0m above.  You can see that [47mX[0m is
  initially bound in the alist to [47m(A B C)[0m, but on successive [47mdo$[0m
  calls, [47mX[0m is bound to successive [47mcdr[0ms of [47m(A B C)[0m.  Meanwhile, the
  accumulator variable [47mY[0m is initially bound to [47mNIL[0m but at each call
  of [47mdo$[0m, the next [47mcar[0m of [47m(A B C)[0m is pushed onto the binding of [47mY[0m.
  Now consider the calls of [47m[apply$][0m.  Up until the last call,
  [47mapply$[0ming the body function results in a triple of the form [47m(mv nil
  nil new-alist)[0m, where [47mnew-alist[0m is supplied as the alist argument
  for the next [47mdo$[0m call.  The last call of [47mapply$[0m on the body
  function gives the result [47m(mv :RETURN (C B A) new-alist)[0m, where [47m(C
  B A)[0m is the value returned by the calls of [47mdo$[0m.

  Now consider this variant of the above example, which was given above
  when introducing [47mFINALLY[0m clauses.

    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 !>

  The corresponding [47mdo$[0m call is similar to that of the preceding
  example, but notice [47m:LOOP-FINISH[0m in place of [47m:RETURN[0m, and notice
  that we show the fourth argument this time: the function
  corresponding to the [47mFINALLY[0m clause.

    (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.
    )

  Above, we also took the opportunity to show the fifth argument of
  [47mdo$[0m, 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 [47m:VALUES[0m keyword in a [47mdo[0m [47mloop$[0m.  If
  omitted and the [47mloop$[0m returns a single ordinary object, the output
  signature is [47m(nil)[0m as here.  The [47mvalues[0m argument to [47mdo$[0m 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 [47mdo$[0m calls.  Since guard
  verification of a [47mdo[0m [47mloop$[0m guarantees termination, the default
  answer is never relevant when dealing with guard verified functions
  containing [47mdo[0m [47mloop$[0ms.

  Here is the definition of [47m[do$][0m.

  [31;1mFunction: [0m<do$>

    (defun do$ (measure-fn alist do-fn finally-fn values dolia)
     (declare (xargs :guard (and (apply$-guard measure-fn '(nil))
                                 (apply$-guard do-fn '(nil))
                                 (apply$-guard finally-fn '(nil))
                                 (weak-dolia-p dolia))))
     (let* ((triple (true-list-fix (apply$ do-fn (list alist))))
            (exit-token (car triple))
            (val (cadr triple))
            (new-alist (caddr triple)))
      (cond
       ((eq exit-token :return) val)
       ((eq exit-token :loop-finish)
        (let*
         ((triple (true-list-fix (apply$ finally-fn (list new-alist))))
          (exit-token (car triple))
          (val (cadr triple)))
         (if (eq exit-token :return) val nil)))
       ((l< (lex-fix (apply$ measure-fn (list new-alist)))
            (lex-fix (apply$ measure-fn (list alist))))
        (do$ measure-fn new-alist
             do-fn finally-fn values dolia))
       (t
        (prog2$
         (let
           ((all-stobj-names
                 (true-list-fix (access dolia dolia :all-stobj-names)))
            (untrans-measure (access dolia dolia :untrans-measure))
            (untrans-do-loop$ (access dolia dolia :untrans-do-loop$)))
          (er
           hard? 'do$
           \"The measure, ~x0, used in the do loop$ ~
                    statement~%~Y12~%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~%~Y32.~|After the execution of the do body the alist ~
                    was~%~Y42.~|Before the execution of the body the measure ~
                    was~%~x5.~|After the execution of the body the measure ~
                    was~%~x6.~|~%Logically, in this situation the do$ returns the ~
                    value of a term whose output signature is ~x7, 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.\"
           untrans-measure untrans-do-loop$ nil
           (eviscerate-do$-alist alist all-stobj-names)
           (eviscerate-do$-alist new-alist all-stobj-names)
           (apply$ measure-fn (list alist))
           (apply$ measure-fn (list new-alist))
           values))
         (loop$-default-values values new-alist))))))

  We conclude by returning to an earlier example that illustrates
  runtime guard-checking.  But this time we do some tracing, as
  indicated.

    (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)

  As before, we have a guard violation.  The trace output is explained
  below.

    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 !>

  To understand the trace output above, we first take a look at the
  translation of the [47mloop$[0m expression above.  This time we show the
  corresponding [47mdo$[0m form with [47m[declare][0m forms included, but as before
  some parts of this form are simplified, untranslated, or elided.
  (You can see the exact translation by applying [47m:[0m[47m[trans][0m to the [47mdo$[0m
  call.)  Note that [47mdo-body-guard-wrapper[0m is just an identity
  function (on its first argument) used by the implementation, but it
  is handy here for the explanation that follows.

    (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))))
      .....)

  Recall that [47mdo$[0m works by repeatedly applying the given lambda to its
  alist argument, which initially binds [47m'X[0m to [47mLST[0m as shown above.
  [47mDo$[0m recurs when that application returns a triple [47m(mv nil nil
  new-alist)[0m, where [47mnew-alist[0m is the alist returned by the body of
  the [47mloop$[0m expression.  But when [47mdo$[0m applies the given [lambda]
  object, it first checks the [47m:guard[0m of that lambda.  We also see
  that before [47mdo$[0m recurs, it applies its [47mmeasure-fn[0m argument to the
  input alist and to [47mnew-alist[0m.

  So let's focus on the following from the end of the trace output
  above.

    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)

  The first [47mDO-BODY-GUARD-WRAPPER[0m call comes from the guard of the
  lambda that represents the body of the [47mdo$[0m loop, from the
  expression [47m(apply$ do-fn (list alist))[0m in the definition of [47mdo$[0m
  (above).  Here [47malist[0m is [47m((X D))[0m, so the conjunct [47m(CONSP (CDR
  (ASSOC-EQ-SAFE 'X ALIST)))[0m from that lambda's guard is true.  The
  second call of [47mDO-BODY-GUARD-WRAPPER[0m comes from the expression
  [47m(apply$ measure-fn (list new-alist))[0m in the definition of [47mdo$[0m.  But
  [47mnew-alist[0m is [47mnil[0m, so the conjunct [47m(CONSP (CDR (ASSOC-EQ-SAFE 'X
  ALIST)))[0m from the measure lambda's guard is false, so the guard
  evaluates to [47mnil[0m.


Subtopics

  [Do$]
      Definition of [47mdo$[0m")
 (DO-NOT
  (HINTS)
  "Instruct the theorem prover not to do certain things.

  See [hints] for documentation about the [47m:do-not[0m keyword for prover
  [47m:hints[0m.

  See [do-not-hint] for documentation about the [47mdo-not[0m macro that
  controls a mechanism for automatically suggesting [47m:do-not[0m and
  [47m:do-not-induct[0m hints.")
 (DO-NOT-INDUCT
    (POINTERS)
    "See [hints] for information about the keyword [47m:do-not-induct[0m.")
 (DOC
  (DOCUMENTATION)
  "[Documentation] at the terminal

  The [47m:doc[0m command may be used at the ACL2 prompt to access the ACL2
  system [documentation].  Usually (when the [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 [documentation].  In particular, consider using the {ACL2+Books
  Manual |
  http://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html},
  for topics documented in the ACL2 community [books] or in the ACL2
  system (where the latter are rearranged).

  If you are not happy with the way text is displayed using [47m:doc[0m, see
  [xdoc::terminal].

  Alternatively, consider using the ACL2-Doc Emacs browser; see
  [ACL2-Doc].

    Examples:
    ACL2 !>:doc DEFTHM          ; print documentation of DEFTHM
    ACL2 !>:doc logical-name    ; print documentation of LOGICAL-NAME

    General Form:
    ACL2>:doc name

  Note that links are always printed with respect to the [47m\"ACL2\"[0m package
  (that is, as though the current package were [47m\"ACL2\"[0m).  So for
  example, a link to the present topic will be displayed as [47m[doc][0m,
  not as [47m[acl2::doc][0m, 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 [ACL2-Doc]).

  Note that [community-book] [47mxdoc/top[0m redefines [47m:doc[0m (using
  [add-ld-keyword-alias!]) to invoke the similar macro [47mxdoc[0m, which
  can access documentation topics defined in books.")
 (DOC-TERMINAL-TEST-1
  (DOCUMENTATION)
  "Short

  [31;1mSymbol [47mEQUAL[0m[31;1m and the rest is still bold.[0m")
 (DOC-TERMINAL-TEST-2
  (DOCUMENTATION)
  "Short

  [4mStart underline [31;1mStart bold [3mStart italics [47mTYPEWRITER FONT [WHICH ENDS
  HERE][0m[4m[31;1m[3m Bold italics underlined[0m[4m[31;1m Bold underlined.[0m[4m Underlined[0m Normal
  text")
 (DOCUMENTATION
  (ACL2)
  "Information about options for downloading and viewing the ACL2
  documentation, contributing documentation, and the available tools
  for documenting your own books.


Available Documentation

  If you are new to ACL2, see the [ACL2-tutorial] for introductory
  tours, tutorials, and information about textbooks about ACL2.  The
  {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2} also
  provides many links to academic publications about ACL2, including
  the ACL2 Workshop series.

  Beyond these resources, there is a vast [31;1mACL2+Books Manual[0m with
  reference material covering the ACL2 system itself and also many
  [community-books].  There are a few ways to access the manual:

    * [31;1mThe online version (recommended).[0m If you expect to have an internet
      connection while using the documentation, you may prefer to use
      the online version of the {ACL2+Books Manual |
      http://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}.

    * [31;1mA local version.[0m If you sometimes work without an internet
      connection, you can {download | download/} 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 [3mBuilding the manual[0m in [books-certification].

    * [31;1mThe ACL2-Doc Emacs version.[0m 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 [ACL2-doc] for details.

  While you are using ACL2, you can get documentation at the terminal
  with the [47m:[0m[47m[doc][0m command, e.g., by typing [47m:doc rewrite[0m.  This is
  often handy, but note that it won't show you any documentation for
  books that you haven't loaded yet!

  Separately from the ACL2+Books Manual, the [4mACL2 User's Manual[0m is
  distributed with ACL2.  This is much like the ACL2+Books Manual but
  it does not include documentation from the books.  A web-based copy
  is included with the ACL2 distribution in directory [47mdoc/manual/[0m,
  and you can easily get to it by opening file [47mdoc/home-page.html[0m in
  your browser.


Documenting Your Books

  Documentation is written using [xdoc], and may be found in the
  [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,
  [47mbooks/system/doc/acl2-doc.lisp[0m.  (Please do not edit ACL2 source
  file [47mdoc.lisp[0m, which is generated from that book.  More generally,
  edit only files under the [47mbooks/[0m directory.)

  You can also use XDOC to document your own books and to build custom
  manuals for your organization.

  [31;1mRemark for Experienced Users[0m.  Occasionally it might make sense to
  add a link to your book's documentation from the ACL2 system
  documentation, which is in [community-book]
  [47mbooks/system/doc/acl2-doc.lisp[0m. You are welcome to do so, but in
  that case, also add to the constant [47m*acl2-broken-links-alist*[0m near
  the top of that file, as described in a comment in that constant.
  For example, that constant's value has the following line.

    (FTY::DEFPROD \"[books]/centaur/fty/top.lisp\")

  That line may have been added because in the form [47m(defxdoc defrec
  ...)[0m in [47macl2-doc.lisp[0m, we find a link to [47mfty::defprod[0m.  You can do
  similarly for your own added link.

  If your topic is not in the [47m\"ACL2\"[0m package, such as in the example
  link [47mfty::defprod[0m above, then add a suitable [47m[include-book][0m form to
  [47mbooks/system/doc/cert.acl2[0m.  For example, that file includes the
  line

    (include-book \"centaur/fty/portcullis\" :dir :system)

  in order to define the [47m\"FTY\"[0m package.  End of Remark for Experienced
  Users


Other Resources

  If you want documentation on an ACL2 function or macro that is not
  documented, there are still several alternatives.

    ACL2 !>:args fn

  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
  [47mfn[0m is defined as a function or macro.

  You might also want to type:

    ACL2 !>:pc fn

  which will print the [command] that introduced [47mfn[0m.  You should see
  [command-descriptor] for details on the kinds of input you can give
  the [47m:[0m[47m[pc][0m command.


Subtopics

  [ACL2-doc]
      A custom Emacs browser for reading ACL2 [documentation]

  [ACL2-doc-summary]
      Summary of [ACL2-doc] commands

  [Args]
      [47margs[0m, [47m[guard][0m, [47mtype[0m, [47m[constraint][0m, etc., of a function symbol

  [Broken-link]
      Placeholder for link to documentation that resides in the community
      books

  [Course-materials]
      Some ACL2 course materials

  [Doc]
      [Documentation] at the terminal

  [Doc-terminal-test-1]
      Short

  [Doc-terminal-test-2]
      Short

  [Documentation-copyright]
      Copyright and authorship of documentation

  [Finding-documentation]
      Searching the documentation

  [Loop$-primer]
      Primer for using [47m[loop$][0m

  [Operational-semantics]
      Modeling State Machines

  [Pointers]
      Links pointing to relevant documentation topics

  [Recursion-and-induction]
      Recursion and Induction")
 (DOCUMENTATION-COPYRIGHT
  (COPYRIGHT DOCUMENTATION)
  "Copyright and authorship of documentation

  There are two manuals associated with ACL2: the ACL2 User's Manual
  and the ACL2+Books Manual.  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 [community-books].

  The ACL2 User's Manual is copyrighted under the terms of the [47mLICENSE[0m
  file distributed with ACL2.  Its original authors are the ACL2
  authors, but it is now defined in an ACL2 community book,
  [47mbooks/system/doc/acl2-doc.lisp[0m, so that members of the ACL2
  community may contribute to it.

  The ACL2+Books Manual is a mechanically generated mashup derived from
  both the ACL2 User's Manual and the [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
  [copyright].  When a book is named, the content was extracted from
  that book which may be inspected for authorship, copyright, and
  license terms.

  There are two standard tools for browsing these manuals, other than
  using the [47m:[0m[47m[doc][0m command at the terminal.

    * [31;1mThe ACL2 [Xdoc] Fancy Viewer.[0m This tool, written by Jared Davis, is
      included with the web-based version of each manual.
      Information on copyright and licensing are provided in {its
      LICENSE file | LICENSE}.

    * [31;1mThe [ACL2-doc] Emacs browser.[0m This tool, authored by Matt Kaufmann
      and J Strother Moore, is distributed with ACL2 and is licensed
      under the terms of the [47mLICENSE[0m file distributed with ACL2.")
 (DOUBLE-FLOAT (POINTERS) "See [df].")
 (DOUBLE-FLOAT (POINTERS) "See [df].")
 (DOUBLE-REWRITE
  (REWRITE)
  "Cause a term to be rewritten twice

  Logically, [47mdouble-rewrite[0m is the [47m[identity][0m function: [47m(double-rewrite
  x)[0m is equal to [47mx[0m.  However, the ACL2 rewriter treats calls of
  [47mdouble-rewrite[0m in the following special manner.  When it encounters
  a term [47m(double-rewrite u)[0m, it first rewrites [47mu[0m in the current
  context, and then the rewriter rewrites the result.

  Such double-rewriting is rarely necessary, but it can be useful when
  rewriting under non-trivial equivalence relations (see
  [equivalence]).  The following example will illustrate the issue.

    ; 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)))

  We might expect the proof of this final [47mthm[0m to succeed by the
  following reasoning.  It is immediate from [47mlemma-3[0m provided we can
  establish [47m(foo (h1 a))[0m.  By the [47mdefcong[0m event above, we know that
  [47m(foo (h1 a))[0m equals [47m(foo (h2 a))[0m provided [47m(my-equiv (h1 a) (h2 a))[0m;
  but this is immediate from [47mlemma-1[0m.  And finally, [47m(foo (h2 a))[0m is
  true by [47mlemma-2[0m.

  Unfortunately, the proof fails.  But fortunately, ACL2 gives the
  following useful warning when [47mlemma-3[0m is submitted:

    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.

  We can follow the warning's advice by changing [47mlemma-3[0m to the
  following.

    (defthm lemma-3
      (implies (foo (double-rewrite x))
               (equal (g x) x)))

  With this change, the proof succeeds for the final [47mthm[0m above.

  In practice, it should suffice for users to follow the advice given
  in the ``[47mDouble-rewrite[0m'' warnings, by adding calls of
  [47mdouble-rewrite[0m 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
  [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 {ACM Digital Library |
  http://portal.acm.org/toc.cfm?id=1217975}); you might also find it
  for free {here |
  http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.90.7190&rep=rep1&type=pdf}.

  [31;1mSuggesting congruence rules.[0m

  Sometimes the best way to respond to a ``[47mDouble-rewrite[0m'' warning may
  be to prove a congruence rule.  Consider for example this rule.

    (defthm insert-sort-is-id
      (perm (insert-sort x) x))

  Assuming that [47mperm[0m has been identified as an [equivalence] relation
  (see [defequiv]), we will get the following warning.

    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.

  The problem is that the second occurrence of [47mx[0m (the right-hand side
  of the rule [47minsert-sort-is-id[0m) is in a context where [47mperm[0m is to be
  maintained, yet in this example, the argument [47mx[0m of [47minsert-sort[0m on
  the left-hand side of that rule is in a context where [47mperm[0m will not
  be maintained.  This can lead one to consider the possibility that
  [47mperm[0m could be maintained in that left-hand side occurrence of [47mx[0m,
  and if so, to prove the following congruence rule.

    (defcong perm perm (insert-sort x) 1)

  This will eliminate the above warning for [47minsert-sort-is-id[0m.  More
  important, this [47m[defcong][0m event would probably be useful, since it
  would allow rewrite rules with equivalence relation [47mperm[0m to operate
  on the first argument of any call of [47minsert-sort[0m whose context
  calls for maintaining [47mperm[0m.

  [31;1mDetails on double-rewrite.[0m

  The reader who wants these details may first wish to see
  [equivalence] for relevant review.

  The ACL2 rewriter takes a number of contextual arguments, including
  the generated equivalence relation being maintained (see
  [congruence]) and an association list that maps variables to terms.
  We call the latter alist the [47munify-subst[0m 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
  [47mthm[0m above.

    (equal (g (h1 a)) (h1 a))

  This rewrite is performed with the empty alist ([47munify-subst[0m), and is
  begun by rewriting the first argument (in that same empty
  [47munify-subst[0m):

    (g (h1 a))

  Note that the only equivalence relation being maintained at this
  point is [47mequal[0m.  Now, the rewriter notices that the left-hand side
  of [47mlemma-3[0m, which is [47m(g x)[0m, matches [47m(g (h1 a))[0m.  The rewriter thus
  creates a [47munify-subst[0m binding [47mx[0m to [47m(h1 a)[0m: [47m((x . (h1 a)))[0m.  It now
  attempts to rewrite the hypothesis of [47mlemma-3[0m to [47mt[0m under this
  [47munify-subst[0m.

  Consider what happens now if the hypothesis of [47mlemma-3[0m is [47m(foo x)[0m.
  To rewrite this hypothesis under a [47munify-subst[0m of [47m((x . (h1 a)))[0m,
  it will first rewrite [47mx[0m under this [47munify-subst[0m.  The key
  observation here is that this rewrite takes place simply by
  returning the value of [47mx[0m in the [47munify-subst[0m, namely [47m(h1 a)[0m.  No
  further rewriting is done!  The efficiency of the ACL2 rewriter
  depends on such caching of previous rewriting results.

  But suppose that, instead, the hypothesis of [47mlemma-3[0m is [47m(foo
  (double-rewrite x))[0m.  As before, the rewriter dives to the first
  argument of this call of [47mfoo[0m.  But this time the rewriter sees the
  call [47m(double-rewrite x)[0m, which it handles as follows.  First, [47mx[0m is
  rewritten as before, yielding [47m(h1 a)[0m.  But now, because of the call
  of [47mdouble-rewrite[0m, the rewriter takes [47m(h1 a)[0m and rewrites it under
  the empty [47munify-subst[0m.  What's more, because of the [47mdefcong[0m event
  above, this rewrite takes place in a context where it suffices to
  maintain the equivalence relation [47mmy-equiv[0m.  This allows for the
  application of [47mlemma-1[0m, hence [47m(h1 a)[0m is rewritten (under
  [47munify-subst[0m = [47mnil[0m) to [47m(h2 a)[0m.  Popping back up, the rewriter will
  now rewrite the call of [47mfoo[0m to [47mt[0m using [47mlemma-2[0m.

  The example above explains how the rewriter treats calls of
  [47mdouble-rewrite[0m, but it may leave the unfortunate impression that
  the user needs to consider each [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[linear][0m rule
  carefully, just in case a call of [47mdouble-rewrite[0m 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 ([47m:[0m[47m[rewrite][0m or [47m:[0m[47m[linear][0m)
  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 [47m:[0m[47m[rewrite][0m rule, and for hypotheses or full conclusion (as
  opposed to just the trigger term) of a [47m:[0m[47m[linear][0m rule.

  If you do see a ``[Double-rewrite]'' warning, then should you add the
  indicated call(s) of [47mdouble-rewrite[0m?  At the time of writing this
  [documentation], the answer is not clear.  Early experiments with
  double rewriting suggested that it may be too expensive to call
  [47mdouble-rewrite[0m 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 [47mdouble-rewrite[0m 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 [47mdouble-rewrite[0m
  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:
  [47m([0m[47m[set-inhibit-warnings][0m[47m \"Double-rewrite\")[0m.

  Finally, we note that it is generally not necessary to call
  [47mdouble-rewrite[0m in order to get its effect in the following case,
  where the discussion above might have led one to consider a call of
  [47mdouble-rewrite[0m: a hypothesis is a variable, or more generally, we
  are considering a variable occurrence that is a branch of the
  top-level [47mIF[0m 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
  [47mdouble-rewrite[0m.  Here is a simple illustrative example.  Notice
  that [47mfoo-holds[0m applies to prove the final [47m[thm][0m below, even without
  a call of [47mdouble-rewrite[0m in the hypothesis of [47mfoo-holds[0m, and that
  there is no ``[Double-rewrite]'' warning when submitting [47mfoo-holds[0m.

    (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)))")
 (DOUBLET-LISTP (POINTERS)
                "See [system-utilities].")
 (DUMB-NEGATE-LIT (POINTERS)
                  "See [system-utilities].")
 (DUMB-OCCUR (POINTERS)
             "See [system-utilities].")
 (DUMB-OCCUR-VAR (POINTERS)
                 "See [system-utilities].")
 (DYNAMICALLY-MONITOR-REWRITES (POINTERS)
                               "See [dmr].")
 (E/D
  (THEORIES THEORY-FUNCTIONS)
  "Enable/disable rules

  The macro [47me/d[0m creates theory expressions for use in [47m[in-theory][0m hints
  and events.  It provides a convenient way to [47m[enable][0m and [47m[disable][0m
  simultaneously, without having to write arcane theory expressions.
  For related utilities, see [enable] and see [disable].

    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)

  where each [47menables-i[0m and [47mdisables-i[0m is a list of runic designators;
  see [theories], see [enable], and see [disable].  Note that the
  concluding [47mdisables-n[0m may be omitted.

  The [47me/d[0m macro takes any number of lists suitable for the [47m[enable][0m and
  [47m[disable][0m macros.  The event

    (in-theory (e/d (e00 e01 e02 ...) (d00 d01 d02 ...)
                    ...
                    (en0 en1 en2 ...) (dn0 dn1 dn2 ...)

  creates a theory that is equivalent to the following sequence of
  [47m[in-theory][0m events.  (An analogous similar effect takes place for
  [47m:in-theory[0m [hints].

    (in-theory (enable e00 e01 e02 ...))
    (in-theory (disable d00 d01 d02 ...))
    ...
    (in-theory (enable en0 en1 en2 ...))
    (in-theory (disable dn0 dn1 dn2 ...))")
 (EARLY-TERMINATION
  (PARALLEL-PROGRAMMING)
  "Early termination for [47m[pand][0m and [47m[por][0m.

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

  The evaluation of [47m(and expr1 expr2)[0m returns [47mnil[0m if [47mexpr1[0m evaluates to
  [47mnil[0m, avoiding the evaluation of [47mexpr2[0m.  More generally, the
  evaluation of [47m(and expr1 expr2 ... exprk)[0m terminates with a return
  value of [47mnil[0m as soon as any [47mexpri[0m evaluates to [47mnil[0m --- no [47mexprj[0m is
  evaluated in this case for [47mj > i[0m.  This so-called ``lazy
  evaluation'' of [47m[and][0m terms can thus save some computation; roughly
  speaking, the smaller the [47mi[0m, the more computation is saved.

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

  Consider the following functions that compute whether a tree is valid
  (see [granularity] for a discussion of the granularity form).

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

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

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

  The concept of early termination also applies to [47m[por][0m, except that
  early termination occurs when an argument evaluates to non-[47mnil[0m.")
 (EC-CALL
  (GUARD ACL2-BUILT-INS)
  "Execute a call in the ACL2 logic instead of raw Lisp

  The name ``[47mec-call[0m'' represents ``executable-counterpart call.'' This
  utility is intended for users who are familiar with guards.  See
  [guard] for a general discussion of guards.

  Logically, [47mec-call[0m behaves like the identity macro; during proofs,
  [47m(ec-call TERM)[0m is typically replaced quickly by [47mTERM[0m during a proof
  attempt.  However, [47mec-call[0m causes function calls to be evaluated in
  the ACL2 logic rather than raw Lisp, as explained below.

    General Forms:
    (ec-call (fn term1 ... termk))
    (ec-call (fn term1 ... termk) :dfs-in 'dfs-in :dfs-out dfs-out)

  where [47mfn[0m is a known function symbol other than those in the list that
  is the value of the constant [47m*ec-call-bad-ops*[0m.  (But see the Note
  on Inlining below for an exception pertaining to inlining.)  In
  particular, [47mfn[0m is not a macro.  The second form is only relevant
  for those who use [df]s and is discussed at the end of this topic.

  Semantically, [47m(ec-call (fn term1 ... termk))[0m equals [47m(fn term1 ...
  termk)[0m.  However, this use of [47mec-call[0m has two effects.

      (1) [Guard] verification generates no proof obligations from the
      guard of [47mfn[0m for this call.  Indeed, guards need not have been
      verified for [47mfn[0m.

      (2) During evaluation, after the arguments of [47mfn[0m are evaluated as
      usual, the executable-counterpart of [47mfn[0m is called, rather than
      its submitted version (see [evaluation]).  That is, the call of
      [47mfn[0m is made on its evaluated arguments as though this call is
      being made in the ACL2 top-level loop, rather than in raw Lisp.
      In particular, the [guard] of [47mfn[0m is checked, at least by
      default (see [set-guard-checking]).

  The use of [47mec-call[0m does not turn off guard-checking, but that can be
  accomplished by using [47m[with-guard-checking][0m as well.  Consider the
  following example.

    (defun f1 (x)
      (declare (xargs :guard t))
      (ec-call (nth t x)))

  This definition is admitted, but evaluation of [47m(f1 '(a b c))[0m
  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 [47mf1[0m.

    (defun f1 (x)
      (declare (xargs :guard t))
      (with-guard-checking nil (ec-call (nth t x))))

  Note that in the term [47m(ec-call (fn term1 ... termk))[0m, only the
  indicated call of [47mfn[0m is made in the logic; each [47mtermi[0m is evaluated
  in the normal manner.  If you want an entire term evaluated in the
  logic, wrap [47mec-call[0m around each function call in the term (other
  than calls of [47mif[0m and [47mec-call[0m).

  [31;1mTechnical Remark[0m (probably best ignored).  During evaluation of a
  call of [47m[defconst][0m or [47m[defpkg][0m in raw Lisp, a form [47m(ec-call (fn
  term1 ... termk))[0m is treated as [47m(fn term1 ... termk)[0m, that is,
  without calling the executable-counterpart of [47mfn[0m.  This situation
  occurs when loading a compiled file (or expansion file) on behalf
  of an [47m[include-book][0m event.  The reason is technical:
  executable-counterparts are defined below a book's events in the
  book's compiled file.  End of Technical Remark.

  Here is another small example.  We define [47mfoo[0m recursively but with
  guard verification inhibited on the recursive call, which is to be
  evaluated in the ACL2 logic.

    ACL2 !>(defun foo (x y)
            (declare (xargs :guard (consp y)))
            (if (consp x)
                (cons (car x) (ec-call (foo (cdr x) (cdr y))))
              (car y)))

    The admission of FOO is trivial, using the relation O< (which is known
    to be well-founded on the domain recognized by O-P) and the measure
    (ACL2-COUNT X).  We could deduce no constraints on the type of FOO.

    Computing the guard conjecture for FOO....

    The guard conjecture for FOO is trivial to prove.  FOO is compliant
    with Common Lisp.

    Summary
    Form:  ( DEFUN FOO ...)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     FOO
    ACL2 !>(foo '(2 3 4 5) '(6 7))

    ACL2 Error in TOP-LEVEL:  The guard for the function call (FOO X Y),
    which is (CONSP Y), is violated by the arguments in the call
    (FOO '(4 5) NIL).  To debug see :DOC print-gv, see :DOC trace, and
    see :DOC wet.  See :DOC set-guard-checking for information about suppressing
    this check with (set-guard-checking :none), as recommended for new
    users.

    ACL2 !>

  The error above arises because eventually, [47mfoo[0m recurs down to a value
  of parameter [47my[0m that violates the guard.  This is clear from tracing
  (see [trace$] and see [trace]).  Each call of the
  executable-counterpart of [47mfoo[0m checks the guard and then invokes the
  submitted version of [47mfoo[0m (see [evaluation]).  The submitted version
  calls the executable-counterpart on the recursive call.  When the
  guard check fails we get a violation.

    ACL2 !>(trace$ foo)
     ((FOO))
    ACL2 !>(foo '(2 3 4 5) '(6 7))
    1> (ACL2_*1*_ACL2::FOO (2 3 4 5) (6 7))
      2> (FOO (2 3 4 5) (6 7))
        3> (ACL2_*1*_ACL2::FOO (3 4 5) (7))
          4> (FOO (3 4 5) (7))
            5> (ACL2_*1*_ACL2::FOO (4 5) NIL)

    ACL2 Error in TOP-LEVEL:  The guard for the function call (FOO X Y),
    which is (CONSP Y), is violated by the arguments in the call
    (FOO '(4 5) NIL).  To debug see :DOC print-gv, see :DOC trace, and
    see :DOC wet.  See :DOC set-guard-checking for information about suppressing
    this check with (set-guard-checking :none), as recommended for new
    users.

    ACL2 !>

  If we turn off guard errors then we can see the trace as above, but
  where we avoid calling the raw Lisp function when the guard fails
  to hold.

    ACL2 !>:set-guard-checking nil

    Masking guard violations but still checking guards except for self-
    recursive calls.  To avoid guard checking entirely, :SET-GUARD-CHECKING
    :NONE.  See :DOC set-guard-checking.

    ACL2 >(foo '(2 3 4 5) '(6 7))
    1> (ACL2_*1*_ACL2::FOO (2 3 4 5) (6 7))
      2> (FOO (2 3 4 5) (6 7))
        3> (ACL2_*1*_ACL2::FOO (3 4 5) (7))
          4> (FOO (3 4 5) (7))
            5> (ACL2_*1*_ACL2::FOO (4 5) NIL)
              6> (ACL2_*1*_ACL2::FOO (5) NIL)
                7> (ACL2_*1*_ACL2::FOO NIL NIL)
                <7 (ACL2_*1*_ACL2::FOO NIL)
              <6 (ACL2_*1*_ACL2::FOO (5))
            <5 (ACL2_*1*_ACL2::FOO (4 5))
          <4 (FOO (3 4 5))
        <3 (ACL2_*1*_ACL2::FOO (3 4 5))
      <2 (FOO (2 3 4 5))
    <1 (ACL2_*1*_ACL2::FOO (2 3 4 5))
    (2 3 4 5)
    ACL2 >

  Note on Inlining.  Although in general, the form [47m(ec-call (fn term1
  ... termk))[0m is only legal if [47mfn[0m is a function symbol, such a form
  is also legal if [47mfn[0m is introduced with [47m[defun-inline][0m, or with
  [47m[define][0m using keyword argument [47m:inline t[0m.  In those cases, [47mfn[0m is a
  macro whose calls expand to corresponding calls of [47mfn$INLINE[0m, the
  symbol in the same package as [47mfn[0m but with the string [47m\"$INLINE\"[0m
  added as a suffix to the [47m[symbol-name][0m of [47mfn[0m.  We do not however
  extend this exception to macros in general, even when
  [47m[add-macro-fn][0m has been invoked.  Consider the following example.

    (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)))

  Consider what would happen if this were legal, where [47m(ec-call (mac))[0m
  used the macro-alias, [47mfoo[0m, for [47mmac[0m.  Then in the first pass of the
  [47m[encapsulate][0m form above, the final [47m[defthm][0m event would prove,
  since (ec-call (mac)) is treated as (ec-call (bar)).  But on the
  second pass, ACL2 would store [47mbad[0m as a theorem even though [47m(h)[0m
  would evaluate to [47mnil[0m, since the macro-alias of [47mmac[0m is [47mfoo[0m on the
  second pass.

  We conclude with a discussion of the second General Form:

    (ec-call (fn term1 ... termk) :dfs-in 'dfs-in :dfs-out 'dfs-out)

  Note that either or both keyword arguments may be omitted, and if
  both are included then they can be given in either order.

  See [df] for background on dfs.  Here is an example.

    ACL2 !>(ec-call (binary-df+ (df1) (df1)) :dfs-in '(t t) :dfs-out '(t))
    #d2.0
    ACL2 !>

  The keyword arguments indicate, respectively, [47mbinary-df+[0m takes two df
  arguments and returns a single df value.  Without those arguments
  ACL2 would report an error.

  The next example illustrates the use of [47m:dfs-out[0m for multiple value
  returns.  First define [47mg[0m as follows.

    (defun g (x)
      (mv (df+ (df1) (to-df x)) (- x 1)))

  The use of [47m:dfs-out[0m below tells ACL2 that the given expression [47m(g 3)[0m
  returns two values: a df and an ordinary value.  In the language of
  :DOC [df]: [47m(g 3)[0m is a df{0} expression and is not a df{1}
  expression.  Note that the argument of [47mg[0m is an ordinary expression,
  not a df, so no [47m:dfs-in[0m argument is necessary.

    ACL2 !>(ec-call (g 3) :dfs-out '(t nil))
    (#d4.0 2)
    ACL2 !>

  Returning to the second General Form, notice that [47mdfs-in[0m and [47mdfs-out[0m
  are lists of Booleans, which must be quoted, that indicate for [47mfn[0m
  which inputs or values (respectively) are dfs.  For example, if [47mfn[0m
  returns a single value, then [47mdfs-out[0m is [47m(t)[0m if the call of [47mfn[0m is a
  df, else [47mdfs-out[0m is optional but may be supplied as [47m(nil)[0m.  If [47mfn[0m
  returns n values where n is greater than 1, then [47mdfs-out[0m should be
  a list of length n where for each zero-based index i less than n,
  the ith element of [47mdfs[0m is [47mt[0m if the ith return value is a df (or
  more precisely, in the language of :DOC [df], calls of [47mfn[0m are df{i}
  expressions), else [47mnil[0m.  The rules for the [47m:dfs-in[0m argument are
  analogous for inputs of the call of [47mfn[0m.

  When there are no df inputs (respectively, outputs) of the call, then
  [47m:dfs-in[0m (respectively, [47m:dfs-out[0m may be omitted or supplied as [47mnil[0m
  or [47m'nil[0m.")
 (EFFICIENCY
  (DEBUGGING PROOF-AUTOMATION PROGRAMMING)
  "Efficiency considerations

  This topic is a grab-bag of ideas for the efficient use of ACL2,
  including proofs and programming.  It is far from complete, and
  [tips] for using ACL2 effectively may be found throughout the
  [documentation].  The present topic will, ideally, improve over
  time, both in its content and in its organization.  Please
  contribute!

  Here we discuss primarily time efficiency rather than space
  efficiency.  You can time forms using [47m[time$][0m.  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.


Proof efficiency

  Perhaps the most basic idea for carrying out proofs efficiently is to
  use rewriting effectively; 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.

    * Consider minimizing the number of hypotheses of a rule.  See
      [remove-hyps] for a tool that can help with that.

    * Manage [theories] effectively.  See [accumulated-persistence] for a
      way to identify rules that might best be [disable]d.  In
      particular, it can be useful to disable functions whose
      expansions generate large case splits (see [splitter]);
      otherwise, sometimes it can be useful to limit case-splits with
      [47m[set-case-split-limitations][0m.

    * When many similar proofs are being performed (for example, for
      families of similar theorems generated by macros), the tool
      [removable-runes] may be helpful.

  Sometimes rewriting is slow for inherent algorithmic reasons.  For
  example, if you have a binary function, [47mop[0m, and you prove the
  [rewrite] rules [47m(equal (op x y) (op y x)[0m) and [47m(equal (op x (op y
  z)) (op y (op x z)))[0m, then ACL2 will use an [47mn^2[0m algorithm to put
  arguments in order, essentially with bubblesort, in a sequence like
  this:

    (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)))

  In such a case, you may find it very helpful to create a suitable
  [meta] rule or a [clause-processor] rule, to implement an [47mn*log(n)[0m
  algorithm.  You may consider creating calls of [47m[hide][0m to avoid
  exploring terms that are in the expected form.  Calls of [47mhide[0m may
  be removed when ready either with a suitable [47m:expand[0m hint or by
  enabling a [rewrite] rule [47m(equal (hide x) x)[0m.

  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.

    (set-rw-cache-state nil)

  Some system behaviors can be modified using [47m[defattach-system][0m ---
  also see [system-attachments] --- typically by modifying
  heuristics.  You can find all attachments by evaluating
  [47m(all-attachments (w state))[0m and all built-in such attachments by
  evaluating [47m(global-val 'attachments-at-ground-zero (w state))[0m,
  except for a few exceptions (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.

    (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)

  In some cases books may provide more sophisticated uses of
  [47m[defattach-system][0m (or [47m[defattach][0m).  For a key example, see
  [47m[use-trivial-ancestors-check][0m.

  Another way to speed up system functions can be by using
  [memoization].  Here is an example from
  [47mbooks/projects/stateman/stateman22.lisp[0m.

    (memoize 'acl2::sublis-var1
             :condition '(and (null acl2::alist)
                              (consp acl2::form)
                              (eq (car acl2::form) 'HIDE)))

  See [memoized-prover-fns] for a convenient way to do such memoization
  that automatically clears memoization tables after each event.
  (Also see [clear-memoize-table] and [clear-memoize-tables], and see
  [hons-wash] for another way to clean up after memoization.)
  Comments in the book [47mbooks/tools/memoize-prover-fns.lisp[0m 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.

  The following may be helpful at the level of book certification, and
  are discussed in :doc certify-book-debug.

    (set-serialize-character-system nil)
    (set-bad-lisp-consp-memoize nil)
    (set-inhibit-output-lst '(proof-tree event))


Programming efficiency

  Ideas for efficient programming include the use of compilation for
  host Lisps (other than CCL and SBCL, which compile automatically);
  see [comp] and [set-compile-fns].  For [logic]-mode functions,
  verify [guard]s if feasible; otherwise consider using
  [program]-mode wrappers (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 [hons-and-memoization].
  Single-threaded objects (see [stobj]), [arrays], [multiple-value]
  return, and [47m[mbe][0m are helpful programming constructs provided by
  ACL2 for efficient execution.  Some built-in functions are
  constructed for efficiency; see for example [47m[cons-with-hint][0m to
  reduce consing and [read-file-into-string] for obtaining the
  contents of a file quickly.

  You might find [47m[type][0m [declaration]s to be useful.  In particular, if
  your host Lisp is GCL then the use of the declaration [47m(signed-byte
  64)[0m, or any stronger declaration (e.g., [47m(unsigned-byte 63)[0m,
  [47m(signed-byte 12)[0m, or [47m(integer 0 100)[0m), can provide dramatic
  performance improvements in compiled code.  You can peruse that
  code using [disassemble$].

  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 [47m[type][0m [declaration]s for numbers in place of
  [47m[xargs][0m [47m:[0m[47m[guard][0m.


Miscellaneous efficiency ideas

  The use of [47m[make-event][0m can sometimes reduce computation time; see
  for example [using-tables-efficiently] and [defconsts].

  You can [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 --- also see [profile-ACL2] and [profile-all] --- 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.

    (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

  For computations and proofs that may benefit from parallel
  computation, you could build the variant ACL2(p) of ACL2.  See
  [parallelism].")
 (EIGHTH
  (NTH ACL2-BUILT-INS)
  "Eighth member of the list

  See any Common Lisp documentation for details.")
 (ELIM
  (RULE-CLASSES)
  "Make a destructor elimination rule

  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.

  The following example of an [47m:elim[0m rule is an important one, and is
  built into ACL2.

    (defaxiom car-cdr-elim
      (implies (consp x)
               (equal (cons (car x) (cdr x)) x))
      :rule-classes :elim)

  The class of [47m:elim[0m rules is fundamentally quite different from the
  more common class of [47m:[0m[47m[rewrite][0m rules.  Briefly put, a [47m:rewrite[0m
  rule replaces instances of its left-hand side with corresponding
  instances of its right-hand side.  But an [47m:elim[0m rule, on the other
  hand, has the effect of generalizing so-called ``destructor''
  function applications to variables.  In essence, applicability of a
  [47m:rewrite[0m rule is based on matching its left-hand side, while
  applicability of an [47m:elim[0m rule is based on the presence of at least
  one destructor term.

  For example, a conjecture about [47m(car x)[0m and [47m(cdr x)[0m can be replaced
  by a conjecture about new variables [47mx1[0m and [47mx2[0m, as shown in the
  following example.  (Run the command [47m:mini-proveall[0m and search for
  [47mCAR-CDR-ELIM[0m to see the full proof containing this excerpt.)

    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)))).

  The resulting conjecture is often simpler and hence more amenable to
  proof.

  The application of an [47m:elim[0m 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 [47mx[0m is
  replaced by the term [47m(cons (car x) (cdr x))[0m, which applies a
  so-called ``constructor'' function, [47m[cons][0m, to applications [47m(car x)[0m
  and [47m(cdr x)[0m of destructor functions [47m[car][0m and [47m[cdr][0m to that same
  variable, [47mx[0m.  But that is only part of the story.  ACL2 then
  generalizes the destructor applications [47m(car x)[0m and [47m(cdr x)[0m to new
  variables [47mx1[0m and [47mx2[0m, respectively, and ultimately the result is a
  simpler conjecture.

  More generally, the application of an [47m:elim[0m 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.

  Notice that the situation can be complicated a bit by a rule's
  hypotheses.  For example, the replacement specified by the rule
  [47mcar-cdr-elim[0m (shown near the beginning of this discussion) is only
  valid if the variable being replaced is a cons structure.  Thus,
  when ACL2 applies [47mcar-cdr-elim[0m to replace a variable [47mv[0m, it will
  split into two cases: one case in which [47m(consp v)[0m is true, in which
  [47mv[0m is replaced by [47m(cons (car v) (cdr v))[0m and then [47m(car v)[0m and [47m(cdr
  v)[0m are generalized to new variables; and one case in which [47m(consp
  v)[0m is false.  In practice, [47m(consp v)[0m 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.

  You might find [47m:elim[0m 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.

    Example:
    (implies (house-p x)
             (equal (make-house (address x)
                                (price x)
                                (color x))
                    x))

  The application of such a rule is entirely analogous to the
  application of the rule [47mcar-cdr-elim[0m discussed above.  We discuss
  such rules and their application more carefully below.

    General Form:
    (implies hyp (equiv lhs x))

  where [47mequiv[0m is a known equivalence relation (see [defequiv]); [47mx[0m is a
  variable symbol; and [47mlhs[0m contains one or more terms (called
  ``destructor terms'') of the form [47m(fn v1 ... vn)[0m, where [47mfn[0m is a
  function symbol and the [47mvi[0m are distinct variable symbols, [47mv1[0m, ...,
  [47mvn[0m include all the variable symbols in the formula, no [47mfn[0m occurs in
  [47mlhs[0m in more than one destructor term, and all occurrences of [47mx[0m in
  [47mlhs[0m are inside destructor terms.

  An [47m:elim[0m rule is available for a given destructor function (in the
  manner described below) when it is the most recently added
  [enable]d [47m:elim[0m rule for that function.

  To use an [47m:elim[0m rule, the theorem prover waits until a conjecture has
  been maximally simplified.  It then searches for an instance of
  some destructor term [47m(fn v1 ... vn)[0m in the conjecture, where the
  instance for [47mx[0m is some variable symbol, [47mvi[0m, and every occurrence of
  [47mvi[0m outside the destructor terms is in an [47mequiv[0m-hittable position.
  If such an instance is found, then the theorem prover instantiates
  the [47m:elim[0m formula as indicated by the destructor term matched;
  splits the conjecture into two goals, according to whether the
  instantiated hypothesis, [47mhyp[0m, holds; and in the case that it does
  hold, generalizes all the instantiated destructor terms in the
  conjecture to new variables and then replaces [47mvi[0m in the conjecture
  by the generalized instantiated [47mlhs[0m.  An occurrence of [47mvi[0m is
  ``[47mequiv[0m-hittable'' if sufficient congruence rules (see [defcong])
  have been proved to establish that the propositional value of the
  [clause] is not altered by replacing that occurrence of [47mvi[0m by some
  [47mequiv[0m-equivalent term.

  If an [47m:elim[0m rule is not applied when you think it should have been,
  and the rule uses an equivalence relation, [47mequiv[0m, other than [47mequal[0m,
  it is most likely that there is an occurrence of the variable that
  is not [47mequiv[0m-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 [47m:elim[0m to fire.

  Further examples of how ACL2 [47m:elim[0m 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.")
 (EMACS
  (ACL2-TUTORIAL)
  "Emacs support for ACL2

  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 [47memacs-acl2.el[0m from
  one of two directories under the main ACL2 directory: [47mbooks/emacs/[0m
  if you use a recent version of Emacs, or [47memacs/[0m if you use Emacs
  24.  An easy way to arrange this is to put the load form into your
  [47m.emacs[0m file; here, [47mDIR[0m denotes your main ACL2 directory.

    (load \"DIR/books/emacs/emacs-acl2.el\") ; for recent Emacs versions

  [31;1m-OR-[0m

    (load \"DIR/emacs/emacs-acl2.el\") ; for Emacs 24

  The file begins with considerable comments describing what it offers.

  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 [ACL2-Doc].

  If you are not comfortable with Emacs, you may prefer to use an
  Eclipse-based interface; see [ACL2-sedan].")
 (EMBEDDED-EVENT-FORM
  (EVENTS)
  "Forms that may be embedded in other [events]

    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:

    * [47mx[0m is a call of an event function other than [47m[defpkg][0m (see [events]
      for a listing of the event functions);

    * [47mx[0m is a call of [47m[encapsulate][0m, [47m[progn][0m, [47m[progn!][0m, or [47m[include-book][0m;

    * [47mx[0m is of the form [47m(LOCAL x1)[0m where [47mx1[0m is an embedded event form;

    * [47mx[0m is of the form [47m(MAKE-EVENT &)[0m, where [47m&[0m is any term whose expansion
      is an embedded event (see [make-event]);

    * [47mx[0m is of the form [47m(SKIP-PROOFS x1)[0m where [47mx1[0m is an embedded event form;

    * [47mx[0m is of the form [47m(WITH-CBD str x1)[0m, where [47mstr[0m is a string and [47mx1[0m is
      an embedded event form;

    * [47mx[0m is of the form [47m(WITH-GUARD-CHECKING-EVENT c x1)[0m or
      [47m(WITH-GUARD-CHECKING-EVENT (QUOTE c) form)[0m, where [47mc[0m is a member
      of the list [47m(t nil :nowarn :all :none)[0m and [47mx1[0m is an embedded
      event form;

    * [47mx[0m is of the form [47m(WITH-OUTPUT ... x1)[0m, [47m(WITH-PROVER-STEP-LIMIT ... x1
      ...)[0m, or [47m(WITH-PROVER-TIME-LIMIT ... x1)[0m, where [47mx1[0m is an
      embedded event form;

    * [47mx[0m macroexpands to one of the forms above; or

    * [intended only for the implementation] [47mx[0m is [47m(RECORD-EXPANSION x1 x2)[0m,
      where [47mx1[0m and [47mx2[0m are embedded event forms.

  However, we add the following restrictions for [47m[local][0m contexts.

    * An embedded event form may not set the [47m[ACL2-defaults-table][0m when in
      the context of [47m[local][0m.  Thus for example, the form

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

      is not an embedded event form, nor is the form [47m(local (program))[0m,
      since the latter sets the [47m[ACL2-defaults-table][0m implicitly.  An
      example at the end of the discussion below illustrates why
      there is this restriction.

    * A call of [47m[defaxiom][0m is illegal in the context of [47m[local][0m.  Without
      this restriction, one could locally assert a strong axiom like
      [47m(equal t nil)[0m and then non-locally prove that formula, leaving
      you in an ACL2 logical [world] in which it appears that the
      formula is actually provable without such an axiom.

    * A call of [47m[add-include-book-dir!][0m or [47m[delete-include-book-dir!][0m is
      illegal in the context of [47m[local][0m.  For an explanation, see
      [add-include-book-dir!].

  Only embedded event forms are allowed in a book after its initial
  [47m[in-package][0m form.  See [books].  However, you may find that
  [47m[make-event][0m 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 [47m[state][0m global
  variable [47mx[0m:

    (make-event (er-progn (assign x 17)
                          (value '(value-triple nil)))
                :check-expansion t)

  For another use of [47mmake-event[0m to create embedded event forms, see
  [make-event-example-3].

  When an embedded event is executed while [47m[ld-skip-proofsp][0m is
  [47m'[0m[47m[include-book][0m, those parts of it inside [47m[local][0m forms are
  ignored.  Thus,

    (progn (defun f1 () 1)
           (local (defun f2 () 2))
           (defun f3 () 3))

  will define [47mf1[0m, [47mf2[0m, and [47mf3[0m when [47m[ld-skip-proofsp][0m is [47mnil[0m or [47mt[0m, but
  will define only [47mf1[0m and [47mf3[0m when [47m[ld-skip-proofsp][0m is
  [47m'[0m[47m[include-book][0m.

  [3mDiscussion:[0m

  [47m[Encapsulate][0m, [47m[progn][0m, and [47m[include-book][0m place restrictions on the
  kinds of forms that may be processed.  These restrictions ensure
  that the non-local [events] are indeed admissible provided that the
  sequence of [47m[local][0m and non-local [events] is admissible when
  proofs are done, i.e., when [47mld-skip-proofs[0m is [47mnil[0m.  But [47m[progn!][0m
  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 [defttag]).

  [47m[Local][0m permits the hiding of an event or group of [events] in the
  sense that [47m[local][0m [events] are processed when we are trying to
  establish the admissibility of a sequence of [events] embedded in
  [47m[encapsulate][0m forms or in [books], but are ignored when we are
  constructing the [world] produced by assuming that sequence.  Thus,
  for example, a particularly ugly and inefficient [47m:[0m[47m[rewrite][0m rule
  might be made [47m[local][0m to an [encapsulate] that ``exports'' a
  desirable theorem whose proof requires the ugly lemma.

  To see why we can't allow just anything as an embedded event,
  consider allowing the form

    (if (ld-skip-proofsp state)
        (defun foo () 2)
        (defun foo () 1))

  followed by

    (defthm foo-is-1 (equal (foo) 1)).

  When we process the [events] with [47m[ld-skip-proofsp][0m is [47mnil[0m, the
  second [47m[defun][0m is executed and the [47m[defthm][0m succeeds.  But when we
  process the [events] with [47m[ld-skip-proofsp][0m [47m'[0m[47m[include-book][0m, the
  second [47m[defun][0m is executed, so that [47mfoo[0m no longer has the same
  definition it did when we proved [47mfoo-is-1[0m.  Thus, an invalid
  formula is assumed when we process the [47m[defthm][0m while skipping
  proofs.  Thus, the first form above is not a legal embedded event
  form.

  If you encounter a situation where these restrictions seem to prevent
  you from doing what you want to do, then you may find [47mmake-event[0m to
  be helpful.  See [make-event].

  [47m[Defpkg][0m 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,

    (encapsulate nil
                 (defpkg \"MY-PKG\" nil)
                 (defun foo () 'my-pkg::bar))

  makes no sense since [47mmy-pkg::bar[0m must have been read before the
  [47m[defpkg][0m for [47m\"MY-PKG\"[0m was executed.

  Finally, let us elaborate on the restriction mentioned earlier
  related to the [47m[ACL2-defaults-table][0m.  Consider the following form.

    (encapsulate
     ()
     (local (program))
     (defun foo (x)
       (if (equal 0 x)
           0
         (1+ (foo (- x))))))

  See [local-incompatibility] for a discussion of how [47m[encapsulate][0m
  processes event forms.  Briefly, on the first pass through the
  [events] the definition of [47mfoo[0m will be accepted in [47m[defun][0m mode
  [47m:[0m[47m[program][0m, and hence accepted.  But on the second pass the form
  [47m(local (program))[0m is skipped because it is marked as [47m[local][0m, and
  hence [47mfoo[0m is accepted in [47m[defun][0m mode [47m:[0m[47m[logic][0m.  Yet, no proof has
  been performed in order to admit [47mfoo[0m, and in fact, it is not hard
  to prove a contradiction from this definition!")
 (ENABLE
  (THEORIES THEORY-FUNCTIONS)
  "Adds names to current theory

    Example:
    (enable fact (:e fact) associativity-of-app)

    General Form:
    (enable name1 name2 ... namek)

  where each [47mnamei[0m is a runic designator; 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
  [rune]s and you will probably regret printing it.

  For related utilities, see [disable] and see [e/d].

  The standard way to ``enable'' a fixed set of names, is as follows;
  see [hints] and see [in-theory].

    :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)))

  Note that all the names are implicitly quoted.  If you wish to enable
  a computed list of names, [47mlst[0m, use the theory expression
  [47m(union-theories (current-theory :here) lst)[0m.")
 (ENABLE-FORCING
  (FORCE)
  "To allow forced case splits

    General Form:
    ACL2 !>:enable-forcing    ; allowed forced case splits

  See [force] and see [case-split] for a discussion of forced case
  splits, which are turned back on by this command.  See
  [disable-forcing] for an example showing how to turn off forced
  case splits.

  [47mEnable-forcing[0m is actually a macro that [enable]s the
  [executable-counterpart] of the function symbol [47mforce[0m; see [force].
  When you want to use [hints] to turn on forced case splits, use a
  form such as one of the following (these are equivalent).

    :in-theory (enable (:executable-counterpart force))
    :in-theory (enable (force))")
 (ENABLE-IMMEDIATE-FORCE-MODEP
  (FORCE)
  "[force]d hypotheses are attacked immediately

    General Form:
    ACL2 !>:enable-immediate-force-modep

  This event causes ACL2 to attack [force]d hypotheses immediately
  instead of delaying them to the next forcing round.  See
  [immediate-force-modep].  Or for more basic information, first see
  [force] for a discussion of [force]d case splits.

  Enable-immediate-force-modep is a macro that [enable]s the
  [executable-counterpart] of the function symbol
  [47m[immediate-force-modep][0m.  When you want to [enable] this mode in
  [hints], use a form such as one of the following (these are
  equivalent).

    :in-theory (enable (:executable-counterpart immediate-force-modep))
    :in-theory (enable (immediate-force-modep))")
 (ENABLED-NUMEP (POINTERS)
                "See [system-utilities].")
 (ENABLED-RUNEP (POINTERS)
                "See [system-utilities].")
 (ENCAPSULATE (EVENTS)
  "Hide some [events] and/or constrain some functions

  [47mEncapsulate[0m provides a way to execute a sequence of [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 [documentation].

  A trivial encapsulation is an event of the following form.

    (encapsulate
     () ; nil here indicates \"trivial\"
     <event-1>
     ...
     <event-k>)

  We use the term ``sub-events'' to refer to [47m<event-1>[0m through
  [47m<event-k>[0m.  Each sub-event [47m<event-i>[0m may be ``[local]'', that is,
  of the form [47m(local <event-i'>)[0m; the other sub-events are called
  ``non-local''.  When this [47mencapsulate[0m 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
  [47mencapsulate[0m fails if any [47m<event-i>[0m fails to be admitted.  Then a
  second pass is made after rolling back the logical [world] to what
  it was just before executing the [47mencapsulate[0m form.  In the second
  pass, only the non-[local] forms [47m<event-i>[0m are evaluated, again in
  order, and proofs are skipped.

  For example, the following trivial encapsulation exports a single
  event, [47mmember-equal-reverse[0m.  The lemma [47mmember-revappend[0m is used
  (as a [rewrite] rule) to prove [47mmember-equal-reverse[0m on the first
  pass, but since [47mmember-revappend[0m is [local], it is ignored on the
  second (final) pass.

    (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))))

  Of course, one might prefer to prove these [events] at the top level,
  rather than within an encapsulation; but the point here is to
  illustrate that you can have [local] [events] that do not become
  part of the logical [world].  (Such a capability is also provided
  at the level of [books]; in particular, see [include-book].)

  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
  [world].  Consider the following example.

    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 !>

  After the above evaluation, we are left in the [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.

    ACL2 !>:pbt 0
               0:x(EXIT-BOOT-STRAP-MODE)
    ACL2 !>

  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.

    (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))))
    )

  The form above introduces a new function symbol, [47mfoo[0m, with the
  indicated property and no definition.  In fact, the output from
  ACL2 concludes as follows.

    The following constraint is associated with the function FOO:

    (IMPLIES (CONSP X) (CONSP (FOO X)))

  To understand this example, we consider how non-trivial
  encapsulations are processed.  The same two passes are made as for
  trivial encapsulations, and the ([local]) definition of [47mfoo[0m is
  ignored on the second pass, and hence does not appear in the
  resulting ACL2 logical [world].  But before the second pass, each
  [signature] is stored in the [world].  Thus, when the theorem
  [47mfoo-preserves-consp[0m is encountered in the second pass, [47mfoo[0m is a
  known function symbol with the indicated signature.

  If any event fails while evaluating a call of [47mencapsulate[0m, the entire
  [47mencapsulate[0m call is deemed to have failed, and the logical [world]
  is rolled back to what it was immediately before the [47mencapsulate[0m
  call.

  We now provide detailed documentation.  But discussion of redundancy
  for [47mencapsulate[0m events may be found elsewhere; see
  [redundant-encapsulate].

    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)

  where each [47m[signature][0m is a well-formed signature, each [47msignature[0m
  describes a different function symbol, and each [47mevi[0m is an embedded
  event form (see [embedded-event-form]).  Also see [signature], in
  particular for a discussion of how a signature can assign a [guard]
  to a function symbol.  There must be at least one [47mevi[0m.  The [47mevi[0m
  inside [47m[local][0m special forms are called ``local'' [events] below.
  [Events] that are not [47m[local][0m are sometimes said to be ``exported''
  by the encapsulation.  We make the further restriction that no
  [47m[defaxiom][0m event may be introduced in the scope of an [47mencapsulate[0m
  (not even by [47mencapsulate[0m or [47m[include-book][0m events that are among
  the [47mevi[0m).  Furthermore, no non-[47m[local][0m [47m[include-book][0m event is
  permitted in the scope of any [47mencapsulate[0m with a non-empty list of
  signatures.

  To be well-formed, an [47mencapsulate[0m event must have the properties that
  each event in the body (including the [47m[local][0m ones) can be
  successfully executed in sequence and that in the resulting theory,
  each function mentioned among the [signature]s was introduced via a
  [47m[local][0m event and has the [signature] listed.  (A utility is
  provided to assist in debugging failures of such execution; see
  [redo-flat].)  In addition, the body may contain no ``local
  incompatibilities'' which, roughly stated, means that the [events]
  that are not [47m[local][0m must not syntactically require symbols defined
  by [47m[local][0m [47m[events][0m, except for the functions listed in the
  [signature]s.  See [local-incompatibility].  Finally, no
  non-[47m[local][0m recursive definition in the body may involve in its
  suggested induction scheme any function symbol listed among the
  [signature]s.  See [subversive-recursions].

  Observe that if the [signature]s list is empty, the resulting
  ``trivial'' [47mencapsulate[0m may still be useful for deriving theorems
  to be exported whose proofs require lemmas you prefer to hide
  (i.e., made [47m[local][0m).  Whether trivial or not (i.e., whether the
  signature is empty or not), [47mencapsulate[0m exports the results of
  evaluating its non-[47m[local][0m [events], but its [47m[local][0m [events] are
  ignored for the resulting logical [world].

  The result of a non-trivial [47mencapsulate[0m event is an extension of the
  logic in which, roughly speaking, the functions listed in the
  [signature]s are constrained to have the [signature]s listed and to
  satisfy the non-[47m[local][0m theorems proved about them.  In fact, other
  functions introduced in the [47mencapsulate[0m event may be considered to
  have ``[constraint]s'' as well.  (See [constraint] for details,
  which are only relevant to functional instantiation.)  Since the
  [constraint]s were all theorems in the ``ephemeral'' or ``local''
  theory, we are assured that the extension produced by [47mencapsulate[0m
  is sound.  In essence, the [47m[local][0m definitions of the constrained
  functions are just ``witness functions'' that establish the
  consistency of the [constraint]s.  Because those definitions are
  [47m[local][0m, they are not present in the theory produced by
  encapsulation.  After a non-trivial [47mencapsulate[0m event is admitted,
  theorems about the constrained function symbols may then be proved
  --- theorems whose proofs necessarily employ only the
  [constraint]s.  Thus, those theorems may be later functionally
  instantiated, as with the [47m:functional-instance[0m lemma instance (see
  [lemma-instance]), to derive analogous theorems about different
  functions, provided the constraints (see [constraint]) can be
  proved about the new functions.

  The [default-defun-mode] for the first event in an encapsulation is
  the default [defun-mode] ``outside'' the encapsulation.  But since
  [events] changing the [defun-mode] are permitted within the body of
  an [47mencapsulate[0m, the default [defun-mode] may be changed.  However,
  [defun-mode] changes occurring within the body of the [47mencapsulate[0m
  are not exported.  In particular, the [47m[ACL2-defaults-table][0m after
  an [47mencapsulate[0m is always the same as it was before the [47mencapsulate[0m,
  even though the [47mencapsulate[0m body might contain [defun-mode]
  changing [events], [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m.  See [defun-mode].
  More generally, after execution of an [47mencapsulate[0m event, the value
  of [47m[ACL2-defaults-table][0m is restored to what it was immediately
  before that event was executed.  See [ACL2-defaults-table].

  We make some remarks on [guard]s and evaluation.  Calls of functions
  introduced in the [signature]s list cannot be evaluated in the ACL2
  read-eval-print loop.  See [defattach] for a way to overcome this
  limitation.  Moreover, any [47m:[0m[47m[guard][0m supplied in the signature is
  automatically associated in the [world] with its corresponding
  function symbol, with no requirement beyond what is required for a
  legal [signature] other than that all of the guard's function
  symbols are in [47m:[0m[47m[logic][0m mode with their [guard]s verified.  In
  particular, there need not be any relationship between a guard in a
  signature and the guard in a [47mlocal[0m witness function.  Finally, note
  that for functions introduced non-[local]ly inside a non-trivial
  [47mencapsulate[0m event, [guard] verification is illegal unless ACL2
  determines that the proof obligations hold outside the
  [47m[encapsulate][0m event as well.

    (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)))

  The order of the [events] in the vicinity of an [47mencapsulate[0m 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
  [events] were executed.  (See [logical-name] and see
  [theory-functions].)  What, for example, is the set of function
  names extant in the middle of an encapsulation?

  If the most recent event is [47mprevious[0m and then you execute an
  [47mencapsulate[0m constraining [47man-element[0m with two non-[47m[local][0m [events]
  in its body, [47mthm1[0m and [47mthm2[0m, then the order of the [events] after
  the encapsulation is (reading chronologically forward): [47mprevious[0m,
  [47mthm1[0m, [47mthm2[0m, [47man-element[0m (the [47mencapsulate[0m itself).  Actually, between
  [47mprevious[0m and [47mthm1[0m certain extensions were made to the [world] by
  the superior [47mencapsulate[0m, to permit [47man-element[0m to be used as a
  function symbol in [47mthm1[0m.

  Remark on return value.  As with all [events], a call of [47mencapsulate[0m
  returns an [error-triple], [47m(mv erp val state)[0m, where [47merp[0m is [47mnil[0m
  when the event is redundant or is successfully admitted.  When [47merp[0m
  is [47mnil[0m, the value [47mval[0m, which is typically printed after a space, is
  determined as follows.

    * If the [47mencapsulate[0m event is [redundant], then [47mval[0m is [47m:redundant[0m.

    * Otherwise, if no new events are introduced, then [47mval[0m is
      [47m:empty-encapsulate[0m.

    * Otherwise, if the last sub-event in the final pass of the [47mencapsulate[0m
      form evaluates to [47m(mv nil '(:return-value x)[0m) for some [47mx[0m, [47mval[0m
      is [47mx[0m.  Note that this can be accomplished by placing the form
      [47m(value-triple '(:return-value x) :on-skip-proofs t)[0m as the
      final form in the [47mencapsulate[0m, but since proofs are skipped
      during that pass, the argument [47m:on-skip-proofs t[0m is necessary
      for [47mval[0m to be [47mx[0m.

    * Otherwise, if the list of [signature]s is [47mnil[0m then [47mval[0m is [47mt[0m.

    * Otherwise, if there is a single signature introducing the function
      symbol, [47mfn[0m, then [47mval[0m is [47mfn[0m.

    * Otherwise, [47mval[0m is the list of function symbols introduced in the list
      of signatures.

  Remark on implicit [constraint]s (unknown-constraints).  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 [defttag]).

  Remark for ACL2(r) (see [real]).  For ACL2(r), [47m[encapsulate][0m can be
  used to introduce classical and non-classical functions, as
  determined by the signatures; see [signature].  Those marked as
  classical (respectively non-classical) must have classical
  (respectively, non-classical) [47m[local][0m witness functions.  A related
  requirement applies to functional instantiation; see
  [lemma-instance].


Subtopics

  [Constraint]
      Restrictions on certain functions introduced in [47m[encapsulate][0m
      [events]

  [Functional-instantiation]
      An analogue in ACL2 of higher-order logical reasoning.  Functional
      instantiation allows you to prove theorems ``by analogy'' with
      previous theorems.  See [hints] and see [lemma-instance].

  [Infected-constraints]
      [47m[Events][0m affecting [constraint]s of [47m[encapsulate][0ms

  [Partial-encapsulate]
      Introduce functions with some constraints unspecified

  [Redundant-encapsulate]
      Redundancy of [47m[encapsulate][0m [events]

  [Signature]
      How to specify the arity of a constrained function")
 (ENDP
  (LISTS ACL2-BUILT-INS)
  "Recognizer for empty lists

  In the ACL2 logic, [47m(endp x)[0m is the same as [47m(atom x)[0m.  See [atom].

  Unlike [47m[atom][0m, the [guard] for [47mendp[0m requires that [47mx[0m is a [47m[cons][0m pair
  or is [47mnil[0m.  Thus, [47mendp[0m is typically used as a termination test for
  functions that recur on a [47m[true-listp][0m argument.  See [guard] for
  general information about [guard]s.

  [47mEndp[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<endp>

    (defun endp (x)
      (declare (xargs :guard (or (consp x) (eq x nil))))
      (atom x))")
 (ENTER-BOOT-STRAP-MODE
  (HISTORY)
  "The first millisecond of the Big Bang

  ACL2 functions, e.g., [47m[if][0m, that show [47menter-boot-strap-mode[0m as their
  defining [command] are in fact [primitive]s.  It is impossible for
  the system to display defining axioms about these symbols.

  [47mEnter-boot-strap-mode[0m is a Common Lisp function but not an ACL2
  function.  It magically creates from [47mnil[0m an ACL2 property list
  [world] that lets us start the boot-strapping process.  That is,
  once [47menter-boot-strap-mode[0m has created its [world], it is possible
  to process the [47m[defconst][0ms, [47m[defun][0ms, and [47m[defaxiom][0ms, necessary to
  bring up the rest of the system.  Before that [world] is created,
  the attempt by ACL2 even to translate a [47m[defun][0m form, say, would
  produce an error because [47m[defun][0m is undefined.

  Several ACL2 functions show [47menter-boot-strap-mode[0m as their defining
  [command].  Among them are [47m[if][0m, [47m[cons][0m, [47m[car][0m, and [47m[cdr][0m.  These
  functions are characterized by axioms rather than definitional
  equations --- 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.")
 (EPHEMERAL-WHS (POINTERS)
                "See [wormhole-status].")
 (EQ
  (EQUAL EQUALITY-VARIANTS ACL2-BUILT-INS)
  "Equality of symbols

  [47mEq[0m 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 [47m[equal][0m in the
  ACL2 logic.

  [47mEq[0m is a Common Lisp function.  In order to ensure conformance with
  Common Lisp, the ACL2 [guard] on [47meq[0m requires at least one of the
  arguments to [47meq[0m to be a symbol.  Common Lisp guarantees that if [47mx[0m
  is a symbol, then [47mx[0m is [47meq[0m to [47my[0m if and only if [47mx[0m is [47m[equal][0m to [47my[0m.
  Thus, the ACL2 user should think of [47meq[0m as nothing besides a fast
  means for checking [47m[equal][0m when one argument is known to be a
  symbol.  In particular, it is possible that an [47meq[0m test will not
  even require the cost of a function call but will be as fast as a
  single machine instruction.

  [31;1mFunction: [0m<eq>

    (defun eq (x y)
      (declare (xargs :guard (if (symbolp x) t (symbolp y))))
      (equal x y))")
 (EQL
  (EQUAL EQUALITY-VARIANTS ACL2-BUILT-INS)
  "Test equality (of two numbers, symbols, or [characters])

  [47m(eql x y)[0m is logically equivalent to [47m(equal x y)[0m.

  Unlike [47m[equal][0m, [47meql[0m has a [guard] requiring at least one of its
  arguments to be a number, a symbol, or a character.  Generally, [47meql[0m
  is executed more efficiently than [47m[equal][0m.

  For a discussion of the various ways to test against 0, See
  [zero-test-idioms].

  [47mEql[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<eql>

    (defun eql (x y)
      (declare (xargs :guard (or (eqlablep x) (eqlablep y))))
      (equal x y))")
 (EQLABLE-ALISTP
  (ALISTS ACL2-BUILT-INS)
  "Recognizer for a true list of pairs whose [47m[car][0ms are suitable for
  [47m[eql][0m

  The predicate [47meqlable-alistp[0m tests whether its argument is a
  [47m[true-listp][0m of [47m[consp][0m objects whose [47m[car][0ms all satisfy
  [47m[eqlablep][0m.

  [31;1mFunction: [0m<eqlable-alistp>

    (defun eqlable-alistp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (equal x nil))
            (t (and (consp (car x))
                    (eqlablep (car (car x)))
                    (eqlable-alistp (cdr x))))))")
 (EQLABLE-LISTP
  (EQLABLEP EQUAL LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of objects each suitable for [47m[eql][0m

  The predicate [47meqlable-listp[0m tests whether its argument is a
  [47m[true-listp][0m of objects satisfying [47m[eqlablep][0m.

  [31;1mFunction: [0m<eqlable-listp>

    (defun eqlable-listp (l)
      (declare (xargs :guard t))
      (if (consp l)
          (and (eqlablep (car l))
               (eqlable-listp (cdr l)))
        (equal l nil)))")
 (EQLABLEP
  (EQUAL ACL2-BUILT-INS)
  "The [guard] for the function [47m[eql][0m

  The predicate [47meqlablep[0m tests whether its argument is suitable for
  [47m[eql][0m, at least one of whose arguments must satisfy this predicate
  in Common Lisp.  [47m(Eqlablep x)[0m is true if and only if its argument
  is a number, a symbol, or a character.

  [31;1mFunction: [0m<eqlablep>

    (defun eqlablep (x)
      (declare (xargs :guard t))
      (or (acl2-numberp x)
          (symbolp x)
          (characterp x)))


Subtopics

  [Eqlable-listp]
      Recognizer for a true list of objects each suitable for [47m[eql][0m")
 (EQUAL
  (BASICS ACL2-BUILT-INS)
  "True equality

  [47m(equal x y)[0m is equal to [47mt[0m or [47mnil[0m, according to whether or not [47mx[0m and [47my[0m
  are the same value.

  For a discussion of the various idioms for testing against 0, See
  [zero-test-idioms].


Subtopics

  [=]
      Test equality of two numbers

  [Eq]
      Equality of symbols

  [Eql]
      Test equality (of two numbers, symbols, or [characters])

  [Eqlable-listp]
      Recognizer for a true list of objects each suitable for [47m[eql][0m

  [Eqlablep]
      The [guard] for the function [47m[eql][0m

  [Hons-equal]
      [47m(hons-equal x y)[0m is a recursive equality check that optimizes when
      parts of its arguments are [normed].")
 (EQUALITY-VARIANTS
  (PROGRAMMING)
  "Versions of a function using different equality tests

  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: [47m[eq][0m for symbols and
  [47m[eql][0m for numbers, symbols, and characters (see [eqlablep]).
  Several list-processing functions built into ACL2 thus have three
  variants, depending on whether the equality function used is [47m[eq][0m,
  [47m[eql][0m, or [47m[equal][0m; 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.

  Consider for example the case of list membership.  Common Lisp
  provides a utility for this purposes, [47m[member][0m, which can take a
  [47m:TEST[0m keyword argument, default [47m[eql][0m.  So for example, one might
  write

    (member a x :TEST 'eq)

  if either [47ma[0m is a symbol or [47mx[0m is a list of symbols, so that the
  fastest equality test ([47m[eq][0m) may be used when comparing [47ma[0m to
  successive elements of the list, [47mx[0m.  One might elsewhere write
  [47m(member b (foo y))[0m, which is equivalent to [47m(member b (foo y) :TEST
  'eql)[0m, for example if [47mb[0m is a number.  If one wants to reason about
  both [47m(member a x :TEST 'eq)[0m and [47m(member b y)[0m, it might be helpful
  for both calls of [47mmember[0m to be the same logically, even though
  Common Lisp will execute them differently (using [47m[eq][0m or [47m[eql][0m,
  respectively).  ACL2 arranges that in fact, both references to
  [47m[member][0m generate calls of [47m[member-equal][0m in the theorem prover.

  In fact, since [47m[member][0m can take the optional [47m:TEST[0m keyword argument,
  then in ACL2 it must be defined as a macro, not a function (see
  [defun]).  ACL2 arranges that a call of [47mmember[0m generates a
  corresponding call of the function [47m[member-equal][0m, regardless of
  the value of [47mTEST[0m, in a manner that produces [47m[member-equal][0m in
  prover output.  More generally, you can expect ACL2 to treat your
  use of [47m[member][0m as though you had written [47m[member-equal][0m, for
  example in the way it stores [47m[rewrite][0m rules and other kinds of
  rules as well (see [rule-classes]).  We say little here about how
  this is all arranged by ACL2, other than to mention that [47m[mbe][0m is
  utilized (so, you might see mention in proof logs) of the function
  [47m[return-last][0m that implements [47m[mbe][0m.  Such details, which involve a
  notion of ``macro alias'' and probably can be ignored by most
  users, may be found elsewhere; see [equality-variants-details].

  As a convenience to the user, the macro [47mmember-eq[0m is provided that
  expands to a corresponding call of [47mmember[0m with [47m:TEST 'eq[0m, as
  follows.

    ACL2 !>:trans1 (member-eq (foo x) (bar y))
     (MEMBER (FOO X) (BAR Y) :TEST 'EQ)
    ACL2 !>

  For efficiency we recommend using the [47m-equal[0m equality variant, for
  example [47m[member-equal][0m or [47m([0m[47m[member][0m[47m ... :TEST 'equal)[0m, in certain
  contexts: [47m[defmacro][0m, [47m[defpkg][0m, [47m[defconst][0m, and [47m[value-triple][0m
  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 [47mF[0m, to get efficient
  execution but where subsequent reasoning is about [47mF-equal[0m.  For
  details about the above recommendation and for a discussion of the
  implementation, see [equality-variants-details].

  The following alphabetical list includes all primitives that have
  equality variants.  Each macro [47mF[0m listed below takes an optional
  [47m:TEST[0m keyword argument of [47m'eq[0m, [47m'eql[0m, or [47m'equal[0m, where [47m'eql[0m is the
  default.  For each such [47mF[0m, a function [47mF-equal[0m is defined such that
  for logical purposes (in particular theorem proving), each call of
  [47mF[0m expands to a corresponding call of [47mF-equal[0m.  For convenience, a
  macro [47mF-eq[0m is also defined, so that a call of [47mF-eq[0m expands to a
  corresponding call of [47mF[0m with [47m:TEST 'eq[0m.

    [47m[add-to-set][0m
    [47m[assoc][0m
    [47m[intersection$][0m ; (see Note below)
    [47m[intersectp][0m
    [47m[member][0m
    [47m[no-duplicatesp][0m
    [47mposition-ac[0m
    [47m[position][0m
    [47m[put-assoc][0m
    [47m[rassoc][0m
    [47m[remove][0m
    [47m[remove-assoc][0m
    [47m[remove-duplicates][0m
    [47m[remove1][0m
    [47m[remove1-assoc][0m
    [47m[set-difference$][0m ; (see Note below)
    [47m[subsetp][0m
    [47m[union$][0m ; (see Note below)

  Note: Three of the macros above have names ending with the character,
  `[47m$[0m': [47m[intersection$][0m, [47m[set-difference$][0m, and [47m[union$][0m.  In each
  case there is a corresponding Common Lisp primitive without the
  trailing `[47m$[0m': [47mintersection[0m, [47mset-difference[0m, and [47munion[0m.  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 `[47m$[0m' is to distinguish the primitives;
  associated functions and macros, for example [47munion-eq[0m and
  [47mintersection-equal[0m, do not include the `[47m$[0m' character in their
  names.

  We conclude with a brief discussion of [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 [47m(member x lst :test
  'eq)[0m, or equivalently, [47m(member-eq x lst)[0m.  Expanding these macros
  leads to a call of [47m[mbe][0m; you can see how that goes by using
  [47m:[0m[47m[trans1][0m.  Ultimately, the guard being checked is that of the
  function [47mmember-eq-exec[0m, which is as follows.

    (if (symbolp x)
        (true-listp lst)
      (symbol-listp lst))

  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 [verify-guards]).  A guard violation
  might look something like this:

    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 !>

  Above, [47mmember-eq-exec$guard-check[0m is a function generated as part of
  ACL2's expansion of [47mmember[0m with [47m:test 'eq[0m, and this function symbol
  can be quite reasonably ignored.  The important thing is that it
  refers to the guard for [47mmember-eq-exec[0m, which as the name may
  suggest is intended to guard the execution of a call of
  [47m[member-eq][0m, or a call of [47m[member][0m with [47m:test 'eq[0m.  The important
  part of the message above is the guard actually being violated: [47m(IF
  (SYMBOLP X) (TRUE-LISTP LST) (SYMBOL-LISTP LST))[0m.


Subtopics

  [=]
      Test equality of two numbers

  [Eq]
      Equality of symbols

  [Eql]
      Test equality (of two numbers, symbols, or [characters])

  [Equality-variants-details]
      Details about [equality-variants]")
 (EQUALITY-VARIANTS-DETAILS
  (EQUALITY-VARIANTS)
  "Details about [equality-variants]

  Here we present details about equality variants, none of which is
  likely to be important to the majority of ACL2 users.  Please see
  [equality-variants] for relevant background.

  We begin by presenting [events] that implement the equality variants
  for [47m[member][0m, as these illustrate the events introduced for all
  macros having equality variants.  The definition of [47m[member][0m, just
  below, calls the macro [47mlet-mbe[0m, which in turn is just an
  abbreviation for a combination of [47m[let][0m and [47m[mbe][0m.  Here is a
  simplified version of the definition of this macro.  For relevant
  background, see [47m[mbe][0m.

    (defmacro let-mbe (bindings &key logic exec)
      `(let ,bindings
         (mbe :logic ,logic
              :exec ,exec)))

  This use of [47m[let][0m arranges that each argument of a call of [47mmember[0m is
  evaluated only once.

  The actual definition of the macro [47mlet-mbe[0m is a bit more complex, in
  order to guarantee that [guard]s are appropriately checked.  For
  purposes of this discussion we ignore this simplification.  (You
  can find the definition of [47mlet-mbe[0m in ACL2 source file
  [47maxioms.lisp[0m.)

  Consider the following definition from ACL2 source file [47maxioms.lisp[0m.
  Notice that it invokes the macro [47mlet-mbe[0m, discussed above.

    (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))))

  Inspection of the definition above shows that every call of [47m[member][0m
  expands to one that is logically equivalent to the corresponding
  call of [47m[member-equal][0m, which is defined as follows.

    (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)))))

  The following two definitions model equality variants of [47m[member][0m for
  tests [47m[eq][0m and [47m[eql][0m, respectively.

    (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)))))

  At this point the user can write [47m(member x y)[0m or [47m(member-equal x y)[0m
  to call equality variants of [47mmember[0m with test [47meql[0m or [47mequal[0m,
  respectively.  We thus provide the following macro for the [47meq[0m
  variant.

    (defmacro member-eq (x lst)
      `(member ,x ,lst :test 'eq))

  [Guard] proof obligations generated by calls of [47mmember[0m will include
  those based on its use of [47mmbe[0m, and are supported by the following
  two lemmas.

    (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)))

  Finally, the following two events arrange that in certain contexts
  such as [theories] (including the use of [47m[in-theory][0m in [events]
  and [hints]), [47m[member-eq][0m and [47m[member][0m are treated as references to
  [47m[member-equal][0m.

    (add-macro-alias member-eq member-equal)
    (add-macro-alias member member-equal)

  Note however that these events do not affect printing of calls during
  proofs: calls of [47mmember[0m and [47mmember-eq[0m will be macroexpanded away,
  leaving you with calls of [47mmember-equal[0m that are displayed in proof
  output.  For a way to change this behavior, see [47m[add-macro-fn][0m.

  We conclude this topic by exploring the following recommendation made
  in the [documentation] for [equality-variants].

      For efficiency we recommend using the [47m-equal[0m equality variant, for
      example [47m[member-equal][0m or [47m([0m[47m[member][0m[47m ... :TEST 'equal)[0m, in
      certain contexts: [47m[defmacro][0m, [47m[defpkg][0m, [47m[defconst][0m, and
      [47m[value-triple][0m forms.

  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 [47m[mbe][0m in execution of a call of an equality variant of a
  primitive, [47mF[0m, other than its [47mF-equal[0m variant.  The [47m[mbe][0m call
  discussed above requires a connection to be established between the
  [47m:logic[0m and [47m:exec[0m forms.  For example, if [47mF[0m is called with [47m:TEST
  'eql[0m (either explicitly or as the default), then ACL2 will call
  both [47mF-eql-exec[0m and [47mF-equal[0m, and check that the two results are
  equal.

  The following partial log illustrates the point above.  We define a
  macro that calls [47m[member][0m, 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.

    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.

  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 [47m[member][0m with [47m:TEST 'eq[0m.  This time, the trace
  in our partial log shows that we have avoided calling two
  membership functions.

    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.")
 (EQUIVALENCE
  (RULE-CLASSES)
  "Mark a relation as an equivalence relation

  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.

    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)

  Also see [defequiv].

    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)))

  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 [47mequiv[0m as an equivalence relation.  Note that only Boolean
  2-place function symbols can be treated as equivalence relations.
  See [congruence] and see [refinement] for closely related concepts.

  The macro form [47m(defequiv equiv)[0m is an abbreviation for a [47m[defthm][0m of
  rule-class [47m:equivalence[0m that establishes that [47mequiv[0m is an
  equivalence relation.  It generates the formula shown above.  See
  [defequiv].

  When [47mequiv[0m is marked as an equivalence relation, its reflexivity,
  symmetry, and transitivity are built into the system in a deeper
  way than via [47m:[0m[47m[rewrite][0m rules.  More importantly, after [47mequiv[0m has
  been shown to be an equivalence relation, lemmas about [47mequiv[0m, e.g.,

    (implies hyps (equiv lhs rhs)),

  when stored as [47m:[0m[47m[rewrite][0m rules, cause the system to rewrite certain
  occurrences of (instances of) [47mlhs[0m to (instances of) [47mrhs[0m.  Roughly
  speaking, an occurrence of [47mlhs[0m in the [47mkth[0m argument of some
  [47mfn[0m-expression, [47m(fn ... lhs' ...)[0m, can be rewritten to produce [47m(fn
  ...  rhs' ...)[0m, provided the system ``knows'' that the value of [47mfn[0m
  is unaffected by [47mequiv[0m-substitution in the [47mkth[0m argument.  Such
  knowledge is communicated to the system via ``congruence lemmas.''

  For example, suppose that [47mr-equal[0m is known to be an equivalence
  relation.  The [47m:[0m[47m[congruence][0m lemma

    (implies (r-equal s1 s2)
             (equal (fn s1 n) (fn s2 n)))

  informs the rewriter that, while rewriting the first argument of
  [47mfn[0m-expressions, it is permitted to use [47mr-equal[0m rewrite-rules.  See
  [congruence] for details about [47m:[0m[47m[congruence][0m 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 [47mfn[0m, we store
  congruence rules that state the following fact:

    (implies (and (fn x1 y1)
                  (fn x2 y2))
             (iff (fn x1 x2) (fn y1 y2)))

  Another aspect of equivalence relations is that of ``refinement.'' We
  say [47mequiv1[0m ``refines'' [47mequiv2[0m iff [47m(equiv1 x y)[0m implies [47m(equiv2 x
  y)[0m.  [47m:[0m[47m[refinement][0m 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
  [47mequiv2[0m it is permitted to use as a [47m:[0m[47m[rewrite][0m rule any refinement
  of [47mequiv2[0m.  Thus, if [47mequiv1[0m is a refinement of [47mequiv2[0m and there are
  [47mequiv1[0m rewrite-rules available, they can be brought to bear while
  maintaining [47mequiv2[0m.  See [refinement].

  The system initially has knowledge of two equivalence relations,
  equality, denoted by the symbol [47m[equal][0m, and propositional
  equivalence, denoted by [47m[iff][0m.  [47m[Equal][0m is known to be a refinement
  of all equivalence relations and to preserve equality across all
  arguments of all functions.

  Typically there are five steps involved in introducing and using a
  new equivalence relation, equiv.

      (1) Define [47mequiv[0m,

      (2) prove the [47m:equivalence[0m lemma about [47mequiv[0m,

      (3) prove the [47m:[0m[47m[congruence][0m lemmas that show where [47mequiv[0m can be used
      to maintain known relations,

      (4) prove the [47m:[0m[47m[refinement][0m lemmas that relate [47mequiv[0m to known
      relations other than equal, and

      (5) develop the theory of conditional [47m:[0m[47m[rewrite][0m rules that drive
      equiv rewriting.

  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.

  Among the theorems proved below is

    (defthm insert-sort-is-id
      (perm (insert-sort x) x))

  Here [47mperm[0m is defined as usual with [47mdelete[0m and is proved to be an
  equivalence relation and to be a congruence relation for [47m[cons][0m and
  [47m[member][0m.

  Then we prove the lemma

    (defthm insert-is-cons
      (perm (insert a x) (cons a x)))

  which you must think of as you would [47m(insert a x) = (cons a x)[0m.

  Now prove [47m(perm (insert-sort x) x)[0m.  The base case is trivial.  The
  induction step is

       (consp x)
     & (perm (insert-sort (cdr x)) (cdr x))

    -> (perm (insert-sort x) x).

  Opening [47minsert-sort[0m makes the conclusion be

    (perm (insert (car x) (insert-sort (cdr x))) x).

  Apply [47minsert-is-cons[0m to get

    (perm (cons (car x) (insert-sort (cdr x)) x)).

  Note that we have proved that [47mperm[0m is a congruence relation for [47mcons[0m.
  That allows us to apply the induction hypothesis (rewriting
  [47m(insert-sort (cdr x))[0m to [47m(cdr x)[0m), to make the conclusion be

    (perm (cons (car x) (cdr x)) x).

  But we know that [47m(cons (car x) (cdr x))[0m is [47mx[0m, so we get [47m(perm x x)[0m
  which is trivial, since [47mperm[0m is an equivalence relation.  An
  exercise left to the reader is how this proof will change had we
  also proved that [47mperm[0m is a congruence relation for [47minsert[0m.

  Here are the events.

    (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))")
 (EQUIVALENT-FORMULAS-DIFFERENT-REWRITE-RULES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Logically equivalent formulas can generate radically different rules

  Consider the rewrite rules that would be generated from the three
  commands below.  In all three cases, the fact being stated relates
  the [47mn[0mth element of the reverse of [47mx[0m to the [47mn[0mth element of [47mx[0m.  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.

    (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)))))

  Here are the three rewrite rules:

  [31;1mnth-rev-1[0m:
  Replace instances of [47m(NTH n (REV x))[0m
  by [47m(NTH (- (LEN x) (+ 1 n)) x)[0m,
  if you can establish that [47mn[0m is a natural number less than the length
  of [47mx[0m.

  [31;1mnth-rev-2[0m:
  Replace instances of [47m(NTH (- (LEN x) (+ 1 n)) x)[0m
  by [47m(NTH n (REV x))[0m,
  if you can establish that [47mn[0m is a natural number less than the length
  of [47mx[0m.

  [31;1mnth-rev-3[0m:
  Replace instances of [47m(< n (LEN x))[0m
  by [47mNIL[0m
  if you can establish that [47mn[0m is a natural number and that [47m(NTH n (REV
  x))[0m is different from [47m(NTH (- (LEN x) (+ 1 n)) x)[0m.

  As the driver of ACL2, you have to decide which rule you want [3mwhen
  you give the command to prove it[0m.

  If you tell the theorem prover to use both [47mnth-rev-1[0m and [47mnth-rev-2[0m,
  ACL2 will enter an infinite loop when it sees any term matching
  either [47mNTH[0m expression.

  Most users would choose form [47mnth-rev-1[0m of the rule.  It eliminates
  [47mrev[0m from the problem --- 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 [47m(rev x)[0m.  The [47mnth-rev-2[0m form of the rule is
  ``bad'' because it introduces [47mrev[0m into a problem where it might not
  have appeared.  The [47mnth-rev-3[0m version is ``bad'' because it makes
  the theorem prover shift its attention from a simple arithmetic
  inequality to a complicated property of [47mnth[0m and [47mrev[0m, which might
  not be in the problem.

  Use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-rewrite-rules-part-1].")
 (ER
  (ERRORS ACL2-BUILT-INS)
  "Print an error message and ``cause an error''

  See [fmt] for a general discussion of formatted printing in ACL2.
  All calls of [47mer[0m print formatted strings, just as is done by [47m[fmt][0m.

    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)

  The examples above all print an error message to standard output
  saying that [47ma[0m and [47mb[0m are illegal inputs.  However, the first three
  abort evaluation after printing an error message (while logically
  returning [47mnil[0m, though in ordinary evaluation the return value is
  never seen); while the last two return [47m(mv t nil state)[0m after
  printing an error message.  The result in each of the last two
  cases can be interpreted as an ``error'' when programming with the
  ACL2 [47m[state][0m, something most ACL2 users will probably not want to
  do unless they are building systems of some sort; see
  [programming-with-state].  If state is not available in the current
  context then you will probably want to use a call other than the
  last to cause an error; for example, if you are returning two
  values, you may write [47m(mv (er hard ...) nil)[0m.

  The difference between the [47mhard[0m and [47mhard?[0m forms is one of guards.
  Use [47mhard[0m if you want the call to generate a (clearly impossible)
  guard proof obligation of (essentially) [47mNIL[0m.  But use [47mhard?[0m 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 [47mT[0m.

  The difference between the [47mhard[0m and [47mhard![0m forms is that there are
  situations in which [47m(er hard ...)[0m returns [47mnil[0m rather than causing
  an error, while [47m(er hard! ...)[0m will always cause an error (though
  such errors are sometimes ``caught'', for example during proofs).
  You will probably be happy using [47mhard[0m rather than considering the
  use of [47mhard![0m, which is really provided mostly for system
  implementors; but you can try [47mhard![0m if you are not getting the
  errors you expect.  There is even an additional option, [47mhard?![0m,
  which avoids guard proof obligations like [47mhard?[0m but ensures errors
  like [47mhard![0m.

  [47mEr[0m is a macro, and the examples above expand to calls of ACL2
  functions; see below.  Also see [illegal], [hard-error], and
  [error1].  The [47mhard?[0m/[47mhard?![0m forms have expansions that call the
  function, [47m[hard-error][0m, which has a [guard] of [47mT[0m, while the
  [47mhard[0m/[47mhard![0m forms have expansions that call the function, [47m[illegal][0m,
  which has a guard that is logically [47mNIL[0m.  Those generate code that
  is in [47m:[0m[47m[logic][0m mode, as do variants of [47m(er soft ...)[0m.

  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 --- see
  [set-inhibit-output-lst] --- but here we show only the essential
  function calls.  Note that all arguments are evaluated even when
  error output is inhibited.

    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)))

  See [ctx] for the possible forms of the [47mctx[0m argument.

  Technical note for raw Lisp programmers only: It is possible to cause
  hard errors to signal actual raw Lisp errors.  See [hard-error].")
 (ER-CMP (POINTERS)
         "See [context-message-pair].")
 (ER-HARD
  (ERRORS ACL2-BUILT-INS)
  "Print an error message and ``cause a hard error''

  See [er] for relevant background, which is assumed below, and related
  utilities.

    General Form:
    (er-hard context summary str &rest str-args)

  where context is a legal context (see [ctx]), [47msummary[0m is [47mnil[0m or a
  string, [47mstr[0m is a string, and [47mstr-args[0m are [47mtsee fmt[0m arguments for
  [47mstr[0m.  Note that [47m(er-hard context summary str ...)[0m is equivalent to
  [47m(er hard context (cons summary str) ...)[0m.  The use of a non-[47mnil[0m
  [47msummary[0m allows suppression of this error message without
  suppressing all error output; see [set-inhibit-er].

  Calls of [47mer-hard[0m expand much like calls [47m(er hard ...)[0m, in the sense
  that both expand to calls of the function, [47m[illegal][0m, which has a
  [guard] equivalent to [47mnil[0m.  See [er-hard?] for a similar utility
  that avoids generating guard obligations.

  See [47m[er-soft][0m for a similar utility pertaining to ``soft'' errors.")
 (ER-HARD?
  (ERRORS ACL2-BUILT-INS)
  "Print an error message and ``cause a hard error''

  See [er-hard] for a nearly identical utility that is aligned with [47m(er
  hard ...)[0m, generating a [guard] obligation of [47mnil[0m.  By contrast,
  [47m(er-hard? ...)[0m is aligned with [47m(er hard? ...)[0m): these do not
  generate guard obligations.  This distinction is due to the fact
  that a call of [47m(er-hard ...)[0m macroexpands to a call of the
  function, [47m[illegal][0m, while a call of [47m(er-hard? ...)[0m macroexpands to
  a call of the function, [47m[hard-error][0m.

    General Form:
    (er-hard? context summary str &rest str-args)

  Other than the difference in guard obligations generated, as
  discussed above, [47mer-hard?[0m behaves identically to [47mer-hard[0m.  See
  [er-hard] and for relevant background, see [er].")
 (ER-LET* (POINTERS)
          "See [programming-with-state].")
 (ER-LET*-CMP (POINTERS)
              "See [context-message-pair].")
 (ER-PROGN
  (ERRORS PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Perform a sequence of state-changing ``error triples''

    Example:
    (er-progn (check-good-foo-p (f-get-global 'my-foo state) state)
              (value (* (f-get-global 'my-foo state)
                        (f-get-global 'bar state))))

  This sequencing primitive is only useful when programming with
  [state], something that very few users will probably want to do.
  See [state].

  [47mEr-progn[0m is used much the way that [47m[progn][0m is used in Common Lisp,
  except that it expects each form within it to evaluate to an
  [error-triple] of the form [47m(mv erp val state)[0m.  The first such
  form, if any, that evaluates to such a triple where [47merp[0m is not [47mnil[0m
  yields the error triple returned by the [47mer-progn[0m.  If there is no
  such form, then the [47mer-progn[0m form returns the value of the last
  form.

    General Form:
    (er-progn <expr1> ... <exprk>)

  where each [47m<expri>[0m is an expression that evaluates to an error triple
  (see [programming-with-state]).  The above form is essentially
  equivalent to the following (``essentially'' because in fact, care
  is taken to avoid variable capture).

    (mv-let (erp val state)
            <expr1>
            (cond (erp (mv erp val state))
                  (t (mv-let (erp val state)
                             <expr2>
                             (cond (erp (mv erp val state))
                                   (t ...
                                          (mv-let (erp val state)
                                                  <expr{k-1}>
                                                  (cond (erp (mv erp val state))
                                                        (t <exprk>)))))))))")
 (ER-PROGN-CMP (POINTERS)
               "See [context-message-pair].")
 (ER-SOFT
  (ERRORS ACL2-BUILT-INS)
  "Print an error message and ``cause a soft error''

  See [er] for relevant background, which is assumed below, and related
  utilities.

    General Form:
    (er-soft context summary str &rest str-args)

  where context is a legal context (see [ctx]), [47msummary[0m is [47mnil[0m or a
  string, [47mstr[0m is a string, and [47mstr-args[0m are [47mtsee fmt[0m arguments for
  [47mstr[0m.  The use of a non-[47mnil[0m [47msummary[0m allows suppression of this error
  message without suppressing all error output; see [set-inhibit-er].

  See [47m[er-hard][0m for a similar utility pertaining to ``hard'' errors.")
 (ERROR (POINTERS)
        "See [hints] for information about the keyword [47m:error[0m.")
 (ERROR-TRIPLE
  (ERRORS PROGRAMMING-WITH-STATE)
  "A common ACL2 programming idiom

  When evaluation returns three values, where the first two are
  ordinary (non-[stobj]) objects and the third is the ACL2 [state],
  the result may be called an ``error triple'' or ``error-triple''.
  If an error triple is [47m(mv erp val state)[0m, we think of [47merp[0m as an
  error flag and [47mval[0m as the returned value.  By default, if the
  result of evaluating a top-level form is an error triple [47m(mv erp
  val state)[0m, then that result is not printed if [47merp[0m is non-[47mnil[0m or if
  [47mval[0m is the keyword [47m:INVISIBLE[0m, and otherwise [47mval[0m is printed with a
  preceding space.  For example:

    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 !>

  In certain settings, notably when printing evaluation results,
  multiple values [47m(mv erp val state)[0m may be considered an error
  triple even when [47mval[0m is a [df] rather than an ordinary object.
  Here is an example; see [df] for more about how floating-point
  numbers are simulated in ACL2.

    ACL2 !>(mv nil (to-df 3) state)
     #d3.0
    ACL2 !>

  See [programming-with-state] for a discussion of error triples and
  how to program with them.  Also see [ld-error-triples] and see [ld]
  for a discussion of the value [47m:COMMAND-CONVENTIONS[0m for keyword
  [47m:LD-POST-EVAL-PRINT[0m.")
 (ERROR-TRIPLES-AND-PARALLELISM
  (PARALLEL-PROGRAMMING)
  "How to avoid error triples in ACL2(p)

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

  ACL2 supports the use of error triples in many features; e.g.,
  [47m[computed-hints][0m.  (For background on error triples, see
  [programming-with-state].)  However, ACL2(p) does not support the
  use of error triples in some of these features (e.g.,
  [47m[computed-hints][0m) while [waterfall-parallelism] is enabled.

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

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

  In this particular example, the cause of the error was trying to use
  a computed hint that returned state, which is not allowed when
  executing the waterfall in parallel (see
  [unsupported-waterfall-parallelism-features] for other related
  information).

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

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

  You may encounter other similar error messages when using
  [computed-hints], [custom-keyword-hints], or [override-hints].
  Chances are that you are somehow returning an error triple when an
  ordinary value is needed.  If this turns out not to be the case,
  please let the ACL2 implementors know.")
 (ERROR1
  (ERRORS ACL2-BUILT-INS)
  "Print an error message and cause a ``soft error''

  [47m(Error1 ctx summary str alist state)[0m returns [47m(mv t nil state)[0m.  An
  error message is first printed using the ``context'' [47mctx[0m, as well
  as the string [47mstr[0m and alist [47malist[0m that are of the same kind as
  expected by [47m[fmt][0m --- unless error output is inhibited (see
  [set-inhibit-output-lst] and [with-output]) or [47msummary[0m is non-[47mnil[0m,
  in which case it is a string, and error output of that type is
  inhibited (see [set-inhibit-er]).  See [fmt].

  [47mError1[0m can be interpreted as causing an ``error'' when programming
  with the ACL2 [47m[state][0m, something most ACL2 users will probably not
  want to do; see [ld-error-triples] and see [er-progn].  In order to
  cause errors with [47m:[0m[47m[logic][0m mode functions, see [hard-error] and see
  [illegal].  Better yet, see [er] for a macro that provides a
  unified way of signaling errors.

  As mentioned above, [47merror1[0m always returns [47m(mv t nil state)[0m.  But if a
  call [47m(error1 ctx summary str alist)[0m is encountered during
  evaluation, then unless output is inhibited as described above, the
  string [47mstr[0m is first printed using the association list [47malist[0m (as in
  [47m[fmt][0m).  Here is a trivial, contrived example.

    ACL2 !>(error1 'my-context
                   \"Printing 4: ~n0\"
                   (list (cons #\\0 4))
                   state)

    ACL2 Error in MY-CONTEXT:  Printing 4: four

    ACL2 !>")
 (ERRORS
  (PROGRAMMING)
  "Support for causing runtime errors, breaks, assertions, etc.


Subtopics

  [Assert$]
      Cause a hard error if the given test is false

  [Assert*]
      Create a [guard] proof obligation that given test holds

  [Assert-event]
      Assert that a given form returns a non-[47mnil[0m value

  [Break$]
      Cause an immediate Lisp break

  [Breaks]
      Common Lisp breaks

  [Ctx]
      Context object for error messages

  [Ctxp]
      Recognizer for context objects for error messages

  [Er]
      Print an error message and ``cause an error''

  [Er-hard]
      Print an error message and ``cause a hard error''

  [Er-hard?]
      Print an error message and ``cause a hard error''

  [Er-progn]
      Perform a sequence of state-changing ``error triples''

  [Er-soft]
      Print an error message and ``cause a soft error''

  [Error-triple]
      A common ACL2 programming idiom

  [Error1]
      Print an error message and cause a ``soft error''

  [Hard-error]
      Print an error message and stop execution

  [Illegal]
      Print an error message and stop execution

  [Set-inhibit-er]
      Control the error output

  [Set-inhibit-er!]
      Control error output non-[47m[local][0mly

  [Set-warnings-as-errors]
      Changing [warnings] to hard [errors] (and vice-versa)

  [Toggle-inhibit-er]
      Add or delete an error output string from the [47minhibit-er-table[0m

  [Toggle-inhibit-er!]
      Toggle an [47minhibit-er-table[0m entry non-[47m[local][0mly

  [Value-triple]
      Compute a value, optionally checking that it is not [47mnil[0m")
 (ESCAPE-TO-COMMON-LISP
  (COMMON-LISP)
  "Escaping to Common Lisp

    Example:
    ACL2 !>:Q

  There is essentially no Common Lisp escape feature in the ACL2 loop
  (see [lp]).  (A potentially unsound exception is raw-mode; see
  [set-raw-mode].)  This is part of the price of purity.  To execute
  a form in Common Lisp as opposed to ACL2, exit [47m[lp][0m with [47m:q[0m, submit
  the desired forms to the Common Lisp read-eval-print loop, and
  reenter ACL2 with [47m(lp)[0m.  WARNING: Doing so is potentially unsound;
  see [q].")
 (EV$
  (APPLY$)
  "Evaluate a tame expression using [47mapply$[0m

  When [47m[apply$][0m, actually [47m[apply$-lambda][0m, is asked to apply a [47mLAMBDA[0m
  object to some arguments it calls [47mev$[0m on the body of the object and
  an alist binding the formals of the object to the arguments.
  Roughly put, [47mev$[0m ``works'' by looking up symbols, returning quoted
  objects, and using [47mapply$[0m to apply function symbols to the results
  of evaluating their arguments.  [47mEv$[0m and its clique-mate [47mev$-list[0m
  are mutually-recursive with [47mapply$[0m.  [47mEv$[0m can only evaluate ``as
  expected'' on [tame] expressions and requires [47m[warrant][0ms, explicit
  in the proof theory or implicit in the evaluation theory, to
  determine [badge]s and thus tameness.  See [47m[apply$][0m for details,
  including the formal definitions of [47mev$[0m and [47mev$-list[0m.  For a
  summary of how the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m
  [scion]s, see [rewriting-calls-of-apply$-ev$-and-loop$-scions].")
 (EV$-LIST (POINTERS) "See [apply$].")
 (EVALUATING_APP_ON_SAMPLE_INPUT
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Evaluating App on Sample Input

  {IMAGE} (see [The_Associativity_of_App])

  {IMAGE}

    ACL2 !>[31;1m(app nil '(x y z))[0m
    (X Y Z)

    ACL2 !>[31;1m(app '(1 2 3) '(4 5 6 7))[0m
    (1 2 3 4 5 6 7)

    ACL2 !>[31;1m(app '(a b c d e f g) '(x y z))[0m   ; click here (see [Conversion]) for an explanation
    (A B C D E F G X Y Z)

    ACL2 !>[31;1m(app (app '(1 2) '(3 4)) '(5 6))[0m
    (1 2 3 4 5 6)

    ACL2 !>[31;1m(app '(1 2) (app '(3 4) '(5 6)))[0m
    (1 2 3 4 5 6)

    ACL2!>[31;1m(let ((a '(1 2))[0m
                [31;1m(b '(3 4))[0m
                [31;1m(c '(5 6)))[0m
            [31;1m(equal (app (app a b) c)[0m
                   [31;1m(app a (app b c))))[0m
    T

  {IMAGE}

  As we can see from these examples, ACL2 functions can be executed
  more or less as Common Lisp.

  The last three examples suggest an interesting property of [47mapp[0m.

  {IMAGE} (see [The_Associativity_of_App])")
 (EVALUATION
  (PROGRAMMING)
  "Evaluating ACL2 expressions

  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.

  At a high level, we can say that ACL2 evaluation takes place using
  the underlying host Common Lisp.  But consider the form [47m(car 3)[0m.
  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.

    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 !>

  The message suggests that the function [47mcar[0m has a [guard], or
  precondition, that is violated by the proposed argument, [47m3[0m.  So
  clearly something more is going on here than just evaluation of the
  form [47m(car 3)[0m in Common Lisp.

  In fact, every ACL2 function symbol is associated with the following
  two Common Lisp definitions, as explained below:

    * the ``executable-counterpart'' definition, sometimes called the
      ``*1*'' function (pronounced ``star one star''); and

    * the ``submitted'' definition (sometimes called the ``raw Lisp''
      function).

  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.

  Let us explore these two functions in the case of [47mcar[0m.  When [47m(car 3)[0m
  is evaluated in the ACL2 loop, the executable-counterpart of [47mcar[0m is
  applied to the argument [47m3[0m.  That executable-counterpart (which was
  hand-coded) first checks the guard of [47mcar[0m, which fails for [47m3[0m,
  leading to the error displayed above.  If instead the form to be
  evaluated by ACL2 is [47m(car '(4 5 6))[0m, the executable-counterpart of
  [47mcar[0m will first check that the guard of [47mcar[0m holds for the list
  argument [47m(4 5 6)[0m; then seeing that this is the case, it will apply
  the Common Lisp function [47mcar[0m --- which we consider to be the
  ``submitted'' function for [47mcar[0m --- to that list argument, returning
  [47m4[0m.

  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 [primitive] like [47mcar[0m.  Suppose
  we define the following functions [47mf[0m and [47mg[0m, each of which has an
  implicit [guard] (precondition) of [47mt[0m, i.e., the precondition always
  holds.

    (defun f (x)
      (car x))
    (defun g (x)
      (f x))

  ACL2 defines two functions named [47m\"F\"[0m: the executable-counterpart of
  [47mf[0m, sometimes called ``[47m*1*f[0m'', and the submitted function for [47mf[0m.  It
  also defines two such functions for [47mg[0m.  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 [47mf[0m (see [trace] for more about tracing); some
  analysis follows below this display.

    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 !>

  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 [47mg[0m calls
  the executable-counterpart of [47mf[0m, rather than calling any submitted
  function.

  Such a trace can show us an error caused by applying [47mcar[0m to [47m3[0m.

    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 !>

  It is generally more efficient to invoke a submitted functions ---
  which has as its Common Lisp definition exactly the [47m[defun][0m form
  submitted to ACL2 --- 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 [47mf[0m and [47mg[0m, in a fresh ACL2 session.

    (defun f (x)
      (declare (xargs :guard (or (consp x) (null x))))
      (car x))
    (defun g (x)
      (declare (xargs :guard (consp x)))
      (f x))

  This time, we see that the executable-counterpart of [47mg[0m directly calls
  the submitted function for [47mg[0m, because [47mg[0m was guard-verified when [47mg[0m
  was admitted and the value [47m'(4 5 6)[0m for the formal [47mx[0m of [47mg[0m satisfies
  the guard [47m(consp x)[0m of [47mg[0m.

    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 !>

  We can also see that because [47m3[0m fails to satisfy the guard of [47mg[0m, a
  guard violation is signaled by the executable-counterpart of [47mg[0m,
  rather than (as before) by the executable-counterpart of [47mcar[0m.

    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 !>

  See if you can predict the corresponding traces if instead, [47mf[0m has a
  suitable guard and is guard-verified, but [47mg[0m is as in the first
  example (with an implicit guard of [47mt[0m, and not guard-verified):

    (defun f (x)
      (declare (xargs :guard (or (consp x) (null x))))
      (car x))
    (defun g (x)
      (f x))

  The corresponding trace is as follows; discussion follows.

    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 !>

  The traces above show that first, the executable-counterpart of [47mg[0m
  calls the executable-counterpart of [47mf[0m.  This is because [47mg[0m is not
  guard-verified, so its executable-counterpart can only invoke other
  executable-counterparts.  However, since [47mf[0m is guard-verified, its
  executable-counterpart invokes its submitted function when the
  guard is satisfied, for example to generate the call [47m(F (4 5 6))[0m.
  If the guard for [47mf[0m fails to hold, however, the
  executable-counterpart for [47mf[0m causes a guard violation error, as
  shown above for the executable-counterpart call [47m(ACL2_*1*_ACL2::F
  3)[0m.

  See also [guard] and its subtopics, especially,
  [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 [47mf[0m may invoke [47m(trace!
  (oneify-cltl-code :native t))[0m before defining [47mf[0m in ACL2.


Subtopics

  [Guard-checking-inhibited]
      Avoiding certain warnings when evaluating ACL2 expressions")
 (EVALUATOR-RESTRICTIONS
  (META)
  "Some restrictions on the use of evaluators in meta-level rules

  Note: This topic, which explains some subtleties for evaluators, can
  probably be skipped by most readers.

  Rules of class [47m:[0m[47m[meta][0m and of class [47m:[0m[47m[clause-processor][0m are stated
  using so-called ``evaluator'' functions.  Here we explain some
  restrictions related to evaluators.  Below we refer primarily to
  [47m:meta[0m rules, but the discussion applies equally to
  [47m:clause-processor[0m rules.

  In a nutshell, we require that a rule's evaluator does not support
  any [meta-extract] functions in the rule or any [47m[defaxiom][0m 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 [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 ``ancestral in'',
  also expressed as ``an ancestor of'', in another function symbol.

  An argument given elsewhere (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 [defevaluator]) to handle all functions
  in the current ACL2 [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 [47m[defaxiom][0m 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 [meta-extract] functions if
  they are used in the proposed [47m:meta[0m theorem.

  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.

  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 [47m[encapsulate][0m 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 [47m(f x)[0m equals [47mt[0m even though, as shown below, that does not
  follow logically from the axioms introduced.

    ; 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))

  To see that the term [47m(equal (f x) t)[0m does not follow logically from
  the axiomatic [events] above, consider following the above
  definition of [47mmy-cancel[0m with the following [events] instead.

    ; (defun my-cancel (term) ...) as before, then:

    (defun f (x)
      (not x))

    (defun g ()
      nil)

    (defevaluator evl evl-list
       ((f x) (g)))

  These events imply the axiomatic events above, because we still have
  the definition of [47mmy-cancel[0m, we have a stronger [47m[defevaluator][0m
  event, and we can now prove [47mcorrectness-of-my-cancel[0m exactly as it
  is stated above.  So, the rule [47mf-t[0m 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 [47mf-t[0m.

    (defthm f-not-t
      (equal (f t) nil)
      :rule-classes nil)

  It follows that the current session logically yields a contradiction!

  Erik Reeber has taken the above example and modified it to prove [47mnil[0m
  in ACL2 Version_3.1, as follows.

    (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)

  Finally, we also require that no function has an attachment (see
  [defattach]) that is both ancestral in the evaluator and also
  ancestral in the meta or clause-processor functions.  (If you don't
  use [47m[defattach][0m or [47m[apply$][0m --- more specifically, [warrant]s ---
  then you can ignore this condition.)  Without this restriction, the
  following events prove [47mnil[0m.

    (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)

  Here is an example that doesn't use [47m[defattach][0m explicitly, but uses
  [warrant]s, which essentially have attachments so that every call
  of a warrant evaluates to [47mT[0m.  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.

    (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)

  To see why this restriction is sufficient, see a comment in the ACL2
  source code entitled ``; Essay on Correctness of Meta Reasoning.''

  One can sometimes work around this restriction; see
  [transparent-functions].")
 (EVENP
  (NUMBERS ACL2-BUILT-INS)
  "Test whether an integer is even

  [47m(evenp x)[0m is true if and only if the integer [47mx[0m is even.  Actually, in
  the ACL2 logic [47m(evenp x)[0m is defined to be true when [47mx/2[0m is an
  integer.

  The [guard] for [47mevenp[0m requires its argument to be an integer.

  [47mEvenp[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<evenp>

    (defun evenp (x)
      (declare (xargs :guard (integerp x)))
      (integerp (* x (/ 2))))")
 (EVENS
  (LISTS ACL2-BUILT-INS)
  "The even-indexed members of a list

  The call [47m(evens x)[0m returns the restriction of the true-list [47mx[0m to its
  even-indexed members (with zero-based indexing).  Note that if [47mx[0m is
  a list [47m(k1 a1 k2 a2 ... kn an)[0m that satisfies the predicate
  [47m[keyword-value-listp][0m, then [47m(evens x)[0m lists the keys [47mki[0m of [47mx[0m.
  Thus, the following is a theorem.

    (thm (iff (keyword-value-listp l)
              (and (true-listp l)
                   (evenp (len l))
                   (keyword-listp (evens l))))
         :hints ((\"Goal\" :induct (keyword-value-listp l))))

  [31;1mFunction: [0m<evens>

    (defun evens (l)
      (declare (xargs :guard (true-listp l)))
      (cond ((endp l) nil)
            (t (cons (car l) (evens (cddr l))))))")
 (EVENT (POINTERS) "See [events].")
 (EVENT-DATA (POINTERS)
             "See [saving-event-data].")
 (EVENTS
  (ACL2)
  "Functions that extend the logic

  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 [world]).  Indeed, the only way to change the ACL2
  [world] is via the successful evaluation of an event function.
  Every time the [world] is changed by an event, a landmark is left
  on the [world] and it is thus possible to identify the [world] ``as
  of'' the evaluation of a given event.  An event may introduce new
  logical names.  Some events introduce no new names (e.g.,
  [47m[verify-guards][0m), some introduce exactly one (e.g., [47m[defmacro][0m and
  [47m[defthm][0m), and some may introduce many (e.g., [47m[encapsulate][0m ).

  ACL2 typically completes processing of an event by printing a
  [summary].  Unless proofs are skipped (see [ld-skip-proofsp]) or
  summary output is inhibited (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 [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 [get-internal-time].

  See [embedded-event-form] for a discussion of events permitted in
  [books].


Subtopics

  [Add-custom-keyword-hint]
      Add a new custom keyword hint

  [Add-global-stobj]
      Add a global [stobj] with a given name

  [Assert-event]
      Assert that a given form returns a non-[47mnil[0m value

  [Comp]
      Compile some ACL2 functions

  [Defabbrev]
      A convenient form of macro definition for simple expansions

  [Defabsstobj]
      Define a new abstract single-threaded object

  [Defabsstobj-missing-events]
      Obtain the [events] needed to admit a [47m[defabsstobj][0m event

  [Defattach]
      Execute constrained functions using corresponding attached functions

  [Defaxiom]
      Add an axiom

  [Defchoose]
      Define a Skolem (witnessing) function

  [Defcong]
      Prove [congruence] rule

  [Defconst]
      Define a constant

  [Defequiv]
      Prove that a function is an [equivalence] relation

  [Defevaluator]
      Introduce an evaluator function

  [Defexec]
      Attach a terminating executable function to a definition

  [Define-trusted-clause-processor]
      Define a trusted (unverified) goal-level simplifier

  [Deflabel]
      Build a landmark

  [Defmacro]
      Define a macro

  [Defmacro-last]
      Define a macro that returns its last argument, but with side effects

  [Defmacro-untouchable]
      Define an ``untouchable'' macro

  [Defn]
      Definition with [guard] [47mt[0m

  [Defnd]
      [disable]d definition with [guard] [47mt[0m

  [Defpkg]
      Define a new symbol package

  [Defproxy]
      Define a non-executable [47m:[0m[47m[program][0m-mode function for attachment

  [Defrec]
      Introduce a record structure, like a [47mstruct[0m in C.

  [Defrefinement]
      Prove that [47mequiv1[0m refines [47mequiv2[0m

  [Defstobj]
      Define a new single-threaded object

  [Defstub]
      Stub-out a function symbol

  [Deftheory]
      Define a theory (to [enable] or [disable] a set of rules)

  [Deftheory-static]
      Define a `static' theory (to [enable] or [disable] a set of rules)

  [Defthm]
      Prove and name a theorem

  [Defthmd]
      Prove and name a theorem and then disable it

  [Defthy]
      Define a theory (to [enable] or [disable] a set of rules)

  [Defttag]
      Introduce a trust tag (ttag)

  [Defun]
      Define a function symbol

  [Defun$]
      Define a function symbol and generate a warrant

  [Defun-inline]
      Define a potentially inlined function symbol and associated macro

  [Defun-notinline]
      Define a not-to-be-inlined function symbol and associated macro

  [Defun-nx]
      Define a non-executable function symbol

  [Defun-sk]
      Define a function whose body has an outermost quantifier

  [Defund]
      Define a function symbol and then disable it

  [Defund-inline]
      Define a potentially disabled, inlined function symbol and
      associated macro

  [Defund-notinline]
      Define a disabled, not-to-be-inlined function symbol and associated
      macro

  [Defund-nx]
      Define a disabled non-executable function symbol

  [Embedded-event-form]
      Forms that may be embedded in other [events]

  [Encapsulate]
      Hide some [events] and/or constrain some functions

  [Evisc-table]
      Support for abbreviated output

  [In-arithmetic-theory]
      Designate theory for some rewriting done for non-linear arithmetic

  [In-theory]
      Designate ``current'' theory (enabling its rules)

  [Include-book]
      Load the [events] in a file

  [Local]
      Hiding an event in an encapsulation or book

  [Logical-name]
      A name created by a logical event

  [Make-event]
      Evaluate (expand) a given form and then evaluate the result

  [Memoize]
      Turn on memoization for a specified function

  [Mutual-recursion]
      Define some mutually recursive functions

  [Name]
      Syntactic rules on logical names

  [Partial-encapsulate]
      Introduce functions with some constraints unspecified

  [Profile]
      Turn on profiling for one function

  [Progn]
      Evaluate some [events]

  [Progn!]
      Evaluate some forms, not necessarily [events]

  [Project-dir-alist]
      Support for moving project directories (also [47m:dir[0m arguments)

  [Redundant-events]
      Allowing a name to be introduced ``twice''

  [Regenerate-tau-database]
      Regenerate the tau database relative to the current enabled theory

  [Remove-custom-keyword-hint]
      Remove a custom keyword hint

  [Remove-global-stobj]
      Remove a global [stobj] with a given name

  [Set-body]
      Set the definition body

  [Set-table-guard]
      Set the [47m:guard[0m for a [table]

  [Skip-proofs]
      Skip proofs for a given form --- a quick way to introduce
      unsoundness

  [Table]
      User-managed tables

  [Theory-invariant]
      User-specified invariants on [theories]

  [Unmemoize]
      Turn off memoization for the specified function

  [Value-triple]
      Compute a value, optionally checking that it is not [47mnil[0m

  [Verify-guards]
      Verify the [guard]s of a function

  [Verify-guards+]
      Verify the [guard]s of a function

  [Verify-termination]
      Convert a function from :program mode to :logic mode")
 (EVISC-TABLE
  (EVENTS)
  "Support for abbreviated output

  The [47mevisc-table[0m is an ACL2 table (see [table]) whose purpose is to
  modify the print representations of specified non-[47mnil[0m 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 [47m(a b
  c)[0m with the token [47m<my-abc-list>[0m.

    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 !>

  Every value in this [table] must be either a string or [47mnil[0m, where [47mnil[0m
  eliminates any association of the key with an abbreviation.
  Continuing with the log above:

    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 !>

  It can be particularly helpful to use this table to abbreviate a
  constant introduced by [47m[defconst][0m by prefixing the constant name
  with [47m\"#.\"[0m, as we now describe.  Consider first the following
  example.

    (defconst *abc* '(1 2 3 4 5 6 7 8))
    (table evisc-table *abc*
      (concatenate 'string \"#.\" (symbol-name '*abc*)))

  Then the constant [47m*abc*[0m is printed as follows --- very helpful if its
  associated structure is significantly larger than the 8-element
  list of numbers shown above!

    ACL2 !>*abc*
    #.*ABC*
    ACL2 !>

  What's more, the ACL2 reader will replace [47m#.*C*[0m, where [47m*C*[0m is defined
  by [47m[defconst][0m, by its value, regardless of [47mevisc-table[0m; see
  [sharp-dot-reader].  Continuing with the example above, we have:

    ACL2 !>(cdr (quote #.*ABC*))
    (2 3 4 5 6 7 8)
    ACL2 !>

  Of course, more care needs to be taken if packages are involved (see
  [defpkg]), as we now illustrate.

    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 !>

  We conclude by an example showing some extra care that may be
  important to consider taking.  We start with:

    (defconst |*BaR*| '(3 4))

  Then the following works just fine; but try it without the extra code
  for the [47mmay-need-slashes[0m case and you'll see that the sharp-dot
  printing is missing.  First:

    (table evisc-table
           |*BaR*|
           (let ((x (symbol-name '|*BaR*|)))
             (if (may-need-slashes x)
                 (concatenate 'string \"#.|\" x \"|\")
               (concatenate 'string \"#.\" x))))

  Then:

    ACL2 !>|*BaR*|
    #.|*BaR*|
    ACL2 !>

  The examples above illustrate how the [47mevisc-table[0m is used when
  printing evaluation results.  More generally, that [table] is used
  when [47m[fmt][0m (or a related function such as [47m[fms][0m) prints an object
  using [47m~x[0m [47m~X[0m, [47m~y[0m, [47m~Y[0m, [47m~f[0m, or [47m~F[0m.")
 (EVISC-TUPLE
  (IO)
  "Control suppression of details when printing

  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: [47m(evisc-tuple print-level print-length alist
  hiding-cars)[0m is the same as the value of [47m(list alist print-level
  print-length hiding-cars)[0m, and the components are used as follows
  (with priority order as discussed below).  The [47malist[0m component is
  used to replace any substructure occurring as a key by the
  corresponding string.  The [47mprint-level[0m and [47mprint-length[0m are
  analogous to Common Lisp variables [47m*print-level*[0m and
  [47m*print-length*[0m, respectively, and cause replacement of
  substructures deeper than [47mprint-level[0m by `[47m#[0m' and those longer than
  [47mprint-length[0m by `[47m...[0m'.  Finally, any [47m[consp][0m [47mx[0m that starts with one
  of the symbols in [47mhiding-cars[0m is printed as [47m<hidden>[0m.

  The following example illustrates the use of an evisc-tuple that
  limits the print-level to 3 --- only three descents into list
  structures are permitted before replacing a subexpression by `[47m#[0m'
  --- and limits the print-length to 4 --- only the first four
  elements of any list structure will be printed before replacing its
  tail by `[47m...[0m'.

    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 !>

  Notice that it is impossible to read the printed value back into
  ACL2, since there is no way for the ACL2 reader to interpret `[47m#[0m' or
  `[47m...[0m'.  To solve this problem, see [set-iprint].

  In the above example we pass an evisc-tuple explicitly to a printing
  function, in this case, [47m[fms][0m (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 [set-evisc-tuple]
  and see [without-evisc].


Subtopics

  [Brr-evisc-tuple]
      Determines partial suppression of output from [brr-commands]")
 (EVISCERATE-HIDE-TERMS
  (IO)
  "To print [47m(hide ...)[0m as [47m<hidden>[0m

    Example:
    (assign eviscerate-hide-terms t)
    (assign eviscerate-hide-terms nil)

  [47mEviscerate-hide-terms[0m is a [47m[state][0m global variable whose value is
  either [47mt[0m or [47mnil[0m.  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 [set-evisc-tuple]).  If [47mt[0m, terms of the form [47m(hide
  ...)[0m are printed as [47m<hidden>[0m.  Otherwise, they are printed
  normally.")
 (EXAMPLE-INDUCTION-SCHEME-BINARY-TREES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction on binary trees

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  [31;1mClassical Induction on Binary Trees[0m: To prove [47m(p x)[0m, for all [47mx[0m, by
  classical induction on binary tree structures, prove each of the
  following:

    [3mBase Case[0m:
    (implies (atom x) (p x))

    [3mInduction Step[0m:
    (implies (and (not (atom x))
                  (p (car x))
                  (p (cdr x)))
             (p x))

  An argument analogous to that given in
  [example-induction-scheme-on-lists] should convince you that [47m(p x)[0m
  holds for every object.

  A function that suggests this induction is:

    (defun flatten (x)
      (if (atom x)
          (list x)
          (app (flatten (car x))
               (flatten (cdr x))))).")
 (EXAMPLE-INDUCTION-SCHEME-DOWN-BY-2
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction downwards 2 steps at a time

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  [31;1mClassical Induction on Natural Numbers Preserving Parity[0m: Here is
  another way to decompose natural numbers.  To prove [47m(p n)[0m, for all
  [47mn[0m, prove each of the following:

    [3mBase Case 1[0m:
    (implies (zp n) (p n))

    [3mBase Case 2[0m:
    (implies (equal n 1) (p n))

    [3mInduction Step[0m:
    (implies (and (not (zp n))
                  (not (equal n 1))
                  (p (- n 2)))
             (p n))

  Base Case 1 establishes that [47mp[0m holds for [47m0[0m (and all objects other
  than positive naturals).

  Base Case 2 establishes that [47mp[0m holds for [47m1[0m.

  The Induction Step establishes that if [47mn[0m is a natural number greater
  than [47m1[0m, and if [47mp[0m holds for [47mn[0m-2, then [47mp[0m holds for [47mn[0m.

  Note that we have thus proved that [47m(p n)[0m holds, for all [47mn[0m.  For
  example, [47m(p -7)[0m, [47m(p 'abc)[0m, and [47m(p 0)[0m are all established by Base
  Case 1.  [47m(p 1)[0m is established by Base Case 2.  [47m(p 2)[0m is established
  from [47m(p 0)[0m and the Induction Step.  Think about it!  [47m(p 3)[0m is
  established form [47m(p 1)[0m and the Induction Step, etc.

  A function that suggests this induction is:

    (defun parity (n)
      (if (zp n)
          'even
          (if (equal n 1)
              'odd
              (parity (- n 2))))).")
 (EXAMPLE-INDUCTION-SCHEME-NAT-RECURSION
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction on natural numbers

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  [31;1mClassical Induction on Natural Numbers[0m: Induction is familiar in the
  arithmetic setting.  To prove [47m(p n)[0m, for all [47mn[0m, by classical
  induction on the construction of the natural numbers, prove each of
  the following:

    [3mBase Case[0m:
    (implies (zp n) (p n))

    [3mInduction Step[0m:
    (implies (and (not (zp n))
                  (p (- n 1)))
             (p n))

  The Base Case establishes that [47mp[0m holds for [47m0[0m.  In fact, because of
  the definition of [47m[zp][0m {ICON} (see [A_Tiny_Warning_Sign]), it
  establishes that [47m(p n)[0m holds when [47mn[0m is [47m0[0m and it holds when [47mn[0m is not
  a natural number.

  The Induction Step establishes that if [47mn[0m is a natural number other
  than [47m0[0m, and if [47mp[0m holds for [47mn[0m-1, then [47mp[0m holds for [47mn[0m.  The hypothesis
  [47m(p (- n 1))[0m above is called the [3minduction hypothesis[0m.

  A function that suggests this induction is

    (defun nat-recursion (n)
      (if (zp n)
          n
          (nat-recursion (- n 1))))

  Similarly, the term [47m(fact n)[0m suggests this induction if [47mfact[0m is
  defined:

    (defun fact (k)
     (if (zp k)
         1
         (* k (fact (- k 1))))).

  even though the formal parameter of this definition of [47mfact[0m is [47mk[0m, not
  [47mn[0m.")
 (EXAMPLE-INDUCTION-SCHEME-ON-LISTS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction on lists

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  [31;1mClassical Induction on Lists[0m: To prove [47m(p x)[0m, for all [47mx[0m, by classical
  induction on the linear list structure, prove each of the
  following:

    [3mBase Case[0m:
    (implies (endp x) (p x))

    [3mInduction Step[0m:
    (implies (and (not (endp x))
                  (p (cdr x)))
             (p x))

  An argument analogous to that given for natural numbers,
  [example-induction-scheme-nat-recursion], establishes [47m(p x)[0m for
  every [47mx[0m.  For example, [47m(p -7)[0m, [47m(p 'abc)[0m, and [47m(p nil)[0m are all
  established by the Base Case.  [47m(p '(Friday))[0m follows from [47m(p nil)[0m,
  given the Induction Step.  That sentence bears thinking about!
  Think about it!  Similarly, [47m(p '(Yellow))[0m holds for the same
  reason.  [47m(p '(Thursday Friday))[0m follows from [47m(p '(Friday))[0m and the
  Induction Step, etc.

  A function that suggests this induction is

    (defun app (x y)
      (if (endp x)
          y
          (cons (car x)
                (app (cdr x) y)))).")
 (EXAMPLE-INDUCTION-SCHEME-ON-SEVERAL-VARIABLES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction on several variables

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  [31;1mInduction on Several Variables[0m To [47m(p n x)[0m for all [47mn[0m and all [47mx[0m, prove
  each of the following:

    [3mBase Case 1[0m:
    (implies (endp x)
             (p n x))

    [3mBase Case 2[0m:
    (implies (and (not (endp x))
                  (zp n))
             (p n x))

    [3mInduction Step[0m:
    (implies (and (not (endp x))
                  (not (zp n))
                  (p (- n 1) (cdr x)))
             (p n x))

  A function that suggests this induction is

    (defun nth (n x)
      (if (endp x)
          nil
          (if (zp n)
              (car x)
              (nth (- n 1) (cdr x))))).")
 (EXAMPLE-INDUCTION-SCHEME-UPWARDS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction upwards

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  [31;1mInduction Upwards[0m: To [47m(p i max)[0m for all [47mi[0m and all [47mmax[0m, prove each of
  the following:

    [3mBase Case[0m:
    (implies (not (and (natp i)
                       (natp max)
                       (< i max)))
             (p i max))

    [3mInduction Step[0m:
    (implies (and  (natp i)
                   (natp max)
                   (< i max)
                   (p (+ i 1) max))
             (p i max))

  Note that the induction hypothesis is about an [47mi[0m that is [3mbigger[0m than
  the [47mi[0m 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.

  A function that suggests this induction is shown below.  ACL2 has to
  be told the measure, namely the difference between [47mmax[0m and [47mi[0m
  (coerced to a natural number to ensure that the measure is an
  ordinal).

    (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)).")
 (EXAMPLE-INDUCTION-SCHEME-WITH-ACCUMULATORS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction scheme with accumulators

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  To prove [47m(p x a)[0m for all [47mx[0m and all [47ma[0m, prove each of the following:

    [3mBase Case[0m:
    (implies (endp x)
             (p x a))

    [3mInduction Step[0m:
    (implies (and (not (endp x))
                  (p (cdr x) (cons (car x) a)))
             (p x a))

  Note that in the induction hypothesis we assume [47mp[0m for a smaller [47mx[0m but
  a larger [47ma[0m.  In fact, we could include as many induction hypotheses
  as we want and use any terms we want in the [47ma[0m position as long as
  the [47mx[0m position is occupied by a smaller term.

  A function that suggests this particular induction is shown below.

    (defun rev1 (x a)
      (if (endp x)
          a
          (rev1 (cdr x) (cons (car x) a)))).

  A function that suggests a similar induction in which three induction
  hypotheses are provided, one in which the [47ma[0m position is occupied by
  [47m(cons (car x) a)[0m, another in which the [47ma[0m position is occupied by
  some arbitrary term [47mb[0m, and a third in which the [47ma[0m position is
  occupied by [47ma[0m, is suggested by the term [47m(rev1-modified x a b)[0m where

    (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))))

  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 [47mlist[0m of all the formals
  (to ensure all variables are involved) and to combine recursive
  calls on a given branch with [47mlist[0m (to avoid introducing additional
  case analysis as would happen if [47mand[0m or [47mor[0m or other propositional
  functions are used).

  If you tried to prove [47m(p x a)[0m and suggested the induct hint
  [47m(rev1-modified x a (fact k))[0m, as by

    (thm (p x a)
         :hints ((\"Goal\" :induct (rev1-modified x a (fact k)))))

  the inductive argument would be:

    [3mBase Case[0m:
    (implies (endp x)
             (p x a))

    [3mInductive Step[0m:
    (implies (and (not (endp x))
                  (p (cdr x) (cons (car x) a))
                  (p (cdr x) (fact k))
                  (p (cdr x) a))
             (p x a))")
 (EXAMPLE-INDUCTION-SCHEME-WITH-MULTIPLE-INDUCTION-STEPS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Induction scheme with more than one induction step

  See [logic-knowledge-taken-for-granted-inductive-proof] for an
  explanation of what we mean by the induction [3msuggested[0m by a
  recursive function or a term.

  [31;1mSeveral Induction Steps[0m: To [47m(p x i a)[0m for all [47mx[0m, [47mi[0m, and [47ma[0m, prove each
  of the following:

    [3mBase Case 1[0m:
    (implies (zp i)
             (p x i a))

    [3mInduction Step 1[0m:
    (implies (and (not (zp i))
                  (equal (parity i) 'even)
                  (p (* x x)
                     (floor i 2)
                     a))
             (p x i a))

    [3mInduction Step 2[0m:
    (implies (and (not (zp i))
                  (not (equal (parity i) 'even))
                  (p x
                     (- i 1)
                     (* x a)))
             (p x i a))

  A function that suggests this induction is the binary exponentiation
  function for natural numbers.

    (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)
                      )))).

  In order to admit this function it is necessary to know that [47m(floor i
  2)[0m is smaller than [47mi[0m in the case above.  This can be proved if the
  community book [47m\"arithmetic-5/top\"[0m has been included from the ACL2
  system directory, i.e.,

    (include-book \"arithmetic-5/top\" :dir :system)

  should be executed before defining [47mbexpt[0m.")
 (EXAMPLE-INDUCTIONS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Some examples of induction schemes in ACL2

  Here are some pages illustrating various induction schemes suggested
  by recursive functions.

  [31;1mClassical Induction on Natural Numbers[0m: see
  [example-induction-scheme-nat-recursion].

  [31;1mInduction Preserving Even/Odd Parity[0m or
  [31;1mInduction Downwards by 2[0m or
  [31;1mInduction with Multiple Base Cases[0m: 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.

  [31;1mClassical Induction on Lists[0m: see [example-induction-scheme-on-lists]
  for an induction over linear lists, in which we inductively assume
  the conjecture for [47m(cdr x)[0m and prove it for [47mx[0m.  It doesn't matter
  whether the list is [47mnil[0m-terminated or not; the Base Case addresses
  all the possibilities.

  [31;1mClassical Induction on Binary (Cons) Trees[0m: 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.

  [31;1mInduction on Several Variables[0m: see
  [example-induction-scheme-on-several-variables] for an induction in
  which several variables participate in the case analysis and
  induction hypotheses.

  [31;1mInduction Upwards[0m: 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.

  [31;1mInduction with Auxiliary Variables[0m or
  [31;1mInduction with Accumulators[0m: 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.

  [31;1mInduction with Multiple Induction Steps[0m: 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.")
 (EXECUTABLE-COUNTERPART
  (RULE-CLASSES)
  "A rule for computing the value of a function

  This topic is about a type of [rune] that controls evaluation using
  the executable-counterpart of a function.  For discussion of
  executable-counterparts of functions, see [evaluation].

    Example:
    (:executable-counterpart length)

  which may be abbreviated in [theory] expressions in either of the
  following two ways (see [rune]).

    (:e length)
    (length)

  Every [47m[defun][0m introduces at least two rules used by the theorem
  prover.  Suppose [47mfn[0m is the name of a [47m[defun][0m'd function.  Then
  [47m(:definition fn)[0m is the rune (see [rune]) naming the rule that
  allows the simplifier to replace calls of [47mfn[0m by its instantiated
  body.  [47m(:executable-counterpart fn)[0m is the [rune] for the rule for
  how to evaluate the function on known constants.

  When typing [theories] it is convenient to know that [47m(fn)[0m is a runic
  designator that denotes [47m(:executable-counterpart fn)[0m.  See
  [theories].

  If [47m(:executable-counterpart fn)[0m is [enable]d, then when applications
  of [47mfn[0m to known constants are seen by the simplifier they are
  computed out by executing the Common Lisp code for [47mfn[0m (with the
  appropriate handling of [guard]s).  Suppose [47mfact[0m is defined as the
  factorial function.  If the executable-counterpart [rune] of [47mfact[0m,
  [47m(:executable-counterpart fact)[0m, is [enable]d when the simplifier
  encounters [47m(fact 12)[0m, then that term will be ``immediately''
  expanded to [47m479001600[0m.  Note that even if subroutines of [47mfn[0m have
  disabled executable-counterparts, [47mfn[0m will call their Lisp code
  nonetheless: once an executable-counterpart function is applied, no
  subsidiary enable checks are made.

  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 [rune] of the
  relevant function.  For example, if [47m(:executable-counterpart fact)[0m
  is [disable]d, [47m(fact 12)[0m will not be expanded by computation.  In
  this situation, [47m(fact 12)[0m may be rewritten to [47m(* 12 (fact 11))[0m,
  using the rule named [47m(:definition fact)[0m, provided the system's
  heuristics permit the introduction of the term [47m(fact 11)[0m.  Note
  that lemmas about multiplication may then be applicable (while such
  lemmas would be inapplicable to [47m479001600[0m).  In many proofs it is
  desirable to [disable] the executable-counterpart [rune]s of
  certain functions to prevent their expansion by computation.  See
  [executable-counterpart-theory].

  Finally: What do we do about functions that are ``constrained''
  rather than defined, such as the following?  (See [encapsulate].)

    (encapsulate (((foo *) => *))
                 (local (defun foo (x) x)))

  Does [47mfoo[0m have an executable-counterpart?  Yes: since the vast
  majority of functions have sensible executable-counterparts, it was
  decided that [31;1mall[0m functions, even such ``constrained'' ones, have
  executable-counterparts.  We essentially ``trap'' when such calls
  are inappropriate.  Thus, consider for example:

    (defun bar (x)
      (if (rationalp x)
          (+ x 1)
        (foo x)))

  If the term [47m(bar '3)[0m is encountered by the ACL2 rewriter during a
  proof, and if the [47m:executable-counterpart[0m of [47mbar[0m is [enable]d, then
  it will be invoked to reduce this term to [47m'4[0m.  However, if the term
  [47m(bar 'a)[0m is encountered during a proof, then since [47m'a[0m is not a
  [47m[rationalp][0m and since the [47m:executable-counterpart[0m of [47mfoo[0m is only a
  ``trap,'' then this call of the [47m:executable-counterpart[0m of [47mbar[0m will
  result in a ``trap.'' In that case, the rewriter will return the
  term [47m(hide (bar 'a))[0m so that it never has to go through this
  process again.  See [hide].")
 (EXECUTABLE-COUNTERPART-THEORY
  (THEORIES THEORY-FUNCTIONS)
  "[Executable-counterpart] rules as of logical name

    Examples:
    (executable-counterpart-theory :here)
    (executable-counterpart-theory 'lemma3)

  See [logical-name].

    General Form:
    (executable-counterpart-theory logical-name)

  Returns the theory containing all the [47m:[0m[47m[executable-counterpart][0m
  [rune]s, whether [enable]d or not, that existed immediately after
  [47m[logical-name][0m was introduced.  See the documentation for
  [theories], [logical-name], [executable-counterpart] and
  [47m[function-theory][0m.

  You may experience a fencepost problem in deciding which logical name
  to use.  [47m[Deflabel][0m can always be used to mark unambiguously for
  future reference a particular point in the development of your
  theory.  The order of [events] in the vicinity of an [47m[encapsulate][0m
  is confusing.  See [encapsulate].

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].")
 (EXECUTION (POINTERS)
            "See [evaluation].")
 (EXISTS
  (DEFUN-SK)
  "Existential quantifier

  The symbol [47mexists[0m (in the ACL2 package) represents existential
  quantification in the context of a [47m[defun-sk][0m form.  See [defun-sk]
  and see [forall].

  See [quantifiers] for an example illustrating how the use of
  recursion, rather than explicit quantification with [47m[defun-sk][0m, may
  be preferable.")
 (EXIT (GOOD-BYE)
       "Quit entirely out of Lisp

  Same as [47m[good-bye][0m.")
 (EXIT-BOOT-STRAP-MODE
  (HISTORY)
  "The end of pre-history

  [47mExit-boot-strap-mode[0m is the last step in creating the ACL2 [world] in
  which the user lives.  It has [command] number [47m0[0m.  [Command]s
  before it are part of the system initialization and extend all the
  way back to [47m:[0m[47m[min][0m.  [Command]s after it are those of the user.

  [47mExit-boot-strap-mode[0m is a Common Lisp function but not an ACL2
  function.  It is called when every [47m[defconst][0m, [47m[defun][0m, etc., in
  our source code has been processed under ACL2 and the [world] is
  all but complete.  [47mexit-boot-strap-mode[0m has only one job: to signal
  the completion of the boot-strapping.")
 (EXPAND (POINTERS)
         "See [hints] for information about the keyword [47m:expand[0m.")
 (EXPLAIN-GIANT-LAMBDA-OBJECT
  (APPLY$)
  "print data related to a large lambda object

  Translate will signal an error if it encounters an ``excessively
  large'' [47m[lambda][0m 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 [47mlambda[0m object that
  caused the error, execute

    (explain-giant-lambda-object)

  The rest of this documentation topic explains why we detect these
  objects and what you can do about them.

  When a [47m[lambda][0m object is translated we [47m[hons-copy][0m it so that it is
  uniquely represented.  This speeds up the performance of the
  compiled [47mlambda[0m cache (see [47m[print-cl-cache][0m).

  However, if the number of conses in the [47mlambda[0m object is greater than
  or equal to [47m(lambda-object-count-max-val)[0m, we cause an error.  If
  this error has been signaled in your session we recommend that you
  evaluate [47m(explain-giant-lambda-object)[0m, which will tell you more
  about the excessively large [47mlambda[0m object.  The current value of
  [47m(lambda-object-count-max-val)[0m is 200,000.  For reference, the
  largest function definition in the ACL2 sources (as of Version 8.6)
  is the [47m[mutual-recursion][0m event defining [47mrewrite[0m and its 51
  mutually recursive subfunctions.  The total number of conses in
  that clique is 14,656.

  There are generally two ways excessively large [47mlambda[0m objects come
  into existence: (1) they are generated automatically, as by macros,
  functions, or [47m[make-event][0m, or (2) you wrote a small [47mlambda[0m object
  but used a big quoted constant in it.

  (1) If the offending [47mlambda[0m object was built mechanically, we
  recommend that you redefine the generation process so that it
  introduces a named function.  For example, suppose the [47mlambda[0m
  object sketched below is excessively large.

    (lambda (x y)
      (if (eq x 'FOO1)
          (my-foo1 y)
          (if (eq x 'FOO2)
              (my-foo2 y)
              ...)))

  Then perhaps instead of generating that object you could generate the
  definition

    (defun my-big-switch (x y)
      (if (eq x 'FOO1)
          (my-foo1 y)
          (if (eq x 'FOO2)
              (my-foo2 y)
              ...)))

  And then use the quite small [47m(lambda$ (x y) (my-big-switch x y))[0m in
  place of the offending [47mlambda[0m object.  Of course, this is not
  always easy to carry out, since it would also require calling
  [47m[defwarrant][0m on [47mmy-big-switch[0m and providing that warrant as a
  hypothesis to any theorem involving the new [47mlambda[0m object.

  (2) If the offending [47mlambda[0m object just contains large quoted
  constants perhaps you can bind a variable to the large value
  outside of the [47mlambda[0m object and pass that variable into the [47mlambda[0m
  object in a new formal.

  For example, suppose the term [47m(regression-suite)[0m 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.

    (defconst *system*
      '(#x488b55f0
        #x31ff
        #xff142570081050
        #xf84995b0000
        #xf645f801
        #xf8573100000
        #x807df019
        ...))

  Then we might wish to execute something like the following.

    ACL2 !>(loop$ for pair in (regression-suite)
                  always (equal (sim *system* (car pair)) (cdr pair)))

  which simulates the [47m*system*[0m on every input in the regression suite
  and compares the result to the known correct answer.

  The formal translation of this term is

    (always$ '(lambda (loop$-ivar)
                (equal (sim '(#x488b55f0
                              #x31ff
                              #xff142570081050
                              #xf84995b0000
                              #xf645f801
                              #xf8573100000
                              #x807df019
                              ...)
                            (car loop$-ivar))
                       (cdr loop$-ivar)))
             (regression-suite))

  Note that the constant [47m*system*[0m has been rendered as its quoted value
  and that it is inside of the [47mlambda[0m object.  If [47m*system*[0m is a very
  large constant, that [47mlambda[0m object may be excessively large.

  But we can avoid that by writing this instead.

    ACL2 !>(let ((sys *system*))
             (loop$ for pair in (regression-suite)
                    always (equal (sim sys (car pair)) (cdr pair))))

  which essentially translates to

    (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)))))

  Note that the [47mlambda[0m object no longer contains the large constant.
  It now refers to a ``global'' variable whose value is that of
  [47m*system*[0m.  The [47mlambda[0m object is quite small.

  For what it is worth, the largest single object in the ACL2 image (as
  of Version 8.6) is the value of [47m(w state)[0m, the logical world.  Upon
  starting the system [47m(w state)[0m 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 [47m(expt 10
  655)[0m when counted naively, but the total number of distinct conses
  is 1,875,653.  So if you build a [47mlambda[0m object containing the value
  of [47m(w state)[0m it will be ``excessively large.''")
 (EXPLAIN-NEAR-MISS
  (DEBUGGING)
  "show why a rule's pattern and the :target do not match

  When a near miss break occurs (see [47m[monitor][0m) the user sees a message
  like this:

    (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.

  It can be difficult to determine why the pattern of the rule, e.g.,
  the [47m:lhs[0m of a [47m:rewrite[0m rule, fails to match the [47m:target[0m term,
  especially when large terms, large quoted constants, and [47mlambda[0m
  expressions are involved.

  Included among the [47m:[0m[47m[brr-commands][0m is the [47m:explain-near-miss[0m 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.

  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 [47m[brr][0m command [47m:target[0m.  The ``triggering pattern'' of the
  rule in question depends on how the rule was stored (see
  [47m[rule-classes][0m).  The triggering pattern of a [47m:[0m[47m[rewrite][0m rule ---
  the most common class of rule --- is the left-hand side of the
  concluding equality and can be obtained from within the break by
  typing the [47m[brr][0m command [47m:lhs[0m.  The triggering pattern for a
  [47m:[0m[47m[rewrite-quoted-constant][0m rule is its right-hand side, but as
  explained in [47m[rewrite-quoted-constant][0m, the [47mbrr[0m command [47m:lhs[0m will
  display it.  The triggering pattern for a [47m:[0m[47m[linear][0m rule is
  displayed by the [47m:[0m[47mmax-term[0m [47mbrr[0m command.  The question the user will
  typically ask in this situation is ``why doesn't the triggering
  pattern match the target?''

  To understand the answer you have to understand how the ACL2 matching
  algorithm works.  The matching algorithm is given two terms, [47mt1[0m and
  [47mt2[0m, and attempts to find a substitution [47ms[0m on the variables in [47mt1[0m
  such that when [47mt1[0m is instantiated with [47ms[0m the result is [47mt2[0m, i.e.,
  [47mt1/s[0m = [47mt2[0m.  Note that only the variables in the pattern, [47mt1[0m, can be
  instantiated by [47ms'[0m.  In the case of a near miss break, no such
  substitution was found.

  The [47m:explain-near-miss[0m 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.

  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 [47m<pat>[0m.  That
  [47m<pat>[0m is displayed in lowercase whereas the rest of the pattern and
  target are in uppercase.  It marks where the matching broke down.

  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 [47m<pat>[0m and what the [47m<pat>[0m subterm of the pattern is
  when instantiated with that substitution.

  So, for example, suppose the rule's [47m:lhs[0m and the current [47m:target[0m are
  as shown below.  Then here is what [47m:explain-near-miss[0m would print.

    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.

  Note that the substitution [47ms[0m binds [47mX[0m to [47mA[0m to match the first argument
  of the [47mF[0m-expression in the [47m:LHS[0m to the corresponding argument in
  the [47m:TARGET[0m.  Then it tries to match [47m(G X Y)[0m with [47m(G B A)[0m.  It
  fails on the first argument of that subterm, where [47m<pat>[0m is shown
  in [47m:LHS'[0m, because [47mX[0m has been bound to [47mA[0m and [47mA[0m and [47mB[0m are different.
  (Remember: only the variables of the pattern can be bound by the
  substitution.)

  When [47m<pat>[0m and its corresponding subterm [47m<tar>[0m are ``large'' but
  unequal quoted constants or [47mlambda[0m expressions, [47m:explain-near-miss[0m
  will call [47m[compare-objects][0m on those objects.  It can be hard to
  spot how two large constants differ and [47mcompare-objects[0m points out
  the differences between two [47mcons[0m trees.  [47m:Explain-near-miss[0m
  considers an object ``large'' if the number of conses in it is 30
  or greater.

  The command [47m:explain-near-miss+[0m is like [47m:explain-near-miss[0m except it
  never eviscerates any term and runs [47mcompare-objects[0m whenever the
  failure is on two distinct quoted objects or [47mlambda[0m expressions
  regardless of their sizes.

  But note that [47mcompare-objects[0m is not run by either version of
  [47mexplain-near-miss[0m when the failure is of the most common kinds:

    * (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

    * (b) a term in the pattern has a different function symbol than the
      corresponding term the target.

  So do not expect the [47mcompare-objects[0m output to appear often!")
 (EXPLODE-ATOM
  (CHARACTERS ACL2-BUILT-INS)
  "Convert any [atom] into a [character-listp] that contains its printed
  representation, rendering numbers in your choice of print base.

  [47m(explode-atom x print-base)[0m prints the atom [47mx[0m as a list of
  characters, using some [print-base-p] to decide what base to print
  numbers in.

  Examples:

    (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

  See also [explode-nonnegative-integer], [str::numbers], and
  [printing-to-strings].

  [31;1mFunction: [0m<explode-atom>

    (defun explode-atom (x print-base)
     (declare (xargs :guard (and (atom x)
                                 (print-base-p print-base))))
     (cond
      ((rationalp x)
       (cond
        ((integerp x)
         (cond ((< x 0)
                (cons #\\-
                      (explode-nonnegative-integer (- x)
                                                   print-base nil)))
               (t (explode-nonnegative-integer x print-base nil))))
        (t
         (append (explode-atom (numerator x) print-base)
                 (cons #\\/
                       (explode-nonnegative-integer (denominator x)
                                                    print-base nil))))))
      ((complex-rationalp x)
       (list*
            #\\# #\\C #\\(
            (append (explode-atom (realpart x) print-base)
                    (cons #\\Space
                          (append (explode-atom (imagpart x) print-base)
                                  '(#\\)))))))
      ((characterp x) (list x))
      ((stringp x) (coerce x 'list))
      ((symbolp x)
       (coerce (symbol-name x) 'list))
      (t (coerce \"SOME BAD ATOM\" 'list))))")
 (EXPLODE-NONNEGATIVE-INTEGER
  (CHARACTERS NUMBERS ACL2-BUILT-INS)
  "The list of [characters] in the radix-r form of a number

    Examples:
    ACL2 !>(explode-nonnegative-integer 925 10 nil)
    (#9 #2 #5)
    ACL2 !>(explode-nonnegative-integer 325 16 nil)
    (#3 #9 #D)

  For a non-negative integer [47mn[0m, [47m(explode-nonnegative-integer n r nil)[0m
  is the list of [characters] in the radix-[47mr[0m (base-[47mr[0m) representation
  of [47mn[0m.

  The [guard] for [47mexplode-nonnegative-integer[0m requires the first
  argument to be a nonnegative integer and second argument to be a
  valid radix for ACL2 (2, 8, 10, or 16).

  See also [explode-atom], [str::numbers], and [printing-to-strings].

  [31;1mFunction: [0m<explode-nonnegative-integer>

    (defun explode-nonnegative-integer (n print-base ans)
      (declare (xargs :guard (and (integerp n)
                                  (>= n 0)
                                  (print-base-p print-base))))
      (cond ((or (zp n)
                 (not (print-base-p print-base)))
             (cond ((null ans) '(#\\0)) (t ans)))
            (t (explode-nonnegative-integer
                    (floor n print-base)
                    print-base
                    (cons (digit-to-char (mod n print-base))
                          ans)))))")
 (EXPT
  (NUMBERS ACL2-BUILT-INS)
  "Exponential function

  [47m(Expt r i)[0m is the result of raising the number [47mr[0m to the integer power
  [47mi[0m.

  The [guard] for [47m(expt r i)[0m is that [47mr[0m is a number and [47mi[0m is an integer,
  and furthermore, if [47mr[0m is [47m0[0m then [47mi[0m is nonnegative.  When the type
  requirements of the [guard] aren't met, [47m(expt r i)[0m first coerces [47mr[0m
  to a number and [47mi[0m to an integer.

  [47mExpt[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.  Note that [47mr[0m can be a complex number; this is
  consistent with Common lisp.

  [31;1mFunction: [0m<expt>

    (defun expt (r i)
      (declare (xargs :guard (and (acl2-numberp r)
                                  (integerp i)
                                  (not (and (eql r 0) (< i 0))))))
      (cond ((zip i) 1)
            ((= (fix r) 0) 0)
            ((> i 0) (* r (expt r (+ i -1))))
            (t (* (/ r) (expt r (+ i 1))))))")
 (EXTEND-PATHNAME
  (IO ACL2-BUILT-INS)
  "Extend a relative pathname to an absolute pathname

  [47mExtend-pathname[0m is a [47m:[0m[47m[program][0m 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.

    General Form:

    (extend-pathname dir filename state)

  where [47mdir[0m is either a string, representing an absolute pathname for a
  directory, or a keyword, representing a project directory (see
  [project-dir-alist]); filename is a string representing a relative
  or absolute pathname; and [47mstate[0m is the ACL2 [state].

  The following examples illustrate the behavior of [47mextend-pathname[0m.

    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\"

  Note that when the indicated file exists, [47mextend-pathname[0m resolves
  symbolic links by using [47m[canonical-pathname][0m.  If you don't want
  symbolic links to be resolved there are simpler alternatives; for
  example, see [oslib::catpath].")
 (EXTEND-PE-TABLE
  (HISTORY)
  "Replace [events] displayed by [history] commands

    Example Form:
    (extend-pe-table all-natp (all-p natp))

    General Form:
    (extend-pe-table event-name form)

  where [47mevent-name[0m is the name of an existing event and [47mform[0m is to be
  displayed by [history] commands in place of the actual event that
  introduced [47mevent-name[0m.

  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.

    (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)))))))

  So for example, after evaluating [47m(all-p natp)[0m, you see the following.

    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 !>

  So far so good.  But suppose that instead, you introduce this event
  within a call of [47m[progn][0m, as follows.

    (progn (defun f1 (x) x)
           (defun f2 (x) x)
           (all-p natp))

  Then when we ask to see the event introducing [47mall-natp[0m, we will not
  see any use of the macro [47mall-p[0m.

    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 !>

  Perhaps we therefore prefer that [history] commands display the event
  for [47mall-natp[0m as [47m(all-p natp)[0m, rather than as the generated [47m[defun][0m
  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!

  A solution is to associate the name [47mall-natp[0m with the form that
  introduced this name, as follows.

    (extend-pe-table all-natp (all-p natp))

  After evaluating this form, we see the desired call of [47mall-natp[0m.  In
  essence, [47m:[0m[47m[pe][0m and other [history] commands consider the defining
  event for [47mall-natp[0m to be [47m(all-p natp)[0m rather than the actual [47mdefun[0m
  form that introduced [47mall-natp[0m.

    ACL2 !>:pe all-natp
               2  (PROGN (DEFUN F1 # ...)
                         (DEFUN F2 # ...)
                         ...)

    >L             (ALL-P NATP)
    ACL2 !>

  As mentioned above, other [history] commands are sensitive to the
  result of evaluating a call of [47mextend-pe-table[0m.  For example:

    ACL2 !>:pcb all-natp
               2  (PROGN (DEFUN F1 # ...)
                         (DEFUN F2 # ...)
                         ...)
     L             (DEFUN F1 (X) ...)
     L             (DEFUN F2 (X) ...)
     L             (ALL-P NATP)
    ACL2 !>

  Note that [47mextend-pe-table[0m actually associates the indicated form with
  the most recent event introducing the given event name.  Consider
  the following example (output elided as shown).

    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 !>

  Note that by using [47m:[0m[47m[pe!][0m, in place of [47m:[0m[47m[pe][0m, you can avoid using the
  information that was provided by [47mextend-pe-table[0m.

    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 !>

  In the examples above we invoked [47mextend-pe-table[0m explicitly.  It
  might have been better, however, to ``bake in'' such calls by way
  of the macro itself, as follows.

    (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))))

  Then in a fresh session, after defining [47mall-p[0m as shown immediately
  above, we can obtain the following (edited) log.

    ACL2 !>(all-p natp)
    [[.. elided ..]]
    ACL2 !>:pe all-natp
               2:x(ALL-P NATP)
    ACL2 !>

  We close with two remarks.  First, note that the indicated event must
  have already been defined at the time [47mextend-pe-table[0m is invoked.
  Second --- in case an advanced user wishes to extend directly the
  underlying table, [47mpe-table[0m --- 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 [47mall-natp[0m as follows.

    (table pe-table 'all-natp nil)")
 (EXTEND-WORLD
  (WORLD)
  "Install an extension of a given ACL2 [world]

  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
  [47m'current-acl2-world[0m, which is maintained by the ACL2 system.  Also
  see [retract-world] for a similar utility that instead installs an
  initial segment of a named world.

    General Form:

    (extend-world name wrld)

  where [47mname[0m is a symbol intended to name the given ACL2 property list
  world, [47mworld[0m.  Consider the following example.

    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 !>

  The first top-level form sets the value of [47m[state][0m global [47mmy-w[0m to the
  world obtained by extending the empty world three times, as shown.
  The second top-level form returns the most recent [47m'my-key1[0m property
  of the symbol [47m'my-sym1[0m.  This second computation is efficient,
  because [47mextend-world[0m has [3minstalled[0m the value of [47mmy-w[0m as the world
  that is current for the name [47m'my-world[0m.  See [world].")
 (EXTENDED-METAFUNCTIONS
  (META)
  "State and context sensitive metafunctions

    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)))

  where the restrictions are as described in the [documentation] for
  [47m[meta][0m where [47mstate[0m is literally the symbol [47mSTATE[0m, and [47mx[0m, [47ma[0m, [47mmfc[0m,
  and [47mstate[0m are distinct variable symbols.  A [47m:meta[0m theorem of the
  above form installs [47mfn[0m as a metatheoretic simplifier with
  hypothesis function [47mhyp-fn[0m, exactly as for vanilla metafunctions.
  The only difference is that when the metafunctions are applied,
  some contextual information is passed in via the [47mmfc[0m argument and
  the ACL2 [47m[state][0m is made available.

  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, [47mfn[0m,
  and its associated hypothesis metafunction, [47mhyp-fn[0m, 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 [ACL2-help]
  list if you need more help.

  To test your extended metafunctions outside of proof attempts, see
  [trust-mfc].

  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 [world].
  These hypotheses provide an even more advanced form of metatheorem
  so we explain them elsewhere; see [meta-extract].

  The metafunction context, [47mmfc[0m, is a list containing many different
  data structures used by various internal ACL2 functions.
  Generally, your extended metafunction will take [47mmfc[0m as its second
  formal and pass it into the functions mentioned below.  However,
  advanced users who want other access to [47mmfc[0m may wish to see the
  documentation for [mfc].  The ACL2 [47mstate[0m is well-documented (see
  [state]).  Below we present expressions below that can be useful in
  defining extended metafunctions.  Some of these expressions involve
  keyword arguments, [47m:forcep[0m and [47m:ttree[0m, which are optional and in
  most cases are fine to omit, and which we explain after we present
  the useful expressions.

  [47m(mfc-clause mfc)[0m: returns the current goal, in clausal form.  A
  clause is a list of ACL2 terms, implicitly denoting the disjunction
  of the listed terms.  The [clause] returned by [47mmfc-clause[0m is the
  clausal form of the translation (see [trans]) of the goal or
  subgoal on which the rewriter is working.  When a metafunction
  calls [47mmfc-clause[0m, the term, [47mterm-mf[0m, being rewritten by the
  metafunction has resulted from an attempt to rewrite some term,
  [47mterm-cl[0m, in this clause.  These could be the same term, but that
  need not be the case: for example, [47mterm-mf[0m could be a term to which
  the rewriter has backchained while trying to rewrite [47mterm-cl[0m, or
  [47mterm-mf[0m could arise from the right-hand side of a rewrite rule
  applied to [47mterm-cl[0m.

  [47m(mfc-ancestors mfc)[0m: returns an alist whose keys are the negations of
  the backchaining hypotheses being pursued.  In particular, [47m(null
  (mfc-ancestors mfc))[0m 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 [47m(:binding-hyp hyp unify-subst)[0m indicates that [47mhyp[0m
  has been encountered as a hypothesis of the form [47m(equal var term)[0m
  or [47m(equiv var (double-rewrite-term))[0m, in each case binding variable
  [47mvar[0m to the result of rewriting [47mterm[0m under [47munify-subst[0m.

  [47m(mfc-rdepth mfc)[0m: returns the remaining stack depth for calls of the
  rewriter (by default, [47m*default-rewrite-stack-limit*[0m at the top
  level; see [rewrite-stack-limit]).  When this is 0, no further
  calls of the rewriter can be made without error.

  [47m(mfc-type-alist mfc)[0m: returns the type-alist governing the occurrence
  of the term, [47mx[0m, being rewritten by the metafunction.  A type-alist
  is an association list, each element of which is of the form [47m(term
  ts . ttree)[0m.  Such an element means that the term [47mterm[0m has the
  [type-set] [47mts[0m; see [type-alist].  The [47mttree[0m component is probably
  irrelevant here.  All the terms in the type-alist are in translated
  form (see [trans]).  The [47mts[0m are numbers denoting finite Boolean
  combinations of ACL2's primitive types (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 [47mmfc-clause[0m.

  [47m(mfc-unify-subst mfc)[0m: returns [47mnil[0m except when evaluating a [47m[syntaxp][0m
  or [47m[bind-free][0m hypothesis, in which case, returns the unifying
  substitution present at the start of that evaluation.

  [47m(mfc-world mfc)[0m: returns the ACL2 logical [47m[world][0m.

  [47m(mfc-ts term mfc state :forcep forcep :ttreep ttreep)[0m: returns the
  [47mtype-set[0m of [47mterm[0m in the current context; see [type-set].

  [47m(mfc-rw term obj equiv-info mfc state)[0m: returns the result of
  rewriting [47mterm[0m in the current context, [47mmfc[0m, with objective [47mobj[0m and
  the equivalence relation described by [47mequiv-info[0m.  [47mObj[0m should be [47mt[0m,
  [47mnil[0m, or [47m?[0m, and describes your objective: try to show that [47mterm[0m is
  true, false, or anything.  [47mEquiv-info[0m is either [47mnil[0m, [47mt[0m, a function
  symbol [47mfn[0m naming a known equivalence relation, or a list of
  congruence rules.  [47mNil[0m means return a term that is [47mequal[0m to [47mterm[0m.
  [47mT[0m means return a term that is propositionally equivalent (i.e., in
  the [47miff[0m sense) to [47mterm[0m, while [47mfn[0m means return a term [47mfn[0m-equivalent
  to [47mterm[0m.  The final case, which is intended only for advanced
  users, allows the specification of generated equivalence relations,
  as supplied to the [47mgeneqv[0m argument of [47mrewrite[0m.  Generally, if you
  wish to establish that [47mterm[0m is true in the current context, use the
  idiom

    (equal (mfc-rw term t t mfc state) *t*)

  The constant [47m*t*[0m is set to the internal form of the constant term [47mt[0m,
  i.e., [47m't[0m.

  [47m(mfc-rw+ term alist obj equiv-info mfc state)[0m: if [47malist[0m is [47mnil[0m then
  this is equivalent to [47m(mfc-rw term obj equiv-info mfc state)[0m.
  However, the former takes an argument, [47malist[0m, that binds variables
  to terms, and returns the result of rewriting [47mterm[0m under that
  [47malist[0m, where this rewriting is as described for [47mmfc-rw[0m above.  The
  function [47mmfc-rw+[0m can be more efficient than [47mmfc-rw[0m, 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.

    (implies (and ...
                  (syntaxp (... (mfc-rw `(bar ,x) ...) ...))
                  ...)
             (equal (... x ...) ...))

  Here, [47mx[0m is bound in the conclusion to the result of rewriting some
  term, say, [47mtm[0m.  Then the above call of [47mmfc-rw[0m will rewrite [47mtm[0m,
  which is probably unnecessary.  So a preferable form of the rule
  above may be as follows, so that [47mtm[0m is not further rewritten by
  [47mmfc-rw+[0m.

    (implies (and ...
                  (syntaxp (... (mfc-rw+ '(bar v) `((v . ,x)) ...) ...))
                  ...)
             (equal (... x ...) ...))

  However, you may find that the additional rewriting done by [47mmfc-rw[0m is
  useful in some cases.

  [47m(mfc-ap term mfc state)[0m: returns [47mt[0m or [47mnil[0m according to whether linear
  arithmetic can determine that [47mterm[0m is false.  To the cognoscenti:
  returns the contradiction flag produced by linearizing [47mterm[0m and
  adding it to the [47mlinear-pot-lst[0m.

  [47m(mfc-relieve-hyp hyp alist rune target bkptr mfc state)[0m: returns [47mt[0m or
  [47mnil[0m according to whether the indicated hypothesis term, [47mhyp[0m, can be
  relieved (proved) under the giving variable bindings, [47malist[0m.  Note
  that this function returns [47mnil[0m if [47mhyp[0m has free variables (see
  [free-variables]).  Here, [47mhyp[0m is the hypothesis of the indicated
  [47m[rune][0m at (one-based) position [47mbkptr[0m, and [47mtarget[0m is an instantiated
  term to which [47mrune[0m is being applied.  Note that no indication is
  returned for whether any assumptions have been generated by [47m[force][0m
  or [47m[case-split][0m.  (If you need such a feature, feel free to request
  it of the ACL2 implementors.)

  We explain the [47m:forcep[0m and [47m:ttreep[0m keyword arguments provided in some
  expressions, as promised above.  Their defaults are [47m:same[0m and [47mnil[0m,
  respectively.  A value of [47m:same[0m for [47m:forcep[0m means that forcing will
  be allowed if and only if it is allowed in the current rewriting
  environment; see [force].  A value of [47mt[0m or [47mnil[0m for [47m:forcep[0m
  overrides this default and allows or disallows forcing,
  respectively.  By default these functions return a single value,
  [47mval[0m, but if [47m:ttreep[0m is [47mt[0m then they return [47m(mv val ttree)[0m, where
  [47mttree[0m is the tag-tree (see [ttree]) returned by the indicated
  operation, with an input tag-tree of [47mnil[0m).

  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 [47mmfc-[0m 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 [47m:[0m[47m[meta][0m rules; see
  [meta-extract].  But we assume for the rest of the present
  [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 [3muse these functions for heuristic purposes only[0m.

  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, [47mhyp-fn[0m, to generate a sufficient
  hypothesis to justify the transformation.  The generated hypothesis
  might have already been ``proved'' internally by your use of [47mmfc-ts[0m
  or [47mmfc-rw[0m, but the system will have to prove it ``officially'' by
  relieving it.  We illustrate this below also.

  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.

    ; 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))))


Subtopics

  [Metafunction-context]
      A structure that holds data supporting extended meta reasoning

  [Trust-mfc]
      A macro that supports testing of extended metafunctions)")
 (EXTENDED-SYNTAXP (POINTERS)
                   "See [syntaxp].")
 (EXTERNAL-FORMAT (POINTERS)
                  "See [character-encoding].")
 (EXTRA-INFO
  (GUARD)
  "Sources of measure or guard proof obligations

  [47m(Extra-info x y)[0m always returns [47mt[0m by definition.  See [guard-debug]
  and see [measure-debug] for a discussion of this function, which is
  useful for debugging failures from attempts to prove measure
  conjectures or to verify [guard]s.")
 (F-BOUNDP-GLOBAL
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Check whether a global variable in [47m[state][0m has a value

    Examples:
    (f-boundp-global 'y state)

    General Form:
    (f-boundp-global s state)

  where [47ms[0m evaluates to a symbol.  Note that this executes more
  efficiently when [47ms[0m is a constant of the form [47m'sym[0m.

  This value returned is [47mt[0m or [47mnil[0m according to whether a value is
  assigned to the given symbol in the ACL2 [state].  Also see related
  utilities [47m[f-get-global][0m, [47m[f-put-global][0m, and [47m[makunbound-global][0m.")
 (F-GET-GLOBAL
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Get the value of a global variable in [47m[state][0m

    Examples:
    (+ (f-get-global 'y state) 1)
    (f-put-global 'a
                  (aset1 'ascii-map-array
                         (f-get-global 'a state)
                         66
                         'Upper-case-B)
                  state)

    General Form:
    (f-get-global 'symbol state)

  where [47msymbol[0m is any symbol to which you have [47m[assign][0med a global
  value.

  The macro [47m[@][0m is closely related to [47mf-get-global[0m: [47m(@ var)[0m
  macroexpands to [47m(f-get-global 'var state)[0m.

  The macro [47m[f-put-global][0m makes it convenient to set the value of a
  symbol.  The [47m:[0m[47m[ubt][0m operation has no effect on the [47mglobal-table[0m of
  [47m[state][0m.  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.")
 (F-PUT-GLOBAL
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Assign to a global variable in [47m[state][0m

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

    General Form:
    (f-put-global (quote symbol) term state)

  where [47msymbol[0m is any symbol (with certain enforced exclusions to avoid
  overwriting ACL2 system ``globals'') and [47mterm[0m is any ACL2 term that
  could be evaluated at the top-level.  [47mF-put-global[0m evaluates the
  term, stores the result as the value of the given symbol in the
  [47mglobal-table[0m of [47m[state][0m, and returns the new [47mstate[0m.  (Note: the
  actual implementation of the storage of this value is much more
  efficient than this discussion of the logic might suggest.)

  The macro [47m[assign][0m is closely related to [47mf-put-global[0m: [47m(assign var
  val)[0m macroexpands to [47m(f-put-global 'var val state)[0m.

  The macros [47m[@][0m and [47m[f-get-global][0m give convenient access to the value
  of such globals.  The [47m:[0m[47m[ubt][0m operation has no effect on the
  [47mglobal-table[0m of [47m[state][0m.  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.")
 (FAILED-FORCING
  (FORCE DEBUGGING)
  "How to deal with a proof [failure] in a forcing round

  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 [force]d goals are indeed theorems.  We discuss the
  possibilities below.

  If you believe the [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 [failure], see [gag-mode], and see [proof-tree].

  The rules designed for the goals of forcing rounds are often just
  what is needed to prove the [force]d hypothesis at the time it is
  [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.

  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., [47m\"[1]Subgoal *1/3''\"[0m.  See
  [goal-spec].

  If you solve a forcing problem by giving explicit [hints] for the
  goals of forcing rounds, you might consider whether you could avoid
  forcing the assumption in the first place by giving those [hints]
  in the appropriate places of the main proof.  This is one reason
  that we print out the origins of each [force]d assumption.  An
  argument against this style, however, is that an assumption might
  be [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.

  We now turn to the possibility that some goal in the forcing round is
  not a theorem.

  There are two possibilities to consider.  The first is that the
  original theorem has insufficient hypotheses to ensure that all the
  [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.

  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.

  Because ACL2 rewrites from the inside out, it is possible that it
  will [force] hypotheses while the context is insufficient to
  establish them.  Consider trying to prove [47m(p x (foo x))[0m.  We first
  rewrite the formula in an empty context, i.e., assuming nothing.
  Thus, we rewrite [47m(foo x)[0m in an empty context.  If rewriting [47m(foo x)[0m
  [force]s anything, that [force]d assumption will have to be proved
  in an empty context.  This will likely be impossible.

  On the other hand, suppose we did not attack [47m(foo x)[0m until after we
  had expanded [47mp[0m.  We might find that the value of its second
  argument, [47m(foo x)[0m, is relevant only in some cases and in those
  cases we might be able to establish the hypotheses [force]d by [47m(foo
  x)[0m.  Our premature forcing is thus seen to be a consequence of our
  ``over eager'' rewriting.

  Here, just for concreteness, is an example you can try.  In this
  example, [47m(foo x)[0m rewrites to [47mx[0m but has a [force]d hypothesis of
  [47m(rationalp x)[0m.  [47mP[0m does a case split on that very hypothesis and
  uses its second argument only when [47mx[0m is known to be rational.
  Thus, the hypothesis for the [47m(foo x)[0m rewrite is satisfied.  On the
  false branch of its case split, [47mp[0m simplifies to [47m(p1 x)[0m which can be
  proved under the assumption that [47mx[0m is not rational.

    (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))

  The attempt then to do [47m(thm (p x (foo x)))[0m [force]s the unprovable
  goal [47m(rationalp x)[0m.

  Since all ``formulas'' are presented to the theorem prover as single
  terms with no hypotheses (e.g., since [47m[implies][0m 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 [force]d.  See [simple].  This does not solve the problem, since
  it is possible to hide the propositional structure arbitrarily
  deeply.  For example, one could define [47mp[0m, above, recursively so
  that the test that [47mx[0m is rational and the subsequent first ``real''
  use of [47my[0m occurred arbitrarily deeply.

  Therefore, the problem remains: what do you do if an impossible goal
  is [force]d and yet you know that the original conjecture was
  adequately protected by hypotheses?

  One alternative is to disable forcing entirely.  See
  [disable-forcing].  Another is to [disable] the rule that caused
  the [force].

  A third alternative is to prove that the negation of the main goal
  implies the [force]d hypothesis.  For example,

    (defthm not-p-implies-rationalp
      (implies (not (p x (foo x))) (rationalp x))
      :rule-classes nil)

  Observe that we make no rules from this formula.  Instead, we merely
  [47m:use[0m it in the subgoal where we must establish [47m(rationalp x)[0m.

    (thm (p x (foo x))
         :hints ((\"Goal\" :use not-p-implies-rationalp)))

  When we said, above, that [47m(p x (foo x))[0m 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 [47mnil[0m and give up --- 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 [force]d hypothesis above.

  A fourth alternative is to weaken your desired theorem so as to make
  explicit the required hypotheses, e.g., to prove

    (defthm rationalp-implies-main
      (implies (rationalp x) (p x (foo x)))
      :rule-classes nil)

  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 [47m[implies][0m here provide the
  necessary case split.

    (thm (p x (foo x))
         :hints ((\"Goal\" :use rationalp-implies-main)))")
 (FAILURE
  (DEBUGGING)
  "How to deal with a failure to admit an event

  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 [47m[encapsulate][0m or [47m[progn][0m events, as well as
  [47m[certify-book][0m failures, see [redo-flat].

  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, [debugging].  Some
  frequently-used tools for proof debugging that are discussed in
  those subtopics include [accumulated-persistence], [break-rewrite],
  [with-brr-data], [cgen], and [proof-builder].  Also see [nil-goal]
  for ideas about how to proceed when the prover generates a goal of
  [47mNIL[0m.

  We turn now to the problem of dealing with proof failures.

  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 [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.

  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 [summary] provides a fine place to start.
  See [the-method] for a general discussion of how to prove theorems
  with ACL2, and see [introduction-to-the-theorem-prover] for a more
  detailed tutorial.  Also 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 ---
  although this should rarely be necessary --- then you can look at
  the full proof, perhaps with the aid of certain utilities: see
  [pso], [set-gag-mode], and [proof-tree].  System hackers may want
  to consider using the utility, [47m[checkpoint-list][0m.

  Again, see [the-method] for a general discussion of how to prove
  theorems with ACL2, and 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).

  If the failure occurred during a forcing round, see [failed-forcing].


Subtopics

  [Useless-runes-failures]
      Failures caused by [useless-runes]")
 (FAKE-RUNE (POINTERS) "See [rune].")
 (FANCY-STRING-READER
  (READER)
  "A friendly syntax for strings literals that have backslashes and
  quotes.

  Examples:

    ACL2 !> #{\"\"\"Hello, World!\"\"\"}
    \"Hello, World!\"

    ACL2 !> #{\"\"\"<img src=\"hello.png\"/>\"\"\"}
    \"<img src=\\\"hello.png\\\"/>\"

    ACL2 !> #{\"\"\"C:\\ACL2\\axioms.lisp\"\"\"}
    \"C:\\\\ACL2\\\\axioms.lisp\"

  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 [47mHello[0m is normally written as
  [47m\"Hello\"[0m.

  Usually this syntax is fine, but things can get tricky when you want
  to write a string whose contents include [47m\"[0m marks.  For example, if
  you wanted to write down a string whose contents were:

    <img src=\"hello.png\"/>

  then you would need to escape the quote marks within it using
  backslash characters, e.g., as follows:

    \"<img src=\\\"hello.png\\\"/>\"

  But using [47m\\[0m 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:

    C:\\ACL2\\axioms.lisp

  Then we would need to write something a string literal such as:

    \"C:\\\\ACL2\\\\axioms.lisp\"

  In certain cases, such as when writing long [documentation] strings,
  the extra escaping can be tedious and error-prone.

  To simplify this, ACL2 provides an alternate [47m#{\"\"\"...\"\"\"}[0m 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 [47m\"\"\"}[0m.

  In the rare case that you need to have the sequence [47m\"\"\"}[0m in your
  string, you can instead use [47m\"\"\"\\}[0m.  If you need to have the
  sequence [47m\"\"\"\\}[0m, you can use [47m\"\"\"\\\\}[0m.  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.")
 (FARGN (POINTERS)
        "See [system-utilities].")
 (FARGS (POINTERS)
        "See [system-utilities].")
 (FAST-ALIST (POINTERS)
             "See [fast-alists].")
 (FAST-ALIST-CLEAN
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(fast-alist-clean alist)[0m can be used to eliminate \"shadowed pairs\"
  from a fast alist.

  This [documentation] topic assumes familiarity with fast alists; see
  [fast-alists].  See [47m[fast-alist-clean!][0m, [47m[fast-alist-fork][0m, and
  [47m[fast-alist-fork!][0m for related utilities.

  Logically, [47m(fast-alist-clean alist)[0m is defined as follows:

  [31;1mFunction: [0m<fast-alist-clean>

    (defun fast-alist-clean (alist)
      (declare (xargs :guard t))
      (fast-alist-fork alist
                       (if (consp alist)
                           (cdr (last alist))
                         alist)))

  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 [fast-alist-fork] for details.  Moreover, if
  [47malist[0m is not a fast alist, then [47m(fast-alist-clean alist)[0m is
  executed in raw Lisp by calling [47mfast-alist-fork[0m as indicated above.

  However, if [47malist[0m is a fast alist, then a special definition under
  the hood provides a different handling of associated hash tables.
  After running [47m(fast-alist-clean alist)[0m to obtain a result,
  [47mcleaned-alist[0m, the hash table that had been associated with [47malist[0m
  will now be associated with [47mcleaned-alist[0m instead.  This saves the
  expense of creating a new hash table, but there is still the
  expense of copying the alist, as for [47m[fast-alist-fork][0m.  However,
  unlike [47mfast-alist-fork[0m, there is no need to free the input alist.

  Note that the final [47mcdr[0m is preserved, so that the name is preserved
  for use by [47m[fast-alist-summary][0m (also see [hons-acons]).")
 (FAST-ALIST-CLEAN!
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(fast-alist-clean! alist)[0m is an alternative to [47m[fast-alist-clean][0m
  that produces a [normed] result.

  Logically this function is just [47mfast-alist-clean[0m; we leave it enabled
  and would think it odd to ever prove a theorem about it.

  Under the hood, this is the same as [47mfast-alist-clean[0m except that it
  uses something like [47m[hons-acons!][0m instead of [47m[hons-acons][0m.  You
  generally [31;1mshould not use[0m this function unless you really know what
  you're doing and understand the drawbacks discussed in
  [47m[hons-acons!][0m.")
 (FAST-ALIST-DISCIPLINE (POINTERS)
                        "See [slow-alist-warning].")
 (FAST-ALIST-FORK
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(fast-alist-fork alist ans)[0m can be used to eliminate \"shadowed pairs\"
  from an alist or to copy [fast-alists].

  This [documentation] topic assumes familiarity with fast alists; see
  [fast-alists].  See [47m[fast-alist-fork!][0m, [47m[fast-alist-clean][0m, and
  [47m[fast-alist-clean!][0m for related utilities.

  Logically, [47m(fast-alist-fork alist ans)[0m is defined as follows:

  [31;1mFunction: [0m<fast-alist-fork>

    (defun fast-alist-fork (alist ans)
      (declare (xargs :guard t))
      (cond ((atom alist) ans)
            ((atom (car alist))
             (fast-alist-fork (cdr alist) ans))
            ((hons-assoc-equal (car (car alist)) ans)
             (fast-alist-fork (cdr alist) ans))
            (t (fast-alist-fork (cdr alist)
                                (cons (car alist) ans)))))

  The alist argument need not be a fast alist.

  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.

  Note that fast-alist-fork is potentially expensive, for the following
  two reasons.

    * 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.

    * 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.

  When ans is not an atom, good discipline requires that it is a fast
  alist.  In this case, [47mfast-alist-fork[0m 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 [47m[hons-assoc-equal][0m, you can think of
  the resulting alist as being basically similar to [47m(append ans
  alist)[0m, but in a different order.

  Note that when ans is not a fast alist (e.g., ans is an atom) then
  such stealing does not take place.

  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.

    (let ((alist (fast-alist-free-on-exit alist
                                          (fast-alist-fork alist nil))))
      ...)

  See [fast-alist-free-on-exit] and see [fast-alist-free].


Subtopics

  [Hons-shrink-alist]
      Deprecated feature")
 (FAST-ALIST-FORK!
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(fast-alist-fork! alist ans)[0m is an alternative to [47m[fast-alist-fork][0m
  that produces a [normed] result.

  Logically this function is just [47mfast-alist-fork[0m; we leave it enabled
  and would think it odd to ever prove a theorem about it.

  Under the hood, this is the same as [47mfast-alist-fork[0m except that it
  uses something like [47m[hons-acons!][0m instead of [47m[hons-acons][0m.  You
  generally [31;1mshould not use[0m this function unless you really know what
  you're doing and understand the drawbacks discussed in
  [47m[hons-acons!][0m.


Subtopics

  [Hons-shrink-alist!]
      Deprecated feature")
 (FAST-ALIST-FREE
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(fast-alist-free alist)[0m throws away the hash table associated with a
  fast alist.

  Logically, this function is the identity; we leave it enabled and
  would think it odd to ever prove a theorem about it.

  Under the hood, [47mfast-alist-free[0m removes the hash table associated
  with this alist, if one exists.  This effectively converts the
  alist into an ordinary alist.

  Also see [fast-alist-free-on-exit].

  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 [gc$].)  But for Lisp implementations
  other than CCL and SBCL this is not the case so, to avoid memory
  leaks, you should use [47mfast-alist-free[0m to free up associated hash
  tables that will no longer be used.  You may find
  [47m[fast-alist-summary][0m useful in tracking down alists that were not
  properly freed.

  It is safe to call [47mfast-alist-free[0m on any argument, including fast
  alists that have already been freed and objects which are not
  alists at all.

  [31;1mFunction: [0m<fast-alist-free>

    (defun fast-alist-free (alist)
      (declare (xargs :guard t))
      alist)


Subtopics

  [Flush-hons-get-hash-table-link]
      Deprecated feature")
 (FAST-ALIST-FREE-ON-EXIT
  (FAST-ALISTS ACL2-BUILT-INS)
  "Free a fast alist after the completion of some form.

  Logically, [47m(fast-alist-free-on-exit alist form)[0m is the identity and
  returns [47mform[0m.  Also see [fast-alist-free].

  Under the hood, this essentially expands to:

    (prog1 form
           (fast-alist-free alist))

  In other words, [47malist[0m 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.

  See also the macro [47mfast-alists-free-on-exit[0m defined in the community
  book [47m\"books/centaur/misc/hons-extra.lisp\"[0m, which can be used to
  free several alists.

  The community book [47m\"books/centaur/misc/hons-extra.lisp\"[0m extends the
  [b*] macro with the [47mfree-on-exit[0m pattern binder.  That is, after
  executing [47m(include-book \"centaur/misc/hons-extra.lisp\" :dir
  :system)[0m, the form

    (b* (...
         ((free-on-exit a b c))
         ...)
      ...)

  causes [47ma[0m, [47mb[0m, and [47mc[0m to be freed when the [47mb*[0m completes, but they remain
  fast alists until then.")
 (FAST-ALIST-LEN
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(fast-alist-len alist)[0m counts the number of unique keys in a fast
  alist.

  Logically this function counts how many elements would remain in the
  alist were we to shrink it with [47m[fast-alist-fork][0m.

  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 [47mhash-table-count[0m on the associated
  hash table, which is very fast and doesn't require us to actually
  shrink the alist.

  [31;1mFunction: [0m<fast-alist-len>

    (defun fast-alist-len (alist)
      (declare (xargs :guard t))
      (len (fast-alist-fork alist nil)))")
 (FAST-ALIST-SUMMARY
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(fast-alist-summary)[0m prints some basic statistics about any current
  fast alists.

  Logically, [47mfast-alist-summary[0m just returns nil; we leave it enabled
  and would think it odd to ever prove a theorem about it.

  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
  [47m[fast-alist-free][0m.

  [31;1mFunction: [0m<fast-alist-summary>

    (defun fast-alist-summary nil
      (declare (xargs :guard t))
      nil)")
 (FAST-ALISTS
  (ALISTS PROGRAMMING HONS-AND-MEMOIZATION)
  "Alists with hidden hash tables for faster execution

  The implementation of fast alists is, in many ways, similar to that
  of ACL2 arrays.  Logically, [47m[hons-acons][0m is just like [47macons[0m, and
  [47m[hons-get][0m is similar to [47m[assoc-equal][0m.  But under the hood, hash
  tables are associated with these alists, and, when a certain
  [31;1mdiscipline[0m is followed, these functions execute with hash table
  speeds.

  What is this discipline?  Each [47mhons-acons[0m 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.

  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 [47m[slow-alist-warning][0ms.

  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 [31;1mno syntactic enforcement[0m
  that insists you only use the most recent extension of an alist as
  there is for single threaded objects ([47m[stobj][0ms).  Also, even with
  perfectly proper code, discipline can sometimes be lost due to user
  interrupts and aborts.

  Performance Notes

  See [hons-acons] for how the final [47m[cdr][0m of a fast alist can be used
  as a size hint or as a name for reports printed by calling
  [47m[fast-alist-summary][0m.

  The keys of fast alists are always [normed].  Why?  In Common Lisp,
  equal-based hashing is relatively slow, so to allow the use of
  eql-based hash tables, [47m[hons-acons][0m and [47m[hons-get][0m always
  [47m[hons-copy][0m the keys involved.

  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.

  There is [31;1mno automatic mechanism[0m for reclaiming the hash tables that
  are associated with alists.  Because of this, to avoid memory
  leaks, you should call [47m[fast-alist-free][0m to remove the hash table
  associated with alists that will no longer be used.


Subtopics

  [Cons-subtrees]
      Build a fast alist whose keys are the subtrees of X

  [Fast-alist-clean]
      [47m(fast-alist-clean alist)[0m can be used to eliminate \"shadowed pairs\"
      from a fast alist.

  [Fast-alist-clean!]
      [47m(fast-alist-clean! alist)[0m is an alternative to [47m[fast-alist-clean][0m
      that produces a [normed] result.

  [Fast-alist-fork]
      [47m(fast-alist-fork alist ans)[0m can be used to eliminate \"shadowed
      pairs\" from an alist or to copy [fast-alists].

  [Fast-alist-fork!]
      [47m(fast-alist-fork! alist ans)[0m is an alternative to [47m[fast-alist-fork][0m
      that produces a [normed] result.

  [Fast-alist-free]
      [47m(fast-alist-free alist)[0m throws away the hash table associated with a
      fast alist.

  [Fast-alist-free-on-exit]
      Free a fast alist after the completion of some form.

  [Fast-alist-len]
      [47m(fast-alist-len alist)[0m counts the number of unique keys in a fast
      alist.

  [Fast-alist-summary]
      [47m(fast-alist-summary)[0m prints some basic statistics about any current
      fast alists.

  [Hons-acons]
      [47m(hons-acons key val alist)[0m is the main way to create or extend
      [fast-alists].

  [Hons-acons!]
      [47m(hons-acons! key val alist)[0m is an alternative to [47m[hons-acons][0m that
      produces [normed], fast alists.

  [Hons-assoc-equal]
      [47m(hons-assoc-equal key alist)[0m is [31;1mnot fast[0m; it serves as the logical
      definition for [47m[hons-get][0m.

  [Hons-get]
      [47m(hons-get key alist)[0m is the efficient lookup operation for
      [fast-alists].

  [Make-fast-alist]
      [47m(make-fast-alist alist)[0m creates a fast-alist from the input alist,
      returning [47malist[0m itself or, in some cases, a new object equal to
      it.

  [Slow-alist-warning]
      Warnings/errors issued when [47m[fast-alists][0m are used inefficiently

  [With-fast-alist]
      [47m(with-fast-alist name form)[0m causes [47mname[0m to be a fast alist for the
      execution of [47mform[0m.

  [With-stolen-alist]
      [47m(with-stolen-alist name form)[0m ensures that [47mname[0m is a fast alist at
      the start of the execution of [47mform[0m.  At the end of execution,
      it ensures that [47mname[0m is a fast alist if and only if it was
      originally.  That is, if [47mname[0m was not a fast alist originally,
      its hash table link is freed, and if it was a fast alist
      originally but its table was modified during the execution of
      [47mform[0m, that table is restored.  Note that any extended table
      created from the original fast alist during [47mform[0m must be
      manually freed.")
 (FAST-CERT
  (CERTIFY-BOOK INCLUDE-BOOK)
  "A mode for faster, but possibly unsound, book certification

  See [certify-book] and [include-book] for background on certifying
  and including [books].

  By default, [47m[certify-book][0m includes a ``Step 3'' that does a
  [local-incompatibility] check.  That check can be expensive for
  some ``industrial-size'' books if there are [local] events early in
  the book or in its [portcullis] commands.  Fast-cert mode provides
  a way to avoid the [local-incompatibility] check.  There are the
  following two drawbacks to using ACL2 with fast-cert mode enabled
  (as described further below).

    * It may be unsound!  See Section ``Unsoundness'' below.

    * 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 [47m[include-book][0m event is
      executed with fast-cert mode enabled.  See Section ``Effects of
      fast-cert mode...'' below.

    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)

  where if [47mexpr[0m evaluates to [47mval[0m, then: if [47mval[0m is [47mt[0m then fast-cert mode
  becomes (or remains) active; if [47mval[0m is [47mnil[0m, then fast-cert mode
  becomes (or remains) disabled; and otherwise [47mval[0m must be [47m:accept[0m.
  In the last case, ACL2 behaves as though fast-cert mode is disabled
  --- we also say ``not enabled'' for ``disabled'' --- 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
  ``Fast-cert modes'' below.

  Another way to enter fast-cert mode is to set environment variable
  [47mACL2_FAST_CERT[0m to a non-empty value before starting ACL2.  The
  case-insensitive value, [47m\"accept\"[0m, causes [47m(set-fast-cert :accept
  state)[0m to be evaluated at startup; otherwise, a non-empty value
  causes [47m(set-fast-cert t state)[0m to be evaluated at startup.

  We turn now to sections that include those promised above.


Fast-cert modes

  There are the following fast-cert modes.

    * [31;1mActive[0m: entered with [47m(set-fast-cert t state)[0m.  When ACL2 is in this
      mode, the [local-incompatibility] check is skipped when
      certifying a book, and the book's [certificate] marks it as a
      ``fast-cert book''.

    * [31;1mDisabled[0m: entered with [47m(set-fast-cert nil state)[0m, though this is the
      default mode.  In this mode the usual [local-incompatibility]
      checks are performed during book certification, and every
      fast-cert book (as defined just above) is considered to be
      uncertified.

    * [31;1mAccept[0m: entered with [47m(set-fast-cert :accept state)[0m.  When ACL2 is in
      this mode, [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.

  Fast-cert mode is considered to be ``enabled'' exactly when it is not
  disabled, that is, when fast-cert mode is active or accept.

  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.

  It is always legal to change fast-cert mode from disabled to enabled
  (using [47mset-fast-cert[0m).  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.


Potential for unsoundness

  Consider the proof of [47mnil[0m constructed by the following two books.

    ;;; 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)))

  Now execute the following commands to prove [47mnil[0m!

    (set-fast-cert t state)
    (certify-book \"fast-cert-unsound-sub\")
    :u
    (certify-book \"fast-cert-unsound\")

  To see what went wrong, consider what happens if we try this without
  first evaluating [47m(set-fast-cert t state)[0m.  In that case, we can see
  that an attempt to certify [47m\"fast-cert-unsound-sub\"[0m fails the
  [local-incompatibility] check.

    * 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).

  That is, the attempt in Step 3 to include
  [47m\"fast-cert-unsound-sub.lisp\"[0m fails the local-incompatibility check
  because the definition of [47mf[0m is [local], hence skipped, so the
  definition of [47mg[0m is illegal.  Without the use of fast-cert mode, the
  local-incompatibility check would catch this problem.

  (Technical note: if the book is certified while fast-cert mode is
  active, then when we subsequently include [47m\"fast-cert-unsound-sub\"[0m
  when fast-cert mode is enabled, there is --- perhaps surprisingly
  --- no error.  That is because the translation (see [term]) of the
  definition of [47mg[0m is cached in the book's [certificate].)

  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 [47mnil[0m 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).

  Unsoundness when fast-cert mode is enabled is probably rare in
  practice.  But because unsoundness is possible with fast-cert mode
  enabled, a ``[47mTTAG NOTE[0m'' message is printed when fast-cert mode is
  enabled, for example as follows when fast-cert mode transitions
  from disabled to active.

    ACL2 !>(set-fast-cert t state)

    TTAG NOTE: Fast-cert mode is active (see :DOC fast-cert).
     T
    ACL2 !>

  The message above may seem a bit misleading, since there is no actual
  trust tag (ttag) involved.  The ``[47mTTAG NOTE[0m'' message is simply
  ACL2's way of conveying that there is a trust issue --- typically
  with the use of [47m[defttag][0m but also when entering fast-cert mode.

  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
  [local-incompatibility] check during certification when fast-cert
  mode is active.

    * Hidden [47m[defpkg][0m events are not recorded in a book's [certificate]
      when fast-cert mode is active.  See [hidden-death-package].

    * Information about sub-books that is normally recorded in a
      [certificate], including the [book-hash] values in the
      [portcullis] and the [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.

  Here are some necessary checks that may be omitted when the
  local-incompatibility check is skipped.

    * A non-local [congruence] rule needs its alleged equivalence relation
      to be an equivalence relation non-locally.  Generally this
      means that the supporting [47m[defequiv][0m event must be non-local.

    * A non-local rule of class [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m needs its
      evaluators to be evaluators non-locally.

    * A [47m[defattach][0m event imposes requirements on function symbols to be
      [guard]-verified.  So if a [47mdefattach[0m event is non-local, each
      necessary guard verification status must hold non-locally.

  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!


Interactions involving fast-cert mode

    * When a book is successfully certified with fast-cert mode active, its
      [certificate] records this fact.  Let's call such a certificate
      (or book) a ``fast-cert certificate'' (or ``fast-cert book'');
      otherwise it is a ``normal`` certificate (or ``normal book'').

    * 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.

    * When [47minclude-book[0m 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.

    * When [47minclude-book[0m 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 [47minclude-book[0m
      time.

    * When [provisional-certification] is used during [47mcertify-book[0m 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.

    * Normally [47mcertify-book[0m warns about functions that have not had their
      [guard]s verified.  This message is suppressed when fast-cert
      mode is active, because local [47minclude-book[0m forms in the
      certification world can make that message very long.

    * 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.

    * It is illegal to call [47mset-fast-cert[0m during [47mmake-event[0m expansion (see
      [make-event]).  There is also an explicit check to prohibit
      calls of [47mset-fast-cert[0m during [47mcertify-book[0m, though that is
      probably unnecessary because of the [47mmake-event[0m restriction
      unless that restriction is subverted using a trust tag.

  See [fast-cert-anomalies] for some possibly surprising (and more
  obscure) consequences of using fast-cert mode.


Fast-cert mode and [47m[save-exec][0m

  The motivation for adding fast-cert mode was to provide faster
  certification based on executables created with [47m[save-exec][0m.  We
  illustrate with an example, which starts by [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) [47minclude-book[0m forms below might not be necessary for all
  uses of the executable.

    (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\")

  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).

    (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))))

  We now invoke the resulting executable, [47m./sv-top[0m.

    ; Start ./sv-top, then:
    (set-fast-cert t state)
    (certify-book \"name\" ? t :ttags :all)

  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 --- -- especially when the book
  contains time-consuming events, in particular [47minclude-book[0m events.


Subtopics

  [Fast-cert-anomalies]
      Potentially surprising consequences of using [fast-cert] mode")
 (FAST-CERT-ANOMALIES
  (FAST-CERT)
  "Potentially surprising consequences of using [fast-cert] mode

  See [fast-cert] for relevant background.  This topic discusses some
  surprises one may encounter when using fast-cert mode.

  When fast-cert mode was developed in February 2023, a call of
  ``[47mmake[0m'' was made with ``[47mACL2_FAST_CERT=t[0m'' and target
  ``[47mregression-everything[0m'', to certify the [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.


Example 1

  Community book [47msystem/tests/early-load-of-compiled/ttag.lisp[0m 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 [47m(set-fast-cert nil state)[0m is in file [47mttag.acl2[0m in the same
  directory.  Key events in the book are as follows, in this order;
  the first forces a [local-incompatibility] check, and you can see
  comments in [47mttag.lisp[0m for why that is crucial.

    (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)))


Example 2

  The second example is rather subtle.  Our starting point is the
  following, from community book
  [47mrtl/rel9/support/lib2.delta1/add-new-proofs.lisp[0m.

    ; 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))

  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
  [47mlamz[0m has been introduced.  We assume here that the sub-books that
  are included were certified with fast-cert mode active.

    (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)

  We see that the built-in [type-prescription] rule for [47mlamz[0m says only
  that [47mlamz[0m returns a rational number, not necessarily a non-negative
  integer.

    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))

    ...

  If we do the same experiment when sub-books were certified with
  fast-cert mode disabled, the [47m:[0m[47m[pr][0m output will instead show a
  built-in [type-prescription] rule for [47mlamz[0m saying that [47mlamz[0m returns
  a non-negative integer.  This discrepancy in that built-in rule
  explains why the additional lemma above, [47mnatp-lamz[0m, was necessary
  when certifying the [community-books] with fast-cert mode active.

  So now let us investigate why certifying books with fast-cert mode
  active weakens the built-in type-prescription rule for [47mlamz[0m.  After
  running the [47mset-fast-cert[0m and [47m[ld][0m commands displayed above, we see
  where [47mlamz[0m is defined.

    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 !>

  But we need to work harder to find the real source of the definition
  of [47mlamz[0m.  In [47mrtl/rel9/support/lib2/add.lisp[0m we see that the
  definition of [47mlamz[0m is preceded by [47m(set-enforce-redundancy t)[0m as
  well as [47m(local (include-book \"base\"))[0m.  When we invoke [47m:ubt 1[0m and
  then [47m(include-book \"base\")[0m, we can evaluate [47m:pe lamz[0m to see that
  [47mlamz[0m is defined in [47mrtl/rel9/support/lib1/add.lisp[0m, which contains
  [47m(set-enforce-redundancy t)[0m and the local event, [47m(local
  (include-book \"../support/top\"))[0m.  So we include [3mthat[0m book after
  invoking [47m:ubt 1[0m, then (again) invoke [47m:pe lamz[0m, and finally find the
  true source of the definition of [47mlamz[0m:
  [47mrtl/rel9/support/support/lextra.lisp[0m.

  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 [47m:ld-skip-proofsp 'include-book[0m to simulate what happens when
  including the book.

    ; 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)))

  Then [47m:pr lamz[0m shows a [47m:type-prescription[0m rule for [47mlamz[0m that this
  function returns a non-negative integer.  That is explained in part
  by the following output, which mentions a rule stating that [47mlnot[0m
  returns a non-negative integer, which was used to compute the
  built-in type for [47mlamz[0m that it returns a non-negative integer.

    We used the :type-prescription rule LNOT-NONNEGATIVE-INTEGER-TYPE.

  Now repeat the same experiment but where we assume that fast-cert
  mode has been active for all book certification and we start with
  [47m(set-fast-cert t state)[0m.  This time there is no such output about
  [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m.  Aha!  The culprit is the following
  form near the top of [47m\"rtl/rel9/support/support/lextra.lisp\"[0m.

    (local (in-theory (current-theory 'lextra0-start)))

  That form disables the [47m:type-prescription[0m rule
  [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m, which is necessary for computing a
  non-negative integer (i.e., [47mnatp[0m) type for the built-in
  [47m:type-prescription[0m rule for [47mlamz[0m.  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 [47minclude-book[0m phase of certification, the rule
  [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m is available for computing the
  built-in type-prescription for [47mlamz[0m, which is stored in the book's
  [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 [47mLNOT-NONNEGATIVE-INTEGER-TYPE[0m
  is disabled.

  Indeed, if you read the certificate file for the [47mlextra.lisp[0m book
  above, you'll see that the [47m:TYPE-PRESCRIPTION[0m entry for [47mlamz[0m
  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.

    (read-file (concatenate 'string
                            (system-books-dir state)
                            \"rtl/rel9/support/support/lextra.cert\")
               state)")
 (FC-REPORT
  (FORWARD-CHAINING-REPORTS)
  "To report on the forward chaining activity in the most recent proof

    Example: (fc-report 15)

    General Form: (fc-report k)

  where [47mk[0m is the number of some forward chaining report printed in the
  most recent event.

  See [forward-chaining-reports] for details.")
 (FCONS-TERM (POINTERS)
             "See [system-utilities].")
 (FCONS-TERM* (POINTERS)
              "See [system-utilities].")
 (FDEFUN-MODE (POINTERS)
              "See [system-utilities].")
 (FFN-SYMB (POINTERS)
           "See [system-utilities].")
 (FFN-SYMB-P (POINTERS)
             "See [system-utilities].")
 (FFNNAMEP (POINTERS)
           "See [system-utilities].")
 (FFNNAMEP-LST (POINTERS)
               "See [system-utilities].")
 (FIFTH
  (NTH ACL2-BUILT-INS)
  "Fifth member of the list

  See any Common Lisp documentation for details.")
 (FILE-LENGTH$
  (IO)
  "The size of a file in bytes

  This analogue of the Common Lisp function, [47mfile-length[0m, uses that
  function under the hood to compute efficiently the number of bytes
  [47mB[0m in the specified file if that number can be determined, returning
  [47m(mv B state)[0m; otherwise it returns [47m(mv nil state)[0m.  The [47m[guard][0m of
  [47mfile-length$[0m requires that the first argument is a string; the
  second argument is the ACL2 [47m[state][0m.  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.

  [31;1mFunction: [0m<file-length$>

    (defun file-length$ (file state)
      (declare (xargs :guard (stringp file)
                      :stobjs state))
      (declare (ignore file))
      (mv-let (erp val state)
              (read-acl2-oracle state)
        (mv (and (null erp) (natp val) val)
            state)))")
 (FILE-READING-EXAMPLE
  (TUTORIAL5-MISCELLANEOUS-EXAMPLES)
  "Example of reading files in ACL2

  This example illustrates the use of ACL2's [io] primitives to read
  the forms in a file.  See [io].

  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 [47mnil[0m, and updating it
  ``appropriately'' upon encountering each successive s-expression in
  the file.  That is, suppose that you have written a function
  [47mupdate-list[0m such that [47m(update-list obj current-list)[0m returns the
  list obtained by ``updating'' [47mcurrent-list[0m with the next object,
  [47mobj[0m, 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 [state] and hence must return [state].
  Thus it actually returns two values: the final list and the new
  [state].

    (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)))))

  The function [47mprocess-file1[0m referred to above takes the currently
  constructed list (initially, [47mnil[0m), together with a channel to the
  file being read and the [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.

    (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)))))

  As an exercise, you might want to add [guard]s to the functions above
  and verify the guards (see [verify-guards]).  See [args] or make a
  call of the form [47m(guard 'your-function nil (w state))[0m to see the
  guard of an existing function.")
 (FILE-WRITE-DATE$
  (IO)
  "The write-date of a file as a natural number

  This analogue of the Common Lisp function, [47mfile-write-date[0m, uses that
  function under the hood to compute the write date [47mD[0m as a natural
  number if the write date can be determined, returning [47m(mv D state)[0m;
  otherwise it returns [47m(mv nil state)[0m.  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 [47m[guard][0m of [47mfile-write-date$[0m requires that the
  first argument is a string; the second argument is the ACL2
  [47m[state][0m.  The logical definition does not actually look at the file
  and hence is not useful for reasoning about the write date.

  This utility provides a reasonable way to determine whether a file
  exists, like Common Lisp's [47mprobe-file[0m, according to whether [47mD[0m is
  non-[47mnil[0m in when [47m(mv D state)[0m is returned.

  [31;1mFunction: [0m<file-write-date$>

    (defun file-write-date$ (file state)
      (declare (xargs :guard (stringp file)
                      :stobjs state)
               (ignorable file))
      (mv-let (erp val state)
              (read-acl2-oracle state)
        (mv (and (null erp) (posp val) val)
            state)))")
 (FINALIZE-EVENT-USER
  (OUTPUT-CONTROLS)
  "User-supplied code to complete [events], e.g., with extra [summary]
  output

  This utility is intended for system hackers, not standard ACL2 users.

  ACL2 prints summaries at the conclusions of processing [events]
  (unless summaries are inhibited; see [set-inhibit-output-lst] and
  also see [set-inhibited-summary-types]).  You may arrange for
  processing to take place just after the [summary], by defining a
  function with argument list [47m(ctx body state)[0m that returns one
  value, namely [47mstate[0m.  We describe [47mctx[0m and [47mbody[0m at the end below,
  but you may simply prefer to ignore these arguments.)  Your
  function should normally be a [guard]-verified [47m:[0m[47m[logic][0m mode
  function with no guard other than that provided by the input
  requirement on [47m[state][0m, that is, [47m(state-p state)[0m; but later below
  we discuss how to avoid this requirement.  You then attach (see
  [defattach]) your function to the function [47mfinalize-event-user[0m.
  The following example illustrates how this all works.

    (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)

  After admission of the two events above, an event [summary] will
  conclude with extra printout, for example:

    Note: Abbrev-evisc-tuple has its default value.

  If the attachment function (above, [47mfinalize-event-user-test[0m) does not
  meet all the requirements stated above, then you can use the
  [47m:skip-checks[0m argument of [47m[defattach][0m to get around the requirement,
  as illustrated by the following example.

    (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)

  So for example:

    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 !>

  Note that (as of this writing) the macro [47m[observation][0m expands to a
  call of a [47m:[0m[47m[program][0m-mode function.  Thus, the trick shown above
  involving [47m:skip-checks[0m allows the use of [47m:program[0m-mode functions;
  for example, you can print with [47m[fmt][0m.

  See community book [47mbooks/misc/defattach-bang.lisp[0m for a variant of
  [47m[defattach][0m that uses [47m[ec-call][0m to avoid issues of [guard]
  verification.

  Also see [initialize-event-user], which discusses the handling of
  [state] globals by that utility as well as by [47mfinalize-event-user[0m.

  Finally, as promised above, we briefly describe the arguments [47mctx[0m and
  [47mbody[0m.  These are the arguments passed to the call of macro
  [47mwith-ctx-summarized[0m under which [47mfinalize-event-user[0m (or
  [47minitialize-event-user[0m) was called.  Thus, they are unevaluated
  expressions.  For example, system function [47mdefthm-fn1[0m has a body of
  the following form.

    (with-ctx-summarized
     (cons 'defthm name)
     (let ((wrld (w state))
           (ens (ens state))
           .....

  Thus, when [47minitialize-event-user[0m and [47mfinalize-event-user[0m are called
  on behalf of [47m[defthm][0m, [47mctx[0m is the s-expression

    (cons 'defthm name)

  while [47mbody[0m is the following s-expression (with most code elided).

    (let ((wrld (w state))
          (ens (ens state))
          .....

  You might find it helpful to use [47m[trace$][0m to get a sense of [47mctx[0m and
  [47mbody[0m, for example, [47m(trace$ finalize-event-user)[0m.")
 (FIND-RULES-OF-RUNE
  (RUNE)
  "Find the rules named rune

    General Form:
    (find-rules-of-rune rune wrld)

  This function finds all the rules in [47mwrld[0m with [47m:[0m[47m[rune][0m rune.  It
  returns a list of rules in their internal form (generally as
  described by the corresponding [47mdefrec[0m).  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 [47m:[0m[47m[rewrite][0m runes only name rewrite-rules).

  At the moment this function returns [47mnil[0m if the rune in question is a
  [47m:[0m[47m[refinement][0m rune, because there is no object representing
  [47m:[0m[47m[refinement][0m rules.  ([47m:[0m[47m[refinement][0m rules cause changes in the
  [47m'coarsenings[0m properties.)  In addition, if the rune is an
  [47m:[0m[47m[equivalence][0m rune, then congruence rules with that rune will be
  returned --- because [47m:[0m[47m[equivalence][0m lemmas generate some congruence
  rules --- 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
  [47m'coarsening[0m of [47m[equal][0m.)")
 (FINDING-DOCUMENTATION
  (DOCUMENTATION)
  "Searching the documentation

  The [47m:[0m[47m[doc][0m command will display, at the terminal, [documentation]
  topics defined in ACL2 or in [books] that have already been
  included.  But how can you find documentation for books that are
  not included in the current ACL2 session?

  The [xdoc] {ACL2+Books Manual |
  http://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html}
  includes documentation for both the ACL2 system and the
  [community-books].  For more information on this manual and how to
  view it, see [documentation].")
 (FIRST
  (NTH ACL2-BUILT-INS)
  "First member of the list

  See any Common Lisp documentation for details.")
 (FIRST-KEYWORD (POINTERS)
                "See [system-utilities].")
 (FIRST-N-AC (POINTERS) "See [take].")
 (FIX
  (NUMBERS ACL2-BUILT-INS)
  "Coerce to a number

  [47mFix[0m simply returns any numeric argument unchanged, returning [47m0[0m on a
  non-numeric argument.  Also see [nfix], see [ifix], and see [rfix]
  for analogous functions that coerce to a natural number, an
  integer, and a rational number, respectively.  See [the-number] for
  a variant of [47mfix[0m whose guard specifies a numeric argument.

  [47mFix[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<fix>

    (defun fix (x)
      (declare (xargs :guard t))
      (if (acl2-numberp x) x 0))")
 (FIX-PKG (POINTERS)
          "See [system-utilities].")
 (FIX-TRUE-LIST
  (LISTS ACL2-BUILT-INS)
  "Coerce to a true list

  [47mFix-true-list[0m is a macro that expands to a call of [47m[true-list-fix][0m
  with the same argument.

  [31;1mMacro: [0m<fix-true-list>

    (defmacro fix-true-list (x)
      (cons 'true-list-fix (cons x 'nil)))")
 (FLAMBDA-APPLICATIONP (POINTERS)
                       "See [system-utilities].")
 (FLAMBDAP (POINTERS)
           "See [system-utilities].")
 (FLATTEN-ANDS-IN-LIT (POINTERS)
                      "See [system-utilities].")
 (FLAWED_INDUCTION_CANDIDATES_IN_APP_EXAMPLE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Flawed Induction Candidates in App Example

  Induction on [31;1ma[0m is unflawed: every occurrence of [31;1ma[0m in the conjecture

    (equal (app (app [31;1ma[0m b) c)
           (app [31;1ma[0m (app b c)))

  is in a position being recursively decomposed!

  Now look at the occurrences of [47mb[0m.  The first (shown in [31;1mbold[0m below) is
  in a position that is held constant in the recursion of [47m(app a b)[0m.
  It would be ``bad'' to induct on [47mb[0m here.

    (equal (app (app a [31;1mb[0m) c)
           (app a (app b c)))")
 (FLET
  (BASICS ACL2-BUILT-INS)
  "Local binding of function symbols

  See [macrolet] for an analogous utility for defining macros locally.

    Example Form:
    ; The following evaluates to (mv 7 10):
    (flet ((f (x)
              (+ x 3))
           (g (x)
              (declare (type integer x))
              (* x 2)))
      (mv (f 4) (g 5)))

    General Forms:
    (flet (def1 ... defk) body)
    (flet (def1 ... defk) declare-form1 .. declare-formk body)

  where [47mbody[0m is a term, and each [47mdefi[0m is a definition as in [47m[defun][0m but
  with the leading [47mdefun[0m symbol omitted.  See [defun], but see
  [declare] for the declarations permitted directly under the [47mdefi[0m.
  On the other hand, regarding the [47mdeclare-formi[0m (if any are
  supplied): each must be of the form [47m(declare decl1 ... decln)[0m,
  where each [47mdecli[0m is of the form [47m(inline g1 ... gm)[0m or [47m(notinline g1
  ... gm)[0m, and each [47mgi[0m is defined by some [47mdefi[0m.

  The innermost [47mflet[0m or [47m[macrolet][0m binding of a symbol, [47mf[0m, above a call
  of [47mf[0m, is the one that provides the definition of [47mf[0m for that call.
  Note that neither [47mflet[0m nor [47mmacrolet[0m provide recursion: that is, the
  definition of [47mf[0m in an [47mflet[0m or [47mmacrolet[0m binding of [47mf[0m is ignored in
  the body of that binding.  Consider the following example.

    ; Give a global definition of f:
    (defun f (x) (+ x 3))
    ; Evaluate an expression using a local binding of f:
    (flet ((f (x) (cons x (f (1+ x)))))
      (f 4))

  In the above term [47m(cons x (f (1+ x)))[0m, [47mf[0m refers to the global
  definition of [47mf[0m above the [47mflet[0m expression.  However, [47m(f 4)[0m refers
  to the [47mflet[0m-binding of [47mf[0m, [47m(f (x) (cons x (f x)))[0m.  The result of
  the [47mflet[0m expression is thus obtained by evaluating [47m(f 4)[0m where [47m(f
  4)[0m is [47m(cons 4 (f (1+ 4)))[0m, where the latter call of [47mf[0m refers to the
  global definition; thus we have [47m(cons 4 (f 5))[0m, which evaluates to
  [47m(4 . 8)[0m.

  Although [47mflet[0m behaves in ACL2 essentially as it does in Common Lisp,
  ACL2 imposes the following restrictions and qualifications.

    * Every [47m[declare][0m form for a local definition ([47mdef1[0m through [47mdefk[0m,
      above) must be an [47mignore[0m, [47mignorable[0m, or [47mtype[0m expression.  Such
      [47mtype[0m declarations affect evaluation and [guard]-checking in a
      way that is completely analogous to such declarations that
      occur between the formal parameters and the body in a [47m[defun][0m
      form.

    * Each [47mdefi[0m must bind a different function symbol.

    * Each [47mdefi[0m 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.

    * Every variable occurring in the body of a [47mdefi[0m must be a formal
      parameter of that [47mdefi[0m.  (This restriction is not enforced in
      Common Lisp.)

    * If the [47mflet[0m-binding [47mdefi[0m is in the body of a function [47mf[0m, then the
      [stobj] inputs for [47mdefi[0m are implicitly those of its inputs that
      are declared [stobj] inputs of [47mf[0m.

    * When an expression [47m(flet (... defi ...) ...)[0m occurs in the body of a
      [47mDO[0m [47m[loop$][0m expression, nevertheless constructs such as [47mPROGN[0m
      and [47mSETQ[0m that ACL2 permits in [47mDO[0m [47mloop$[0m bodies are not permitted
      in [47mdefi[0m (unless they occur within the scope of a [47mDO[0m [47mloop$[0m
      expression in that body).  (This restriction is only for ACL2;
      for example, it may be reasonable to call [47mRETURN[0m in such
      situations but ACL2 does not allow that.)

  [47mFlet[0m bindings are evaluated in parallel.  Consider the following
  example.

    (defun f (x) x)
    (flet ((f (x) (cons x x))
           (g (x) (f x)))
      (g 3))

  The binding of [47mg[0m refers to the global value of [47mf[0m, not the
  [47mflet[0m-binding of [47mf[0m.  Thus, the [47mflet[0m expression evaluates to 3.
  Compare the [47mflet[0m expression above to the following one, which
  instead evaluates to [47m(3 . 3)[0m.

    (defun f (x) x)
    (flet ((f (x) (cons x x)))
      (flet ((g (x) (f x)))
        (g 3)))

  Under the hood, ACL2 translates [47mflet[0m bindings to [47m[lambda][0m expressions
  (see [term]), throwing away the [47minline[0m and [47mnotinline[0m declarations
  (if any).  The following example illustrates this point.

    ACL2 !>:trans (flet ((f (x) (cons x x))
                         (g (x y) (+ x y)))
                    (declare (inline f))
                    (f (g 3 4)))

    ((LAMBDA (X) (CONS X X))
     ((LAMBDA (X Y) (BINARY-+ X Y)) '3 '4))

    => *

    ACL2 !>

  [47mFlet[0m is part of Common Lisp.  See any Common Lisp documentation for
  more information.  We conclude by pointing out an important aspect
  of [47mflet[0m shared by ACL2 and Common Lisp: The binding is lexical, not
  dynamic.  That is, the [47mflet[0m binding of a function symbol only
  applies to calls of that function symbol in the body of the [47mflet[0m,
  not other calls made in the course of evaluation.  Consider the
  following example.  Suppose we define:

    (defun f (x) x)
    (defun g (x) (f x))
    (defun h (x)
      (flet ((f (x) (cons x x)))
        (g x)))

  Then evaluation of [47m(h 3)[0m results in [47m3[0m, not in the [47mcons[0m pair [47m(3 . 3)[0m,
  because the [47mflet[0m binding of [47mf[0m only applies to calls of [47mf[0m that
  appear in the body of that [47mflet[0m.  In this case, only [47mg[0m is called in
  the body of that [47mflet[0m.")
 (FLOATING-POINT (POINTERS) "See [df].")
 (FLOOR
  (NUMBERS ACL2-BUILT-INS)
  "Division returning an integer by truncating toward negative infinity

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

  [47m(Floor i j)[0m returns the result of taking the quotient of [47mi[0m and [47mj[0m and
  returning the greatest integer not exceeding that quotient.  For
  example, the quotient of [47m-14[0m by [47m3[0m is [47m-4 2/3[0m, and the largest
  integer not exceeding that rational number is [47m-5[0m.

  The [guard] for [47m(floor i j)[0m requires that [47mi[0m and [47mj[0m are rational
  ([real], in ACL2(r)) numbers and [47mj[0m is non-zero.

  [47mFloor[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.  However, note that unlike Common Lisp, the
  ACL2 [47mfloor[0m function returns only a single value, that is, the
  quotient of the division, while the remainder is returned by [47m[mod][0m.

  [31;1mFunction: [0m<floor>

    (defun floor (i j)
      (declare (xargs :guard (and (real/rationalp i)
                                  (real/rationalp j)
                                  (not (eql j 0)))))
      (let* ((q (* i (/ j)))
             (n (numerator q))
             (d (denominator q)))
        (cond ((= d 1) n)
              ((>= n 0)
               (nonnegative-integer-quotient n d))
              (t (+ (- (nonnegative-integer-quotient (- n) d))
                    -1)))))")
 (FLUSH-COMPRESS
  (ARRAYS ACL2-BUILT-INS)
  "Flush the under-the-hood array for the given name

    Example Form:
    (flush-compress 'my-array)

    General Form:
    (flush-compress name)

  where [47mname[0m is a symbol.

  Recall that [47m(compress1 nm alist)[0m associates an under-the-hood raw
  Lisp one-dimensional array of name [47mnm[0m with the given association
  list, [47malist[0m, while [47m(compress2 nm alist)[0m is the analogous function
  for two-dimensional arrays; see [compress1] and see [compress2].
  The only purpose of [47mflush-compress[0m, which always returns [47mnil[0m, is to
  remove the association of any under-the-hood array with the given
  name, thus eliminating slow array accesses (see
  [slow-array-warning]).  It is not necessary if the return values of
  [47m[compress1][0m and [47m[compress2][0m are always used as the ``current'' copy
  of the named array, and thus [47mflush-compress[0m should rarely, if ever,
  be needed in user applications.

  Nevertheless, we provide the following contrived example to show how
  [47mflush-compress[0m can be used to good effect.  Comments have been
  added to this log to provide explanation.

    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 !>

  [31;1mFunction: [0m<flush-compress>

    (defun flush-compress (name)
      (declare (xargs :guard t))
      (declare (ignore name))
      nil)")
 (FLUSH-HONS-GET-HASH-TABLE-LINK
  (FAST-ALIST-FREE ACL2-BUILT-INS)
  "Deprecated feature

  Deprecated.  Alias for [47m[fast-alist-free][0m.")
 (FMS
  (IO ACL2-BUILT-INS)
  "[47m(fms str alist co-channel state evisc) => state[0m

  See [fmt] for further explanation, including documentation of the
  tilde-directives.")
 (FMS!
  (IO ACL2-BUILT-INS)
  "[47m(fms! str alist co-channel state evisc) => state[0m

  This function is nearly the same as [47m[fms][0m, but [47mfms![0m avoids inserting
  backslash (\\) characters when forced to print past the right
  margin.  Use [47mfms![0m if you want to be able to read the forms back in.")
 (FMS!-TO-STRING (POINTERS)
                 "See [printing-to-strings].")
 (FMS-TO-STRING (POINTERS)
                "See [printing-to-strings].")
 (FMT
  (IO ACL2-BUILT-INS)
  "Formatted printing

  ACL2 provides the functions [47mfmt[0m, [47m[fmt1][0m, and [47m[fms][0m as substitutes for
  Common Lisp's [47mformat[0m function.  Also see [fmt!], see [fmt1!], and
  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 ([47m\\[0m) to break long lines.  There are also analogues of
  these functions that return a string without taking [47m[state][0m as an
  argument; see [printing-to-strings].  A convenient macro, [47mfmx[0m, is
  described below; also see [cw] and see [fmx-cw].

  All three print a given string under an alist pairing character
  objects with values, interpreting certain ``tilde-directives'' in
  the string.  [47mChannel[0m must be a character output channel (e.g.,
  [47m[*standard-co*][0m).

    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)

  [47m[Fms][0m and [47mfmt[0m print an initial newline to put [47mchannel[0m in column [47m0[0m;
  [47m[Fmt1][0m requires the current column as input.  Columns are numbered
  from [47m0[0m.  The current column is the column into which the next
  character will be printed.  (Thus, the current column number is
  also the number of [characters] printed since the last newline.)
  The [47mcol[0m returned by [47mfmt[0m and [47m[fmt1][0m is the current column at the
  conclusion of the formatting.  [47mEvisc-tuple[0m must be either [47mnil[0m
  (meaning no abbreviations are used when objects are printed) or an
  ``evisceration tuple''; see [evisc-tuple].

  We list the tilde-directives below.  The notation is explained after
  the chart.

    ~xx  pretty print vx (maybe after printing a newline)
    ~yx  pretty print vx starting in current column; end with newline
    ~Xxy like ~xx but use vy as the evisceration tuple
    ~Yxy like ~yx but use vy as the evisceration tuple
    ~@x  if vx is a string, \"str\",  recursively format \"str\"
         if vx is (\"str\" . a), recursively format \"str\" under a+
    ~#x~[...~/...~/ ... ~/...~] cases on vx
         ^    ^     ...   ^  if 0<=vx<=k, choose vxth alternative
         0    1     ...   k  if vx is a list of length 1, case 0; else 1
    ~*x  iterator: vx must be of the form
         (\"str0\" \"str1\" \"str2\" \"str3\" lst . a);
         if lst is initially empty, format \"str0\" under a+; otherwise,
         bind #\\* successively to the elements of lst and then
         recursively format \"stri\" under a+, where i=1 if there is one
         element left to process, i=2 if there are two left, and i=3
         otherwise.
    ~&x  print elements of vx with ~x, separated by commas and a
         final ``and''
    ~vx  print elements of vx with ~x, separated by commas and a
         final ``or''
    ~nx  if vx is a small positive integer, print it as a word, e.g.,
         seven;
         if vx is a singleton containing a small positive integer, print
           the corresponding ordinal as a word, e.g., seventh
    ~Nx  like ~nx but the word is capitalized, e.g., Seven or Seventh
    ~tx  tab out to column vx; newline first if at or past column vx
    ~cx  vx is (n . w), print integer n right justified in field of
         width w
    ~fx  print object vx flat over as many lines as necessary
    ~Fx  same as ~f, except that subsequent lines are indented to
         start one character to the right of the first character printed
    ~sx  if vx is a symbol, print vx, breaking on hyphens (unless the
         symbol would normally be printed with surrounding vertical bar
         characters (|), in which case print as with ~fx); if vx is a
         string, print the characters in it, breaking on hyphens; else
         vx is a number, to be printed using the current print-base and
         print-radix
    ~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

  If [47mx[0m is a character, then [47mvx[0m is the value of [47m#\\x[0m under the current
  alist.  Consider for example the discussion above for [47m~y[0m, ``[47m~yx
  pretty print vx[0m'', applied to the following expression: [47m(fmt \"HELLO
  ~y7\" (list (cons #\\7 'world)) *standard-co* state nil)[0m.  Then in
  this example: [47m#\\x[0m is 7; and [47mvx[0m is the value of character [47m#\\7[0m under
  the given alist, which is the symbol, [47mWORLD[0m.  Thus, ACL2 will print
  [47mHELLO WORLD[0m.  When we say ``format [47mstr[0m under [47ma+[0m'' we mean: process
  the given string under an alist obtained by appending [47ma[0m to the
  current alist.  The following example illustrates how this works.

    ACL2 !>(fms \"~@0\"
                (list (cons #\\0 (cons \"~x0 ~@1\" (list (cons #\\0  'abc))))
                      (cons #\\1 \"-- and now: ~x0 again~%\"))
                *standard-co* state nil)

    ABC -- and now: ABC again
    <state>
    ACL2 !>

  Note: [47m~p[0m, [47m~q[0m, [47m~P[0m, and [47m~Q[0m are also currently supported, but are
  deprecated and generally avoided in this manual.  These are
  respectively the same as [47m~x[0m, [47m~y[0m, [47m~X[0m, and [47m~Y[0m, 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.

  ACL2's formatting functions print to the indicated channel, keeping
  track of which column they are in.  [47m[Fmt1][0m can be used if the
  caller knows which column the channel is in (i.e., how many
  [characters] have been printed since the last newline).  Otherwise,
  [47mfmt[0m or [47m[fms][0m must be used, both of which output a newline so as to
  establish the column position at [47m0[0m.  Unlike Common Lisp's [47mformat[0m
  routine, [47mfmt[0m and its relatives break the output into lines so that,
  by default, an attempt is made to avoid printing past column [47m77[0m
  (the value of constant [47m*fmt-hard-right-margin-default*[0m), except
  when using [47m~S[0m.  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
  [47m~y[0m, [47m~Y[0m, [47m~q[0m, and [47m~Q[0m and can be changed to a positive integer [47mN[0m with
  [47m(set-ppr-flat-right-margin N state)[0m.

  The formatting functions scan the string from left to right, printing
  each successive character unless it is a tilde [47m(~)[0m.  Upon
  encountering tildes the formatters take action determined by the
  character or [characters] immediately following the tilde.  The
  typical tilde-directive is a group of three successive [characters]
  from the string being printed.  For example, [47m~x0[0m is a 3 character
  [47mtilde-directive[0m.  The first character in a tilde-directive is
  always the tilde character itself.  The next character is called
  the ``command'' character.  The character after that is usually
  taken as the name of a ``format variable'' that is bound in the
  alist under which the string is being printed.  Format variables
  are, by necessity, [characters].  The objects actually printed by a
  tilde-directive are the objects obtained by looking up the
  command's format variables in the alist.  Typical format variable
  names are [47m0[0m, [47m1[0m, [47m2[0m, ..., [47m9[0m, [47ma[0m, [47mb[0m, [47mc[0m, etc., and if a tilde-directive
  uses the format variable [47m0[0m, as in [47m~x0[0m, then the character [47m#\\0[0m must
  be bound in the alist.  Some tilde commands take no arguments and
  others take more than one, so some directives are of length two and
  others are longer.

  It should be noted that this use of [characters] in the string to
  denote arguments is another break from Common Lisp's [47mformat[0m
  routine.  In Common Lisp, the directives refer implicitly to the
  ``next item to be printed.'' But in ACL2 the directives name each
  item explicitly with our format variables.

  The following text contains examples that can be evaluated.  To make
  this process easier, we use a macro, [47mfmx[0m.  It takes up to eleven
  arguments, the first of which is a format string, [47mstr[0m, and the
  others of which are taken as the values of format variables; for
  similar utilities that do not take or return [state], see [cw] and
  [fmx-cw].  The variables used are [47m#\\0[0m through [47m#\\9[0m.  The macro
  constructs an appropriate alist, [47ma[0m, and then evaluates [47m(fmt` str a
  0 *standard-co* state nil)[0m.

  Thus,

    (fmx \"~%Here is v0, ~x0, and here is v1, ~x1.\"
         (cons 'value 0)
         (cons 'value 1))

  is just an abbreviation for

    (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)

  which returns [47m(mv 53 state)[0m after printing, on a separate line,

    Here is v0, (VALUE . 0), and here is v1, (VALUE . 1).

  We now devote special attention to three of the tilde-directives
  whose use is non-obvious.

  [3mThe Case Statement[0m

  [47m~#x[0m is essentially a ``case statement'' in the language of [47mfmt[0m.  The
  proper form of the statement is

    ~#x~[case-0~/case-1~/ ... ~/case-k~],

  where each of the [47mcase-i[0m is a format string.  In the most common use,
  the variable [47mx[0m has an integer value, [47mvx[0m, between [47m0[0m and [47mk[0m,
  inclusive.  The effect of formatting the directive is to format
  [47mcase-vx[0m.

  For example

    (fmx \"Go ~#0~[North~/East~/South~/West~].~%\" 1)

  will print ``Go East.'' followed by a newline and will return

  [47m(mv 0 state)[0m, while if you change the [47m1[0m above to [47m3[0m (the maximum legal
  value), it will print ``Go West.''

  In order to make it easier to print such phrases as ``there are seven
  cases'' requiring agreement between subject and verb based on the
  number of elements of a list, the case statement allows its
  variable to take a list as its value and selects [47mcase-0[0m if the list
  has length [47m1[0m and [47mcase-1[0m otherwise.

    (let ((cases '(a b c)))
      (fmx \"There ~#0~[is ~n1 case~/are ~n1 cases~].\"
           cases
           (length cases)))

  will print ``There are three cases.'' but if you change the

  [47m'(a b c)[0m above simply to [47m'(a)[0m it will print ``There is one case.''
  and if you change it to [47mnil[0m it will print ``There are zero cases.''

  [3mIndirection[0m

  Roughly speaking, [47m~@[0m will act as though the value of its argument is
  a format string and splice it into the current string at the
  current position.  It is often used when the phrase to be printed
  must be computed.  For example,

    (let ((ev 'DEFUN))
     (fmx \"~x0 is an event~@1.\"
          'foo
          (if (member-eq ev '(defun defstub encapsulate))
              \" that may introduce a function symbol\"
              \"\")))

  will print ``[47mfoo[0m is an event that may introduce a function symbol,''
  but if the value of [47mev[0m is changed from [47m'[0m[47m[defun][0m to [47m'[0m[47m[defthm][0m, it
  prints ``[47mfoo[0m is an event.'' The [47m~@[0m directive ``splices'' in the
  computed phrase (which might be empty).  Of course, this particular
  example could be done with the case statement

    ~#1~[~/ that may introduce a function symbol~]

  where the value of [47m#\\1[0m is appropriately computed to be [47m0[0m or [47m1[0m.

  If the argument to [47m~@[0m is a pair, it is taken to be a format string
  [47m[cons][0med onto an alist, i.e., [47m(\"str\" . a)[0m, and the alist, [47ma[0m, is
  used to extend the current one before [47m\"str\"[0m is recursively
  processed.  This feature of [47mfmt[0m can be used to pass around
  ``phrases'' that contain computed contextual information in [47ma[0m.  The
  most typical use is as ``error messages.'' For example, suppose you
  are writing a function which does not have access to [47m[state][0m 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-[47mnil[0m.  Our convention is to use a [47m~@[0m pair to represent such
  messages.  For example, the error value might be produced by the
  code:

    (cons
      \"Error:  The instruction ~x0 is illegal when the stack is ~x1.~%\"
      (list (cons #\\0 (current-instruction st))
            (cons #\\1 (i-stack st))))

  If the [47mcurrent-instruction[0m and [47mi-stack[0m (whatever they are) are [47m'(popi
  3)[0m and [47m'(a b)[0m when the [47m[cons][0m above is evaluated, then it produces

    '(\"Error:  The instruction ~x0 is illegal when the stack is ~x1.~%\"
      (#\\0 POPI 3)
      (#\\1 A B))

  and if this pair is made the value of the [47mfmt[0m variable [47m0[0m, then [47m~@0[0m
  will print

    Error:  The instruction (POPI 3) is illegal when the stack is (A B).

  For example, evaluate

    (let
     ((pair
      '(\"~%Error:  The instruction ~x0 is illegal when the stack is ~x1.~%\"
        (#\\0 POPI 3)
        (#\\1 A B))))
     (fmx \"~@0\" pair)).

  Thus, even though the function that produced the ``error'' could not
  print it, it could specify exactly what error message and data are
  to be printed.

  This example raises another issue.  Sometimes it is desirable to
  break lines in your format strings so as to make your source code
  more attractive.  That is the purpose of the [47mtilde-newline[0m
  directive.  The following code produces exactly the same output as
  described above.

    (let ((pair '(\"Error:  The instruction ~x0 ~
                  is illegal when the stack is ~
                  ~x1.~%\"
                  (#\\0 POPI 3)
                  (#\\1 A B))))
     (fmx \"~%~@0\" pair)).

  Finally, observe that when [47m~@0[0m extends the current alist, [47malist[0m, with
  the one, [47ma[0m, in its argument, the bindings from [47ma[0m are added to the
  front of [47malist[0m, overriding the current values of any shared
  variables.  This ensures that the variable values seen by the
  recursively processed string, [47m\"str\"[0m, are those from [47ma[0m, but if [47m\"str\"[0m
  uses variables not bound in [47ma[0m, their values are as specified in the
  original alist.  Intuitively, variables bound in [47ma[0m are local to the
  processing of [47m(\"str\" . a)[0m but [47m\"str\"[0m may use ``global variables.''
  The example above illustrates this because when the [47m~@0[0m is
  processed, [47m#\\0[0m is bound to the error message pair.  But when the
  [47m~x0[0m in the error string is processed, [47m#\\0[0m is bound to the illegal
  instruction.

  [3mIteration[0m

  The [47m~*[0m directive is used to process each element of a list.  For
  example,

    (let ((lst '(a b c d e f g h))) ; a true-list whose elements we exhibit
     (fmx \"~*0\"
          `(\"Whoa!\"          ; what to print if there's nothing to print
            \"~x*!\"           ; how to print the last element
            \"~x* and \"       ; how to print the 2nd to last element
            \"~x*, \"          ; how to print all other elements
            ,lst)))          ; the list of elements to print

  will print ``[47mA, B, C, D, E, F, G and H![0m''.  Try this example with
  other true list values of [47mlst[0m, such as [47m'(a b)[0m, [47m'(a)[0m, and [47mnil[0m.  The
  tilde-directives [47m~&0[0m and [47m~v0[0m, 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 [47m~*[0m.

  The [47m~*[0m directive allows the 5-tuple to specify in its final [47m[cdr][0m an
  alist with which to extend the current one before processing the
  individual elements.

  We often use [47m~*[0m to print a series of phrases, separated by suitable
  punctuation, whitespace and noise words.  In such use, the [47m~*[0m
  handles the separation of the phrases and each phrase is generally
  printed by [47m~@[0m.

  Here is a complex example.  In the [47m[let*][0m, below, we bind phrases to
  a list of [47m~@[0m pairs and then we create a [47m~*[0m 5-tuple to print out the
  conjunction of the phrases with a parenthetical ``finally!'' if the
  series is longer than 3.

    (let* ((phrases
            (list (list \"simplifying with the replacement rules ~&0\"
                        (cons #\\0 '(rewrite-rule1
                                    rewrite-rule2
                                    rewrite-rule3)))
                  (list \"destructor elimination using ~x0\"
                        (cons #\\0 'elim-rule))
                  (list \"generalizing the terms ~&0\"
                        (cons #\\0 '((rev x) (app u v))))
                  (list \"inducting on ~x0\"
                        (cons #\\0 'I))))
           (5-tuple
            (list
             \"magic\"                            ; no phrases
             \"~@*\"                              ; last phrase
             \"~@*, and~#f~[~/ (finally!)~] \"    ; second to last phrase
             \"~@*, \"                            ; other phrases
             phrases                            ; the phrases themselves
             (cons #\\f
                   (if (>(length phrases) 3) 1 0))))) ;print ``finally''?
      (fmx \"We did it by ~*0.\" 5-tuple))

  This [47m[let*][0m prints

    We did it by simplifying with the replacement rules REWRITE-RULE1,
    REWRITE-RULE2 and REWRITE-RULE3, destructor elimination using ELIM-
    RULE, generalizing the terms (REV X) and (APP U V), and (finally!)
    inducting on I.

  You might wish to try evaluating the [47m[let*][0m after removing elements
  of phrases.

  Most of the output produced by ACL2 is produced via [47mfmt[0m statements.
  Thus, inspection of the source code will yield many examples.  A
  complicated example is the code that explains the simplifier's
  work.  See [47m:[0m[47m[pc][0m [47msimplify-clause-msg1[0m.  An ad hoc example is
  provided by the function [47mfmt-doc-example[0m, which takes two
  arguments: an arbitrary true list and [47m[state][0m.  To see how
  [47mfmt-doc-example[0m works, [47m:[0m[47m[pe][0m [47mfmt-doc-example[0m.

    (fmt-doc-example '(a b c d e f g h i j k l m n o p) state)

  will produce the output

    Here is a true list:  (A B C D E F G H I J K L M N O P).  It has 16
    elements, the third of which is C.

    We could print each element in square brackets:
    ([A], [B], [C], [D], [E], [F], [G], [H], [I], [J], [K], [L], [M], [N],
    [almost there: O], [the end: P]).  And if we wished to itemize them
    into column 15 we could do it like this
    0123456789012345
        0 (zeroth) A
        1 (first)  B
        2 (second) C
        3 (third)  D
        4 (fourth) E
        5 (fifth)  F
        6 (sixth)  G
        7 (seventh)
                   H
        8 (eighth) I
        9 (ninth)  J
       10 (tenth)  K
       11 (eleventh)
                   L
       12 (twelfth)
                   M
       13 (thirteenth)
                   N
       14 (14th)   O
       15 (15th)   P
    End of example.

  and return [47m(mv 15 state)[0m.

  Finally, we should remind the reader that [47mfmt[0m and its subfunctions,
  most importantly [47mfmt0[0m, 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.")
 (FMT!
  (IO ACL2-BUILT-INS)
  "[47m(fmt! str alist co-channel state evisc) => state[0m

  This function is nearly the same as [47m[fmt][0m, but [47mfmt![0m avoids inserting
  backslash (\\) characters when forced to print past the right
  margin.  Use [47mfmt![0m if you want to be able to read the forms back in.")
 (FMT!-TO-STRING (POINTERS)
                 "See [printing-to-strings].")
 (FMT-HARD-RIGHT-MARGIN (POINTERS)
                        "See [set-fmt-hard-right-margin].")
 (FMT-SOFT-RIGHT-MARGIN (POINTERS)
                        "See [set-fmt-hard-right-margin].")
 (FMT-TO-COMMENT-WINDOW
  (CW IO ACL2-BUILT-INS)
  "Print to the comment window

    General Form:
    (fmt-to-comment-window fmt-string alist col evisc-tuple print-base-radix)

  where these arguments are as described for [47m[fmt1][0m (see [fmt]) except
  that the last argument is as described for [47m[cw-print-base-radix][0m.

  See [cw] for important background.  Calls of the macro [47mcw[0m expand to
  calls of the function [47mfmt-to-comment-window[0m whose final three
  arguments are [47m0[0m, [47mnil[0m, and [47mnil[0m.  For variants of
  [47mfmt-to-comment-window[0m that provide readable output (suffix [47m\"!\"[0m) and
  are never inhibited (suffix [47m\"+\"[0m), see [fmt-to-comment-window!],
  [fmt-to-comment-window+], and [fmt-to-comment-window!+].

  Function [47mfmt-to-comment-window[0m is similar to [47mfmt1[0m (see [fmt]), except
  that the channel is [47m[*standard-co*][0m and the ACL2 [47m[state][0m 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
  [47mcw-print-base-radix[0m; see [cw-print-base-radix].  An analogous
  function, [47mfmt-to-comment-window![0m, prints with [47m[fmt!][0m instead of
  [47m[fmt][0m, in order to avoid insertion of backslash (\\) characters for
  margins; also see [cw!], a macro that expands to a call of
  [47mfmt-to-comment-window![0m.  Note that even if you change the value of
  [47m[ld][0m special [47mstandard-co[0m (see [standard-co]), [47mfmt-to-comment-window[0m
  will print to [47m[*standard-co*][0m, which is the original value of
  [47m[standard-co][0m.")
 (FMT-TO-COMMENT-WINDOW!
  (CW IO ACL2-BUILT-INS)
  "Print readably to the comment window

  See [cw] for important background.

  This is nearly the same as [47m[fmt-to-comment-window][0m, but
  [47mfmt-to-comment-window![0m avoids inserting backslash (\\) characters
  when forced to print past the right margin.  Use
  [47mfmt-to-comment-window![0m if you want to be able to read the forms
  back in.")
 (FMT-TO-COMMENT-WINDOW!+
  (CW IO ACL2-BUILT-INS)
  "Print readably and uninhibited to the comment window

  See [cw] for important background.

  This is nearly the same as [47m[fmt-to-comment-window][0m, but
  [47mfmt-to-comment-window!+[0m always produces readable output (like
  [47m[fmt-to-comment-window!][0m), even when the [47mCOMMENT[0m output type is
  inhibited (like [47m[fmt-to-comment-window+][0m).")
 (FMT-TO-COMMENT-WINDOW+
  (CW IO ACL2-BUILT-INS)
  "Print uninhibited to the comment window

  See [cw] for important background.

  This is nearly the same as [47m[fmt-to-comment-window][0m, but
  [47mfmt-to-comment-window+[0m always produces output, even when the
  [47mCOMMENT[0m output type is inhibited (see [set-inhibit-output-lst]).")
 (FMT-TO-STRING (POINTERS)
                "See [printing-to-strings].")
 (FMT1
  (IO ACL2-BUILT-INS)
  "[47m(fmt1 str alist col co-channel state evisc) => (mv col state)[0m

  See [fmt] for further explanation, including documentation of the
  tilde-directives.")
 (FMT1!
  (IO ACL2-BUILT-INS)
  "[47m(fmt1! str alist col channel state evisc) => (mv col state)[0m

  This function is nearly the same as [47m[fmt1][0m, but [47mfmt1![0m avoids
  inserting backslash (\\) characters when forced to print past the
  right margin.  Use [47mfmt1![0m if you want to be able to read the forms
  back in.")
 (FMT1!-TO-STRING (POINTERS)
                  "See [printing-to-strings].")
 (FMT1-TO-STRING (POINTERS)
                 "See [printing-to-strings].")
 (FMX
  (IO ACL2-BUILT-INS)
  "[47m(fmx str &rest args) => state[0m

  See [fmt] for further explanation, including documentation of the
  tilde-directives.")
 (FMX!-CW (POINTERS) "See [fmx-cw].")
 (FMX-CW
  (IO ACL2-BUILT-INS)
  "[47m(fmx-cw str &rest args) => state[0m

  [47mFmx-cw[0m is a variant of [47mcw[0m: both take the same arguments and have the
  same behavior on well-formed input, and both return [47mnil[0m.  See [cw]
  for documentation on how to use both utilities.  Unlike [47mcw[0m, which
  has a [guard] of [47mt[0m, [47mfmx-cw[0m has a non-trivial guard that can can
  catch errors in the use of tilde-directives.  Here is an example of
  such a guard violation, where the corresponding call of [47mcw[0m would
  instead cause a hard error.

    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 !>

  Thus, call [47mfmx-cw[0m instead of [47mcw[0m in the body of [47m:[0m[47m[logic][0m mode
  definition when you want its [guard] verification to help ensure
  the absence of runtime errors from that call.  Note that if you
  call [47mfmx-cw[0m in a definition, the guard proof may benefit from the
  lemma, [47mfmx-cw-msg-1-opener[0m, found in [community-book]
  [47mbooks/system/fmx-cw.lisp[0m.

  The variant [47mfmx!-cw[0m avoids the insertion of backslash () characters
  when forced to print past the right margin.  Thus, use [47mfmx!-cw[0m
  instead of [47mfmx-cw[0m if you want the output to be machine-readable.")
 (FN-EQUAL
  (APPLY$ DEFWARRANT)
  "Equivalence relation on tame functions

  [47mFn-equal[0m is an equivalence relation on tame functions.  It holds
  between [47mfn1[0m and [47mfn2[0m iff both are tame functions and [47m(apply$ fn1
  args)[0m is [47m(apply$ fn2 args)[0m, for all [47margs[0m.  A [47mdefun-sk[0m event is used
  to express the universally quantified condition.  [47m[defwarrant][0m
  proves that [47mfn-equal[0m is a congruence relation for every argument
  position of ilk [47m:FN[0m.

  Ideally one can substitute one functional object for an equivalent
  one in functional positions.  For example, [47mfn-equal[0m holds between
  [47m'(LAMBDA (X) X)[0m and [47m'IDENTITY[0m, so one would hold that [47m(collect$
  '(LAMBDA (X) X) lst)[0m could be rewritten to [47m(collect$ 'IDENTITY lst)[0m
  since the first argument of [47mcollect$[0m (as defined in the
  [introduction-to-apply$]) has ilk [47m:FN[0m.  Unfortunately, because
  these are quoted constants, ACL2's rewriter will not rewrite one to
  the other!

  We regard [47mfn-equal[0m as a reminder to us --- or a challenge to users!
  --- to find a way to handle functional equivalence in the rewriter.")
 (FN-RUNE-NUME (POINTERS)
               "See [system-utilities].")
 (FN-SYMB (POINTERS)
          "See [system-utilities].")
 (FNCALL-TERM (POINTERS)
              "See [meta-extract].")
 (FOR-LOOP$
  (LOOP$)
  "Iteration with [47m[loop$][0m over an interval of integers or a list

  This topic assumes that you have read the introduction to [47mloop$[0m
  expressions in ACL2; see [loop$].  Here we give more complete
  documentation on [47mFOR[0m [47mloop$[0m expressions, beginning with informal
  discussion and then continuing with detailed syntax (General Form)
  and semantics.  For a discussion of proofs about [47mloop$[0ms, see
  [stating-and-proving-lemmas-about-loop$s].

  Examples of [47m[loop$][0m expressions, including [47mFOR[0m [47mloop$[0ms, may be found
  in [community-book] [47mprojects/apply/loop-tests.lisp[0m.

  The only allowed iteration clauses are [47mIN[0m, where the variable ranges
  over the elements of the given true list; [47mON[0m, where the variable
  ranges over the tails of the given true-list; and [47mFROM/TO/BY[0m, where
  the variable ranges over the integers between two bounds, stepping
  by a positive integer increment (or by 1 if no [47mBY[0m clause is
  provided).

  You may have as many iteration clauses as you wish, connected with
  [47mAS[0m.  Each must introduce a unique iteration variable and that
  variable may be optionally followed by an [47mOF-TYPE[0m [type-spec]
  specification.  [47mOF-TYPE[0m is a Common Lisp feature that allows the
  compiler to optimize operations on the variable in question.  Here
  is an example.

    (loop$ for v of-type (and integer (not (satisfies zerop)))
                 from 1 to 100
           sum (/ 1 v))

  Here is that same example with a more concise type specification.

    (loop$ for v of-type (integer 1 *)
                 from 1 to 100
           sum (/ 1 v))

  After all of the iteration clauses, you may have a termination test,
  signaled by [47mUNTIL[0m, and/or a conditional test, signaled by [47mWHEN[0m.  If
  both are provided, the [47mUNTIL[0m test must come first.  Iteration stops
  when the [47mUNTIL[0m test is satisfied.  The conditional test determines
  whether the loop body is executed for the current value of the
  iteration variables.

  Between the [47mUNTIL[0m symbol and the expression to be tested, and between
  the [47mWHEN[0m symbol and its expression, you may include a [47m:GUARD[0m
  clause.  This is useful if [guard] verification requires an
  invariant relating multiple iteration variables.  An example of a
  guarded [47mUNTIL[0m clause is

    (loop$ for u in lst1 as v in lst2
           until :guard (invariantp u v) (test u v)
           collect (body u v))

  ACL2 supports only five operators in [47mFOR[0m [47mloop$[0ms: [47mSUM[0m, [47mCOLLECT[0m,
  [47mALWAYS[0m, [47mTHEREIS[0m and [47mAPPEND[0m.  We anticipate adding other Common Lisp
  operators eventually.

  The special symbols noted above, sometimes called ``[47mFOR[0m [47mloop$[0m
  keywords'' or just ``[47mloop$[0m keywords'' may be in any package.  These
  are [47mFOR[0m, [47mIN[0m, [47mON[0m, [47mFROM[0m, [47mTO[0m, [47mBY[0m, [47mOF-TYPE[0m, [47mWHEN[0m, [47mUNTIL[0m, [47mSUM[0m, [47mCOLLECT[0m,
  [47mALWAYS[0m, [47mTHEREIS[0m, and [47mAPPEND[0m.

  Between the operator, e.g., [47mSUM[0m or [47mCOLLECT[0m, and the [47mloop$[0m body you
  may include a [47m:GUARD[0m clause as in

    (loop$ for u in lst1 as v in lst2
           collect :guard (invariantp u v) (body u v))

  This is sometimes necessary in the verification of the [guard]s for
  the [47mloop$[0m body because Common Lisp's [47mOF-TYPE[0m clauses do not permit
  you to relate one variable to another.

  See [lp-section-6] of the [47mLoop$[0m Primer for some exercises in writing
  [47mFOR[0m [47mLoop$[0ms (with answers in a Community Book).  But remember to
  come back here when you get to the end of that section.


General Form

  The syntax of Common Lisp [47mloop[0m expressions is extremely complicated.
  Rather than try to write the abstract syntax of ACL2's [47mloop$[0m
  expressions in the same formal style, we take a different approach,
  which is workable because [47mloop$[0m allows fewer options.

  First we introduce the syntax of a ``target clause,'' a
  ``type-spec,'' and the ``operators.'' Then we describe the most
  elaborate form of a [47mloop$[0m expression in terms of these elements and
  ordinary ACL2 terms.  Every legal [47mloop$[0m expression can be produced
  by omitting certain optional elements from the most elaborate [47mloop$[0m
  form.  So we conclude the syntactic description of [47mloop$[0m by listing
  the elements that can be omitted.

  A [3mtarget clause[0m has one of four forms

    * [47mIN[0m [3mlist-expr[0m

    * [47mON[0m [3mexpr[0m

    * [47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m

    * [47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m [47mBY[0m [3mstep-expr[0m

  where [3mlist-expr[0m is a term (which is expected to evaluate to a true
  list), [3mexpr[0m is a term, [3mlo-expr[0m and [3mhi-expr[0m are terms (which are
  expected to evaluate to integers), and [3mstep-expr[0m is a term (which
  is expected to evaluate to a positive integer).

  The legal [3mtype-specs[0m are listed in [47m[type-spec][0m.

  The legal [3moperators[0m are [47mSUM[0m, [47mCOLLECT[0m, [47mALWAYS[0m, [47mTHEREIS[0m, and [47mAPPEND[0m.

  The most elaborate [47mloop$[0m expression is of the form

  [47m(LOOP$ FOR [0m[3mv1[0m[47m OF-TYPE [0m[3mspec1 target1[0m
  [47mAS [0m   [3mv2[0m[47m OF-TYPE [0m[3mspec2 target2[0m
  ...
  [47mAS [0m   [3mvn[0m[47m OF-TYPE [0m[3mspecn targetn[0m
  [47mUNTIL :GUARD [0m[3mguard1 until-expr[0m
  [47mWHEN [0m   [47m:GUARD [0m[3mguard2 when-expr[0m
  ; Note the [47mALWAYS[0m/[47mTHEREIS[0m Exceptions below!
  [3mop[0m[47m :GUARD [0m[3mguard3 body-expr[0m[47m)[0m

  where each [3mvi[0m   is a legal variable symbol and they are all distinct,
  each [3mtype-speci[0m   is a [47m[type-spec][0m, each [3mtargeti[0m   is a target
  clause, each [3mguardi[0m, [3muntil-expr[0m, and [3mwhen-expr[0m   is a term, [3mop[0m   is
  an operator, and [3mbody-expr[0m   is a term.  Furthermore, [3muntil-expr[0m,
  [3mwhen-expr[0m, and [3mbody-expr[0m   must be [tame]!

  [3mThe [47mALWAYS[0m[3m/[47mTHEREIS[0m[3m Exception:[0m Common Lisp prohibits loops with both a
  [47mWHEN[0m clause and either an [47mALWAYS[0m or a [47mTHEREIS[0m operator.  For
  example, if you are tempted to use [47mWHEN[0m [3mp[0m with [47mALWAYS[0m [3mq[0m you can
  instead write [47mALWAYS[0m [47m(implies [0m[3mp q[0m[47m)[0m or, if you want to evaluate [47mq[0m
  only when [47mp[0m is true, you can write [47mALWAYS[0m [47m(if [0m[3mp q[0m [47mt)[0m.

  The following elements may be omitted.

    * any line beginning with [47mAS[0m, [47mUNTIL[0m or [47mWHEN[0m,

    * any [47mOF-TYPE[0m [3mspeci[0m, and

    * any [47m:GUARD[0m [3mguardi[0m.

  As noted above, the [47mFOR[0m [47mloop$[0m keywords (as used above) may be in any
  package.  These are [47mFOR[0m, [47mIN[0m, [47mON[0m, [47mFROM[0m, [47mTO[0m, [47mBY[0m, [47mOF-TYPE[0m, [47mWHEN[0m,
  [47mUNTIL[0m, [47mSUM[0m, [47mCOLLECT[0m, [47mALWAYS[0m, [47mTHEREIS[0m, and [47mAPPEND[0m.

  We give names to certain classes of the syntactic entities above.
  The [3mv1[0m, ..., [3mvn[0m are called the [3miteration variables[0m.  The [3mspec1[0m,
  ..., [3mspecn[0m are called [3mtype specs[0m, each corresponds to a certain
  iteration variable, and each gives rise to a [3mtype term[0m about its
  variable in the sense that ``[47mX OF-TYPE (SATISFIES NATP)[0m'' gives
  rise to the type term [47m(NATP X)[0m and ``[47mI OF-TYPE INTEGER[0m'' gives rise
  to the type term [47m(INTEGERP I)[0m.  The terms involved in the target
  expressions, e.g., the [3mlist-expr[0m and [3mexpr[0m in ``[47mIN[0m [3mlist-expr[0m'' and
  ``[47mON[0m [3mexpr[0m'' and the [3mlo-expr[0m, [3mhi-expr[0m and optional [3mstep-expr[0m in the
  ``[47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m [47mBY[0m [3mstep-expr[0m'' targets are called [3mtarget
  terms[0m.  Finally, the [3muntil-expr[0m, [3mwhen-expr[0m, and [3mbody-expr[0m are
  called [3miterative forms[0m.

  We distinguish the target terms from the iterative forms because they
  are handled very differently at evaluation time.  When a [47mloop$[0m 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.

  A [47mFOR[0m [47mloop$[0m expression with just one iteration variable and in which
  the iterative forms mention no free variable other than the
  iteration variable is called a [3msimple [47mloop$[0m[3m[0m (or, sometimes, a
  [3msimple loop[0m).  An example of a simple loop is

    (loop$ for x in lst when (evenp x) collect (+ 1 (sq x)))

  A [47mFOR[0m [47mloop$[0m expression is called a [3mfancy [47mloop$[0m[3m[0m if it is not simple.
  Both of the following [47mloop$[0ms are fancy.

    (loop$ for x in xlst as y on ylst collect (expr x y))

    (loop$ for x in xlst collect (expr x z))

  The first is fancy because it has two iteration variables.  The
  second is fancy because the body freely uses the variable [47mz[0m which
  is not the iteration variable.  The free variables cannot be
  [stobj]s or [df]s, since the translation of the [47mloop$[0m will put them
  into a list; see discussion of the semantics, below.  In such cases
  you may wish to use [47mDO[0m [47mloop$[0m expressions (see [do-loop$]) instead.


Semantics

  [47mFOR[0m [47mloop$[0m expressions are translated into calls of [scion]s, with the
  [47mUNTIL[0m and [47mWHEN[0m 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
  [47mas[0m clauses, and/or (b) one of the iterative forms (the [47mUNTIL[0m, [47mWHEN[0m
  or loop body expression) refers to variables other than an
  iteration variable.  If the [47mloop$[0m expression is simple, the simple
  scions are used; otherwise the fancy scions are used.

    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$+

  We deal with simple [47mloop$[0ms first.

  Semantics of Simple Loop$s

  For example, the simple [47mloop$[0m

    (loop$ for x in lst collect (+ 1 (sq x)))

  translates to (a term equivalent to)

    (collect$ (lambda$ (x)
                       (declare (ignorable x))
                       (+ 1 (sq x)))
              lst).

  [31;1mNote:[0m 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 [47m[trans][0m.

  In the translation the target term, [47mlst[0m, appears as an ordinary
  subterm of the translation.  But the iterative form, [47m(+ 1 (sq x))[0m,
  becomes the body of a [47m[lambda$][0m expression, which means its
  translation becomes a component of a quoted [47mLAMBDA[0m object.  When
  the [47mcollect$[0m is evaluated, the target term is evaluated once but
  the iterative form is evaluated once for each element of the value
  of the target.

  [47mUNTIL[0m and [47mWHEN[0m clauses are handled by preprocessing the target.
  E.g.,

    (loop$ for x in lst
           until (> x 100)
           when (evenp x)
           collect (+ 1 (sq x)))

  becomes

    (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)))

  So from a logical perspective, the presence of an [47mUNTIL[0m and/or [47mWHEN[0m
  clause in a [47mcollect[0m iteration over [47mlst[0m ``copies'' the target value.
  The [47muntil$[0m copies [47mlst[0m until encountering the first element on which
  its functional argument is true.  The [47mwhen$[0m then copies that
  (shortened?) target, keeping only the elements that satisfy its
  functional argument.  Finally, the [47mcollect$[0m then applies its
  functional argument and collects all the values.

  [47mON[0m and [47mFROM/TO/BY[0m targets are handled by listing all the elements in
  the given target.  For example,

    (loop$ for x on lst collect (expr x))

  which maps [47mx[0m over successive non-empty tails of [47mlst[0m and collects the
  value of [47mexpr[0m has the logical meaning

    (collect$ (lambda$ (x) (expr x))
              (tails lst))

  where, for example, [47m(tails '(1 2 3))[0m is [47m((1 2 3) (2 3) (3))[0m.

  Spiritually similarly,

    (loop$ for i from 1 to max by step collect (expr x))

  logically becomes

    (collect$ (lambda$ (x) (expr x))
              (from-to-by 1 max step))

  where, for example, [47m(from-to-by 1 10 2)[0m is [47m(1 3 5 7 9)[0m.

  Similar translations are done for the other operators, e.g., [47mSUM[0m and
  [47mALWAYS[0m.  The advantage of this translation style is that it allows
  compositional reasoning.  We discuss this further below.

  The following example illustrates basic [guard] proof obligations, in
  particular showing that [47mWHEN[0m clauses do not help with verifying
  guards for the [47mloop$[0m bodies.  (Similarly, [47mUNTIL[0m clauses do not help
  either.)  The basic problem is that ACL2 requires that [47m[lambda][0m
  objects be guard verifiable in isolation, not confined to the
  context in which a particular [47mlambda[0m object appears.  Consider the
  following.

    (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))))

  Guard verification fails for [47mfoo[0m.  The summary says that a goal of
  [47mNIL[0m was generated.  Using [47m:[0m[47m[pso][0m we can see that the [47mNIL[0m goal came
  from:

    Subgoal 1.2
    (IMPLIES (NAT-LISTP LOOP$-IVAR)
             (INTEGERP (CAR LOOP$-IVAR))).

  Let's see what is going on by looking at the following simplified
  translation of the [47mloop$[0m expression.

    (sum$ '(lambda (loop$-ivar)
             (declare (type (satisfies nat-listp) loop$-ivar))
             (sq (car loop$-ivar)))
          (when$ '(lambda ...) (tails lst)))

  Notice that the [47mlambda[0m object supplied to [47msum$[0m cannot be guard
  verified in isolation: [47mnil[0m satisfies the [47m:guard[0m and [47m(car nil)[0m
  violates the guard of [47msq[0m.  The following modification, which adds a
  [47m:guard[0m directive after the [47mSUM[0m op keyword, solves the problem.

    (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))))

  This new [47m:guard[0m may feel redundant, coming as it does after the [47mwhen
  (consp x)[0m clause.  But it is necessary given the compositional
  semantics.

  A simplified translation of the [47mdefun[0m above shows that the
  application [47m(sq (car x))[0m is protected by a suitable guard in the
  [47mlambda[0m object.

    (sum$ '(lambda (loop$-ivar)
             (declare (type (satisfies nat-listp) loop$-ivar)
                      (xargs :guard (consp loop$-ivar)))
             (sq (car loop$-ivar)))
          (when$ '(lambda ...) (tails lst)))

  Naively we might have expected that the guard proof obligation for
  the [47mloop$[0m body [47m(sq (car x))[0m could assume the [47mWHEN[0m clause, but that
  expectation would be wrong because of the compositional semantics
  we use and the fact that [47m[lambda][0m objects must be guard-verifiable
  on their own.  The reason for the latter requirement is that our
  implementation caches guard-verified [47mlambda[0m objects for evaluation
  in raw Lisp, which may take place in other contexts different from
  that in which the [47mlambda[0m first appeared.  See [print-cl-cache].

  Semantics of Fancy Loop$s

  An example of a fancy [47mloop$[0m is

    (loop$ for x in xlst as y in ylst collect (expr x y z))

  This loop exhibits both characteristics (a) and (b): it has an [47mAS[0m
  clause and the variable [47mz[0m 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.

    (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)))

  Before we show the definition of [47mcollect$+[0m, note that the arguments
  above to [47mcollect$+[0m are (i) a [47mlambda$[0m expression that handles the
  evaluation of the iterative form, in this case [47m(expr x y z)[0m, where
  [47mx[0m and [47my[0m are iteration variables and [47mz[0m is a ``global'' variable not
  among the iteration variables; (ii) the list of values of the
  ``global'' variables, in this case the list containing [47mz[0m; and (iii)
  a target list constructed by [47mloop$-as[0m from the various targets
  provided in the [47mloop$[0m, in this case [47mxlst[0m and [47mylst[0m, supplying values
  for iteration variables [47mx[0m and [47my[0m respectively.  For example,
  [47m(loop$-as (list '(a b c d e) '(1 2 3)))[0m is [47m((a 1) (b 2) (c 3))[0m.
  These tuples contain successive corresponding values of [47mx[0m and [47my[0m.

  The definition of [47mcollect$+[0m is essentially

    (defun collect$+ (fn loop$-gvars lst)
      (if (endp lst)
          nil
          (cons (apply$ fn (list loop$-gvars (car lst)))
                (collect$+ fn loop$-gvars (cdr lst)))))

  We have omitted the guard and an [47m[mbe][0m form that make it run more
  efficiently.  All the fancy [47mloop$[0m scions are defined analogously.

  Inspection of the [47mlambda$[0m expression above reveals that it takes a
  list of global variable values and a list of iteration variable
  values, unpacks them with a [47mlet[0m that binds the global variables,
  here just [47mz[0m, to their values and binds the iteration variables,
  here [47mx[0m and [47my[0m, to the corresponding pair of values from the target,
  and then evaluates the [47mloop$[0m body, [47m(expr x y z)[0m.

  The names of the formals for the [47mlambda$[0m expressions generated by
  fancy [47mloop$[0m expressions are always [47mloop$-gvars[0m and [47mloop$-ivars[0m, for
  ``[47mloop$[0m global variables'' and ``[47mloop$[0m iteration variables.''

  [47mUNTIL[0m and [47mWHEN[0m clauses in a fancy [47mloop$[0m are handled exactly as they
  are in simple [47mloop$[0ms, except that the fancy scions are used since
  the target list is a list of tuples of iteration variable values
  and the [47mUNTIL[0m and [47mWHEN[0m forms may refer to global variables.

  See [lp-section-10] of the [47mLoop$[0m Primer for a step-by-step discussion
  of the evaluation of the formal semantics of an example of a fancy
  [47mLoop$[0m.  But remember to come back here when you get to the end of
  that section.

  Special Guard Conjectures for [47mFOR[0m [47mloop$[0ms

  Since every [47mloop$[0m expands to a call of a [47mloop$[0m scion on a lambda
  object and a target, one would expect that [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 [47m[true-listp][0m.

  But in addition to the expected guard conjectures, we generate some
  special ones for the terms produced by translating [47mFOR[0m [47mloop$[0m
  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 [47mloop$[0m.  Fancy [47mloop$[0ms generalize in the obvious way.
  The two classes of ``special guard conjectures'' for [47mFOR[0m [47mloop$[0m
  expressions are as follows.

    * First, every element (or tail, in the case of [47mON[0m [47mloop$[0ms)) satisfies
      the type-spec, if any, and the [47mloop$[0m body's [47m:GUARD[0m, if any.

    * Second, the [47mloop$[0m body produces a value acceptable to the [47mloop$[0m
      operator, e.g., the body of a [47mSUM[0m [47mloop$[0m produces a number and
      the body of an [47mAPPEND[0m [47mloop$[0m produces a true list.

  See [lp-section-8] of the [47mLoop$[0m Primer for some exercises in
  converting recursive functions to guard verified functions using
  [47mFOR[0m [47mloop$[0ms rather than recursion (with answers in a Community
  Book).  But remember to come back here when you get to the end of
  that section.

  Discussion of Why LOOP$s Have Special Guards

  All of the simple [47mloop$[0m scions have the same guard, namely

    (AND (APPLY$-GUARD FN '(NIL))
         (TRUE-LISTP LST)),

  and all the fancy [47mloop$[0m scions have the same guard, namely

    (AND (APPLY$-GUARD FN '(NIL NIL))
         (TRUE-LISTP LOOP$-GVARS)
         (TRUE-LIST-LISTP LST)).

  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 [47mloop[0m expressions.

  For example, the simplified translation of the body of

    (defun foo (lst)
      (declare (xargs :guard (foo-guardp lst)))
      (loop$ for x of-type (satisfies spec) on lst sum (expr x)))

  is as follows.  (One might expect the second argument of the [47msum$[0m
  call to be [47m(tails lst)[0m, and of course that is what it equals,
  logically; the change is to support guards, as discussed in the
  Technical Note below.)

    (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)))

  Prior to the provision for special guards, the normal guard
  conjectures generated for [47mfoo[0m would be

    (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)))

  Conjectures [1] and [2] stem from the guard for [47msum$[0m and establish
  that the guard for [47mfoo[0m implies that [47msum$[0m is passed a function
  object of one argument and a true-list.  Conjecture [3] establishes
  that the guard on the [47mlambda$[0m implies the guard of its body.
  Conjecture [4] says that the final tail of [47mlst[0m (which is [47mnil[0m if [47mlst[0m
  is a true list; see [last-cdr]) satisfies [47mspec[0m.  At first [4] may
  be surprising, but inspection of Common Lisp reveals that even
  though [47m(expr x)[0m is never called on the final tail of [47mlst[0m,
  implementations running with high safety settings check that the
  final tail satisfies [47mspec[0m.  If you see a runtime guard violation
  involving variable [47mloop$-last-cdr[0m, you can reasonably assume that
  you are seeing case [4] above.  A guard proof failure involving a
  call of [47m[last-cdr][0m may also be from [4].

  (Technical Note.  The production of [4] is accomplished as follows
  for an expression [47m(loop for var of-type type-spec on lst ...)[0m: for
  the translation to a scion call, the target term, [47mlst[0m, is replaced
  by the following expression (simplifying slightly).

    (prog2$ (let ((loop$-last-cdr (last-cdr lst)))
              (declare (type type-spec loop$-last-cdr))
              loop$-last-cdr)
            lst)

  The [47m[declare][0m form causes formula [4] above to be generated as a
  guard proof obligation.  End of Technical Note.)

  The guard proof obligation shown as [4] above, for an expression
  [47m(loop$ for ... on ...)[0m, has a variant for an expression [47m(loop$ for
  n from i to j by k ...)[0m, where ``[47mby k[0m'' may be implicit if [47mk[0m is [47m1[0m.
  Instead of the requirement in [4] above that the bound variable
  [47mloop$-last-cdr[0m satisfy the [47mtype-spec[0m, variables [47mloop$-lo[0m, [47mloop$-hi[0m,
  and [47mloop$-by[0m, which are bound respectively to [47mi[0m, [47mj[0m, and [47mk[0m, are
  required to satisfy the [47mtype-spec[0m.  A fourth requirement is that
  the last value tested must also satisfy the [47mtype-spec[0m.  That last
  value tested is [47m(+ loop$-lo loop$-by (* loop$-by (floor (- loop$-hi
  loop$-lo) loop$-by)))[0m.  If you see a runtime guard violation
  involving variable [47mloop$-lo[0m, [47mloop$-hi[0m, [47mloop$-by[0m, or [47mloop$-final[0m,
  you can reasonably assume that you are seeing this variant of [4].

  But consider the raw Lisp [47mloop[0m generated by the [47mloop$[0m in the raw Lisp
  definition of [47mfoo[0m,

    (loop for x of-type (satisfies spec) on lst sum (expr x)).

  For this [47mloop[0m to execute without error we need to know that [5] every
  non-empty tail of [47mlst[0m satisfies [47mspec[0m, and [6] every non-empty tail
  [47mx[0m of [47mlst[0m is such that [47m(expr x)[0m returns a number.

  So when ACL2's guard verification process encounters a [47msum$[0m like that
  in the logical [47mdefun[0m of [47mfoo[0m, 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 [47mloop$[0m body is acceptable to the [47mloop$[0m operator.

    (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))))

  Notice the addition of hypotheses above of the form [47m(warrant ...)[0m.
  ACL2 adds such [3m[warrant] hypotheses[0m for function symbols that might
  be [47m[apply$][0m'd during evaluation of a scion call (in this case,
  [47msum$[0m).

  In general, you may notice that ACL2 generates such ``special'' guard
  conjectures for all calls of [47mFOR[0m [47mloop$[0m scions, whether or not they
  stemmed from uses of [47mloop$[0m.  [47mFROM/TO/BY[0m targets require that the
  bounds and step all satisfy the [47mOF-TYPE[0m specification, and the
  [47mAPPEND[0m operator requires that the loop body generate a [47m[true-listp][0m
  (instead of an [47m[ACL2-numberp][0m as required by the [47mSUM[0m operator).

  The Compromise Between Reasoning and Efficiency

  The translation of [47mloop$[0m expressions into formal terms reflects a
  compromise between facilitating compositional reasoning and
  efficient execution.

  One sign of that compromise is our use of scions to handle [47mUNTIL[0m and
  [47mWHEN[0m clauses.  As noted above, by translating

    (loop$ for x in lst until ... when ... collect ...)

  into

    (collect$ ... (when$ ... (until$ ... lst)))

  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 [47mcollect$[0m, [47mwhen$[0m, and [47muntil$[0m.  We could
  have defined a version of [47mcollect$[0m that took three [47mlambda$[0m
  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.

  Another example of compositionality is to consider a simple [47mloop$[0m
  over the [47mIN[0m target [47m(append a b)[0m.  There are 8 different ways you
  can do a simple [47mCOLLECT[0m over an [47m(append a b)[0m target,

    (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))

  Similarly, there are 8 ways to [47mSUM[0m over an [47m(append a b)[0m target, 8
  ways to [47mAPPEND[0m over an [47m(append a b)[0m, and 4 ways each to [47mALWAYS[0m or
  [47mTHEREIS[0m over an [47m(append a b)[0m target.  Thus, there are 32 different
  simple [47mloop$[0ms over [47m(append a b)[0m.  And you can arrange to distribute
  the simple [47mloop$[0m over the [47m(append a b)[0m with just seven rewrite
  rules.

    (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)))

  Thus, you can reason about [47mWHEN[0m and [47mUNTIL[0m clauses without having to
  consider how they are used in the superior [47mloop$[0m expression.

  To deal with fancy [47mloop$[0m you need seven more rewrite rules, one for
  each fancy [47mloop$[0m scion.  But since every simple [47mloop$[0m can be
  expressed by an appropriate use of fancy scions, we could have
  translated every [47mFOR[0m [47mloop$[0m to fancy scions.  We chose to break
  compositionality here because we think simple [47mloop$[0ms are most
  common and wanted to keep their semantics simple.  I.e., we
  compromised.

  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.

    (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))))))))")
 (FORALL
  (DEFUN-SK)
  "Universal quantifier

  The symbol [47mforall[0m (in the ACL2 package) represents universal
  quantification in the context of a [47m[defun-sk][0m form.  See [defun-sk]
  and see [exists].

  See [quantifiers] for an example illustrating how the use of
  recursion, rather than explicit quantification with [47m[defun-sk][0m, may
  be preferable.")
 (FORCE
  (REWRITE LINEAR
           TYPE-PRESCRIPTION DEFINITION META)
  "Identity function used to force a hypothesis

  [47mForce[0m is the identity function: [47m(force x)[0m is equal to [47mx[0m.  However,
  for rules of many classes (see [rule-classes]), a hypothesis of the
  form [47m(force term)[0m is given special treatment, as described below.
  This treatment takes place for rule classes [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m,
  [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[meta][0m (actually in that
  case, the result of evaluating the hypothesis metafunction call),
  and [47m:[0m[47m[forward-chaining][0m.

  When a hypothesis of a conditional rule (of one of the classes listed
  above) has the form [47m(force hyp)[0m, it is logically equivalent to [47mhyp[0m
  but has a pragmatic effect.  In particular, when the rule is
  considered, the needed instance of the hypothesis, [47mhyp'[0m, 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 [47mhyp'[0m 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 [forcing-round] and see
  [immediate-force-modep].

  Note that the only time that ACL2 gives special treatment to calls of
  [47mforce[0m 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 [47mforce[0m is not treated specially.  For example, if you provide a
  [47m:use[0m hint (see [hints]) that replaces a goal [47mG[0m by the goal

    (implies (implies (and ... (force HYP) ...)
                      concl)
             G)

  then the rewriter will not give any special treatment to [47m(force HYP)[0m.
  Instead, it will first rewrite [47mHYP[0m to, say, [47mHYP'[0m; and then, using
  the fact that [47mforce[0m is the identity function, the rewriter will
  return [47mHYP'[0m as the rewritten value for [47m(force HYP)[0m.

  Forcing is generally used on hypotheses that are always expected to
  be true, as is commonly the case for [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 [immediate-force-modep]) or in a
  subsequent forcing round (see [forcing-round]).  Also see
  [case-split] for a related utility.  If the
  [47m:[0m[47m[executable-counterpart][0m of the function [47mforce[0m is [disable]d, then
  no hypothesis is forced.  For more on enabling and disabling
  forcing, see [enable-forcing] and see [disable-forcing].

  It sometimes happens that a conditional rule is not applied because
  some hypothesis, [47mhyp[0m, could not be relieved, even though the
  required instance of [47mhyp[0m, [47mhyp'[0m, can be shown true in the context.
  This happens when insufficient resources are brought to bear on
  [47mhyp'[0m at the time we try to relieve it.  A sometimes desirable
  alternative behavior is for the system to assume [47mhyp'[0m, apply the
  rule, and to generate explicitly a special case to show that [47mhyp'[0m
  is true in the context.  This is called ``forcing'' [47mhyp[0m.  It can be
  arranged by restating the rule so that the offending hypothesis,
  [47mhyp[0m, is embedded in a call of [47mforce[0m, as in [47m(force hyp)[0m.  By using
  the [47m:[0m[47m[corollary][0m field of the [47m[rule-classes][0m entry, a hypothesis
  can be forced without changing the statement of the theorem from
  which the rule is derived.

  Technically, [47mforce[0m is just a function of one argument that returns
  that argument.  It is generally [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.

  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.

  A particularly common situation in which some hypotheses should be
  forced is in ``most general'' [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 [type-prescription] lemmas generally has fairly
  thorough knowledge of the types of all terms (see
  [type-prescription] for relevant background).

  [47mForce[0m can have the additional benefit of causing the ACL2 typing
  mechanism to interact with the ACL2 rewriter to establish the
  hypotheses of [type-prescription] rules.  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 [type-prescription] rule with that hypothesis will be
  inapplicable in that case.  But by embedding such hypotheses in
  [47mforce[0m 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 [type-prescription] rule, then the
  rule will be found inapplicable because the hypothesis will not be
  established by type reasoning alone.

  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.

  This makes the following surprising behavior possible: A
  [type-prescription] rule fails to apply because some true
  hypothesis is not being relieved.  The user changes the rule so as
  to [31;1mforce[0m 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.

  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
  [linear-arithmetic].  Consider the following example:

    (implies (not (equal 0 x))
             (or (< 0 x) (< x 0)))

  This is not a theorem; in particular, it fails when [47mx[0m is [47mnil[0m.  What
  is missing is the hypothesis, [47m(acl2-numberp x)[0m.  If you try to
  prove the displayed formula above and you look at the proof using
  [47m:[0m[47m[pso][0m, you'll see the following.

    But forced simplification reduces this to T, using the :executable-
    counterpart of FORCE and linear arithmetic.

  Thus, no specific rule created this forcing round (see also
  [forcing-round]).  Rather, ACL2 was able to prove the goal using
  linear arithmetic, but it needed to force the assumption that [47mx[0m is
  a number.  This is clear when we look at output for the forcing
  round:

    [1]Goal, below, will focus on
    (ACL2-NUMBERP X),
    which was forced in
     Goal'
      by the linearization of
      (EQUAL 0 X).

  Finally, we should mention that the rewriter is never willing to
  force when there is an [47m[if][0m term present in the goal being
  simplified.  Since [47m[and][0m terms and [47m[or][0m terms are merely
  abbreviations for [47m[if][0m terms, they also prevent forcing.  Note that
  [47m[if][0m terms are ultimately eliminated using the ordinary flow of the
  proof (but see [set-case-split-limitations]), allowing [47mforce[0m
  ultimately to function as intended.  Moreover, forcing can be
  disabled, as described above; also see [disable-forcing].

  [31;1mFunction: [0m<force>

    (defun force (x)
      (declare (xargs :guard t))
      x)


Subtopics

  [Disable-forcing]
      To disallow forced case-splits

  [Disable-immediate-force-modep]
      [force]d hypotheses are not attacked immediately

  [Enable-forcing]
      To allow forced case splits

  [Enable-immediate-force-modep]
      [force]d hypotheses are attacked immediately

  [Failed-forcing]
      How to deal with a proof [failure] in a forcing round

  [Forcing-round]
      A section of a proof dealing with [force]d assumptions

  [Immediate-force-modep]
      When the [executable-counterpart] is [enable]d, [force]d hypotheses
      are attacked immediately")
 (FORCED (POINTERS) "See [force].")
 (FORCING-ROUND
  (FORCE)
  "A section of a proof dealing with [force]d assumptions

  If ACL2 ``[force]s'' some hypothesis of some rule to be true, it is
  obliged later to prove the hypothesis.  See [force].  ACL2 delays
  the consideration of [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 [force]d
  in the preceding proof.  Call this round of proofs the ``Forcing
  Round.'' Additional hypotheses may be [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 [force]d
  hypotheses and this continues until no hypotheses are [force]d.
  Thus, there is a succession of Forcing Rounds.

  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, [47m\"[1]Subgoal 1.3\"[0m 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 [47m\"[1]Subgoal 1.3\"[0m.  See [goal-spec].

  When a round is successfully completed --- and for these purposes you
  may think of the proof of the main goal as being the 0th forcing
  round --- the system collects all of the assumptions [force]d by
  the just-completed round.  Here, an assumption should be thought of
  as an implication, [47m(implies context hyp)[0m, 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 [force]d assumptions are generated by the same
  rule being applied repeatedly in a given context.

  By delaying and collecting the [47mforced[0m 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 [force]d assumptions ACL2 can undertake
  the proof of each assumption only once, no matter how many times it
  was [force]d in the main goal.

  In order to indicate which proof steps of the previous round were
  responsible for which [force]d assumptions, we print a sentence
  explaining the origins of each newly [force]d goal.  For example,

    [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).

  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
  [force]d hypothesis, call it [47mx[0m, which is [47m(good-inputp (xtrans i))[0m
  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 [47mx[0m was [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 [force]d [47mx[0m.  In the example
  above we see that Subgoals 14 and 28 of the just-completed proof
  [force]d [47m(good-inputp (xtrans i))[0m by applying [47m(:rewrite
  pred-cruncher)[0m to the term [47m(pred (xtrans i) i)[0m.

  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
  ``[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
  [force]d.  Similarly, if at the beginning of a forcing round a
  [rune] is blamed for causing a [force] in some subgoal, inspection
  of the commentary for that subgoal will reveal the word
  ``[force]d'' after the rule name blamed.

  Most [force]d hypotheses come from within the prover's simplifier.
  When the simplifier encounters a hypothesis of the form [47m(force hyp)[0m
  it first attempts to establish it by rewriting [47mhyp[0m to, say, [47mhyp'[0m.
  If the truth or falsity of [47mhyp'[0m is known, forcing is not required.
  Otherwise, the simplifier actually [force]s [47mhyp'[0m.  That is, the [47mx[0m
  mentioned above is [47mhyp'[0m, not [47mhyp[0m, when the [force]d subgoal was
  generated by the simplifier.

  Once the system has printed out the origins of the newly [force]d
  goals, it proceeds to the next forcing round, where those goals are
  individually displayed and attacked.

  At the beginning of a forcing round, the [enable]d structure defaults
  to the global [enable]d structure.  For example, suppose some
  [rune], [47mrune[0m, is globally [enable]d.  Suppose in some event you
  [disable] the [rune] at [47m\"Goal\"[0m and successfully prove the goal but
  [force] [47m\"[1]Goal\"[0m.  Then during the proof of [47m\"[1]Goal\"[0m, [rune] is
  [enable]d ``again.'' The right way to think about this is that the
  [rune] is ``still'' [enable]d.  That is, it is [enable]d globally
  and each forcing round resumes with the global [enable]d structure.")
 (FORMALS (POINTERS)
          "See [system-utilities].")
 (FORMULA
  (HISTORY WORLD ACL2-BUILT-INS)
  "The formula of a name or [rune]

  The ACL2 system function, [47mformula[0m, returns the [term] associated with
  a given [rune] or symbolic name, returning [47mnil[0m if there is no such
  term.  Note that a non-[47mnil[0m result will be an ACL2 ``translated''
  term (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 [world] to be useful.

  When ACL2 is given a [47m:use[0m or [47m:by[0m hint, it looks for the [term] stored
  in the ACL2 logical [world] that is associated with the name given
  in the hint, which is a symbol or a [rune].  (See
  [lemma-instance].)  The utility used to find that term is [47mformula[0m,
  which ACL2 invokes as follows.

    (formula x t wrld)   ; for :use hints
    (formula x nil wrld) ; for :by hints

  The second argument can affect whether or not to use a normalized
  version of the term (in particular, a definition body) associated
  with [47mx[0m; see [normalize].  The value is [47mt[0m for [47m:use[0m [hints] because
  normalizing a term simplifies it, which is often desirable.  But
  for a [47m:by[0m 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 [47mt[0m, normalization
  might not take place.  In the unlikely case that you need to know
  more precisely the effect of supplying [47mt[0m, see the source code for
  [47mformula[0m.

  Here are some examples.  Note that [47m(w state)[0m returns the current ACL2
  logical [world].  First let us submit a few [events].

    (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)))))

  Then:

    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 !>")
 (FORWARD-CHAINING
  (RULE-CLASSES)
  "Make a rule to forward chain when a certain trigger arises

  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.

    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)))

  To specify the triggering terms provide a non-empty list of terms as
  the value of the [47m:trigger-terms[0m field of the rule class object.

    General Form:
    Any theorem, provided an acceptable triggering term exists.

  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
  [47m:forward-chaining[0m rules.  Then we give more details about the
  process and point to a tool to assist you in debugging your
  [47m:forward-chaining[0m rules.

  [3mOverview and When to Use Forward Chaining[0m

  Forward chaining is performed as part of the simplification process:
  before the goal is rewritten a [3mcontext[0m 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 [47m:forward-chaining[0m rule [47m(implies (p x) (p1 x))[0m
  would add [47m(p1 A)[0m to the context, where [47mA[0m is some term, if [47m(p A)[0m is
  already in the context.

  Forward chaining and backchaining are duals.  If a rewrite rule
  requires that [47m(p1 A)[0m be established and [47m(p A)[0m is known, it could be
  done either by making [47m(implies (p x) (p1 x))[0m a [47m:forward-chaining[0m
  rule or a [47m:rewrite[0m rule.  Which should you choose?

  As a rule of thumb, if a conclusion like [47m(p1 A)[0m 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 [47m(p1 A)[0m 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.

  The following example illustrates that forward chaining may be
  indispensable in a scenario with [free-variables], whose handling
  is quite weak with rewrite rules.

    (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)))

  [3mSyntactic Restrictions[0m

  Forward chaining rules are generated from the corollary term (see
  [rule-classes]) as follows.  First, every [47m[let][0m expression is
  expanded away (hence, so is every [47m[let*][0m and [47m[lambda][0m expression),
  and trivial ``guard holders'' are removed; see [guard-holders].  If
  the resulting term has the form [47m(implies hyp concl)[0m, then [47mconcl[0m is
  treated as a conjunction, with one forward chaining rule with
  hypothesis [47mhyp[0m created for each conjunct.  In the other case, where
  the corollary term is not an [47m[implies][0m, we process it as we process
  the conclusion in the first case.

  Note that unlike rewrite rules, a nested implication is not folded
  into a single implication.  Consider for example the following
  term.

    (implies (p1 x)
             (implies (p2 x)
                      (p3 x)))

  Although this term is parsed for a rewrite rule as [47m(implies (and (p1
  x) (p2 x)) (p3 x))[0m, that is not the case when this term is parsed
  for a forward-chaining rule, in which case [47m(p1 x)[0m is treated as the
  hypothesis and [47m(implies (p2 x) (p3 x))[0m is treated as the
  conclusion.

  The [47m:trigger-terms[0m field of a [47m:forward-chaining[0m rule class object
  should be a non-empty list of terms, if provided, and should have
  certain properties described below.  If the [47m:trigger-terms[0m field is
  not provided, it defaults to the singleton list containing the
  ``atom'' of the first hypothesis of the formula.  (The atom of [47m(not
  x)[0m is [47mx[0m; the atom of any other term is the term itself.)  If there
  are no hypotheses and no [47m:trigger-terms[0m were provided, an error is
  caused.

  A triggering term is acceptable if it is not a variable, a quoted
  constant, a lambda application, a [47m[let][0m- (or [47m[let*][0m-) expression,
  or a [47m[not][0m-expression, and every variable symbol in the conclusion
  of the theorem either occurs in the hypotheses or occurs in the
  trigger.

  [3mMore Details about Forward Chaining[0m

  [47m:Forward-chaining[0m rules are used by the simplifier [3mbefore[0m 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
  type reasoning (see [TYPE-REASONING]), 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
  [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 [47m(implies (p x)
  (p (f x)))[0m, which might otherwise forward chain from [47m(p A)[0m to [47m(p (f
  A))[0m to [47m(p (f (f A)))[0m, etc.

  [3mCaution[0m.  Forward chaining does not actually add terms to the goals
  displayed during proof attempts.  Instead, it extends an associated
  [3mcontext[0m, called ``assumptions'' in the preceding paragraph, that
  ACL2 builds from the goal currently being proved.  (For insiders:
  forward chaining extends the [47m[type-alist][0m.)  The context starts out
  with ``obvious'' consequences of the negation of the goal.  For
  example, if the goal is

    (implies (and (p A) (q (f A)))
             (c A))

  then the context notes that [47m(p A)[0m and [47m(q (f A))[0m are non-[47mnil[0m and [47m(c A)[0m
  is [47mnil[0m.  Forward chaining is then used to expand the context.  For
  example, if a forward chaining rule has [47m(f x)[0m as a trigger term and
  has body [47m(implies (p x) (r (f x)))[0m, then the context is extended by
  binding [47m(r (f A))[0m to non-[47mnil[0m, provided the heuristics approve of
  this extension.  Note however that since [47m(r (f A))[0m 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.

  However, forward-chaining does support the linear arithmetic
  reasoning package.  For example, suppose that forward-chaining puts
  [47m(< (f x) (g x))[0m 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 [47mg[0m.  See
  [linear].

  Debugging [47m:forward-chaining[0m 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 [forward-chaining-reports].


Subtopics

  [Case-split]
      Like force but immediately splits the top-level goal on the
      hypothesis

  [Forward-chaining-reports]
      To see reports about the forward chaining process")
 (FORWARD-CHAINING-REPORTS
  (FORWARD-CHAINING DEBUGGING)
  "To see reports about the forward chaining process

  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!

  [3mA Quick Introduction to Forward Chaining Reports[0m

  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:

    (reset-fc-reporting)

  You can get a report about all forward chaining activity in
  subsequent proofs by doing:

    (set-fc-criteria t)

  Options will be discussed later that allow you to monitor the
  activity caused by particular [47m:forward-chaining[0m rules or terms.

  Then do a proof that is expected to cause some forward chaining.  In
  the proof output you will see lines like this:

    (Forward Chaining on behalf of PREPROCESS-CLAUSE:  (FC-Report 1))

  This is the only difference you should see in the proof output.

  After the proof attempt has terminated, you can execute:

    (fc-report k)

  for any [47mk[0m printed during the immediately preceding proof attempt.
  That will print a much longer report describing the activity that
  occurred during the [47mk[0mth use of forward chaining in that proof
  attempt.

  If you want to see these reports in real time (embedded in the proof
  output), do this before invoking the prover:

    (set-fc-report-on-the-fly t)

  Collecting the data used to generate these reports slows down the
  prover.  If you no longer wish to see such reports, do

    (set-fc-criteria nil)

  [3mHow To Read FC Reports[0m

  The report printed by [47m(fc-report k)[0m is of the form:

    Forward Chaining Report [3mk[0m:
    Caller: [3mtoken[0m
    Clause: ([3mlit1[0m [3mlit2[0m ... [3mlitn[0m)
    Number of Rounds: [3mm[0m
    Contradictionp: [3mbool[0m
    Activations: ([3mact1[0m [3mact2[0m ...)

  This report means that the [3mk[0mth use of forward chaining in the most
  recent proof attempt was done on behalf of [3mtoken[0m (see below).  The
  initial context (set of assumptions) consisted of the negations of
  the literals listed in the [clause] shown and the initial candidate
  trigger terms are all those appearing in that clause.  This
  invocation of forward chaining proceeded to do [3mm[0m rounds of
  successive extensions of the initial context and ultimately either
  reached a contradiction ([3mbool[0m = [47mT[0m) or returned an extended context
  ([3mbool[0m = [47mNIL[0m).  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.

  Forward chaining is done on behalf of many proof techniques in the
  system.  Each is associated with a [3mtoken[0m.  The main proof technique
  that uses forward chaining is [47mSIMPLIFY-CLAUSE[0m.  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 [47mPREPROCESS-CLAUSE[0m, the first process in the
  ACL2 waterfall (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 [47mINDUCT[0m, which uses forward chaining to set up a
  context for applying [47m:[0m[47m[induction][0m rules, and the definitional
  principle (and related utilities such as [47m[verify-termination][0m and
  [47m[verify-guards][0m) which uses forward chaining during the
  construction of both measure conjectures and guard conjectures.
  When used this way, the [3mtoken[0m is [47mdefun-or-guard-verification[0m.

  [3mHow to Read Activation Reports[0m

  The forward chaining report concludes with a list of activation
  reports.

    Activations: ([3mact1[0m [3mact2[0m ...)

  Each [3macti[0m is of the form:

    ([3mrune[0m
     (:TRIGGER [3minst-trig[0m)
     ((:UNIFY-SUBST [3msubst[0m)
      (:DISPOSITION [3moutcome-part1[0m [3moutcome-part2[0m [3minst-term[0m))
     ...)

  where the [47m...[0m indicates that the rest of the report consists of more
  of those tuples listing a [47m:UNIFY-SUBST[0m and [47m:DISPOSITION[0m.  We call
  each tuple a [3mdisposition[0m of the activation and each disposition
  describes a substitution [3msubst[0m identifying the final instantiation
  of the rule and how the activation fared.  Suppose there are [3mn[0m
  dispositions.  (If the rule in question contains no free variables,
  [3mn[0m will be 1.)

  This activation report means that during the forward chaining process
  in question, the [47m:[0m[47m[forward-chaining][0m [rune] [3mrune[0m was fired due to
  the presence in the evolving context of the trigger term [3minst-trig[0m.
  (Note that [3minst-trig[0m is an instantiation of the trigger term of the
  named rule.  That is, the variable symbols you see in [3minst-trig[0m are
  those of the clause printed in the forward chaining report.)  The
  activation of [3mrune[0m by [3minst-trig[0m proceeded to split [3mn[0m ways as
  different choices were made for the [free-variables] occurring
  among the hypotheses.  Each of those [3mn[0m choices gave rise to a
  different substitution [3msubst[0m, and each succeeded or failed as
  described by the corresponding [47m:DISPOSITION[0m.

  The [47m:DISPOSITION[0m of an activation is described in three parts,
  [3moutcome-part1[0m, [3moutcome-part2[0m, and [3minst-term[0m.  [3mOutcome-part1[0m is
  either [47mSUCCESS[0m or [47mBLOCKED[0m, meaning that the instance given by [3msubst[0m
  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.

  If [47moutcome-part1[0m is [47mSUCCESS[0m then [3minst-term[0m is the instantiated
  conclusion produced by the rule.  [3mOutcome-part2[0m is [47mAPPROVED[0m if the
  instantiated conclusion was acceptable to our heuristics designed
  to prevent looping and not already known in the evolving context.
  [3mOutcome-part2[0m is [47mREJECTED[0m if the instantiated conclusion was not
  approved by our heuristics.  [3mOutcome-part2[0m is [47mREDUNDANT[0m if the
  instantiated conclusion was approved by the heuristics but already
  known true in the current evolving context.  If [47mAPPROVED[0m, the truth
  of the instantiated conclusion is added to the evolving context.
  Otherwise, it is not.

  If [47moutcome-part1[0m is [47mBLOCKED[0m then [47moutcome-part2[0m is one of three
  possible things: [47mFALSE[0m, in which case [3minst-term[0m is an instantiated
  hypothesis of the rule that is assumed false in the current
  context, [47mUNRELIEVED-HYP[0m, in which case [3minst-term[0m is an instantiated
  hypothesis whose truth value is not determined by the context, or
  [47mUNRELIEVED-HYP-FREE[0m, in which case [3minst-term[0m 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 [3msubst[0m but
  extended so that free variables in the hypothesis are renamed to
  start with the prefix [47mUNBOUND-FREE-[0m to draw your attention to them.

  Note: All of the terms printed in the report are instantiated with
  the relevant unifying substitution (possibly extended to bind free
  variables).

  [3mSpecifying the Tracking Criteria[0m

  During a proof attempt, the forward chaining module stores
  information about the activations satisfying certain criteria.  The
  [3mcriteria[0m 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 [47mt[0m and that is given special significance.

  An activation [47msatisfies[0m 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
  [47mt[0m.  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 [3mcould[0m produce the instantiated
  conclusion (with the right choice of any free variables).

  Thus, the criteria is interpreted as a disjunction of conjunctions,
  making it possible to track a specific set of runes, triggers, and
  conclusions.

  For example, here is a triple that might appear in the criteria:

    ((:FORWARD-CHAINING ALISTP-FORWARD-TO-TRUE-LISTP)
     t
     t).

  This triple would cause every activation of the given rule to be
  tracked.  However, the triple

    ((:FORWARD-CHAINING ALISTP-FORWARD-TO-TRUE-LISTP)
     (ALISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S))))
     t)

  would only track activations of that rule fired by the specific term
  shown as the second element of the triple.  Furthermore

    (t
     (ALISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S))))
     t)

  would track any forward chaining rule triggered by that term, and

    (t
     t
     (TRUE-LISTP (MAKE-BINDINGS VARS (TOP-N (OP1 INST) (STACK S)))))

  would track any rule fired by any trigger that might lead to the
  specific term given as the third component above.

  Note: The condition on how an activation satisfies an instantiated
  conclusion is a little subtle.  Consider the activation of the
  forward chaining rule

    (implies (and (symbol-listp x)
                  (equal (len x) (len y)))
             (true-listp (make-bindings x y)))

  triggered by [47m(SYMBOL-LISTP VARS)[0m arising in the current context.
  This activation [3mcould[0m produce the specific conclusion shown in the
  last triple above, if it just happened that [47m(TOP-N (OP1 INST)
  (STACK S))[0m were chosen as the binding of the free variable [47my[0m.
  Thus, the activation of this rule triggered by [47m(SYMBOL-LISTP VARS)[0m
  satisfies the last triple above.

  Observe that the triple

    (t t t)

  is satisfied by every activation of any rule by any trigger term
  producing any conclusion.

  The function [47mset-fc-criteria[0m sets the criteria describing which
  activations are to be tracked.  For example, if you execute:

    (set-fc-criteria ((:FORWARD-CHAINING LEMMA1)
                      t t)
                     ((:FORWARD-CHAINING LEMMA2)
                      (ALISTP (BASIC-MAPPER A B))
                      t)
                     (t t (TRUE-LISTP (DLT D)))),

  the system would track all activations of the forward-chaining rule
  [47mLEMMA1[0m, plus those activations of forward-chaining rule [47mLEMMA2[0m
  triggered by the term given in the second triple, plus any
  activation of any rule that might derive [47m(TRUE-LISTP (DLT D))[0m.

  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.

  If the criteria is [47mnil[0m, then nothing is tracked.  Setting the
  criteria to [47mnil[0m is the way you turn off tracking and reporting of
  forward chaining activity.  You may do this either by
  [47m(set-fc-criteria)[0m or by [47m(set-fc-criteria nil)[0m.  (Technically the
  second form is an odd use of [47mset-fc-criteria[0m, which expects any
  supplied arguments to be triples; if the ``triple'' [47mnil[0m is the only
  one supplied, we take it to mean that the entire criteria should be
  [47mnil[0m.)

  To track every forward chaining activation you may set the criteria
  with either [47m(set-fc-criteria (t t t))[0m or use the abbreviation
  [47m(set-fc-criteria t)[0m.

  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 [47m:[0m[47m[brr][0m and
  [47m:[0m[47m[monitor][0m to monitor the application of a rewrite rule and then
  seeing no interactive break.)

  For some relevant functions to help you manage criteria and when the
  full reports are printed see [47m[fc-report][0m, [47m[show-fc-criteria][0m,
  [47m[set-fc-criteria][0m, [47m[reset-fc-reporting][0m, and
  [47m[set-fc-report-on-the-fly][0m.


Subtopics

  [Fc-report]
      To report on the forward chaining activity in the most recent proof

  [Reset-fc-reporting]
      Reset the forward-chaining tracking state to its initial
      configuration

  [Set-fc-criteria]
      To set the tracking criteria for forward chaining reports

  [Set-fc-report-on-the-fly]
      To determine when forward-chaining reports are printed

  [Show-fc-criteria]
      Print the forward-chaining tracking criteria")
 (FOURTH
  (NTH ACL2-BUILT-INS)
  "Fourth member of the list

  See any Common Lisp documentation for details.")
 (FP
  (DF)
  "Floating-point and ACL2

  ACL2 supports computation that uses floating-point operations; see
  [df].  If you are using an older Lisp, an attempt to build ACL2 may
  fail with an error complaining that ``feature :ieee-floating-point
  is missing'' [from the Lisp's [47m*features*[0m].  [31;1mTHIS ERROR INDICATES
  THAT ACL2 MAY BE UNSOUND WHEN BUILT ON THAT LISP![0m 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 [47mACL2_FP_OK[0m to any non-empty
  string.  You might want to do that in a script that invokes your
  Lisp.")
 (FQUOTEP (POINTERS)
          "See [system-utilities].")
 (FREE-VARIABLES
  (RULE-CLASSES REWRITE)
  "Free variables in rules

  As described elsewhere (see [rule-classes]), ACL2 rules are treated
  as implications for which there are zero or more hypotheses [47mhj[0m to
  prove.  In particular, rules of class [47m:[0m[47m[rewrite][0m may look like
  this:

    (implies (and h1 ... hn)
             (fn lhs rhs))

  Variables of [47mhi[0m are said to occur [3mfree[0m in the above [47m:rewrite[0m rule if
  they do not occur in [47mlhs[0m or in any [47mhj[0m with [47mj<i[0m.  (To be precise,
  here we are only discussing those variables that are not in the
  scope of a [47m[let][0m/[47m[let*][0m/[47mlambda[0m that binds them.)  We also refer to
  these as the [3mfree variables[0m of the rule.  ACL2 may issue a warning
  or error when there are free variables in a rule, as described
  below.  (Variables of [47mrhs[0m may be considered free if they do not
  occur in [47mlhs[0m or in any [47mhj[0m.  But we do not consider those in this
  discussion.)

  In general, the [3mfree variables[0m of rules are those variables occurring
  in their hypotheses (not [47m[let][0m/[47m[let*][0m/[47mlambda[0m-bound) that are not
  bound when the rule is applied.  For rules of class [47m:[0m[47m[linear][0m and
  [47m:[0m[47m[forward-chaining][0m, variables are bound by a trigger term.  (See
  [rule-classes] for a discussion of the [47m:trigger-terms[0m field).  For
  rules of class [47m:[0m[47m[type-prescription][0m, variables are bound by the
  [47m:typed-term[0m field.

  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
  [free-variables-examples-rewrite] for an explanation of output from
  the [break-rewrite] facility in the presence of rewriting failures
  involving free variables, as well as an example exploring ``binding
  hypotheses'' as described below.

  Let us discuss the method for relieving hypotheses of [rewrite] rules
  with free variables.  Similar considerations apply to [linear] and
  [forward-chaining] rules, and [type-prescription] rules.  Note that
  the [47m:match-free[0m mechanism discussed below does not apply to
  [type-prescription] rules.  See [free-variables-type-prescription]
  for a discussion of how to control free-variable matching for
  [type-prescription] rules.

  We begin with an example.  Does the proof of the [47m[thm][0m below succeed?

    (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)))

  Consider what happens when the proof of the [47mthm[0m is attempted.  The
  ACL2 rewriter attempts to apply rule [47mp2-trans[0m to the conclusion,
  [47m(p2 a d)[0m.  So, it binds variables [47mx[0m and [47mz[0m from the left-hand side
  of the conclusion of [47mp2-trans[0m to terms [47ma[0m and [47md[0m, respectively, and
  then attempts to relieve the hypotheses of [47mp2-trans[0m.  The first
  hypothesis of [47mp2-trans[0m, [47m(p2 x y)[0m, is considered first.  Variable [47my[0m
  is free in that hypothesis, i.e., it has not yet been bound.  Since
  [47mx[0m is bound to [47ma[0m, the rewriter looks through the context for a
  binding of [47my[0m such that [47m(p2 a y)[0m is true, and it so happens that it
  first finds the term [47m(p2 a b)[0m, thus binding [47my[0m to [47mb[0m.  Now it goes on
  to the next hypothesis, [47m(p2 y z)[0m.  At this point [47my[0m and [47mz[0m have
  already been bound to [47mb[0m and [47md[0m; but [47m(p2 b d)[0m cannot be proved.

  So, in order for the proof of the [47m[thm][0m to succeed, the rewriter
  needs to backtrack and look for another way to instantiate the
  first hypothesis of [47mp2-trans[0m.  Because [47m:match-free :all[0m has been
  specified, backtracking does take place.  This time [47my[0m is bound to
  [47mc[0m, and the subsequent instantiated hypothesis becomes [47m(p2 c d)[0m,
  which is true.  The application of rule [47m(p2-trans)[0m succeeds and the
  theorem is proved.

  If instead [47m:match-free :all[0m had been replaced by [47m:match-free :once[0m in
  rule [47mp2-trans[0m, then backtracking would not occur, and the proof of
  the [47m[thm][0m would fail.

  Next we describe in detail the steps used by the rewriter in dealing
  with free variables.

  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 [47m:forward-chaining[0m rules and step (3) is skipped for
  [47m:type-prescription[0m rules.  First, if the hypothesis is of the form
  [47m(force hyp0)[0m or [47m(case-split hyp0)[0m, then replace it with [47mhyp0[0m.

      (1) Suppose the hypothesis has the form [47m(equiv var term)[0m where [47mvar[0m is
      free and no variable of [47mterm[0m is free, and either [47mequiv[0m is
      [47m[equal][0m or else [47mequiv[0m is a known [equivalence] relation and
      [47mterm[0m is a call of [47m[double-rewrite][0m.  We call this a ``binding
      hypothesis.'' Then bind [47mvar[0m to the result of rewriting [47mterm[0m in
      the current context.

      (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.

      (3) Search all [47m[enable][0md, hypothesis-free rewrite rules of the form
      [47m(equiv lhs rhs)[0m, where [47mlhs[0m has no variables (other than those
      bound by [47m[let][0m, [47m[let*][0m, or [47mlambda[0m), [47mrhs[0m is known to be true in
      the current context, and [47mequiv[0m is typically [47mequal[0m but can be
      any equivalence relation appropriate for the current context
      (see [congruence]); then attempt to bind the free variables so
      that the instantiated hypothesis is [47mlhs[0m.

  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 ``[47m:once[0m'' or
  ``[47m:all[0m'' (the default), respectively.

  Suppose that the original hypothesis is a call of [47m[force][0m or
  [47m[case-split][0m, where forcing is enabled (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 [47m:all[0m (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.

  Is it better to specify [47m:once[0m or [47m:all[0m?  We believe that [47m:all[0m 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).

  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 [47m:all[0m) or found at all
  (in the case of [47m:once[0m).  For example, a rewrite rule like

    (implies (and (p1 x y)
                  (p2 x y))
             (equal (bar x) (bar-prime x)))

  may never succeed if [47mp1[0m is nonrecursive and enabled, since we may
  well not find calls of [47mp1[0m in the current context.  If however [47mp2[0m 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 [47m(p2 x y)[0m in the current context that therefore binds [47mx[0m and [47my[0m;
  then the rewriter's full power may be brought to bear to prove [47m(p1
  x y)[0m for that [47mx[0m and [47my[0m.

  Moreover, the ordering of hypotheses can affect the efficiency of the
  rewriter.  For example, the rule

    (implies (and (rationalp y)
                  (foo x y))
             (equal (bar x) (bar-prime x)))

  may well be sub-optimal.  Presumably the intention is to rewrite [47m(bar
  x)[0m to [47m(bar-prime x)[0m in a context where [47m(foo x y)[0m is explicitly
  known to be true for some rational number [47my[0m.  But [47my[0m 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 [47my[0m that is found
  is the first one for which [47m(foo x y)[0m is known to be true, then
  wasted work will have been done on behalf of the first 99 such
  terms [47my[0m --- unless [47m:once[0m has been specified, in which case the rule
  will simply fail after the first binding of [47my[0m for which [47m(rationalp
  y)[0m is known to be true.  Thus, a better form of the above rule is
  almost certainly the following.

    (implies (and (foo x y)
                  (rationalp y))
             (equal (bar x) (bar-prime x)))

  [3mSpecifying `once' or `all'.[0m

  As noted above, the following discussion applies only to [rewrite],
  [linear], and [forward-chaining] rules.  See
  [free-variables-type-prescription] for a discussion of analogous
  considerations for [type-prescription] rules.

  One method for specifying [47m:once[0m or [47m:all[0m for free-variable matching is
  to provide the [47m:match-free[0m field of the [47m:rule-classes[0m of the rule,
  for example, [47m(:rewrite :match-free :all)[0m.  See [rule-classes].
  However, there are global events that can be used to specify [47m:once[0m
  or [47m:all[0m; see [set-match-free-default] and see
  [add-match-free-override].  Here are some examples.

    (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

  [3mSome history.[0m Before Version 2.7 the ACL2 rewriter performed Step (2)
  above first.  More significantly, it always acted as though [47m:once[0m
  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.


Subtopics

  [Add-match-free-override]
      Set [47m:match-free[0m value to [47m:once[0m or [47m:all[0m in existing rules

  [Free-variables-examples]
      Examples pertaining to free variables in rules

  [Free-variables-type-prescription]
      Matching for free variable in [type-prescription] rules

  [Set-match-free-default]
      Provide default for [47m:match-free[0m in future rules

  [Set-match-free-error]
      Control error vs. warning when [47m:match-free[0m is missing")
 (FREE-VARIABLES-EXAMPLES
  (FREE-VARIABLES)
  "Examples pertaining to free variables in rules

  The examples in the two sub-topics of this topic illustrate the
  handling of free variables in rules of class [47m:[0m[47m[rewrite][0m (see
  [free-variables-examples-rewrite]) and of class [47m:[0m[47m[forward-chaining][0m
  (see [free-variables-examples-forward-chaining]), respectively.
  These implicitly illustrate [free-variables] handling in rules of
  class [47m:[0m[47m[linear][0m as well.  Also see [free-variables] and see
  [rule-classes].


Subtopics

  [Free-variables-examples-forward-chaining]
      Examples pertaining to free variables in [forward-chaining] rules

  [Free-variables-examples-rewrite]
      Examples pertaining to free variables in [rewrite] rules")
 (FREE-VARIABLES-EXAMPLES-FORWARD-CHAINING
  (FREE-VARIABLES-EXAMPLES)
  "Examples pertaining to free variables in [forward-chaining] rules

  The following examples illustrate ACL2's handling of free variables
  in [forward-chaining] rules, as well as user control over how such
  free variables are handled.  See [free-variables] for a background
  discussion.

    ; 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)))")
 (FREE-VARIABLES-EXAMPLES-REWRITE
  (FREE-VARIABLES-EXAMPLES)
  "Examples pertaining to free variables in [rewrite] rules

  The following examples illustrate ACL2's handling of free variables
  in [rewrite] rules, as well as user control over how such free
  variables are handled.  See [free-variables] for a background
  discussion.

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;;; 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
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

  The next example illustrates the use of the [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.

    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 >

  The [47m:eval[0m command above asks the rewriter to attempt to apply the
  rewrite rule [47mlemma-1[0m to the term [47m(prop u0)[0m, shown just above the
  line with [47m:eval[0m.  As we can see at the end, the variable [47mu[0m in the
  conclusion of [47mlemma-1[0m is being bound to the variable [47mu0[0m in the
  conjecture.  The first hypothesis of [47mlemma-1[0m is [47m(p1 u x)[0m, so the
  rewriter looks for some [47mx[0m for which [47m(p1 u0 x)[0m is known to be true.
  It finds [47mx1[0m, and then goes on to consider the second hypothesis,
  [47m(bad x)[0m.  Since the theorem we are proving has [47m(bad x1)[0m in the
  hypothesis and [47mx[0m is currently bound to [47mx1[0m, the rewriter is
  satisfied and moves on to the third hypothesis of [47mlemma-1[0m, [47m(p2 x y
  z)[0m.  However, [47mx[0m is bound to [47mx1[0m and there are no instances of [47my[0m and
  [47mz[0m for which [47m(p2 x1 y z)[0m is known in the current context.  All of
  the above analysis is summarized in the first part of the output
  from [47m:eval[0m above:

        [1] X : X1
    Failed because :HYP 3 contains free variables Y and Z, for which no
    suitable bindings were found.

  Thus, the binding of [47mx[0m to [47mx1[0m on behalf of the first hypothesis has
  failed.

  The rewriter now backs up to look for other values of [47mx[0m that satisfy
  the first hypothesis, and finds [47mx2[0m because our current theorem has
  a hypothesis of [47m(p1 u0 x2)[0m.  But this time, the second hypothesis
  of [47mlemma-1[0m, [47m(bad x)[0m, is not known to be true for [47mx[0m; that is, [47m(bad
  x2)[0m does not rewrite to [47mt[0m; in fact, it rewrites to itself.  That
  explains the next part of the output from [47m:eval[0m above:

        [1] X : X2
    Failed because :HYP 2 rewrote to (BAD X2).

  The rewriter now backs up again to look for other values of [47mx[0m that
  satisfy the first hypothesis, and finds [47mx3[0m because our current
  theorem has a hypothesis of [47m(p1 u0 x3)[0m.  This time, the second
  hypothesis of [47mlemma-1[0m is not a problem, and moreover, the rewriter
  is able to bind [47my[0m and [47mz[0m to [47my1[0m and [47mz1[0m, respectively, in order to
  satisfy the third hypothesis, [47m(p2 x y z)[0m: that is, [47m(p2 x2 y1 z1)[0m is
  known in the current context.  That explains more of the above
  output from [47m:eval[0m:

    [1] X : X3
        [3] Z : Z1
            Y : Y1

  Unfortunately, the sixth hypothesis, [47m(foo x y)[0m, rewrites to itself
  under the above bindings:

    Failed because :HYP 6 rewrote to (FOO X3 Y1).

  So the rewriter looks for other bindings to satisfy the third
  hypothesis and finds these.

    [3] Z : Z1
        Y : Y3

  This time, the sixth hypothesis can be rewritten under the above
  bindings, from [47m(foo x3 y3)[0m to [47m(poo x3 y3)[0m by lemma [47mfoo-poo[0m, but
  still not to [47mt[0m.

    Failed because :HYP 6 rewrote to (POO X3 Y3).

  There are no more free variable bindings to try, so this concludes
  the output from [47m:eval[0m.

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;;; Example 3
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

  The next pair of examples illustrates so-called ``binding
  hypotheses'' (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
  [47m[double-rewrite][0m.

  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.

    ; 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))))

  Let us look at how ACL2 uses the above binding hypothesis in the
  proof of the preceding [47mthm[0m form.  The rewriter considers the term
  [47m(g (h a))[0m and finds a match with the left-hand side of the rule
  [47mg-rewrite[0m, binding [47mx[0m to [47m(h a)[0m.  The first hypothesis binds [47my[0m to the
  result of rewriting [47m(k x)[0m in the current context, where the
  variable [47mx[0m is bound to the term [47m(h a)[0m; thus [47my[0m is bound to [47m(k (h
  a))[0m.  The second hypothesis, [47m(f y)[0m, is then rewritten under this
  binding, and the result is [47mt[0m by application of the rewrite rule
  [47mf-k-h[0m.  The rule [47mg-rewrite[0m is then applied under the
  already-mentioned binding of [47mx[0m to [47m(h a)[0m.  This rule application
  triggers a recursive rewrite of the right-hand side of [47mg-rewrite[0m,
  which is [47my[0m, in a context where [47my[0m is bound (as discussed above) to
  [47m(k (h a))[0m.  The result of this rewrite is that same term, [47m(k (h
  a))[0m.  The original call of [47mequal[0m then trivially rewrites to [47mt[0m.

  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 [47m:equivalence[0m rules; see [equivalence].

  Recall that when a hypothesis is a call of an equivalence relation
  other than [47mequal[0m, the second argument must be a call of
  [47m[double-rewrite][0m in order for the hypothesis to be treated as a
  binding hypothesis.  That is indeed the case below; an explanation
  follows.

    ; 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)))

  The proof succeeds much as in the first example, but the following
  observation is key: when ACL2 binds [47my[0m upon considering the first
  hypothesis of [47mlemma-3[0m, it rewrites the term [47m(double-rewrite x)[0m in a
  context where it need only preserve the equivalence relation
  [47mmy-equiv[0m.  At this point, [47mx[0m is bound by applying [47mlemma-3[0m to the
  term [47m(g (h1 a))[0m; so, [47mx[0m is bound to [47m(h1 a)[0m.  The rule [47mlemma-1[0m then
  applies to rewrite this occurrence of [47mx[0m to [47m(h2 a)[0m, but only because
  it suffices to preserve [47mmy-equiv[0m.  Thus [47my[0m is ultimately bound to
  [47m(h2 a)[0m, and the proof succeeds as one would expect.

  If we tweak the above example slightly by disabling the user's
  [equivalence] [rune], then the proof of the [47m[thm][0m form fails
  because the above rewrite of [47m(double-rewrite x)[0m is done in a
  context where it no longer suffices to preserve [47mmy-equiv[0m as we dive
  into the second argument of [47mmy-equiv[0m in the first hypothesis of
  [47mlemma-3[0m; so, [47mlemma-1[0m does not apply this time.

    (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)))")
 (FREE-VARIABLES-TYPE-PRESCRIPTION
  (FREE-VARIABLES)
  "Matching for free variable in [type-prescription] rules

  We assume familiarity with the issue of dealing with free variables
  in hypotheses; see [free-variables].

  By default, starting with Version 4.3, ACL2 attempts all possible
  matches for free variables.  Consider the following example.

    (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)))

  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 [3mtype-prescription[0m [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,
  [47moncep-ts[0m.  The following examples are intended to explain how this
  works.

  First, let us disallow all multiple matching of free variables (i.e.,
  implement the behavior often referred to as ``[47m:match-free :once[0m'';
  see [free-variables]).

    (defun oncep-tp-always (rune wrld)
      (declare (ignore rune wrld)
               (xargs :mode :logic :guard t))
      t)

    (defattach-system oncep-tp oncep-tp-always)

  The second [47mthm[0m form above will now fail, because only one
  free-variable match is permitted for the first hypothesis of rule
  [47mf1-prop[0m above.

  Now suppose that instead, we want to disallow multiple matches for
  free variables in hypotheses of type-prescription rules [3mexcept[0m for
  the rule [47mf1-prop[0m above.  With the following events, the second [47mthm[0m
  form above once again succeeds.

    (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)

  In general, your [47m[defattach][0m event will attach a function symbol to
  [47moncep-tp[0m.  The [guard] of that function symbol must be implied by
  the guard of [47moncep-tp[0m:

    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 !>")
 (FREE_VARIABLES_IN_TOP-LEVEL_INPUT
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Free Variables in Top-Level Input

    ACL2 !>[31;1m(equal (app (app a b) c)[0m
                  [31;1m(app a (app b c))))[0m

    ACL2 Error in TOP-LEVEL:  Global variables, such as C, B, and A, are
    not allowed. See :DOC ASSIGN and :DOC @.

  ACL2 does not allow ``global variables'' in top-level input.  There
  is no ``top-level binding environment'' to give meaning to these
  variables.

  Thus, expressions involving no variables can generally be evaluated,

    ACL2 !>[31;1m(equal (app (app '(1 2) '(3 4)) '(5 6))[0m
                  [31;1m(app '(1 2) (app '(3 4) '(5 6))))[0m
    (1 2 3 4 5 6)

  but expressions containing variables cannot.

  There is an exception to this rule.  References to ``single-threaded
  objects'' may appear in top-level forms.  See [stobj] {ICON} (see
  [A_Tiny_Warning_Sign]).  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.''

  The most commonly used single-threaded object in ACL2 is the ACL2
  system state, whose current value is always held in the variable
  [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign]).

  ACL2 provides a way for you to use [47mstate[0m to save values of
  computations at the top-level and refer to them later.  See
  [assign] {ICON} (see [A_Tiny_Warning_Sign]) and [@] {ICON} (see
  [A_Tiny_Warning_Sign]).")
 (FREQUENTLY-ASKED-QUESTIONS-BY-NEWCOMERS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Some questions newcomers frequently ask

  This FAQ is for people who've read through all the other sections of
  the tutorial introduction to the theorem prover (see
  [introduction-to-the-theorem-prover] and all the links from it that
  are not marked with the little warning sign (``{ICON} (see
  [A_Tiny_Warning_Sign])'').  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 ``{ICON} (see
  [A_Tiny_Warning_Sign])'' 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.

  [31;1mQ[0m.  How do I find something in the [31;1mACL2 documentation[0m?  [31;1mA[0m.  Try the
  ``Jump to'' or ``Search'' boxes at the {ACL2+Books Manual |
  http://www.cs.utexas.edu/users/moore/acl2/current/combined-manual/index.html}.

  [31;1mQ[0m.  How does the theorem prover work?  [31;1mA[0m.  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
  [introduction-to-the-theorem-prover] is about.  However, if you
  want the most basic overview of the prover, see
  [architecture-of-the-prover].

  [31;1mQ[0m. How do I [31;1mdefine a new function[0m?  [31;1mA[0m. See [defun].

  [31;1mQ[0m. How do I [31;1mdefine a new predicate[0m?  [31;1mA[0m. See [defun].

  [31;1mQ[0m. How do I [31;1mdefine a new relation[0m?  [31;1mA[0m. See [defun].

  [31;1mQ[0m. How do I define a [31;1mfunction or predicate that takes a varying
  number of arguments[0m?  [31;1mA[0m. You can't.  However, 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.

  [31;1mQ[0m. How do I define a [31;1mmacro that is sensitive to the state[0m?  [31;1mA[0m.  You
  can't.  However, advanced users should consider [47m[make-event][0m.

  [31;1mQ[0m. How do I define [31;1mmutually recursive[0m functions?  [31;1mA[0m.  See
  [mutual-recursion].  However, you should realize that when two
  functions, say [47mf[0m and [47mg[0m, are mutually recursive, properties of [47mf[0m
  generally have to be stated simultaneously with properties of [47mg[0m,
  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 [mutual-recursion-proof-example].

  [31;1mQ[0m. How do I declare the [31;1mtype signature of a function[0m?  [31;1mA[0m.  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 [3mguard[0m 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 ---
  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 [3mguard conjectures[0m and the process of
  proving them is called [3mguard verification[0m.  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 [47mdefun[0m-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 [31;1mstrongly[0m 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 [guard].

  [31;1mQ[0m. How do I tell [47mdefun[0m [31;1mwhat measure to use[0m?  [31;1mA[0m. See [xargs],
  specifically [47m:measure[0m.

  [31;1mQ[0m.  I specified a measure that always returns a natural number but
  ACL2 is acting like it's not a natural number.  [31;1mA[0m.  There are two
  likely problems.  The most likely one is that your measure isn't
  really always a natural!  Suppose the formals of your [47mdefun[0m are [47mx[0m
  and [47my[0m and your measure is [47m(m x y)[0m.  Suppose the recursive calls of
  your function are protected by tests that ensure that [47mx[0m and [47my[0m are
  naturals.  Then you might assume [47mx[0m and [47my[0m are naturals in the
  measure.  But ACL2 has to prove [47m(o-p (m x y))[0m, where [47m[o-p][0m 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 [47m[nfix][0m
  around it or around its uses of [47mx[0m and [47my[0m 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 [47mm[0m involves some
  recursive functions.  In this case, prove [47m(natp (m x y))[0m before
  your [47mdefun[0m.  Perhaps you should consider making the [47mnatp[0m lemma a
  [47m:[0m[47m[type-prescription][0m lemma to make ACL2's typing algorithm aware of
  it.

  [31;1mQ[0m. How do I tell [47mdefun[0m [31;1mwhat well-founded relation to use[0m?  [31;1mA[0m. See
  [xargs], specifically [47m:well-founded-relation[0m.

  [31;1mQ[0m. How do I show that a [31;1mrelation is well-founded[0m?  [31;1mA[0m. Prove a theorem
  establishing that there is an order preserving embedding into the
  ordinals and store it with [47m:rule-classes[0m [47m:well-founded-relation[0m
  [well-founded-relation-rule].

  [31;1mQ[0m.  What is an [31;1mordinal[0m?  What does it mean to be [31;1mwell-founded[0m?  [31;1mA[0m.
  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 [3mwell-founded[0m.  See [47m[o-p][0m for more
  information about ordinals in ACL2 and about well-foundedness.  See
  [ordinals] for a deeper discussion and a discussion of books that
  can help configure ACL2 to reason about ordinals.

  [31;1mQ[0m. How can provide [31;1mhints for the termination proofs[0m in [47mdefun[0m?  [31;1mA[0m. See
  [xargs], specifically [47m:hints[0m (for the termination proofs) and
  [47m:guard-hints[0m (for the guard verification proofs).

  [31;1mQ[0m. How do I define a [31;1mconstant[0m (something like a [31;1mglobal variable[0m)?  [31;1mA[0m.
  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!

  [31;1mQ[0m. How do I save the value of a top-level computation for future use?
  [31;1mA[0m. See [assign] and see [@].

  [31;1mQ[0m. How do I introduce [31;1mnew syntactic form[0m or [31;1mabbreviation[0m?  [31;1mA[0m. See
  [defmacro].

  [31;1mQ[0m.  How can create and modify an array?  [31;1mA[0m.  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 [arrays], provided you use them in a restricted way.  They give
  you constant-time access and change under the use restrictions.

  [31;1mQ[0m.  How do I read from or write to a file?  How do I do IO?  [31;1mA[0m.  To
  manipulate files, your function must have [47m[state][0m as an argument,
  so you should read about the restrictions that imposes.  For
  input/output facilities, see [io].

  [31;1mQ[0m. How do I define a [31;1mstructure that can be destructively modified[0m?
  [31;1mA[0m. ACL2 is an [3mapplicative programming language[0m.  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 [47mcar[0m of some object is [47m1[0m at
  one moment and [47m2[0m later, then the basic logical axiom [47m(car x)[0m = [47m(car
  x)[0m is violated!  However, if the only reference to the old object,
  e.g., [3mx[0m, 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 [3mx[0m a
  modifiable structure but they will impose a heavy burden on you as
  a programmer: if pass such an [3mx[0m to a function and the function
  modifies it, then you must pass [3mx[0m only to that function and you
  must return the modified value and use it henceforth.  Such objects
  are said to be [3msingle threaded[0m.  See [defstobj].

  [31;1mQ[0m.  How do I write a universal quantifier?  An existential
  quantifier?  How can I say ``for all'' or ``there exists''?  [31;1mA[0m You
  can't literally write quantifiers.  But ACL2 has the power of full
  first order logic with quantification.  See [quantifiers].

  [31;1mQ[0m.  How do I introduce an undefined or uninterpreted function symbol?
  Can I constrain it to have certain properties?  [31;1mA[0m.  See
  [encapsulate].

  [31;1mQ[0m.  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.
  [31;1mA[0m.  One way to get a similar effect is to prove the lemma and then
  disable it with an [47m(in-theory (disable ...))[0m event; see
  [in-theory].  Another way is to put the lemma and the theorem that
  needs it into an [47m[encapsulate][0m and wrap a [47m[local][0m around the lemma.

  [31;1mQ[0m. What is an [31;1mevent[0m?  [31;1mA[0m. An [3mevent[0m is a command that adds information
  to the ACL2 database (the ``logical world''), like [47mdefun[0m or [47mdefthm[0m.
  See [events].

  [31;1mQ[0m. How do I say that I [31;1mdo not want a rewrite rule[0m generated from a
  theorem?  [31;1mA[0m. The command

    (defthm [3mname[0m [3mformula[0m
            :rule-classes nil)

  will attempt to prove [3mformula[0m and, if successful, give [3mformula[0m the
  name [3mname[0m, which you may use in hints as a theorem, but it will
  build no rules from the formula.

  [31;1mQ[0m. How do I say that I want a formula to be [31;1mstored as a rewrite rule[0m?
  [31;1mA[0m. The command

    (defthm [3mname[0m [3mformula[0m)

  will attempt to prove [3mformula[0m and, if successful, it will give
  [3mformula[0m the name [3mname[0m and generate a rewrite rule from it, with the
  runic name [47m(:rewrite [0m[3mname[0m)].  It could happen that [3mformula[0m
  generates more than one rewrite rule, e.g., this happens if the
  conclusion is an [47mAND[0m.  In this case, each conjunctive branch
  through the conclusion generates a rule named [47m(:rewrite [0m[3mname[0m[47m . i)[0m,
  for [3mi[0m=1,2,...  For more details, see [rewrite].

  [31;1mQ[0m. How do I say that I want a formula to be [31;1mstored as a rewrite rule[0m
  [31;1mand some other kinds of rules[0m?  [31;1mA[0m. The command

    (defthm [3mname[0m [3mformula[0m
            :rule-classes ([3m:class1[0m ... [3mclassk[0m))

  will attempt to prove [3mformula[0m and, if successful, it will give
  [3mformula[0m the name [3mname[0m and generate a rule of each [3m:classi[0m
  specified.  Each [3m:classi[0m should either be a keyword, like [47m:REWRITE[0m
  or [47m:GENERALIZE[0m, naming a rule class (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 [47m:REWRITE[0m among the rule
  classes if you want the formula to generate a rewrite rule.  It
  doesn't do that automatically if you explicitly specify
  [47m:rule-classes[0m!

  [31;1mQ[0m. How do I [31;1mrearrange[0m the shape of a formula before generating a rule
  from it?  [31;1mA[0m. See [rule-classes] and read about the [47m:corollary[0m
  modifier.

  [31;1mQ[0m. What is a [31;1mtype-prescription[0m?  [31;1mA[0m. 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 [type-prescription].

  [31;1mQ[0m. How do [31;1mrewrite rules work[0m?  [31;1mA[0m. Re-read the tutorial sections:
  [introduction-to-rewrite-rules-part-1] and
  [introduction-to-rewrite-rules-part-2].

  [31;1mQ[0m. How do I [31;1msee what's in the database[0m?  [31;1mA[0m. 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 [history].
  If you have loaded a book from another user, you might wish to read
  the source file.  For example, the source file for [47m(include-book
  \"arithmetic-5/top\" :dir :system)[0m is the file named
  [47marithmetic-5/top.lisp[0m on the [47macl2-sources/books/[0m directory where
  ever your ACL2 sources are installed.  Often, books are
  well-documented by comments by their authors.  Some books have
  [47mReadme[0m or [47mREADME[0m files on the same directory.

  [31;1mQ[0m. How do I [31;1mundo[0m a command?  [31;1mA[0m. See [history], especially see [u]
  (``undo'') and see [ubt] (``undo back through''). [31;1mQ[0m. What [31;1mrewrite
  rules match[0m a given term?  [31;1mA[0m. See [pl].

  [31;1mQ[0m.  What were those [31;1mquestions to ask when looking at key checkpoints[0m?
  [31;1mA[0m.  See [introduction-to-key-checkpoints].

  [31;1mQ[0m. How do I figure out [31;1mwhy a rewrite rule won't fire[0m?  [31;1mA[0m. If you
  activate rewrite rule monitoring (see [brr]) and then install a
  monitor (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 [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.

  [31;1mQ[0m. [31;1mWhy is a proof taking so long?[0m [31;1mA[0m. Unexpectedly poor performance on
  simple problems is usually a sign of cyclic rewriting or
  combinatoric explosion.  See [dmr] and see
  [accumulated-persistence].

  [31;1mQ[0m. How do I tell ACL2 [31;1mwhat induction to do[0m for a particular formula?
  [31;1mA[0m. When issuing the [47mdefthm[0m command for the formula, supply an
  [47m:induct[0m hint:

    (defthm [3mname[0m
            [3mformula[0m
            :hints ((\"Goal\" :induct (f x1 ... xn))))

  where [47mf[0m is a function that recurs the way you want the induction to
  unfold and [47mx1 ... xn[0m are the relevant variables in [3mformula[0m.  You
  usually have to define [47mf[0m appropriately for each formula that needs
  an induct hint, though sometimes you can re-use an earlier [47mf[0m or one
  of the functions in the formula itself.  It doesn't matter what
  value [47m(f x1 ... xn)[0m returns.  All that matters is how it recurs.
  The termination analysis for [47mf[0m justifies the induction done.  See
  [hints], especially the section on [47m:induct[0m hints; also see
  [induction].

  [31;1mQ[0m. ACL2 doesn't know [31;1msimple arithmetic[0m that can simplify the term [47m(+
  1 -1 x)[0m.  [31;1mA[0m.  You should load an arithmetic book whenever you're
  dealing with an arithmetic problem.  The simplest arithmetic book
  is typically loaded with the event [47m(include-book
  \"arithmetic/top-with-meta\" :dir :system)[0m.  If you're using [47mfloor[0m
  and [47mmod[0m or non-linear arithmetic like [47m(* x y)[0m you should use
  [47m(include-book \"arithmetic-5/top\" :dir :system)[0m.  See also the
  discussion of arithmetic books under the ``Lemma Libraries and
  Utilities'' link of the ACL2 home page, and see [community-books].

  [31;1mQ[0m. ACL2 is not using an [31;1marithmetic lemma[0m that I proved.  [31;1mA[0m. Lemmas
  concluding with arithmetic inequalities, like

    (implies (member e x)
             (< (len (delete e x)) (len x)))

  are not good rewrite rules because they rarely match targets because
  of intervening arithmetic operators.  For example, the above
  conclusion doesn't match [47m(< (LEN (DELETE E X)) (+ 1 (LEN X)))[0m.  You
  should store such lemmas as [47m:linear[0m rules by using the command:

    (defthm len-delete
      (implies (member e x)
               (< (len (delete e x)) (len x)))
      :rule-classes :linear)

  See [linear].

  [31;1mQ[0m.  What is a [31;1mlinear rule[0m?  [31;1mA[0m.  See [linear].

  [31;1mQ[0m. How do I make ACL2 [31;1mtreat a relation as an equality[0m?  [31;1mA[0m. 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
  [equivalence], see [congruence], and see [refinement].

  [31;1mQ[0m. One of my rewrite rules has a [31;1mhypothesis that doesn't rewrite[0m to
  true.  What do I do?  [31;1mA[0m. 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 [47m[force][0m 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
  [47m[case-split][0m.  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 [47mIF[0ms; see
  [strong-rewrite-rules].

  [31;1mQ[0m. How do I make ACL2 ``guess'' the [31;1mright instantiation of a free
  variable[0m?  [31;1mA[0m. You can provide a [47m:restrict[0m hint that names the
  problematic lemma and provides an instantiation of the free
  variable.  See [hints], specifically [47m:restrict[0m.  You could
  alternatively give a hint that [47m:uses[0m the rule and provides the
  appropriate instantiation in full.  See [hints], specifically [47m:use[0m.
  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 [47m:match-free :all[0m modifier of the [47m:rewrite[0m
  or [47m:linear[0m rule class.  See [rule-classes].  Alternatively, undo
  and prove the problematic rule again and use a [47m[bind-free][0m form to
  compute the appropriate instantiation.

  [31;1mQ[0m. How can I make ACL2 do a [31;1mcase split[0m to prove a certain subgoal?
  [31;1mA[0m. See [hints], specifically [47m:cases[0m.

  [31;1mQ[0m. How can I [31;1mprevent ACL2 from using a rewrite rule[0m?  [31;1mA[0m.  See
  [hints], specifically [47m:in-theory (disable ...)[0m.  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., [47m\"Subgoal 1/3.2.1\"[0m) as the
  goal specifier in the hint.  If the rule isn't needed anywhere in
  the proof, you could use the specifier [47m\"Goal\"[0m.  If you don't think
  the rule will ever be needed for a while, you could globally
  disable it with the event [47m(in-theory (disable ...))[0m (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 [47m:[0m[47m[rule-classes][0m [47mnil[0m.

  [31;1mQ[0m.  How can I prevent ACL2 from running a definition on constants?  I
  tried disabling the function but that didn't work.  [31;1mA[0m.  If you have
  a function named [47mf[0m then disabling [47mf[0m will disable the definitional
  axiom about [47mf[0m.  But ACL2 has another kind of rule about [47mf[0m, telling
  it how to evaluate [47mf[0m.  The [rune] of this rule is
  [47m(:executable-counterpart f)[0m.  Try disabling that, as in the
  [47m:[0m[47m[hints][0m [47m(([0m...  [47m:in-theory (disable (:executable-counterpart f))
  ...c[))[0m.

  [31;1mQ[0m. How can I make ACL2 [31;1muse a rule[0m in a proof?  [31;1mA[0m. See [hints],
  specifically [47m:use[0m.

  [31;1mQ[0m.  How can I make ACL2 expand a function call in a proof?  [31;1mA[0m.  You
  can give an [47m:[0mSee [expand] hint.

  [31;1mQ[0m.  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?  [31;1mA[0m. See [otf-flg], which stands for Onward Thru the
  Fog FLaG.

  [31;1mQ[0m. How can I [31;1mcompute when I want a rule to fire[0m?  [31;1mA[0m.  See [syntaxp].

  [31;1mQ[0m.  How can I add [31;1mpragmatic advice to a lemma after it has been
  proved[0m?  For example, how can add a forced hypothesis, a backchain
  limit, or a [47msyntaxp[0m test?  [31;1mA[0m.  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 --- a task that should be easy since the old
  version is in the database and will presumably make the proof
  trivial --- and then disable the old name.

  [31;1mQ[0m. How can I [31;1mstop ACL2 from rewriting a term[0m?  [31;1mA[0m. If you need
  rewriting done but want to prevent some particular terms from being
  rewritten, see [hints], specifically [47m:hands-off[0m.  Alternatively,
  consider embedding the problematic term in a [47m[hide][0m.  Users
  sometime develop special theories (see [theory]) containing just
  the rules they want and then use hints to switch to those theories
  on the appropriate subgoals.

  [31;1mQ[0m.  Can I [31;1mcompute which subgoals a hint refers to[0m?  [31;1mA[0m.  Yes, see
  [computed-hints].  This topic is for advanced users but knowing
  that it is possible might come in handy someday.

  [31;1mQ[0m.  I want the rewriter to [31;1malways use one theory and then switch to
  another[0m so that it doesn't use my most complicated before until
  doing the simple things.  [31;1mA[0m.  This is possible but is something for
  the advanced user.  It can be done using a form of
  [computed-hints].  See [using-computed-hints-7].

  [31;1mQ[0m.  Is there a way to attach [31;1mthe same hint to every defthm[0m?  [31;1mA[0m.  See
  [default-hints].

  [31;1mQ[0m.  How can I just tell ACL2 the proof steps?  [31;1mA[0m.  See [verify] and
  see [proof-builder].

  [31;1mQ[0m. How can I write [31;1mmy own simplifier[0m?  [31;1mA[0m.  See [meta].

  [31;1mQ[0m. How can I add an axiom or just assume some lemma without proof?
  [31;1mA[0m. 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 [defaxiom] and see
  [skip-proofs].

  [31;1mQ[0m. How can redefine a user-defined function?  [31;1mA[0m.  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
  [ld-redefinition-action] (and note specifically the discussion of
  updater function for it, [47mset-ld-redefinition-action[0m); also see
  [redef], see [redef!], see [redef+], and see [redef-].

  [31;1mQ[0m. How do I [31;1mchange a function from[0m [47m:program[0m [31;1mmode to[0m [47m:logic[0m [31;1mmode[0m?  [31;1mA[0m.
  See [verify-termination].

  [31;1mQ[0m. How do I [31;1mchange the guards[0m on a function?  [31;1mA[0m. You can't.  Undo it
  and redefine it.

  [31;1mQ[0m. What is [31;1mprogram mode[0m?  [31;1mA[0m. See [program].

  [31;1mQ[0m. What does the ACL2 [31;1mprompt[0m mean?  [31;1mA[0m.  See
  [introduction-to-a-few-system-considerations] or, specifically, see
  [prompt].

  [31;1mQ[0m. What is [31;1mlogic mode[0m?  [31;1mA[0m. See [logic].

  [31;1mQ[0m. How do I [31;1mget into or out of[0m [47m:program[0m [31;1mmode?[0m [47m:Logic[0m [31;1mmode?[0m [31;1mA[0m. See
  [program] and see [logic].  You can enter these modes temporarily
  for a particular [47m[defun][0m by using [47m(declare (xargs :mode :program))[0m
  or [47m(declare (xargs :mode :logic))[0m after the list of formal
  parameters to the definition.

  [31;1mQ[0m.  How do I quit from ACL2?  [31;1mA[0m.  This varies depending on the
  interface you're using.  See
  [introduction-to-a-few-system-considerations].

  [31;1mQ[0m. How do I [31;1mload a file[0m of definitions and theorems created by
  someone else?  [31;1mA[0m. See [include-book].

  [31;1mQ[0m. How do I [31;1mcreate my own book[0m of definitions and theorems?  [31;1mA[0m. See
  [books].

  [31;1mQ[0m. Where are the books referenced by [31;1m:dir :system[0m on my machine?  [31;1mA[0m.
  If your ACL2 is installed on the directory [3mdir[0m[47m/acl2-sources[0m and you
  follow the standard installation instructions, then the books are
  typically the files under the directory [3mdir[0m[47m/acl2-sources/books/[0m.

  [31;1mQ[0m. How can I find out [31;1mwhat books are available[0m?  [31;1mA[0m. Go to the ACL2
  home page, [47mhttp://www.cs.utexas.edu/u/moore/acl2/[0m and look at the
  link labeled ``Lemma Libraries and Utilities.''

  [31;1mQ[0m. How do I [31;1mproduce my own book[0m?  [31;1mA[0m. See [books].

  [31;1mQ[0m. What is a [31;1mdecision procedure[0m?  What [31;1mdecision procedures does ACL2
  have[0m?  [31;1mA[0m. A [3mdecision procedure[0m 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 [47mand[0m, [47mor[0m, [47mnot[0m, [47mimplies[0m, [47miff[0m, and [47mif[0m.  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 --- but is not
  guaranteed to be faster.  ACL2 also contains an optional [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 ([47m<[0m, [47m<=[0m, [47m>=[0m, and [47m>[0m).  It can be
  extended with [47m:[0m[47m[linear][0m 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 [clause-processor].

  [31;1mQ[0m. ACL2 has the [31;1mchange of variable[0m trick ([31;1mdestructor elimination[0m)
  that it does to get rid of [47m(CAR X)[0m and [47m(CDR X)[0m by replacing [47mx[0m by
  [47m(CONS A B)[0m.  Is there a way to make ACL2 do that for other terms?
  [31;1mA[0m. Yes.  See [elim].

  [31;1mQ[0m. How can I [31;1mprevent destructor elimination[0m?  [31;1mA[0m. See [hints],
  specifically [47m:do-not '(eliminate-destructors)[0m.

  [31;1mQ[0m. How can I [31;1mprevent cross-fertilization[0m?  [31;1mA[0m. See [hints],
  specifically [47m:do-not '(fertilize)[0m.

  [31;1mQ[0m. How can I [31;1mprevent generalization[0m?  [31;1mA[0m. See [hints], specifically
  [47m:do-not '(generalize)[0m.

  [31;1mQ[0m. How can I make ACL2 [31;1mimpose a restriction on a new variable[0m
  introduced by destructor elimination or generalization?  [31;1mA[0m.  See
  [generalize].

  [31;1mQ[0m. What [31;1mrule classes[0m are there?  [31;1mA[0m. See [rule-classes].

  [31;1mQ[0m. What is a [31;1mtheory[0m?  [31;1mA[0m. See [theories].

  [31;1mQ[0m. How are [31;1mhints inherited by the children of a subgoal[0m?  [31;1mA[0m. See
  [hints-and-the-waterfall].

  [31;1mQ[0m.  How do I use ACL2 under [31;1mEmacs[0m?  [31;1mA[0m. See [emacs].

  [31;1mQ[0m.  How do I use ACL2 under [31;1mEclipse[0m?  [31;1mA[0m. See [ACL2-Sedan].

  [31;1mQ[0m.  How do I interrupt the prover?  [31;1mA[0m.  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 --- that is, you have to type the
  previously mentioned sequence twice in succession.  If you are
  running the ACL2 Sedan, you can use the [3mInterrupt Session[0m 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 [47m:q[0m or [47m:a[0m.  You can usually
  determine what environment you're in by paying attention to the
  prompt.

  [31;1mQ[0m.  What is the [31;1mACL2 loop[0m?  [31;1mA[0m.  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
  [introduction-to-a-few-system-considerations].

  [31;1mQ[0m.  What is [31;1mraw lisp[0m?  [31;1mA[0m.  That is our name for the host Common Lisp
  in which ACL2 is implemented.  See
  [introduction-to-a-few-system-considerations].  There is an ACL2
  mode named [3mraw mode[0m which is different from ``raw lisp.'' See
  [set-raw-mode].

  [31;1mQ[0m.  Can I get a tree-like view of a proof?  [31;1mA[0m.  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.

  [31;1mQ[0m.  I used the earlier Boyer-Moore theorem prover, Nqthm.  How is
  ACL2 different?  [31;1mA[0m. See [nqthm-to-ACL2].

  If you are reading this as part of the tutorial introduction to the
  theorem prover, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-the-theorem-prover].")
 (FROM-DF (POINTERS) "See [df].")
 (FSUBCOR-VAR (POINTERS)
              "See [system-utilities].")
 (FULL-BOOK-NAME
  (BOOKS-REFERENCE)
  "Book naming conventions assumed by ACL2

  See [pathname] for background on ACL2 pathnames.

  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
  [3m[sysfile][0m; but until then, our discussion of full-book-names is
  restricted to the special (but common) case of full-book-strings.

  A full-book-name string may be divided into contiguous sections: a
  ``directory string'', a ``familiar name'' and an ``extension''.
  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:

    \"/usr/home/smith/project/arith.lisp\"

    \"/usr/home/smith/project/\"           ; directory string
                            \"arith\"      ; familiar name
                                 \".lisp\" ; extension

  The sections are marked by the rightmost slash and rightmost dot, as
  shown below.

    \"/usr/home/smith/project/arith.lisp\"
                            |     |
                            slash dot
                            |     |
    \"/usr/home/smith/project/\"           ; directory string
                            \"arith\"      ; familiar name
                                 \".lisp\" ; extension

  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.

  We conclude by discussing the other representation of full-book-names
  as promised above: the sysfile, which is a pair of the form [47m(:kwd .
  \"relpath\")[0m where [47m:kwd[0m is a [keyword] and [47m\"relpath\"[0m is a relative
  pathname string.  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 [certificate] files and in various
  data structures in the ACL2 logical [world].")
 (FUNCTION-SYMBOLP (POINTERS)
                   "See [system-utilities].")
 (FUNCTION-THEORY
  (THEORIES THEORY-FUNCTIONS)
  "Function symbol rules as of logical name

    Examples:
    (function-theory :here)
    (function-theory 'lemma3)

  See [logical-name].

    General Form:
    (function-theory logical-name)

  Returns the theory containing all the [47m:[0m[47m[definition][0m [rune]s, whether
  [enable]d or not, that existed immediately after [47m[logical-name][0m was
  introduced.  See the documentation for [theories], [logical-name]
  and [47m[executable-counterpart-theory][0m.

  You may experience a fencepost problem in deciding which logical name
  to use.  [47m[Deflabel][0m can always be used to mark unambiguously for
  future reference a particular point in the development of your
  theory.  The order of [events] in the vicinity of an [47m[encapsulate][0m
  is confusing.  See [encapsulate].

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].")
 (FUNCTIONAL-INSTANTIATION
  (ENCAPSULATE)
  "An analogue in ACL2 of higher-order logical reasoning.  Functional
  instantiation allows you to prove theorems ``by analogy'' with
  previous theorems.  See [hints] and see [lemma-instance].


Subtopics

  [Functional-instantiation-example]
      A small proof demonstrating functional instantiation

  [Functional-instantiation-in-ACL2r]
      Additional requirements for [47m:functional-instance[0m hints in ACL2(r)

  [Lemma-instance]
      An object denoting an instance of a theorem")
 (FUNCTIONAL-INSTANTIATION-EXAMPLE
  (FUNCTIONAL-INSTANTIATION TUTORIAL5-MISCELLANEOUS-EXAMPLES)
  "A small proof demonstrating functional instantiation

  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.

  The details of the proof (such as the [47m[in-theory][0m event and
  particulars of the lemmas) are not the point here.  Rather, the
  point is to demonstrate the interaction of [47m[encapsulate][0m [events]
  and [47m:functional-instance[0m [lemma-instance]s.  Of course, if you are
  interested in details then you may find it helpful to run these
  [events] through ACL2.

  Also see [constraint] for more about [47m:functional-instance[0m and see
  [lemma-instance] for general information about the use of
  previously-proved lemmas.

    (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))))))")
 (FUNCTIONAL-INSTANTIATION-IN-ACL2R
  (FUNCTIONAL-INSTANTIATION)
  "Additional requirements for [47m:functional-instance[0m hints in ACL2(r)

  This documentation topic relates to ACL2(r), the modification of ACL2
  that supports the real numbers (see [real]).

  See [hints] and see [lemma-instance] for a discussion of [47m:use[0m hints
  that employ the [47m:functional-instance[0m keyword.  Here, we document
  additional requirements for such hints that applies to ACL2(r).  We
  assume familiarity with lemma instances; see [lemma-instance].

  (1) When functionally instantiating a non-classical formula, it is
  illegal to use pseudo-lambda expressions in a lemma instance.

  (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.")
 (FUNCTIONS_FOR_MANIPULATING_THESE_OBJECTS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Functions for Manipulating these Objects

  {IMAGE} (see [Modeling_in_ACL2])

  Consider a typical ``stack'' of control frames.

  {IMAGE}

  Suppose the model required that we express the idea of ``the most
  recent frame whose return program counter points into [47mMAIN[0m.''

  The natural expression of this notion involves

  [31;1mfunction application[0m --- ``fetch the [47mreturn-pc[0m of this frame''

  [31;1mcase analysis[0m --- ``[31;1mif[0m the pc is [47mMAIN[0m, [31;1mthen[0m ...''

  [31;1miteration[0m or [31;1mrecursion[0m --- ``pop this frame off and repeat.''

  The designers of ACL2 have taken the position that a [31;1mprogramming[0m
  [31;1mlanguage[0m is the natural language in which to define such notions,
  [31;1mprovided[0m the language has a mathematical foundation so that models
  can be analyzed and properties derived logically.

  Common Lisp is the language supported by ACL2.  To be precise, a
  small applicative subset of Common Lisp is the language supported
  by ACL2.

  {IMAGE} (see [Modeling_in_ACL2])")
 (FURTHER-INFORMATION-ON-REWRITING
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A grab bag of advice and information on rewriting

  In the following paragraphs we give some links to advanced topics,
  marked with ``{ICON} (see [A_Tiny_Warning_Sign])''.  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.

  [Arithmetic]: If your goal theorem involves even trivial arithmetic,
  such as adding or subtracting [47m1[0m, we recommend that you do

    (include-book \"arithmetic/top-with-meta\" :dir :system)

  which loads into ACL2 all the rules in one of the so-called ACL2
  ``community books''.  ([3mBooks[0m are certified files of definitions,
  lemmas, etc., usually prepared by other ACL2 users and explicitly
  shared with the community.  The ACL2 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
  [47m(include-book \"arithmetic-5/top\" :dir :system)[0m.

  [31;1mRules Concluding with Arithmetic Inequalities[0m: 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

    (<= (len (delete e x)) (len x))

  make poor left-hand sides for rewrite rules.  For example, the
  inequality above does not match the target

    (<= (LEN (DELETE E X)) (+ 1 (LEN X)))

  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 [3mlinear[0m rule.
  See [linear] {ICON} (see [A_Tiny_Warning_Sign]).

  [31;1mRearranging Formulas Before Making Rules[0m: 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 [introduction-to-the-database] (a tutorial topic you'll
  come to later) and its discussion of the concept of [47mcorollary[0m.
  Also, see the discussion of [47mcorollary[0m in [47m[rule-classes][0m {ICON} (see
  [A_Tiny_Warning_Sign]).

  [31;1mRewriting with New Equivalence Relations[0m: You may introduce new
  [3mequivalence[0m relations, like ``set-equal'' or ``is-a-permutation''
  and cause the rewriter to replace equivalents by equivalents in
  suitable contexts, where you use [3mcongruence[0m rules to inform ACL2 of
  where these more relaxed notions of equivalence may be used; see
  [equivalence] {ICON} (see [A_Tiny_Warning_Sign]) and see
  [congruence] {ICON} (see [A_Tiny_Warning_Sign]).

  [31;1mPragmatic Advice to Control Rules[0m: You may attach various [3mpragmas[0m 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 [3mforced[0m (see [force] {ICON} (see
  [A_Tiny_Warning_Sign])) meaning that the rule is to be applied even
  if that hypothesis is not relieved --- 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
  [case-split] {ICON} (see [A_Tiny_Warning_Sign]).  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 [syntaxp] {ICON} (see [A_Tiny_Warning_Sign]).  By providing a
  [47m:match-free[0m modifier to the [47m:rewrite[0m rule declaration in your
  rule-classes, you may tell ACL2 to try all or only the first free
  variable value it guesses (see [rule-classes] {ICON} (see
  [A_Tiny_Warning_Sign])).  You may provide a bogus hypothesis that
  computes from the syntactic environment the values to guess for the
  free variables in a rule; see [bind-free] {ICON} (see
  [A_Tiny_Warning_Sign]).  You may mark a term so that the rewriter
  does not dive into it; see [hide] {ICON} (see
  [A_Tiny_Warning_Sign]).

  [31;1mProgramming Your Own Rewriter[0m: If you cannot find a way to use
  rewrite rules to make the transformations you desire, you might
  investigate the use of [3mmetafunctions[0m.  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 [meta] {ICON} (see
  [A_Tiny_Warning_Sign]).

  [31;1mThe Order in which Targets are Rewritten[0m: The rewriter sweeps through
  terms ``inside-out'' otherwise known as ``left-most innermost
  first''.  Thus, before trying to apply rewrite rules to [47m([0m[3mf a1 ...
  an[0m[47m)[0m, rules are applied to the [3mai[0m.  This has the good effect of
  normalizing the [3mai[0m.

  This fact might help you understand why sometimes your rules ``don't
  seem to fire.'' For example, suppose you have a rule for rewriting
  [47m(len (rev x))[0m to [47m(len x)[0m and suppose you wish to prove a theorem
  about [47m(LEN (REV (CONS A B)))[0m.  Suppose [47mrev[0m is defined in terms of
  [47mappend[0m, as shown in [programming-knowledge-taken-for-granted].
  Then you might see a checkpoint in which the [47m(LEN (REV ...))[0m above
  has been simplified to [47m(LEN (APPEND (REV B) (LIST A)))[0m instead of
  to [47m(LEN (CONS A B))[0m.  Why wasn't your rule about [47m(len (rev x))[0m
  applied?  The reason is that [47m(REV (CONS A B))[0m rewrote to [47m(APPEND
  (REV B) (LIST A))[0m before rules were applied to [47m(LEN (REV ...))[0m.
  You need a rule about [47m(len (append x y))[0m, as you will see from the
  checkpoint.

  [31;1mThe Order in which Rules are Tried[0m: The rewriter tries the most
  recently proved rules first.  For example, suppose [47mf[0m, [47mg[0m, and [47mh[0m are
  functions defined so that the following two theorems are provable
  and suppose you executed the following two events in the order
  shown:

    (defthm rule1 (equal (f (g x)) (h 1 x)))
    (defthm rule2 (equal (f (g x)) (h 2 X)))

  Then if rewrite rules are applied to [47m(F (G A))[0m, the result will be [47m(H
  2 A)[0m, because the latter rule, [47mrule2[0m, 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.

  If you were reading this topic as part of the tutorial introduction
  to the theorem prover, use your browser's [31;1mBack Button[0m now to return
  to [introduction-to-rewrite-rules-part-2].")
 (FUTURE-WORK-RELATED-TO-THE-TAU-SYSTEM
  (INTRODUCTION-TO-THE-TAU-SYSTEM)
  "Some tau system problems that we hope someone will address

  The tau system is inexpressive compared to modern polymorphic type
  systems --- 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.

  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.

  Some tools we [3mthink[0m might help are listed below.  We invite
  volunteers and further suggestions.

  [3mA tau-centric signature notation[0m for use in function definitions,
  exploited by a macro replacing [47mdefun[0m so that input-output
  relationships phrased in tau terms are proved as [47m:tau-system[0m rules
  immediately after functions are introduced:

  We have, for example, experimented with a book defining a macro that
  allows the definition of the function [47map[0m (append) accompanied by a
  signature rule.  Subsequent [47mdefsig[0m events can add other signatures
  in the same notation.

    (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))

  This experimental book provides succinct syntax for all tau
  signatures.  For example, that book parses the signature

    (NATP (/= 3 5 7) (< 16) * TRUE-LISTP ==> BOOLEANP * INTEGER-LISTP * NATP)

  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.

  To express this signature for function [47mfn[0m as a formula requires
  significantly more typing by the user:

    (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)))))

  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.

  [3mSome tau inference mechanisms[0m: 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 [47map[0m
  above rather obviously has the signature

    (integer-listp * integer-listp ==> integer-listp)

  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.

  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 [47m[symbol-alistp][0m
  implies [47m[alistp][0m.  Making the user state these relations invites
  omissions that render the tau system very unpredictable.

  [3mA tau assistant[0m: 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
  [47m(g x)[0m is known to satisfy [47mP[0m and [47m(f x)[0m is known to satisfy [47mR[0m when
  its argument satisfies [47mS[0m:

    g : T ==> P
    f : S ==> R

  then if the user asserts that [47m(f (g x))[0m ``ought'' to have tau [47mR[0m, one
  plausible suggestion is the simple tau rule that [47m(P x)[0m implies [47m(S
  x)[0m.  Such assistance --- while still confronting an undecidable
  problem --- 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.)")
 (GAG-MODE
  (OUTPUT-CONTROLS)
  "Verbosity of proof output

  Please see [set-gag-mode] for an explanation of gag-mode, which can
  take any of the following values:

    (gag-mode) ; generally evaluates to t, nil, or :goals")
 (GC$
  (MISCELLANEOUS ACL2-BUILT-INS)
  "Invoke the garbage collector

  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 [47mgc$[0m is translated into a call of a function
  below on the same arguments.

    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

  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.

  Also see [gc-verbose].

  Evaluation of a call of this macro always returns [47mnil[0m.

  To include [47mgc$[0m in a book, one can use [47mvalue-triple[0m:

    (value-triple (gc$))


Subtopics

  [Gc-verbose]
      Control printing from the garbage collector")
 (GC-STRATEGY
  (MISCELLANEOUS ACL2-BUILT-INS)
  "The garbage collection strategy

  The form [47m(gc-strategy state)[0m 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
  [47mgc-strategy[0m reads its value from the [47moracle[0m field of the ACL2
  [47m[state][0m.  The return value is thus a triple of the form [47m(mv erp val
  state)[0m, where [47merp[0m will always be [47mnil[0m in practice, and logically,
  [47mval[0m is the top of the acl2-oracle field of the state (see
  [47m[read-ACL2-oracle][0m) and the returned state has the updated (popped)
  acl2-oracle.

  For more information, see [set-gc-strategy].")
 (GC-VERBOSE
  (GC$)
  "Control printing from the garbage collector

    General Form:
    (gc-verbose arg &optional arg2)

  Garbage collection (gc) is performed by every Lisp implementation;
  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 [47mnil[0m 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.

  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.

  Evaluation of a call of this macro always returns [47mnil[0m.")
 (GCL
  (MISCELLANEOUS)
  "Tips on building and using ACL2 based on Gnu Common Lisp

  See the 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.

  1. You can place forms to evaluate at start-up into file [47minit.lsp[0m in
  the directory where you are starting ACL2 (GCL), or into file
  [47macl2-init.lsp[0m 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 [47minit.lsp[0m in the current directory or in
  [47m~/acl2-init.lsp[0m (either way, without [47m(lp)[0m or [47m:q[0m):

    (setq si::*optimize-maximum-pages* nil)
    (si::allocate 'cons 75000 t)

  Note that if you want to put ACL2 patches in this file, you should
  precede them with (in-package \"ACL2\").

  2. Suppose you run out of space, for example with an error like this:

    Error: The storage for CONS is exhausted.
      Currently, 59470 pages are allocated.
      Use ALLOCATE to expand the space.

  The following suggestion from Camm Maguire will minimize the heap
  size, at the cost of more garbage collection time.

    :q   ; exit the ACL2 loop
    (setq si::*optimize-maximum-pages* nil)
    (lp) ; re-enter the ACL2 loop

  A second thing to try, suggested by several people, is to preallocate
  more pages before the run, e.g.:

    :q   ; exit the ACL2 loop
    (si::allocate 'cons 75000 t)
    (lp) ; re-enter the ACL2 loop

  Also see [reset-kill-ring] for a suggestion on how to free up space.

  3. Windows users have seen this error:

    cc1.exe: unrecognized option `-fno-zero-initialized-in-bss'

  Camm Maguire suggests that a solution may be to evaluate the
  following in GCL before building ACL2.

    (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))))))

  4. It is possible to profile using ACL2 built on GCL.  See file
  [47msave-gprof.lsp[0m in the ACL2 source directory.

  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:

    :q
    (si::sgc-on nil)
    (lp)

  Alternatively, put [47m(si::sgc-on nil)[0m in your [47m~/acl2-init.lsp[0m file.

  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.

  6. GCL operations on numbers can sometimes be sped up, perhaps by up
  to two orders of magnitude, by suitable [47m[declare][0m forms (also 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.)

    ; 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))))

  7. You may want to set environment variable [47mGCL_MEM_MULTIPLE[0m 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 ``[47m-j
  4[0m'' in your [47mmake[0m command), you may want to specify
  [47mGCL_MEM_MULTIPLE=0.25[0m.  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 [47mHOME[0m may change soon if it hasn't already.

    HOME=/tmp ACL2=$(pwd)/saved_acl2 GCL_MULTIPROCESS_MEMORY_POOL=t \\
      make -j 20 regression-fresh

  (Technical explanation: The reason for setting [47mHOME[0m to directory [47m/tmp[0m
  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.)")
 (GCS (POINTERS)
      "See [get-command-sequence].")
 (GENEQV
  (INTRODUCTION-TO-THE-THEOREM-PROVER BREAK-REWRITE)
  "the rewriter's generated equivalence relation

  As the rewriter descends through a term, rewriting the subterms, it
  uses [congruence] rules to determine which [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.

  The outline of this discussion is as follows.

    * Basic Support for Equivalence Relations: a review of equivalence
      relations, refinement, and congruence

    * Salient Facts about the ACL2 Rewriter: a review of how the rewriter
      works

    * 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

    * 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.


Basic Support for Equivalence Relations

  If you do not know what the following ACL2 macro forms do, you should
  see their documentation.

    ; 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)

  An example of the last form is

    (defcong set-equal iff (member e x) 2)

  which essentially expands to

    (defthm set-equal-implies-iff-member-2
      (implies (set-equal x y)
               (iff (member e x)
                    (member e y)))
      :rule-classes (:congruence))

  (ACL2 actually generates a different variable name in place of [47my[0m
  above.)

  Helpful documentation topics include [equivalence], [refinement],
  [congruence], [47m[defequiv][0m, [47m[defrefinement][0m, and [47m[defcong][0m.


Salient Facts about the ACL2 Rewriter

    * Goals, which are represented as clauses, are simplified by rewriting
      each literal in turn, assuming the other literals false.

    * When a term is rewritten (under some assumptions) the rewriter is
      given an [equivalence] relation to maintain, i.e., the output
      of the rewriter must be equivalent in that sense to the input,
      under the assumptions.

    * The initial equivalence relation to be maintained while rewriting a
      literal is [47m[iff][0m.

    * Each [47m:[0m[47m[rewrite][0m rule in ACL2 effectively concludes with a term of the
      form [47m(eqv lhs rhs)[0m, where [47meqv[0m is an equivalence relation.  Such
      a rule may be used to replace instances of [47mlhs[0m by the
      corresponding instance of [47mrhs[0m, and maintains the equivalence
      relation [47meqv[0m.  But the rule is only applicable if [47meqv[0m [3mrefines[0m
      the equivalence relation to be maintained by rewrite.  See
      [refinement].

    * If the term to be rewritten is a function call, [47m(fn a1 ... ak)[0m, the
      rewriter rewrites each [47mai[0m to, say, [47mai'[0m, before applying rules
      to [47m(fn a1' ... ak[0m').  To be more precise, when the ACL2
      rewriter is asked to rewrite [47m(fn a1 ... an)[0m maintaining some
      equivalence [47meqv[0m, it first rewrites each [47mai[0m, maintaining an
      equivalence generated from the congruence rules about how to
      rewrite the [47mi[0mth argument of [47mfn[0m maintaining [47meqv[0m.  Suppose each
      [47mai[0m is thus rewritten to some other term [47mai'[0m.  That is, [47m(fn a1
      ... an)[0m is transformed to [47m(fn a1' ... an[0m') which is known to be
      [47meqv[0m-equivalent to [47m(fn a1 ... an)[0m.  Then the rewriter applies
      all the [47meqv[0m rules it knows to [47m(fn b1 ... bn)[0m.

    * How the rewriter uses the known [congruence] rules to determine the
      equivalence relation to be maintained while rewriting each [47mai[0m
      is illustrated below.

    * [47mEqual[0m refines all equivalence relations.

    * [47mEqual[0m maintains all equivalence relations across all argument
      positions of all functions.


Using Congruence Rules to Generate Acceptable Equivalences for
Subterms

  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 [47mbooks/demos/geneqv.lisp[0m.

  Our examples use the following functions.

    * [47mLen[0m is an ACL2 primitive that determines the number of elements in a
      list.

    * [47m(perm x y)[0m determines whether [47mx[0m is a permutation of [47my[0m, i.e., whether
      each element that occurs in either [47mx[0m or [47my[0m occurs in both the
      same number of times.  For example [47m(perm '(A B A C) '(C B A A))[0m
      is true, but [47m(perm '(A B A C) '(A B B C))[0m is false.

    * [47m(pairwise-iff x y)[0m determines whether corresponding elements of [47mx[0m and
      [47my[0m are propositionally equivalent (i.e., [47mIFF[0m-equivalent).  For
      example, [47m(pairwise-iff '(T NIL T) '(1 NIL A))[0m is true (since
      both [47m1[0m and [47mA[0m are non-[47mNIL[0m and thus propositionally equivalent to
      [47mT[0m), but [47m(pairwise-iff '(T NIL T) '(1 NIL NIL))[0m is false.

    * Both [47mperm[0m and [47mpairwise-iff[0m can be proved to be [equivalence]
      relations.

    * Both [47mperm[0m and [47mpairwise-iff[0m are congruence relations for the first
      argument of [47mlen[0m that maintain [47mequal[0mity of [47mlen[0m.

          (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))

  Now consider proving

    (defthm example-thm-1
      (equal (len (isort (norml x)))
             (len x))
      :rule-classes nil)

  Before we start you should understand that there are many ways to
  prove this little theorem.  The most straightforward is just to
  prove that [47m(len (isort x))[0m is [47m(len x)[0m and to prove [47m(len (norml x))[0m
  is [47m(len x)[0m.  In this case, where the functions involved are [47misort[0m
  and [47mnorml[0m, 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.

  If you run the [47mdefthm[0m above, the prover (after preprocessing)
  eventually calls the rewriter on the [47mequal[0m term, requiring it to
  maintain [47miff[0m.  The rewriter then dives into the two arguments,
  rewriting [47m(len (isort (norml x)))[0m first, maintaining [47mequal[0mity.

  The rewriter then dives into the first argument of the [47mlen[0m term,
  [47m(isort (norml x))[0m.  The congruence rule [47mperm-implies-equal-len-1[0m
  above tells it that [47mequal[0mity of the [47mlen[0m term is maintained if the
  first argument is rewritten maintaining the [47mperm[0m equivalence.  In
  addition, the congruence rule [47mpairwise-iff-implies-equal-len-1[0m
  tells it that [47mequal[0mity of the [47mlen[0m term is also maintained if the
  first argument is rewritten maintaining the [47mpairwise-iff[0m
  equivalence.

  Thus, when rewriting [47m(isort (norml x))[0m the rewriter can use any
  rewrite rule that maintains [47mperm[0m, any rewrite rule that maintains
  [47mpairwise-iff[0m, and, of course, any rewrite rule that maintains
  [47mequal[0m.  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.

  The geneqv just derived is represented internally as

    ((5658 PAIRWISE-IFF
           :CONGRUENCE PAIRWISE-IFF-IMPLIES-EQUAL-LEN-1)
     (5651 PERM
           :CONGRUENCE PERM-IMPLIES-EQUAL-LEN-1))

  Ignoring the two numbers, we see two pairs, each naming an
  equivalence relation and the [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 [47mEQUAL[0m since it
  maintains every equivalence relation in every argument position of
  every function.  Indeed, if you see a geneqv of [47mNIL[0m it means [47mEQUAL[0m
  is the only acceptable equivalence relation in that context.

  Debugging tools in ACL2 typically display the geneqv above as

    ((PAIRWISE-IFF PAIRWISE-IFF-IMPLIES-EQUAL-LEN-1)
     (PERM PERM-IMPLIES-EQUAL-LEN-1))

  or even

    (PAIRWISE-IFF PERM).

  We discuss debugging tools that display geneqvs below.

  But what does this geneqv buy us during this proof?  Recall where we
  were in the proof discussed above.  We're rewriting [47m(isort (norml
  x))[0m maintaining [47m(PAIRWISE-IFF PERM)[0m.  If the user had proved the
  following two rewrite rules

    (defthm perm-isort                ; isort preserves perm
      (perm (isort X) X))

    (defthm pairwise-iff-norml        ; norml preserves pairwise-iff
       (pairwise-iff (norml x) x))

  then the rewriter would replace [47m(isort (norml x))[0m by [47m(norml x)[0m using
  the first rule, since [47mperm[0m is a refinement of the geneqv, and then
  the rewriter would rewrite that and replace it by [47mx[0m using the
  second rule, since [47mpairwise-iff[0m is also a refinement of the geneqv.
  Note that neither of these replacements preserve [47mequal[0mity, but they
  are permitted because they preserve the [47mequal[0mity of the [47mlen[0ms.

  Thus, [47m(equal (len (isort (norml x))) (len x))[0m has been simplified to
  [47m(equal (len x) (len x))[0m which further simplifies to [47mt[0m and the proof
  is done.

  The Community Book [47m\"books/demos/geneqv-test-book.lisp\"[0m (which
  executes the commands in books/demos/geneqv-test-input.lsp)
  contains this and other examples.


Debugging Tools

  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 [47m[brr][0m is enabled and a [47m[monitor][0med rule is tried by the rewriter
  but does not fire because it failed the refinement test, a
  [break-rewrite] interactive break occur.  See [refinement-failure]
  for some advice for how you might respond to such a failure.

  From within a break-rewrite break the [47m[brr-commands][0m [47m:path[0m will print
  the ``path'' from the current top-level goal down to the call of
  the rewriter on current [47m:target[0m 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 [47m[linear-arithmetic][0m procedure) that orchestrate other
  calls to the rewriter.  As of Version 8.6, each frame of the [47m:path[0m
  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 [47mequal[0m).  Every frame describing a call of the
  rewriter includes the geneqv to be maintained as the target is
  rewritten (unless the geneqv is [47mnil[0m which denotes the [47mequal[0mity
  relation).  The noted exceptions are intended to shorten the output
  in the most common cases: rewriting with [47mequal[0m and maintaining
  equality.

  In addition, from within such a break the brr-command [47m:geneqv[0m will
  print the geneqv for the current target.")
 (GENERALIZE
  (RULE-CLASSES)
  "Make a rule to restrict generalizations

  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.

    Example:
    (defthm integer-listp-rev
      (implies (integer-listp x)
               (integer-listp (rev x)))
      :rule-classes :generalize)

    General Form:
    any theorem

  To use a [47m:generalize[0m rule, the system waits until it has decided to
  generalize some term, [47mterm[0m, by replacing it with some new variable
  [47mv[0m.  If any [47m:generalize[0m formula can be instantiated so that some
  non-variable subterm becomes [47mterm[0m, then that instance of the
  formula is added as a hypothesis.  Thus for the example above, if
  the term [47m(rev x2)[0m is generalized to the variable [47mrv[0m during a proof,
  then the following is added as a hypothesis when generalizing to a
  new goal.

    (implies (integer-listp x2)
             (integer-listp rv))

  At the moment, the best description of how ACL2 [47m:generalize[0m 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
  [introduction-to-the-theorem-prover] for detailed tutorial on using
  ACL2 to prove theorems, which includes some discussion of
  generalization.")
 (GENERALIZED-BOOLEANS
  (COMMON-LISP)
  "Potential soundness issues related to ACL2 predicates

  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.

  Consider for example the question: What is the value of [47m(equal 3 3)[0m?
  According to the ACL2 axioms, it's [47mt[0m.  And as far as we know, based
  on considerable testing, the value is [47mt[0m in every Common Lisp
  implementation.  However, according the Common Lisp draft proposed
  ANSI standard, any non-[47mnil[0m value could result.  Thus for example,
  [47m(equal 3 3)[0m is allowed by the standard to be [47m17[0m.

  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 [47m[equal][0m, [47m[rationalp][0m, and [47m[<][0m; 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 [47mnot[0m and [47mnull[0m.  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 [47mnil[0m or not [47mnil[0m.

  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 [47m[equal][0m function is
  defined to be Common Lisp's [47mequal[0m.  Hence if in Common Lisp the
  form [47m(equal 3 3)[0m were to evaluate to 17, then in ACL2 we could
  prove (using the [47m:[0m[47m[executable-counterpart][0m of [47m[equal][0m) [47m(equal
  (equal 3 3) 17)[0m.  However, ACL2 can also prove [47m(equal (equal x x)
  t)[0m, and these two terms together are contradictory, since they
  imply (instantiating [47mx[0m in the second term by [47m3[0m) that [47m(equal 3 3)[0m is
  both equal to [47m17[0m and to [47mt[0m.

  To make matters worse, the standard allows [47m(equal 3 3)[0m to evaluate to
  [3mdifferent[0m non-[47mnil[0m values every time.  That is: [47mequal[0m need not even
  be a function!

  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
  [guard]).  For now, we'll sleep a bit better knowing that we have
  been up-front about this potential problem.

  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 [47m[ACL2-numberp][0m
  and [47m[complex-rationalp][0m are directly defined in terms of respective
  Common Lisp functions [47mnumberp[0m and [47mcomplexp[0m.

    /=
    <
    =
    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")
 (GENERALIZING-KEY-CHECKPOINTS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Getting rid of unnecessary specificity

  Suppose [47mMEMBER[0m determines whether its first argument is a member of
  its second, and [47mSUBSETP[0m 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?

    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))

  The key observation is that the fourth hypothesis implies the
  negation of the fifth.  Writing it in the contrapositive:

    (IMPLIES (AND ...
                  (SUBSETP (CDR A) B)
                  ...)
             (SUBSETP (CDR A) (APPEND B C)))

  In fact, that is more complicated than it needs to be.  A ``correct''
  response to the key checkpoint above is to prove

    (defthm subsetp-append
      (implies (subsetp a b)
               (subsetp a (append b c)))).

  A still better response is to prove this:

    (defthm subsetp-append-2
      (implies (or (subsetp a b)
                   (subsetp a c))
               (subsetp a (append b c)))).

  This version is better because it handles both of the possibilities
  regarding whether [47ma[0m is a subset of the arguments of the [47mappend[0m.

  It would be nice if we could think of a ``strong'' version, one in
  which [47m(SUBSETP a (APPEND b c))[0m is rewritten to some clearly simpler
  term, but nothing comes to mind.

  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 [47mSUBSETP[0m).  It is also a
  good heuristic to throw out parts of the formula that seem
  disconnected (as here, with the terms involving [47m(CAR A)[0m).

  This discussion suggests several ``modes'' of looking at key
  checkpoints and the idea of trying the modes in sequence:

  (1) look for simplifiable combinations of function symbols within
  propositional components,

  (2) look for relations between propositional components, and

  (3) throw out irrelevant or weakly connected components.

  In all cases you are bringing to bear your intuitions about the
  [3msemantics[0m 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!

  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.

  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 --- more often
  than you might think --- local considerations can prove many of
  your checkpoints.

  If you have been working your way through the tutorial introduction
  to the theorem prover, use your browser's [31;1mBack Button[0m now to return
  to [introduction-to-key-checkpoints].")
 (GENTLE-INTRODUCTION-TO-ACL2-PROGRAMMING
  (START-HERE)
  "A Gentle Introduction to ACL2 Programming


A Gentle Introduction to ACL2 Programming


[3mby[0m


J Strother Moore


Abstract

  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. ``ACL2'' denotes ``A Computational Logic for
  Applicative Common Lisp''.  The ACL2 programming language is a
  subset of [3mside-effect free[0m 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.


Getting Started

  If you haven't installed ACL2 on your machine, do so, by following
  the instructions at ``Obtaining, Installing, and License'' on the
  {ACL2 Home Page | https://www.cs.utexas.edu/users/moore/acl2}.  As
  those instructions make clear, to run ACL2 you'll need a Common
  Lisp implementation.  The instructions name several suitable ones.

  In addition to the installation instructions, the Home Page has a
  wealth of documentation.  You should visit ``The User's Manuals''.
  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 ``ACL2
  User's Manual''.  Explore it briefly just so you know how to find
  more information.  For example, type ``defun'' 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 [47mdefun[0m 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!

  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.

  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 ACL2s (see [ACL2-SEDAN]), 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.

  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.

  Now fire up your ACL2.  You should see a prompt that looks like this

    ACL2 !>

  Type ``:program'' and a return.

    ACL2 !>:program
    ACL2 p!>

  The [47m:program[0m 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 [47m:program[0m mode.)

  Now type ``[47m(+ 2 2)[0m''.  You should see the answer, [47m4[0m 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.

    ACL2 !>:program
    ACL2 p!>(+ 2 2)
    4
    ACL2 p!>(+ 1 2 3 4)
    10
    ACL2 p!>(car '(hello world))
    HELLO
    ACL2 p!>(cdr '(hello world))
    (WORLD)
    ACL2 p!>(cons 'hello '(world))
    (HELLO WORLD)
    ACL2 p!>

  Sometimes computations cause errors, most commonly due to type
  violations or resource limitations.  See the sections Type Errors
  and Stack Overflow below.

  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.

    (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.

  If you aren't sure what a ``linear list'' is just hang in and we'll
  get to it.  But you've probably figured out that [47mnil[0m is the empty
  list, that [47mcons[0m constructs a list by ``adding'' an element to the
  front of another list, that [47mcar[0m returns the first element of a
  non-empty list, and that [47mcdr[0m returns all but the first element of a
  non-empty list.  Those deductions are right, as far as they go.

  Here is what it looks like if you submit the [47msquare-all[0m 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.

    ACL2 !>:program
    ...
    ACL2 p!>(cons 'hello '(world))
    (HELLO WORLD)
    ACL2 p!>(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!>

  Once [47msquare-all[0m is defined we can run it.  Here are some tests.

    ACL2 p!>(square-all '(1 2 3 4 5))
    (1 4 9 16 25)
    ACL2 p!>(square-all nil)
    NIL
    ACL2 p!>(square-all '(-9 3/4 #c(0 5)))
    (81 9/16 -25)
    ACL2 p!>


Data Types

  ACL2 supports five very simple but rather abstract types of data:

    * numbers,

    * characters,

    * strings,

    * symbols (which includes the two Booleans [47mT[0m and [47mNIL[0m), and

    * pairs or ``conses''.

  Objects of each type are distinct.  That is, no number is a character
  or a string or a symbol or a pair.  Etc.

  All of these objects are ``first class'' 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.

  Many operators are provided for each type.  Each operator is a
  [3mfunction[0m.

  [3mNo ACL2 operator or function can modify, mutate, or otherwise alter
  the objects passed in as arguments.[0m

  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 ``behind the scenes'' when the ACL2 function [47mcons[0m
  is called on [47m4[0m and [47m5[0m?  Mathematically it returns the pair < [47m4[0m, [47m5[0m >
  which is printed in ACL2 as [47m(4 . 5)[0m.  But operationally, some
  memory is allocated for a new object, then the representations of 4
  and 5 are stored in two fields (called the [3mcar[0m and [3mcdr[0m fields) of
  that object, that region of memory is effectively tagged to
  indicate that it represents a [47mcons[0m pair, and a pointer to the newly
  allocated object is returned as the result of the call of [47mcons[0m.
  When that result is printed by ACL2 it appears as [47m(4 . 5)[0m.  The
  italicized sentence above means [3mnothing you can do in ACL2 will
  change the contents of that newly allocated memory.[0m In most
  programming languages you could invoke some procedure or method to
  overwrite the contents of the [3mcar[0m field of that object, changing it
  from [47m4[0m to [47m3[0m.  No such procedure or method exists in ACL2.  The
  object returned by that call of [47mcons[0m will print as the pair [47m(4 . 5)[0m
  --- will [3mbe[0m the pair [47m(4 . 5)[0m --- for as long as you have access to
  the pointer returned by that call of [47mcons[0m.

  ACL2 expressions are just nests of function calls.  For example
  [47m(factors (+ x (* 3 y)))[0m calls the function [47mfactors[0m on the value of
  [3mx+3y[0m.  (We define [47mfactors[0m below to return the list of prime factors
  of its input.)  The functions [47m+[0m and [47m*[0m are examples of functions
  that operate on numbers.

  Before we discuss ACL2 expressions further we must discuss the
  important issue of how you write down constants of each of the five
  types.

  A few examples suffice to illustrate the common ways to enter
  numeric constants: [47m123[0m, [47m22/7[0m and [47m#c(3 5)[0m.  Note that ACL2 provides
  ``infinitely precise'' rational numbers like [47m1/3[0m and [47m22/7[0m.  These
  are not floating point numbers; we don't provide floating point
  numbers.  The rational [47m2/3[0m could also be written [47m4/6[0m --- they are
  two different ways of writing the same number.  The ACL2 number
  [47m#c(3 5)[0m is more conventionally written as the complex number [3m3+5i[0m.
  ACL2 also supports writing numeric constants in binary, octal and
  hexadecimal notation, but we do not use that here.

  We will list some operations on numbers later.

  Here are examples of how to write character objects: [47m#\\A[0m and [47m#\\a[0m and
  [47m#\\Space[0m.  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.

  Strings are delimited by the double quote mark, e.g., [47m\"This is an
  error message.\"[0m Again, there are functions more manipulating
  strings but we won't use them in this guide.

  This leaves us with symbols and conses.  Two symbols are easy to
  understand because they have counterparts in most programming
  languages: [47mT[0m is a symbol but it is also ACL2's Boolean ``true''
  object.  [47mNIL[0m is a symbol and is ACL2's Boolean ``false'' object.
  When an ACL2 predicate is said to be false, we mean the predicate
  returns [47mNIL[0m.  When an ACL2 predicate is said to be true, it usually
  means it returns [47mT[0m, but more precisely it means it returns anything
  but [47mNIL[0m.  Oddly, Lisp and ACL2 also use the symbol [47mNIL[0m as the
  ``empty list''.

  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.


Symbols

  Symbols are sequences of alphabetic letters, signs and digits.  So
  [47mX[0m, [47mX*[0m, and [47mABC23[0m are symbols.  So are [47mCAR[0m, [47mIF[0m, and [47mTRUE-LISTP[0m.
  Note that dashes and other signs do not ``break'' symbols into
  pieces.  [47mTRUE-LISTP[0m is one symbol, not two symbols separated by a
  minus sign.

  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 ``escape'' conventions you can
  actually write symbols containing spaces and parentheses, symbols
  composed entirely of digits, and symbols with other ``weird''
  characters.  But we will not go into these conventions in this
  introduction.  We will limit ourselves to symbols that ``look
  like'' 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.

  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.

  As noted, [47mT[0m and [47mNIL[0m are symbols with special significance.  They are
  our ``Booleans'' data objects and [47mNIL[0m is used as the ``empty
  list''.

  Symbols are more complicated than described above because in
  addition to their names they belong to ``packages.'' For example,
  there might be a symbol named [47mABS[0m in a package named [47m\"MATH\"[0m and a
  symbol named [47mABS[0m in a package named [47m\"VECTORS\"[0m.  There is always one
  ``current package'' in ACL2 --- you can select any package as the
  current package.  If [47m\"MATH\"[0m were the current package, then when you
  write [47mABS[0m you denote the symbol [47mABS[0m in the [47m\"MATH\"[0m package.  If you
  mean the symbol [47mABS[0m in the [47m\"VECTORS\"[0m package you would have to
  write [47mVECTORS::ABS[0m.  We will not use packages here.

  There is a special package called the [47m\"KEYWORD\"[0m package.  The symbol
  [47mABS[0m in the [47m\"KEYWORD\"[0m package can, of course, be written
  [47mKEYWORD::ABS[0m.  But special syntactic sugar also allows us to write
  [47m:ABS[0m for that symbol.

  When we write symbols, case is unimportant (unless that previously
  mentioned ``escape'' convention is used).  When reading a symbol
  all characters are all uppercased.  That is, ACL2 reads the symbol
  [47mx[0m as [47mX[0m.  The symbol [47mThe[0m is read as [47mTHE[0m and [47mTrue-Listp[0m is read as
  [47mTRUE-LISTP[0m.  Thus, the choice of whether to write a symbol in
  uppercase, lowercase, or some mixture of cases is just a stylistic
  one.

    ACL2 p!>'(Here is a list of SymBols!)
    (HERE IS A LIST OF SYMBOLS!)
    ACL2 p!>'(This list contains a |Weird Symbol|)
    (THIS LIST CONTAINS A |Weird Symbol|)
    ACL2 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 ``create'' symbols, strings and
  characters and none of our examples create these objects
  dynamically.


Lists

  We first discuss how to write down ``cons pairs'' and `` list
  objects''.  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 [47m123[0m, [47m000123[0m, [47m+0123[0m, [47m246/2[0m and [47m#b1111011[0m 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 ``style'' is just
  that: stylistic.

  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 [3mordered pair[0m or [3mcons pair[0m.  A cons
  pair is just a pair of two objects.  Sometimes we call a cons pair
  a ``list pair'' or a ``dotted pair'' or simply a ``list.''

  Any two objects may be put together into a cons pair.  The cons pair
  containing the integer [47m1[0m and the integer [47m2[0m might be drawn as:

      *
     / \\
    1   2

  or might be written in Cartesian coordinate notation as <[47m1[0m,[47m2[0m>.  But
  in ACL2 it is written as the object [47m(1 . 2)[0m.  This is a single cons
  object in ACL2, with two integer objects as constituents.  The
  left-hand constituent is called the [3mcar[0m of the pair.  The
  right-hand constituent is called the [3mcdr[0m.

  The tree we might draw as

      *
     / \\
    1   *
       / \\
      2   3

  or write in coordinate notation as <[47m1[0m, <[47m2[0m, [47m3[0m>>, in ACL2 is written
  the object [47m(1 . (2 . 3))[0m.  The car of this object is the integer [47m1[0m.
  The cdr of this object is the object [47m(2 . 3)[0m.

  Similarly,

         *
        / \\
       /   \\
      *     *
     / \\   / \\
    1   2 3   4

  or <<[47m1[0m, [47m2[0m>,<[47m3[0m, [47m4[0m>> is written [47m((1 . 2) . (3 . 4))[0m.  Suppose [3mx[0m is the
  cons object just mentioned.  Then the car of [3mx[0m is the object [47m(1 .
  2)[0m and the cdr is the object [47m(3 . 4)[0m.  Obviously, the car of the
  car of [3mx[0m is [47m1[0m.  The cdr of the car of [3mx[0m is [47m2[0m, etc.

  The notation we are using to write list objects is called [3mdot
  notation[0m. It is a straightforward translation of the familiar
  coordinate notation in which parentheses replace the brackets and a
  dot replaces the comma.

  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 [47m5[0m?
  There are an infinite number!  [47m5[0m, [47m05[0m, [47m005[0m, [47m+000005[0m, etc., not to
  mention possibly [47m#B101[0m and others.  Those are all just ``syntactic
  sugar'' for denoting one familiar object.  The sugars above might
  be described as ``you can add a leading [47m0[0m'' and ``you can add a
  single leading plus sign on a positive number.''

  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:

      *
     / \\
    1   nil

  namely, you can write [47m(1 . nil)[0m or you can write [47m(1)[0m.  That is: if a
  cons pair has [47mNIL[0m as its cdr, you can drop the ``dot'' and the [47mNIL[0m.

  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
  [47m([0m[3mx[0m [47m. (...))[0m as [47m([0m[3mx[0m [47m...)[0m.  That is, when the cdr is a cons, you can
  drop the dot and the pair of balanced parentheses following it.

  Thus, the tree

      *
     / \\
    1   *
       / \\
      2   *
         / \\
        3   nil

  can be written in any of the following ways.

    (1 . (2 . (3 . nil)))
    (1 . (2 . (3)))
    (1 . (2 3))
    (1 2 3)

  It can also be written in many other ways, e.g., [47m(1 2 . (3 . nil))[0m
  and [47m(1 . (2 3))[0m.

  Binary trees that terminate in [47mnil[0m on the right-most branch, such as
  the one above, are often called [3mlinear lists[0m.  The [3melements[0m of a
  list are the successive cars along the ``cdr chain.'' 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 [47m1[0m, [47m2[0m, and [47m3[0m, in that
  order.  If we let [3mx[0m denote that tree, i.e., let [3mx[0m be [47m(1 2 3)[0m, then
  the car of [3mx[0m is [47m1[0m.  The cdr of [3mx[0m is the linear list [47m(2 3)[0m.  The car
  of the cdr of [3mx[0m is thus [47m2[0m.  The cdr of the cdr of [3mx[0m is the linear
  list [47m(3)[0m.  The car of the cdr of the cdr of [3mx[0m is [47m3[0m.  And the
  ``third cdr'' of [3mx[0m is [47mnil[0m.

  The linear list [47m(A (B C D) E)[0m has three elements.  [47mB[0m is not an
  element of that list, it is an element of an element.

  The following is a linear list of pairs.

        *
       / \\
      *   \\
     / \\   \\
    A   1   *
           / \\
          *   \\
         / \\   \\
        B   2   *
               / \\
              *   \\
             / \\   \\
            C   3   nil

  This list can be written [47m((A . 1) (B . 2) (C . 3))[0m.  In full dot
  notation it is written

    ((A . 1) . ((B . 2) . ((C . 3) . NIL))).

  By the way, lists such as the one above are so common they have a
  name.  They are called [3massociation lists[0m or [3malists[0m and are used as
  keyed tables.  The list above associates the key [47mA[0m with the value
  [47m1[0m, the key [47mB[0m with the value [47m2[0m, etc.  Later we show functions for
  manipulating alists.

  Lists are often used to represent more elaborate data structures.
  For example, an ``account'' might consist of a name, an id number,
  a balance and a list of transactions, laid out like this:

            *
           / \\
          /   \\
         /     \\
        *       *
       / \\     / \\
      /   \\   /   \\
    name  id bal  trans

  An example of an account object might be

    ((\"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))))

  Rather than refer to these four components in terms of the [47mcar[0m and
  [47mcdr[0m of the account object most programmers would define functions
  with application-specific names like [47maccount-name[0m, [47maccount-id[0m, etc.
  Instead of building each account object with a nest of [47mcons[0m
  expressions they would define [47m(make-account name id bal trans)[0m to
  do the consing.


Expressions

  We've seen that the basic idiom for defining a new function in ACL2
  is to write

    (defun f (v1 ... vn) body)

  where [47mf[0m is the name of the function, the [47mvi[0m are its input parameters,
  and [47mbody[0m is an expression that computes the value of the function
  in terms of the parameters.  The [3mn[0m parameters must be distinct
  variable names and we say that [3mn[0m is the [3marity[0m of the new function
  [47mf[0m.  But what are expressions?

  With a few exceptions, an expression is either

    * a variable symbol,

    * a constant expression,

    * a call of a function of arity [3mn[0m on [3mn[0m argument expressions (sometimes
      called the [3mactuals[0m).

  Variable symbols are written in the same way that symbol objects are
  written, except [47mT[0m, [47mNIL[0m, and keywords may not be used as variable
  symbols.  Examples of variable symbols are thus [47mX[0m, [47mk[0m, [47mtemp3[0m, and
  [47minit-val[0m.

  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, [47mT[0m, [47mNIL[0m, 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 [47m#\\Space[0m, [47m\"EOF Error\"[0m, [47m128[0m, [47mT[0m, [47mNIL[0m, and
  [47m:element[0m.  Constant expressions of the second kind include [47m'X[0m,
  [47m'HELLO[0m, and [47m'(MON WED FRI)[0m.

  Function calls are written by writing an open parenthesis, the name
  of the function and the [3mn[0m argument expressions, all separated by
  whitespace, followed by a close parenthesis.  For example [47m(cons (*
  (car x) (car x)) (square-all (cdr x)))[0m is a function call of the
  function [47mcons[0m on two argument expressions.  The first argument is a
  call of [47m*[0m on two expressions, both of which are calls of [47mcar[0m on the
  variable symbol [47mx[0m.  The second argument to the call of [47mcons[0m is
  [47m(square-all (cdr x))[0m, which is a call of [47msquare-all[0m on a call of
  [47mcdr[0m on [47mx[0m.

  Consider the list object [47m(CAR X)[0m, which we can draw as

      *
     / \\
    CAR \\
         *
        / \\
       X  NIL.

  This object can be written as [47m(CAR X)[0m.  But that is also the way we
  write the expression that denotes a call of the function [47mCAR[0m on [47mX[0m.
  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.

  We have said that an expression is either a variable, a constant, or
  a function call of a function symbol of arity [47mn[0m on [47mn[0m 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 [47m+[0m and [47m*[0m to take more than two arguments.  So
  [47m(+ (* x x) (* 2 x y) (* y y))[0m 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 [3mmacro[0m 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
  [3mlambda expressions[0m, but we won't use them explicitly in this
  introduction.  The reason we say ``explicitly'' is that we will use
  so-called [47mlet[0m expressions to introduce some local temporary
  variables and ACL2 understands [47mlet[0m expressions as applications of
  lambda expressions.  We'll explain when we introduce [47mlet[0m.

  An example expression is

    (cons (cons 'square-all (cons x nil))
          (cons '=
                (cons (square-all x) nil)))

  provided [47msquare-all[0m 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.

  Expressions have [3mvalues[0m computed with respect to an environment
  assigning values to variable symbols.  For example, if [47msquare-all[0m
  is defined as previously shown and [47mx[0m has the value [47m(1 2 3)[0m then the
  value of the expression above is

    ((SQUARE-ALL (1 2 3)) = (1 4 9)).

  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 [3mn[0m argument expressions to obtain a sequence of [3mn[0m
  objects, (b) creating a new environment in which the function's [3mn[0m
  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 [47m*[0m
  or [47mcons[0m, is determined by running special code on the values of the
  arguments.

  For example, suppose we have added this definition

    (defun sq (x) (* x x))

  and we are in an environment where [47mx[0m has value [47m5[0m.  Then here is an
  annotated computation of the value of [47m(sq (+ 1 x))[0m.

    (sq (+ 1 x))
    =                ; evaluate argument of sq, when x = 5
    (sq 6)
    =                ; evaluate body of sq, when x = 6
    36.


Primitive Functions

  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, [47m(natp
  x)[0m is defined to be [47m(and (integerp x) (<= 0 x))[0m.  Other
  ``functions'' mentioned below are actually macros that expand into
  primitive expressions.

    * [47m(EQUAL x y)[0m --- [47mt[0m if [47mx[0m and [47my[0m are the same object and [47mnil[0m otherwise

    * [47m(IF x y z)[0m --- [47my[0m if [47mx[0m is non-[47mNIL[0m and [47mz[0m if [47mx[0m is [47mNIL[0m.  Put more
      colloquially, [47m(IF x y z)[0m means ``if [47mx[0m is true, return [47my[0m,
      otherwise return [47mz[0m''

    * [47m(COND (p1 x1) (p2 x2) ... (T xn))[0m --- an abbreviation for

          (IF p1
              x1
              (IF p2
                  x2
                  (IF ...
                      ...
                      y)))

    * [47m(AND x1 ... xn)[0m --- [47mxn[0m if each [47mxi[0m is non-[47mnil[0m, and [47mnil[0m otherwise

    * [47m(OR x1 ... xn)[0m --- [47mxi[0m for the first [47mxi[0m that is non-[47mnil[0m, [47mnil[0m
      otherwise

    * [47m(NOT x)[0m --- [47mt[0m if [47mx[0m is [47mnil[0m and [47mnil[0m otherwise

    * [47m(NATP x)[0m --- [47mt[0m if [47mx[0m is a non-negative integer and [47mnil[0m otherwise

    * [47m(INTEGERP x)[0m --- [47mt[0m if [47mx[0m is an integer and [47mnil[0m otherwise

    * [47m(RATIONALP x)[0m --- [47mt[0m if [47mx[0m is a rational number and [47mnil[0m otherwise

    * [47m(ZP x)[0m --- [47mnil[0m if [47mx[0m is a positive integer and [47mt[0m otherwise

    * [47m(+ x1 ... xn)[0m --- sum of the [47mxi[0m

    * [47m(* x1 ... xn)[0m --- product of the [47mxi[0m

    * [47m(- x y)[0m --- [47mx[0m minus [47my[0m

    * [47m(/ x y)[0m --- quotient of [47mx[0m divided by [47my[0m

    * [47m(< x y)[0m --- [47mt[0m if [47mx[0m is less than [47my[0m and [47mnil[0m otherwise

    * [47m(<= x y)[0m --- [47mt[0m if [47mx[0m is less than or equal to [47my[0m and [47mnil[0m otherwise

    * [47m(CONSP x)[0m --- [47mt[0m if [47mx[0m is a cons pair and [47mnil[0m otherwise

    * [47m(ATOM x)[0m --- [47mt[0m if [47mx[0m is a not cons pair and [47mnil[0m otherwise

    * [47m(ENDP x)[0m --- [47mt[0m if [47mx[0m is [47mnil[0m or a not cons pair and [47mnil[0m otherwise

    * [47m(CONS x y)[0m --- the ordered pair whose left-hand component is [47mx[0m and
      whose right-hand component is [47my[0m

    * [47m(CAR x)[0m --- left-hand component of [47mx[0m if [47mx[0m is a cons pair and [47mnil[0m
      otherwise

    * [47m(CDR x)[0m --- right-hand component of [47mx[0m if [47mx[0m is a cons pair and [47mnil[0m
      otherwise

    * [47m(CADR x)[0m --- [47m(CAR (CDR X))[0m

    * [47m(CDDR x)[0m --- [47m(CDR (CDR X))[0m

    * [47m(LIST x1 x2 ... xn)[0m --- [47m(CONS x1 (CONS x2 ... (CONS xn NIL)))[0m

    * [47m(LIST* x1 x2 ... xn)[0m --- [47m(CONS x1 (CONS x2 ... xn))[0m

    * [47m(SYMBOLP x)[0m --- [47mt[0m if [47mx[0m is a symbol and [47mnil[0m otherwise

    * [47m(STRINGP x)[0m --- [47mt[0m if [47mx[0m is a string and [47mnil[0m otherwise

    * [47m(CHARACTERP x)[0m --- [47mt[0m if [47mx[0m is a character and [47mnil[0m otherwise

  You can learn more about these functions by executing them on some
  sample data.  For example, the value of [47m(AND T 23 33)[0m is [47m33[0m, [47m(+ 1 2
  3)[0m is [47m6[0m, [47m(ZP 0)[0m is [47mT[0m but [47m(ZP 3)[0m is false (i.e., [47mNIL[0m).  [47m(LIST 1 (+ 2
  2) (+ 3 3))[0m has the value [47m(1 4 6)[0m but [47m(LIST* 1 (+ 2 2) (+ 3 3))[0m has
  the value [47m(1 4 . 6)[0m.

  Perhaps more interestingly, the value of [47m(EQUAL (CONS (- 6 1) 7)
  (CONS 5 (+ 5 2)))[0m is [47mT[0m.  ``Behind the scenes'' those two calls of
  [47mCONS[0m return two different pointers to two different newly allocated
  regions of memory, but the [3mcar[0m and [3mcdr[0m fields of both objects are
  the same, namely [47m5[0m and [47m7[0m respectively.  ACL2 cannot tell those two
  pointers apart.  Operationally, [47mEQUAL[0m checks equality recursively
  down to the tips of both objects.  But logically, both [47mCONS[0m
  expressions here return the pair [47m(5 . 7)[0m.


Common Patterns of Recursion

  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 [47mvisit[0m several different
  ways to illustrate common recursions.  (In ACL2 you are not allowed
  to define a function more than one way; there is no ``overriding,''
  ``hiding,'' or ``overloading.'' These multiple definitions are just
  a device for illustrating a lot of definitions without burdening
  you with many different names.)


Visiting every element of a linear list

    (defun visit (lst ...)
      (cond ((endp lst) ...)              ; [3mNo elements left to process.[0m
            (t .                          ; [3mSome elements to process:[0m
                .
                 .
                  (car lst)               ; [3mdo something with this element[0m

                  (visit (cdr lst) ...)   ; [3mand visit the rest.[0m
                 .
                .
               .)))

  We illustrate this scheme in the next section.


Visiting every node and leaf in a binary tree

    (defun visit (tree ...)
      (cond ((atom tree) ...)             ; [3mThe tree is a leaf: do something.[0m

            (t .                          ; [3mThe tree is an interior node:[0m
                . tree                    ; [3mdo something with it,[0m
                 .
                   (visit (car tree) ...) ; [3m visit nodes in left branch, and[0m

                 . (visit (cdr tree) ...) ; [3m visit nodes in right branch.[0m
                .
               .)))

  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 [47mcdr[0m chain and consider the [47mcar[0m of each such
  subtree as the ``data,'' or element, to be processed.  We
  illustrate this recursion below.


Visiting all the natural numbers from n to 0

    (defun visit (n ...)
      (cond ((zp n) ...)                  ; [3mN ``is'' 0: finish up![0m
            (t .                          ; [3mN is a positive integer:[0m
                . n                       ; [3mdo something with it, and[0m
                 .
                  (visit (- n 1) ...)     ; [3mvisit the naturals below it.[0m
                 .
                .
               .)))

  The reason ``is'' is in quotation marks above is that [47m(zp n)[0m is true
  if either [47mn[0m is 0 or [47mn[0m is not a natural number.  For example, [47m(zp
  -3)[0m and [47m(zp 1/3)[0m both return true!  So when [47m(zp n)[0m is true you
  don't [3mreally[0m know [47mn[0m is 0 but you do know there is nothing more to
  do, if you're thinking of [47mn[0m as a natural number.  When [47m(zp n)[0m is
  false, you [3mknow[0m [47mn[0m is a positive integer.  The predicate [47mzp[0m is just
  a convenient way to recur through natural numbers and guarantees to
  halt the recursion even if you call the function on ``unexpected''
  input, whether numeric or not.


Computing Results

  When you define a recursive function you often have the choice of
  computing the results ``on the way up'' or ``on the way down.''

  Suppose [47mx[0m is a linear list of numbers and you wish to sum them.
  Here are two ways:

    (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)))))

  For example [47m(sum-up '(1 2 3 4))[0m is [47m10[0m and [47m(sum-down '(1 2 3 4) 7)[0m is
  [47m17[0m.  Both definitions fit within the ``visiting every element of a
  linear list'' recurrence scheme.

  Note that [47msum-up[0m takes a list of numbers and returns their sum while
  [47msum-down[0m takes a list of numbers and some initial value and adds
  the numbers in the list to the initial value.  Of course, [47m(sum-up
  x)[0m is equal to [47m(sum-down x 0)[0m --- but only because the operation of
  addition is insensitive to the order in which the additions are
  done.

  In many applications, the [47msum-up[0m 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 [47msum-down[0m 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 [47msum-down[0m style, one must carefully inspect
  how [47mtemp[0m is used to determine if it is just the final answer or is
  being used to direct the computation.

  Of course, sometimes information about the elements already visited
  is necessary to decide how to process subsequent ones, in which
  case the [47msum-down[0m style might be the appropriate choice.

  Finally, when these two functions are compiled in a straightforward
  way, the recursion in [47m sum-up[0m may a call stack while the recursion
  in [47m sum-down[0m does not: [47msum-down[0m is [3mtail recursive[0m.  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 ``remember'' to come
  back after the call to ``do something.'' In [47msum-up[0m the execution
  engine must ``remember'' to add the two intermediate results
  together.  Tail recursive calls can be compiled as simple jumps or
  ``gotos'' 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.


Saving Intermediate Results

  ACL2 is applicative so it does not have assignment statements.  But
  it is possible to use ``local variables'' to save intermediate
  results.  Here is a function that computes x^4 + y^4, i.e., the sum
  of the fourth powers of [47mx[0m and [47my[0m.

    (defun x4y4 (x y)
      (let ((x2 (* x x))            ; Let x2 be x^2 and, ``simultaneously,''
            (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.

  For example, [47m(x4y4 2 3)[0m is [47m16[0m + [47m81[0m or [47m97[0m.  The [47mlet[0m 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 [47mlet[0m.

  [47mLet[0m expressions are formalized in ACL2 as applications of anonymous
  functions.  For example, [47m(let ((v1 a1) (v2 a2)) (g v1 v2))[0m is
  actually transformed into [47m((lambda (v1 v2) (g v1 v2)) a1 a2)[0m where
  the [47mlambda[0m expression is an anonymous function with two parameters,
  [47mv1[0m and [47mv2[0m, and body [47m(g v1 v2)[0m.  The terms [47ma1[0m and [47ma2[0m that determine
  the values of the local variables in the [47mlet[0m become the argument
  expressions on which the anonymous function is called.

  While [47mlet[0m binds its variables in parallel, [47mlet*[0m binds its variables
  sequentially.  The expression

    (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.

  computes [47mx[0m^8.

  Here is an example of a common use of [47mlet[0m.  Suppose you wish to find
  the length of the longest branches in a binary tree.  The function
  [47mdepth[0m does that.  It is an example of the ``visit every node in a
  binary tree'' scheme.

    (defun depth (x)
      (cond ((atom x) 0)
            (t (let ((left-depth (depth (car x)))
                     (right-depth (depth (cdr x))))
                  (if (< left-depth right-depth)
                      (+ 1 right-depth)
                      (+ 1 left-depth))))))

  Just to illustrate the definition and list notation, consider the
  tree

         *
        / \\
       /   \\
      *     *
     / \\   / \\
    a   * e   *
       / \\   / \\
      b   * f   g
         / \\
        c   d

  The longest branches in this tree have length four and terminate in
  either [47mc[0m or [47md[0m.  This tree can be written

    ((a . (b . (c . d))) . (e . (f . g)))

  or equivalently as [47m((a b c . d) e f . g)[0m.

  The expression [47m(depth '((a b c . d) e f . g))[0m has value 4.

  We could have defined this function this way:

    (defun depth (x)
      (cond ((atom x) 0)
            (t (if (< (depth (car x))
                      (depth (cdr x)))
                   (+ 1 (depth (cdr x)))
                   (+ 1 (depth (car x)))))))

  But this would execute less efficiently because after recurring into
  both the car and cdr of [47mx[0m to determine which is deepest it recurs
  into one of them again to return the answer.  The use of [47mlet[0m
  eliminates this duplication of effort by saving the results of the
  earlier calls.

  Still a third way to define [47mdepth[0m might be

    (defun depth (x)
      (cond ((atom x) 0)
            (t (+ 1 (max (depth (car x))
                         (depth (cdr x)))))))

  where [47m(max i j)[0m is defined to be [47m(if (&lt; i j) j i)[0m.  This
  definition executes almost as efficiently as the first one.  The
  values of the two recursive calls are passed to the subroutine [47mmax[0m.
  [47mMax[0m uses [47mi[0m twice and [47mj[0m twice but now that ``duplication of effort''
  only requires looking up the values of variables, just as in the
  [47mlet[0m case.


Sample Definitions


Functions on Linear Lists

  The next several functions all illustrate the ``visiting every
  element of a linear list'' recurrence scheme.

    (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)))))

  Equivalently:

    (defun mem (e x)
      (if (endp x)
          nil
          (if (equal e (car x))
              t
              (mem e (cdr x)))))

  or even

    (defun mem (e x)
      (and (not (endp x))
           (or (equal e (car x))
               (mem e (cdr x)))))

  (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.)

  For all three of the above definitions, the following examples hold:

    ACL2 p!>(mem 'd '(a b c d e f g))
    T
    ACL2 p!>(mem 'd '(a b c   e f g))
    NIL
    ACL2 p!>

  Here is a function to concatenate two lists together:

    (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.

  Here are some examples of [47mapp[0m.

    ACL2 p!>(app '(1 2 3) '(a b c d))
    (1 2 3 A B C D)
    ACL2 p!>(app '(1 2 3) nil)
    (1 2 3)
    ACL2 p!>(app (app '(1 2 3) '(4 5 6)) '(7 8 9))
    (1 2 3 4 5 6 7 8 9)
    ACL2 p!>

  Here is a function to find the first pair in an alist (if any) that
  binds a given key.

    (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.

  Here are some examples.

    ACL2 p!>(lookup 'b '((a . 1)(b . 2) (c . 3)))
    (B . 2)
    ACL2 p!>(lookup 'd '((a . 1)(b . 2) (c . 3)))
    NIL
    ACL2 p!>(lookup 'b '((a . 1)(b . 2) (b . 3)))
    (B . 2)
    ACL2 p!>

  Note that only the first binding of the key matters.

  Here is a function to ``change'' the value of a key in an alist.
  Note that it does not modify the alist but produces a new alist.

    (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.

    ACL2 p!>(store 'b 7 '((a . 1) (b . 2) (c . 3)))
    ((A . 1) (B . 7) (C . 3))
    ACL2 p!>(store 'x 26 '((a . 1) (b . 2)))
    ((A . 1) (B . 2) (X . 26))
    ACL2 p!>(store 'c 3 '((a . 1) (b . 2) (x . 26)))
    ((A . 1) (B . 2) (X . 26) (C . 3))

  It is important to recall that ACL2 is functional (side-effect
  free)!  Despite its name, [47mstore[0m does not change the alist it is
  given but returns a new one.  Consider

    ACL2 p!>(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!>

  The above expression binds [47malist1[0m to an alist in which [47mb[0m is
  associated with 2.  Then it uses [47mstore[0m to bind [47mb[0m in [47malist1[0m to the
  new value [47m7[0m and calls the result [47malist2[0m.  Then it returns the list
  containing the values of looking up [47mb[0m in each of the alists.  You
  might think the answer would be [47m((B . 7) (B . 7))[0m and it [3mwould be
  if[0m [47mstore[0m actually changed [47malist1[0m to create [47malist2[0m.  But in fact
  [47malist1[0m is not changed.  The answer is [47m((B . 2) (B . 7))[0m.


Functions on Binary Trees

  Here is a function to count the number of tips of a binary tree.
  This function illustrates the ``visiting every node of a binary
  tree'' scheme.

    (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.

  The function above does the computation ``on the way up.''

  Here is a version that does it ``on the way down.''

    (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)))))

  This function has one tail recursive call.

  Let [47mx[0m be the tree

         *
        / \\
       /   \\
      *     *
     / \\   / \\
    a   * e   *
       / \\   / \\
      b   * f   g
         / \\
        c   d

  which we can write as [47m'((a b c . d) e f . g)[0m.  Then [47m(count-tips x)[0m
  is [47m7[0m (here we mean to use the first version of the definition).
  Similarly, [47m(count-tips x 0)[0m is also [47m7[0m (here we mean to use the
  second version).


Mutual Recursion

  ACL2 requires that subroutines be defined before they are used in
  other definitions.  So what do you do if you have two functions, [3mf[0m
  and [3mg[0m, and [3mf[0m calls [3mg[0m and [3mg[0m calls [3mf[0m?  You define them together.
  This is called [3mmutual recursion[0m.

  The example below shows a very inefficient way to factor a number
  into a list of primes.

    (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)))))
    )

  We can read this as follows.  To determine the [47mfactors[0m of [3mn[0m, call
  [47mfactors-below[0m on [3mn[0m and [3mn-1[0m to collect all the factors of [3mn[0m less
  than or equal to [3mn-1[0m.  To find all the factors of [3mn[0m less than or
  equal to [3mm[0m, consider three cases.  First, if [3mm[0m is 0 or 1, return
  the list containing just [3mn[0m.  Second, if [3mn/m[0m is an integer (i.e., [3mm[0m
  divides [3mn[0m), then use [47mapp[0m to concatenate the factors of [3mn/m[0m to the
  factors of [3mm[0m.  Third (and otherwise), find the factors of [3mn[0m below
  [3mm-1[0m.

  We can run [47mfactors[0m.  For example [47m(factors 12)[0m returns [47m(2 2 3)[0m.  If we
  call [47m(factors 123456789)[0m the computation takes a while (27 seconds
  on my laptop) and returns [47m(3 3 3607 3803)[0m.  [47m(Factors (- (expt 2 31)
  1))[0m takes about 500 seconds and returns [47m(2147483647)[0m.


Returning and Using Multiple Values

  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, [47mnodes[0m) how many cons nodes it sees and
  counts (in its third argument, [47mtips[0m) how many tips it sees.  It
  returns both numbers as a list of length 2 (without actually
  creating the intermediate lists).

    (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)))))

  For example,

    (node-and-tip-count '((a . b) . (c . d)) 0 0)
    = (3 4)

  Thus, the tree in question has 3 cons nodes and 4 (non-cons) tips.

  If you want to use multiple values you should read the ACL2
  documentation on that topic.


Type Errors

  The ACL2 programming language is untyped.  Objects have types that
  can be checked at runtime with predicates like [47mintegerp[0m, [47mconsp[0m,
  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, [47m+[0m expects its arguments to be numbers.
  If you supply a non-numeric input to [47m+[0m it will use [47m0[0m instead.
  Thus, the value of [47m(+ 3 T)[0m is [47m3[0m.  [47mCar[0m and [47mcdr[0m expect their
  arguments to be either a cons pair or [47mnil[0m.  (A special case in Lisp
  is that [47mcar[0m and [47mcdr[0m return [47mnil[0m on [47mnil[0m.)  If called on objects of
  the wrong type, [47mcar[0m and [47mcdr[0m default the argument to [47mnil[0m.

  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
  [47m:set-guard-checking nil[0m command as shown in the session below.

    ACL2 p!>(+ 2 2)
    4
    ACL2 p!>(+ 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!>: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>(+ 2 T)
    2
    ACL2 p>(CAR 'ABC)
    NIL
    ACL2 p>

  Note that the prompt changes after the [47m:set-guard-checking[0m command
  above.  The exclamation mark ([47m![0m) in the standard prompt indicates
  that types are being checked.


Stack Overflow

  Sometimes a computation will consume more space than your machine
  has.  For example, the following function constructs a list of [47mn[0m
  [47mnil[0ms.

    (defun nils (n)
      (if (zp n)
          nil
          (cons nil (nils (- n 1)))))

  We can run it on small values of [47mn[0m.

    (nils 10) = (nil nil nil nil nil nil nil nil nil nil)

  So that we don't have to read long lists of [47mnil[0ms below we just take
  the length of the result with the ACL2 function [47mlen[0m.

    ACL2 p!>(len (nils 10))
    10
    ACL2 p!>(len (nils 100))
    100
    ACL2 p!>(len (nils 1000))
    1000
    ACL2 p!>(len (nils 10000))
    10000
    ACL2 p!>(len (nils 100000))
    100000
    ACL2 p!>(len (nils 1000000))
    1000000
    ACL2 p!>(len (nils 10000000))
    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Stack overflow on value stack.
    ...
    :q
    ACL2 p!>

  But that last test, where we attempt to produce a list of ten million
  [47mnil[0ms, 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 [47m:q[0m followed by return, but in
  Allegro CL you type [47m:reset[0m followed by return, and in CMU CL you
  type [47mq[0m followed by return.)

  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.

  However, often you can just code up a more efficient algorithm.  For
  example, the following tail-recursive version of [47mnils[0m won't
  overflow the stack.

    (defun nils (n ans)
      (if (zp n)
          ans
          (nils (- n 1) (cons nil ans))))

  So now

    ACL2 p!>(len (nils 10000000 nil))
    10000000
    ACL2 p!>(len (nils 100000000 nil))
    100000000
    ACL2 p!>(len (nils 1000000000 nil))
    1000000000
    ACL2 p!>

  Of course, it will eventually use up all the memory.

  The tests above sort of suggest we're interested in the question
  ``Does [47m(nils n nil)[0m always return a list of length [47mn[0m?'' 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!

  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.

    ACL2 p!>:logic
    ACL2 !>(verify-termination nils)
    ...
    ACL2 !>(defthm lemma-about-nils
            (implies (natp n)
                     (equal (len (nils n ans))
                            (+ n (len ans)))))
    ...
    ACL2 !>(defthm main-theorem-about-nils
            (implies (natp n)
                     (equal (len (nils n nil)) n)))
    ...

  That is, switch back into logic mode, admit [47mnils[0m to the logic by
  proving termination, prove the general theorem that [47m(nils n ans)[0m
  returns a list whose length is [47mn[0m plus the length of [47mans[0m, when [47mn[0m is
  natural number, and then prove the main theorem.  Your job as an
  ACL2 ``theorem prover driver'' is to think of the commands.  The
  prover does the work to complete each of those steps.

  So maybe you should learn to prove theorems about your functions?  If
  so, see ``Recursion and Induction''.


Conclusion

  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 {ACL2 Home Page |
  https://www.cs.utexas.edu/users/moore/acl2} 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.

  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.")
 (GENVAR (POINTERS)
         "See [system-utilities].")
 (GET-BRR-LOCAL (POINTERS)
                "See [system-utilities].")
 (GET-CHECK-INVARIANT-RISK (POINTERS)
                           "See [set-check-invariant-risk].")
 (GET-COMMAND-SEQUENCE
  (HISTORY)
  "Return list of [command]s that are between two [command] descriptors

    Examples:
    (get-command-sequence 4 12)
    :gcs 4 12 ; same as above
    (get-command-sequence 4 :x)
    :gcs 4 :x ; same as above

  See [pcs] for a utility that prints abbreviated information about the
  [command]s that are between two command descriptors.  The utility
  [47mget-command-sequence[0m --- or simply [47mgcs[0m, so that you can just type
  [47m:gcs[0m at the prompt --- has the same syntax but instead of printing,
  it simply returns the corresponding list of commands.  More
  precisely, it returns an [error-triple] [47m(mv erp val state)[0m such
  that if [47merp[0m is not [47mnil[0m, then [47mval[0m is the desired list of commands.")
 (GET-CPU-TIME
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS READ-RUN-TIME)
  "Read elapsed cpu time

  [47m(Get-cpu-time state)[0m returns the elapsed cpu time in seconds since
  the start of the current ACL2 session.  See [read-run-time] for
  further documentation.

  [31;1mFunction: [0m<get-cpu-time>

    (defun get-cpu-time (state)
      (declare (xargs :stobjs state))
      (read-run-time state))")
 (GET-DEFUN-EVENT (POINTERS)
                  "See [system-utilities].")
 (GET-ENFORCE-REDUNDANCY
  (REDUNDANT-EVENTS)
  "Query the [world] on whether redundancy is being enforced

  See [set-enforce-redundancy] for relevant background.  For a given
  world, [47mwrld[0m --- typically, [47m(w state)[0m --- the value of
  [47m(get-enforce-redundancy wrld)[0m is [47mnil[0m, [47mt[0m, or [47m:warn[0m according to the
  most recent call of [47mset-enforce-redundancy[0m, [47mnil[0m by default.")
 (GET-EVENT (POINTERS)
            "See [system-utilities].")
 (GET-EVENT-DATA
  (SYSTEM-UTILITIES OUTPUT-CONTROLS)
  "Obtain data stored after at the conclusion of an event

  Warning: This is a low-level system utility that may change somewhat
  over time.  For more details, see the ACL2 source code.

  Evaluation of the form [47m(get-event-data key state)[0m returns the value
  of [47mkey[0m in an association list, which we call an [3mevent-data alist[0m.
  Such an alist is the value of [state] global variable
  [47mlast-event-data[0m.  (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 [summary].  We
  anticipate continuing to support at least the following keys, each
  with value [47mVAL[0m as follows.

    * [47mABORT-CAUSES[0m: [47mVAL[0m is a list of reasons why the proof aborted.  In
      particular, if the value [47mINTERRUPT[0m is in the list, then the
      proof was interrupted (typically with Control-C).

    * [47mEVENT[0m: the [event].

    * [47mFORM[0m: [47mVAL[0m is the ``context'' for the event, printed in the summary,
      [warnings], and [errors].

    * [47mHINT-EVENTS[0m: [47mVAL[0m is as in the corresponding field of the event
      summary.

    * [47mNAMEX[0m: [47mVAL[0m is 0, a single name, or a list of names; see comments in
      ACL2 source function [47maccess-event-tuple-namex[0m.

    * [47mPROVER-STEPS-COUNTED[0m: [47mVAL[0m is as in the corresponding field of the
      event summary.  Note: This value can be obtained using
      [47m[last-prover-steps][0m.

    * [47mRULES[0m: [47mVAL[0m is as in the corresponding field of the event summary.

    * [47mSPLITTER-RULES[0m: [47mVAL[0m represents the corresponding field of the event
      summary, as the list [47m(case-split immed-forced if-intro)[0m.

    * [47mSYSTEM-ATTACHMENTS[0m: [47mVAL[0m lists the pairs [47m(f . g)[0m for which [47mf[0m is a
      system function with attachment [47mg[0m ([defattach]), which differs
      from the attachment to [47mf[0m when ACL2 starts up.

    * [47mTIME[0m: [47mVAL[0m represents the corresponding field of the event summary, as
      the list [47m(prove print proof-tree other)[0m.

    * [47mWARNINGS[0m: [47mVAL[0m is as in the corresponding field of the event summary.")
 (GET-GUARD-CHECKING
  (REDUNDANT-EVENTS)
  "Get the status most recently installed by [47m[set-guard-checking][0m

  See [set-guard-checking] for relevant background.  The value returned
  by [47m(get-guard-checking)[0m is [47mt[0m by default, but is the value most
  recently installed for [guard]-checking, typically supplied as the
  argument of a call of [47m[set-guard-checking][0m.")
 (GET-IN-THEORY-REDUNDANT-OKP (POINTERS)
                              "See [set-in-theory-redundant-okp].")
 (GET-INTERNAL-TIME
  (PROGRAMMING ACL2-BUILT-INS)
  "Runtime vs. realtime in ACL2 timings

  The ACL2 system provides utilities that deal with elapsed time.
  These are most visibly used in reporting the time summaries when
  completing evaluation of [events].  For utilities that return
  elapsed cpu or run time, see [read-run-time], [get-cpu-time], and
  [get-real-time].  Other time-related utilities include
  [with-prover-time-limit], [time-tracker], [time-tracker-tau], see
  [pstack].

  By default, these utilities all use an underlying notion of run time
  provided by the host Common Lisp implementation: specifically, the
  Common Lisp functions [47mget-internal-run-time[0m for cpu time (or a
  slight variant if the host Lisp is a version of GCL that precedes
  2.7.0) and [47mget-internal-real-time[0m 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.

    (defttag t) ; to allow sys-call
    (make-event
     (prog2$ (sys-call \"sleep\" '(\"2\"))
             (value '(value-triple nil))))

  A typical time [summary] might be as follows, drastically
  under-reporting the actual elapsed (real, wall clock) time.

    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)

  However, you can instruct ACL2 to switch to using elapsed time (real
  time), in summaries and elsewhere, by evaluating the following
  form.

    (assign get-internal-time-as-realtime t)

  To return to using runtime:

    (assign get-internal-time-as-realtime nil)

  While the above example is rather silly, the issue becomes
  significant in time summaries for proofs that call out to external
  tools (see [sys-call] and see [clause-processor]).

  Note that a function [47mget-internal-time[0m is defined in raw Lisp but is
  not available inside the ACL2 loop.  However, the expression
  [47m(read-run-time state)[0m provides an interface to this function that
  is available inside the ACL2 loop; see [read-run-time], and also
  see [get-cpu-time] and [get-real-time].")
 (GET-OUTPUT-STREAM-STRING$ (POINTERS)
                            "See [io].")
 (GET-PERSISTENT-WHS
  (WORMHOLE)
  "Make a wormhole's status visible outside the wormhole

    General Form:
    (get-persistent-whs name state)

  [47mName[0m should be the name of a wormhole (see [wormhole]).  This
  function returns an [error-triple] of the form [47m(mv nil s state)[0m,
  where [47ms[0m 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 [47m[state][0m with
  [47m[read-ACL2-oracle][0m.

  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 [47mcar[0m is the ``entry code'' ([47m:enter[0m or [47m:skip[0m) or, more
  precisely, is either [47m:skip[0m or not [47m:skip[0m, the latter case being
  treated like [47m:enter[0m.  But the [47mcdr[0m 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 [47m'wormhole-status[0m and is thus accessible
  via [47m(f-get-global 'wormhole-status state)[0m.  We call this copy of
  the status the ephemeral-whs because when the wormhole is exited
  the ephemeral-whs is moved to the [47mpersistent-whs[0m and the state
  global [47m'wormhole-status[0m is restored to whatever value it had when
  the wormhole was entered.

  See [47m[wormhole-status][0m for a discussion of these two senses of the
  status of a wormhole.  See also [wormhole-programming-tips].")
 (GET-REAL-TIME
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS READ-RUN-TIME)
  "Read elapsed real time

  [47m(Get-real-time state)[0m returns [47m(mv rtime state)[0m where [47mrtime[0m is the
  elapsed real (wall clock) time in seconds since the start of the
  current ACL2 session.  See [read-run-time] for further
  documentation.

  [31;1mFunction: [0m<get-real-time>

    (defun get-real-time (state)
      (declare (xargs :stobjs state))
      (read-run-time state))")
 (GET-REGISTER-INVARIANT-RISK (POINTERS)
                              "See [set-register-invariant-risk].")
 (GET-SERIALIZE-CHARACTER (POINTERS)
                          "See [with-serialize-character].")
 (GET-SKIPPED-PROOFS-P (POINTERS)
                       "See [system-utilities].")
 (GETENV$
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Read an environment variable

  [47m(Getenv$ str state)[0m, where [47mstr[0m is a string, reads the value of
  environment variable [47mstr[0m, returning a value of [47mnil[0m 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 [47m[char-code][0m
  exceeding 255, then an error is signaled.)  The logical story is
  that [47mgetenv$[0m reads its value from the [47moracle[0m field of the ACL2
  [47m[state][0m.  The return value is thus a triple of the form [47m(mv erp val
  state)[0m, where [47merp[0m will always be [47mnil[0m in practice, and logically,
  [47mval[0m is the top of the acl2-oracle field of the state (see
  [47m[read-ACL2-oracle][0m) and the returned state has the updated (popped)
  acl2-oracle.

    Example:
    (getenv$ \"PWD\" state) ==> (mv nil \"/u/joe/work\" state)

  Also see [setenv$].

  [31;1mFunction: [0m<getenv$>

    (defun getenv$ (str state)
      (declare (xargs :stobjs state
                      :guard (stringp str)))
      (declare (ignore str))
      (read-acl2-oracle state))")
 (GETPROP
  (WORLD ACL2-BUILT-INS)
  "Access fast property lists

    General form:
    (getprop symb key default world-name world-alist)

  See [getpropc] for a convenient abbreviation, and see [world] for
  discussion of both utilities [47mgetprop[0m and [47m[putprop][0m.  Also see
  community book [47mbooks/misc/getprop.lisp[0m for an example that
  illustrates the use of ACL2 utilities [47mgetprop[0m and [47mputprop[0m to take
  advantage of under-the-hood Lisp (hashed) property lists.

  [31;1mMacro: [0m<getprop>

    (defmacro getprop (symb key default world-name world-alist)
      (if (equal world-name ''current-acl2-world)
          (cons 'fgetprop
                (cons symb
                      (cons key
                            (cons default (cons world-alist 'nil)))))
        (cons 'sgetprop
              (cons symb
                    (cons key
                          (cons default
                                (cons world-name
                                      (cons world-alist 'nil))))))))")
 (GETPROPC
  (WORLD ACL2-BUILT-INS)
  "Access fast property lists

    General form:
    (getpropc symb key &optional default world-alist)

  where [47mdefault[0m is [47mnil[0m if omitted, and [47mworld-alist[0m is [47m(w state)[0m if
  omitted.  This is a convenient abbreviation for the common case in
  which [47m[getprop][0m is used for system programming, with
  [47m'current-acl2-world[0m as the (implicit, for [47mgetpropc[0m) world-name.

  [31;1mMacro: [0m<getpropc>

    (defmacro getpropc (symb key &optional
                             default (world-alist '(w state)))
      (cons 'getprop
            (cons symb
                  (cons key
                        (cons default
                              (cons ''current-acl2-world
                                    (cons world-alist 'nil)))))))")
 (GETTING-STARTED (POINTERS)
                  "See [ACL2-tutorial].")
 (GIT-QUICK-START
  (ABOUT-ACL2)
  "Git quick start guide

  Each of the two topics [github-commit-code-using-push] and
  [github-commit-code-using-pull-requests] presents a minimal guide
  to using the Github repository for ACL2+Books.  That {repository |
  https://github.com/acl2/acl2} exists on the web and contains the
  ``bleeding edge'' ACL2 source code and [community-books], available
  between ACL2 releases (see [release-notes]).  Those who are
  familiar with older version control systems, or perhaps with no
  version control systems, might find this guide to be helpful.  For
  additional information, including the use of branches and links to
  more information about git, see {the wiki page for git tips |
  https://github.com/acl2/acl2/wiki/ACL2-repo-git-tips},
  [books-certification], and the Internet in general.  However, both
  of the above-mentioned guides are intended to be sufficient for you
  to obtain the latest ACL2 source code and community-books, and
  optionally, for you to contribute to the [community-books].

  Select the guide that is right for you based upon the headings below.


For non-contributors:

See sections (A) and (B) in [github-commit-code-using-push].


For infrequent contributors:

For those only planning on contributing a few times per year (or
less), see [github-commit-code-using-pull-requests].


For frequent contributors:

For those contributing on a monthly or weekly basis, see
[github-commit-code-using-push].


Subtopics

  [Github-commit-code-using-pull-requests]
      How to commit code to the books using pull requests

  [Github-commit-code-using-push]
      How to commit code to the books using direct push access")
 (GITHUB-COMMIT-CODE-USING-PULL-REQUESTS
  (GIT-QUICK-START)
  "How to commit code to the books using pull requests

  This guide is written for contributors who will probably only commit
  to the repository a few times a year. If you find yourself
  committing more often, you should see
  [github-commit-code-using-push].

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 [3mFork and Pull[0m method.


(A) GETTING STARTED

   1. Go to {https://github.com/acl2/acl2 | https://github.com/acl2/acl2}
      and click on the [47mfork[0m button on the top-right.  Fork the
      repository into your github space.  This will create a new
      repository at [47mhttps://github.com/<your-github-username>/acl2[0m.

   2. In your working space on your computer, create a [47mclone[0m of your github
      repository and [47mcd[0m into it:

          git clone https://github.com/<your-github-username>/acl2
          cd acl2

   3. Add the Community ACL2 repository as a git remote:

          git remote add upstream https://github.com/acl2/acl2


(B) UPDATING

  The following commands will update your local repository to match the
  latest contents of the ACL2 Community github repository (on the
  web).

    git fetch --all
    git merge remotes/upstream/master


(C) CONTRIBUTING


Change and Test

   1. Before beginning your edits, update, as in (B) above:

          git fetch --all
          git merge remotes/upstream/master

   2. Build an executable.

          (time nice make LISP=<your_lisp>) >& make.log

   3. Make book changes.  If you are creating any new books, tell git that
      you intend to add them (but the local repository on the web
      won't change until the [47mcommit[0m step below is executed).

          git add file1 file2 ...

      Also, consider adding some high-level information about your changes
      to the Community Books' release notes --- i.e., the appropriate
      [release-notes-books] XDOC topic in [47mbooks/doc/relnotes.lisp[0m.

   4. Run a regression.

          (time nice make -j 8 regression-fresh) >& make-regression.log

      Note that the [47m-j 8[0m 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).

   5. Look for failures, as indicated by [47m**[0m in the log.

          fgrep -a '**' make-regression.log

   6. If there were failures, then go back to Step 1 above to make
      appropriate changes and re-test, but you can replace the '[47mmake[0m'
      step by replacing [47mregression-fresh[0m with [47mregression[0m, since
      '[47mmake[0m' is clever enough to avoid recertifying more than is
      necessary.  For example:

          (time nice make -j 8 regression) >& make-regression-finish-1.log


Update, and Iterate If Necessary

  Update again as in (B) above:

    git fetch --all
    git merge remotes/upstream/master

      The merge may fail if there have been remote updates, that is updates
      in the repository on the web.  In that case, commit your
      changes locally and then try the merge again.  You might want
      to use the [47m-F[0m option instead of [47m-m[0m; see the next section for
      more on those options.

        git commit -a -m '<some message, with descriptive first line>'
        git merge remotes/upstream/master

      If the second command (the [47mgit merge[0m) prompts you for a message, the
      empty message should suffice as a reasonable default (in emacs
      --- if vi tries to come up, just type [47m:q[0m and [47m<RETURN>[0m.

  You can now go on to the next step (Contribute Your Changes).  But
  ideally: If the output indicates that anything has changed, then go
  back to ``Change and Test'' above.  Of course, you can skip the
  build if no ACL2 sources have changed, and you can skip making book
  changes if you are still happy with your changes.


Contribute Your Changes

  The following commands will update your github repository on the web.
  The [47m-m ...[0m option is a log message whose first line should be a
  summary of your changes and other lines may give more details.  You
  are welcome to replace the [47m-m ...[0m option by [47m-F <filename>[0m, where
  [47m<filename>[0m is the name of a file that contains your log message.

    git commit -a -m '<some message, with descriptive first line>'
    git push

You now need to create a [3mpull request[0m, where you request that
changes from your github repository be accepted into the Community
ACL2 repository.  To achieve this:

   1. Goto [47mhttps://github.com/<your-github-username>/acl2[0m.

   2. Click the [47mNew pull request[0m button (you can search for it with your
      browser).

   3. In the drop-down box labeled \"base\" (next to the box labeled \"base
      fork\"), change the value from \"master\" to \"testing\".

   4. Click [47mCreate pull request[0m.

   5. Put some explanation about what's in the changes in the comments
      section.  It's helpful if you quote (possibly abbreviated)
      versions of your commit log messages here, as that way the
      descriptions are easily read when clicking on the Community
      Repository [47mcommits[0m tab, which goes to {
      https://github.com/acl2/acl2/commits/master |
      https://github.com/acl2/acl2/commits/master}.

   6. Click [47mCreate pull request[0m.

At this point, the Community ACL2 repository maintainers will be
notified, check that things seem to be in order, and then adopt your
changes.")
 (GITHUB-COMMIT-CODE-USING-PUSH
  (GIT-QUICK-START)
  "How to commit code to the books using direct push access

  This guide is written for two groups of people:

    * Users of the ACL2 System and Books who do not plan to contribute to
      the books, and

    * Contributors who commit to the repository on a monthly or weekly
      basis.  In this case, a contributor will typically begin with
      the [github-commit-code-using-pull-requests] method, and after
      they are familiar with the process and community, they will
      move to this method.


(A) GETTING STARTED

  Start by obtaining an up-to-date copy of the web-based github
  repository.  Here, we show how to put it into into a directory
  called [47mACL2[0m (but name it whatever you like).

    mkdir ACL2
    cd ACL2
    git clone https://github.com/acl2/acl2 .


(B) UPDATING

  The following commands will update your directory to match the latest
  contents of the github repository (on the web).

    git fetch --all
    git merge remotes/origin/master


(C) CONTRIBUTING (optional)

  To join the {github project | https://github.com/acl2/acl2/}, please
  send email to one of the following individuals.

    * Jared Davis ([47mjared.c.davis@gmail.com[0m)

    * David Rager ([47mragerdl@gmail.com[0m)

    * Sol Swords ([47msswords@gmail.com[0m)

  After you have joined the project, you can proceed as follows when
  you are ready to contribute.


Change and Test

   1. Update as in (B) above:

          git fetch --all
          git merge remotes/origin/master

   2. Build an executable.

          (time nice make LISP=<your_lisp>) >& make.log

   3. Make book changes.  If you are creating any new books, tell git that
      you intend to add them (but the repository on the web won't
      change until the last step below is executed).

          git add file1 file2 ...

      Also, consider adding some high-level information about your changes
      to the Community Books' release notes --- i.e., the appropriate
      [release-notes-books] XDOC topic in [47mbooks/doc/relnotes.lisp[0m.

   4. Run a regression.

          (time nice make -j 8 regression-fresh) >& make-regression.log

   5. Look for failures, as indicated by [47m**[0m in the log.

          fgrep -a '**' make-regression.log

   6. If there were failures, then go back to Step 1 above to make
      appropriate changes and re-test, but you can replace the '[47mmake[0m'
      step by replacing [47mregression-fresh[0m with [47mregression[0m, since
      '[47mmake[0m' is clever enough to avoid recertifying more than is
      necessary.  For example:

          (time nice make -j 8 regression) >& make-regression-finish-1.log

      Note that the [47m-j 8[0m 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).


Update, and Iterate If Necessary

  Update again as in (B) above:

    git fetch --all
    git merge remotes/origin/master

      The merge may fail if there have been remote updates, that is updates
      in the repository on the web.  In that case, commit your
      changes locally and then try the merge again.  You might want
      to use the [47m-F[0m option instead of [47m-m[0m; see the next section for
      more on those options.

        git commit -a -m '<some message, with descriptive first line>'
        git merge remotes/origin/master

      If the second command prompts you for a message, the empty message
      should suffice as a reasonable default.  (In emacs, if vi tries
      to come up, just type [47m:q[0m and [47m<RETURN>[0m.

  You can now go on to the next step (Contribute Your Changes).  But
  ideally: If the output indicates that anything has changed, then go
  back to ``Change and Test'' above.  Of course, you can skip the
  build if no ACL2 sources have changed, and you can skip making book
  changes if you are still happy with your changes.


Contribute Your Changes

  The following commands will update the github repository on the web.
  The [47m-m ...[0m option is a log message whose first line should be a
  summary of your changes and other lines may give more details.  You
  are welcome to replace the [47m-m ...[0m option by [47m-F <filename>[0m, where
  [47m<filename>[0m is the name of a file that contains your log message.

    git commit -a -m '<some message, with descriptive first line>'
    git push origin testing")
 (GOAL-SPEC
  (HINTS OUTPUT-CONTROLS)
  "To indicate where a hint is to be used

    Examples:
    \"Goal\"
    \"goal\"
    \"Subgoal *1/3''\"
    \"subgoal *1/3''\"
    \"[2]Subgoal *1/3''\"

  When [hints] are given to the theorem prover, a goal-spec is provided
  to specify the goal to which the [hints] are to be applied.  The
  [hints] provided are carried along innocuously until the named goal
  arises.  When it arises, the [hints] are ``activated'' for that
  goal and its descendents.

  A legal goal specification may be extracted from the theorem prover's
  output.  Certain lines clearly label formulas, as in

    Subgoal *1/3.2'
    (IMPLIES ... ...)

  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

    [1]Subgoal *1/3.2'
    (IMPLIES ... ...).

  A goal specification may be obtained by deleting any surrounding
  whitespace from such a line and embedding the text in string
  quotation marks.  Thus

    \"[1]Subgoal *1/3.2'\"

  is the goal specifier for the goal above.

  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 [47m\"[1]subgoal *1/3.2'\"[0m and
  [47m\"[1]SUBGOAL *1/3.2'\"[0m.  The matching algorithm does not tolerate
  non-case discrepancies.  Thus, [47m\"[1]Subgoal*1/3.2'\"[0m and [47m\" [1]Subgoal
  *1/3.2'\"[0m are unacceptable.

  Sometimes a formula is given two names, e.g.,

    Subgoal *1/14.2'
    (IMPLIES ...
             ...)
    Name the formula above *1.1.

  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 [hints] that
  are attached to that goal-spec.  Consider the example above.
  Suppose [47mSubgoal *1/14.2'[0m could be proved by using a certain lemma
  instance.  Then the appropriate entry in the [hints] would be:

    (\"Subgoal *1/14.2'\" :use ...)

  This might surprise you because the system appears to do nothing to
  [47m*1/14.2'[0m 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 [47muse[0m hint activated when [47mSubgoal *1/14.2'[0m
  arises is just what you want.

  But what if you want to give an [47m:induct[0m hint?  By the time induction
  is tried, the formula has been given the name [47m*1.1[0m.  Well, this is
  one you just have to remember:

    (\"Subgoal *1/14.2'\" :induct ...).

  When the above hint is activated the [47m:induct[0m 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.

  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 [47m'[0m for a suffix.  If a goal has a single subgoal then
  a prime is added; e.g., if [47m\"Subgoal 3.2\"[0m has a single subgoal then
  it is named [47m\"Subgoal 3.2'\"[0m rather than [47m\"Subgoal 3.2.1\"[0m.  If in turn
  that goal has a single subgoal, it is named [47m\"Subgoal 3.2''\"[0m; and so
  on.  When four or more primes would be generated, say, [47mn[0m primes,
  then the suffix is [47m\"'n'\"[0m; e.g., continuing the preceding example we
  get [47m\"Subgoal 3.2'''\"[0m, [47m\"Subgoal 3.2'4'\"[0m, [47m\"Subgoal 3.2'5'\"[0m, and so
  on.  If any of these generates at least two subgoals then any
  ``prime'' suffix is dropped; for example, if [47m\"Subgoal 3.2'5'\"[0m has
  two subgoals then they are named [47m\"Subgoal 3.2.2\"[0m and [47m\"Subgoal
  3.2.1\"[0m.

  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.

    (thm (equal (append (append x y) z) (append x y z))
         :hints ((\"Subgoal *1/\" :in-theory nil)))

  Normally, [47m:in-theory[0m hints are inherited by subgoals (see
  [hints-and-the-waterfall]), so you might expect that the empty
  theory is used in [47mSubgoal *1/2[0m and [47mSubgoal *1/1[0m.  But in fact,
  since there is no subgoal printed that is labeled [47mSubgoal *1/[0m, the
  above [47m:in-theory[0m hint is ignored.  The above example is in contrast
  to the following, where the hint makes the proof fail, because
  there really is a [47mSubgoal *1/[0m in the proof this time.

    (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)))


Subtopics

  [Clause-identifier]
      The internal form of a [goal-spec]")
 (GOOD-BYE
  (BASICS ACL2-BUILT-INS)
  "Quit entirely out of Lisp

    Examples:
    ACL2 !>(good-bye)
    ; [ACL2 is exited]

    ACL2 !>(good-bye 3)
    ; [ACL2 is exited with Unix exit status 3]

  Note: Your entire session will disappear forever when you evaluate
  [47m(good-bye)[0m.

  The command [47m(good-bye)[0m quits not only out of the ACL2 [command] loop,
  but in fact quits entirely out of the underlying Lisp.  Thus, there
  is no going back!  You will [31;1mnot[0m be able to re-enter the [command]
  loop after typing [47m(good-bye)[0m!  All your work will be lost!!!

  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.

  In some systems, typing [47mcontrol-d[0m at the top-level ACL2 prompt
  ([47mcontrol-c control-d[0m if inside emacs) will call this function.

  The optional argument for [47mgood-bye[0m (default 0) indicates the Unix
  (Linux) exit status.  If it is not an integer, it will be treated
  as 0.

  If you merely want to exit the ACL2 [command] loop, use [47m:q[0m instead.
  (That can be risky; see [q]).

  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 [47mexit-lisp[0m, you may see that it is
  called twice; the second call happens while cleaning up from an
  [47munwind-protect[0m call.


Subtopics

  [Exit]
      Quit entirely out of Lisp

  [Quit]
      Quit entirely out of Lisp")
 (GRANULARITY
  (PARALLEL-PROGRAMMING)
  "Limit the amount of parallelism

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

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

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

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

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

  We realize quickly that writing both of these function definitions is
  cumbersome and redundant.  This problem can be avoided by using a
  [47mgranularity[0m 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-[47mnil[0m value at the time
  of the call.  Below is a definition of the Fibonacci function using
  a granularity form.

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

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

    (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))))))))

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

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

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

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

  If you experiment with calls of [47mpvalid-tree[0m, 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
  [47msome-depth-exceeds[0m 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
  [47mSET::pmergesort-exec[0m.")
 (GRATUITOUS-LAMBDA-OBJECT-RESTRICTIONS
  (APPLY$)
  "Enforcement of logically unnecessary restrictions on [47m:FN[0m slots

  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 [47m(cadr x)[0m are expanded away and
  constants are always quoted.  See [term] for details of the
  internal form.

  But translation also enforces a logically unnecessary restriction in
  argument positions of [ilk] [47m:FN[0m.  If a quoted [47mconsp[0m object whose
  [47mcar[0m is the symbol [47mLAMBDA[0m occurs in a [47m:FN[0m slot, translate insists
  that the object satisfy [47m[well-formed-lambda-objectp][0m.
  Well-formedness implies tameness, so any [47mLAMBDA[0m object that passes
  this translate-time test will have the ``expected behavior'' under
  [47mapply$[0m.  If a quoted ill-formed ``LAMBDA-like'' object is passed
  into a [47m:FN[0m slot, an error is signaled.

  This is logically unnecessary because, like all ACL2 functions,
  [47mapply$[0m can be called on any objects.  Indeed, ill-formed
  [47mLAMBDA[0m-like objects induce some kind of default behavior by [47mapply$[0m
  and can, sometimes, deliver non-erroneous values.

  But ground [47mapply$[0m terms can be evaluated more quickly on well-formed
  [47mLAMBDA[0m objects than on ill-formed ones.  See for example the
  discussion of performance in [47m[print-cl-cache][0m.  So this restriction
  is really motivated by a desire to encourage the exclusive use of
  well-formed [47mLAMBDA[0m objects.

  Why would you want to call [47mapply$[0m on ill-formed input?  The answer is
  that you might be trying to explore the semantics of [47mapply$[0m 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 [47m:FN[0m slot.  Soundness is not
  imperiled but execution may slow down.

  [3mWarning[0m: Using an ill-formed [47mLAMBDA[0m object in a [47m:FN[0m slot in a [47mdefun[0m
  will make it impossible to warrant the newly defined function
  because it will not pass the stringent tests necessary to analyze
  its ilks.  See [47m[defwarrant][0m.  Basically these bypasses are intended
  primarily for top-level input to ACL2's read-eval-print loop.

  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 [47mLAMBDA[0m 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 [47m[defconst][0m and then
  use the defined constant symbol in the [47m:FN[0m slot.  We illustrate
  these and other points below.

    ; 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.

  By the way, [47m:FN[0m slots are treated differently in another way by
  translate: [47m[lambda$][0m terms are [3monly[0m allowed in [47m:FN[0m slots.  This
  restriction is necessary for ACL2's correct operation.  [47mLambda$[0m
  expands differently in the logic than it does in the underlying
  Common Lisp.  If [47mlambda$[0m 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.")
 (GROUND-ZERO
  (THEORIES THEORY-FUNCTIONS)
  "[enable]d rules in the [startup] theory

  ACL2 concludes its initialization [47m(boot-strapping)[0m procedure by
  defining the theory [47mground-zero[0m; see [theories].  In fact, this
  theory is just the theory defined by [47m(current-theory :here)[0m at the
  conclusion of initialization; see [current-theory].

  Note that by evaluating the event

    (in-theory (current-theory 'ground-zero))

  you can restore the current theory to its value at the time you
  started up ACL2.")
 (GTHM
  (HISTORY GUARD-FORMULA-UTILITIES)
  "The [guard] theorem for a given function symbol

  This utility (pronounced ``gee-thumb'') generates the [guard] theorem
  (i.e., guard proof obligation) for a given function symbol, as
  would be generated by a [47m:[0m[47m[guard-theorem][0m [lemma-instance] in a
  [47m:[0m[use] hint.

    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)

  where [47mFN[0m is a function symbol and [47mx[0m evaluates to a function symbol.
  Evaluation returns the guard theorem as a user-level (untranslated)
  [47m[term][0m.  The optional argument [47msimplify[0m, described below, is
  [47m:limited[0m by default.  The optional argument [47mguard-debug[0m is [47mnil[0m by
  default; when non-[47mnil[0m, the guard theorem is modified as with the
  option [47m:guard-debug[0m for [47m[verify-guards][0m; see [guard-debug].

  See [lemma-instance] for how to provide the result of [47m:gthm[0m as a
  [47m:guard-theorem[0m prover hint.  Also see [guard-formula-utilities] for
  related utilities.

  Normally one will evaluate [47m:gthm FN[0m or equivalently (see
  [keyword-commands]), the form [47m(gthm 'FN)[0m.  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 [built-in-clause] rules that
  come with ACL2.  The [47msimplify[0m argument should be [47mnil[0m to avoid such
  simplification; that is, use [47m(gthm 'FN nil)[0m.  See also
  [guard-simplification] for discussion of simplification done for
  various guard formula utilities.

  Note that the result from evaluating [47m(gthm x simplify guard-debug)[0m is
  an [3muntranslated[0m term, that is, a user-level term; see [term].  The
  corresponding call [47m(guard-theorem x simplify guard-debug (w state)
  state)[0m returns a translated term.")
 (GUARANTEES-OF-THE-TOP-LEVEL-LOOP
  (SOUNDNESS LD)
  "Guarantees provided by top-level evaluation

  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 [47m[ld][0m.  [47mLd[0m is
  the ACL2 implementation of the loop (as a macro that calls a
  [47m[state][0m-using function with many parameters which may be set by the
  user).  [47mLd[0m is called initially when ACL2 is fired up.

  But here we are concerned with what it means, logically, when a term
  [3mtm[0m evaluates without error to a value [3mv[0m in the loop.

  We do not formalize macroexpansion here, but rather, we deal with
  so-called ``translated'' [term]s, where macros and constants have
  been expanded away.  We also do not discuss here how ACL2 evaluates
  expressions; see [evaluation] for such discussion.  (Those
  interested in implementation issues may also read the long comment
  in ACL2 source file [47minterface-raw.lisp[0m that is labeled ``Essay on
  Evaluation in ACL2''.)

  See [soundness] for a more general discussion of soundness-related
  issues (including, for example, interrupts and trust tags).


A Strawman Proposal on the Meaning of Top-Level Evaluation

  One might like to think that for any term, [3mtm[0m, a non-erroneous
  interaction like

    ACL2 !>[3mtm[0m
    [3mv[0m

  means that the formula

    (equal [3mtm[0m '[3mv[0m)

  is a theorem and can be proved by the prover.

  For example, let [47msq[0m be a :logic mode function that squares its
  argument.  (For the sake of a later example, let us also make the
  [guard] of [47msq[0m be [47mt[0m and verify the guard by fixing (with [47m[rfix][0m) the
  argument to be a rational, but those aspects of [47msq[0m are irrelevant
  in our immediate use of it below.)

    (defun sq (x)
      (declare (xargs :guard t :verify-guards t))
      (let ((x (rfix x)))
        (* x x)))

  then the evaluation

    ACL2 !>(sq 3)
    9

  suggests that [47m(equal (sq 3) 9)[0m is a theorem and that is indeed
  provable by the ACL2 theorem prover.

  But the situation is quite subtle and deserves further discussion.
  That is what this topic is about.

  [31;1mSpoiler Alert[0m: 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 [3mevaluation theory[0m which is an extension of
  ACL2's [3mproof theory[0m.  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
  [3mprover's theory[0m.


Problems Raised by [47m:Program[0m Mode Functions

  Suppose [47mprog-sq[0m is defined as a [47m:[0m[47m[program][0m mode function that squares
  its argument.  Then the top-level evaluation

    ACL2 !>(prog-sq 3)
    9

  clearly should not suggest

    (equal (prog-sq 3) 9)

  is a theorem.  [47m:Program[0m mode functions are not defined in the
  prover's theory.  ([47m:Program[0m 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 [47m:program[0m 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 [47m:program[0m mode expressions is supported
  in the loop primarily as a way to execute commands like [47m[defun][0m and
  [47m[defthm][0m.  But it is also a convenience that allows ACL2 to be used
  as a [programming] language (e.g., to prototype a system one might
  eventually admit to the logic and prove theorems about).

  Therefore, when attempting to define the logical meaning of top-level
  evaluations we might restrict our attention to [47m:[0m[47m[logic][0m mode terms
  only.  But this is not sufficient for several reasons.

  [47m:Program[0m mode functions raise another problem discussed below in
  connection with [47mapply$[0m.


Problems Raised by Single-Threaded Objects

  Evaluation of terms involving single-threaded objects or ``[stobj]s''
  raise problems, even if the terms involved are in [47m:logic[0m mode.
  Here is a top-level evaluation sequence

    ACL2 !>(defstobj st fld)
    ...
    ST
    ACL2 !>(update-fld 3 st)
    <st>
    ACL2 !>(update-fld (sq (fld st)) st)
    <st>
    ACL2 !>(fld st)
    9

  but the strawman conjecture from the last evaluation, [47m(equal (fld st)
  9)[0m, is not a theorem.  However, a related formula is a theorem and
  can be proved by the prover.

    (implies (stp st)
             (let* ((st (update-fld 3 st))
                    (st (update-fld (sq (fld st)) st)))
               (equal (fld st) 3)))

  This reminds us that the top-level loop tracks changes to each
  ``live'' stobj and records them in the ACL2 [47m[state][0m.  Those changes
  must be reflected in any suggested theorems.


Problems Raised by Apply$

  [47m[Apply$][0m calls [47m[apply$-userfn][0m to handle the application of
  user-defined function symbols.  [47mApply$-userfn[0m is undefined but
  might be constrained by [47m[warrant][0m hypotheses (see [47m[defwarrant][0m).
  Recall that warrants link the functions approved by [47mdefwarrant[0m to
  their names and constrain [47m(apply$ 'fn (list a1 ... an))[0m to be [47m(fn
  a1 ... an)[0m under certain [47m[tame][0mness conditions.  As noted at the
  bottom of the discussion of [47m[defwarrant][0m, there is a model of the
  prover's theory in which all warrants issued by [47mdefwarrant[0m 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 [31;1mLesson 12[0m of [introduction-to-apply$]).

  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

    [31;1mUnsound Axiom Schema[0m:
    (equal (apply$ '[3mf[0m (list a1 ... an)) ([3mf[0m a1 ... an))

  for every defined function [3mf[0m.  See the [47mrussell[0m example in
  [introduction-to-apply$].  So warrants and the restrictions
  enforced by [47m[defwarrant][0m keep the prover's theory consistent.  One
  might then ask ``how do we get away with letting the top-level loop
  [47mapply$[0m all badged [47m:program[0m mode functions?'' The answer is simple:
  [47m:program[0m mode functions are not axiomatized so we don't have a
  theory to worry about!

  To illustrate the difference between the behavior of the top-level
  loop and the prover, suppose the function [47msq[0m, defined above, has
  been warranted.

    (defwarrant sq)

  and then consider the top-level evaluation

    ACL2 !>(apply$ 'sq '(3))
    9

  This is possible because the warrant for [47msq[0m is assumed true in the
  top-level loop and that warrant tells the loop that [47m(apply$ 'sq
  '(3))[0m = [47m(sq 3)[0m.

  However, [47m(equal (apply$ 'sq '(3)) '9)[0m is not a theorem in the
  prover's theory.  Instead, this is a theorem

    (implies (warrant sq)
             (equal (apply$ 'sq '(3)) '9))

  where [47m(warrant sq)[0m is just a convenient abbreviation for [47m(force
  (apply$-warrant-sq))[0m.

  Thus, to extend the strawman conjecture to functions in which [47mapply$[0m
  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.

  But [47mapply$[0m introduces another source of complexity: mixed-mode
  functions (see [mixed-mode-functions]).  Recall the [47m:program[0m mode
  function [47mprog-sq[0m which squares its argument.  We can assign a badge
  to [47mprog-sq[0m and then define a [47m:logic[0m mode function that [47mapply$[0ms it!

    (defbadge prog-sq)

    (defun logic-sq (x)
      (declare (xargs :mode :logic))
      (apply$ 'prog-sq (list x)))

  Since the top-level loop can evaluate applications of [47m:program[0m mode
  symbols we see the following evaluation.

    ACL2 !>(logic-sq 3)
    9

  Note that [47m(logic-sq 3)[0m is a [47m:logic[0m mode term and [47mlogic-sq[0m can even be
  warranted with [47mdefwarrant[0m.  But neither

    (equal (logic-sq 3) '9)

  nor

    (implies (warrant logic-sq) (equal (logic-sq 3) '9))

  is a theorem in the prover's theory because [47mprog-sq[0m is undefined in
  that theory.  For what it is worth, the prover can prove

    (implies (warrant logic-sq) (equal (logic-sq 3) (apply$ 'prog-sq '(3))))

  This example contradicts the suggestion, just above, that if we
  properly considered warrants we could give logical meaning to
  evaluations of [47m:logic[0m mode terms involving [47mapply$[0m.


Problems Raised by Constrained Functions

  Constrained functions raise problems if they have been given
  attachments (see [47m[defattach][0m).  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.

  For example, let [47m(nonneg-rat x)[0m be constrained to return some
  nonnegative rational.

    (encapsulate (((nonneg-rat *) => *))
      (local (defun nonneg-rat (x)
               (declare (ignore x))
               0))
      (defthm nonneg-rat-constraint
        (and (rationalp (nonneg-rat x))
             (<= 0 (nonneg-rat x)))))

  It is impossible to evaluate [47m(nonneg-rat 3)[0m 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 [47msq[0m, as
  defined above to [47mrfix[0m its argument as a rational, satisfies that
  constraint, we can attach [47msq[0m to [47mnonneg-rat[0m.

    (defattach nonneg-rat sq)

  and then we can ``evaluate'' calls of [47mnonneg-rat[0m in the loop, getting
  results that are consistent with its constraint (but overly
  specific!).

    ACL2 !>(nonneg-rat 3)
    9

  But of course the strawman conjecture [47m(equal (nonneg-rat 3) '9)[0m is
  not a theorem of the prover's theory.


The Prover's Theory

  The ACL2 logic formalizes an applicative (functional and side-effect
  free) extension of a subset of Common Lisp (see [common-lisp]).  It
  is described in chapter 6 of {Computer-Aided Reasoning: An Approach
  |
  http://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html},
  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 [term]s though the user is allowed to
  use a more flexible syntax which can be extended by defining
  constant symbols and macros (see [47m[defconst][0m and [47m[defmacro][0m).  To
  see the formal translation of such a term use the command [47m:[0m[47m[trans][0m.
  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 [ordinals].  In Section 6.4, a conservative
  Principle of Definition (see [47m[defun][0m and [47m[defuns][0m or
  [47m[mutual-recursion][0m) 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 [induction] and [47m[hints][0m for ways to influence this
  selection.  Finally, in section 6.6, the book introduces
  [47m[encapsulate][0m 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.

  The ACL2 prover proves theorems in the extension of the above theory
  obtained by adding the axioms introduced by [events] successfully
  carried out in the user's session.  The most common such
  axiom-adding events are [47m[defun][0m, [47m[defchoose][0m, and [47m[encapsulate][0m,
  which all conservatively extend the theory by the addition of
  axioms about new function symbols.  But [47mdefun[0m is just a special
  case of [47mdefuns[0m which adds a mutually recursive clique of new names
  (see also [47m[mutual-recursion][0m).  [47m[Defstobj][0m and [47m[defabsstobj][0m add
  recognizers, constructors, and accessors for single-threaded
  objects (aka ``[stobj]s'') but logically just use [47mdefun[0m 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, [47m[defaxiom][0m, but [3mstrongly discourage its use[0m.  There are many
  other events that add axioms, e.g., [47m[defun-nx][0m and [47m[defun-sk][0m 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, [47m[include-book][0m.

  Note that an event of the form [47m(skip-proofs EV)[0m does not introduce
  any axioms other that those added by the event, [47mEV[0m.  However, this
  [47m[skip-proofs][0m event does assume that all proof obligations
  introduced by [47mEV[0m are indeed provable in the prover's theory.

  Given a user's session, we call the above described theory the
  [3mprover's theory[0m.

  Now recall the strawman proposal for what evaluation in the top-level
  loop means, i.e., that the evaluation

    ACL2 !>[3mtm[0m
    [3mv[0m

  might mean that the formula

    (equal [3mtm[0m '[3mv[0m)

  is a theorem.  We have illustrated with [47m:program[0m mode functions, uses
  of [47mapply$[0m, and of constrained functions that this strawman
  conjecture is [3mnot[0m necessarily a theorem of the prover's theory!

  However, there is a theory in which many of these conjectures are
  theorems.


The Evaluation Theory

  The [3mevaluation theory[0m is obtained from the prover's theory as
  follows.

    * 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

          ACL2 !>(defstobj st fld)                           ; [1]
          ST
          ACL2 !>(update-fld 3 st)                           ; [2]
          <st>
          ACL2 !>(update-fld (* (fld st) (fld st)) st)       ; [3]
          <st>

      [47mst[0m is an abbreviation for [47m(NIL)[0m after evaluation [1], an
      abbreviation for [47m(3)[0m after evaluation [2], and an abbreviation
      for [47m(9)[0m after evaluation [3].

    * Every warrant created by [47mdefwarrant[0m is assumed true as an axiom.

    * For every [47m(defattach f g)[0m event in the prover's theory the axiom
      (i.e., constraints) on [47mf[0m is replaced by the axiom [47m(equal (f
      ...) (g ...))[0m in the evaluation theory.  (Of course this
      replacement also takes place when using the more general form
      for [47m[defattach][0m, [47m(defattach ... (f g ...) ...)[0m.)

  Given the restrictions enforced by [47mdefun[0m, [47mdefstobj[0m, [47mdefwarrant[0m,
  [47mapply$[0m, [47mencapsulate[0m, and [47mdefattach[0m, the evaluation theory is
  consistent if the prover's theory is consistent and free of
  [47mdefaxiom[0m events.  (Those interested in reading a proof of this
  claim are welcome to read the ``Essay on Defattach'' in ACL2 source
  file [47mother-events.lisp[0m.)

  Furthermore, the top-level evaluation

    ACL2 !>[3mtm[0m
    [3mv[0m

  means that

    (equal [3mtm[0m '[3mv[0m)

  is a theorem in the evaluation theory provided

    * [3mtm[0m is a [47m:logic[0m mode term, and

    * every symbol that reaches the first argument of any [47mapply$-userfn[0m in
      the execution of [3mtm[0m is in [47m:logic[0m mode.

  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 --- in particular, by adding suitable warrant hypotheses
  --- though the ACL2 system does not provide tools for doing so.


Some Examples of Top-Level Evaluations

  In this section we illustrate some consequences of the guarantee that
  for any term, [3mtm[0m, satisfying certain restrictions, if [3mtm[0m evaluates
  to a value [3mv[0m, then the term

    (equal [3mtm[0m '[3mv[0m)

  is a theorem of the evaluation theory.

  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 [31;1mTop-Level Evaluation of Apply$[0m in the
  documentation for [47m[apply$][0m, which describes how [47mapply$[0m is
  implemented in the top-level loop.

    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.

  In events [1] and [2] [47mmy-cons[0m is introduced as a badged [47m:program[0m mode
  function.  Command [3] shows that we can [47mapply$[0m [47m'my-cons[0m 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 [47mmy-cons[0m and there is no warrant connecting the symbol
  [47m'my-cons[0m to the function [47mmy-cons[0m.  The failure of the first [47mthm[0m
  command, [4], shows that the prover's theory knows nothing of the
  behavior of [47mapply$[0m on [47m'my-cons[0m.  After converting [47mmy-cons[0m to [47m:logic[0m
  mode with [47m[verify-termination][0m in [5] we can no longer evaluate the
  application of [47mmy-cons[0m at the top-level, as shown by [6]!  This is
  surprising because one might expect ACL2 to be able to do more with
  a [47m:logic[0m mode function than its [47m:program[0m mode counterpart.  But in
  the evolving evaluation theory as of [6], [47mmy-cons[0m is a [47m:logic[0m mode
  function with no warrant and so logically speaking [47m(apply$ 'my-cons
  ...)[0m is undefined.  Computing a value for it at [6] would violate
  the guarantee that values of [47m:logic[0m mode terms can be proved
  correct in the evaluation theory --- i.e., that the computed value
  can be derived logically.  Such a derivation is impossible without
  a warrant.  However, after [47mdefwarrant[0m, in [7], confirms that it is
  sound to issue a warrant (linking the symbol [47m'my-cons[0m to the
  function [47mmy-cons[0m via [47mapply$[0m), the evaluation of the [47m'my-cons[0m term
  in [8] succeeds.  The [47mdefwarrant[0m soundly extends the proof theory
  by adding a definition for the warrant function for [47mmy-cons[0m and
  extends the evaluation theory by assuming the warrant for [47mmy-cons[0m
  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 [47mapply$[0m 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 [31;1mLesson 12[0m of
  [introduction-to-apply$] and discussed more thoroughly in
  {``Limited Second-Order Functionality in a First-Order Setting'' |
  http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by
  Matt Kaufmann and J Strother Moore.")
 (GUARD
  (PROGRAMMING XARGS)
  "Restricting the domain of a function

  NOTE: Novices are often best served by avoiding guards.

  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 ---
  informally, that it terminates).  (See [mbt] for a discussion of
  one way to use the guard explicitly to assist with that proof while
  avoiding execution overhead.)

  Guards can be useful as a specification device or for increasing
  execution efficiency.  To make such a restriction, use the [47m:guard[0m
  keyword (see [xargs]) or, especially if you want the host Lisp
  compiler to use this information, use [47mtype[0m declarations (see
  [declare]; also see [xargs] for a discussion of the [47m:split-types[0m
  keyword).  The general issue of guards and guard verification is
  discussed in the topics listed below.

  To begin further discussion of guards, see [guard-introduction].
  That section directs the reader to further sections for more
  details.  To see just a summary of some [command]s related to
  guards, see [guard-quick-reference].  For a discussion of the use
  of proof to verify the absence of guard violations, see
  [verify-guards].


Subtopics

  [Ec-call]
      Execute a call in the ACL2 logic instead of raw Lisp

  [Extra-info]
      Sources of measure or guard proof obligations

  [Guard-checking-inhibited]
      Avoiding certain warnings when evaluating ACL2 expressions

  [Guard-debug]
      Generate markers to indicate sources of [guard] proof obligations

  [Guard-evaluation-examples-log]
      Log showing combinations of [defun-mode]s and [guard]-checking

  [Guard-evaluation-examples-script]
      A script to show combinations of [defun-mode]s and [guard]-checking

  [Guard-evaluation-table]
      A table that shows combinations of [defun-mode]s and
      [guard]-checking

  [Guard-example]
      A brief transcript illustrating [guard]s in ACL2

  [Guard-formula-utilities]
      Utilities that show guard proof obligations

  [Guard-holders]
      Remove trivial calls from a [term]

  [Guard-introduction]
      Introduction to [guard]s in ACL2

  [Guard-miscellany]
      Miscellaneous remarks about guards

  [Guard-quick-reference]
      Brief summary of guard checking and guard verification

  [Guard-theorem-example]
      How to use a previously-proved [guard] theorem

  [Guards-and-evaluation]
      The relationship between guards and evaluation

  [Guards-for-specification]
      Guards as a specification device

  [Invariant-risk]
      Potential slowdown for [program]-mode updates to [stobj]s or
      [arrays]

  [Mbe]
      Attach code for execution

  [Non-exec]
      Mark code as non-executable

  [Print-gv]
      Print a form whose evaluation caused a guard violation

  [Program-only]
      Functions that cannot be in [logic] mode

  [Safe-mode]
      A mode that avoids [guard] violations on [primitive]s

  [Set-check-invariant-risk]
      Affect certain [program]-mode updates to [stobj]s or [arrays]

  [Set-guard-checking]
      Control checking [guard]s during execution of top-level forms

  [Set-guard-msg]
      Specify what is printed when a [guard] is violated

  [Set-print-gv-defaults]
      Set default keyword values for [47m[print-gv][0m

  [Set-register-invariant-risk]
      Avoid [invariant-risk] checking for specified functions

  [Set-verify-guards-eagerness]
      The eagerness with which [guard] verification is tried.

  [The]
      Special form for execution efficiency or run-time type checks

  [Verify-guards]
      Verify the [guard]s of a function

  [With-guard-checking]
      Suppress or enable guard-checking for a form

  [With-guard-checking-error-triple]
      Suppress or enable guard-checking for a form

  [With-guard-checking-event]
      Suppress or enable guard-checking for an event form")
 (GUARD-CHECKING (POINTERS)
                 "See [set-guard-checking].")
 (GUARD-CHECKING-INHIBITED
  (EVALUATION GUARD)
  "Avoiding certain warnings when evaluating ACL2 expressions

  ACL2 sometimes omits the checking of [guard]s on recursive calls of
  functions.  This omission is signaled by a warning like the one
  shown below.

    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 !>

  This behavior can occur for a recursively-defined [logic]-mode
  function with a guard other than [47mt[0m whose guards have not been
  verified, when [guard-checking] has its default value, [47mt[0m.
  (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.

  To check guards on all recursive calls:

    (set-guard-checking :all)

  To leave the current behavior unchanged except for inhibiting such
  messages:

    (set-guard-checking :nowarn)")
 (GUARD-DEBUG
  (GUARD DEBUGGING)
  "Generate markers to indicate sources of [guard] proof obligations

  ACL2 guard verification (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 [documentation] topic explains a capability
  provided by ACL2 to help find such bugs.

  For a similar utility appropriate for proving [measure] conjectures
  (that is, for termination proofs), see [measure-debug].

  We begin with the following example.  Although it is contrived and a
  bit simplistic, it illustrates how the guard-debug utility works.

    (defun length-repeat (x)
      (length (append x x)))
    (verify-guards length-repeat :guard-debug t)

  The output produces two top-level key checkpoints, as follows.

    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)))

  The upper subgoal (numbered 2) says that the body of the definition
  of [47mlength-repeat[0m contains a call [47m(APPEND X X)[0m, which is the source
  of the goal.  In this case, that makes sense: the [guard] for a
  call [47m(append arg1 arg2)[0m is [47m(true-listp arg1)[0m, which in this case is
  [47m(TRUE-LISTP X)[0m.  The lower subgoal (numbered 1) says that the same
  definition contains the call [47m(LENGTH (APPEND X X))[0m, which generates
  the proof obligation that if [47m(APPEND X X)[0m does not satisfy
  [47mtrue-listp[0m, then it must satisfy [47mstringp[0m.  That proof obligation
  comes directly from the [guard] for [47m[length][0m.

  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 [47m[verify-guards][0m
  events but also in [47m[xargs][0m [47m[declare][0m forms of [47m[defun][0m events.

  We now describe the guard-debug utility in some detail.

  [47m(Extra-info x y)[0m always returns [47mt[0m by definition.  However, if [guard]
  verification takes place with a non-[47mnil[0m setting of [47mguard-debug[0m (see
  below), then the goals generated for guard verification can include
  hypotheses that are calls of [47mextra-info[0m.  Typically, such a
  hypothesis is of the following form:

    (extra-info '(:guard (:body F))
                '(G ARG1 ... ARGk))

  The above form indicates that the goal in which it occurs was
  generated to verify that the [guard] of the function [47mF[0m is satisfied
  by the arguments [47mARG1[0m through [47mARGk[0m, where the term [47m(G ARG1 ...
  ARGk)[0m occurs in the body of the function [47mF[0m whose guard verification
  is in progress.  If however the above call of [47mG[0m occurs in the guard
  of [47mF[0m instead of the body of [47mF[0m, then [47m:body[0m is replaced by [47m:guard[0m
  above:

    (extra-info '(:guard (:guard F))
                '(G ARG1 ... ARGk))

  If the same proof obligation (goal [clause]) arises from more than
  one occurrence of the same call, then a single goal will be
  generated, which has several [47mextra-info[0m hypotheses added to show
  the multiple sources of that proof obligation.

  All rules (see [rune]) associated with [47mextra-info[0m are [disable]d by
  default, so that hypotheses of the form described above are not
  simplified to [47mt[0m.  These hypotheses are intended to ride along for
  free: you can generally expect the proof to have the same structure
  whether or not the [47m:guard-debug[0m option is supplied, though on rare
  occasions the proofs may diverge.

  It remains to explain the notion of a [47mguard-debug[0m setting of [47mt[0m, that
  is, to explain how to obtain the additional hypotheses described
  above.  If guards are being verified during processing of a [47m[defun][0m
  event (whether or not inside a call of [47m[mutual-recursion][0m), then
  one specifies [47m:guard-debug t[0m in an [47m[xargs][0m declaration of a
  [47m[declare][0m form; see [xargs].  If however the guard verification is
  on behalf of a [47m[verify-guards][0m call, whether for a definition or a
  theorem, then one specifies the keyword argument [47m:guard-debug t[0m.

  Also 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.")
 (GUARD-EVALUATION-EXAMPLES-LOG
  (GUARD)
  "Log showing combinations of [defun-mode]s and [guard]-checking

  See [guard-evaluation-examples-script] for a script that shows the
  interaction of [defun-mode]s with the value set by
  [47m[set-guard-checking][0m.  Here, we present a log resulting from
  running this script.  It may also be helpful to see [evaluation].

  See [set-guard-checking] for discussion of the interaction between
  [defun-mode]s and [guard]-checking that is illustrated by this
  script.  Also see [guard-evaluation-table] for a succinct table,
  with associated discussion, that covers in detail the interactions
  illustrated here.

    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 >")
 (GUARD-EVALUATION-EXAMPLES-SCRIPT
  (GUARD)
  "A script to show combinations of [defun-mode]s and [guard]-checking

  Below is a script that illustrates the combination of [defun-mode]s
  --- [47m:[0m[47m[program][0m mode, [47m:[0m[47m[logic][0m mode without [guard]s verified, and
  [47m:[0m[47m[logic][0m mode with [guard]s verified --- with values from
  [47m[set-guard-checking][0m --- [47mt[0m (the default), [47m:all[0m, [47m:none[0m, and [47mnil[0m.
  (It does not illustrate the value [47m:nowarn[0m, which is the same as [47mt[0m
  except for inhibiting a warning.)  The script also illustrates
  cases where the guard is not, or is, [47mt[0m.

  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.

  See [set-guard-checking] for discussion of the interaction between
  [defun-mode]s and [guard]-checking that is illustrated by this
  script.  Also see [guard-evaluation-table] for a succinct table,
  with associated discussion, that covers in detail the interactions
  illustrated here.

  The script mentions the running of ``Tracing Code''.  The code is the
  following sequence of commands.

    (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)

  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 [47mdefine-key[0m command is
  optional, in case you want to put that keyboard macro on a key ---
  though in that case you'll need to have defined [47mctl-t-keymap[0m, which
  happens automatically if you load file [47memacs-acl2.el[0m; see :DOC
  emacs.

    (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)

  The script follows.

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;;; 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.")
 (GUARD-EVALUATION-TABLE
  (GUARD)
  "A table that shows combinations of [defun-mode]s and [guard]-checking

  See [set-guard-checking] for an introduction to the topic discussed
  here.  Also see [guard] for a general discussion of guards, and see
  [guard-evaluation-examples-script] for a script that illustrates
  combinations presented below.

  Note: The default setting for guard-checking (that is, the initial
  value for [state] global [47m(@ guard-checking-on)[0m) is [47mT[0m.

  The table below illustrates the interaction of the [defun-mode] with
  the value supplied to [47m[set-guard-checking][0m.  The first row
  considers functions defined in [47m:[0m[47m[program][0m mode; the other two
  consider functions defined in [47m:[0m[47m[logic][0m mode.  The columns
  correspond to four values of state global [47m'guard-checking-on[0m, as
  supplied to [47m[set-guard-checking][0m.  (A fifth value, [47m:nowarn[0m, is
  similar to [47mt[0m but suppresses warnings; a remark with details for
  system hackers is at the end of this topic.)  Note that
  [47m'guard-checking-on[0m is set to [47mnil[0m during proofs but is set to [47mt[0m
  during [47m[certify-book][0m, and [47m[include-book][0m, regardless of how this
  variable has been set in the top-level loop (see the ``Essay on
  Guard Checking'' in source file [47mother-events.lisp[0m if you are
  interested in a rationale).

  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 [47m:[0m[47m[logic][0m mode function whose
  guards have not been verified, after having executed
  [47m:[0m[47m[set-guard-checking][0m[47m :all[0m.

      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

  a1. Check the [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 [47m(defun foo (x) (car x))[0m in [47m:[0m[47m[program][0m
  mode and execute [47m:[0m[47m[set-guard-checking][0m[47m t[0m, and then execute [47m(foo 3)[0m,
  you will likely get an error from the call [47m(car 3)[0m made in raw
  Lisp.

  a2. For built-in (predefined) functions, see a1 instead.  Otherwise:
  Check the [guard], without exception.  Thus, we never run the raw
  Lisp code in this case.  This can be useful when testing [47m:[0m[47m[program][0m
  mode functions, but you may want to run [47m:[0m[47m[comp][0m[47m t[0m or at least
  [47m:[0m[47m[comp][0m[47m :exec[0m in this case, so that the execution is done using
  compiled code.

  a3. For built-in (predefined) functions, see a4 instead.  Otherwise:
  Do not check the [guard].  For [47m:[0m[47m[program][0m 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 [47m:[0m[47m[comp][0m.  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 [guard] violations.  In this case, you can forget about any
  connection between ACL2 and Common Lisp.

  a4. Run the raw Lisp code without checking [guard]s at all.  Thus,
  for [47m:[0m[47m[program][0m mode functions, the [47mnil[0m setting is often preferable
  to the [47m:none[0m setting because you get the efficiency of raw Lisp
  execution.  However, with [47mnil[0m you can therefore get hard Lisp
  errors as in a1 above.

  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.

  b2. Unlike the [47mt[0m setting, guards are checked even on self-recursive
  calls.  But like the [47mt[0m 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.

  b3, b4. Execution avoids the raw Lisp code and never checks guards.
  The [47mnil[0m and [47m:none[0m settings behave the same in this case (i.e., for
  [47m:[0m[47m[logic][0m mode functions whose guards have not been verified),
  except that recursive calls are never inlined for [47m:none[0m and tracing
  (see [trace]) will show recursive calls for [47m:none[0m but not for [47mnil[0m.

  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 [47mt[0m and [47m:all[0m behave the
  same in this case, (i.e. for [47m:[0m[47m[logic][0m mode functions whose [guard]s
  have been verified).

  c3, c4. For the [47m:none[0m and [47mnil[0m settings, [47m:[0m[47m[logic][0m mode functions whose
  guards have been verified will never cause guard violations.
  However, with [47mnil[0m and for built-in functions in [47m:logic[0m 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 [47mt[0m case, we
  will not see a warning about this).  But with [47m:none[0m 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 [47mt[0m 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 [47m:[0m[47m[comp][0m).  Thus, if you
  use [47m:none[0m and you want a function [47m(foo x)[0m with guard [47m(g x)[0m to
  execute using raw Lisp code, you can write a ``wrapper''function
  with a guard of [47mt[0m:

    (defun foo-wrap (x)
      (declare (xargs :guard t))
      (if (g x)
          (foo x)
        'do-not-case))

  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 [47mnil[0m rather than [47m:none[0m.

  Remark for system hackers.  As noted above, a fifth value, [47m:nowarn[0m,
  is similar to [47mt[0m but suppresses warnings.  Only the four values in
  the column headers above and [47m:nowarn[0m are legal for
  [47m[set-guard-checking][0m, [47m[with-guard-checking][0m,
  [47m[with-guard-checking-error-triple][0m, and
  [47m[with-guard-checking-event][0m.  Behavior is technically undefined if
  you set [state] global [47mguard-checking-on[0m directly to other than
  those five values, say using [47m[assign][0m, [47m[f-put-global][0m, or
  [47m[state-global-let*][0m.  However, as of this writing (in August 2021),
  such a value will cause the same behavior as value [47m:nowarn[0m.  End of
  Remark.")
 (GUARD-EXAMPLE
  (TUTORIAL5-MISCELLANEOUS-EXAMPLES GUARD)
  "A brief transcript illustrating [guard]s in ACL2

  This note addresses the question: what is the use of [guard]s in
  ACL2?  Although we recommend that beginners try to avoid [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 [guard].  For a
  summary of that topic, see [guard-quick-reference].

  Before we get into the issue of [guard]s, let us note that there are
  two important ``modes'':

      [defun-mode] --- ``Does this [defun] add an axiom (`logic mode') or
      not (`:program mode')?'' (See [defun-mode].)  Only [logic] mode
      functions can have their ``[guard]s verified'' via mechanized
      proof; see [verify-guards].

      [47m[set-guard-checking][0m --- ``Should runtime [guard] violations signal
      an error ([47m:all[0m, and usually with [47mt[0m or [47m:nowarn[0m) or go undetected
      ([47mnil[0m, [47m:none[0m)?  The question relates to the use of Common Lisp
      to evaluate expressions; see [set-guard-checking].


Examples of prompts

  Here are some examples of the relation between the ACL2 [prompt] and
  the ``modes'' discussed above.  Also see [default-print-prompt].
  The first examples all have [47m[ld-skip-proofsp][0m equal to [47mnil[0m; that
  is, proofs are [3mnot[0m skipped.

    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

  Here are some examples with [47m[default-defun-mode][0m equal to [47m:logic[0m.

    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


Sample session

    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


Guard verification for functions

  See [declare], and [xargs], and [verify-guards] for related
  background, though we intend what follows to be self-explanatory.

          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 >

  We continue this demo by tracing [47msum-list[0m.  (See [trace$].)  The
  calls shown below of [47mACL2_*1*_ACL2::SUM-LIST[0m are calls of the
  logical version, or [3mexecutable-counterpart[0m, of [47msum-list[0m; also see
  [evaluation].  Note that the guard-checking value is still [47mnil[0m.  So
  the logical version of [47msum-list[0m calls the Common Lisp [47msum-list[0m
  function when the [guard] of ``list of integers'' is true of its
  input, i.e., its input satisfies [47m[integer-listp][0m; but otherwise,
  evaluation continues using its executable-counterpart.

    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 >


Guard verification for theorems

  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 [47mA[0m and
  [47mB[0m are not both lists of numbers.

    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 >

  Perhaps surprisingly, a [47m[defthm][0m event with statement

    (implies (and (integer-listp a)
                  (integer-listp b))
             (equal (sum-list (append a b))
                    (+ (sum-list a) (sum-list b))))

  is still not guard-verifiable.  The reason is that [47m[implies][0m is a
  function, so its arguments are both always evaluated --- in
  particular, its second argument is evaluated even if its first
  argument evaluates to [47mnil[0m.  Here is a way to fix that problem.

    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 >

  Guard verification fails when the theorem is for ``code'' that cannot
  even be parsed (or ``translated''; see [term]) as executable code.

    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 >")
 (GUARD-FORMULA-UTILITIES
  (GUARD)
  "Utilities that show guard proof obligations

  See [verify-guards] and 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.

  The first pair of utilities captures formulas produced during guard
  verification.

      [47m[Verify-guards-formula][0m: Use this to see what the corresponding
      [47m[verify-guards][0m event prints, but without following through
      with a proof attempt.  This utility is only for output, without
      returning an interesting value.

      [47m[Guard-obligation][0m: This function is a programmatic version of the
      macro, [47m[verify-guards-formula][0m.  It provides the guard
      obligation as a set of [clause]s, along with other information.

  The second pair of utilities captures the formula provided when a
  [47m:guard-theorem[0m is supplied for a [47m:use[0m hint.

      [47m[Gthm][0m: This macro returns a user-level (``untranslated'')
      representation of the [term] that is generated for a
      [47m:guard-theorem[0m [lemma-instance].  Options control whether or
      not simplification and [guard-debug] are used.

      [47m[Guard-theorem][0m: This utility is like [gthm], except that it is a
      function rather than a macro and it returns a translated term
      (a [47m[termp][0m).

  We conclude by contrasting these two pairs of utilities.

    * 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.

    * The level of simplification differs between the two pairs.  See
      [guard-simplification] for a detailed explanation; here are
      highlights.  The first pair simplifies (by default) with
      respect to the [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 [47m:guard-theorem[0m
      specified in a [47m:use[0m hint, or if a suitable option is supplied,
      no simplification at all.

    * The two pairs differ in their output [signature]s: in particular, the
      utilities in the first pair return multiple values while those
      in the second pair return a single value.


Subtopics

  [Gthm]
      The [guard] theorem for a given function symbol

  [Guard-obligation]
      The guard proof obligation

  [Guard-simplification]
      Levels of simplification for [guard] proof obligations

  [Guard-theorem]
      Use a previously-proved [guard] theorem

  [Guard-theorem-example]
      How to use a previously-proved [guard] theorem

  [Verify-guard-implication]
      [Guard] implication for [47m[memoize][0m keyword [47m:invoke[0m

  [Verify-guards-formula]
      View the guard proof obligation, without proving it")
 (GUARD-HINTS
      (POINTERS)
      "See [xargs] for information about the keyword [47m:guard-hints[0m.")
 (GUARD-HOLDER (POINTERS)
               "See [guard-holders].")
 (GUARD-HOLDERS
  (RULE-CLASSES TERM GUARD)
  "Remove trivial calls from a [term]

  For many [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
  [hints] processing, generating proof obligations for [guard]s and
  termination, and the storing of induction schemes and
  [constraint]s.

  In all such cases, the resulting term is provably equivalent to the
  input term.  A common example is to replace the term [47m(prog2$ term1
  term2)[0m by the term [47mterm2[0m.  But [47m(prog2$ term1 term2)[0m is really an
  abbreviation for (i.e., macroexpands to) the term [47m(return-last
  'progn term1 term2)[0m; so a more accurate explanation, at the level
  of proper ACL2 [term]s, is that the call of function [47m[return-last][0m
  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.)

  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 [lambda] expressions (see [term]),
  usually including quoted lambda expressions that appear in an
  argument position with [ilk] [47m:FN[0m (see [apply$]).

    (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

  Because of how [47m[mbe][0m and [47m[ec-call][0m are defined in terms of
  [47m[return-last][0m, the expressions [47m(mbe :logic l :exec e)[0m and [47m(ec-call
  (f t1 ... tk))[0m are effectively transformed by removing guard
  holders into [47ml[0m and [47m(f t1 ... tk)[0m, respectively.

  The final two classes of simplification above (removal of ``trivial''
  lambda applications) may be removed by executing the following
  form, which is [47m[local][0m to an [47m[encapsulate][0m form and to [books].

    (defattach-system remove-guard-holders-lamp constant-nil-function-arity-0)

  Here is how to restore the default behavior.

    (defattach-system remove-guard-holders-lamp constant-t-function-arity-0)

  Note that by default, guard-holders are not removed inside calls of
  [47m[hide][0m.  You can however cause them to be removed inside such calls
  after all, as was the case through Version 8.2, as follows.

    (defattach-system ; generates (local (defattach ...))
      remove-guard-holders-blocked-by-hide-p
      constant-nil-function-arity-0)")
 (GUARD-INTRODUCTION
  (GUARD)
  "Introduction to [guard]s in ACL2

  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 [47m:[0m[47m[set-guard-checking][0m [47mnil[0m; for more about
  this, see [set-guard-checking].  For more about guards in general,
  see [guard].

  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
  [47m:[0m[47m[args][0m.  See [args].  To specify the guard on a function at
  [47mdefun-time[0m, use the [47m:[0m[47m[guard][0m [47mxarg[0m (See [xargs]) or [47mtype[0m
  declarations (see [declare]).  The latter may be preferable if you
  want the host Lisp compiler to use this information.

  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 [verify-guards]), then the evaluation of a
  call of that function on arguments satisfying its guard will have
  the following property:

      All subsequent function calls during that evaluation will be on
      arguments satisfying the guard of the called function.

  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 [47m[defun][0m event is used to evaluate the
  call.  Note however that even when the user-supplied [47m[defun][0m is not
  used, ACL2 uses a corresponding executable-counterpart function
  that generally performs, we expect, nearly as well as submitted
  function; see [evaluation] for relevant background on these two
  functions.  See [comp] to see how [compilation] can speed up both
  kinds of execution.

  Let us turn next to the issue of the relationship between guards and
  evaluation.  See [guards-and-evaluation].")
 (GUARD-MISCELLANY
  (GUARD)
  "Miscellaneous remarks about guards

  The discussion of guards concludes here with a few miscellaneous
  remarks.  (Presumably you found this documentation by following a
  link; see [guards-for-specification].)  For further information
  related to guards other than what you find under ``[guard],'' see
  any of the following documentation topics: [guard-example],
  [47m[set-verify-guards-eagerness][0m, [47m[set-guard-checking][0m,
  [47m[verify-guards][0m, and (for a discussion of keyword [47m:split-types[0m)
  [47m[xargs][0m.

  [47m[Defun][0m can be made to try to verify the guards on a function.  This
  is controlled by the ``[defun-mode]'' of the [47m[defun][0m; see
  [defun-mode].  The [defun-mode] is either as specified with the
  [47m:mode[0m [47mxarg[0m of the [47m[defun][0m or else defaults to the default
  [defun-mode].  See [default-defun-mode].  If the [defun-mode] of
  the [47m[defun][0m is [47m:[0m[47m[logic][0m and either a [guard] is specified
  explicitly or [47m:[0m[47m[verify-guards][0m [47mt[0m is specified in the [47m[xargs][0m, then
  we attempt to verify the guards of the function.  Otherwise we do
  not.  (But see [set-verify-guards-eagerness] for how to modify this
  behavior.)

  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
  [47m:verify-guards nil[0m then to state and prove key theorems about the
  function, and only then have the system attempt guard verification.
  Post-[47m[defun][0m guard verification is achieved via the event
  [47m[verify-guards][0m.  See [verify-guards].

  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.

  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.

  Finally, we note that ACL2 collects up [guard]s from [47m[declare][0m forms
  in order of appearance.  So for example, the [47m[declare][0m form

    (declare (xargs :guard (foo x))
             (type string x)

  will generate the guard [47m(and (foo x) (stringp x))[0m, while the form

    (declare (type string x)
             (xargs :guard (foo x))

  will generate the guard [47m(and (stringp x) (foo x))[0m.  The only
  exceptions to this rule are that all [47m:stobjs[0m and [47m:dfs[0m declarations
  will be treated as through they precede all [47m:guard[0m and [47mtype[0m
  declarations.")
 (GUARD-MSG-TABLE (POINTERS)
                  "See [set-guard-msg].")
 (GUARD-OBLIGATION
  (GUARD-FORMULA-UTILITIES)
  "The guard proof obligation

  See [verify-guards], and see [guard] for a discussion of guards.
  [47mGuard-obligation[0m is a low-level function for use in system
  programs, not typically appropriate for most ACL2 users.  A
  corresponding user-level utility is [verify-guards-formula]; also
  see [guard-formula-utilities] for related utilities.

    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)

  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; [47mrrp[0m
  (``return redundant p'') is non-[47mnil[0m when it is permissible to
  return a value of [47m'redundant[0m in the first (name) case (and is
  irrelevant in the term case); [47mguard-debug[0m is typically [47mnil[0m but may
  be [47mt[0m (see [guard-debug]); [47mguard-simplify[0m is typically [47mt[0m but may be
  [47m:limited[0m (see [verify-guards]); [47mctx[0m is a context (typically, a
  symbol used in error and warning messages); and [47m[state][0m references
  the ACL2 [state].

  If you want to obtain the formula but you don't care about the
  so-called ``tag tree'':

    (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 .. ))))

  The form [47m(guard-obligation x rrp guard-debug guard-simplify ctx
  state)[0m evaluates to a pair [47m(mv erp val)[0m, where [47merp[0m is [47mnil[0m 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 [47merp[0m is [47mnil[0m.  Then [47mval[0m is the keyword
  [47m:redundant[0m if the corresponding [47m[verify-guards][0m event would be
  redundant and [47mrrp[0m is not [47mnil[0m; see [redundant-events].  Otherwise,
  [47mval[0m is a tuple [47m(list* names cl-set ttree)[0m, where: [47mnames[0m is [47m(cons
  :term xt)[0m if [47mx[0m is not a variable, where [47mxt[0m is the translated form
  of [47mx[0m; and otherwise is a list containing [47mx[0m along with, if [47mx[0m is
  defined in a [47mmutual-recursion[0m, any other functions defined in the
  same [47m[mutual-recursion][0m nest; [47mcl-set[0m is a list of lists of terms,
  viewed as a conjunction of [clause]s (each viewed (as a
  disjunction); and [47mttree[0m is an assumption-free tag-tree that
  justifies cl-set.  (The notion of ``tag-tree'' may probably be
  ignored except for system developers.)

  [47mGuard-obligation[0m is typically used for function names or non-variable
  terms, but as for [47m[verify-guards][0m, it may also be applied to
  theorem names.

  See the source code for [47m[verify-guards-formula][0m for an example of how
  to use [47mguard-obligation[0m.")
 (GUARD-QUICK-REFERENCE
  (GUARD)
  "Brief summary of guard checking and guard verification

  For a careful introduction to guards, see [guard].

  [31;1mI. GUARD CHECKING DURING EXECUTION[0m

  [3mEffect[0m

  Guards on definitions are checked at execution time (except for
  guards on subsidiary calls of recursive or mutually recursive
  functions).

  [3mWhen does it happen[0m

  By default, guards are checked for all forms submitted at the top
  level.

  [3mTo disable[0m
  [47m:set-guard-checking nil[0m ; skip raw Lisp if there is a guard
  violation [47m:set-guard-checking :none[0m ; skip guard checking entirely

  [3mTo (re-)enable[0m
  [47m:set-guard-checking t[0m

  See [set-guard-checking] for more options.

  [31;1mII. GUARD VERIFICATION[0m

  [3mEffect[0m

  A proof is attempted of the obligations arising from the guards of
  subsidiary functions in a [47m[defun][0m, [47m[defthm][0m, or [47m[defaxiom][0m event.
  In the case of a [47mdefun[0m, the guard itself is also verified (under an
  implicit guard of [47mt[0m).

  [3mWhen does it happen[0m

  Only names of defined functions, [47m[defthm][0ms, and [47m[defaxiom][0ms are
  subject to guard verification.  Guard verification may occur when
  functions are defined (using [47m[defun][0m), but it requires an explicit
  call of [47m[verify-guards][0m in order to verify guards for [47m[defthm][0ms and
  [47m[defaxiom][0ms.  Constrained functions (see [encapsulate]) may not
  have their guards verified.

  [47m(verify-guards foo ...)[0m
  causes guard verification for the [47m[defun][0m, [47m[defthm][0m, or [47m[defaxiom][0m
  named by [47mfoo[0m, if it has not already been successfully done.  The
  default [defun-mode] (see [default-defun-mode]) must be [47m:[0m[47m[logic][0m,
  or else this event is ignored.

  [47m(defun foo ...)[0m
  causes guard verification of [47mfoo[0m if and only if the following two
  conditions are both met.  First, foo is processed in [47m:[0m[47m[logic][0m mode
  (either by setting mode [47m:[0m[47m[logic][0m globally, or by including [47m:mode
  :logic[0m in the [47m[xargs][0m declaration).  Second, at least one of the
  following sub-conditions is met.  Also see [xargs], and see
  [set-verify-guards-eagerness] for how to change this behavior.

      1. The [47m[xargs][0m declaration specifies a [47m:[0m[47m[guard][0m.

      2. There is at least one [47mtype[0m declaration (see [declare]).

      3. The [47m[xargs][0m declaration specifies [47m:[0m[47m[stobj][0m[47ms[0m.

      4. The [47m[xargs][0m declaration specifies [47m:[0m[47m[verify-guards][0m [47mt[0m.

  [47m(verify-termination foo ...)[0m
  causes guard verification of [47mfoo[0m if [47mfoo[0m is a function currently
  defined in [47m:[0m[47m[program][0m mode and the criteria for guard verification
  of a [47m[defun][0m form are met, as discussed above.  The default
  [defun-mode] (see [default-defun-mode]) must be [47m:[0m[47m[logic][0m, or else
  this event is ignored.")
 (GUARD-SIMPLIFICATION
  (GUARD-FORMULA-UTILITIES)
  "Levels of simplification for [guard] proof obligations

  ACL2 provides several features for obtaining the proof obligations
  generated for [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.

  These features can be partitioned into two groups, which we reference
  below as the ``[31;1mAT[0m'' and ``[31;1mAFTER[0m'' groups, as follows.  These
  correspond respectively to the two groups discussed in the
  documentation topic, [guard-formula-utilities], for capturing
  formulas produced either during guard verification or when a
  [47m:guard-theorem[0m is supplied for a [47m:use[0m hint.

    * Simplification [31;1mAT[0m guard-verification time:

        * the [47m[xargs][0m keyword [47m:guard-simplify[0m,

        * the [47m[guard-obligation][0m utility, and

        * the [47m[verify-guards-formula][0m utility.

    * Simplification [31;1mAFTER[0m guard-verification time:

        * the [47m:[0m[47m[gthm][0m utility, and

        * the [47m:[0m[47m[guard-theorem][0m [lemma-instance] (and related low-level utility,
          [47mguard-theorem[0m.

  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 [31;1mNOTE[0m: [47mT[0m and [47m:LIMITED[0m are the only
  legal values for the ``AT'' (first) group, and [47m:LIMITED[0m and [47mNIL[0m are
  the only legal values for the ``AFTER'' (second) group.

    * [47mT[0m:
      Full simplification, which is the default behavior for
      [47m[verify-guards][0m

    * [47m:LIMITED[0m:
      Reduced simplification, skipping simplifications that depend on the
      set of currently [enable]d rules

    * [47mNIL[0m:
      No simplification

  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 [31;1mAT[0m group, [47mT[0m and [47m:LIMITED[0m are the
  legal values.  For features in the [31;1mAFTER[0m group, [47m:LIMITED[0m and [47mNIL[0m
  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.

  First consider the [31;1mAFTER[0m group.  A [47m:[0m[47m[guard-theorem][0m [47m:use[0m hint obtains
  the [guard] theorem proved for a previously guard-verified
  function.  The [47m[current-theory][0m at the time of that [47m:use[0m 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 [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 [47mT[0m is not allowed for the simplification
  argument of a [47m:[0m[47m[guard-theorem][0m hint.  Instead, the default is
  [47m:LIMITED[0m.  The [47m[gthm][0m utility provides a way to show the formula
  that would be provided by a [47m:guard-theorem[0m lemma instance, so [47mgthm[0m
  also disallows [47mT[0m, and its default is also [47m:LIMITED[0m.  Note that the
  utility [47m[verify-guards-formula][0m is more appropriate than [47mgthm[0m to
  view the formula to be proved if one is about to verify guards for
  a function.  (If [47mgthm[0m were to be used for that purpose too, then [47mT[0m
  might be allowed as a simplification argument; but that could lead
  to confusion, in particular about the default.)

  Now consider the [31;1mAT[0m group, which relates to guard verification.  [47mT[0m 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.  [47m:LIMITED[0m 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 [built-in-clause] rules.  If the
  need arises to support [47mNIL[0m as a simplification value, perhaps ACL2
  will change to support that.")
 (GUARD-THEOREM
  (LEMMA-INSTANCE GUARD-FORMULA-UTILITIES HINTS)
  "Use a previously-proved [guard] theorem

  See [lemma-instance] for a discussion of [47m:guard-theorem[0m lemma
  instances, as illustrated in the topic [guard-theorem-example].

  The function [47mguard-theorem[0m is a low-level system utility that returns
  a translated [term].  It is essentially the functional version of
  the [47mgthm[0m macro, which however returns an untranslated term.  See
  [gthm].


Subtopics

  [Guard-theorem-example]
      How to use a previously-proved [guard] theorem")
 (GUARD-THEOREM-EXAMPLE
  (LEMMA-INSTANCE GUARD HINTS
                  GUARD-THEOREM GUARD-FORMULA-UTILITIES)
  "How to use a previously-proved [guard] theorem

  See [lemma-instance] for a discussion of [47m:guard-theorem[0m lemma
  instances, and 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 [guard] theorem already proved for an existing
  definition, when attempting to admit a new definition.

  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 [47m[mbe][0m 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 [47mf1[0m.

    (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))))

  Now suppose that later, we wish to admit a function with the same
  guard and body.  Since the lemma [47mappend-revappend[0m above is [local],
  guard verification will likely fail.  However, we can tell the
  prover to use the guard theorem already proved for [47mf1[0m, as follows;
  then the guard verification proof succeeds.

    (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)))

  See [termination-theorem-example] for an example use of the analogous
  lemma instance type, [47m:termination-theorem[0m.  That topic also
  includes discussion of the use of event names in prover output.")
 (GUARDS (POINTERS) "See [guard].")
 (GUARDS-AND-EVALUATION
  (GUARD)
  "The relationship between guards and evaluation

  For relevant background see [evaluation].

  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.

  For more about guards in general, see [guard].  For in-depth
  discussion of the interaction between the [defun-mode] and guard
  checking, see [set-guard-checking], see [guard-evaluation-table],
  see [guard-evaluation-examples-script], and see
  [guard-evaluation-examples-log].  Also see [generalized-booleans]
  for discussion about a subtle issue in the evaluation of certain
  Common Lisp functions.

  [3mGuards and evaluation I: the default[0m

  Consider the following very simple definition.

    (defun foo (x) (cons 1 (cdr x)))

  First consider how raw Common Lisp behaves when evaluating calls of
  this function.  To evaluate [47m(foo x)[0m for some expression [47mx[0m, first [47mx[0m
  is evaluated to some value [47mv[0m, and then [47m(cons 1 (cdr x))[0m is
  evaluated with [47mx[0m bound to [47mv[0m.  For example, if [47mv[0m is [47m(cons 'a 3)[0m,
  then Common Lisp computes [47m(cons 1 3)[0m.  But if (for example) [47mv[0m is a
  number, e.g., [47m7[0m, 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
  [47mfoo[0m in question is in compiled code.

  Now by default, ACL2 evaluates calls of [47mfoo[0m exactly as Common Lisp
  does, except that it uses guards to check the ``legality'' of each
  function call.  So for example, since [47m(cdr x)[0m has a guard of [47m(or
  (consp x) (equal x nil))[0m, the call [47m(foo 7)[0m would cause a ``guard
  violation,'' as illustrated below.

    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 !>

  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.

  [3mGuards and evaluation II:[0m [47m:[0m[47m[set-guard-checking][0m.

  The ACL2 logic is a logic of total functions.  That is, every
  application of a function defined has a completely specified
  result.  See the [documentation] for each individual primitive for
  the specification of what it returns when its guard is violated;
  for example, see [cdr].

  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 [47m[cdr][0m
  implies that the [47m[cdr][0m of an [atom] is [47mnil[0m; see [cdr].  So: should
  [47m(cdr 7)[0m cause a guard violation error or return [47mnil[0m?

  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 [47m:[0m[47m[set-guard-checking][0m[47m nil[0m; or
  evaluate [47m:[0m[47m[set-guard-checking][0m[47m :none[0m to skip guard checking
  entirely.  To turn ``guard checking'' back on, execute the
  top-level form [47m:[0m[47m[set-guard-checking][0m[47m t[0m.  The status of guard
  checking reflected in the [prompt]; guard-checking is ``on'' when
  the [prompt] contains an exclamation mark (also see
  [default-print-prompt]).  For example,

    ACL2 !>

  means guard checking is on and

    ACL2 >

  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

    ACL2 !>(car 'abc)

  will signal an error, while

    ACL2 >(car 'abc)

  will return [47mnil[0m.  To return to our previous example: with guard
  checking off, [47m(foo 7)[0m evaluates to [47m(cons 1 nil)[0m.  Also see
  [set-guard-checking].

  [3mGuards and evaluation III: guard verification[0m

  Consider the definition of [47mfoo[0m given above, but modified so that a
  reasonable guard of [47m(consp x)[0m is specified, as shown below.

    (defun foo (x)
      (declare (xargs :guard (consp x)))
      (cons 1 (cdr x)))

  We say ``reasonable guard'' above because if [47mx[0m is such that [47m(consp x)[0m
  holds, then the call of [47m[cdr][0m in the evaluation of [47m(foo x)[0m will not
  cause a guard violation.  Thus, it ``should'' be legal to evaluate
  [47m(foo x)[0m, for any such [47mx[0m, simply by evaluating this form in raw
  Common Lisp.

  The [47m[verify-guards][0m event has been provided for this purpose.
  Details may be found elsewhere; see [verify-guards].  Briefly, for
  any defined function [47mfn[0m, the event [47m(verify-guards fn)[0m attempts to
  check the condition discussed above, that whenever [47mfn[0m 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.

  Returning to our example above, the [47m(verify-guards foo)[0m will succeed
  because the guard [47m(consp x)[0m of [47mfoo[0m implies the guard generated from
  the call [47m(cdr x)[0m in the body of the definition, namely, [47m(or (consp
  x) (equal x nil))[0m (see [cdr]).  Then the evaluation of [47m(foo (cons
  'a 3))[0m will take place in raw Common Lisp, because [47m(cons 'a 3)[0m
  satisfies the guard of [47mfoo[0m.

  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.

  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
  [guard-example] for an example.

  [3mGuards and evaluation IV: functions having :program mode[0m

  Strictly speaking, functions in [47m:[0m[47m[program][0m mode (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
  [47m:[0m[47m[program][0m functions much as we treat [47m:[0m[47m[logic][0m 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 [47m:[0m[47m[logic][0m
  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 [47m:[0m[47m[program][0m 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:

  [31;1mAside[0m.  There are exceptions to the use of raw Lisp, discussed just
  above, to evaluate calls of [47m:[0m[47m[program][0m mode functions.  The primary
  one is that after [47m:[0m[47m[set-guard-checking][0m[47m :none[0m, evaluation of
  user-defined [47m:[0m[47m[program][0m mode function calls is done in the ACL2
  logic, not in raw Lisp.  The more obscure exception is that during
  expansion of macros and [47m[make-event][0m forms, and during evaluation
  of [47m[defconst][0m 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 [47m:[0m[47m[set-guard-checking][0m[47m :none[0m if you are happy to
  skip all guard checking and evaluate forms in the logic.

    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):

  The other exception occurs after [47m[set-guard-checking][0m can be called
  with a value of [47m:all[0m; see [set-guard-checking].  [31;1mEnd of aside.[0m

  Thus, as with [47m:[0m[47m[logic][0m functions: when a guard has been satisfied on
  a call of a function with [47m:[0m[47m[program][0m mode, no subsidiary guard
  checking will be done.

  Notice that by treating functions in [47m:[0m[47m[program][0m 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.

    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>>

  See [defun-mode-caveat].

  However, here is a way to get ACL2 to do run-time guard checking for
  user-defined [47m:[0m[47m[program][0m mode functions.  With this method, ACL2
  will evaluate calls of user-defined [47m:program[0m 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.''

    (f-put-global 'safe-mode t state)

  Let us revisit the example above, using safe mode.  Notice that the
  guard of [47m[cdr][0m is now being checked, because the
  executable-counterpart of [47mfoo[0m is being called even though the
  [guard] is [47mt[0m.

    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!>

  If we go back into ``unsafe'' mode, then we once again see a raw Lisp
  error, as we now illustrate.

    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>>

  [3mGuards and evaluation V: efficiency issues[0m

  We have seen that by verifying the guards for a [47m:[0m[47m[logic][0m function, we
  arrange that raw lisp is used for evaluation of calls of such
  functions when the arguments satisfy its guard.

  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 [compilation]), enormous
  speed-ups are possible.  Third, if your Common Lisp or its compiler
  does such optimizations as [47mtail-recursion[0m removal, raw Common Lisp
  may be able to compute your functions on input much ``bigger'' than
  ACL2 can.

  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.

  When a function is defined in [47m:[0m[47m[logic][0m mode, its [47m[defun][0m is executed
  in raw Common Lisp; we call this the ``submitted'' definition of
  the function.  However, a corresponding executable-counterpart also
  executed.  (See [evaluation] for an introduction to submitted and
  executable-counterpart definitions.)  The executable-counterpart is
  a [47m[defun][0m 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 [compilation] often speeds up execution significantly.
  However, the [47m:[0m[47m[comp][0m command (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 [47m[defun][0m, a corresponding tail recursion removal is done
  on the executable-counterpart definition.

  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.

  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 [47m[declare][0m 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 [xargs] for a discussion of the
  [47m:split-types[0m keyword.

  To continue the discussion of guards, see [guards-for-specification]
  to read about the use of guards as a specification device.")
 (GUARDS-FOR-SPECIFICATION
  (GUARD)
  "Guards as a specification device

  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 [programming] languages,
  though guards allow much greater expressiveness than most systems
  of types (and unfortunately, as a result they are not syntactically
  checkable).

  For more discussion of guards in general, see [guard].

  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.

  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.

  The rest of this topic addresses those who wish to understand
  [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,

    (defun foo (x)
      (declare (xargs :guard (consp x)))
      (cons 1 (cdr x)))

  originally generates the axiom

    (equal (foo x)
           (cons 1 (cdr x)))

  but in fact, when evaluation involves no guard violation then the
  following weaker axiom suffices in the justification of the
  evaluation.

    (implies (consp x)
             (equal (foo x)
                    (cons 1 (cdr x))))

  So for example, suppose we evaluate [47m(foo '(a b c))[0m and get [47m'(1 b c)[0m.
  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.

  If you are following links to read this documentation as a hypertext
  style document, then please see [guard-miscellany].  This concludes
  our discussion of guards with miscellaneous remarks, and also
  contains pointers to related topics.")
 (GUARDS_IN_ACL2
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Guards

  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 [31;1mcompletion[0m 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.

  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 [47m[car][0m {ICON} (see [A_Tiny_Warning_Sign]), for example, is
  [47m(or (consp x) (equal x nil))[0m, which requires the argument to be
  either an ordered pair or [47mnil[0m.  We will discuss later how to
  specify a guard for a defined function; when one is not specified,
  the guard is [47mt[0m which is just to say all arguments are allowed.

  [31;1mBut guards are entirely extra-logical[0m: 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 [31;1mall[0m arguments, not just on the guarded domain.

  So what is the purpose of guards?

  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 [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.

  For a thorough discussion of guards, see the paper [km97] in the ACL2
  [bibliography].")
 (GUESSING_THE_TYPE_OF_A_NEWLY_ADMITTED_FUNCTION
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Guessing the Type of a Newly Admitted Function

  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 [47mapp[0m
  the term is

    (OR (CONSP (APP X Y))
        (EQUAL (APP X Y) Y))

  which says that [47mapp[0m returns either a cons or its second argument.
  This formula is added to ACL2's rule base as a [47m[type-prescription][0m
  {ICON} (see [A_Tiny_Warning_Sign]) 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.

  You should now return to the Walking Tour (see
  [Revisiting_the_Admission_of_App]).")
 (GUIDING_THE_ACL2_THEOREM_PROVER
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Guiding the ACL2 Theorem Prover

  {IMAGE} (see [ACL2_as_an_Interactive_Theorem_Prover_{cont}])

  Now that you have seen the theorem prover in action you might be
  curious as to how you guide it.

  {IMAGE}

  Look at the picture above.  It is meant to suggest that [3mQ[0m is an
  important lemma needed for the proof of [3mP[0m.  Note that to lead the
  prover to the proof of [3mP[0m the user first proves [3mQ[0m.  In a way, the
  formulation and proof of [3mQ[0m is a hint to the prover about how to
  prove [3mP[0m.

  The user usually doesn't think of [3mQ[0m or recognize the need to prove it
  separately until he or she sees the theorem prover [31;1mfail[0m to prove [3mP[0m
  without it ``knowing'' [3mQ[0m.

  The way the user typically discovers the need for [3mQ[0m is to look at
  failed proofs.

  {IMAGE} (see [ACL2_as_an_Interactive_Theorem_Prover_{cont}])")
 (HANDS-OFF
      (POINTERS)
      "See [hints] for information about the keyword [47m:hands-off[0m.")
 (HANDS-OFF-LAMBDA-OBJECTS-THEORY
  (THEORIES THEORY-FUNCTIONS REWRITE)
  "how to specify no modification of lambda objects

  The enabled status of two [47mrewrite-lambda-modep[0m runes are used as
  flags to determine the action taken when eligible [47mlambda[0m objects
  are encountered by the ACL2 rewriter.  See [rewrite-lambda-object]
  and [47m[rewrite-lambda-object-actions][0m.  To prevent the rewriter even
  considering changing a quoted [47mlambda[0m object, the rune
  [47m(:executable-counterpart rewrite-lambda-modep)[0m must be disabled in
  the then-current theory.  The 0-ary function
  [47mhands-off-lambda-objects-theory[0m returns such a theory.

  In fact, diving into eligible quoted [47mlambda[0m object constants to
  rewrite the body is the default action when ACL2 starts up.  See
  [rewriting-versus-cleaning-up-lambda-objects] for why you might
  want to change the default action when eligible [47mlambda[0m objects are
  encountered by the rewriter.

  The expression [47m(hands-off-lambda-objects-theory)[0m macroexpands to the
  theory expression

    (e/d nil
         ((:executable-counterpart rewrite-lambda-modep)))

  which is a theory equal to the current theory except that the
  executable-counterpart rune of [47mrewrite-lambda-modep[0m is disabled.
  This expansion is suitable for use in an [47m[in-theory][0m event or
  [47m:in-theory[0m hint (see [47m:[0m[47m[hints][0m).

  This rune is initially enabled, so eligible [47mlambda[0m object bodies are
  either rewritten or syntactically cleaned by default (depending on
  the status of [47m(:definition rewrite-lambda-modep)[0m) until and unless
  some event (e.g., an [47m[in-theory][0m or [47m[include-book][0m) or a superior
  local subgoal hint changes the status of this rune.

  For example, if [47mlambda[0m object rewriting is active and you wish it not
  to be (so that [47mlambda[0m objects remain unchanged) in [47mSubgoal 3[0m of
  some proof, you could use the [47m:[0m[47m[hints][0m

    (\"Subgoal 3\"
     :in-theory (hands-off-lambda-objects-theory))

  Note that if you also wish to enable or disable other runes in the
  same subgoal you must construct an appropriate theory.

  For example, if in [47mSubgoal 3[0m of some proof you wanted to enable
  [47mLEMMA1[0m and disable [47mLEMMA2[0m in a theory that will also specify
  syntactic cleaning of [47mlambda[0m objects, you might write

    (\"Subgoal 3\"
     :in-theory (set-difference-theories
                   (union-theories (hands-off-lambda-objects-theory)
                                   '(LEMMA1))
                   '(LEMMA2)))

  Some users might prefer

    (\"Subgoal 3\"
     :in-theory (e/d (LEMMA1)
                     ((:executable-counterpart rewrite-lambda-modep)
                      LEMMA2)))

  See [theories] for general information about theories and how to
  create and use them.")
 (HARD-ERROR
  (ERRORS ACL2-BUILT-INS)
  "Print an error message and stop execution

  [47m(Hard-error ctx str alist)[0m causes evaluation to halt with a short
  message using the ``context'' [47mctx[0m.  An error message is first
  printed using the string [47mstr[0m and alist [47malist[0m that are of the same
  kind as expected by [47m[fmt][0m.  See [fmt].  Also see [er] for a macro
  that provides a unified way of signaling errors.

  [47mHard-error[0m has a guard of [47mt[0m.  Also see [illegal] for a similar
  capability which however has a guard of [47mnil[0m that supports static
  checking using [47m[guard][0m verification, rather than using dynamic
  (run-time) checking.  This distinction is illustrated elsewhere:
  see [prog2$] for examples.

  Semantically, [47mhard-error[0m ignores its arguments and always returns
  [47mnil[0m.  But if a call [47m(hard-error ctx str alist)[0m is encountered
  during evaluation, then the string [47mstr[0m is printed using the
  association list [47malist[0m (as in [47m[fmt][0m), after which evaluation halts
  immediately.  Here is a trivial, contrived example.

    ACL2 !>(cons 3 (hard-error 'my-context
                                \"Printing 4: ~n0\"
                                (list (cons #\\0 4))))

    HARD ACL2 ERROR in MY-CONTEXT:  Printing 4: four

    ACL2 Error in TOP-LEVEL:  Evaluation aborted.

    ACL2 !>

  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: [47m(setq
  *hard-error-is-error* t)[0m.  Indeed, any non-[47mnil[0m value for
  [47m*hard-error-is-error*[0m will cause [47mhard-error[0m or [47m[illegal][0m --- or
  indeed [47m(er hard ...)[0m, [47m(er hard! ...)[0m, or [47m(er hard?  ...)[0m --- to
  produce a Lisp error whose condition, when printed with [47mformat[0m
  directive [47m~a[0m, is the same error message that ACL2 would otherwise
  print.  Below is a sample log, closely based on an example provided
  by Jared Davis.

    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
    ?

  Note that when a raw Lisp error occurs because [47m*hard-error-is-error*[0m
  is non-[47mnil[0m, the error message will not use [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 [47m#@i#[0m after that return.

  [31;1mFunction: [0m<hard-error>

    (defun hard-error (ctx str alist)
      (declare (xargs :guard t))
      (declare (ignore ctx str alist))
      nil)")
 (HASH-TABLES (POINTERS)
              "See [defstobj].")
 (HEADER
  (ARRAYS ACL2-BUILT-INS)
  "Return the header of a 1- or 2-dimensional array

    Example Form:
    (header 'delta1 a)

    General Form:
    (header name alist)

  where [47mname[0m is arbitrary and [47malist[0m is a 1- or 2-dimensional array.
  This function returns the header of the array [47malist[0m.  The function
  operates in virtually constant time if [47malist[0m is the semantic value
  of [47mname[0m.  See [arrays].

  [31;1mFunction: [0m<header>

    (defun header (name l)
      (declare (xargs :guard (or (array1p name l) (array2p name l))))
      (prog2$ name (assoc-eq :header l)))")
 (HEAVY-LINEAR-P
  (LINEAR-ARITHMETIC SYSTEM-ATTACHMENTS)
  "Extend the use of [linear-arithmetic] during rewriting

  This topic concerns an advanced control for the ACL2 prover.

  This zero-ary attachable system function supports extending the usual
  use of [linear-arithmetic] during rewriting, specifically with the
  test (first) argument of a call of [47mIF[0m.  To get this additional
  power, possibly at considerable loss of efficiency, evaluate
  [47m(defattach-system heavy-linear-p constant-t-function-arity-0)[0m.  To
  restore the default behavior, evaluate [47m(defattach-system
  heavy-linear-p constant-nil-function-arity-0)[0m.")
 (HEY_WAIT!__IS_ACL2_TYPED_OR_UNTYPED{Q}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Hey Wait!  Is ACL2 Typed or Untyped?

  The example

    ACL2 !>[31;1m(app 7 27)[0m

    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).

  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
  [Guards_in_ACL2] for a discussion of guards.

  The guard on [47m[endp][0m {ICON} (see [A_Tiny_Warning_Sign]) 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 here (see [About_the_Prompt])) with its ``!''.")
 (HIDDEN-DEATH-PACKAGE
  (PACKAGES DEFPKG)
  "Handling [47m[defpkg][0m [events] that are [47m[local][0m

  This documentation topic explains a little bit about certain errors
  users may see when attempting to evaluate a [47m[defpkg][0m event.  In
  brief, if you see an error that refers you to this topic, you are
  probably trying to admit a [47m[defpkg][0m event, and you should change
  the name of the package to be introduced by that event.

  Recall that [47mdefpkg[0m events introduce axioms, for example as follows.

    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 !>

  Consider a [47m[defpkg][0m event that is introduced during evaluation of an
  [47m[include-book][0m event, where that [47minclude-book[0m event occurs
  [local]ly inside a surrounding [47m[encapsulate][0m event or another
  [47minclude-book[0m event.  In that case, traces of the axiom added by the
  [47mdefpkg[0m 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
  [package-reincarnation-import-restrictions] for relevant
  discussion, or see the ``Essay on Hidden Packages'' in source file
  [47maxioms.lisp[0m..

  In order to prevent unsoundness, ACL2 maintains the following
  invariant.  Let us say that a [47mdefpkg[0m event is ``hidden'' if it is
  in support of the current logical [world] but is not present in
  that world as an event, because it is [47m[local][0m as indicated above.
  We maintain the invariant that all [47m[defpkg][0m [events], even if
  ``hidden'', are tracked under-the-hood in the current logical
  [world].  Sometimes this property causes [47m[defpkg][0m events to be
  written to the [portcullis] of a book's [certificate] (see
  [books]).  This invariant guarantees that if you then try to define
  a package in a manner inconsistent with its earlier definition ---
  specifically, with a different imports list --- you will see an
  error because of the tracking discussed above.

  (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!)")
 (HIDDEN-DEFPKG
      (PACKAGES DEFPKG)
      "Handling defpkg events that are local

  See [hidden-death-package]")
 (HIDE
  (REWRITE)
  "Hide a term from the rewriter

  [47mHide[0m is actually the [identity] function: [47m(hide x) = x[0m for all [47mx[0m.
  However, terms of the form [47m(hide x)[0m are ignored by the ACL2
  rewriter, except when explicit [47m:expand[0m [hints] are given for such
  terms (see [hints]) or when rewrite rules explicitly about [47mhide[0m are
  available.  An [47m:expand[0m hint that removes all calls of [47mhide[0m is:

    :expand ((:free (x) (hide x)))

  The above hint can be particularly useful when ACL2's equality
  heuristics apply [47mhide[0m to an equality after substituting it into the
  rest of the goal, if that goal (or a subgoal of it) fails to be
  proved.

  Another common case, described below, is when [47mhide[0m is added by the
  simplifier because an attempted execution of the term failed.  In
  this case, an [47m:expand[0m hint as described above will have no effect
  because the execution will just fail again; the [47mhide[0m will be
  re-inserted; and the hapless user will find themselves questioning
  their own sanity.

  [47mHide[0m terms are generally ignored not only by the rewriter but by
  other ACL2 procedures, including the induction heuristics and (by
  default) removal of [guard-holders].

  Sometimes the ACL2 simplifier inserts [47mhide[0m 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 [47mconstrained-fn[0m, and
  you define another function, say [47manother-fn[0m, in terms of it, as in:

    (defun another-fn (x y z)
      (if (big-hairy-test x y z)
          (constrained-fn x y z)
          t))

  Suppose the term [47m(another-fn 1 2 3)[0m 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 [47manother-fn[0m.  However,
  after a possibly extensive computation (because of [47mbig-hairy-test[0m)
  the execution fails because of the unevaluable call of
  [47mconstrained-fn[0m.  To avoid subsequent attempts to evaluate the term,
  ACL2 embeds it in a [47mhide[0m expression.  Often that expression will
  use a call of [47m[comment][0m, where [47m(comment x y)[0m is logically just [47my[0m,
  to tell you the problematic constrained function, in this case by
  rewriting the original expression to the following; see [comment].
  (Near the end of this topic we discuss how to avoid the call of
  [47mcomment[0m.)

    (hide (comment \"Failed attempt to call constrained function CONSTRAINED-FN\"
                   (another-fn 1 2 3)))

  You might think this rarely occurs since all the arguments of
  [47manother-fn[0m must be constants.  You would be right except for one
  special case: if [47manother-fn[0m takes no arguments, i.e., is a constant
  function, then every call of it fits this case.  Thus, if you
  define a function [47mf[0m of no arguments in terms of a constrained
  function [47mg[0m, you may often see [47m(f)[0m rewrite to:

    (hide (comment \"Failed attempt to call constrained function G\"
                   (f))).

  We do not hide the term if the [executable-counterpart] of the
  function is [disable]d --- because we do not try to evaluate it in
  the first place.  Thus, to prevent the insertion of a [47mhide[0m term
  into the proof attempt, you can globally disable the
  executable-counterpart of the offending defined function, e.g.,

    (in-theory (disable (:executable-counterpart another-fn))).

  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 [47mhide[0m terms are introduced
  on the calls that cannot be computed, but prove explicit [47m:[0m[47m[rewrite][0m
  rules for each of those [47mhide[0m terms.  For example, suppose that in
  the proof of some theorem, thm, it is necessary to leave the
  executable-counterpart of [47manother-fn[0m enabled but that the call
  [47m(another-fn 1 2 3)[0m arises in the proof and cannot be computed.
  Thus the proof attempt will introduce the term [47m(hide (comment \"..\"
  (another-fn 1 2 3)))[0m mentioned above.  Suppose that you can show
  that [47m(another-fn 1 2 3)[0m is [47m(constrained-fn 1 2 3)[0m and that such a
  step is necessary to the proof.  Unfortunately, proving the rewrite
  rule

    (defthm thm-helper
      (equal (another-fn 1 2 3) (constrained-fn 1 2 3)))

  would not help the proof of thm because the target term is hidden
  inside the [47mhide[0m.  However,

    (defthm thm-helper
      (equal (hide (comment \"Failed attempt to call constrained function CONSTRAINED-FN\"
                            (another-fn 1 2 3)))
             (constrained-fn 1 2 3)))

  would be applied in the proof of thm and is the rule you should
  prove.

  Now to prove [47mthm-helper[0m you need to use the two ``tricks'' which have
  already been discussed.  First, to eliminate the [47mhide[0m term in the
  proof of [47mthm-helper[0m you should include a hint to [47m:expand[0m that term.
  Second, to prevent the [47mhide[0m term from being reintroduced when the
  system tries and fails to evaluate [47m(another-fn 1 2 3)[0m you should
  include the hint [47m:in-theory[0m [47m(disable (:executable-counterpart
  another-fn))[0m.  Thus, [47mthm-helper[0m will actually be:

    (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)))))

  See [eviscerate-hide-terms] for how to affect the printing of [47mhide[0m
  terms.

  Finally, note that you can avoid the generation of [47m[comment][0m calls
  inside the generated call of [47mhide[0m, as was the case through ACL2
  Version 8.2, as follows.

    (defattach-system ; generates (local (defattach ...))
      hide-with-comment-p
      constant-nil-function-arity-0)

  After evaluation of this event, our running example [47m(another-fn 1 2
  3)[0m would generate [47m(hide (another-fn 1 2 3))[0m rather than a term of
  the form [47m(hide (comment \"...\" (another-fn 1 2 3)))[0m.

  In some cases such backward compatibility might also be achieved as
  follows; also see [guard-holders].

    (defattach-system ; generates (local (defattach ...))
      remove-guard-holders-blocked-by-hide-p
      constant-nil-function-arity-0)

  [31;1mFunction: [0m<hide>

    (defun hide (x)
      (declare (xargs :guard t))
      x)


Subtopics

  [Comment]
      Variant of [47m[prog2$][0m to help debug evaluation failures during proofs")
 (HINTS
  (MISCELLANEOUS)
  "Advice to the theorem proving process

    Examples:
    The following :hints value is nonsensical.  Nevertheless, it
    illustrates all of the available hint keywords except the
    ``custom keywords'' (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 ((<-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)))
             :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)))

  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
  [hints-and-the-waterfall]).  The following hints, however, have a
  specific effect only on the goal to which they are applied: [47m:bdd[0m,
  [47m:by[0m, [47m:cases[0m, [47m:clause-processor[0m, [47m:error[0m, [47m:induct[0m, [47m:or[0m, and [47m:use[0m.
  For example, suppose that you specify both a [47m:cases[0m hint and an
  [47m:expand[0m hint for [47m\"Goal\"[0m.  Then the [47m:cases[0m hint will immediately
  result in subgoals, without calling the ACL2 rewriter; the [47m:expand[0m
  hint will be used by the rewriter in subsequent goals.

  A very common hint is the [47m:use[0m hint, which is described below.  In
  general it takes as its value a list of ``lemma instances'' (see
  [lemma-instance]), but it allows special cases, including a single
  lemma name.  In each case, a goal [47mG[0m is replaced by a new goal
  [47m(IMPLIES P G)[0m, where [47mP[0m is the theorem specified by the (conjunction
  of the) lemma instances provided.  Here are some examples.

    ; 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)))))

  ACL2 also provides ``custom keyword'' hints (see
  [custom-keyword-hints]) and even more general ``computed hints''
  for the advanced user (see [computed-hints]).  Not documented in
  this topic are such hints implemented in books; for an example of
  so-called [47m:consider[0m hints, see [consideration].

  When the ACL2 prover encounters a goal [47m\"G\"[0m, then the first hint of
  the form [47m(\"G\" :kwd1 val1 ...)[0m is applied to that goal.  This
  usually means that all hints for the goal [47m\"G\"[0m after the first such
  hint are ignored, and ACL2 produces a warning about that.  (Note
  however that [47m(\"G\")[0m is simply dropped; such an empty hint is
  considered not to be there, for purposes of this discussion.)  If
  there are default hints (see [set-default-hints]) then this
  behavior applies to the user-supplied list of [47m:hints[0m followed by
  the default hints; see [hints-and-the-waterfall] for a detailed
  discussion of how hints fit into the ACL2 waterfall, which in
  particular has a ``slightly tricky example'' illustrating the
  unusual case when a goal can be encountered more than once, thus
  applying more than one hint on that goal.  Also see
  [override-hints] for an advanced feature that can modify the
  ``first hint'' behavior described above.  For examples of the
  sophisticated use of hints, primarily for experts, see community
  book [47mbooks/hints/basic-tests.lisp[0m.

  Duplicate hint keywords are prohibited in a hint; for example, the
  hint [47m(\"Goal\" :induct t :induct t)[0m is illegal.  Also, certain hint
  keywords are incompatible within a given hint, for example, in
  [47m(\"Goal\" :use nth :induct t)[0m.  These restrictions for duplicates and
  compatibility apply not only for explicit hints but also for hints
  that are generated by computed hints or [override-hints]; for
  example, the command [47m(add-override-hints '((append '(:use nth
  :induct t) keyword-alist)))[0m will cause subsequent proof attempts to
  fail because [47m:use[0m and [47m:induct[0m are incompatible keywords.  Here is
  the full list of incompatibilities for hint keywords on a given
  goal.

    * It is illegal to use two or more keywords from the following list,
      except that [47m:use[0m and [47m:cases[0m may be used together:
      [47m(:induct :use :cases :by :bdd :clause-processor :or)[0m.

    * It is illegal to use [47m:reorder[0m with either [47m:or[0m or [47m:induct[0m.

  Background: [47mHints[0m are allowed in all [events] that use the theorem
  prover.  During [47m[defun][0m [events] there are two different uses of
  the theorem prover: one to prove termination and another to verify
  the [guard]s.  To pass a hint to the theorem prover during
  termination proofs, use the [47m:hints[0m keyword in the [47m[defun][0m's [47m[xargs][0m
  declaration.  To pass a hint to the theorem prover during the
  [guard] verification portion of admitting a [47m[defun][0m, use the
  [47m:guard-hints[0m keyword in the [47m[defun][0m's [47m[xargs][0m declaration.  The
  [47m[verify-guards][0m event and the [47m[defthm][0m event also use the theorem
  prover.  To pass hints to them, use the [47m:hints[0m keyword argument to
  the event.

    General Form of Common :hints:
      ((goal-spec :key1 val1 ... :keyn valn)
       ...
       (goal-spec :key1 val1 ... :keyn valn))

  where [47m[goal-spec][0m is as described elsewhere (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 [computed-hints].  The hint keywords below are
  considered in alphabetical order.

    [47m:backchain-limit-rw[0m

        [47mValue[0m is a natural number or [47mnil[0m, indicating the level of
        backchaining for [rewrite], [meta], and [linear] rules.  This
        overrides, for the current goal and (as with [47m:[0m[47m[in-theory][0m
        hints) descendant goals, the default [backchain-limit] (see
        [set-backchain-limit]).

    [47m:backtrack[0m

        This is an advanced hint.  You can probably accomplish its effect by
        the use of ordinary computed hints; see [computed-hints].
        But if you are an expert, read on.  (See
        [hints-and-the-waterfall] for some relevant background.)

        [47mValue[0m is a computed hint, which is an expression that evaluates
        either to [47mnil[0m --- indicating that the [47m:backtrack[0m hint is to
        have no effect --- or to a non-empty alternating list of
        [47m:keyi vali[0m pairs, as expected for a hint.  However, unlike
        ordinary computed hints, [47m:backtrack[0m hints are evaluated [31;1mafter[0m
        a goal has been processed to yield zero or more subgoals, not
        before.  Moreover, variables [47mPROCESSOR[0m and [47mCLAUSE-LIST[0m are
        allowed, but variable [47mSTABLE-UNDER-SIMPLIFICATIONP[0m is not.
        We explain in more detail below, but first consider the
        following simple example.  First we define a standard list
        reversal function:

          (defun rev (x)
            (if (consp x)
                (append (rev (cdr x)) (cons (car x) nil))
              nil))

        Now we prove:

          (thm (true-listp (rev x)))

        The successful proof includes the following output.

          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)))).

        But suppose that we attach a [47m:backtrack[0m hint to the goal above at
        which destructor elimination was applied:

          (thm (true-listp (rev x))
               :hints ((\"Subgoal *1/1'\"
                        :backtrack
                        (quote (:do-not '(eliminate-destructors))))))

        Then when ACL2 applies destructor elimination as displayed above,
        this time the [47m:backtrack[0m hint applies, evaluating to [47m(:do-not
        '(eliminate-destructors))[0m.  Since this list is not [47mnil[0m, the
        prover decides not to keep the new subgoal, and instead
        supplies this [47m:do-not[0m 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:

          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))))).

        We now provide a careful explanation of how [47m:backtrack[0m hints work,
        but we suggest that you keep the example above in mind.  If
        ``[47m:backtrack form[0m'' is part of the hint that has been
        selected for a goal, then [47mform[0m is evaluated when one of
        ACL2's [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 [computed-hints]), with the following exceptions.
        First, the variable [47mSTABLE-UNDER-SIMPLIFICATIONP[0m is not
        allowed to occur free in [47mform[0m, but instead the following new
        variables are allowed to occur free and are bound for this
        evaluation as follows: [47mPROCESSOR[0m is bound to the processor in
        the list [47m*preprocess-clause-ledge*[0m that has applied to the
        goal, and [47mCLAUSE-LIST[0m is bound to the list of clauses (each a
        list of literals that is implicitly disjoined) returned by
        that clause processor.  Second, the variables [47mHIST[0m and [47mPSPV[0m
        are bound to the history and pspv returned by the clause
        processor, [31;1mnot[0m 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 [47mnil[0m, then the
        [47m:backtrack[0m hint has no effect, and the goal is replaced by
        the list of goals (the value of [47mCLAUSE-LIST[0m 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 [custom-keyword-hints]), then it will be
        handled in the usual manner but with the first three
        variables above bound to the symbol [47m:OMITTED[0m.  Of course, if
        the new hint includes a value for [47m:BACKTRACK[0m then this
        process can loop; care should be taken to keep that from
        happening.

        A final note about [47m:BACKTRACK[0m hints: since these are a form of
        computed hints, [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 [47mnil[0m).  See
        [override-hints].

    [47m:[0m[47m[bdd][0m

        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 [bdd] for an introduction to the ACL2
        BDD algorithm.

        [47mValue[0m is a list of even length, such that every other element,
        starting with the first, is one of the keywords [47m:vars[0m,
        [47m:bdd-constructors[0m, [47m:prove[0m, or [47m:literal[0m.  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 [47m:vars[0m must always be supplied, we expect that most
        users will be content with the defaults used for the other
        values.

            [47m:vars[0m --- A list of ACL2 variables, which are to be treated as
            Boolean variables.  The prover must be able to check,
            using [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 [47m:vars[0m (so that they are
            ``greater than'' the variables that do occur in [47m:vars[0m),
            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 [3mnot[0m to rely on the default order,
            but to supply a list of variables instead.  Finally, it
            is allowed to use a value of [47mt[0m for [47mvars[0m.  This means the
            same as a [47mnil[0m 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 [bdd-algorithm]).

            [47m:literal[0m --- An indication of which part of the current goal should
            receive BDD processing.  Possible values are:

              :all     treat entire goal as a single literal (the default)
              :conc    process the conclusion
              n        process the hypothesis with index n (1, 2, ...)

            [47m:bdd-constructors[0m --- When supplied, this value should be a list of
            function symbols in the current ACL2 [world]; it is
            [47m(cons)[0m by default, unless [47m:bdd-constructors[0m has a value
            in the [47m[ACL2-defaults-table][0m by default, in which case
            that value is the default.  We expect that most users
            will be content with the default.  See [bdd-algorithm]
            for information about how this value is used.

            [47m:prove[0m --- When supplied, this value should be [47mt[0m or [47mnil[0m; it is [47mt[0m by
            default.  When the goal is not proved and this value is
            [47mt[0m, the entire proof will abort.  Use the value [47mnil[0m if you
            are happy to the proof to go on with the simplified term.

    [47m:by[0m

        [47mValue[0m is a [lemma-instance], [47mnil[0m, or a new event name. If the value
        is a [lemma-instance] (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,

          (IMPLIES (AND (h1 t1) (h2 t2)) (c t1))

        may be viewed as the clause

          {~(h1 t1) ~(h2 t2) (c t1)}.

        Clause [47mc1[0m is ``subsumed'' by clause [47mc2[0m iff some instance of [47mc2[0m is a
        subset of [47mc1[0m.  For example, the clause above is subsumed by
        [47m{~(h1 x) (c x)}[0m, which when viewed as a formula is [47m(implies
        (h1 x) (c x))[0m.

        Note that if the value is the name of a function symbol introduced by
        [47m[defun][0m, then the original form of the body of that
        definition is used.  This behavior differs from that provided
        by a [47m:use[0m hint, which uses the normalized (simplified) body;
        see [normalize].

        If the value is [47mnil[0m 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 [defthm] form to define
        each of the [47m:by[0m names.  The ``name'' [47mnil[0m means ``make up a
        name.'' Here is an example (admittedly contrived for
        illustration purposes).

          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 ...]]

        The system does not attempt to check the uniqueness of the [47m:by[0m 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'' [47m[defthm][0m 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 [47m:by[0m hints themselves.

    [47m:[0m[47m[case-split-limitations][0m

        [47mValue[0m is the same as for [47m[set-case-split-limitations][0m.  The
        simplifier will behave as though the value had instead been
        supplied to [47mset-case-split-limitations[0m; see
        [set-case-split-limitations].  This behavior will persist
        through subgoals unless overridden by another
        [47m:CASE-SPLIT-LIMITATIONS[0m hint.

    [47m:cases[0m

        [47mValue[0m 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.

    [47m:[0m[47m[clause-processor][0m

        [47mValue[0m specifies the application of a user-defined simplifier to the
        current goal.  See [clause-processor], which provides
        necessary background and hint syntax.  Also 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.

        You can see all current [47m:clause-processor[0m rules by issuing the
        command [47m(print-clause-processor-rules)[0m, and you can see the
        names of all trusted clause-processors by issuing the command
        [47m(table trusted-cl-proc-table)[0m.

    [47m:do-not[0m

        [47mValue[0m is a term having at most the single free variable [47m[world][0m,
        which when evaluated (with [47m[world][0m bound to the current ACL2
        logical [world]) produces a list of symbols that is a subset
        of the list

          (preprocess ;propositional logic, simple rules
           simplify   ;as above plus rewriting, linear arithmetic
           eliminate-destructors
           fertilize  ;use of equalities
           generalize
           eliminate-irrelevance).

        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

          :do-not '(generalize fertilize)

        If [47mvalue[0m is a single symbol, as in

          :do-not generalize,

        it is taken to be [47m'(value)[0m.

        See also [do-not-hint] for a way to automatically provide [47m:do-not[0m
        hints across several theorems.

    [47m:do-not-induct[0m

        [47mValue[0m indicates whether [induction] is permitted under the specified
        goal.  The legal values are [47mt[0m, [47m:otf-flg-override[0m, [47m:otf[0m, [47mnil[0m,
        or a non-keyword symbol other than [47mt[0m or [47mnil[0m.  The default is
        [47mnil[0m, meaning that induction is permitted as usual.  A non-[47mnil[0m
        value prohibits the use of induction to prove the indicated
        goal or any of its subgoals, as described below.

        If [47mvalue[0m is [47mt[0m or [47m:otf-flg-override[0m, then the attempt to apply
        [induction] to the indicated goal or any subgoal under the
        indicated goal will immediately cause the theorem prover to
        report [failure], except that if [47m:otf-flg t[0m is specified (see
        [otf-flg]) and [47mvalue[0m is [47mt[0m, 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 [47mvalue[0m is [47m:otf[0m.  See however the [47m:induct[0m hint
        below.  If [47mvalue[0m is a non-keyword symbol other than [47mt[0m or [47mnil[0m,
        the theorem prover will skip every subgoal under the
        indicated goal (giving it a ``bye'', as with a ``[47m:by[0m'' 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 [47m:do-not-induct[0m hint
        that caused that subgoal to be skipped.

        [31;1mRemarks.[0m

        (1) An [47m:induct[0m hint is applied to a goal even if a [47m:do-not-induct[0m
        hint is in effect for that goal.  Consider the following
        examples.

          (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)))

        In the first of these, the [47m:do-not-induct[0m hint has no effect on the
        proof; instead, the [47m:induct[0m hint forces an induction that
        allows the proof to succeed (without any sub-inductions).
        The second of these illustrates that even though
        [47m:do-not-induct[0m can stop sub-inductions, its effect is
        overridden by [47m:induct[0m.  For the proof of that second example,
        ACL2 immediately splits into two subgoals.  Then in spite of
        the top-level [47m:do-not-induct[0m hint, the proof is allowed to
        proceed past Subgoal 2, which requires induction, because of
        the hint [47m:induct t[0m.  However, the proof halts after Subgoal 1
        because of the [47m:do-not-induct[0m hint that has been established
        ``above'' it, at [47m\"Goal\"[0m.  (For more about the way hints are
        processed, see [hints-and-the-waterfall].)

        (2) For an advanced example of the use of value [47m:otf[0m for
        [47m:do-not-induct[0m combined with [override-hints], see community
        book [47mbooks/hints/basic-tests.lisp[0m.

    [47m:error[0m

        [47mValue[0m is typically a ``fmt message'' to be printed by the [47m[fmt][0m
        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 [47m:ERROR[0m hint in any user-typein,
        since it will only cause an error when the form is evaluated.
        [47m:ERROR[0m hints are useful in the definition of functions that
        generate custom keyword hints (see [custom-keyword-hints])
        and computed hints (see [computed-hints]).  For example, if
        you wish to define a custom keyword hint [47m:my-hint val[0m and you
        wish the hint to signal an error if there is something
        inappropriate about [47mval[0m in the context of the hint, use the
        following code to generate the hint

          (list :ERROR (cons \"Your specified value, ~x0, is inappropriate\"
                             (list (cons #0 val))))

        which is equivalent to

          (list :ERROR (msg \"Your specified value, ~x0, is inappropriate\"
                            val))

        which, if [47mval[0m has the value [47m123[0m, would evaluate to the hint

          (:ERROR (\"Your specified value, ~x0, is inappropriate\" (#0 . 123))).

        Note that any time an [47m:ERROR[0m keyword is produced during hint
        processing, including iterations of the expansions of custom
        keyword hints or of [override-hints], an error will occur.

    [47m:expand[0m

        [47mValue[0m is a true list of terms, each of which is of one of the forms
        [47m(let ((v1 t1)...) b)[0m or [47m(fn t1 ... tn)[0m, where [47mfn[0m is a defined
        function symbol with formals [47mv1, ..., vn,[0m and [47mbody[0m [47mb[0m.  Such a
        term is said to be ``expandable:'' it can be replaced by the
        result of substituting the [47mti[0m's for the [47mvi[0m's in [47mb[0m.  The terms
        listed in the [47m:expand[0m 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 [47mvalue[0m to be a single such
        term instead of a singleton list.  [31;1mRemarks[0m: (0) Note that in
        the event that a [47m:definition[0m rule has been admitted for [47mfn[0m,
        then by default, the body [47mb[0m is determined by the (most
        recently admitted such) rule rather than the original
        definition of [47mfn[0m; see [definition].  (1) Allowed are
        ``terms'' of the form [47m(:free (var1 var2 ...  varn) pattern)[0m
        where the indicated variables are distinct and [47mpattern[0m 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 [47mpattern[0m by instantiating the variables [47m(var1
        var2 ...  varn)[0m, then it expands that term.  (2) Also allowed
        are ``terms'' of the form [47m(:with name term)[0m, where [47mname[0m is a
        function symbol, a macro name that denotes a function symbol
        (see [macro-aliases-table]), or a [rune].  The corresponding
        [definition] rule or (less often) [47m[rewrite][0m rule is then used
        in place of the current body for the function symbol of [47mterm[0m;
        see [show-bodies] and see [set-body].  If the rule is of the
        form [47m(implies hyp (equiv lhs rhs))[0m, then after matching [47mlhs[0m
        to the current term in a context that is maintaining
        equivalence relation [47mequiv[0m, ACL2 will replace the current
        term with [47m(if hyp rhs (hide term))[0m, or just [47mrhs[0m if the rule
        is just [47m(equal lhs rhs)[0m.  (3) A combination of both [47m:free[0m and
        [47m:with[0m, as described above, is legal.  (4) The term [47m:LAMBDAS[0m
        is treated specially.  It denotes the list of all lambda
        applications (i.e., [47m[let][0m expressions) encountered during the
        proof.  Conceptually, this use of [47m:LAMBDAS[0m 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).

    [47m:hands-off[0m

        [47mValue[0m 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 [hide] if that is not
        what is intended.  (The community book
        [47mbooks/clause-processors/autohide.lisp[0m from Jared Davis may
        also be helpful in that case.) [47mValue[0m may also be a single
        function symbol or lambda expression instead of a list.

    [47m:[0m[47m[in-theory][0m

        [47mValue[0m is a ``theory expression,'' i.e., a term having at most the
        single free variable [47m[world][0m which when evaluated (with
        [47m[world][0m bound to the current ACL2 logical world (see
        [world])) will produce a theory to use as the current theory
        for the goal specified.  See [theories].

        Note that an [47m:[0m[47m[in-theory][0m hint will always be evaluated relative to
        the current ACL2 logical [world], not relative to the theory
        of a previous goal.  Consider the following example.

          (defthm prop
            (p (f (g x)))
            :hints ((\"Goal\"      :in-theory (disable f))
                    (\"Subgoal 3\" :in-theory (enable  g))))

        Consider in particular the theory in effect at [47mSubgoal 3[0m.  This call
        of the [47m[enable][0m macro enables [47mg[0m relative to the
        [47m[current-theory][0m of the current logical [world], [3mnot[0m relative
        to the theory produced by the hint at [47mGoal[0m.  Thus, the
        [47m[disable][0m of [47mf[0m on behalf of the hint at [47mGoal[0m will be lost at
        [47mSubgoal 3[0m, and [47mf[0m will be enabled at [47mSubgoal 3[0m if was enabled
        globally when [47mprop[0m was submitted.

    [47m:induct[0m

        [47mValue[0m is either [47mt[0m or a term that is not an atom or a quoted constant.
        The value [47mt[0m 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 [47mvalue[0m rather than the goal to generate its
        [induction] scheme.  Either way (i.e., for value [47mt[0m or not),
        merging and the other [induction] heuristics are applied.
        Thus, if [47mvalue[0m contains several mergeable [induction]s, the
        ``best'' will be created and chosen.  E.g., the [47m:induct[0m hint

          (and (nth i a) (nth j a))

        suggests simultaneous [induction] on [47mi[0m, [47mj[0m, and [47ma[0m.

        If both an [47m:induct[0m and a [47m:do-not-induct[0m hint are supplied for a given
        goal then the indicated [induction] is applied to the goal
        and the [47m:do-not-induct[0m hint is inherited by all subgoals
        generated.

    [47m:[0m[47m[instructions][0m

        [47mValue[0m is a list of interactive [proof-builder] instructions; see
        [instructions].  Unlike other hint keywords described here,
        this one is actually a custom keyword hint (see
        [custom-keyword-hints]) that generates a suitable
        [47m:[0m[47m[clause-processor][0m hint.

    [47m:no-op[0m

        [47mValue[0m is any object and is irrelevant.  This hint has no effect,
        although unlike an empty hint such as [47m(\"Goal\")[0m, it is not
        dropped.  Thus, [47m(\"Goal\" :no-op t)[0m will shadow any later (or
        default) hint on [47m\"Goal\"[0m, but [47m(\"Goal\")[0m will not.  Unlike other
        hint keywords, multiple occurrences of the keyword [47m:no-op[0m are
        tolerated.

    [47m:no-thanks[0m

        [47mValue[0m is any object.  This hint does nothing, except that if [47mvalue[0m is
        non-[47mnil[0m then the usual ``[Note: A hint was supplied...
        Thanks!]'' is not printed.

    [47m:nonlinearp[0m

        [47mValue[0m is [47mt[0m or [47mnil[0m, indicating whether [non-linear-arithmetic] is
        active.  The default value is [47mnil[0m.  See
        [non-linear-arithmetic].

    [47m:or[0m

        [47mValue[0m is a list [47m(kwd-val-listp-1 ... kwd-val-listp-k)[0m, where each
        [47mkwd-val-listp-i[0m is a list satisfying [47m[keyword-value-listp][0m,
        i.e., an alternating list of keywords and values.  This hint
        causes an attempt to prove the specified goal using hints
        [47mkwd-val-listp-i[0m in sequence (first [47mkwd-val-listp-1[0m, then
        [47mkwd-val-listp-2[0m, 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.

        The following (contrived but illustrative example illustrates how [47m:or[0m
        hints work.

          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).

        ... and so on.  This example illustrates how ACL2 processes [47m:or[0m hints
        in general.  For each [47mi[0m from 1 to [47mk[0m, a so-called
        ``disjunctive'' subgoal is created by splicing
        [47mkwd-val-listp-i[0m into the other hint values (if any) supplied
        for the given goal, in order.  A corresponding subgoal is
        created for each [47mi[0m, numbered in the usual manner (hence,
        counting down) except that the ``[47mD[0m'' is prefixed to each
        resulting goal.

    [47m:reorder[0m

        [47mValue[0m is a list of positive integers without duplicates,
        corresponding to the numbering of subgoals generated for the
        [goal-spec] [47m\"G\"[0m, say [47m\"G.k\"[0m down to [47m\"G.1\"[0m.  Those subgoals are
        reordered so that if [47mvalue[0m is [47m(n1 n2 ... nk)[0m, then the goal
        now numbered [47m\"G.k\"[0m will be the goal originally numbered
        [47m\"G.n1\"[0m; the goal now numbered [47m\"G.k-1\"[0m will be the goal
        formerly numbered [47m\"G.n2\"[0m; and so on, down the list of [47mni[0m,
        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 [47m*1[0m, is not supported.

    [47m:restrict[0m

        This hint, originally suggested by Bishop Brock, sometimes allows
        rules with free variables (see [free-variables]) to be
        applied successfully by the rewriter, thus avoiding the
        clutter, case-splitting, and theory management (disabling)
        that can occur with [47m:use[0m hints.

        Warning: This is a sophisticated hint that may be most appropriate
        for experienced ACL2 users.  In particular, [47m:restrict[0m hints
        are ignored by the preprocessor, so you might find it useful
        to give the hint [47m:do-not '(preprocess)[0m when using any
        [47m:restrict[0m hints, at least if the rules in question are
        abbreviations (see [simple]).

        [47mValue[0m is an association list.  Its members are of the form [47m(x subst1
        subst2 ...)[0m, where: [47mx[0m is either (1) a [rune] whose [47m[car][0m is
        [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m or (2) an event name
        corresponding to one or more such [rune]s; and [47m(subst1 subst2
        ...)[0m is a non-empty list of substitutions, i.e., of
        association lists pairing variables with terms.  First
        consider the case that [47mx[0m is a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m
        [rune].  Recall that without this hint, the rule named [47mx[0m is
        used by matching its left-hand side (call it [47mlhs[0m) against the
        term currently being considered by the rewriter, that is, by
        attempting to find a substitution [47ms[0m such that the
        instantiation of [47mlhs[0m using [47ms[0m is equal to that term.  If
        however the [47m:restrict[0m hint contains [47m(x subst1 subst2 ...)[0m,
        then this behavior will be modified by restricting [47ms[0m so that
        it must extend [47msubst1[0m; and if there is no such [47ms[0m, then [47ms[0m is
        restricted so that it must extend [47msubst2[0m; and so on, until
        the list of substitutions is exhausted.  If no such [47ms[0m is
        found, then the rewrite or definition rule named [47mx[0m is not
        applied to that term.  Finally, if [47mx[0m is an event name
        corresponding to one or more [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m
        [rune]s (that is, [47mx[0m is the ``base symbol'' of such [rune]s;
        see [rune]), say [rune]s [47mr1[0m, ... [47mrn[0m, then the meaning is the
        same except that [47m(x subst1 subst2 ...)[0m is replaced by [47m(ri
        subst1 subst2 ...)[0m for each [47mi[0m.  Once this replacement is
        complete, the hint may not contain two members whose [47m[car][0m is
        the same [rune].

        Note that the substitutions in [47m:restrict[0m hints refer to the variables
        actually appearing in the goals, not to the variables
        appearing in the rule being restricted.

        The following example, supplied by Mihir Mehta, illustrates the use
        of [47m:restrict[0m to handle free variables (in this case, a single
        free variable [47my[0m).  The call of [47m[thm][0m below fails without the
        indicated [47m:restrict[0m hint.

          (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))))))))

        Here is another example, this one supplied by Bishop Brock.  Suppose
        that the database includes the following rewrite rule, which
        is probably kept [disable]d.  (We ignore the question of how
        to prove this rule.)

          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))))))

        Then ACL2 can prove the following theorem (unless other rules get in
        the way), essentially by multiplying both sides by [47mx[0m.

          (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)))))))

        The [47m:restrict[0m hint above says that the variables [47mx[0m, [47my[0m, and [47mz[0m in the
        rewrite rule [47mcancel-<-*$free[0m above should be instantiated
        respectively by [47mx[0m, [47m(/ x)[0m, and [47m1[0m.  Thus [47m(< y z)[0m becomes [47m(< (/
        x) 1)[0m, and this inequality is replaced by the corresponding
        instance of the right-hand-side of [47mcancel-<-*$free[0m.  Since
        the current conjecture assumes [47m(< 1 x)[0m, that instance of the
        right-hand side simplifies to

          (< (* x (/ x)) (* x 1))

        which in turn simplifies to [47m(< 1 x)[0m, a hypothesis in the present
        theorem.

    [47m:rw-cache-state[0m

        [47mValue[0m is an element of the list constant [47m*legal-rw-cache-states*[0m:
        [47m:atom[0m (the default), [47mnil[0m, [47mt[0m, or [47m:disabled[0m.  This hint applies
        to the indicated goal and all its descendants, to set the
        so-called ``rw-cache-state'' to the indicated value; see
        [set-rw-cache-state].

    [47m:use[0m

        Examples of [47m:USE[0m hints are shown near the top of this documentation
        topic.

        [47mValue[0m is a [lemma-instance] or a true list of [lemma-instance]s,
        indicating that the propositions denoted by the instances be
        added as hypotheses to the specified goal: that is, the [47m:use[0m
        hint replaces a goal, [47mG[0m, by the new goal, [47m(IMPLIES P G)[0m,
        where [47mP[0m is the theorem specified by the (conjunction of the)
        lemma instances provided.  The [47m:instance[0m form of a
        [lemma-instance] permits you to instantiate the free
        variables of previously proved theorems any way you wish,
        even allowing for differences in [packages]; 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 [47m:by[0m (documented above).
        Sometimes [theories] are helpful when employing [47m:use[0m hints;
        see [minimal-theory].

        If the value is the name of a function symbol introduced by [47m[defun][0m,
        then the normalized (simplified) body of that definition is
        used; see [normalize].  This behavior differs from that
        provided by a [47m:by[0m hint, where the original body of the
        definition is used.


Subtopics

  [Computed-hints]
      Computing advice to the theorem proving process

  [Custom-keyword-hints]
      User-defined hints

  [Default-hints]
      A list of hints added to every proof attempt

  [Do-not]
      Instruct the theorem prover not to do certain things.

  [Goal-spec]
      To indicate where a hint is to be used

  [Guard-theorem]
      Use a previously-proved [guard] theorem

  [Guard-theorem-example]
      How to use a previously-proved [guard] theorem

  [Hints-and-the-waterfall]
      How [hints] fit into the ACL2 proof waterfall

  [Lemma-instance]
      An object denoting an instance of a theorem

  [Override-hints]
      A list of hints given priority in every proof attempt

  [Termination-theorem]
      Use a (functional instance of a) previously-proved measure theorem

  [Termination-theorem-example]
      How to use a previously-proved measure theorem

  [Using-computed-hints]
      How to use computed hints")
 (HINTS-AND-THE-WATERFALL
  (HINTS)
  "How [hints] fit into the ACL2 proof waterfall

  Below we describe the flow of an ACL2 proof attempt, with special
  attention to how [hints] are applied during a proof.  For most ACL2
  users, only one point is important to take away from this
  [documentation] topic: you may specify hints during a proof (see
  [hints]; perhaps also see [computed-hints] and see
  [default-hints]), and they can be expected to behave intuitively.
  See [the-method] for a summary of how to interact with the ACL2
  prover; see [introduction-to-the-theorem-prover] for a more
  detailed tutorial; and see [hints] for an introduction to ACL2
  hints, including detailed [documentation] for specific hint types.

  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 [47mbooks/hints/basic-tests.lisp[0m.

  First, we describe the ACL2 ``waterfall''.  Then, we describe how
  hints are handled by the waterfall.

  [31;1mThe Waterfall.[0m

  The ACL2 [3mwaterfall[0m 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 [3msteps[0m, 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.

  Each goal considered by the ACL2 prover passes through a series of
  proof processes, called the ``waterfall processes'', as stored in
  the constant [47m*preprocess-clause-ledge*[0m.  The top process applies
  top-level hints, including [47m:use[0m hints; the next is a lightweight
  ``preprocess'' simplifier for ``simple'' rules (see [simple]); that
  is followed by the main ACL2 simplifier and then the
  ``settled-down'' process described further below; and finally ACL2
  attempts (in this order) destructor elimination, fertilization
  (heuristic use of equalities), generalization, and elimination of
  irrelevance.  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.

  We next describe the two additional ways in which control can be
  returned to the top of the waterfall.

  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 [47m\"Goal\"[0m simplifies to [47m\"Subgoal 2\"[0m (among others), and
  [47m\"Subgoal 2\"[0m simplifies to [47m\"Subgoal 2.3\"[0m (among others), which in
  turn is not further simplified.  Then the ``settled-down'' process
  hits on [47m\"Subgoal 2.3\"[0m, but it does not hit not on any of its
  children or their children (and so on), because each of those has
  an ancestor, [47m\"Subgoal 2.3\"[0m, that has already been marked as
  ``settled-down''.

  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 [computed-hints], especially the
  discussion of [47mstable-under-simplificationp[0m), 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.

  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 ``[47mstable-under-simplificationp[0m'' case
  mentioned above.  We turn now to a more thorough discussion of how
  hints are selected and applied.

  [31;1mThe handling of hints.[0m

  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.

  When the theorem prover is called by [47m[thm][0m or [events] such as
  [47m[defthm][0m, [47m[defun][0m, and [47m[verify-guards][0m, it gathers up the hints
  that have been supplied, often provided as a [47m:[0m[47m[hints][0m argument, but
  for example using a [47m:guard-hints[0m argument for [guard] verification
  proofs.  (ACL2(r) users (see [real]) may also employ [47m:std-hints[0m.)
  It then appends these to the front of the list of default hints
  (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.

  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 [47mt[0m specified for [47m:computed-hint-replacement[0m, 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 [computed-hints]).  The selected
  hint is also used to update the hint settings, as described below.

  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 [47m\"Subgoal 3\"[0m includes [47m:in-theory
  (enable foo)[0m, then the hint settings are correspondingly updated
  when processing [47m\"Subgoal 3\"[0m, and they persist at subgoals such as
  [47m\"Subgoal 3.2\"[0m and [47m\"Subgoal 3.2.1\"[0m (unless overridden by hints on
  those goals); but the theory specifying [47mfoo[0m is not re-installed at
  every such subgoal.

  When a hint is selected, the list of hint settings is updated so that
  for each keyword [47m:kwd[0m and associated value [47mval[0m from the hint, [47m:kwd[0m
  is associated with [47mval[0m in the hint settings, discarding any
  previous association of [47m:kwd[0m with a value in the hint settings.
  Except, certain ``top-level'' hints are never saved in the hint
  settings: [47m:use[0m, [47m:cases[0m, [47m:by[0m, [47m:bdd[0m, [47m:or[0m, and [47m:clause-processor[0m.

  For example, suppose that we specify the following hints, with no
  default hints.

    ((\"Goal\" :expand ((bar x y)))
     (\"Subgoal 3\" :in-theory (enable foo)))

  These hints then become the initial list of pending hints.  When the
  proof attempt begins, the prover encounters the top-level goal
  ([47m\"Goal\"[0m) and pulls the [47m\"Goal\"[0m hint from the pending hints, so that
  the list of hint settings contains a value only for keyword
  [47m:expand[0m.  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 --- in other words, it will remain
  throughout the entire proof.  Now consider what happens when the
  proof reaches [47m\"Subgoal 3\"[0m.  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 [47m:in-theory[0m
  keyword with the theory represented by [47m(enable foo)[0m.  That theory
  is immediately installed until the prover finishes addressing
  [47m\"Subgoal 3\"[0m, its children, their children, and so on; and until
  that completion is reached, the [47m:in-theory[0m keyword remains
  associated with the [47m(enable foo)[0m in the hint settings, although of
  course there is no re-installation of the theory at any ensuing
  child goal.  When finally [47m\"Subgoal 3\"[0m and its descendants have been
  completed and the prover is about to consider [47m\"Subgoal 2\"[0m, the
  [47m:in-theory[0m association is removed from the hint settings and the
  global theory is re-installed.  However, the list of pending hints
  remains empty.

  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 [47m(goal-name :kwd1 val1
  ... :kwdn valn)[0m is suitable if [47mgoal-name[0m 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-[47mnil[0m value.  As indicated earlier
  in this documentation topic, an exception occurs when a computed
  hint is selected after simplification fails (the
  ``[47mstable-under-simplificationp[0m'' 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.

  The following slightly tricky example illustrates handling of hints.

    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.

  The warning above is printed because [47m\"Goal\"[0m is associated with two
  pending hints: one given by the [47m[set-default-hints][0m call and one
  supplied by the [47m:[0m[47m[hints][0m keyword of the [47m[thm][0m form.  The [47m:in-theory[0m
  hint is selected first because user-supplied hints are ahead of
  default hints in the list of pending hints; we then get the first
  ``Note'' 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
  ``settled-down'' process applies, as discussed above, immediately
  causing another trip through the waterfall.  Since the [47m:in-theory[0m
  hint was earlier removed from the list of pending hints when it was
  applied, the default ([47m:do-not[0m) hint is now the only pending hint.
  That hint is applied, resulting in the second ``Note'' above.

  Again, more examples may be found in the community book
  [47mbooks/hints/basic-tests.lisp[0m.  A particularly tricky but
  informative example in that book is the one related to
  [47mnonlinearp-default-hint[0m.

  Also see [override-hints] for an advanced feature that allows
  modification of the hint selected for a goal.")
 (HISTORY
  (ACL2)
  "Functions to display or change contents of the logical [world]

  ACL2 keeps track of the [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
  [47m:[0m[47m[pc][0m [47m:x[0m), or the preceding 10 commands (by issuing [47m:[0m[47m[pbt][0m [47m:x-10[0m),
  or the command that introduced a given function symbol, [47mfn[0m (by
  issuing [47m:pc fn[0m).  You can also undo back through some previous
  command (see [ubt]), restoring the logical [world] to what it was
  before the given command.

  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 [47m:[0m[47m[pc][0m.

  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 [documentation] entries of their
  own.  See [command], see [events], see [command-descriptor], and
  see [logical-name].


Subtopics

  [Command]
      Forms you type at the top-level, but...

  [Command-descriptor]
      An object describing a particular [command] typed by the user

  [Disable-ubt]
      Make it illegal to undo back through the current [command]

  [Enter-boot-strap-mode]
      The first millisecond of the Big Bang

  [Exit-boot-strap-mode]
      The end of pre-history

  [Extend-pe-table]
      Replace [events] displayed by [history] commands

  [Formula]
      The formula of a name or [rune]

  [Get-command-sequence]
      Return list of [command]s that are between two [command] descriptors

  [Gthm]
      The [guard] theorem for a given function symbol

  [Ld-history]
      Saving and querying command history

  [Oops]
      Undo a [47m:u[0m or [47m:[0m[47m[ubt][0m

  [Pbt]
      Print the [command]s back through a [command] descriptor

  [Pc]
      Print the [command] described by a [command] descriptor

  [Pcb]
      Print the [command] block described by a [command] descriptor

  [Pcb!]
      Print in full the [command] block described by a [command]
      descriptor

  [Pcs]
      Print the sequence of [command]s between two [command] descriptors

  [Pe]
      Print the events named by a logical name

  [Pe!]
      Print events as with [47m[pe][0m but ignoring the [pe-table]

  [Pf]
      Print the formula corresponding to the given name

  [Pl]
      Print the rules for the given name or term

  [Pl2]
      Print rule(s) for the given form

  [Pr]
      Print the rules stored by the event with the given name

  [Pr!]
      Print rules stored by the command with a given command descriptor

  [Puff]
      Replace a compound [command] by its immediate subevents

  [Puff*]
      Replace a compound [command] by its subevents

  [Reset-kill-ring]
      Save memory by resetting and perhaps resizing the kill ring used by
      [47m[oops][0m

  [Reset-prehistory]
      Reset the prehistory

  [Tau-database]
      To see the tau database as a (very large) object

  [Tthm]
      The [measure] (termination) theorem for a given function symbol

  [U]
      Undo last [command], without a query

  [Ubt]
      Undo the [command]s back through a [command] descriptor

  [Ubt!]
      Undo [command]s, without a query or an error

  [Ubt-prehistory]
      Undo the [command]s back through the last [47m[reset-prehistory][0m event

  [Ubt?]
      Undo [command]s, with queries as appropriate

  [Ubu]
      Undo the [command]s back up to (not including) a [command]
      descriptor

  [Ubu!]
      Undo [command]s, without a query or an error

  [Ubu?]
      Undo [command]s, with queries as appropriate

  [Undo]
      Undoing and perhaps redefining")
 (HONS
  (PROGRAMMING HONS-AND-MEMOIZATION ACL2-BUILT-INS)
  "[47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m.

  In the logic, [47mhons[0m is just [47m[cons][0m; we leave it enabled and would
  think it odd to ever prove a theorem about it.

  Under the hood, [47mhons[0m does whatever is necessary to ensure that its
  result is [normed].

  What might this involve?

  Since the car and cdr of any normed cons must be normed, we need to
  [47m[hons-copy][0m 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.

  After that, we need to check whether any normed cons equal to [47m(x . y)[0m
  already exists.  If so, we return it; otherwise, we need to
  construct a new cons for [47m(x . y)[0m and install it as the normed
  version of [47m(x . y)[0m.

  Generally speaking, these extra operations make [47mhons[0m much slower than
  [47mcons[0m, even when given normed arguments.

  [31;1mFunction: [0m<hons>

    (defun hons (x y)
      (declare (xargs :guard t))
      (cons x y))


Subtopics

  [Hons-clear]
      [47m(hons-clear gc)[0m is a drastic garbage collection mechanism that
      clears out the underlying Hons Space.

  [Hons-clear!]
      A version of [47m[hons-clear][0m for [parallel] execution

  [Hons-copy]
      [47m(hons-copy x)[0m returns a [normed] object that is equal to X.

  [Hons-copy-persistent]
      [47m(hons-copy-persistent x)[0m returns a [normed] object that is equal to
      X and which will be re-normed after any calls to [47m[hons-clear][0m.

  [Hons-equal]
      [47m(hons-equal x y)[0m is a recursive equality check that optimizes when
      parts of its arguments are [normed].

  [Hons-equal-lite]
      [47m(hons-equal-lite x y)[0m is a non-recursive equality check that
      optimizes if its arguments are [normed].

  [Hons-note]
      Notes about [hons], especially pertaining to expensive resizing
      operations

  [Hons-resize]
      [47m(hons-resize ...)[0m can be used to manually adjust the sizes of the
      hash tables that govern which ACL2 Objects are considered
      [normed].

  [Hons-summary]
      [47m(hons-summary)[0m prints basic information about the sizes of the
      tables in the current Hons Space.

  [Hons-wash]
      [47m(hons-wash)[0m is like [47m[gc$][0m but can also garbage collect [normed]
      objects (CCL and GCL Only).

  [Hons-wash!]
      A version of [47m[hons-wash][0m for [parallel] execution

  [Normed]
      Normed objects are ACL2 Objects that are \"canonical\" or \"unique\" in
      a certain sense.")
 (HONS-ACONS
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(hons-acons key val alist)[0m is the main way to create or extend
  [fast-alists].

  Logically, [47mhons-acons[0m is like [47m[acons][0m except that its guard does not
  require [47m[alistp][0m; we leave it enabled and would think it odd to
  ever prove a theorem about it.

  Under the hood, two things are done differently.  First, the key is
  copied with [47m[hons-copy][0m; 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 [47mhons-acons[0m.

  Hash Table Creation

  A new hash table is created by [47mhons-acons[0m whenever alist is an atom.
  Unlike ordinary [47macons[0m, 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.

  1.  As a size hint

  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.

  When a natural number is used as a fast alist's name, we interpret it
  as a size hint.  For example, [47m(hons-acons 'foo 'bar 1000)[0m 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.

  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.

  2.  As an alist name

  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:

  First, the name can be helpful in identifying fast alists that should
  have been freed, see [47m[fast-alist-summary][0m.

  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 [47m[hons-acons!][0m.

  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.

  [31;1mFunction: [0m<hons-acons>

    (defun hons-acons (key val alist)
      (declare (xargs :guard t))
      (cons (cons key val) alist))")
 (HONS-ACONS!
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(hons-acons! key val alist)[0m is an alternative to [47m[hons-acons][0m that
  produces [normed], fast alists.

  Logically, [47mhons-acons![0m is like [47m[acons][0m except that its guard does not
  require [47m[alistp][0m; we leave it enabled and would think it odd to
  ever prove a theorem about it.

  Ordinarily, [fast-alists] are constructed with [47m[hons-acons][0m instead
  of [47mhons-acons![0m.  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:

    (hons-acons key val alist) == (cons (cons (hons-copy key) val) alist)

  In contrast, when [47mhons-acons![0m is used, the conses making up the alist
  itself are also normed.  That is,

    (hons-acons! key val alist) == (hons (hons key val) alist)

  Generally, you [31;1mshould not use[0m [47mhons-acons![0m unless you really know what
  you're doing.

  Drawback 1.  [47mhons-acons![0m requires you to [47m[hons-copy][0m all of the
  values that are being stored in the fast alist.  If you are storing
  large values, this may be expensive.

  Drawback 2.  It can be more difficult to maintain the proper
  discipline when using [47mhons-acons![0m.  For instance, consider the
  following:

    (let ((al1 (hons-acons 1 'one (hons-acons 2 'two nil)))
          (al2 (hons-acons 1 'one (hons-acons 2 'two nil))))
       ...)

  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 [47mhons-acons![0m, then since both al1 and al2 are
  equal, normed conses, they will literally be [47m[eq][0m and hence will
  refer to precisely the same hash table.  In other words,
  [47mhons-acons![0m makes it relatively easy to [31;1minadvertently[0m steal the
  hash table associated with some other fast alist.  This problem can
  be alleviated somewhat by uniquely naming alists; see the
  discussion in [47m[hons-acons][0m for details.

  Despite these drawbacks, [47mhons-acons![0m is the typical way to generate a
  fast alist that is normed (but also, for example, see
  [fast-alist-fork!]).  It is not adequate to [47m[hons-copy][0m a fast
  alist that was generated by ordinary [47m[hons-acons][0m 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.

  [31;1mFunction: [0m<hons-acons!>

    (defun hons-acons! (key val alist)
      (declare (xargs :guard t))
      (cons (cons key val) alist))")
 (HONS-AND-MEMOIZATION
  (ACL2)
  "Hash cons, function memoization, and applicative hash tables

  This topic describes the hash cons, function memoization, and
  applicative hash tables features available in ACL2, sometimes
  called the ``[hons-enabled]'' features.

  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.

  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 ``[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.

  Power users who want to take advantage of the [hons-enabled] features
  of ACL2 might find it helpful to consult the document
  [47mcentaur/README.html[0m in the ACL2 community books.

  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.

  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
  [47m[cons][0m function.  In Common Lisp, [47mcons[0m is guaranteed to provide a
  new pair, distinct from any previously created pair.  We have
  defined a new ACL2 function [47m[hons][0m that is logically identical to
  the ACL2 [47mcons[0m 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 [47mhons[0m ACL2 searches for an existing identical
  pair before allocating a new pair; this operation been called
  ``hash consing''.

  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.

  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.

  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.

  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.

  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.

  We recommend that users focus at first on the logical definitions of
  [47m[hons][0m 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 [47m[hons][0m and function memoization.
  For a more detailed description of these tools, please see the ACL2
  2006 workshop paper mentioned above.

  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.

    (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))))))

  Below we show how the ACL2 [47m[time$][0m utility can measure the time to
  execute a call to the [47mfib[0m function (with some editing to avoid
  noise from the underlying Common Lisp implementation).  [47m[Memoize][0m
  is actually an ACL2 macro that expands to a call of the ACL2
  function used to identify a function for memoization; 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 [guard]
  of the memoized function is satisfied, then this instance will
  execute without error.

    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)

  We see that once the function [47mfib[0m is identified as a function for
  which function calls should be memoized, the execution times are
  substantially reduced.  Finally, we can prevent [47mfib[0m from being
  further memoized; in fact, [47m[unmemoize][0m erases the previously
  memoized values.

  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.

  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.

  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 [47m[hons][0m operation as
  does the fast association list operation mechanism.  Each time [47mhons[0m
  is invoked, its arguments are themselves converted, if necessary,
  to uniquely represented objects.

  The ACL2 universe is recursively closed under the [47mcons[0m pairing
  operation and the atoms.  Hash consing ([47m[hons][0m) is logically
  identical to [47mcons[0m, but a set of tables is used to record each [47mhons[0m
  pair.  When a [47mhons[0m 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 [47mhons[0m has a unique
  representation, as does every subcomponent.  We also arrange for
  strings to have a unique representation --- only one copy of each
  different string is kept --- and when any previously unseen string
  is an argument to [47mhons[0m, 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.

  The definition of [47m[hons][0m in no way changes the operation of [47mcons[0m ---
  [47mhons[0m creates a [47mcons[0m pair.  When asked to create a [47mhons[0m, the
  implementation checks to see if there is a [47mcons[0m with the same [47m[car][0m
  and [47m[cdr][0m as the [47mhons[0m being requested.  Thus, the only difference
  between the results of a [47mhons[0m call and a corresponding [47mcons[0m call is
  a notation in some invisible (to the ACL2 logic) tables where we
  record which [47mcons[0m elements are also [47mhons[0m elements.  Since a [47mhons[0m is
  nothing but a [47mcons[0m, the operation of [47mcar[0m and [47mcdr[0m is unchanged.  In
  fact, the implementation is designed so that at any time it is safe
  to clear the table identifying which [47mcons[0m elements are also
  considered [47mhons[0m elements.

  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
  [47mhons[0m 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.

  We next discuss the fast lookup operation for association lists.
  When a pair is added to an association list using the functions
  [47m[hons-acons][0m or [47m[hons-acons!][0m, 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 [47m[hons-get][0m 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
  [47m[compress1][0m function is analogous to the functions
  [47m[fast-alist-clean][0m and [47m[fast-alist-clean!][0m.  There are user-level
  ACL2 functions that allow the associated hash tables to be cleared
  and removed.

  As mentioned above, the [hons-enabled] features are optimized for CCL
  and GCL.  See [ccl-updates] for easy instructions for obtaining the
  latest version of CCL.

  REFERENCES

  Baker, Henry G., The Boyer Benchmark at Warp Speed. ACM Lisp Pointers
  V,3 (Jul-Sep 1992), pages 13-14.

  Baker, Henry G., A Tachy 'TAK'.  ACM Lisp Pointers Volume 3,
  July-September, 1992, pages 22-23.

  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.

  L.P. Deutsch. An Interactive Program Verifier. Tech. Rept. CSL-73-1,
  Xerox Palo Alto Research Center, May, 1973.

  A. P. Ershov.  On Programming of Arithmetic Operations.  In the
  Communications of the ACM, Volume 118, Number 3, August, 1958,
  pages 427-430.

  Eiichi Goto, Monocopy and Associative Algorithms in Extended Lisp,
  TR-74-03, University of Tokyo, 1974.

  Richard P. Gabriel.  Performance and Evaluation of Lisp Systems.  MIT
  Press, 1985.

  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.

  Donald Michie.  Memo Functions and Machine Learning.  In Nature,
  Volume 218, 1968, pages 19-22.


Subtopics

  [Fast-alists]
      Alists with hidden hash tables for faster execution

  [Hons]
      [47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m.

  [Hons-enabled]
      Hash cons, function memoization, and applicative hash tables

  [Memoize]
      Turn on memoization for a specified function

  [Number-subtrees]
      [47m(number-subtrees x)[0m returns the number of distinct subtrees of X, in
      the sense of [47m[equal][0m

  [Unmemoize]
      Turn off memoization for the specified function")
 (HONS-ASSOC-EQUAL
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(hons-assoc-equal key alist)[0m is [31;1mnot fast[0m; it serves as the logical
  definition for [47m[hons-get][0m.

  The definition of [47mhons-assoc-equal[0m is similar to that of
  [47m[assoc-equal][0m, except that (1) it does not require [47m[alistp][0m as a
  guard, and (2) it \"skips over\" any non-conses when its alist
  argument is malformed.

  We typically leave [47mhons-get[0m enabled and reason about [47mhons-assoc-equal[0m
  instead.  One benefit of this approach is that it avoids certain
  \"false\" discipline warnings that might arise from execution during
  theorem proving.

  [31;1mFunction: [0m<hons-assoc-equal>

    (defun hons-assoc-equal (key alist)
      (declare (xargs :guard t))
      (cond ((atom alist) nil)
            ((and (consp (car alist))
                  (hons-equal key (caar alist)))
             (car alist))
            (t (hons-assoc-equal key (cdr alist)))))")
 (HONS-CLEAR
  (HONS ACL2-BUILT-INS)
  "[47m(hons-clear gc)[0m is a drastic garbage collection mechanism that clears
  out the underlying Hons Space.

  Logically, [47mhons-clear[0m just returns nil; we leave it enabled and would
  think it odd to ever prove a theorem about it.

  Under the hood, [47mhons-clear[0m brutally (1) clears all the tables that
  govern which conses are [normed], then (2) optionally garbage
  collects, per the [47mgc[0m argument, then finally (3) re-norms the keys
  of [47m[fast-alists][0m and persistently normed conses; see
  [hons-copy-persistent].

  Notes.

    * The hash tables making up the Hons Space retain their sizes after
      being cleared.  If you want to shrink them, see [47m[hons-resize][0m.

    * CCL and GCL users might prefer [47m[hons-wash][0m, which is relatively
      efficient and allows for the garbage collection of normed
      conses without impacting their normed status.

    * 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.

    * (For ACL2(p) users only; see [parallelism]) If parallel execution is
      enabled (see [set-parallel-execution]), as it is by default in
      ACL2(p), then [47mhons-clear[0m 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 [47m[hons-clear!][0m, which however requires a
      [trust-tag].

  [31;1mFunction: [0m<hons-clear>

    (defun hons-clear (gc)
      (declare (xargs :guard t))
      (declare (ignore gc))
      nil)")
 (HONS-CLEAR!
  (HONS ACL2-BUILT-INS)
  "A version of [47m[hons-clear][0m for [parallel] execution

  This function is only of interest to ACL2(p) users; see
  [parallelism], because for ACL2 it suffices to use [47m[hons-clear][0m.
  However, if parallel execution is enabled (see
  [set-parallel-execution]), as it is by default in ACL2(p), then
  [47mhons-clear[0m 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 [47mhons-clear[0m
  directly in the top-level loop, you can use [47mhons-clear![0m, which does
  not check for parallelism violations.  However, [47mhons-clear![0m
  requires a trust tag; see [defttag].")
 (HONS-COPY
  (HONS ACL2-BUILT-INS)
  "[47m(hons-copy x)[0m returns a [normed] object that is equal to X.

  In the logic, [47mhons-copy[0m is just the identity function; we leave it
  enabled and would think it odd to ever prove a theorem about it.

  Under the hood, [47mhons-copy[0m does whatever is necessary to produce a
  [normed] version of X.

  What might this involve?

  If X is a symbol, character, or number, then it is already normed and
  nothing is done.

  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 [47m[equal][0m to X.

  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.

  Note that running [47mhons-copy[0m on an object that was created with [47m[cons][0m
  is often slower than just using [47m[hons][0m directly when constructing
  the object.

  [31;1mFunction: [0m<hons-copy>

    (defun hons-copy (x)
      (declare (xargs :guard t))
      x)")
 (HONS-COPY-PERSISTENT
  (HONS ACL2-BUILT-INS)
  "[47m(hons-copy-persistent x)[0m returns a [normed] object that is equal to X
  and which will be re-normed after any calls to [47m[hons-clear][0m.

  Logically [47mhons-copy-persistent[0m is the identity; we leave it enabled
  and would think it odd to ever prove a theorem about it.

  Under the hood, [47mhons-copy-persistent[0m is virtually identical to
  [47m[hons-copy][0m.

  The only difference is that when [47m[hons-clear][0m is used, any
  persistently normed conses are automatically re-normed, and this
  re-norming can be carried out more efficiently than, say, an
  ordinary [47m[hons-copy][0m.

  [31;1mFunction: [0m<hons-copy-persistent>

    (defun hons-copy-persistent (x)
      (declare (xargs :guard t))
      x)")
 (HONS-ENABLED
  (HONS-AND-MEMOIZATION)
  "Hash cons, function memoization, and applicative hash tables

  ACL2 supports hash cons, function memoization, and applicative hash
  tables; see [hons-and-memoization].  These are sometimes called the
  ``hons-enabled features'' of ACL2.")
 (HONS-EQUAL
  (HONS EQUAL ACL2-BUILT-INS)
  "[47m(hons-equal x y)[0m is a recursive equality check that optimizes when
  parts of its arguments are [normed].

  In the logic, [47mhons-equal[0m is just [47m[equal][0m; we leave it enabled and
  would think it odd to ever prove a theorem about it.

  Under the hood, when [47mhons-equal[0m encounters two arguments that are
  both normed, it becomes a mere [47m[eql][0m check, and hence avoids the
  overhead of recursively checking large cons structures for
  equality.

  Note.  If [47mhons-equal[0m is given arguments that do not contain many
  normed objects, it can actually be much slower than [47m[equal][0m!  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 [hons-equal-lite], which only checks at the
  top level whether its arguments are normed.

  [31;1mFunction: [0m<hons-equal>

    (defun hons-equal (x y)
      (declare (xargs :guard t))
      (equal x y))


Subtopics

  [Hons-equal-lite]
      [47m(hons-equal-lite x y)[0m is a non-recursive equality check that
      optimizes if its arguments are [normed].")
 (HONS-EQUAL-LITE
  (HONS HONS-EQUAL)
  "[47m(hons-equal-lite x y)[0m is a non-recursive equality check that
  optimizes if its arguments are [normed].

  In the logic, [47mhons-equal-lite[0m is just [47m[equal][0m; we leave it enabled
  and would think it odd to ever prove a theorem about it.

  Under the hood, [47mhons-equal-lite[0m checks whether its arguments are
  normed, and if so it effectively becomes a [47m[eql][0m check.  Otherwise,
  it immediately calls [47m[equal][0m to determine if its arguments are
  equal.

  The idea here is to strike a useful balance between [47mequal[0m and
  [47m[hons-equal][0m.  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 [47mequal[0m do its work, without the extra overhead of
  recursively checking whether the subtrees of x and y are normed.

  [31;1mFunction: [0m<hons-equal-lite>

    (defun hons-equal-lite (x y)
      (declare (xargs :guard t))
      (equal x y))")
 (HONS-GET
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(hons-get key alist)[0m is the efficient lookup operation for
  [fast-alists].

  Logically, [47mhons-get[0m is just an alias for [47m[hons-assoc-equal][0m; we
  typically leave it enabled and prefer to reason about
  [47mhons-assoc-equal[0m instead.  One benefit of this approach is that it
  helps to avoids \"false\" discipline warnings that might arise from
  execution during theorem proving.

  Under the hood, when [47malist[0m is a fast alist that is associated with a
  valid hash table, [47mhons-get[0m first norms [47mkey[0m using [47m[hons-copy][0m, then
  becomes a [47mgethash[0m operation on the hidden hash table.  Otherwise
  [47mhons-get[0m simply invokes [47m[hons-assoc-equal][0m, which is similar (in
  definition and in performance) to [47m[assoc-equal][0m, on [47mkey[0m and [47malist[0m.

  [31;1mFunction: [0m<hons-get>

    (defun hons-get (key alist)
      (declare (xargs :guard t))
      (hons-assoc-equal key alist))")
 (HONS-NOTE
  (HONS)
  "Notes about [hons], especially pertaining to expensive resizing
  operations

  Certain ``Hons-Notes'' are printed to the terminal to report
  implementation-level information about the management of [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
  [47mbooks/centaur/ubdds/[0m), variable ordering can make a big
  difference.)

  By way of background:

      The ADDR-HT is the main hash table that lets us look up [normed]
      conses, i.e., [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!)

      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:

      (1) allocate a new, bigger array
      (2) rehash elements, copying them into the new array
      (3) free the old array

      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.

      Since resizing a hash table is expensive, we want to avoid it.
      There's a [47m[hons-resize][0m command for this.  You may want your
      books to start with something like the following.

        (value-triple (set-max-mem (* 30 (expt 2 30))))      ; 30 GB heap
        (value-triple (hons-resize :addr-ht #u_100_000_000)) ; 100M honses

      Basically, if you roughly know how many honses your book will need,
      you can just get them up front and then never to resize.

  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 [47m[hons-resize][0m command had too small of an ADDR-HT
  size, or might suggest that your book should have a [47m[hons-resize][0m
  command.  There are also commands like [47m([0m[47m[hons-summary][0m[47m)[0m,
  [set-max-mem], and defined in community book
  [47mbooks/centaur/misc/memory-mgmt-logic.lisp[0m, [47m(hons-analyze-memory
  nil)[0m.  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 [47m[hons-summary][0m at the end of a book, to get an idea of
  how many honses you should ask for in your [47m[hons-resize][0m command).")
 (HONS-RESIZE
  (HONS ACL2-BUILT-INS)
  "[47m(hons-resize ...)[0m can be used to manually adjust the sizes of the
  hash tables that govern which ACL2 Objects are considered [normed].

  General form:

    (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])

  Example:

    (hons-resize :str-ht 100000
                 :addr-ht (expt 2 27))

  Logically, [47mhons-resize[0m just returns nil; we leave it enabled and
  would think it odd to ever prove a theorem about it.

  Under the hood, [47mhons-resize[0m can be used to change the sizes of
  certain hash tables in the Hons Space.

  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.

  You may wish to call this function for two reasons.

  1.  Improving Performance by Resizing Up

  Since the hash tables in the Hons Space automatically grow as new
  objects are normed, [47mhons-resize[0m 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 [47mhons-resize[0m to pick a more appropriate initial
  size may help to reduce this overhead.

  2.  Reducing Memory Usage by Resizing Down

  Resizing can also be used to shrink the hash tables.  This might
  possibly be useful immediately after a [47m[hons-clear][0m to free up
  memory taken by the hash tables themselves.  (Of course, the tables
  will grow again as you create new normed objects.)

  Advice for using [47mhons-resize[0m.

  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.\"

  Note that the [47m[hons-summary][0m 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 [47mhons-resize[0m.

  Note that [47mhons-resize[0m 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
  [47m[hons-clear][0m.")
 (HONS-SHRINK-ALIST
  (FAST-ALIST-FORK ACL2-BUILT-INS)
  "Deprecated feature

  Deprecated.  Alias for [47m[fast-alist-fork][0m.")
 (HONS-SHRINK-ALIST!
  (FAST-ALIST-FORK! ACL2-BUILT-INS)
  "Deprecated feature

  Deprecated.  Alias for [47m[fast-alist-fork!][0m.")
 (HONS-SUMMARY
  (HONS ACL2-BUILT-INS)
  "[47m(hons-summary)[0m prints basic information about the sizes of the tables
  in the current Hons Space.

  Logically, [47mhons-summary[0m just returns nil; we leave it enabled and
  would think it odd to ever prove a theorem about it.

  Under the hood, this function gathers and prints some basic
  information about the sizes of the tables in the Hons Space.

  This information may be useful for deciding if you want to garbage
  collect using functions such as [47m[hons-clear][0m or [47m[hons-wash][0m.  It
  may also be useful for determining good initial sizes for the Hons
  Space hash tables for your particular computation; see
  [hons-resize].  For information about [fast-alists], see
  [fast-alist-summary].

  [31;1mFunction: [0m<hons-summary>

    (defun hons-summary nil
      (declare (xargs :guard t))
      nil)")
 (HONS-WASH
  (HONS ACL2-BUILT-INS)
  "[47m(hons-wash)[0m is like [47m[gc$][0m but can also garbage collect [normed]
  objects (CCL and GCL Only).

  Logically, [47mhons-wash[0m just returns nil; we leave it enabled and would
  think it odd to ever prove a theorem about it.

  Under the hood, in CCL and GCL, [47mhons-wash[0m runs a garbage collection
  after taking special measures to allow normed conses to be
  collected.  In Lisps other than CCL, [47mhons-wash[0m does nothing.  This
  is because the efficient implementation of [47mhons-wash[0m is specific to
  the \"static honsing\" scheme which requires CCL-specific features.

  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,
  [47mhons-wash[0m (1) clears out these pointers, (2) runs a garbage
  collection, then (3) re-norms any previously-normed conses which
  have survived the garbage collection.

  Notes.

    * 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.

    * (For ACL2(p) users only; see [parallelism]) If parallel execution is
      enabled (see [set-parallel-execution]), as it is by default in
      ACL2(p), then [47mhons-wash[0m 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 [47m[hons-wash!][0m, which however requires a
      [trust-tag].

  [31;1mFunction: [0m<hons-wash>

    (defun hons-wash nil
      (declare (xargs :guard t))
      nil)")
 (HONS-WASH!
  (HONS ACL2-BUILT-INS)
  "A version of [47m[hons-wash][0m for [parallel] execution

  This function is only of interest to ACL2(p) users; see
  [parallelism], because for ACL2 it suffices to use [47m[hons-wash][0m.
  However, if parallel execution is enabled (see
  [set-parallel-execution]), as it is by default in ACL2(p), then
  [47mhons-wash[0m 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 [47mhons-wash[0m directly
  in the top-level loop, you can use [47mhons-wash![0m, which does not check
  for parallelism violations.  However, [47mhons-wash![0m requires a trust
  tag; see [defttag].")
 (HOW_LONG_DOES_IT_TAKE_TO_BECOME_AN_EFFECTIVE_USER{Q}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "How Long Does It Take to Become an Effective User?

  {IMAGE} (see [Other_Requirements])

  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.

  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.''

  {IMAGE} (see [Other_Requirements])")
 (HOW_TO_FIND_OUT_ABOUT_ACL2_FUNCTIONS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "How To Find Out about ACL2 Functions

  {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions_{cont}])

  Most ACL2 primitives are documented.  Here is the definition of [47mapp[0m
  again, with the documented topics highlighted.  {ICON} (see
  [A_Tiny_Warning_Sign]) All of the links below lead into the ACL2
  User's Manual.  So follow these links if you wish, but use your
  [31;1mBack Button[0m to return here!

    ([defun] app (x y)
      ([cond] (([endp] x) y)
            (t ([cons] ([car] x)
                     (app ([cdr] x) y)))))

  By following the link on [endp] {ICON} (see [A_Tiny_Warning_Sign]) we
  see that it is a Common Lisp function and is defined to be the same
  as [atom] {ICON} (see [A_Tiny_Warning_Sign]), which recognizes
  non-conses.  But [47mendp[0m has a guard.  Since we are ignoring guards
  for now, we'll ignore the guard issue on [47mendp[0m.

  So this definition reads ``to [47mapp[0m [47mx[0m and [47my[0m: if [47mx[0m is an atom, return [47my[0m;
  otherwise, [47mapp[0m [47m(cdr x)[0m and [47my[0m and then cons [47m(car x)[0m onto that.''

  {IMAGE} (see [How_To_Find_Out_about_ACL2_Functions_{cont}])")
 (HOW_TO_FIND_OUT_ABOUT_ACL2_FUNCTIONS_{CONT}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "How To Find Out about ACL2 Functions (cont)

  {IMAGE} (see [The_Admission_of_App])

  The ACL2 documentation is also available in Emacs, via the ACL2-Doc
  browser (see [ACL2-Doc]) {ICON} (see [A_Tiny_Warning_Sign]),
  allowing you to explore the hyperlinked documentation in the
  comfort of a text editor that can also interact with ACL2.

  In addition, runtime images of ACL2 have the hyperlinked text as a
  large ACL2 data structure that can be explored with ACL2's [31;1m:doc[0m
  command.  If you have ACL2 running, try the command [31;1m:doc endp[0m.

  Another way to find out about ACL2 functions, if you have an ACL2
  image available, is to use the command [47m:[0m[47m[args][0m {ICON} (see
  [A_Tiny_Warning_Sign]) which prints the formals, type, and guard of
  a function symbol.

  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.

  Now let's continue with [47mapp[0m.

  {IMAGE} (see [The_Admission_of_App])")
 (I-AM-HERE
  (LD)
  "A convenient marker for use with [47m[rebuild][0m or [47m[ld][0m

    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 ???
    ...

  By putting an [47m(i-am-here)[0m form at the ``frontier'' of an evolving
  file of [command]s, you can use [47m[rebuild][0m to load the file up to
  the [47m(i-am-here)[0m.  [47mI-am-here[0m simply returns an [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 [47m(i-am-here)[0m
  need not be machine readable.")
 (I-CLOSE
  (REAL)
  "ACL2(r) test for whether two numbers are infinitesimally close

  [47m(I-close x y)[0m is true if and only if [47mx-y[0m is an infinitesimal number.
  This predicate is only defined in ACL2(r) (see [real]).")
 (I-LARGE
  (REAL)
  "ACL2(r) recognizer for infinitely large numbers

  [47m(I-large x)[0m is true if and only if [47mx[0m is non-zero and [47m1/x[0m is an
  infinitesimal number.  This predicate is only defined in ACL2(r)
  (see [real]).")
 (I-LIMITED
  (REAL)
  "ACL2(r) recognizer for limited numbers

  [47m(I-limited x)[0m is true if and only if [47mx[0m is a number that is not
  infinitely large.  This predicate is only defined in ACL2(r) (see
  [real]).")
 (I-SMALL
  (REAL)
  "ACL2(r) recognizer for infinitesimal numbers

  [47m(I-small x)[0m is true if and only if [47mx[0m is an infinitesimal number
  (possibly 0).  This predicate is only defined in ACL2(r) (see
  [real]).")
 (IDENTITY
  (BASICS ACL2-BUILT-INS)
  "The identity function

  [47m(Identity x)[0m equals [47mx[0m; what else can we say?

  [47mIdentity[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<identity>

    (defun identity (x)
      (declare (xargs :guard t))
      x)")
 (IF
  (BASICS ACL2-BUILT-INS)
  "If-then-else function

  [47m(if x y z)[0m is equal to [47my[0m if [47mx[0m is any value other than [47mnil[0m, and is
  equal to [47mz[0m if [47mx[0m is [47mnil[0m.

  Only one of [47my[0m, [47mz[0m is evaluated when [47m(if x y z)[0m is evaluated.

  [47mIf[0m has a [guard] of [47mt[0m.

  [47mIf[0m is part of Common Lisp.  See any Common Lisp documentation for
  more information."
)
 (IF*
  (BDD)
  "For conditional rewriting with BDDs

  The function [47mIF*[0m is defined to be [47m[if][0m, but it is used in a special
  way by ACL2's [bdd] package.

  [31;1mFunction: [0m<if*>

    (defun if* (x y z) (if x y z))

  As explained elsewhere (see [bdd-algorithm]), ACL2's [bdd] algorithm
  gives special treatment to [term]s of the form [47m(IF* TEST TBR FBR)[0m.
  In such cases, the algorithm simplifies [47mTEST[0m first, and the result
  of that simplification must be a constant (normally [47mt[0m or [47mnil[0m, but
  any non-[47mnil[0m explicit value is treated like [47mt[0m here).  Otherwise, the
  algorithm aborts.

  Thus, [47mIF*[0m may be used to implement a sort of conditional rewriting
  for ACL2's [bdd] package, even though this package only nominally
  supports unconditional rewriting.  The following contrived example
  should make this point clear.

  Suppose that we want to prove that [47m(nthcdr (length x) (append x y))[0m
  is equal to [47my[0m, but that we would be happy to prove this only for
  lists having length 4.  We can state such a theorem as follows.

    (let ((x (list x0 x1 x2 x3)))
      (equal (nthcdr (length x) (append x y))
             y))

  If we want to prove this formula with a [47m:[0m[47m[bdd][0m hint, then we need to
  have appropriate rewrite rules around.  First, note that [47mLENGTH[0m is
  defined as follows (try [47m:[0m[47m[pe][0m [47m[length][0m):

    (length x)
     =
    (if (stringp x)
        (len (coerce x 'list))
        (len x))

  Since [bdd]-based rewriting is merely very simple unconditional
  rewriting (see [bdd-algorithm]), we expect to have to prove a rule
  reducing [47m[stringp][0m of a [47m[cons][0m:

    (defthm stringp-cons
      (equal (stringp (cons x y))
             nil))

  Now we need a rule to compute the [47mLEN[0m of [47mX[0m, because the definition of
  [47mLEN[0m is recursive and hence not used by the [bdd] package.

    (defthm len-cons
      (equal (len (cons a x))
             (1+ (len x))))

  We imagine this rule simplifying [47m(LEN (LIST X0 X1 X2 X3))[0m in terms of
  [47m(LEN (LIST X1 X2 X3))[0m, and so on, and then finally [47m(LEN nil)[0m should
  be computed by execution (see [bdd-algorithm]).

  We also need to imagine simplifying [47m(APPEND X Y)[0m, where still [47mX[0m is
  bound to [47m(LIST X0 X1 X2 X3)[0m.  The following two rules suffice for
  this purpose (but are needed, since [47m[append][0m, actually
  [47m[binary-append][0m, is recursive).

    (defthm append-cons
      (equal (append (cons a x) y)
             (cons a (append x y))))

    (defthm append-nil
      (equal (append nil x)
             x))

  Finally, we imagine needing to simplify calls of [47m[nthcdr][0m, where the
  first argument is a number (initially, the length of [47m(LIST X0 X1 X2
  X3)[0m, 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.)

    (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)))))

  The problem with this rule is that its hypothesis makes it a
  conditional [rewrite] rule, and conditional rewrite rules are not
  used by the [bdd] package.  (See [bdd-algorithm] for a discussion
  of ``BDD rules.'') (Note that the hypothesis cannot simply be
  removed; the resulting formula would be false for [47mn = -1[0m and [47mx =
  '(a)[0m, for example.)  We can solve this problem by using [47mIF*[0m, as
  follows; comments follow.

    (defthm nthcdr-add1
      (equal (nthcdr (+ 1 n) x)
             (if* (zp (1+ n))
                  x
                  (nthcdr n (cdr x)))))

  How is [47mnthcdr-add1[0m applied by the [bdd] package?  Suppose that the
  [bdd] computation encounters a [term] of the form [47m(NTHCDR (+ 1 N)
  X)[0m.  Then the [bdd] package will apply the [rewrite] rule
  [47mnthcdr-add1[0m.  The first thing it will do when attempting to
  simplify the right hand side of that rule is to attempt to simplify
  the term [47m(ZP (1+ N))[0m.  If [47mN[0m is an explicit number (which is the
  case in the scenario we envision), this test will reduce (assuming
  the executable-counterparts of [47m[zp][0m and [47m[binary-+][0m are [enable]d)
  to [47mt[0m or to [47mnil[0m.  In fact, the lemmas above (not including the lemma
  [47mnthcdr-add1-conditional[0m) suffice to prove our goal:

    (thm (let ((x (list x0 x1 x2 x3)))
           (equal (nthcdr (length x) (append x y))
                  y))
         :hints ((\"Goal\" :bdd (:vars nil))))

  If we execute the following form that disables the definition and
  executable-counterpart of the function [47m[zp][0m

    (in-theory (disable zp (zp)))

  before attempting the proof of the theorem above, we can see more
  clearly the point of using [47mIF*[0m.  In this case, the prover makes the
  following report.

    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.

  If we follow the advice above, we can see rather clearly what
  happened.  See [show-bdd].

    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 !>

  Each of these term-alist pairs led to the next, and the test of the
  last one, namely [47m(ZP (+ 1 N))[0m where [47mN[0m is bound to [47m3[0m, was not
  simplified to [47mt[0m or to [47mnil[0m.

  What would have happened if we had used [47m[if][0m in place of [47mIF*[0m in the
  rule [47mnthcdr-add1[0m?  In that case, if [47mZP[0m and its
  [executable-counterpart] were disabled then we would be put into an
  infinite loop!  For, each time a term of the form [47m(NTHCDR k V)[0m is
  encountered by the BDD package (where k is an explicit number), it
  will be rewritten in terms of [47m(NTHCDR k-1 (CDR V))[0m.  We would
  prefer that if for some reason the term [47m(ZP (+ 1 N))[0m cannot be
  decided to be [47mt[0m or to be [47mnil[0m, then the BDD computation should
  simply abort.

  Even if there were no infinite loop, this kind of use of [47mIF*[0m is
  useful in order to provide feedback of the form shown above
  whenever the test of an [47mIF[0m term fails to simplify to [47mt[0m or to [47mnil[0m.")
 (IF-INTRO (POINTERS) "See [splitter].")
 (IFF
  (BASICS ACL2-BUILT-INS)
  "Logical ``if and only if''

  [47mIff[0m is the ACL2 biconditional, ``if and only if''.  [47m(iff P Q)[0m means
  that either [47mP[0m and [47mQ[0m are both false (i.e., [47mnil[0m) or both true (i.e.,
  not [47mnil[0m).

  [31;1mFunction: [0m<iff>

    (defun iff (p q)
      (declare (xargs :guard t))
      (if p (if q t nil) (if q nil t)))")
 (IFIX
  (NUMBERS ACL2-BUILT-INS)
  "Coerce to an integer

  [47mIfix[0m simply returns any integer argument unchanged, returning [47m0[0m on a
  non-integer argument.  Also see [nfix], see [rfix], see [realfix]
  and see [fix] for analogous functions that coerce to a natural
  number, a rational number, a real, and a number, respectively.

  [47mIfix[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<ifix>

    (defun ifix (x)
      (declare (xargs :guard t))
      (if (integerp x) x 0))")
 (IGNORABLE (POINTERS) "See [declare].")
 (IGNORE (POINTERS) "See [declare].")
 (IGNORED-ATTACHMENT
  (DEFATTACH DEFCONST DEFMACRO DEFPKG)
  "Why attachments are sometimes not used

  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
  [defattach].

  We illustrate this issue with the following example, discussed below.

    (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))
     )

  Here, a non-executable function [47mfoo[0m is introduced with no
  constraints, and is provided two contradictory implementations,
  [47mfoo-impl-1[0m and [47mfoo-impl-2[0m.  A function, [47mbar[0m, is defined using a
  macro, [47mmac[0m, whose expansion depends on which of [47mfoo-impl-1[0m or
  [47mfoo-impl-2[0m is attached to [47mfoo[0m.  If ACL2 were to allow this, then as
  indicated by the comments above, [47m(bar)[0m would be defined to be [47mnil[0m
  on the first pass of the [47m[encapsulate][0m form, where [47mfoo[0m is attached
  to [47mfoo-impl-2[0m; but [47m(bar)[0m would be defined to be [47mt[0m on the second
  pass, where [47mfoo[0m is attached to [47mfoo-impl-1[0m because the second
  [47m[defattach][0m call is [47m[local][0m.  Thus, after execution of the
  [47mencapsulate[0m form, [47m(bar)[0m would be provably equal to [47mt[0m even though
  there would be a theorem, [47mbar-is-nil[0m --- proved during the first
  pass of the [47mencapsulate[0m --- saying that [47m(bar)[0m is [47mnil[0m!

  Fortunately, ACL2 does not permit this to happen.  The example above
  produces the following output.

    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.

  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.

  We conclude with an example illustrating how [47m[make-event][0m can be used
  to work around the refusal of ACL2 to use attachments during
  macroexpansion.  The idea is that [47m[make-event][0m expansions are
  stored, and this avoids the issue of [47m[local][0m attachments.  In
  particular, for the example below, the second [47m[defattach][0m affects
  the body of [47mf2[0m even though that [47m[defattach][0m is [47m[local][0m, because the
  expansion of the corresponding [47m[make-event][0m is saved during the
  first pass of [47m[certify-book][0m, when full admissibility checks are
  done.  Then even after including the book, the definition of [47mf2[0m
  will be based on the second ([47m[local][0m) [47m[defattach][0m form below.

    (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)))")
 (ILK
  (APPLY$)
  "Indicator of how an argument is used

  The [3milk[0m of the ith argument of a [47m[badge][0md function symbol [47mfn[0m is one
  of three tokens with the following meanings.

    * [47m:FN[0m - the ith argument is used exclusively as a function object by
      [47mfn[0m; informally this means that the argument is passed only into
      slots of ilk [47m:FN[0m in the definition of [47mfn[0m and that on some
      (syntactic) execution paths reaches the first argument of a
      call of [47m[apply$][0m.

    * [47m:EXPR[0m - the ith argument is used exclusively as a expression object
      by [47mfn[0m; informally this means that the argument is passed only
      into slots of ilk [47m:EXPR[0m in the definition of [47mfn[0m and that on
      some (syntactic) execution paths reaches the first argument of
      a call of [47m[ev$][0m.

    * [47mNIL[0m - the ith argument is never used as a function or expression
      object in the definition of [47mfn[0m.

  See [47m[badge][0m for more details.

  The [3milks[0m of all the arguments of [47mfn[0m are stored in the [47m[badge][0m of [47mfn[0m.
  If each ilk of [47mfn[0m is [47mNIL[0m the [47m[badge][0m stores a [47mT[0m as the ``list'' of
  ilks.

  The [47m[badge][0m of [47mfn[0m is computed by a successful call of [47m[defwarrant][0m on
  [47mfn[0m.

  Ilks are used by the various notions of [tame]ness controlling
  whether [47m[apply$][0m and [47m[ev$][0m can properly interpret a quoted function
  or expression object.")
 (ILKS (POINTERS) "See [ilk].")
 (ILLEGAL
  (ERRORS ACL2-BUILT-INS)
  "Print an error message and stop execution

  [47m(Illegal ctx str alist)[0m causes evaluation to halt with a short
  message using the ``context'' [47mctx[0m.  An error message is first
  printed using the string [47mstr[0m and alist [47malist[0m that are of the same
  kind as expected by [47m[fmt][0m.  See [fmt], and see [prog2$] for an
  example of how to use a related function, [47m[hard-error][0m (see
  [hard-error]).  Also see [er] for a macro that provides a unified
  way of signaling errors.

  The difference between [47millegal[0m and [47m[hard-error][0m is that the former
  has a guard of [47mnil[0m while the latter has a [47m[guard][0m of [47mt[0m.  Thus, you
  may want to use [47millegal[0m rather than [47mhard-error[0m when you intend to
  do [47m[guard][0m verification at some point, and you expect the guard to
  guarantee that the [47millegal[0m call is never executed.  See [prog2$]
  for an example.

  Technical note for raw Lisp programmers only: It is possible to cause
  hard errors to signal actual raw Lisp errors.  See [hard-error].

  [31;1mFunction: [0m<illegal>

    (defun illegal (ctx str alist)
      (declare (xargs :guard (hard-error ctx str alist)))
      (hard-error ctx str alist))")
 (ILLEGAL-STATE
  (DEFABSSTOBJ)
  "Illegal ACL2 state

  See [set-absstobj-debug] for background on invariance violations for
  abstract [stobj]s.  In short, they may occur when execution does
  not complete for certain atomic operations.

  Such violations cause the following error message to be printed.

    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.

  At this point, the only way to get ACL2 to evaluate further input is
  to submit the form [47m:CONTINUE-FROM-ILLEGAL-STATE[0m, as noted above ---
  or more generally, the form it actually represents,
  [47m(CONTINUE-FROM-ILLEGAL-STATE)[0m, which may need to be written as
  [47m(ACL2::CONTINUE-FROM-ILLEGAL-STATE)[0m if the [47m[current-package][0m is
  other than [47m\"ACL2\"[0m.  There is actually one exception: [47m:[0m[47m[q][0m is
  accepted, to pop out of the current call of [47m[ld][0m.

  To get a bit more information from the error message displayed above,
  see [set-absstobj-debug].

  See [community-book] file
  [47mbooks/system/tests/abstract-stobj-nesting/nested-abstract-stobjs-input.lsp[0m,
  Examples 3 and 4, for relevant examples.

  Technical note.  An illegal-state is entered when ACL2 sets the [47mld[0m
  special, [47m[ld-pre-eval-print][0m, to the value [47m:illegal-state[0m.")
 (IMAGPART
  (NUMBERS ACL2-BUILT-INS)
  "Imaginary part of a complex number

  Completion Axiom ([47mcompletion-of-imagpart[0m):

    (equal (imagpart x)
           (if (acl2-numberp x)
               (imagpart x)
             0))

  [Guard] for [47m(imagpart x)[0m:

    (acl2-numberp x)")
 (IMMED-FORCED (POINTERS)
               "See [splitter].")
 (IMMEDIATE-FORCE-MODEP
  (FORCE)
  "When the [executable-counterpart] is [enable]d, [force]d hypotheses
  are attacked immediately

  Also see [disable-immediate-force-modep] and see
  [enable-immediate-force-modep].

  This function symbol is defined simply to provide a [rune] which can
  be [enable]d and [disable]d.  Enabling

    (:executable-counterpart immediate-force-modep)

  causes ACL2 to attack [force]d hypotheses immediately instead of
  delaying them to the next forcing round.

    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

  See [force] for background information.  When a [47m[force][0md 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
  [force]d hypotheses explicitly.  However, if the [rune]
  [47m(:executable-counterpart immediate-force-modep)[0m is [enable]d at the
  time the hypothesis is [force]d, then ACL2 does not delay the
  attempt to prove that hypothesis but undertakes the attempt more or
  less immediately.")
 (IMPLICATE (POINTERS)
            "See [system-utilities].")
 (IMPLIES
  (BASICS ACL2-BUILT-INS)
  "Logical implication

  [47mImplies[0m is the ACL2 implication function.  [47m(implies P Q)[0m means that
  either [47mP[0m is false (i.e., [47mnil[0m) or [47mQ[0m is true (i.e., not [47mnil[0m).

  [31;1mFunction: [0m<implies>

    (defun implies (p q)
      (declare (xargs :guard t))
      (if p (if q t nil) t))")
 (IMPROPER-CONSP
  (LISTS ACL2-BUILT-INS)
  "Recognizer for improper (non-[47mnil[0m-terminated) non-empty lists

  [47mImproper-consp[0m is the function that checks whether its argument is a
  non-empty list that ends in other than [47mnil[0m.  See [proper-consp] and
  also see [true-listp].

  [31;1mFunction: [0m<improper-consp>

    (defun improper-consp (x)
      (declare (xargs :guard t))
      (and (consp x) (not (true-listp x))))")
 (IN-ARITHMETIC-THEORY
  (EVENTS)
  "Designate theory for some rewriting done for non-linear arithmetic

  We assume familiarity with [theories]; in particular, 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
  [non-linear-arithmetic]).

    Example:
    (in-arithmetic-theory '(lemma1 lemma2))

    General Form:
    (in-arithmetic-theory term)

  where [47mterm[0m is a term that when evaluated will produce a theory (see
  [theories]).  Except for the variable [47m[world][0m, [47mterm[0m must contain no
  free variables.  [47mTerm[0m is evaluated with the variable [47m[world][0m bound
  to the current [world] to obtain a theory and the corresponding
  runic theory (see [theories]) is then used by non-linear arithmetic
  (see [non-linear-arithmetic]).

  Warning: If [47mterm[0m involves macros such as [47m[enable][0m and [47m[disable][0m you
  will probably not get what you expect!  Those macros are defined
  relative to the [47m[current-theory][0m.  But in this context you might
  wish they were defined in terms of the
  ``[47mCURRENT-ARITHMETIC-THEORY[0m'' which is not actually a defined
  function.  We do not anticipate that users will repeatedly modify
  the arithmetic theory.  We expect [47mterm[0m most often to be a constant
  list of runes and so have not provided ``arithmetic theory
  manipulation functions'' analogous to [47m[current-theory][0m and
  [47m[enable][0m.

  See [non-linear-arithmetic].")
 (IN-PACKAGE
  (PACKAGES ACL2-BUILT-INS)
  "Select current package

    Example:
    (in-package \"MY-PKG\")

    General Form:
    (in-package str)

  where [47mstr[0m is a string that names an existing ACL2 package, i.e., one
  of the initial packages such as [47m\"KEYWORD\"[0m or [47m\"ACL2\"[0m or a package
  introduced with [47m[defpkg][0m.  For a complete list of the known
  packages created with [47m[defpkg][0m, evaluate

    (strip-cars (known-package-alist state)).

  See [defpkg].  An ACL2 book (see [books]) must contain a single
  [47min-package[0m form, which must be the first form in that book.")
 (IN-TAU-INTERVALP
  (TAU-SYSTEM ACL2-BUILT-INS)
  "Boolean membership in a tau interval

    General Form:
    (in-tau-intervalp e x)

  Here, [47mx[0m should be an interval (see [47m[tau-intervalp][0m).  This function
  returns [47mt[0m or [47mnil[0m indicating whether [47me[0m, which is generally but not
  necessarily a number, is an element of interval [47mx[0m.  By that is
  meant that [47me[0m satisfies the domain predicate of the interval and
  lies between the two bounds.

  Suppose [47mx[0m is an interval with the components [3mdom[0m, [3mlo-rel[0m, [3mlo[0m, [3mhi-rel[0m
  and [3mhi[0m.  Suppose [47m(<?  [0m[3mrel u v[0m[47m)[0m means [47m(< [0m[3mu v[0m[47m)[0m when [3mrel[0m is true and
  [47m(<= [0m[3mu v[0m[47m)[0m otherwise, with appropriate treatment of infinities.

  Then for [47me[0m to be in interval [47mx[0m, it must be the case that [47me[0m satisfies
  the domain predicate [3mdom[0m (where where [3mdom[0m=[47mnil[0m means there is no
  restriction on the domain) and [47m(<? [0m[3mlo-rel lo[0m[47m e)[0m and [47m(<? [0m[3mhi-rel[0m[47m e
  [0m[3mhi[0m[47m)[0m.  [Note: ``Appropriate treatment of infinities'' is slightly
  awkward if both infinities are represented by the same object, [47mnil[0m.
  However, this is handled by coercing [47me[0m to a number [3mafter[0m checking
  that it is in the domain.  By this trick, ``[47m<?[0m'' is presented with
  at most one ``infinity'' and it is always negative when in the
  first argument and positive when in the second.]

  Note that every element in an [47mINTEGERP[0m interval is contained in the
  analogous [47mRATIONALP[0m interval (i.e., the interval obtained by just
  replacing the domain [47mINTEGERP[0m by [47mRATIONALP[0m).  That is because every
  integer is a rational.  Similarly, every rational is an ACL2
  number.

  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.

  Note that an interval in which the relations are strong and the
  bounds are equal rationals is empty: it contains no objects.

  Note that the interval [47m(make-tau-interval nil nil nil nil nil)[0m 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 [47m0[0m and ACL2's
  inequalities coerce non-numbers to [47m0[0m.  The universal interval is
  useful if you are defining a bounder (see [bounders]) for a
  function and do not wish to address a certain case: return the
  universal interval.

  Recall that [47m[make-tau-interval][0m constructs intervals.  Using
  [47mmake-tau-interval[0m we give several self-explanatory examples of
  [47min-tau-intervalp[0m:

    (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")
 (IN-THEORY
  (EVENTS THEORIES)
  "Designate ``current'' theory (enabling its rules)

    Example:
    (in-theory (set-difference-theories
                 (universal-theory :here)
                 '(flatten (:executable-counterpart flatten))))

    General Form:
    (in-theory term)

  where [47mterm[0m is a term that when evaluated will produce a theory (see
  [theories]).

  Except for the variable [47m[world][0m, [47mterm[0m must contain no free variables.
  [47mTerm[0m is evaluated with the variable [47m[world][0m bound to the current
  [world] to obtain a theory and the corresponding runic theory (see
  [theories]) is then made the current theory.  Thus, immediately
  after the [47min-theory[0m, a rule is [enable]d iff its rule name is a
  member of the runic interpretation (see [theories]) of some member
  of the value of [47mterm[0m.  See [theory-functions] for a list of the
  commonly used theory manipulation functions.

  Note that it is often useful to surround [47min-theory[0m [events] with
  [47mlocal[0m, that is, to use [47m(local (in-theory ...))[0m.  This use of
  [47m[local][0m in [47m[encapsulate][0m events and [books] will prevent the effect
  of this theory change from being exported outside the context of
  that [47mencapsulate[0m or book.

  Also see [hints] for a discussion of the [47m:in-theory[0m hint, including
  some explanation of the important point that an [47m:in-theory[0m hint
  will always be evaluated relative to the current ACL2 logical
  [world], not relative to the theory of a previous goal.

  [47m[In-theory][0m returns an [error-triple].  When the return is without
  error, the value is of the form [47m(mv nil (:NUMBER-OF-ENABLED-RUNES
  k) state)[0m where [47mk[0m is the length of the new current theory.  This
  value of [47mk[0m is what is printed when an [47min-theory[0m event evaluates
  without error at the top level.")
 (INCLUDE-BOOK
  (BOOKS-REFERENCE BOOKS-TOUR EVENTS)
  "Load the [events] in a file

    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)

  where [47mfile[0m is a book-name without the [47m\".lisp\"[0m extension.  See [books]
  for general information, see [book-name] for information about
  book-names, and see [pathname] for information about file names.
  [47mAction[0m is one of [47mt[0m, [47mnil[0m, [47m:default[0m, [47m:warn[0m, or [47m:comp[0m; these values
  are explained below, and the default is [47m:default[0m.  The three [47m-okp[0m
  keyword arguments, which default to [47mt[0m, determine whether errors or
  warnings are generated under certain conditions explained below;
  when the argument is [47mt[0m, warnings are generated.  The [47m:dir[0m argument,
  if supplied, is a keyword that represents an absolute [pathname]
  for a directory, to be used instead of the current book directory
  (see [cbd]) for resolving the given [47mfile[0m argument to an absolute
  pathname.  In particular, by default [47m:dir :system[0m resolves the
  given [47mfile[0m using the [47mbooks/[0m directory of your ACL2 installation;
  see ``Books Directory'' below.  To define other keywords that can
  be used with [47m:dir[0m, see [add-include-book-dir],
  [add-include-book-dir!], and [project-dir-alist].  If the book has
  no [certificate], if its certificate is invalid (say, because its
  [book-hash] shows that books have changed after their
  certification), or if the certificate was produced by a different
  [version] of ACL2, a warning is printed and the book is included
  anyway; see [certificate].  This can lead to serious errors,
  perhaps mitigated by the presence of a [47m.port[0m file from an earlier
  certification; see [uncertified-books].  If the portcullis of the
  [certificate] (see [portcullis]) cannot be raised in the host
  logical [world], an error is caused and no change occurs to the
  logic.  Otherwise, the non-[47m[local][0m [events] in file are assumed.
  Then the [keep] of the [certificate] is checked to ensure that the
  correct files were read; see [keep].  A warning is printed if
  uncertified [books] were included.  Even if no warning is printed,
  [47minclude-book[0m places a burden on you; see [certificate].

  If you use [guard]s, please note [47minclude-book[0m is executed as though
  [47m(set-guard-checking t)[0m has been evaluated; see
  [set-guard-checking].  If you want to run with different
  guard-checking, consider using [47mld[0m instead, or in addition; see
  [ld].

  The value of [47m:load-compiled-file[0m controls whether a compiled file for
  the given [47mfile[0m is loaded by [47minclude-book[0m.  Note that this keyword
  applies only to the given [47mfile[0m, not to any included sub-books.  In
  order to skip loading all compiled files, for the given [47mfile[0m as
  well as all included sub-books --- for example, to avoid Lisp
  errors such as ``Wrong FASL version'' --- use [47m(set-compiler-enabled
  nil state)[0m; see [compilation].  Otherwise, if keyword argument
  [47m:load-compiled-file[0m is missing or its value is the keyword
  [47m:default[0m, then it is treated as [47m:warn[0m.  If its value is [47mnil[0m, 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 [certificate] (except in raw mode, where it must be more
  recent than the book itself; see [set-raw-mode]).  For non-[47mnil[0m
  values of [47m:load-compiled-file[0m 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
  [47m[include-book][0m form is encountered for which no suitable compiled
  or expansion file can be loaded.  For much more detail, see
  [book-compiled-file].

      [47mt[0m: Cause an error if the compiled file is not loaded.  This same
      requirement is imposed on every [47m[include-book][0m form evaluated
      during the course of evaluation of the present [47minclude-book[0m
      form, except that for those subsidiary [47minclude-book[0ms that do
      not themselves specify [47m:load-compiled-file t[0m, it suffices to
      load the expansion file (see [book-compiled-file]).

      [47m:warn[0m: An attempt is made to load the compiled file, and a warning is
      printed if that load fails to run to completion.

      [47m:comp[0m: A compiled file is loaded as with value [47mt[0m, except that if a
      suitable ``expansion file'' exists but the compiled file does
      not, then the compiled file is first created.  See
      [book-compiled-file].

  The three [47m-okp[0m arguments, [47m:uncertified-okp[0m, [47mdefaxioms-okp[0m, and
  [47mskip-proofs-okp[0m, 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 [47m[defaxiom][0m events, and when the book
  or any sub-book is found to contain [47m[skip-proofs][0m events,
  respectively.  All three default to [47mt[0m, 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 [47mnil[0m and the corresponding condition arises, an
  error is signaled and processing is aborted.  [31;1mExceptions[0m:
  [47m:uncertified-okp t[0m is ignored if the [47minclude-book[0m is being
  performed on behalf of a [47m[certify-book][0m, and [47m:uncertified-okp
  :ignore-certs[0m is an advanced option explained later in this topic.

  The keyword argument [47m:ttags[0m may normally be omitted.  A few
  constructs, used for example if you are building your own system
  based on ACL2, may require it.  See [defttag] for an explanation of
  this argument.

  [47mInclude-book[0m is similar in spirit to [47m[encapsulate][0m in that it is a
  single event that ``contains'' other [events], in this case the
  [events] listed in the file named.  [47mInclude-book[0m processes the
  non-[47m[local][0m event forms in the file, assuming that each is
  admissible.  [47m[Local][0m [events] in the file are ignored.  You may use
  [47minclude-book[0m to load several [books], creating the logical [world]
  that contains the definitions and theorems of all of them.

  If any non-[47m[local][0m event of the book attempts to define a [name] that
  has already been defined --- and the book's definition is not
  syntactically identical to the existing definition --- the attempt
  to include the book fails, an error message is printed, and no
  change to the logical [world] occurs.  See [redundant-events] for
  the details.

  When a book is included, the default [defun-mode] (see
  [default-defun-mode]) for the first event is always [47m:[0m[47m[logic][0m.  That
  is, the default [defun-mode] ``outside'' the book --- in the
  environment in which [47minclude-book[0m was called --- is irrelevant to
  the book.  [Events] that change the [defun-mode] are permitted
  within a book (provided they are not in [47m[local][0m forms).  However,
  such changes within a book are not exported, i.e., at the
  conclusion of an [47minclude-book[0m, the ``outside'' default [defun-mode]
  is always the same as it was before the [47minclude-book[0m.

  Unlike every other event in ACL2, [47minclude-book[0m puts a burden on you.
  Used improperly, [47minclude-book[0m can be unsound in the sense that it
  can create an inconsistent extension of a consistent logical
  [world].  A certification mechanism is available to help you carry
  this burden --- 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
  [certificate] for a discussion of the security issues.

  At the beginning of execution of an [47minclude-book[0m form, even before
  executing [portcullis] [command]s, the value of
  [47m[ACL2-defaults-table][0m is restored to the value it had at startup.
  After execution of an [47minclude-book[0m form, the value of
  [47m[ACL2-defaults-table][0m is restored to what it was immediately before
  that [47minclude-book[0m form was executed.  See [ACL2-defaults-table].

  An advanced option is [47m:uncertified-okp :ignore-certs[0m.  This tells
  ACL2 to ignore all [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 [47m.acl2x[0m file for the first
  ``run'' of a ``two-runs approach'' to certification; see
  [set-write-ACL2x].  Note however that ordinary certification (the
  second ``run'') will then fail unless care is taken to avoid
  [47m:uncertified-okp :ignore-certs[0m during that second certification
  run.  Finally (and speaking in general, not particularly about a
  [47m[certify-book][0m context), we emphasize that the option
  [47m:uncertified-okp :ignore-certs[0m applies when including all
  sub-books, not only for the current book.  In particular, a
  subsidiary [47minclude-book[0m call specifying [47m:uncertified-okp nil[0m will
  fail, because the superior [47m:ignore-certs[0m value causes the
  subsidiary book to be treated as uncertified, which conflicts with
  the requirement of [47m:uncertified-okp nil[0m.

  [31;1mBooks Directory.[0m We refer to the ``books directory'' of an executable
  image as the full pathname string of the directory associated with
  [47minclude-book[0m keyword option [47m:dir :system[0m for that image.  By
  default, it is the [47mbooks/[0m subdirectory of the directory where the
  sources reside and the executable image is thus built).  If those
  books reside elsewhere, the environment variable [47mACL2_SYSTEM_BOOKS[0m
  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:

    export ACL2_SYSTEM_BOOKS
    ACL2_SYSTEM_BOOKS=/home/acl2/4-0/acl2-sources/books

  If you follow suggestions in the installation instructions, these
  books will be the ACL2 community books; see [community-books].  For
  another way to set the system books directory, which also permits
  similar handling for other directories, see [project-dir-alist].

  This concludes the guided tour through [books].  See
  [set-compile-fns] for a subtle point about the interaction between
  [47minclude-book[0m and on-the-fly [compilation].  See [certify-book] for
  a discussion of how to certify a book.


Subtopics

  [Fast-cert]
      A mode for faster, but possibly unsound, book certification")
 (INCOMPATIBLE
  (THEORIES)
  "Declaring that two rules should not both be [enable]d

    Example:
    (theory-invariant (incompatible (:rewrite left-to-right)
                                    (:rewrite right-to-left)))

    General Form:
    (incompatible rune1 rune2)

  where [47mrune1[0m and [47mrune2[0m are two specific [rune]s.  The arguments are
  not evaluated.  [47mInvariant[0m is just a macro that expands into a term
  that checks that not both [rune]s are enabled.  See
  [theory-invariant].  Also see [incompatible!] for a variant that
  insists the arguments are indeed runes, not merely having the
  shapes of runes.")
 (INCOMPATIBLE!
  (THEORIES)
  "Declaring that two rules must exist and should not both be [enable]d

  This variant of [47mincompatible[0m causes an error if either of its
  arguments is not a [rune], by calling [47m[active-or-non-runep][0m instead
  of [47m[active-runep][0m.  See [incompatible] and see [theory-invariant].")
 (INDUCT (POINTERS)
         "See [hints] for information about the keyword [47m:induct[0m.")
 (INDUCTION
  (RULE-CLASSES)
  "Make a rule that suggests a certain induction

    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))))

  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 [rulers] and
  [induction-coarse-v-fine-grained].

  For example, since [47m[append][0m (actually [47m[binary-append][0m, but we'll
  ignore the distinction here) decomposes its first argument by
  successive [47m[cdr][0ms as long as it is a cons, the induction scheme
  suggested by [47m(append x y)[0m has a base case supposing [47mx[0m to be an atom
  (i.e., not a cons) and then has an induction step in which the
  induction hypothesis is obtained by replacing [47mx[0m by [47m(cdr x)[0m.  This
  substitution decreases the same measure used to justify the
  definition of [47m[append][0m.  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, [47m(append (foo x) y)[0m does not
  suggest an induction unwinding [47m[append][0m because the induction
  scheme suggested by [47m(append x y)[0m requires that we substitute [47m(cdr
  x)[0m for [47mx[0m and we cannot do that if [47mx[0m is not a variable symbol.

  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
  [induction-heuristics].

  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 [47m:induction[0m rules.  The
  definitional principle automatically creates an [47m:induction[0m rule,
  named [47m(:induction fn)[0m, for each admitted recursive function, [47mfn[0m.
  It is this rule that links applications of [47mfn[0m to the induction
  scheme it suggests.  Disabling [47m(:induction fn)[0m will prevent [47mfn[0m 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 [47m:induction[0m rules by
  using the [47m:induction[0m rule class in [47m[defthm][0m.

  Technically we are ``overloading'' [47m[defthm][0m by using it in the
  creation of [47m:induction[0m rules because no theorem need be proved to
  set up the heuristic link represented by an [47m:induction[0m rule.
  However, since [47m[defthm][0m 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 [47m:induction[0m rule.  An [47m:induction[0m rule can be created from any
  lemma whatsoever.

    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)

  where [47mpat-term[0m, [47mcond-term[0m, and [47mscheme-term[0m are all terms, [47mpat-term[0m is
  the application of a function symbol, [47mfn[0m, [47mscheme-term[0m is the
  application of a function symbol, [47mrec-fn[0m, that suggests an
  induction, and, finally, every free variable of [47mcond-term[0m and
  [47mscheme-term[0m is a free variable of [47mpat-term[0m.  We actually check that
  [47mrec-fn[0m is either recursively defined --- so that it suggests the
  induction that is intrinsic to its recursion --- or else that
  another [47m:induction[0m rule has been proved linking a call of [47mrec-fn[0m as
  the [47m:pattern[0m to some scheme.

  The induction rule created is used as follows.  When an instance of
  the [47m:pattern[0m term occurs in a conjecture to be proved by induction
  and the corresponding instance of the [47m:condition[0m term is known to
  be non-[47mnil[0m (by [type-reasoning] alone), the corresponding instance
  of the [47m:scheme[0m 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 [47mrec-fn[0m has a recursive definition, then the
  definition's dual induction scheme is suggested (i.e., unwinding
  the function).

  (Remark.  Unlike [47m:induct[0m [hints], the [47m:scheme[0m of an [47m:induction[0m 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.)

  Consider, for example, the example given above,

    (:induction :pattern (* 1/2 i)
                :condition (and (integerp i) (>= i 0))
                :scheme (recursion-by-sub2 i)).

  In this example, we imagine that [47mrecursion-by-sub2[0m is the function:

    (defun recursion-by-sub2 (i)
      (if (and (integerp i)
               (< 1 i))
          (recursion-by-sub2 (- i 2))
          t))

  Observe that this function recursively decomposes its natural number
  argument by subtracting [47m2[0m from it repeatedly and stops when the
  argument is [47m1[0m or less.  The value of the function is irrelevant; it
  is its induction scheme that concerns us.  The induction scheme
  suggested by [47m(recursion-by-sub2 i)[0m is

    (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)))

  We can think of the base case as covering two situations.  The first
  is when [47mi[0m is not an integer.  The second is when the integer [47mi[0m is
  less than or equal to [47m1[0m.  In the base case we must prove [47m(:p i)[0m
  without further help.  The induction step deals with those natural
  numbers [47mi[0m greater than [47m1[0m, and inductively assumes the conjecture
  for [47mi-2[0m while proving it for [47mi[0m.  Let us call this scheme
  ``induction on [47mi[0m by twos.''

  Suppose the above [47m:induction[0m rule has been added.  Then an occurrence
  of, say, [47m(* 1/2 k)[0m in a conjecture to be proved by induction would
  suggest, via this rule, an induction on [47mk[0m by twos, provided [47mk[0m was
  known to be a nonnegative integer.  This is because the induction
  rule's [47m:pattern[0m is matched in the conjecture, its [47m:condition[0m is
  satisfied, and the [47m:scheme[0m suggested by the rule is that derived
  from [47m(recursion-by-sub2 k)[0m, which is induction on [47mk[0m by twos.
  Similarly, the term [47m(* 1/2 (length l))[0m would suggest no induction
  via this rule, even though the rule ``fires'' because it creates
  the [47m:scheme[0m [47m(recursion-by-sub2 (length l))[0m which suggests no
  inductions unwinding [47mrecursion-by-sub2[0m (since the controlling
  argument of [47mrecursion-by-sub2[0m in this [47m:scheme[0m is not a variable
  symbol).

  Continuing this example one step further illustrates the utility of
  [47m:induction[0m rules.  We could define the function [47mrecursion-by-cddr[0m
  that suggests the induction scheme decomposing its [47m[consp][0m argument
  two [47m[cdr][0ms at a time.  We could then add the [47m:induction[0m rule
  linking [47m(* 1/2 (length x))[0m to [47m(recursion-by-cddr x)[0m and arrange for
  [47m(* 1/2 (length l))[0m to suggest induction on [47ml[0m by [47m[cddr][0m.

  Observe that [47m:induction[0m rules require no proofs to be done.  Such a
  rule is merely a heuristic link between the [47m:pattern[0m term, which
  may occur in conjectures to be proved by induction, and the [47m:scheme[0m
  term, from which an induction scheme may be derived.  Hence, when
  an [47m:induction[0m rule-class is specified in a [47m[defthm][0m event, the
  theorem proved is irrelevant.  The easiest theorem to prove is, of
  course, [47mt[0m.  Thus, we suggest that when an [47m:induction[0m rule is to be
  created, the following form be used:

    (defthm name T
      :rule-classes ((:induction :pattern pat-term
                                 :condition cond-term
                                 :scheme scheme-term)))

  The name of the rule created is [47m(:induction name)[0m.  When that [rune]
  is [disable]d the heuristic link between [47mpat-term[0m and [47mscheme-term[0m
  is broken.

  Note that if [47mfn[0m is defined recursively and [47m(:induction fn)[0m is
  [disable]d, then normally the induction scheme for [47mfn[0m will not be
  available during a proof.  However, the induction scheme for [47mfn[0m is
  available, even if it is disabled, when it is indicated by
  application of a user-defined [47m:induction[0m rule.  So for the
  [47m:induction[0m rule above, [47mrecursion-by-sub2-induction-rule[0m: even if
  [47m(:induction recursion-by-sub2)[0m is disabled, nevertheless the
  induction scheme for [47mrecursion-by-sub2[0m will be available to apply
  to the instantiated [47m:scheme-term[0m.


Subtopics

  [Induction-depth-limit]
      The maximum number permitted of nested inductions

  [Set-induction-depth-limit!]
      Set the induction-depth-limit non-[47m[local][0mly")
 (INDUCTION-COARSE-V-FINE-GRAINED
  (RULERS)
  "advice on case explosion in complex inductions

  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 [rulers] for a discussion of
  ruler-extenders.


Governing versus Ruling Tests

  Roughly speaking, a test [3mgoverns[0m a recursive call if the test must be
  true for control to reach that call.  The [3mruling[0m tests are a subset
  of the governing tests and are the ones that determine the case
  analysis of any suggested induction.

  For example, if we are analyzing a definition of [47m(fn x)[0m and the body
  is [47m(if (not (consp x)) (h nil) (h (fn (cdr x))))[0m then [47m(consp x)[0m
  governs the recursive call and it also rules the call.  But if the
  body were [47m(h (if (not (consp x)) nil (fn (cdr x))))[0m then [47m(consp x)[0m
  governs the recursive call but may not rule it.  It would be
  considered a ruler if the symbol [47mh[0m were on the ``ruler-extenders''
  list --- the list of symbols that allow further collection of
  rulers from inside terms that begin with those symbols.

  The default setting of ruler-extenders is [47m(if mv-list return-last)[0m.
  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 [47mlambda[0m expression, that term is considered a tip of the
  tree.  ([47mLambda[0m expressions are relevant because they are introduced
  by the macroexpansion of [47m[let][0m and [47m[let*][0m expressions, which arise
  frequently in interesting recursive functions because they
  facilitate [3mcode sharing[0m 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 [3mall[0m 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.

  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
  [47mset-ruler-extenders[0m or specified locally in a [47mdefun[0m by the [47m[xargs][0m
  keyword [47m:ruler-extenders[0m.  See [rulers] for the details.


Coarse versus Fine Induction Case Analysis

  Most often, users think about ruler-extenders only in the context of
  [3mfailed[0m 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.

  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 [47m[let*][0m bindings that contain
  [47mif[0m-expressions, some of which contain recursive calls.  For
  example, the following artificial example raises the possibility of
  this problem.

    (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))

  Recall that [47mlet*[0m expressions are translated into nested [47mlambda[0m
  expressions, so the formal definition of [47mfn[0m is

    (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))

  So, the entire [47mlet*[0m above, i.e., the formal term starting with the
  first [47mlambda[0m expression, is a tip ruled only by [47m(consp x)[0m.  The [47mif[0ms
  within it are not considered even though their tests govern (but do
  not rule) the subsequent recursions.  The recursive calls in that
  tip are

    (fn (car x) (cons 'car y))

  and

    (fn (cdr x)
        (cons 'cdr
              (if (consp (car x))
                  (fn (car x) (cons 'car y))
                  y))).

  The default measure in this definition is [47m(acl2-count x)[0m.  The
  measure conjectures are easy to prove because [47m(consp x)[0m implies
  [47m(acl2-count (car x))[0m and [47m(acl2-count (cdr x))[0m are both less than
  [47m(acl2-count x)[0m.  Since there are no more recursive calls in the
  definition, [47mfn[0m is admitted.

  Now consider how the prover would attempt to prove [47m(p (fn x y))[0m by
  the induction suggested by [47mfn[0m.  The induction argument, shown
  below, has one base case and one induction step.  The induction
  step has two induction hypotheses.

    (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)))).

  [31;1mNote[0m: 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 [47m(p (fn x y))[0m 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.

  The prover attempts to reduce each of these two conjuncts to [47mT[0m by
  simplification.  The base case is generally simple.  So consider
  the induction step, the second implication above, which we
  abbreviate here as

    (implies (and (consp x)
                  [3mind-hyp1[0m
                  [3mind-hyp2[0m)
             [3mind-concl[0m)

  where, [3mind-hyp1[0m, the first induction hypothesis, is [47m(p (fn (car x)
  (cons 'car y)))[0m, etc.  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, [3mind-concl[0m, 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.

  But rewriting [3mind-hyp1[0m here will involve rewriting [47m(fn (car x) (cons
  'car y))[0m, which is completely irrelevant to half of the proof of
  [3mind-concl[0m.  In particular, inspection of [47mfn[0m reveals that the first
  recursive call of [47mfn[0m is only relevant if [47m(consp (car x))[0m is true.
  But we know nothing about [47m(car x)[0m 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.

  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
  [47m(consp (car x))[0m), 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).

  Depending on how hard it is to rewrite irrelevant induction
  hypotheses --- which depends not just on the function, like [47mfn[0m,
  suggesting the induction but also on the conjecture being proved
  --- 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.

  A finer-grained induction scheme is generated, in the case of [47mfn[0m, by
  arranging for [47mlambda[0m expressions [3mnot[0m to stop the collection of
  rulers.  This can be done by adding the keyword [47m:lambdas[0m to the
  ruler-extenders.  The presence of that keyword means ``keep
  collecting rulers as you dive into [3many[0m term beginning with a [47mlambda[0m
  expression.'' (By the way, normally [47m:ruler-extenders[0m expects a list
  but if you specify the single keyword [47m:lambdas[0m it denotes the list
  [47m(if :lambdas mv-list return-last)[0m.)  Again, see [47mrulers[0m for details.

  If we had defined [47mfn[0m as shown below we would get the finer induction
  analysis shown subsequently.

    (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))

  Note that [47mfn[0m can be admitted without extending the rulers --- we have
  already demonstrated that.  We are including [47m:lambdas[0m here
  precisely to get a finer case analysis for induction.

  The induction generated is shown below.  We have slightly simplified
  the induction by replacing [47m(if [0m[3ma b c[0m[47m)[0m by [3mb[0m when [3ma[0m is among the
  hypotheses in the case analysis, and by replacing [47m(if [0m[3ma b c[0m[47m)[0m by [3mc[0m
  when [47m(not [0m[3ma[0m[47m)[0m is among the hypotheses.  This simplification is
  actually not done by induction analysis but by the first
  simplification.

    (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))))

  Note that the case analysis here steers the [47m(fn x y)[0m in the
  conclusion down exactly one path and the only hypotheses provided
  in each induction step concern recursive calls on that path.

  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 [47m(p (fn ...))[0m 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.

  [31;1mNote[0m: The ruler-extenders may include arbitrary function symbols and
  the keyword [47m:lambdas[0m as above.  But it can also be set to [47m:all[0m
  which makes all the governors be rulers, i.e., collection of rulers
  dives through all function symbols.  We focus here on diving
  through [47mlambda[0m expressions because they are by far the most common
  ``function symbol'' (other than [47mif[0m) under which one finds
  additional tests and recursive calls.

  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.


An Actual Example of Coarse versus Fine Induction Schemes

  The ACL2 prettyprinter is implemented with the function [47mppr[0m.  It is
  basically the composition of two functions, [47mppr1[0m, 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
  [47mppr2[0m, which actually prints.  To admit [47mppr[0m 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
  [47mppr1[0m returns a [47mppr-tuple-p[0m.  You can see the definitions of [47mppr1[0m
  and [47mppr-tuple-p[0m and their mutually recursive peers by using the
  [47m:[0m[47m[pe][0m command, e.g., [47m:pe ppr1[0m.

  We'll focus here on [47mppr1[0m, which is mutually recursive with [47mppr1-lst[0m.
  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 [47mbooks/tools/flag[0m 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.

  A good demonstration of the ``coarse'' and ``fine'' induction schemes
  for [47mppr1[0m can be found in the community book
  [47mbooks/demos/ppr1-experiments[0m.  We summarize the contents of that
  book here.

  The book proves that [47mppr1[0m returns a [47mppr-tuple-p[0m and [47mppr1-lst[0m returns
  a [47mppr-tuple-lst-p[0m.  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
  [47mppr1[0m/[47mppr1-lst[0m under the default ruler-extenders.  The fine
  induction is obtained by admitting a differently named flagged
  version of [47mppr1[0m/[47mppr1-lst[0m with [47m:ruler-extenders :lambdas[0m.

  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.

    (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

  The fine induction, generated under the [47m:lambdas[0m ruler-extension, can
  be similarly sketched.

    (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

  The induction generated under the [47m:all[0m ruler-extensions is identical
  to the fine induction for [47mppr1[0m and [47mppr1-lst[0m.  (No governing [47mif[0ms are
  hidden under function calls other than [47mif[0m and [47mlambda[0m expressions in
  those two functions.)

  Regardless of which induction scheme we use, the proof that [47mppr1[0m
  returns a [47mppr-tuple-p[0m and that [47mppr1-lst[0m returns a [47mppr1-tuple-lst-p[0m
  fails without a certain hint: we have to tell the prover to expand
  the calls of [47mppr1[0m and [47mppr1-lst[0m 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 [47m:expand[0m hint, the coarse induction takes 2,165 seconds and
  the fine induction takes 65 seconds.  See scenarios 1 and 3 in the
  next section.


Comparing Several Optimizations

  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 [47mbooks/demos/ppr1-experiments[0m for the
  details of each hint, etc.  The times reported below were
  originally recovered from the [47m.cert.out[0m 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 [47m.cert.out[0m file for more recent results.

  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 [47mppr1[0m and [47mppr1-lst[0m calls in the
  conclusion.  In these experiments we provide that hint two ways,
  either as part of fairly sophisticated computed hint or with an
  [47m:expand[0m hint on [47m\"Goal\"[0m.  If you try to prove this theorem with no
  hint it fails.

  We will also be experimenting with the enabled status of [47mppr1[0m and
  [47mppr1-lst[0m.

  The seven scenarios are specified by saying which induction scheme is
  used, whether [47mppr1[0m and [47mppr1-lst[0m are enabled or disabled by default,
  and what hints are provided.  There are three basic hints to chose
  from.

    * [47mcomputed[0m --- when a subgoal becomes stable, open [47mppr1[0m and [47mppr1-lst[0m in
      the conclusion, and when any subgoal of that becomes stable
      again, enable [47mppr1[0m and [47mppr1-lst[0m and let ACL2's heuristics take
      over.  This hint only makes sense if [47mppr1[0m and [47mppr1-lst[0m are
      initially disabled.

    * [47mcomputed'[0m --- like [47mcomputed[0m but skips the first stable opening of
      [47mppr1[0m and [47mppr1-lst[0m.  That is handled instead by an [47m:expand[0m hint.

    * [47m:expand[0m --- a traditional [47m:expand[0m hint to open [47mppr1[0m and [47mppr1-lst[0m
      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 [47mppr1[0m and [47mppr1-lst[0m to be
      any terms but insists that the controllers, [47mx[0m and [47mlst[0m,
      respectively, be those particular variable names.

  In addition, we sometimes avail ourselves of special-purpose lemmas.

    * [47mNIL lem[0m --- rewrites [47m(ppr1-lst nil ...)[0m to [47mnil[0m.

    * [47mMAX hack[0m --- lemmas about [47mMAX[0m allowing us to disable [47mMAX[0m

  We try seven different combinations, numbered 1-7, but listed below
  in descending order of proof times.

    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

  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.

  Scenario 2 shows that much time is saved by disabling [47mppr1[0m and
  [47mppr1-lst[0m 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 [47mppr1[0m and [47mppr1-lst[0m, the calls of [47mppr1[0m and [47mppr1-lst[0m in the
  induction hypotheses do not expand until the relevant case analysis
  is exposed by expanding the conclusion.

  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 [47m:expand[0m
  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 [47mMAX hack[0m saves another 10% by
  avoiding case splits caused by the many occurrences of [47mMAX[0m in [47mppr1[0m.

  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 [47m:expand[0m hint.  And
  it was a lot easier to leave [47mppr1[0m and [47mppr1-lst[0m 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!

  Ignoring scenario 7 --- where the additional improvement came from a
  completely different source, namely, avoiding the expansion of [47mMAX[0m
  expressions --- the difference between the easiest thing to do
  (scenario 3) and the fastest method that focused on manually
  controlling [47mppr1[0m and [47mppr1-lst[0m (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!


Conclusion

  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 [47mlet*[0m expressions in which some of the bindings
  conditionally make recursive calls, be alert to the possibility
  that adjusting ruler-extenders to include [47m:lambdas[0m 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.")
 (INDUCTION-DEPTH-LIMIT
  (INDUCTION)
  "The maximum number permitted of nested inductions

  ACL2 may limit the number of levels of induction.  Consider for
  example a subgoal with this [goal-spec]:

    Subgoal *1.2.3.1.2.3.1.2.3/7'11'

  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 [rewrite] rules.  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.

  To see the current limit:

    (induction-depth-limit (w state))

  This limit is always a natural number, with one exception: it can be
  [47mnil[0m, which means that there is no limit on the nesting depth of
  inductions.

  Note that an explicit [47m:induct[0m hint (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 [47m:induct[0m hint is applied, then any attempt to push a
  subgoal for induction will fail (unless it too has an associated
  [47m:induct[0m hint).

  To change the limit, see [set-induction-depth-limit].


Subtopics

  [Set-induction-depth-limit]
      Set the [induction-depth-limit]")
 (INDUCTION-HEURISTICS
  (RULE-CLASSES)
  "How ACL2 selects induction schemes

  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.

  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.

  For a detailed description of how ACL2 generates induction schemes
  see {``ACL2 Induction Heuristics.'' |
  http://www.cs.utexas.edu/users/moore/publications/acl2-induction-heuristics.pdf}
  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.")
 (INFECTED-CONSTRAINTS
  (ENCAPSULATE)
  "[47m[Events][0m affecting [constraint]s of [47m[encapsulate][0ms

  Here we explain briefly the two kinds of [47m\"Infected\"[0m [warnings] that
  are sometimes printed near the end of the output from [47m[encapsulate][0m
  [events].  Also see [constraint] for a more complete discussion of
  constraints produced by [47mencapsulate[0m events, and see
  [subversive-recursions] for a more complete discussion of the
  second kind of [47m\"Infected\"[0m warning mentioned below, in the last
  example.

  An [47m\"Infected\"[0m warning indicates that an event introducing a function
  symbol inside [47mencapsulate[0m event affects the constraint exported for
  the function introduced in the [signature] list of that
  [47mencapsulate[0m.  That function is typically introduced with [47m[defun][0m,
  but it could be introduced in a signature list of a subsidiary
  [47mencapsulate[0m event or in a [47m[defchoose][0m event.  Below we'll discuss
  the case of [47mdefun[0m, but the others are completely analogous for an
  [47m\"Infected\"[0m warning.

  Let's compare the following three examples.

  [31;1mEXAMPLE 1[0m.

    (encapsulate
     (((sig-fn *) => *))

     (local (defun sig-fn (x) (cons x x)))

     (defun foo (x)
       (sig-fn x))

     (defthm foo-prop
       (consp (foo x))))

  In Example 1 above, ACL2 warns us that the [47mdefun[0m event is having an
  effect on the constraint of another function (more on that below).

    ACL2 Warning [Infected] in ( ENCAPSULATE (((SIG-FN * ...) ...) ...)
    ...):  Note that the definitional equation for FOO infects the constraint
    of this encapsulation....

  Indeed, just above that warning we see that the definitional equation
  for [47mfoo[0m is part of the constraint not only on [47mfoo[0m but also on
  [47msig-fn[0m.

    The following constraint is associated with both of the functions FOO
    and SIG-FN:

    (AND (EQUAL (FOO X) (SIG-FN X)) (CONSP (FOO X)))

  The warning message suggests the desirability of moving the
  definition out of the [47mencapsulate[0m, if possible.  That is not
  possible above: the definition of [47mfoo[0m cannot be moved before the
  [47mencapsulate[0m because it depends syntactically on [47msig-fn[0m, and it
  cannot be moved after the [47mencapsulate[0m because it depends
  syntactically on [47mfoo-prop[0m.

  By contrast, in the next two examples the [47mdefun[0m of [47mfoo[0m can be moved
  before, respectively after, the [47mencapsulate[0m.  In these simple
  cases, ACL2 in effect does that for us automatically, and the
  constraint for [47msig-fn[0m doesn't mention [47mfoo[0m or vice-versa.  In other
  cases, you might want to think about how to move the relevant [47mdefun[0m
  (for [47mfoo[0m, in this case) manually.

  [31;1mEXAMPLE 2[0m (moving the definition of [47mfoo[0m before the [47mencapsulate[0m).

    (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)))))

  [31;1mEXAMPLE 3[0m (moving the definition of [47mfoo[0m after the [47mencapsulate[0m).

    (encapsulate
     (((sig-fn *) => *))

     (local (defun sig-fn (x) (cons x x)))

     (defun foo (x)
       (sig-fn x))

     (defthm foo-prop
       (consp (sig-fn x)))
     )

  We now turn to a second kind of [47m\"Infected\"[0m warning for a [47mdefun[0m form
  inside an [47mencapsulate[0m 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 [type-prescription] rule
  for the [47mdefun[0m.  Consider the following example.

  [31;1mEXAMPLE 4[0m.

    (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)))

  As in Example 1 above, the exported constraint is on both function
  symbols that have been introduced, reported as follows by ACL2.

    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)))

  But this time, in addition, no induction scheme is stored for [47mg[0m, nor
  is any built-in [type-prescription] rule stored for [47mg[0m, as indicated
  by a warning that begins as follows.

    ACL2 Warning [Infected] in ( ENCAPSULATE (((F * ...) ...) ...) ...):
    Note that G is ``subversive.''  See :DOC infected-constraints....

  Note that if [47mf[0m and [47mg[0m had been similarly defined at the top level
  instead of within an [47mencapsulate[0m, a type-prescription rule would be
  added asserting that ``the type of G is described by the theorem
  [47m(NOT (CONSP (G X)))[0m.'' But there is no such rule introduced in this
  ``subversive'' case.  Indeed, this ``theorem'' is not actually a
  theorem after evaluating the [47mencapsulate[0m, as it does not even
  follow from the stronger axiom (stronger, that is, than the
  constraint displayed above) that both [47mf[0m and [47mg[0m are the identity
  function.

  See [subversive-recursions] for more details, including criteria for
  when this ``subversive'' situation arises and what might be done to
  address it.  Also see [constraint] for a general discussion of
  constraints introduced by an [47m[encapsulate][0m event.")
 (INITIALIZE-EVENT-USER
  (OUTPUT-CONTROLS)
  "User-supplied code to initiate [events]

  This utility is intended for system hackers, not standard ACL2 users.

  See [finalize-event-user] to see how to supply code to be run at the
  end of [events].  We assume familiarity with [47mfinalize-event-user[0m;
  here we focus on how to supply code for the beginning as well as
  the end of events.

  As with [finalize-event-user], you attach your own function of
  argument list [47m(ctx qbody state)[0m to [47minitialize-event-user[0m.  (See
  [finalize-event-user] for discussion of [47mctx[0m and [47mbody[0m.)  The
  attachment should return [47mstate[0m and have a trivial guard, requiring
  (implicitly) only that [47mstate[0m satisfies [47mstate-p[0m unless you use trust
  tags to avoid that requirement.  For example:

    (defattach-system initialize-event-user initialize-event-user-test)

  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 [state] global variable,
  [47mmy-time[0m.  You could do the following.

    (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)

  Here is an abbreviated log, showing the time being printed at the
  end.

    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 !>")
 (INLINE (POINTERS)
         "See [defun-inline].")
 (INSTRUCTIONS
  (PROOF-BUILDER)
  "Instructions to the interactive proof-builder

  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 [47m[defthm][0m or [47m[thm][0m).  In
  brief, typical use is to evaluate the form [47m(verify SOME-GOAL)[0m,
  where [47mSOME-GOAL[0m is a formula (i.e., term) that you would like to
  prove.  Various commands (instructions) are available at the
  resulting prompt; see [proof-builder-commands].  When the proof is
  completed, suitable invocation of the [47mexit[0m command will print out a
  form containing an [47m:instructions[0m field that provides the
  instructions that you gave interactively, so that this form can be
  evaluated non-interactively.

  Thus, also see [defthm] for the role of [47m:instructions[0m in place of
  [47m:[0m[47m[hints][0m.  As illustrated by the following example, the value
  associated with [47m:instructions[0m is a list of interactive
  [proof-builder] commands.

    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))

  See [proof-builder-commands] for a list of supported interactive
  proof-builder instructions and links to their documentation.

  Below, we describe a capability for supplying [47m:instructions[0m as
  [47m:[0m[47m[hints][0m.

  The most basic utilities for directing the discharge of a proof
  obligation are [47m:[0m[47m[hints][0m and (less commonly) [47m:instructions[0m.
  Individual instructions may call the prover with [47m:hints[0m; in that
  sense, prover hints may occur inside instructions.  We now describe
  how, on the other hand, instructions may occur inside hints.

  ACL2 supports [47m:instructions[0m 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 ---
  which is \"Subgoal *1/2\" --- was difficult.  You could submit that
  goal to [47m[verify][0m, do an interactive proof, submit [47m(exit t)[0m to
  obtain the list of [47m:instructions[0m, and then paste in those
  instructions.  When you submit the resulting event, you might see
  the following.  Below we'll explain the hint processing.

    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 !>

  To understand how the [47m:instructions[0m 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.

  [31;1mIMPORTANT![0m.  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:

    * The interactive proof-builder's theory is not sensitive to [47m:in-theory[0m
      [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
      [world], i.e., the value of [47m(current-theory :here)[0m.  Moreover,
      references to [47m(current-theory :here)[0m in a proof-builder
      [47min-theory[0m command, even implicit references such as provided by
      [47m[enable][0m and [47m[disable][0m expressions, are also references to the
      current theory of the ACL2 logical [world].

    * The [rune]s used during an [47m:instructions[0m hint are not tracked beyond
      that hint, hence may not show up in the [summary] of the
      overall proof.  Again, think of the [47m:instructions[0m hint as a
      [clause-processor] call, which has some effect not tracked by
      the surrounding proof other than for the child goals that it
      returns.

  We continue now with our discussion of the interactive proof-builder
  instruction interpreter as a clause-processor.

  In the example above, the input goal ([47m\"Subgoal *1/2\"[0m) 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.

    [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.

  [31;1mRemark.[0m This brief remark can probably be ignored, but we include it
  for completeness.  The [47m:CLAUSE-PROCESSOR[0m message above may be
  surprising, since the hint attached to [47m\"Subgoal *1/2\"[0m is an
  [47m:instructions[0m hint, not a [47m:clause-processor[0m hint.  But
  [47m:instructions[0m is actually a custom keyword hint (see
  [custom-keyword-hints]), and may be thought of as a macro that
  expands to a [47m:[0m[47m[clause-processor][0m hint, one that specifies
  [47mproof-builder-cl-proc[0m 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 [defttag]) to install a trusted clause-processor, but that is
  not the case for the built-in clause-processor,
  [47mproof-builder-cl-proc[0m.  Finally, we note that [47m:instructions[0m [hints]
  are ``spliced'' into the hints as follows: the appropriate
  [47m:[0m[47m[clause-processor][0m hint replaces the [47m:instructions[0m hint, and the
  other hints remain intact.  It may seems surprising that one can
  thus, for example, use [47m:instructions[0m and [47m:in-theory[0m together; but
  although the [47m:in-theory[0m hint will have no effect on execution of
  the [47m:instructions[0m (see first bullet above), the [47m:in-theory[0m hint
  will apply in the usual manner to any child goals (see
  [hints-and-the-waterfall]).  End of Remark.

  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.

    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 ... ]]

  We have seen that an [47m:instructions[0m 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 `[47mfinish[0m' 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 [47m:s[0m command
  at the end), you will see an informative error message.

    (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)))))

  If an :instructions hint of the form [47m((finish ...))[0m 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:

    Saving proof-builder error state; see :DOC instructions.  To retrieve:

    (RETRIEVE :ERROR1)

  In this case, you can evaluate the indicated [47m[retrieve][0m command in
  the ACL2 read-eval-print loop, to get to the point of failure.

  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 [47mprove[0m, [47mbash[0m, [47msplit[0m,
  and [47minduct[0m.  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

     [47m(comment inhibit-output-lst VAL)[0m

  where [47mVAL[0m is either the keyword [47m:SAME[0m (indicating that no change
  should be made to which output is inhibited) or else is a legal
  value for inhibited output; see [set-inhibit-output-lst].  The
  following two variants of the immediately preceding [47mTHM[0m form will
  each produce output from the interactive proof-builder commands,
  assuming in the first variant that output hasn't already been
  inhibited.

    (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))))))

  Note that such a [47mcomment[0m instruction must be provided explicitly
  (i.e., not by way of a proof-builder [macro-command]) as the first
  instruction, in order to have the effect on inhibited output that
  is described above.

  The following contrived example gives a sense of how one might want
  to use [47m:instructions[0m within [47m:[0m[47m[hints][0m.  If you submit the following
  theorem

    (thm (implies (true-listp x)
                  (equal (reverse (reverse x)) x)))

  then you will see the following checkpoint printed with the
  [summary].

    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))

  This suggests proving the following theorem.  Here we state it using
  [47m[defthmd][0m, 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 [rewrite] rules disabled.

    (defthmd revappend-revappend
      (equal (revappend (revappend x y) z)
             (revappend y (append x z))))

  We might then enter the interactive [proof-builder] to prove the
  original theorem interactively, as follows.

    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 !>

  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 [47m:instructions[0m within [47m:[0m[47m[hints][0m within
  [47m:instructions[0m, and so on.  Notice the indication of nesting levels:
  ``[47m1>[0m'' to ``[47m<1[0m'' for output from nesting level 1, and ``[47m2>[0m'' to
  ``[47m<2[0m'' for output from nesting level 2.

    (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)))))))))

  Here is an edited version of the resulting log.

    [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]]

  The nesting levels are independent of whether or not output is
  enabled; for example, if the first [47m(comment ...)[0m form below is
  omitted, then we will see only the output bracketed by ``[47m2>[0m'' to
  ``[47m<2[0m''.  Note also that these levels are part of the error states
  saved for access by [47m[retrieve][0m (as indicated above); for example, a
  failure at level 1 would be associated with symbol [47m:ERROR1[0m as
  indicated above, while a failure at level 2 would be associated
  with symbol [47m:ERROR2[0m.")
 (INT=
  (NUMBERS ACL2-BUILT-INS)
  "Test equality of two integers

  [47m(int= x y)[0m is logically equivalent to [47m(equal x y)[0m.

  Unlike [47m[equal][0m, [47mint=[0m requires its arguments to be numbers (or else
  causes a [guard] violation; see [guard]).  Generally, [47mint=[0m is
  executed more efficiently than [47m[equal][0m or [47m[=][0m on integers.

  [31;1mMacro: [0m<int=>

    (defmacro int= (i j)
      (list 'eql
            (if (integerp i)
                i
              (list 'the 'integer i))
            (if (integerp j)
                j
              (list 'the 'integer j))))")
 (INTEGER-LENGTH
  (NUMBERS ACL2-BUILT-INS)
  "Number of bits in two's complement integer representation

  For non-negative integers, [47m(integer-length i)[0m 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 [47m(+
  (integer-length i) 1)[0m bits.

  The [guard] for [47minteger-length[0m requires its argument to be an
  integer.  [47mInteger-length[0m is defined in Common Lisp.  See any Common
  Lisp documentation for more information.

  [31;1mFunction: [0m<integer-length>

    (defun integer-length (i)
      (declare (xargs :guard (integerp i)))
      (if (zip i)
          0
        (if (= i -1)
            0
          (+ 1 (integer-length (floor i 2))))))")
 (INTEGER-LISTP
  (NUMBERS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of integers

  The predicate [47minteger-listp[0m tests whether its argument is a true list
  of integers.

  [31;1mFunction: [0m<integer-listp>

    (defun integer-listp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (eq l nil))
            (t (and (integerp (car l))
                    (integer-listp (cdr l))))))")
 (INTEGER-RANGE-P
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for integers between two bounds.

  The predicate [47m(integer-range-p lower upper x)[0m tests whether [47mx[0m is an
  integer greater than or equal to [47mlower[0m and less than [47mupper[0m.

  [31;1mFunction: [0m<integer-range-p>

    (defun integer-range-p (lower upper x)
      (declare (type integer lower upper))
      (and (integerp x)
           (<= lower x)
           (< x upper)))")
 (INTEGERP
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for whole numbers

  [47m(integerp x)[0m is true if and only if [47mx[0m is an integer.")
 (INTERESTING-APPLICATIONS
  (ACL2-TUTORIAL)
  "Some industrial examples of ACL2 use

  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.

  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 Tours (see [The_Tours]) after you leave
  this page.

  ACL2 was used at [31;1mMotorola Government Systems[0m to certify several
  microcode programs for the [31;1mMotorola CAP digital signal processor[0m,
  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 --- 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 [3mIndustrial-Strength
  Formal Methods[0m. Springer-Verlag, 1999.)

  ACL2 was used at [31;1mAdvanced Micro Devices[0m (AMD) to verify the
  compliance of the [31;1mAMD Athlon[0m'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 [31;1mAMD
  K5[0m. 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''.  [3mFormal Methods in System Design[0m Special Issue on
  Arithmetic Circuits, 1997.)

  ACL2 was used at [31;1mIBM[0m to verify the floating point divide and square
  root on the [31;1mIBM Power 4[0m.  (See Jun Sawada. ``Formal verification of
  divide and square root algorithms using series calculation''. In
  [3mProceedings of the ACL2 Workshop 2002[0m, Grenoble, April 2002.)

  ACL2 was used to verify floating-point addition/subtraction
  instructions for the [31;1mmedia unit[0m from [31;1mCentaur Technology[0m'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 [3mCAV '09: Proceedings of the 21st International[0m
  [31;1mConference on Computer Aided Verification[0m, pages 353--367, Berlin,
  Heidelberg, 2009. Springer-Verlag.)

  [31;1mRockwell Collins[0m used ACL2 to prove information flow properties about
  its [31;1mAdvanced Architecture MicroProcessor 7 Government Version
  (AAMP7G)[0m, 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 [3mDesign and Verification of Microprocessor
  Systems for High-Assurance Applications[0m, David S. Hardin, ed.,
  pages 175--191, Springer US, 2010.)

  Key properties of the [31;1mSun Java Virtual Machine[0m and its [31;1mbytecode
  verifier[0m were verified in ACL2. Among the properties proved were
  that certain invariants are maintained by [31;1mclass loading[0m and that
  the bytecode verifier ensures that execution is safe. In addition,
  various [31;1mJVM bytecode programs[0m have been verified using this model
  of the JVM.  (See Hanbing Liu. [3mFormal Specification and[0m
  [3mVerification of a JVM and its Bytecode Verifier[0m. PhD thesis,
  University of Texas at Austin, 2006.)

  The [31;1mBoyer-Moore fast string searching algorithm[0m 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 [3mEngineering
  Methods and Tools for Software Safety and Security[0m pages 267--284.
  IOS Press, 2009.)

  ACL2 was used to verify the fidelity between an [31;1mACL2-like theorem
  prover[0m and a simple (``trusted by inspection'') [31;1mproof checker[0m,
  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.
  [3mMilawa: A Self-Verifying Theorem Prover[0m.  Ph.D. Thesis, University
  of Texas at Austin, December, 2009.)

  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.  In addition, see {Books and Papers
  about ACL2 and its Applications |
  http://www.cs.utexas.edu/users/moore/publications/acl2-papers.html}.
  Also, see the presentations in each of the {ACL2 Workshops |
  http://www.cs.utexas.edu/users/moore/acl2/workshops.html}.")
 (INTERFACING-TOOLS
  (TOP ACL2)
  "Libraries and tools for doing basic file i/o (see [STD/IO]), using
  raw Common Lisp libraries (see [QUICKLISP]), working with the
  operating system (see [OSLIB]), and interfacing with other programs
  (see [BRIDGE]).


Subtopics

  [Command-line]
      Handling of command-line arguments when ACL2 is invoked

  [Defttag]
      Introduce a trust tag (ttag)

  [Io]
      Input/output facilities in ACL2

  [Save-exec]
      Save an executable image and a wrapper script

  [Startup-banner]
      Modifying the ACL2 startup banner

  [Sys-call]
      Make a system call to the host operating system")
 (INTERN
  (SYMBOLP PACKAGES ACL2-BUILT-INS)
  "Create a new symbol in a given package

  [47m(intern symbol-name symbol-package-name)[0m returns a symbol with the
  given [47m[symbol-name][0m and the given [47m[symbol-package-name][0m.  We
  restrict Common Lisp's [47mintern[0m 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 [intern$].

  In ACL2 [47mintern[0m is actually implemented as a macro that expands to a
  call of a similar function whose second argument is a symbol.
  Invoke [47m:pe intern[0m to see the definition, or see
  [intern-in-package-of-symbol].

  To see why [47mintern[0m is so restricted consider [47m(intern \"X\" \"P\")[0m.  In
  particular, is it a symbol and if so, what is its
  [47m[symbol-package-name][0m?  One is tempted to say ``yes, it is a symbol
  in the package [47m\"P\"[0m.'' But if package [47m\"P\"[0m has not yet been defined,
  that would be premature because the imports to the package are
  unknown.  For example, if [47m\"P\"[0m were introduced with

    (defpkg \"P\" '(LISP::X))

  then in Common Lisp [47m(symbol-package-name (intern \"X\" \"P\"))[0m returns
  [47m\"LISP\"[0m.

  The obvious restriction on [47mintern[0m 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
  [47m[intern-in-package-of-symbol][0m 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.")
 (INTERN$
  (SYMBOLP PACKAGES ACL2-BUILT-INS)
  "Create a new symbol in a given package

  [47mIntern$[0m is a macro that behaves the same as the macro [47m[intern][0m,
  except for weakening the restriction to a fixed set of package
  names so that any package name other than [47m\"\"[0m is legal.  See
  [intern].  Note that if you evaluate a call [47m(intern$ x y)[0m for which
  there is no package with name [47my[0m that is known to ACL2, you will get
  an error.

  [47m(Intern$ x y)[0m expands to:

    (intern-in-package-of-symbol x (pkg-witness y))

  See [intern-in-package-of-symbol] and see [pkg-witness].")
 (INTERN-IN-PACKAGE-OF-SYMBOL
  (SYMBOLP PACKAGES ACL2-BUILT-INS)
  "Create a symbol with a given name

  Completion Axiom ([47mcompletion-of-intern-in-package-of-symbol[0m):

    (equal (intern-in-package-of-symbol x y)
           (if (and (stringp x)
                    (symbolp y))
               (intern-in-package-of-symbol x y)
             nil))

  [Guard] for [47m(intern-in-package-of-symbol x y)[0m:

    (and (stringp x) (symbolp y))

  Intuitively, [47m(intern-in-package-of-symbol x y)[0m creates a symbol with
  [47m[symbol-name][0m [47mx[0m [intern]ed in the package containing [47my[0m.  More
  precisely, suppose [47mx[0m is a string, [47my[0m is a symbol with
  [47m[symbol-package-name][0m pkg and that the [47m[defpkg][0m event creating pkg
  had the list of symbols imports as the value of its second
  argument.  Then [47m(intern-in-package-of-symbol x y)[0m returns a symbol,
  ans, the [47m[symbol-name][0m of ans is [47mx[0m, and the [47m[symbol-package-name][0m
  of ans is pkg, unless [47mx[0m is the [47m[symbol-name][0m of some member of
  imports with [47m[symbol-package-name][0m ipkg, in which case the
  [47m[symbol-package-name][0m of ans is ipkg.  Because [47m[defpkg][0m requires
  that there be no duplications among the [47m[symbol-name][0ms of the
  imports, [47mintern-in-package-of-symbol[0m is uniquely defined.

  For example, suppose [47m\"MY-PKG\"[0m was created by

    (defpkg \"MY-PKG\" '(ACL2::ABC LISP::CAR)).

  Let [47mw[0m be [47m'my-pkg::witness[0m.  Observe that

    (symbolp w) is t                     ; w is a symbol
    (symbol-name w) is \"WITNESS\"         ; w's name is \"WITNESS\"
    (symbol-package-name w) is \"MY-PKG\"  ; w is in the package \"MY-PKG\"

  The construction of [47mw[0m illustrates one way to obtain a symbol in a
  given package: write it down as a constant using the double-colon
  notation.

  But another way to obtain a symbol in a given package is to create it
  with [47mintern-in-package-of-symbol[0m.

    (intern-in-package-of-symbol \"XYZ\" w) is MY-PKG::XYZ

    (intern-in-package-of-symbol \"ABC\" w) is ACL2::ABC

    (intern-in-package-of-symbol \"CAR\" w) is LISP::CAR

    (intern-in-package-of-symbol \"car\" w) is MY-PKG::|car|")
 (INTERRUPTS (POINTERS)
             "See [abort-soft].")
 (INTERSECTION$
  (LISTS ACL2-BUILT-INS)
  "Elements common to the given lists

    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

  [47m(Intersection$ x y)[0m equals a list that contains the [47mmember[0ms of [47mx[0m that
  are also [47mmember[0ms of [47my[0m.  More precisely, the resulting list is the
  result of deleting from [47mx[0m those members that are not members of [47my[0m.
  The optional keyword, [47m:TEST[0m, has no effect logically, but provides
  the test (default [47m[eql][0m) used for comparing members of the two
  lists.

  [47mIntersection$[0m need not take exactly two arguments, though it must
  take at least one argument: [47m(intersection$ x)[0m is [47mx[0m, [47m(intersection$
  x y z ... :test test)[0m is [47m(intersection$ x (intersection$ y z ...
  :test test) :test test)[0m, and if [47m:TEST[0m is not supplied, then
  [47m(intersection$ x y z ...)[0m is [47m(intersection$ x (intersection$ y z
  ...))[0m.  For the discussion below we restrict ourselves, then, to
  the cases [47m(intersection$ x y)[0m and [47m(intersection$ x y :test test)[0m.

  The [guard] for a call of [47mintersection$[0m (in the two cases just above)
  depends on the test.  In all cases, both arguments must satisfy
  [47m[true-listp][0m.  If the test is [47m[eql][0m, then one of the arguments must
  satisfy [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then one of the
  arguments must satisfy [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mintersection$[0m and its variants:

      [47m(intersection-eq x lst)[0m is equivalent to [47m(intersection$ x lst :test
      'eq)[0m;

      [47m(intersection-equal x lst)[0m is equivalent to [47m(intersection$ x lst
      :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mintersection-equal[0m.

  Note that [47mintersection-eq[0m can take any positive number of arguments,
  in analogy to [47mintersection$[0m; indeed, [47m(intersection-eq ...)[0m expands
  to [47m(intersection$ ... :test 'eq)[0m.  However, [47mintersection-equal[0m is a
  function, not a macro, and takes exactly two arguments.

  [47mIntersection$[0m is similar to the Common Lisp primitive [47mintersection[0m.
  However, Common Lisp does not specify the order of elements in the
  result of a call of [47mintersection[0m.

  [31;1mFunction: [0m<intersection-equal>

    (defun intersection-equal (l1 l2)
      (declare (xargs :guard (and (true-listp l1) (true-listp l2))))
      (cond ((endp l1) nil)
            ((member-equal (car l1) l2)
             (cons (car l1)
                   (intersection-equal (cdr l1) l2)))
            (t (intersection-equal (cdr l1) l2))))")
 (INTERSECTION-EQ (POINTERS)
                  "See [intersection$].")
 (INTERSECTION-EQUAL (POINTERS)
                     "See [intersection$].")
 (INTERSECTION-THEORIES
  (THEORIES THEORY-FUNCTIONS)
  "Intersect two [theories]

    Example:
    (intersection-theories (current-theory :here)
                           (theory 'arith-patch))

    General Form:
    (intersection-theories th1 th2)

  where [47mth1[0m and [47mth2[0m are theories (see [theories]).  To each of the
  arguments there corresponds a runic theory.  This function returns
  the intersection of those two runic [theories], represented as a
  list and ordered chronologically.

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].")
 (INTERSECTP
  (LISTS ACL2-BUILT-INS)
  "Test whether two lists intersect

    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

  [47m(Intersectp l1 l2)[0m returns [47mt[0m if [47ml1[0m and [47ml2[0m have a [47m[member][0m in common,
  else it returns [47mnil[0m.  The optional keyword, [47m:TEST[0m, has no effect
  logically, but provides the test (default [47m[eql][0m) used for comparing
  members of the two lists.

  The [guard] for a call of [47mintersectp[0m depends on the test.  In all
  cases, both arguments must satisfy [47m[true-listp][0m.  If the test is
  [47m[eql][0m, then one of the arguments must satisfy [47m[eqlable-listp][0m.  If
  the test is [47m[eq][0m, then one of the arguments must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mintersectp[0m and its variants:

      [47m(intersectp-eq x lst)[0m is equivalent to [47m(intersectp x lst :test 'eq)[0m;

      [47m(intersectp-equal x lst)[0m is equivalent to [47m(intersectp x lst :test
      'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mintersectp-equal[0m.

  [31;1mFunction: [0m<intersectp-equal>

    (defun intersectp-equal (x y)
      (declare (xargs :guard (and (true-listp x) (true-listp y))))
      (cond ((endp x) nil)
            ((member-equal (car x) y) t)
            (t (intersectp-equal (cdr x) y))))")
 (INTERSECTP-EQ (POINTERS)
                "See [intersectp].")
 (INTERSECTP-EQUAL (POINTERS)
                   "See [intersectp].")
 (INTRODUCTION-TO-A-FEW-SYSTEM-CONSIDERATIONS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "The mechanics of interaction with the theorem prover

  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 [47mdefthm[0m.

  Most people use Emacs (see [Emacs] {ICON} (see
  [A_Tiny_Warning_Sign])) or the ACL2 Sedan (Eclipse) interface (see
  [ACL2-Sedan] {ICON} (see [A_Tiny_Warning_Sign])).  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.

  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 [3mInterrupt Session[0m 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., [47m:q[0m
  for GCL and CCL).  You can usually determine what environment
  you're in by paying attention to the prompt, which we discuss
  below.

  The ACL2 ``interactive loop'' is called [47m[lp][0m ({ICON} (see
  [A_Tiny_Warning_Sign])) and is generally invoked automatically from
  your Common Lisp when you start up the ACL2 process.  [47mLP[0m is just a
  special case of an ACL2 function called [47m[ld][0m {ICON} (see
  [A_Tiny_Warning_Sign]), 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 ``[47m-ld-[0m'' in their names!

  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

    ACL2 !>

  The ``[47mACL2[0m'' 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 [current-package] {ICON} (see
  [A_Tiny_Warning_Sign])).  You could create a new namespace (see
  [defpkg] {ICON} (see [A_Tiny_Warning_Sign])) and set the current
  package to it (see [in-package] {ICON} (see
  [A_Tiny_Warning_Sign])).  The next part of the prompt above
  (``[47m![0m''), the exclamation mark) tells you that before ACL2 evaluates
  your type-in it will check to see whether [47m[guard][0ms ({ICON} (see
  [A_Tiny_Warning_Sign])) 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.''

  If the exclamation mark is missing from the prompt,

    ACL2 >

  then evaluation occurs strictly according to the ACL2 axioms, without
  regard for any declared guards.

  You can switch between these two prompts by typing

    ACL2 !>:set-guard-checking nil

  to turn guard checking off and

    ACL2 >:set-guard-checking t

  to turn it on.  Try typing [47m(car 7)[0m to each prompt.

  If there is a ``[47mp[0m'' in the prompt,

    ACL2 p!>

  with or without the exclamation mark:

    ACL2 p>

  it means you are in [47m:[0m[47m[program][0m ({ICON} (see [A_Tiny_Warning_Sign]))
  mode rather than [47m:[0m[47m[logic][0m ({ICON} (see [A_Tiny_Warning_Sign]))
  mode.  In [47m:program[0m mode, [47mdefun[0m 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 [47mdefthm[0m.  [47m:Program[0m mode
  is often used to prototype a model.

  Most commands are just typical parenthesized Lisp expressions, like

    ACL2 !>(defthm rev-rev
             (implies (true-listp x)
                      (equal (rev (rev x)) x)))

  but some are typed as keywords followed by a certain number of
  arguments.

  For example, to undo the last event you may type

    ACL2 !>:u

  or to undo back through the introduction of [47mrev[0m you may type

    ACL2 !>:ubt rev

  The first is equivalent to evaluating [47m(u)[0m and the second is
  equivalent to evaluating [47m(ubt 'rev)[0m.  See [keyword-commands] {ICON}
  (see [A_Tiny_Warning_Sign]).  So if you see a sentence like ``to
  turn on the break rewrite facility, execute [47m:brr t[0m,'' we mean type

    ACL2 !>:brr t

  or equivalently

    ACL2 !>(brr t)

  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 [47mLD[0m recursively, the prompt ``gets
  deeper,'' e.g.,

    ACL2 !>>

  and you can pop out one level with [47m:[0m[47m[q][0m {ICON} (see
  [A_Tiny_Warning_Sign]) (for ``quit'') or pop to the outermost ACL2
  loop with [47m:[0m[47mabort![0m {ICON} (see [A_Tiny_Warning_Sign]).  If you are
  in the outermost call of the ACL2 interactive loop and you type [47m:q[0m,
  you pop out into raw lisp, which carries some risk; 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
  [prompt].  To get back into the ACL2 interactive loop from raw
  lisp, evaluate [47m(LP)[0m.

  If you see a prompt that looks like an ACL2 prompt but has a number
  in front of it, e.g.,

    1 ACL2 >

  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 [47m:brr t[0m, 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 [47mdefthm[0m) inside that break will be lost when you exit
  the break.

  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 [47m:[0m[47m[abort!][0m.

  If you discover you've been working in a [47mbrr[0m break, exit, turn off
  the break facility with [47m:brr nil[0m, and redo whatever [47mdefun[0ms and
  [47mdefthm[0ms you did while in that break.

  Users of the Emacs interface may occasionally type commands directly
  in the [47m*shell*[0m buffer running ACL2.  This can be ``dangerous'' for
  two reasons.  One is that if you type an event, like a [47mdefun[0m or
  [47mdefthm[0m, 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 [47mdefthm[0m
  below after you've typed the ``[47m(implies (true-listp x)[0m'' you will
  confuse the Lisp parser because it has already read ``[47m(defthm
  rev-rev[0m''.

    ACL2 !>(defthm rev-rev
             (implies (true-listp x)

  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.

  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.

  The fundamental lesson is that you should pay attention to the prompt
  and learn what the different prompts mean --- or use the ACL2
  Sedan.

  If you have been working your way through the tutorial introduction
  to the theorem prover, use your browser's [31;1mBack Button[0m now to return
  to [introduction-to-the-theorem-prover].")
 (INTRODUCTION-TO-APPLY$
  (APPLY$)
  "Background knowledge on how to use [47m[apply$][0m, [47m[defwarrant][0m, etc.


Background and Organization

  [47mApply$[0m is the ACL2 version of LISP's [47mapply[0m function.  It takes a
  ``function'' and a list of argument values, applies the function to
  the arguments, and returns the result.  For example, [47m(apply$ 'expt
  (list 2 8))[0m returns 256.

  A good introduction to the basic ideas and challenges of adding
  [47mapply$[0m to ACL2 is the paper {``Limited Second-Order Functionality
  in a First-Order Setting'' |
  http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by
  Matt Kaufmann and J Strother Moore, [3mJournal of Automated Reasoning[0m,
  Springer, [31;1m64[0m, 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 [47mapply$[0m 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
  [47mbooks/projects/apply-model/[0m.  See the [47mREADME[0m file there.

  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 [47mapply$[0m 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.

  This topic links to reference-level documentation for [47m[apply$][0m and
  those other concepts.  But if you are just getting started with
  [47mapply$[0m we recommend that you work your way through this topic,
  including doing the examples described below, without following all
  the links.


Challenges and Basic Solutions

  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 `[tame] functions' (which are in fact [3mnot[0m 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.

  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 [47mapply$[0m and we use
  lowercase when we're using the symbol as a function symbol in a
  term.

  ``Tameness'' imposes strict rules on how functional arguments are
  used.  We'll discuss it further below.

  The fundamental question raised by [47mapply$[0m is ``How can [47mapply$[0m 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 [47mmy-append[0m, how can [47mapply$[0m
  know that [47m(apply$ 'MY-APPEND (list a b))[0m should expand to
  [47m(my-append a b)[0m?

  The ACL2 primitives can be built in.  The logical definition of
  [47mapply$[0m includes a big case split that recognizes about 800 ACL2
  primitives, so that for example:

    (apply$ 'car (list a)) = (car a)

  and

    (apply$ 'assoc-equal (list a b)) = (assoc-equal a b).

  But user-defined functions are problematic because once [47mapply$[0m has
  been defined in the ACL2 sources it cannot be extended to handle
  new symbols.

  Intuitively, if you have defined the [47mn[0m-ary function [47mfoo[0m then you
  would expect [47m(apply$ 'foo (list a1...an))[0m to be [47m(foo a1...an)[0m.  One
  way to arrange that might be to leave [47mapply$[0m undefined on the
  symbol [47mfoo[0m but to assume, as by a new axiom or hypothesis,

    forall a1...an : (apply$ 'foo (list a1...an)) = (foo a1...an).

  It will turn out that using new axioms for this purpose is a bad
  idea.  Hiding the link between [47mapply$[0m and new symbols in axioms
  raises a problem with ACL2's notion of [47m[local][0m.  This is called
  ``the [47mLOCAL[0m problem'' and we illustrate it later in this doc topic.
  But for that reason, the suppositions extending [47mapply$[0m will take
  the form of hypotheses to be added to conjectures in which the
  behavior of [47mapply$[0m on new symbols is important.  These hypotheses
  are called ``[47m[warrant][0ms.''

  Warrant (Merriam-Webster): (noun) a commission or document giving
  authority to do something....

  In our case, a warrant for [47mfn[0m gives [47mapply$[0m permission to apply [47mfn[0m
  under some circumstances, by asserting a universally quantified
  conditional equality about [47mapply$[0m's behavior on [47m'fn[0m. It also tells
  [47mapply$[0m and the [tame]ness predicates things like how many arguments
  [47mfn[0m takes and how it uses them by asserting the [47m[badge][0m of [47m'fn[0m.  The
  [47mbadge[0m of [47mfn[0m is an ACL2 object that contains various tokens
  interpretable by [47mapply$[0m and the tameness predicates.

  But there is a fundamental logical problem: it is not always possible
  to satisfy such suppositions. There may be no way that [47mapply$[0m could
  handle [47mfn[0m.  An example of a [47mfn[0m for which that hypothesis is
  unsatisfiable is

    (defun russell (x y) (not (apply$ x (list y y)))).

  This definition of [47mrussell[0m is not recursive: it does not call itself.
  So this definition is admissible.  But if we had a warrant for
  [47mapply$[0m and that [47mwarrant[0m were as simple as

    forall x,y : (apply$ 'russell (list x y)) = (russell x y)

  then we would have this classical problem with self-reference:

    (russell 'russell 'russell)
    =                                      {def russell}
    (not (apply$ 'russell (list 'russell 'russell)))
    =                                      {warrant russell}
    (not (russell 'russell 'russell))

  which is contradictory.

  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'' [47mapply$[0m to handle them.

  It should be pretty clear that if the user defines an ACL2 function
  that in no way depends on [47mapply$[0m, e.g., a function like:

    (defun sq (x) (* x x))

  then the hypothesis

    forall x : (apply$ 'SQ (list x)) = (sq x)

  is satisfiable: we could have introduced [47msq[0m before [47mapply$[0m and then
  defined [47mapply$[0m in the first place to handle that particular symbol.

  [47mSq[0m 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 [47mapply$[0m while maintaining the soundness of the resulting theory.

  For example, consider the following function, which maps a given
  function over a list and collects the results.

    (defun my-collect$ (fn lst)
      (if (endp lst)
          nil
          (cons (apply$ fn (list (car lst)))
                (my-collect$ fn (cdr lst)))))

  Our definition of tameness considers [47m(my-collect$ 'SQ lst)[0m to be a
  tame expression, even though [47mmy-collect$[0m calls [47mapply$[0m.  The reason
  we can allow this is that in this particular call of [47mmy-collect$[0m
  the function to be applied is itself tame.  But if [47m(my-collect$ 'SQ
  lst)[0m is a tame expression, then [47m'(LAMBDA (LST) (MY-COLLECT$ 'SQ
  LST))[0m is a tame function and thus

    (my-collect$ '(LAMBDA (LST) (MY-COLLECT$ 'SQ LST)) z)

  is a tame expression.  So, for example, at the top-level of ACL2 one
  can do this:

    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))

  Of course, this presumes we have defined [47msq[0m and [47mmy-collect$[0m and have
  analyzed them to make sure they have the appropriate tameness
  properties.  (Note that [47mmy-collect$[0m is not tame, but the way it
  uses its ``functional'' argument is crucial to the tameness of
  [47m(my-collect$ 'SQ lst)[0m.)  To use [47mapply$[0m 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 [47mapply$[0m it is convenient to define it with the new
  command [47m[defun$][0m, which is just an ordinary [47m[defun][0m followed by a
  [47m[defwarrant][0m command.  If you've already defined the function and
  then realize you wish to [47mapply$[0m it, you can call [47mdefwarrant[0m
  yourself.

  [47mDefwarrant[0m analyzes a [47m:[0m[47m[logic][0m mode definition and produces a badge
  and a warrant, if possible.  Also relevant is the [47m[defbadge][0m
  command which issues a badge for a function (if possible) but does
  not issue a warrant.  Its primary purpose is to allow [47m:[0m[47mprogram[0m mode
  functions to be analyzed and badged so they can be safely executed
  by [47mapply$[0m at the top-level ACL2 loop.  But the present discussion
  focuses primarily on the logical machinery, which requires
  warrants.

  We explain further via an annotated example, starting from scratch
  but from the basic background just sketched.  For many additional
  examples, see [community-books] [47mbooks/projects/apply/report.lisp[0m
  which is a certified book containing the examples in the paper.

  [31;1mNote carefully:[0m the directory [47mbooks/projects/apply-model/[0m, mentioned
  earlier in conjunction with the paper, is different from the
  directory [47mbooks/projects/apply/[0m just mentioned!  The former
  directory concerns the logical foundations of [47mapply$[0m as they stood
  when the paper was written.  The latter is more directly relevant
  to ACL2 users and provides useful lemmas about [47mapply$[0m as it is
  axiomatized and implemented today.  It also includes many example
  theorems.


Exercises and Lessons

  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.

    ACL2 !>(defun sq (x) (* x x))

    ACL2 !>(defun rev (x)
             (if (endp x)
                 nil
                 (append (rev (cdr x)) (list (car x)))))

  [31;1mLesson 0:[0m Learn about [47mapply$[0m by reading this tutorial introduction.
  But this tutorial mentions many undefined concepts: tameness,
  warrants, badges, ilks.  These concepts are intertwined with [47mapply$[0m
  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 --- we'll try to
  give you a sense of what they mean.

  [31;1mLesson 1:[0m To use [47mapply$[0m, be sure to include the following book of
  lemmas.  These lemmas are important not just to proving theorems
  about [47mapply$[0m but to defining functions that use [47mapply$[0m.

    ACL2 !>(include-book \"projects/apply/top\" :dir :system)

  [31;1mLesson 2:[0m To allow [47mapply$[0m to ``work'' on a function symbol the symbol
  must be ``warranted.'' Actually, of course, you can pass anything
  to [47mapply$[0m and the axioms will reduce it to some value: ACL2 is
  untyped and all functions are total!  But [47mapply$[0m won't work in the
  logic as you expect if the first argument to [47mapply$[0m is not
  warranted!  (And [47mapply$[0m 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 [47msq[0m and [47mrev[0m do:

    ACL2 !>(defwarrant sq)

    ACL2 !>(defwarrant rev)

  [47m[Defwarrant][0m checks that its argument, [3mfn[0m, 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 [47mapply$[0m to ``work'' without causing
  logical contradictions.  [47mDefwarrant[0m causes an error if [3mfn[0m does not
  obey our rules.  But if [47mdefwarrant[0m does not cause an error it
  produces a ``badge'' for [3mfn[0m that describes which formals are
  treated as ``functions.'' Henceforth, we'll say such formals have
  ``[ilk]'' [47m:FN[0m.  In addition to computing a badge, non-erroneous
  calls of [47mdefwarrant[0m introduce a ``[47m[warrant][0m function'' for [3mfn[0m.  The
  warrant function for [3mfn[0m is a 0-ary function named
  [47mapply$-warrant-[0m[3mfn[0m.  A call of the warrant function, i.e., the term
  [47m(apply$-warrant-[0m[3mfn[0m[47m)[0m is called the ``warrant'' for [3mfn[0m and if the
  warrant for [3mfn[0m is included among the hypotheses of a conjecture
  then [47m(apply$ '[0m[3mfn[0m[47m (list a1 ... an))[0m can expand to [47m([0m[3mfn[0m[47m a1 ... an)[0m,
  provided the [47mai[0m meet the tameness requirements required by [3mfn[0m's
  badge.

  [31;1mLesson 3:[0m We'll say more about tameness, badges, and warrants later.
  You already know that warrants can only be issued for [47m:logic[0m 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 [47mapply$[0m: (i) [47mApply$[0m does not take [47m[state][0m
  or [stobj] arguments and so cannot call any function that takes
  [47mSTATE[0m or [47mstobj[0m arguments.  (ii) [47mApply$[0m cannot call a function whose
  measure, well-founded relation, or domain predicate depends on
  [47mapply$[0m. (iii) [47mApply$[0m cannot call a function that itself uses [47mapply$[0m
  unless that function's measure is a natural number or a
  lexicographic combination of naturals formed with [47mllist[0m as defined
  in the Community Books at [47mbooks/ordinals/[0m. (iv) [47mApply$[0m cannot call
  a function that itself uses [47mapply$[0m if that function was defined
  mutually recursively.  Another way of saying all this is that
  [47mdefwarrant[0m will cause an error if you try to warrant a function
  violating (i), (ii), (iii) or (iv).

  [31;1mLesson 4:[0m If you want to define a function and immediately call
  [47mdefwarrant[0m on it you can use the handy macro [47mdefun$[0m.  We'll use
  [47mdefun$[0m freely below.

  [31;1mLesson 5:[0m You can define functions that take warranted ``functions''
  as arguments and [47mapply$[0m 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 [47mmy-collect$[0m
  ``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
  [scion]s of [47mapply$[0m.  In ordinary English usage, a ``scion'' is a
  descendent of an important family or individual; our scions are
  ``descendents'' of [47mapply$[0m and inherit its power and restrictions.

    ACL2 !>(defun$ my-collect$ (fn lst)
             (if (endp lst)
                 nil
                 (cons (apply$ fn (list (car lst)))
                       (my-collect$ fn (cdr lst)))))

  In this definition, the first argument has ilk [47m:FN[0m because it is used
  exclusively as a ``function:'' it reaches the first argument of
  [47mapply$[0m and is untouched otherwise.  The second argument has ilk [47mNIL[0m
  and we say it's ``ordinary.'' It is [3mnever[0m used as a function.

  Note: We define [47mmy-collect$[0m with [47mdefun$[0m simply to illustrate [47mdefun$[0m.
  Unless we mean to pass [47mmy-collect$[0m to [47mapply$[0m or to some scion in
  the future, there is no reason to have a warrant for [47mmy-collect$[0m.
  Had we defined [47mmy-collect$[0m with the ordinary [47mdefun[0m and realized
  later that we want to pass [47m'MY-COLLECT$[0m into a slot of ilk [47m:FN[0m, we
  could get a warrant for [47mmy-collect$[0m by calling [47m(defwarrant
  my-collect$)[0m.

  Actually, the function [47mcollect$[0m is pre-defined in ACL2 and behaves
  like [47mmy-collect$[0m.  We chose to introduce [47mmy-collect$[0m 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.

    (defun$ always$ (fn lst)
      (if (endp lst)
          t
          (and (apply$ fn (list (car lst)))
               (always$ fn (cdr lst)))))

  It checks that every element of [47mlst[0m satisfies its [47m:FN[0m argument [47mfn[0m.

  The reason that both [47mcollect$[0m and [47malways$[0m are pre-defined is that
  they are part of the support for the [47m[loop$][0m statment.

  [31;1mLesson 6:[0m You can run scions on warranted function symbols:

    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))

  You might wonder why you can run [47mmy-collect$[0m on [47m'SQ[0m --- which
  evaluates [47mapply$[0m on [47m'SQ[0m --- without explicitly acknowledging the
  warrant that links [47m(apply$ 'SQ (list a))[0m to [47m(sq a)[0m.  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.

  [31;1mLesson 7:[0m You can run scions on tame quoted [47mLAMBDA[0m objects.  These
  [47mLAMBDA[0m objects can even include calls of scions, provided they are
  tame.

    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))

  Note that the ``function symbols'' in the ``body'' of a quoted [47mLAMBDA[0m
  object may reach [47mapply$[0m as the [47mLAMBDA[0m object is applied.

  [47mLAMBDA[0m objects are just quoted list expressions that start with the
  symbol [47mLAMBDA[0m and look like lambda-expressions.  But quoted [47mLAMBDA[0m
  objects have to have fully translated bodies and meet other
  restrictions so [47mapply$[0m can interpret them.  You cannot use macros
  like [47m+[0m or [47mcond[0m and must you quote all constants.  We urge you not
  to try to type quoted [47mLAMBDA[0m objects by hand!  Instead, we provide
  a macro, [47m[lambda$][0m, that allows you to write lambda expressions in
  untranslated form.

  [31;1mLesson 8:[0m There are three very similar looking but very different
  notions used in this documentation: lambda expressions, [47mLAMBDA[0m
  objects, and [47mlambda$[0m expressions.  Read carefully!  See [47m[lambda][0m
  for some definitions and disambiguation help.  The [47mLAMBDA[0m objects
  reaching [47mapply$[0m must be fully translated (and tame) to be handled
  correctly.  The special macro [47mlambda$[0m will translate for you.

    ; 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)

  [31;1mLesson 9:[0m Almost all ACL2 primitives are known to [47mapply$[0m.  For a
  complete list of the built-ins evaluate

    (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP
                    APPLY$ EV$)
            (strip-cars *badge-prim-falist*))

  You can freely use these ACL2 primitives with [47mapply$[0m and in your
  [47mlambda$[0m expressions, without warrants.

  [31;1mLesson 10:[0m You can prove and use theorems about scions.

    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))))

  Notice that the lemma [47mmy-collect$-append[0m talks about an arbitrary [47mfn[0m.
  The definition of [47mapply$[0m is completely irrelevant to this theorem!
  Once [47mmy-collect$-append[0m has been proved can be instantiated with
  anything for [47mfn[0m.  This is demonstrated when the [47mthm[0m above is
  proved: the proof is just to rewrite with [47mmy-collect$-append[0m.
  Notice that the only function being [47mapply$[0m'd in the [47mthm[0m above is
  the primitive multiplication function, which is built into apply$.

  [31;1mLesson 11:[0m But when your theorems depend on the behavior of [47mapply$[0m on
  particular user-defined functions, you will need to provide
  hypotheses stipulating the behavior of [47mapply$[0m on those values.
  Those hypotheses are the [3mwarrants[0m for the (non-primitive) function
  symbols involved.  Here is an example: Recall the function [47msq[0m
  defined and warranted above.  We might wish to prove that if [47mlst[0m is
  a list of integers then [47m(my-collect$ 'SQ lst)[0m is a list of natural
  numbers.  We can use [47malways$[0m to express the notions of ``list of
  integers'' and ``list of naturals.'' We could try to state the
  conjecture this way:

    ACL2 !>(thm (implies (always$ 'INTEGERP lst)
                         (always$ 'NATP (my-collect$ 'SQ lst)))).

  But the attempt to prove that formula will fail because it depends on
  the fact that the [47msq[0m of an integer is a natural [3mand on the
  assumption that[0m [47m(apply$ 'SQ (list x))[0m [3mis[0m [47m(sq x)[0m.  That assumption
  is what the [3mwarrant[0m for [47msq[0m tells us.  Thus, the warrant for [47msq[0m is
  required as a hypothesis!  The following theorem can be proved.

    ACL2 !>(defthm all-natp-collect$-sq
             (implies (and (warrant sq)
                           (always$ 'INTEGERP lst))
                      (always$ 'NATP (collect$ 'SQ lst))))

  Note that we don't need to provide warrants for [47mintegerp[0m or [47mnatp[0m
  because they are ACL2 primitives and thus built into the behavior
  of [47mapply$[0m.  But we must provide the warrant for [47msq[0m because we know
  the proof depends on [47m(apply$ 'sq (list x1 ...))[0m simplifying to [47m(sq
  x1)[0m.

  The macro form [47m(warrant f1 ... fk)[0m expands to the conjunction of the
  warrants for the [47mfi[0ms.  That is

    (warrant f1 ... fk)
    =
    (and (apply$-warrant-f1)
         ...
         (apply$-warrant-fk)).

  If you attempt a proof and it fails, and you see among the
  checkpoints terms of the form [47m(apply$ 'fn (list a1 ... an))[0m, then
  you probably forgot to call [47mdefwarrant[0m on [47mfn[0m and [47mapply$[0m doesn't
  know what to do with that symbol!  If, on the other hand, you see a
  [forcing-round] checkpoint that is attempting to prove a warrant,
  like [47m(apply$-warrant-fn)[0m, then you probably forgot to add the
  warrant for [47mfn[0m to the hypotheses of the conjecture you're trying to
  prove.

  [31;1mLesson 12:[0m Warrants solve the ``[47mLOCAL[0m problem.'' Imagine the trouble
  we'd be in if the theorem above did not require a warrant on [47msq[0m.
  We could get away with this:

    (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))))

  This would be a disaster because the final [47mthm[0m is invalid since [47m(sq
  -2)[0m here is [47m-8[0m and yet the [47mthm[0m is trivially proved by appealing to
  the unwarranted theorem exported from the encapsulate.

  If we could prove the unwarranted theorem we could export it because
  it does not mention or depend on the locally defined function [47msq[0m,
  it just mentions the constant symbol [47m'SQ[0m.  Fortunately, we cannot
  actually prove the unwarranted version of the theorem because there
  is no [3ma priori[0m connection between [47m(apply$ 'SQ (list x))[0m and [47m(sq x)[0m.
  And if we add the warrant for [47msq[0m to the [47mdefthm[0m in the encapsulate
  we can prove the theorem but then we cannot export it because the
  warrant ancestrally depends on locally defined function [47msq[0m.

  [31;1mLesson 13:[0m 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

    (defthm all-natp-collect$-sq
      (implies (and (warrant sq)
                    (always$ 'INTEGERP lst))
               (always$ 'NATP (collect$ 'SQ lst))))

  it just employs its usual first-order matching algorithm.  Thus, the
  lemma won't apply to

    (always$ 'NATP (collect$ (lambda$ (x) (* x x)) lst))

  because the constant symbol [47m'SQ[0m is not the same as the constant list
  generated by translating [47mlambda$[0m expression, [47m[47m'(LAMBDA (X) (BINARY-*
  X X))[0m[47m[0m, even though they are equivalent if understood as functions.
  See the discussion at [47m[fn-equal][0m.

  [31;1mLesson 14:[0m Recall Lesson 0!  Before you start to use [47mapply$[0m outside
  of this simple demo script, we advise you to read the documentation
  for [47mapply$[0m.

  [31;1mAn Advanced Lesson:[0m We conclude this tutorial by defining one of the
  most useful scions and proving a couple of theorems illustrating
  its flexibility: [47mfoldr[0m.

    ACL2 !>(defun$ foldr (lst fn init)
             (if (endp lst)
                 init
                 (apply$ fn
                         (list (car lst)
                               (foldr (cdr lst) fn init)))))

  Note that [47mfoldr[0m 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.

  When its functional argument is [47mCONS[0m [47mfoldr[0m is just the concatenation
  of its other two arguments:

    ACL2 !>(defthm foldr-cons
             (equal (foldr x 'CONS y)
                    (append x y)))

  We do not need a warrant for [47mcons[0m because it is built into [47mapply$[0m.
  In fact, the built-ins don't have warrants but if you unnecessarily
  list a primitive in a [47mwarrant[0m expression, like [47m(warrant foldr
  cons)[0m, it just ignores the primitives that are built into [47mapply$[0m.

  By supplying a certain [47mlambda[0m expression we can use [47mfoldr[0m to reverse
  its first argument:

    ACL2 !>(defthm foldr-can-be-rev
             (implies (warrant foldr)
                      (equal (foldr x
                                    (lambda$ (x y)
                                       (FOLDR y 'CONS (CONS x nil)))
                                    nil)
                             (rev x))))

  Note that the [47mlambda$[0m expression calls [47mFOLDR[0m.  Because of this, we
  must provide the warrant for [47mfoldr[0m since that inner [47mfoldr[0m will be
  applied by the outer [47mfoldr[0m.  This illustrates an important point
  made in Lesson 7 above: scions can apply other scions, including
  themselves, as long as the applications are tame.


Some Practice Problems

  There is no better way to learn than to practice.  So here are a few
  challenge problems.  The answers can be found in
  [47mbooks/projects/apply/answers-to-doc-intro-to-apply.lisp[0m.

  [31;1mProblem 1[0m: Assume [47mfn[0m is a binary relation.  Define [47m(insert$ e lst fn)[0m
  to insert [47me[0m into the list [47mlst[0m in front of the first element, [47md[0m, in
  [47mlst[0m such that [47m(fn e d)[0m is true.

  [31;1mProblem 2[0m: Define [47m(sort$ lst fn)[0m to be an insertion sort algorithm
  for the binary relation [47mfn[0m, e.g., to successively insert each
  element into the recursively sorted remaining elements.  (Note:
  There is no assurance that [47msort$[0m will actually produce a list
  ordered by [47mfn[0m because we don't know that [47mfn[0m is an ordering
  relation.)

  [31;1mProblem 3[0m: 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!)

    (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)

  [31;1mProblem 4[0m: Prove the following theorem suggested especially by the
  last example above.  To state this theorem we first introduce the
  familiar reverse function, [47mrev[0m.

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x))
                  (list (car x)))))

  and we use the pre-defined function [47m(when$ fn lst)[0m which computes the
  elements of [47mlst[0m satisfying the unary-function [47mfn[0m, in the order in
  which they occur, e.g., [47m(when$ '(1 a 2 b) 'symbolp)[0m is [47m'(a b)[0m.

  Prove

    (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))))))

  Lemmas will be needed.

  [31;1mProblem 5[0m: Define [47m(orderedp$ lst fn)[0m to check whether [47mfn[0m holds
  between each adjacent pair of elements in [47mlst[0m.  Test your function
  with

    (defthm examples-of-orderedp$
      (and (orderedp$ '(1 3 5 7) '<)
           (not (orderedp '(1 3 3 5 7) '<)))
      :rule-classes nil)

  [31;1mProblem 6[0m: You might hope that [47m(orderedp$ (sort$ lst fn) fn)[0m is a
  theorem.  But it is not as is easily shown by the example
  [47m(orderedp$ (sort$ '(3 1 5 3 7) '<) '<)[0m.  If you try to prove the
  conjecture and inspect the output you'll see that the proof fails
  because we do not know that [47m(or (fn x y) (fn y x))[0m is true.  That
  is, we don't know that [47mfn[0m is [3mStrongly Connected[0m.  How could we,
  since the conjecture is claimed for all [47mfn[0m?

  Unfortunately, it is awkward to state that [47mfn[0m 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!

  But we can prove versions of the conjecture for concrete strongly
  connected [47mfn[0ms.  The relation named [47mbefore-dayp[0m, below, is strongly
  connected, as demonstrated by the events following its definition.

  Carry out these events.

    (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))

  Now, prove the version of [47m(orderedp$ (sort$ lst fn) fn)[0m for the
  instance in which [47mfn[0m is [47m'before-dayp[0m.")
 (INTRODUCTION-TO-HINTS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "How to provide hints to the theorem prover

  We assume you've read [introduction-to-rewrite-rules-part-1],
  [introduction-to-key-checkpoints], and
  [introduction-to-the-database].

  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.

  The most common hint is to enable and/or disable a particular rule on
  some particular subgoal.

    (defthm [3mname[0m
            [3mformula[0m
            :hints ((\"Subgoal *1/3.2''\" :in-theory (disable nth-nthcdr))))

  The hint above tells the rewriter that just before it begins to work
  on [47mSubgoal *1/3.2''[0m it should switch to a local theory in which all
  of the rules generated from the event [47mnth-nthcdr[0m 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 [47m:in-theory[0m hint associated with
  it.  There are many kinds of hints besides [47m:in-theory[0m 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.

  The top-level goal is always named [47mGoal[0m.  Thus

    (defthm [3mname[0m
            [3mformula[0m
            :hints ((\"Goal\" ...[3mhints1[0m...)
                    (\"Subgoal *1/3.2''\" ...[3mhints2[0m...)))

  has the effect of using [3mhints1[0m for the top-level goal and all of its
  children throughout the entire proof, except for [47mSubgoal *1/3.2''[0m
  and its children, where [3mhints2[0m is used instead.

  There are a few hints which ``take effect'' exactly on the subgoal to
  which they are attached and are not inherited by their descendents.

  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
  ``{ICON} (see [A_Tiny_Warning_Sign])'') below until you have read
  the entire tutorial.

  See [in-theory] {ICON} (see [A_Tiny_Warning_Sign]) for how to enable
  and/or disable rules.  The new theory is computed by a ``theory
  expression'' (see [theories] {ICON} (see [A_Tiny_Warning_Sign]))
  such as [47m(disable nth-nthcdr)[0m 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

    (defthm [3mname[0m
            [3mformula[0m
            :hints ((\"Goal\" :in-theory (disable rule1))
                    (\"Subgoal *1/3.2''\" (disable rule2))))

  the theory mentioned for [47mGoal[0m is the global current theory minus
  [47mrule1[0m, while the theory mentioned for its descendant, [47mSubgoal
  *1/3.2''[0m, is the global current theory minus [47mrule2[0m.  In particular,
  if both [47mrule1[0m and [47mrule2[0m are enabled in the global current theory,
  then [47mrule1[0m is enabled during the processing of [47mSubgoal *1/3.2''[0m
  because it was not removed explicitly there.

  See [use] {ICON} (see [A_Tiny_Warning_Sign]) 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
  [47m:use[0m hint) is an enabled rewrite rule, it might interfere with the
  added hypothesis --- by rewriting itself to [47mT[0m --- and thus often
  you will both [47m:use ...[0m and [47m:in-theory (disable ...)[0m.

  See [expand] {ICON} (see [A_Tiny_Warning_Sign]) for how to tell the
  theorem prover to expand one or more function calls whenever
  encountered.

  See [cases] {ICON} (see [A_Tiny_Warning_Sign]) 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.

  See [induct] {ICON} (see [A_Tiny_Warning_Sign]) 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 descendents.

  See [hints] {ICON} (see [A_Tiny_Warning_Sign]) for a complete list of
  all hints, and see [hints-and-the-waterfall] {ICON} (see
  [A_Tiny_Warning_Sign]) for a more thorough description of how the
  effects of hints at a subgoal are inherited by the descendents.

  If you are reading this as part of the tutorial introduction to the
  theorem prover, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-the-theorem-prover].")
 (INTRODUCTION-TO-KEY-CHECKPOINTS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "What questions to ask at key checkpoints

  We assume you've read about rewrite rules; see
  [introduction-to-rewrite-rules-part-1].

  When a proof attempt fails, ACL2 prints some [3mkey checkpoints[0m.  These
  are formulas that we think you should look at.  There are two kinds
  printed: key checkpoints [3mbefore an induction[0m, and key checkpoints
  [3munder a top-level induction[0m.  (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.)

  Below is a list of questions to ask yourself about the key
  checkpoints.  Initially, we recommend just picking one key
  checkpoint [3mbefore[0m 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.

  [31;1m(1) Do you believe this formula is a theorem?[0m 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.

  [31;1m(2) Can it be simplified?[0m 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
  [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.

  [31;1m(3) Is the simpler fact already in the database?[0m 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
  [47m:[0m[47m[pl][0m {ICON} (see [A_Tiny_Warning_Sign]), [47m:[0m[47m[pc][0m {ICON} (see
  [A_Tiny_Warning_Sign]), [47m:[0m[47m[pbt][0m {ICON} (see [A_Tiny_Warning_Sign]),
  and other [3mhistory[0m commands to inspect the database; (see [history]
  {ICON} (see [A_Tiny_Warning_Sign])).  But if you find the allegedly
  relevant simpler fact in the database, you must ask: [31;1mwhy wasn't it
  used?[0m There are four principal reasons:

  (3a) it is disabled --- so enable it; you'll learn how when you read
  the coming sections on [introduction-to-the-database] and
  [introduction-to-hints].

  (3b) its left-hand side doesn't match the target --- 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 [3mundo[0m commands in [history] {ICON} (see
  [A_Tiny_Warning_Sign]).

  (3c) it is an [47mIFF[0m rule but the target doesn't occur propositionally
  --- so see if you you can strengthen the rule to an [47mEQUAL[0m 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 [3mundo[0m commands in [history] {ICON} (see
  [A_Tiny_Warning_Sign]).

  (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 ([47m:[0msee [brr] {ICON} (see
  [A_Tiny_Warning_Sign])) help you figure out why the rule failed, so
  use them and improve the rule, or the current conjecture, or the
  database as appropriate.

  [31;1m(4) If the simpler fact is not already known, prove it.[0m This means
  you must create a new [47mdefthm[0m event with appropriate [3mrule-classes[0m to
  store your new theorem so that it will be used.  See
  [dealing-with-key-combinations-of-function-symbols].  Then you must
  start using The Method recursively to prove your new lemma.

  [31;1m(5) Otherwise, is this formula something you'd prove by induction?[0m 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 [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 [47mdefthm[0m and use The Method recursively to prove it.

  [31;1m(6) If the formula is right for induction, did ACL2 do an induction
  for it?[0m 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).

  [31;1m(7) If ACL2 did do an induction, was it the right one?[0m 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
  [post-induction-key-checkpoints] now and then come back here.

  [31;1m(8) If the post-induction key checkpoints seems plausible,[0m [31;1mthen
  repeat the questions above for each one of them,[0m [31;1mperhaps starting
  with the simplest.[0m

  In any case, after successfully taking whatever action you've decided
  on, e.g., proving some new lemma and adding it as a rule:

  [31;1mStart over trying to prove your main conjecture.[0m 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.

  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?''

  Two other ideas are helpful to keep in mind.

  [31;1mIs a key checkpoint unexpectedly complicated?[0m 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).

  [31;1mDoes the theorem prover just hang up, printing nothing?[0m 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 [3mInterrupt Session[0m
  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 [breaks] {ICON} (see
  [A_Tiny_Warning_Sign]).

  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 [dmr] {ICON} (see [A_Tiny_Warning_Sign]) and, perhaps, see
  [accumulated-persistence] {ICON} (see [A_Tiny_Warning_Sign]).

  If you are reading this as part of the tutorial introduction to the
  theorem prover, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-the-theorem-prover].")
 (INTRODUCTION-TO-PROGRAMMING-IN-ACL2-FOR-THOSE-WHO-KNOW-LISP
  (PROGRAMMING INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Introduction to programming in ACL2 for Lisp users

  The [documentation] topic, [ACL2-built-ins], as well as its parent
  topic, [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.

  The [47m[documentation][0m for ACL2 and its [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
  Precise Description of the ACL2 Logic |
  http://www.cs.utexas.edu/users/moore/publications/km97a.pdf}''
  (Matt Kaufmann and J Moore, April, 1998).


Applicative Common Lisp

  The ACL2 (``A Computational Logic for Applicative Common Lisp'')
  programming language is essentially a subset of Common Lisp ---
  albeit with some useful extensions --- that is [3mapplicative[0m: the
  value returned by a function depends only on its inputs, not state.
  (There is an ACL2 notion of [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)
  [47m[car][0m, [47m[cons][0m, [47m[nth][0m, [47m[append][0m, [47m[let][0m, and [47m[let*][0m.  A few others
  are not directly included in ACL2 because they have incomplete
  specifications in Common Lisp, such as [47m[pairlis][0m; 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 [47m\"$\"[0m to the Common Lisp name; for example, ACL2 has
  [47m[pairlis$][0m, [47m[union$][0m, and even [47m[random$][0m.  Yet other Common Lisp
  functions, for example [47mformat[0m, are not available in ACL2 but have
  useful alternatives in ACL2; for example, see [47m[fmt][0m.  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 `[47m$[0m' will show you utilities like [47mpairlis$[0m that are based on
  related Common Lisp utilities.

  In the ACL2 read-eval-print loop, you can define functions and macros
  with [47m[defun][0m and [47m[defmacro][0m just as in Common Lisp, with some
  restrictions (see for example [name]) and also some additional
  [47m[declare][0m forms.


Data types

  Only certain Lisp data types are supported for programming in ACL2:
  numbers that are either rational numbers or complex numbers with
  rational coefficients (see [numbers-introduction]); the
  [characters] constructed with [47m(code-char n)[0m for [47mn[0m from 0 to 255;
  [strings] formed from those characters; [symbols] whose
  [47m[symbol-name][0m and [47m[symbol-package-name][0m are ACL2 strings; and
  objects constructed from others using [47m[cons][0m.

  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 [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:
  [3msingle-threaded objects[0m, or [3mstobjs[0m; see [stobj].

  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 [defrec].


Program and logic modes

  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 [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 [xargs] for how to specify [47m:program[0m in a [declare] form), or
  you can set the default [defun-mode] to [47m:program[0m (see
  [default-defun-mode] and see [program]).

  When you are ready to reason about your functions, you can use
  [47m:[0m[47m[logic][0m mode instead, or you can convert a program-mode function
  to logic-mode with [47m[verify-termination][0m.


Connection to Common Lisp

  Many Common Lisp functions should only be applied to certain types of
  objects: for example, [47m[car][0m should only be applied to a cons pair
  or [47mnil[0m.  Every ACL2 function has a [3mguard[0m, which specifies the
  intended domain of the function; see [guard].  For example, the
  guard for [47mcar[0m is [47m(OR (CONSP X) (EQUAL X NIL))[0m.  See [args] for a
  utility that provides this and other information about a given
  function symbol.

  Beginning ACL2 programmers should probably ignore guards, at least
  initially.  Otherwise, see [xargs] for how to specify a guard; also
  see [verify-guards].


Multiple values

  The analogues of Common Lisp utilities [47mmultiple-value-bind[0m and [47mvalues[0m
  are [47m[mv-let][0m and [47m[mv][0m, respectively.  Also see [b*] for an
  alternative to [47m[let*][0m that can be convenient in the presence of
  multiple values.


State

  ACL2 provides a notion of [3mstate[0m 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, [47mstate[0m, i.e., the symbol in the
  [47m\"ACL2\"[0m package whose [47m[symbol-name][0m is [47m\"STATE\"[0m.  This is a rather
  complex notion, perhaps best avoided by beginning ACL2 programmers.
  To learn about the ACL2 state, see [state], which points to a
  topic, [programming-with-state], that discusses many utilities for
  reading and writing the ACL2 state.


More help

  ACL2 does not provide [47mapropos[0m.  However, you can search the
  documentation to find substring matches.  For example, if you type
  [47mprinc[0m into the ``[47mJump to[0m'' box in the web-based manual, or if you
  type the command [47mi[0m [for ''index''] into the [ACL2-doc] Emacs-based
  documentation browser, you will find [47m[princ$][0m.  The ``[47mJump to[0m'' box
  in the web-based manual matches on prefixes, but the [47mi[0m command in
  [ACL2-doc] matches on any substring.

  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 {ACL2 home page |
  http://www.cs.utexas.edu/users/moore/acl2/}.  Moreover, that could
  be a good place to request or suggest improvements to this
  documentation topic!  Also see [history] for some ways to query the
  current session.

  Finally, here are a few specific alternatives to Common Lisp
  utilities.

    * [47mdescribe[0m: see [47m[doc][0m

    * [47mfboundp[0m and other utilities to provide information about functions,
      macros, and special operators: see [47m[args][0m

    * [47mformat[0m: see [47m[fmt][0m, which has links to related functions that perform
      formatted printing

    * [47mlist-all-packages[0m: see [47m[in-package][0m; also see the description of
      [47mknown-package-alist[0m in [system-utilities]

    * [47msetq[0m: see [47m[assign][0m, but perhaps first look at the documentation
      topics for [state] and [programming-with-state]

    * [47msymbol-plist[0m: see [47m[props][0m, [47m[getprop][0m, and [47m[putprop][0m

    * [47mwith-open-file[0m: see [io]")
 (INTRODUCTION-TO-REWRITE-RULES-PART-1
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Introduction to ACL2's notion of rewrite rules

  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 [random-remarks-on-rewriting]
  instead.

  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 [rewrite],
  [definition], and [meta] rules it knows, in order from the most
  recently submitted rule to the oldest, until it finds one to apply.

  Here's an example.  Just pretend that you have made a rewrite rule
  from the formula below.

    (implies (and (natp i)
                  (< i (len a)))
             (equal (put i v (append a b))
                    (append (put i v a) b)))

  Then every time the rewriter sees a target term that [3mmatches[0m

    (put i v (append a b))

  it considers the rule, with the variables [47mi[0m, [47mv[0m, [47ma[0m, and [47mb[0m of the rule
  [3mbound[0m to whatever terms matched them in the target, say the terms
  [3mi[0m, [3mv[0m, [3ma[0m, and [3mb[0m.  To consider the rule, the rewriter first tries to
  establish (``relieve'') the hypotheses.  In particular, it
  rewrites:

    (natp [3mi[0m)           ; [3mhyp 1[0m

  and

    (< [3mi[0m (len [3ma[0m)). ; [3mhyp 2[0m

  If both hypotheses rewrite to true, then the rule [3mfires[0m and replaces
  the target by:

    (append (put [3mi[0m [3mv[0m [3ma[0m) [3mb[0m).

  In short, rewrite rules direct ACL2 to rearrange the terms in the
  goal formulas.

  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 [47mdefthm[0m command.  Recall that

    (defthm [3mname[0m
            [3mformula[0m
            ...)

  commands ACL2 to try to prove [3mformula[0m and, if successful, build it
  into the database as a rule according to your specification in the
  [3mrule-classes[0m argument of the ... part of the command.

  To make it easy for you to generate rewrite rules, [47mdefthm[0m has a
  simple heuristic: if you don't tell it what kind of rule to
  generate from [3mformula[0m, it generates a rewrite rule!  Thus, if this
  command

    (defthm [3mname[0m
            [3mformula[0m)

  is successful, ACL2 will have a new rewrite rule in the database,
  even though you did not [3mexplicitly[0m tell it to add a rule.

  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 [3monly[0m adds
  a rule.  It does not magically make ACL2 aware of all the
  mathematical consequences of the formula: it just makes a rewrite
  rule.

  When you prove a theorem with [47mdefthm[0m you are [3mprogramming[0m ACL2.  Being
  careless in your statement of lemmas is tantamount to being
  careless in your programming.

  ACL2 can generate rewrite rules from formulas that look like this:

    (IMPLIES (AND [3mhyp1[0m ... [3mhypk[0m)
             ([3meqv[0m [3mlhs[0m [3mrhs[0m))

  where [3meqv[0m is either [47mEQUAL[0m or [47mIFF[0m, and [3mlhs[0m is not a variable symbol,
  not a constant, and not a call of the function [47mIF[0m, and not a call
  of an abbreviation (``macro'') that expands to any of these.  So
  illegal [3mlhs[0m include [47mX[0m, [47m0[0m, [47m(IF X Y Y)[0m, and [47m(OR p q)[0m.  The last is
  illegal because [47mOR[0m is just an abbreviation for a certain
  [47mIF[0m-expression.

  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 [3meqv[0m other
  than just [47mEQUAL[0m and [47mIFF[0m.  But we'll ignore these fine points for
  now.

  We call the [3mhyp[0m terms the [3mhypotheses[0m of the rule.  We call [3mlhs[0m the
  [3mleft-hand side[0m of the rule, and we call [3mrhs[0m the [3mright-hand side[0m of
  the rule.  If the conclusion of the rule is an [47mEQUAL[0m term we call
  it an [3mequality[0m rule.  Otherwise, it is a [3mpropositional equivalence[0m
  rule.  If there are no hypotheses, [3mk[0m=0, we say the rule is an
  [3munconditional[0m rewrite rule; otherwise it is [3mconditional[0m.

  ACL2 allows several special cases of the shapes above.  See
  [special-cases-for-rewrite-rules], but come back here and continue.

  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.

  That is, the left-hand side is treated as a [3mpattern[0m that triggers the
  rule.  The hypotheses are [3mconditions[0m that have to be proved in
  order for the rule to fire.  The right-hand side is the [3mreplacement[0m
  and is put into the formula where the pattern occurred.

  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 [47mAND[0m, [47mOR[0m, [47mNOT[0m, [47mIMPLIES[0m, and [47mIFF[0m, or in the test of an [47mIF[0m.  When
  we say that the left-hand side of the rule must [3mmatch[0m the target we
  mean that we can instantiate the variables in the rule to make the
  left-hand side identical to the target.  To [3mrelieve[0m 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.

  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 [3mfree variables[0m.  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

    (IMPLIES (AND (TRUE-LISTP A)
                  (MEMBER (CAR P) A)
                  (MEMBER (CDR P) A))
             ...)

  and the target you're rewriting is in the ``...'' part of the
  formula, the rewriter knows that [47m(TRUE-LISTP A)[0m [47m(MEMBER (CAR P) A)[0m
  and [47m(MEMBER (CDR P) A)[0m are true.  So if a rewrite rule is
  considered and the rule has [47m(member e x)[0m as a hypothesis, where [47me[0m
  is a free variable but [47mx[0m was bound to [47mA[0m in the pattern matching,
  then it will guess that [47me[0m must be [47m(CAR P)[0m or [47m(CDR P)[0m, even though
  there are many other possibilities that would make [47m(MEMBER e A)[0m
  true.  Of course, whatever guess it makes must also satisfy all the
  other hypotheses that mention [47me[0m in the rule.  It simply isn't very
  imaginative at guessing!

  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.

  It is possible to make the rewriting process loop forever, e.g., by
  rewriting [3malpha[0m to [3mbeta[0m with one set of rules and rewriting [3mbeta[0m to
  [3malpha[0m 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 [47m(equal (+ x y)
  (+ y x))[0m to replace [47m(+ B A)[0m by [47m(+ A B)[0m, but not vice versa.  (It is
  sensitive to alphabetic ordering when dealing with [3mpermutative[0m
  rules.)

  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 ---
  while having no effect on the mathematical meaning of a formula ---
  can have a drastic impact on the pragmatic meaning as a rule.  To
  see an illustration of this, see
  [equivalent-formulas-different-rewrite-rules].

  Developing an effective set of rewrite rules is key to success at
  using ACL2.  We'll look more at this later in the tutorial.

  If you are working your way through the tutorial for the theorem
  prover, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-the-theorem-prover].  If you are reading just
  about how to make effective rewrite rules, go on to
  [introduction-to-rewrite-rules-part-2].")
 (INTRODUCTION-TO-REWRITE-RULES-PART-2
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "How to arrange rewrite rules

  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 [3m(2x + 6)(3x - 9)[0m you
  automatically normalize it, by ``multiplying out and collecting
  like terms,'' to get [3m(6x^2 - 54)[0m.  This normalization strategy
  allows you to recognize equivalent terms presented differently,
  such as [3m6(x^2 - 9)[0m.

  The ACL2 user is responsible for making up the rules.  (Standard
  ``books'' --- files of ACL2 definitions and theorems --- 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 [47mnthcdr[0m, which
  returns the [47mn[0mth [47mcdr[0m of a list, you might see both [47m(cdr (nthcdr i
  x))[0m and [47m(nthcdr i (cdr x))[0m.  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.

  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.

  Generally, the lightest terms are primitives such as [47mIF[0m, [47mEQUAL[0m,
  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
  [47mrev[0m is defined in terms of [47mappend[0m, [47mrev[0m is heavier than [47mappend[0m.  But
  the size and subtlety of recursively defined functions also affects
  their place in the ordering.

  But rewrite rules are surprisingly subtle.  Recall that a rewrite
  rule can be made from a formula of this form:

    (IMPLIES (AND [3mhyp1[0m ... [3mhypk[0m)
             ([3meqv[0m [3mlhs[0m [3mrhs[0m))

  where [3meqv[0m is either [47mEQUAL[0m or [47mIFF[0m, and [3mlhs[0m is a call of a function
  other than [47mIF[0m.  In such a rule, [3mlhs[0m is the pattern responsible for
  triggering the rule, the [3mhypi[0m are conditions which must be
  satisfied by the context of the target being rewritten, and [3mrhs[0m 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 [47mIFF[0m rule) the target occurs propositionally.  There
  are other heuristic restrictions that we won't discuss here.

  So how should you phrase a theorem in order to make it an effective
  rule?

  General Principles:

  * [31;1mStrengthen the Formula[0m: 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.

  * [31;1mChoosing the Conclusion[0m: 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:

  [3mChoosing the Conclusion Heuristic 1[0m: Can you make the conclusion be
  an [47mEQUAL[0m or [47mIFF[0m 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.

  [3mChoosing the Conclusion Heuristic 2[0m: 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 [47mAND[0m or [47mOR[0m) 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.

  * [31;1mOrienting the Conclusion[0m: If the conclusion is an [47mEQUAL[0m or an [47mIFF[0m,
  you have to decide which is the left-hand side and which is the
  right.  If the conclusion is [47m(NOT[0m [3mlhs[0m[47m)[0m, then the left-hand side is
  [3mlhs[0m and the right-hand side is [47mNIL[0m.  If the conclusion is not an
  [47mEQUAL[0m, an [47mIFF[0m, or a [47mNOT[0m then the conclusion itself will be the
  left-hand side and the right-hand side will be [47mT[0m.  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.

  Remember, the left-hand side is the ``trigger'' that will make the
  rule fire.  It is the pattern that ACL2 will be looking for.

  * [31;1mPay attention to the free variables[0m: 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 [3mv[0m, that is not in the pattern?  We call [3mv[0m a
  [3mfree variable[0m because it will not be assigned a value (``bound'')
  by the process of pattern matching.  ACL2 will have to guess a
  value for [3mv[0m.  If some hypothesis contains [3mv[0m as a free variable, ask
  whether more than one hypothesis contains [3mv[0m?  ACL2 uses the first
  hypothesis containing a free [3mv[0m to guide its guess for [3mv[0m.  To
  ``guess'' a value for [3mv[0m, 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 [3mv[0m first in the list of
  conjuncts.  For example, if [47mv[0m is free in two hypotheses, [47m(natp v)[0m
  and [47m(member (nthcdr v a) b)[0m, then we recommend putting the [47mmember[0m
  term first.  There are likely to be many terms in the goal
  satisfying the [47mnatp[0m hypothesis --- or none if [47mnatp[0m has expanded to
  an integer inequality --- while there are likely to be few terms
  satisfying the [47mmember[0m hypothesis, especially if [47ma[0m and [47mb[0m are bound
  by the left-hand side of the rule.

  Here are some (possibly conflicting) heuristics for choosing the
  left-hand side:

  [3mChoose a Left-Hand Side that Occurs in a Key Checkpoint[0m: 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.

  [3mAvoid Non-Recursive Functions in the Left-Hand Side[0m: 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 [47mSQ[0m so that [47m(SQ x)[0m is [47m(* x x)[0m.  Suppose
  you considered choosing a left-hand side like [47m(+ (SQ x) (SQ y))[0m.
  Suppose you hoped it would hit the target [47m(+ (SQ A) (SQ B))[0m in some
  formula.  But when ACL2 simplifies the formula, it will first
  rewrite that target to

    (+ (* A A) (* B B))

  by expanding the definition of [47mSQ[0m, 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 [47mAND[0m, [47mNOT[0m), you'll avoid this problem since [47mSQ[0m
  will have already been expanded before the Key Checkpoint is
  printed.

  [3mDisable Non-Recursive Functions[0m: 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 [47mSQ[0m 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.

  [3mChoose a Left-Hand Side Already in Simplest Form[0m: 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 [47m(foo (car (cons x
  y)))[0m then it would never match any target!  The reason is that even
  if [47m(FOO (CAR (CONS A B)))[0m did occur in some goal formula, before
  ACL2 would try your rule about [47mfoo[0m it will use the obvious rule
  about [47mCAR[0m and [47mCONS[0m to transform your imagined target to [47m(FOO A)[0m.
  Thus, your rule would not match.  So you have to keep in mind [3mall
  your other rules[0m 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 [community-books] example
  [47mbooks/demos/knuth-bendix-problem-1.lisp[0m.

  [3mMake Sure the Left-Hand Side is ``Heavier'' than the Right[0m: Sometimes
  this is obvious, as when you choose [47m(REV (REV x))[0m for the left-hand
  side and [47mx[0m for the right.  But what do you about [47m(REV (APPEND x y))[0m
  versus [47m(APPEND (REV y) (REV x))[0m?  Most of the time we choose to
  drive the heaviest function (in this case [47mREV[0m) down toward the
  variables, lifting the lighter function ([47mAPPEND[0m) up so that we can
  reason about the lighter function's interaction with the
  surrounding ``matrix'' of the formula.  So we'd rewrite [47m(REV
  (APPEND x y))[0m to [47m(APPEND (REV y) (REV x))[0m, not vice versa.

  [3mAlternative Ways to Talk About the Same Thing[0m: 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 [47mnth[0m returns the nth element of a list, and the
  built-in function [47mnthcdr[0m returns the nth [47mcdr[0m of a list.  They are
  defined independently.  But [47m(nth n x)[0m is the same thing as [47m(car
  (nthcdr n x))[0m.  Since [47mnth[0m can be expressed in terms of [47mnthcdr[0m but
  not vice versa, it is clear we should prove [47m(equal (nth n x) (car
  (nthcdr n x)))[0m as a rewrite rule if both [47mnth[0m and [47mnthcdr[0m are
  involved in the problem.

  [3mDon't Let Computational Efficiency Dictate the Terms[0m: 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.

  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.

  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 [3mproof maintenance[0m 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.

  We now recommend that you practice inventing strong rules; see
  [strong-rewrite-rules].

  For advice on handling specific kinds of formulas and definitions,
  see [specific-kinds-of-formulas-as-rewrite-rules].

  For more information about the rewriter works and how rules are
  created, see [further-information-on-rewriting].

  If you are working your way through the tutorial introduction to the
  theorem prover, use your browser's [31;1mBack Button[0m to return to
  [introduction-to-the-theorem-prover].")
 (INTRODUCTION-TO-THE-DATABASE
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "How to update the database

  We assume you've read [introduction-to-rewrite-rules-part-1] and
  [introduction-to-key-checkpoints].

  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 [3mglobal[0m hint, potentially affecting all parts
  of a proof attempt.

  However, in addition to the ``global hint,'' it is possible to give
  [3mlocal[0m hints that affect the theorem prover's behavior on specific
  subgoals.  We discuss the database here and discuss local hints
  later in the tutorial.

  The theorem prover's ``database'' is called the [3mACL2 world[0m.  You
  change the world by issuing commands called [3mevents[0m.  The most
  common events are [47mdefun[0m for defining new functions (and predicates)
  and [47mdefthm[0m for proving new theorems.  Both add rules to the
  database.  Here are some commonly used events.

  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.

  See [defun] {ICON} (see [A_Tiny_Warning_Sign]) to define a new
  function or predicate symbol.  Definitional axioms are just a kind
  of [47mrewrite[0m rule, but [47mdefun[0m may also add rules affecting the
  determination of the type of a term and rules affecting the
  induction analysis.  When you issue a [47mdefun[0m command you will always
  supply the [3mname[0m of the function or predicate, the list of [3mformal
  parameters[0m, [3mv1,...vn[0m, and the [3mbody[0m:

    (defun [3mname[0m ([3mv1 ... vn[0m)
       [3mbody[0m)

  If the event is accepted, a [3mdefinitional axiom[0m is added to the world,
  [47m([0m[3mname[0m [3mv1...vn[0m[47m)[0m=[3mbody[0m, stored as a special kind of unconditional
  rewrite rule.  However, the [47mdefun[0m event may require theorems to be
  proved.  Specifically, [3mmeasure theorems[0m must be proved to establish
  that recursively defined functions always terminate, by proving
  that an [3mordinal[0m measure of the formal parameters decreases in a
  [3mwell-founded[0m way in every recursive call.  In addition, if [3mguards[0m
  are being used to declare the [3mexpected domain[0m of the newly defined
  function, [3mguard theorems[0m might be proved to establish that all
  functions stay within their expected domains.  In any case, you may
  provide additional information to the [47mdefun[0m event, coded as part of
  the [47mdeclaration[0m that Common Lisp allows:

    (defun [3mname[0m ([3mv1 ... vn[0m)
       (declare (xargs ...))
       [3mbody[0m)

  The [47mxargs[0m (``extra arguments to [47mdefun[0m'') 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.

  See [defthm] {ICON} (see [A_Tiny_Warning_Sign]) to prove a theorem
  and to add it as a rule of one or more specified rule-classes.
  When you issue a [47mdefthm[0m command you always specify a [3mname[0m for the
  theorem you're trying to prove and a [3mformula[0m stating the theorem.
  You may optionally supply some local hints as we describe later in
  the tutorial.  You may also optionally supply some [3mrule classes[0m
  indicating how you want your formula stored as a rule, after it is
  proved.  We discuss the [47mdefthm[0m [3mrule classes[0m below.

  See [in-theory] {ICON} (see [A_Tiny_Warning_Sign]) to enable or
  disable rules.  Rules have names derived from the names you give to
  functions and theorems, e.g., [47m(:REWRITE LEFT-IDENTITY-OF-FOO . 2)[0m
  for the second rewrite rule you created from the theorem named
  [47mLEFT-IDENTITY-OF-FOO[0m.  Rule names are called [3mrunes[0m.  A [3mtheory[0m is
  just a set (list) of runes.  The [3mcurrent theory[0m is the list of
  enabled runes and the [47min-theory[0m event can add runes to or delete
  runes from the current theory.

  See [include-book] {ICON} (see [A_Tiny_Warning_Sign]) to change the
  world by loading a certified file of other events.  The most common
  use of [47minclude-book[0m is to load ``community books'' --- 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:

    ; * for the most elementary arithmetic, needed for any problem
    ;   that involves even simple addition and multiplication like
    ; [47m(+ x (* 2 y) -3)[0m:

        (include-book \"arithmetic/top-with-meta\" :dir :system)

    ; * for more complicated arithmetic involving non-linear terms like
    ; [47m(* x y)[0m, [47m(expt x (+ i j))[0m, and [47mfloor[0m and [47mmod[0m

        (include-book \"arithmetic-5/top\" :dir :system)

  But for a complete list of system books, see [books] {ICON} (see
  [A_Tiny_Warning_Sign]).

  See [certify-book] {ICON} (see [A_Tiny_Warning_Sign]) to certify a
  file of events for reuse later.

  See [defconst] {ICON} (see [A_Tiny_Warning_Sign]) to define a new
  constant, allowing you to write a symbol, e.g., [47m*weekdays*[0m in place
  of some object, e.g., [47m'(MON TUE WED THU FRI)[0m in formulas.

  See [defmacro] {ICON} (see [A_Tiny_Warning_Sign]) to define a new
  syntactic abbreviation.  The macro facility in Lisp is quite
  powerful, allowing you to [3mcompute[0m the form to which some type-in
  expands.  For example, the primitive macro [47mCOND[0m is defined so that
  [47m(COND ((P X) 1)((Q X) 2)(T 3))[0m expands to [47m(IF (P X) 1 (IF (Q X) 2
  3))[0m.

  See [defstobj] {ICON} (see [A_Tiny_Warning_Sign]) to introduce a
  [3msingle-threaded object[0m that your functions may modify
  ``destructively'' provided they follow strict syntactic rules.

  See [events] {ICON} (see [A_Tiny_Warning_Sign]) 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.

  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 [history] {ICON}
  (see [A_Tiny_Warning_Sign]).

  [31;1mThe Defthm Rule-Classes[0m

  We've already discussed the key role that rules play in controlling
  the behavior of the system.  New rules are introduced primarily
  with the [47mdefthm[0m event, though [47mdefun[0m and other events may introduce
  rules.

  To prove [3mformula[0m and generate, say a [47m:rewrite[0m rule and a [47m:generalize[0m
  rule from it, you would write

    (defthm [3mname[0m
            [3mformula[0m
            :rule-classes (:rewrite :generalize))

  If you wanted to rearrange the shape of the formula before generating
  the [47m:rewrite[0m rule you could provide a [47m:corollary[0m modifier to the
  [47m:rewrite[0m rule class:

    (defthm [3mname[0m
            [3mformula[0m
            :rule-classes ((:rewrite :corollary ...)
                           :generalize)).

  There are many classes of rules, affecting different parts of the
  system.  Each class is denoted by a keyword, e.g., [47m:REWRITE[0m,
  [47m:LINEAR[0m, 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 [47m:corollary[0m 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,
  [47m:rewrite[0m rule modifiers include an optional limit on the depth of
  backchaining and options for handling free variables.

  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!

  See [rewrite] {ICON} (see [A_Tiny_Warning_Sign]) for a description of
  how to create a rewrite rule.

  See [linear] {ICON} (see [A_Tiny_Warning_Sign]) for a description of
  how to store theorems concluding with arithmetic inequalities.  The
  trouble with storing

    (<= (len (delete e x)) (len x))

  as a rewrite rule is that it only matches instances of that
  inequality and thus fails to match

    (<= (LEN (DELETE E X)) (+ 1 (LEN X)))

  ACL2 contains an extensible linear arithmetic decision procedure and
  by storing inequalities as [47m:linear[0m rules you can make that decision
  procedure aware of the basic inequalities between non-primitive
  numerically valued terms.

  See [equivalence] {ICON} (see [A_Tiny_Warning_Sign]), see
  [congruence] {ICON} (see [A_Tiny_Warning_Sign]), and see
  [refinement] {ICON} (see [A_Tiny_Warning_Sign]) to learn how to
  introduce a new equivalence relation to the rewriter.  For example,
  suppose you define [47mset-equal[0m 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'', [47m(rev x)[0m is the identity function and [47mappend[0m is
  commutative, for example.

    (set-equal (rev x) x)

    (set-equal (append x y) (append y x))

  You can make ACL2 use these two theorems as [47m:rewrite[0m rules to replace
  instances of [47m(REV x)[0m and [47m(APPEND x y)[0m by [47mset-equal[0m terms, even
  though the results are not actually [47mEQUAL[0m.  This is possible
  provided the target occurs in a context admitting [47mset-equal[0m as a
  congruence relation.  For example, the congruence rule:

    (implies (set-equal a b)
             (iff (member e a)
                  (member e b)))

  gives the rewriter permission to use the above [47mset-equal[0m rules as
  rewrite rules in the second argument of any [47mmember[0m expression being
  used in a propositional way.

  See [elim] {ICON} (see [A_Tiny_Warning_Sign]) for a description of
  how to make the system adopt a ``change of variable'' tactic that
  can trade in [3mdestructor[0m functions for [3mconstructor[0m functions.  In
  analogy with how ACL2 eliminates [47m(CAR X)[0m and [47m(CDR X)[0m by replacing [47mX[0m
  with [47m(CONS A B)[0m, you can make it eliminate other destructors.  For
  example, the community book [47m\"arithmetic-5/top\"[0m provides an [47melim[0m
  rule that eliminates [47m(floor x y)[0m and [47m(mod x y)[0m by replacing [47mx[0m by [47m(+
  r (* y q))[0m, so that the [47mfloor[0m expression becomes [47mq[0m and the [47mmod[0m
  expression becomes [47mr[0m.  When introducing your own [47melim[0m rules you
  will probably also need to introduce [47mgeneralize[0m rules (see below)
  so that the new variables are appropriately constrained.

  See [generalize] {ICON} (see [A_Tiny_Warning_Sign]) 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 [47mgeneralize[0m rules you can ensure that the new
  variable symbol has certain properties of the term it replaces.

  See [induction] {ICON} (see [A_Tiny_Warning_Sign]) 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 [47m:induct[0m hint (see below).  But if the same problem
  arises repeatedly in several theorems, you might want to
  ``educate'' ACL2's induction heuristic.

  For a complete list of rule-classes, See [rule-classes] {ICON} (see
  [A_Tiny_Warning_Sign]).

  If you are reading this as part of the tutorial introduction to the
  theorem prover, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-the-theorem-prover].")
 (INTRODUCTION-TO-THE-TAU-SYSTEM
  (TAU-SYSTEM)
  "A decision procedure for runtime types

  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.

  [3mA ``Type-Checker'' for an Untyped Language[0m

  Because ACL2 is an untyped language it is impossible to type check
  it.  All functions are total.  An [3mn[0m-ary function may be applied to
  any combination of [3mn[0m ACL2 objects.  The syntax of ACL2 stipulates
  that [47m([0m[3mfn a1...an[0m[47m)[0m is a well-formed term if [3mfn[0m is a function symbol
  of [3mn[0m arguments and the [3mai[0m 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.

  Nevertheless, the system provides a variety of monadic Boolean
  function symbols, like [47m[natp][0m, [47m[integerp][0m, [47m[alistp][0m, 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.''

  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.

  [3mDesign Philosophy[0m

  The following basic principles were kept in mind when developing tau
  checker and may help you exploit it.

  (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.

  (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.

  Tau reasoning is used by the prover as part of [47mpreprocess-clause[0m, 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.

  (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.

  (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.

  (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,

    (implies (n16p x) (n32p x)),

  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:

    (implies (and (natp n)
                  (< n 16)
                  (n32p val)
                  (register-filep regs))
             (register-filep (update-nth n val regs))).

  For a complete description of acceptable forms see [47m:[0m[47m[tau-system][0m.

  (6) The tau system is ``greedy'' in its efforts to augment its
  database.  Its database is potentially augmented when rules of [3many[0m
  [47m:rule-class[0m (see [47m:[0m[47m[rule-classes][0m) are proved.  For example, if you
  make a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[type-prescription][0m rule which expresses a
  relationship between one tau and another (e.g., that [47m(P x)[0m implies
  [47m(Q x)[0m), ACL2 will build it into the tau database.  The rule-class
  [47m:[0m[47m[tau-system][0m can be used to add a rule to the tau database without
  adding any other kind of rule.

  (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
  [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[type-prescription][0m or [47m:[0m[47m[forward-chaining][0m 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 [3mboth[0m the rewriter and the tau system and use
  [47m:[0m[47m[tau-system][0m rules explicitly when you want to ``talk'' just to
  the tau system.

  (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.

  (9) For speed, tau does not track dependencies and is not sensitive
  to the enabled/disabled status (see [47m[enable][0m and [47m[disable][0m) of
  rules, other than [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
  [47m(:[0m[47m[executable-counterpart][0m[47m tau-system)[0m.  If any tau reasoning is
  used in a proof, the rune [47m(:[0m[47m[executable-counterpart][0m[47m tau-system)[0m is
  reported in the [summary].  For a complete list of all the runes in
  the tau database, evaluate [47m(get-tau-runes (w state))[0m.  Any of these
  associated theorems could have been used.

  These design criteria are not always achieved!  For example, the tau
  system's ``greediness'' can be turned off (see
  [47m[set-tau-auto-mode][0m), the tau database can be regenerated from
  scratch to ignore disabled rules (see [47m[regenerate-tau-database][0m),
  and disabling the [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 [clause-identifier]s, thus making
  explicit hints no longer applicable.  We deal with such problems in
  [47m[dealing-with-tau-problems][0m.

  [3mTechnical Details[0m

  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 [47mnatp[0m implies [47mintegerp[0m and that [47mintegerp[0m
  implies not [47mconsp[0m, 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.

  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:

    (natp i)
    (not (consp x))
    (equal y 'MONDAY)
    (not (eql 23 k))
    (< 8 max)
    (<= max 24)

  Synonyms for [47m[equal][0m include [47m[=][0m, [47m[eq][0m, and [47m[eql][0m.  Note that negated
  equalities are also allowed.  The arithmetic ordering relations
  that may be used are [47m[<][0m, [47m[<=][0m, [47m[>=][0m, and [47m[>][0m.  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.

  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.

  When we say that a term ``has'' a given tau we mean the term
  satisfies all of the recognizers in that tau.

  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.

  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, [3ms[0m, we compute a tau, [3mr[0m, for the term and
  ask whether [3ms[0m is a subset of [3mr[0m.  To determine whether a constant,
  [3mc[0m, satisfies tau [3ms[0m we apply each of the literals in [3ms[0m to [3mc[0m.
  Evaluation might, of course, be time-consuming for complex
  user-defined predicates.

  The tau database contains rules derived from definitions and theorems
  stated by the user.  See [47m:[0m[47m[tau-system][0m for a description of the
  acceptable forms of tau rules.

  To shut off the greedy augmentation of the tau database, 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 [47m:[0m[47m[tau-system][0m.

  There are some slight complexities in the design related to how we
  handle events with both [47m:tau-system[0m corollaries and corollaries of
  other [47m:rule-classes[0m, see [47m[set-tau-auto-mode][0m.

  To prevent tau reasoning from being used, disable the
  [47m:[0m[47m[executable-counterpart][0m of [47mtau-system[0m, i.e., execute

    (in-theory (disable (:executable-counterpart tau-system)))

  or, equivalently,

    (in-theory (disable (tau-system)))

  To prevent tau from being used in the proof of a particular subgoal,
  locally disable the [47m:[0m[47m[executable-counterpart][0m of [47mtau-system[0m with a
  local [47m:in-theory[0m hint (see [hints]).

  The event command [47m[tau-status][0m 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

    (tau-status :system nil :auto-mode nil)

  prevents the tau system from being used in proofs and prevents the
  augmentation of the tau database by rules other than those
  explicitly labeled [47m:[0m[47m[tau-system][0m.

  To see what the tau system ``knows'' about a given function symbol
  see [tau-data].  To see the entire tau database, see
  [tau-database].  To regenerate the tau database using only the
  runes listed in the current enabled theory, see
  [regenerate-tau-database].


Subtopics

  [Dealing-with-tau-problems]
      Some advice on dealing with problems caused by the tau system

  [Future-work-related-to-the-tau-system]
      Some tau system problems that we hope someone will address

  [Regenerate-tau-database]
      Regenerate the tau database relative to the current enabled theory")
 (INTRODUCTION-TO-THE-THEOREM-PROVER
  (ACL2-TUTORIAL)
  "How the theorem prover works --- level 0

  Software is complex, and ACL2 is a piece of software that is used to
  analyze software --- adding another layer of complexity.
  Furthermore, instead of being limited to static analysis for
  certain fixed properties, ACL2 allows you --- indeed, forces you
  --- 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.

  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.

  We assume you know some of the industrial applications (see
  [INTERESTING-APPLICATIONS]) 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 Flying Tour (see
  [A_Flying_Tour_of_ACL2]) and the Walking Tour (see
  [A_Walking_Tour_of_ACL2]).  The tours give you a good overview of
  the whole system where this tutorial focuses on how to use the
  prover itself.

  If you haven't visited these links, please do so now.

  This tutorial will take you several hours --- maybe several days ---
  to work through.  Do not breeze through it as you might a blog.
  [3mThink[0m your way through it.  [3mRemember[0m what you read.  Do not take
  short cuts.  If you start to use ACL2 before you really know how,
  it will only frustrate you.

  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.

    [introduction-to-the-theorem-prover]
        [introduction-to-rewrite-rules-part-1]
            [special-cases-for-rewrite-rules]
            [equivalent-formulas-different-rewrite-rules]
        [introduction-to-key-checkpoints]
            [dealing-with-key-combinations-of-function-symbols]
            [generalizing-key-checkpoints]
            [post-induction-key-checkpoints]
        [introduction-to-rewrite-rules-part-2]
            [strong-rewrite-rules]
                [practice-formulating-strong-rules]
                    [practice-formulating-strong-rules-1]
                    [practice-formulating-strong-rules-2]
                    [practice-formulating-strong-rules-3]
                    [practice-formulating-strong-rules-4]
                    [practice-formulating-strong-rules-5]
                    [practice-formulating-strong-rules-6]
            [specific-kinds-of-formulas-as-rewrite-rules]
            [further-information-on-rewriting]
        [introduction-to-the-database]
        [introduction-to-hints]
        [introduction-to-a-few-system-considerations]
        [introductory-challenges]
            [introductory-challenge-problem-1]
            [introductory-challenge-problem-2]
            [introductory-challenge-problem-3]
            [3m(there are others but at least do a few)[0m
        [frequently-asked-questions-by-newcomers]

  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, ``{ICON} (see [A_Tiny_Warning_Sign])''.  They lead out of
  this linear tutorial and into ACL2's hypertext reference manual.
  We recommend that you [3mnot[0m visit any of these advanced links until
  you have read the entire tutorial at least once.

  After you finish this tutorial material, we recommend that you look
  at the ACL2 Demos, at the ``Demos'' link of the {ACL2 home page |
  http://www.cs.utexas.edu/users/moore/acl2}.

  Most users of ACL2 have bought the book

  [3mComputer-Aided Reasoning: An Approach[0m, Kaufmann, Manolios, and Moore,
  Kluwer Academic Publishers, June, 2000

  which is available {in paperback |
  http://www.lulu.com/content/1746161} from Lulu for approximately
  $20 (as of 2010).  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
  {appendices |
  http://link.springer.com/content/pdf/bbm%3A978-1-4615-4449-4%2F1.pdf}
  that focus on some practical usage aspects.  See this { web page
  about the book |
  http://www.cs.utexas.edu/users/moore/publications/acl2-papers.html#Books},
  which also includes information about its companion (also available
  on Lulu) describing applications of ACL2, some of which are from
  industry.

  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.

  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.

  This article is about the [3mtheorem prover[0m 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
  [programming-knowledge-taken-for-granted].  If you want a brief
  tutorial on the ACL2 programming language see
  [gentle-introduction-to-ACL2-programming].

  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
  [logic-knowledge-taken-for-granted].  If you want an introduction
  to the ACL2 logic work your way through [recursion-and-induction].

  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 [3mproof techniques[0m built into ACL2.
  Different proof techniques break the formula apart in different
  ways.  For example, the [3msimplifier[0m rips apart the propositional
  structure to isolate the various cases and applies rewrite rules to
  simplify the subterms of the formula, while the [3minduction[0m [3mengine[0m
  will attempt to break the goal into some base cases and some
  induction steps.

  The theorem prover's behavior is affected by a [3mdatabase[0m of [3mrules[0m
  derived from axioms, definitions, and previously proved theorems.
  The database also records the [3menabled status[0m 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.

  You guide the theorem prover most of the time simply by identifying
  lemmas for it to prove.  (A [3mlemma[0m is just a theorem that you think
  is useful in the proofs of other theorems.)

  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 [3myou[0m
  determine the kind of rule ACL2 stores.

  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.

  Here is the way we recommend you use ACL2.

  [31;1mThe Method[0m.

  (1) you present ACL2 with the goal conjecture to prove

  (2) typically, it fails to prove it (or you abort its attempt), but
  it prints some [3mKey Checkpoints[0m

  (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

  (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 [3mrewrite[0m rule

  (5) you recursively apply The Method to get ACL2 to prove your
  formula and to store it as the kind of rule you specified

  (6) go to step (1)

  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.''

  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 [3mproof planning[0m approach will gradually become
  an integral part of your use of The Method.

  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.

  To use The Method you have to read the Key Checkpoints printed at the
  very end of [3mfailed[0m proof attempts, just after the line that reads:

    The key checkpoint goals, below, may help you to debug this failure.

  Most users do not read the output from successful proofs and do not
  read the output [3mduring[0m a proof --- 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.

  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 [3mname[0m and write some [3mformula[0m to express the
  mathematical idea.  You'll command ACL2 to prove it by typing:

    (defthm [3mname[0m
            [3mformula[0m
            ...)

  In the ``...'' you may provide two other kinds of information: [3mhints[0m
  for how to prove [3mformula[0m and directives, called [3mrule-classes[0m, for
  how to convert [3mformula[0m into a rule after it has proved [3mformula[0m.
  Note that [3myou[0m 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 [3mrewrite[0m rule.

  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, ``{ICON} (see
  [A_Tiny_Warning_Sign])''.

  (1) See [introduction-to-rewrite-rules-part-1] to read about the use
  and design of rewrite rules.

  (2) See [introduction-to-key-checkpoints] to see how to use The
  Method to help you design rules.

  (3) See [introduction-to-rewrite-rules-part-2] for general guidance
  on how to turn formulas into effective rules.

  (4) 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.

  (5) 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.

  (6) See [introduction-to-a-few-system-considerations] for a few words
  about system aspects of interacting with ACL2.

  (7) See [introductory-challenges] for a graduated sequence of good
  challenge problems for the new user to tackle.  [31;1mDo not skip this
  section![0m It is here that you [3mreally[0m learn how to use ACL2 --- by
  using it.

  (8) 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''.

  Please read all of the material cited above (skipping only the ACL2
  User's Manual links (``{ICON} (see [A_Tiny_Warning_Sign])''))
  before you try to use ACL2 on problems of your own.

  By this point you should have read, at least, the following topics
  from this tutorial introduction to the theorem prover:

    [introduction-to-the-theorem-prover]
        [introduction-to-rewrite-rules-part-1]
            [special-cases-for-rewrite-rules]
            [equivalent-formulas-different-rewrite-rules]
        [introduction-to-key-checkpoints]
            [dealing-with-key-combinations-of-function-symbols]
            [generalizing-key-checkpoints]
            [post-induction-key-checkpoints]
        [introduction-to-rewrite-rules-part-2]
            [strong-rewrite-rules]
                [practice-formulating-strong-rules]
                    [practice-formulating-strong-rules-1]
                    [practice-formulating-strong-rules-2]
                    [practice-formulating-strong-rules-3]
                    [practice-formulating-strong-rules-4]
                    [practice-formulating-strong-rules-5]
                    [practice-formulating-strong-rules-6]
            [specific-kinds-of-formulas-as-rewrite-rules]
            [further-information-on-rewriting]
        [introduction-to-the-database]
        [introduction-to-hints]
        [introduction-to-a-few-system-considerations]
        [introductory-challenges]
            [introductory-challenge-problem-1]
            [introductory-challenge-problem-2]
            [introductory-challenge-problem-3]
            [3m(there are others but at least do a few)[0m
        [frequently-asked-questions-by-newcomers]

  We also recommend that you look at the ACL2 Demos mentioned in the
  [ACL2-tutorial].

  Most users of ACL2 have bought the book

  [3mComputer-Aided Reasoning: An Approach[0m, Kaufmann, Manolios, and Moore,
  Kluwer Academic Publishers, June, 2000

  which is {available in paperback from Lulu |
  http://www.lulu.com/content/1746161} for approximately $20 (as of
  2010).  That book contains hundreds of exercises in programming,
  proof, and using The Method to prove theorems.  Solutions to the
  exercises are online.  See also this { web page about the book |
  http://www.cs.utexas.edu/users/moore/publications/acl2-papers.html#Books},
  which also includes information about its companion (also available
  on Lulu) describing applications of ACL2, some of which are from
  industry.

  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.

  [31;1mEnd of Tutorial Introduction to the Theorem Prover[0m

  Below is a list of all of the topics cited on this page.


Subtopics

  [Architecture-of-the-prover]
      A simple overview of how the prover works

  [Dealing-with-key-combinations-of-function-symbols]
      How to get rid of key combinations of function symbols

  [Equivalent-formulas-different-rewrite-rules]
      Logically equivalent formulas can generate radically different rules

  [Example-induction-scheme-binary-trees]
      Induction on binary trees

  [Example-induction-scheme-down-by-2]
      Induction downwards 2 steps at a time

  [Example-induction-scheme-nat-recursion]
      Induction on natural numbers

  [Example-induction-scheme-on-lists]
      Induction on lists

  [Example-induction-scheme-on-several-variables]
      Induction on several variables

  [Example-induction-scheme-upwards]
      Induction upwards

  [Example-induction-scheme-with-accumulators]
      Induction scheme with accumulators

  [Example-induction-scheme-with-multiple-induction-steps]
      Induction scheme with more than one induction step

  [Example-inductions]
      Some examples of induction schemes in ACL2

  [Frequently-asked-questions-by-newcomers]
      Some questions newcomers frequently ask

  [Further-information-on-rewriting]
      A grab bag of advice and information on rewriting

  [Geneqv]
      the rewriter's generated equivalence relation

  [Generalizing-key-checkpoints]
      Getting rid of unnecessary specificity

  [Introduction-to-a-few-system-considerations]
      The mechanics of interaction with the theorem prover

  [Introduction-to-hints]
      How to provide hints to the theorem prover

  [Introduction-to-key-checkpoints]
      What questions to ask at key checkpoints

  [Introduction-to-programming-in-ACL2-for-those-who-know-lisp]
      Introduction to programming in ACL2 for Lisp users

  [Introduction-to-rewrite-rules-part-1]
      Introduction to ACL2's notion of rewrite rules

  [Introduction-to-rewrite-rules-part-2]
      How to arrange rewrite rules

  [Introduction-to-the-database]
      How to update the database

  [Introductory-challenge-problem-1]
      Challenge problem 1 for the new user of ACL2

  [Introductory-challenge-problem-1-answer]
      Answer to challenge problem 1 for the new user of ACL2

  [Introductory-challenge-problem-2]
      Challenge problem 2 for the new user of ACL2

  [Introductory-challenge-problem-2-answer]
      Answer to challenge problem 2 for the new user of ACL2

  [Introductory-challenge-problem-3]
      Challenge problem 3 for the new user of ACL2

  [Introductory-challenge-problem-3-answer]
      Answer to challenge problem 3 for the new user of ACL2

  [Introductory-challenge-problem-4]
      Challenge problem 4 for the new user of ACL2

  [Introductory-challenge-problem-4-answer]
      Answer to challenge problem 4 for the new user of ACL2

  [Introductory-challenges]
      Challenge problems for the new ACL2 user

  [Logic-knowledge-taken-for-granted]
      Background knowledge in ACL2 logic for theorem prover tutorial

  [Logic-knowledge-taken-for-granted-base-case]
      A brief explanation of base cases

  [Logic-knowledge-taken-for-granted-equals-for-equals]
      Substitution of equals for equals

  [Logic-knowledge-taken-for-granted-evaluation]
      Evaluation during proofs

  [Logic-knowledge-taken-for-granted-inductive-proof]
      A brief explanation of induction

  [Logic-knowledge-taken-for-granted-instance]
      A brief explanation of substitution instances

  [Logic-knowledge-taken-for-granted-propositional-calculus]
      A brief explanation of propositional calculus

  [Logic-knowledge-taken-for-granted-q1-answer]
      The inductive step of the [47mrev-rev[0m proof --- Answer to Question 1

  [Logic-knowledge-taken-for-granted-q2-answer]
      The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2

  [Logic-knowledge-taken-for-granted-q3-answer]
      The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2

  [Logic-knowledge-taken-for-granted-rewriting]
      A brief explanation of rewriting from the logical perspective

  [Logic-knowledge-taken-for-granted-rewriting-repeatedly]
      Further information on expanding definitions via rewriting

  [Post-induction-key-checkpoints]
      Reading post-induction key checkpoints

  [Practice-formulating-strong-rules]
      A few simple checkpoints suggesting strong rules

  [Practice-formulating-strong-rules-1]
      Rules suggested by [47m(TRUE-LISTP (APPEND (FOO A) (BAR B)))[0m

  [Practice-formulating-strong-rules-2]
      Rules suggested by [47m(TRUE-LISTP (REV (FOO A)))[0m

  [Practice-formulating-strong-rules-3]
      Rules suggested by [47m(MEMBER (FOO A) (APPEND (BAR B) (MUM C)))[0m

  [Practice-formulating-strong-rules-4]
      Rules suggested by [47m(SUBSETP (APPEND (FOO A) (BAR B)) (MUM C))[0m

  [Practice-formulating-strong-rules-5]
      Rules suggested by [47m(SUBSETP (FOO A) (APPEND (BAR B) (MUM C)))[0m

  [Practice-formulating-strong-rules-6]
      Rules suggested by [47m(MEMBER (FOO A) (NATS-BELOW (BAR B)))[0m

  [Programming-knowledge-taken-for-granted]
      Background knowledge in ACL2 programming for theorem prover tutorial

  [Refinement-failure]
      what to do when a rewrite rule fails the refinement check

  [Special-cases-for-rewrite-rules]
      Convenient short forms for rewrite rule formulas

  [Specific-kinds-of-formulas-as-rewrite-rules]
      Advice about how to handle commonly occurring formulas as rewrite
      rules

  [Strong-rewrite-rules]
      Formulating good rewrite rules")
 (INTRODUCTORY-CHALLENGE-PROBLEM-1
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Challenge problem 1 for the new user of ACL2

  Start in a fresh ACL2, either by restarting your ACL2 image from
  scratch or executing

    :ubt! 1

  which will undo everything since the first user event.

  Then define this function:

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

  Then use The Method to prove:

    (defthm triple-rev
      (equal (rev (rev (rev x))) (rev x)))

  When you've solved this problem, compare your answer to ours; see
  [introductory-challenge-problem-1-answer].

  Then, use your browser's [31;1mBack Button[0m to return to
  [introductory-challenges].")
 (INTRODUCTORY-CHALLENGE-PROBLEM-1-ANSWER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Answer to challenge problem 1 for the new user of ACL2

  This answer is in the form of an ACL2 script sufficient to lead ACL2
  to a proof.

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

    ; Trying [47mtriple-rev[0m at this point produces a key checkpoint containing
    ; [47m(REV (APPEND (REV (CDR X)) (LIST (CAR X))))[0m, which suggests:

    (defthm rev-append
      (equal (rev (append a b))
             (append (rev b) (rev a))))

    ; And now [47mtriple-rev[0m succeeds.

    (defthm triple-rev
      (equal (rev (rev (rev x))) (rev x)))

    ; An alternative, and more elegant, solution is to prove the [47mrev-rev[0m
    ; instead of [47mrev-append[0m:

    ; (defthm rev-rev
    ;   (implies (true-listp x)
    ;            (equal (rev (rev x)) x)))

    ; [47mRev-rev[0m is also discoverable by The Method because it is
    ; suggested by the statement of [47mtriple-rev[0m itself: [47mrev-rev[0m
    ; simplifies a simpler composition of the functions in [47mtriple-rev[0m.

    ; Both solutions produce lemmas likely to be of use in future proofs
    ; about [47mrev[0m.

  Use your browser's [31;1mBack Button[0m now to return to
  [introductory-challenge-problem-1].")
 (INTRODUCTORY-CHALLENGE-PROBLEM-2
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Challenge problem 2 for the new user of ACL2

  Start in a fresh ACL2, either by restarting your ACL2 image from
  scratch or executing [47m:ubt! 1[0m.

  Use The Method to prove

    (defthm subsetp-reflexive
      (subsetp x x))

  When you've solved this problem, compare your answer to ours; see
  [introductory-challenge-problem-2-answer].

  Then, use your browser's [31;1mBack Button[0m to return to
  [introductory-challenges].")
 (INTRODUCTORY-CHALLENGE-PROBLEM-2-ANSWER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Answer to challenge problem 2 for the new user of ACL2

  This answer is in the form of a script sufficient to lead ACL2 to a
  proof.

    ; Trying [47msubsetp-reflexive[0m 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 [47msubsetp-reflexive[0m succeeds.

    (defthm subsetp-reflexive
      (subsetp x x))

    ; A weaker version of the lemma, namely the one in which we
    ; add the hypothesis that [47mb[0m is a [47mcons[0m, is also sufficient.

    ;    (defthm subsetp-cdr-weak
    ;      (implies (and (consp b)
    ;                    (subsetp a (cdr b)))
    ;               (subsetp a b)))

    ; But the [47m(consp b)[0m hypothesis is not really necessary in
    ; ACL2's type-free logic because [47m(cdr b)[0m is [47mnil[0m if [47mb[0m is
    ; not a [47mcons[0m.  For the reasons explained in the tutorial, we
    ; prefer the strong version.

  Use your browser's [31;1mBack Button[0m now to return to
  [introductory-challenge-problem-2].")
 (INTRODUCTORY-CHALLENGE-PROBLEM-3
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Challenge problem 3 for the new user of ACL2

  Start in a fresh ACL2, either by restarting your ACL2 image from
  scratch or executing [47m:ubt! 1[0m.

  Define the following functions and use The Method to prove the
  theorem at the bottom:

    (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)))

  When you've solved this problem, compare your answer to ours; see
  [introductory-challenge-problem-3-answer].

  Then, use your browser's [31;1mBack Button[0m to return to
  [introductory-challenges].")
 (INTRODUCTORY-CHALLENGE-PROBLEM-3-ANSWER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Answer to challenge problem 3 for the new user of ACL2

  This answer is in the form of a script sufficient to lead ACL2 to a
  proof.

    ; Trying [47mdupsp-rev[0m 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 [47m(MEMBER (CAR X) (APPEND (CDR X) (LIST E)))[0m.
    ; 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 [47miff[0m instead of [47mequal[0m since
    ; [47mmember[0m is not a Boolean function.

    ; Having proved this lemma, we return to [47mdupsp-append[0m and succeed:

    (defthm dupsp-append
      (implies (not (member e x))
               (equal (dupsp (append x (list e)))
                      (dupsp x))))

    ; So now we return to [47mdups-rev[0m, 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 [47mdupsp-append[0m 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 [47mdups-append[0m rule has the hypothesis [47m(not
    ; (member e x))[0m and after the match with the left-hand side, [47me[0m
    ; is [47m(CAR X)[0m and [47mx[0m is [47m(REV (CDR X))[0m.  So the system
    ; couldn't rewrite [47m(NOT (MEMBER (CAR X) (REV (CDR X))))[0m to true,
    ; even though it knows that [47m(NOT (MEMBER (CAR X) (CDR X)))[0m from
    ; the second hypothesis of the checkpoint.  Obviously, we need to
    ; prove [47mmember-rev[0m below.

    ; Use tools:  We could enable the ``break rewrite'' facility, with

    ; ACL2 !>:brr t

    ; and then install an unconditional monitor on the rewrite rule
    ; [47mdupsp-append[0m, 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 >: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 [47m(member ... (rev ...))[0m.  Thus, we're led to the
    ; same conclusion that Thinking produced.  To get out of the
    ; interactive break we type:

    ; 1 ACL2 >: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 !>: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)))

  Use your browser's [31;1mBack Button[0m now to return to
  [introductory-challenge-problem-3].")
 (INTRODUCTORY-CHALLENGE-PROBLEM-4
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Challenge problem 4 for the new user of ACL2

  Start in a fresh ACL2, either by restarting your ACL2 image from
  scratch or executing [47m:ubt! 1[0m.

  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.

  (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.)

  [31;1mHint[0m: 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 [introductory-challenge-problem-4-answer].  In that
  page you'll see a definition of a function [47mcollect-once[0m and the
  proofs of two theorems:

    (defthm main-theorem-1-about-collect-once
      (subsetp (collect-once x) x))

    (defthm main-theorem-2-about-collect-once
      (not (dupsp (collect-once x))))

  The function [47mdupsp[0m is as defined in see
  [introductory-challenge-problem-3].  This is quite easy.

  Then, we define a tail-recursive version of the method based on the
  pseudo-code:

    a = nil;
    while (x not empty) {
     a = if (member (car x) a) then a else (cons (car x) a);
     x = (cdr x);
     }
    return a;

  We formalize this with the function [47mwhile-loop-version[0m, where
  [47m(while-loop-version x nil)[0m is the ``semantics'' of the code above.
  I.e., the function [47mwhile-loop-version[0m captures the while loop in
  the pseudo-code above and returns the final value of [47ma[0m, and it
  should be invoked with the initial value of [47ma[0m being [47mnil[0m.

  We prove [47m(while-loop-version x nil)[0m returns a subset of [47mx[0m that
  contains no duplications.  Furthermore, we do it two ways: first
  ``indirectly'' by relating [47mwhile-loop-version[0m to [47mcollect-once[0m, and
  second (``directly'') without using [47mcollect-once[0m.  Both of these
  proofs are much harder than the [47mcollect-once[0m approach, involving
  about a dozen lemmas each.

  Compare your solutions to ours at see
  [introductory-challenge-problem-4-answer].

  Then, use your browser's [31;1mBack Button[0m to return to
  [introductory-challenges].

  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.

    (thm
      (subsetp x (collect-once x)))")
 (INTRODUCTORY-CHALLENGE-PROBLEM-4-ANSWER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Answer to challenge problem 4 for the new user of ACL2

  This topic solves a challenge problem presented elsewhere; 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.

  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:

    a = nil;
    while (x not empty) {
      a = if (member (car x) a) then a else (cons (car x) a);
      x = (cdr x);
      }
    return a;

  We'll prove the two ``equivalent'' and we'll prove that they return a
  subset of [47mx[0m that contains no duplications.

  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 [47mwhile[0m-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 [47mwhile[0m-loop version will be straightforward from the correctness
  of the primitive recursive version.  (C) We will disable the rules
  we prove about the [47mwhile[0m-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 --- a narrative that
  summarizes what we learn from these examples.

  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.

    [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!

  The rest of this page is just a re-playable script.

    ; -----------------------------------------------------------------
    ; 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.

  Use your browser's [31;1mBack Button[0m now to return to
  [introductory-challenge-problem-4].")
 (INTRODUCTORY-CHALLENGES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Challenge problems for the new ACL2 user

  Do each of the problems.  In each case, start with a fresh ACL2 (or
  undo all effects of previous events with [47m:ubt! 1[0m).  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.

  We recommend that you follow The Method and consult the documentation
  as needed --- but that you not look at our answers until you're
  well and truly baffled!

  See [introductory-challenge-problem-1] (Answer:
  [introductory-challenge-problem-1-answer])

  See [introductory-challenge-problem-2] (Answer:
  [introductory-challenge-problem-2-answer])

  See [introductory-challenge-problem-3] (Answer:
  [introductory-challenge-problem-3-answer])

  See [introductory-challenge-problem-4] (Answer:
  [introductory-challenge-problem-4-answer])

  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

  [annotated-ACL2-scripts] (Answer: the answers are given in the
  examples)

  When you've done the problems and compared your solutions to ours,
  use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-the-theorem-prover].")
 (INVARIANT-RISK
  (PROGRAMMING ADVANCED-FEATURES GUARD DEBUGGING)
  "Potential slowdown for [program]-mode updates to [stobj]s or [arrays]

  You may see a warning like this:

    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.

  Such warnings indicate potential slowdown due to aggressive
  protection by ACL2 against either:

    * writing a value of the wrong type to a [stobj] field; or

    * performing an out-of-bounds write to an ACL2 [array].

  Whenever a [47m:[0m[47m[program][0m-mode function call can perhaps lead to such a
  write, [guard]-checking is performed by ACL2, even though the
  normal expectation is to execute without such checks in Common
  Lisp; see [evaluation].  Consider the following example.

    (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)

  Each of the two calls of [47mg[0m produces an [47m\"Invariant-risk\"[0m warning, and
  indeed [guard]s are checked for the ensuing calls of [47mf[0m, causing a
  guard violation for the second call of [47mg[0m.

  We may say that such [47m:[0m[47m[program][0m-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 [trace$].

  There are two general methods for avoiding such warnings: at runtime
  with [47m[set-check-invariant-risk][0m, and at definition time with
  [47m[set-register-invariant-risk][0m.  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 [invariant-risk-details].  For tools that may
  help find sources of invariant-risk, see [community-book]
  [47mbooks/std/system/invariant-risk.lisp[0m.


Controlling runtime checking for invariant-risk

  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.

    (set-check-invariant-risk t)
    (set-inhibit-warnings \"invariant-risk\")

  You can also replace such warnings by errors:

    (set-check-invariant-risk :error)

  Evaluate [47m(get-check-invariant-risk state)[0m to see the current setting
  for invariant-risk checking.  For details, including a dangerous
  way to remove invariant-risk checking completely at runtime, see
  [set-check-invariant-risk].


Eliminating invariant-risk checking done by specific functions

  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 [3mall[0m functions at runtime with
  [47m[set-check-invariant-risk][0m, it is probably much safer to remove it
  only for the functions in a given book or [47m[encapsulate][0m event.  See
  [set-register-invariant-risk] for how to do that.


Subtopics

  [Invariant-risk-details]
      More details about [invariant-risk]

  [Set-check-invariant-risk]
      Affect certain [program]-mode updates to [stobj]s or [arrays]

  [Set-register-invariant-risk]
      Avoid [invariant-risk] checking for specified functions")
 (INVARIANT-RISK-DETAILS
  (INVARIANT-RISK)
  "More details about [invariant-risk]

  This topic, which may be unnecessary for most ACL2 users, expands on
  the documentation for [invariant-risk].  See that topic and see
  [evaluation] for relevant background.

  We refer below to the following example, which is slightly expanded
  from the one in the documentation for [invariant-risk].

    (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))

  To understand invariant-risk, consider the case that a [stobj]
  updater (such as [47mupdate-fld[0m above) is called on ill-guarded
  arguments.  In that case the resulting ACL2 [state] could be
  ill-formed, as in the example above: after turning off
  invariant-risk checking, the stobj [47mst[0m 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 [47m:[0m[47m[program][0m-mode function to prevent it
  from calling its corresponding submitted function.  It does this
  when the [47m:program[0m-mode function has a non-nil [47m'invariant-risk[0m
  property; in the example above, note:

    ACL2 !>(getpropc 'g 'invariant-risk)
    UPDATE-FLD
    ACL2 !>

  When the function symbol [47mg[0m was defined, it inherited this property
  from [47mf2[0m, which in turn inherited it from [47mf1[0m, which in turn
  inherited it from the stobj updater, [47mupdate-fld[0m.  However, the
  aforementioned special code is only installed for [47m:program[0m mode
  functions, hence not for [47mf1[0m or [47mf2[0m.  Consider for example the
  following trace, from the call of [47m(g 3)[0m made above before turning
  off invariant-risk checking.

    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 !>

  This trace illustrates that even though [47mf2[0m has the [47m'invariant-risk[0m
  property, its executable-counterpart has permission to call its
  submitted function because [47mf2[0m is a guard-verified [47m:logic[0m-mode
  function.

  As an optimization, ACL2 avoids setting the [47m'invariant-risk[0m property
  on [47m:[0m[47m[logic][0m mode functions whose [guard] is [47mt[0m or, more generally, a
  conjunction of [stobj] recognizer calls.  For example, the call of
  [47m(bar 3 st)[0m below does not cause an invariant-risk warning.

    (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)

  This optimization can hold even if the function is originally
  submitted without guard verification (typically, using [xargs]
  declaration [47m:verify-guards nil[0m), but only if its guards are
  verified before defining the [47m:program[0m-mode wrapper (e.g., [47mbar[0m
  above).  Thus we see an invariant-risk warning in the call of [47mbar[0m
  below.

    (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

  Here is code that will return a list of all [47m:program[0m-mode functions
  subject to invariant-risk checking that are user-defined (not built
  into ACL2).

    :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)

  To see exactly the executable-counterpart code generated for a
  [47m:program[0m-mode function with invariant-risk, evaluate [47m(trace!
  (oneify-cltl-code :native t))[0m before submitting its definition.")
 (INVISIBLE-FNS-TABLE
  (LOOP-STOPPER)
  "Functions that are invisible to the [loop-stopper] algorithm

    Examples:
    ACL2 !>(invisible-fns-table (w state))
    ((binary-+ unary--)
     (binary-* unary-/)
     (unary-- unary--)
     (unary-/ unary-/))

  Among other things, the setting above has the effect of making
  [47m[unary--][0m ``invisible'' for the purposes of applying permutative
  [47m:[0m[47m[rewrite][0m rules to [47m[binary-+][0m trees.  Also see [add-invisible-fns]
  and see [remove-invisible-fns], which manage macro aliases (see
  [macro-aliases-table]), as well as see [set-invisible-fns-table].

  See [table] for a general discussion of tables.

  The ``invisible functions [table]'' is an alist with elements of the
  following form, where [47mfn[0m is a function symbol and the [47mufni[0m are
  unary function symbols in the current ACL2 [world], and [47mk[0m is at
  least 1.

    (fn ufn1 ufn2 ... ufnk)

  This [table] thus associates with certain function symbols, e.g., [47mfn[0m
  above, a set of unary functions, e.g., the [47mufni[0m above.  The [47mufni[0m
  associated with [47mfn[0m in the invisible functions table are said to be
  ``invisible with respect to [47mfn[0m.'' If [47mfn[0m is not the [47m[car][0m of any
  pair in the [47malist[0m, then no function is invisible for it.  Thus for
  example, setting the invisible functions alist to [47mnil[0m completely
  eliminates the consideration of invisibility.

  The notion of invisibility is involved in the use of the
  [47m:[0m[47m[loop-stopper][0m field of [47m:[0m[47m[rewrite][0m rules to prevent the indefinite
  application of permutative rewrite rules.  Roughly speaking, if
  rewrite rules are being used to permute [47marg[0m and (ufni arg) inside
  of a nest of [47mfn[0m calls, and [47mufni[0m is invisible with respect to [47mfn[0m,
  then [47marg[0m and [47m(ufni arg)[0m are considered to have the same ``weight''
  and will be permuted so as to end up as adjacent tips in the [47mfn[0m
  nest.  See [loop-stopper].")
 (IO
  (INTERFACING-TOOLS STATE PROGRAMMING)
  "Input/output facilities in ACL2

    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))..)))

  Also see [std/io] and [file-reading-example].

  For advanced ways to control printing, see [print-control].

  For a discussion of formatted printing, see [fmt].

  To control ACL2 abbreviation (``evisceration'') of objects before
  printing them, see [set-evisc-tuple], see [without-evisc], and see
  [set-iprint].

  To redirect output to a file, see [output-to-file].

  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 [read-file-into-string]) or
  bidirectional streams.  In Common Lisp, input and output are to or
  from objects of type [47mstream[0m.  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, [47m\"ACL2-INPUT-CHANNEL\"[0m and [47m\"ACL2-OUTPUT-CHANNEL\"[0m.
  When one ``opens'' a file one gets back a channel whose
  [47m[symbol-name][0m is the file name passed to ``open,'' postfixed with
  [47m-n[0m, where [47mn[0m is a counter that is incremented every time an open or
  close occurs.

  There are three channels which are open from the beginning and which
  cannot be closed:

    acl2-input-channel::standard-character-input-0
    acl2-input-channel::standard-object-input-0
    acl2-input-channel::standard-character-output-0

  All three of these are really Common Lisp's [47m*standard-input*[0m or
  [47m*standard-output*[0m, appropriately.

  For convenience, three global variables are bound to these rather
  tedious channel names:

    *standard-ci*
    *standard-oi*
    *standard-co*

  Common Lisp permits one to open a stream for several different kinds
  of [47mio[0m, e.g. character or byte.  ACL2 permits an additional type
  called ``object''.  In ACL2 an ``io-type'' is a keyword, either
  [47m:character[0m, [47m:byte[0m, or [47m:object[0m.  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 [47m:character[0m and
  [47m:byte[0m are familiar.  Type [47m:object[0m is an abstraction not found in
  Common Lisp.  An [47m:object[0m file is a file of Lisp objects.  One uses
  [47mread-object[0m or [47mread-object-with-case[0m (see below) to read from
  [47m:object[0m files and [47m[print-object$][0m, its more flexible variant
  [47m[print-object$+][0m, or [47mprint-object$-preserving-case[0m (see below;
  also, [47mprint-object$-fn[0m) to print to [47m:object[0m files.  (The reading
  and printing are really done with the Common Lisp [47mread[0m and printing
  functions.  For those familiar with [47mread[0m, we note that the
  [47mrecursive-p[0m argument is [47mnil[0m.)  The function [47mread-object-suppress[0m is
  logically the same as [47mread-object[0m except that [47mread-object-suppress[0m
  throws away the second returned value, i.e. the value that would
  normally be read, simply returning [47m(mv eof state)[0m; under the hood,
  [47mread-object-suppress[0m avoids errors, for example those caused by
  encountering symbols in packages unknown to ACL2.

  The functions [47mread-object-with-case[0m is defined logically simply to be
  [47mread-object[0m, while the function [47mprint-object$-preserving-case[0m and
  macro [47m[print-object$+][0m are defined logically simply to be
  [47mprint-object$[0m.  However, these variants generally do I/O
  differently (except that when the host Lisp is GCL,
  [47mprint-object$-preserving-case[0m behaves the same as [47mprint-object$[0m).
  For [47mread-object-with-case[0m the value that is read is affected by an
  extra argument, namely, the second argument: the [3mmode[0m.  The mode is
  one of the keywords [47m:upcase[0m, [47m:downcase[0m, [47m:preserve[0m, or [47m:invert[0m,
  where [47m:upcase[0m gives the same behavior as [47mread-object[0m, and the other
  three modes are handled according to the specification for the
  Common Lisp function, [47mreadtable-case[0m (see for example {the Common
  Lisp HyperSpec's documentation for ``Examples of Effect of
  Readtable Case on the Lisp Reader'' |
  http://www.lispworks.com/documentation/HyperSpec/Body/23_aba.htm}).
  The function [47mprint-object$-preserving-case[0m is somewhat analogous:
  it is defined logically to be [47mprint-object$[0m 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 [47m\"abc\"[0m will be printed as [47mabc[0m, not as
  [47m|abc|[0m.  But note that [47mprint-object$-preserving-case[0m 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 [47m|1u|[0m.  Using
  [47mprint-object$-preserving-case[0m, this prints simply as [47m1u[0m in CCL and
  Allegro CL, but it is printed as [47m|1u|[0m in SBCL, LispWorks, and CMUCL
  --- at least in the implementations that we tested!

  [47mFile-name[0m arguments are strings (except for the [47m:STRING[0m case
  discussed below).  ACL2 does not support the Common Lisp type
  [47m[pathname][0m; 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 [cbd].  You can do that elaboration
  yourself with a directory [47mdir[0m using [47m(extend-pathname dir file-name
  state)[0m; see [extend-pathname].

  For the [47mfile-name[0m argument of the output-related functions listed
  below, ACL2 supports a special value, [47m:STRING[0m.  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 [47mget-output-stream-string$[0m.

  Here are the names, formals and output descriptions of the ACL2 io
  functions.

    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))

  Note that [47mopen-output-channel[0m and [47mopen-output-channel![0m will attempt
  to create directories as needed (but this is not the case for
  [47mopen-input-channel[0m).  For example, the following can succeed in
  writing to the indicated file by creating subdirectory [47m\"dir4\"[0m if
  that directory does not already exist.

    (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)))

  The ``formatting'' functions are particularly useful; see [fmt] and
  see [cw].  In particular, [47m[cw][0m prints to a ``comment window'' and
  does not involve the ACL2 [47m[state][0m, so many may find it easier to
  use than [47m[fmt][0m and its variants.  The functions [47m[fms!][0m, [47m[fmt!][0m, and
  [47m[fmt1!][0m are the same as their respective functions without the
  ``[47m![0m,'' except that the ``[47m![0m'' functions are guaranteed to print
  forms that can be read back in (at a slight readability cost).

  When one enters ACL2 with [47m(lp)[0m, input and output are taken from
  [47m[*standard-oi*][0m to [47m[*standard-co*][0m.  Because these are synonyms for
  [47m*standard-input*[0m and [47m*standard-output*[0m, one can drive ACL2 io off
  of arbitrary Common Lisp streams, bound to [47m*standard-input*[0m and
  [47m*standard-output*[0m before entry to ACL2.

  The macro [47mget-output-stream-string$[0m 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 [47mt[0m), and if it evaluates to [47mnil[0m 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.

    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 !>

  Also see [printing-to-strings] for a discussion of formatted printing
  functions such as [47mfmt-to-string[0m that do not take a channel or
  [47m[state][0m argument and return a string.

  By default, symbols are printed in upper case when vertical bars are
  not required, as specified by Common Lisp.  See [set-print-case]
  for how to get ACL2 to print symbols in lower case.

  By default, numbers are printed in radix 10 (base 10).  See
  [set-print-base-radix] for how to get ACL2 to print numbers in
  radix 2, 8, or 16.

  To see the [guard] of an IO function, or indeed any function, see
  [args] or call the function [47mguard[0m; but some built-in functions
  (including some IO functions) will print the result using the
  variable [47mSTATE-STATE[0m.  While that is logically correct, if you want
  to execute the guard then you should replace that variable by [47mSTATE[0m
  and also replace each built-in function symbol of the form [47mxxx-p1[0m
  by corresponding function symbol [47mxxx-p[0m.  Consider the following
  example.

    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 !>

  If you want to execute the guard for [47m[princ$][0m, then according to the
  suggestion above, you should consider the guard for [47m(princ$ x
  channel state)[0m to be as follows.

    (AND (OR (ACL2-NUMBERP X)
             (CHARACTERP X)
             (STRINGP X)
             (SYMBOLP X))
         (STATE-P STATE)
         (SYMBOLP CHANNEL)
         (OPEN-OUTPUT-CHANNEL-P CHANNEL :CHARACTER STATE))

  For example, we can check the guard for a given value and channel as
  follows.

    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 !>

  Comment for advanced users: Function [47m[open-output-channel!][0m is
  identical as a function to [47mopen-output-channel[0m, except that the
  former may be called even during [47m[make-event][0m expansion and
  [47m[clause-processor][0m [hints], but requires that there is an active
  trust tag (see [defttag]).

  Finally, we note that the [std/io] library contains useful file io
  functions whose definitions illustrate some of the features
  described above, as does the definition of [47m[write-list][0m in
  [community-book] [47mbooks/misc/file-io.lisp[0m.


Subtopics

  [*standard-ci*]
      An ACL2 character-based analogue of CLTL's [47m*standard-input*[0m

  [*standard-co*]
      The ACL2 analogue of CLTL's [47m*standard-output*[0m

  [*standard-oi*]
      An ACL2 object-based analogue of CLTL's [47m*standard-input*[0m

  [Character-encoding]
      How bytes are parsed into characters

  [Cw]
      Print to the comment window

  [Cw!]
      Print readably to the comment window

  [Cw!+]
      Print readably and uninhibited to the comment window

  [Cw+]
      Print uninhibited to the comment window

  [Cw-print-base-radix]
      Print to the comment window in a given print-base

  [Cw-print-base-radix!]
      Print to the comment window in a given print-base

  [Delete-file$]
      Delete a file

  [Evisc-tuple]
      Control suppression of details when printing

  [Eviscerate-hide-terms]
      To print [47m(hide ...)[0m as [47m<hidden>[0m

  [Extend-pathname]
      Extend a relative pathname to an absolute pathname

  [File-length$]
      The size of a file in bytes

  [File-write-date$]
      The write-date of a file as a natural number

  [Fms]
      [47m(fms str alist co-channel state evisc) => state[0m

  [Fms!]
      [47m(fms! str alist co-channel state evisc) => state[0m

  [Fmt]
      Formatted printing

  [Fmt!]
      [47m(fmt! str alist co-channel state evisc) => state[0m

  [Fmt-to-comment-window]
      Print to the comment window

  [Fmt-to-comment-window!]
      Print readably to the comment window

  [Fmt-to-comment-window!+]
      Print readably and uninhibited to the comment window

  [Fmt-to-comment-window+]
      Print uninhibited to the comment window

  [Fmt1]
      [47m(fmt1 str alist col co-channel state evisc) => (mv col state)[0m

  [Fmt1!]
      [47m(fmt1! str alist col channel state evisc) => (mv col state)[0m

  [Fmx]
      [47m(fmx str &rest args) => state[0m

  [Fmx-cw]
      [47m(fmx-cw str &rest args) => state[0m

  [Msg]
      Construct a ``message'' suitable for the [47m~@[0m directive of [47m[fmt][0m

  [Msgp]
      Recognizer for a ``message''

  [Newline]
      Print a newline to a given output channel

  [Observation]
      Print an observation

  [Open-output-channel!]
      When trust tags are needed to open output channels

  [Output-controls]
      Methods for controlling the output produced by the ACL2 prover

  [Output-to-file]
      Redirecting output to a file

  [Ppr-special-syms]
      A [table] to control indentation for pretty-printing

  [Princ$]
      Print an atom

  [Print-base-p]
      Recognizer for print bases that are understood by functions such as
      [explode-nonnegative-integer] and [explode-atom].

  [Print-control]
      Advanced controls of ACL2 printing

  [Print-object$]
      Print an object to an open object output channel

  [Print-object$+]
      Print an object to an open output channel in a specified manner

  [Printing-to-strings]
      Printing to strings instead of files or standard output

  [Probe-file]
      Determine whether a file exists

  [Proofs-co]
      The proofs character output channel

  [Read-file-into-string]
      The contents of a file (or part of it) as a string

  [Serialize]
      Routines for saving ACL2 objects to files, and later restoring them

  [Set-evisc-tuple]
      Control suppression of details when printing

  [Set-fmt-hard-right-margin]
      Set the right margin for formatted output

  [Set-fmt-soft-right-margin]
      Set the soft right margin for formatted output

  [Set-iprint]
      Control whether abbreviated output can be read back in

  [Set-print-base]
      Control radix in which numbers are printed

  [Set-print-base-radix]
      Control radix in which numbers are printed and printing of the radix

  [Set-print-case]
      Control whether symbols are printed in upper case or in lower case

  [Set-print-radix]
      Control printing of the radix for numbers

  [Standard-co]
      The character output channel to which [47m[ld][0m prints

  [Standard-oi]
      The standard object input ``channel''

  [Trace-co]
      The [trace] character output channel

  [Without-evisc]
      Print output in full

  [Wof]
      Direct standard output and proofs output to a file")
 (IO? (POINTERS)
      "See [system-utilities].")
 (IPRINT (POINTERS) "See [set-iprint].")
 (IPRINTING (POINTERS)
            "See [set-iprint].")
 (IRRELEVANT-FORMALS
  (PROGRAMMING)
  "Formals that are used but only insignificantly

  Let [47mfn[0m be a function of [47mn[0m arguments.  Let [47mx[0m be the [47mi[0mth formal of [47mfn[0m.
  We say [47mx[0m is ``irrelevant in [47mfn[0m'' if [47mx[0m does not occur in either the
  [guard] or the measure for [47mfn[0m, and the value of [47m(fn a1...ai...an)[0m
  is independent of [47mai[0m.

  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 [47m[declare][0md [47mignore[0md or [47mignorable[0m, or if it
  occurs free in an [47m[xargs][0m term associated with [47m:[0m[measure],
  [47m:[0m[guard], or [47m:[0m[47m[split-types][0m, then it will not be reported as
  irrelevant.

  An example of an irrelevant formal is [47mx[0m in the definition of [47mfact[0m
  below.

    (defun fact (i x)
      (declare (xargs :guard (and (integerp i) (<= 0 i))))
      (if (zp i) 1 (* i (fact (1- i) (cons i x))))).

  Observe that [47mx[0m is only used in recursive calls of [47mfact[0m; 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
  [47mi[0mth formal is only used in the [47mi[0mth argument position of recursive
  calls, then it is clearly irrelevant.  This is how [47mx[0m is used above.

  It is possible for a formal to appear only in recursive calls but not
  be clearly irrelevant, or even irrelevant at all.  For example, [47mx[0m
  is [31;1mnot[0m irrelevant below, even though it only appears in the
  recursive call.

    (defun fn (i x y)
      (if (zp i) y (fn (1- i) y x)))

  The following examples show the relevance of [47mx[0m.

    ACL2 !>(fn 1 3 0)
    3
    ACL2 !>(fn 1 4 0)
    4
    ACL2 !>

  The key observation for the definition of [47mfn[0m is that while [47mx[0m only
  appears in a recursive call, it appears in the argument position
  for a formal that is not clearly irrelevant, namely [47my[0m's.

  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 [47mx[0m irrelevant below?

    (defun test (i j k x) (if (p i j k) 0 x))

  Note that the value of [47m(test i j k x)[0m is independent of [47mx[0m --- thus
  making [47mx[0m irrelevant --- precisely if [47m(p i j k)[0m is a theorem.
  ACL2's syntactic analysis of a definition to determine the
  ``clearly irrelevant'' formals does not guarantee to notice all
  irrelevant formals.

  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 [47m[declare][0m the irrelevant
  formals, for example as follows.

    (defun fact (i x)
      (declare (irrelevant x))
      (if (zp i) 0 (* i (fact (1- i) (cons i x)))))

  Note that an [47mirrelevant[0m declaration is only legal for a [47m[defun][0m form,
  not in other contexts that allow declarations ([47m[let][0m, etc.).

  To turn off the checking of irrelevant formals globally (though we do
  not recommend avoiding those checks), see
  [set-irrelevant-formals-ok].  In that case ACL2 will ignore every
  [47mirrelevant[0m declaration.  But otherwise, and by default, if you
  provide an [47mirrelevant[0m declaration (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.")
 (KEEP
  (BOOKS-TOUR)
  "How we know if [47m[include-book][0m read the correct files

  The certificate (see [certificate] for general information) of a
  certified file contains a [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 [book-hash] values used after the book has been included,
  to determine if the files read were (up to book-hash) those
  certified.

  Once the [portcullis] is open, [47m[include-book][0m can enter the book and
  read the event forms therein.  The non-[47m[local][0m event forms are in
  fact executed, extending the host theory.  That may read in other
  [books].  When that has been finished, the keep of the
  [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 [book-hash] values for those [books] at the time of
  certification.  We compare the book-hash values of the [books] just
  included to those of the [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.

  See [include-book] to continue the guided tour through [books].")
 (KEYWORD (POINTERS) "See [keywordp].")
 (KEYWORD-COMMANDS
  (LD)
  "How keyword commands like [47m:u[0m and [47m:pbt[0m are processed

    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

  When a keyword, [47m:key[0m, is read as a command, ACL2 determines whether
  the symbol with the same name in the [47m\"ACL2\"[0m package, [47macl2::key[0m, is
  a function or simple macro of n arguments.  If so, ACL2 reads [47mn[0m
  more objects, [47mobj1[0m, ..., [47mobjn[0m, and then acts as though it had read
  the following form (for a given [47mkey[0m):

    (ACL2::key 'obj1 ... 'objn)

  Thus, by using the keyword command hack you avoid typing the
  parentheses, the [47m\"ACL2\"[0m package name, and the quotation marks.

  See [ld-keyword-aliases] for how to customize this behavior.

  Note the generality of this hack.  Any function or macro in the
  [47m\"ACL2\"[0m 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 [47m\"ACL2\"[0m package.

  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 [47m&optional[0m, [47m&rest[0m, [47m&body[0m, or [47m&key[0m
  arguments are read for that call.  The macro is thus called with
  only its required arguments.  The following log illustrates this
  caveat.

    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 !>

  What happened?  First, the command [47m:set-iprint[0m was read.  Since the
  macro [47m[set-iprint][0m has no required arguments, the ACL2 evaluator
  was then called on the form [47m(set-iprint)[0m, that is, calling the
  macro on no arguments.  [47mSet-iprint[0m 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 [47mt[0m that had been supplied
  by the user.  So the query returned immediately and the [47mset-iprint[0m
  call was completed.")
 (KEYWORD-LISTP
  (LISTS KEYWORDP ACL2-BUILT-INS)
  "Recognizer for true lists of keywords

  The call [47m(keyword-listp x)[0m return [47mt[0m when [47mx[0m is a true-list whose
  members are all [keyword]s, else returns [47mnil[0m.")
 (KEYWORD-VALUE-LISTP
  (KEYWORDP LISTS ACL2-BUILT-INS)
  "Recognizer for true lists whose even-position elements are keywords

  [47m(Keyword-value-listp l)[0m is true if and only if [47ml[0m is a list of even
  length of the form [47m(k1 a1 k2 a2 ... kn an)[0m, where each [47mki[0m is a
  keyword.  To list the keys [47mki[0m and values [47mai[0m of [47ml[0m evaluate [47m(evens l)[0m
  and [47m(odds l)[0m, respectively.

  [31;1mFunction: [0m<keyword-value-listp>

    (defun keyword-value-listp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (null l))
            (t (and (keywordp (car l))
                    (consp (cdr l))
                    (keyword-value-listp (cddr l))))))


Subtopics

  [Assoc-keyword]
      Look up key in a [47m[keyword-value-listp][0m")
 (KEYWORDP
  (SYMBOLS ACL2-BUILT-INS)
  "Recognizer for keywords

  [47m(Keywordp x)[0m is true if and only if [47mx[0m is a keyword, i.e., a symbol in
  the \"KEYWORD\" package.  Such symbols are typically printed using a
  colon (:) followed by the [47m[symbol-name][0m of the symbol.

  [47mKeywordp[0m has a [guard] of [47mt[0m.

  [47mKeywordp[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.  The following log may be
  illuminating.

    ACL2 !>(intern \"ABC\" \"KEYWORD\")
    :ABC
    ACL2 !>(symbol-name ':ABC)
    \"ABC\"
    ACL2 !>(symbol-package-name ':ABC)
    \"KEYWORD\"
    ACL2 !>

  [31;1mFunction: [0m<keywordp>

    (defun keywordp (x)
      (declare (xargs :guard t))
      (and (symbolp x)
           (equal (symbol-package-name x)
                  \"KEYWORD\")))


Subtopics

  [Keyword-listp]
      Recognizer for true lists of keywords

  [Keyword-value-listp]
      Recognizer for true lists whose even-position elements are keywords")
 (KNOWN-PACKAGE-ALIST (POINTERS)
                      "See [system-utilities].")
 (KWOTE
  (TERM ACL2-BUILT-INS)
  "Quote an arbitrary object

  For any object [47mx[0m, [47m(kwote x)[0m returns the two-element list whose
  elements are the symbol [47mquote[0m and the given [47mx[0m, respectively.  The
  guard of [47m(kwote x)[0m is [47mt[0m.

  [31;1mFunction: [0m<kwote>

    (defun kwote (x)
      (declare (xargs :guard t))
      (mbe :logic (list 'quote x)
           :exec (cond ((eq x nil) *nil*)
                       ((eq x t) *t*)
                       ((eql x 0) *0*)
                       ((eql x 1) *1*)
                       ((eql x -1) *-1*)
                       (t (list 'quote x)))))")
 (KWOTE-LST
  (TERM ACL2-BUILT-INS)
  "Quote an arbitrary true list of objects

  The function [47mkwote-lst[0m applies the function [47mkwote[0m to each element of
  a given list.  The guard of [47m(kwote-lst lst)[0m is [47m(true-listp lst)[0m.

  [31;1mFunction: [0m<kwote-lst>

    (defun kwote-lst (lst)
      (declare (xargs :guard (true-listp lst)))
      (cond ((endp lst) nil)
            (t (cons (kwote (car lst))
                     (kwote-lst (cdr lst))))))")
 (L<
  (TERM APPLY$)
  "Ordering on naturals or lists of naturals

  The function [47ml<[0m 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 [47mlex-fix[0m to two objects
  before comparing them with [47ml<[0m.  Below are the relevant definitions.

  [31;1mFunction: [0m<l<>

    (defun l< (x y)
      (declare (xargs :guard (and (lexp x) (lexp y))))
      (or (< (len x) (len y))
          (and (= (len x) (len y))
               (if (atom x) (< x y) (d< x y)))))

  [31;1mFunction: [0m<lexp>

    (defun lexp (x)
      (declare (xargs :guard t))
      (or (natp x)
          (and (consp x) (nat-listp x))))

  [31;1mFunction: [0m<d<>

    (defun d< (x y)
      (declare (xargs :guard (and (nat-listp x) (nat-listp y))))
      (and (consp x)
           (consp y)
           (or (< (car x) (car y))
               (and (= (car x) (car y))
                    (d< (cdr x) (cdr y))))))

  [31;1mFunction: [0m<lex-fix>

    (defun lex-fix (x)
      (declare (xargs :guard t))
      (cond ((atom x) (nfix x))
            (t (nfix-list x))))

  [31;1mFunction: [0m<nfix-list>

    (defun nfix-list (list)
      (declare (xargs :guard t))
      (if (consp list)
          (cons (nfix (car list))
                (nfix-list (cdr list)))
        nil))")
 (LAMBDA (TERM APPLY$)
  "Lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions

  The word ``lambda'' occurs in several different contexts in ACL2.
  When we are being precise our meanings are as outlined below.

    * lambda expression -- This phrase is used to describe the syntactic
      entity beginning with the symbol [47mlambda[0m that is allowed to
      occupy the ``function'' position in an ACL2 [term].  Lambda
      expressions are most often created when [47mlet[0m expressions are
      translated into their formal counterparts.  We provide an
      example below.

    * [47mLAMBDA[0m object -- An ACL2 list constant interpreted as a ``function''
      by [47m[apply$][0m.  [47mLAMBDA[0m objects may be written in terms by quoting
      them.  However, we urge the user to introduce [47mLAMBDA[0m objects
      into terms by using the built-in macro [47m[lambda$][0m.  We provide
      examples below.

    * [47mlambda$[0m expressions -- These are untranslated terms beginning with
      the macro symbol [47mlambda$[0m.  They expand during translation to
      quoted [47mLAMBDA[0m objects.  We provide examples below.

  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!


About Lambda Expressions

  Consider the function [47modd-evenp[0m, defined with

    (defun odd-evenp (x)
      (if (zp x)
          -1
          (let ((ans (odd-evenp (- x 1))))
            (* (+ ans 1) (- ans 1)))))

  Distracting Aside: Can you see why we gave this function this name?
  Hint: We might have named it ``weird [47mevenp[0m.''

  The translated body of [47modd-evenp[0m is

    (if (zp x)
        '-1
        ((lambda (ans)
                 (binary-* (binary-+ ans '1)
                           (binary-+ '-1 ans)))
         (odd-evenp (binary-+ '-1 x))))

  The syntactic entity in the function position of the term in the
  false branch, namely

    (lambda (ans)
      (binary-* (binary-+ ans '1)
                (binary-+ '-1 ans)))

  is a lambda expression.

  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 [47modd-evenp[0m where the
  recursive call is outside of the lambda expression.)  For more
  details on the formal representation of ACL2 terms, see [term].


About [47mLAMBDA[0m Objects

  Prior to Version 8.0 when [47mapply$[0m 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 [47mapply$[0m 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!

  When [47m[apply$][0m was introduced, [47mLAMBDA[0m objects became a formally
  supported concept in the ACL2 implementation and we started using
  ``[47mLAMBDA[0m objects'' to refer to them.  A [47mLAMBDA[0m object is generally
  a list, either of the form [47m(LAMBDA vars body)[0m or [47m(LAMBDA vars dcl
  body)[0m.  There are additional restrictions on [47mvars[0m, [47mdcl[0m, and [47mbody[0m
  that we discuss later.  But [47mapply$[0m treats any [47mconsp[0m object and
  tries to extract those components by rudimentary pattern matching.
  An example of a [47mLAMBDA[0m object is the list of length three [47m(LAMBDA
  (x) (BINARY-+ '1 X))[0m.

  Generally speaking when [47mLAMBDA[0m objects occur in translated terms they
  are [47mquote[0md, as in

    (collect$ '(LAMBDA (X) (BINARY-+ '1 X)) lst)

  To highlight the fact that these objects are constants, we try to
  write them in UPPERCASE and [47mtypewriter[0m font in this documentation.
  For the same reason, we generally write ``[47mLAMBDA[0m object'' rather
  than ``lambda object.''

  But of course there's no difference between the symbol [47mLAMBDA[0m and the
  symbol [47mlambda[0m.  Furthermore, [47mLAMBDA[0m 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 [47mapply$[0m.  So one
  could write

    (collect$ (list 'lambda '(x) '(binary-+ '1 x)) lst)

  and we would say that the value of the term in the first argument of
  [47mcollect$[0m is a [47mLAMBDA[0m object.

  Beware, however, that consing up [47mLAMBDA[0m objects defeats the [ilk]
  analysis in [47m[defwarrant][0m and the [tame]ness analysis of [47mapply$[0m and
  hence prevents functions containing such terms from being [47mapply$[0md.

  According to the definitional axiom defining [47m[apply$][0m, any object
  satisfying [47mconsp[0m is treated as a [47mLAMBDA[0m object.  [47mApply$[0m uses
  ``accessor'' functions to extract the ``formals'' and ``body'' of
  the object and proceeds to [47m[ev$][0m the body in an alist binding the
  formals.  But [47mev$[0m insists that the expression object being
  evaluated be [tame] or else assigns it a default value.  This
  insistence on tameness is due to fundamental logical reasons;
  otherwise, [47mapply$[0m would allow us to prove [47mNIL[0m.  So axiomatically
  [47mapply$[0m operates as ``naively expected'' only on [47mtamep-lambdap[0m
  objects.  One consequence of this, which we expect will be a minor
  inconvenience, is that unlike ACL2's lambda expressions [47mapply$[0m's
  [47mLAMBDA[0m objects, when used in definitions of new functions, may not
  include recursive calls of the function being defined because they
  fail the tameness test.

  But wait!  There's more.  Execution efficiency of [47mapply$[0m 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 [47mLAMBDA[0m objects most efficiently they
  must be well-formed, which is a concept even stronger than
  tameness.  Among other requirements, well-formed [47mLAMBDA[0m 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 [47m[well-formed-lambda-objectp][0m if you
  want, but we don't encourage beginners to go there!

  Note: Even well-formedness is not enough to guarantee execution of
  compiled code.  The [47mLAMBDA[0m object must also be guard verified (see
  [47m[verify-guards][0m for a discussion) and its guard must be satisfied
  by the arguments to which it is applied.

  Note: A peculiar aspect of [47mLAMBDA[0m objects is that they can be written
  as legal ACL2 constants [3mbefore[0m they are well-formed [47mLAMBDA[0m objects,
  e.g., by referring to undefined functions, [47m:program[0m mode functions,
  unbadged functions, etc.  They are, after all, just arbitrary
  quoted objects and any value in ACL2 can be quoted.  An ill-formed
  [47mLAMBDA[0m object can [3mbecome[0m well-formed if the world is appropriately
  extended, e.g., the appropriate [47mdefun[0ms or [47mdefwarrant[0ms are made.
  Perhaps worse, they can be well-formed and then [3mbecome[0m ill-formed
  by an undo.  So at runtime [47mapply$[0m has to check that the function
  symbol or [47mLAMBDA[0m object is appropriate.  There is a sophisticated
  cache behind the execution machinery for [47mLAMBDA[0m objects in the
  evaluation theory.  See [47m[print-cl-cache][0m.


About Lambda$ Expressions

  Rather than force users to type well-formed [47mLAMBDA[0m objects as quoted
  constants, ACL2 provides a macro allowing you to enter [47mLAMBDA[0m
  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).

  That macro -- which is not really a defined macro but is built into
  ACL2's translation mechanism -- is called [47m[lambda$][0m and uses of it
  in terms are called ``[47mlambda$[0m expressions.'' [47mLambda$[0m expressions
  may only be used in argument slots of [ilk] [47m:FN[0m.

  An example of a [47mlambda$[0m expression is the first argument of [47mcollect$[0m
  in

    (collect$ (lambda$ (x) (+ 1 x)) lst)

  That [47mlambda$[0m expression essentially translates to the quoted
  well-formed [47mLAMBDA[0m object

    '(LAMBDA (X) (BINARY-+ '1 X))

  Note that the body is fully translated, unlike its appearance in the
  [47mlambda$[0m expression.  We say ``essentially'' because [47mlambda$[0m always
  add a [47m(DECLARE (IGNORABLE v1 ... vn))[0m that includes every formal.
  In addition, except when translating in theorems, [47mlambda$[0m tags the
  translated body with a [47m[return-last][0m expression to indicate it came
  from a [47mlambda$[0m.  Despite these differences, the meaning of the
  translated [47mlambda$[0m is the simple quoted [47mLAMBDA[0m object shown.

  [47mLambda$[0m expressions never appear in a fully translated term.  All the
  [47mlambda$[0m objects will have been translated into quoted [47mLAMBDA[0m
  objects.

  The body of a [47mlambda$[0m expression must return a single value that is
  neither a [stobj] nor a [df].  The following example illustrates
  this point.

    (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)))

  Finally, to see how a [47mlambda$[0m expression translates, see [47m[translam][0m.")
 (LAMBDA$ (APPLY$)
  "Lambda object constructor for use with [47mapply$[0m

  [47mLambda$[0m is a built-in ACL2 ``macro'' that allows you to enter
  well-formed fully-translated quoted [47mLAMBDA[0m objects in argument
  positions of ilk [47m:FN[0m.  We urge you to use [47mlambda$[0m instead of trying
  to type quoted [47mLAMBDA[0m objects meant for use by [47mapply$[0m.  We explain
  and document [47mlambda$[0m below.

  Intuitively, a quoted [47mLAMBDA[0m object is a quoted constant like

    '(LAMBDA (X) (BINARY-+ '1 X))

  e.g., a quoted constant beginning with the symbol [47mLAMBDA[0m and listing
  some formal variables, possibly some declarations, and a fully
  translated body satisfying various rules.  [47m[Apply$][0m can handle
  quoted [47mLAMBDA[0m objects provided they have the right basic shape and
  all the listed formals are symbols and the bodies are [tame].  But
  it is difficult to type fully translated bodies and, for runtime
  efficiency, it is important that the quoted [47mLAMBDA[0m objects satisfy
  additional (logically unnecessary) well-formedness restrictions
  allowing faster guard checking and compilation.

  One should strive to always enter ``well-formed [47mLAMBDA[0m objects.'' The
  details of well-formedness may be found in
  [47m[well-formed-lambda-objectp][0m but our hope is that mastering those
  details is unnecessary because ACL2 provides a built-in ``macro,''
  [47mlambda$[0m, for constructing quoted well-formed [47mLAMBDA[0m objects.  We
  urge you to use [47mlambda$[0m instead of typing quoted [47mLAMBDA[0m objects!
  That is, write [47m(lambda$ (x) (+ 1 x))[0m instead of [47m'(LAMBDA (X)
  (BINARY-+ '1 X))[0m.

  [47mLambda$[0m [3mterms may only appear in argument slots of ilk[0m [47m:FN[0m!

    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)
                                         (< (- n 1) (length lst)))))
             (nth (- n 1) lst))

    General Form:
    (lambda$ vars dcl* body)

  where the [47mlambda$[0m expression occurs in an argument position of ilk
  [47m:FN[0m, [47mvars[0m is a list of distinct variable names, [47mdcl*[0m is zero or
  more [47mDECLARE[0m forms as described below, and [47mbody[0m 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
  [47m(loop$ ... DO ...)[0m.  [47mBody[0m must satisfy the same restrictions one
  would expect in a non-recursive [47m[defun][0m event with the same
  formals, declarations and body.  In particular, [47mbody[0m should contain
  no free variables other than those listed in [47mvars[0m.  [47mLambda$[0m always
  adds a declaration that every formal is ignorable and, hence, we
  prohibit you from adding [47mignore[0m or [47mignorable[0m declarations in the
  [47mlambda$[0m expression itself.  [47mLambda$[0m expands to a well-formed quoted
  [47mLAMBDA[0m object or else causes a translate-time error.

  The allowed [47mDECLARE[0m forms in [47mlambda$[0m are [47mtype[0m and [47mxargs[0m.
  Furthermore, the only [47m[xargs][0m keywords allowed are [47m:guard[0m and
  [47m:split-types[0m.  The other [47mXARGS[0m keywords, such as [47m:measure[0m, [47m:hints[0m
  or [47m:guard-hints[0m, play no role.


About [47mLambda$[0ms and Prover Output

  The translated form of a [47mlambda$[0m expression is a quoted [47m[lambda][0m
  object.  For example, [47m(collect$ (lambda$ (x) (+ 1 x)) lst)[0m
  translates to

    (COLLECT$ '(LAMBDA (X)
                     (DECLARE (IGNORABLE X))
                     (RETURN-LAST 'PROGN
                                  '(LAMBDA$ (X) (+ 1 X))
                                  (BINARY-+ '1 X)))
              LST)

  The [47mlambda$[0m has been replaced by a quoted [47mlambda[0m.

  The prover tries to print each quoted [47mlambda[0m object (that occurs an
  argument position of [ilk] :[47mFN[0m) as a [47mlambda$[0m expression that is
  (provably) functionally equal (see [47m[fn-equal][0m) to the original
  [47mlambda[0m object assuming the necessary warrants.  If the quoted
  [47mlambda[0m object was produced by the expansion of a [47mlambda$[0m expression
  and has not been simplified by subsequent rewriting, it will print
  as the original [47mlambda$[0m expression.  This can be unfortunate if the
  original [47mlambda$[0m expression was itself produced by a macro and
  contains logically irrelevant (but operationally important) tags.
  This phenomenon occurs most often when [47m[do-loop$][0ms are involved.

  Furthermore, since you are allowed to type in quoted [47mlambda[0m objects
  directly, you may --- or may not --- see them printed by the prover
  as [47mlambda$[0m expressions, depending on whether a suitable [47mlambda$[0m is
  found.  If a quoted [47mlambda[0m object contains a reference to a
  function symbol for which no [47m[warrant][0m has been issued there is
  probably no provably equivalent [47mlambda$[0m.

  The main lessons here are

    * you should use [47mlambda$[0m rather than quoted [47mlambda[0m objects in your
      prover input,

    * you should make sure to warrant every user-defined function in your
      [47mlambda$[0m expressions, and

    * if you see a quoted [47mlambda[0m object rather than a [47mlambda$[0m expression in
      your prover output, that quoted [47mlambda[0m object probably involves
      unwarranted symbols which will make it impossible to prove
      anything interesting about it.

  If you do not want the prover output to give special treatment to
  quoted [47mlambda[0m objects in :[47mFN[0m slots, do

    (defattach-system (untranslate-lambda-object-p
                      constant-nil-function-arity-0))

  With this attachment, the prover will print all quoted [47mlambda[0m 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 [47mlambda$[0m.  See
  [gratuitous-lambda-object-restrictions].


About Guard Verification of Lambda Objects

  Quoted [47mLAMBDA[0m objects, whether produced by hand (don't!) or by
  [47mlambda$[0m may have guards.  If the [47mLAMBDA[0m object is well-formed its
  guard plays the same role the guard of a defined function symbol
  plays when the object is [47mapply$[0md.  If the guard can be verified to
  imply the guards of the body (which we call [3mguard verification[0m),
  and if the guard holds of the actuals to which the object is
  applied (which we call [3mguard checking[0m), a compiled version of the
  object is run.  Otherwise, depending on how [47m[set-guard-checking][0m
  has been configured, either an error is signaled or the object is
  interpreted under the axioms defining [47mapply$[0m and [47mev$[0m.  [47mApply$[0m
  caches its investigations into guard verification (but not guard
  checking) and compilation.  We discuss the cache in
  [47m[print-cl-cache][0m.

  When a guarded quoted [47mLAMBDA[0m object is used in a [47m:FN[0m slot of a
  function definition, its guards are verified as part of the guard
  verification step of [47mdefun[0m or [47mverify-guards[0m.  If that guard
  verification fails, checkpoints will be printed and you can use
  [47m:guard-hints[0m or [47m:hints[0m in the [47mdefun[0m or [47mverify-guards[0m events to
  supply the necessary guidance.  When successful, the guard verified
  [47mLAMBDA[0m objects in the [47mdefun[0m are recorded in the cache.

  But unlike defined function symbols, whose guards may be verified at
  [47mdefun[0m-time or at [47mverify-guards[0m-time, quoted [47mLAMBDA[0m expressions may
  be introduced without an associated event.  For example, the user
  may simply type

    ACL2 !>(apply$ (lambda$ (x)
                            (declare (type (satisfies natp) x))
                            (* x x))
                   '(5))

  giving [47mapply$[0m a [47mLAMBDA[0m object never before seen.

  So [47mapply$[0m must be ready to verify the guards of a quoted [47mLAMBDA[0m
  object before attempting to apply it.  This is in contrast to what
  happens when [47mapply$[0m is given a quoted function symbol.  ([47mApply$[0m can
  just look up whether a function symbol has been guard verified.)

  To try to verify the guards of a quoted [47mLAMBDA[0m expression, [47mapply$[0m
  limits itself to tau reasoning (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.

  Interpreting small quoted [47mLAMBDA[0m objects can be done relatively
  quickly.  After all, when the interpreter reaches a guard verified
  function symbol inside the [47mLAMBDA[0m body it runs compiled code.  It's
  only the body itself that is interpreted.

  But the tau system is pretty weak and so will be unable to verify
  some non-trivial guard conjectures, which will mean the [47mLAMBDA[0m
  object is interpreted.  If the [47mLAMBDA[0m 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 [47m[verify-guards][0m, which as of
  Version 8.1 takes [47mLAMBDA[0m objects and [47mlambda$[0m terms and updates the
  cache.  E.g.,

    (verify-guards
      (lambda$ (x)
               (declare (type (satisfies natp) x))
               (* x x)))

  While this functionality is available to you, deciding that you need
  to use it is problematic.  [47mApply$[0m prints no warning that it has
  failed to verify the guards of a [47mLAMBDA[0m object and is running
  interpreted code.  However, the utility [47m[print-cl-cache][0m provides
  basic information about the cache and its documentation may help
  you discover which [47mLAMBDA[0m objects in use are unverified.")
 (LAMBDA-APPLICATIONP (POINTERS)
                      "See [system-utilities].")
 (LAMBDA-BODY (POINTERS)
              "See [system-utilities].")
 (LAMBDA-FORMALS (POINTERS)
                 "See [system-utilities].")
 (LAST
  (LISTS ACL2-BUILT-INS)
  "The last [47m[cons][0m (not element) of a list

  [47m(Last l)[0m is the last [47m[cons][0m of a list, [47ml[0m.  Here are examples.

    ACL2 !>(last '(a b . c))
    (B . C)
    ACL2 !>(last '(a b c))
    (C)

  [47m(Last l)[0m has a [guard] of [47m(listp l)[0m; thus, [47ml[0m need not be a
  [47m[true-listp][0m.

  [47mLast[0m 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 [47mlast[0m.

  [31;1mFunction: [0m<last>

    (defun last (l)
      (declare (xargs :guard (listp l)))
      (if (atom (cdr l)) l (last (cdr l))))")
 (LAST-CDR
  (LISTS ACL2-BUILT-INS)
  "The last [47m[cdr][0m of a list

  [47m(Last-cdr x)[0m is [47mx[0m if [47mx[0m is an [47m[atom][0m, and otherwise is the last [47m[cdr][0m
  of a list.  Here are examples.

    ACL2 !>(last-cdr '(a b . c))
    C
    ACL2 !>(last-cdr '(a b c))
    NIL

  [47m(Last-cdr x)[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<last-cdr>

    (defun last-cdr (x)
      (declare (xargs :guard t))
      (if (atom x) x (cdr (last x))))")
 (LAST-PROVER-STEPS
  (SET-PROVER-STEP-LIMIT WITH-PROVER-STEP-LIMIT
                         PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "The number of prover steps most recently taken

  For discussions of prover step limits, See [set-prover-step-limit]
  and see [with-prover-step-limit].

  The [summary] printed for an [event] typically includes a line
  showing the prover steps counted, for example as follows.

    Prover steps counted:  7240

  The value of the form [47m(last-prover-steps state)[0m indicates the number
  of prover steps taken, in the sense described below, for the most
  recent context in which an event [summary] would normally be
  printed.  Note that the value of [47m(last-prover-steps state)[0m is
  updated for all [events], and more generally, for all forms that
  are set up to print a [summary], such as calls of [47m[thm][0m or
  [47m[certify-book][0m --- regardless of whether or not summary output is
  inhibited (see [set-inhibit-output-lst] and see
  [set-inhibited-summary-types]).  In particular, the value is
  updated (typically to [47mnil[0m) for [47m[table][0m [events], even when no
  summary is printed; for example, the value is updated to [47mnil[0m for
  [47mtable[0m events such as [47m([0m[47m[logic][0m[47m)[0m, [47m([0m[47m[program][0m[47m)[0m, and even calls of
  [47m[set-prover-step-limit][0m.

  The value of [47m(last-prover-steps state)[0m is determined as follows,
  based on the most recent summary context (as described above):

      [47mnil[0m, if no prover steps were taken, e.g., with [47m(thm (equal x x))[0m;
      else,

      the (positive) number of steps taken, if the number of steps did not
      exceed the starting limit; else,

      the negative of the starting limit.

  Note that the ``most recently completed event'' in this sense
  includes compound events.  Consider the following example.

    (progn (thm (equal (append (append x y) z) (append x y z)))
           (thm (equal (car (cons x y)) x)))

  The summaries show (in some ACL2 versions, at least) 435 steps for
  the first call of [47mthm[0m and 7 steps for the second call of [47mthm[0m, with
  442 steps thus shown in the summary for the entire [47mprogn[0m call.
  Subsequent evaluation of [47m(last-prover-steps state)[0m returns 442.  On
  the other hand, suppose that [47m(set-prover-step-limit 440)[0m is
  evaluated immediately before evaluating the [47mprogn[0m call above.  Then
  the summaries show the following for the two [47mthm[0m calls and the
  [47mprogn[0m call, in order as follows.

    Prover steps counted:  435
    Prover steps counted:  More than 5
    Prover steps counted:  More than 440

  Since the most recently completed event is the [47mprogn[0m call, then
  [47m(last-prover-steps state)[0m returns -440.

  We conclude with two remarks for advanced users who wish to invoke
  [47mlast-prover-steps[0m in the development of utilities that track prover
  steps.

  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 [47mf1[0m in the following
  example.

    (progn (defun f1 ...)
           (defun f2 ...))

  A solution is to record the steps taken by the first [47m[defun][0m before
  executing subsequent events, as follows (see [make-event]).

    (progn (defun f1 ...)
           (make-event (pprogn (f-put-global 'my-step-count
                                             (last-prover-steps state)
                                             state)
                               (value '(value-triple nil))))
           (defun f2 ...))

  Remark 2.  It is possible to write utilities that are treated as
  [events] for purposes of the discussion above; that is, their calls
  can be followed by evaluating [47m(last-prover-steps state)[0m as
  described above.  For an example of how to do this using the ACL2
  system macro [47mwith-ctx-summarized[0m, see the implementation of
  [47m[prove$][0m in [community-book] [47mbooks/tools/prove-dollar.lisp[0m.")
 (LD
  (MISCELLANEOUS)
  "The ACL2 read-eval-print loop, file loader, and [command] processor

    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 < n < 0 or 0 < n <= 100)
                                     ;   (see [useless-runes])
        :ld-skip-proofsp    ...      ; nil, 'include-book, or t
                                     ;   (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

  [47mLd[0m is the top-level ACL2 read-eval-print loop.  (When you call [47m[lp][0m,
  a little initialization is done in raw Common Lisp and then [47mld[0m is
  called.)  [47mLd[0m is also a general-purpose ACL2 file loader and a
  [command] interpreter.  [47mLd[0m is actually a macro that expands to a
  function call involving [47m[state][0m.  [47mLd[0m returns an ``error triple''
  [47m(mv erp val state)[0m as explained below.  (For much more on error
  triples, see [programming-with-state].)

  See [rebuild] for a variant of [47mld[0m that skips proofs.  See
  [output-to-file] for examples showing how to redirect output to a
  file.

  The arguments to [47mld[0m, except for [47m:dir[0m, all happen to be global
  variables in [47m[state][0m (see [state] and see
  [programming-with-state]).  For example, [47m'[0m[47m[current-package][0m and
  [47m'[0m[47m[ld-verbose][0m are global variables, which may be accessed via [47m(@
  current-package)[0m and [47m(@ ld-verbose)[0m.  When [47mld[0m 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 [47mld[0m provides the illusion of [state] global variables
  being bound, they are generally called ``[47mld[0m specials'' (after the
  Lisp convention of calling a variable ``special'' if it is
  referenced freely after having been bound).  (We say ``generally''
  because technically, [47mcurrent-package[0m and [47museless-runes[0m are not
  considered to be [47mld[0m specials.)

  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 [47m:[0m[47m[ld-error-action][0m, which
  generally defaults to [47m:return![0m if not explicitly specified.

  Just as an example to drive the point home: If [47m[current-package][0m is
  [47m\"ACL2\"[0m and you typed

    (ld *standard-oi* :current-package \"MY-PKG\")

  you would find yourself in (an inner) read-eval-print loop in which
  the [current-package] was [47m\"MY-PKG\"[0m.  You could operate there as
  long as you wished, changing the current package at will.  But when
  you typed [47m:[0m[47m[q][0m you would return to the outer read-eval-print loop
  where the current package would still be [47m\"ACL2\"[0m.

  Roughly speaking, [47mld[0m repeatedly reads a form from [47m[standard-oi][0m,
  evaluates it, and prints its result to [47m[standard-co][0m.  It does this
  until the form is [47m:[0m[47m[q][0m or evaluates to an error triple whose value
  component is [47m:[0m[47m[q][0m, or until the input channel or list is emptied.
  However, [47mld[0m has many bells and whistles controlled by the [47mld[0m
  specials.  Each such special is documented individually.  For
  example, see the documentation for [47m[standard-oi][0m,
  [47m[current-package][0m, [useless-runes], [47m[ld-pre-eval-print][0m, etc.

  A more precise description of [47mld[0m is as follows.  In the description
  below we use the [47mld[0m specials as variables, e.g., we say ``a form is
  read from [47m[standard-oi][0m.'' By this usage we refer to the current
  value of the named [state] global variable, e.g., we mean ``a form
  is read from the current value of [47m'[0m[47m[standard-oi][0m.'' This
  technicality has an important implication: If while interacting
  with [47mld[0m you change the value of one of the [47mld[0m specials, e.g.,
  [47m'[0m[47m[standard-oi][0m, you will change the behavior of [47mld[0m, e.g.,
  subsequent input will be taken from the new value.

  Three [47mld[0m specials are treated as channels: [47m[standard-oi][0m is treated
  as an object input channel and is the source of forms evaluated by
  [47mld[0m; [47m[standard-co][0m and [47m[proofs-co][0m 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.

  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 [47mld[0m.
  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
  [pathname]) and a channel of the appropriate type is opened to/from
  that file.  Any channel opened by [47mld[0m during the binding of the [47mld[0m
  specials is automatically closed by [47mld[0m upon termination.  If
  [47m[standard-co][0m and [47m[proofs-co][0m are strings that represent the same
  file, only one channel to that file is opened and is used for both.

  As a special convenience, when [47m[standard-oi][0m is a string and the [47m:dir[0m
  argument is provided and not [47mnil[0m, we look up [47m:dir[0m just as is done
  for [47m[include-book][0m; also see [47m[add-include-book-dir][0m,
  [47m[add-include-book-dir!][0m, and [47m[project-dir-alist][0m.  Thus a suitable
  directory is prepended to create the filename.  Note that
  [47mstandard-oi[0m must be a string that is a relative pathname, not an
  absolute pathname.  For example, one can write [47m(ld
  \"arithmetic/top-with-meta.lisp\" :dir :system)[0m to [47mld[0m that particular
  [community-books] library.  (Of course, for certified [books] you
  should almost always use [47m[include-book][0m instead of [47mld[0m.)  If [47m:dir[0m is
  not specified, then a relative pathname is resolved using the
  connected book directory; see [cbd].  If you want to load a list of
  forms, then consider prepending a call of [47m[set-cbd][0m to that list
  rather than using [47m:dir[0m, which is not supported when [47mstandard-oi[0m is
  a list.

  Several other alternatives are allowed for [47m[standard-oi][0m.  If
  [47m[standard-oi][0m is a true list then it is taken as the list of forms
  to be processed.  If [47m[standard-oi][0m is a list ending in an open
  channel, then [47mld[0m processes the forms in the list and then reads and
  processes the forms from the channel.  Analogously, if
  [47m[standard-oi][0m is a list ending a string, an object input channel
  from the named file is opened and [47mld[0m processes the forms in the
  list followed by the forms in the file.  That channel is closed
  upon termination of [47mld[0m.

  In the cases that a string is to be converted to an object input
  channel --- that is, when [47m[standard-oi][0m is a string or is a list
  ending in a string --- an error occurs by default if the conversion
  fails, presumably because the file named by the string does not
  exist.  However, if keyword argument [47m:ld-missing-input-ok[0m is [47mt[0m,
  then [47mld[0m immediately returns without error in this case, but without
  reading or executing any forms, as though [47mstandard-oi[0m is [47mnil[0m and
  keyword arguments [47m:ld-verbose[0m and [47m:ld-prompt[0m both have value [47mnil[0m.
  The other legal values for [47m:ld-missing-input-ok[0m are [47mnil[0m, which
  gives the default behavior, and [47m:warn[0m, which behaves the same as [47mt[0m
  except that a warning is printed, which contains the same
  information as would be printed for the default error described
  above.

  The remaining [47mld[0m specials are handled more simply and generally have
  to be bound to one of a finite number of tokens described in the
  [47m:[0m[47m[doc][0m entries for each [47mld[0m special.  Should any [47mld[0m special be
  supplied an inappropriate value, an error message is printed.

  Next, if [47m[ld-verbose][0m is [47mt[0m, [47mld[0m prints the message ``ACL2 loading
  name'' where [47mname[0m names the file or channel from which forms are
  being read.  At the conclusion of [47mld[0m, it will print ``Finished
  loading name'' if [47m[ld-verbose][0m is [47mt[0m.

  One may generally omit [47mld-user-stobjs-modified-warning[0m except when
  calling [47mld[0m in the body of a definition.  In that case this keyword
  argument is required, and the value [47mt[0m is recommended.  With that
  value, a warning will generally be printed if a user-defined
  [stobj] is modified by the call of [47mld[0m; value [47mnil[0m avoids such
  warnings, and value [47m:same[0m causes the value to be inherited from the
  existing value (generally from a superior call of [47mld[0m).  A
  discussion of these warnings is highly recommended reading before
  you give a value other than [47mt[0m; see [user-stobjs-modified-warnings].

  Finally, [47mld[0m repeatedly executes the ACL2 read-eval-print step, which
  may be described as follows.  A [prompt] is printed to
  [47m[standard-co][0m if [47m[ld-prompt][0m is non-[47mnil[0m.  The format of the
  [prompt] is determined by [47m[ld-prompt][0m.  If it is [47mt[0m, the default
  ACL2 [prompt] is used.  If it is any other non-[47mnil[0m value then it is
  treated as an ACL2 function that will print the desired [prompt].
  See [ld-prompt].  In the exceptional case where [47mld[0m's input is
  coming from the terminal [47m(*standard-oi*)[0m but its output is going to
  a different sink (i.e., [47m[standard-co][0m is not [47m[*standard-co*][0m), we
  also print the [prompt] to the terminal.

  [47mLd[0m then reads a form from [47m[standard-oi][0m.  If the object read is a
  keyword, [47mld[0m constructs a ``keyword command form'' by possibly
  reading several more objects.  See [keyword-commands].  This
  construction process is sensitive to the value of
  [47m[ld-keyword-aliases][0m.  See [ld-keyword-aliases].  Otherwise, the
  object read is treated as the command form.

  (Technical Aside.  Some special handling takes place when [47mld[0m is
  called in the scope of [47m[local][0m, as in [47m(local (ld <C>))[0m for a
  command, [47m<C>[0m.  In that case, after [47m<C>[0m is evaluated, then if the
  result is an [error-triple] and [47m<C>[0m is not already of the form
  [47m(local <C0>)[0m, then when the command is stored in the ACL2 [world]
  it is stored as [47m(local <C>)[0m instead of [47m<C>[0m.  See [ld-history] for a
  similar treatment of local commands.  End of Technical Aside.)

  [47mLd[0m next decides whether to evaluate or skip this form, depending on
  [47m[ld-pre-eval-filter][0m.  Initially, the filter must be either [47m:all[0m,
  [47m:query[0m, or a new name.  If it is [47m:all[0m, it means all forms are
  evaluated.  If it is [47m:query[0m, 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 [47mld[0m terminates.  See [ld-pre-eval-filter].

  If the form is to be evaluated, then [47mld[0m first prints the form to
  [47m[standard-co][0m, if [47m[ld-pre-eval-print][0m is [47mt[0m.  With this feature, [47mld[0m
  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
  [ld-pre-eval-print].

  [47mLd[0m then evaluates the form, with [47m[state][0m bound to the current
  [state].  The result is some list of (multiple) values.  If a
  [state] is among the values, then [47mld[0m uses that [state] as the
  subsequent current [state].

  Depending on [47m[ld-error-triples][0m, [47mld[0m may interpret the result as an
  ``error.'' See [ld-error-triples].  We first discuss [47mld[0m's behavior
  if no error signal is detected (either because none was sent or
  because [47mld[0m is ignoring them because [47m[ld-error-triples][0m is [47mnil[0m).

  In the case of a non-erroneous result, [47mld[0m does two things: First, if
  the logical [world] in the now current [state] is different than
  the [world] before execution of the form, [47mld[0m adds to the [world] a
  ``[command] landmark'' containing the form evaluated.  See
  [command-descriptor].  Second, [47mld[0m prints the result to
  [47m[standard-co][0m, but only if [47m[ld-post-eval-print][0m is not [47mnil[0m.  The
  result is printed as a list of (multiple) values unless
  [47m[ld-post-eval-print][0m is [47m:command-conventions[0m, [47m[ld-error-triples][0m is
  [47mt[0m, and the result is an [error-triple], i.e., of the form [47m(mv * *
  state)[0m.  In that case, only the non-erroneous ``value'' component
  of the result is printed.  See [ld-post-eval-print].

  Whenever [47mld[0m prints anything (whether the input form, a query, or some
  results) it ``eviscerates'' it if [47mld-evisc-tuple[0m is non-[47mnil[0m.
  Essentially, evisceration is a generalization of Common Lisp's use
  of [47m*print-level*[0m and [47m*print-length*[0m to hide large substructures.
  See [evisc-tuple] and also see [set-iprint].

  We now return to the case of a form whose evaluation signals an
  error.  In this case, [47mld[0m first restores the ACL2 logical [world] to
  what it was just before the erroneous form was evaluated.  Thus, a
  form that partially changes the [world] (i.e., begins to store
  properties) and then signals an error, has no effect on the
  [world].  You may see this happen on [command]s that execute
  several [events] (e.g., an [47m[encapsulate][0m or a [47m[progn][0m of several
  [47m[defuns][0m): even though the output makes it appear that the initial
  [events] were executed, if an error is signaled by a later event
  the entire block of [events] is discarded.

  After rolling back, [47mld[0m takes an action determined by
  [47m[ld-error-action][0m.  If the action is [47m:continue[0m, [47mld[0m merely iterates
  the read-eval-print step.  Note that nothing suggestive of the
  value of the ``erroneous'' form is printed.  If the action is
  [47m:return[0m, [47mld[0m terminates normally; similarly if the action is
  [47m:return![0m, but a special value is returned that can cause superior
  [47mld[0m commands to terminate; see [ld-error-action] for details.  If
  the action is [47m:error[0m, [47mld[0m terminates signaling an error to its
  caller.  If its caller is in fact another instance of [47mld[0m and that
  instance is watching out for error signals, the entire [world]
  created by the inner [47mld[0m will be discarded by the outer [47mld[0m if the
  inner [47mld[0m terminates with an error.  Note that if the action is
  [47m(:exit N)[0m, then there is no rolling back, because ACL2 quits
  immediately with exit status [47mN[0m.

  [47mLd[0m returns an error triple, [47m(mv erp val state)[0m.  [47mErp[0m is [47mt[0m or [47mnil[0m
  indicating whether an error is being signaled.  If no error is
  signaled, [47mval[0m is the ``reason'' [47mld[0m terminated and is one of [47m:exit[0m
  (meaning [47m:[0m[47m[q][0m was read), [47m:eof[0m (meaning the input source was
  exhausted), [47m:error[0m (meaning an error occurred but has been
  suppressed), [47m:filter[0m (meaning the [47m[ld-pre-eval-filter][0m terminated
  [47mld[0m), [47m:missing-input[0m (meaning that the specified input file is
  missing, in the case that keyword [47m:ld-missing-input-ok[0m has a
  non-[47mnil[0m value so that an error is avoided), or a cons pair whose
  first component is the symbol [47m:STOP-LD[0m, which typically indicates
  that an error occurred while the value of variable
  [47m'[0m[47m[ld-error-action][0m was [47m:RETURN![0m.  See [ld-error-action] for details
  of this last case.


Subtopics

  [A!]
      To return to the top-level of ACL2's command loop

  [Abort!]
      To return to the top-level of ACL2's command loop

  [Calling-ld-in-bad-contexts]
      Errors caused by calling [47m[ld][0m in inappropriate contexts

  [Current-package]
      The package used for reading and printing

  [Default-print-prompt]
      The default [prompt] printed by [47m[ld][0m

  [Guarantees-of-the-top-level-loop]
      Guarantees provided by top-level evaluation

  [I-am-here]
      A convenient marker for use with [47m[rebuild][0m or [47m[ld][0m

  [Keyword-commands]
      How keyword commands like [47m:u[0m and [47m:pbt[0m are processed

  [Ld-always-skip-top-level-locals]
      Determines whether [47m[ld][0m skips [47m[local][0m top-level forms

  [Ld-error-action]
      Determines [47m[ld][0m's response to an error

  [Ld-error-triples]
      Determines whether a form caused an error during [47m[ld][0m

  [Ld-evisc-tuple]
      Determines whether [47m[ld][0m suppresses details when printing

  [Ld-history]
      Saving and querying command history

  [Ld-keyword-aliases]
      Abbreviation of some keyword commands

  [Ld-missing-input-ok]
      Determine whether [47m[ld][0m causes an error for a missing file

  [Ld-post-eval-print]
      Determines whether and how [47m[ld][0m prints the result of evaluation

  [Ld-pre-eval-filter]
      Determines which forms [47m[ld][0m evaluates

  [Ld-pre-eval-print]
      Determines whether [47m[ld][0m prints the forms to be [47meval[0m'd

  [Ld-prompt]
      Determines the [prompt] printed by [47m[ld][0m

  [Ld-query-control-alist]
      How to default answers to queries

  [Ld-redefinition-action]
      To allow redefinition without [undoing]

  [Ld-skip-proofsp]
      How carefully ACL2 processes your [command]s

  [Ld-verbose]
      Determines whether [47m[ld][0m prints ``ACL2 Loading ...''

  [Lp]
      The Common Lisp entry to ACL2

  [P!]
      To pop up (at least) one level of ACL2's command loop

  [Prompt]
      The prompt printed by [47m[ld][0m

  [Rebuild]
      A convenient way to reconstruct your old [state]

  [Redef]
      A common way to set [ld-redefinition-action]

  [Redef!]
      A common way to set [ld-redefinition-action]

  [Redef+]
      System hacker's redefinition [command]

  [Redef-]
      Turn off system hacker's redefinition [command]

  [Reset-ld-specials]
      Restores initial settings of the [47m[ld][0m specials

  [Wormhole]
      [47m[ld][0m without [47m[state][0m --- a short-cut to a parallel universe")
 (LD-ALWAYS-SKIP-TOP-LEVEL-LOCALS
  (LD)
  "Determines whether [47m[ld][0m skips [47m[local][0m top-level forms

  [47mLd-always-skip-top-level-locals[0m is an [47m[ld][0m special (see [ld]).  The
  accessor is [47m(ld-always-skip-top-level-locals state)[0m and the updater
  is [47m(set-ld-always-skip-top-level-locals val state)[0m.  The value of
  [47mld-always-skip-top-level-locals[0m must be either [47mnil[0m or [47mt[0m.  The
  initial value of [47mld-always-skip-top-level-locals[0m is [47mnil[0m.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, is controlled by
  various flags that control its behavior, and
  [47mld-always-skip-top-level-locals[0m is one of them.  When the value is
  [47mt[0m, [47m[local][0m [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 [47m[certify-book][0m, [47m[include-book][0m, or [47m[encapsulate][0m, or else
  during [47m[make-event][0m expansion.")
 (LD-ERROR-ACTION
  (LD)
  "Determines [47m[ld][0m's response to an error

  [47mLd-error-action[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-error-action state)[0m and the updater is [47m(set-ld-error-action val
  state)[0m.  [47mLd-error-action[0m must be [47m:continue[0m, [47m:return[0m, [47m:return![0m,
  [47m:error[0m, or [47m(:exit N)[0m for some natural number [47mN[0m.  The initial value
  of [47mld-error-action[0m is [47m:continue[0m, which means that the top-level
  ACL2 [command] loop (see [47m[lp][0m) will not exit when an error is
  caused by [47muser-typein[0m.  But the default value for [47mld-error-action[0m
  on calls of [47m[ld][0m is [47m:return![0m, with one exception: in the case that
  the value of [47m[ld][0m special [47mld-error-action[0m is [47m(:exit N)[0m, the default
  remains that value.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-error-action[0m is one of them.  Suppose that [47m[ld-error-triples][0m is
  [47mt[0m and a form evaluates to an [error-triple] [47m(mv erp val state)[0m.  If
  the ``error component'', [47merp[0m, is non-[47mnil[0m, then an error is said to
  have occurred.  If an error occurs, [47m[ld][0m's action depends on
  [47mld-error-action[0m.  If it is [47m:continue[0m, [47m[ld][0m just continues
  processing the forms in [47m[standard-oi][0m.  If it is [47m:return[0m or
  [47m:return![0m, [47m[ld][0m stops and returns as though it had emptied the
  channel.  If it is [47m:error[0m, [47m[ld][0m stops and returns, signaling an
  error to its caller by returning an error triple with non-[47mnil[0m error
  component, and reverting the logical [world] to its value just
  before that call of [47m[ld][0m.  If it is [47m(:exit N)[0m, then ACL2 quits with
  exit status [47mN[0m.  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 [47m(:STOP-LD . x)[0m.

  To see this effect of [47m:ERROR[0m for [47mld-error-action[0m, consider the
  following example.

    (ld '((defun f (x) x) (defun bad (x)) (defun g (x) x)))

  When the [47m[defun][0m of [47mbad[0m fails (because its body is missing),
  evaluation of the [47mld[0m call stops; thus, the [47m[defun][0m of [47mg[0m is not
  evaluated.  The definition of [47mf[0m will be removed from the logical
  [world] before the call of [47mld[0m returns.

  However, by default each user call of [47mld[0m is made with a
  [47mld-error-action[0m of [47m:RETURN![0m (not [47m:ERROR[0m).  In the common case that
  all nested calls of [47mld[0m inside the ACL2 loop are made this way, an
  error will not roll back the logical [world].  However, it will
  still halt evaluation of forms for the current call of [47mld[0m and any
  parent calls of [47mld[0m (other than the call made on behalf of [47mlp[0m that
  entered the ACL2 loop in the first place), as though there were no
  more forms to evaluate.

  We have already discussed the behavior of [47mld[0m when an error occurs.
  But there is another case when [47mld[0m can stop processing more forms:
  when [47mld-error-action[0m is not [47m:CONTINUE[0m, [47m[ld-error-triples][0m is [47mt[0m, and
  evaluation of a form returns an error triple [47m(mv nil val state)[0m,
  where [47mnil[0m is the error component and whose ``value component'', [47mval[0m
  is a [47m[cons][0m pair whose [47m[car][0m is the symbol [47m:STOP-LD[0m.  Let [47mval[0m be
  the pair [47m(:STOP-LD . x)[0m.  If [47mld-error-action[0m is of the form [47m(:EXIT
  N)[0m, then ACL2 quits with exit status [47mN[0m.  Otherwise (i.e., when
  [47mld-error-action[0m is [47m:RETURN[0m, [47m:RETURN![0m, or [47m:ERROR[0m), the call of [47mld[0m
  returns the error triple [47m(mv nil (:STOP-LD n . x) state)[0m, where [47mn[0m
  is the value of [47m[state][0m global variable [47m'ld-level[0m at the time of
  termination.  The following example illustrates how this works.

    (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)))

  The outer call of [47mld[0m returns the value

    (:STOP-LD 2 3 MY-ERROR MORE-INFO)

  and leaves us in a world the includes definitions for [47mf1[0m and [47mf2[0m, but
  no definition for [47mg1[0m or [47mg2[0m since neither of their two [47mdefun[0m forms
  was evaluated.  The value of [47m[state][0m global [47m'ld-level[0m is
  incremented from 1 to 2 when the outer [47mld[0m is entered and then again
  to 3 when the inner [47mld[0m is entered.  When the inner [47mld[0m encounters
  the error triple [47m(mv nil (:STOP-LD my-error more-info) state)[0m, it
  sees [47m:STOP-LD[0m in the [47mcar[0m of the value component and pushes the
  current value of [47m'ld-level[0m, 3, onto the [47m[cdr][0m of that value, to
  return the value triple [47m(mv nil (:STOP-LD my-error 3 more-info)
  state)[0m.  The outer of [47mld[0m then sees this value and returns [47m(mv nil
  (:STOP-LD my-error 2 3 more-info) state)[0m, since its current value
  of [47m'ld-level[0m is 2 after the inner [47mld[0m exits.

  That concludes our discussion of how these special [47m:STOP-LD[0m 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, [47mld[0m returns an error triple
  [47m(mv nil (:STOP-LD n) state)[0m, where [47mn[0m is the value of variable
  [47mld-level[0m at the time of termination, when the following conditions
  hold: an error occurs, [47mld-error-action[0m is [47mRETURN![0m (which is the
  default), and [47m[ld-error-triples][0m is [47mt[0m (the default).  The following
  example, which is a bit similar to the preceding one, illustrates
  both creation and handling of the special [47m:STOP-LD[0m values.

    (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)))

  The result is that [47mf1[0m, [47mf2[0m, and [47mf3[0m are defined, but none of [47mg1[0m, [47mg2[0m, or
  [47mg3[0m is defined.  Let's see why.  The innermost call of [47m[ld][0m has a
  default [47m:ld-error-action[0m of [47m:RETURN![0m (as do the other calls).  So
  when the definition of [47mbad[0m fails, then the innermost [47mld[0m returns [47m(mv
  nil (:STOP-LD 4) state)[0m.  The middle [47mld[0m sees this value, and since
  its [47m:ld-error-action[0m is not [47m:CONTINUE[0m (because it has the default
  value of [47m:RETURN![0m), it returns before considering the definition of
  [47mg2[0m, with value [47m(mv nil (:STOP-LD 3 4) state)[0m.  The topmost call of
  [47mld[0m similarly sees the [47m:STOP-LD[0m; stops evaluation of forms, without
  defining [47mg1[0m; and returns [47m(mv nil (:STOP-LD 2 3 4) state)[0m.")
 (LD-ERROR-TRIPLES
  (LD)
  "Determines whether a form caused an error during [47m[ld][0m

  [47mLd-error-triples[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-error-triples state)[0m and the updater is [47m(set-ld-error-triples
  val state)[0m.  [47mLd-error-triples[0m must be either [47mt[0m or [47mnil[0m.  The initial
  value of [47mld-error-triples[0m is [47mt[0m.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-error-triples[0m is one of them.  If this variable has the value [47mt[0m
  then when a form evaluates to an [error-triple] [47m(mv erp val state)[0m
  such that [47merp[0m is non-[47mnil[0m, then an error is deemed to have occurred.
  When an error occurs in evaluating a form, [47m[ld][0m rolls back the ACL2
  [world] to the configuration it had at the conclusion of the last
  error-free form.  Then [47m[ld][0m takes the action determined by
  [47m[ld-error-action][0m.")
 (LD-EVISC-TUPLE
  (LD)
  "Determines whether [47m[ld][0m suppresses details when printing

  [47mLd-evisc-tuple[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-evisc-tuple state)[0m and an updater is [47m(set-ld-evisc-tuple val
  state)[0m, although the use of [47m[set-evisc-tuple][0m is preferred for
  updating.  [47mLd-evisc-tuple[0m must be either [47mnil[0m, which is its initial
  value, or a legal evisc-tuple: see [set-evisc-tuple].

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-evisc-tuple[0m is one of them.  [47m[Ld][0m may print the forms it is
  evaluating and/or the results of evaluation.  Depending on the
  value of [47mld-evisc-tuple[0m [47m[ld][0m may ``eviscerate'' objects before
  printing them.  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 [47mld[0m.")
 (LD-HISTORY
  (LD HISTORY)
  "Saving and querying command history

  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.

    * Each entry in the history includes the input command, the value
      returned, and other information, as explained further below.

    * This is about commands, not events: that is, we are concerned with
      forms that are submitted for evaluation to the top-level loop.
      See [command].

    * An entry is saved for every command submitted by the user, even if it
      doesn't change the ACL2 [world] --- e.g., [47m(+ 3 4)[0m --- and even
      if it undoes commands --- e.g., [47m:[0m[47mubt[0m.

    * Keyword commands are turned into s-expressions before saving an
      entry; see [keyword-commands].  For example, the input [47m:ubt :x[0m
      is stored in an entry as the input [47m(ubt ':x)[0m.

    * When an entry is saved for a command [47mC[0m that is evaluated in the
      context of a call of [47m[local][0m, where [47mC[0m evaluates to an
      [error-triple], then [47mC[0m is stored in the entry as [47m(local C)[0m
      unless [47mC[0m is already a call of [47mlocal[0m.  (Technical Aside: This
      behavior supports local [portcullis] commands.)

    * 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 [47m[ld][0m --- but not during [47m[make-event][0m
      expansion.

    * Entries are generally saved even when there are errors.  However,
      entries are not saved for commands that exit with raw Lisp
      errors.

  Also see [community-books] file [47mbooks/demos/ld-history-input.lsp[0m for
  examples.  The output from calling [47m[ld][0m on that file (by calling
  the [47m[run-script][0m tool in [47mbooks/demos/ld-history-book.acl2[0m) is in
  [community-books] file [47mbooks/demos/ld-history-log.txt[0m.

  The ld-history is a stack, represented as a list with the most recent
  commands at the front.  But by default ACL2 is in [3msingle-entry
  mode[0m, 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 [3mmultiple-entry mode[0m, 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.

    * [47m(ld-history state)[0m
      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
      [47madjust-ld-history[0m below.  Each entry in the list is recognized
      by the following predicate.  [31;1mNOTE[0m: 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
      [47m(ld-history state)[0m at the ACL2 prompt does not put that form at
      the front of the returned list.)

    * [47m(weak-ld-history-entry-p x)[0m
      This function returns [47mt[0m if [47mx[0m has the shape of an entry in the
      ld-history list, else [47mnil[0m.

    * Here are accessors for an ld-history entry, which we think of as
      returning its fields.  The formal parameter [47mentry[0m below is an
      entry in (i.e., member of) [47m(ld-history state)[0m; an example call
      is thus [47m(ld-history-entry-input (car (ld-history state)))[0m.

        * [47m(ld-history-entry-input entry)[0m
          The user input

        * [47m(ld-history-entry-error-flg entry)[0m
          Non-[47mnil[0m when there was an error translating the user input

        * [47m(ld-history-entry-stobjs-out/value entry)[0m
          When [47m(ld-history-entry-error-flg entry)[0m is [47mnil[0m, this is a cons whose
          [47mcar[0m is the [stobjs-out] --- a list whose length is the
          number of values returned, with [47mnil[0m in each position except
          when occupied by a symbol indicating a returned [stobj] for
          that position --- and whose [47mcdr[0m is the returned value in
          the single-value case, but is the list of returned values
          in the [multiple-value] case.

        * [47m(ld-history-entry-stobjs-out entry)[0m
          When [47m(ld-history-entry-error-flg entry)[0m is [47mnil[0m, this is the
          stobjs-out as described above; otherwise this is [47mnil[0m.

        * [47m(ld-history-entry-value entry)[0m
          When [47m(ld-history-entry-error-flg entry)[0m is [47mnil[0m, this is the value or
          values as described above; otherwise this is [47mnil[0m.

        * [47m(ld-history-entry-user-data entry)[0m
          This is [47mnil[0m by default.  However, code can be provided to compute
          this field, as discussed below.

    * [47m(adjust-ld-history x state)[0m
      [47mX[0m is [47mt[0m, [47mnil[0m, or an integer.  The result is an [error-triple] [47m(mv nil
      value state)[0m, where [47mvalue[0m and the effect are as follows, and
      where if there is no change (i.e., the effect is a no-op) then
      [47mvalue[0m is [47m(:no-change :length N)[0m where [47mN[0m is the current length
      of the ld-history.

        * [47mT[0m:
          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 [47mvalue[0m is [47m(:saving-ld-history t)[0m.

        * [47mNIL[0m:
          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 [47mvalue[0m is
          [47m(:saving-ld-history nil)[0m, and all old entries will be
          discarded (to produce a single-element ld-history).

        * Positive integer [47mk[0m:
          Replace the current ld-history by its first [47mk[0m entries, except there
          is no change if in single-entry mode or if [47mk[0m 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 [47madjust-ld-history[0m is invoked, which does not
          include the current command being evaluated.  (Thus, even
          if [47mk[0m is 1, multiple-entry mode will be preserved: the
          ld-history will have 2 entries immediately after the
          current command completes.)  The returned [47mvalue[0m is
          [47m(:ld-history-truncated :old-length LEN :new-length k)[0m,
          where [47mLEN[0m is the length of the current ld-history before
          the change.

        * Negative integer [47m-k[0m:
          This is intended to specify removal of the oldest [47mk[0m entries from the
          current ld-history.  Thus, it is treated identically to
          argument [47mk2[0m where [47mk2[0m is the sum of [47m-k[0m and the length of the
          current ld-history, but only if that sum is positive; else
          there is no change.  For example, suppose that [47m-k[0m is -3.
          If the current ld-history, [47mh[0m, has length 2 or 3, then there
          is no change; but if [47mh[0m has length 10, then it is to be
          replaced by [47m(take 7 h)[0m and the length will actually thus be
          8 after the current command completes.

  Note that a call of [47madjust-ld-history[0m is not an [event] that can be
  placed directly in [books] or [47m[encapsulate][0m forms.

  Remark.  If [47m(adjust-ld-history n state)[0m 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 [47mn+1[0m.  That's essentially
  because it will have length [47mn[0m immediately after that call of
  [47madjust-ld-history[0m 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 [47mn[0m is 1 then a 2-element list of
  entries [47m(e1 e2)[0m is created where [47me2[0m has fields that are all [47mnil[0m;
  then when the new entry [47me[0m is pushed onto the ld-history, [47me2[0m is
  dropped so that the new ld-history is [47m(e e1)[0m.  This special-case
  trick is also used in multiple-entry mode when [47mn[0m is [47m-k[0m where [47mk[0m is
  one less than the length of the current ld-history, since that is
  treated the same as [47m(adjust-ld-history 1 state)[0m; and this trick is
  also used when [47m(adjust-ld-history t state)[0m switches from
  single-entry mode to multiple-entry mode.  End of Remark.

  Finally we discuss the user-data field of a ld-history entry, which
  (as noted above) has default [47mnil[0m.  It is accessed using
  [47m(ld-history-entry-user-data entry)[0m.  It is set automatically when
  the ld-history is extended with a new entry: the function call
  [47m(set-ld-history-entry-user-data input error-flg stobjs-out/value
  state)[0m, 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,
  [47mld-history-entry-input[0m).  Although [47mset-ld-history-entry-user-data[0m
  returns [47mnil[0m by default, this can be changed by providing your own
  function with a [47m:[0m[47m[guard][0m of [47mt[0m and the same formal parameters (which
  however may be renamed, other than [47mstate[0m).  To make that change,
  define a function, which here we call [47mmy-user-data[0m, and then attach
  it to [47mset-ld-history-entry-user-data[0m, as follows.

    (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)

  The following example illustrates how to store the length of the ACL2
  [world] in the user-data.  Note that the [world] present in the
  [state] at the time the user-data is set, computed as [47m(w state)[0m, is
  almost the final world produced by the command --- it is missing
  just one triple, a so-called command marker.

    (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)

  A subsequent inspection of the stored user-data shows the length of
  the current world, for example as follows.

    ACL2 !>(ld-history-entry-user-data (car (ld-history state)))
    125914
    ACL2 !>

  Notice that we used [47m[len][0m, not [47m[length][0m, since the [47m:[0m[47m[guard][0m specified
  for our function needs to be [47mt[0m.  Alternative definitions, which
  however are less efficient, are as follows.

    (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))))

  Here is how to restore the original behavior, i.e., the default where
  the user-data is set to [47mnil[0m.

    (defattach-system set-ld-history-entry-user-data
                      set-ld-history-entry-user-data-default)")
 (LD-HISTORY-ENTRY-ERROR-FLG (POINTERS)
                             "See [ld-history].")
 (LD-HISTORY-ENTRY-INPUT (POINTERS)
                         "See [ld-history].")
 (LD-HISTORY-ENTRY-STOBJS-OUT (POINTERS)
                              "See [ld-history].")
 (LD-HISTORY-ENTRY-STOBJS-OUT/VALUE (POINTERS)
                                    "See [ld-history].")
 (LD-HISTORY-ENTRY-USER-DATA (POINTERS)
                             "See [ld-history].")
 (LD-HISTORY-ENTRY-VALUE (POINTERS)
                         "See [ld-history].")
 (LD-KEYWORD-ALIASES
  (LD)
  "Abbreviation of some keyword commands

    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

  [47mLd-keyword-aliases[0m is the name of a ACL2 table (see [table]) and also
  the name of a function of [47mstate[0m that returns the value of this
  table.  That value must be an alist, each element of which is of
  the form [47m(:keyword n fn)[0m, where [47m:keyword[0m is a keyword, [47mn[0m is a
  nonnegative integer, and [47mfn[0m is a function symbol of arity [47mn[0m, a
  macro symbol, or a [47mlambda[0m expression of arity [47mn[0m.  When [47mkeyword[0m is
  typed as an [47m[ld][0m command, [47mn[0m more forms are read, [47mx1, ..., xn[0m, and
  the form [47m(fn 'x1 ... 'xn)[0m is then evaluated.  The initial value of
  the [47mld-keyword-aliases[0m [table] is [47mnil[0m.

  ACL2 provides functions to modify the [47mld-keyword-aliases[0m table, as
  follows.

      [47m(Set-ld-keyword-aliases val state)[0m: sets the table to [47mval[0m, which must
      be a legal alist as described above.  This is an event that may
      go into a book (see [events]), but its effect will be [local]
      to that book.

      [47mSet-ld-keyword-aliases![0m is the same as [47mset-ld-keyword-aliases[0m, except
      that its effect is not [local].  Indeed, the form
      [47m(set-ld-keyword-aliases val state)[0m is equivalent to the form
      [47m(local (set-ld-keyword-aliases! val state)[0m.

      [47m(Add-ld-keyword-alias key val state)[0m: modifies the table by binding
      the keyword [47mkey[0m to [47mval[0m, which must be a legal value as
      described above.  This is an event that may go into a book (see
      [events]), but its effect will be [local] to that book.

      [47mAdd-ld-keyword-alias![0m is the same as [47madd-ld-keyword-alias[0m, except
      that its effect is not [local].  Indeed, the form
      [47m(add-ld-keyword-alias key val state)[0m is equivalent to the form
      [47m(local (add-ld-keyword-alias! key val state)[0m.

  Consider the first example above:

    (set-ld-keyword-aliases '((:q 0 q-fn)
                              (:e 0 exit-acl2-macro))
                            state)

  With this event, [47m:[0m[47m[q][0m is redefined to have the effect of executing
  [47m(q-fn)[0m, so for example if you have defined [47mq-fn[0m with

    (defmacro q-fn ()
      '(er soft 'q \"You un-bound :q and now we have a soft error.\"))

  then [47m:[0m[47m[q][0m will cause an error, and if you have defined

    (defmacro exit-acl2-macro () '(exit-ld state))

  then [47m:e[0m will cause the effect (it so happens) that [47m:[0m[47m[q][0m normally has.
  If you prefer [47m:e[0m to [47m:[0m[47m[q][0m for exiting the ACL2 loop, you might even
  want to put such definitions of [47mq-fn[0m and [47mexit-acl2-macro[0m together
  with the [47mset-ld-keyword-aliases[0m form above into your
  [47m\"acl2-customization.lsp\"[0m file; see [ACL2-customization].

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-keyword-aliases[0m is one of them.  [47mLd-keyword-aliases[0m affects how
  keyword commands are parsed.  Generally speaking, [47m[ld][0m's command
  interpreter reads ``[47m:fn x1 ... xn[0m'' as ``[47m(fn 'x1 ... 'xn)[0m'' when
  [47m:fn[0m is a keyword and [47mfn[0m is the name of an [47mn[0m-ary function; see
  [keyword-commands].  But this parse is overridden, as described
  above, for the keywords bound in the [47mld-keyword-aliases[0m [table].")
 (LD-MISSING-INPUT-OK
  (LD)
  "Determine whether [47m[ld][0m causes an error for a missing file

  [47mLd-missing-input-ok[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-missing-input-ok state)[0m and the updater is
  [47m(set-ld-missing-input-ok val state)[0m.  The value of
  [47mld-missing-input-ok[0m must be either [47mnil[0m, [47mt[0m, or [47m:warn[0m.  The initial
  value of [47mld-missing-input-ok[0m is [47mnil[0m.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, is controlled by
  various flags that control its behavior, and [47mld-missing-input-ok[0m is
  one of them.  In brief, the first argument of [47mld[0m can indicate a
  file from which to read input.  If the file does not exist, it is
  an error by default, but [47mld[0m becomes essentially a no-op if [47mt[0m or
  [47m:warn[0m is supplied for [47m:ld-missing-input-ok[0m, where [47m:warn[0m prints a
  warning.  Also see [ld].")
 (LD-POST-EVAL-PRINT
  (LD)
  "Determines whether and how [47m[ld][0m prints the result of evaluation

  [47mLd-post-eval-print[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-post-eval-print state)[0m and the updater is
  [47m(set-ld-post-eval-print val state)[0m.  [47mLd-post-eval-print[0m must be
  either [47mt[0m, [47mnil[0m, or [47m:command-conventions[0m.  The initial value of
  [47mld-post-eval-print[0m is [47m:command-conventions[0m.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-post-eval-print[0m is one of them.  If this global variable is [47mt[0m,
  [47m[ld][0m prints the result.  In the case of a form that produces a
  multiple value, [47m[ld][0m prints the list containing all the values
  (which, logically speaking, is what the form returned).  If
  [47mld-post-eval-print[0m is [47mnil[0m, [47m[ld][0m does not print the values.  This is
  most useful when [47m[ld][0m is used to load a previously processed file.

  Finally, if [47mld-post-eval-print[0m is [47m:command-conventions[0m and also
  [47mld-error-triples[0m is [47mt[0m, then [47m[ld][0m prints the result but treats
  ``error triples'' specially.  An ``error triple'' (see
  [error-triple]) is a result, [47m(mv erp val state)[0m, that consists of
  two ordinary values and [47m[state][0m.  Many ACL2 functions use such
  triples to signal errors.  The convention is that if [47merp[0m (the first
  value) is [47mnil[0m, then the function is returning [47mval[0m (the second
  value) as its conventional single result and possibly
  side-effecting [state] (as with some output).  If [47merp[0m is not [47mnil[0m,
  then an error has been caused, [47mval[0m is irrelevant and the error
  message has been printed in the returned [state].  Example ACL2
  functions that follow this convention include [47m[defun][0m and
  [47m[in-package][0m.  If such ``error producing'' functions are evaluated
  while [47mld-post-eval-print[0m is set to [47mt[0m, 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 [state]).  For
  more information about error triples, see [programming-with-state].

  When [47mld-post-eval-print[0m is [47m:command-conventions[0m and a form produces
  an error triple [47m(mv erp val state)[0m as its value, [47m[ld][0m prints
  nothing if [47merp[0m is non-[47mnil[0m and otherwise [47m[ld][0m prints just [47mval[0m.
  Because it is a misrepresentation to suggest that just one result
  was returned, [47m[ld][0m prints the value of the global variable
  [47m'triple-print-prefix[0m before printing [47mval[0m.  [47m'triple-print-prefix[0m is
  initially [47m\" \"[0m, which means that when non-erroneous error triples
  are being abbreviated to [47mval[0m, [47mval[0m appears one space off the left
  margin instead of on the margin.

  In addition, when [47mld-post-eval-print[0m is [47m:command-conventions[0m and the
  value component of an error triple is the keyword [47m:invisible[0m then
  [47m[ld][0m prints nothing.  This is the way certain commands (e.g.,
  [47m:[0m[47m[pc][0m) appear to return no value.

  By printing nothing when an error has been signaled, [47m[ld][0m makes it
  appear that the error (whose message has already appeared in
  [state]) has ``thrown'' the computation back to load without
  returning a value.  By printing just [47mval[0m otherwise, we suppress the
  fact that [state] has possibly been changed.")
 (LD-PRE-EVAL-FILTER
  (LD)
  "Determines which forms [47m[ld][0m evaluates

  [47mLd-pre-eval-filter[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-pre-eval-filter state)[0m and the updater is
  [47m(set-ld-pre-eval-filter val state)[0m.  [47mLd-pre-eval-filter[0m must be
  either [47m:all[0m, [47m:query[0m, or a new name that could be defined (e.g., by
  [47m[defun][0m or [47m[defconst][0m).  (There is actually a value that may on
  rare occasions be set by the ACL2 system, [47m:illegal-state[0m; we ignore
  that value here, but the curious reader is welcome to see
  [illegal-state].)  The initial value of [47mld-pre-eval-filter[0m is [47m:all[0m.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-pre-eval-filter[0m is one of them.  If the filter is [47m:all[0m, then
  every form read is evaluated.  If the filter is [47m:query[0m, then after
  a form is read it is printed to [47m[standard-co][0m 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 [47m[ld][0m terminates normally.

  The [47m:all[0m filter is, of course, the normal one.  [47m:Query[0m is useful if
  you want to replay selected [command]s in some file.  The new name
  filter is used if you wish to replay all the [command]s in a file
  up through the introduction of the given one.")
 (LD-PRE-EVAL-PRINT
  (LD)
  "Determines whether [47m[ld][0m prints the forms to be [47meval[0m'd

  [47mLd-pre-eval-print[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-pre-eval-print state)[0m and the updater is [47m(set-ld-pre-eval-print
  val state)[0m.  [47mLd-pre-eval-print[0m must be either [47mt[0m, [47mnil[0m, or [47m:never[0m.
  The initial value of [47mld-pre-eval-print[0m is [47mnil[0m.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-pre-eval-print[0m is one of them.  If this global variable is [47mt[0m,
  then before evaluating the form just read from [47m[standard-oi][0m, [47m[ld][0m
  prints the form to [47m[standard-co][0m.  If the variable is [47mnil[0m, no such
  printing occurs.  The [47mt[0m option is useful if you are reading from a
  file of [command]s and wish to assemble a complete script of the
  session in [47m[standard-co][0m.

  The value [47m:never[0m of [47mld-pre-eval-print[0m is rarely used.  During the
  evaluation of [47m[encapsulate][0m and of [47m[certify-book][0m forms, subsidiary
  events are normally printed, even if [47mld-pre-eval-print[0m is [47mnil[0m.
  Thus for example, when the user submits an [47m[encapsulate][0m form, all
  subsidiary events are generally printed even in the default
  situation where [47mld-pre-eval-print[0m is [47mnil[0m.  But occasionally one may
  want to suppress such printing.  In that case, [47mld-pre-eval-print[0m
  should be set to [47m:never[0m.  As described elsewhere (see
  [set-inhibit-output-lst]), another way to suppress such printing is
  to execute [47m(set-inhibit-output-lst lst)[0m where [47mlst[0m evaluates to a
  list including [47m'prove[0m and [47m'event[0m.")
 (LD-PROMPT
  (LD)
  "Determines the [prompt] printed by [47m[ld][0m

  [47mLd-prompt[0m is an [47m[ld][0m special (see [ld]).  The accessor is [47m(ld-prompt
  state)[0m and the updater is [47m(set-ld-prompt val state)[0m.  [47mLd-prompt[0m
  must be either [47mnil[0m, [47mt[0m, or a function symbol that, when given an
  open output character channel and [state], prints the desired
  [prompt] to the channel and returns two values: the number of
  [characters] printed and the [state].  The initial value of
  [47mld-prompt[0m is [47mt[0m.

  The general-purpose ACL2 read-eval-print loop, [47m[ld][0m, reads forms from
  [47m[standard-oi][0m, evaluates them and prints the result to
  [47m[standard-co][0m.  Note that the ACL2 top-level loop (see [47m[lp][0m)
  results from an invocation of [47m[ld][0m.

  However, there are various flags that control [47m[ld][0m's behavior and
  [47mld-prompt[0m is one of them.  [47mLd-prompt[0m determines whether [47m[ld][0m prints
  a [prompt] before reading the next form from [47m[standard-oi][0m.  If
  [47mld-prompt[0m is [47mnil[0m, [47m[ld][0m prints no [prompt].  If [47mld-prompt[0m is [47mt[0m, the
  default [prompt] printer is used, which displays information that
  includes the current package, default [defun-mode], [guard]
  checking status (on or off), and [47m[ld-skip-proofsp][0m; see
  [default-print-prompt].

  If [47mld-prompt[0m is neither [47mnil[0m nor [47mt[0m, then it should be a function name,
  [47mfn[0m, such that [47m(fn channel state)[0m will print the desired [prompt] to
  [47mchannel[0m in [47m[state][0m and return [47m(mv col state)[0m, where [47mcol[0m is the
  number of [characters] output (on the last line output).  You may
  define your own [prompt] printing function, [47mfn[0m, and install it with
  [47m(set-ld-prompt 'fn state)[0m.  However, a trust tag must be active
  (see [defttag]) when you set [47mld-prompt[0m to other than [47mt[0m or [47mnil[0m (with
  two exceptions: the functions [47mbrr-prompt[0m and [47mwormhole-prompt[0m, which
  print the prompt in the [break-rewrite] loop and the general
  [wormhole] loop, respectively).

  If you supply an inappropriate [prompt] function, i.e., one that
  causes an error or does not return the correct number and type of
  results, the following odd [prompt] will be printed instead:

    Bad Prompt
    See :DOC ld-prompt>

  which will lead you to this message.  You should either call [47m[ld][0m
  appropriately next time or assign an appropriate value to
  [47mld-prompt[0m.")
 (LD-QUERY-CONTROL-ALIST
  (LD)
  "How to default answers to queries

  [47mLd-query-control-alist[0m is an [47m[ld][0m special (see [ld]).  The accessor
  is [47m(ld-query-control-alist state)[0m and the updater is
  [47m(set-ld-query-control-alist val state)[0m.  Roughly speaking,
  [47mld-query-control-alist[0m is either [47mnil[0m (meaning all queries should be
  interactive), [47mt[0m (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 [47mt[0m or [47mnil[0m, indicating the default value
  for all ids not listed explicitly.  Formally, the
  [47mld-query-control-alist[0m must satisfy [47mld-query-control-alistp[0m.  The
  initial [47mld-query-control-alist[0m is [47mnil[0m, which means all queries are
  handled interactively.

  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
  [47mld-query-control-alist[0m to prevent the query from being handled
  interactively.  By ``handled interactively'' we mean that the query
  is printed to [47m[*standard-co*][0m and a response is read from
  [47m[*standard-oi*][0m.  The alist can be used to obtain a ``default
  value'' for each query id.  If this value is [47mnil[0m, then the query is
  handled interactively.  In all other cases, the system handles the
  query without interaction (although text may be printed to
  [47m[standard-co][0m to make it appear that an interaction has occurred;
  see below).  If the default value is [47mt[0m, 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
  [47mnil[0m nor [47mt[0m, 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.

  Next, we discuss how the [47mld-query-control-alist[0m 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 [47m[cdr][0m of the alist as the value.  Thus, [47mnil[0m
  assigns all ids [47mnil[0m.  [47mT[0m assigns all ids [47mt[0m.  [47m'((:filter . nil)
  (:sysdef . :n) . t)[0m assigns [47mnil[0m to the [47m:filter[0m query, [47m:n[0m to the
  [47m:sysdef[0m query, and [47mt[0m to all others.

  It remains only to discuss how the system prints text when the
  default value is not [47mnil[0m, 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, [47m:sysdef[0m queries would be handled noninteractively,
  with printing done to simulate the interaction.  But if we change
  the example so that [47m:sysdef[0m is paired with [47m(:n)[0m, i.e., if
  [47mld-query-control-alist[0m is [47m'((:filter . nil) (:sysdef :n) . t)[0m, then
  no such printing would take place for [47msysdef[0m queries.  Instead, the
  default value of [47m:n[0m would be assigned ``quietly''.")
 (LD-REDEFINITION-ACTION
  (LD)
  "To allow redefinition without [undoing]

  The present topic discusses redefining functions, macros, and
  constants, using a mechanism that may be convenient but also may be
  unsafe or unsound.  See [undo] for what is often a better way to
  carry out redefinition.

  [47mLd-redefinition-action[0m is an [47m[ld][0m special (see [ld]).  The accessor
  is [47m(ld-redefinition-action state)[0m and the updater is
  [47m(set-ld-redefinition-action val state)[0m.

  [31;1mWARNING![0m If [47mld-redefinition-action[0m is non-[47mnil[0m then ACL2 is liable to
  be made unsafe or unsound, or behave in unexpected ways.  For
  example, redefining a macro or inlined function, [47mf[0m, that is called
  in the body of another function, [47mg[0m, may not cause the new version
  of [47mf[0m to be called by [47mg[0m.  In addition, for some Lisps, in particular
  GCL Version 2.7.0 or later, the return type [47mTP[0m inferred for the
  original definition of [47mf[0m might cause mishandling of the return
  value from [47mf[0m as [47mg[0m still expects that value's type to be [47mTP[0m.
  Redefinition should be viewed as a way to facilitate unsafe, but
  potentially useful, hacking.

  The keyword command [47m:[0m[47m[redef][0m will set [47mld-redefinition-action[0m to a
  convenient setting allowing unsound redefinition.  See below.

  When [47mld-redefinition-action[0m is [47mnil[0m, 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
  [47m:[0m[47m[program][0m mode to be a function symbol in [47m:[0m[47m[logic][0m mode provided
  the formals and body remain the same.  This is the standard way a
  function ``comes into'' logical existence.

  Throughout the rest of this discussion we exclude from our meaning of
  ``redefinition'' the case in which a function in [47m:[0m[47m[program][0m mode is
  identically redefined in [47m:[0m[47m[logic][0m mode.  At one time, ACL2 freely
  permitted the [signature]-preserving redefinition of [47m:[0m[47m[program][0m
  mode functions but it no longer does.  See [redefining-programs].

  When [47mld-redefinition-action[0m is non-[47mnil[0m, you are allowed to redefine a
  name that is already in use.  [31;1mThe system may be rendered unsound[0m by
  such an act.  It is important to understand how dangerous
  redefinition is.  Suppose [47mfn[0m is a function symbol that is called
  from within some other function, say [47mg[0m.  Suppose [47mfn[0m is redefined so
  that its arity changes.  Then the definition of [47mg[0m 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 [47mg[0m by
  running the corresponding function in raw Common Lisp the
  redefinition of [47mfn[0m 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 [47mg[0m survive the
  redefinition of [47mfn[0m but may have crucially depended on the
  properties of the old [47mfn[0m.  In summary, we repeat the warning: [31;1mall
  bets are off if you set[0m [47mld-redefinition-action[0m to [31;1mnon[0m-[47mnil[0m.

  ACL2 provides some enforcement of the concern above, by disabling
  [47m[certify-book][0m if any [world]-changing [events] exist in the
  certification [world] that were executed with a non-[47mnil[0m value of
  [47m'ld-redefinition-action[0m.  (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 [embedded-event-form].)

  If at any point in a session you wish to see the list of all names
  that have been redefined, see [redefined-names].

  That said, we'll give you enough rope to hang yourself.  When
  [47mld-redefinition-action[0m is non-[47mnil[0m, it must be a pair, [47m(a .  b)[0m.
  The value of [47ma[0m determines how the system interacts with you when a
  redefinition is submitted.  The value of [47mb[0m allows you to specify
  how the property list of the redefined name is to be ``renewed''
  before the redefinition.

  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:

      [47m:query[0m --- 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 [47mb[0m for this
      redefinition.  [47m:Query[0m is the recommended setting for users who
      wish to dabble in redefinition.

      [47m:warn[0m --- 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 [47ma[0m.

      [47m:doit[0m --- 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 [47m:warn[0m).

  In support of our own ACL2 systems [programming] there are two other
  settings.  We suggest ordinary users not use them.

      [47m:warn![0m --- 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.

      [47m:doit![0m --- 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.)

  Part [47mb[0m of [47mld-redefinition-action[0m tells the system how to ``renew''
  the property list of the name being redefined.  There are two
  choices:

      [47m:erase[0m --- erase all properties stored under the name, or

      [47m:overwrite[0m --- preserve existing properties and let the redefining
      overwrite them.

  It should be stressed that neither of these [47mb[0m settings is guaranteed
  to result in an entirely satisfactory state of affairs after the
  redefinition.  Roughly speaking, [47m:erase[0m 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,
  [47m:overwrite[0m might be the correct [47mb[0m setting.  For example if [47mfn[0m was a
  function and is being re-[47m[defun][0m'd with the same [signature], then
  the properties stored by the new [47m[defun][0m should overwrite those
  stored by the old [47m[defun][0m but the properties stored by [47m[defthm][0ms
  will be preserved.

  In addition, neither setting will cause ACL2 to erase properties
  stored under other symbols!  Thus, if [47mFOO[0m names a rewrite rule
  which rewrites a term beginning with the function symbol [47mBAR[0m and
  you then redefine [47mFOO[0m to rewrite a term beginning with the function
  symbol [47mBAZ[0m, then the old version of [47mFOO[0m is still available (because
  the rule itself was added to the rewrite rules for [47mBAR[0m, whose
  property list was not cleared by redefining [47mFOO[0m).

  The [47mb[0m 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.

  The keyword command [47m:[0m[47m[redef][0m sets [47mld-redefinition-action[0m to the pair
  [47m(:query . :overwrite)[0m.  Since the resulting query will give you the
  chance to specify [47m:erase[0m instead of [47m:overwrite[0m, this setting is
  quite convenient.  But when you are engaged in heavy-duty
  prototyping, you may wish to use a setting such as [47m:warn[0m or even
  [47m:doit[0m.  For that you will have to invoke a form such as:

    (set-ld-redefinition-action '(:doit . :overwrite) state) .

  [47m[Encapsulate][0m causes somewhat odd interaction with the user if
  redefinition occurs within the encapsulation because the
  [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.

  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 [redundant-events], in particular the
  section ``Note About Unfortunate Redundancies,'' for more
  discussion of potential pitfalls of redefinition.")
 (LD-SKIP-PROOFSP
  (LD)
  "How carefully ACL2 processes your [command]s

    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>

  A global variable in the ACL2 [47m[state][0m, called [47m'ld-skip-proofsp[0m,
  determines the thoroughness with which ACL2 processes your
  [command]s.  This variable may take on one of three values: [47mt[0m, [47mnil[0m
  or [47m'[0m[47m[include-book][0m.  When [47mld-skip-proofsp[0m is non-[47mnil[0m, the system
  skips all proofs, which of course can render the system unsound.
  The form [47m(set-ld-skip-proofsp flg state)[0m is the general-purpose way
  of setting [47mld-skip-proofsp[0m.  This global variable is an ``[47m[ld][0m
  special,'' which is to say, you may call [47m[ld][0m in such a way as to
  ``bind'' this variable for the dynamic extent of the [47m[ld][0m.

  When [47mld-skip-proofsp[0m is non-[47mnil[0m, the default [prompt] displays the
  character [47ms[0m.  Thus, the [prompt]

    ACL2 !s>

  means that the default [defun-mode] is [47m:[0m[47m[logic][0m (otherwise the
  character [47mp[0m, for [47m:[0m[47m[program][0m, would also be printed; see
  [default-print-prompt]) but ``proofs are being skipped.''

  Observe that there are two legal non-[47mnil[0m values, [47mt[0m and
  [47m'[0m[47m[include-book][0m.  When [47mld-skip-proofsp[0m is [47mt[0m, ACL2 skips all proof
  obligations but otherwise performs all other required analysis of
  input [events].  When [47mld-skip-proofsp[0m is [47m'[0m[47m[include-book][0m, ACL2
  skips not only proof obligations but all analysis except that
  required to compute the effect of successfully executed [events].
  To explain the distinction, let us consider one particular event,
  say a [47m[defun][0m.  Very roughly speaking, a [47m[defun][0m 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
  [47m:[0m[47m[definition][0m rule and some [47m:[0m[47m[type-prescription][0m rules.  By
  ``normally'' above we mean when [47mld-skip-proofsp[0m is [47mnil[0m.  How does a
  [47m[defun][0m behave when [47mld-skip-proofsp[0m is non-[47mnil[0m?

  If [47mld-skip-proofsp[0m is [47mt[0m, then [47m[defun][0m performs the syntactic
  well-formedness checks and computes and stores the various rules,
  but it does not actually carry out the termination proofs.  If
  [47mld-skip-proofsp[0m is [47m'[0m[47m[include-book][0m, [47m[defun][0m 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 [47m'[0m[47m[include-book][0m is ``stronger''
  than a setting of [47mt[0m in the sense that [47m'[0m[47m[include-book][0m causes
  [47m[defun][0m to assume even more about the admissibility of the event
  than [47mt[0m does.

  As one might infer from the choice of name, the [47m[include-book][0m event
  sets [47mld-skip-proofsp[0m to [47m'[0m[47m[include-book][0m when processing the
  [events] in a book being loaded.  Thus, [47m[include-book][0m 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.

  A non-[47mnil[0m value for [47mld-skip-proofsp[0m also affects the system's output
  messages.  Event summaries (the paragraphs that begin ``[Summary]''
  and display the event forms, rules used, etc.) are not printed when
  [47mld-skip-proofsp[0m is non-[47mnil[0m.  Warnings and observations are printed
  when [47mld-skip-proofsp[0m is [47mt[0m but are not printed when it is
  [47m'[0m[47m[include-book][0m.

  Intuitively, [47mld-skip-proofsp[0m [47mt[0m means skip just the proofs and
  otherwise do all the work normally required for an event; while
  [47mld-skip-proofsp[0m [47m'[0m[47m[include-book][0m is ``stronger'' and means do as
  little as possible to process [events].  In accordance with this
  intuition, [47m[local][0m [events] are processed when [47mld-skip-proofsp[0m is [47mt[0m
  but are skipped when [47mld-skip-proofsp[0m is [47m'[0m[47m[include-book][0m.

  The ACL2 system itself uses only two settings, [47mnil[0m and
  [47m'[0m[47m[include-book][0m, the latter being used only when executing the
  [events] inside of a book being included.  The [47mld-skip-proofsp[0m
  setting of [47mt[0m is provided as a convenience to the user.  For
  example, suppose one has a file of [events].  By loading it with
  [47m[ld][0m with [47mld-skip-proofsp[0m set to [47mt[0m, the [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 [events] file.

  The foregoing discussion is actually based on a lie.  [47mld-skip-proofsp[0m
  is allowed two other values, [47m'initialize-acl2[0m and
  [47m'include-book-with-locals[0m.  The first causes behavior similar to [47mt[0m
  but skips [47m[local][0m [events] and avoids some error checks that would
  otherwise prevent ACL2 from properly booting.  The second is
  identical to [47m'[0m[47m[include-book][0m but also executes [47m[local][0m [events].
  These additional values are not intended for use by the user, but
  no barriers to their use have been erected.

  User-defined tools may temporarily modify the global setting of
  [47mld-skip-proofsp[0m; for example, see [remove-hyps].

  We close by reminding the user that ACL2 is potentially unsound if
  [47mld-skip-proofsp[0m is set by the user.  Indeed, direct setting of
  [47mld-skip-proofsp[0m is illegal within a book (except during
  [47m[make-event][0m expansion).  We provide access to it simply to allow
  experimentation and rapid reconstruction of lost or modified
  logical [world]s.")
 (LD-USER-STOBJS-MODIFIED-WARNING (POINTERS)
                                  "See [user-stobjs-modified-warnings].")
 (LD-VERBOSE
  (LD)
  "Determines whether [47m[ld][0m prints ``ACL2 Loading ...''

  [47mLd-verbose[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(ld-verbose state)[0m and the updater is [47m(set-ld-verbose val state)[0m.
  [47mLd-verbose[0m must be [47mt[0m, [47mnil[0m or a string or [47m[consp][0m suitable for [47m[fmt][0m
  printing via the [47m~@[0m command.  The initial value of [47mld-verbose[0m is a
  [47m[fmt][0m message that prints the system books directory.

  Note: [47mLd-verbose[0m has no effect on proofs.  See [set-gag-mode] and see
  [set-inhibit-output-lst] for how to control the size of proof
  output.

  Before processing the forms in [47m[standard-oi][0m, [47m[ld][0m may print a
  header.  The printing of this header is controlled by [47mld-verbose[0m.
  If [47mld-verbose[0m is [47mnil[0m, no header is printed.  If it is [47mt[0m, [47m[ld][0m
  prints the message

    ACL2 loading <file>

  where [47m<file>[0m is the input channel supplied to [47m[ld][0m.  A similar
  message is printed when [47m[ld][0m completes.  If [47mld-verbose[0m is neither [47mt[0m
  nor [47mnil[0m then it is presumably a header and is printed with the [47m~@[0m
  [47m[fmt][0m directive before [47m[ld][0m begins to read and process forms.  In
  this case the [47m~@[0m [47m[fmt][0m directive is interpreted in an environment
  in which [47m#\\b[0m is the system books directory, [47m#\\v[0m is the ACL2 version
  string, [47m#\\l[0m is the level of the current recursion in [47m[ld][0m and/or
  [47m[wormhole][0m, and [47m#\\c[0m is the connected book directory [47m(cbd)[0m.")
 (LEGAL-CONSTANTP (POINTERS)
                  "See [system-utilities].")
 (LEGAL-VARIABLEP (POINTERS)
                  "See [system-utilities].")
 (LEMMA-INSTANCE
  (HINTS FUNCTIONAL-INSTANTIATION)
  "An object denoting an instance of a theorem

  Lemma instances are the objects one provides via [47m:use[0m and [47m:by[0m [hints]
  to bring to the theorem prover's attention some previously proved
  or easily provable fact.  A typical use of the [47m:use[0m hint is given
  below.  The value specified is a list of five lemma instances.

    :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))))

  Observe that an event name can be a lemma instance.  The [47m:use[0m hint
  allows a single lemma instance to be provided in lieu of a list, as
  in:

    :use reverse-reverse

  or

    :use (:instance assoc-of-app (x a) (y b) (z c))

  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.

  A lemma instance, or [47mlmi[0m, is of one of the following forms:

  (1) [47mname[0m, where [47mname[0m names a previously proved theorem, axiom, or
  definition and denotes the formula (theorem) of that name.

  (2) [47mrune[0m, where [47mrune[0m is a [rune] (see [rune]) denoting the
  [47m:[0m[47m[corollary][0m justifying the rule named by the [rune].

  (3) [47m(:theorem term)[0m, where [47mterm[0m is any term alleged to be a theorem.
  Such a lemma instance denotes the formula [47mterm[0m.  But before using
  such a lemma instance the system will undertake to prove [47mterm[0m.

  (4) [47m(:instance lmi (v1 t1) ... (vn tn))[0m, where [47mlmi[0m is recursively a
  lemma instance, the [47mvi[0m's are distinct variables, and the [47mti[0m's are
  terms.  Such a lemma instance denotes the formula obtained by
  instantiating the formula [47mF[0m denoted by [47mlmi[0m, normally by replacing
  each [47mvi[0m by [47mti[0m in [47mF[0m and requiring that each [47mvi[0m must be bound in [47mF[0m.
  There are two exceptions.  If the keyword [47m:extra-bindings-ok[0m is
  inserted immediately after the lemma instance in order to remove
  that requirement, as follows, then that requirement is ignored:
  [47m(:instance lmi :extra-bindings-ok (v1 t1) ... (vn tn))[0m.  Otherwise
  there is the following exception pertaining to [packages]: if one
  or more variables [47mvi[0m do not occur in [47mF[0m, but for each such [47mvi[0m
  exactly one variable [47mv[0m with the same [47m[symbol-name][0m as [47mvi[0m occurs in
  [47mF[0m and no other [47mvj[0m with the same [47msymbol-name[0m as [47mv[0m is bound in the
  substitution, then the pair [47m(vi ti)[0m is replaced by the pair [47m(v ti)[0m
  in the substitution.

  (5) [47m(:functional-instance lmi (f1 g1) ... (fn gn))[0m, where [47mlmi[0m is
  recursively a lemma instance and each [47mfi[0m is an ``instantiable''
  function symbol of arity [47mni[0m and [47mgi[0m is a function symbol, a macro
  alias for a function symbol [47mgi'[0m (see [macro-aliases-table]) in
  which case we treat [47mgi[0m as [47mgi'[0m, or a pseudo-lambda expression of
  arity [47mni[0m.  An instantiable function symbol is any defined or
  constrained function symbol except the primitives [47m[not][0m, [47m[member][0m,
  [47m[implies][0m, and [47m[o<][0m, and a few others, as listed by the constant
  [47m*non-instantiable-primitives*[0m.  These are built-in in such a way
  that we cannot recover the [constraint]s on them.  (Special case: a
  function introduced in the [47m:partial-theory[0m of a dependent
  clause-processor is not instantiable; see
  [define-trusted-clause-processor].)  A pseudo-lambda expression is
  an expression of the form [47m(lambda (v1 ... vn) body)[0m where the [47mvi[0m
  are distinct variable symbols and [47mbody[0m is any term.  No [3ma priori[0m
  relation is imposed between the [47mvi[0m and the variables of [47mbody[0m, i.e.,
  [47mbody[0m may ignore some [47mvi[0m's and may contain ``free'' variables.
  However, we do not permit [47mv[0m to occur freely in [47mbody[0m if the
  functional substitution is to be applied to any formula ([47mlmi[0m or the
  [constraint]s to be satisfied) in a way that inserts [47mv[0m into the
  scope of a binding of [47mv[0m by [47m[let][0m or [47m[mv-let][0m (or, [47m[lambda][0m).  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 [47mv[0m in the context in which the
  functional substitution is offered.  A [47m:functional-instance[0m lemma
  instance denotes the formula obtained by functionally instantiating
  the formula denoted by [47mlmi[0m, replacing [47mfi[0m by [47mgi[0m.  However, before
  such a lemma instance can be used, the system will generate proof
  obligations arising from the replacement of the [47mfi[0m's by the [47mgi[0m's in
  constraints that ``support'' the lemma to be functionally
  instantiated; 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 [47m[encapsulate][0m event that either has a non-empty
  [signature] list or is ``empty'' (stores no events), and then
  avoids re-proving that constraint in future [events].

  See [functional-instantiation-example] for an example of the use of
  [47m:functional-instance[0m (so-called ``functional instantiation'').

  Note that ACL2(r) (see [real]) imposes additional requirements for
  functional instantiation.  See [functional-instantiation-in-ACL2r].

  (6) [47m(:termination-theorem name)[0m or [47m(:termination-theorem! name)[0m,
  where [47mname[0m is a function symbol in [logic] mode.  Such a lemma
  instance denotes the termination theorem previously proved for
  [47mname[0m, possibly modified as discussed in the next paragraph.  If no
  such theorem exists --- for example, if the definition of [47mname[0m is
  not recursive --- then the lemma instance is illegal in the case of
  [47m:termination-theorem[0m, but denotes [47mT[0m in the case of
  [47m:termination-theorem![0m.  If [47mname[0m is defined as part of a
  mutually-recursive clique of definitions (see [mutual-recursion]),
  then the lemma instance refers to the termination theorem proved
  for the entire clique.  See [termination-theorem-example] and see
  [tthm].

  Consider the application of [47m:termination-theorem f[0m while attempting
  to prove the termination theorem for a function, [47mg[0m.  For now
  suppose that neither [47mf[0m nor [47mg[0m is defined using [47m[mutual-recursion][0m.
  Suppose that [47mf[0m and [47mg[0m have the same number of formal parameters.
  Then every call of [47mf[0m in the termination theorem for [47mf[0m will be
  replaced by a call of [47mg[0m on the same arguments (except, recursively,
  [47mf[0m is also replaced by [47mg[0m in those arguments).  The analogous
  replacement also takes place for mutually recursive definitions, as
  follows.  In the case that [47mf[0m was introduced with [47m(mutual-recursion
  (defun f1 ...) ... (defun fk ...))[0m and similarly [47mg[0m is being
  introduced with [47m(mutual-recursion (defun g1 ...)  ... (defun gk
  ...))[0m, where for each [47mi[0m from [47m1[0m to [47mk[0m the number of formal parameters
  is the same for [47mfi[0m and [47mgi[0m, then the functional substitution [47m((f1 .
  g1) ... (fk . gk))[0m is applied to the termination theorem for the
  [47mfi[0m.  (Logical justification in a nutshell: the termination proof
  for the [47mfi[0m took place before adding their definitional equations to
  the current theory, where the [47mfi[0m were thus stubs with no axioms.)
  Note that unlike normal [functional-instantiation], here there is
  no proof obligation.  However, the restriction applies from (5)
  above that the functions [47mfi[0m are instantiable; when that fails, then
  the replacement of each [47mfi[0m by [47mgi[0m will not take place.

  Finally, note that an optional second argument to
  [47m:termination-theorem[0m specifies an explicit functional substitution
  [47m((f1 g1) ... (fn gn))[0m, which is to be applied to the termination
  theorem for [47mf[0m.  If that argument is supplied, then there will be no
  attempt to derive a functional substitution automatically, as
  described in the preceding paragraph.

  (7) [47m(:guard-theorem name)[0m or [47m(:guard-theorem name simplify)[0m, where
  [47mname[0m is a [guard]-verified function symbol (hence, in particular,
  is in [logic] mode).  Such a lemma instance denotes the guard
  theorem previously proved for [47mname[0m, where by default [47msimplify[0m is
  [47m:limited[0m, which enables certain simplifications as documented
  elsewhere; see [gthm].  Otherwise [47msimplify[0m should be [47mnil[0m, to avoid
  all such simplification.  If [47mname[0m is defined as part of a
  mutually-recursive clique of definitions (see [mutual-recursion]),
  then the lemma instance refers to the guard theorem proved for the
  entire clique.  See [guard-theorem-example] and see [gthm].

  Obscure case for [definition]s.  If the lemma instance refers to a
  [47m:definition[0m [rune], then it refers to the [47m[corollary][0m formula of
  that rune, which can be a normalized (simplified) form of the
  definition body; see [normalize].  However, if the hint is a [47m:by[0m
  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 [47m:[0m[47m[pe][0m, rather than the normalized version, as
  shown by [47m:[0m[47m[pf][0m.  This is as one would expect: If you supply the
  name of an event, you expect it to refer to the original event.
  For [47m:use[0m hints we use the simplified ([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.

  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
  [47m:termination-theorem[0m lemma instances; for [47m:guard-theorem[0m, 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 [built-in-clause] rules that
  come with ACL2.  Also see [guard-formula-utilities] and
  [guard-simplification].  Moreover, the [47m:[0m[47m[measure-debug][0m and
  [47m:[0m[47m[guard-debug][0m keywords for [47m[xargs][0m are ignored when generating the
  termination or guard theorem.  You can see the termination or guard
  theorem for an existing function symbol [47mFN[0m by evaluating the form
  [47m(termination-theorem 'FN (w state))[0m or [47m(guard-theorem 'FN simplify
  guard-debug (w state) state)[0m, respectively.  In the former case,
  failure is indicated by a result of the form [47m(FAILED . msg)[0m, where
  [47mmsg[0m is a message suitable for [47m[fmt][0m; see [msg].

  Also see [make-termination-theorem].

  Why do we avoid simplification for [47m:termination-theorem[0m, 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
  [47m[make-event][0m.  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 [case-split-limitations], which
  depends on the current logical [world]; but we expect the two
  theorems to be logically equivalent.


Subtopics

  [Guard-theorem]
      Use a previously-proved [guard] theorem

  [Guard-theorem-example]
      How to use a previously-proved [guard] theorem

  [Termination-theorem]
      Use a (functional instance of a) previously-proved measure theorem

  [Termination-theorem-example]
      How to use a previously-proved measure theorem")
 (LEN
  (LISTS ACL2-BUILT-INS)
  "Length of a list

  [47mLen[0m returns the length of a list.

  A Common Lisp function that is appropriate for both strings and
  proper lists is [47mlength[0m; see [length].  The guard for [47mlen[0m is [47mt[0m.

  (Low-level implementation note.  ACL2 provides a highly-optimized
  implementation of [47mlen[0m, which is tail-recursive and fixnum-aware,
  that differs from its simple ACL2 definition.)

  [31;1mFunction: [0m<len>

    (defun len (x)
      (declare (xargs :guard t))
      (if (consp x) (+ 1 (len (cdr x))) 0))")
 (LENGTH
  (LISTS STRINGS ACL2-BUILT-INS)
  "Length of a string or proper list

  [47mLength[0m is the function for determining the length of a sequence.  In
  ACL2, the argument is required to be either a [47m[true-listp][0m or a
  string.

  For a similar function that is logically defined to be equal to zero
  on any atom, including any string, see [47m[len][0m.

  [47mLength[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<length>

    (defun length (x)
      (declare (xargs :guard (if (true-listp x) t (stringp x))))
      (if (stringp x)
          (len (coerce x 'list))
        (len x)))")
 (LET (BASICS ACL2-BUILT-INS)
  "Binding of lexically scoped (local) variables


Introduction

  Example

    (let ((x (* x x))
          (y (* 2 x)))
     (list x y))

  If the form above is executed in an environment in which [47mx[0m has the
  value [47m-2[0m, then the result is [47m'(4 -4)[0m.

  [47mLet[0m expressions bind variables so that their ``local'' values, the
  values they have when the ``body'' of the [47mlet[0m is evaluated, are
  possibly different than their ``global'' values, the values they
  have in the context in which the [47mlet[0m expression appears.  In the
  [47mlet[0m expression above, the local variables bound by the [47mlet[0m are [47mx[0m
  and [47my[0m.  They are locally bound to the values delivered by the two
  forms [47m(* x x)[0m and [47m(* 2 x)[0m, respectively, that appear in the
  ``bindings'' of the [47mlet[0m.  The body of the [47mlet[0m is [47m(list x y)[0m.

  Suppose that the [47mlet[0m expression above occurs in a context in which [47mx[0m
  has the value [47m-2[0m.  (The global value of [47my[0m is irrelevant to this
  example.)  For example, one might imagine that the [47mlet[0m form above
  occurs as the body of some function, [47mfn[0m, with the formal parameter
  [47mx[0m and we are evaluating [47m(fn -2)[0m.

  To evaluate the [47mlet[0m above in a context in which [47mx[0m is [47m-2[0m, we first
  evaluate the two forms specifying the local values of the
  variables.  Thus, [47m(* x x)[0m is evaluated and produces [47m4[0m (because [47mx[0m is
  [47m-2[0m) and [47m(* 2 x)[0m is evaluated and produces [47m-4[0m (because [47mx[0m is [47m-2[0m).
  Then [47mx[0m and [47my[0m are bound to these values and the body of the [47mlet[0m is
  evaluated.  Thus, when the body, [47m(list x y)[0m is evaluated, [47mx[0m is [47m4[0m
  and [47my[0m is [47m-4[0m.  Thus, the body produces [47m'(4 -4)[0m.

  Note that the binding of [47my[0m, which is written after the binding of [47mx[0m
  and which mentions [47mx[0m, nevertheless uses the global value of [47mx[0m, not
  the new local value.  That is, the local variables of the [47mlet[0m are
  bound ``in parallel'' rather than ``sequentially.'' In contrast, if
  the example [47mlet*[0m form:

    (let* ((x (* x x))
           (y (* 2 x)))
     (list x y))

  is evaluated when the global value of [47mx[0m is [47m-2[0m, then the result is [47m'(4
  8)[0m, because the local value of [47my[0m is computed after [47mx[0m has been bound
  to [47m4[0m.  [47m[Let*][0m binds its local variables ``sequentially.''

  General [47mlet[0m forms

    (let ((var1 term1) ... (varn termn)) body)
    and
    (let ((var1 term1) ... (varn termn))
     (declare ...) ... (declare ...)
     body)

  where the [47mvari[0m are distinct variables, the [47mtermi[0m are terms involving
  only variables bound in the environment containing the [47mlet[0m, and
  [47mbody[0m is a term involving only the [47mvari[0m plus the variables bound in
  the environment containing the [47mlet[0m.  Each [47mvari[0m must be used in [47mbody[0m
  or else [declare]d ignored.  In ACL2 the only [47m[declare][0m forms
  allowed for a [47mlet[0m form are [47mignore[0m, [47mignorable[0m, and [47mtype[0m.  See
  [declare].

  A [47mlet[0m form is evaluated by first evaluating each of the [47mtermi[0m,
  obtaining for each a [47mvali[0m.  Then, each [47mvari[0m is bound to the
  corresponding [47mvali[0m and [47mbody[0m is evaluated.

  Actually, [47mlet[0m forms are just abbreviations for certain uses of [47mlambda[0m
  notation.  In particular

    (let ((var1 term1) ... (varn termn)) (declare ...) body)

  is equivalent to

    ((lambda (var1 ... varn)
       (declare ...)
       body)
     term1 ... termn).

  [47m[Let*][0m forms are used when it is desired to bind the [47mvari[0m
  sequentially, i.e., when the local values of preceding [47mvarj[0m are to
  be used in the computation of the local value for [47mvari[0m.

  General [47mlet*[0m forms:

    (let* ((var1 term1) ... (varn termn)) body)
    and
    (let* ((var1 term1) ... (varn termn))
     (declare (ignore x1 ... xm))
     body)

  where the [47mvari[0m are variables (not necessarily distinct), the [47mtermi[0m
  are terms involving only variables bound in the environment
  containing the [47m[let*][0m and those [47mvarj[0m such that [47mj<i[0m, and [47mbody[0m is a
  term involving only the [47mvari[0m plus the variables bound in the
  environment containing the [47m[let*][0m.  Each [47mvari[0m must be used either
  in some subsequent [47mtermj[0m or in [47mbody[0m, except that in the second form
  above we make an exception when [47mvari[0m is among the [47mxk[0m, in which case
  [47mvari[0m must not be thus used.  Note that [47m[let*][0m does not permit the
  inclusion of any [47m[declare][0m forms other than one as shown above.  In
  the second general form above, every [47mxk[0m must be among the [47mvari[0m, and
  furthermore, [47mxk[0m may not equal [47mvari[0m and [47mvarj[0m for distinct [47mi[0m, [47mj[0m.

  The first [47m[let*][0m above is equivalent to

    (let ((var1 term1))
     ...
     (let ((varn termn)) body)...)

  Thus, the [47mtermi[0m are evaluated successively and after each evaluation
  the corresponding [47mvari[0m is bound to the value of [47mtermi[0m.  The second
  [47m[let*][0m is similarly expanded, except that each for each [47mvari[0m that
  is among the [47m(x1 ... xm)[0m, the form [47m(declare (ignore vari))[0m is
  inserted immediately after [47m((vari termi))[0m.

  Each [47m(vari termi)[0m pair in a [47mlet[0m or [47m[let*][0m form is called a
  ``binding'' of [47mvari[0m and the [47mvari[0m are called the ``local variables''
  of the [47mlet[0m or [47m[let*][0m.  The common use of [47mlet[0m and [47m[let*][0m is to save
  the values of certain expressions (the [47mtermi[0m) so that they may be
  referenced several times in the body without suggesting their
  recomputation.

  [47mLet[0m is part of Common Lisp.  See any Common Lisp documentation for
  more information.")
 (LET* (BASICS ACL2-BUILT-INS)
  "Binding of lexically scoped (local) variables

  Examples

    (let* ((x (* x x))
           (y (* 2 x)))
     (list x y))

    (let* ((x (* x x))
           (y (* 2 x))
           (x (* x y))
           (a (* x x)))
     (declare (ignore a))
     (list x y))

  If the forms above are executed in an environment in which [47mx[0m has the
  value [47m-2[0m, then the respective results are [47m'(4 8)[0m and [47m'(32 8)[0m.  See
  [let] for a discussion of both [47m[let][0m and [47mlet*[0m, or read on for a
  briefer discussion.

  The difference between [47m[let][0m and [47mlet*[0m is that the former binds its
  local variables in parallel while the latter binds them
  sequentially.  Thus, in [47mlet*[0m, 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 [let].

  In ACL2 the only [47m[declare][0m forms allowed for a [47mlet*[0m form are [47mignore[0m,
  [47mignorable[0m, and [47mtype[0m.  See [declare].  Moreover, no variable
  declared [47mignore[0md or [47mignorable[0m 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.

  [47mLet*[0m is a Common Lisp macro.  See any Common Lisp documentation for
  more information.")
 (LET-MBE (POINTERS)
          "See [equality-variants-details].")
 (LEX-FIX (POINTERS) "See [l<].")
 (LEXORDER
  (<< ACL2-BUILT-INS)
  "Total order on ACL2 objects

  [47mLexorder[0m is a non-strict total order, a ``less than or equal,'' on
  ACL2 objects.  Also see [alphorder], the restriction of [47mlexorder[0m to
  atoms; the notion of ``non-strict total order'' is defined there.

  [47mLexorder[0m has a guard of [47mt[0m.

  For [47mlexorder[0m, an [atom] and a [cons] are ordered so that the [atom]
  comes first, and two [cons]es are ordered so that the one with the
  recursively smaller [47m[car][0m comes first, with the [47m[cdr][0ms being
  compared only if the [47m[car][0ms are equal.  [47mLexorder[0m compares two atoms
  by using [47m[alphorder][0m.

  [31;1mFunction: [0m<lexorder>

    (defun lexorder (x y)
      (declare (xargs :guard t))
      (cond ((atom x)
             (cond ((atom y) (alphorder x y)) (t t)))
            ((atom y) nil)
            ((equal (car x) (car y))
             (lexorder (cdr x) (cdr y)))
            (t (lexorder (car x) (car y)))))")
 (LEXP (POINTERS) "See [l<].")
 (LINEAR
  (RULE-CLASSES)
  "Make some arithmetic inequality rules

  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.

    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)
                                ...)))
         ...)

  We process the [47m:[0m[47m[corollary][0m formula of one [47m:linear[0m rule class object
  to create one or more [47m:linear[0m rules.  The first step is to flatten
  the [47m[and][0m and [47m[implies][0m structure of the formula, transforming it
  into a conjunction of formulas, each of the form

    (implies (and h1 ... hn) (rel lhs rhs))

  where no hypothesis is a conjunction and the term [47m(rel lhs rhs)[0m is a
  call of one of the inequality relations [47m[<][0m, [47m[<=][0m, [47m[>][0m, or [47m[>=][0m;
  the negation of such a call; a call of [47m[=][0m or [47m[equal][0m; or a negated
  call of [47m[/=][0m.  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 [47m:linear[0m
  rule for each such conjunct, if possible, and otherwise cause an
  error.  To create a [47m:linear[0m 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 [47m[<=][0m, [47m[>][0m, and
  [47m[>=][0m).

   1. Remove [guard-holders] such as [47m[prog2$][0m from the term to obtain
      [47m(implies hyp concl)[0m, where [47mhyp[0m is [47mt[0m in the case of an
      unconditional rule.

   2. If [47mconcl[0m is [47m(not (not concl2))[0m, replace [47mconcl[0m by [47mconcl2[0m.

   3. For the resulting [47mconcl[0m, replace [47m[=][0m and [47m[/=][0m by [47m[equal][0m and [47mnot
      equal[0m, respectively.

  Each rule has one or more ``trigger terms'' which may be specified by
  the user using the [47m:trigger-terms[0m 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.

  [47m:Linear[0m rules are used by an arithmetic decision procedure during
  rewriting.  See [linear-arithmetic] and see
  [non-linear-arithmetic].  Here we assume that the reader is
  familiar with the material described in [47m[linear-arithmetic][0m.

  Recall that we eliminate the unknowns of an inequality in term-order,
  largest unknowns first.  (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 [47m:linear[0m rules.

  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 [47m:linear[0m 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.

  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 [47m(<= (fn i j) (/ i (* j j)))[0m under the trigger
  term [47m(fn i j)[0m.  Then when the system ``needs'' an inequality about
  [47m(fn a b)[0m, (i.e., because [47m(fn a b)[0m is the label of some linear pot,
  and hence the largest unknown in some inequality), it will appeal
  to the rule and deduce [47m(<= (fn a b) (/ a (* b b)))[0m.  However, the
  largest unknown in this inequality is [47m(/ a (* b b))[0m and hence it
  will be stored in a linear pot labeled with [47m(/ a (* b b))[0m.  The
  original, triggering inequality which is in a pot about [47m(fn a b)[0m
  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.

  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 [47m:trigger-terms[0m field in the rule
  class, e.g.,

    General Form of a Linear Rule Class:
    (:LINEAR :COROLLARY formula
             :TRIGGER-TERMS (term1 ... termk))

  Each [47mtermi[0m must be a term and must not be a variable, quoted
  constant, lambda application, [47mlet-expression[0m or [47mif-expression[0m.  In
  addition, each [47mtermi[0m 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 [47mtermi[0m must hold
  for each conjunct.

  If [47m:trigger-terms[0m 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 [current-theory], ground subterms
  (those that have no free variables) with their values.

  The ``addends'' of [47m(+ x y)[0m and [47m(- x y)[0m are the union of the addends
  of [47mx[0m and [47my[0m.  The addends of [47m(- x)[0m and [47m(* n x)[0m, where [47mn[0m is a
  rational constant, is just [47m{x}[0m.  The addends of an inequality are
  the union of the addends of the left- and right-hand sides.  The
  addends of any other term, [47mx[0m, is [47m{x}[0m.

  A term is maximal for a conjunct [47m(implies hyps concl)[0m of the
  corollary if (a) the term is a non-variable, non-quote, non-lambda
  application, non-[47m[let][0m and non-[47m[if][0m 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 [free-variables]) then all the variables in [47mconcl[0m 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 [47mbind-free[0m; see [bind-free].

  The technical notion referenced above depends on the notion of
  [3mfn-count[0m, the number of function symbols in a term, and
  [3mpseudo-fn-count[0m, which is essentially the number of function
  symbols implicit in a constant (see [term-order], specifically the
  discussion of ``pseudo-function application count'' at the end).
  We say [47mterm1[0m is always bigger than [47mterm2[0m if all instances of [47mterm1[0m
  have a larger fn-count (actually lexicographic order of fn-count
  and pseudo-fn-count) than the corresponding instances of [47mterm2[0m.
  This is equivalent to saying that the fn-count of [47mterm1[0m is larger
  than that of [47mterm2[0m (by ``fn-count'' here we mean the lexicographic
  order of fn-count and pseudo-fn-count) and the variable bag for
  [47mterm2[0m is a subbag of that for [47mterm1[0m.  For example, [47m(/ a (* b b))[0m is
  always bigger than [47m(fn a b)[0m because the first has two function
  applications and [47m{a b}[0m is a subbag of [47m{a b b}[0m, but [47m(/ a (* b b))[0m is
  not always bigger than [47m(fn a x)[0m.

  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 [47m:trigger-terms[0m is supplied explicitly
  by the user.


Subtopics

  [Backchain-limit]
      Limiting the effort expended on relieving hypotheses

  [Bind-free]
      To bind free variables of a rewrite, definition, or linear rule

  [Case-split]
      Like force but immediately splits the top-level goal on the
      hypothesis

  [Force]
      Identity function used to force a hypothesis

  [Linear-arithmetic]
      A description of the linear arithmetic decision procedure

  [Non-linear-arithmetic]
      Non-linear Arithmetic

  [Syntaxp]
      Attach a heuristic filter on a rule")
 (LINEAR-ARITHMETIC
  (LINEAR)
  "A description of the linear arithmetic decision procedure

  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
  [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 [47m:[0m[47m[linear][0m 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 [introduction-to-rewrite-rules-part-1] and
  [introduction-to-rewrite-rules-part-2].)

  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 [47m1[0m simply to allow a term in the sum to be
  constant.  Thus, an example linear polynomial is [47m3*x + 7*a + 2[0m;
  here [47mx[0m and [47ma[0m are the (interesting) unknowns.  However, the unknowns
  need not be variable symbols.  For example, [47m(length x)[0m might be
  used as an unknown in a linear polynomial.  Thus, another linear
  polynomial is [47m3*(length x) + 7*a[0m.  A ``linear polynomial
  inequality'' is an inequality (either [47m[<][0m or [47m[<=][0m) relation between
  two linear polynomials.  Note that an equality may be considered as
  a pair of inequalities; e.q., [47m3*x + 7*a + 2 = 0[0m is the same as the
  conjunction of [47m3*x + 7*a + 2 <= 0[0m and [47m0 <= 3*x + 7*a + 2[0m.

  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.

  For example, suppose we have two assumptions

    p1:       3*x + 7*a <  4
    p2:               3 <  2*x

  and we wish to prove that, given [47mp1[0m and [47mp2[0m, [47ma < 0[0m.  As suggested
  above, we proceed by assuming the negation of our goal

    p3:               0 <= a.

  and looking for a contradiction.

  Our first step will be to eliminate the variable [47mx[0m.  To that end, we
  cross-multiply based on the coefficients of [47mx[0m in the two
  inequalities.  By multiplying [47mp1[0m by [47m2[0m and [47mp2[0m by [47m3[0m, and then adding
  the respective sides, we deduce the intermediate result

    p4:  6*x + 14*a + 9 < 8 + 6*x

  which, after cancellation, is:

    p4:        14*a + 1 <  0.

  If we then cross-multiply and add [47mp3[0m to [47mp4[0m, we get

    p5:               1 <= 0,

  a contradiction.  Thus, we have proved that [47mp1[0m and [47mp2[0m imply the
  negation of [47mp3[0m.

  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 [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 [47mx[0m is the largest unknown in each of [47mp1[0m and [47mp2[0m, and [47ma[0m in
  [47mp3[0m and [47mp4[0m.

  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 [47m:linear[0m
  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 [47m:[0m[47m[linear][0m rules for rules about the
  unknowns that are candidates for cancellation (i.e., are the
  largest unknowns in their respective inequalities).  See [linear]
  for a description of how [47m:[0m[47m[linear][0m rules are used.

  See also [47m[non-linear-arithmetic][0m for a description of an extension to
  the linear-arithmetic procedure described here.


Subtopics

  [Heavy-linear-p]
      Extend the use of [linear-arithmetic] during rewriting")
 (LISP-PROGRAMMER-INTRODUCTION
      (POINTERS)
      "See [introduction-to-programming-in-ACL2-for-those-who-know-lisp].")
 (LIST
  (LISTS ACL2-BUILT-INS)
  "Build a list

  [47mList[0m is the macro for building a list of objects.  For example, [47m(list
  5 6 7)[0m returns a list of length 3 whose elements are [47m5[0m, [47m6[0m, and [47m7[0m
  respectively.  Also see [list*].

  If a call of [47mlist[0m results in an error due to too many arguments,
  consider using [47m[list$][0m.

  [47mList[0m is defined in Common Lisp.  See any Common Lisp documentation
  for more information.

  [31;1mMacro: [0m<list>

    (defmacro list (&rest args)
      (list-macro args))

  [31;1mFunction: [0m<list-macro>

    (defun list-macro (lst)
      (declare (xargs :guard t))
      (if (consp lst)
          (cons 'cons
                (cons (car lst)
                      (cons (list-macro (cdr lst)) nil)))
        nil))")
 (LIST$
  (LISTS ACL2-BUILT-INS)
  "Build a list

  [47mList$[0m is a macro that is virtually interchangeable with [47m[list][0m.  The
  only difference is that when the host Lisp is [gcl] with GCL
  version at least 2.7.0, [47mlist[0m may cause an error when given too many
  arguments (generally, more than 63).  In such cases, [47mlist$[0m may be
  used in place of [47mlist[0m, since [47mlist$[0m has no restriction on the number
  of arguments.")
 (LIST*
  (LISTS ACL2-BUILT-INS)
  "Build a list

  [47mList*[0m is the Common Lisp macro for building a list of objects from
  given elements and a tail.  For example, [47m(list* 5 6 '(7 8 9))[0m
  equals the list [47m'(5 6 7 8 9)[0m.  Also see [list].

  [47mList*[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mMacro: [0m<list*>

    (defmacro list* (&rest args)
      (declare (xargs :guard (consp args)))
      (list*-macro args))

  [31;1mFunction: [0m<list*-macro>

    (defun list*-macro (lst)
      (declare (xargs :guard (and (true-listp lst) (consp lst))))
      (if (endp (cdr lst))
          (car lst)
        (cons 'cons
              (cons (car lst)
                    (cons (list*-macro (cdr lst)) nil)))))")
 (LISTP
  (LISTS CONSES ACL2-BUILT-INS)
  "Recognizer for (not necessarily proper) lists

  [47m(listp x)[0m is true when [47mx[0m is either a [47m[cons][0m pair or is [47mnil[0m.

  [47mListp[0m has no [guard], i.e., its [guard] is [47mt[0m.

  [47mListp[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<listp>

    (defun listp (x)
      (declare (xargs :guard t))
      (or (consp x) (equal x nil)))")
 (LISTS
  (PROGRAMMING)
  "Lists of objects, the classic Lisp data structure.


Subtopics

  [ACL2-number-listp]
      Recognizer for a true list of numbers

  [Add-to-set]
      Add a symbol to a list

  [Append]
      [concatenate] zero or more lists

  [Atom-listp]
      Recognizer for a true list of [atom]s

  [Boolean-listp]
      Recognizer for a true list of booleans

  [Butlast]
      All but a final segment of a list

  [Character-listp]
      Recognizer for a true list of characters

  [Concatenate]
      Concatenate lists or strings together

  [Count]
      Count the number of occurrences of an item in a string or true-list

  [Endp]
      Recognizer for empty lists

  [Eqlable-listp]
      Recognizer for a true list of objects each suitable for [47m[eql][0m

  [Evens]
      The even-indexed members of a list

  [Fix-true-list]
      Coerce to a true list

  [Improper-consp]
      Recognizer for improper (non-[47mnil[0m-terminated) non-empty lists

  [Integer-listp]
      Recognizer for a true list of integers

  [Intersection$]
      Elements common to the given lists

  [Intersectp]
      Test whether two lists intersect

  [Keyword-listp]
      Recognizer for true lists of keywords

  [Keyword-value-listp]
      Recognizer for true lists whose even-position elements are keywords

  [Last]
      The last [47m[cons][0m (not element) of a list

  [Last-cdr]
      The last [47m[cdr][0m of a list

  [Len]
      Length of a list

  [Length]
      Length of a string or proper list

  [List]
      Build a list

  [List$]
      Build a list

  [List*]
      Build a list

  [Listp]
      Recognizer for (not necessarily proper) lists

  [Make-list]
      Make a list of a given size

  [Member]
      Membership predicate

  [Merge-sort-lexorder]
      Sort a list

  [Nat-listp]
      Recognizer for a true list of natural numbers

  [No-duplicatesp]
      Check for duplicates in a list

  [Nth]
      The nth element (zero-based) of a list

  [Nthcdr]
      Final segment of a list

  [Odds]
      The odd-indexed members of a list

  [Pairlis]
      See [pairlis$]

  [Pairlis$]
      Zipper together two lists

  [Pairlis-x1]
      Cons a given element to each member of a list

  [Pairlis-x2]
      Cons each element of a list with a given element

  [Pos-listp]
      Recognizer for a true list of positive integers

  [Position]
      Position of an item in a string or a list

  [Proper-consp]
      Recognizer for proper ([47mnil[0m-terminated) non-empty lists

  [Rational-listp]
      Recognizer for a true list of rational numbers

  [Real-listp]
      ACL2(r) recognizer for a true list of real numbers

  [Remove]
      Remove all occurrences

  [Remove-duplicates]
      Remove duplicates from a string or a list

  [Remove1]
      Remove first occurrences, testing using [47m[eql][0m

  [Revappend]
      Concatenate the [reverse] of one list to another

  [Reverse]
      Reverse a list or string

  [Search]
      Search for a string or list in another string or list

  [Set-difference$]
      Elements of one list that are not elements of another

  [Standard-char-listp]
      Recognizer for a true list of standard characters

  [String-listp]
      Recognizer for a true list of strings

  [Subseq]
      Subsequence of a string or list

  [Subsetp]
      Test if every [47m[member][0m of one list is a [47m[member][0m of the other

  [Substitute]
      Substitute into a string or a list, using [47m[eql][0m as test

  [Symbol-listp]
      Recognizer for a true list of symbols

  [Take]
      Initial segment (first n elements) of a list

  [True-list-listp]
      Recognizer for true (proper) lists of true lists

  [True-listp]
      Recognizer for proper ([47mnil[0m-terminated) lists

  [Union$]
      A list that contains exactly the elements of the given lists

  [Update-nth]
      Modify a list by putting the given value at the given position")
 (LOCAL
  (EVENTS)
  "Hiding an event in an encapsulation or book

    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)

  where [47mev[0m is an event form.  If the current default [defun-mode] (see
  [default-defun-mode]) is [47m:[0m[47m[logic][0m and [47m[ld-skip-proofsp][0m is [47mnil[0m or
  [47mt[0m, then [47m(local ev)[0m is equivalent to [47mev[0m.  But if the current default
  [defun-mode] is [47m:[0m[47m[program][0m or if [47m[ld-skip-proofsp][0m is
  [47m'[0m[47m[include-book][0m, then [47m(local ev)[0m is a [47mno-op[0m.  Thus, if such forms
  are in the event list of an [47m[encapsulate][0m event or in a book, they
  are processed when the encapsulation or book is checked for
  admissibility in [47m:[0m[47m[logic][0m mode but are skipped when extending the
  host [world].  Such [events] are thus considered ``local'' to the
  verification of the encapsulation or book.  The non-local [events]
  are the ones ``exported'' by the encapsulation or book.  See
  [encapsulate] for a thorough discussion.  Also 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.

  Note that [events] that change the default [defun-mode], and in fact
  any [events] that set the [47m[ACL2-defaults-table][0m, are disallowed
  inside the scope of [47mlocal[0m.  See [embedded-event-form].")
 (LOCAL-INCOMPATIBILITY
  (MISCELLANEOUS)
  "When non-local [events] won't replay in isolation

  Sometimes a ``[47m[local][0m incompatibility'' is reported while attempting
  to embed some [events], as in an [47m[encapsulate][0m or [47m[include-book][0m.
  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
  [47m[local][0m.  (But see the Remark at the end of this topic about a
  related issue with guard-checking.)

  [47m[Local][0m incompatibilities may be detected while trying to execute the
  strictly non-[local] [events] of an [47m[encapsulate][0m or [47m[certify-book][0m
  call.  For example, [47mencapsulate[0m operates by first executing all the
  [events] (local and non-local) with [47m[ld-skip-proofsp][0m [47mnil[0m, 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 [events] with [47m[ld-skip-proofsp][0m set to [47m'include-book[0m.
  [47mCertify-book[0m does something similar, so that when [47m[include-book][0m
  assumes the non-local events in the book, we are confident that the
  previously successful certification has performed the necessary
  admissibility check.

  How can a sequence of [events] admitted with [47m[ld-skip-proofsp][0m [47mnil[0m
  fail when [47m[ld-skip-proofsp][0m is [47m'include-book[0m?  The key observation
  is that in the latter case only the non-local [events] are
  processed.  The [47m[local][0m ones are skipped and so the non-local ones
  must not depend upon them.

  Two typical mistakes are suggested by the detection of a [47m[local][0m
  incompatibility: (1) a locally defined function or macro was used
  in a non-[47m[local][0m event (and, in the case of [47m[encapsulate][0m, was not
  included among the [signature]s) and (2) the witnessing definition
  of a function that was included among the [signature]s of an
  [47m[encapsulate][0m was not made [47m[local][0m.

  An example of mistake (1) would be to include among your
  [encapsulate]d [events] both a local definition of [47mf[0m and a
  non-local theorem about [47mf[0m, for example as follows.

    (encapsulate ()
      (local (defun f (x) x))
      (defun g (x) x)

      (defthm f-is-g (equal (f x) (g x)))
      )

  In this case, either the [47m[defthm][0m should be made [47m[local][0m or, if we
  want to export the [47mdefthm[0m, then the [47m[defun][0m of [47mf[0m should be made
  non-local.  Similar analysis holds if the events in the [47mencapsulate[0m
  call above are instead in a book.

  An example of mistake (2) would be to include [47m((fn *) => *)[0m among
  your [signature]s and then to write [47m(defun fn (x) ...)[0m in your
  [events], instead of [47m(local (defun fn ...))[0m, as shown in the
  example below.  In essence, this is an error because [47mfn[0m is exported
  twice: once by the signature and once by the [47mdefun[0m.

    (encapsulate
      ( ((fn *) => *) )

      (defun fn (x) x)
      )

  One subtle aspect of [47m[encapsulate][0m 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.

  Errors due to [47m[local][0m incompatibility should never occur in the
  inclusion of a fully certified book.  Certification ensures against
  it.  Therefore, if [47m[include-book][0m reports an incompatibility, we
  claim that earlier in the processing of the [47m[include-book][0m a
  warning was printed advising you that some book was uncertified.
  If this is not the case --- if [47m[include-book][0m reports an
  incompatibility and there has been no prior warning about lack of
  certification --- please report it to the ACL2 implementors.

  When a [47m[local][0m incompatibility is detected during the second pass of
  an [47m[encapsulate][0m or [47m[certify-book][0m, the logical [world] is restored
  to what it was immediately before that call was evaluated.

  Note that for [47mcertify-book[0m, local incompatibility could be caused by
  an event that is local either in the certification world (see
  [portcullis]) or in the book itself.  ACL2 checks during
  [47mcertify-book[0m for local incompatibility by rolling back the world
  --- 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
  [47mencapsulate[0m, but see final Remark below) --- and then including the
  book.  But all that is skipped in the absence of either kind of
  local event.

  See [fast-cert] for a way to skip the local incompatibility check,
  although that may compromise soundness.

  Here is a subtle example of [47m[local][0m incompatibility.  The problem is
  that in order for [47mfoo-type-prescription[0m to be admitted using the
  specified [47m:typed-term[0m [47m(foo x)[0m, the conclusion [47m(my-natp (foo x))[0m
  depends on [47mmy-natp[0m being a [compound-recognizer].  This is fine on
  the first pass of the [47m[encapsulate][0m, during which lemma [47mmy-natp-cr[0m
  is admitted.  But [47mmy-natp-cr[0m is skipped on the second pass because
  it is marked [47m[local][0m, and this causes [47mfoo-type-prescription[0m to fail
  on the second pass.

    (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)))))

  [31;1mRemark[0m.  We conclude by remarking that for ``local incompatibility''
  in the case of [47mcertify-book[0m, the notion of ``local'' is a bit more
  comprehensive than the name suggests, in that it can involve
  [guard]-checking in the following situation.  For example, in a
  fresh ACL2 session evaluate the [command] [47m(set-guard-checking
  :none)[0m followed by [47m(table foo 0 (car 3))[0m.  Then any attempt to
  certify a book should fail, since subsequent inclusion of that book
  would fail with a [guard] violation; that's because the
  [47mset-guard-checking[0m call was not saved in the [certificate] file,
  hence was not evaluated when evaluating [47m(car 3)[0m while attempting to
  include the book.

  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 [command]s directly
  in the top-level read-eval-print loop.  One of those commands might
  be a call of [47m[set-guard-checking][0m that weakens guard-checking from
  its default behavior, i.e., [47m(set-guard-checking VAL)[0m where [47mVAL[0m is
  other than [47mt[0m, [47m:nowarn[0m, or [47m:all[0m.  This command does not change the
  logical [world], so it will not be part of the book's [portcullis]
  commands.  In that sense, it is like a [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.")
 (LOGAND
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical `and' of zero or more integers

  When integers are viewed in their two's complement representation,
  [47mlogand[0m returns their bitwise logical `and'.  In ACL2 [47mlogand[0m is a
  macro that expands into calls of the binary function [47mbinary-logand[0m,
  except that [47m(logand)[0m expands to [47m-1[0m and [47m(logand x)[0m expands to [47m(the
  integer x)[0m.

  The [guard] for [47mbinary-logand[0m requires its arguments to be integers.
  [47mLogand[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mMacro: [0m<logand>

    (defmacro logand (&rest args)
      (cond ((null args) -1)
            ((null (cdr args))
             (cons 'the
                   (cons 'integer (cons (car args) 'nil))))
            (t (xxxjoin 'binary-logand args))))

  [31;1mFunction: [0m<binary-logand>

    (defun binary-logand (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (cond ((zip i) 0)
            ((zip j) 0)
            ((eql i -1) j)
            ((eql j -1) i)
            (t (let ((x (* 2 (logand (floor i 2) (floor j 2)))))
                 (+ x
                    (cond ((evenp i) 0)
                          ((evenp j) 0)
                          (t 1)))))))")
 (LOGANDC1
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical `and' of two ints, complementing the first

  When integers are viewed in their two's complement representation,
  [47mlogandc1[0m returns the bitwise logical `and' of the second with the
  bitwise logical `not' of the first.

  The [guard] for [47mlogandc1[0m requires its arguments to be integers.
  [47mLogandc1[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<logandc1>

    (defun logandc1 (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (logand (lognot i) j))")
 (LOGANDC2
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical `and' of two ints, complementing the second

  When integers are viewed in their two's complement representation,
  [47mlogandc2[0m returns the bitwise logical `and' of the first with the
  bitwise logical `not' of the second.

  The [guard] for [47mlogandc2[0m requires its arguments to be integers.
  [47mLogandc2[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<logandc2>

    (defun logandc2 (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (logand i (lognot j)))")
 (LOGBITP
  (NUMBERS ACL2-BUILT-INS)
  "The [47mi[0mth bit of an integer

  For a nonnegative integer [47mi[0m and an integer [47mj[0m, [47m(logbitp i j)[0m is a
  Boolean, which is [47mt[0m if and only if the value of the [47mi[0mth bit is [47m1[0m in
  the two's complement representation of [47mj[0m.

  [47m(Logbitp i j)[0m has a [guard] that [47mi[0m is a nonnegative integer and [47mj[0m is
  an integer.

  [47mLogbitp[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<logbitp>

    (defun logbitp (i j)
      (declare (xargs :guard (and (integerp j)
                                  (integerp i)
                                  (>= i 0))))
      (oddp (floor (ifix j) (expt 2 (nfix i)))))")
 (LOGCOUNT
  (NUMBERS ACL2-BUILT-INS)
  "Number of ``on'' bits in a two's complement number

  [47m(Logcount x)[0m is the number of ``on'' bits in the two's complement
  representation of [47mx[0m.

  [47m(Logcount x)[0m has a [guard] of [47m(integerp x)[0m.

  [47mLogcount[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<logcount>

    (defun logcount (x)
      (declare (xargs :guard (integerp x)))
      (cond ((zip x) 0)
            ((< x 0) (logcount (lognot x)))
            ((evenp x)
             (logcount (nonnegative-integer-quotient x 2)))
            (t (1+ (logcount (nonnegative-integer-quotient x 2))))))")
 (LOGEQV
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical equivalence of zero or more integers

  When integers are viewed in their two's complement representation,
  [47mlogeqv[0m returns their bitwise logical equivalence.  In ACL2 [47mlogeqv[0m
  is a macro that expands into calls of the binary function
  [47mbinary-logeqv[0m, except that [47m(logeqv)[0m expands to [47m-1[0m and [47m(logeqv x)[0m
  expands to [47m(the integer x)[0m.

  The [guard] for [47mbinary-logeqv[0m requires its arguments to be integers.
  [47mLogeqv[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mMacro: [0m<logeqv>

    (defmacro logeqv (&rest args)
      (cond ((null args) -1)
            ((null (cdr args))
             (cons 'the
                   (cons 'integer (cons (car args) 'nil))))
            (t (xxxjoin 'binary-logeqv args))))

  [31;1mFunction: [0m<binary-logeqv>

    (defun binary-logeqv (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (logand (logorc1 i j) (logorc1 j i)))")
 (LOGIC
  (DEFUN-MODE)
  "To set the default [defun-mode] to [47m:logic[0m

    Example:
    ACL2 p!>:logic
    ACL2 !>

  Typing the keyword [47m:logic[0m sets the default [defun-mode] to [47m:logic[0m.

  Functions defined in [47m:logic[0m mode are logically defined.  See
  [defun-mode].

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

  See [defun-mode] for a discussion of the [defun-mode]s available and
  what their effects on the logic are.  See [default-defun-mode] for
  a discussion of how the default [defun-mode] is used.  This event
  is equivalent to [47m(table acl2-defaults-table :defun-mode :logic)[0m,
  and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs. See [ACL2-defaults-table].

  Recall that the top-level form [47m:logic[0m is equivalent to [47m(logic)[0m; see
  [keyword-commands].  Thus, to change the default [defun-mode] to
  [47m:logic[0m in a book, use [47m(logic)[0m, which is an embedded event form,
  rather than [47m:logic[0m, which is not a legal form for [books].  See
  [embedded-event-form].")
 (LOGIC-FNS-LIST-LISTP
  (TERMP ACL2-BUILT-INS)
  "Recognizer for when a given list of lists of [term]s calls only
  [47m:[0m[47m[logic][0m-mode function symbols

  For a list [47mx[0m of lists of [term]s in [world] [47mwrld[0m,
  [47m(logic-fns-list-listp x wrld)[0m is true if and only if every function
  symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in [47mwrld[0m.  Unlike
  [47m[logic-term-list-listp][0m, [47mlogic-fns-list-listp[0m does not check that [47mx[0m
  is a list of lists of terms; rather, [47mlogic-fns-list-listp[0m should
  only be applied to such lists.  See [47m[defun-mode-lambdas][0m for some
  clarifications of how [47m:program[0m mode functions are allowed in
  certain [47m:logic[0m mode terms.

  [31;1mFunction: [0m<logic-fns-list-listp>

    (defun logic-fns-list-listp (x wrld)
      (declare (xargs :guard (and (plist-worldp wrld)
                                  (pseudo-term-list-listp x))))
      (cond ((endp x) t)
            (t (and (logic-fns-listp (car x) wrld)
                    (logic-fns-list-listp (cdr x) wrld)))))")
 (LOGIC-FNS-LISTP
  (TERMP ACL2-BUILT-INS)
  "Recognizer for when a given list of [term]s calls only [47m:[0m[47m[logic][0m-mode
  function symbols

  For a list [47mx[0m of [term]s in [world] [47mwrld[0m, [47m(logic-fns-listp x wrld)[0m is
  true if and only if every function symbol called in [47mx[0m is in
  [47m:[0m[47m[logic][0m mode in [47mwrld[0m.  Unlike [47m[logic-term-listp][0m, [47mlogic-fns-listp[0m
  does not check that [47mx[0m is a list of terms; rather, [47mlogic-fns-listp[0m
  should only be applied to such lists.  See [47m[defun-mode-lambdas][0m for
  some clarifications of how [47m:program[0m mode functions are allowed in
  certain [47m:logic[0m mode terms.

  [31;1mFunction: [0m<logic-fns-listp>

    (defun logic-fns-listp (lst wrld)
      (declare (xargs :guard (and (plist-worldp wrld)
                                  (pseudo-term-listp lst))))
      (cond ((endp lst) t)
            (t (and (logic-fnsp (car lst) wrld)
                    (logic-fns-listp (cdr lst) wrld)))))")
 (LOGIC-FNSP
  (TERMP ACL2-BUILT-INS)
  "Recognizer for when a given [term] calls only [47m:[0m[47m[logic][0m-mode function
  symbols

  For a [term] [47mx[0m in [world] [47mwrld[0m, [47m(logic-fnsp x wrld)[0m is true if and
  only if every function symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in
  [47mwrld[0m.  Unlike [47m[logic-termp][0m, [47mlogic-fnsp[0m does not check that [47mx[0m is a
  term; rather, [47mlogic-fnsp[0m should only be applied to terms.  See
  [47m[defun-mode-lambdas][0m for some clarifications of how [47m:program[0m mode
  functions are allowed in certain [47m:logic[0m mode terms.

  [31;1mFunction: [0m<logic-fnsp>

    (defun logic-fnsp (term wrld)
      (declare (xargs :guard (and (plist-worldp wrld)
                                  (pseudo-termp term))))
      (cond ((variablep term) t)
            ((fquotep term) t)
            ((flambdap (ffn-symb term))
             (and (logic-fnsp (lambda-body (ffn-symb term))
                              wrld)
                  (logic-fns-listp (fargs term) wrld)))
            ((programp (ffn-symb term) wrld) nil)
            (t (logic-fns-listp (fargs term) wrld))))")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Background knowledge in ACL2 logic for theorem prover tutorial

  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.

  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 --- and for
  good reason.

  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 [3mvalid[0m: 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 [31;1monly[0m 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.

  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.

  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.

  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 [3mconvinced[0m that the
  formula holds for that case.

  Read this and follow the links to confirm that you understand what
  happens.  Be sure to then use your browser's [31;1mBack Button[0m to return
  to this page and continue.

  [31;1mAn Annotated Proof of[0m

    (implies (true-listp z)
             (equal (rev (rev z)) z))

  ``We will prove that reversing the reverse of a [47mtrue-listp[0m yields the
  original list.  The formula stating this is above.  We will prove
  it by induction (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INDUCTIVE-PROOF]) on the list
  structure of [47mz[0m.

  The base case (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-BASE-CASE]) of
  the induction is:

    (implies (endp z)
             (implies (true-listp z)
                      (equal (rev (rev z)) z))).

  This formula is equivalent, by propositional calculus (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]), to

    (implies (and (endp z)
                  (true-listp z))
             (equal (rev (rev z)) z))

  Rewriting (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING]) with
  the definition of [47mendp[0m produces:

    (implies (and (not (consp z))
                  (true-listp z))
             (equal (rev (rev z)) z))

  Rewriting repeatedly (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING-REPEATEDLY]) starting
  with the definition of [47mtrue-listp[0m produces:

    (implies (and (not (consp z))
                  (equal z nil))
             (equal (rev (rev z)) z))

  Then using the second [3mhypothesis[0m, just substituting equals for equals
  (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EQUALS-FOR-EQUALS]), we get

    (implies (and (not (consp z))
                  (equal z nil))
             (equal (rev (rev nil)) nil))

  Since the [3mconclusion[0m involves no variables, we can evaluate (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EVALUATION]) it, getting

    (implies (and (not (consp z))
                  (equal z nil))
             T)

  But this is an instance (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of the tautology (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS])
  [47m(implies p T)[0m.  Thus, the base case is proved.''

  Now it is time for a little quiz.  There are just three questions.

  [31;1mQ1[0m: The case above was the Base Case of an inductive proof of

    (implies (true-listp z)
             (equal (rev (rev z)) z))

  in which we did induction on the structure of the linear list [47mz[0m.
  What is the Induction Step?  That is, what do you have to prove
  besides the Base Case to complete this inductive proof?

  Below are four commonly given answers; choose one.  Then look here
  (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q1-ANSWER]) to find out if
  you're right.

    [3mInduction Step -- Choice (i)[0m:
    (implies (not (endp z))
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

    [3mInduction Step -- Choice (ii)[0m:
    (implies (true-listp (cdr z))
             (equal (rev (rev (cdr z))) (cdr z)))

    [3mInduction Step -- Choice (iii)[0m:
    (implies (and (not (endp z))
                  (equal (rev (rev (cdr x))) (cdr x)))
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

    [3mInduction Step -- Choice (iv)[0m:
    (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)))

  [31;1mQ2[0m: To prove the Induction Step we must prove one or more of the
  goals below.

  Which combinations are sufficient to imply the Induction Step?
  Decide what is required and then look here (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q2-ANSWER]) to find out if
  you're right.  To help you, the Induction Step is of the form:

    [3mInduction Step[0m:
    (implies (and [3mc[0m
                  (implies [3mp'[0m [3mq'[0m))
             (implies [3mp[0m [3mq[0m))

  and beside each candidate subgoal we show its structure in those
  terms.

    [3mSubgoal (i)[0m:
    (implies (and (not (endp z))                        ; (implies (and [3mc[0m
                  (true-listp z))                       ;               [3mp[0m)
             (true-listp (cdr z)))                      ;          [3mp'[0m)

    [3mSubgoal (ii)[0m:
    (implies (and (not (endp z))                        ; (implies (and [3mc[0m
                  (true-listp z)                        ;               [3mp[0m
                  (equal (rev (rev (cdr z))) (cdr z)))  ;               [3mq'[0m)
             (equal (rev (rev z)) z))                   ;          [3mq[0m)

    [3mSubgoal (iii)[0m:
    (implies (and (not (endp z))                        ; (implies (and [3mc[0m
                  (equal (rev (rev (cdr z))) (cdr z)))  ;               [3mq'[0m)
             (equal (rev (rev z)) z))                   ;          [3mq[0m)

    [3mSubgoal (iv)[0m:
    (implies (and (not (endp z))                        ; (implies (and [3mc[0m
                  (true-listp (cdr z))                  ;               [3mp'[0m
                  (equal (rev (rev (cdr z))) (cdr z)))  ;               [3mq'[0m)
             (equal (rev (rev z)) z))                   ;          [3mq[0m)

  [31;1mQ3[0m: Suppose you know the theorem

    [3mTheorem[0m:
    (implies (p (f x))
             (equal (g (h x))
                    x))

  and you wish to rewrite the target [47m(g (h a))[0m to [47ma[0m in

    [3mGoal Conjecture[0m:
    (implies (and (q (f a))
                  (r a))
             (s (g (h a))))

  What must you prove to relieve the hypothesis of [3mTheorem[0m?

  After you've thought about it, look here (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q3-ANSWER]) for our answer.

  [31;1mEnd of the Quiz[0m

  If this page made sense, you're ready to read the introduction to the
  theorem prover.

  If you are reading this as part of the tutorial introduction to the
  theorem prover, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-the-theorem-prover].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-BASE-CASE
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A brief explanation of base cases

  According to the sentence, the conjecture being proved is ``reversing
  the reverse of a [47mtrue-listp[0m yields the original list.'' The formula
  corresponding to this conjecture is:

    (implies (true-listp z)
             (equal (rev (rev z)) z)).

  We're also told that this is an inductive proof.  Evidently we're
  doing an induction on the structure of the list [47mz[0m.  Then the [3mBase
  Case[0m is the formula:

    (implies (endp z)
             (implies (true-listp z)
                      (equal (rev (rev z)) z))).

  Now use your browser's [31;1mBack Button[0m to return to the example proof in
  [logic-knowledge-taken-for-granted].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EQUALS-FOR-EQUALS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Substitution of equals for equals

  Anytime you have an equality hypothesis relating two terms, e.g.,

    (equal [3mlhs[0m [3mrhs[0m)

  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.

  You can use a [3mnegated equality[0m this way [3mprovided[0m it appears in the
  conclusion.  For example, it is ok to transform

    (implies (true-listp x)
             (not (equal x 23)))

  to

    (implies (true-listp 23)
             (not (equal x 23)))

  by substitutions of equals for equals.  That is because, by
  propositional calculus (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]), we
  could rearrange the formulas into their [3mcontrapositive[0m forms:

    (implies (equal x 23)
             (not (true-listp x)))

  and

    (implies (equal x 23)
             (not (true-listp 23)))

  and see the equality as a hypothesis and the substitution of [47m23[0m for [47mx[0m
  as sensible.

  Sometimes people speak loosely and say ``substitution of equals for
  equals'' when they really mean ``substitutions of equivalents for
  equivalents.'' Equality, as tested by [47mEQUAL[0m, is only one example of
  an equivalence relation.  The next most common is propositional
  equivalence, as tested by [47mIFF[0m.  You can use propositional
  equivalence hypotheses to substitute one side for the other
  [3mprovided[0m the target term occurs in a propositional place, as
  discussed at the bottom of propositional calculus (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]).

  Now use your browser's [31;1mBack Button[0m to return to the example proof in
  [logic-knowledge-taken-for-granted].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-EVALUATION
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Evaluation during proofs

  Any time you are proving a formula and see a subterm in the formula
  that contains no variables, you can just evaluate the subterm.

  This is familiar from algebra: It is not uncommon to rearrange a
  polynomial to collect all the constants and then add them up:

    (3x + 2 + 7y + 2)
    =
    (3x + 7y + (2 + 2))
    =
    (3x + 7y + 4).

  That last step is just evaluation.

  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 [3mnot[0m 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.

  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.

  Now use your browser's [31;1mBack Button[0m to return to the example proof in
  [logic-knowledge-taken-for-granted].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INDUCTIVE-PROOF
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A brief explanation of induction

  We start by showing classical induction on the natural numbers in an
  ACL2 setting before turning to a more general treatment of
  induction.

  [31;1mClassical Induction on Natural Numbers[0m: Induction is familiar in the
  arithmetic setting.  Let [47m(p n)[0m denote some formula involving the
  variable [47mn[0m (and perhaps some other variables which we don't
  exhibit).  Then to prove [47m(p n)[0m, for all [47mn[0m, by classical induction
  on the construction of the natural numbers, prove each of the
  following:

    [3mBase Case[0m:
    (implies (zp n) (p n))

    [3mInduction Step[0m:
    (implies (and (not (zp n))
                  (p (- n 1)))
             (p n))

  The Base Case establishes that [47mp[0m holds for [47m0[0m.  In fact, because of
  the definition of [47m[zp][0m {ICON} (see [A_Tiny_Warning_Sign]), it
  establishes that [47m(p n)[0m holds when [47mn[0m is [47m0[0m and it holds when [47mn[0m is not
  a natural number.

  The Induction Step establishes that if [47mn[0m is a natural number other
  than [47m0[0m, and if [47mp[0m holds for [47mn[0m-1, then [47mp[0m holds for [47mn[0m.  The hypothesis
  [47m(p (- n 1))[0m above is called the [3minduction hypothesis[0m.

  Note that if the Base Case and Induction Step are valid, then we know
  [47m(p n)[0m, for all [47mn[0m.  You can convince yourself of this by picking any
  object and asking ``how do I know [47mp[0m holds for this object?'' For
  example, [47m(p -7)[0m, [47m(p 'abc)[0m, and [47m(p 0)[0m are all established by the
  Base Case.  What about [47m(p 1)[0m?  That follows from [47m(p 0)[0m, given the
  Induction Step.  Why?  To prove [47m(p 1)[0m using the Induction Step, you
  have to establish [47m(not (zp 1))[0m, which is true, and [47m(p (- 1 1))[0m,
  which is [47m(p 0)[0m, which is true by the Base Case.  So [47m(p 1)[0m is true.
  Similar reasoning proves [47m(p 2)[0m from from [47m(p 1)[0m, etc.  Clearly, for
  every natural number other than [47m0[0m we could reason like this to show
  that [47mp[0m holds.  Since the Base Case handled all the objects that are
  not natural numbers, and handled [47m0[0m, we know [47m(p n)[0m, for all [47mn[0m.

  There is a duality between recursion and induction that ACL2
  exploits.  The fact that the Base and Induction steps above are
  sufficient to prove [47mp[0m for all objects is related to the fact that
  the following recursion defines a total, terminating function:

    (defun nat-recursion (n)
      (if (zp n)
          n
          (nat-recursion (- n 1))))

  When this function is admitted we have to prove that if [47m(zp n)[0m does
  not hold, then [47m(- n 1)[0m is smaller, in some sense, than [47mn[0m.  This
  sense of ``smaller'' is determined by some [3mmeasure[0m of the
  arguments.  That measure must return an ordinal (see [ordinals]
  {ICON} (see [A_Tiny_Warning_Sign])), 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 [47m(- n 1)[0m must be
  smaller than the measure of [47mn[0m, when the recursive branches are
  taken.  This sense of ``smaller'' must be [3mwell-founded[0m: 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 [47m[o<][0m {ICON} (see [A_Tiny_Warning_Sign])).  Well-foundedness
  means that eventually any recursion must ``bottom out'' because
  things can't keep getting smaller forever.

  The recursion in [47mnat-recursion[0m [31;1msuggests[0m the induction shown above:
  the Base Case is defined by the [47mif[0m 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., [47m(- n
  1)[0m.  The theorems proved when [47mnat-recursion[0m is introduced [3mjustify[0m
  the classical induction scheme noted above.

  Every recursively defined ACL2 function suggests a legal induction
  and vice versa.

  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.

  For example, it should be clear that [47m(nat-recursion a)[0m suggests a
  Base Case defined by [47m(zp a)[0m, and induction step defined by [47m(not (zp
  a))[0m and an induction hypothesis about [47m(- a 1)[0m.

  Note that the term [47m(fact n)[0m suggests the same classical induction on
  natural numbers shown above, where [47mfact[0m is defined as follows (even
  though we've used the formal parameter [47mk[0m below).

    (defun fact (k)
      (if (zp k)
          1
          (* k (fact (- k 1)))))

  The induction suggested by a term like [47m(fact n)[0m is insensitive to the
  name of the formal parameter used in the [47mdefun[0m.

  The induction suggested by a function or term is insensitive to the
  value returned by the function or term.

  It doesn't matter what the function returns in its ``base case''
  (e.g., [47m1[0m in [47mfact[0m) or what the function ``does'' to its recursive
  call (e.g., multiply by [47mk[0m in the [47mdefun[0m of [47mfact[0m).

  All that matters is (i) how the [47mif[0m structure breaks down the cases on
  [47mk[0m, (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.

  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.)  check this link (see
  [EXAMPLE-INDUCTIONS]).

  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.

  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.

  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.

  The main point of this discussion of induction is familiarize you
  with the basic terms: [3mBase Case[0m (of which there may be several),
  [3mInduction Step[0m (of which there may be several), [3mInduction
  Hypothesis[0m (of which there may be several in each Induction Step),
  [3mmeasure[0m and [3mwell-founded relation[0m [3mjustifying[0m an induction, and the
  induction [3msuggested[0m by a term or recursive function definition.
  Furthermore, every Induction Hypothesis is always an instance (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of the conjecture
  being proved: each induction hypothesis is obtained from the
  conjecture being proved by applying a [3msubstitution[0m replacing
  variables by terms.

  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 [31;1mBack Button[0m to return to the example
  proof in [logic-knowledge-taken-for-granted].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A brief explanation of substitution instances

  Let [3mp[0m and [3mq[0m be terms or formulas (there is no difference in ACL2).
  Then we say [3mp[0m is an [3minstance[0m or [3msubstitution instance[0m of [3mq[0m if and
  only if [3mp[0m can be obtained from [3mq[0m by uniformly replacing the
  variables of [3mq[0m by terms.  Sometimes we call [3mp[0m the [3mtarget[0m and [3mq[0m the
  [3mpattern[0m because by choosing appropriate replacements we can make
  the pattern [3mmatch[0m many different targets.

  For example, the following [3mtarget[0m is an instance of the given
  [3mpattern[0m:

    [3mtarget[0m:      (APP (APP (REV A) (REV B)) (REV C))
    [3mpattern[0m:     (APP (APP   x       y    ) (REV z))

  The replacement or [3msubstitution[0m used in this match of the pattern to
  the target is:

    [3mvariable in pattern[0m          [3mreplacement term[0m
    x                              (REV A)
    y                              (REV B)
    z                              C

  Such substitutions are usually written this way in ACL2:

    ((x  (REV A))
     (y  (REV B))
     (z  C)).

  Please use your browser's [31;1mBack Button[0m to return to the page that
  mentioned ``instance.''")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A brief explanation of propositional calculus

  It is impossible in this short introduction to teach you
  propositional calculus if you don't already know it!

  A typical use of propositional calculus is to observe that

    (implies (endp z)
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

  is equivalent to:

    (implies (and (endp z)
                  (true-listp z))
             (equal (rev (rev z)) z))

  If this is surprising and you know propositional calculus, then the
  problem might be our notation.  We're exploiting the tautology

    [3m(p ---> (q ---> r)) <---> ((p & q) ---> r)[0m

  where [3m--->[0m and [3m<--->[0m are meant to be the traditional arrows denoting
  logical implication and logical equivalence.

  If you don't know propositional calculus, we'll say just a few things
  to help ease your journey.

  A [3mpropositional formula[0m, in ACL2, is any formula written entirely in
  terms of variable symbols, [47mT[0m, [47mNIL[0m, and the propositional functions
  [47mAND[0m, [47mOR[0m, [47mNOT[0m, [47mIMPLIES[0m, and [47mIFF[0m.  The ``tautology'' above in
  traditional notation is this propositional formula in ACL2:

    (IFF (IMPLIES P (IMPLIES Q R))
         (IMPLIES (AND P Q) R)).

  If you have a formula like

    (implies [3mhyp[0m
             [3mconcl[0m)

  then we say that formula is an [3mimplication[0m, that [3mhyp[0m is the
  [3mhypothesis[0m, and that [3mconcl[0m is the conclusion.  If the hypothesis is
  an [47mand[0m expression, as in

    (implies (and [3mhyp1[0m
                  [3mhyp2[0m
                  ...)
             [3mconcl[0m)

  then we call [3mhyp1[0m is the [3mfirst hypothesis[0m, [3mhyp2[0m is the [3msecond
  hypothesis[0m, etc.

  If a term is of the form

    (and [3mterm1[0m [3mterm2[0m ...)

  we say it is a [3mconjunction[0m and that [3mterm1[0m is the [3mfirst conjunct[0m,
  [3mterm2[0m is the [3msecond conjunct[0m, etc.  We treat an [47mor[0m-term analogously
  but call it a [3mdisjunction[0m and its arguments are [3mdisjuncts[0m.

  A [3mtautology[0m 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 [3mtruth-table proof[0m below,
  but hasten to add that ACL2 does not generally use truth tables to
  recognize tautologies.  It primarily uses [normalization] and BDDs
  to recognize tautologies, which can be seen as a mix of symbolic
  manipulation and case analysis.

  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:

    [3mDouble Negation[0m:
    (iff (not (not p)) p)

    [3mDeMorgan[0m:
    (iff (not (and p q))
         (or (not p) (not q)))

    [3mDistributivity[0m:
    (iff (and p (or q r))
         (or (and p q)
             (and p r)))

    [3mPromotion[0m:
    (iff (implies p (implies q r))
         (implies (and p q) r))

    [3mImplicative Disjunction[0m:
    (iff (implies p q)
         (or (not p) q))

    [3mContrapositive[0m:
    (iff (implies p q)
         (implies (not q) (not p)))

    [3mGeneralized Contrapositive[0m:
    (iff (implies (and p r) q)
         (implies (and p (not q)) (not r)))

  There are, of course, many others, even with these same names!  For
  example, there is a dual version of DeMorgan showing how [47mnot[0m
  distributes over [47mor[0m, a dual version of Distributivity for [47mor[0m over
  [47mand[0m, etc.

  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 [3mwhy[0m
  ACL2 is working on a certain subgoal the reason can be traced back
  to propositional calculus.

  The most common example of this is that to prove a formula of the
  form

    (implies (implies p1 q1)
             (implies p2 q2))

  propositional calculus will convert it to

    (and (implies (and p2 (not p1)) q2)
         (implies (and p2 q1) q2))

  Many users are surprised that the first conjunct above does not have
  [47mq1[0m 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 [47m(implies p1 q1)[0m implies something, you must
  deal with the case that [47m(implies p1 q1)[0m is true because [47mp1[0m is
  false.  Think about it.

  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:

    (IFF (IMPLIES P (IMPLIES Q R))
         (IMPLIES (AND P Q) R))

  The formula above is a tautology.  It contains three variables, [47mP[0m, [47mQ[0m,
  and [47mR[0m, and so there are 8 combinations of Boolean assignments to
  them.  If we let

    [3mformula1[0m:  (IMPLIES P (IMPLIES Q R))
    [3mformula2[0m:  (IMPLIES (AND P Q) R)

  then we wish to test the formula [47m(IFF [0m[3mformula1 formula2[0m[47m)[0m:

    P   Q   R       [3mformula1[0m   [3mformula2[0m   (IFF [3mformula1[0m [3mformula2[0m)
    ---------
    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

  So we see that the formula always returns [47mT[0m and is thus a tautology.

  Recall that in the original example at the top of this page we were
  trying to prove the formula

    (implies (endp z)
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

  This formula is an instance (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of

    (implies p (implies q r)).

  The substitution required by the match is

    [3msigma[0m:
    ((p    (endp z))
     (q    (true-listp z))
     (r    (equal (rev (rev z)) z)))

  Since we know the tautology:

    (iff (implies p (implies q r))
         (implies (and p q) r)).

  is always true no matter what Boolean values [47mp[0m, [47mq[0m, and [47mr[0m have, then
  we know this instance of it (obtained by applying the substitution
  [3msigma[0m above) is always true:

    (iff (implies (endp z)                            [3mformula1'[0m
                  (implies (true-listp z)
                           (equal (rev (rev z)) z)))
         (implies (and (endp z)                       [3mformula2'[0m
                       (true-listp z))
                  (equal (rev (rev z)) z))).

  Thus, if we're trying to prove [3mformula1'[0m it is permitted to try to
  prove [3mformula2'[0m instead, because they return the same truthvalue.

  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 [47mnil[0m and any non-[47mnil[0m value,
  including [47mt[0m, 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
  [47mnil[0m or not.  When we prove a formula in ACL2 we are really
  establishing that it never returns [47mnil[0m, i.e., no matter what the
  values of the variables, the value of the formula is non-[47mnil[0m.

  A very simple example of this is with Double Negation.

    (iff (not (not p)) p)

  is a tautology.  This means that if we were trying to prove

    (implies (not (not p)) ...)

  we could transform it to

    (implies p ...).

  But if we were trying to prove:

    (equal (not (not p)) p)

  we could not prove it by using Double Negation!  The formula above
  claims that [47m(not (not p))[0m and [47mp[0m have identical values.  They do
  not!  For example, [47m(not (not 3))[0m is [47mt[0m, not [47m3[0m.  However, [47m(not (not
  3))[0m and [47mt[0m are propositionally equivalent (i.e., satisfy [47miff[0m)
  because one is as good as the other in a test.  [3mThat[0m is what Double
  Negation says.

  As long as you only use propositional formulas in propositional
  places this aspect of ACL2 should not affect you.

  Now please use your browser's [31;1mBack Button[0m to return to the example
  proof in [logic-knowledge-taken-for-granted].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q1-ANSWER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "The inductive step of the [47mrev-rev[0m proof --- Answer to Question 1

  The correct answer to Question 1 in
  [logic-knowledge-taken-for-granted] is [3mChoice (iv)[0m.

  The Induction Step of the inductive proof of

    (implies (true-listp z)
             (equal (rev (rev z)) z))

  for an induction on the linear list [47mz[0m is:

    [3mInduction Step[0m:
    (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)))

  The second hypothesis above is the [3minduction hypothesis[0m.  The
  conclusion above is the formula we are trying to prove.  Each
  induction hypothesis is [3malways[0m an instance (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) 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 [47mz[0ms have been replaced by
  [47m(cdr z)[0m.

  If you thought the right answer was

    [3mInduction Step -- Choice (i)[0m:
    (implies (not (endp z))
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

  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 [3mChoice (i)[0m above, then you will have proved the goal
  conjecture, but you would have done it by simple case analysis:
  prove it when [47m(endp z)[0m and prove it when [47m(not (endp z))[0m.  While
  logically valid, you probably can't prove [3mChoice (i)[0m directly
  because you have no induction hypothesis to work with.

  If you thought the right answer was:

    [3mInduction Step -- Choice (ii)[0m:
    (implies (true-listp (cdr z))
             (equal (rev (rev (cdr z))) (cdr z)))

  then perhaps you misunderstand the difference between the [3mInduction
  Step[0m and the [3mInduction Hypothesis[0m.  The Induction [3mStep[0m is the
  ``other half'' of the main proof, balancing the Base Case.  The
  Induction [3mHypothesis[0m is just a hypothesis you get to use during the
  Induction Step.  The question Q1 asked what is the Induction Step.

  If you thought the right answer was:

    [3mInduction Step -- Choice (iii)[0m:
    (implies (and (not (endp z))
                  (equal (rev (rev (cdr x))) (cdr x))) ; [3m``induction hyp''[0m
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

  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 [47m(rev (rev (cdr x)))[0m is [47m(cdr
  x)[0m, whereas the correct induction hypothesis says those two terms
  are equal [3mif[0m [47m(true-listp (cdr x))[0m.  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.

  If this doesn't make sense, perhaps you should read about induction
  (see [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INDUCTIVE-PROOF]) again.

  When you understand why [3mChoice (iv)[0m is the correct answer, use your
  browser's [31;1mBack Button[0m to return to
  [logic-knowledge-taken-for-granted] and go to question Q2.")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q2-ANSWER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2

  The correct answer to Question 2 in
  [logic-knowledge-taken-for-granted] is [3mSubgoal (i)[0m plus any one of
  the other other three.  For your reference, the four choices were:

    [3mSubgoal (i)[0m:
    (implies (and (not (endp z))
                  (true-listp z))
             (true-listp (cdr z)))

    [3mSubgoal (ii)[0m:
    (implies (and (not (endp z))
                  (true-listp z)
                  (equal (rev (rev (cdr z))) (cdr z)))
             (equal (rev (rev z)) z))

    [3mSubgoal (iii)[0m:
    (implies (and (not (endp z))
                  (equal (rev (rev (cdr z))) (cdr z)))
             (equal (rev (rev z)) z))

    [3mSubgoal (iv)[0m:
    (implies (and (not (endp z))
                  (true-listp (cdr z))
                  (equal (rev (rev (cdr z))) (cdr z)))
             (equal (rev (rev z)) z))

  In particular, it is wrong to think the Induction Step of the proof
  of

    (implies (true-listp z)
             (equal (rev (rev z)) z))

  can be established by proving just [3mSubgoal (ii)[0m, [3mSubgoal (iii)[0m,
  [3mSubgoal (iv)[0m, or combinations of those three.  You must also prove
  [3mSubgoal (i)[0m or something like it!

  The Inductive Step for the conjecture above is

    [3mInduction Step[0m:
    (implies (and (not (endp z))
                  ; [3mInduction Hypothesis[0m:
                  (implies (true-listp (cdr z))
                           (equal (rev (rev (cdr z))) (cdr z))))
             ; [3mInduction Conclusion[0m:
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

  Note that the Inductive Hypothesis is an implication:

    (implies (true-listp (cdr z))
             (equal (rev (rev (cdr z))) (cdr z)))

  This hypothesis can be true two different ways.  The ``normal'' way
  --- the way everybody remembers --- is that [47m(true-listp (cdr z))[0m is
  true and thus [47m(equal (rev (rev (cdr z))) (cdr z))[0m is true.  But the
  way many people forget is that [47m(true-listp (cdr z))[0m is false.  You
  must prove the Induction Step even in this ``forgettable'' case.

  In this case, the Induction Step simplifies to

    [3mInduction Step[0m:
    (implies (and (not (endp z))
                  (not (true-listp (cdr z))))
             (implies (true-listp z)
                      (equal (rev (rev z)) z)))

  By Promotion (see the list of tautologies in our discussion of
  propositional calculus (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS])) this
  is

    [3mInduction Step'[0m:
    (implies (and (not (endp z))
                  (not (true-listp (cdr z)))
                  (true-listp z))
             (equal (rev (rev z)) z))

  Using the Contrapositive and rearranging the order of the hypotheses
  (see propositional calculus (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]) again),
  this is

    [3mInduction Step''[0m:
    (implies (and (not (endp z))
                  (true-listp z)
                  (not (equal (rev (rev z)) z)))
             (true-listp (cdr z)))

  Notice that [3mSubgoal (i)[0m implies [3mInduction Step''[0m:

    [3mSubgoal (i)[0m:
    (implies (and (not (endp z))
                  (truelistp z))
             (truelistp (cdr z)))

  Every inductive proof of an implication raises a case like this.  If
  we denote the conjecture [47m(implies p q)[0m as [47mp ---> q[0m, then the
  Induction Step will look like this:

      ( c  &  (p'  --->  q'))
    --->
      (p ---> q)

  where [47mc[0m is the test that determines the inductive step, (e.g., [47m(not
  (endp z))[0m) and [47mp'[0m and [47mq'[0m are inductive instances of [47mp[0m and [47mq[0m.
  Promotion produces

      ( c  & p & (p'  --->  q'))
    --->
      q

  It is then very common to prove that [47mp[0m implies [47mp'[0m,

    [3m(i)[0m:
    (c & p) ---> p'

  and then prove that [47mq'[0m implies [47mq[0m,

    [3m(ii)[0m:
    (c & p & q') ---> q

  These correspond exactly to our choices [3mSubgoal (i)[0m and [3mSubgoal (ii)[0m.

  It is sometimes helpful to remember this diagram:

    (c  &  (p'  --->  q')
            ^         |
            |         |
            |         v
     -->   (p   --->  q )

  When you understand why [3mSubgoals (i)[0m and [3m(ii)[0m are sufficient, use
  your browser's [31;1mBack Button[0m to return to
  [logic-knowledge-taken-for-granted] and go to question Q3.")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-Q3-ANSWER
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "The inductive step of the [47mrev-rev[0m proof --- Answer to Question 2

  The correct answer to Question 3 in
  [logic-knowledge-taken-for-granted] is that you need to prove

    [3mSubgoal to Relieve Hyp 1[0m:
    (implies (and (q (f a))
                  (r a))
             (p (f a)))

  in order to use

    [3mTheorem[0m:
    (implies (p (f x))
             (equal (g (h x))
                    x))

  to rewrite the target [47m(g (h a))[0m to [47ma[0m in

    [3mGoal Conjecture[0m:
    (implies (and (q (f a))
                  (r a))
             (s (g (h a))))

  If you don't see why, re-read the discussion of rewriting (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING]) 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!

  Now use your browser's [31;1mBack Button[0m to return to the end of quiz in
  [logic-knowledge-taken-for-granted].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A brief explanation of rewriting from the logical perspective

  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.

  [31;1mExample 1[0m: Suppose your goal conjecture is:

    [3mGoal Conjecture[0m:
    (implies (and (endp z)
                  (true-listp z))
             (equal (rev (rev z)) z))

  Then you can use the following theorem (actually the definitional
  axiom introduced by the [47mdefun[0m of [47mendp[0m):

    [3mDefinitional Axiom[0m: endp
    (equal (endp x)
           (not (consp x))).

  to [3mrewrite[0m the [3mGoal Conjecture[0m to

    [3mRewritten Goal Conjecture[0m:
    (implies (and (not (consp z))
                  (true-listp z))
             (equal (rev (rev z)) z))

  Note that in this example, rewriting replaced the call of [47mendp[0m by its
  body after instantiating its body with the actuals from the call.
  This is sometimes just called [3mexpanding[0m the definition of [47mendp[0m.
  (The notions of [3mformal[0m, [3mbody[0m, [3mcall[0m, and [3mactuals[0m are discussed in
  [programming-knowledge-taken-for-granted].)

  Expanding a definition is an example of [3munconditional[0m 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

    (equal (append (append x y) z)
           (append x (append y z)))

  to replace an instance of one side by the corresponding instance of
  the other in a goal conjecture, we call that [3munconditional[0m
  rewriting with the equality.

  [31;1mExample 2[0m: Suppose your goal conjecture is:

    [3mGoal Conjecture[0m:
    (implies (and (subsetp a b)
                  (true-listp b)
                  (member e a))
             (< (len (rm e b)) (len b))).

  This conjecture may be read ``if [47ma[0m is a subset of the [47mtrue-listp[0m [47mb[0m
  and [47me[0m is a member of [47ma[0m, then the result of removing [47me[0m from [47mb[0m has a
  shorter length than [47mb[0m.''

  You can use the following theorem:

    [3mTheorem[0m:
    (implies (member u v)
             (equal (len (rm u v))
                    (- (len v) 1)))

  to [3mrewrite[0m the [3mGoal Conjecture[0m to

    [3mRewritten Goal Conjecture[0m:
    (implies (and (subsetp a b)
                  (true-listp b)
                  (member e a))
             (< (- (len b) 1) (len b))).

  To do this you must know that the following subgoal is provable:

    [3mSubgoal to Relieve Hyp 1[0m:
    (implies (and (subsetp a b)
                  (true-listp b)
                  (member e a))
             (member e b)).

  This is an example of [3mconditional[0m rewriting.  In order to use the
  [3mTheorem[0m we had to establish that its hypotheses are satisfied.
  That is called [3mrelieving the hypotheses[0m and was done by proving the
  [3mSubgoal to Relieve Hyp 1[0m.  Conditional rewriting is the most
  commonly used proof technique in ACL2.

  Unconditional rewriting is just a special case, where there are no
  hypotheses to relieve.

  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.

  This page discusses [3mrewriting[0m from the logical perspective.  It is
  important that you are familiar with the notions of a [3mtarget[0m term
  being an instance (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE]) of a [3mpattern[0m term.
  We often say the pattern [3mmatches[0m the target.  These notions involve
  a corresponding [3msubstitution[0m of terms for variables.  All these
  notions are discussed in the link for ``instance (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE])'' above and we
  recommend you read it before continuing.  Then use your browser's
  [31;1mBack Button[0m to come back here.

  You should also be aware of the terms introduced in our discussion of
  propositional calculus (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-PROPOSITIONAL-CALCULUS]).

  [3mRewriting[0m 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.

  Suppose you have a theorem that is of the form (or can be put into
  the form):

    [3mTheorem[0m:
    (implies (and [3mhyp1[0m
                  ...
                  [3mhypk[0m)
             (equal [3mpattern[0m
                    [3mreplacement[0m))

  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 [3mhypi[0m could just be [47mt[0m), or it could have been
  written in a different but equivalent propositional style, [47m(or (not[0m
  [3mhyp1[0m[47m) ...)[0m, or the equality could have been written the other way
  around, [47m(equal [0m[3mreplacement[0m [3mpattern[0m[47m)[0m.  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.

  Suppose some target term, [3mtarget[0m that occurs in your goal conjecture
  is an instance of [3mpattern[0m.  Let the corresponding substitution be
  [3msigma[0m.  If [3msigma[0m does not contain a binding for every variable that
  occurs in [3mTheorem[0m, then extend [3msigma[0m to [3msigma'[0m by adding one
  binding for each such variable.  (This is necessary only if [3mpattern[0m
  does not contain every variable in [3mTheorem[0m.)

  Let [3mreplacement'[0m be the result of instantiating [3mreplacement[0m with
  [3msigma'[0m.  Let [3mhypi'[0m be the result of instantiating [3mhypi[0m with [3msigma'[0m.

  Then the [31;1mRewrite Rule of Inference[0m tells us it is permitted to
  replace that occurrence of [3mtarget[0m in the goal by [3mreplacement'[0m ---
  [31;1mif you can prove[0m each [3mhypi'[0m in this context.  We make this last
  condition clear in a moment.

  The justification for this is that [3mTheorem[0m is true for all values of
  the variables.  Hence, it is true for the values specified by
  [3msigma'[0m.  If the [3mhypi'[0m are true, then the target is really equal to
  [3mreplacement'[0m.  But it is always permitted to replace something by
  something it's equal to.

  Rewriting thus involves several steps:

  (1) Finding a [3mtarget[0m and a [3mtheorem[0m to use to rewrite it to some more
  desirable [3mreplacement[0m.

  (2) Instantiating [3mpattern[0m in the (rearranged) theorem to match
  [3mtarget[0m.

  (3) Extending [3msigma[0m to [3msigma'[0m to bind all the variables in [3mTheorem[0m.

  (4) Establishing that the [3msigma'[0m instances of each of the [3mhypi[0m hold.
  This is called [3mrelieving the hypotheses[0m of the theorem and is
  discussed in greater detail below.

  (5) Replacing the occurrence of [3mtarget[0m in the goal conjecture by the
  [3msigma'[0m instance of [3mreplacement[0m, provided all the hypotheses are
  relieved.

  Step (4) above, [3mrelieving the hypotheses[0m, 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 [3mtarget[0m is in the conclusion and let [3mcontext[0m be the
  hypothesis.

    [3mRearranged Conjecture[0m:
    (implies [3mcontext[0m
             (... [3mtarget[0m ...))

  To relieve the hypotheses you must then prove each of the following
  subgoals:

    [3mSubgoal to Relieve Hyp i[0m:
    (implies [3mcontext[0m [3mhypi'[0m).

  It is important to note that this description of rewriting with
  [3mTheorem[0m 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 [3mTheorem[0m and can be used as
  described.  But in the actual implementation of ACL2, the syntactic
  form of a proved [3mTheorem[0m 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 [3mpattern[0m
  and the right-hand side as [3mreplacement[0m, unless you tell it
  otherwise.  We'll discuss this later.

  Furthermore, being from the logical perspective this discussion of
  rewriting does not address (a) how you extend [3msigma[0m to [3msigma'[0m ---
  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.

  Crucially, it does not discuss whether it is a [3mgood idea[0m to do a
  particular rewrite!  For example, the definitional equality:

    (equal (len x)
           (if (endp x)
               0
               (+ 1 (len (cdr x)))))

  may be used repeatedly, endlessly, to replace [47m(len a)[0m by an ever
  growing sequence of terms:

    (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)))))))
    = ...

  The ACL2 implementation of rewriting uses certain heuristics and you
  can guide the system in its choices.  We'll discuss this later.

  Now use your browser's [31;1mBack Button[0m to return to the example proof in
  [logic-knowledge-taken-for-granted].")
 (LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING-REPEATEDLY
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Further information on expanding definitions via rewriting

  We assume you've read about ``instances (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-INSTANCE])'' and picked up our
  basic terminology including the ideas of [3mmatching[0m a [3mpattern[0m term to
  a [3mtarget[0m term, obtaining a [3msubstitution[0m and how to [3minstantiate[0m a
  term with a substitution.  We use these notions below without
  further citation.

  In addition, we assume you've read about ``rewriting (see
  [LOGIC-KNOWLEDGE-TAKEN-FOR-GRANTED-REWRITING])'' where we
  introduced the idea of treating a theorem (axiom, definition, or
  lemma) as a [3mconditional rewrite[0m rule and replaced one term by an
  equivalent one provided we can [3mrelieve the hypotheses[0m.

  Suppose you're trying to prove [3mformula1[0m and you transform it to
  [3mformula2[0m by rewriting.  What happened?

    [3mformula1[0m:
    (implies (and (not (consp z))
                  (true-listp z))
             (equal (rev (rev z)) z))

    [3mformula2[0m:
    (implies (and (not (consp z))
                  (equal z nil))
             (equal (rev (rev z)) z))

  Evidently we replaced [47m(true-listp z)[0m by [47m(equal z nil)[0m.  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.

  The definition of [47mtrue-listp[0m is:

    (defun true-listp (x)
      (if (consp x)
          (true-listp (cdr x))
          (equal x nil))).

  By rewriting once with the definition of [47mtrue-listp[0m, we transform
  [3mformula1[0m to:

    [3mformula1'[0m:
    (implies (and (not (consp z))
                  (if (consp z)
                      (true-listp (cdr z))
                      (equal z nil)))
             (equal (rev (rev z)) z)).

  Note how the call of [47mtrue-listp[0m has been replaced by the entire body
  of [47mtrue-listp[0m.

  Next, note that the first hypothesis above is that [47m(consp z)[0m is
  false.  That is, [47m(not (consp z))[0m is the same as [47m(equal (consp z)
  nil)[0m.  Thus, replacement of equals by equals means we can transform
  [3mformula1'[0m to

    [3mformula1''[0m:
    (implies (and (not (consp z))
                  (if nil
                      (true-listp (cdr z))
                      (equal z nil)))
             (equal (rev (rev z)) z)).

  (We will explore replacement of equals by equals later.)

  Furthermore, we know the basic axiom about [47mif[0m:

    [3mAxiom[0m if-nil:
    (if nil x y) = y.

  Rewriting with this particular axiom, using [47m(if nil x y)[0m as the
  pattern and [47my[0m as the replacement, will transform [3mformula1''[0m to

    [3mformula2[0m:
    (implies (and (not (consp z))
                  (equal z nil))
             (equal (rev (rev z)) z)).

  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 [47m(consp z)[0m
  by [47mnil[0m, and we typically omit to mention the use of basic axioms
  like [47mif-nil[0m above.

  Now use your browser's [31;1mBack Button[0m to return to the example proof in
  [logic-knowledge-taken-for-granted].")
 (LOGIC-TERM-LIST-LISTP
  (TERMP ACL2-BUILT-INS)
  "Recognizer for lists of lists of [term]s that call only [47m:[0m[47m[logic][0m-mode
  function symbols

  This predicate strengthens [47m(term-list-listp x wrld)[0m, as it also
  requires [47m(logic-fns-list-listp x wrld)[0m, i.e., that every function
  symbol called in [47mx[0m is in [47m:[0m[47m[logic][0m mode in the [world], [47mwrld[0m.

  [31;1mFunction: [0m<logic-term-list-listp>

    (defun logic-term-list-listp (x w)
      (declare (xargs :guard (plist-worldp-with-formals w)))
      (and (term-list-listp x w)
           (logic-fns-list-listp x w)))")
 (LOGIC-TERM-LISTP
  (TERMP ACL2-BUILT-INS)
  "Recognizer for lists of [term]s that call only [47m:[0m[47m[logic][0m-mode function
  symbols

  This predicate strengthens [47m(term-listp x wrld)[0m, as it also requires
  [47m(logic-fns-listp x wrld)[0m, i.e., that every function symbol called
  in [47mx[0m is in [47m:[0m[47m[logic][0m mode in the [world], [47mwrld[0m.

  [31;1mFunction: [0m<logic-term-listp>

    (defun logic-term-listp (x w)
      (declare (xargs :guard (plist-worldp-with-formals w)))
      (and (term-listp x w)
           (logic-fns-listp x w)))")
 (LOGIC-TERMP
  (TERMP ACL2-BUILT-INS)
  "Recognizer for [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols

  This predicate strengthens [47m(termp x wrld)[0m, as it also requires
  [47m(logic-fnsp x wrld)[0m, i.e., that every function symbol called in [47mx[0m
  is in [47m:[0m[47m[logic][0m mode in the [world], [47mwrld[0m.

  [31;1mFunction: [0m<logic-termp>

    (defun logic-termp (x wrld)
      (declare (xargs :guard (plist-worldp-with-formals wrld)))
      (and (termp x wrld)
           (logic-fnsp x wrld)))")
 (LOGICAL-NAME
  (EVENTS WORLD)
  "A name created by a logical event

    Examples:
    assoc
    caddr
    +
    \"ACL2-USER\"
    :here

  A logical name is either a name introduced by some event, such as
  [47m[defun][0m, [47m[defthm][0m, or [47m[defpkg][0m, or else is the keyword [47m:here[0m, which
  refers to the most recent such event.  See [events].  Every logical
  name is either a symbol or a package name (a string).  For the
  syntactic rules on names, see [name].  The symbols name functions,
  macros, constants, axioms, theorems, labels, and [theories].  The
  strings name packages.  We permit the keyword symbol [47m:here[0m to be
  used as a logical name denoting the most recently completed event.

  Logical names are used primarily in the theory manipulation
  functions, e.g., [47m[universal-theory][0m and [47m[current-theory][0m with which
  you may obtain some standard [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 [events] it
  contains.  One might ask, ``Why not discuss the past with the much
  more flexible language of [command] descriptors?'' (See
  [command-descriptor].)  The reason is that inside of such [events]
  as [47m[encapsulate][0m or macro [command]s that expand to [47m[progn][0ms of
  [events], [command] descriptors provide too coarse a grain.

  When logical names are used as referents in theory expressions used
  in [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
  [redundant-events].")
 (LOGICP (POINTERS)
         "See [system-utilities].")
 (LOGIOR
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical inclusive or of zero or more integers

  When integers are viewed in their two's complement representation,
  [47mlogior[0m returns their bitwise logical inclusive or.  In ACL2 [47mlogior[0m
  is a macro that expands into calls of the binary function
  [47mbinary-logior[0m, except that [47m(logior)[0m expands to [47m0[0m and [47m(logior x)[0m
  expands to [47m(the integer x)[0m.

  The [guard] for [47mbinary-logior[0m requires its arguments to be integers.
  [47mLogior[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mMacro: [0m<logior>

    (defmacro logior (&rest args)
      (cond ((null args) 0)
            ((null (cdr args))
             (cons 'the
                   (cons 'integer (cons (car args) 'nil))))
            (t (xxxjoin 'binary-logior args))))

  [31;1mFunction: [0m<binary-logior>

    (defun binary-logior (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (lognot (logand (lognot i) (lognot j))))")
 (LOGNAND
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical `nand' of two integers

  When integers are viewed in their two's complement representation,
  [47mlognand[0m returns their bitwise logical `nand'.

  The [guard] for [47mlognand[0m requires its arguments to be integers.
  [47mLognand[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<lognand>

    (defun lognand (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (lognot (logand i j)))")
 (LOGNOR
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical `nor' of two integers

  When integers are viewed in their two's complement representation,
  [47mlognor[0m returns the bitwise logical `nor' of the first with the
  second.

  The [guard] for [47mlognor[0m requires its arguments to be integers.  [47mLognor[0m
  is defined in Common Lisp.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<lognor>

    (defun lognor (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (lognot (logior i j)))")
 (LOGNOT
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise not of a two's complement number

  [47m(lognot i)[0m is the two's complement bitwise [47m`not'[0m of the integer [47mi[0m.

  [47mLognot[0m is actually defined by coercing its argument to an integer
  (see [ifix]), negating the result, and then subtracting [47m1[0m.

  The [guard] for [47mlognot[0m requires its argument to be an integer.

  [47mLognot[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<lognot>

    (defun lognot (i)
      (declare (xargs :guard (integerp i)))
      (+ (- (ifix i)) -1))")
 (LOGORC1
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical inclusive or of two ints, complementing the first

  When integers are viewed in their two's complement representation,
  [47mlogorc1[0m returns the bitwise logical inclusive or of the second with
  the bitwise logical `not' of the first.

  The [guard] for [47mlogorc1[0m requires its arguments to be integers.
  [47mLogorc1[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<logorc1>

    (defun logorc1 (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (logior (lognot i) j))")
 (LOGORC2
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical inclusive or of two ints, complementing the second

  When integers are viewed in their two's complement representation,
  [47mlogorc2[0m returns the bitwise logical inclusive or of the first with
  the bitwise logical `not' of the second.

  The [guard] for [47mlogorc2[0m requires its arguments to be integers.
  [47mLogorc2[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<logorc2>

    (defun logorc2 (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (logior i (lognot j)))")
 (LOGTEST
  (NUMBERS ACL2-BUILT-INS)
  "Test if two integers share a `1' bit

  When integers [47mx[0m and [47my[0m are viewed in their two's complement
  representation, [47m(logtest x y)[0m is true if and only if there is some
  position for which both [47mx[0m and [47my[0m have a `1' bit in that position.

  The [guard] for [47mlogtest[0m requires its arguments to be integers.
  [47mLogtest[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<logtest>

    (defun logtest (x y)
      (declare (xargs :guard (and (integerp x) (integerp y))))
      (not (zerop (logand x y))))")
 (LOGXOR
  (NUMBERS ACL2-BUILT-INS)
  "Bitwise logical exclusive or of zero or more integers

  When integers are viewed in their two's complement representation,
  [47mlogxor[0m returns their bitwise logical exclusive or.  In ACL2 [47mlogxor[0m
  is a macro that expands into calls of the binary function
  [47mbinary-logxor[0m, except that [47m(logxor)[0m expands to [47m0[0m and [47m(logxor x)[0m
  expands to [47m(the integer x)[0m.

  The [guard] for [47mbinary-logxor[0m requires its arguments to be integers.
  [47mLogxor[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mMacro: [0m<logxor>

    (defmacro logxor (&rest args)
      (cond ((null args) 0)
            ((null (cdr args))
             (cons 'the
                   (cons 'integer (cons (car args) 'nil))))
            (t (xxxjoin 'binary-logxor args))))

  [31;1mFunction: [0m<binary-logxor>

    (defun binary-logxor (i j)
      (declare (xargs :guard (and (integerp i) (integerp j))))
      (lognot (logeqv i j)))")
 (LOOP$
  (ACL2-BUILT-INS PROGRAMMING)
  "Iteration with an analogue of the Common Lisp [47mloop[0m macro

  [47mLoop$[0m is the ACL2 analogue of the Common Lisp's iteration primitive,
  [47mloop[0m.  This topic introduces the two classes of ACL2 [47mloop$[0m
  expressions, [47mFOR[0m [47mloop$[0ms and [47mDO[0m [47mloop$[0ms; see [for-loop$] and
  [do-loop$] (respectively) for their full documentation.

  [47mLoop$[0m 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 [47mloop$[0m.  The [47mLoop$[0m Primer, 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 ``monkey-see monkey-do'' 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 [47mloop$[0m and ACL2 in general, you might want to work
  your way through the primer (see [loop$-primer]) instead of
  bouncing around the hypertext user's manual.

  The Introduction below is followed by a discussion of types and
  guards.  For a discussion of how to state effective lemmas about
  [47mloop$[0ms and how to prove inductive theorems about [47mloop$[0ms see
  [stating-and-proving-lemmas-about-loop$s].  Also, for a summary of
  how the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m [scion]s, see
  [rewriting-calls-of-apply$-ev$-and-loop$-scions].

  But before we get started we emphasize a few key points.

    * As noted, The Loop$ Primer (see [loop$-primer]) may be a good place
      to start if you're using ACL2 [47mloop$[0ms for the first time.

    * The Table of Contents of the Loop$ Primer (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 [47mLoop$[0m Primer Section 6 ([lp-section-6]) for some
      exercises on writing [47mloop$[0ms and, when you get to the end,
      ignore the ``Now go to [lp-section-7],'' and use your browser's
      Back key to return to the general hypertext user's manual.

    * [31;1mMany examples[0m of [47m[loop$][0m expressions may be found in [community-book]
      [47mprojects/apply/loop-tests.lisp[0m.

    * The semantics of [47mloop$[0m involve [47mapply$[0m.  Therefore, before using
      [47mloop$[0m, it is [31;1mstrongly recommended[0m that you include the same
      book as is typically included when using [47m[apply$][0m, as follows.

          (include-book \"projects/apply/top\" :dir :system)

    * ACL2 [47mloop$[0m statements are executed as Common Lisp [47mloop[0m statements
      after the relevant [guard] conjectures are proved.  Common Lisp
      [47mloop[0m statements generally execute much faster than equivalent
      (tail-recursive) functions.

    * [31;1mWarning:[0m [47mLoop$[0m implements only a modest part of the functionality of
      Common Lisp's [47mloop[0m.  Aside from the simple fact that [47mloop$[0m
      allows only a limited subset of the syntax of [47mloop[0m, the main
      restriction is that the subexpressions of the [47mloop$[0m expression
      that are evaluated repeatedly must be [tame]!  These
      expressions include not only the loop body but, if present, the
      [47mUNTIL[0m test, the [47mWHEN[0m test, and the [47mFINALLY[0m clause (all
      discussed below).  Thus, all the function symbols used in these
      expressions must be [badge]d (see [47m[defbadge][0m and [47m[defwarrant][0m).
      Further restrictions are enforced for [47m[defun][0m'd functions in
      which recursive calls appear in [47mloop$[0m bodies, but we say little
      about that in this documentation topic; see [loop$-recursion].
      We recommend that users unfamiliar with [47mloop$[0m acquaint
      themselves with the material below and in [for-loop$] before
      wading into [47mloop$-recursion[0m!


Introduction to [47mloop$[0m

  As noted above, there are two classes of [47mloop$[0m expressions.  These
  are identified as follows.

    * [47mFOR[0m loop$ expressions:

          (loop$ FOR ...)

    * [47mDO[0m loop$ expressions:

          (loop$ WITH ... DO ...)

  Below we introduce these two classes of [47mloop$[0m expressions.  For full
  documentation see the topic for each class: see [for-loop$] for [47mFOR[0m
  [47mloop$[0ms and [do-loop$] for [47mDO[0m [47mloop$[0ms.  In particular various
  restrictions are discussed in those topics, but for now we mention
  just the following.  While [47mFOR[0m [47mloop$[0m expressions are often more
  convenient to use than [47mDO[0m [47mloop$[0m expressions, their [47mUNTIL[0m, [47mWHEN[0m, and
  body expressions are not permitted to reference [47m[state][0m or
  [stobj]s, and they always return a single value.  [47mDO[0m [47mloop$[0m
  expressions do not have these restrictions, but they may not use
  the idioms of [47mFOR[0m [47mloop$[0ms, like ``[47mFOR x IN ...[0m'' or ``[47mUNTIL p[0m''.

  ACL2's [47mloop$[0m is considerably more restrictive than Common Lisp's
  [47mloop[0m, but when an ACL2 [47mloop$[0m expression is translated without error
  it has the same meaning as the corresponding Common Lisp [47mloop[0m.
  [47mLoop$[0m supports [47m:[0m[47m[guard][0m expressions (discussed below) in certain
  places and these are ignored by Common Lisp.

  Next we present some [47mFOR[0m [47mloop$[0m examples.  They illustrate the three
  supported forms of [47mFOR[0m [47mloop$[0m iteration: the use of [47mIN[0m, to iterate
  over elements of a list; the use of [47mON[0m, to iterate over the
  non-empty tails of a list; and the use of [47mFROM .. TO[0m, to iterate
  over a range of integers (optionally with [47mBY[0m to specify the
  increment at each step).  These examples also illustrate the use of
  [47mWHEN[0m to restrict which iterations are considered and the use of
  [47mUNTIL[0m to terminate early.  Additional keywords illustrated are
  [47mOF-TYPE[0m to specify types and [47mAS[0m to specify additional iteration
  variables.  They also illustrate some of the operations permitted
  at each iteration, such as [47mSUM[0m and [47mCOLLECT[0m.

    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))

  Finally we present two [47mDO[0m [47mloop$[0m examples.  We explore them further in
  the documentation specific to [47mDO[0m [47mloop$[0m expressions; see [do-loop$].

  Our first [47mDO[0m [47mloop$[0m example shows iteration with the indicated initial
  values for local variables [47mx[0m and [47my[0m.  They are modified at each
  iteration through the loop until [47mx[0m is empty, at which point the
  value of [47my[0m is returned.  (See [do-loop$] for more thorough
  explanations.)

    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 !>

  Our second example of a [47mDO[0m [47mloop$[0m expression illustrates more features
  than the first.  Also, it illustrates the use of a [47mloop$[0m expression
  inside a definition, which is allowed for both [47mFOR[0m [47mloop$[0ms and [47mDO[0m
  [47mloop$[0ms.  We see here that [stobj]s and [multiple-value] returns are
  allowed for [47mDO[0m [47mloop$[0ms, where the [47m:VALUES[0m keyword specifies the
  shape of the return.  We also see here the use of the optional
  [47m:GUARD[0m keyword of a [47mloop$[0m expression (legal for both classes of
  [47mloop$[0ms, as discussed further below) and the optional [47m:MEASURE[0m
  keyword of a [47mDO[0m [47mloop$[0m expression.

  But notice the [47m[defwarrant][0m events below!  They are required because
  the functions [47mfld[0m and [47mupdate-fld[0m are not system primitives.  They
  are introduced by the user's [47m[defstobj][0m event below.  This is in
  contrast to the [47mDO[0m [47mloop$[0m in our first example above where no
  warrants are required because all the functions in that example are
  primitive.

  The semantics of [47mloop$[0m involve [47mapply$[0m and thus [47mloop$[0ms inherit the
  restrictions imposed on [47mapply$[0m and its [scion]s.  Among those
  restrictions are that (a) unwarranted [47m:logic[0m mode functions cannot
  be [47mapply$[0m'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 [47m:logic[0m mode [47mloop$[0m
  containing unwarranted functions.  Restriction (b) means you can't
  verify the [guard]s of such [47mloop$[0m.  This last point obviates the
  main reason for using [47mloop$[0m: its fast execution as a Common Lisp
  loop once guards are verified.

  Now here is our second example.

    (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 !>

  Both classes of [47mloop$[0m expressions ([47mFOR[0m and [47mDO[0m [47mloop$[0ms) rely heavily on
  the ACL2 built-in function, [47m[apply$][0m: in each iteration through the
  loop, a [lambda] object based on the body of the [47mloop$[0m is given as
  the function argument of [47mapply$[0m.  Similarly, the [47mUNTIL[0m and [47mWHEN[0m
  clauses of [47mFOR[0m [47mloop$[0ms and the [47m:measure[0m and [47mFINALLY[0m clauses of [47mDO[0m
  [47mloop$[0ms are translated into [47mlambda[0m objects.  The functions in all
  those [47mlambda[0m objects must be warranted to evaluate the [47mloop$[0m and/or
  prove its properties (including its guards) because logically the
  application of an unwarranted function is undefined.  (However,
  recall from [guarantees-of-the-top-level-loop] that [47m:program[0m mode
  functions do not need warrants, just badges, for execution in the
  evaluation theory.)

  The documentation for [47m[apply$][0m illustrates a simple [47mdefun[0m 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 [47mloop$[0m whose body involves a user-defined function.  For a
  simple example of this issue and how to work around it, see
  [community-book] [47mbooks/demos/measure-and-warrant.lisp[0m.


Types and guards in [47mloop$[0m expressions

  In this section we document basic aspects of the [47mOF-TYPE[0m and [47m:GUARD[0m
  keywords in [47m[loop$][0m expressions.  See [for-loop$] and [do-loop$]
  for detailed documentation on guards for [47mFOR[0m and [47mDO[0m [47mloop$[0m
  expressions, respectively.

  [47mLoop$[0m expressions execute fastest when they are [guard] verified.
  But the [47mloop$[0m body raises interesting guard verification problems,
  as do the [47mUNTIL[0m and [47mWHEN[0m tests of a [47mFOR[0m [47mloop$[0m, because they are
  executed for many different values of the iteration variables.  The
  [47mFINALLY[0m clause of a [47mDO[0m [47mloop$[0m raises a similar concern, since the
  values of its variables may be modified repeatedly by execution of
  the [47mloop$[0m body.  It may be necessary to provide type information or
  even stronger invariants to verify guards for [47mloop$[0ms.  We now
  provide a few examples illustrating the handling of guards in
  [47mloop$[0m.

  The first example below is an acceptable [47mloop$[0m expression but cannot
  be guard verified, as would be necessary if it appeared in a
  [47m[defun][0m that was to be guard verified.  The problem is that [47m(+ 1 x)[0m
  requires [47mx[0m to be numeric and, in general, we don't know anything
  about the value of [47mx[0m here.  (Actually, because the target range is
  just a constant below, ACL2 could deduce information about each
  value [47mx[0m 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 [47m(+ 1 x)[0m.  The third example
  can also be guard verified but since the [47m:GUARD[0m 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
  [47mloop$[0m: the [47m:GUARD[0m directive protecting, in this case, the [47mloop$[0m
  body.  [47m:GUARD[0m is useful when you wish to add more guard information
  than can be expressed with the Common Lisp [47mOF-TYPE[0m directive.  The
  [47mOF-TYPE[0m and [47m:GUARD[0m directives are conjoined to form the actual
  guard protecting the [47mloop$[0m body.

    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)

  The guard on the [47m(- max x)[0m above is [47m(and (integerp x) (integerp max)
  (< x max))[0m and the compiler is informed that [47mx[0m is an integer by the
  [47mOF-TYPE[0m.

  The examples just above are of [47mFOR[0m [47mloop$[0ms.  Here is a [47mDO[0m [47mloop$[0m
  example that illustrates types and guards.

    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 !>

  Neither [47m:GUARD[0m is necessary in order for this execution to complete.
  However, if this [47mloop$[0m is put into a definition --- [47m(defun foo ()
  (loop$ ...))[0m --- then both [47m:GUARD[0m expressions are necessary in
  order for the definition to be [guard]-verified.

  As suggested above, when a [47mloop$[0m expression occurs in the body of a
  [guard]-verified function, it will be executed as a Common Lisp
  [47mloop[0m expression, which can be much more efficient than executing
  without such guard verification.  This efficiency can also be
  gained in top-level [47mloop$[0m expressions if the [tau-system] completes
  (silently) the necessary guard verification.  See [print-cl-cache].


Subtopics

  [Do$]
      Definition of [47mdo$[0m

  [Do-loop$]
      Iteration with [47m[loop$][0m using local variables and [stobj]s

  [For-loop$]
      Iteration with [47m[loop$][0m over an interval of integers or a list

  [Loop$-primer]
      Primer for using [47m[loop$][0m

  [Loop$-recursion]
      Defining functions that recur from within [47mFOR[0m [47mloop$[0m expressions

  [Loop$-recursion-induction]
      Advice on inductive theorems about [47m[loop$][0m-recursive functions

  [Stating-and-proving-lemmas-about-loop$s]
      Stating and proving theorems about [47mloop$[0ms")
 (LOOP$-DO (POINTERS) "See [do-loop$].")
 (LOOP$-FOR (POINTERS)
            "See [for-loop$].")
 (LOOP$-PRIMER
  (LOOP$ DOCUMENTATION PROGRAMMING)
  "Primer for using [47m[loop$][0m


The Loop$ Primer


Preface

  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.

  The ACL2 [47m[loop$][0m feature is an iteration primitive modeled on a small
  subset of the Common Lisp [47mloop[0m facility.  This documentation is an
  elementary introduction to [47mloop$[0m for use in both programming and
  proofs.  We assume the reader is already an experienced ACL2 user
  who is just new to [47mloop$[0m.

  [47mLoop$[0m exploits ACL2's ``higher order'' capability using [47m[apply$][0m.
  Logically, [47mloop$[0m expressions are translated into calls of [scion]s
  or ``mapping functions'' that map one or more [47m[lambda][0m objects over
  ranges.  When [47mloop$[0m expressions are typed into the ACL2 top-level
  loop these formal semantics are executed, which can be inefficient.
  When [47mloop$[0m expressions are in [guard] verified (see
  [47m[verify-guards][0m) functions they are compiled into Common Lisp [47mloop[0m
  expressions and are executed very efficiently.

  Two issues complicate the situation.  First, Common Lisp's [47mloop[0m
  facility is extraordinarily complex, requiring a full chapter of
  the reference manual to explain.  See {loop |
  http://www.lispworks.com/documentation/HyperSpec/Body/m_loop.htm#loop}
  in the Common Lisp HyperSpec or Chapter 26 (pages 709-747) of Guy
  Steele's monumental [31;1mCommon Lisp The Language, Second Edition[0m.
  Second, ACL2's logic is first-order, not higher-order, and so the
  [47mapply$[0m-based semantics imposes restrictions that new users of ACL2
  may find hard to deal with.

  This primer focuses on how to write [47mloop$[0m 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 ``[47mFOR[0m'' [47mloop$[0m and later move on to the ``[47mDO[0m'' [47mloop$[0m.  We
  follow the ``monkey see, monkey do'' 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.

  There are two glaring omissions in this primer: [guard] verification
  and the use of [stobj]s in [47mDO[0m [47mloop$[0m.

  While guard verification is crucial to the efficient execution of
  [47mloop$[0ms by Common Lisp, we omitted much discussion of it because
  guard obligations are generated automatically and are generally
  just ``ordinary'' conjectures that we assume the experienced user
  can figure out how to prove.  The newcomer to [47mloop$[0m may wonder
  ``why am I having to prove this?'' but the answer is always the
  same: ``the Common Lisp compiler requires this in order for [47mloop$[0m
  to behave like [47mloop[0m.'' Often the ``fix'' to a [47mloop$[0m guard
  verification problem is to add a [47m:guard[0m to the [47mloop$[0m body,
  remembering that it is translated into a [47mlambda[0m object that must be
  guard verified in isolation since it might be passed around and
  applied in many contexts.  We include the syntax for [47mloop$[0m guards.

  We omitted much discussion of stobjs --- which are allowed in [47mDO[0m
  [47mloop$[0ms but not in other kinds of [47mloop$[0ms --- because they raise the
  same problems in [47mDO[0m [47mloop$[0ms as they do in ``ordinary'' uses:
  syntactic single-threadedness into, through, and out of
  expressions.  We assume the experienced user knows how to deal with
  these issues.

  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!

  The primer is divided into subjects listed in the Table of Contents
  which is at the link [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.

  Now go to [lp-section-1].  The Table of Contents is at
  [lp-section-0].


Subtopics

  [Lp-section-0]
      Loop$ Primer Table of Contents)

  [Lp-section-1]
      Background Reviews

  [Lp-section-2]
      [47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2

  [Lp-section-3]
      Examples of [47mFOR[0m [47mLoop$[0ms

  [Lp-section-4]
      Syntax of [47mFOR[0m [47mLoop$[0ms

  [Lp-section-5]
      Informal Semantics of [47mFOR[0m [47mLoop$[0ms

  [Lp-section-6]
      Challenge Problems about [47mFOR[0m [47mLoop$[0ms

  [Lp-section-7]
      Using [47mLoop$[0ms and Guards in [47mDefun[0ms

  [Lp-section-8]
      Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms

  [Lp-section-9]
      Semantics of [47mFOR[0m [47mLoop$[0ms

  [Lp-section-10]
      The Evaluation of the Formal Semantics of a Fancy [47mLoop$[0m

  [Lp-section-11]
      Proving Theorems about [47mFOR[0m [47mLoop$[0ms

  [Lp-section-12]
      Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms

  [Lp-section-13]
      Examples of [47mDO[0m [47mLoop$[0ms

  [Lp-section-14]
      Challenge Problems about [47mDO[0m [47mLoop$[0ms

  [Lp-section-15]
      Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms

  [Lp-section-16]
      Proving Theorems about [47mDO[0m [47mLoop$[0ms

  [Lp-section-17]
      Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms

  [Lp-section-18]
      Conclusion")
 (LOOP$-RECURSION
  (LOOP$)
  "Defining functions that recur from within [47mFOR[0m [47mloop$[0m expressions


Examples

    (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))))))

  Notice that [47mnat-treep[0m and [47mcopy-nat-tree[0m each contain a simple [47mFOR[0m
  [47m[loop$][0m (also see [for-loop$]) in which the function being defined
  is called recursively.  [47mCopy-nat-tree[0m is a little more complicated
  than [47mnat-treep[0m because [47mcopy-nat-tree[0m also contains a recursive call
  outside of any [47mloop$[0m.  Notice also that both events specify the
  [47m[xargs][0m [47m:loop$-recursion t[0m and explicitly provide a [47m:measure[0m.  The
  usual other [47mxargs[0m are optional but [47m:loop$-recursion t[0m is required
  if recursion is used inside a [47mFOR[0m [47mloop$[0m and the measure must be
  made explicit.

  Recursion is not allowed inside a [47mDO[0m [47mloop$[0m expression.  In fact, ACL2
  disallows the use of [47m:loop$-recursion[0m in the [47mxargs[0m of any
  definition whose body contains a [47mDO[0m [47mloop$[0m.  So this topic is only
  about [47mFOR[0m [47mloop$[0ms.

  Some examples of [47mloop$[0m-recursive definitions may be found in the book
  [47mprojects/apply/loop-recursion-examples.lisp[0m.

  [31;1mWarning:[0m We advise you to use [47m[defun$][0m rather than [47m[defun][0m when
  introducing a [47m:logic[0m mode [47mloop$[0m-recursive function.  When a
  [47mloop$[0m-recursive function is introduced it is assigned a badge.
  This is required because we cannot translate the body of a
  [47mloop$[0m-recursive function without a badge.  However, no warrant is
  assigned by [47mdefun[0m.  But it is impossible to reason about
  applications (with [47m[apply$][0m) of unwarranted functions.  Indeed, it
  is even impossible to execute such applications in the top-level
  ACL2 read-eval-print loop.  See [guarantees-of-the-top-level-loop].
  So a [47m:logic[0m mode [47mloop$[0m-recursive function --- which is guaranteed
  to involve applications of itself with [47mapply$[0m --- can't be reasoned
  about or executed (except on data not exercising the recursive
  calls inside [47mloop$[0ms).  These inconveniences can be avoided by using
  [47mdefun$[0m when introducing [47m:logic[0m mode [47mloop$[0m-recursive functions
  because [47mdefun$[0m expands to a [47mdefun[0m followed by a [47m[defwarrant][0m.

  [31;1mWarning:[0m Even though the functions defined above are recursive, ACL2
  does not generate induction schemes for them!  If you want to do
  inductive proofs about [47mloop$[0m-recursive functions you must provide a
  suitable [47m:induction[0m hint.  In addition, to be provable by
  induction, theorems about [47mloop$[0m-recursive functions must be
  suitably general.  This topic is discussed further in
  [loop$-recursion-induction].


Restrictions

  If a function being defined exhibits recursion from within a [47m[loop$][0m
  body or within the [47mWHEN[0m or [47mUNTIL[0m clauses of a [47mloop$[0m in a [47m[defun][0m of
  [3mfn[0m, then the [47mdefun[0m must include an [47m[xargs][0m declaration with
  [47m:loop$-recursion t[0m.  In addition,

    * the [47mxargs[0m declaration must include an explicit [47m:measure[0m,

    * [3mfn[0m must not be part of a [47m[mutual-recursion][0m clique,

    * every formal of [3mfn[0m must be ``ordinary,'' e.g., not of [47m[ilk][0m [47m:FN[0m or
      [47m:EXPR[0m,

    * [3mfn[0m must return a single value,

    * [3mfn[0m's measure must be of type [47m[natp][0m or be a lexicographic combination
      of natural numbers as defined by the [47mllist[0m function in the
      Community Books at [47mbooks/ordinals/[0m,

    * [3mfn[0m must be [47m[tame][0m, which implies it may not take or return [47m[state][0m or
      [47m[stobj][0ms,

    * every quoted [47m[lambda][0m object in the body of [3mfn[0m must be well-formed
      (see [47m[well-formed-lambda-objectp][0m), which implies that every
      such [47mlambda[0m object is tame and every function symbol, including
      [3mfn[0m, used in each must have a [47m[badge][0m,

    * every quoted [47mlambda[0m object in the body of [3mfn[0m that calls [3mfn[0m
      recursively must occur as the first argument of a [47mloop$[0m scion
      and [3mnot[0m in some arbitrary scion,

    * there is at least one recursive call of [3mfn[0m inside a quoted [47mlambda[0m
      object which means that the [47mloop$-recursion t[0m declaration was
      actually necessary, and

    * the necessary measure conjectures (see below) must be proved.

  These restrictions make a little more sense if you reflect on what
  has to be done to check and admit a [47mloop$[0m-recursive function.
  First, we assume that most ACL2 functions are not [47mloop$[0m-recursive.
  So to keep [47mdefun[0m-processing as fast as possible, we require you to
  declare when you are using [47mloop$[0m recursion.  That declaration
  triggers additional checks.

  But before checks can begin, we have to translate the body of [3mfn[0m and
  since [47mloop$[0ms translate into calls of [47mloop$[0m scions on quoted [47mlambda[0ms
  and those must be tame, and since some of those [47mlambda[0ms involve
  calls of [3mfn[0m, we must assign a badge to [3mfn[0m even before we have
  translated its body.  We assign a badge that declares [3mfn[0m to take
  the appropriate number of ordinary inputs, to return one result,
  and be tame.  We check those requirements after [3mfn[0m has been
  admitted.

  Because the measure guessing heuristics of ACL2 do not look for calls
  inside of quoted [47mlambda[0ms, the measure must be explicitly declared
  even if it [47macl2-count[0m.

  To find every recursive call in a quoted [47mlambda[0m object those objects
  must all be well-formed.  If such an object occurs as the first
  argument of a [47mloop$[0m scion then we know it is only applied to
  elements of the [47mloop$[0m scion's target.  Given that, we can
  investigate whether the recursive calls in the [47mlambda[0m object are on
  smaller things.  But if a recursive call were to occur in a quoted
  [47mlambda[0m 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.

  Some of these restrictions could be lifted with more analysis and
  coding.  For example, we could change the specification for the
  [47m:loop$-recursion[0m [47mxargs[0m keyword so that instead of taking on a
  Boolean value it takes on a badge.  Then we could tentatively
  assign that badge to [3mfn[0m before processing and check it afterwards.
  Our current thinking is to ask users to live with these
  restrictions and let us see whether [47mloop$[0m-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.


Measure Conjectures

  Measure conjectures must be generated for the recursive calls inside
  [47mloop$[0m bodies.  (We also generate conjectures for the recursive
  calls the other [47mloop$[0m-expression components, e.g., the [47mWHEN[0m clause,
  exactly analogously, but we speak of the [47mloop$[0m body only below.  We
  also focus on simple [47mloop$[0ms here but the conjectures described
  generalize to fancy [47mloop$[0ms.)  Given a recursive call inside the
  body of a [47mloop$[0m with iteration variable [3mv[0m, we first generate a new
  variable symbol, [3mv'[0m.  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 [3mv[0m to [3mv'[0m in these terms to
  distinguish occurrences of [3mv[0m outside the [47mloop$[0m 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
  [47mloop$[0m, conjoined with the hypothesis that [3mv'[0m is a member of the
  target, conjoined with the (renamed) tests from inside the body
  ruling the recursive call.

  Below is an example.  We show only the measure conjectures generated
  from inside the [47mloop$[0m because there are two recursive calls in the
  [47mloop$[0m body.

    (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 ...)))

  Note that [47mv[0m used both as the formal of [47mfn[0m and as the iterative
  variable of the [47mloop$[0m.  In the measure conjectures below, the
  iterative variable has been renamed to [47mnv0[0m.  Two measure
  conjectures are generated from within the [47mloop$[0m:

    (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)))

  Note that these conjectures require that when [47mfn[0m is called from
  within the [47mloop$[0m the argument is smaller than the initial value of
  the formal.  Notice also that there is no [3ma priori[0m restriction on
  the size of [47m(target v)[0m.  However, because of the way [47mfn[0m is used
  inside this particular example [47mloop$[0m, there are restrictions on the
  size of the elements of [47m(target v)[0m.  These conjectures, along with
  those generated from calls outside the [47mloop$[0m are sufficient to
  guarantee that [47mfn[0m always terminates.

  [31;1mNote:[0m Careful readers might note that the way we handle measure
  conjectures for [47mloop$[0ms differs from the way we handle guard
  conjectures for [47mloop$[0ms.  In [47m[loop$][0m we explained that [47mloop$[0ms are
  translated into calls of [47mloop$[0m [47m[scion][0ms on quoted [47m[lambda][0m objects
  and that the guard conjectures for the [47mlambda[0m are insensitive to
  the context in which the object appeared.  But the measure
  conjectures are sensitive to the context: tests from outside the
  [47mloop$[0m are present in the measure conjectures.  This is deliberate.
  Guard conjectures are context insensitive because the
  implementation caches compiled [47mlambda[0m objects without remembering
  the contexts in which they first occurred.  Thus, a [47mlambda[0m object
  generated by a [47mloop$[0m may be called on anything and we cannot
  guarantee that the input guard to the [47mlambda[0m object will be
  satisfied.  [3mBut we can guarantee that the computation carried out
  by the [47mlambda[0m[3m will terminate![0m The [47mlambda[0m object generated for [47mfn[0m
  above terminates no matter what it is called on -- even if called
  on elements not in [47m(target v)[0m -- because [47mfn[0m terminates.

  Finally, recall that [47mloop$[0m-recursive functions do not automatically
  suggest induction schemes and that special care must be taken when
  formulating inductively provable conjectures about them.  See
  [loop$-recursion-induction].


Subtopics

  [Definductor]
      Create an induction scheme for a [47mloop$[0m-recursive function")
 (LOOP$-RECURSION-INDUCTION
  (LOOP$)
  "Advice on inductive theorems about [47m[loop$][0m-recursive functions

  [31;1mWarning:[0m This documentation topic is fairly preliminary because we do
  not have a lot of experience yet with [47m[apply$][0m, [47m[loop$][0m, and
  [47m[loop$-recursion][0m.  We assume here that readers are familiar with
  the topics cited above.


Definductor

  The principles sketched here are illustrated concretely in the
  tutorial community book [47mprojects/apply/copy-nat-tree.lisp[0m.  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 [47mprojects/apply/top[0m we provide a utility that sometimes
  automates the creation of the inductive hint function and
  associates it with the given [47mloop$[0m-recursive function.  See
  [47m[definductor][0m.  The examples worked manually in [47mcopy-nat-tree.lisp[0m
  are recapitulated towards the end of
  [47mprojects/apply/definductor-tests.lisp[0m, without the manually
  provided hints.  In addition, the book
  [47mprojects/apply/loop-recursion-examples.lisp[0m gives some other
  examples of loop$-recursive functions and inductive theorems about
  them.


Some Basic Principles for Inductive Proofs about [47mLoop$[0m-Recursive
Functions

  If ACL2 did not have [47mloop$[0m, functions defined in terms of
  [47mloop$[0m-recursion would have to be defined with [47m[mutual-recursion][0m.
  Reconsider the example presented in [47m[loop$-recursion][0m.

    (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))))))

  Without [47mloop$[0m the latter function would have to be defined this way.
  We name it [47mmr-copy-nat-tree[0m, where the ``[47mmr[0m'' reminds us this is
  part of a mutually recursive clique.

    (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)))))))

  Note that we define [47mmr-copy-nat-tree[0m by copying the definition of
  [47mcopy-nat-tree[0m (renaming recursive calls appropriately) but
  replacing the use of [47mloop$[0m in [47mcopy-nat-tree[0m with a call of a
  mutually-recursive function here called [47mmr-copy-nat-tree-list[0m.  We
  call [47mmr-copy-nat-tree-list[0m the ``list counterpart'' of
  [47mmr-copy-nat-tree[0m.  However, in general there may be more than just
  two functions in the clique and so we refer generically to
  [47mmr-copy-nat-tree-list[0m as a ``co-member'' of the clique.

  How would you prove theorems about [47mmr-copy-nat-tree[0m?  Four principles
  are known to most ACL2 users of [47mmutual-recursion[0m.  These principles
  apply to [47mloop$[0m-recursive functions as well as to mutually recursive
  ones.  We state them here in terms of both kinds of definitions.

    * While simple recursive functions suggest ``appropriate'' inductions,
      mutually recursive functions and [47mloop$[0m-recursive functions do
      not.  If you want to prove a theorem about such functions you
      have to arrange some kind of induction hint.

    * You can't generally prove an isolated theorem about a single member
      of a mutually recursive clique or a [47mloop$[0m-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
      [47mmr-copy-nat-tree[0m this advice means we must conjoin the theorem
      about that function with ``the same'' theorem about
      [47mmr-copy-nat-tree-list[0m, 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 [47mloop$[0m-recursive function
      [47mcopy-nat-tree[0m this advice means we must simultaneously prove a
      theorem about every [47mloop$[0m in the function.

    * 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 [47m(mr-copy-nat-tree-list x)[0m not to the
      specific call inside [47mmr-copy-nat-tree[0m, which is
      [47m(mr-copy-nat-tree-list (cdr x))[0m.  When dealing with a
      [47mloop$[0m-recursive function, each conjunct must address itself to
      the general target, not to specific target in the [47mloop$[0m
      recursive function.  In the case of the [47mloop$[0m-recursive
      function [47mcopy-nat-tree[0m we need a conjunct about [47m(loop$ for e in
      x collect (copy-nat-tree e))[0m, not about [47m(loop$ for e in (cdr x)
      collect (copy-nat-tree e))[0m.

    * 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 [47mloop$[0m-recursion, about every
      recursive unwinding of each [47mloop$[0m.

  [31;1mRemember:[0m Because [47mloop$[0m-recursive functions call themselves
  recursively with [47mapply$[0m, any theorem about a [47mloop$[0m recursive
  function must almost certainly include a warrant hypothesis for
  that function!

  We illustrate these principles in the community book
  [47mprojects/apply/copy-nat-list.lisp[0m.")
 (LOOP-STOPPER
  (REWRITE)
  "Limit application of permutative rewrite rules

  See [rule-classes] for a discussion of the syntax of the
  [47m:loop-stopper[0m field of [47m:[0m[47m[rewrite][0m 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.

  For example, the built-in [47m:[0m[47m[rewrite][0m rule [47mcommutativity-of-+[0m,

    (implies (and (acl2-numberp x)
                  (acl2-numberp y))
             (equal (+ x y) (+ y x))),

  creates a rewrite rule with a loop-stopper of [47m((x y binary-+))[0m.  This
  means, very roughly, that the term corresponding to [47my[0m must be
  ``smaller'' than the term corresponding to [47mx[0m in order for this rule
  to apply.  However, the presence of [47m[binary-+][0m in the list means
  that certain functions that are ``invisible'' with respect to
  [47m[binary-+][0m (by default, [47m[unary--][0m is the only such function) are
  more or less ignored when making this ``smaller'' test.  We are
  much more precise below.

  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 [47m:loop-stopper[0m 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.

  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 [47m'(a b c)[0m are simpler
  than terms containing variables such as [47mx[0m and [47m(+ 1 x)[0m.  Terms
  containing variables are ordered according to how many occurrences
  of variables there are.  Thus [47mx[0m and [47m(+ 1 x)[0m are both simpler than
  [47m(cons x x)[0m and [47m(+ x y)[0m.  If variable counts do not decide the
  order, then the number of function applications are tried.  Thus
  [47m(cons x x)[0m is simpler than [47m(+ x (+ 1 y))[0m 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 [term-order] for details.

  When the loop-stopping algorithm is controlling the use of
  permutative [47m:[0m[47m[rewrite][0m rules it allows [47mterm1[0m to be moved leftward
  over [47mterm2[0m only if [47mterm1[0m is smaller, in a suitable sense.  Note:
  The sense used in loop-stopping is [31;1mnot[0m 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 [47m(+ b a)[0m to be permuted to [47m(+ a b)[0m
  but not vice versa, assuming [47ma[0m is smaller than [47mb[0m 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 [47mx[0m does in the
  [47m[binary-+][0m tree denoted by the term [47m(+ a x b x)[0m, 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 [47m(+ a b x x)[0m.

  Suppose the loop-stopping algorithm used term order, as noted above,
  and consider the [47m[binary-+][0m tree denoted by [47m(+ x y (- x))[0m.  The
  arguments here are in ascending term order already.  Thus, no
  permutative rules are applied.  But because we are inside a
  [47m+-expression[0m it is very convenient if [47mx[0m and [47m(- x)[0m could be given
  virtually the same position in the ordering so that [47my[0m is not
  allowed to separate them.  This would allow such rules as [47m(+ i (-
  i) j) = j[0m 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., [47m[+][0m function
  above.

  Briefly, a unary function symbol [47mfn1[0m is invisible with respect to a
  function symbol [47mfn2[0m if [47mfn2[0m belongs to the value of [47mfn1[0m in
  [47m[invisible-fns-table][0m; also 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.

  Consider the example above, [47m(+ x y (- x))[0m.  The translated version of
  this term is [47m(binary-+ x (binary-+ y (unary-- x)))[0m.  The initial
  [47m[invisible-fns-table][0m makes [47m[unary--][0m invisible with respect to
  [47m[binary-+][0m.  The commutativity rule for [47m[binary-+][0m will attempt to
  swap [47my[0m and [47m(unary-- x)[0m 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 [47m[binary-+][0m expression,
  [47m[unary--][0m is invisible.  Thus, instead of comparing [47my[0m with [47m(unary--
  x)[0m, the loop-stopping algorithm compares [47my[0m with [47mx[0m, approving the
  swap because [47mx[0m comes before [47my[0m.

  Here is a more precise specification of the total order used for
  loop-stopping with respect to a list, [47mfns[0m, of functions that are to
  be considered invisible.  Let [47mx[0m and [47my[0m be distinct terms; we specify
  when ``[47mx[0m is smaller than [47my[0m with respect to [47mfns[0m.'' If [47mx[0m is the
  application of a unary function symbol that belongs to [47mfns[0m, replace
  [47mx[0m by its argument.  Repeat this process until the result is not the
  application of such a function; let us call the result [47mx-guts[0m.
  Similarly obtain [47my-guts[0m from [47my[0m.  Now if [47mx-guts[0m is the same term as
  [47my-guts[0m, then [47mx[0m is smaller than [47my[0m in this order iff [47mx[0m is smaller
  than [47my[0m in the standard term order.  On the other hand, if [47mx-guts[0m is
  different than [47my-guts[0m, then [47mx[0m is smaller than [47my[0m in this order iff
  [47mx-guts[0m is smaller than [47my-guts[0m in the standard term order.

  Now we may describe the loop-stopping algorithm.  Consider a rewrite
  rule with conclusion [47m(equiv lhs rhs)[0m that applies to a term [47mx[0m in a
  given context; see [rewrite].  Suppose that this rewrite rule has a
  loop-stopper field (technically, the [47m:heuristic-info[0m field) of [47m((x1
  y1 . fns-1) ... (xn yn . fns-n))[0m.  (Note that this field can be
  observed by using the command [47m:[0m[47m[pr][0m with the name of the rule; see
  [pr].)  We describe when rewriting is permitted.  The simplest case
  is when the loop-stopper list is [47mnil[0m (i.e., [47mn[0m is [47m0[0m); in that case,
  rewriting is permitted.  Otherwise, for each [47mi[0m from 1 to [47mn[0m let [47mxi'[0m
  be the actual term corresponding to the variable [47mxi[0m when [47mlhs[0m is
  matched against the term to be rewritten, and similarly correspond
  [47myi'[0m with [47my[0m.  If [47mxi'[0m and [47myi'[0m are the same term for all [47mi[0m, then
  rewriting is not permitted.  Otherwise, let [47mk[0m be the least [47mi[0m such
  that [47mxi'[0m and [47myi'[0m are distinct.  Let [47mfns[0m be the list of all
  functions that are invisible with respect to every function in
  [47mfns-k[0m, if [47mfns-k[0m is non-empty; otherwise, let [47mfns[0m be [47mnil[0m.  Then
  rewriting is permitted if and only if [47myi'[0m is smaller than [47mxi'[0m with
  respect to [47mfns[0m, in the sense defined in the preceding paragraph.

  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
  [47m:loop-stopper[0m, see [rule-classes].)  Suppose the conclusion of the
  rule is of the form [47m(equiv lhs rhs)[0m.  First of all, if [47mrhs[0m 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 [47mnil[0m.
  Otherwise, consider all pairs [47m(u . v)[0m from this substitution with
  the property that the first occurrence of [47mv[0m appears in front of the
  first occurrence of [47mu[0m in the print representation of [47mrhs[0m.  For each
  such [47mu[0m and [47mv[0m, form a list [47mfns[0m of all functions [47mfn[0m in [47mlhs[0m with the
  property that [47mu[0m or [47mv[0m (or both) appears as a top-level argument of a
  subterm of [47mlhs[0m with function symbol [47mfn[0m.  Then the loop-stopper for
  this rewrite rule is a list of all lists [47m(u v . fns)[0m.

  [3mRemark.[0m The paragraph above mentions ``the conclusion of the rule''
  as [47m(equiv lhs rhs)[0m.  The rule's conclusion is actually produced
  from a naive version [47m(equiv lhs0 rhs)[0m of the conclusion by
  expanding away all [lambda] applications in [47mlhs0[0m.  If [47mlhs0[0m and [47mlhs[0m
  are distinct (i.e., if there is any such lambda expansion) and also
  the loop-stopper field is calculated as [47mnil[0m as described above,
  then a second attempt to calculate the loop-stopper is made using
  [47mlhs0[0m in place of [47mlhs[0m.


Subtopics

  [Add-invisible-fns]
      Make some unary functions invisible to the [loop-stopper] algorithm

  [Invisible-fns-table]
      Functions that are invisible to the [loop-stopper] algorithm

  [Remove-invisible-fns]
      Make some unary functions no longer invisible

  [Set-invisible-fns-table]
      Set the invisible functions table")
 (LOWER-CASE-P
  (CHARACTERS ACL2-BUILT-INS)
  "Recognizer for lower case characters

  [47m(Lower-case-p x)[0m is true if and only if [47mx[0m is a lower case character,
  i.e., a member of the list [47m#\\A[0m, [47m#\\B[0m, ..., [47m#\\Z[0m.

  The [guard] for [47mlower-case-p[0m states that its argument is a character.

  [47mLower-case-p[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<lower-case-p>

    (defun lower-case-p (x)
      (declare (xargs :guard (characterp x)))
      (cond ((standard-char-p x)
             (and (member x
                          '(#\\a #\\b #\\c #\\d #\\e #\\f #\\g
                                #\\h #\\i #\\j #\\k #\\l #\\m #\\n #\\o #\\p #\\q
                                #\\r #\\s #\\t #\\u #\\v #\\w #\\x #\\y #\\z))
                  t))
            (t (lower-case-p-non-standard x))))")
 (LP
  (LD)
  "The Common Lisp entry to ACL2

  To enter the ACL2 [command] loop from Common Lisp, call the Common
  Lisp program [47mlp[0m (which stands for ``loop,'' as in ``read-eval-print
  loop'' or ``[command] loop.'') The ACL2 [command] loop is actually
  coded in ACL2 as the function [47m[ld][0m (which stands for ``load'').
  The [command] loop is just what you get by loading from the
  standard object input channel, [47m[*standard-oi*][0m.  Calling [47m[ld][0m
  directly from Common Lisp is possible but fragile because hard lisp
  errors or aborts throw you out of [47m[ld][0m and back to the top-level of
  Common Lisp.  [47mLp[0m calls [47m[ld][0m in such a way as to prevent this and is
  thus the standard way to get into the ACL2 [command] loop.  Also
  see [ACL2-customization] for information on the loading of an
  initialization file.

  All of the visible functionality of [47mlp[0m is in fact provided by [47m[ld][0m,
  which is written in ACL2 itself.  Therefore, you should see [ld]
  for detailed [documentation] of the ACL2 [command] loop.  We sketch
  it below, for novice users.

  Every expression typed to the ACL2 top-level must be an ACL2
  expression.

  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 [encapsulate]).  In addition, ACL2 does not allow
  ``global variables'' in expressions to be evaluated.  Thus, [47m(car
  '(a b c))[0m is legal and evaluates to [47mA[0m, but [47m(car x)[0m is not, because
  there is no ``global context'' or binding environment that gives
  meaning to the variable symbol [47mx[0m.

  There is an exception to the global variable rule outlined above:
  single-threaded objects (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 [47m[state][0m.  This variable may occur in the top-level
  form to be evaluated, but must be passed only to ACL2 functions
  ``expecting'' [47mstate[0m as described in the documentation for [47m[state][0m
  and for [47m[stobj][0ms in general.  If the form returns a new [state]
  object as one of its values, then that is considered the new
  ``current'' [state] for the evaluation of the subsequent form.  See
  [state].

  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 [assign] and see [@].

  If the form read is a single keyword, e.g., [47m:[0m[47m[pe][0m or [47m:[0m[47m[ubt][0m, then
  special procedures are followed.  See [keyword-commands].

  The [command] loop keeps track of the [command]s you have typed and
  allows you to review them, display them, and roll the logical
  [state] back to that created by any [command].  See [history].

  ACL2 makes the convention that if a top-level form returns three
  values, the last of which is an ACL2 [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 [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 [47mnil[0m!).  See [ld] for details.


Subtopics

  [Q]
      Quit ACL2 (type [47m:q[0m) --- reenter with [47m(lp)[0m")
 (LP-BACKGROUND-REVIEW-1
  (LP-SECTION-1)
  "Background review of basic ACL2 knowledge

  Here are some questions to review basic features of ACL2.

------------------------------
  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
  [lp-background-review-1-answers].

    (defun abc (x)
      (declare (xargs :mode :program
                      :guard (true-listp x)))
      (cond
       ((endp x) nil)
       (t (cons (cons '? (car x))
                (abc (cdr x))))))

------------------------------
  1: Informally, what happens if you type that expression at the
  top-level of the ACL2 read-eval-print loop?

------------------------------
  2: More formally, how does the utterance above affect the ACL2 logic?

------------------------------
  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 [47m(fn a1 ... an)[0m, where [47mfn[0m is
  a function symbol or [47mlambda[0m object that takes [47mn[0m arguments and the
  [47mai[0m are terms.  But the [47mcond[0m expression above is not of this form.
  [47mCond[0m 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?

------------------------------
  4: Let [47mx[0m be the object that prints as [47m((A . 1) (B . 2) (C . 3))[0m.
  What is the value of [47m(car x)[0m or is that a nonsensical question?
  Several of the questions below are nonsensical!

------------------------------
  5: Given the value of [47mx[0m in question 4, what is the value of
  [47m(true-listp x)[0m?

------------------------------
  6: Given the value of [47mx[0m in question 4, what is the value of [47m(cons '?
  (car x))[0m?

------------------------------
  7: Given the value of [47mx[0m in question 4, what is the value of [47m(cdr x)[0m?

------------------------------
  8: Recall we defined [47mabc[0m above.  What is the value [47m(abc '((a . 1) (b
  . 2) (c . 3)))[0m?

------------------------------
  9: What is the difference between [47m'((a . 1) (b . 2) (c . 3))[0m and [47m((A
  . 1) (B . 2) (C . 3))[0m?

------------------------------
  10: What is the value of [47m(abc ((a . 1) (b . 2) (c . 3)))[0m?

------------------------------
  11: How would you explain what [47mabc[0m is, i.e., how it ``works'' or what
  it ``does?''

------------------------------
  12: What is the value of [47m(abc 3 4 5)[0m?

------------------------------
  13: What is the value of [47m(abc '(3 . 4))[0m?

------------------------------
  14: How do you get ACL2 to print the value of [47m(abc '(3 . 4))[0m?

------------------------------
  15: How can you upgrade [47mabc[0m from a [47m:program[0m mode function to a [47m:logic[0m
  mode function?

------------------------------
  16: What is the axiom added to ACL2 when [47mabc[0m is upgraded?

------------------------------
  17: Is [47m(true-listp (abc x))[0m a theorem in ACL2?

------------------------------
  18: What would you type to get ACL2 to try to prove it?

------------------------------
  19: How would you describe the behavior of the [47m:logic[0m function [47mdef[0m
  below?  By the way, we're naming certain functions in these reviews
  with consecutive letters of the alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m,
  [47mmno[0m, etc.  These names are not mnemonic or acronyms.  Don't read
  anything into the names!

    (defun def (x)
      (if (endp x)
          nil
          (append (def (cdr x)) (list (car x)))))

------------------------------
  20: Define [47msq[0m to square a number.  E.g., [47m(sq 9)[0m returns [47m81[0m and [47m(sq
  -1/2)[0m returns [47m1/4[0m.

------------------------------
  21: How would you describe the behavior of [47msq*[0m below?

    (defun sq* (x)
      (if (endp x)
          nil
          (cons (sq (car x))
                (sq* (cdr x)))))

------------------------------
  22: What would you type to make ACL2 prove the following conjecture?

    (equal (sq* (def x)) (def (sq* x)))

------------------------------
  23: Prove [47m(nat-listp (ghi 0 max))[0m, where

    (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))))))

------------------------------
  For our answers 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 [loop$].  We recommend that you read
  the topic, [recursion-and-induction].

  If your answers largely agree with ours, go back to the
  [lp-section-1].

  (Return to the Table of Contents (see [LP-SECTION-0]).)")
 (LP-BACKGROUND-REVIEW-1-ANSWERS
  (LP-SECTION-1)
  "Answers to background review of basic ACL2 knowledge

    (defun abc (x)
      (declare (xargs :mode :program
                      :guard (true-listp x)))
      (cond
       ((endp x) nil)
       (t (cons (cons '? (car x))
                (abc (cdr x))))))

------------------------------
  1: Informally, what happens if you type that expression at the
  top-level of the ACL2 read-eval-print loop?

  Answer: It defines [47mabc[0m as a Lisp program.  Note the [47mdeclare[0m that says
  the [47m:mode[0m is [47m:program[0m.  By the way, when Lisp and ACL2 read
  symbols, like [47mabc[0m, [47mx[0m, [47mdeclare[0m, etc., they automatically convert
  them to UPPERCASE.  So it doesn't matter if we write [47mabc[0m or [47mABC[0m, or
  [47mAbc[0m, etc.

------------------------------
  2: More formally, how does the utterance above affect the ACL2 logic?

  Answer: It doesn't.  Defining a [47m:program[0m introduces no axioms into
  the logic.

------------------------------
  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 [47m(fn a1 ... an)[0m, where [47mfn[0m is
  a function symbol or [47mlambda[0m object that takes [47mn[0m arguments and the
  [47mai[0m are terms.  But the [47mcond[0m expression above is not of this form.
  [47mCond[0m is a macro that translates into a formal term.  What formal
  term does the [47mcond[0m expression translate to?  And if you didn't
  know, how would you find out?

  Answer: The expression

    (cond
     ((endp x) nil)
     (t (cons (cons '? (car x))
              (abc (cdr x)))))

  translates to

    (if (endp x)
        'nil
        (cons (cons '? (car x))
              (abc (cdr x))))

  To see the translation of an expression use [47m[trans][0m.

------------------------------
  4: Let [47mx[0m be the object that prints as [47m((A . 1) (B . 2) (C . 3))[0m.
  What is the value of [47m(car x)[0m or is that a nonsensical question?
  Several of the questions below are nonsensical!

  Answer: [47m(car x)[0m is [47m(A . 1)[0m if [47mx[0m is [47m((A . 1) (B . 2) (C . 3))[0m.

------------------------------
  5: Given the value of [47mx[0m in question 4, what is the value of
  [47m(true-listp x)[0m?

  Answer: [47mT[0m, because [47mx[0m is a nest of conses whose rightmost terminal is
  [47mNIL[0m.

------------------------------
  6: Given the value of [47mx[0m in question 4, what is the value of [47m(cons '?
  (car x))[0m?

  Answer: [47m(? A . 1)[0m

------------------------------
  7: Given the value of [47mx[0m in question 4, what is the value of [47m(cdr x)[0m?

  Answer: [47m((B . 2) (C . 3))[0m

------------------------------
  8: What is the value [47m(abc '((a . 1) (b . 2) (c . 3)))[0m?

  Answer: [47m((? A . 1) (? B . 2) (? C . 3))[0m

------------------------------
  9: What is the difference between [47m'((a . 1) (b . 2) (c . 3))[0m and [47m((A
  . 1) (B . 2) (C . 3))[0m?

  Answer: [47m'((a . 1) (b . 2) (c . 3))[0m is a constant term that evaluates
  to the list [47m((A . 1) (B . 2) (C . 3))[0m.  The quote mark in front an
  object forms a term that evaluates to that object.  And remember,
  case is generally irrelevant in symbols.

------------------------------
  10: What is the value of [47m(abc ((a . 1) (b . 2) (c . 3)))[0m?

  Answer: That's a nonsensical question.  [47m(abc ((a . 1) (b . 2) (c .
  3)))[0m is not a well-formed term.  For example, [47m(a . 1)[0m is not a
  function symbol or a [47mlambda[0m expression, or a macro.

------------------------------
  11: How would you explain what [47mabc[0m is, i.e., how it ``works'' or what
  it ``does?''

  Answer: The symbol [47mABC[0m 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 [47mabc[0m
  is called on [47mx[0m it copies the [47mcdr[0m-chain of [47mx[0m, adding the question
  mark symbol to each new element.

------------------------------
  12: What is the value of [47m(abc 3 4 5)[0m?

  Answer: Nonsensical. [47mABC[0m takes only one argument, not three.

------------------------------
  13: What is the value of [47m(abc '(3 . 4))[0m?

  Answer: Actually, it is [47m((? . 3))[0m, but ACL2 won't evaluate [47m(abc '(3 .
  4))[0m in the default configuration of the top-level read-eval-print
  loop because [47m(3 . 4)[0m is not a [47m[true-listp][0m.  The guard on [47mABC[0m
  stipulates that the argument to [47mABC[0m is ``supposed'' to be a
  [47mtrue-listp[0m.  So the read-eval-print loop causes a guard violation
  error.  We explain why the value of [47m(abc '(3 . 4))[0m is actually [47m((?
  . 3))[0m in the next answer.

------------------------------
  14: How do you get ACL2 to compute and print the value of [47m(abc '(3 .
  4))[0m?

  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 [47mT[0m, meaning it does check guards.  But by
  executing [47m(set-guard-checking nil)[0m the parameter is set to [47mNIL[0m and
  then guards are not checked.  With that setting, ACL2 evaluation
  just ignores the guard and runs the body of the program.

  So here is how [47m(abc '(3 . 4))[0m is evaluated.  First, it checks whether
  [47m[endp][0m holds on [47m(3 . 4)[0m.  The definition of [47mendp[0m is [47matom[0m, which
  means ``is not a [47m[cons][0m pair,'' and [47m(3 . 4)[0m is a [47mcons[0m pair.  So the
  answer to the [47mendp[0m test is [47mNIL[0m and the execution of [47m(abc '(3 . 4))[0m
  branches to the [47m(cons (cons '? (car x)) (abc (cdr x)))[0m, where [47mx[0m is
  [47m(3 . 4)[0m.

  But the [47mcar[0m and [47mcdr[0m of the pair [47m(3 . 4)[0m are [47m3[0m and [47m4[0m respectively.  So
  the value of [47m(abc '(3 . 4))[0m is [47m(cons (cons '? 3) (abc 4))[0m.

  But what is the value of [47m(abc 4)[0m?  [47m(Endp 4)[0m is [47mT[0m because [47m4[0m is an
  atom.  So the value of [47m(cons (cons '? 3) (abc 4))[0m is [47m(cons (cons '?
  3) NIL)[0m, which is printed as [47m((? . 3))[0m.

------------------------------
  15: How can you upgrade [47mabc[0m from a [47m:program[0m mode function to a [47m:logic[0m
  mode function?

  Answer: Invoke [47m[verify-termination][0m like this [47m(verify-termination
  abc)[0m.

------------------------------
  16: What is the axiom added to the ACL2 logic when [47mabc[0m is upgraded?

  Answer:

    <b>Definitional Axiom for ABC</b>
    (abc x)
    =
    (if (endp x)
        nil
        (cons (cons '? (car x))
              (abc (cdr x)))).

  Note that the guard is irrelevant in the logic.  [47m(Abc x)[0m is always
  equal to the right-hand side of the axiom above (the ``body'' of
  [47mabc[0m), regardless of what [47mx[0m is.

------------------------------
  17: Is [47m(true-listp (abc x))[0m a theorem in ACL2?

  Answer: Yes!  It may not seem so because the [47mdefun[0m of [47mabc[0m mentions
  the [47m:guard[0m of [47m(true-listp x)[0m and yet the conjecture here doesn't
  constrain [47mx[0m.  But guards of ACL2 functions are logically
  irrelevant.  The Definitional Axiom added for [47mabc[0m does not mention
  the guard.  So [47m(true-listp (abc x))[0m is a theorem no matter what [47mx[0m
  is!

  Proof of [47m(true-listp (abc x))[0m by induction on [47mx[0m:

    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.

  If you ask ACL2 to do the proof (see the next question) its proof
  doesn't mention induction.  That's because when [47mabc[0m was defined
  ACL2 does a little inductive reasoning to deduce the ``type'' of
  the output and deduced that it is always a [47mtrue-listp[0m.  That type
  inference essentially does the inductive proof above.

------------------------------
  18: What would you type to get ACL2 to try to prove it?

  Answer:

    (thm (true-listp (abc x)))

  or

    (defthm little-theorem-about-abc
      (true-listp (abc x)))

------------------------------
  19: How would you describe the behavior of the [47m:logic[0m function [47mdef[0m
  below?  By the way, we're naming certain functions in these reviews
  with consecutive letters of the alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m,
  [47mmno[0m, etc.  These names are not mnemonic or acronyms.  Don't read
  anything into the names!

    (defun def (x)
      (if (endp x)
          nil
          (append (def (cdr x)) (list (car x)))))

  Answer: It reverses [47mx[0m, i.e., it returns a list containing the
  elements of [47mx[0m in reverse order.  E.g., [47m(def '(a b c))[0m returns [47m(C B
  A)[0m.

------------------------------
  20: Define [47msq[0m to square a number.  E.g., [47m(sq 9)[0m returns [47m81[0m and [47m(sq
  -1/2)[0m returns [47m1/4[0m.

  Answer:

    (defun sq (x) (* x x))

  We could add a declaration, like [47m(declare (xargs :guard (rationalp
  x)))[0m or [47m(declare (xargs :guard (acl2-numberp x)))[0m.  But we've
  chosen to keep things simple here.

------------------------------
  21: How would you describe the behavior of [47msq*[0m below?

    (defun sq* (x)
      (if (endp x)
          nil
          (cons (sq (car x))
                (sq* (cdr x)))))

  Answer: It squares every element of [47mx[0m and returns the list of those
  results in the same order.  E.g., [47m(sq* '(1 2 3 -1/2 #c(0 1)))[0m is [47m(1
  4 9 1/4) -1[0m.

------------------------------
  22: What would you type to make ACL2 prove the following conjecture?

    (equal (sq* (def x)) (def (sq* x)))

  Answer: To get ACL2 to try to prove the theorem you could type

    (defthm sq*-def
      (equal (sq* (def x)) (def (sq* x))))

  But ACL2 would fail to find the proof unless you'd proved some lemmas
  about [47mdef[0m.  You might see a ``checkpoint'' like

    *** 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))))))

  What would that suggest you do?

  What we'd do is prove the following lemma first and then try [47msq*-def[0m.

    (defthm sq*-append
      (equal (sq* (append a b))
             (append (sq* a) (sq* b))))

  When that lemma is available as a [47m:[0m[47m[rewrite][0m rule during the proof of
  [47msq*-def[0m the checkpoint above would be further simplified, the
  induction hypothesis of the [47msq*-def[0m conjecture would be used, and
  the proof of [47msq*-def[0m would succeed.

  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 [the-method].

------------------------------
  23: Prove [47m(nat-listp (ghi 0 max))[0m, where

    (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))))))

  Answer: You can't prove [47m(nat-listp (ghi 0 max))[0m by induction with
  that [47m0[0m in one of the controlling arguments.  You have to generalize
  first.

    (defthm nat-listp-ghi-lemma
       (nat-listp (ghi i max)))

    (defthm nat-listp-ghi
       (nat-listp (ghi 0 max)))

------------------------------
  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 [loop$-primer].  We recommend
  that you take the ``Recursion and Induction'' course [31;1m(which should
  be somehow linked in here!)[0m.

  (Return to the Table of Contents (see [LP-SECTION-0]).)")
 (LP-BACKGROUND-REVIEW-2
  (LP-SECTION-1)
  "Review of [47m[apply$][0m and related concepts

  Below are some questions designed to review basic knowledge of
  [47m[apply$][0m and related concepts used in the semantics of [47mloop$[0m.  For
  our answers see [lp-background-review-2-answers].

  But our answers are sometimes quite long and elaborate --- 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 [47mloop$[0m, 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
  ``Ack! What's that all about?'' We want it to be at least ``Oh yes,
  I remember now.'' We recommend that after you've read and answered
  the questions, you read our answers even if you're pretty confident
  in your answers.

------------------------------
  Consider these events, executed as the first three events in new ACL2
  sessions.

    (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))))))

  The three events are executed without error and [47msq[0m and [47mghi[0m are
  admitted in [47m:logic[0m mode.  By the way, we're naming certain
  functions in these reviews with consecutive letters of the
  alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m, [47mmno[0m, 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
  [47m[lp-background-review-1][0m), here we define [47m(sq x)[0m with a guard of
  [47m(natp x)[0m.  Both [47msq[0m and [47mghi[0m are guard verified upon admission.

------------------------------
  1: What is the value of [47m(ghi 'sq '(1 2 3))[0m?  Hint: This is a trick
  question!

------------------------------
  2: How do you assign a badge and warrant to [47msq[0m?

------------------------------
  3: What is the name of the ``warrant function for [47msq[0m?'' What does
  [47m(warrant sq)[0m abbreviate?  What does [47m(warrant sq)[0m imply about [47mbadge[0m
  and [47mapply$[0m?

------------------------------
  4: Can [47mghi[0m be warranted?  If so, what command do you type?

------------------------------
  5: What is the name of the warrant function for [47mghi[0m?  Explain what
  the warrant for [47mghi[0m tells us.

------------------------------
  6: The following definition is admissible.  Can it be warranted?

    (defun mno (x y z)
      (if (endp x)
          z
          (apply$ y
                  (list (car x)
                        (mno (cdr x) y z)))))

------------------------------
  7: Is [47m(equal (mno x 'cons y) (append x y))[0m a theorem?

------------------------------
  8: The following [47mdefun[0m is admissible but cannot be warranted.  Why?

    (defun xyz (x) (apply$ x (list x)))

------------------------------
  9: Recall [47mghi[0m as defined at the beginning of this review.  Assume [47msq[0m
  has been warranted.  What is the value of [47m(ghi 'sq '(1 2 3))[0m?

------------------------------
  10: Is [47m(nat-listp (ghi 'sq lst))[0m a theorem?  If not, what theorem
  does this suggest?

------------------------------
  11: What is the value of the term below?

    (ghi (lambda$ (e) (ghi 'sq e))
         '((1 2 3)
           (4 5 6)
           (7 8 9)))

------------------------------
  12: Suppose you want to define [47mjkl[0m to be something like what's shown
  below and you want the guards verified.

    (defun jkl (lst)
      (declare (xargs :guard ...))
      (ghi (lambda$ (e) (ghi 'sq e)) lst)))

  Notice that the body of [47mjkl[0m is the doubly nested [47mghi[0m term just
  tested, except now instead of applying it to a constant list we're
  applying it to the argument of [47mjkl[0m.

  What is the appropriate [47m:[0m[47m[guard][0m and do you have to make other
  modifications to the suggested [47mdefun[0m of [47mjkl[0m?

------------------------------
  13: Can [47mjkl[0m be warranted?

------------------------------
  14: Is this a theorem?  If not, what theorem does it suggest?

    (implies (nat-listp-listp lst)
             (nat-listp-listp (jkl lst)))

------------------------------
  See [lp-background-review-2-answers] for our answers.  If your
  answers basically agree with ours we think you're ready to learn
  about [47mloop$[0m, so go back to the [loop$-primer].  Otherwise, we
  strongly recommend that you read [introduction-to-apply$] and then
  [47m[apply$][0m before reading about [47mloop$[0m.

  (Return to the Table of Contents (see [LP-SECTION-0]).)")
 (LP-BACKGROUND-REVIEW-2-ANSWERS
  (LP-SECTION-1)
  "Answers to the review of [47m[apply$][0m and related concepts

  Below are our answers to the Review of [47m[apply$][0m and related concepts.
  If your answers basically agree with ours, we think you're ready to
  follow the discussion in [47m[loop$-primer][0m.  If not, we recommend that
  you read [introduction-to-apply$] and then [47m[apply$][0m before reading
  about [47mloop$[0m.

  But our answers are sometimes quite long and elaborate --- 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 [47mloop$[0m, 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
  ``Ack! What's that all about?'' We want it to be at least ``Oh yes,
  I remember now.'' So we recommend that you read these little
  mini-lectures in full.

------------------------------
  Consider these events, executed as the first three events in new ACL2
  sessions.

    (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))))))

  The three events are executed without error and [47msq[0m and [47mghi[0m are
  admitted in [47m:logic[0m mode.  By the way, we're naming certain
  functions in these reviews with consecutive letters of the
  alphabet, e.g., [47mabc[0m, [47mdef[0m, [47mghi[0m, [47mjkl[0m, [47mmno[0m, 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
  [47m[lp-background-review-1][0m), here we define [47m(sq x)[0m with a guard of
  [47m(natp x)[0m.  Both [47msq[0m and [47mghi[0m are guard verified upon admission.

------------------------------
  1: What is the value of [47m(ghi 'sq '(1 2 3))[0m?  Hint: This is a trick
  question!

  Answer: Note that [47mghi[0m is a [scion] of [47mapply$[0m.  It calls [47mapply$[0m,
  passing in the first argument of [47mghi[0m as the ``function'' to [47mapply$[0m.
  The evaluation of the above term fails with an error message
  because [47msq[0m is a user-defined [47m:[0m[47m[logic][0m mode function but has not
  been [warrant]ed (see [47m[defwarrant][0m).  [47m:Logic[0m mode functions must be
  warranted to be applied (with [47mapply$[0m) 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
  [47mapply$[0m) of such functions, their warrants must be provided as
  hypotheses.  We'll get to that later.

  By the way, [47m:[0m[47m[program][0m mode functions must be [47m[badge][0md (see
  [47m[defbadge][0m) to be applied at the top-level, but they need not be
  warranted (because [47m:program[0m mode functions cannot be warranted or
  used meaningfully in conjectures to be proved).  See
  [guarantees-of-the-top-level-loop] for a discussion of the badge
  and warrant restrictions enforced by top-level evaluation.

------------------------------
  2: How do you assign a badge and warrant to [47msq[0m?

  Answer: [47m(defwarrant sq)[0m.

  [47m[Defwarrant][0m assigns both a badge and a warrant to its argument,
  which must be a [47m:logic[0m 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.

  [47m[Defbadge][0m just assigns a badge and can work on [47m:program[0m or [47m:logic[0m
  mode functions.

------------------------------
  3: What is the name of the ``warrant function for [47msq[0m?'' What does
  [47m(warrant sq)[0m abbreviate?  What does [47m(warrant sq)[0m imply about [47mbadge[0m
  and [47mapply$[0m?

  Answer: The warrant function for [47msq[0m is named [47mapply$-warrant-sq[0m, which
  is a 0-ary predicate.  [47m(Warrant sq)[0m is just an abbreviation for a
  call of [47mapply$-warrant-sq[0m and if more than one function symbol
  appears after the symbol [47mwarrant[0m then it expands to the conjunction
  of each of their predicates.  We'll show an example later.

  [47mApply$-warrant-sq[0m is introduced as a constrained function using
  [47m[defun-sk][0m.  Here is the event in question, but the details here
  are not critical to the present discussion.

    (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)

  What is critical is the role that [47m(apply$-warrant-sq)[0m plays in the
  following theorem, which is proved as a [47m:[0m[47m[rewrite][0m rule by
  [47m(defwarrant sq)[0m.

    (defthm apply$-sq
      (implies (force (apply$-warrant-sq))
               (and (equal (badge 'sq)
                           '(apply$-badge 1 1 . t))
                    (equal (apply$ 'sq args)
                           (sq (car args))))))

  which allows the prover to reduce [47m(badge 'sq)[0m to [47m(apply$-badge 1 1 .
  t)[0m and to reduce any instance of [47m(apply$ 'sq args)[0m to [47m(sq (car
  args))[0m.

  The [47m[badge][0m of [47msq[0m tells the prover that [47msq[0m is a function of one
  argument that returns one result.  The ``[47m . t[0m'' means ``all the
  arguments are ordinary objects,'' i.e., never treated like
  ``functions.''

  The second part of the rule above will reduce the typical application
  of [47msq[0m, e.g., [47m(apply$ 'sq (list e))[0m, to [47m(sq e)[0m.

  Finally, note that name of the rule is [47mapply$-sq[0m, both the [47mbadge[0m and
  [47mapply$[0m reductions are conditional on the warrant hypothesis for [47msq[0m,
  and that the warrant hypothesis is [47m[force][0md.

------------------------------
  4: Can [47mghi[0m be warranted?  If so, what command do you type?

  Answer: Yes!  Just type [47m(defwarrant ghi)[0m.

------------------------------
  5: What is the name of the warrant function for [47mghi[0m?  Explain what
  the warrant for [47mghi[0m tells us.

  Answer: The warrant function for [47mghi[0m is named [47mapply$-warrant-ghi[0m.
  [47m(warrant ghi)[0m abbreviates [47m(apply$-warrant-ghi)[0m, and, by the way,
  [47m(warrant sq ghi ...)[0m expands to

    (and (apply$-warrant-sq)
         (apply$-warrant-ghi)
         ...).

  The rule [47mapply$-ghi[0m is proved by [47mdefwarrant[0m.

    (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)))))))

  Notice that [47mapply$-ghi[0m is really two [47m:rewrite[0m rules, both conditioned
  on the forced warrant for [47mghi[0m.

  The first rule tells us what the [47m[badge][0m of [47mghi[0m is.  In particular we
  see that the first argument of [47mghi[0m has ``[ilk]'' [47m:[0m[47mfn[0m, which means
  that argument is treated as a function and can eventually be
  applied with [47mapply$[0m.  Arguments of ilk [47m:fn[0m are never treated as
  ordinary objects.  The badge of [47mghi[0m also tells us the second
  argument has ilk [47mnil[0m, which means it is an ordinary object (and is
  never treated as a function).  The details are in [47m[defbadge][0m.

  Note that the second conjunct of the [47mapply$-ghi[0m rule above rewrites
  instances of [47m(apply$ 'ghi args)[0m and would rewrite [47m(apply$ 'ghi
  (list x y))[0m to [47m(ghi x y)[0m.  However, it can only be used if the
  first argument passed to [47mghi[0m, namely [47mx[0m above, is a [tame] function.
  Ilks, warrants, and tameness are concepts that are critical to the
  soundness of ACL2's handling of [47mapply$[0m.  For details see [47m[apply$][0m.

------------------------------
  6: The following definition is admissible.  Can it be warranted?

    (defun mno (x y z)
      (if (endp x)
          z
          (apply$ y
                  (list (car x)
                        (mno (cdr x) y z)))))

  Answer: Yes.  Its badge is determined to be [47m(apply$-badge 3 1 nil :fn
  nil)[0m.

  For example,

    (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)

  In fact, [47mmno[0m is more often named ``[47mfoldr[0m'' in the functional
  programming literature.

------------------------------
  7: Is [47m(equal (mno x 'cons y) (append x y))[0m a theorem?

  Answer: Yes!  You might think we need to add the warrant hypothesis
  for [47mcons[0m since [47m(apply$ 'cons ...)[0m must be expanded to do the proof.
  However, most ACL2 primitives, like [47mcons[0m, are built into the
  definition of [47mapply$[0m and warrants are not necessary for them.  In
  fact, the primitives don't have warrant functions.  E.g., [47m(apply$
  'cons (list x y))[0m is [47m(cons x y)[0m, unconditionally.  The complete
  list of [47mapply$[0m primitives may be exhibited by evaluating

    (append '(BADGE TAMEP TAMEP-FUNCTIONP SUITABLY-TAMEP-LISTP
                    APPLY$ EV$)
            (strip-cars *badge-prim-falist*)).

  However, [3muser-defined function symbols[0m need warrants in order to be
  applied (with [47mapply$[0m).  But not all user-defined symbols can be
  warranted.

------------------------------
  8: The following [47mdefun[0m is admissible but cannot be warranted.  Why?

    (defun xyz (x) (apply$ x (list x)))

  Answer: It is impossible to classify the argument [47mx[0m.  Is it a
  function or is it an ordinary object?  It's used both ways.
  [47m(Defwarrant xyz)[0m fails.

  In order for [47mapply$[0m 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 [47mapply$[0m is defined as a big case analysis that
  enumerates all the functions that [47mapply$[0m can handle and calls them
  appropriately.  That big definition of [47mapply$[0m has some measure that
  explains why it terminates --- a fairly messy measure given that
  [47mapply$[0m can all [47mghi[0m which calls [47mapply$[0m.  Now imagine you want to
  define a new function, e.g., [47mxyz[0m, and change the definition of that
  big [47mapply$[0m to include all the old functions plus [47mxyz[0m.  You'll need
  to weave the measure of [47mxyz[0m into the measure of the big [47mapply$[0m.
  [47mDefwarrant[0m enforces restrictions that tell us this is possible.  Of
  course, the restrictions are overly restrictive: to be perfect
  [47mdefwarrant[0m would have to solve the halting problem.

  While the failure of [47m(defwarrant xyz)[0m prevents us from being able to
  use [47mapply$[0m to apply [47mxyz[0m, it is possible to evaluate some calls of
  [47mxyz[0m and to prove theorems about them.

    (thm
      (equal (xyz '(lambda (x) (len x))) 3)

  In the proof of the theorem above, [47mxyz[0m applied the given [47mlambda[0m
  object to itself and computed that its length is 3.

------------------------------
  9: Recall [47mghi[0m as defined at the beginning of this review.  Assume [47msq[0m
  has been warranted.  What is the value of [47m(ghi 'sq '(1 2 3))[0m?

  Answer: [47m(1 4 9)[0m.

  Recall that an earlier question established that [47mghi[0m can be warranted
  and one might think warranting [47mghi[0m is necessary for [47m(ghi 'sq '(1 2
  3))[0m to be evaluated without error.  But that's untrue.  [47mGhi[0m is not
  being applied (with [47mapply$[0m) here, so whether it has been warranted
  or not is irrelevant.  However, [47msq[0m is being applied.

------------------------------
  10: Is [47m(nat-listp (ghi 'sq lst))[0m a theorem?  If not, what theorem
  does this suggest?

  Answer: No, it's not a theorem as written.  For example [47m(ghi 'sq
  '(-1/2 #c(0 1)))[0m has the value [47m(1/4 -1)[0m, although to get that value
  computed by the top-level read-eval-print loop you have to turn off
  guard checking (see [47m[set-guard-checking][0m).

  The following is a theorem.

    (implies (and (warrant sq)
                  (nat-listp lst))
             (nat-listp (ghi 'sq lst)))

  The [47mwarrant[0m hypothesis for [47msq[0m is necessary because to prove anything
  interesting about [47m(apply$ 'sq ...)[0m we need the warrant for [47msq[0m.  The
  [47mnat-listp[0m hypothesis is necessary because otherwise [47msq[0m may not
  return a natural number.

------------------------------
  11: What is the value of the term below?

    (ghi (lambda$ (e) (ghi 'sq e))
         '((1 2 3)
           (4 5 6)
           (7 8 9)))

  Answer: [47m((1 4 9) (16 25 36) (49 64 81))[0m.

  [47m[Lambda$][0m is an interesting ACL2 feature.  It translates the body
  term and constructs a [47mlambda[0m object suitable for [47mapply$[0m.

  The [47mghi[0m term above is also interesting.  It shows that the outer call
  of [47mghi[0m can successfully [47mapply$[0m the [47mlambda[0m object which itself calls
  [47mghi[0m on [47msq[0m.

------------------------------
  12: Suppose you want to define [47mjkl[0m to be something like what's shown
  below and you want the guards verified.

    (defun jkl (lst)
      (declare (xargs :guard ...))
      (ghi (lambda$ (e) (ghi 'sq e)) lst)))

  Notice that the body of [47mjkl[0m is the doubly nested [47mghi[0m term just
  tested, except now instead of applying it to a constant list we're
  applying it to the argument of [47mjkl[0m.

  What is the appropriate [47m:[0m[47m[guard][0m and do you have to make other
  modifications to the suggested [47mdefun[0m of [47mjkl[0m?

  Answer: First, we define a predicate that recognizes a list of
  [47mnat-listp[0ms, i.e., a list of lists, where each element of each of
  the inner lists is a natural number.

    (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)))))

  We could warrant [47mnat-list-listp[0m with [47m(defwarrant nat-list-listp)[0m 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 [47mapply$[0m we
  would need a warrant and we can always warrant it when needed.

  We can then define [47mjkl[0m with the :[47mguard[0m shown below.  The [47mtrue-listp[0m
  conjunct of the guard below is necessary because [47mnat-list-listp[0m has
  [47mtrue-listp[0m as its guard.  But note that we also modified the
  [47m[lambda$][0m expression to express the guard on its local variable [47me[0m.

    (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))

  [47mJkl[0m is guard verified upon admission.  Consider what that means.  In
  particular, every time [47msq[0m is called it is called on something
  satisfying the guard of [47msq[0m.  The guard proof obligations generated
  for a nest of functions using [47mapply$[0m can be quite messy.

------------------------------
  13: Can [47mjkl[0m be warranted?

  Answer: Yes.  [47m(defwarrant jkl)[0m succeeds.  A key observation is that
  the [47mlambda$[0m expression in its definition is a [47mtame[0m function (see
  [47mtame[0m).  That is syntactically determined because the body of the
  [47mlambda$[0m is [47m(ghi 'sq e)[0m, [47mghi[0m requires a tame function as its first
  argument, and [47msq[0m is a tame function.

------------------------------
  14: Is this a theorem?  If not, what theorem does it suggest?

    (implies (nat-list-listp lst)
             (nat-list-listp (jkl lst)))

  Answer: It is not quite a theorem as written.  We need to add warrant
  hypotheses for the functions being applied with [47mapply$[0m.  Note that
  [47mjkl[0m is not being applied, so we don't need its warrant.  The outer
  [47mghi[0m in the definition of [47mjkl[0m is also not being applied.  But the
  [47m[lambda$][0m expression passed as an argument to the outer [47mghi[0m is
  being applied by the outer [47mghi[0m, and to evaluate the body of that
  [47mlambda[0m object we [47mapply$[0m [47mghi[0m, so we need the warrant for [47mghi[0m there.
  Furthermore, that inner [47mghi[0m will apply [47msq[0m.  So we need the warrant
  for that.

  Thus, the following is indeed a theorem.

    (implies (and (warrant ghi sq)
                  (nat-list-listp lst))
             (nat-list-listp (jkl lst)))

  For some heuristic advice on how to figure out the necessary
  warrants, see the section ``Determining the Necessary Warrants'' in
  see [47m[warrant][0m.

  However, if you omit the warrant hypotheses ACL2 will often
  ``remind'' you at the end of failed proof attempts by exhibiting
  checkpoints derived from forcing the warrants when [47mapply$[0m rules are
  applied.  If the warrants are omitted in this particular theorem
  checkpoints require proving both [47m(apply$-warrant-sq)[0m and
  [47m(apply$-warrant-ghi)[0m.

  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 [47mdefwarrant[0m 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.

------------------------------
  If your answers basically agree with ours you should proceed on to
  [lp-section-2].  Otherwise, we strongly recommend that you read
  [introduction-to-apply$] and then [47m[apply$][0m before reading about
  [47mloop$[0m.

  (Return to the Table of Contents (see [LP-SECTION-0]).)")
 (LP-SECTION-0
  (LOOP$-PRIMER)
  "Loop$ Primer Table of Contents)


The Loop$ Primer Table of Contents

    * [loop$-primer]:   Preface

    * lp-section-0:   Table of Contents

    * [lp-section-1]:   Background Reviews

    * [lp-section-2]:   [47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2

    * [lp-section-3]:   Examples of [47mFOR[0m [47mLoop$[0ms

    * [lp-section-4]:   Syntax of [47mFOR[0m [47mLoop$[0ms

    * [lp-section-5]:   Informal Semantics of [47mFOR[0m [47mLoop$[0ms

    * [lp-section-6]:   Challenge Problems about [47mFOR[0m [47mLoop$[0ms

    * [lp-section-7]:   Using [47mLoop$[0ms and Guards in [47mDefun[0ms

    * [lp-section-8]:   Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms

    * [lp-section-9]:   Semantics of [47mFOR[0m [47mLoop$[0ms

    * [lp-section-10]: The Evaluation of the Formal Semantics of a Fancy
      [47mLoop$[0m

    * [lp-section-11]: Proving Theorems about [47mFOR[0m [47mLoop$[0ms

    * [lp-section-12]: Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms

    * [lp-section-13]: Examples of [47mDO[0m [47mLoop$[0ms

    * [lp-section-14]: Challenge Problems about [47mDO[0m [47mLoop$[0ms

    * [lp-section-15]: Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms

    * [lp-section-16]: Proving Theorems about [47mDO[0m [47mLoop$[0ms

    * [lp-section-17]: Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms

    * [lp-section-18]: Conclusion

    * lp-section-0:   Table of Contents")
 (LP-SECTION-1
  (LOOP$-PRIMER)
  "Background Reviews


LP1: Background Reviews

  We assume you're familiar with elementary Common Lisp and ACL2.  The
  questions and answers in [lp-background-review-1] offer a quick
  review.  Come back here when you're comfortable with such
  questions.

  [47mLoop$[0m makes extensive use of ACL2's limited second order
  functionality.  The questions and answers in
  [47m[lp-background-review-2][0m offer a quick review of the main features
  and limitations of [47mapply$[0m and the related concepts.  We assume
  you're comfortable with these features too.

  Now go to [lp-section-2] (or return to the  Table of Contents (see
  [LP-SECTION-0])).


Subtopics

  [Lp-background-review-1]
      Background review of basic ACL2 knowledge

  [Lp-background-review-1-answers]
      Answers to background review of basic ACL2 knowledge

  [Lp-background-review-2]
      Review of [47m[apply$][0m and related concepts

  [Lp-background-review-2-answers]
      Answers to the review of [47m[apply$][0m and related concepts")
 (LP-SECTION-10
  (LOOP$-PRIMER)
  "The Evaluation of the Formal Semantics of a Fancy [47mLoop$[0m


LP10: The Evaluation of the Formal Semantics of a Fancy [47mLoop$[0m

  Below we show the evaluation of a fancy [47mloop$[0m that uses the function
  [47mpackn[0m to create a list of symbols.  We start with an example of
  [47mpackn[0m so you can infer its behavior.  But our real interest is the
  behavior of the [47mloop$[0m.

    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 !>

  We now explain carefully the evaluation of the [47mloop$[0m expression above
  in an environment in which [47mmark[0m is bound to the asterisk symbol, [47m*[0m.

  The first three lines of the [47mloop$[0m introduce the so-called [3miteration
  variables[0m, [47mx[0m, [47my[0m, and [47mi[0m, and their respective [3mranges[0m.

  The [47mwhen[0m clause specifies a predicate on the iteration variables,
  identifying the ``good'' cases, i.e., the values of the iteration
  variables that we care about.  However, note that the predicate
  above mentions the variable [47mmark[0m, which is not one of the iteration
  variables.  We call such variables [3mglobals[0m because their values are
  not set within the scope of the [47mloop[0m.

  The [47mcollect[0m clause specifies an expression to be evaluated on the
  ``good'' iteration variable values and collects the results of
  those evaluations.

  If you replace the symbol [47mloop$[0m above by [47mloop[0m you get a legal Common
  Lisp [47mloop[0m expression with the same value (if executed when [47mmark[0m is
  bound to [47m*[0m).

  For our purposes, the easiest way to think about this particular
  statement is to decompose it into three steps.

  Step 1: The lines introducing the iteration variables and their
  ranges cause us to make a table of corresponding values of [47mx[0m, [47my[0m,
  and [47mi[0m, as shown below in the form of a list of triples.  This list
  is as long as the shortest individual range.

    ; 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)).

  Step 2: the [47mwhen[0m clause maps over the above table and identifies the
  entries as ``good'' or ``bad'', where the good ones have an even
  value for [47mi[0m and values for [47mx[0m and [47my[0m that are not the asterisk mark,
  [47m*[0m.  We annotate the table accordingly below.

    ; 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!

  Effectively the [47mwhen[0m clause pares down the table to just the good
  entries.

    ; x y  i
    ((A U  0)        ; GOOD!
     (G X 24)        ; GOOD!
     (I Z 30)).      ; GOOD!

  Step 3: the [47mcollect[0m clause maps over pared-down table, evaluating and
  collecting the results of [47m(packn (list x y '_ i))[0m for each triple
  in the table.

    (AU_0
     GX_24
     IZ_30).

  The ACL2 semantics of the [47mloop$[0m statement reflects this understanding
  of the statement.  (The display below is the output of [47m:tca[0m on the
  [47mloop$[0m, but with the [47mDECLARE[0m forms deleted and the three comments
  added.)

      (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)))))

  In step 1, the [47mloop$-as[0m function takes a list of the individual
  ranges and builds the first version of the iteration variable
  table.  The function [47mfrom-to-by[0m just enumerates the integers from
  its first argument to its second argument in steps of size given by
  its third argument.

  In step 2, the [47mwhen$+[0m function takes three arguments.  Note that the
  last argument of the [47mwhen$+[0m function is the iteration variable
  table computed by step 1.  The first argument of the [47mwhen$+[0m
  function is a [47mlambda$[0m expression representing the predicate used to
  identify the ``good'' entries.  But that predicate may also require
  the value of any global variables used.  So the [47mlambda$[0m expression
  has two arguments, [47mloop$-gvars[0m, the list of values of the global
  variables, and [47mloop$-ivars[0m, a tuple of values corresponding to a
  line in the iteration variable table.  The middle argument of the
  [47mwhen$+[0m provides the values of the global variables and, as noted
  earlier, the last argument is the iteration variable table.  The
  [47mwhen$+[0m maps over the iteration variable table and collects the
  ``good'' lines, returning them as a list.

  In step 3, the [47mcollect$+[0m takes three arguments.  The first is a
  [47mlambda$[0m expression on the [47mloop$-gvars[0m and [47mloop$-ivars[0m as above.
  The second and third arguments are the global variable values and
  the ``good'' lines from the pared-down iteration variable table as
  computed by step 2.  Note that since the [47mcollect[0m clause does not
  mention any global variables the global variable tuple in the
  second argument of the [47mcollect$+[0m is [47mnil[0m.

  Of course, Common Lisp does not decompose the corresponding [47mloop[0m
  statement this way but generates much more efficient compiled code.

  The ACL2 semantics is rendered compositionally to make it easier to
  reason about [47mloop$[0m statements.  If the guards of the [47mloop$[0m
  statement --- which we haven't discussed yet --- are verified then
  the ACL2 loop$ statement is rendered into the corresponding Common
  Lisp [47mloop[0m statement, compiled, and efficiently executed.

  Now go to [lp-section-11] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-11
  (LOOP$-PRIMER)
  "Proving Theorems about [47mFOR[0m [47mLoop$[0ms


LP11: Proving Theorems about [47mFOR[0m [47mLoop$[0ms

  Proving theorems about [47mFOR[0m [47mloop$[0m in ACL2 is essentially no different
  than proving theorems about other constructs in ACL2.  Indeed,
  since [47mloop$[0ms turn into calls of [scion]s of [47m[apply$][0m, proving
  things about them is exactly the problem of proving things about
  scions.  However, [47mloop$[0ms raise some problems that are not fully
  technical.

    * Iteration is so common in programming --- and the meaning of [47mloop$[0m
      statements are intuitively obvious --- 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.

    * You're not syntactically aware of the presence of [47mapply$[0m and the
      concomitant need for [tame]ness and [warrant]s.

    * You don't see the translations of [47mloop$[0ms when you type them but they
      appear ``unexpectedly'' in the checkpoints of failing proofs
      and that can throw you for a loop (so to speak).

    * The translations of [47mloop$[0ms, especially of fancy [47mloop$[0m, are pretty
      complicated in and of themselves and can be difficult to
      understand, much less generalize and manipulate formally.

    * The ACL2 user rarely has to think about local variable bindings, but
      those issues arise quite often in dealing with loop$s (and
      nested [47mlambda[0m objects in general).

  With these points in mind we will now work through a proof about a
  fancy [47mloop$[0m.  In the next section we'll challenge you to do some
  proofs about other [47mloop$[0ms.  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.

  Sample Question: Define the function [47mall-pairs[0m recursively so that
  [47m(all-pairs imax jmax)[0m creates a list of all pairs [47m(i . j)[0m where [47m1
  <= i <= imax[0m and [47m1 <= j <= jmax[0m.  Then define the [47mloop$[0m version of
  [47mall-pairs[0m and prove it is equivalent to [47mall-pairs[0m.  Both versions
  must be guard verified.

  Sample Solution (as a narrative of the discovery).

  As usual, we make sure we're operating in a session where

    (include-book \"projects/apply/top\" :dir :system)

  We will construct our pairs with

    (defun make-pair (i j)
      (declare (xargs :guard t))
      (cons i j))

  Here is our recursive definition.  It involves two helper functions.
  [47mAll-pairs-helper2[0m keeps [47mi[0m fixed and runs [47mj[0m from [47m1[0m to [47mjmax[0m to
  compute the list of pairs [47m((i . 1) (i . 2) ... (i . jmax))[0m.
  [47mAll-pairs-helper1[0m just calls the former helper for each [47mi[0m from [47m1[0m to
  [47mimax[0m and appends the lists together.  The top-level [47mall-pairs[0m calls
  [47mall-pairs-helper1[0m with [47mi[0m properly initialized to [47m1[0m.

    (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))

  Here is a simple test.

    ACL2 !>(all-pairs 2 4)
    ((1 . 1)
     (1 . 2)
     (1 . 3)
     (1 . 4)
     (2 . 1)
     (2 . 2)
     (2 . 3)
     (2 . 4))

  And here is our first attempt to define the [47mloop$[0m version, which is
  considerably ``simpler'' (or, at least, shorter).  But this will
  fail!  Can you say why without reading the error message?

    (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))).

  The error message above includes some extraneous possible explanation
  of the error which we've omitted.

  The error tells us we forgot to assign a badge to [47mmake-pair[0m.  We
  could call [47m(defbadge make-pair)[0m at this point.  But since we intend
  to prove things about [47mall-pairs-loop$[0m we'll actually need the
  warrant for the [47mmake-pair[0m, since [47mmake-pair[0m is user-defined and is
  used in the body of a [47mloop$[0m.  So we'll go ahead and create the
  warrant.

    (defwarrant make-pair)

  (Had we just badged [47mmake-pair[0m at this point and proceeded another
  error message would crop up in due course and tell us to warrant
  it.)

  Trying the [47mdefun[0m again causes another failure with the checkpoint
  shown below.

    (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.

  We need to prove, as part of the guard verification, that [47m(CAR
  LOOP$-GVARS)[0m is an integer.  At this point we might want to refresh
  our idea of what the formal semantics of that nested loop$ is!

  We do not recommend using [47m:trans[0m 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
  [47m:tca[0m (``translate, clean, and annotate'') which produces about half
  as much output and shows the original form of each [47mloop$[0m together
  with formal semantics, complete with [47m:guard[0m declarations on the
  [47mLAMBDA[0m objects and correspondences between the variable names used
  in the original statement with the components of the formals
  [47mLOOP$-GVARS[0m and [47mLOOP$-IVARS[0m in the [47mlambda$[0m terms generated.

  (Note: We have manually inserted some comments to identify certain
  lines of the display below.)

    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]

  We're trying to verify the guards all the functions in that
  expression, and we have the [47m:guard[0m in the [47mdefun[0m of [47mall-pairs-loop$[0m
  to work with.  That [47m:guard[0m is [47m(and (natp imax) (natp jmax))[0m.

  So what functions above require an argument to be an integer?  Hint:
  There is only one such function but it occurs in two places.

  [47mFrom-to-by[0m requires all three of its arguments to be integers and
  that function appears on lines [4] and [6].  Line [4] requires [47mjmax[0m
  to be an integer and line [6] requires [47mimax[0m to be an integer.  But
  line [6] is the formal term representing the ``[47mfrom 1 to imax[0m''
  range of the [47mappend[0m [47mloop$[0m formalized with the fancy scion [47mAPPEND$+[0m
  at line [0].  That [47mimax[0m is literally the first formal variable of
  the defun of [47mall-pairs-loop$[0m whose [47m:guard[0m says [47mimax[0m and [47mjmax[0m are a
  naturals.  So [6] is not the problem.

  The [47mjmax[0m in line [4], on the other hand, is actually a [47mlet[0m-bound
  variable (see line [3]) within the [47mlambda[0m object (line [1]) that is
  the body of the [47mappend[0m loop$ [line 0].  [47mjmax[0m is bound inside that
  [47mlambda[0m on line [3] to [47m(car loop$-gvars)[0m and the [47m:guard[0m (line [2])
  of that [47mlambda[0m does not require [47m(car loop$-gvars)[0m to be an integer.
  We need to add that requirement to [2].

  So how do we change the [47m:guard[0m of a [47mlambda[0m generated by the
  translation of the [47mappend[0m [47mloop$[0m?  We add ``[47m:guard (natp jmax)[0m''
  after the [47mappend[0m operator.  (Note that [47m(integerp jmax)[0m would
  suffice here but we added the stronger condition ensured by the
  [47mall-pairs-loop$[0m's guard.)

  Using [47m:tca[0m again on the modified [47mloop$[0m confirms our change.

    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]

  Observe the difference between the [47m:guard[0m on the original line [2]
  and the [47m:guard[0m on the new line [2'].  The latter includes [47m(natp
  (car loop$-gvars))[0m.

  If we think in terms of scions, we're saying ``Every time this [47mlambda[0m
  object is applied, its two formals must satisfy the conjunction
  beginning at line [2'].''

  Finally, how do we know every application of the [47mlambda[0m by the fancy
  scion [47mappend$+[0m (line [0]) will satisfy this guard?  We know from
  the definition of [47mappend$+[0m that every application supplies the
  [47m(list jmax)[0m from line [5] as the value of [47mloop$-gvars[0m.  That
  occurrence of [47mjmax[0m is at the top-level of the body and in the scope
  of the guard of [47mall-pairs-loop$[0m, which says [47mjmax[0m is a natural.  So
  the guards can be proved now.

  So now we can admit and verify the guards of our [47mloop$[0m version of
  [47mall-pairs[0m.

    (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))))

  Our goal is to prove the theorem below.  We use [The-Method], with
  which we assume you're familiar but which we narrate below.

  First we try to prove our main goal.  It fails with the checkpoint
  shown.

    (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)))

  Looking at the conclusion we see need to prove that the [47mappend$+[0m term
  is equal to the [47mall-pairs-helper1[0m term.  From our ACL2 experience
  with recursive functions like [47mall-pairs-helper1[0m we know this is an
  inductive proof.  But no induction is suggested by
  [47m(all-pairs-helper1 1 imax jmax)[0m because the constant [47m1[0m is in a
  controller position.  We need to generalize the [47m1[0m by replacing it
  with [47mi0[0m, a general initial value of [47mi[0m.  Note that we replace the [47m1[0m
  in two places, namely, the first [47m1[0m in [47m(loop$-as (list (from-to-by 1
  imax 1)))[0m, and the [47m1[0m in [47m(all-pairs-helper1 1 imax jmax)[0m.  Those two
  [47m1[0ms are the concrete initial values of two [47mi[0m counters on opposite
  sides of the equality.  There are three other occurrences of the
  number [47m1[0m in the conjecture.  The first one is the initial value of
  the variable [47mj[0m, the second is the step size for counting up from [47mj[0m
  to [47mjmax[0m, and the third one is the step size for counting up from [47mi[0m
  to [47mimax[0m.  We do not change those three occurrences of [47mi[0m.

  We submit the proposed generalization as [47mlemma1[0m.  The conclusion of
  [47mlemma1[0m is exactly the equality conclusion above except for the
  replacement of those two [47m1[0ms by the new variable [47mi0[0m.  The hypothesis
  of [47mlemma1[0m requires all the variables to be naturals.  But the proof
  attempt fails!  The checkpoint is shown below.

    (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))))

  Notice that we're trying to prove something of the form

    (EQUAL (APPEND a1 b1)
           (APPEND a2 b2))

  where [47mb1[0m and [47mb2[0m are identical.  So we will prove [47m(EQUAL a1 a2)[0m.

  But again, this is inductive.  The [47m(from-to-by 1 jmax 1)[0m and the
  [47m(all-pairs-helper2 i0 1 jmax)[0m are both counting up from [47m1[0m as the
  initial value of [47mj[0m.  We need to generalize those [47m1[0ms to [47mj0[0m.  So we
  submit the following as [47mlemma2[0m.  And it succeeds!

    (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))))

  So now we return to [47mlemma1[0m, whose checkpoint suggested [47mlemma2[0m.  But
  it fails again, this time with a different checkpoint

    (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$+)

  Note that this checkpoint comes from a forcing round (the clue is the
  ``[47m[1][0m prefix to the [47mGoal[0m), 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 [47mcollect$+[0m.  We need the warrant for [47mcollect$+[0m because
  that function is being applied with [47mapply$[0m every time [47mappend$+[0m
  iterates.  This is easy to fix.  We just add the warrant as a
  hypothesis to [47mlemma1[0m.

    (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))))

  This proof succeeds.

  So now we return to [47mmain[0m.  By the way, because we expect the theorem
  to be proved by applying [47mlemma1[0m, we provide the hint that tells the
  prover not to even try induction.  This just reduces the output if
  the proof fails.

  Unfortunately this attempt fails, but with two easy-to-fix
  checkpoints.

    (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$+)

  Note that the checkpoints are forcing round subgoals showing that we
  need two warrants.  So we add both warrants to [47mmain[0m's hypotheses.
  And we're done.

    (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)))

  Note: The [47m:do-not-induct[0m hint could be deleted because the theorem is
  proved without appealing to induction anyway.

  You might wonder why we need the warrant on [47mmake-pairs[0m.  It never
  arose in any checkpoint except in the very last failed proof.

  The first time we tried to prove [47mmain[0m we failed, and got this
  checkpoint.

    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)))

  The innermost [47mlambda$[0m is the body of the innermost [47mloop$[0m statement,
  [47m(loop$ for j from 1 to jmax collect (make-pair i j))[0m, except it has
  been simplified by the expansion of [47m(make-pair i j)[0m to [47m(cons i j)[0m.
  That expansion of [47mmake-pair[0m inside a [47mlambda$[0m required the warrant
  for [47mmake-pair[0m and that was forced to produce the [47mcons[0m.

  Had that first proof attempt at [47mmain[0m succeeded except for that forced
  subgoal, a forcing round would have brought to our attention the
  need for the warrant on [47mmake-pair[0m.  But that proof attempt failed
  because the prover could not do a suitable induction to prove
  [47mGoal''[0m.  Indeed, that is what led us to [47mlemma1[0m.

  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 [47mmake-pair[0m.  In the penultimate failed proof [47mmain[0m just
  above, the same forced expansion of [47mmake-pair[0m occurred and this
  time the proof succeeded except for the forced subgoals requiring
  warrants for [47mmake-pair[0m and [47mcollect$+[0m.  That finally brought the
  [47mmake-pair[0m expansion to our attention.

  The more experienced ACL2 user would have noticed (indeed, did
  notice!)  the expansion of [47mmake-pair[0m in [47mGoal''[0m above and understood
  the warrant for [47mmake-pair[0m was needed but wanted to see what would
  happen if that fact was overlooked.

  The final series of events to solve this problem is shown below.

    ; 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))))

  Now go to [lp-section-12] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-12
  (LOOP$-PRIMER)
  "Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms


LP12: Challenge Proof Problems about [47mFOR[0m [47mLoop$[0ms

  If you have not already, warm up by proving the correctness of your
  solutions to the problems in [lp-section-8].

  Remember to operate in a session in which you have included the
  standard [47mloop$[0m book.

    (include-book \"projects/apply/top\" :dir :system)

  Our answers to the problems in [lp-section-8] are in
  [community-books] file [47mdemos/loop-primer/lp8.lisp[0m, and our answers
  to the problems below are in [community-books] file
  [47mdemos/loop-primer/lp12.lisp[0m.

------------------------------
  [31;1mLP12-1[0m Define [47m(assoc-equal-loop$ x alist)[0m to be equal to [47m(assoc-equal
  x alist)[0m when [47m(alistp alist)[0m.  Verify the guards of
  [47massoc-equal-loop$[0m and prove that your function satisfies the
  specification above.  Is your function in fact unconditionally
  equal to [47massoc-equal[0m?  If so, prove it; if not, show a
  counterexample.

------------------------------
  [31;1mLP12-2[0m Under what conditions is the following a theorem?  Fill in the
  blank and prove the theorem.

    (defthm LP12-2
      (implies ...
               (equal (loop$ for x in keys as y in vals collect (cons x y))
                      (pairlis$ keys vals)))
      :rule-classes nil)

------------------------------
  [31;1mLP12-3[0m Prove

    (defthm LP12-3
      (equal (* 2 (len (loop$ for tl on lst append tl)))
             (* (len lst) (+ (len lst) 1))))

  [3mHint:[0m 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 ``heavy duty'' 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.

------------------------------
  [31;1mLP12-4[0m Define

    (defun nats (n)
      (cond ((zp n) (list 0))
            (t (append (nats (- n 1)) (list n)))))

  and prove that the obvious [47mloop$[0m statement is equivalent to [47m(nats n)[0m
  when [47mn[0m is a natural.  Make your [47mdefthm[0m have [47m:rule-classes nil[0m so as
  not to interfere with your work on the next problem.

------------------------------
  [31;1mLP12-5[0m Define

    (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))))))

  Prove

    (defthm LP12-5
      (implies (natp n)
               (equal (loop$ for i from 0 to n collect i)
                      (nats-up 0 n)))
      :rule-classes nil)

------------------------------
  [31;1mLP12-6[0m Fill in the blanks below and prove the theorem.  You may need
  hints.  If not, just delete the :hints setting.

    (defthm LP12-6
      (implies (true-listp lst)
               (equal (loop$ ...)
                      (strip-cars lst)))
      :hints ...
      :rule-classes nil)

------------------------------
  [31;1mLP12-7[0m Prove the following, adding hints if necessary.  Otherwise,
  just delete the [47m:hints[0m setting.

    (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 ...)

------------------------------
  [31;1mLP12-8[0m Fill in the blanks below and then prove the theorem.  You may
  need hints.  If not, just delete the [47m:hints[0m setting.

    (defthm LP12-8
      (implies (natp n)
               (equal (loop$ ...)
                      (nth n lst)))
      :hints ...
      :rule-classes nil)

  Now go to [lp-section-13] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-13
  (LOOP$-PRIMER)
  "Examples of [47mDO[0m [47mLoop$[0ms


LP13: Examples of [47mDO[0m [47mLoop$[0ms

  Below is a log of an ACL2 session demonstrating the behavior of a few
  [47mDO[0m [47mloop$[0ms.  As usual with [47mloop$[0ms, 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 [47mDO[0m [47mloop$[0ms.

  We'll describe the syntax and semantics of [47mDO[0m [47mloop$[0ms later.  But we
  expect you can intuit the syntax and semantics of these [47mloop$[0m
  statements from these examples.  The following may help if you're
  unfamiliar with the following Common Lisp primitives.

  In ACL2, [31;1mThese primitives may only be used within [47mDO[0m[31;1m [47mloop$[0m[31;1ms![0m

    * [47m(RETURN [0m[3mexpr[0m[47m)[0m terminates the [47mloop$[0m and returns the value of [3mexpr[0m as
      the value.

    * [47m(SETQ [0m[3mvar expr[0m[47m)[0m evaluates [3mexpr[0m and assigns the value to the variable
      [3mvar[0m.  Parallel assignment with [47mmv-setq[0m is also supported but
      not illustrated here.

    * [47m(PROGN [0m[3mstmt_1 ... stmt_n[0m[47m)[0m evaluates each [3mstmt_i[0m in turn and returns
      the value of the last one.

    * [47m(LOOP-FINISH)[0m terminates the iteration in the [47mloop$[0m and passes
      control to the [47mFINALLY[0m clause, if any.

  We start the session with the following commands, whose output we do
  not display here.  Note that we use [47m[defstobj][0m to introduce a
  single-threaded object, [47mst[0m, with one field, [47mfld1[0m.  We initialize
  [47m(fld1 st)[0m to 0. In addition, we warrant two of the functions
  introduced by the [47m[defstobj][0m.  We warrant those functions because
  they are user-defined [47m:logic[0m mode functions that we'll use in a [47mDO[0m
  [47mloop$[0m.  [47mDefstobj[0m does not automatically badge or warrant the
  functions it defines but they are warrantable.

    (include-book \"projects/apply/top\" :dir :system)
    (defstobj st fld1)
    (update-fld1 0 st)
    (defwarrant fld1)
    (defwarrant update-fld1)

  So having set up our session, we now experiment with [47mDO[0m [47mloop$[0ms.

    ; 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

  We included the last example showing that stobjs can be used inside
  of [47mDO[0m [47mloop$[0ms just to alert you to that feature.  However, in the
  rest of this primer we do not deal with stobjs in [47mloop$[0m because
  there is enough to cover without that!

  See the ACL2 documentation topic [DO-loop$] for a more thorough
  discussion of [47mDO[0m [47mloop$[0ms.

  Now go to [lp-section-14] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-14
  (LOOP$-PRIMER)
  "Challenge Problems about [47mDO[0m [47mLoop$[0ms


LP14: Challenge Problems about [47mDO[0m [47mLoop$[0ms

  In this section you'll be asked to write and evaluate some [47mDO[0m [47mloop$[0ms
  based entirely on the examples given in the previous section.
  We'll deal with termination, guards, proofs, etc., later.

  We want all iteration in your answers to be done with [47mDO[0m [47mloop$[0ms even
  if the problem could be solved with a [47mFOR[0m [47mloop$[0m.

  Our answers to the problems in this section are in [community-books]
  file [47mdemos/loop-primer/lp14.lisp[0m.

------------------------------
  [31;1mLP14-1:[0m Make a list of the integers from 10 down to 0.

  [31;1mExpected Value:[0m[47m(10 9 8 7 6 5 4 3 2 1 0)[0m

  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

    (loop$ with ans = '(10 9 8 7 6 5 4 3 2 1 0) do (return ans))

  But the spirit of these questions is to use iteration and, if it
  helps, imagine we'd asked you to write a [47mloop$[0m that returns the
  list of integers from 1000000 down to 0!

------------------------------
  [31;1mLP14-2:[0m Sum the naturals less than or equal to 100.

  [31;1mExpected Value:[0m [47m5050[0m

  Hint: Write the [47mloop$[0m so that it counts down!  If you count up you'll
  have to provide a measure term, which can be done by including
  [47m:measure[0m [3mmeasure-term[0m immediately after the [47mDO[0m operand and before
  the body.

------------------------------
  [31;1mLP14-3:[0m Sum the squares of the naturals less than or equal to 100,
  using the following function to square.

    (defun sq (x) (* x x))

  [31;1mExpected Value:[0m [47m338350[0m

------------------------------
  [31;1mLP14-4:[0m Write a [47mDO[0m that finds the first occurrence of the symbol [47mXXX[0m
  in the list [47m'(A B C XXX D E F)[0m and returns the tail of the list
  starting with that occurrence.

  [31;1mExpected Value:[0m [47m(XXX D E F)[0m

------------------------------
  [31;1mLP14-5:[0m 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).

    (defun do-loop$-member (e lst)
      (loop$ ...))

    (defthm lp14-5
      (equal (do-loop$-member e lst)
             (member e lst))
      :rule-classes nil)

------------------------------
  [31;1mLP14-6:[0m Given the following

    (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)))))

  fill in the blank so that this is a theorem.

    (defthm lp14-6
      (equal (loop$ ...)
             (steps-for-member e lst steps))
      :rule-classes nil)

------------------------------
  [31;1mLP14-7:[0mWrite a [47mDO[0m to compute the list of all pairs [47m(i . j)[0m such that
  1 <= [47mi[0m <= 3 and 1 <= [47mj[0m <= 4.

  [31;1mExpected Value:[0m

    ((1 . 1)
     (1 . 2)
     (1 . 3)
     (1 . 4)
     (2 . 1)
     (2 . 2)
     (2 . 3)
     (2 . 4)
     (3 . 1)
     (3 . 2)
     (3 . 3)
     (3 . 4))

------------------------------
  Now go to [lp-section-15] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-15
  (LOOP$-PRIMER)
  "Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms


LP15: Informal Syntax and Semantics of [47mDO[0m [47mLoop$[0ms

  The ``most elaborate'' [47mDO[0m [47mloop$[0m looks like this.

    (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)

  where much of that is optional: ``[47mOF-TYPE speci[0m'', ``[47m= initi[0m'' (when
  ``[47mOF-TYPE speci[0m'' is present), ``[47m:MEASURE m[0m'', the two ``[47m:GUARD[0m
  ...'' clauses, ``[47m:VALUES v[0m'', and ``[47mFINALLY fin-body[0m''.  If the
  [47m:MEASURE[0m is omitted, ACL2 tries to guess a likely measure using the
  same heuristic it does with recursive [47m[defun][0ms.  If [47m:VALUES[0m is
  omitted then [47mv[0m defaults to [47m(nil)[0m.

  All ACL2 function symbols in [47mm[0m, [47mdo-body[0m, and [47mfin-body[0m must be
  [badge]d so [47m[apply$][0m can handle them.  Furthermore, they must be
  [warrant]ed if proofs are to be done about them or if they are in
  [logic] mode and are called during evaluation.

  As you've already inferred from our examples, [47mdo-body[0m and [47mfin-body[0m
  are not normal ACL2 terms!  They allow restricted uses of [47mRETURN[0m,
  [47mPROGN[0m, [47mSETQ[0m, [47mMV-SETQ[0m, and [47mLOOP-FINISH[0m.

  As for semantics, every legal [47mDO[0m [47mloop$[0m translates into a term of the
  form

    (DO$ m-lambda
         alist
         do-body-lambda
         fin-body-lambda
         a5
         a6)

  where [47mm-lambda[0m, [47mdo-body-lambda[0m, and [47mfin-body-lambda[0m are quoted [47mLAMBDA[0m
  objects derived from the respective terms in the [47mloop$[0m statement.
  [47mAlist[0m is an association list that maps the variables of those terms
  to their initial values.  We discuss the other three arguments
  later.

  All three of these [47mLAMBDA[0m objects operate on [47malist[0m.  The [47mm-lambda[0m 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 [47mLAMBDA[0m objects return a triple
  of the form [47m(exit-token value new-alist)[0m.  The [47mexit-token[0m is
  [47m:RETURN[0m, [47m:LOOP-FINISH[0m, or [47mNIL[0m, and indicates what happens next: the
  [47mvalue[0m is to be returned as the value of the [47mloop$[0m, the
  [47mfin-body-lambda[0m is to be applied to the [47mnew-alist[0m, or the [47mloop$[0m is
  to iterate again on [47mnew-alist[0m.  But before the iteration, the
  [47mm-lambda[0m is applied to the [47mnew-alist[0m and must be of smaller measure
  according to [47m[l<][0m for iteration to continue.

  If the given measure fails to decrease, then, logically speaking, [47ma5[0m
  is used to compute a default answer.  (That argument is actually
  the output signature of the [47mloop$[0m specifying how many values are to
  be returned and whether each value is an ordinary object, a
  double-float, or a [stobj].)  However, in execution, an error is
  signaled if the measure fails to decrease.  Such runtime errors
  (including [47mOF-TYPE[0m and guard violations if guards are being
  checked) are reported using [47ma6[0m which is just a quoted constant
  about the original [47mloop$[0m statement.  (In fact, [47ma6[0m is logically
  irrelevant and the theorem prover replaces quoted non-[47mnil[0m final
  argument to [47mdo$[0m by [47mnil[0m in proofs as part of the cleaning-up
  process.)

  Consider this simple [47mDO[0m [47mloop$[0m and its cleaned-up semantics as shown
  by the [47m:[0m[47m[tcp][0m command.  (We have re-pretty-printed it to add
  comments and highlight some symmetries.)

      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)

  [47mASSOC-EQ-SAFE[0m is just [47mASSOC-EQ[0m with a slightly weaker guard.  Think
  of [47m(CDR (ASSOC-EQ-SAFE 'var ALIST))[0m as the current value of the
  local variable [47mvar[0m.  The measure is that the [47mACL2-COUNT[0m of the
  current value of [47mI[0m decreases.  The output of the [47mdo-body[0m [47mlambda[0m is
  a triple.  The true branch of the [47mIF[0m indicate iteration is to stop
  and return the current value of [47mANS[0m.  The false branch indicates
  iteration is to continue with the new alist given as the third
  element of the triple.  The [47mfin-body[0m [47mlambda[0m is irrelevant because
  there is no [47m:LOOP-FINISH[0m exit in the do-body.

  Of course, the semantics of [47mdo$[0m is explicit in its definition.  So
  you might want to execute [47m:pe do$[0m in your ACL2 session and just
  read how [47mdo$[0m operates.

  We realize the above descriptions are pretty sketchy.  But in the
  coming discussions and proof problems we'll limit ourselves to [47mDO[0m
  [47mloop$[0ms without [47mof-type[0ms or [47mguards[0m, they'll all return single
  non-[47m[stobj][0m values so the [47m:values[0m option won't be needed, and you
  won't really need to use the [47mfinally[0m clause or any fancier bodies
  than we show in our examples.

  For more details about both the syntax and semantics of [47mDO[0m [47mloop$[0ms see
  [do-loop$].  [31;1mBut beware!  That link takes you out of the [47mloop$[0m[31;1m
  primer![0m To get back here either use your browser's ``back'' button
  or remember to return to [47mlp-section-15[0m!

  Now go to [lp-section-16] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-16
  (LOOP$-PRIMER)
  "Proving Theorems about [47mDO[0m [47mLoop$[0ms


LP16: Proving Theorems about [47mDO[0m [47mLoop$[0ms

  Let's prove a theorem about a [47mDO[0m [47mloop$[0m.  Specifically, let's prove

    (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)))

  A few words of warning are appropriate.

    * The Method (see [the-method]) is a good way to proceed: try to prove
      the theorem expecting it to fail and look at the checkpoints.

    * Unsurprisingly, the theorem above has to be [3mgeneralized[0m before it can
      be proved.  But it can feel strange to generalize a [47mloop$[0m.

    * If we prove a lemma that rewrites a [47mloop$[0m 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 [47mlambda[0m objects.  The most common changes are that
      non-recursive functions are generally expanded (depending on
      the theory in use) and [47mIF[0ms are normalized.  That means we need
      to normalize the bodies of any [47mloop$[0m we use in a lemma if we
      expect that lemma to match a term being rewritten!  This
      observation is relevant here because [47m[zp][0m is non-recursively
      defined and so will expand when the body of the [47mloop$[0m above is
      rewritten.

    * ACL2 does not display [47mdo$[0m terms as [47mDO[0m [47mloop$[0ms.  So get used to reading
      [47mdo$[0m terms and thinking of [47mloop$[0m statements!  (We may fix this
      someday but at the moment we find it advantageous to really see
      the terms the prover is dealing with!)

  [31;1mA Tedious Recipe for Proving Theorems about [47mDO[0m[31;1m [47mLoop$[0m[31;1ms[0m

  When you first start proving theorems about [47mDO[0m [47mloop$[0ms it might be
  helpful to follow the tedious recipe below.  It will familiarize
  you with the semantics of [47mDO[0m [47mloop$[0ms and teach you certain
  techniques that are easy applications of lessons you've already
  internalized as an experienced ACL2 user, albeit one unfamiliar
  with [47mloop$[0m.  But after a little experience you'll find it
  straightforward to skip some steps!

    * Use The Method to find the normal form of the [47mloop$[0m.

    * Define a recursive function that computes the value of the [47mloop$[0m
      using the same algorithm as the [47mloop$[0m. This function can serve
      two purposes.  First, it can be an intermediate stop on the way
      to proving that the [47mloop$[0m 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 [47mDO[0m
      [47mloop$[0ms.

    * Prove that the [47mloop$[0m computes the same value as the function.  We
      frequently refer to this as ``lemma 1'' in the recipe.
      Generally you will have to generalize the [47mloop$[0m to prove it by
      the induction suggested by the function.  And you will have to
      write the normal form of the [47mloop$[0m body instead of the
      ``pretty'' form used in the main theorem so this lemma can be
      used to hit the rewritten [47mloop$[0m in the proof of the main
      theorem later.

    * Prove that the function satisfies the specification.  We frequently
      refer to this as ``lemma 2''.

    * Prove that the [47mloop$[0m satisfies the specification by chaining together
      the two lemmas.

  Of course, as with all ``recipes'', sometimes you have to adjust
  depending on the ingredients at hand.  Sometimes you can just write
  the body of the [47mloop$[0m in normal form to begin with.  Sometimes you
  do not have to define a special function because the [47mloop$[0m itself
  or a function already in the conjecture suggests an appropriate
  induction.  Sometimes you may find it easier to copy the [47mdo$[0m form
  revealed by The Method into your statement of lemma 1 and
  generalize that form, rather than try to express lemma 1 as a
  [47mloop$[0m.  You may also be content to skip the ``intermediate stop''
  of lemma 1 altogether and prove that the [47mloop$[0m satisfies a
  generalized specification, sometimes providing an [47m:induct[0m 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.

  We're going to prove the theorem

    (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)))

  both ways, first by following the tedious recipe, and then the way a
  user familiar with [47mDO[0m [47mloop$[0m proofs might do it.

  So here goes!  Following the recipe to prove [47mmain[0m above, we first try
  The Method.  The prover tries an induction suggested by the [47mDO[0m
  [47mloop$[0m, namely induction on [47mN[0m by [47m-1[0m, but without instantiating [47mANS[0m
  because the initial value of [47mANS[0m is the constant [47m0[0m.  We know this
  proof will fail and it does.  The pre-induction checkpoint is shown
  below.

    *** 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))

  Look carefully at the [47mdo-body[0m [47mlambda[0m, the second [47mlambda[0m object in the
  [47mdo$[0m.  The [47m(ZP I)[0m in our original [47mDO[0m [47mloop$[0m has opened up,
  introducing [47m(INTEGERP i)[0m and [47m(< 0 i)[0m and [47mIF[0m normalization -- except
  instead of seeing the simple variable [47mI[0m we see its current value in
  the [47mALIST[0m being computed on each iteration.

  [31;1mThis is valuable information! It tells us what the rewritten body of
  the [47mloop$[0m[31;1m looks like in the theory in which our proof is being
  conducted.  If we prove a [47m:rewrite[0m[31;1m rule expecting it to fire during
  the proof of our [47mmain[0m[31;1m theorem, its body must match that shown
  above![0m

  Now we define the recursive function that is supposed to be
  operationally equivalent to the [47mloop$[0m.  This will suggest the
  induction.

    (defun copy-nat-ac (i ans)
      (if (zp i)
          ans
          (copy-nat-ac (- i 1)
                       (+ 1 ans))))

  Next comes the hard part.  We state the lemma that equates the [47mloop$[0m
  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 [47mDO$[0m of course, but with a little
  practice you can usually ``reverse engineer'' the desired lemma
  into a [47mloop$[0m.  So here is the so-called ``lemma 1''.

    (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))))

  Note that we generalized the initial value of [47mans[0m in the [47mloop$[0m from [47m0[0m
  to [47mans0[0m and used [47mans0[0m as the accumulator in [47m(copy-nat-ac n ans0)[0m.

  By the way, we could have written [47mlemma1[0m in terms of the [47mDO$[0m term
  shown in the checkpoint, rather than as a [47mloop$[0m.  But we have to
  generalize that [47m0[0m whether we use a [47mloop$[0m or the [47mDO$[0m term.  The
  generalized [47mDO$[0m form of [47mlemma1[0m is

    (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 'ans ans0)) ; 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)))).

  The UPPERCASE part above was just copied from the checkpoint and then
  the pair in the initial alist binding [47mANS[0m, which was [47m'(ANS . 0)[0m,
  was replaced by [47m(cons 'ans ans0)[0m.  So while it looks messy, it's
  not hard to enter.  Furthermore, it saves us from having to figure
  out the normal form --- it's already in the checkpoint.  The [47mDO$[0m
  term in this version of [47mlemma1[0m is just the formal translation of
  the generalized [47mDO[0m [47mloop$[0m we wrote in the earlier version of [47mlemma1[0m.

  Next we prove ``lemma 2'' equating the recursive function with the
  (generalized) specification.  This theorem does not involve [47mloop$[0m
  and its proof should be utterly familiar to you.

    (defthm lemma2
      (implies (and (natp n)
                    (natp ans0))
               (equal (copy-nat-ac n ans0)
                      (+ n ans0))))

  Finally, we prove our main theorem.

    (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)))

  The proof rewrites the ``pretty'' [47mdo-body[0m [47mlambda[0m into the normal
  form, [47mlemma1[0m rewrites the new form of the [47mloop$[0m after instantiating
  [47mans0[0m to [47m0[0m, to [47m(copy-nat-ac n 0)[0m, then [47mlemma2[0m hits that to [47m(+ n 0)[0m,
  and arithmetic does the rest.

  As we noted, our recipe is overly rigid.  Here is another sequence of
  events that proves [47mmain[0m.  The experienced user realizes that the
  generalized [47mDO[0m [47mloop$[0m will in fact suggest the appropriate induction
  to ACL2.  So no special function is introduced.  Furthermore, the
  user --- who has proved several theorems about [47mloop$[0ms involving [47mIF[0m
  and [47mZP[0m will know how to write the normal form.  That user would
  just do this.

    (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)))

  For more details about rewriting [47mlambda[0m objects you can leave the
  [47mloop$[0m primer and read [rewrite-lambda-object] and
  [rewriting-versus-cleaning-up-lambda-objects].  But remember to
  come [31;1mback[0m here to [47mlp-section-16[0m!

  Now go to [lp-section-17] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-17
  (LOOP$-PRIMER)
  "Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms


LP17: Challenge Proof Problems for [47mDO[0m [47mLoop$[0ms

  In the following problems please write [47mDO[0m [47mloop$[0ms even though some of
  the problems can be solved with [47mFOR[0m [47mloop$[0ms.

  Our answers to the problems in this section are in [community-books]
  file [47mdemos/loop-primer/lp17.lisp[0m.

------------------------------
  [31;1mLP17-1:[0m Write a [47mDO[0m [47mloop$[0m that reverses the list [47mlst[0m.  For example, if
  [47mlst[0m is [47m(A B C)[0m the result should be [47m(C B A)[0m.  Prove that your [47mDO[0m
  [47mloop$[0m is equal to [47m(rev lst)[0m, where

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

------------------------------
  [31;1mLP17-2:[0m Write a [47mDO[0m [47mloop$[0m that computes [47m(member e lst)[0m and prove it
  correct.

  [31;1mHint:[0m Sometimes the main theorem suggests the right induction on its
  own.

------------------------------
  [31;1mLP17-3:[0m Prove the following:

    (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)))

------------------------------
  [31;1mLP17-4:[0m Write a [47mDO[0m [47mloop$[0m that computes [47m(nth n lst)[0m, when [47mn[0m is a
  natural number.  Prove it correct.

------------------------------
  [31;1mLP17-5:[0m Prove the following.

    (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)))

------------------------------
  [31;1mLP17-6:[0m Prove the following.

    (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))))

------------------------------
  [31;1mLP17-7:[0m Write a [47mDO[0m [47mloop$[0m that computes [47m(fact n)[0m, for natural number
  [47mn[0m, where

    (defun fact (n)
      (if (zp n)
          1
          (* n (fact (- n 1)))))

------------------------------
  [31;1mLP17-8:[0m Write a [47mDO[0m [47mloop$[0m that scans a list of numbers, [47mlst[0m, once and
  returns the sum of the elements and the sum of the squares (with [47msq[0m
  as defined below) of the elements of [47mlst[0m as a cons pair.  E.g.,
  given [47m(1 2 3 4 5)[0m return [47m(cons (+ 1 2 3 4 5) (+ (sq 1) (sq 2) (sq
  3) (sq 4) (sq 5)))[0m = [47m(15 . 55)[0m.

  Prove that your do loop$ is equal to

    (cons (loop$ for e in lst sum e)
          (loop$ for e in lst sum (sq e)))

  Use the following definition of [47msq[0m.

    (defun sq (x) (* x x))

------------------------------
  [31;1mLP17-9:[0m Define [47m(partition-symbols lst)[0m with a [47mDO[0m [47mloop$[0m that
  partitions [47mlst[0m into two lists, one containing all the symbols in
  [47mlst[0m and the other containing all the non-symbols.  Return the cons
  of the two partitions and prove [47mpartition-symbols[0m correct.

  Hint: Since you are likely to collect the elements in reverse order,
  a suitable specification for these purposes is that
  [47mpartition-symbols[0m is equal to

    (cons (rev (loop$ for e in lst when (symbolp e) collect e))
          (rev (loop$ for e in lst when (not (symbolp e)) collect e)))

------------------------------
  [31;1mLP17-10:[0m Write a [47mDO[0m [47mloop$[0m that returns the list of naturals from [47mn[0m
  down to [47m0[0m, where [47mn[0m is a natural.  For example, if [47mn[0m is [47m10[0m the
  answer is [47m(10 9 8 7 6 5 4 3 2 1 0)[0m.  Prove that when [47mn[0m is a
  natural, your [47mDO[0m [47mloop$[0m returns the same thing as [47m(loop$ for i from
  0 to n collect (- n i))[0m.

  Hints: Remember that in order for your ``lemma1'' 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 [47mdo-body[0m
  [47mlambda[0m.  But it must also match the measure [47mlambda[0m.  So when you
  formulate your ``lemma1'', 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.)

------------------------------
  [31;1mLP17-11:[0m Define [47m(all-pairs-do-loop$ imax jmax)[0m to compute the same
  [47m(all-pairs imax jmax)[0m as was defined in section 11 (and below).
  But use [47mDO[0m [47mloop$s[0m instead of [47mFOR[0m [47mloop$[0ms in your definition of
  [47mall-pairs-do-loop$[0m.  Below we comment on what you should prove.

  The definition of [47mall-pairs[0m was as follows.

    (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))

  Hints: In following our advice on proving do loop$s you will define
  functions that compute the same things as your [47mDO[0m [47mloop$[0ms.  In our
  solution we called these two functions [47mapdh1[0m and [47mapdh2[0m, where
  ``[47mapdh[0m'' stands for @ldquo;[47mall-pairs-do-helper[0m''.  You will prove
  two ``[47mlemma1[0m'' theorems, one for each [47mloop$[0m.  The second of those
  theorems will establish allow you to prove that your
  [47mall-pairs-do-loop$[0m is [47mapdh1[0m.

  The next step in our recipe is to prove that the [47mapdh1[0m is [47mall-pairs[0m
  as above.  This will not involve [47mloop$[0ms of any sort.  It's just a
  normal proof about the relation between some recursively defined
  functions.  But we found this step surprisingly challenging!

  Since that second step does not involve [47mloop$[0ms, you may consider your
  answer correct if you just prove the two ``[47mlemma1[0m'' theorems!  But
  if you want a non-[47mloop$[0m challenge, finish the proof all the way to
  [47mall-pairs[0m.

  Now go to [lp-section-18] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-18
  (LOOP$-PRIMER)
  "Conclusion


LP18: Conclusion

  Here are two pieces of advice.

  First, if you can think of a good name for the concept implemented by
  a [47mloop$[0m statement, use [47mdefun[0m to define that name.  This is
  especially the case if you intend to reason about that [47mloop$[0m
  statement or to write more than one instance of it.

  For example, rather than write instances of

    (loop$ for a in x as b in y sum (* a b))

  it is better to define [47m(dot-product x y)[0m with that [47mloop$[0m as its body
  and then write calls of [47mdot-product[0m.

  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
  [47mloop$[0ms compute concepts with obvious, memorable names, but just
  because you can write ``anonymous'' iterations doesn't mean you
  should!

  Second, remember when you create a lemma intended to rewrite a [47mloop$[0m
  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 [47mendp[0m or [47mnfix[0m or [47mzp[0m term.  The lemma will
  never ``see'' 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 [47mloop$[0ms.

  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.

  Some relevant topics are

    * [47m[loop$][0m

    * [for-loop$]

    * [do-loop$]

    * [47m[lambda$][0m

    * [rewrite-lambda-object]

    * [stating-and-proving-lemmas-about-loop$s]

  The End of the [47mLoop$[0m Primer. (Return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-2
  (LOOP$-PRIMER)
  "[47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2


LP2: [47mLoop[0m in Common Lisp and [47mloop$[0m in ACL2

  The [47mloop[0m macro of Common Lisp was inspired by the ``iterative
  statements'' 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 ``DO loop.'' 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.

  ACL2's [47mloop$[0m facility supports a tiny subset of Common Lisp's [47mloop[0m
  statements.  It is hard to overstate how small the ACL2 subset is!
  For example, to manage iteration over a range of numbers, ACL2
  provides [47mFROM[0m, [47mTO[0m, and [47mBY[0m, but Common Lisp additionally provides
  [47mDOWNFROM[0m,[47mUPFROM[0m,[47mDOWNTO[0m,[47mUPTO[0m,[47mBELOW[0m,and [47mABOVE[0m.  For value
  accumulation, ACL2 supports [47mSUM[0m, [47mCOLLECT[0m, [47mAPPEND[0m, [47mALWAYS[0m, and
  [47mTHEREIS[0m, while Common Lisp also supports [47mNCONC[0m, [47mCOUNT[0m, [47mMAXIMIZE[0m,
  and [47mMINIMIZE[0m.  Even within its restricted subset, ACL2 syntax is
  less flexible regarding the order of the various ``clauses'' and
  the presence of, say, multiple accumulators.  The list of
  differences could go on and on because the Common Lisp facility is
  so elaborate.

  While many more Common Lisp [47mloop[0m features could be supported in ACL2,
  we believe it is best to test and refine the techniques reasoning
  about [47mloop$[0m before elaborating it further.

  Now go to [lp-section-3] (or return to the  Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-3
  (LOOP$-PRIMER)
  "Examples of [47mFOR[0m [47mLoop$[0ms


LP3: Examples of [47mFOR[0m [47mLoop$[0ms

  Below is the complete log of an ACL2 session demonstrating the
  behavior of [47mFOR[0m [47mloop$[0ms.  ACL2 also supports [47mDO[0m [47mloop$[0ms but they are
  not illustrated here.  Note that to use [47mloop$[0m 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 [47mloop$[0m expressions, or proofs about [47mloop$[0ms.

  We'll describe the syntax and semantics of [47mloop$[0m in the next two
  sections. But we expect you can intuit the syntax and semantics of
  [47mloop$[0m statements from these examples alone.  Please try!

    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))

  Now go to [lp-section-4] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-4
  (LOOP$-PRIMER)
  "Syntax of [47mFOR[0m [47mLoop$[0ms


LP4: Syntax of [47mFOR[0m [47mLoop$[0ms

  To describe the syntax of [47mFOR[0m [47mloop$[0ms we first describe the most
  elaborate [47mFOR[0m [47mloop$[0m.  Then we note which elements can be omitted.
  The most elaborate [47mFOR[0m [47mloop$[0m is of the form

  [47m(LOOP$ FOR [0m[3mv1[0m[47m OF-TYPE [0m[3mspec1 target1[0m
  [47mAS [0m   [3mv2[0m[47m OF-TYPE [0m[3mspec2 target2[0m
  ...
  [47mAS [0m   [3mvn[0m[47m OF-TYPE [0m[3mspecn targetn[0m
  [47mUNTIL :GUARD [0m[3mguard1 until-expr[0m
  [47mWHEN [0m   [47m:GUARD [0m[3mguard2 when-expr[0m
  [3mop[0m[47m :GUARD [0m[3mguard3 body-expr[0m[47m)[0m

  where

    * each [3mvi[0m   is a legal variable symbol, they are all distinct, and are
      collectively called the [3miteration variables[0m,

    * each [3mspeci[0m   is a [47m[type-spec][0m for the corresponding variable [3mvi[0m,

    * each [3mtargeti[0m is of one of the forms below and specifies the range of
      values to be taken by the corresponding variable [3mvi[0m.
      Abstractly you may think of the ``range'' here simply as a list
      of the values as described below, where [3mlist-expr[0m is a term
      (which is expected to evaluate to a true list), [3mlo-expr[0m and
      [3mhi-expr[0m are terms (which are expected to evaluate to integers),
      and [3mstep-expr[0m is a term (which is expected to evaluate to a
      positive integer).  In the examples given below, let [47mrv[0m be the
      list reverse function, so [47m(rv '(a b c))[0m is [47m(C B A)[0m.

        * [47mIN[0m [3mlist-expr[0m --- range is the value of [3mlist-expr[0m.  For example, the
          range of ``[47mIN[0m [47m(rv '(a b c))[0m'' is [47m(C B A)[0m.

        * [47mON[0m [3mlist-expr[0m --- range is the list of successive non-[47mnil[0m tails of the
          value of [3mlist-expr[0m.  For example, the range of ``[47mON[0m [47m(rv '(a
          b c))[0m'' is [47m((C B A) (B A) (A))[0m.  The range value is
          produced by [47m(TAILS [0m[3mlist-expr[0m[47m)[0m.

        * [47mFROM[0m [3mlo-expr[0m [47mTO[0m [3mhi-expr[0m [47mBY[0m [3mstep-expr[0m --- If ``[47mBY[0m [3mstep-expr[0m'' is
          omitted, ``[47mBY 1[0m'' is used.  The range contains all the
          integers from the value of [3mlo-expr[0m to the greatest integer
          less than or equal to the value of [3mhi-expr[0m such that each
          is separated from its higher neighbor by the value of
          [3mstep-expr[0m.  For example, the range of ``[47mFROM[0m 1 [47mTO[0m 10 [47mBY[0m 2''
          is [47m(1 3 5 7 9)[0m.  The range value is produced by [47m(FROM-TO-BY
          [0m[3mlo-expr[0m [3mhi-expr[0m [3mstep-expr[0m[47m)[0m.

    * each [3mguardi[0m is a term,

    * each [3muntil-expr[0m, [3mwhen-expr[0m, and [3mbody-expr[0m   is a [47m[tame][0m term, and

    * [3mop[0m   is one of the [3moperators[0m   [47mSUM[0m, [47mCOLLECT[0m, [47mAPPEND[0m, [47mALWAYS[0m, or
      [47mTHEREIS[0m.

  The symbols [47mFOR[0m, [47mIN[0m, [47mON[0m, [47mFROM[0m, [47mTO[0m, [47mBY[0m, [47mOF-TYPE[0m, [47mWHEN[0m, [47mUNTIL[0m, [47mSUM[0m,
  [47mCOLLECT[0m, [47mAPPEND[0m, [47mALWAYS[0m, and [47mTHEREIS[0m when used in [47mloop$[0m statements
  may be in any package.

  Common Lisp prohibits loops with both a [47mWHEN[0m clause and either an
  [47mALWAYS[0m or a [47mTHEREIS[0m operator.  For example, if you are tempted to
  write ``[47mWHEN[0m [3mp[0m [47mALWAYS[0m [3mq[0m'' you can instead write ``[47mALWAYS[0m [47m(if [0m[3mp q[0m
  [47mt)[0m.''

  The following elements may be omitted from the most elaborate form
  and still produce legal [47mloop$[0m statements:

    * any line beginning with [47mAS[0m, [47mUNTIL[0m or [47mWHEN[0m,

    * any [47mOF-TYPE[0m [3mspeci[0m, and

    * any [47m:GUARD[0m [3mguardi[0m.

  A [47mFOR[0m [47mloop$[0m expression with just one iteration variable and in which
  the iterative expressions mention no free variable other than the
  iteration variable is called a [3msimple [47mloop$[0m[3m[0m (or, sometimes, a
  [3msimple loop[0m).  An example of a simple loop is

    (loop$ for x in lst when (evenp x) collect (+ 1 (sq x))).

  A [47mFOR[0m [47mloop$[0m expression is called a [3mfancy [47mloop$[0m[3m[0m if it is not simple.
  Both of the following [47mloop$[0ms are fancy.

    (loop$ for x in xlst as y on ylst collect (expr x y))

    (loop$ for x in xlst collect (expr x z))

  The first is fancy because it has two iteration variables, [47mx[0m and [47my[0m.
  The second is fancy because the body freely uses the variable [47mz[0m
  which is not the iteration variable.

  Now go to [lp-section-5] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-5
  (LOOP$-PRIMER)
  "Informal Semantics of [47mFOR[0m [47mLoop$[0ms


LP5: Informal Semantics of [47mFOR[0m [47mLoop$[0ms

  The value returned by a [47mFOR[0m [47mloop$[0m can be specified as follows --- but
  we hasten to add that this is not how Common Lisp compilers
  implement [47mloop$[0m!  We think this description is easier to
  understand.

  The first step in evaluating a [47mFOR[0m [47mloop$[0m is to determine the range of
  each iteration variable by evaluating the target expressions as
  previously described.

  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 [3muntil-expr[0m evaluates to
  non-[47mnil[0m under the current values of the global and iteration
  variables, stop.  Otherwise, if the [3mwhen-expr[0m evaluates to non-[47mnil[0m
  under the current values of the variables, then evaluate the
  [3mbody-expr[0m under the current values.  Otherwise, do not evaluate the
  [3mbody-expr[0m.

  When the repetition stops, the [3mbody-expr[0m will have been evaluated [3mn[0m
  times, each time producing a value [3mvali[0m, 0 <= [3mi[0m < [3mn[0m, where the [3mvali[0m
  are listed in the order in which they were produced.  The result
  returned by the [47mloop$[0m is determined by the operator, [3mop[0m, of the
  [47mloop$[0m as follows.

    * [47mSUM[0m          --- return the sum of the [3mvali[0m

    * [47mCOLLECT[0m --- return [47m(LIST [0m[3mval1[0m ... [3mvaln[0m[47m)[0m

    * [47mAPPEND[0m   --- return [47m(APPEND [0m[3mval1[0m ... [3mvaln[0m[47m)[0m

    * [47mALWAYS[0m   --- return [47m(AND [0m[3mval1[0m ... [3mvaln[0m[47m T)[0m

    * [47mTHEREIS[0m --- return [47m(OR [0m[3mval1[0m ... [3mvaln[0m[47m)[0m

  Note that if [3mop[0m is [47mALWAYS[0m, iteration can stop the first time a [3mvali[0m
  is [47mnil[0m.  Similarly, if [3mop[0m is [47mTHEREIS[0m, iteration can stop the first
  time a [3mvali[0m is non-[47mnil[0m.  Note also that an [47mALWAYS[0m [47mloop$[0m returns [47mNIL[0m
  or [47mT[0m but a [47mTHEREIS[0m [47mloop$[0m returns [47mnil[0m or the first non-[47mnil[0m value
  produced by the evaluation of the body.

  Now go to [lp-section-6] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-6
  (LOOP$-PRIMER)
  "Challenge Problems about [47mFOR[0m [47mLoop$[0ms


LP6: Challenge Problems about [47mFOR[0m [47mLoop$[0ms

  The questions below ask you to write and evaluate some [47mFOR[0m [47mloop$[0ms at
  the top-level of ACL2.

  Our answers to the problems in this section are in [community-books]
  file [47mdemos/loop-primer/lp6.lisp[0m.  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.

  Don't forget to start your session by including the standard book for
  [47mapply$[0m.

    (include-book \"projects/apply/top\" :dir :system)

  Don't bother with adding [47m:guard[0m expressions and don't define any
  functions of your own yet.  All of these questions can be answered
  by [47mloop$[0m expressions involving only ACL2 primitives and the
  constant function [47mbags[0m which we introduce below for convenience.

  Let a ``bag'' be a true list of symbols.  The function below returns
  a constant list of bags.  You may use [47m(bags)[0m in your solutions.
  Notice that some elements of [47m(bags)[0m contain the symbol [47mx[0m and other
  do not.

    (defun bags ()
      '((a b c)
        (d x e f)
        (g h i x)
        (j)
        (x k l)))

  Here is a sample question and how you might check that your [47mloop$[0m
  computes the expected value.

------------------------------
  Sample Question: Build an alist that pairs the first symbol in every
  bag of [47m(bags)[0m with the number of other symbols in the bag.  The
  expected value is [47m((A . 2) (D . 3) (G . 3) (J . 0) (X . 2))[0m.

  Sample Check of a Solution:

    (equal (loop$ for bag in (bags)
                  collect (cons (car bag) (len (cdr bag))))
           '((A . 2) (D . 3) (G . 3) (J . 0) (X . 2)))

  Of course, you could just type the [47mloop$[0m 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 [47mdefthm[0m events of [47m:rule-classes nil[0m, as in

    (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)

  However, if your [47mloop$[0m involves a user-defined function and you
  express your answers as [47mdefthm[0ms then each theorem will need to have
  appropriate warrant hypotheses, as illustrated below.

    (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)

------------------------------
  [31;1mLP6-1:[0m Concatenate all the bags in [47m(bags)[0m.

  [31;1mExpected Value:[0m[47m(A B C D X E F G H I X J X K L)[0m

------------------------------
  [31;1mLP6-2:[0m Collect the bags that contain the symbol [47mx[0m.

  [31;1mExpected Value:[0m[47m((D X E F) (G H I X) (X K L))[0m

------------------------------
  [31;1mLP6-3:[0m If you used some version of [47mmember[0m in your solution to LP6-2,
  now do it without using any version of [47mmember[0m.

  [31;1mExpected Value:[0m[47m((D X E F) (G H I X) (X K L))[0m

  Don't use any version of [47mmember[0m in your answers to the remaining
  questions in this section.

------------------------------
  [31;1mLP6-4:[0m Remove all the [47mx[0ms from each bag in [47m(bags)[0m and concatenate the
  resulting bags.

  [31;1mExpected Value:[0m[47m(A B C D E F G H I J K L)[0m

------------------------------
  [31;1mLP6-5:[0m Collect the first symbol of each of the bags in [47m(bags)[0m that
  contains an [47mx[0m.

  [31;1mExpected Value:[0m[47m(D G X)[0m

------------------------------
  [31;1mLP6-6:[0m From each bag in [47m(bags)[0m, remove the elements preceding the
  first [47mx[0m and collect the resulting bags.

  [31;1mExpected Value:[0m[47m(NIL (X E F) (X) NIL (X K L))[0m

------------------------------
  [31;1mLP6-7:[0m Let's say the ``alternating sum of signed squares'' 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 [47m(1 2 3 4 5)[0m is [47m(+ 1 -4 9 -16 25)[0m = [47m15[0m.  Compute
  the alternating sum of signed squares of the lengths of the bags in
  [47m(bags)[0m

  [31;1mExpected Value:[0m[47m(+ 9 -16 16 -1 9)[0m = [47m17[0m.

------------------------------
  [31;1mLP6-8:[0m Collect all the function symbols in the current ACL2 world
  with an arity greater than 9.

  Three Hints: First, the term [47m(function-theory :here)[0m returns a list
  of the runes of all the [47m:logic[0m mode functions currently in the ACL2
  world.  However, it expands to an expression involving the variable
  [47mworld[0m which can be obtained by [47m(w state)[0m.  And [47m[state][0m may not be
  used in [47mFOR[0m [47mloop$[0m!  So you'll have to [47m[let][0m bind [47mworld[0m to [47m(w state)[0m
  and write your [47mloop$[0m inside the scope of that [47mlet[0m.

  Second, every [47m[rune][0m returned by [47mfunction-theory[0m is of the form
  [47m(:DEFINITION fn . x)[0m, where [47mfn[0m is the name of a function.

  Third, the arity of a symbol [47mfn[0m is obtained from the world by [47m(arity
  fn world)[0m, except sometimes (for reasons we won't go into!) it
  returns [47mnil[0m.

  [31;1mExpected Value:[0m As of ACL2 Version 8.5 (after including the
  [47m\"projects/apply/top\"[0m book) the answer was [47m(MEMOIZE-FORM SEARCH-FN
  SEARCH-FN-GUARD BUILD-STATE1)[0m, but that may change.

------------------------------
  [31;1mLP6-9:[0m Collect the name of every theorem about [47mEXPT[0m in the current
  world.

  Three More Hints: First, the ACL2 world is a list of triples of the
  form [47m(name property . val)[0m representing the current property lists.
  In ACL2 Version 8.5, the length of the world (after including the
  [47m\"projects/apply/top\"[0m book) is 137,846, so it's too big to just look
  at!

  Second, each event that named a theorem has a triple of the form
  [47m(name THEOREM . val)[0m, where [47mname[0m is the event name and [47mval[0m is the
  translated version of the theorem.  (Thus, you won't find macros
  like [47m+[0m or [47mappend[0m in [47mval[0m!  Instead it would contain the function
  symbols appearing in their expansions, e.g., [47mbinary-+[0m and
  [47mbinary-append[0m.  But since we're looking for [47mexpt[0m and it is not a
  macro, this doesn't matter.)

  Third, the ACL2 term [47m(all-fnnames term)[0m returns a list of all the
  function symbols used in the fully translated term [47mterm[0m.

  [31;1mExpected Value:[0m As of ACL2 Version 8.5 (after including the
  [47m\"projects/apply/top\"[0m book) the answer was
  [47m(APPLY$-PRIM-META-FN-EV-CONSTRAINT-462
  RATIONALP-EXPT-TYPE-PRESCRIPTION
  EXPT-TYPE-PRESCRIPTION-NON-ZERO-BASE)[0m

------------------------------
  These exercises highlight three important lessons about [47mloop$[0m.

  The first is that with [47mloop$[0m you can avoid defining a lot of
  recursive functions.  Imagine doing these same exercises without
  [47mloop$[0m.

  The second is that it is not always a good idea to ``inline'' [47mloop$[0ms
  instead of defining functions.  The clearest example of that arises
  above when we prohibited you from using [47mmember[0m!  Just because
  [47mmember[0m can be replaced by a [47mloop$[0m doesn't mean it should be!
  [47mMember[0m is an exceptionally useful function that enjoys a lot of
  elegant properties.  By introducing the name [47mmember[0m and proving its
  properties we can use it conveniently and appeal to those
  properties often.  Of course, [47mmember[0m 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 [47mloop$[0m in its definition.

  Another example of this second lesson is in question LP6-7.
  Depending on the project at hand, the notion of ``alternating sum
  of signed squares'' might be a useful one in its own right.  So
  perhaps if such a problem came up you might define
  [47m(alternating-sum-of-signed-squares lst)[0m, perhaps using [47mloop$[0m in the
  [47mdefun[0m, and then use

    (alternating-sum-of-signed-squares
      (loop$ for bag in (bags) collect (len bag)))

  to compute the quantity requested in LP6-7.

  The question raised by this second lesson isn't so much whether you
  use a [47mloop$[0m to express the concept but whether you use a [47mdefun[0m to
  give the concept a name.  A good rule of thumb is: [3mif the concept
  has a natural name, define it![0m

  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 [47mloop$[0m we won't discuss
  them.

  The third lesson is highlighted by LP6-8 and LP6-9.  [47mLoop$[0m can be
  very useful in extracting data about your current ACL2 session, if
  you are familiar with the ACL2 system-level utilities (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 [47mloop$[0m handy in querying your own data.

  Now go to [lp-section-7] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-7
  (LOOP$-PRIMER)
  "Using [47mLoop$[0ms and Guards in [47mDefun[0ms


LP7: Using [47mLoop$[0ms and Guards in [47mDefun[0ms

  [47mLoop$[0m statements are most efficient when they are guard verified.
  [47mLoop$[0ms typed at the top-level are typically not guard verified and
  so they are not executed by running compiled Common Lisp [47mloop[0ms.
  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 [47mloop$[0m and that is best
  achieved by using [47mloop$[0ms in guard verified function definitions.

  Here is an example.  We've already discussed [47mmember[0m and the fact that
  calls of [47mmember[0m can be replaced by [47mloop$[0ms.  [47mMember[0m is a macro that
  expands logically to [47mmember-equal[0m, where

    (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)))))

  Let's define an equivalent function, named [47mmember-equal-loop$[0m, using
  [47mloop$[0m.

    (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)))

  Since [47mmember-equal[0m has a guard of [47m(true-listp lst)[0m, we will give our
  [47mmember-equal-loop$[0m the same guard.  But in our [47mloop$[0m above we also
  wrote that the iteration variable [47mtail[0m satisfies [47mtrue-listp[0m.  We do
  that so that ACL2 can prove the guard on [47m(car tail)[0m in the [47mthereis[0m
  clause.  (We could change ACL2 to infer this type for [47mtail[0m in this
  special case, but more generally we would prefer to have an
  effective heuristic for transferring arbitrary properties of [47mlst[0m to
  relevant properties of [47mtail[0m.)

  The guard obligations for [47mmember-equal-loop$[0m are obscure because we
  haven't explained the formal semantics of [47mloop$[0m yet.  But we do not
  discuss the guard obligations of [47mloop$[0ms in the primer.  If you
  define a function containing a [47mloop$[0m 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 [47mFOR[0m [47mloop$[0m guards
  and the guard obligations they generate, see [for-loop$],
  specifically, the sections ``Special Guard Conjectures for [47mFOR[0m
  [47mLoop$[0ms'' and ``Discussion of Why [47mLoop$[0ms Have Special Guards.''

  After admitting [47mmember-equal-loop$[0m ACL2 can prove inductively that it
  is equal to [47mmember-equal[0m.  We'll come back to that later too.

  An alternative way to specify the type of [47mtail[0m would be to add a
  [47m:guard[0m rather than an [47mof-type[0m expression.

    (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)))

  The [47m:guard[0m feature of ACL2 is more flexible than [47mof-type[0m because
  guards allow you to use multiple variables to express a constraint,
  while [47mof-type[0m implicitly limits the assertion to the variable being
  introduced.  For example, with a guard you could say [47m(subsetp-equal
  tail lst)[0m while you cannot express such a constraint with [47mof-type[0m.
  However, [47mof-type[0m 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.

  When you use a [47mloop$[0m in a [47mdefun[0m 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 [47mwhen[0m and [47muntil[0m
  expressions.)  We generally split our constraints between [47mof-type[0m
  and [47m:guard[0m 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 [47mof-type[0m information
  and conjoin it to any [47m:guard[0m when doing guard verification.

  Now go to [lp-section-8] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-8
  (LOOP$-PRIMER)
  "Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms


LP8: Challenge Problems about [47mFOR[0m [47mLoop$[0m in [47mDefun[0ms

  Do the problems below, starting in a fresh ACL2 session that starts
  with the standard [47m(include-book \"projects/apply/top\" :dir :system)[0m.
  Each problem starts with one or more recursive functions.  Admit
  those functions in your session.  Then define equivalent versions
  using [47mloop$[0ms instead of recursion.  Make sure each of your [47mdefun[0ms
  is admitted and guard verified.  Try to ensure that the [47mloop$[0m
  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 [47mloop$[0m
  is the runtime efficiency of the compiled raw Lisp, and since no
  ACL2 function is executed in raw Lisp unless the guards are
  verified.

  Finally, you need not use ACL2 to prove that your [47mloop$[0m 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
  [47mloop$[0ms later in the primer.

  Our answers to the problems in this section are in [community-books]
  file [47mdemos/loop-primer/lp8.lisp[0m.

------------------------------
  Sample Question: [47m(Sum-vals alist)[0m sums the value components of an
  alist.  Note its guard.

    (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))))))

  E.g., [47m(sum-vals '((a . 1) (b . 2) (c . 3))) = 6[0m.

  Define [47msum-vals-loop$[0m so that it is unconditionally equivalent to
  [47msum-vals[0m but uses [47mloop$[0m instead of recursion.

  Sample Solution:

    (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)))

  The [47m(consp pair)[0m in the [47mloop$[0m [47m:guard[0m is necessary because the [47mloop$[0m
  body contains [47m(cdr pair)[0m and Common Lisp expects [47mcdr[0m to be applied
  to a [47mconsp[0m or [47mnil[0m.  The [47m(integerp (cdr pair))[0m is necessary because
  the value of the [47mloop$[0m body is being [47msum[0mmed and so must be (at
  least) a number to satisfy Common Lisp's expectation on [47m+[0m.

  Verification of Sample Solution:

    (defthm sum-vals-loop$-is-sum-vals
      (equal (sum-vals-loop$ alist)
             (sum-vals alist))
      :rule-classes nil)

  It is conceivable in some Common Lisps that the following would
  compile into more efficient code.

    (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))))

  The thinking is that the [47mof-type cons[0m and [47m(the integer (cdr pair))[0m
  could in principle allow the compiler to do type checking that
  could eliminate runtime tests to avoid errors.  That's because
  [47mof-type[0m and [47mthe[0m are Common Lisp primitives, as are the particular
  [47m[type-spec][0ms used in [47msum-vals-loop$[0m.  Whether such a well-declared
  version of [47msum-vals-loop$[0m 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 [47m:guard[0ms.

------------------------------
  [31;1mLP8-1[0m Define [47msum-vals-loop$[0m which is like our solution shown for
  [47msum-vals[0m above, except instead of using [47msymbol-to-integer-alist[0m as
  the [47m:guard[0m write the [47m:guard[0m as [47m(and (true-listp alist) (loop$
  ...))[0m.  Be sure your definition is admitted and guard verified.

  If you want a slightly more challenging problem, omit the [47m(true-listp
  alist)[0m from the [47m:guard[0m and use a [47mFOR[0m [47mloop$[0m ``[47mON[0m'' [47malist[0m.  FYI:
  Common Lisp requires ``[47mIN[0m'' [47mloop$[0ms to be over a [47mtrue-listp[0m target,
  but there is no such requirement for ``[47mON[0m'' [47mloop$[0ms.

  You can always convert an ``[47mIN[0m'' [47mloop$[0m governed by a [47mtrue-listp[0m check
  to an ``[47mON[0m'' [47mloop$[0m without the check.  See our solutions.  But
  because of that, we'll use the more elegant ``[47mIN[0m'' solutions in the
  rest of these problems.

------------------------------
  [31;1mLP8-2[0m 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 [47marglistp1-loop$[0m that uses [47mloop$[0m instead
  of recursion.

    (defun arglistp1 (lst)
      (declare (xargs :guard t))
      (cond ((atom lst) (null lst))
            (t (and (legal-variablep (car lst))
                    (arglistp1 (cdr lst))))))

  Why is [47marglistp1-loop$[0m a little less efficient than [47marglistp[0m?

------------------------------
  [31;1mLP8-3[0m The two recursive functions below are used in the ACL2 sources
  (thus, you won't have to define them in your session).  Define
  [47mpackn1-loop$[0m that is equivalent to [47mpackn1[0m but so that it uses
  [47mloop$[0ms and does not mention [47matom-listp[0m.

    (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))))))

------------------------------
  [31;1mLP8-4[0m Define [47mselect-corresponding-element-loop$[0m so that it is
  equivalent to [47mselect-corresponding-element[0m, below, but using a
  [47mloop$[0m statement.

    (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)))))

  For example,

    (select-corresponding-element
      'wednesday
      '(sunday monday tueday wednesday thursday friday saturday)
      '(dimanche lundi mardi mercredi jeudi vendredi samedi))
    =
    'MERCREDI

------------------------------
  [31;1mLP8-5[0m Define [47msame-mod-wildcard-loop$[0m to be equivalent to
  [47msame-mod-wildcard[0m, below, but using a [47mloop$[0m statement.

    (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)))

  For example,

    (same-mod-wildcard '(a * c d *) '(a x c * d))
    =
    T

------------------------------
  [31;1mLP8-6[0m The following function is part of the ACL2 source code, so you
  don't have to define it in your session.

    (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))))))

  Define [47mgetprops1-loop$[0m to do the same thing using [47mloop$[0m.

------------------------------
  Now go to [lp-section-9] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (LP-SECTION-9
  (LOOP$-PRIMER)
  "Semantics of [47mFOR[0m [47mLoop$[0ms


LP9: Semantics of [47mFOR[0m [47mLoop$[0ms

  For a thorough discussion of the semantics of [47mFOR[0m [47mloop$[0ms see
  [for-loop$], specifically the section ``Semantics'' which includes
  two subsections, ``Semantics of Simple [47mLoop$[0ms'' and ``Semantics of
  Fancy [47mLoop$[0ms.'' ``Fancy'' [47mFOR[0m [47mloop$[0ms are [47mFOR[0m [47mloop$[0ms involving
  multiple iteration variables and/or use of ``global'' (i.e.,
  non-iteration) variables in the [47mloop$[0m body or the [47muntil[0m or [47mwhen[0m
  clauses. We discuss [47mDO[0m [47mloop$[0ms later.  In this section of the primer
  we just present some examples to drive home a few important points
  about [47mFOR[0m [47mloop$[0ms, namely

    * The semantics of a [47mloop$[0m statement is obtained by translating the
      [47mloop$[0m statement, as with the command [47m:[0m[47m[trans][0m.

    * However, translation inserts a lot of tags into the formal term it
      produced.  These tags allow us to execute [47mloop$[0m statements more
      efficiently in the top-level ACL2 read-eval-print [47mloop$[0m.  The
      tags on a translated [47mloop$[0m, [3mterm[0m, can be removed by the [47m:[0m[47m[tc][0m
      (``translate and clean'') command and its variants [47m:tca[0m and
      [47m:tcp[0m.  When we exhibit semantics we typically show these
      simplified, equivalent terms produced by one of these commands.

    * The semantics of [47mFOR[0m [47mloop$[0ms look quite different from the semantics
      of [47mDO[0m [47mloop$[0ms.  Furthermore, the semantics of simple [47mloop$[0ms have
      a different form than those of fancy [47mloop$[0m.  So ``minor''
      changes in the syntax of a [47mloop$[0m statement --- the addition of
      an [47mAS[0m clause, the use of global variable in the body of the
      [47mloop$[0m, or the use of [47mDO[0m instead of, say, [47mcollect[0m --- can cause
      radical changes in the form of the semantics.

    * The semantics of [47mloop$[0ms always involve calls of [47m[scion][0ms on lambda
      objects derived from the [47mwhen[0m, [47muntil[0m, and [47mloop$[0m body clauses.
      The scions for simple [47mFOR[0m [47mloop$[0ms are [47msum$[0m, [47mcollect$[0m, [47malways$[0m,
      [47mthereis$[0m, [47mappend$[0m, [47muntil$[0m, and [47mwhen$[0m; the scions for fancy [47mFOR[0m
      [47mloop$[0ms are [47msum$+[0m, [47mcollect$+[0m, [47malways$+[0m, [47mthereis$+[0m, [47mappend$+[0m,
      [47muntil$+[0m, and [47mwhen$+[0m; and the scion for [47mDO[0m [47mloop$[0ms is [47mdo$[0m.

    * The iteration variables become formals of the [47mlambda[0m objects and
      standard names are used in place of the user's names.

  Now we drive home these points with some examples.  The next section
  (see [LP-SECTION-10]) elaborates further.

  Here is the full, formal translation of a simple [47mFOR[0m [47mloop$[0m.

    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)))

  However, the logical meaning of this is easier to understand by
  looking at one of the [47mtc[0m variations.

    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)))

  Note that [47m:tc[0m prints the term generated by translating the [47mloop$[0m 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 [47mlambda[0m object is just a quoted
  list constant and the body has been translated so that the [47m*[0m macro
  was expanded in terms of [47mbinary-*[0m.

  [47m:Tcp[0m (``p'' for ``pretty'') introduces familiar system macros.

  [47m:Tca[0m (``a'' for ``annotations'') includes the original [47mloop$[0m
  statement and shows declarations (if any) and the correspondence
  between the user's iteration variable ([47mx[0m here) and the formal
  variable used in the [47mlambda[0m objects generated ([47mloop$-ivar[0m here).

  The translation of [47mloop$[0m bodies into [47mlambda[0m objects standardizes the
  variable name, either as [47mloop$-ivar[0m for simple [47mloop$[0ms which have
  just one iteration variable, or as [47mloop$-gvars[0m and [47mloop$-ivars[0m for
  fancy [47mloop$[0ms which may have one or more global variables and one or
  more iteration variables.  We'll deal with fancy [47mloop$[0ms immediately
  below, but values are passed for [47mloop$-gvars[0m and [47mloop$-ivars[0m as
  tuples listing all the global values and all the current iteration
  variable values.

  The advantage of this standardization is that choosing different
  names for the iteration variables does not affect the formal
  semantics.

  However, if we make a simple syntactic change, like introducing a
  global variable by changing the body of the loop$ from [47m(* x x)[0m to
  [47m(* x a)[0m, where [47ma[0m is not an iteration variable, we drastically
  change the semantics because we've converted the simple [47mloop$[0m into
  a fancy [47mloop$[0m.  The (clean and pretty) semantics of

    (loop$ for x in lst when (evenp x) collect (* x a))

  is

    (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))))

  The annotated semantics of that [47mloop$[0m is

    (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)))))

  Logically, we could have typed either of the above terms instead of
  the fancy [47mloop$[0m.  But operationally, the [47mloop$[0m executes faster
  (when guards are verified).

  Notice that the simple scions [47mCOLLECT$[0m and [47mWHEN$[0m have been replaced
  by their fancy counterparts, [47mCOLLECT$+[0m and [47mWHEN$+[0m.  The [47mlambda[0m
  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, [47m(LIST A)[0m, is passed into the fancy scions if the
  corresponding [47mlambda[0m object uses globals (as for the [47mcollect$+[0m but
  not for the [47mwhen$+[0m [47mlambda[0m where [47mNIL[0m is passed instead).  The list
  over which the iteration variable ranges, [47mLST[0m, is now a list of
  tuples constructed by [47mLOOP$-AS[0m.  Finally, the bodies of the [47mlambda[0ms
  now access the relevant values with [47mCAR[0m and [47mCDR[0m nests around the
  global and iteration tuples. (No [47mCDR[0ms appear above because there is
  only one global and one iteration variable in this example.)

  The following similar but still fancier [47mloop$[0m illustrates the general
  situation.  This [47mloop$[0m has two iteration variables, [47mx[0m and [47my[0m taking
  on values from two ranges, [47mxlst[0m, and [47mylst[0m, and uses two global
  variables, [47ma[0m and [47mb[0m, in the body.  We've added comments to name the
  components of the two tuples.

    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))))

  Notice how the bodies of the [47mlambda[0m objects now use components of the
  [47mloop$-gvars[0m and [47mloop$-ivars)[0m for the current values of the global
  variables [47ma[0m and [47mb[0m and the iteration variables [47mx[0m and [47my[0m.  The values
  of [47mx[0m and [47my[0m are corresponding elements of [47mxlst[0m and [47mylst[0m as grouped
  together by [47m(loop$-as (list xlst ylst))[0m.

  For a still-more elaborate [47mFOR[0m [47mloop$[0m and a step-by-step description
  of how the value of the formal semantics is computed, go to
  [lp-section-10].

  Now go to [lp-section-10] (or return to the Table of Contents (see
  [LP-SECTION-0])).")
 (MACRO-ALIASES-TABLE
  (MACROS)
  "A [table] used to associate function names with macro names

    Example:
    (table macro-aliases-table 'append 'binary-append)

  This example associates the function symbol [47m[binary-append][0m with the
  macro name [47m[append][0m.  As a result, the name [47m[append][0m may be used as
  a runic designator (see [theories]) by the various theory
  functions.  Thus, for example, it will be legal to write

    (in-theory (disable append))

  as an abbreviation for

    (in-theory (disable binary-append))

  which in turn really abbreviates

    (in-theory (set-difference-theories (current-theory :here)
                                        '(binary-append)))

    General Form:

    (table macro-aliases-table 'macro-name 'function-name)

  or very generally

    (table macro-aliases-table macro-name-form function-name-form)

  where [47mmacro-name-form[0m and [47mfunction-name-form[0m evaluate, respectively,
  to a macro name and a symbol in the current ACL2 [world].  See
  [table] for a general discussion of tables and the [47mtable[0m event used
  to manipulate tables.

  Note that [47mfunction-name-form[0m (above) does not need to evaluate to a
  function symbol, but only to a symbol.  As a result, one can
  introduce the alias before defining a recursive function, as
  follows.

    (table macro-aliases-table 'mac 'fn)
    (defun fn (x)
      (if (consp x)
          (mac (cdr x))
        x))

  Although this is obviously a contrived example, this flexibility can
  be useful to macro writers; see for example the definition of ACL2
  system macro [47m[defun-inline][0m.

  The [47m[table][0m [47m[macro-aliases-table][0m is an alist that associates macro
  symbols with function symbols, so that macro names may be used as
  runic designators (see [theories]).  For a convenient way to add
  entries to this [table], see [add-macro-alias].  To remove entries
  from the [table] with ease, see [remove-macro-alias].

  This [table] is used by the theory functions; see [theories].  For
  example, in order that [47m(disable append)[0m be interpreted as [47m(disable
  binary-append)[0m, it is necessary that the example form above has
  been executed.  In fact, this [table] does indeed associate many of
  the macros provided by the ACL2 system, including [47m[append][0m, with
  function symbols.  Loosely speaking, it only does so when the macro
  is ``essentially the same thing as'' a corresponding function; for
  example, [47m(append x y)[0m and [47m(binary-append x y)[0m represent the same
  term, for any expressions [47mx[0m and [47my[0m.")
 (MACRO-ARGS
  (MACROS)
  "The formals list of a macro definition

    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)

  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:

    * [47m&whole x[0m
      [47mX[0m does not represent an actual parameter; rather, it is bound to the
      entire macro call.

    * [47m&optional x1 x2 ...[0m
      The actual for any [47mxi[0m may be omitted, in which case the actual for
      every [47mxj[0m with [47mj > i[0m must also be omitted.

    * [47m&rest x[0m
      [47mX[0m does not represent an actual parameter; rather, it is bound to the
      list of all actuals provided from that position onward.

    * [47m&body x[0m
      This is identical to [47m&rest x[0m.

    * [47m&key x[0m
      The call may have a keyword argument for [47mx[0m by including [47m:x val[0m after
      all required actual parameters, in which case the formal [47mx[0m is
      bound to the actual [47mval[0m.

    * [47m&allow-other-keys[0m
      Keyword arguments not specified by [47m&key[0m are allowed but ignored.

  ACL2 does not support the Common Lisp lambda-list keywords [47m&aux[0m and
  [47m&environment[0m.  In addition, there are the following restrictions:

      (1) initialization forms in [47m&optional[0m and [47m&key[0m specifiers must be
      quoted values;

      (2) [47m&allow-other-keys[0m may only be used once, as the last specifier;
      and

      (3) destructuring is not allowed.

  The use of default values is allowed, so that an optional or keyword
  argument may be given in any of the following forms.

    * [47marg[0m or, equivalently, [47m(arg)[0m

    * [47m(arg 'init)[0m

    * [47m(arg 'init supplied-p)[0m

  For the second and third forms above, [47minit[0m is the value when the
  argument is not supplied; for the first form, that default value is
  [47mnil[0m.  Note that it must be quoted.  The [47msupplied-p[0m argument is [47mnil[0m
  when the argument is not supplied, else is [47mt[0m, as illustrated by the
  demo below.

  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.,

    (defmacro demo (x y &optional (opt '5) &key (key1 '6 key1p) key2)
      (list 'quote (list x y opt key1 key1p key2)))

  You may then execute the macro on some sample forms, e.g.,

      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)

  In particular, Common Lisp specifies (hence so does ACL2) that if you
  use both [47m&rest[0m and [47m&key[0m, then both will be bound using the same
  list of arguments.  The following example should serve to
  illustrate how this works.

    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 !>

  If we don't want to get the error above, we can use
  [47m&allow-other-keys[0m, as follows.

    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 !>

  Also see [trans].


Subtopics

  [Set-duplicate-keys-action]
      Control action for macro calls with duplicate keyword arguments")
 (MACRO-COMMAND
  (PROOF-BUILDER)
  "Compound command for the interactive proof-builder

  The interactive [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.

  More [documentation] may be written on the interactive
  [proof-builder].  For now, we simply point out that there are lots
  of examples of the use of [47mdefine-pc-macro[0m and
  [47mdefine-pc-atomic-macro[0m in the ACL2 source file
  [47m\"proof-builder-b.lisp\"[0m.  The former is used to create macro
  commands, which can be submitted to the interactive loop (see
  [verify]) and will ``expand'' into zero or more commands.  The
  latter is similar, except that the undoing mechanism (see
  [ACL2-pc::undo]) understands atomic macro commands to represent
  single interactive commands.  Also see [ACL2-pc::comm] and see
  [ACL2-pc::commands] for a discussion of the display of interactive
  commands.

  Also see [toggle-pc-macro] for how to change a macro command to an
  atomic macro command, and vice versa.")
 (MACROLET
  (BASICS ACL2-BUILT-INS)
  "Local binding of macro symbols

  See [flet] for an analogous utility for defining functions locally.

    Example Form:
    (defun f1 (x)
      (macrolet ((mac (a) (list 'quote a)))
        (cons x (mac x))))

  The Example Form above is equivalent to the following, in which the
  call of local macro [47mmac[0m has been expanded.

    (defun f1-alt (x)
      (cons x (quote x)))

  The General Forms are similar to those of [47m[flet][0m.

    General Forms:
    (macrolet (def1 ... defk) body)
    (macrolet (def1 ... defk) declare-form1 .. declare-formk body)

  where [47mbody[0m is a term, and each [47mdefi[0m is a definition as in [47m[defmacro][0m
  but with the leading [47mdefmacro[0m symbol omitted.  See [defmacro], but
  see [declare] for the declarations permitted directly under the
  [47mdefi[0m.  On the other hand, regarding the [47mdeclare-formi[0m (if any are
  supplied): each must be of the form [47m(declare decl1 ... decln)[0m,
  where each [47mdecli[0m is of the form [47m(inline g1 ... gm)[0m or [47m(notinline g1
  ... gm)[0m, and each [47mgi[0m is defined by some [47mdefi[0m.  Unlike the related
  utility [47m[flet][0m, those [47minline[0m and [47mnotinline[0m declarations are
  unlikely to have any effect.

  The innermost [47m[flet][0m or [47mmacrolet[0m binding of a symbol, [47mf[0m, above a call
  of [47mf[0m, is the one that provides the definition of [47mf[0m for that call.
  Note that neither [47mflet[0m nor [47mmacrolet[0m provide recursion: that is, the
  definition of [47mf[0m in an [47mflet[0m or [47mmacrolet[0m binding of [47mf[0m is ignored in
  the body of that binding.

  The following requirements are imposed by Common Lisp and enforced by
  ACL2.

    * Every variable occurring in the body of a [47mdefi[0m must be a formal
      parameter name of that [47mdefi[0m.

    * No function or macro symbol called in the body of a [47mdefi[0m may be
      defined by a superior [47mflet[0m or [47mmacrolet[0m binding.  (Not every
      Common Lisp implementation includes this restriction for
      superior [47mmacrolet[0m bindings, but at least one (GCL) does so we
      include it in ACL2.)

  Although [47mmacrolet[0m behaves in ACL2 essentially as it does in Common
  Lisp, ACL2 imposes the following restrictions and qualifications.

    * Every [47m[declare][0m form for a local definition ([47mdef1[0m through [47mdefk[0m,
      above) must be an [47mignore[0m, [47mignorable[0m, or [47mtype[0m expression.

    * Each [47mdefi[0m must bind a different symbol.

    * Each [47mdefi[0m 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.

    * When an expression [47m(macrolet (... defi ...) ...)[0m occurs in the body
      of a [47mDO[0m [47m[loop$][0m expression, nevertheless constructs such as
      [47mPROGN[0m and [47mSETQ[0m that ACL2 permits in [47mDO[0m [47mloop$[0m bodies are not
      permitted in [47mdefi[0m (unless they occur within the scope of a [47mDO[0m
      [47mloop$[0m expression in that body).

  [47mMacrolet[0m bindings are evaluated in parallel.  Consider the following
  example.

    (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))

  The [47mmacrolet[0m form above evaluates to [47m(3 . x)[0m, 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.

    (macrolet ((f1 (x) x))
      (macrolet ((f2 () (list 'quote (f1 3))))
        (f2)))

  The body of [47mf2[0m calls a symbol, [47mf1[0m, that is bound by a superior
  [47mmacrolet[0m binding.  As noted above, this is illegal (also for
  superior [47mflet[0m bindings).

  Under the hood, ACL2 expands away [47mmacrolet[0m bindings.  The following
  example illustrates this point.

    ACL2 !>:trans (macrolet ((mac (a) (list 'cons a a)))
                    (car (mac b)))

    (CAR (CONS B B))

    => *

    ACL2 !>

  [47mMacrolet[0m is part of Common Lisp.  See any Common Lisp documentation
  for more information.  We conclude by pointing out an important
  aspect of [47mmacrolet[0m shared by ACL2 and Common Lisp: The binding is
  lexical, not dynamic.  That is, the [47mmacrolet[0m binding of a symbol
  only applies to calls of that symbol in the body of the [47mmacrolet[0m,
  not other calls made in the course of evaluation.  See [flet] for
  discussion of this point.")
 (MACROS
  (ACL2)
  "Macros allow you to extend the syntax of ACL2.


Subtopics

  [Add-binop]
      Associate a function name with a macro name

  [Add-macro-alias]
      Associate a function name with a macro name

  [Add-macro-fn]
      Associate a function name with a macro name

  [Check-vars-not-free]
      Avoid variable capture in macro calls

  [Defabbrev]
      A convenient form of macro definition for simple expansions

  [Defmacro]
      Define a macro

  [Defmacro-untouchable]
      Define an ``untouchable'' macro

  [Macro-aliases-table]
      A [table] used to associate function names with macro names

  [Macro-args]
      The formals list of a macro definition

  [Make-event]
      Evaluate (expand) a given form and then evaluate the result

  [Remove-binop]
      Remove the association of a function name with a macro name

  [Remove-macro-alias]
      Remove the association of a function name with a macro name

  [Remove-macro-fn]
      Remove the association of a function name with a macro name

  [Safe-mode]
      A mode that avoids [guard] violations on [primitive]s

  [Set-duplicate-keys-action]
      Control action for macro calls with duplicate keyword arguments

  [Tc]
      translate form and clean it up

  [Tca]
      translate a form and clean it up into an annotated pretty term

  [Tcp]
      translate a form and clean it up into a pretty term

  [Trans]
      Print the translation of a form

  [Trans!]
      Print the translation of a form without code restrictions

  [Trans*]
      Show intermediate expansion results for the translation of a form

  [Trans*-]
      Variant of [47m[trans*][0m the skips [47m[make-event][0m expansion

  [Trans1]
      Print the one-step macroexpansion of a form

  [Untrans-table]
      Associates a function symbol with a macro for printing user-level
      terms

  [User-defined-functions-table]
      An advanced [table] used to replace certain system functions")
 (MAGIC-EV-FNCALL
  (META)
  "Call the named function on the given arguments and return the value.

  Introduction.  [47mMagic-ev-fncall[0m is a [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,
  [47mmagic-ev-fncall[0m is technically a constrained function (with unknown
  constraints), which can be assumed in metafunctions and [clause]
  processors to produce correct results, via [meta-extract].

  Examples:

    (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)

  General Form:

    (magic-ev-fncall fn arglist state hard-error-returns-nilp aokp)

  where [47mfn[0m is a function symbol, [47marglist[0m is a suitable argument list
  for [47mfn[0m, and the last two formals are described below.  When
  successful, the result is [47m(mv nil value)[0m where [47mvalue[0m is the
  application of [47mfn[0m to [47marglist[0m.  Although this fact cannot be proven,
  it may be assumed correct in metafunctions and clause processors
  via [meta-extract], assuming of course that [47mfn[0m is a [logic]-mode
  function.

  In general, the result is either [47m(mv t error-msg)[0m (if, e.g., the
  function was not defined, the arity was wrong, or the guards were
  violated) or [47m(mv nil value)[0m on success.  In the case of a
  [multiple-value]d function the second return value is the list of
  values.  A non-nil error message, [47merror-msg[0m, is a message suitable
  for printing with [47m[fmt][0m; see [msg].

  If a hard error is encountered during execution and
  [47mhard-error-returns-nilp[0m is non-[47mnil[0m, then the error is ignored and
  the value returned is [47m(mv nil nil)[0m (note that the logical value of
  a call of [47mHARD-ERROR[0m is [47mnil[0m).  If [47mhard-error-returns-nilp[0m is [47mnil[0m
  then the return value is of the form [47m(mv T error-msg)[0m.

  The [47maokp[0m argument controls whether attachments to constrained
  functions may be executed (see [defattach]).  If [47mnil[0m, then an error
  message is returned when an attachment would otherwise be executed.

  When used in a clause-processor or metafunction, it can be assumed
  via a [meta-extract] hypothesis that [47mmagic-ev-fncall[0m works
  correctly with respect to the evaluator, but only if
  [47mhard-error-returns-nilp[0m is [47mt[0m and [47maokp[0m is [47mnil[0m.

  The [guard] for [47m(magic-ev-fncall fn arglist state h aokp)[0m is [47mt[0m, but
  evaluation of this call enforces the following requirements.

    * [47mFn[0m must be a function symbol of the current ACL2 [world] other than
      [47mif[0m, whose arity is equal to the length of the true-list,
      [47marglist[0m.

    * [47mFn[0m must not have any [47mstobj[0m inputs or be a stobj creator.

    * Calls of [47mfn[0m must not require a trust tag (see [defttag]).

    * [47mFn[0m must not be untouchable (see [push-untouchable]).

  The implementation of these checks incorporates a bit of trickery so
  that they are reasonably efficient.

  Note that [47m[set-guard-checking][0m affects evaluation of calls of
  [47m(magic-ev-fncall fn ...)[0m just as it affects calls of [47mfn[0m, for
  example as follows.

    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 >

  Additional Notes.

    * If [47mfn[0m is a [program]-mode function, then the call will be evaluated
      under [safe-mode], which avoids raw Lisp errors due to calls of
      ill-[guard]ed program-mode functions.

    * If the application of [47mfn[0m returns multiple values [47m(mv v1 v2 ...)[0m, then
      the resulting value will be the corresponding list [47m(v1 v2 ...)[0m.

    * A reasonable model for [47m(magic-ev-fncall 'fn (list a1 a2 ...) state h
      aokp)[0m is [47m(ec-call (fn a1 a2 ...))[0m.")
 (MAKE
  (DEFREC ACL2-BUILT-INS)
  "Constructor macro for [defrec] structures.

  The [47mmake[0m macro is built into ACL2, and allows you to construct new
  instances of structures that have been introduced with [defrec].
  For instance:

    (make employee :name \"Jimmy\"
                   :salary 0
                   :position \"Unpaid Intern\")

  Creates a new [47memployee[0m structure with the given values for its [47mname[0m,
  [47msalary[0m, and [47mposition[0m fields.  See [defrec] for more information.")
 (MAKE-CHARACTER-LIST
  (CHARACTERS ACL2-BUILT-INS)
  "[coerce] to a list of characters

  Non-characters in the given list are [coerce]d to the character with
  code 0.

  [31;1mFunction: [0m<make-character-list>

    (defun make-character-list (x)
      (declare (xargs :guard t))
      (cond ((atom x) nil)
            ((characterp (car x))
             (cons (car x)
                   (make-character-list (cdr x))))
            (t (cons *null-char*
                     (make-character-list (cdr x))))))")
 (MAKE-EVENT
  (EVENTS MACROS)
  "Evaluate (expand) a given form and then evaluate the result

  [47mMake-event[0m is a utility for generating [events].  It provides a
  capability not offered by Lisp macros (see [defmacro]), as it
  allows access to the ACL2 [state] and logical [world].  In essence,
  the expression [47m(make-event form)[0m replaces itself with the result of
  evaluating [47mform[0m --- let's call that result [47mev[0m --- as though one had
  submitted [47mev[0m instead of the [47mmake-event[0m call.  For example,
  [47m(make-event (quote (defun f (x) x)))[0m is equivalent to the event
  [47m(defun f (x) x)[0m.

  We assume basic familiarity with the ACL2 [3mstate[0m.  For relevant
  background, see [state] and perhaps see [programming-with-state].

  There are several simple examples below.  For examples that can give
  additional insight into the use of [47mmake-event[0m for tool development,
  see [make-event-example-1] and [make-event-example-2].  Also see
  the [47mmake-event/[0m subdirectory of the ACL2 [community-books] for more
  examples, for example, [47mbooks/make-event/search-generation.lisp[0m.

  We break this documentation into the following sections.

    * [31;1mIntroduction[0m

    * [31;1mDetailed Documentation[0m

    * [31;1mError Reporting[0m

    * [31;1mRestriction to Event Contexts[0m

    * [31;1mExamples Illustrating How to Access State[0m

    * [31;1mAdvanced Expansion Control[0m

  We begin with an introduction, which focuses on examples and
  introduces the key notion of ``expansion phase''.


Introduction

  [47mMake-event[0m is particularly useful for those who program using the
  ACL2 [47m[state][0m; see [programming-with-state].  That is because the
  evaluation of [47mform[0m may read and even modify the ACL2 [47m[state][0m.

  Suppose for example that we want to define a constant [47m*world-length*[0m,
  that is the length of the current ACL2 [world].  A [47mmake-event[0m form
  can accomplish this task, as follows.

    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 !>

  How did this work?  First, evaluation of the form [47m(list 'defconst
  '*world-length* (length (w state)))[0m returned the event form
  [47m(defconst *world-length* 98883)[0m.  Then that event form was
  automatically submitted to ACL2.  Of course, that changed the ACL2
  logical [world], which is why the final value of [47m(length (w state))[0m
  is greater than its initial value.

  The example above illustrates how the evaluation of a [47mmake-event[0m call
  takes place in two phases.  The first phase evaluates the argument
  of the call, in this case [47m(list 'defconst '*world-length* (length
  (w state)))[0m, to compute an event form, in this case [47m(defconst
  *world-length* 98883)[0m.  We call this evaluation the ``expansion''
  phase.  Then the resulting event form is evaluated, which in this
  case defines the constant [47m*world-length*[0m.

  Now suppose we would like to introduce such a [47m[defconst][0m 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.

    ; WRONG!
    (defmacro define-world-length-constant (name state)
      (list 'defconst name (length (w state))))

  But ACL2 rejects such a definition, because the formal parameter
  [47m\"STATE\"[0m is bound to the syntactic object in the macro call, not to
  the actual ACL2 [state]; 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.

  Instead, however, you can use the approach illustrated by the
  [47mmake-event[0m example above to define the desired macro, as follows.

    (defmacro define-world-length-constant (name)
      `(make-event (list 'defconst ',name (length (w state)))))

  Here is a log that may help to explain this macro, assuming it has
  been defined as displayed just above.

    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 !>

  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 [assign]).

    (make-event
     (er-progn (assign my-world-length (length (w state)))
               (value '(value-triple nil))))

  Notice that this time, the value returned by the expansion phase is
  not a single value; rather, it is an [error-triple] whose value
  component is an event form, namely, the event form [47m(value-triple
  nil)[0m.  Evaluation of that event form does not change the ACL2 world
  (see [value-triple]).  Thus, the sole purpose of the [47mmake-event[0m
  call above is to change the [state] by associating the length of
  the current logical world with the state global, [47mmy-world-length[0m.
  After evaluating this form, [47m(@ my-world-length)[0m provides the length
  of the ACL2 world, as illustrated by the following transcript.

    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 !>

  When [47mmake-event[0m is invoked by a book, it is expanded during book
  certification but not, by default, when the book is included.
  Consider again the example [47m(define-world-length-constant *foo*)[0m
  given above.  If that form is in a book, then the value of [47m*foo*[0m
  will be the length of the world at the time this form was invoked
  during book certification, regardless of world length at
  [47m[include-book][0m time.  That is because the expansion, [47m(DEFCONST
  *FOO* 109700)[0m, is recorded in the book's [certificate] and re-used
  during a subsequent [47m[include-book][0m.

  However, the keyword [47m:check-expansion[0m may be given the value [47mt[0m so
  that the expansion is done even during [47minclude-book[0m, 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 [47m[certify-book][0m or during [47m[include-book][0m.

    (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)


Detailed Documentation

    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)

  where [47mchk[0m is [47mnil[0m (the default), [47mt[0m, or the intended ``expansion
  result'' from the evaluation of [47mform[0m (as explained below); [47mobj[0m is
  an arbitrary ACL2 object, used only in reporting errors in
  expansion, i.e., in the evaluation of form; and [47msave[0m is arbitrary
  but is considered only as either [47mnil[0m or non-[47mnil[0m.  The [47m:EXPANSION?[0m
  keyword is discussed in the final section, on Advanced Expansion
  Control.  See [make-event-details] for discussion of the
  [47m:ON-BEHALF-OF[0m and :SAVE-EVENT-DATA keywords.

  We strongly recommend that you browse some [47m.lisp[0m files in the
  community books directory [47mbooks/make-event/[0m.  You may even find it
  helpful, in order to understand [47mmake-event[0m, to do so before
  continuing to read this documentation.  You may also find it useful
  to browse community book [47mbooks/std/testing/eval.lisp[0m, which
  contains definitions of macros [47mmust-succeed[0m and [47mmust-fail[0m that are
  useful for testing and are used in many books in the
  [47mbooks/make-event/[0m directory, especially [47meval-tests.lisp[0m.  Another
  example, [47mbooks/make-event/defrule.lisp[0m, shows how to use macros
  whose calls expand to [47mmake-event[0m forms, which in turn can generate
  [events].  For more examples, see file [47mbooks/make-event/Readme.lsp[0m.
  Other than the examples, the explanations here should suffice for
  most users.  If you want explanations of subtler details, see
  [make-event-details].

  Note that [47mmake-event[0m 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
  [47mmake-event[0m or of event constructors such as [47m[progn][0m and
  [47m[encapsulate][0m.  For details see the section ``Restriction to Event
  Contexts'', below.

  [47mMake-event[0m 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.

      ``is evaluated'' --- The argument can be any expression, which is
      evaluated as would be any expression submitted to ACL2's top
      level loop.  Thus, [47m[state][0m and user-defined [47m[stobj][0ms may appear
      in the form supplied to [47mmake-event[0m.  Henceforth, we will refer
      to this evaluation as ``expansion.'' Expansion is actually done
      in a way that restores ACL2's built-in [47m[state][0m global
      variables, including the logical [world], to their
      pre-expansion values (with a few exceptions --- see
      [make-event-details] --- and where we note that changes to
      user-defined [47m[state][0m global variables (see [assign]) are
      preserved).  So, for example, events might be evaluated during
      expansion, but they will disappear from the logical [world]
      after expansion returns its result.  Moreover, proofs are
      enabled by default during expansion (see [ld-skip-proofsp]) if
      keyword [47m:CHECK-EXPANSION[0m is supplied a non-[47mnil[0m value or a
      certain attachment is made (see (4) below).

      ``expansion result'' --- The above expansion may result in an
      ordinary (non-[47m[state][0m, non-[47m[stobj][0m) value, which we call the
      ``expansion result.'' Or, expansion may result in a multiple
      value of the form [47m(mv erp val state)[0m, or, more generally, [47m(mv
      erp val state stobj-1 ... stobj-k)[0m where each [47mstobj-i[0m is a
      [stobj]; then the expansion result is [47mval[0m unless [47merp[0m is not
      [47mnil[0m, in which case there is no expansion result, and the
      original [47mmake-event[0m evaluates to a soft error.  In either case
      (single or multiple value), either [47mval[0m is an embedded event
      form (see [embedded-event-form]), or else the original
      [47mmake-event[0m evaluates to a soft error, printed as described
      under ``Error Reporting'' below.
      ([3mTechnical remark[0m: The expansion result described above may be
      modified for [47m[include-book][0m, [47m[add-include-book-dir][0m, and
      [47m[add-include-book-dir!][0m, replacing [book-name]s to indicate
      [full-book-name]s.  For further details see comments in source
      function [47mmake-include-books-absolute[0m.  End of technical
      remark.)

      ``evaluated again'' --- the expansion result is evaluated in place of
      the original [47mmake-event[0m.

  The expansion process can invoke subsidiary calls of [47mmake-event[0m, and
  the expansion result can (perhaps after macroexpansion) be a call
  of [47mmake-event[0m.  It can be useful to track all these [47mmake-event[0m
  calls.  The [state] global variable [47mmake-event-debug[0m may be set to
  a non-[47mnil[0m value, for example [47m(assign make-event-debug t)[0m, in order
  to see a trace of the expansion process, where a level is displayed
  (as in ``[47m3>[0m'') to indicate the depth of subsidiary expansions.

  Expansion of a [47mmake-event[0m call will yield an event that replaces the
  original [47mmake-event[0m call.  In particular, if you put a [47mmake-event[0m
  form in a book, then in essence it is replaced by its expansion
  result, created during the proof pass of the [47m[certify-book][0m
  process.  We now elaborate on this idea of keeping the original
  expansion.

  A [47mmake-event[0m call generates a ``[47mmake-event[0m 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
  [47m:EXPANSION-ALIST[0m 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 [47m[include-book][0m will then include the
  book expansion corresponding to the indicated book.  When a book is
  compiled during [47m[certify-book][0m, 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 [47m(assign keep-tmp-files t)[0m.  Note
  however that all of the original forms must still be legal
  [events]; see [embedded-event-form].  So for example, if the first
  event in a book is [47m(local (defmacro my-id (x) x))[0m, and is followed
  by [47m(my-id (make-event ...))[0m, the final ``[47minclude-book[0m'' pass of
  [47m[certify-book][0m will fail because [47mmy-id[0m is not defined when the
  [47mmy-id[0m call is encountered.

  A [47mmake-event[0m replacement might not be the expansion when either of
  the keyword arguments [47m:CHECK-EXPANSION[0m or [47m:EXPANSION?[0m is supplied.
  We deal with the latter in the final section, on Advanced Expansion
  Control.  If [47m:CHECK-EXPANSION t[0m is supplied and the expansion is
  [47mexp[0m, then the replacement is obtained from the original [47mmake-event[0m
  call, by substituting [47mexp[0m for [47mt[0m as the value of keyword
  [47m:CHECK-EXPANSION[0m.  Such a [47mmake-event[0m call --- during the second
  pass of an [47m[encapsulate][0m, or during event processing on behalf of
  [47m[include-book][0m other than when including a book near the end of its
  certification process --- will do the expansion again and check
  that the expansion result is equal to the original expansion
  result, [47mexp[0m.  In the unusual case that you know the expected
  expansion result, [47mres[0m, you can specify [47m:CHECK-EXPANSION res[0m in the
  first place, so that the check is also done during the initial
  evaluation of the [47mmake-event[0m 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.

  (Here are details on the point made just above, for those who use the
  [47m:CHECK-EXPANSION[0m argument to perform side-effects on the [state].
  When you include a book, ACL2 generally loads a compiled file
  before processing the events in the book; see [book-compiled-file].
  While it is true that a non-[47mnil[0m [47m:CHECK-EXPANSION[0m argument causes
  [47m[include-book][0m to perform expansion of the [47mmake-event[0m form during
  event processing it does [3mnot[0m perform expansion when the compiled
  file (or expansion file; again, see [book-compiled-file]) is
  loaded.)

  ACL2 performs the following space-saving optimization: when the
  expansion result is a [47m[local][0m event, then the [47mmake-event[0m
  replacement is [47m(local (value-triple :ELIDED))[0m.

  The notion of ``expansion'' and ``replacement'' extend to the case
  that a call of [47mmake-event[0m is found in the course of macroexpansion.
  The following example illustrates this point.

    (encapsulate
     ()
     (defmacro my-mac ()
       '(make-event '(defun foo (x) x)))
     (my-mac))
    :pe :here

  The above call of [47m[pe][0m shows that the form [47m(my-mac)[0m has a [47mmake-event[0m
  expansion (and replacement) of [47m(DEFUN FOO (X) X)[0m:

    (ENCAPSULATE NIL
                 (DEFMACRO MY-MAC
                           NIL
                           '(MAKE-EVENT '(DEFUN FOO (X) X)))
                 (DEFUN FOO (X) X))


Error Reporting

  Suppose that expansion produces a soft error as described above.
  That is, suppose that the argument of a [47mmake-event[0m call evaluates
  to a multiple value [47m(mv erp val state ...)[0m where [47merp[0m is not [47mnil[0m.
  If [47merp[0m is a string, then that string is printed in the error
  message.  If [47merp[0m is a [47m[cons][0m pair whose [47m[car][0m is a string, then the
  error prints [47m\"~@0\"[0m with [47m#\\0[0m bound to that [47mcons[0m pair; see [fmt].
  Any other non-[47mnil[0m value of [47merp[0m causes a generic error message to be
  printed.


Restriction to Event Contexts

  A [47mmake-event[0m call must occur either at the top level, or during
  [47mmake-event[0m 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 [47mmake-event[0m.

  The following examples illustrate this restriction.

    ; 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))

  More precisely: a [47mmake-event[0m call that is not itself evaluated during
  [47mmake-event[0m expansion is subject to the following requirement.
  After macroexpansion has taken place, such a [47mmake-event[0m 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 [embedded-event-form].)

    * A form submitted at the top level, or more generally, supplied to a
      call of [47m[ld][0m, is in an event context.

    * A form occurring at the top level of a book is in an event context.

    * If [47m([0m[47m[local][0m[47m x1)[0m is in an event context, then so is [47mx1[0m.

    * If [47m([0m[47m[skip-proofs][0m[47m x1)[0m is in an event context, then so is [47mx1[0m.

    * If [47m([0m[47m[make-event][0m[47m x ...)[0m is in an event context and its expansion [47mx1[0m
      is an embedded event form, then [47mx1[0m is in an event context.

    * If [47m([0m[47m[with-output][0m[47m ... x1)[0m, [47m([0m[47m[with-prover-step-limit][0m[47m ... x1 ...)[0m, or
      [47m([0m[47m[with-prover-time-limit][0m[47m ... x1)[0m is in an event context, then
      so is [47mx1[0m.

    * For any call of [47m[progn][0m or [47m[progn!][0m, each of its arguments is in an
      event context.

    * For any call of [47m[encapsulate][0m, each of its arguments except the first
      (the signature list) is in an event context.

    * If [47m(RECORD-EXPANSION x1 x2)[0m is in an event context, then [47mx1[0m and [47mx2[0m
      are in event contexts.  Note: [47mrecord-expansion[0m is intended for
      use only by the implementation.

  Low-level remark, for system implementors.  There is the one
  exception to the above restriction: a single [47m[state-global-let*][0m
  form immediately under a [47mprogn![0m call.  For example:

    (progn! (state-global-let* <bindings> (make-event ...)))

  However, the following form may be preferable (see [progn!]):

    (progn! :STATE-GLOBAL-BINDINGS <bindings> (make-event ...))

  Also see [remove-untouchable] for an interesting use of this
  exception.


Avoiding large [47mmake-event[0m forms in [certificate] files

  The [certificate] file for a book contains expansions of [47mmake-event[0m
  forms from the book.  (Those interested may find details about this
  in an Implementation Note about ``The book expansion'' in the
  documentation topic, [make-event-details].)  Those expansions can
  be very large if one is not careful.  Consider the difference
  between the following two events.

    (make-event
     `(defconst *foo* ,(length (w state))))

    (make-event
     `(defconst *foo* (length ',(w state))))

  The first generates an expansion such as [47m(defconst *foo* 122700)[0m
  (where the numeric value depends on the [world] in which the
  [47mmake-event[0m form is evaluated).  The second, however, generates an
  expansion of the form [47m(defconst *foo* (length '<wrld>))[0m, where
  [47m<wrld[0m is an ACL2 world --- a very large structure.  The [47m.cert[0m 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).


Examples Illustrating How to Access State

  You can modify the ACL2 [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.

  First consider the following.  Notice that expansion modifies a state
  global, [47mmy-global[0m, during [47mmake-event[0m expansion (see [assign]); and
  then, expansion returns a [47m[defun][0m event to be evaluated.

    (make-event
      (er-progn (assign my-global (length (w state)))
                (value '(defun foo (x) (cons x x)))))

  Then we get:

    ACL2 !>(@ my-global)
    72271
    ACL2 !>:pe foo
     L        1:x(MAKE-EVENT (ER-PROGN # #))

    >L            (DEFUN FOO (X) (CONS X X))
    ACL2 !>

  Here's a slightly fancier example, where the computation affects the
  [47m[defun][0m.  In a new session, execute:

    (make-event
      (er-progn (assign my-global (length (w state)))
                (value `(defun foo (x) (cons x ,(@ my-global))))))

  Then:

    ACL2 !>(@ my-global)
    72271
    ACL2 !>:pe foo
     L        1:x(MAKE-EVENT (ER-PROGN # #))

    >L            (DEFUN FOO (X) (CONS X 72271))
    ACL2 !>

  Because [47mmake-event[0m creates [event] forms that can go into [books] and
  [47m[encapsulate][0m events, you can use [47mmake-event[0m forms such as those
  above to modify the ACL2 [state] using books and [47mencapsulate[0m
  events.  The most common way to do this is for the [47mmake-event[0m
  expansion to be a trivial event form such as [47m(value-triple nil)[0m,
  such as the following.

    (make-event (er-progn (assign my-list-of-10 (make-list 10))
                          (value '(value-triple nil))))

  The desired effect will take place during calls of [47m[certify-book][0m,
  but it will generally [31;1mnot[0m take place during [47m[include-book][0m on a
  certified book because the expansion is evaluated (it is stored in
  the book's [certificate] for this purpose), but the expansion is
  merely [47m(value-triple nil)[0m.  To ensure that the original [47mmake-event[0m
  call is evaluated even when including the book, use
  [47m:check-expansion t[0m, for example as follows.

    (make-event (er-progn (assign my-list-of-10 (make-list 10))
                          (value '(value-triple nil)))
                :check-expansion t)

  Note that ACL2 [table] [events] may avoid the need to use [state]
  globals.  For example, instead of the example above, consider this
  example in a new session.

    (make-event
      (let ((world-len (length (w state))))
        `(progn (table my-table :STORED-WORLD-LENGTH ,world-len)
                (defun foo (x) (cons x ,world-len)))))

  Then:

    ACL2 !>(table my-table)
     ((:STORED-WORLD-LENGTH . 72271))
    ACL2 !>:pe foo
              1:x(MAKE-EVENT (LET # #))

    >L            (DEFUN FOO (X) (CONS X 72271))
    ACL2 !>

  Many built-in [state] globals revert after expansion.  If your own
  state global (like [47mmy-global[0m 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, [47m*protected-system-state-globals*[0m.  We advise users [31;1mnot[0m to
  assume that system state modifications, such as the state of
  guard-checking, will persist after executing a [47mmake-event[0m form;
  persistence depends on the relevant state globals not being in the
  list, [47m*protected-system-state-globals*[0m.

  That advice may suffice for most users.  But if you want to
  understand the point above more deeply, then consider the following
  example.

    (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)))))

  This [47mmake-event[0m form succeeds and afterwards, the value of [47m(@
  my-global)[0m is [47mnil[0m, which of course is the value expected after the
  call above of [47m[assign][0m.  However, the value of [47m(@
  guard-checking-on)[0m after executing this [47mmake-event[0m form is [47mt[0m, not
  [47m:none[0m.  That is because the symbol [47mguard-checking-on[0m belongs to the
  list of symbols stored in the constant,
  [47m*protected-system-state-globals*[0m, and thus the value of the state
  global [47mguard-checking-on[0m is reverted to its initial value (which
  was assume here is the default, [47mt[0m) after the [47mmake-event[0m form
  completes execution.

  [31;1mRemarks on [47m*Protected-system-state-globals*[0m[31;1m for advanced users.[0m

    * The constant [47m*protected-system-state-globals*[0m is defined to include
      all built-in state globals, [3mexcept[0m for those that the ACL2
      implementors have decided can safely retain values set during
      [47mmake-event[0m 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 [47mguard-checking-on[0m 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).

    * As noted in a comment in the example above, the macro
      [47m[set-guard-checking][0m sets the state global, [47m'guard-checking-on[0m.
      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
      [47mmake-event[0m form.  For system implementors, one however needs to
      work with the ACL2 system by looking at the definition of the
      utility --- in this example, [47mset-guard-checking[0m --- or at the
      least, get a sense of its expansion by using macroexpansion
      (for example see [trans1]).


Advanced Expansion Control

  We conclude this [documentation] section by discussing additional
  control over [47mmake-event[0m expansion.  The discussion below is split
  into the following parts; further discussion follows.  The first
  three parts are illustrated in community book
  [47mbooks/make-event/make-event-keywords-or-exp.lisp[0m.

  (1) The value produced by expansion may have the form [47m(:DO-PROOFS
  exp)[0m, which specifies [47mexp[0m as the expansion result, to be evaluated
  without skipping proofs even when including a book.

  (2) The value produced by expansion may have the form [47m(:OR exp-1 ...
  exp-k)[0m, which specifies that the first form [47mexp-i[0m to evaluate
  without error is the expansion result.

  (3) The keyword argument [47m:EXPANSION?[0m can serve to eliminate the
  storing of [47mmake-event[0m replacements, as described above for the
  ``book expansion'' of a book.

  (4) In contexts where proofs are normally skipped (see
  [ld-skip-proofsp]), the expansion phase normally takes place with
  proofs skipped unless the [47m:CHECK-EXPANSION[0m keyword is supplied a
  non-[47mnil[0m value.  However, proofs can be made to take place
  unconditionally during the expansion phase by using an attachment,
  as discussed below.

  We now elaborate on each of these.

  (1) [47m:DO-PROOFS[0m ``call'' produced by expansion.

  We have discussed the expansion result produced by the expansion
  phase of evaluating a [47mmake-event[0m call.  However, if the expansion
  phase produces an expression of the form [47m(:DO-PROOFS exp)[0m, then the
  expansion result is actually [47mexp[0m.  The [47m:DO-PROOFS[0m wrapper indicates
  that even if proofs are currently being skipped (see
  [ld-skip-proofsp]), then evaluation of [47mexp[0m should take place with
  proofs not skipped.  For example, proofs will be performed when
  evaluating the [47mmake-event[0m expansion, namely the indicated [47mdefthm[0m
  event, in the following example.

    (set-ld-skip-proofsp t state)
    (make-event '(:DO-PROOFS
                  (defthm app-assoc (equal
                                     (append (append x y) z)
                                     (append x y z)))))

  Note that such use of [47m:DO-PROOFS[0m causes proofs to be performed when
  evaluating the expansion while including an uncertified book.  But
  when including a certified book, then unless [47m:CHECK-EXPANSION[0m is
  supplied a non-[47mnil[0m value, the [47mmake-event[0m replacement will just be
  the expansion, which does not include the [47m:DO-PROOFS[0m wrapper and
  hence will be evaluated with proofs skipped.

  (2) [47m:OR[0m ``call'' produced by expansion.

  There may be times where you want to try different expansions.  For
  example, the community book [47mbooks/make-event/proof-by-arith.lisp[0m
  attempts to admit a given event, which we'll denote [47mEV[0m, by trying
  events of the following form as [47mBOOK[0m varies over different
  community books.

    (encapsulate
     ()
     (local (include-book BOOK :DIR :SYSTEM))
     EV)

  A naive implementation of this macro would evaluate all such
  [47m[encapsulate][0m 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 [47m[skip-proofs][0m, 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 [47m(:OR
  ev-1 ev-2 ... ev-k)[0m, where the list [47m(ev-1 ev-2 ... ev-k)[0m enumerates
  the generated encapsulate events.  In general, for this
  ``disjunctive case'' of a result from expansion, each [47mev-i[0m is
  evaluated in sequence, and the first that succeeds without error is
  considered to be the expansion result --- and a repeat evaluation
  is avoided.  If evaluation of each [47mev-i[0m results in an error, then
  so does the [47mmake-event[0m call.

  This special use of [47m:OR[0m in a value produced by expansion does not
  permit nesting such as [47m(:OR ev-1 (:OR ev-2 ev-3))[0m.  That is, when
  an expansion result is [47m(:OR ev-1 ev-2 ... ev-k)[0m, none of the [47mev-i[0m
  may be of the form [47m(:OR ...)[0m.  Note that it is allowed for [47mev-i[0m to
  be a call of [47mmake-event[0m, even one involving this special use of
  [47m:OR[0m.  If [47mev-i[0m is [47m(:DO-PROOFS ev-i')[0m, then [47mev-i'[0m is considered to be
  the expansion in place of [47mev-i[0m.

  (3) The [47m:EXPANSION?[0m keyword argument.

  If keyword argument [47m:EXPANSION?[0m has a non[47mnil[0m value, then the
  [47m:CHECK-EXPANSION[0m keyword must be omitted or have value [47mnil[0m or [47mt[0m,
  hence not a cons pair.

  The idea of the [47m:EXPANSION?[0m keyword is to give you a way to avoid
  storing expansion results in a book's [certificate].  Roughly
  speaking, when the expansion result matches the value of
  [47m:EXPANSION?[0m, then no expansion result is stored for the event by
  book certification; then when the book is later included, the value
  of [47m:EXPANSION?[0m 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 [47m:EXPANSION?[0m is used and also discuss other
  properties of this keyword.

  We modify the notion of ``expansion result'' for [47mmake-event[0m forms to
  comprehend the use of the [47m:EXPANSION?[0m keyword.  For that purpose,
  let's consider a call of [47mmake-event[0m to be ``reducible'' if it has
  an [47m:EXPANSION?[0m keyword with non-[47mnil[0m value, [47mexp[0m, and its
  [47m:CHECK-EXPANSION[0m keyword is missing or has value [47mnil[0m, in which case
  the ``reduction'' of this [47mmake-event[0m call is defined to be [47mexp[0m.
  The expansion result as originally defined is modified by the
  following ``recursive reduction'' process: recur through the
  original expansion, passing through calls of [47m[local][0m,
  [47m[skip-proofs][0m, [47m[with-output][0m, [47m[with-prover-step-limit][0m, and
  [47m[with-prover-time-limit][0m, and replacing (recursively) any reducible
  call of [47mmake-event[0m 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 [47m[progn][0m or [47m[encapsulate][0m, but that process is applied to
  the computation of expansions for their subsidiary [47m[make-event][0m
  calls.

  To explain further the effect of [47m:EXPANSION? exp[0m, we split into the
  following two cases.

  [31;1mCase 1[0m: Evaluation is not taking place when including a book or
  evaluating the second pass of an [47m[encapsulate][0m event; more
  precisely, the value of [47m(ld-skip-proofsp state)[0m is not the symbol
  [47mINCLUDE-BOOK[0m.  There are two subcases.

    * Case 1a: The expansion result is not reduction-equivalent to [47mexp[0m.
      Then the [47mmake-event[0m call is processed as though the [47m:EXPANSION?[0m
      keyword had been omitted.

    * Case 2a: The expansion result is reduction-equivalent to [47mexp[0m.  Then
      there is no [47mmake-event[0m replacement for this call of [47mmake-event[0m;
      no replacement will be put into the [certificate] file for a
      book containing this [47mmake-event[0m call.  When that book is
      subsequently included, the original form will be evaluated in
      the manner described in the next case.

  [31;1mCase 2[0m: Evaluation is taking place when including a book or
  evaluating the second pass of an [47m[encapsulate][0m event; more
  precisely, the value of [47m(ld-skip-proofsp state)[0m is the symbol
  [47mINCLUDE-BOOK[0m.  Then the expansion is [47mexp[0m.  The expansion phase is
  skipped unless [47m:CHECK-EXPANSION[0m is [47mt[0m.

  The [47m:EXPANSION?[0m keyword can be particularly useful in concert with
  the disjunctive (``[47m:OR[0m'') case (2) discussed above.  Suppose that
  expansion produces a value as discussed in (2) above, [47m(:OR exp-1
  ... exp-k)[0m.  If one of these expressions [47mexp-i[0m is more likely than
  the others to be the expansion, then you may wish to specify
  [47m:EXPANSION? exp-i[0m, as this will avoid storing a [47mmake-event[0m
  replacement in that common case.  This could be useful if the
  expressions are large, to avoid enlarging the [certificate] file
  for a book containing the [47mmake-event[0m call.

  It is legal to specify both [47m:EXPANSION? exp[0m and [47m:CHECK-EXPANSION t[0m.
  When either [47m(ld-skip-proofsp state)[0m is the symbol [47mINCLUDE-BOOK[0m, or
  evaluation is taking place in raw Lisp, then this combination is
  treated the same as if [47m:EXPANSION?[0m is omitted and the value of
  [47m:CHECK-EXPANSION[0m is [47mexp[0m.  Otherwise, this combination is treated
  the same as [47m:CHECK-EXPANSION t[0m, modified to accommodate the effect
  of [47m:EXPANSION?[0m as discussed above: if the expansion is indeed the
  value of [47m:EXPANSION?[0m, then no [47mmake-event[0m replacement is generated.

  (4) Unconditionally enabling proofs during the expansion phase using
  an attachment.

  Proofs are normally skipped during the expansion phase unless the
  [47m:CHECK-EXPANSION[0m keyword is supplied a non-[47mnil[0m value.  To cause
  proofs to take place unconditionally during the expansion phase,
  evaluate one of the following two forms, as explained below.

    (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)

  The first of these is probably preferred in most cases, since it does
  not have any effect while evaluating an [47m[include-book][0m form (more
  precisely, when [47m(ld-skip-proofsp state)[0m is [47m'include-book[0m).  The
  second removes that restriction.

  To restore the default behavior, evaluate the following.

    (defattach (always-do-proofs-during-make-event-expansion
                constant-nil-function-arity-0)
      :system-ok t)

  (If you would like an explanation of [47mdefattach[0m in general, see
  [defattach].)


Subtopics

  [Make-event-details]
      Details on [47m[make-event][0m expansion

  [Make-event-example-1]
      An example use of [47m[make-event][0m

  [Make-event-example-2]
      An example use of [47m[make-event][0m

  [Make-event-example-3]
      Using [47m[make-event][0m to define [47m[thm][0m")
 (MAKE-EVENT-DETAILS
  (MAKE-EVENT)
  "Details on [47m[make-event][0m expansion

  The normal user of [47mmake-event[0m can probably ignore this section, but
  we include it for completeness.  We assume that the reader has read
  and understood the basic documentation for [47mmake-event[0m (see
  [make-event]), but we begin below with a summary of expansion.


Introduction

  Here is a summary of how we handle expansion involving [47mmake-event[0m
  forms.

  [47m(make-event form :check-expansion nil)[0m

  This shows the [47m:check-expansion[0m default of [47mnil[0m, and is typical user
  input.  We compute the expansion [47mexp[0m of [47mform[0m, which is the
  expansion of the original [47mmake-event[0m expression and is evaluated in
  place of that expression.

  [47m(make-event form :check-expansion t)[0m

  The user presumably wants it checked that the expansion doesn't
  change in the future, in particular during [47m[include-book][0m.  If the
  expansion of [47mform[0m is [47mexp[0m, then we will evaluate [47mexp[0m to obtain the
  value as before, but this time we record that the expansion of the
  original [47mmake-event[0m expression is [47m(make-event form :check-expansion
  exp)[0m rather than simply [47mexp[0m.

  [47m(make-event form :check-expansion exp) ; exp a cons[0m

  This is generated for the case that [47m:check-expansion[0m is [47mt[0m, as
  explained above.  Evaluation is handled as described in that above
  case, except here we check that the expansion result is the given
  [47mexp[0m.  (Actually, the user is also allowed to supply such a form.)
  The original [47mmake-event[0m expression does not undergo any expansion
  (intuitively, it expands to itself).

  Now let us take a brief look at how we expand [47m[progn][0m and
  [47m[encapsulate][0m forms.  More details are found further below (see
  ``Detailed semantics'').

  [47m(progn ... (make-event form ...) ...)[0m

  The expansion is obtained, roughly speaking, by replacing the
  [47mmake-event[0m form by its expansion, [47mexp[0m, except that if
  [47m:check-expansion exp[0m is supplied explicitly, then no such
  replacement takes place.

  Expansion for [47m(encapsulate ... (make-event form ...) ...)[0m is similar
  to the case for [47mprogn[0m, except that if the expansion of [47mform[0m is [47mexp[0m,
  then what is stored is [47m(record-expansion (make-event form ...)
  exp)[0m.  Also as for [47mprogn[0m, the exception is that when
  [47m:check-expansion exp[0m is supplied explicitly, no such replacement
  takes place.  Here, [47mrecord-expansion[0m is a macro that simply returns
  its second argument, but is used for checking redundancy of
  [47mencapsulate[0m forms (see [redundant-encapsulate]).

  Certain ``wrappers'' around a [47mmake-event[0m are restored as the last
  part of the expansion process, in particular for [47mmake-event[0m calls
  that are inside calls of [47m[encapsulate][0m or [47m[progn][0m, as well as in
  events processed during a book's certification, including
  [portcullis] commands from the certification [world].  For example,
  if you evaluate a form [47m(local (with-prover-step-limit 100
  (make-event ...)))[0m where the [47mmake-event[0m call has expansion [47m<exp>[0m,
  and then you certify a book, the book's [certificate] file will
  include among its portcullis commands the form [47m(local
  (with-prover-step-limit 100 <exp>))[0m.  Macroexpansion is performed
  to determine the wrappers.  The wrappers thus restored are as
  follows.

    local
    skip-proofs
    with-cbd
    with-guard-checking-event
    with-output
    with-prover-step-limit
    with-prover-time-limit

  The discussion below references this process as the final expansion
  being ``rebuilt from'' the form.


Detailed semantics

  In our explanation of the semantics of [47mmake-event[0m, we assume
  familiarity with the notion of ``embedded event form'' (see
  [embedded-event-form]).

  Let's say that the ``actual embedded event form'' corresponding to a
  given form is the underlying call of an ACL2 event: that is,
  [47m[local][0ms are dropped when [47mld-skip-proofsp[0m is [47m'include-book[0m, and
  macros are expanded away, thus leaving us with a [47m[progn][0m, a
  [47m[make-event][0m, or an event form (possibly [47m[encapsulate][0m), any of
  which might have surrounding [47m[local][0m, [47m[skip-proofs][0m, or
  [47m[with-output][0m calls.

  Thus, such an actual embedded event form can be viewed as having the
  form [47m(rebuild-expansion wrappers base-form)[0m where [47mbase-form[0m is a
  [47mprogn[0m, a [47mmake-event[0m, or an event form (possibly [47mencapsulate[0m), and
  [47mwrappers[0m are (as in ACL2 source function [47mdestructure-expansion[0m) the
  result of successively removing the event form from the result of
  macroexpansion, leaving a sequence of [47m(local)[0m, [47m(skip-proofs)[0m, and
  [47m(with-output ...)[0m forms.  In this case we say that the form
  ``destructures into'' the indicated [47mwrappers[0m and [47mbase-form[0m, and
  that it can be ``rebuilt from'' those [47mwrappers[0m and [47mbase-form[0m.

  Elsewhere we define the notion of the ``expansion result'' from an
  evaluation (see [make-event]), and we mention that when expansion
  concludes, the ACL2 logical [world] and most of the [47mstate[0m are
  restored to their pre-expansion values.  Specifically, after
  evaluation of the argument of [47mmake-event[0m (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
  [47m*protected-system-state-globals*[0m.  Thus, assignments to
  user-defined state globals (see [assign]) do persist after
  expansion, since they are not in that list.

  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 [47mmake-event[0m subterm of an expansion
  result has a [47m:check-expansion[0m field that is a [47m[consp][0m, where for
  this purpose [47mmake-event[0m is viewed as a macro that returns its
  [47m:check-expansion[0m field.

      If the given form is not an embedded event form, then simply cause a
      soft error, [47m(mv erp val state)[0m where [47merp[0m is not [47mnil[0m.
      Otherwise:

      If the evaluation of the given form does not take place (presumably
      because [47m[local][0m events are being skipped), then no expansion
      takes place.  Otherwise:

      Let [47mx[0m be the actual embedded event form corresponding to the given
      form, which destructures into wrappers [47mW[0m and base-form [47mB[0m.  Then
      the original form is evaluated by evaluating [47mx[0m, and its
      expansion is as follows.

      If [47mB[0m is [47m(make-event form :check-expansion val)[0m, then expansion takes
      place if and only if [47mval[0m is not a [47mconsp[0m and no error occurs, as
      now described.  Let [47mR[0m be the expansion result from protected
      evaluation of [47mform[0m, if there is no error.  [47mR[0m must be an
      embedded event form, or it is an error.  Then evaluate/expand
      [47mR[0m, where if [47mval[0m is not [47mnil[0m then state global [47m'ld-skip-proofsp[0m
      is initialized to [47mnil[0m.  (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
      [47mmake-event[0m expression, as well as an expansion, [47mE_R[0m.  Let [47mE[0m be
      rebuilt from [47mW[0m and [47mE_R[0m.  The expansion of the original form is
      [47mE[0m if [47mval[0m is [47mnil[0m, and otherwise is the result of replacing the
      original form's [47m:check-expansion[0m field with [47mE[0m, with the added
      requirement that if [47mval[0m is not [47mt[0m (thus, a [47mconsp[0m) then [47mE[0m must
      equal [47mval[0m or else we cause an error.

      If [47mB[0m is [47m(progn form1 form2 ...)[0m (and similarly for [47m[progn!][0m), and at
      least one [47mformi[0m has an expansion, then the expansion of the
      original form is obtained by replacing each [47mformi[0m by its
      expansion and then rebuilding the entire [47mprogn[0m call from [47mB[0m.

      If [47mB[0m is [47m(encapsulate sigs form1 form2 ...)[0m, then after evaluating [47mB[0m,
      the expansion of the original form is the result of rebuilding
      from [47mB[0m, with wrappers [47mW[0m, after replacing each [47mformi[0m in [47mB[0m for
      which expansion takes place by [47m(record-expansion formi formi')[0m,
      where [47mformi'[0m is the expansion of [47mformi[0m.  Note that these
      expansions are determined as the [47mformi[0m are evaluated in
      sequence (where in the case of [47mencapsulate[0m, this determination
      occurs only during the first pass).  Except, if no expansion
      takes place for any [47mformi[0m, then the expansion of the original
      form is itself.

      Otherwise, the expansion of the original form is itself.

  (Optional Implementation Notes.  The latest expansion of a
  [47m[make-event][0m, [47m[progn][0m, [47m[progn!][0m, or [47m[encapsulate][0m is temporarily
  stored in state global [47m'last-make-event-expansion[0m, except that if
  no expansion has taken place for that form then
  [47m'last-make-event-expansion[0m has value [47mnil[0m.  Expansions ultimately
  show up in the world's [47m[command][0m tuples; for example, immediately
  after processing a command its expansion is
  [47m(access-command-tuple-last-make-event-expansion (cddr (car (w
  state))))[0m.  Top-level expansions do not include rebuilding of
  wrappers, although such wrappers are restored when constructing
  [portcullis] commands as discussed above.  End of Implementation
  Notes.)

  Similarly to the [47m[progn][0m and [47m[encapsulate][0m cases above, book
  certification causes a book to be replaced by its so-called ``book
  expansion,'' where each event [47mev[0m for which expansion took place
  during the proof pass of certification is replaced by its
  expansion, but with certain [47m[local][0m events elided.

  Optional Implementation Note.  The book expansion is actually
  implemented by way of the [47m:expansion-alist[0m field of its
  [certificate], which associates 0-based positions of top-level
  forms in the book (not including the initial [47m[in-package][0m 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.

  It is straightforward by computational induction to see that for any
  expansion of an embedded event form, every [47mmake-event[0m sub-event has
  a [47m[consp][0m [47m:check-expansion[0m field.  Here, by ``sub-event'' we mean
  to expand macros; and we also mean to traverse [47mprogn[0m and
  [47mencapsulate[0m forms as well as [47m:check-expansion[0m fields of [47mmake-event[0m
  forms.  Thus, we will only see [47mmake-event[0m forms with [47mconsp[0m
  [47m:check-expansion[0m fields in the course of [47minclude-book[0m forms, the
  second pass of [47mencapsulate[0m forms, and raw Lisp.  This fact
  guarantees that an event form will always be treated as its
  original expansion.


Notes on ttags

  See [defttag] for documentation of the notion of ``trust tag''
  (``ttag'').  We note here that even if an event [47m(defttag tag-name)[0m
  for non-[47mnil[0m [47mtag-name[0m is admitted only during the expansion phase of
  a [47m[make-event][0m form, then such expansion will nevertheless still
  cause [47mtag-name[0m to be recorded in the logical [world] (assuming that
  the [47mmake-event[0m form is admitted).  So in order to certify such a
  book, a suitable [47m:ttags[0m argument must be supplied; see
  [certify-book].

  ACL2 does provide a way to avoid the need for [47m:ttags[0m arguments in
  such cases.  The idea is to certify a book twice, where the results
  of [47mmake-event[0m expansion are saved from the first call of
  [47m[certify-book][0m and provided to the second call.  See
  [set-write-ACL2x].

  Finally, we discuss a very unusual case where certification does not
  involve trust tags but a subsequent [47m[include-book][0m does involve
  trust tags: a [47mmake-event[0m call specifying [47m:check-expansion t[0m, whose
  expansion generates a [47m[defttag][0m event during [47m[include-book][0m but not
  [47m[certify-book][0m.  Consider the following book.

    (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)

  This book certifies successfully without the need for a [47m:ttags[0m
  argument for [47m[certify-book][0m.  Indeed, the above book's
  [certificate] does not specify [47m:foo[0m as a trust tag associated with
  the book, because no [47mdefttag[0m event was executed during book
  certification.  Unfortunately, if we try to include this book
  without specifying a value of [47m:ttags[0m that allows [47m:foo[0m, book
  inclusion will cause executing of the above [47m[defttag][0m.  If that
  inclusion happens in the context of certifying some superior book
  and the appropriate [47m:ttags[0m arguments have not been provided, that
  certification will fail.


Expansion errors and the [47m:ON-BEHALF-OF[0m keyword argument

  Consider the case that expansion returns an [error-triple] [47m(mv erp
  val state)[0m, where [47merp[0m is not [47mnil[0m.  Then [47mmake-event[0m may conclude
  with an error message, as follows.

    * If keyword [47m:ON-BEHALF-OF[0m has value [47m:quiet![0m then there is no such
      concluding error message.

    * Otherwise, if [47merp[0m is a string, then the concluding error message is
      produced by printing [47merp[0m with the call [47m(er soft ctx erp)[0m, where
      [47mctx[0m is the context (see [ctx]).

    * Otherwise, if [47merp[0m is a message (see [msg]), then the concluding error
      message is produced by the call [47m(er soft ctx \"~@0\" erp)[0m, where
      [47mctx[0m is the context (see [ctx]).

    * Otherwise, if keyword [47m:ON-BEHALF-OF[0m has value [47m:quiet[0m then there is no
      concluding error message.

    * Otherwise, if keyword [47m:ON-BEHALF-OF[0m is not supplied or has value [47mnil[0m
      --- so we are now in the typical case --- then the concluding
      error message is ``Error in MAKE-EVENT from expansion of:''
      followed by the form.

    * Otherwise, keyword [47m:ON-BEHALF-OF[0m has a value [47mx[0m other than [47m:quiet![0m,
      [47m:quiet[0m, or [47mnil[0m, 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 [47mx[0m.

  Note that errors generated during expansion are not affected by the
  cases above; those only control the concluding error message, if
  any.


The [47m:save-event-data[0m keyword argument

  See [get-event-data] for relevant background on data stored for each
  event.  The association list stored in [47mlast-event-data[0m is normally
  replaced every time an event concludes (at the summary phase), and
  that holds for calls of [47mmake-event[0m.  But there is the following
  exception: when [47mmake-event[0m is called with a non-[47mnil[0m value for
  keyword [47m:save-event-data[0m, then that association list persists from
  the expansion phase.  This is how the [47m[thm][0m macro is able to
  populate the [47mlast-event-data[0m association list without having that
  list be smashed when the surrounding [47mmake-event[0m (used for
  implementing [47mthm[0m) concludes.")
 (MAKE-EVENT-EXAMPLE-1
  (MAKE-EVENT)
  "An example use of [47m[make-event][0m

  Here, we develop a reasonably self-contained example that illustrates
  how to use [47mmake-event[0m to develop tools, by solving a challenge
  posed by Alessandro Coglio.  For another such example, see
  [make-event-example-2].

  The challenge is to develop a programmatic method for solving the
  following sort of problem.

   1. Create a [47m[defun][0m form.

   2. Submit it to ACL2, obtaining a new ACL2 [state] whose [world]
      includes the function just submitted.

   3. Access various elements of this function (e.g., unnormalized body).

   4. Create and return a new [47mdefun[0m that's based on elements of the
      previous one.

   5. Submit this new defun via a [47m[make-event][0m, but in a state that does
      not include the previous [47mdefun[0m.

  We illustrate how to do this sort of thing by specifying the ``new
  [47mdefun[0m that's based on elements of the previous one'' to be as
  follows: add the formal, [47my[0m, and modify the body so that [47my[0m is consed
  onto the old body.  Of course, this is a trivial example that could
  be done without [47mmake-event[0m; 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 [47my[0m is already a formal of the existing [47mdefun[0m.  Here
  are the main steps.

    * (a) Submit the [47mdefun[0m.

    * (b) Gather information from the resulting world.  In this case, we
      access the formals and body of the definition.

    * (c) Create the desired event.

  The following code does those three things, as explained in comments
  below, which include references to the three steps above.

    (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)))))

  So far so good: we have computed an error triple [47m(mv nil val state)[0m
  whose value component, [47mval[0m, is the desired [47mdefun[0m form.  However,
  that leaves us in a world that includes the first [47mdefun[0m form.  For
  a solution to the original challenge (for our specific case), that
  must not be the case, and moreover the second [47mdefun[0m form should be
  included in the current world.  Fortunately, [47m[make-event][0m is
  perfectly suited to do both of these things.  Consider the
  following form, which simply wraps [47mmake-event[0m around the code
  displayed just above.

    (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))))))

  The expansion phase (see [make-event]) computes the new [47mdefun[0m form
  --- the one with the extra formal and modified body --- and then
  that new [47mdefun[0m form is evaluated in the original world, which does
  not include the first [47mdefun[0m form.

  We complete the job by making a programmatic solution, with a macro
  that expands to such a [47mmake-event[0m form.  We make it nice by
  inhibiting all output except error output.

    (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!))

  This could be improved by doing some error checking, but we leave
  that as an exercise.

  Below is a log, with comments added, that shows uses of the macro
  above.

    ; 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 !>")
 (MAKE-EVENT-EXAMPLE-2
  (MAKE-EVENT)
  "An example use of [47m[make-event][0m

  Here, we develop a reasonably self-contained example that illustrates
  how to use [47mmake-event[0m to develop tools.  For another such example,
  see [make-event-example-1].  We thank Yan Peng for putting forward
  this problem.

  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.


Prerequisites

  We assume some general ACL2 and Common Lisp background, including
  familiarity with [macros] and backquote.  But we do some
  programming below that goes beyond that general background in our
  use of the ACL2 [state].  See [programming-with-state] for relevant
  discussion, including state global variables, [47m[f-get-global][0m,
  [47m[f-put-global][0m, [error-triple]s and their construction using [47mvalue[0m,
  [47m[value-triple][0m, and [47m[pprogn][0m.  We also assume familiarity with both
  [47m[progn][0m and the notion of legal event form; 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.

  Next, we present the challenge problem that we will solve below.


Challenge problem

      Define a utility that evaluates a given sequence of [events], even
      continuing past errors, which stores the list of event forms
      that caused errors.

  Let us call this utility [47mprogn+[0m, since it can be viewed as an
  enhancement of [47m[progn][0m.  So a successful solution should allow us
  to evaluate the following form to define function symbols [47mf1[0m, [47mf2[0m,
  and [47mf3[0m, as well as the event [47mgood-thm[0m, and also store the events
  for [47mbad-thm[0m and [47mbad-fn[0m.

    (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)
            )

  We next present a definition of [47mprogn+[0m, together with output from the
  example displayed above.  After that we will start from the
  beginning and describe how one might develop [47mprogn+[0m from scratch.


The completed code and a test

    (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)
            )

  After running the example (which is the final form above), we expect
  the resulting logical [world] to contain definitions of function
  symbols [47mf1[0m, [47mf2[0m, and [47mf3[0m, as well as the event [47mgood-thm[0m, but that no
  events would be stored for [47mbad-thm[0m or [47mbad-fn[0m.  Moreover, we expect
  that a state global variable holds the event forms for [47mbad-thm[0m and
  [47mbad-fn[0m.  Let us check that all of these expectations are met.

    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 !>


Development of the solution

  We now start from the beginning.  Recall that [47m[progn][0m does almost
  what we ask [47mprogn+[0m to do, except that [47m[progn][0m stops at the first
  error.  So our approach will be to define a macro that is much like
  [47mprogn[0m, 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 [programming-with-state]),
  [47mprogn+-errors[0m.  Moreover, since [47m[progn][0m is applied only to legal
  event forms (see [embedded-event-form]), we need this modification
  to be a legal event form, too.  Fortunately, a call of [47m[make-event][0m
  is a legal event form.  So our plan is for [47m(progn+ ... <event> ...)[0m
  to expand to a call [47m(progn ... (make-event ...) ...)[0m so that the
  indicated [47mmake-event[0m call attempts to evaluate [47m<event>[0m, and if that
  attempt fails, then [47m<event>[0m it is pushed onto [47mprogn+-errors[0m.

  Thus, we begin with a simple piece of the task, by showing how to
  create an event that will push a specific form, [47m(defthm bad-thm
  (equal x y) :rule-classes nil)[0m, onto [47mprogn+-errors[0m.

    (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))))

  It might seem more natural to write [47m(f-put-global ...)[0m, instead of
  the more complex [47m(pprogn (f-put-global ...) (value '(value-triple
  nil)))[0m.  However, the argument to [47mmake-event[0m must evaluate to
  either: (1) a legal event form; or (2) an [error-triple], [47m(mv nil x
  state)[0m, where [47mx[0m is a legal event form.  Since the [47mf-put-global[0m call
  modifies state, (1) is not an option; so we choose (2).  Since the
  role of [47mx[0m is only to provide an event form, we choose [47mx[0m to be the
  trivial event form [47m(value-triple nil)[0m.

  We follow good programming practice by wrapping the functionality
  displayed above into a concise utility, as follows.

    (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)))))

  Before we write [47mprogn+[0m, 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 [47mprogn[0m but with those two
  forms replaced by calls to [47msave-progn+-error[0m.

    (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)
            )

  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
  [47msave-progn+-error[0m.  Fortunately, the [47m:OR[0m keyword of [47m[make-event][0m is
  perfect for this task.  Consider the following two examples.

    (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))))

  In the first example, [47mmake-event[0m invokes the given call of [47m[defun][0m,
  which runs without error; and [47mmake-event[0m then exits without error.
  In the second example, [47mmake-event[0m invokes the given call of [47mdefun[0m,
  which causes an error; so then [47mmake-event[0m evaluates the second
  argument of the [47m:OR[0m, to invoke [47msave-progn+-error[0m on that same [47mdefun[0m
  call.  Since that call of [47msave-progn+-error[0m evaluates without error
  (because it expands to [47m(value-triple nil)[0m), the [47mmake-event[0m call
  exits without error.  See [make-event] for more information about
  the [47m:OR[0m keyword.

  We can now define [47mprogn+[0m 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.

    (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))))))

  We complete our definition of [47mprogn+[0m, by generating a [47mprogn[0m call with
  the desired modification of each form in the list, using [47mprogn+-fn[0m
  --- but preceded by yet another [47mmake-event[0m call, this one for
  initializing our state global to [47mnil[0m.

    (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)))

  [31;1mExercise[0m: 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
  [make-event-example-2-exercise] for a solution.


Subtopics

  [Make-event-example-2-exercise]
      Solution to an exercise from [47m[make-event-example-2][0m")
 (MAKE-EVENT-EXAMPLE-2-EXERCISE
  (MAKE-EVENT-EXAMPLE-2)
  "Solution to an exercise from [47m[make-event-example-2][0m

  See [make-event-example-2] for a worked example using [47m[make-event][0m,
  concluding with an exercise.  Here we present a solution to that
  exercise.  It assumes that we have evaluated the definitions of
  [47msave-progn+-error[0m, [47mprogn+-fn[0m, and [47mprogn+[0m from
  [make-event-example-2].

    (defmacro progn+-errors (&rest lst)
      (declare (xargs :guard (and (true-listp lst)
                                  lst)))
      `(progn (progn+ ,@lst)
              (make-event
               (list 'value-triple
                     (list 'quote
                           (reverse (f-get-global 'progn+-errors state)))))))")
 (MAKE-EVENT-EXAMPLE-3
  (MAKE-EVENT)
  "Using [47m[make-event][0m to define [47m[thm][0m

  The definition of [47m[thm][0m provides a simple, yet informative, example
  use of [47mmake-event[0m.  Formerly (through ACL2 Version 8.1), this was
  the definition of [47mthm[0m, where [47mthm-fn[0m provides an interface to the
  prover.

    (defmacro thm (term &key hints otf-flg)
      (list 'thm-fn
            (list 'quote term)
            'state
            (list 'quote hints)
            (list 'quote otf-flg)))

  However, this version of [47mthm[0m did not permit calls of [47mthm[0m in [books]
  or [47m[encapsulate][0m forms.  To remedy that deficiency, the definition
  was changed to the following; below we explain components of this
  definition.  (It has since been updated further, but that is not
  relevant here so we don't comment here on further updates.)

    (defmacro thm (&whole event-form
                          term &key hints otf-flg)
      `(with-output :off summary :stack :push
         (make-event (er-progn (with-output :stack :pop
                                 (thm-fn ',term
                                         state
                                         ',hints
                                         ',otf-flg
                                         ',event-form))
                               (value '(value-triple :invisible)))
                     :expansion? (value-triple :invisible)
                     :on-behalf-of :quiet!
                     :save-event-data t)))

  The use of [47m[with-output][0m avoids printing anything about [47mmake-event[0m in
  the [summary] (by using [47m:off summary[0m).  But we do want a summary
  for the prover call itself, to see the rules used, time elapsed,
  and so on.  By using the keyword argument [47m:stack :push[0m, but then
  calling [47mwith-output[0m again with argument [47m:stack :pop[0m before calling
  [47mthm-fn[0m, we remove the effect of [47m:off summary[0m before calling [47mthm-fn[0m.

  By ignoring the [47mwith-output[0m wrapper, we may view the body of the
  [47mmake-event[0m form as follows.

    (er-progn (thm-fn ...)
              (value '(value-triple :invisible)))

  Evaluation of this call of [47m[er-progn][0m causes [47mthm-fn[0m to be run and, if
  there is no error and the proof succeeds, to return the event
  [47m(value-triple :invisible)[0m.  That event is a no-op, and it generally
  doesn't even cause a value to be printed; see [ld-post-eval-print].

  Since an error-free expansion is always [47m(value-triple :invisible)[0m,
  that event is specified with the [47m:expansion?[0m keyword so that the
  expansion is not stored, in particular in a book's [certificate]
  file.  See [make-event].

  The use of [47m:on-behalf-of :quiet![0m avoids a needless, distracting error
  message from [47mmake-event[0m when the proof fails.

  The [47m:save-event-data[0m keyword argument is a low-level implementation
  detail that we ignore here.")
 (MAKE-FAST-ALIST
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(make-fast-alist alist)[0m creates a fast-alist from the input alist,
  returning [47malist[0m itself or, in some cases, a new object equal to it.

  Note: it is often better to use [47mwith-fast-alist[0m; see
  [with-fast-alist].

  Logically, [47mmake-fast-alist[0m is the identity function.

  [31;1mFunction: [0m<make-fast-alist>

    (defun make-fast-alist (alist)
      (declare (xargs :guard t))
      alist)

  Under the hood, we construct and return an object that is [47mequal[0m to
  [47malist[0m and which is a fast alist.  If [47malist[0m is already a fast alist,
  almost no work is required: we simply return it unchanged.

  When [47malist[0m is not fast, we must minimally construct a hash table for
  its bindings.  It is often possible to bind this new hash table to
  [47malist[0m itself.  But in certain cases when the alist keys are not
  [normed], a new alist must be constructed, also, and so we may
  return an [47mequal[0m but not [47meq[0m alist.  (In these cases, we still try to
  avoid at least some consing by reusing the \"longest normed tail\" of
  the alist.)")
 (MAKE-LAMBDA (POINTERS)
              "See [system-utilities].")
 (MAKE-LAMBDA-APPLICATION (POINTERS)
                          "See [system-utilities].")
 (MAKE-LAMBDA-TERM (POINTERS)
                   "See [system-utilities].")
 (MAKE-LIST
  (LISTS ACL2-BUILT-INS)
  "Make a list of a given size

  For a nonnegative integer [47msize[0m, [47m(Make-list size)[0m is a list of
  elements of length [47msize[0m, each of which is initialized to the
  [47m:initial-element[0m (which defaults to [47mnil[0m).

  [47mMake-list[0m is a macro in ACL2, defined in terms of a tail recursive
  function [47mmake-list-ac[0m whose [guard] requires [47msize[0m to be a
  nonnegative integer.  [47mMake-list[0m is a Common Lisp function.  See any
  Common Lisp documentation for more information.

  [31;1mMacro: [0m<make-list>

    (defmacro make-list (size &key initial-element)
      (cons 'make-list-ac
            (cons size (cons initial-element '(nil)))))

  [31;1mFunction: [0m<make-list-ac>

    (defun make-list-ac (n val ac)
      (declare (xargs :guard (and (integerp n) (>= n 0))))
      (cond ((zp n) ac)
            (t (make-list-ac (1- n)
                             val (cons val ac)))))")
 (MAKE-LIST-AC (POINTERS)
               "See [make-list].")
 (MAKE-ORD
  (ORDINALS ACL2-BUILT-INS)
  "A constructor for ordinals.

  [47mMake-ord[0m is the ordinal constructor.  Its use is recommended instead
  of using [47m[cons][0m to make ordinals.  For a discussion of ordinals,
  see [ordinals].

  For any ordinal, [47malpha < epsilon-0[0m, there exist natural numbers [47mp[0m and
  [47mn[0m, positive integers [47mx1, x2, ..., xn[0m and ordinals [47ma1 > a2 > ... >
  an > 0[0m such that [47malpha > a1[0m and [47malpha = w^(a1)x1 + w^(a2)x2 + ... +
  w^(an)xn + p[0m.  We call [47ma1[0m the ``first exponent'', [47mx1[0m the ``first
  coefficient'', and the remainder [47m(w^(a2)x2 + ... + w^(an)xn + p)[0m
  the ``rest'' of alpha.

  [47m(Make-ord fe fco rst)[0m corresponds to the ordinal [47m(w^fe)fco + rst[0m.
  Thus the first infinite ordinal, [47mw[0m ([47momega[0m), is constructed by

    (make-ord 1 1 0)

  and, for example, the ordinal [47m(w^2)5 + w2 + 7[0m is constructed by:

    (make-ord 2 5 (make-ord 1 2 7)) .

  The reason [47mmake-ord[0m is used rather than [47m[cons][0m is that it allows us
  to reason more abstractly about the ordinals, without having to
  worry about the underlying representation.

  [31;1mFunction: [0m<make-ord>

    (defun make-ord (fe fco rst)
      (declare (xargs :guard (and (posp fco) (o-p fe) (o-p rst))))
      (cons (cons fe fco) rst))")
 (MAKE-SUMMARY-DATA
  (CLAUSE-PROCESSOR)
  "Return summary data from a [clause-processor] function

  For relevant background, see [clause-processor].  Here we discuss the
  value [47md[0m and its effect in the signature [3+] shown in that topic:

    [3+] ((CL-PROC cl hint st_1 ... st_k) => (mv erp cl-list st_i1 ... st_in d))

  The purpose of [47md[0m is to return [summary] information, as illustrated
  by the following (admittedly artificial) example.  Here we
  abbreviate somewhat; the full example may be found in the
  [community-book], [47mbooks/clause-processors/basic-examples.lisp[0m.

    (defevaluator evl evl-list ...)

    (defun strengthen-cl2 (cl term state)
      (declare (xargs :stobjs state))
      (cond ((null term) ; then no change
             (mv nil (list cl) state nil))
            ...
            ((pseudo-termp term)
             (mv nil
                 (list (cons (list 'not term)
                             cl)
                       (list term))
                 state
                 (make-summary-data :runes '((:rewrite car-cons)
                                             (:rewrite cdr-cons)
                                             (:rewrite car-cons))
                                    :use-names '(nth binary-append)
                                    :by-names '(nthcdr)
                                    :clause-processor-fns
                                    '(note-fact-clause-processor))))
            (t ..)))

    (defthm correctness-of-strengthen-cl2
      (implies (and (pseudo-term-listp cl)
                    (alistp a)
                    (evl (conjoin-clauses
                          (clauses-result (strengthen-cl2 cl term state)))
                         a))
               (evl (disjoin cl) a))
      :rule-classes :clause-processor)

    (defthm test-strengthen-cl2
      (equal y y)
      :hints ((\"Goal\"
               :instructions
               ((:prove
                 :hints ((\"Goal\"
                          :clause-processor
                          (strengthen-cl2 clause '(equal x x) state)))))))
      :rule-classes nil)

  Evaluation of the final [47mdefthm[0m event above prints the following
  [summary], which illustrates how the values of the four legal
  keywords for [47mmake-summary-data[0m naturally translate to the summary,
  specifically, to the [47m\"Rules\"[0m field for the [47m:runes[0m keyword and to
  the [47m\"Hint-events\"[0m field for the others.

    Summary
    Form:  ( DEFTHM TEST-STRENGTHEN-CL2 ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)
            (:REWRITE CAR-CONS)
            (:REWRITE CDR-CONS))
    Hint-events: ((:BY NTHCDR)
                  (:CLAUSE-PROCESSOR NOTE-FACT-CLAUSE-PROCESSOR)
                  (:CLAUSE-PROCESSOR STRENGTHEN-CL2)
                  (:USE BINARY-APPEND)
                  (:USE NTH))
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  Note that each keyword is optional; in particular, the form
  [47m(make-summary-data)[0m is legal, and it specifies [47mnil[0m for each of the
  four keywords.  Moreover, it is also legal for [47md[0m to be [47mnil[0m, which
  is equivalent to [47m(make-summary-data)[0m.  Thus, if [47md[0m is [47mnil[0m or
  [47m(make-summary-data)[0m then [3+] and [3] in the documentation for
  [clause-processor] have the same effect: that is, there will be no
  visible effect if we change such a clause-processor function (i.e.,
  one returning empty summary data) from form [3+] to form [3] by
  dropping the return value of [47md[0m.

  Duplicates are allowed in the list, for each argument of
  [47mmake-summary-data[0m; no duplicates will appear in the summary.  There
  is also no need to sort elements of those lists.

  Finally, note that the summary information from [47md[0m not only goes into
  the summary, but also is incorporated when extending the
  [proof-supporters-alist] to record the dependencies of the
  completed event.

    (assert-event
     (equal (sort-symbol-listp
             (car (global-val 'proof-supporters-alist (w state))))
            '(BINARY-APPEND CAR-CONS CDR-CONS
                            NOTE-FACT-CLAUSE-PROCESSOR NTH NTHCDR
                            STRENGTHEN-CL2 TEST-STRENGTHEN-CL2)))")
 (MAKE-TAU-INTERVAL
  (TAU-SYSTEM ACL2-BUILT-INS)
  "Make a tau interval

    General Form:
    (make-tau-interval doc lo-rel lo hi-rel hi)

  An interval is a structure of the form: [47m([0m[3mdom[0m [47m([0m[3mlo-rel[0m [47m.[0m [3mlo[0m[47m)[0m [47m.[0m [47m([0m[3mhi-rel[0m
  [47m.[0m [3mhi[0m[47m))[0m.  Every tau contains an interval used to represent the
  domain, the upper, and the lower bounds of the objects recognized
  by the tau.

  [47mmake-tau-interval[0m constructs well-formed intervals only if its five
  arguments satisfy certain restrictions given below.  When these
  restrictions are violated [47mmake-tau-interval[0m can construct objects
  that are not intervals!  [47mmake-tau-interval[0m does not attempt to
  coerce or adjust its arguments to make well-formed intervals.

  For examples of intervals (and non-intervals!) constructed by
  [47mmake-tau-interval[0m see [47m[tau-intervalp][0m.  For examples of what
  objects are contained in certain intervals, see [47m[in-tau-intervalp][0m.

  The components of an interval are as follows:

  [3mDom[0m (``domain'') must be one of four symbols: [47mINTEGERP[0m, [47mRATIONALP[0m,
  [47mACL2-NUMBERP[0m, or [47mNIL[0m denoting no restriction on the domain.

  The two ``relations,'' [3mlo-rel[0m and [3mhi-rel[0m are Booleans, where [47mt[0m
  denotes less-than inequality ([47m[<][0m) and [47mnil[0m represents
  less-than-or-equal inequality ([47m[<=][0m).  Think of [47mt[0m meaning
  ``strong'' and [47mnil[0m meaning ``weak'' inequality.

  [3mLo[0m and [3mhi[0m must be either [47mnil[0m or explicit rational numbers.  If [3mlo[0m is
  [47mnil[0m it denotes negative infinity; if [3mhi[0m is [47mnil[0m it denotes positive
  infinity.  [3mLo[0m must be no greater than [3mhi[0m.  [3mNote[0m: Even though
  [47mACL2-NUMBERP[0m intervals may contain complex rationals, the [3mlo[0m and [3mhi[0m
  bounds must be rational.  This is an arbitrary decision made by the
  implementors to simplify coding.

  Finally, if the [3mdom[0m is [47mINTEGERP[0m, then both relations should be weak
  and [3mlo[0m and [3mhi[0m must be integers when they are non-[47mnil[0m.

  For [3mx[0m to be ``in'' an interval it must be of the type described by
  the domain predicate [3mdom[0m, [3mlo[0m must be smaller than [3mx[0m in the strong
  or weak sense denoted by [3mlo-rel[0m, and [3mx[0m must be smaller than [3mhi[0m in
  the strong or weak sense denoted by [3mhi-rel[0m.

  The components of an interval may be accessed with the functions
  [47m[tau-interval-dom][0m, [47m[tau-interval-lo-rel][0m, [47m[tau-interval-lo][0m,
  [47m[tau-interval-hi-rel][0m, and [47m[tau-interval-hi][0m.")
 (MAKE-WORMHOLE-STATUS
  (WORMHOLE)
  "Creates a wormhole status object from given status, entry code, and
  data

    General Form:  (make-wormhole-status whs code data)

  See [wormhole].  [47mWhs[0m is generally a well-formed wormhole status (but
  see below), [47mcode[0m should be [47m:ENTER[0m or [47m:SKIP[0m, and [47mdata[0m is arbitrary.
  This function returns a new status with the specified entry code
  and data.  The result does not logically depend on [47mwhs[0m, but if the
  wormhole status corresponding to the given code and data is equal
  to [47mwhs[0m, then [47mwhs[0m is returned, which will save a cons.

  [31;1mWarning[0m: if [47mdata[0m is large then the equality test can be slow.  That
  problem is avoided by passing [47mwhs = nil[0m.  For an example of this
  use of [47mnil[0m in the ACL2 source code, see source function
  [47msave-ev-fncall-guard-er[0m.")
 (MAKUNBOUND-GLOBAL
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Remove the value assigned to a global variable in [47m[state][0m

    Examples:
    (makunbound-global 'y state)

    General Form:
    (makunbound-global s state)

  where [47ms[0m evaluates to a symbol.

  This value returned is the result of modifying the ACL2 [state] so
  that the given symbol does not have a value.  This function thus
  acts as a no-op if the symbol does not have a value in the given
  state.  Also see related utilities [47m[f-get-global][0m, [47m[f-put-global][0m,
  and [47m[f-boundp-global][0m.")
 (MANAGING-ACL2-PACKAGES
  (PACKAGES)
  "User-contributed documentation on packages

  Jared Davis has contributed documentation on {managing ACL2 packages
  |
  http://www.cs.utexas.edu/users/moore/acl2/contrib/managing-acl2-packages.html}.

  Also see [working-with-packages].")
 (MATCH-FREE (POINTERS)
             "See [free-variables].")
 (MAX
  (NUMBERS ACL2-BUILT-INS)
  "The larger of two numbers

  [47m(Max x y)[0m is the larger of the numbers [47mx[0m and [47my[0m.

  The [guard] for [47mmax[0m requires its arguments to be rational ([real], in
  ACL2(r)) numbers.

  [47mMax[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<max>

    (defun max (x y)
      (declare (xargs :guard (and (real/rationalp x)
                                  (real/rationalp y))))
      (if (> x y) x y))")
 (MAXIMUM-LENGTH
  (ARRAYS ACL2-BUILT-INS)
  "Return the [47m:maximum-length[0m from the [header] of an array

    Example Form:
    (maximum-length 'delta1 a)

    General Form:
    (maximum-length name alist)

  where [47mname[0m is an arbitrary object and [47malist[0m is a 1- or 2-dimensional
  array.  This function returns the contents of the [47m:maximum-length[0m
  field of the [header] of [47malist[0m.  Whenever an [47m[aset1][0m or [47m[aset2][0m
  would cause the length of the alist to exceed its maximum length, a
  [47m[compress1][0m or [47m[compress2][0m is done automatically to remove
  irrelevant pairs from the array.  [47mMaximum-length[0m operates in
  virtually constant time if [47malist[0m is the semantic value of [47mname[0m.
  See [arrays].

  [31;1mFunction: [0m<maximum-length>

    (defun maximum-length (name l)
      (declare (xargs :guard (or (array1p name l) (array2p name l))))
      (cadr (assoc-keyword :maximum-length (cdr (header name l)))))")
 (MAYBE-CONVERT-TO-MV (POINTERS)
                      "See [system-utilities].")
 (MAYBE-FLUSH-AND-COMPRESS1
  (ARRAYS ACL2-BUILT-INS)
  "Compress a one-dimensional array only if necessary

  The call [47m(maybe-flush-and-compress1 name ar)[0m is equivalent to the
  first calling [47m(flush-compress name)[0m and then [47m(compress1 name ar)[0m,
  except that both operations are skipped (and [47mar[0m is returned) if [47mar[0m,
  which has name [47mname[0m, is already compressed.")
 (MBE
  (GUARD PROGRAMMING ACL2-BUILT-INS)
  "Attach code for execution

  The macro [47mmbe[0m (``must be equal'') can be used in function definitions
  in order to cause evaluation to use alternate code to that provided
  for the logic.  An example is given below.  However, the use of [47mmbe[0m
  can lead to non-terminating computations.  See [defexec], perhaps
  after reading the present documentation, for a way to prove
  termination.

  In the ACL2 logic, [47m(mbe :exec exec-code :logic logic-code)[0m equals
  [47mlogic-code[0m; the value of [47mexec-code[0m is ignored.  However, in raw
  Lisp it is the other way around: this form macroexpands simply to
  [47mexec-code[0m.  ACL2's [guard] verification mechanism ensures that the
  raw Lisp code is only evaluated when appropriate, since the guard
  proof obligations generated for (the macroexpansion of) this call
  of [47mmbe[0m include not only the guard proof obligations from [47mexec-code[0m,
  but also, under suitable contextual assumptions, the term [47m(equal
  exec-code logic-code)[0m.  See [verify-guards] (in particular, for
  discussion of the contextual assumptions from the [47m:guard[0m and
  [47m[if][0m-tests) and, for general discussion of guards, see [guard].

  Normally, during evaluation of an [47mmbe[0m call, only the [47m:logic[0m code is
  evaluated unless the call is in the body of a [guard]-verified
  function or under a call of a [47m:[0m[47m[program][0m mode function; in those
  cases only the [47m:exec[0m code is evaluated.  This implies that equality
  of [47m:exec[0m and [47m:logic[0m code is never checked at runtime. (Rather, such
  equality is proved when verifying guards.)  We qualified with
  ``normally'' above because there are two exceptions.  During a
  ``safe mode'', which is used in macroexpansion and evaluation of
  [47m[defconst][0m forms, the [47m:logic[0m and [47m:exec[0m code are both evaluated and
  their equality is checked.  Second, when guard-checking is set to
  [47m:all[0m or [47m:none[0m, then for any [47mmbe[0m call in the body of a [47m:logic[0m mode
  definition, only the [47m:logic[0m code will be evaluated.

  Note that the [47m:exec[0m and the [47m:logic[0m code in an [47mmbe[0m call must have the
  same output signature.  For example, one cannot return [47m([0m[47m[mv][0m[47m * *)[0m
  while the other returns just a single value.

  Also see [mbt], which stands for ``must be true.'' You may find it
  more natural to use [47m[mbt][0m for certain applications, as described in
  its [documentation].

  Here is an example of the use of [47mmbe[0m.  Suppose that you want to
  define factorial in the usual recursive manner, as follows.

    (defun fact (n)
      (if (zp n)
          1
        (* n (fact (1- n)))))

  But perhaps you want to be able to execute calls of [47mfact[0m on large
  arguments that cause stack overflows, perhaps during proofs.  (This
  isn't a particularly realistic example, but it should serve.)  So,
  instead you can define this tail-recursive version of factorial:

    (defun fact1 (n acc)
      (declare (xargs :guard (and (integerp n) (>= n 0) (integerp acc))))
      (if (zp n)
          acc
        (fact1 (1- n) (* n acc))))

  We are now ready to define [47mfact[0m using [47mmbe[0m.  Our intention is that
  logically, [47mfact[0m is as shown in the first definition above, but that
  [47mfact[0m should be executed by calling [47mfact1[0m.  Notice that we defer
  [guard] verification, since we are not ready to prove the
  correspondence between [47mfact1[0m and [47mfact[0m.

    (defun fact (n)
      (declare (xargs :guard (and (integerp n) (>= n 0))
                      :verify-guards nil))
      (mbe :exec  (fact1 n 1)
           :logic (if (zp n)
                      1
                    (* n (fact (1- n))))))

  Next, we prove the necessary correspondence lemmas.  Notice the
  inclusion of a community book to help with the arithmetic
  reasoning.

    (include-book \"arithmetic/top-with-meta\" :dir :system)

    (defthm fact1-fact
      (implies (integerp acc)
               (equal (fact1 n acc)
                      (* acc (fact n)))))

  We may now do guard verification for [47mfact[0m, which will allow the
  execution of the raw Lisp [47mfact[0m function, where the above [47mmbe[0m call
  expands simply to [47m(fact1 n 1)[0m.

    (verify-guards fact)

  Now that guards have been verified, a trace of function calls
  illustrates that the evaluation of calls of [47mfact[0m is passed to
  evaluation of calls of [47mfact1[0m.  The outermost call below is of the
  logical function stored for the definition of [47mfact[0m; all the others
  are of actual raw Common Lisp functions.

    ACL2 !>(trace$ fact fact1)
    NIL
    ACL2 !>(fact 3)
    1> (ACL2_*1*_ACL2::FACT 3)
      2> (FACT 3)
        3> (FACT1 3 1)
          4> (FACT1 2 3)
            5> (FACT1 1 6)
              6> (FACT1 0 6)
              <6 (FACT1 6)
            <5 (FACT1 6)
          <4 (FACT1 6)
        <3 (FACT1 6)
      <2 (FACT 6)
    <1 (ACL2_*1*_ACL2::FACT 6)
    6
    ACL2 !>

  You may occasionally get warnings when you compile functions defined
  using [47mmbe[0m.  (For commands that invoke the compiler, see
  [compilation].)  These can be inhibited by using an [47mignorable[0m
  [47m[declare][0m form.  Here is a simple but illustrative example.  Note
  that the declarations can optionally be separated into two
  [47m[declare][0m forms.

    (defun foo (x y)
      (declare (ignorable x)
               (xargs :guard (equal x y)))
      (mbe :logic x :exec y))

  Finally, we observe that when the body of a function contains a term
  of the form [47m(mbe :exec exec-code :logic logic-code)[0m, the user would
  be unlikely to notice any difference in the theorem prover if this
  term were replaced by [47mlogic-code[0m.  ACL2 takes various steps to
  ensure this.  For example, the proof obligations generated for
  admitting a function treat the above [47mmbe[0m term simply as [47mlogic-code[0m.
  Function expansion, [47m:use[0m [hints], [47m:[0m[47m[definition][0m rules, generation
  of [constraint]s for functional instantiation, and creation of
  rules of class [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[forward-chaining][0m also treat [47mmbe[0m
  calls as their [47m:logic[0m code.


Subtopics

  [Defexec]
      Attach a terminating executable function to a definition

  [Mbe1]
      Attach code for execution

  [Mbt]
      Introduce a test into the logic that, however, evaluates to [47mt[0m

  [Mbt*]
      Introduce a guard proof obligation

  [Must-be-equal]
      Attach code for execution")
 (MBE1
  (MBE ACL2-BUILT-INS)
  "Attach code for execution

  The form [47m(mbe1 exec logic)[0m is equivalent to the forms [47m(mbe :logic
  logic :exec exec)[0m and [47m(must-be-equal logic exec)[0m.  See [mbe].")
 (MBT
  (MBE ACL2-BUILT-INS)
  "Introduce a test into the logic that, however, evaluates to [47mt[0m

  The macro [47mmbt[0m (``must be true'') can be used in order to add code in
  order to admit function definitions in [47m:[0m[47m[logic][0m mode, without
  paying a cost in execution efficiency.  Examples below illustrate
  its intended use.

  Semantically, [47m(mbt x)[0m equals [47mx[0m.  However, in raw Lisp [47m(mbt x)[0m ignores
  [47mx[0m entirely, and macroexpands to [47mt[0m.  ACL2's [guard] verification
  mechanism ensures that the raw Lisp code is only evaluated when
  appropriate, since a guard proof obligation [47m(equal x t)[0m is
  generated.  See [verify-guards] and, for general discussion of
  guards, see [guard].

  Also see [mbe], which stands for ``must be equal.'' Although [47mmbt[0m is
  more natural in many cases, [47mmbe[0m has more general applicability.  In
  fact, [47m(mbt x)[0m is essentially defined to be [47m(mbe :logic x :exec t)[0m.
  Another related utility is [47m[mbt*][0m, which generates the same proof
  obligation as [47mmbt[0m but logically, is simply [47mt[0m.

  We can illustrate the use of [47mmbt[0m on the following generic example,
  where [47m<g>[0m, [47m<test>[0m, [47m<rec-x>[0m, and [47m<base>[0m are intended to be terms
  involving only the variable [47mx[0m.

    (defun foo (x)
      (declare (xargs :guard <g>))
      (if <test>
          (foo <rec-x>)
        <base>))

  In order to admit this function, ACL2 needs to discharge the proof
  obligation that [47m<rec-x>[0m is smaller than [47mx[0m, namely:

    (implies <test>
             (o< (acl2-count [47m<rec-x>[0m)
                  (acl2-count x)))

  But suppose we need to know that [47m<g>[0m is true in order to prove this.
  Since [47m<g>[0m is only the [guard], it is not part of the logical
  definition of [47mfoo[0m.  A solution is to add the guard to the
  definition of [47mfoo[0m, as follows.

    (defun foo (x)
      (declare (xargs :guard <g>))
      (if (mbt <g>)
          (if <test>
              (foo <rec-x>)
            <base>)
        nil))

  If we do this using [47m<g>[0m rather than [47m(mbt <g>)[0m, then evaluation of
  every recursive call of [47mfoo[0m will cause the evaluation of (the
  appropriate instance of) [47m<g>[0m.  But since [47m(mbt <g>)[0m expands to [47mt[0m in
  raw Lisp, then once we verify the guards of [47mfoo[0m, the evaluations of
  [47m<g>[0m will be avoided (except at the top level, when we check the
  guard before allowing evaluation to take place in Common Lisp).

  Other times, the guard isn't the issue, but rather, the problem is
  that a recursive call has an argument that itself is a recursive
  call.  For example, suppose that [47m<rec-x>[0m is of the form [47m(foo
  <expr>)[0m.  There is no way we can hope to discharge the termination
  proof obligation shown above.  A standard solution is to add some
  version of this test:

    (mbt (o< (acl2-count [47m<rec-x>[0m) (acl2-count x)))

  Here is a specific example based on one sent by Vernon Austel.

    (defun recurX2 (n)
      (declare (xargs :guard (and (integerp n) (<= 0 n))
                      :verify-guards nil))
      (cond ((zp n) 0)
            (t (let ((call (recurX2 (1- n))))
                 (if (mbt (< (acl2-count call) n))
                     (recurX2 call)
                   1 ;; this branch is never actually taken
                   )))))

    (defthm recurX2-0
     (equal (recurX2 n) 0))

    (verify-guards recurX2)

  If you [47m([0m[47m[trace$][0m[47m acl2-count)[0m, you will see that evaluation of
  [47m(recurX2 2)[0m causes several calls of [47m[ACL2-count][0m before the
  [47m[verify-guards][0m.  But this evaluation does not call [47macl2-count[0m
  after the [47mverify-guards[0m, because the ACL2 evaluation mechanism uses
  raw Lisp to do the evaluation, and the form [47m(mbt (< (acl2-count
  call) n))[0m macroexpands to [47mt[0m in Common Lisp.

  You may occasionally get warnings when you compile functions defined
  using [47mmbt[0m.  (For commands that invoke the compiler, see
  [compilation].)  These can be inhibited by using an [47mignorable[0m
  [47m[declare][0m form.  Here is a simple but illustrative example.  Note
  that the declarations can optionally be separated into two
  [47m[declare][0m forms.

    (defun foo (x y)
      (declare (ignorable x)
               (xargs :guard (equal x t)))
      (and (mbt x) y))")
 (MBT*
  (MBE ACL2-BUILT-INS)
  "Introduce a guard proof obligation

  The macro [47mmbt*[0m is a variant of [47mmbt[0m (``must be true'').  However,
  unlike [47mmbt[0m, the call [47m(mbt* test)[0m is equivalent simply to [47mt[0m for both
  logic and evaluation.  The only effective difference between [47m(mbt*
  test)[0m and [47mt[0m is that [47m(mbt* test)[0m generates a [guard] proof
  obligation (when used in a [47m[logic][0m-mode definition) of [47mtest[0m.

  If you think that [47mmbt*[0m might be of use, please see [assert*], which
  is defined using [47mmbt*[0m to create a [guard] proof obligation without
  any logical or execution burden.")
 (MEASURE
  (XARGS)
  "Declare a measure for a [47m[defun][0m

  See [xargs] for discussion of how to use the [47m:measure[0m keyword to
  specify a measure for a definition.  A related utility, [47mmeasure[0m,
  may be found in the [community-books], file
  [47mkestrel/utilities/system/world-queries.lisp[0m.


Subtopics

  [Measure-debug]
      Generate markers to indicate sources of [measure] proof obligations

  [Termination-theorem]
      Use a (functional instance of a) previously-proved measure theorem

  [Termination-theorem-example]
      How to use a previously-proved measure theorem

  [Tthm]
      The [measure] (termination) theorem for a given function symbol")
 (MEASURE-DEBUG
  (MEASURE DEBUGGING)
  "Generate markers to indicate sources of [measure] proof obligations

  When ACL2 is asked to accept a recursive (or mutually recursive)
  function definition, it generates a goal often called the ``measure
  conjecture.'' That goal can split into numerous goals, some of
  which may not be theorems if the definition being processed has
  bugs.  This [documentation] topic explains a capability provided by
  ACL2 to help find such bugs.  For a similar utility appropriate for
  [guard] verification, see [guard-debug].

  We begin with the following simple, admittedly artificial, example.

    (defun f (x)
      (if (consp x)
          (f (cons x x))
        x))

  ACL2 generates the following proof obligation..

    (IMPLIES (CONSP X)
             (O< (ACL2-COUNT (CONS X X))
                 (ACL2-COUNT X)))

  In this simple example, it is obvious that ACL2 cannot prove the goal
  because in fact, [47m(CONS X X)[0m does not have a smaller [47m[ACL2-count][0m
  than [47mX[0m, even assuming [47m(CONSP X)[0m.  But you can get ACL2 to show
  explicitly the source of this proof obligation by specifying
  [47m:measure-debug t[0m in an [47m[xargs][0m [47m[declare][0m form, as follows.

    ACL2 !>(defun f (x)
             (declare (xargs :measure-debug t))
             (if (consp x)
                 (f (cons x x))
               x))

    For the admission of F 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

    Goal
    (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:RELATION F))
                              '(F (CONS X X)))
                  (CONSP X))
             (O< (ACL2-COUNT (CONS X X))
                 (ACL2-COUNT X))).

  The [47mextra-info[0m call is telling us the following about the [31;1mmeasure[0m
  conjecture:

    The appropriate well-founded [31;1mrelation[0m (typically [47m[o<][0m) holds between
    appropriate terms, because of the indicated recursive call, [47m(F
    (CONS X X))[0m.

  We now describe the measure-debug utility in some detail.

  [47m(Extra-info x y)[0m always returns [47mt[0m by definition.  However, if the
  measure conjecture takes place with a non-[47mnil[0m value for the [47m[xargs][0m
  keyword [47m:measure-debug[0m, then the goals generated will include
  hypotheses that are calls of [47mextra-info[0m.  Such a hypothesis has one
  of the following forms.

    (extra-info '(:MEASURE (:RELATION function-name))
                'recursive-call)

    (extra-info '(:MEASURE (:DOMAIN function-name))
                '(D (M term)))

  The first form says that the goal is to show that the measure
  decreases for the indicated recursive call in the body of the
  function named [47mfunction-name[0m.  The second form says that the goal
  is to show that the measure always returns a suitable value.

  We illustrate with a slightly more elaborate, but still contrived,
  example, which we hope clearly illustrates the points above.
  Notice that [47m:measure-debug t[0m need only be specified for a single
  [47m[defun][0m form in a call of [47m[mutual-recursion][0m.  Also notice in the
  output that when there is more than one source for a goal, each
  source is indicated by its own call of [47mextra-info[0m.

    ACL2 !>(defstub my-measure (x) t) ; for the contrived example below
    [[ .. output omitted here .. ]]
    ACL2 !>(mutual-recursion
             (defun f1 (x)
               (declare (xargs :measure (my-measure x) :measure-debug t))
               (if (consp x)
                   (f2 (cons x (cdr x)))
                 t))
             (defun f2 (x)
               (declare (xargs :measure (my-measure x)))
               (if (consp x)
                   (f1 (cons (make-list (car x)) (cdr x)))
                 nil)))

    For the admission of F1 and F2 we will use the relation O< (which is
    known to be well-founded on the domain recognized by O-P) and the measure
    (MY-MEASURE X) for F1 and (MY-MEASURE X) for F2.  The non-trivial part
    of the measure conjecture is

    Goal
    (AND (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:RELATION F1))
                                   '(F2 (CONS X (CDR X))))
                       (CONSP X))
                  (O< (MY-MEASURE (CONS X (CDR X)))
                      (MY-MEASURE X)))
         (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:RELATION F2))
                                   '(F1 (CONS (MAKE-LIST-AC (CAR X) NIL NIL)
                                              (CDR X))))
                       (CONSP X))
                  (O< (MY-MEASURE (CONS (MAKE-LIST-AC (CAR X) NIL NIL)
                                        (CDR X)))
                      (MY-MEASURE X)))
         (IMPLIES (AND (EXTRA-INFO '(:MEASURE (:DOMAIN F2))
                                   '(O-P (MY-MEASURE X)))
                       (EXTRA-INFO '(:MEASURE (:DOMAIN F1))
                                   '(O-P (MY-MEASURE X))))
                  (O-P (MY-MEASURE X)))).

  All rules (see [rune]) associated with [47mextra-info[0m are [disable]d by
  default, so that hypotheses of the form described above are not
  simplified to [47mt[0m.  These hypotheses are intended to ride along for
  free: you can generally expect the proof to have the same structure
  whether or not the [47m:measure-debug[0m option is supplied, though on
  rare occasions the proofs may diverge.")
 (MEASURE-THEOREM (POINTERS)
                  "See [termination-theorem].")
 (MEMBER
  (LISTS ACL2-BUILT-INS)
  "Membership predicate

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

  [47m(Member x lst)[0m equals the longest tail of the list [47mlst[0m that begins
  with [47mx[0m, or else [47mnil[0m if no such tail exists.  The optional keyword,
  [47m:TEST[0m, has no effect logically, but provides the test (default
  [47m[eql][0m) used for comparing [47mx[0m with successive elements of [47mlst[0m.

  The [guard] for a call of [47mmember[0m depends on the test.  In all cases,
  the second argument must satisfy [47m[true-listp][0m.  If the test is
  [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m
  (see [eqlablep]) or the second argument must satisfy
  [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then either the first
  argument must be a symbol or the second argument must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mmember[0m and its variants:

      [47m(member-eq x lst)[0m is equivalent to [47m(member x lst :test 'eq)[0m;

      [47m(member-equal x lst)[0m is equivalent to [47m(member x lst :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mmember-equal[0m.

  [47mMember[0m is defined by Common Lisp.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<member-equal>

    (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)))))")
 (MEMBER-EQ (POINTERS) "See [member].")
 (MEMBER-EQUAL (POINTERS)
               "See [member].")
 (MEMOIZATION (POINTERS)
              "See [memoize].")
 (MEMOIZE
  (PROGRAMMING HONS-AND-MEMOIZATION EVENTS)
  "Turn on memoization for a specified function

  See [hons-and-memoization] for a general discussion of the
  ``[hons-enabled]'' features: memoization, hash consing, and
  applicative hash tables.

    Examples:
    (memoize 'foo)                      ; remember the values of calls
                                        ;   of foo
    (memoize 'foo :condition t)         ; same as above
    (memoize 'foo :condition '(test x)) ; memoize for args satisfying
                                        ;   the given condition
    (memoize 'foo :condition-fn 'test)  ; memoize for args satisfying
                                        ;   a call of the given function
    (memoize 'foo :recursive nil)       ; don't memoize recursive calls
    (memoize 'foo :aokp t)              ; attachments OK for stored results
    (memoize 'foo :stats nil)           ; don't collect info for (memsum)
    (memoize 'foo :ideal-okp t)         ; memoize for raw Lisp even if foo is
                                        ;   in :logic but not guard-verified

    General Form:
    (memoize fn                         ; memoizes fn and returns fn
             :aokp         t/nil        ; optional (default nil)
             :commutative  t/lemma-name ; optional (default nil)
             :condition    condition    ; optional (default t (unless :invoke))
             :condition-fn condition-fn ; optional
             :forget       t/nil        ; optional (default nil)
             :hints        hints        ; optional, for verifying the
                                        ;   guards of condition-fn
             :ideal-okp    t/:warn/nil  ; optional (default nil)
             :invoke       nil/fn       ; optional (default nil)
             :memo-table-init-size size ; optional (default *mht-default-size*)
             :otf-flg      otf-flg      ; optional, for verifying the
                                        ;   guards of condition-fn
             :recursive    t/nil        ; optional (default t)
             :stats        t/nil        ; optional (default t (unless :invoke))
             :total        ;            ; see :DOC memoize-partial
             :verbose      t/nil        ; optional (default nil)
             )

  where [47mfn[0m evaluates to a user-defined function symbol; [47mcondition[0m is
  either [47mt[0m (the default), [47m't[0m, [47mnil[0m, or [47m'nil[0m, or else evaluates to an
  expression whose free variables are among the formal parameters of
  [47mfn[0m; and [47mcondition-fn[0m is either [47mnil[0m (the default) or else evaluates
  to a legal function symbol.  Further restrictions and options are
  discussed below.  Note that all arguments are evaluated (but for
  the special handling of value [47mt[0m for [47m:commutative[0m, the argument must
  literally be [47mt[0m; see below).

  Generally [47mfn[0m must evaluate to a defined function symbol.  However,
  this value can be the name of a macro that is associated with such
  a function symbol; see [macro-aliases-table].  That associated
  function symbol is the one called ``memoized'' in the discussion
  below, but we make no more mention of this subtlety.

  In the most common case, [47mmemoize[0m takes a single argument, which
  evaluates to a function symbol.  We call this function symbol the
  ``memoized function'' because ``memos'' are saved and re-used, in
  the following sense.  When a call of the memoized function is
  evaluated, the result is ``memoized'' by associating the call's
  arguments with that result, in a suitable table.  But first an
  attempt is made to avoid such evaluation, by doing a lookup in that
  table on the given arguments for the result, as stored for a
  previous call on those arguments.  If such a result is found, then
  it is returned without further computation.  This paragraph also
  applies if [47m:condition[0m is supplied but is [47mt[0m or [47m't[0m.

  If keyword argument [47m:condition-fn[0m is supplied, but [47m:condition[0m is not,
  then the result of evaluating [47m:condition-fn[0m must be a defined
  function symbol whose formal parameter list and [47m[guard][0m are the
  same as for the function being memoized.  If [47mfn[0m is in [47m:[0m[47m[logic][0m
  mode, then [guard]s must have been verified for [47m:condition-fn[0m.
  Such a ``condition function'' will be run whenever the memoized
  function is called, on the same parameters, and the lookup or table
  store described above are only performed if the result from the
  condition function call is non-[47mnil[0m.

  Suppose however that [47m:condition[0m is supplied.  If the value supplied
  is [47mt[0m or [47m't[0m, then the lookup and table store described above are
  always done.  If the value is [47mnil[0m or [47m'nil[0m, then this lookup and
  table store are never done, although statistics may be gathered;
  see [profile].  Now consider other values for [47m:condition[0m.  An
  attempt will be made to define a condition function whose [guard]
  and formal parameters list are the same as those of the memoized
  function, and whose body is the result, [47mr[0m, of evaluating the given
  [47mcondition[0m.  The name of that condition function is the result of
  evaluating [47m:condition-fn[0m if supplied, else is the result of
  concatenating the string [47m\"-MEMOIZE-CONDITION\"[0m to the end of the
  name of the memoized function.  The condition function will be
  defined with [guard] verification turned off, but that definition
  will be followed immediately by a [47m[verify-guards][0m event; and this
  is where the optional [47m:hints[0m and [47m:otf-flg[0m are attached.  At
  evaluation time the condition function is used as described in the
  preceding paragraph; so in effect, the condition ([47mr[0m, above) is
  evaluated, with its variables bound to the corresponding actuals of
  the memoized function call, and the memoized function attempts a
  lookup or table store if and only if the result of that evaluation
  is non-[47mnil[0m.

  Note that [47mfn[0m can be either a [47m:[0m[47m[logic][0m mode function or a [47m:[0m[47m[program][0m
  mode function.  However, only the corresponding raw Lisp function
  is actually memoized, so [guard] violations can defeat memoization,
  and [47m:[0m[47m[logic][0m mode functions without their [guard]s verified will
  only be memoized when called by [47m:[0m[47m[program][0m mode functions.  (See
  [guards-and-evaluation] for more information about guards and
  evaluation in ACL2.)  If [47mfn[0m is a [47m:[0m[47m[logic][0m mode function and
  [47m:condition[0m is supplied and not [47mt[0m or [47mnil[0m, then the condition must be
  a [guard]-verified function.

  Calls of this macro generate events of the form [47m(table memoize-table
  fn ((:condition-fn fn) ...))[0m.  When successful, the returned value
  is of the form [47m(mv nil function-symbol state)[0m.

  Suppose that a function is already memoized.  Then it is illegal to
  memoize that function.  Moreover, if the function was memoized with
  an associated condition (i.e., was memoized with keyword [47m:condition[0m
  or [47m:condition-fn[0m having value other than [47mt[0m or [47mnil[0m), then it is also
  illegal to convert the function from [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m mode
  (see [verify-termination]).  To turn off memoization, see
  [unmemoize].

  [47mMemoize[0m is illegal for a function if its arguments include [47m[state][0m;
  if it returns any [stobj]s; if it has been excluded by
  [47m[never-memoize][0m; or if it is excluded because it is ``special'' in
  the sense that it is in the [47m\"COMMON-LISP\"[0m [package], it has no
  fixed output signature (i.e., it is in the value of the list
  constant [47m(if return-last do$ read-user-stobj-alist)[0m, [47m(if
  return-last do$ read-user-stobj-alist)[0m), it has associated raw-Lisp
  code, or it is used in the implementation of
  [hons-and-memoization].  A constrained function (typically, one
  that is introduced in the signature of an [47m[encapsulate][0m event)
  cannot be memoized; in that case, one may wish to memoize its
  caller or attachment (see [defattach]).  A stobj can be an input of
  a memoized function, but in that case, the memoization table for
  that stobj will be cleared every time that stobj is updated.

  By default, [47mmemoize[0m does not store results when any attachments have
  been used (see [defattach]).  However, such results are stored when
  [47mmemoize[0m keyword parameter [47m:aokp[0m has value [47mt[0m.  Note that for
  purposes of this discussion, the use of a stored value for a
  subsidiary function that was memoized with [47m:aokp t[0m is treated as
  the use of an attachment, since ACL2 does not know whether or not
  an attachment was actually used in that case.

  We conclude by documenting keyword parameters not discussed above.

  Keyword parameter [47m:invoke[0m is [47mnil[0m by default, but its value can be a
  symbol, [47mg[0m.  Examples may be found in [community-books] file
  [47mdemos/memoize-invoke-input.lsp[0m; for a tool built on this capability
  that supports evaluation using proved input-output pairs for a
  function, see [add-io-pairs].  The effect of [47m:invoke g[0m is to
  replace every call of [47mfn[0m by a call of [47mg[0m.  However, there are some
  restrictions.  The function symbol [47mfn[0m must be in [47m:logic[0m mode, and
  the symbol [47mg[0m must be a [guard]-verified [47m:[0m[47m[logic][0m-mode function
  symbol with the same [signature] as that of [47mfn[0m.  There is the
  following proof obligation: there must be a theorem in the current
  ACL2 [world] stating the equality of calls of [47mfn[0m and [47mg[0m on a
  duplicate-free argument list; for example, if the formals list of
  [47mfn[0m is [47m(x1 ... xn)[0m, then the theorem could be [47m(equal (fn x1 .... xn)
  (g x1 ... xn))[0m.  If ACL2 finds no such theorem, it will print a
  [47m[defthm][0m event that you may wish to submit.  Next we describe a
  potential second proof obligation, which will similarly be printed
  if it is not met.  Let [47mguard-fn[0m be the [guard] for [47mfn[0m, and let
  [47mguard-g[0m be the result of substituting the formals of [47mfn[0m for the
  formals of [47mg[0m in the guard for [47mg[0m.  If [47mguard-fn[0m tautologically
  implies [47mguard-g[0m (for example, the two are equal or [47mguard-g[0m is [47m'T[0m),
  then there is no further proof obligation.  Otherwise, there must
  be a theorem in the current ACL2 [world] of the form [47m(implies
  guard-fn guard-g)[0m.  See [verify-guard-implication] for a utility
  that makes it easy for you to prove such a theorem.  Finally,
  contrary to the usual defaults, the values of keyword [47m:recursive[0m,
  [47m:condition[0m and [47m:stats[0m default to [47mnil[0m.  Indeed, it is an error to
  specify a non-nil value for [47m:recursive[0m.  The alternate defaults of
  [47mnil[0m for [47m:condition[0m and [47m:stats[0m can avoid memoization overhead when
  one simply wishes to call [47mg[0m in place of [47mfn[0m; you may override those
  defaults if you actually want to save computed values and use
  [47m(memsum)[0m to see statistics.

  Keyword parameter [47m:recursive[0m is [47mt[0m by default, which means that
  recursive calls of [47mfn[0m will be memoized just as ``top-level'' calls
  of [47mfn[0m.  When [47m:recursive[0m is instead set to [47mnil[0m, memoization is only
  done at the top level.  Using [47m:recursive nil[0m is similar to writing
  a wrapper function that just calls [47mfn[0m, and memoizing the wrapper
  instead of [47mfn[0m.

  A non-[47mnil[0m value for [47m:commutative[0m can be supplied if [47mfn[0m is a binary
  function in [47m:logic[0m mode.  Suppose that the [47mmemoize[0m event is
  successful, and consider a subsequent call of [47mfn[0m for which some
  argument to [47mfn[0m is either a rational number or, in some host Lisps
  (currently either CCL, or GCL Version 2.6.12 or later) a [hons].
  (Indeed, for such GCL versions this is true for any cons, not just
  a hons.)  Then when the evaluation of [47mfn[0m on those arguments is
  memoized, the evaluation of [47mfn[0m on the swap of those arguments is,
  in essence, also memoized.  If [47m:commutative[0m is supplied and is not
  [47mnil[0m or [47mt[0m, then it should be the name of a previously-proved theorem
  whose formula states the commutativity of [47mfn[0m, i.e., is the formula
  [47m(equal (fn x y) (fn y x))[0m for a pair [47m{x,y}[0m of distinct variables.
  If [47m:commutative[0m is [47mt[0m --- but not merely an expression that
  evaluates to [47mt[0m --- then an attempt to prove such a lemma will be
  made on-the-fly.  The name of the lemma is the symbol in the same
  package as [47mfn[0m, obtained by adding the suffix [47m\"-COMMUTATIVE\"[0m to the
  [47m[symbol-name][0m of [47mfn[0m.  If the proof attempt fails, then you may want
  first to prove the lemma yourself with appropriate hints and
  perhaps supporting lemmas, and then supply the name of that lemma
  as the value of [47m:commutative[0m.  Note that because most output is
  inhibited by default, you might wish to supply keyword argument
  [47m:verbose t[0m if the event fails.

  If [47m:commutative[0m is supplied, and a non-commutative condition is
  provided by [47m:condition[0m or [47m:condition-fn[0m, then although the results
  will be correct, the extra memoization afforded by [47m:commutative[0m is
  unspecified.

  If [47m:memo-table-init-size[0m is supplied, then it should be a positive
  integer specifying the initial size of an associated hash table.

  Argument [47m:aokp[0m is relevant only when attachments are used; see
  [defattach] for background on attachments.  When [47m:aokp[0m is [47mnil[0m, the
  default, computed values are not stored when an attachment was
  used, or even when an attachment may have been used because a
  function was called that had been memoized using [47m:aokp t[0m.
  Otherwise, computed values are always stored, but saved values are
  not used except when attachments are allowed.  To summarize:

    aokp=nil (default): ``Pure'', i.e., values do not depend on attachments
    - Fetch: always legal
    - Store: only store resulting value when attachments were not used

    aokp=t: ``Impure'', i.e., values may depend on attachments
    - Fetch: only legal when attachments are allowed (e.g., not during proofs)
    - Store: always legal

  Note that for this handling of [47m:aokp[0m, the computation of a value
  returned by function [47m[apply$-userfn][0m or [47m[badge-userfn][0m is
  considered to have used an attachment.

  The default value for [47m:stats[0m is essentially [47mt[0m.  (Technically, this
  can be subverted by using raw Lisp, to change the default by
  changing the values of variables [47m*record-xxx*[0m introduced in ACL2
  source file [47mmemoize-raw.lisp[0m.)  When [47m:stats[0m has its default value
  (assuming the above raw Lisp changes are not made) or value [47mt[0m,
  calls of memoized functions will collect information that can be
  displayed by calling [47m[memsum][0m.  But if [47m:stats[0m is [47mnil[0m, this
  information will not be collected, possibly resulting in better
  performance for the memoized function.  As of this writing,
  built-in memoized functions use [47m:stats nil[0m to benefit performance.

  If [47m:ideal-okp[0m is supplied and not [47mnil[0m, then it is permitted to
  memoize an ``ideal-mode'' function: one in [47m:[0m[47m[logic][0m mode whose
  [guard]s have not been verified.  However, this might not have the
  effect you desire, because you will be memoizing the submitted
  version of the function, not its executable-counterpart that is
  executed in the ACL2 loop and on behalf of the prover (see
  [evaluation]).  Thus, if you memoize an ideal-mode function and
  then call it at the top-level of the ACL2 loop (or, for example, it
  is called to evaluate a ground term arising in a proof or in the
  evaluation of a [meta]function in a proof), the effects of
  memoization will not be felt because the raw Lisp code is not run
  unless guards are verified.

  There are circumstances in which the raw Lisp code of an ideal-mode
  function is called.  For example, if the ideal-mode function is
  called by a [47m:[0m[47m[program][0m mode function, evaluation can transfer to
  raw Lisp where the effects of memoization will be felt.

  A trick, described below, with [47m[ec-call][0m can provide some of the
  benefit of memoizing an ideal-mode function.  The trick exploits
  the fact that [47mec-call[0m allows you to call an ideal-mode function
  within a [guard]-verified (``Common Lisp compliant'') [47m:[0m[47m[logic][0m mode
  function without having to verify guards for the ideal-mode
  function.  The following edited log illustrates the points above.

    ACL2 !>(defun fib (n)
             (declare (xargs :guard (natp n) :verify-guards nil))
             (if (zp n)
                 0
               (if (eql n 1)
                   1
                 (+ (fib (- n 1)) (fib (- n 2))))))
    [[ .. output omitted .. ]]
     FIB
    ACL2 !>(memoize 'fib :ideal-okp t)
     FIB
    ACL2 !>(time$ (fib 38)) ; slow: uses only executable-counterpart

    ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking will be inhibited
    on recursive calls of the executable-counterpart (i.e., in the ACL2
    logic) of FIB.  To check guards on all recursive calls:
      (set-guard-checking :all)
    To leave behavior unchanged except for inhibiting this message:
      (set-guard-checking :nowarn)

    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 3.91 seconds realtime, 3.90 seconds runtime
    ; (416 bytes allocated).
    39088169
    ACL2 !>(time$ (fib 38)) ; still slow; no results were stored before

    ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking will be inhibited
    on recursive calls of the executable-counterpart (i.e., in the ACL2
    logic) of FIB.  To check guards on all recursive calls:
      (set-guard-checking :all)
    To leave behavior unchanged except for inhibiting this message:
      (set-guard-checking :nowarn)

    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 3.92 seconds realtime, 3.91 seconds runtime
    ; (416 bytes allocated).
    39088169
    ACL2 !>(defun fib-logic-wrapper (n) ; guard-verified
             (declare (xargs :guard (natp n)))
             (ec-call (fib n)))
    [[ .. output omitted .. ]]
     FIB-LOGIC-WRAPPER
    ACL2 !>(memoize 'fib-logic-wrapper)
     FIB-LOGIC-WRAPPER
    ACL2 !>(time$ (fib-logic-wrapper 38)) ; slow; no fib results are stored

    ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking will be inhibited
    on recursive calls of the executable-counterpart (i.e., in the ACL2
    logic) of FIB.  To check guards on all recursive calls:
      (set-guard-checking :all)
    To leave behavior unchanged except for inhibiting this message:
      (set-guard-checking :nowarn)

    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 3.92 seconds realtime, 3.91 seconds runtime
    ; (2,128 bytes allocated).
    39088169
    ACL2 !>(time$ (fib-logic-wrapper 38)) ; fast; fib-logic-wrapper result was stored
    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 0.00 seconds realtime, 0.00 seconds runtime
    ; (16 bytes allocated).
    39088169
    ACL2 !>(time$ (fib-logic-wrapper 37)) ; slow; result only for 38 was stored

    ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking will be inhibited
    on recursive calls of the executable-counterpart (i.e., in the ACL2
    logic) of FIB.  To check guards on all recursive calls:
      (set-guard-checking :all)
    To leave behavior unchanged except for inhibiting this message:
      (set-guard-checking :nowarn)

    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 2.42 seconds realtime, 2.42 seconds runtime
    ; (416 bytes allocated).
    24157817
    ACL2 !>(defun fib-program-wrapper (n) ; program mode function
             (declare (xargs :guard (natp n) :mode :program))
             (fib n))

    Summary
    Form:  ( DEFUN FIB-PROGRAM-WRAPPER ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     FIB-PROGRAM-WRAPPER
    ACL2 !>(time$ (fib-program-wrapper 100)) ; fast because raw-Lisp fib is called
    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 0.00 seconds realtime, 0.00 seconds runtime
    ; (7,600 bytes allocated).
    354224848179261915075
    ACL2 !>

  Two non-[47mnil[0m values are allowed for keyword parameter [47m:ideal-okp[0m:
  [47m:warn[0m and [47mt[0m.  Both of these values allow memoization of ideal-mode
  functions, but if [47m:warn[0m is supplied then a warning will take place
  at memoization time, specifically for the resulting [table] event.
  Note that you may set the key [47m:memoize-ideal-okp[0m of the
  [47m[ACL2-defaults-table][0m to value [47mt[0m or [47m:warn[0m to change the default,
  but if parameter [47m:ideal-okp[0m is supplied, the [47m[ACL2-defaults-table][0m
  value is ignored.

  The value of [47m:verbose[0m is [47mnil[0m by default, which avoids output that is
  typically distracting.  Otherwise [47mverbose[0m should be [47mt[0m.  We can see
  the types of output that are inhibited by default by using
  [47m:[0m[47m[trans1][0m as follows follows (most output elided here); see
  [with-output].

    ACL2 !>:trans1 (memoize 'nth :verbose nil)
     (WITH-OUTPUT
         :OFF (SUMMARY PROVE EVENT)
         :GAG-MODE NIL
         ...
    ACL2 !>

  The default for [47m:forget[0m is [47mnil[0m.  If [47m:forget[0m is supplied, and not [47mnil[0m,
  then it must be [47mt[0m, which causes all memoization done for a
  top-level call of [47mfn[0m to be forgotten when that top-level call
  exits.


Subtopics

  [Clear-memoize-statistics]
      Clears all profiling info displayed by [47m([0m[47m[memoize-summary][0m[47m)[0m

  [Clear-memoize-table]
      Forget values remembered for the given function

  [Clear-memoize-tables]
      Forget values remembered for all the memoized functions

  [Memoize-partial]
      [47m[Memoize][0m a partial version of a limited (`clocked') function

  [Memoize-summary]
      Display all collected profiling and memoization info

  [Memsum]
      Display all collected profiling and memoization info

  [Never-memoize]
      Mark a function as unsafe to memoize.

  [Protect-memoize-statistics]
      Ensure the integrity of memoization statistics even upon aborts

  [Restore-memoization-settings]
      Restore the saved memoization settings

  [Save-and-clear-memoization-settings]
      Save and remove the current memoization settings

  [Set-bad-lisp-consp-memoize]
      Turn off or on memoization of raw Lisp function [47mbad-lisp-consp[0m

  [Unmemoize]
      Turn off memoization for the specified function

  [Verify-guard-implication]
      [Guard] implication for [47m[memoize][0m keyword [47m:invoke[0m")
 (MEMOIZE-PARTIAL
  (MEMOIZE)
  "[47m[Memoize][0m a partial version of a limited (`clocked') function

  See [memoize] for relevant background.  Here we describe a utility
  that supports effective memoization for functions that have been
  introduced by [47m[defun][0m, as follows, under certain restrictions.

    (defun fn-limit (x1 ... xn limit)
      (declare ...) ; optional, as usual for defun ; ;
      (if (zp limit)
          <base>
        (let ((limit (1- limit)))
          <body>)))

  Here [47mfn-limit[0m represents a function symbol and [47m(x1 ... xn limit)[0m
  denotes a non-empty list of formal parameters, where we call the
  final formal (here, shown as [47mlimit[0m) the ``limit variable''.  [47m<Base>[0m
  is any syntactically legal expression, but [47m<body>[0m is restricted as
  follows: the occurrences of the limit variable are exactly as the
  final parameter in each recursive call of [47mfn[0m.  More precisely, that
  restriction must hold after [47m<body>[0m is converted to a translated
  term (see [term]).  In other words, the translation of [47m<body>[0m must
  have the property that the limit variable only occurs in recursive
  calls, and in those calls it occurs exactly as the final argument
  and not in any other arguments.

  Such use of a ``limit'' argument to obtain termination is an old
  trick that pre-dates ACL2.  Such ``limited'' functions have
  traditionally often been called ``clocked'' functions.  In this
  documentation we refer to such a function as a ``total'' function,
  because the limit argument guarantees that its evaluation
  terminates.  We will be generating a corresponding ``partial''
  function that avoids the limit argument, and hence might not
  terminate --- but when it does, it computes the desired value, and
  uses memoization to do so, which can speed up computation.

  We organize the rest of this topic as follows: General Form, Basic
  Example, Example with Mutual Recursion, Detailed Documentation, and
  Optional Technical Remarks.


General Form:

    (memoize-partial fn+ ; see below
                     :kwd1 val1 ... :kwdn valn)

  where the supplied [47m:kwdi[0m and [47mvali[0m are valid keywords and values for
  [47m[memoize][0m.  In the simplest case, [47mfn+[0m is a symbol.  Later below,
  after providing an example, we give more complete documentation,
  including discussion of [47m[mutual-recursion][0m and the general case for
  [47mfn+[0m.  None of the arguments is evaluated.


Basic Example

  The following example from [community-book] file
  [47mbooks/demos/memoize-partial-input.lsp[0m illustrates the use of
  [47m[memoize-partial][0m.  Consider the {Collatz Conjecture |
  https://en.wikipedia.org/wiki/Collatz_conjecture}, sometimes known
  as the 3n+1 problem.  For any positive integer [47mn[0m, compute a new
  integer as [47mn/2[0m if [47mn[0m is even, else as [47m3*n+1[0m.  The Collatz conjecture
  states that this process eventually reaches [47m1[0m.  Since this is an
  open problem, we can't realistically hope to prove termination, so
  we may code the above algorithm by using a limit argument, as
  follows.  This function returns, unless the limit is reached, the
  number of steps required for the computation to terminate (reach
  1).

    (defun collatz-limit (n limit)
      (declare (xargs :guard (and (natp n)
                                  (natp limit))
                      :measure (acl2-count limit)))
      (if (zp limit)
          (prog2$ (er hard? 'collatz-limit
                      \"Limit exceeded!\")
                  0)
        (let ((limit (1- limit)))
          (if (int= n 1)
              0
            (1+ (collatz-limit (if (evenp n)
                                   (floor n 2)
                                 (1+ (* 3 n)))
                               limit))))))

  A moment's reflection suggests that if this algorithm terminates,
  then there are no cycles, so memoization from a single call will be
  useless.  However, memoization can be useful if we make distinct
  calls.  But memoization might not be very useful even then, because
  after we save the result of a call [47m(collatz-limit n0 limit0)[0m, a
  later call on [47mn0[0m might be with a different limit, say,
  [47m(collatz-limit n0 limit1)[0m.  So we prefer to memoize using the
  corresponding partial function, without a limit argument.  We can
  do that as follows.

    (memoize-partial collatz)

  Under the hood this generates, essentially, the following Common Lisp
  definition, which is to be memoized.

    (defun collatz (n)
      (if (int= n 1)
          0
        (1+ (collatz (if (evenp n)
                         (floor n 2)
                       (1+ (* 3 n)))))))

  Since the [47mlimit[0m argument has disappeared, memoization is now more
  effective.  But how can one define [47mcollatz[0m in the ACL2 logic?  The
  [47mmemoize-partial[0m call shown above actually generates the following
  events, which define [47mcollatz[0m to capture the notion of the
  ``eventual stable value, as [47mlimit[0m goes to infinity, of [47m(collatz n
  limit)[0m''.  It probably is not important to read these events unless
  one plans to reason about [47mcollatz[0m, and even then one might be able
  to complete proofs without reading these events.

    (DEFCHOOSE COLLATZ-LIMIT-CHANGE (LARGE)
      (N LIMIT)
      (AND (NATP LARGE)
           (<= LIMIT LARGE)
           (NOT (EQUAL (COLLATZ-LIMIT N LIMIT)
                       (COLLATZ-LIMIT N LARGE)))))
    (DEFCHOOSE COLLATZ-LIMIT-STABLE (LIMIT)
      (N)
      (AND (NATP LIMIT)
           (EQUAL (COLLATZ-LIMIT N LIMIT)
                  (COLLATZ-LIMIT N (COLLATZ-LIMIT-CHANGE N LIMIT)))))
    (DEFUN COLLATZ (N)
      (DECLARE (XARGS :GUARD (LET ((LIMIT 0))
                                  (DECLARE (IGNORABLE LIMIT))
                                  (AND (NATP N) (NATP LIMIT)))))
      (COLLATZ-LIMIT N (NFIX (COLLATZ-LIMIT-STABLE N))))

  The upshot is a logical definition of [47m(collatz n)[0m as the eventual
  value (if any), as [47mlimit[0m increases without bound, of [47m(collatz n
  limit)[0m --- together with an installed Common Lisp definition that
  is actually executed and, moreover, is memoized.

  We note that the call [47m(memoize-partial collatz)[0m also generates a
  [47m[table][0m event as well as the form [47m(MEMOIZE 'COLLATZ :TOTAL
  'COLLATZ-LIMIT)[0m.  However, these details are best ignored by the
  user; we do not expect those events to be generated by hand, and in
  particular it is probably inadvisable to use the [47m:TOTAL[0m keyword of
  [47m[memoize][0m other than indirectly using [47mmemoize-partial[0m.  Failure to
  heed this advice could make failures more difficult to debug.

  See [community-book] file [47mbooks/demos/memoize-partial-input.lsp[0m for
  an application of this use of [47mmemoize-partial[0m, to compute the total
  number of steps required (without accounting for memoization) to
  run the Collatz algorithm to completion on the first [47mn[0m positive
  integers.


Example with Mutual Recursion

  The following example, also from [community-book] file
  [47mbooks/demos/memoize-partial-input.lsp[0m, illustrates the use of
  [47mmemoize-partial[0m on functions that have been defined using
  [47m[mutual-recursion][0m.  (The suffix ``[47m-bdd[0m'' below is intended to
  denote ``bounded'', to suggest what the ``[47m-limit[0m'' suffix suggested
  in the first example.)

    (mutual-recursion
     (defun evenlp-bdd (x bound)
       (declare (xargs :guard (natp bound)))
       (if (zp bound)
           'ouch
         (let ((bound (1- bound)))
           (if (consp x) (oddlp-bdd (cdr x) bound) t))))
     (defun oddlp-bdd (x bound)
       (declare (xargs :guard (natp bound)))
       (if (zp bound)
           'ouch
         (let ((bound (1- bound)))
           (if (consp x) (evenlp-bdd (cdr x) bound) nil)))))

    (memoize-partial ((evenlp evenlp-bdd) (oddlp oddlp-bdd)))

  Notice that this time the argument of [47mmemoize-partial[0m is a list of
  tuples.  Each tuple is a list with two elements: the name of the
  partial function to be defined, followed by the corresponding total
  (limited) function that has already been defined.  Indeed, the
  preceding example abbreviates [47m(memoize-partial ((collatz
  collatz-limit)))[0m.  Such abbreviations are discussed in the Detailed
  Documentation section below.

  Recall that in the first example, the [47mmemoize-partial[0m call defined
  functions [47mcollatz-limit-change[0m and [47mcollatz-limit-stable[0m using
  [47m[defchoose][0m, and then function [47mcollatz[0m using [47m[defun][0m.  In the
  present example such a trio of functions is introduced for each of
  the functions defined in the corresponding [47mmutual-recursion[0m ---
  equivalently, for each of the tuples supplied to [47mmemoize-partial[0m.

    (DEFCHOOSE EVENLP-BDD-CHANGE (LARGE)
      (X BOUND)
      (AND (NATP LARGE)
           (<= BOUND LARGE)
           (NOT (EQUAL (EVENLP-BDD X BOUND)
                       (EVENLP-BDD X LARGE)))))
    (DEFCHOOSE EVENLP-BDD-STABLE (BOUND)
      (X)
      (AND (NATP BOUND)
           (EQUAL (EVENLP-BDD X BOUND)
                  (EVENLP-BDD X (EVENLP-BDD-CHANGE X BOUND)))))
    (DEFUN EVENLP (X)
      (DECLARE (XARGS :GUARD (LET ((BOUND 0))
                                  (DECLARE (IGNORABLE BOUND))
                                  (NATP BOUND))))
      (EVENLP-BDD X (NFIX (EVENLP-BDD-STABLE X))))
    (DEFCHOOSE ODDLP-BDD-CHANGE (LARGE)
      (X BOUND)
      (AND (NATP LARGE)
           (<= BOUND LARGE)
           (NOT (EQUAL (ODDLP-BDD X BOUND)
                       (ODDLP-BDD X LARGE)))))
    (DEFCHOOSE ODDLP-BDD-STABLE (BOUND)
      (X)
      (AND (NATP BOUND)
           (EQUAL (ODDLP-BDD X BOUND)
                  (ODDLP-BDD X (ODDLP-BDD-CHANGE X BOUND)))))
    (DEFUN ODDLP (X)
      (DECLARE (XARGS :GUARD (LET ((BOUND 0))
                                  (DECLARE (IGNORABLE BOUND))
                                  (NATP BOUND))))
      (ODDLP-BDD X (NFIX (ODDLP-BDD-STABLE X))))

  The corresponding Common Lisp functions, to be executed for
  [guard]-verified calls of [47mevenlp[0m and [47moddlp[0m, are defined as one
  might expect, in analogy to the Common Lisp definition in the first
  example.  Moreover, they are memoized.  Here are (again,
  essentially) the Common Lisp definitions of [47mevenlp[0m and [47moddlp[0m.

    (DEFUN EVENLP (X)
      (IF (CONSP X)
          (ODDLP (CDR X))
          T))
    (DEFUN ODDLP (X)
      (DECLARE (IGNORABLE X))
      (IF (CONSP X)
          (EVENLP (CDR X))
          NIL))


Detailed Documentation

  Recall the General Form

    (memoize-partial fn+ ; see below
                     :kwd1 val1 ... :kwdn valn)

  where the supplied [47m:kwdi[0m and [47mvali[0m represent keyword options to be
  used for a generated call of [47m[memoize][0m.  We discuss later below how
  [47mfn+[0m specifies either a recursively-defined function symbol or a
  sequence of function symbols defined by [47mmutual-recursion[0m --- all
  [guard]-verified.  We call the final formal parameter, which must
  be the same for each function symbol defined in the
  [47mmutual-recursion[0m case, the ``limit variable''.  The translated body
  (see [term] regarding the notion of ``translated'') of each of
  these function symbols must be of the following form, or of the
  corresponding form using [47m[cond][0m in place of [47m[if][0m, where here [47mlimit[0m
  denotes the limit variable.

    (if (zp limit)
        <base>
      (let ((limit (1- limit)))
        <body>))

  Moreover, each limit variable occurring in [47m<body>[0m must occur as the
  final argument of a call of the defined function --- in the mutual
  recursion case, of the functions defined by the [47mmutual-recursion[0m
  --- and conversely, each such call must have the limit variable as
  its final argument.

  Let us refer to each specified function as the ``total'' function.  A
  successful invocation admits a sequence of three definitions for
  each total function, which we call the ``changed'', ``stable'', and
  ``partial'' function.  Here are those three definitions, where
  ``[47m...[0m'' denotes the formals of the partial function (that is, the
  formals of the total function other than the final formal, which is
  the limit variable).  We write [47mLIMIT[0m below to denote the limit
  variable.  Note that [47mLARGE[0m is replaced by a fresh variable when
  necessary, to avoid duplicating an existing formal.

    (DEFCHOOSE <changed> (LARGE)
      (... LIMIT)
      (AND (NATP LARGE)
           (<= LIMIT LARGE)
           (NOT (EQUAL (<total> ... LIMIT)
                       (<total> ... LARGE)))))
    (DEFCHOOSE <stable> (LIMIT)
      (...)
      (AND (NATP LIMIT)
           (EQUAL (<total> ... LIMIT)
                  (<total> ... (<change> ... LIMIT)))))
    (DEFUN <partial> (...)
      (DECLARE (XARGS :GUARD (LET ((LIMIT 0))
                                  (DECLARE (IGNORABLE LIMIT))
                                  <guard_of_total>)))
      (<total> ... (NFIX (<stable> ...))))

  Under the hood, however, a Common Lisp definition is installed for
  [47m<partial>[0m that avoids the limit variable, essentially by
  eliminating it in [47m<body>[0m to produce a corresponding term, [47m<body'>[0m,
  with the following result.  (Low-level details about exactly what
  is generated are discussed in the Optional Technical Remarks below,
  but should probably be ignored by most users.)

    (defun <partial> (...)
      <body'>

  We turn now to the first argument of [47mmemoize-partial[0m, denoted [47mfn+[0m
  above, with discussion of its legal forms and its relation to the
  other (keyword) arguments of [47mmemoize-partial[0m.  The most flexible
  form for [47mfn+[0m is a list of tuples, where each tuple is of the
  following form and the keyword arguments are optional and in any
  order.

    (<partial> <total>
     :change <change>
     :stable <stable>
     :kwd1 val1 ... :kwdn valn)

  The symbols [47m<partial>[0m, [47m<total>[0m, [47m<change>[0m, and [47m<stable>[0m are as
  discussed above, and the arguments [47m:kwd1 val1 ... :kwdn valn[0m are as
  supplied to [47m[memoize][0m.  There should be a single tuple in the
  singly recursive case.  In the case that the partial functions were
  defined by a [47mmutual-recursion[0m defining functions [47mf1[0m, ..., [47mfn[0m, then
  the [47m<partial>[0m components of the tuples (their [47m[car][0ms) must also be
  [47mf1[0m, ..., [47mfn[0m.

  The keyword/value pairs of the tuple are optional.  The default for
  [47m<change>[0m is obtained by adding the suffix [47m\"-CHANGE\"[0m to [47m<total>[0m, to
  create a symbol in the same package as that of [47m<total>[0m; similarly
  for [47m<stable>[0m and the suffix [47m\"-STABLE\"[0m.  The [47m<total>[0m function is
  defined as described above, with an under-the-hood Common Lisp
  definition also as described above, and [memoize]d.  The [47mmemoize[0m
  call uses the keywords supplied in the tuple other than [47m:change[0m and
  [47m:stable[0m.  For any [47mmemoize[0m keywords not specified in the tuple, the
  keywords specified at the top level of the [47mmemoize-partial[0m call ---
  that is, the keyword arguments (if any) following the first
  argument (that is, following [47mfn+[0m) --- are also used in that
  generated [47mmemoize[0m call.

  There are some abbreviations allowed for [47mfn+[0m, as follows.

    * A symbol [47mfn[0m for [47mfn+[0m abbreviates the list [47m(fn)[0m, which is an
      abbreviation as noted below.

    * If [47mfn+[0m is a list [47m(t1 ... tk)[0m, then each [47mti[0m that is a symbol, say [47mfn[0m,
      abbreviates the tuple [47m(fn fn-limit)[0m, where [47mfn-limit[0m is obtained
      by adding the suffix [47m\"-LIMIT\"[0m to [47mfn[0m, to create a symbol in the
      same package as that of [47mfn[0m.

  Consider our first example, [47m(memoize-partial collatz)[0m.  In this case
  [47mfn+[0m is [47mcollatz[0m.  By the first rule above, this abbreviates
  [47m(collatz)[0m, which the second rule says is an abbreviation for
  [47m(collatz collatz-limit)[0m.  The default values are computed to treat
  this as the following tuple.

    (collatz collatz-limit
             :change collatz-limit-change
             :stable collatz-limit-stable)

  Note that the keyword value [47m:condition nil[0m for [47mmemoize[0m can be used to
  install executable definitions without actually saving values,
  essentially by merely profiling (except that unlike [47m[profile][0m the
  recursive calls are also affected by the [47mmemoize[0m call).  See the
  example involving ``worse-than'' functions in community book
  [47mbooks/demos/memoize-partial-input.lsp[0m.

  We conclude this section by discussing restrictions pertaining to
  [stobj]s.  Recall that memoization is illegal (other than
  profiling) for functions that return a stobj or have the ACL2
  [state] as an input.  Those same restrictions apply to
  [47mmemoize-partial[0m.  However, it is legal for the given (``total'')
  functions to have user-defined stobjs as inputs, as long as they
  are not returned.  In that case, the generated definition of the
  partial function will be made with a call of [47m[non-exec][0m wrapped
  around the body.


Optional Technical Remarks.

  Warning: These are technical remarks that are completely optional.

  Our general remark is to invite readers who want to dive below the
  user level, including implementation and foundational issues, to
  read the comment entitled ``Essay on Memoization with Partial
  Functions (Memoize-partial)'' in ACL2 source file
  [47mother-events.lisp[0m.

  Our more specific remark concerns generated Common Lisp definitions.
  Recall that in the Basic Example above, we say that the Common Lisp
  definition of [47mcollatz[0m is essentially as follows.

    (defun collatz (n)
      (if (int= n 1)
          0
        (1+ (collatz (if (evenp n)
                         (floor n 2)
                       (1+ (* 3 n)))))))

  We say ``essentially'' because the actual Common Lisp definition of
  [47mcollatz[0m is a bit different, as follows.

    (DEFUN COLLATZ (N)
      (DECLARE (IGNORABLE N))
      (FLET ((COLLATZ-LIMIT (N LIMIT)
                            (DECLARE (IGNORE LIMIT))
                            (COLLATZ N)))
            (DECLARE (INLINE COLLATZ-LIMIT))
            (LET ((LIMIT 0))
                 (DECLARE (IGNORABLE LIMIT))
                 (IF (INT= N 1)
                     0
                     (1+ (COLLATZ-LIMIT
                          (IF (EVENP N) (FLOOR N 2) (1+ (* 3 N)))
                          LIMIT))))))

  A little reflection will conclude that these two definitions are
  equivalent.  The latter, however, avoids a macroexpansion issue
  discussed in the aforementioned Essay.")
 (MEMOIZE-SUMMARY
  (MEMOIZE)
  "Display all collected profiling and memoization info

  Logically, this function just returns [47mnil[0m, but it displays profiling
  and memoization table information.  The profiling statistics may be
  cleared with [47m([0m[47m[clear-memoize-statistics][0m[47m)[0m.

  Note that by default, statistics might be inaccurate when calls of
  [memoize]d functions are aborted.  This issue can be avoided,
  however; see [protect-memoize-statistics].")
 (MEMSUM
  (MEMOIZE)
  "Display all collected profiling and memoization info

  This macro is an abbreviation for [47m[memoize-summary][0m.  Logically, it
  just returns [47mnil[0m.  Also see [protect-memoize-statistics].")
 (MERGE-SORT-LEXORDER
  (LISTS ACL2-BUILT-INS)
  "Sort a list

  The call [47m(merge-sort-lexorder x)[0m sorts the true-list [47mx[0m using a
  non-strict total order, [47m[lexorder][0m, on the ACL2 universe.")
 (META
  (RULE-CLASSES)
  "Make a [47m:meta[0m rule (a hand-written simplifier)

  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.

  Meta rules extend the ACL2 simplifier with hand-written code to
  transform certain terms to equivalent ones.  To add a meta rule,
  the [47m:[0m[47m[corollary][0m formula must establish that the hand-written
  ``metafunction'' preserves the meaning of the transformed term.

    Examples:
    (defthm fn-correct-1                ; Modify the rewriter to use fn to
      (equal (evl x a)                  ; transform terms that are calls of
             (evl (fn x) a))            ; nth or of foo.
      :rule-classes ((:meta :trigger-fns (nth foo))))

    (defthm fn-correct-2                ; As above, but this illustrates
      (implies (and (pseudo-termp x)    ; that without loss of generality we
                    (alistp a))         ; may restrict x to be shaped like a
               (equal (evl x a)         ; term and a to be an alist.
                      (evl (fn x) a)))
      :rule-classes ((:meta :trigger-fns (nth foo))))

    (defthm fn-correct-3                ; As above (with or without the
      (implies (and (pseudo-termp x)    ; hypotheses on x and a), with the
                    (alistp a)          ; additional restriction that the
                    (evl (hyp-fn x) a)) ; meaning of (hyp-fn x) is true in
               (equal (evl x a)         ; the current context.  That is, the
                      (evl (fn x) a)))  ; applicability of the transformation
      :rule-classes                     ; may be dependent upon some computed
      ((:meta :trigger-fns (nth foo)))) ; hypotheses.

  While our intention is that the set of ACL2 documentation topics is
  self-contained, readers might find it useful to see the following
  paper for an introduction to meta reasoning in ACL2.

      W. A. Hunt, Jr., R. B. Krug, M. Kaufmann, J S. Moore and E. W. Smith,
      ``Meta Reasoning in ACL2.'' TPHOLs 2005, ed. J. Hurd and T. F.
      Melham, LNCS 3603, Springer-Verlag, Berlin, 2005, pp. 163--178.

  A non-[47mnil[0m list of function symbols must be supplied as the value of
  the [47m:trigger-fns[0m field in a [47m:meta[0m rule class object (except that a
  macro alias can stand in for a function symbol; see
  [add-macro-alias]).

    General Forms:
    (implies (and (pseudo-termp x)        ; this hyp is optional
                  (alistp a)              ; this hyp is optional
                  (ev (hyp-fn x ...) a)   ; this hyp is optional
                  ; meta-extract hyps may also be included (see below)
                  )
             (equiv (ev x a)
                    (ev (fn x ...) a)))

  where [47mequiv[0m is a known [equivalence] relation, [47mx[0m and [47ma[0m are distinct
  variable names, and [47mev[0m is an evaluator function (see below), and [47mfn[0m
  is a function symbol, as is [47mhyp-fn[0m when provided.  The arguments to
  [47mfn[0m and [47mhyp-fn[0m should be identical.  In the most common case, both
  take a single argument, [47mx[0m, which denotes the term to be simplified.
  If [47mfn[0m and/or [47mhyp-fn[0m are [guard]ed, their [guard]s should be
  trivially implied by [47m[pseudo-termp][0m.  We say the theorem above is a
  ``metatheorem'' or ``metalemma'' and [47mfn[0m is a ``metafunction'', and
  [47mhyp-fn[0m is a ``hypothesis metafunction''.

  If ``[47m...[0m'' is empty, i.e., the metafunctions take just one argument,
  we say they are ``vanilla flavored.'' If ``[47m...[0m'' is non-empty, we
  say the metafunctions are ``extended.'' Extended metafunctions can
  access [47m[state][0m and context sensitive information to compute their
  results, within certain limits.  We discuss vanilla metafunctions
  here and recommend a thorough understanding of them before
  proceeding (at which time see [extended-metafunctions]).

  If a metafunction application to a term, [47mu[0m, evaluates to a result of
  the form [47m(if TEST NEW-TERM u)[0m, then [47mTEST[0m is treated as an
  ``implicit hypothesis''.  For discussion of this relatively
  advanced feature, see [meta-implicit-hypothesis].

  Additional hypotheses are supported, called ``meta-extract
  hypotheses''.  These allow metafunctions to depend on the validity
  of certain terms extracted from the context or the logical [world].
  These hypotheses provide a relatively advanced form of metatheorem
  so we explain them elsewhere; see [meta-extract].

  One might think that metafunctions and (if supplied) hypothesis
  metafunctions must be executable: that is, not constrained (i.e.,
  introduced in the [signature] of [47m[encapsulate][0m [events]), and not
  [declare]d [47m:[0m[47m[non-executable][0m.  After all, there is no point in
  installing a simplifier that cannot be run!  However, such a
  restriction is not enforced, because one could introduce a
  metafunction using [47m[encapsulate][0m and then use [47m[defattach][0m to attach
  it to an executable function; see [defattach].

  We defer discussion of the case in which there is a hypothesis
  metafunction and for now address the case in which the other two
  hypotheses are present.

  In the discussion below, we refer to the argument, [47mx[0m, of [47mfn[0m and
  [47mhyp-fn[0m as a ``(translated) term,'' i.e., an object satisfying the
  ACL2 built-in predicate [47mtermp[0m.  When these metafunctions are
  executed by the simplifier, they will be applied to (the quotations
  of) terms.  But during the proof of the metatheorem itself, [47mx[0m may
  not be the quotation of a term.  If the [47m[pseudo-termp][0m hypothesis
  is omitted, [47mx[0m may be any object.  Even with the [47m[pseudo-termp][0m
  hypothesis, [47mx[0m may merely ``look like a term'' but use non-function
  symbols or function symbols of incorrect arity.  In any case, the
  metatheorem is stronger than necessary to allow us to apply the
  metafunctions to terms, as we do in the discussion below.  We
  return later to the question of proving the metatheorem.

  Suppose the general form of the metatheorem above is proved with the
  [47m[pseudo-termp][0m and [47m[alistp][0m hypotheses.  Then when the simplifier
  encounters a term, [47m(h t1 ... tn)[0m, that begins with a function
  symbol, [47mh[0m, listed in [47m:trigger-fns[0m, it applies the metafunction, [47mfn[0m,
  to the quotation of the term, i.e., it evaluates [47m(fn '(h t1 ...
  tn))[0m to obtain some result, which can be written as [47m'val[0m.  If [47m'val[0m
  is different from [47m'(h t1 ... tn)[0m and [47mval[0m is a well-formed term (see
  the next paragraph), then [47m(h t1 ... tn)[0m is replaced by [47mval[0m, which
  is then passed along for further rewriting.  Because the
  metatheorem establishes the correctness of [47mfn[0m for all terms (even
  non-terms!), there is no restriction on which function symbols are
  listed in the [47m:trigger-fns[0m.  Generally, of course, they should be
  the symbols that head up the terms simplified by the metafunction
  [47mfn[0m.

  Note that the result of applying a metafunction (or a hypothesis
  metafunction) must be a term, i.e., must satisfy the predicate
  [47m[termp][0m in the current logical [world].  If not, then an error
  occurs.  See [term-table] for how one obtains some assistance
  towards testing that [47mval[0m is indeed a term.  ACL2 actually enforces
  a stronger requirement, disallowing calls of certain ``forbidden''
  function symbols as described in [47m[set-skip-meta-termp-checks][0m.
  Both of these runtime checks can be avoided by proving that the
  metafunction (and the corresponding hypothesis metafunction, if
  any) always produces an acceptable term.  See
  [well-formedness-guarantee].  Alternatively, with an active trust
  tag (see [defttag]) you can tell ACL2 to skip these tests; see
  [47m[set-skip-meta-termp-checks][0m.

  The ``evaluator'' function, [47mev[0m, is a function that can evaluate a
  certain class of expressions, namely, all of those composed of
  variables, constants, and applications of a fixed, finite set of
  function symbols, [47mg1[0m, ..., [47mgk[0m.  Generally speaking, the set of
  function symbols handled by [47mev[0m is chosen to be exactly the function
  symbols recognized and manipulated by the metafunctions being
  introduced.  For example, if [47mfn[0m manipulates expressions in which
  [47m'[0m[47m[equal][0m and [47m'[0m[47m[binary-append][0m occur as function symbols, then [47mev[0m is
  generally specified to handle [47m[equal][0m and [47m[binary-append][0m.  The
  actual requirements on [47mev[0m become clear when the metatheorem is
  proved.  The standard way to introduce an evaluator is to use the
  ACL2 macro [47m[defevaluator][0m, though this is not strictly necessary.
  See [defevaluator] if you want details.

  [Aside for the logic-minded.] Why are we justified in using
  metafunctions this way?  Suppose [47m(fn 'term1)[0m is [47m'term2[0m.  What
  justifies replacing [47mterm1[0m by [47mterm2[0m?  The first step is to assert
  that [47mterm1[0m is [47m(ev 'term1 a)[0m, where [47ma[0m is an alist that maps [47m'var[0m to
  [47mvar[0m, for each variable [47mvar[0m in [47mterm1[0m.  This step is incorrect,
  because [47m'term1[0m may contain function symbols other than the ones,
  [47mg1[0m, ..., [47mgk[0m, that [47mev[0m knows how to handle.  But we can grow [47mev[0m to a
  ``larger'' evaluator, [47mev*[0m, an evaluator for all of the symbols that
  occur in [47mterm1[0m or [47mterm2[0m.  We can prove that [47mev*[0m satisfies the
  [constraint]s on [47mev[0m, provided no [47m[defaxiom][0m events are adding
  constraints to [47mev[0m (or callers of [47mev[0m, and recursively); ACL2 checks
  this additional property.  Hence, the metatheorem holds for [47mev*[0m in
  place of [47mev[0m, by functional instantiation.  We can then carry out
  the proof of the [equivalence] of [47mterm1[0m and [47mterm2[0m as follows: Fix [47ma[0m
  to be an alist that maps the quotations of the variables of [47mterm1[0m
  and [47mterm2[0m to themselves.  Then,

    term1 = (ev* 'term1 a)      ; (1) by construction of ev* and a
          = (ev* (fn 'term1) a) ; (2) by the metatheorem for ev*
          = (ev* 'term2 a)      ; (3) by evaluation of fn
          = term2               ; (4) by construction of ev* and a

  Note that in line (2) above, where we appeal to the (functional
  instantiation of the) metatheorem, we can relieve its (optional)
  [47m[pseudo-termp][0m and [47m[alistp][0m hypotheses by appealing to the facts
  that [47mterm1[0m is a term and [47ma[0m is an alist by construction.  [End of
  Aside for the logic-minded.]

  There are subtleties related to the notion of ``growing'' [47mev[0m to a
  ``larger'' evaluator, as mentioned in the paragraph just above.
  For corresponding restrictions on [47m:meta[0m rules, see
  [evaluator-restrictions].

  Finally, we turn to the second case, in which there is a hypothesis
  metafunction.  In that case, consider as before what happens when
  the simplifier encounters a term, [47m(h t1 ... tn)[0m, where [47mh[0m is listed
  in [47m:trigger-fns[0m.  This time, after it applies [47mfn[0m to [47m'(h t1 ... tn)[0m
  to obtain the quotation of some new term, [47m'val[0m, it then applies the
  hypothesis metafunction, [47mhyp-fn[0m.  That is, it evaluates [47m(hyp-fn '(h
  t1 ... tn))[0m to obtain some result, which can be written as
  [47m'hyp-val[0m.  If [47mhyp-val[0m is not in fact a term, the metafunction is
  not used.  Provided [47mhyp-val[0m is a term, the simplifier attempts to
  establish (by conventional backchaining) that this term is non-[47mnil[0m
  in the current context.  Note that this backchaining is done just
  as it is done for hypotheses of [rewrite] (and [linear]) rules,
  namely, by rewriting with special attention to calls of certain
  functions including [47m[force][0m, [47m[case-split][0m, [47m[syntaxp][0m, and
  [47m[bind-free][0m.  If this attempt to establish this term fails, then
  the meta rule is not applied.  Otherwise, [47m(h t1...tn)[0m is replaced
  by [47mval[0m as in the previous case (where there was no hypothesis
  metafunction).

  Why is it justified to make this extension to the case of hypothesis
  metafunctions?  First, note that the rule

    (implies (and (pseudo-termp x)
                  (alistp a)
                  (ev (hyp-fn x) a))
             (equal (ev x a)
                    (ev (fn x) a)))

  is logically equivalent to the rule

    (implies (and (pseudo-termp x)
                  (alistp a))
             (equal (ev x a)
                    (ev (new-fn x) a)))

  where [47m(new-fn x)[0m is defined to be [47m(list 'if (hyp-fn x) (fn x) x)[0m.
  (If we're careful, we realize that this argument depends on making
  an extension of [47mev[0m to an evaluator [47mev*[0m that handles [47m[if][0m and the
  functions manipulated by [47mhyp-fn[0m.)  If we write [47m'term[0m for the
  quotation of the present term, and if [47m(hyp-fn 'term)[0m and [47m(fn 'term)[0m
  are both terms, say [47mhyp1[0m and [47mterm1[0m, then by the previous argument
  we know it is sound to rewrite term to [47m(if hyp1 term1 term)[0m.  But
  since we have established in the current context that [47mhyp1[0m is
  non-[47mnil[0m, we may simplify [47m(if hyp1 term1 term)[0m to [47mterm1[0m, as desired.

  We now discuss the role of the [47m[pseudo-termp][0m hypothesis.
  [47m(Pseudo-termp x)[0m checks that [47mx[0m has the shape of a term.  Roughly
  speaking, it ensures that [47mx[0m is a symbol, a quoted constant, or a
  true list consisting of a [47mlambda[0m expression or symbol followed by
  some pseudo-terms.  Among the properties of terms not checked by
  [47m[pseudo-termp][0m are that variable symbols never begin with
  ampersand, [47mlambda[0m expressions are closed, and function symbols are
  applied to the correct number of arguments.  See [pseudo-termp].

  There are two possible roles for [47m[pseudo-termp][0m in the development of
  a metatheorem: it may be used as the [guard] of the metafunction
  and/or hypothesis metafunction and it may be used as a hypothesis
  of the metatheorem.  Generally speaking, the [47m[pseudo-termp][0m
  hypothesis is included in a metatheorem only if it makes it easier
  to prove.  The choice is yours.  (An extreme example of this is
  when the metatheorem is invalid without the hypothesis!)  We
  therefore address ourselves the question: should a metafunction
  have a [47m[pseudo-termp][0m [guard]?  A [47m[pseudo-termp][0m [guard] for a
  metafunction, in connection with other considerations described
  below, improves the efficiency with which the metafunction is used
  by the simplifier.

  To make a metafunction maximally efficient you should (a) provide it
  with a [47m[pseudo-termp][0m [guard] and exploit the [guard] when possible
  in coding the body of the function (see [guards-and-evaluation],
  especially the section on efficiency issues), (b) verify the
  [guard]s of the metafunction (see [verify-guards]), and (c) compile
  the metafunction (see [comp]).  When these three steps have been
  taken the simplifier can evaluate [47m(fn 'term1)[0m by running the
  compiled ``primary code'' (see [guards-and-evaluation]) for [47mfn[0m
  directly in Common Lisp.  (Note however that explicit compilation
  may be suppressed; see [compilation].)

  Before discussing efficiency issues further, let us review for a
  moment the general case in which we wish to evaluate [47m(fn 'obj)[0m for
  some [47m:[0m[47m[logic][0m function.  We must first ask whether the [guard]s of
  [47mfn[0m have been verified.  If not, we must evaluate [47mfn[0m by executing
  its logic definition.  This effectively checks the [guard]s of
  every subroutine and so can be slow.  If, on the other hand, the
  [guard]s of [47mfn[0m have been verified, then we can run the primary code
  for [47mfn[0m, provided [47m'obj[0m satisfies the [guard] of [47mfn[0m.  So we must next
  evaluate the [guard] of [47mfn[0m on [47m'obj[0m.  If the [guard] is met, then we
  run the primary code for [47mfn[0m, otherwise we run the logic code.

  Now in the case of a metafunction for which the three steps above
  have been followed, we know the [guard] is (implied by)
  [47m[pseudo-termp][0m and that it has been verified.  Furthermore, we know
  without checking that the [guard] is met (because [47mterm1[0m is a term
  and hence [47m'term1[0m is a [47m[pseudo-termp][0m).  Hence, we can use the
  compiled primary code directly.

  We strongly recommend that you compile your metafunctions, as well as
  all their subroutines (unless explicit compilation is suppressed;
  see [compilation]).  Guard verification is also recommended.

  Finally, we present a very simple example of the use of [47m:meta[0m rules,
  based on one provided by Robert Krug.  This example illustrates a
  trick for avoiding undesired rewriting after applying a
  metafunction or any other form of rewriting.  To elaborate: in
  general, the term [47mt2[0m obtained by applying a metafunction to a term
  [47mt1[0m is then handed immediately to the rewriter, which descends
  recursively through the arguments of function calls to rewrite [47mt2[0m
  completely.  But if [47mt2[0m shares a lot of structure with [47mt1[0m, then it
  might not be worthwhile to rewrite [47mt2[0m immediately.  (A rewrite of
  [47mt2[0m will occur anyhow the next time a goal is generated.)  The trick
  involves avoiding this rewrite by wrapping [47mt2[0m inside a call of
  [47m[hide][0m, which in turn is inside a call of a user-defined
  ``unhiding'' function, [47munhide[0m.

    (defun unhide (x)
      (declare (xargs :guard t))
      x)

    (defthm unhide-hide
      (equal (unhide (hide x))
             x)
      :hints ((\"Goal\" :expand ((hide x)))))

    (in-theory (disable unhide))

    (defun my-plus (x y)
      (+ x y))

    (in-theory (disable my-plus))

    (defevaluator evl evl-list
      ((my-plus x y)
       (binary-+ x y)
       (unhide x)
       (hide x)))

    (defun meta-fn (term)
      (declare (xargs :guard (pseudo-termp term)))
      (if (and (consp term)
               (equal (length term) 3)
               (equal (car term) 'my-plus))
          `(UNHIDE (HIDE (BINARY-+ ,(cadr term) ,(caddr term))))
        term))

    (defthm my-meta-lemma
      (equal (evl term a)
             (evl (meta-fn term) a))
      :hints ((\"Goal\" :in-theory (enable my-plus)))
      :rule-classes ((:meta :trigger-fns (my-plus))))

  Notice that in the following (silly) conjecture, ACL2 initially does
  only does the simplification directed by the metafunction; a second
  goal is generated before the commutativity of addition can be
  applied.  If the above calls of [47mUNHIDE[0m and [47mHIDE[0m had been stripped
  off, then [47mGoal'[0m would have been the term printed in [47mGoal''[0m below.

    ACL2 !>(thm
            (equal (my-plus b a)
                   ccc))

    This simplifies, using the :meta rule MY-META-LEMMA and the :rewrite
    rule UNHIDE-HIDE, to

    Goal'
    (EQUAL (+ B A) CCC).

    This simplifies, using the :rewrite rule COMMUTATIVITY-OF-+, to

    Goal''
    (EQUAL (+ A B) CCC).

  The discussion above probably suffices to make good use of this
  [47m(UNHIDE (HIDE ...))[0m trick.  However, we invite the reader who
  wishes to understand the trick in depth to evaluate the following
  form before submitting the [47m[thm][0m form above.

    (trace$ (rewrite :entry (list (take 2 arglist))
                     :exit (list (car values)))
            (rewrite-with-lemma :entry (list (take 2 arglist))
                                :exit (take 2 values)))

  The following annotated subset of the trace output (which may appear
  a bit different depending on the underlying Common Lisp
  implementation) explains how the trick works.

        2> (REWRITE ((MY-PLUS B A) NIL))>
          3> (REWRITE-WITH-LEMMA
                  ((MY-PLUS B A)
                   (REWRITE-RULE (:META MY-META-LEMMA)
                                 1822
                                 NIL EQUAL META-FN NIL META NIL NIL)))>

    We apply the meta rule, then recursively rewrite the result, which is the
    (UNHIDE (HIDE ...)) term shown just below.

            4> (REWRITE ((UNHIDE (HIDE (BINARY-+ B A)))
                         ((A . A) (B . B))))>
              5> (REWRITE ((HIDE (BINARY-+ B A))
                           ((A . A) (B . B))))>

    The HIDE protects its argument from being touched by the rewriter.

              <5 (REWRITE (HIDE (BINARY-+ B A)))>
              5> (REWRITE-WITH-LEMMA
                      ((UNHIDE (HIDE (BINARY-+ B A)))
                       (REWRITE-RULE (:REWRITE UNHIDE-HIDE)
                                     1806 NIL EQUAL (UNHIDE (HIDE X))
                                     X ABBREVIATION NIL NIL)))>

    Now we apply UNHIDE-HIDE, then recursively rewrite its right-hand
    side in an environment where X is bound to (BINARY-+ B A).

                6> (REWRITE (X ((X BINARY-+ B A))))>

    Notice that at this point X is cached, so REWRITE just returns
    (BINARY-+ B A).

                <6 (REWRITE (BINARY-+ B A))>
              <5 (REWRITE-WITH-LEMMA T (BINARY-+ B A))>
            <4 (REWRITE (BINARY-+ B A))>
          <3 (REWRITE-WITH-LEMMA T (BINARY-+ B A))>
        <2 (REWRITE (BINARY-+ B A))>


Subtopics

  [Backchain-limit]
      Limiting the effort expended on relieving hypotheses

  [Case-split]
      Like force but immediately splits the top-level goal on the
      hypothesis

  [Evaluator-restrictions]
      Some restrictions on the use of evaluators in meta-level rules

  [Extended-metafunctions]
      State and context sensitive metafunctions

  [Force]
      Identity function used to force a hypothesis

  [Magic-ev-fncall]
      Call the named function on the given arguments and return the value.

  [Meta-extract]
      Meta reasoning using valid terms extracted from context or [world]

  [Meta-implicit-hypothesis]
      A potentially more efficient way of coding a hypothesis metafunction

  [Set-skip-meta-termp-checks]
      Skip output checks for [meta] functions and [clause-processor]s

  [Set-skip-meta-termp-checks!]
      Skip output checks non-[local]ly for [meta] functions and
      [clause-processor]s

  [Syntaxp]
      Attach a heuristic filter on a rule

  [Term-table]
      A table used to validate meta rules

  [Transparent-functions]
      Working around restrictions on the use of evaluators in meta-level
      rules")
 (META-EXTRACT
  (META CLAUSE-PROCESSOR)
  "Meta reasoning using valid terms extracted from context or [world]

  For this advanced topic, we assume familiarity with metatheorems and
  metafunctions (see [meta]), as well as extended metafunctions (see
  [extended-metafunctions]).  The capability described here ---
  so-called ``meta-extract hypotheses'' for a [47m:[0m[47m[meta][0m or a
  [47m:[0m[47m[clause-processor][0m rule --- provides an advanced form of
  meta-level reasoning that was initially designed largely by Sol
  Swords, who also provided a preliminary implementation.

  A meta rule or clause-processor rule may have so-called
  ``meta-extract'' hypotheses that take forms displayed below.  Here
  [47mevl[0m is the evaluator, [47mobj[0m is an arbitrary term, [47mmfc[0m is the
  metafunction context (which is a variable other than the symbol
  [47mSTATE[0m that represents the metafunction context; see
  [extended-metafunctions]), [47mstate[0m is literally the symbol [47mSTATE[0m, [47ma[0m
  is the second argument of [47mevl[0m in both arguments of the conclusion
  of the rule, and [47maa[0m is an arbitrary term.

    (evl (meta-extract-contextual-fact obj mfc state) a)
    (evl (meta-extract-global-fact obj state) aa) ; equivalent to the next form
    (evl (meta-extract-global-fact+ obj state state) aa)
    (evl (meta-extract-global-fact+ obj st state) aa)

  The first form is only legal for [47m:meta[0m rules for which the
  metafunction is an extended metafunction.  The remaining forms are
  legal for both [47m:meta[0m rules and [47m:clause-processor[0m rules.

  Sol Swords has contributed a community book,
  [47mclause-processors/meta-extract-user.lisp[0m, that uses a Skolemization
  trick to allow one to use at most one [47mmeta-extract-global-fact+[0m
  hypothesis and at most one [47mmeta-extract-contextual-fact[0m hypothesis.

  These additional hypotheses may be necessary in order to prove a
  proposed metatheorem or (for the second type of hypothesis above)
  clause-processor rule, in particular when the correctness of the
  metafunction depends on the correctness of utilities extracting
  formulas from the logical [world] or (for the first type) facts
  from the metafunction context (mfc).  After the rule is proved,
  however, the meta-extract hypotheses have no effect on how the rule
  is applied during a proof.  An argument for correctness of using
  meta-extract hypotheses is given in the ACL2 source code within a
  comment entitled ``Essay on Correctness of Meta Reasoning''.  In
  the documentation below, we focus primarily on [47m:[0m[47m[meta][0m rules, since
  the use of [47mmeta-extract-global-fact[0m hypotheses in
  [47m:[0m[47m[clause-processor][0m rules is entirely analogous.  (At the end,
  though, we discuss the last of the four forms displayed above.)
  And for [47m:meta[0m rules we focus not on the application of rules but,
  rather, on how the use of meta-extract hypotheses allow you to
  prove correctness of metafunctions that use facts from the logical
  [world] or the metafunction context (mfc).

  Below we describe properties of [47mmeta-extract-contextual-fact[0m and
  [47mmeta-extract-global-fact[0m, but only after we illustrate their
  utility with an example.  But even before we present that example,
  we first give a sense of how to think about these functions by
  showing a theorem that one can prove about the first of them.  If
  this snippet doesn't help your intuition, then just skip over it
  and start with the example.

    (defevaluator evl evl-list
      ((binary-+ x y) (typespec-check x y)))

    (thm (implies
          (not (bad-atom (cdr (assoc-equal 'x alist))))
          (equal (evl (meta-extract-contextual-fact (list :typeset 'x)
                                                    mfc
                                                    state)
                      alist)
                 (not (equal 0 ; indicates non-empty intersection
                             (logand (type-set-quote ; type-set of a constant
                                      (cdr (assoc-equal 'x alist)))
                                     (mfc-ts-fn 'x mfc state nil)))))))

  Next we present an example, which comes from the community book,
  [47mbooks/clause-processors/meta-extract-simple-test.lisp[0m.  That book
  presents very basic, contrived examples that nevertheless
  illustrate meta-extract hypotheses.  For a more interesting
  tutorial example, see the community book
  [47mbooks/demos/nth-update-nth-meta-extract.lisp[0m.

  Our example includes this meta rule.

    (defthm plus-identity-2-meta
      (implies (and (nthmeta-ev (meta-extract-global-fact '(:formula bar-posp)
                                                          state)
                                (list (cons 'u
                                            (nthmeta-ev (cadr (cadr term))
                                                        a))))
                    (nthmeta-ev (meta-extract-contextual-fact
                                 `(:typeset ,(caddr term)) mfc state)
                                a))
               (equal (nthmeta-ev term a)
                      (nthmeta-ev (plus-identity-2-metafn term mfc state) a)))
      :rule-classes ((:meta :trigger-fns (binary-+))))

  The two hypotheses illustrate the two basic kinds of meta-extract
  hypotheses: applications of the evaluator to a call of
  [47mmeta-extract-global-fact[0m and to a call of
  [47mmeta-extract-contextual-fact[0m.  Here is the definition of the
  metafunction used in the above rule, slightly simplified here from
  what is found in the above book (but adequate for proving the two
  events that follow it in the above book).

    (defun plus-identity-2-metafn (term mfc state)
      (declare (xargs :stobjs state :verify-guards nil))
      (case-match term
        (('binary-+ ('bar &) y)
         (cond
          ((equal (meta-extract-formula 'bar-posp state)
                  '(POSP (BAR U)))
           (if (ts= (mfc-ts y mfc state :forcep nil)
                    *ts-character*)
               (cadr term)
             term))
          (t term)))
        (& term)))

  This metafunction returns its input term unchanged except in the case
  that the term is of the form [47m(binary-+ (bar x) y)[0m and the following
  two conditions are met, in which case it returns [47m(bar x)[0m.

    (1)  (equal (meta-extract-formula 'bar-posp state)
                '(POSP (BAR U)))

    (2)  (ts= (mfc-ts y mfc state :forcep nil)
              *ts-character*)

  So suppose that term is [47m(list 'binary-+ (list 'bar x) y)[0m.  We show
  how the meta-extract hypotheses together with (1) and (2) imply
  that the conclusion of the above [47m:meta[0m rule holds.  Here is that
  conclusion after a bit of simplification.

    (equal (nthmeta-ev (list 'binary-+ (list 'bar x) y) a)
           (nthmeta-ev (list 'bar x) a))

  This equality simplifies as follows using the evaluator properties of
  [47mnthmeta-ev[0m.

    (equal (binary-+ (bar (nthmeta-ev x a))
                     (nthmeta-ev y a))
           (bar (nthmeta-ev x a)))

  Since a positive number plus a character is that number, it clearly
  suffices to show:

    (A)  (posp (bar (nthmeta-ev x a)))

    (B)  (characterp (nthmeta-ev y a))

  It remains then to show that these follow from (1) and (2) together
  with the meta-extract hypotheses.

  First consider (A).  We show that it is just a simplification of the
  first meta-extract hypothesis.

    (nthmeta-ev (meta-extract-global-fact '(:formula bar-posp)
                                          state)
                (list (cons 'u
                            (nthmeta-ev (cadr (cadr term))
                                        a))))
    = {by our assumption that term is (list 'binary-+ (list 'bar x) y)}
    (nthmeta-ev (meta-extract-global-fact '(:formula bar-posp)
                                          state)
                (list (cons 'u
                            (nthmeta-ev x a))))
    = {by definition of meta-extract-global-fact, as discussed later}
    (nthmeta-ev (meta-extract-formula 'bar-posp state)
                (list (cons 'u
                            (nthmeta-ev x a))))
    = {by (1)}
    (nthmeta-ev '(posp (bar u))
                (list (cons 'u
                            (nthmeta-ev x a))))
    = {by evaluator properties of nthmeta-ev}
    (posp (bar (nthmeta-ev x a)))

  Now consider (B).  We show that it is just a simplification of the
  second meta-extract hypothesis.

    (nthmeta-ev (meta-extract-contextual-fact
                 `(:typeset ,(caddr term)) mfc state)
                a)
    = {by our assumption that term is (list 'binary-+ (list 'bar x) y)}
    (nthmeta-ev (meta-extract-contextual-fact (list ':typeset y) mfc state)
                a)
    = {by definition of meta-extract-contextual-fact, as discussed later}
    (nthmeta-ev (list 'typespec-check
                      (list 'quote
                            (mfc-ts y mfc state :forcep nil))
                      y)
                a)
    = {by (2)}
    (nthmeta-ev (list 'typespec-check
                      (list 'quote *ts-character*)
                      y)
                a)
    = {by evaluator properties of nthmeta-ev}
    (typespec-check *ts-character* (nthmeta-ev y a))
    = {by definition of typespec-check}
    (characterp (nthmeta-ev y a))

  Note the use of [47m:forcep nil[0m above.  All of the [47mmfc-xx[0m functions take
  a keyword argument [47m:forcep[0m.  Calls of [47mmfc-xx[0m functions made on
  behalf of [47mmeta-extract-contextual-fact[0m always use [47m:forcep nil[0m, so
  in order to reason about these calls in your own metafunctions, you
  will want to use [47m:forcep nil[0m.  We have contemplated adding a
  utility like [47mmeta-extract-contextual-fact[0m that allows forcing but
  returns a tag-tree (see [ttree]), and may do so if there is demand
  for it.

  Finally, we document what is provided logically by calls of
  [47mmeta-extract-global-fact[0m and [47mmeta-extract-contextual-fact[0m.  Of
  course, you are invited to look at the definitions of these
  functions in the ACL2 source code, or by using [47m:[0m[47m[pe][0m.  Note that
  both of these functions are non-executable (each of their bodies is
  inside a call of [47m[non-exec][0m); their purpose is purely logical, not
  for execution.  The functions return [47m*t*[0m, i.e., [47m(quote t)[0m, in cases
  that they provide no information.

  First we consider the value of [47m(meta-extract-global-fact obj state)[0m
  for various values of [47mobj[0m.  When we refer below to concepts like
  ``body'' and ``evaluation'', we refer to these with respect to the
  logical world of the input [47mstate[0m.

      CASE [47mobj[0m = [47m(list :formula FN)[0m:

      In this case [47m(meta-extract-global-fact obj state)[0m is equal to
      [47m(meta-extract-formula FN state)[0m.  That, in turn, evaluates to
      the ``formula'' of [47mFN[0m in the following sense when [47mstate[0m is the
      ACL2 ``live'' [state] object.  If [47mFN[0m is a function symbol with
      formals [47m(X1 ... Xk)[0m, then the formula is the [constraint] on [47mFN[0m
      if [47mFN[0m is constrained or introduced by [47m[defchoose][0m, and
      otherwise is [47m(equal (FN X1 ... Xk) BODY)[0m, where [47mBODY[0m is the
      (unsimplified) body of the definition of [47mFN[0m.  Otherwise, if [47mFN[0m
      is the name of a theorem, the formula is just what is stored
      for that theorem.  Otherwise, the formula is [47m*t*[0m.

      CASE [47mobj[0m = [47m(list :lemma FN N)[0m:

      Assume [47mN[0m is a natural number; otherwise, treat [47mN[0m as 0.  Then
      [47m(meta-extract-global-fact obj state)[0m is equal to the term
      naturally constructed from the [47mrewrite-rule[0m record structure
      [47m(nth N (getpropc FN 'lemmas nil (w state)))[0m if [47mN[0m is in range,
      else [47m*t*[0m.  (The ACL2 source function [47mrewrite-rule-term[0m does
      this construction of a term from a [47mrewrite-rule[0m record
      structure.  It has a guard of [47mt[0m; a version that may execute
      more quickly but has a less trivial guard is
      [47mrewrite-rule-term-exec[0m.)  Thus, if [47mFN[0m is a function symbol with
      more than [47mN[0m associated lemmas --- ``associated'' in the sense
      of being either a [47m:[0m[47m[definition][0m rule for [47mFN[0m or a [47m:[0m[47m[rewrite][0m
      rule for [47mFN[0m whose left-hand side has a top function symbol of
      [47mFN[0m --- then when [47mstate[0m is the actual ACL2 ``live'' [state]
      object, [47m(meta-extract-global-fact obj state)[0m evaluates to the
      [47mN[0mth such lemma (with zero-based indexing).

      CASE [47mobj[0m = [47m(list :linear-lemma FN N)[0m:

      Assume [47mN[0m is a natural number; otherwise, treat [47mN[0m as 0.  Then
      [47m(meta-extract-global-fact obj state)[0m is equal to the term
      naturally constructed from the [47mlinear-lemma[0m record structure
      [47m(nth N (getpropc FN 'linear-lemmas nil (w state)))[0m if [47mN[0m is in
      range, else [47m*t*[0m.  (The ACL2 source function [47mlinear-lemma-term[0m
      does this construction of a term from a [47mlinear-lemma[0m record
      structure.  It has a guard of [47mt[0m; a version that may execute
      more quickly but has a less trivial guard is
      [47mlinear-lemma-term-exec[0m.)  Thus, if [47mFN[0m is a function symbol with
      more than [47mN[0m associated linear-lemmas --- ``associated'' in the
      sense of being a [47m:[0m[47m[linear][0m rule that has a max-term whose top
      function symbol is [47mFN[0m --- then when [47mstate[0m is the actual ACL2
      ``live'' [state] object, [47m(meta-extract-global-fact obj state)[0m
      evaluates to the [47mN[0mth such linear lemma (with zero-based
      indexing).

      CASE [47mobj[0m = [47m(list :fncall FN ARGLIST)[0m:

      Consider the term [47m(magic-ev-fncall FN ARGLIST state t nil)[0m, which is
      axiomatized to return a multiple values pair [47m(mv erp val)[0m, and
      moreover: if [47mstate[0m is the actual ACL2 ``live'' [state] and [47merp[0m
      is [47mnil[0m, then [47mval[0m is the result of applying [47mfn[0m to [47marglist[0m.  For
      example, after submitting [47m(defun foo (z) (mv (cdr z) (car z)))[0m,
      we can evaluate a corresponding call of [47mmagic-ev-fncall[0m as
      follows, noting that for this purpose the macro [47m[mv][0m is given
      its logical meaning, [47m[list][0m:

        ACL2 !>(magic-ev-fncall 'foo '((a b c)) state t nil)
        (NIL ((B C) A))
        ACL2 !>

      Let [47merp[0m and [47mval[0m be as above: more precisely, let them abbreviate the
      terms [47m(nth '0 (magic-ev-fncall FN ARGLIST state t nil))[0m and
      [47m(nth '1 (magic-ev-fncall FN ARGLIST state t nil))[0m,
      respectively.  Then [47m(meta-extract-global-fact obj state)[0m is
      either [47m*t*[0m, in the ``error case'' that [47merp[0m is not [47mnil[0m, or else
      is a term that equates [47mval[0m with the application of [47mFN[0m to
      [47mARGLIST[0m, as follows.  Assume that [47mFN[0m is a [47m:[0m[47m[logic][0m-mode
      function symbol and that [47mARGLIST[0m is a true list of values of
      the same length as list of formal parameters for [47mFN[0m (i.e., as
      the input arity of [47mFN[0m).  Let [47m(QARG1 ... QARGk)[0m be the result of
      quoting each element of [47mARGLIST[0m, i.e., replacing each [47my[0m in
      [47mARGLIST[0m by the two-element list [47m(quote y)[0m.  Then
      [47m(meta-extract-global-fact obj state)[0m reduces to the term [47m(equal
      (FN QARG1 ... QARGk) (quote val))[0m.

      CASE otherwise:

      For any other values of [47mobj[0m, the value is [47m*t*[0m.

  Finally, the value of [47m(meta-extract-contextual-fact obj mfc state)[0m is
  as follows for various values of [47mobj[0m.  Note a difference from the
  semantics of [47mmeta-extract-global-fact[0m: below, the relevant logical
  world is the one stored in the metafunction context, [47mmfc[0m, not in
  the input [47mstate[0m.

      CASE [47mobj[0m = (list :typeset TERM ...):

      The value is the value of [47m(typespec-check ts TERM)[0m, where [47mts[0m is the
      value of [47m(mfc-ts TERM mfc state :forcep nil :ttreep nil)[0m, and
      where [47m(typespec-check ts val)[0m is defined to be true when [47mval[0m
      has type-set [47mts[0m.  (Exception: If [47mval[0m satisfies [47mbad-atom[0m then
      [47mtypespec-check[0m is true when [47mts[0m is negative.)

      CASE [47mobj[0m = (list :rw+ TERM ALIST OBJ EQUIV ...):

      We assume below that [47mEQUIV[0m is a symbol that represents an equivalence
      relation, where [47mnil[0m represents [47m[equal][0m, [47mt[0m represents [47m[iff][0m, and
      otherwise [47mEQUIV[0m represents itself (an equivalence relation in
      the current logical [world]).  For any other [47mEQUIV[0m the value is
      [47m*t*[0m.  Now let [47mrhs[0m be the value of [47m(mfc-rw+ TERM ALIST OBJ EQUIV
      mfc state :forcep nil :ttreep nil)[0m.  Then the value is the term
      [47m(list 'equv (sublis-var ALIST TERM) rhs)[0m, where equv is the
      equivalence relation represented by [47mEQUIV[0m, and [47msublis-var[0m is
      defined to substitute a variable-binding alist into a term.

      CASE [47mobj[0m = (list :rw TERM OBJ EQUIV ...):

      The value is the same as above but for an [47mALIST[0m of [47mnil[0m, i.e., for the
      case that [47mobj[0m is [47m(list :rw+ TERM nil OBJ EQUIV ...)[0m.

      CASE [47mobj[0m = (list :ap TERM ...):

      The value is [47m(list 'not TERM)[0m if [47m(mfc-ap TERM mfc state :forcep nil)[0m
      is true, else is [47m*t*[0m.

      CASE [47mobj[0m = (list :relieve-hyp HYP ALIST RUNE TARGET BKPTR ...):

      The value is [47m(sublis-var alist hyp)[0m --- see above for a discussion of
      [47msublis-var[0m --- if the following is true.

        (mfc-relieve-hyp hyp alist rune target bkptr mfc state
                         :forcep nil :ttreep nil)

      Otherwise the value is [47m*t*[0m.

      CASE otherwise:

      If no case above applies, then the value is [47m*t*[0m.

  We conclude by considering the fourth of the four forms above (and
  implicitly, its special case represented by the third form above):

    (evl (meta-extract-global-fact+ obj st state) aa)

  The discussion above is for the function [47mmeta-extract-global-fact+[0m,
  but assumes that the logical [world]s of [47mst[0m and [47mstate[0m are equal;
  otherwise the value returned is [47m*t*[0m.  Of course, since a call of
  [47mmeta-extract-global-fact[0m expands to a corresponding call of
  [47mmeta-extract-global-fact+[0m in which the last two arguments are both
  [47mstate[0m, that condition holds automatically for that case.  But the
  [47mstate[0m mentioned in the meta-extract hypotheses of a [meta] rule or
  [clause-processor] rule is in essence an initial state.  In the
  case of a clause-processor rule, the clause-processor function may
  modify that initial state (say, by printing or modifying some state
  globals) without changing its world, and then pass that modified
  state to [47mfncall-term[0m.  While [47mfncall-term[0m may produce a different
  result for this modified state than for the initial state, both are
  valid: other than its world, the state is used only for heuristic
  purposes, such as determining whether guard-checking may cause an
  error.  A useful instance of the hypothesis displayed above will be
  one in which [47mst[0m is that modified state.")
 (META-EXTRACT-CONTEXTUAL-FACT (POINTERS)
                               "See [meta-extract].")
 (META-EXTRACT-FORMULA (POINTERS)
                       "See [meta-extract].")
 (META-EXTRACT-GLOBAL-FACT (POINTERS)
                           "See [meta-extract].")
 (META-EXTRACT-GLOBAL-FACT+ (POINTERS)
                            "See [meta-extract].")
 (META-EXTRACT-RW+-TERM (POINTERS)
                        "See [meta-extract].")
 (META-IMPLICIT-HYPOTHESIS
  (META)
  "A potentially more efficient way of coding a hypothesis metafunction

  We assume familiarity with [meta] rules.  In this topic, we discuss a
  relatively advanced capability of meta reasoning in ACL2 that can
  increase its efficiency.


Introduction

  In brief: if a metafunction application to a term, [47mu[0m, evaluates to a
  result of the form [47m(if TEST NEW-TERM u)[0m, then [47mTEST[0m is treated as an
  ``implicit hypothesis,'' which must rewrite to true in order for
  the meta rule to simplify the input term.  We now explain in more
  detail.

  Recall the general form of a meta rule:

    (implies (and (pseudo-termp x)        ; this hyp is optional
                  (alistp a)              ; this hyp is optional
                  (ev (hyp-fn x ...) a)   ; this hyp is optional
                  ; meta-extract hyps may also be included (see below)
                  )
             (equiv (ev x a)
                    (ev (fn x ...) a)))

  When this rule is to be applied to a term, [47mx[0m, then [47m(hyp-fn x ...)[0m is
  evaluated to produce a term, which must rewrite to true in order to
  evaluate the call [47m(fn x ...)[0m, which is then rewritten to a
  replacement for [47mx[0m.  But it may be that these calls of [47mhyp-fn[0m and [47mfn[0m
  share a sub-computation.  ACL2 provides the ``implicit hypothesis''
  mechanism in order to share such a sub-computation.  The next
  section illustrates how this mechanism works. The final section
  provides a precise specification of implicit hypotheses and how
  they are used in metareasoning.


Example

  The following example is trivial but illustrates the sort of
  situation for which implicit hypotheses can be useful.  First let
  us introduce a function and an evaluator (see [defevaluator]).

    (defun foo (x y)
      (+ x y))

    (defevaluator evl evl-list
      ((if x y z)
       (foo x y)
       (binary-+ x y)
       (unary-- x)
       (acl2-numberp x)
       (not x)))

  Let us write a meta function and associated hypothesis metafunction
  that apply a common function, [47mmeta-helper[0m, to a term, [47mterm[0m, to
  return one of two multiple values: [47m(mv nil term)[0m in the case that
  there is no simplification; else [47m(mv hyp new-term)[0m, where the
  following is a theorem: `(implies ,hyp (equal ,term ,new-term)).
  Of course, the following definition introduces a function whose
  calls can be evaluated very quickly; but for purposes of this
  example, let us pretend that calls of [47mmeta-helper[0m take a great deal
  of time to evaluate.

    (defun meta-helper (term) ; PRETEND that his function is expensive to compute!
      (declare (xargs :guard (pseudo-termp term)))
      (case-match term
        (('foo x ('foo y ('unary-- x)))
         (declare (ignore x))
         (mv `(acl2-numberp ,y)
             y))
        (& (mv nil term))))

  We can now define our meta function and hypothesis metafunction and
  prove a meta rule based on them.

    (defun meta-fn (term)
      (declare (xargs :guard (pseudo-termp term)))
      (mv-let (hyp new-term)
              (meta-helper term)
              (if hyp new-term term)))

    (defun meta-hyp-fn (term)
      (declare (xargs :guard (pseudo-termp term)))
      (mv-let (hyp new-term)
              (meta-helper term)
              (declare (ignore new-term))
              (or hyp ''nil)))

    (defthm meta-fn-correct
      (implies (evl (meta-hyp-fn x) a)
               (equal (evl x a)
                      (evl (meta-fn x) a)))
      :rule-classes ((:meta :trigger-fns (foo))))

  In order to see this meta rule in action, let us disable [47mfoo[0m and try
  a little test.

    (in-theory (disable foo))

    (defthm meta-fn-correct-test
      (implies (acl2-numberp b)
               (equal (foo a (foo b (- a)))
                      b)))

  Happily, the test succeeds, with the [summary] showing that our meta
  rule, [47mmeta-fn-correct[0m, was indeed used in the proof.  But if we
  first submit the form [47m(trace$ meta-fn meta-hyp-fn meta-helper)[0m, we
  will see that [47mmeta-helper[0m is called twice on the term [47m(FOO A (FOO B
  (UNARY-- A)))[0m: once on behalf of [47mmeta-fn[0m and once on behalf of
  [47mmeta-hyp-fn[0m.  This would be unfortunate if [47mmeta-helper[0m were
  expensive to compute.

  So let us back up and try a different approach, which illustrates the
  idea of using an ``implicit hypothesis'' in order to avoid
  recomputation.  This time, we avoid defining a hypothesis
  metafunction, but instead we define [47mmeta-fn[0m to return a term of the
  form [47m(if TEST NEW-TERM term)[0m.  Here, [47mTEST[0m is [47m`(acl2-numberp ,y)[0m; we
  call this an ``implicit hypothesis.''

    :ubt! meta-fn

    (defun meta-fn (term)
      (declare (xargs :guard (pseudo-termp term)))
      (mv-let (hyp new-term)
              (meta-helper term)
              (if hyp ; the interesting case
                  `(if ,hyp ,new-term ,term)
                term)))

  There is nothing remarkable in the proof of the corresponding meta
  rule.

    (defthm meta-fn-correct
      (equal (evl x a)
             (evl (meta-fn x) a))
      :rule-classes ((:meta :trigger-fns (foo))))

  Let us test our new implementation.  If we first evaluate the form
  [47m(trace$ meta-fn meta-helper)[0m, we will see that this time,
  [47mmeta-helper[0m is called only once on the term [47m(FOO A (FOO B (UNARY--
  A)))[0m.

    (in-theory (disable foo))

    (defthm meta-fn-correct-test
      (implies (acl2-numberp b)
               (equal (foo a (foo b (- a)))
                      b)))

  Note that the following proof attempt fails but does not loop.
  Naively, one might expect it to loop, since the false branch of the
  [47mIF[0m term returned by [47mmeta-fn[0m has the original (input) term as its
  false branch.  However, ACL2 notices the special form [47m(if TEST
  NEW-TERM term)[0m of the term returned by calling [47mmeta-fn[0m, and treats
  this result as though [47mTEST[0m is the term returned by a hypothesis
  metafunction and [47mNEW-TERM[0m is the term returned by the metafunction.

    (thm ; FAILS but does not loop!
     (equal (foo a (foo b (- a)))
            b))

  Suppose that instead we had defined [47mmeta-fn[0m as follows, that is, with
  the `then' and `else' branches swapped.

    (defun meta-fn (term)
      (declare (xargs :guard (pseudo-termp term)))
      (mv-let (hyp new-term)
              (meta-helper term)
              (if hyp ; the interesting case ;
                  `(if (not ,hyp) ,term ,new-term)
                term)))

  Then the events above go through as before, up to the [47m[thm][0m form.
  But that form loops, because the generated [47mIF[0m term no longer has
  the special form [47m(if TEST NEW-TERM term)[0m.  In the (likely rare)
  case that really wishes to allow an unresolved case split for which
  one branch is the original term, this swapping of branches is
  available to defeat the recognition of an implicit hypothesis.


Precise specification

  Consider a meta rule:

    (implies (and (pseudo-termp x)        ; this hyp is optional
                  (alistp a)              ; this hyp is optional
                  (ev (hyp-fn x ...) a)   ; this hyp is optional
                  ; meta-extract hyps may also be included (see below)
                  )
             (equiv (ev x a)
                    (ev (fn x ...) a)))

  Recall that when this rule is applied to a term, [47mterm[0m, then a list of
  hypotheses is initially generated as follows, where each generated
  hypothesis must be rewritten to a non-[47mnil[0m value in order for the
  rule to fire.

   1. If there is a hypothesis metafunction, [47mhyp-fn[0m, then let [47mhyps[0m be the
      list of hypothesis terms returned by the call of [47mhyp-fn[0m on
      [47mterm[0m.  More precisely, the term returned by the call of [47mhyp-fn[0m
      is flattened into a list of ``hypothesis terms,'' so that for
      example the (translated) conjunction [47m(if a (if b c 'nil) 'nil)[0m
      generates the list [47m(a b c)[0m of hypothesis terms.

   2. Otherwise, let [47mhyps[0m be [47mnil[0m.

  When this rule is applied by calling [47mfn[0m on a term, [47mterm[0m, we say that
  a term, [47mtest[0m, is an ``implicit hypothesis'' if the value returned
  by that call of [47mfn[0m is a term of the form [47m(if test new-term term)[0m:
  that is, [47mtest[0m is the test of the resulting [47mif[0m term and the input
  term is the false branch of that [47mif[0m term.  In this case, ACL2
  recognizes [47mtest[0m as an implicit hypothesis, which triggers two
  changes made in how this meta rule is applied.  First, [47mhyps[0m is
  extended by the flattened list of hypotheses generated from [47mtest[0m.
  Second, instead of applying [47mhyp-fn[0m to the original term, [47mterm[0m,
  [47mhyp-fn[0m is applied to [47mnew-term[0m.")
 (METAFUNCTION-CONTEXT
  (EXTENDED-METAFUNCTIONS)
  "A structure that holds data supporting extended meta reasoning

  This advanced topic explains the [47mmfc[0m structure documented elsewhere;
  see [extended-metafunctions] for prerequisite background.  This
  documentation is deliberately minimal, as we consider the [47mmfc[0m
  structure to be implementation-level; comments in the source code
  may serve to provide more information.

  [31;1mWARNING![0m This is a data structure that supports the ACL2
  implementation.  While it is highly stable in practice, there is no
  guarantee that future ACL2 implementations will avoid changing it.
  Use it at your own (perhaps small) risk!  If you want to avoid all
  such risk, use the interfaces described in the documentation for
  [extended-metafunctions], such as [47mmfc-rw[0m.

  The [47mmfc[0m (metafunction-context) structure, which is given in the ACL2
  sources by the form [47m(defrec metafunction-context ...)[0m, currently
  has the following fields.  Each instance is constructed in the
  context where it is needed, for example, during execution of a
  function that implements the ACL2 rewriter.

    * [47mancestors[0m: a list of terms assumed true, modified as we backchain

    * [47mbackchain-limit[0m: heuristic limit to backchaining

    * [47mfnstack[0m: functions and terms currently being expanded --- of
      heuristic use only

    * [47mgeneqv[0m: a generated equivalence relation to maintain

    * [47mgstack[0m: either [47mnil[0m or a goal stack, as in [cw-gstack]

    * [47mobj[0m: this ``objective'' is either [47mt[0m, [47mnil[0m, or [47m?[0m --- of heuristic use
      only.

    * [47mrcnst[0m: a [47mrewrite-constant[0m record that holds many fields to be
      accessed by the ACL2 rewriter.  See the definition [47m(defrec
      rewrite-constant ...)[0m, including comments therein, in the ACL2
      sources.

    * [47mrdepth[0m: maximum allowed rewrite stack depth --- of heuristic use only

    * [47msimplify-clause-pot-lst[0m: a pot-lst of polynomials ([47mpoly[0m records)

    * [47mttree[0m: the evolving [ttree] describing the rewrites

    * [47mtype-alist[0m: a [type-alist], representing assumptions governing the
      current rewrite

    * [47munify-subst[0m: either [47mnil[0m or a unifying substitution used by the
      rewriter

    * [47mwrld[0m: the current ACL2 [world]

  Here is an example of the use of these fields, which shows how to
  access the literal of the [clause] (goal) under which the current
  rewrite is taking place.

    (defevaluator my-ev my-ev-lst ((if x y z)))

    (defun my-metafn (x mfc state)
      (declare (xargs :stobjs state
                      :verify-guards nil)
               (ignore state))
      (let* ((rcnst (access metafunction-context mfc :rcnst))
             (not-flg/atm (access rewrite-constant rcnst :current-literal))
             (atm (access current-literal not-flg/atm :atm)))
        (prog2$ (cw \"Current literal:~%~x0~%Current term:~%~x1~%\"
                    atm
                    x)
                x)))

    (defthm my-meta-correct
      (equal (my-ev x a)
             (my-ev (my-metafn x mfc state) a))
      :rule-classes ((:meta :trigger-fns (nth))))

    (defthmd mv-nth-is-nth
      (equal (mv-nth x y)
             (nth x y)))

    (set-gag-mode nil)

    (thm (implies (and (true-listp x)
                       (true-listp y))
                  (equal (mv-nth n (append (car (cons x x)) y))
                         uuu))
         :hints ((\"Goal\" :do-not '(preprocess))
                 (\"Goal'\" :in-theory (enable mv-nth-is-nth))))

  Here is some relevant output from the [thm] call, which shows that
  the rule [47mmv-nth-is-nth[0m above has been applied while rewriting the
  conclusion of the proposed theorem --- the meta function's printing
  happens while in the course of rewriting the [47mNTH[0m call resulting
  from the application of the rule (i.e., an instance of the
  right-hand side of the rule).

    Goal'
    (IMPLIES (AND (TRUE-LISTP X) (TRUE-LISTP Y))
             (EQUAL (MV-NTH N (APPEND X Y)) UUU)).
    Current literal:
    (EQUAL (MV-NTH N (BINARY-APPEND X Y)) UUU)
    Current term:
    (NTH N (BINARY-APPEND X Y))")
 (MFC (POINTERS)
      "See [metafunction-context].")
 (MFC-ANCESTORS (POINTERS)
                "See [extended-metafunctions].")
 (MFC-AP (POINTERS)
         "See [extended-metafunctions].")
 (MFC-CLAUSE (POINTERS)
             "See [extended-metafunctions].")
 (MFC-RDEPTH (POINTERS)
             "See [extended-metafunctions].")
 (MFC-RELIEVE-HYP (POINTERS)
                  "See [extended-metafunctions].")
 (MFC-RW (POINTERS)
         "See [extended-metafunctions].")
 (MFC-RW+ (POINTERS)
          "See [extended-metafunctions].")
 (MFC-TS (POINTERS)
         "See [extended-metafunctions].")
 (MFC-TYPE-ALIST (POINTERS)
                 "See [extended-metafunctions].")
 (MFC-UNIFY-SUBST (POINTERS)
                  "See [extended-metafunctions].")
 (MFC-WORLD (POINTERS)
            "See [extended-metafunctions].")
 (MIN
  (NUMBERS ACL2-BUILT-INS)
  "The smaller of two numbers

  [47m(Min x y)[0m is the smaller of the numbers [47mx[0m and [47my[0m.

  The [guard] for [47mmin[0m requires its arguments to be rational ([real], in
  ACL2(r)) numbers.

  [47mMin[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<min>

    (defun min (x y)
      (declare (xargs :guard (and (real/rationalp x)
                                  (real/rationalp y))))
      (if (< x y) x y))")
 (MINIMAL-THEORY
  (THEORIES THEORY-FUNCTIONS)
  "A minimal theory to enable

  This [47m[theory][0m (see [theories]) enables only a few built-in functions
  and [executable-counterpart]s.  It can be useful when you want to
  formulate lemmas that rather immediately imply the theorem to be
  proved, by way of a [47m:use[0m hint (see [hints]), for example as
  follows.

    :use (lemma-1 lemma-2 lemma-3)
    :in-theory (union-theories '(f1 f2) (theory 'minimal-theory))

  In this example, we expect the current goal to follow from lemmas
  [47mlemma-1[0m, [47mlemma-2[0m, and [47mlemma-3[0m together with rules [47mf1[0m and [47mf2[0m and
  some obvious facts about built-in functions (such as the
  [definition] of [47m[implies][0m and the [47m:[0m[47m[executable-counterpart][0m of
  [47m[car][0m).  The [47m:[0m[47m[in-theory][0m hint above is intended to speed up the
  proof by turning off all inessential rules.")
 (MINUSP
  (NUMBERS ACL2-BUILT-INS)
  "Test whether a number is negative

  [47m(Minusp x)[0m is true if and only if [47mx < 0[0m.

  The [guard] of [47mminusp[0m requires its argument to be a rational ([real],
  in ACL2(r)) number.

  [47mMinusp[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<minusp>

    (defun minusp (x)
      (declare (xargs :guard (real/rationalp x)))
      (< x 0))")
 (MISCELLANEOUS
  (ACL2)
  "A miscellany of documented functions and concepts (often cited in
  more accessible [documentation])

  Perhaps as the system matures this section will become more
  structured.


Subtopics

  [Abort-soft]
      Control how interrupts are handled in proofs

  [ACL2-customization]
      File of initial commands for ACL2 to run at [startup]

  [Case-split-limitations]
      Limiting the number of immediate subgoals

  [Clause]
      A representation of prover goals

  [Default-defun-mode]
      The default [defun-mode] of [47m[defun][0m'd functions

  [Gc$]
      Invoke the garbage collector

  [Gc-strategy]
      The garbage collection strategy

  [Gcl]
      Tips on building and using ACL2 based on Gnu Common Lisp

  [Hints]
      Advice to the theorem proving process

  [Ld]
      The ACL2 read-eval-print loop, file loader, and [command] processor

  [Local-incompatibility]
      When non-local [events] won't replay in isolation

  [Ordinals]
      Ordinals in ACL2

  [Reader]
      Reading expressions in the ACL2 read-eval-print loop

  [Set-case-split-limitations]
      Set the [case-split-limitations]

  [Set-gc-strategy]
      Set the garbage collection strategy (CCL only)

  [Set-prover-step-limit]
      Sets the step-limit used by the ACL2 prover

  [Specious-simplification]
      Nonproductive proof steps

  [Subversive-inductions]
      Why we restrict [encapsulate]d recursive functions

  [Subversive-recursions]
      Why we restrict [encapsulate]d recursive functions

  [Syntax]
      The syntax of ACL2 is that of Common Lisp

  [Term]
      The three senses of well-formed ACL2 expressions or formulas

  [Thm]
      Prove a theorem

  [Top-level]
      Evaluate a top-level form as a function body

  [Ttags-seen]
      List some declared trust tags (ttags)

  [Ttree]
      Tag-trees

  [Type-set]
      How type information is encoded in ACL2

  [With-prover-step-limit]
      Limit the number of steps for proofs

  [With-prover-time-limit]
      Limit the time for proofs")
 (MIXED-MODE-FUNCTIONS
  (APPLY$)
  "[47m:[0m[47m[logic][0m mode functions can [47m[apply$][0m [47m:[0m[47m[program][0m mode functions

  Because [47m:[0m[47m[program][0m mode functions can be given badges it is possible
  to [47m[apply$][0m them from within [47m:[0m[47m[logic][0m mode functions.
  Colloquially, we call such [47m:logic[0m mode functions ``mixed mode,''
  but that is a misnomer.  They are indisputably in [47m:logic[0m mode.

  First, note that the only way to introduce a [47m:program[0m mode function
  into [47m:logic[0m mode functions is to use the quoted [47m:program[0m mode
  function name in an argument slot of [ilk] [47m:FN[0m, use the [47m:program[0m
  mode function in a quoted [47m[lambda][0m object or [47m[lambda$][0m expression
  in a slot of [ilk] [47m:FN[0m or use it in a quoted expression in a slot
  of ilk [47m:EXPR[0m.  We do not allow [47m:program[0m mode functions to be called
  directly from [47m:logic[0m mode functions.  For example, if [47mprgm[0m is
  defined as a [47m:program[0m mode function of one argument, and has been
  assigned a badge by [47m[defbadge][0m

    (defun foo (x)
      (declare (xargs :mode :logic))
      (apply$ 'prgm (list x)))

  is legal but

    (defun foo (x)
      (declare (xargs :mode :logic))
      (prgm x))

  is not.

  Second, the presence of a [47m:program[0m mode function in a [47m:logic[0m mode
  function prohibits the [47m:logic[0m mode function from being guard
  verified.

  Mixed-mode functions raise interesting questions for top-level
  evaluation and evaluation and rewriting during proofs.

  When a [47m:program[0m mode function is [47mapply$[0med, it is always done in
  [47m[safe-mode][0m.  In general, evaluating a [47m:program[0m mode function at
  the top-level can cause hard Lisp errors.  For example,

    (defun prgm (x) (declare (xargs :mode :program)) (car x))

  Then [47m(prgm 23)[0m causes a hard Lisp error in both CCL and SBCL, but
  [47m(prgm 'abc)[0m returns numbers in both of those Common Lisps, but they
  return different numbers.  Furthermore, there is no guarantee
  across all Common Lisps that [47m(prgm 'abc)[0m will always return the
  same number throughout a given ACL2 session; the value could
  conceivably change as memory is allocated, compacted, garbage
  collected, etc., since according to the CLTL standard, one is not
  supposed to apply [47mCAR[0m to any symbol other than [47mNIL[0m but no error
  need be signaled.  It is likely that a CLTL implementation of [47mCAR[0m
  just accesses memory where the [47mCAR[0m component of a cons is supposed
  to be!

  We tolerate such behavior when [47m:program[0m mode functions are directly
  called at the top-level because there are no axioms about them and
  we regard the evaluation of such programs from within the ACL2 loop
  as just a convenience to the user.

  But [47mapply$[0m is a [47m:logic[0m mode function and we must guarantee that when
  any [47m:logic[0m mode function is evaluated functional substitutivity
  holds: identical calls must yield identical results.  That is,
  [47mapply$[0m must behave like a [3mfunction[0m and not give different answers
  to the same questions over time when errors are not signaled.  We
  also strive to achieve the goal that [47m:logic[0m mode functions never
  cause hard Lisp errors other than resource errors like stack
  overflow or memory exhaustion.  So when [47mapply$[0m is given a badged
  [47m:program[0m mode function, e.g., had we badged [47mprgm[0m and then evaluated
  [47m(apply$ 'prgm '(abc))[0m, it must at least return the same ACL2 object
  every time!  To achieve this end [47mapply$[0m runs [47m:program[0m mode
  functions in [47m[safe-mode][0m.  (Safe mode does shift into raw Lisp on
  calls of guard verified [47m:logic[0m mode functions which might be called
  from within the [47m:program[0m mode function.  But a mixed mode function
  cannot be guard verified because the [47m:program[0m mode functions used
  within it cannot be guard verified.)

  This means that a top-level call of a mixed mode function generally
  runs slower than a corresponding call of an otherwise identical
  [47m:program[0m mode function.  (And, on the positive side, it means that
  mixed mode functions actually behave like [3mfunctions[0m while [47m:program[0m
  mode ones may not!)  The only way to speed up a mixed-mode function
  is to convert the [47m:program[0m mode functions in it to [47m:logic[0m mode with
  [47m[verify-termination][0m and verify the guards.

  As for proofs, since there are no axioms about [47m:program[0m mode
  functions, if a mixed-mode function is expanded in a proof all
  [47m:program[0m mode functions in it are treated as though they are
  undefined.  In particular, the absence of a warrant on the [47m:program[0m
  mode function [47mprgm[0m means that [47m(apply$ 'prgm '(abc))[0m, is not
  evaluated by the prover despite the fact that it is a ground term.")
 (MOD
  (NUMBERS ACL2-BUILT-INS)
  "Remainder using [47m[floor][0m

    ACL2 !>(mod 14 3)
    2
    ACL2 !>(mod -14 3)
    1
    ACL2 !>(mod 14 -3)
    -1
    ACL2 !>(mod -14 -3)
    -2
    ACL2 !>(mod -15 -3)
    0
    ACL2 !>

  [47m(Mod i j)[0m is that number [47mk[0m that [47m(* j (floor i j))[0m added to [47mk[0m equals
  [47mi[0m.

  The [guard] for [47m(mod i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real],
  in ACL2(r)) numbers and [47mj[0m is non-zero.

  [47mMod[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<mod>

    (defun mod (x y)
      (declare (xargs :guard (and (real/rationalp x)
                                  (real/rationalp y)
                                  (not (eql y 0)))))
      (- x (* (floor x y) y)))")
 (MOD-EXPT
  (NUMBERS ACL2-BUILT-INS)
  "Exponential function

  [47m(mod-expt r i m)[0m is the result of raising the number [47mr[0m to the integer
  power [47mi[0m and then taking the residue mod [47mm[0m.  That is, [47m(mod-expt r i
  m)[0m is equal to [47m(mod (expt r i) m)[0m.

  The [guard] for [47m(mod-expt r i m)[0m is that [47mr[0m is a rational number and [47mi[0m
  is an integer; if [47mr[0m is [47m0[0m then [47mi[0m is nonnegative; and [47mm[0m is a non-zero
  rational number.

  In some implementations (GCL Version 2.7.0 as of this writing), this
  function is highly optimized when [47mr[0m and [47mi[0m are natural numbers, not
  both zero, and [47mm[0m is a positive integer.  For other Lisp
  implementations, consider using function [47mmod-expt-fast[0m, defined in
  the community book [47marithmetic-3/floor-mod/mod-expt-fast.lisp[0m, which
  should still provide significantly improved performance over this
  function.

  [31;1mFunction: [0m<mod-expt>

    (defun mod-expt (base exp mod)
      (declare (xargs :guard (and (real/rationalp base)
                                  (integerp exp)
                                  (not (and (eql base 0) (< exp 0)))
                                  (real/rationalp mod)
                                  (not (eql mod 0)))))
      (mod (expt base exp) mod))")
 (MODE (POINTERS)
       "See [xargs] for information about the keyword [47m:mode[0m.")
 (MODELING_IN_ACL2
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Modeling in ACL2

  {IMAGE} (see [Running_Models])

  {IMAGE}

  Below we define [31;1mmc(s,n)[0m to be the function that [31;1msingle-step[0ms [31;1mn[0m times
  from a given starting state, [31;1ms[0m.  In Common Lisp, ``mc(s,n)'' is
  written [47m(mc s n)[0m.

    [31;1m(defun mc (s n)[0m                     ; To step [31;1ms[0m [31;1mn[0m times:
     [31;1m(if (zp n)[0m                         ; If [31;1mn[0m is 0
         [31;1ms[0m                              ;    then return [31;1ms[0m
         [31;1m(mc (single-step s) (- n 1))))[0m ;    else step [31;1msingle-step(s)[0m
                                                          [31;1mn-1[0m times.

  This is an example of a formal model in ACL2.

  {IMAGE} (see [Running_Models])")
 (MODELS_IN_ENGINEERING
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Models in Engineering

  {IMAGE}

  Frequently, engineers use mathematical models.  Use of such models
  frequently lead to

  [31;1mbetter designs[0m,

  [31;1mfaster completion of acceptable products[0m, and

  [31;1mreduced overall cost[0m,

  because models allow the trained user to study the design before it
  is built and analyze its properties.  Usually, testing and
  analyzing a model is cheaper and faster than fabricating and
  refabricating the product.

  {IMAGE}")
 (MODELS_OF_COMPUTER_HARDWARE_AND_SOFTWARE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Models of Computer Hardware and Software

  {IMAGE} (see [A_Typical_State])

  {IMAGE}

  Computing machines, whether hardware or software or some combination,
  are frequently modeled as ``state machines.''

  To so model a computing machine we must represent its [31;1mstates[0m as
  objects in our mathematical framework.

  [31;1mTransitions[0m are functions or relations on state objects.

  In what language shall we define these objects, functions, and
  relations?

  The mathematical languages we were taught in high school

  [31;1malgebra[0m,

  [31;1mgeometry[0m,

  [31;1mtrigonometry[0m, and

  [31;1mcalculus[0m

  are often inappropriate for modeling digital systems.  They primarily
  let us talk about numbers and continuous functions.

  To see what kind of expressive power we need, take a closer look at
  what a typical state contains.

  {IMAGE} (see [A_Typical_State])")
 (MONITOR
  (BREAK-REWRITE)
  "To monitor attempted applications of certain rules by the rewriter

  This function stores information about which runes should be
  monitored during rewriting and what criteria are used to invoke an
  interactive break when those runes are tried by the rewriter during
  a subsequent proof attempt.


Outline

    * Protocol for Using Monitors

    * Example and General Forms

    * Background on Rewriting

    * Criteria for Breaks

    * Example Break Conditions

    * What If No Break Occurs?


Protocol for Using Monitors

  When a proof fails and you expected it to succeed by applying rules
  you've proved, it can be helpful to see what happens when (if) the
  rewriter attempts to use your rules.  The [break-rewrite] utility
  allows you to monitor each attempt by the rewriter to use specific
  rules ([rune]s).  The basic protocol is that you turn on the
  break-rewrite utility with [47m[brr][0m and then you use this facility,
  [47mmonitor[0m, to specify the rules you want to monitor and the criteria
  for entering an interactive break.  (The variant [47m[monitor!][0m is like
  [47mmonitor[0m but also makes sure the break rewrite utility is turned
  on.)  Then you attempt the failed proof again.  When a monitored
  rule is tried and the criteria for that rule are satisfied, the
  rewriter triggers an interactive break allowing you to query the
  environment and watch what happens.  The break is a read-eval-print
  loop (in fact it is managed by [47mld[0m, the same function that provides
  ACL2's top-level interactive loop).  However, it is inside a
  [47m[wormhole][0m, allowing you to see what happening in rewrite.  But any
  changes you make while in this break disappear when the break exits
  and the wormhole evaporates.  See [brr-commands] for a list of the
  commands that specifically give you access to parts of the
  rewriter's state.  Such breaks do not allow you to change the
  course of the rewriter or otherwise guide the proof attempt!
  Breaks [31;1mdo[0m allow you to abort a proof attempt, which you typically
  do when you've understood why your rule failed to apply.  If you're
  seeking an interactive proof checker see [47m[proof-builder][0m.  To learn
  about the interactive breaks triggered when monitored runes are
  tried, see [break-rewrite].

  The current topic deals with how to install a monitor on a rule.


Example and General Forms

    Examples:
    (monitor '(:rewrite assoc-of-app) 't)
    (monitor '(:r assoc-of-app) t)
    (monitor 'assoc-of-app t)
    (monitor '(rewrite assoc-of-app) '(:condition t :depth 2))
    (monitor '(rewrite assoc-of-app) '(:condition t :rf t :depth 2))

    Keyword Command Examples:
    :monitor assoc-of-app t
    :monitor lemma42 (:condition (equal (brr@ :target) '(F A (G A (H B))))
                      :rf t
                      :depth 2
                      :abstraction (F x (G x y))
                      :lambda t))

    General Forms:
    (monitor x criteria)
    (monitor x criteria t) ; a quiet version
    (monitor! x criteria)  ; like quiet monitor but turns on brr first

  where (the value of) [47mx[0m is a [rune] or more generally a runic
  designator (see [theories]) designating one or more runes of
  classes [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, [47m:[0m[47m[rewrite-quoted-constant][0m, or
  [47m:[0m[47m[linear][0m and (the value of) [47mcriteria[0m is a ``keyword value list''
  --- a list of alternating keywords and values.  If no [47m:condition[0m
  key is supplied, [47m:condition t[0m is used.  If [47mcriteria[0m is some term,
  [47my[0m, it is treated as the keyword value list [47m(:condition y)[0m.  The
  following keywords and values are supported but the details are
  discussed below.

    * [47m:rf[0m --- value must be [47mT[0m or [47mNIL[0m, defaults to [47mNIL[0m

    * [47m:depth[0m --- value must be a natural number

    * [47m:abstraction[0m --- value must be a term and it is most often an
      abstraction of the pattern that triggers [47mx[0m obtained by
      replacing some subterms of that pattern by new variables

    * [47m:lambda[0m --- value must be [47mt[0m or [47mnil[0m

    * [47m:condition[0m --- value must be a term, called the ``break condition''
      which contains at most one free variable and that variable must
      be [47m[state][0m.  An interactive break is initiated only if the
      [47m:condition[0m term evaluates to non-[47mnil[0m.  If not provided, the
      [47m:condition[0m value defaults to [47m'T[0m.

  The keys [47m:depth[0m, [47m:abstraction[0m, and [47m:lambda[0m are only relevant when the
  rule named by [47mx[0m rewrites with an equivalence relation that is a
  refinement of the equivalence relation the rewriter is obligated to
  maintain on the current target (see [geneqv]) and the rule's
  ``pattern'' [31;1mdoes not match[0m the target.  They specify criteria under
  which a failed match is to be considered a ``near miss.'' Details
  are given below.

  The key [47m:rf[0m with value [47mT[0m indicates that breaks are to also occur (if
  the [47m:condition[0m evaluates to non-[47mnil[0m and) the rune's equivalence
  relation has failed to be a refinement of the equivalence relation
  the rewriter is obligated to maintain on the current target.  See
  [refinement-failure].  If [47m:rf[0m is [47mnil[0m or not provided, refinement
  failures do not trigger breaks but the other kinds of breaks may
  occur.

  Keywords other than [47m:condition[0m, [47m:rf[0m, [47m:depth[0m, [47m:abstraction[0m, and
  [47m:lambda[0m are allowed with no constraints on their values.  The
  purpose of this allowance is so that the user who wants to attach
  his or her own function to ACL2's [47m[brr-near-missp][0m predicate can
  pass information to that function.

  When successful, [47mmonitor[0m arranges for the rewriter to trigger an
  interactive break when any rule named by [47mx[0m and of the above classes
  is tried, provided the [break-rewrite] utility has been turned on
  --- using [47m:[0m[47m[brr][0m[47m t[0m, [47m:[0m[47m[monitor!][0m, or [with-brr-data] --- and the
  circumstances of the attempt to apply the rule satisfy the [47mcriteria[0m
  as checked by the function [47m[brr-near-missp][0m.  [47mMonitor[0m prints to the
  comment window a list of all the currently-monitored runes and
  their criteria and returns the error-triple [47m(value :invisible)[0m.
  The so-called ``quiet'' versions above do no printing.

  Some [47m:rewrite[0m rules are considered ``simple abbreviations''; see
  [simple].  These can be be monitored, but are only tried at certain
  times during the proof.  Monitoring is carried out by code inside
  the rewriter but abbreviation rules may be applied by a special
  purpose simplifier inside the so-called [3mpreprocess[0m phase of a
  proof.  If you desire to monitor an abbreviation rule, a warning
  will be printed suggesting that you may want to supply the hint
  [47m:DO-NOT '(PREPROCESS)[0m; see [hints].  Without such a hint, an
  abbreviation rule can be applied during the preprocess phase of a
  proof, and no such application will cause an interactive break.

  To remove a rune from the list of monitored runes, use [47m[unmonitor][0m.
  To see which runes are monitored and what their break criteria are,
  evaluate [47m([0m[47m[monitored-runes][0m[47m)[0m.

  [47mMonitor[0m, [47munmonitor[0m and [47mmonitored-runes[0m are macros that expand into
  expressions involving [47mstate[0m.  While these macros appear to return
  the list of [monitor]ed runes this is an illusion.  They all print
  [monitor]ed rune information to the comment window and then return
  [error-triple]s instructing [47mld[0m to print nothing.  It is impossible
  to return the list of [monitor]ed runes because it exists only in
  the [wormhole] [state] with which you interact when a break occurs.
  This allows you to change the [monitor]ed runes and their
  conditions during the course of a proof attempt without changing
  the [state] in which the proof is being constructed.

  Note: This list of monitored runes is maintained as a locally bound
  variable by break-rewrite.  For example, suppose that at the
  top-level of ACL2 the list of monitored runes and their criteria is
  [47mx[0m.  Suppose you then start a proof attempt, a break-rewrite break
  occurs and in that break you use [47mmonitor[0m or [47munmonitor[0m to change the
  list of monitored runes to [47my[0m.  Now suppose that you release or
  abort from the break and ACL2 returns to the top-level.  You might
  think the list of monitored runes is [47my[0m but in fact it is [47mx[0m.  The
  list is locally bound to value in the caller's environment each
  time break-rewrite is entered and thus restored to the value in the
  caller's environment when break-rewrite returns.


Background on Rewriting

  Before we explain the criteria for triggering breaks we establish
  some basic terminology about the rewriter.  We start with how it
  applies [47m:rewrite[0m rules.  The rewriter walks through a term
  (typically left-to-right, innermost first) maintaining a list of
  known assumptions represented as a [type-alist].  It rewrites each
  subterm under those assumptions.  The subterm the rewriter is
  currently considering is called the ``target''.  Each [47m:rewrite[0m rule
  is derived from some theorem essentially of the form [47m(implies (and
  hyp1 ... hypn) (equiv lhs rhs))[0m, where the [47mhypi[0m, [47mlhs[0m, and [47mrhs[0m are
  terms and [47mequiv[0m is known [equivalence] relation.  The [47mlhs[0m is always
  a function application and the rule derived from the theorem is
  stored in the ACL2 logical [world] under the topmost function
  symbol of the [47mlhs[0m.

  Each time the rewriter steps to a new target it retrieves all the
  rules stored under the topmost function symbol of the target and
  tries each rule in turn (provided the rule is enabled and its [47mequiv[0m
  is a [congruence] relation in the current context).  To try a
  [47m:rewrite[0m rule the rewriter first attempts to match the [47mlhs[0m to the
  target.  By ``match'' we mean the rewriter tries to find a
  substitution for the variables of [47mlhs[0m (consistent with the
  [47m[restrict][0m hints governing the target) such that applying the
  substitution to the [47mlhs[0m produces the target.  If the [47mlhs[0m matches
  the target, the rewriter then attempts to establish the [47mhypi[0m by
  rewriting each of them in turn, instantiating each [47mhypi[0m with the
  substitution.  If the instance of each [47mhypi[0m rewrites to true, we
  know --- by the theorem justifying this rule --- that that the
  instance of [47mlhs[0m is equivalent to the corresponding instance of [47mrhs[0m,
  but the instance of [47mlhs[0m is the target.  So the rewriter is
  logically justified in replacing the occurrence of the target by
  the instance of [47mrhs[0m and recursively rewrites that.  Heuristic
  considerations may prevent such a replacement, e.g., the
  instantiated [47mrhs[0m is considered ``too complicated,'' a loop might be
  detected, etc.

  We can generalize and summarize this description just by saying that
  each rule has a pattern, some hypotheses, and a result.  We say the
  rule is ``about'' the topmost function symbol in the pattern.  If
  the pattern matches the target, the hypotheses are true, and
  heuristic considerations allow, we use the result.  [47m:Definition[0m and
  [47m:rewrite-quoted-constant[0m rules fit easily within this scheme.  But
  [47m:linear[0m rules are a little different.  The conclusion of a [47m:linear[0m
  rule an arithmetic inequality relating subterms, the pattern is one
  of those subterms, and the result is the entire inequality
  conclusion.  If the hypotheses are all rewritten to true, the
  result is instantiated and added to the context, telling the
  rewriter possibly useful information about the target.


Criteria for Breaks

  If matching fails it is sometimes useful to see why.  How did the
  pattern and the target differ?  But since a rule about a given
  function symbol is tried every time the target has that same
  topmost function symbol, most rules fail to match much more often
  than they match.  Triggering a break on every failed match is
  counterproductive.  Instead, we introduce the notion of a ``near
  miss'' and allow you to set criteria that trigger breaks when a
  failed match is a near miss. There are three built-in near miss
  criteria, [47m:depth[0m, [47m:abstraction[0m, and [47m:lambda[0m.  We expect any given
  monitored command will probably specify only one of these three
  criteria, depending on the pattern in the rule and your judgment of
  what might be going wrong, but there is nothing preventing you from
  specifying multiple criteria.  If any one of them is satisfied by a
  failed match a break will occur.

    * [47m:depth n[0m causes a break if the pattern of the rune fails to match the
      target but the pattern does match down to depth [47mn[0m.  For
      example, the pattern [47m(F X (G X (H Y (I Z))))[0m fails to match the
      target [47m(F A (G B C))[0m, but it does match to depth 2.  To check
      this criterion the break utility abstracts the pattern by
      copying it and replacing every subterm at [47mn[0m by a new variable
      symbol.  The depth [47mn[0m abstractions of [47m(F X (G (H Y (I Z))))[0m for
      [47mn[0m=1, 2, and 3 are shown below.

        * [47mn[0m = 1: [47m(F GENSYM0 GENSYM1)[0m

        * [47mn[0m = 2: [47m(F X (G GENSYM0 GENSYM1))[0m

        * [47mn[0m = 3: [47m(F X (G X (H GENSYM0 GENSYM1)))[0m

    * [47m:abstraction apat[0m causes a break if the pattern of the rune fails to
      match the target but the translation of [47mapat[0m does match the
      target.  This is useful when you want more control over the
      abstraction of the pattern than [47m:depth[0m gives you.  For example,
      the depth 2 abstraction of [47m(F X (G X (H Y (I Z))))[0m is [47m(F X (G
      GENSYM0 GENSYM1))[0m but you may be interested only in breaks when
      [47m(F X (G X GENSYM1))[0m matches the target, i.e., where the first
      arguments of [47mF[0m and [47mG[0m are the same.  If so you could specify the
      criterion [47m:abstraction (F X (G X Y))[0m or, equivalently,
      [47m:abstraction (F X (G X GENSYM1))[0m.

    * [47m:lambda t[0m causes a break if the pattern of the rune fails to match
      the target but does match everywhere except on quoted [47m[lambda][0m
      constants.  This is checked by replacing each quoted [47mlambda[0m
      object in the pattern by a new variable.  This is particularly
      useful when your rule contains a [47mlambda$[0m expression, which
      translates to a quoted [47mlambda[0m constant, but the occurrence of
      that constant in the target has been rewritten (see
      [rewrite-lambda-object]).  See also the discussion of ``Normal
      Forms in Loop$ Bodies'' in
      [stating-and-proving-lemmas-about-loop$s].

  When a near miss break is caused it prints a message like this

    (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 (F X1 X2 X3)), specified when this rule
    was monitored.

  The message then displays all of the near miss break criteria that
  were satisfied and then prompts you for input.  This allows you to
  inspect the pattern (via the [47m[brr-commands][0m [47m:lhs[0m or [47m:max-term[0m
  depending on whether the monitored lemma is a [47m:rewrite[0m rule or a
  [47m:linear[0m rule.  You can inspect the target term with the command
  [47m:target[0m.  The ``+'' versions of those commands, e.g., [47m:lhs+[0m, will
  print the terms without evisceration.  If you want more information
  about why the pattern of the rule failed to match the target, use
  the command [47m:explain-near-miss[0m or its ``+'' version.  You may exit
  the break with any of the usual commands, e.g., [47m:ok[0m to continue the
  proof attempt (because perhaps you determined that the lemma was
  never supposed to match this particular target) or [47m:a![0m to abort
  back to the top-level to fix the problem (because you figured out
  why the lemma, as written, will not match the intended target).

  On the other hand, suppose the pattern of the rune matches the
  target.  Then the break condition term, i.e., the [47m:condition[0m
  criterion, is evaluated.  The only variable allowed in the break
  condition term is [47mstate[0m, which in the context of the break-rewrite
  utility is a [47m[wormhole][0m state.  Suppose the break condition term
  evaluates to [47mans[0m.  If [47mans[0m is [47mnil[0m, no break occurs.  If [47mans[0m is [47mt[0m, an
  interactive break occurs and the user is prompted for commands.
  Otherwise, [47mans[0m is expected to be a true list of commands to be fed
  to the break, i.e., to be appended to [47mstandard-oi[0m.  Those commands
  are then executed just as though the user typed them.  If they exit
  the break, the user is not prompted for further commands.  If they
  don't exit the break, the user is prompted for more commands.


Example Break Conditions

  In order to develop effective break conditions it must be possible to
  access context sensitive information, i.e., information about the
  context in which the [monitor]ed rune is being tried.  The [47m[brr@][0m
  macro may be used in break conditions to access such information as
  the term being rewritten and the current governing assumptions.
  This information is not stored in the proof [state] but is
  transferred into the [wormhole] [state] when breaks occur.  The
  macro form is [47m(brr@ :sym)[0m where [47m:sym[0m is one of several keyword
  symbols, including [47m:target[0m (the term being rewritten), [47m:unify-subst[0m
  (the substitution that instantiates the left-hand side of the
  conclusion of the rule so that it is the target term), and
  [47m:[0m[47m[type-alist][0m (the governing assumptions).  See [brr@].

  For example,

    ACL2 !>:monitor (:rewrite assoc-of-app)
                    (equal (brr@ :target) '(app (app a b) c))

  will monitor [47m(:rewrite assoc-of-app)[0m but will cause an interactive
  break only when the target term is literally [47m(APP (APP A B) C)[0m.

  Because break conditions are evaluated in the interaction
  environment, the user developing a break condition for a given rune
  can test candidate break conditions before installing them.  For
  example, suppose an unconditional break has been installed on a
  rune, that an interactive break has occurred and that the user has
  determined both that this particular application is uninteresting
  and that many more such applications will likely occur.  An
  appropriate response would be to develop an expression that
  recognizes such applications and returns [47mnil[0m.  Of course, the hard
  task is figuring out what makes the current application
  uninteresting.  But once a candidate expression is developed, the
  user can evaluate it in the current context simply to confirm that
  it returns [47mnil[0m.

  Recall that when a break condition returns a non-[47mnil[0m true list that
  list is appended to the front of [47mstandard-oi[0m.  For example,

    ACL2 !>:monitor (:rewrite assoc-of-app) '(:go)

  will cause [47m(:rewrite assoc-of-app)[0m to be monitored and will make the
  break condition be [47m'(:go)[0m.  This break condition always evaluates
  to the non-[47mnil[0m true list [47m(:go)[0m.  Thus, an interactive break will
  occur every time [47m(:rewrite assoc-of-app)[0m is tried.  The break is
  fed the command [47m:go[0m.  Now the command [47m:go[0m causes [47mbreak-rewrite[0m to
  (a) evaluate the attempt to apply the lemma, (b) print the result
  of that attempt, and (c) exit from the interactive break and let
  the proof attempt continue.  Thus, in effect, the above [47m:monitor[0m
  merely ``traces'' the attempted applications of the rune but never
  causes an interactive break requiring input from the user.

  It is possible to use this feature to cause a conditional break where
  the effective break condition is tested [31;1mafter[0m the lemma has been
  tried.  For example:

    ACL2 !>:monitor (:rewrite lemma12)
                    '(:unify-subst
                      :eval!
                      :ok-if (or (not (brr@ :wonp))
                                 (not (equal (brr@ :rewritten-rhs) '(foo a))))
                      :rewritten-rhs)

  causes the following behavior when [47m(:rewrite lemma12)[0m is tried.  A
  break always occurs, but it is fed the commands above.  The first,
  [47m:unify-subst[0m, causes [47mbreak-rewrite[0m to print out the unifying
  substitution.  Then in response to [47m:eval![0m the lemma is tried but
  with all runes temporarily [unmonitor]ed.  Thus no breaks will
  occur during the rewriting of the hypotheses of the lemma.  When
  the attempt has been made, control returns to [47mbreak-rewrite[0m (which
  will print the results of the attempt, i.e., whether the lemma was
  applied, if so what the result is, if not why it failed).  The next
  command, the [47m:ok-if[0m with its following expression, is a conditional
  exit command.  It means exit [47mbreak-rewrite[0m if either the attempt
  was unsuccessful, [47m(not (brr@ :wonp))[0m, or if the result of the
  rewrite is any term other than [47m(foo a)[0m.  If this condition is met,
  the break is exited and the remaining break commands are
  irrelevant.  If this condition is not met then the next command,
  [47m:rewritten-rhs[0m, prints the result of the application (which in this
  contrived example is known to be [47m(foo a)[0m).  Finally, the list of
  supplied commands is exhausted but [47mbreak-rewrite[0m expects more
  input.  Therefore, it begins prompting the user for input.  The end
  result of the above [47m:monitor[0m command is that the rune in question
  is elaborately traced and interactive breaks occur whenever it
  rewrites its target to [47m(foo a)[0m.

  We recognize that the above break condition is fairly arcane.  We
  suspect that with experience we will develop some useful idioms.
  For example, it is straightforward now to define macros that
  monitor runes in the ways suggested by the following names:
  [47mtrace-rune[0m, [47mbreak-if-target-is[0m, and [47mbreak-if-result-is[0m.  For
  example, the last could be defined as

    (defmacro break-if-result-is (rune term)
      `(monitor ',rune
                '(quote (:eval :ok-if
                               (not (equal (brr@ :rewritten-rhs) ',term))))))

  (Note however that the submitted term must be in translated form.)

  Since we don't have any experience with this kind of control on
  lemmas we thought it best to provide a general (if arcane)
  mechanism and hope that the ACL2 community will develop the special
  cases that we find most convenient.

  Note: The combination of a non-trivial [47m:condition[0m and some near-miss
  criteria can result in confusing behavior.  To get a near-miss
  break a target has to fail to match the rule's pattern but succeed
  in matching the near-miss criteria.  So the near-miss criteria is
  irrelevant if the target matches the rule. But to get a break the
  target must match the rule in such a way that the [47m:condition[0m is
  satisfied.  Failure to get any breaks when you have a non-trivial
  [47m:condition[0m and a very general near-miss criteria may mean targets
  matching the near-miss criteria also matched the rule's pattern but
  failed to satisfy your [47m:condition[0m.  Our personal preference when
  monitoring for near-misses is to use the default [47m:condition[0m of [47mt[0m,
  at least until we see what kind of matches are arising.


What If No Break Occurs?

  Suppose [47mrune[0m is a rune that names a rule about some function symbol
  [47mfn[0m.  What does it mean if you've installed a monitor on [47mrune[0m with
  [47m(:condition t :depth 1)[0m and [31;1mno break ever occurs[0m?  Then one of the
  following is probably true.

    * the break-rewrite utility is not turned on --- you should evaluate
      [47m(brr t)[0m,

    * [47mrune[0m is disabled in the theory used for subgoals mentioning [47mfn[0m ---
      you should enable it either with a global [47m[in-theory][0m command
      or a subgoal-specific [47m:in-theory[0m hint (see [hints]),

    * [47mrune[0m names an abbreviation rule as discussed above --- you should add
      the hint [47m:DO-NOT '(PREPROCESS)[0m (see [hints]),

    * the [47m:[0m[47m[hints][0m supplied includes a [47m:hands-off[0m list that includes [47mfn[0m ---
      perhaps you should disable other rules about [47mfn[0m (since that is
      presumably why you put [47mfn[0m on the [47m:hands-off[0m list in the first
      place) and remove [47mfn[0m from the [47m:hands-off[0m list,

    * the only terms that the rewriter ever encountered with the topmost
      function [47mfn[0m were within a [47mHIDE[0m,

    * no target with the topmost function symbol [47mfn[0m was ever seen by
      rewrite --- perhaps [47mfn[0m was involved in the conjecture or
      introduced into the proof attempt but was eliminated by another
      rewrite.

  The rewriter is complicated.  There may be other ways this could
  happen!")
 (MONITOR!
  (BREAK-REWRITE)
  "A quiet combination of [47m[monitor][0m and [47m[brr][0m

  [47mMonitor![0m is essentially the corresponding call of [47m[monitor][0m preceded
  by [47m(brr t)[0m, but avoiding output.  See [monitor] and see [brr].

  Note that [47mmonitor![0m may be used in place of [47mmonitor[0m even when inside
  an interactive break from [break-rewrite]; in that case, the [47mbrr[0m
  invocation on its behalf is essentially redundant.")
 (MONITORED-RUNES
  (BREAK-REWRITE)
  "Print the [monitor]ed [rune]s and their break conditions

    Example and General Form:
    (monitored-runes)
    :monitored-runes

  This macro prints a list, each element of which is of the form [47m(rune
  condition)[0m, showing each [monitor]ed [rune] and its current break
  condition.

  The list is printed to the comment window and [3mnot[0m returned as the
  value [47m(monitored-runes)[0m.  The actual list is maintained in a
  wormhole managed by [break-rewrite].

  Technically, the list of monitored runes is a locally bound variable
  of break-rewrite.  The initial value of the variable is determined
  by its value in the containing scope of a call of break-rewrite.
  The value may be changed during interactions within the break, but
  it reverts to its old value upon return from break-rewrite.  Thus
  if you monitor some runes, start a proof, adjust the monitored
  runes from within break-rewrite breaks in the proof attempt, and
  eventually return to the top-level, the value shown by
  [47m:monitored-runes[0m will be the same as it was when you started the
  proof.")
 (MSG
  (IO ACL2-BUILT-INS)
  "Construct a ``message'' suitable for the [47m~@[0m directive of [47m[fmt][0m

  See [fmt] for background on formatted printing with ACL2.

  In short: for a call [47m(msg s arg0 arg1 arg2 ...[0m), [47ms[0m should be a string
  suitable as an argument to [47m[fmt][0m and [47m(arg0 arg1 arg2 ...)[0m should be
  the bindings of [47m#\\0[0m, [47m#\\1[0m, [47m#\\2[0m, and so on.  See [msgp] for a weak
  recognizer of objects returned by [47mmsg[0m.  Now, for a more careful
  explanation:

  We document [47mmsg[0m precisely below, but first, we give an informal
  introduction and illustrate with an example.  Suppose you are
  writing a program that is to do some printing.  Typically, you will
  either pass the ACL2 state around (see [programming-with-state])
  and use formatted printing functions that take the state as an
  argument (see [fmt])), or else you might avoid using state by
  calling the utility, [47m[cw][0m, to do your printing.  Alternatively, you
  might print error messages upon encountering illegal situations;
  see [er].  But there are times where instead of printing
  immediately, you may prefer to pass messages around, for example to
  accumulate them before printing a final message.  In such cases, it
  may be desirable to construct ``message'' objects to pass around.

  For example, consider the following pair of little programs.  The
  first either performs a computation or prints an error, and the
  second calls the first on two inputs.

    (defun invert1 (x)
      (if (consp x)
          (cons (cdr x) (car x))
        (prog2$ (cw \"ERROR: ~x0 expected a cons, but was given ~x1.~|\"
                    'invert1 x)
                nil)))

    (defun invert2 (x1 x2)
      (list (invert1 x1) (invert1 x2)))

  For example:

    ACL2 !>(invert1 '(3 . 4))
    (4 . 3)
    ACL2 !>(invert1 'a)
    ERROR: INVERT1 expected a cons, but was given A.
    NIL
    ACL2 !>(invert2 '(3 . 4) '(5 . 6))
    ((4 . 3) (6 . 5))
    ACL2 !>(invert2 'a 'b)
    ERROR: INVERT1 expected a cons, but was given A.
    ERROR: INVERT1 expected a cons, but was given B.
    (NIL NIL)
    ACL2 !>

  Notice that when there are errors, there is no attempt to explain
  that these are due to a call of [47minvert2[0m.  That could be fixed, of
  course, by arranging for [47minvert2[0m to print its own error; but for
  complicated programs it can be awkward to coordinate printing from
  many sources.  So let's try a different approach.  This time, the
  first function returns two results.  The first result is an ``error
  indicator'' --- either a message object or [47mnil[0m --- while the second
  is the computed value (only of interest when the first result is
  [47mnil[0m).  Then the higher-level function can print a single error
  message that includes the error message(s) from the lower-level
  function, as shown below.

    (defun invert1a (x)
      (if (consp x)
          (mv nil
              (cons (cdr x) (car x)))
        (mv (msg \"ERROR: ~x0 expected a cons, but was given ~x1.~|\"
                 'invert1a x)
            nil)))

    (defun invert2a (x1 x2)
      (mv-let (erp1 y1)
              (invert1a x1)
              (mv-let (erp2 y2)
                      (invert1a x2)
                      (if erp1
                          (if erp2
                              (cw \"~x0 failed with two errors:~|  ~@1  ~@2\"
                                  'invert2a erp1 erp2)
                            (cw \"~x0 failed with one error:~|  ~@1\"
                                'invert2a erp1))
                        (if erp2
                            (cw \"~x0 failed with one error:~|  ~@1\"
                                'invert2a erp2)
                          (list y1 y2))))))

  For example:

    ACL2 !>(invert2a '(3 . 4) '(5 . 6))
    ((4 . 3) (6 . 5))
    ACL2 !>(invert2a '(3 . 4) 'b)
    INVERT2A failed with one error:
      ERROR: INVERT1A expected a cons, but was given B.
    NIL
    ACL2 !>(invert2a 'a 'b)
    INVERT2A failed with two errors:
      ERROR: INVERT1A expected a cons, but was given A.
      ERROR: INVERT1A expected a cons, but was given B.
    NIL
    ACL2 !>

  If you study the example above, you might well understand [47mmsg[0m.  But
  we conclude with precise documentation.

    General Form:
    (msg str arg1 ... argk)

  where [47mstr[0m is a string and [47mk[0m is at most 9.

  This macro returns a pair suitable for giving to the [47mfmt[0m directive
  [47m~@[0m.  Thus, suppose that [47m#\\c[0m is bound to the value of [47m(msg str arg1
  ... argk)[0m, where [47mc[0m is a character and [47mk[0m is at most 9.  Then the [47mfmt[0m
  directive [47m~@c[0m will print out the string, [47mstr[0m, in the context of the
  alist in which the successive [47mfmt[0m variables [47m#\\0[0m, [47m#\\1[0m, ..., [47m#\\k[0m are
  bound to the successive elements of [47m(arg1 ... argk)[0m.")
 (MSGP
  (IO ACL2-BUILT-INS)
  "Recognizer for a ``message''

  The form [47m(msgp x)[0m evaluates to true when [47mx[0m evaluates either to a
  string or to a [47mcons[0m whose [47mcar[0m is a string and whose [47mcdr[0m satisfies
  [47m[character-alistp][0m.  Note that [47mmsgp[0m will always hold for the output
  of the macro [msg].

  [31;1mFunction: [0m<msgp>

    (defun msgp (x)
      (declare (xargs :guard t))
      (or (stringp x)
          (and (consp x)
               (stringp (car x))
               (character-alistp (cdr x)))))")
 (MULTIPLE-VALUE (POINTERS)
                 "See [mv-let].")
 (MUST-BE-EQUAL
  (MBE ACL2-BUILT-INS)
  "Attach code for execution

  The form [47m(must-be-equal logic exec)[0m evaluates to [47mlogic[0m in the ACL2
  logic but evaluates to [47mexec[0m in raw Lisp.  The point is to be able
  to write one definition to reason about logically but another for
  evaluation.  Please see [mbe] and see [mbt] for appropriate macros
  to use, rather than calling [47mmust-be-equal[0m directly, since it is
  easy to commute the arguments of [47mmust-be-equal[0m by accident.

  In essence, the guard for [47m(must-be-equal x y)[0m is [47m(equal x y)[0m.
  However, note that [47mmust-be-equal[0m is a macro: [47m(must-be-equal logic
  exec)[0m expands to [47m(mbe1 exec logic)[0m, which expands to a call of
  [47m[return-last][0m.")
 (MUTUAL-RECURSION
  (EVENTS PROGRAMMING DEFUN)
  "Define some mutually recursive functions

  See [defun] for relevant background.

    Example:
    (mutual-recursion
     (defun evenlp (x)
       (if (consp x) (oddlp (cdr x)) t))
     (defun oddlp (x)
       (if (consp x) (evenlp (cdr x)) nil)))

    General Form:
    (mutual-recursion def1 ... defn)

  where each [47mdefi[0m is a call of [47m[defun][0m, [47m[defund][0m, [47m[defun-nx][0m, or
  [47mdefund-nx[0m.  Note that although one definition is acceptable, we
  focus on the case of at least two definitions, since normally one
  would not bother with [47mmutual-recursion[0m otherwise.

  When mutually recursive functions are introduced it is necessary to
  do the termination analysis on the entire clique of definitions.
  Each [47m[defun][0m form specifies its own measure, either with the
  [47m:measure[0m keyword [47mxarg[0m (see [xargs]) or by default to [47m[ACL2-count][0m.
  When a function in the clique calls a function in the clique, the
  measure of the callee's actuals must be smaller than the measure of
  the caller's formals --- just as in the case of a simply recursive
  function.  But with mutual recursion, the callee's actuals are
  measured as specified by the callee's [47m[defun][0m while the caller's
  formals are measured as specified by the caller's [47m[defun][0m.  These
  two measures may be different but must be comparable in the sense
  that [47m[o<][0m decreases through calls.

  If you want to specify [47m:[0m[47m[hints][0m or [47m:guard-hints[0m (see [xargs]), you
  can put them in the [47m[xargs][0m declaration of any of the [47m[defun][0m
  forms, as the [47m:[0m[47m[hints][0m from each form will be appended together, as
  will the [47m:[0m[47m[guard-hints][0m from each form.

  However, for the following [47m[xargs][0m declarations, listed
  alphabetically, it is illegal to specify more than one value,
  though it is legal to specify the same value more than once.

    :GUARD-DEBUG
    :GUARD-SIMPLIFY
    :LOOP$-RECURSION
    :MEASURE-DEBUG
    :MODE
    :NON-EXECUTABLE
    :NORMALIZE
    :OTF-FLG
    :SPLIT-TYPES
    :VERIFY-GUARDS
    :WELL-FOUNDED-RELATION

  Thus, for example, you may specify [47m:guard-debug t[0m in two different
  [47mdefun[0m forms in your [47mmutual-recursion[0m call, in which case the
  [guard-debug] feature will be active; but you must not specify
  [47m:guard-debug t[0m in one [47mdefun[0m but [47m:guard-debug nil[0m in another.  It
  suffices to specify such a value once, as that will apply
  throughout analysis of the [47mmutual-recursion[0m form.

  You may find it helpful to use a lexicographic order, the idea being
  to have a measure that returns a list of two arguments, where the
  first takes priority over the second.  Here is an example.

    (include-book \"ordinals/lexicographic-ordering\" :dir :system)

    (encapsulate
     ()
     (set-well-founded-relation l<) ; will be treated as LOCAL

     (mutual-recursion
      (defun foo (x)
        (declare (xargs :measure (list (acl2-count x) 1)))
        (bar x))
      (defun bar (y)
        (declare (xargs :measure (list (acl2-count y) 0)))
        (if (zp y) y (foo (1- y))))))

  The [47m[guard][0m analysis must also be done for all of the functions at
  the same time.  If any one of the [47m[defun][0ms specifies the
  [47m:[0m[47m[verify-guards][0m [47mxarg[0m to be [47mnil[0m, then [guard] verification is
  omitted for all of the functions.  Similarly, if any one of the
  [47m[defun][0ms specifies the [47m:non-executable[0m [47mxarg[0m to be [47mt[0m, or if any of
  the definitions uses [47m[defun-nx][0m or [47mdefund-nx[0m, then every one of the
  definitions will be treated as though it specifies a
  [47m:non-executable[0m [47mxarg[0m of [47mt[0m.

  Technical Note: Each [47mdefi[0m above must be a call of [47m[defun][0m, [47m[defund][0m,
  [47m[defun-nx][0m, or [47mdefund-nx[0m.  In particular, it is not permitted for a
  [47mdefi[0m to be an arbitrary form that macroexpands into a [47m[defun][0m form.
  This is because [47mmutual-recursion[0m is itself a macro, and since
  macroexpansion occurs from the outside in, at the time
  [47m(mutual-recursion def1 ... defk)[0m is expanded the [47mdefi[0m have not yet
  been macroexpanded.

  Suppose you have defined your own [47m[defun][0m-like macro and wish to use
  it in a [47mmutual-recursion[0m expression.  Well, you can't.  (!)  But
  you can define your own version of [47mmutual-recursion[0m that allows
  your [47m[defun][0m-like form.  Here is an example.  Suppose you define

    (defmacro my-defun (&rest args) (my-defun-fn args))

  where [47mmy-defun-fn[0m takes the arguments of the [47mmy-defun[0m form and
  produces from them a [47m[defun][0m form.  As noted above, you are not
  allowed to write [47m(mutual-recursion (my-defun ...) ...)[0m.  But you
  can define the macro [47mmy-mutual-recursion[0m so that

    (my-mutual-recursion (my-defun ...) ... (my-defun ...))

  expands into [47m(mutual-recursion (defun ...) ... (defun ...))[0m by
  applying [47mmy-defun-fn[0m to each of the arguments of
  [47mmy-mutual-recursion[0m.

    (defun my-mutual-recursion-fn (lst)
      (declare (xargs :guard (alistp lst)))

    ; Each element of lst must be a consp (whose car, we assume, is always
    ; MY-DEFUN).  We apply my-defun-fn to the arguments of each element and
    ; collect the resulting list of DEFUNs.

      (cond ((atom lst) nil)
            (t (cons (my-defun-fn (cdr (car lst)))
                     (my-mutual-recursion-fn (cdr lst))))))

    (defmacro my-mutual-recursion (&rest lst)

    ; Each element of lst must be a consp (whose car, we assume, is always
    ; MY-DEFUN).  We obtain the DEFUN corresponding to each and list them
    ; all inside a MUTUAL-RECURSION form.

      (declare (xargs :guard (alistp lst)))
      (cons 'mutual-recursion (my-mutual-recursion-fn lst))).


Subtopics

  [Defuns]
      An alternative to [47m[mutual-recursion][0m

  [Mutual-recursion-proof-example]
      A small proof about mutually recursive functions

  [Set-bogus-mutual-recursion-ok]
      Allow unnecessary ``mutual recursion''")
 (MUTUAL-RECURSION-PROOF-EXAMPLE
  (TUTORIAL5-MISCELLANEOUS-EXAMPLES MUTUAL-RECURSION)
  "A small proof about mutually recursive functions

  Sometimes one wants to reason about mutually recursive functions.
  Although this is possible in ACL2, it can be a bit awkward.  This
  example is intended to give some ideas about how one can go about
  such proofs.

  For an introduction to mutual recursion in ACL2, see
  [mutual-recursion].

  We begin by defining two mutually recursive functions: one that
  collects the variables from a [term], the other that collects the
  variables from a list of [term]s.  We actually imagine the [term]
  argument to be a [47mpseudo-termp[0m; see [pseudo-termp].

    (mutual-recursion

    (defun free-vars1 (term ans)
      (cond ((atom term)
             (add-to-set-eq term ans))
            ((fquotep term) ans)
            (t (free-vars1-lst (cdr term) ans))))

    (defun free-vars1-lst (lst ans)
      (cond ((atom lst) ans)
            (t (free-vars1-lst (cdr lst)
                               (free-vars1 (car lst) ans)))))

    )

  Now suppose that we want to prove the following theorem.

    (defthm symbol-listp-free-vars1-try-1
      (implies (and (pseudo-termp x)
                    (symbol-listp ans))
               (symbol-listp (free-vars1 x ans))))

  Often ACL2 can generate a proof by induction based on the structure
  of definitions of function symbols occurring in the conjecture.  In
  this case, ACL2 chooses to use an induction scheme suggested by
  [47m(symbol-listp ans)[0m, and sadly, that doesn't work.  If one were
  doing this proof with pencil and paper, one would be more likely to
  prove a combination of the conjecture above and an analogous
  conjecture about free-vars1-lst.  Feel free to try a pencil and
  paper proof!  Or you can read on, to see how one can get ACL2 to do
  such a proof after all.

  The trick is to define a function that suggests an appropriate
  induction.  The induction suggested is based on the if-then-else
  structure of the function's definition, where inductive hypotheses
  are generated for recursive calls --- below we explain how that
  works for this function.

    (defun symbol-listp-free-vars1-induction (x ans)
      (if (atom x)
    ; then we just make sure x and ans aren't considered irrelevant:
          (list x ans)
        (list (symbol-listp-free-vars1-induction (car x) ans)
              (symbol-listp-free-vars1-induction (cdr x) ans)
              (symbol-listp-free-vars1-induction (cdr x)
                                                 (free-vars1 (car x) ans)))))

  The if-then-else structure of this function generates two cases.  In
  one case, [47m(atom x)[0m is true, and the theorem to be proved should be
  proved under no additional hypotheses except for [47m(atom x)[0m; in other
  words, [47m(atom x)[0m gives us the base case of the induction.  In the
  other case, [47m(not (atom x))[0m is assumed together with three instances
  of the theorem to be proved, one for each recursive call.  So, one
  instance substitutes [47m(car x)[0m for [47mx[0m; one substitutes [47m(cdr x)[0m for [47mx[0m;
  and the third substitutes [47m(cdr x)[0m for [47mx[0m and [47m(free-vars1 (car x)
  ans)[0m for [47mans[0m.  If you think about how you would go about a hand
  proof of the theorem to follow, you'll likely come up with a
  similar scheme.

  We now prove the two theorems together as a conjunction, because the
  inductive hypotheses for one are sometimes needed in the proof of
  the other (even when you do this proof on paper!).

    (defthm symbol-listp-free-vars1
      (and (implies (and (pseudo-termp x)
                         (symbol-listp ans))
                    (symbol-listp (free-vars1 x ans)))
           (implies (and (pseudo-term-listp x)
                         (symbol-listp ans))
                    (symbol-listp (free-vars1-lst x ans))))
      :hints
      ((\"Goal\" :induct (symbol-listp-free-vars1-induction x ans))))

  The above works, but we conclude by illustrating a more efficient
  approach, in which we restrict to appropriate inductive hypotheses
  for each case.

    (ubt 'symbol-listp-free-vars1-induction)

    (defun symbol-listp-free-vars1-induction (flg x ans)

    ; Flg is nil if we are ``thinking'' of a single term.

      (if (atom x) ; whether x is a single term or a list of terms
          (list x ans)
        (if flg ; i.e., if x is a list of terms
            (list (symbol-listp-free-vars1-induction nil (car x) ans)
                  (symbol-listp-free-vars1-induction t
                                                     (cdr x)
                                                     (free-vars1 (car x) ans)))
          (symbol-listp-free-vars1-induction t (cdr x) ans))))

  We now state the theorem as a conditional, so that it can be proved
  nicely using the [induction] scheme that we have just coded.  The
  prover will not store an [47m[if][0m [term] as a [rewrite] rule, but
  that's OK (provided we tell it not to try), because we're going to
  derive the corollaries of interest later and make [31;1mthem[0m into
  [rewrite] rules.

    (defthm symbol-listp-free-vars1-flg
      (if flg
          (implies (and (pseudo-term-listp x)
                        (symbol-listp ans))
                   (symbol-listp (free-vars1-lst x ans)))
        (implies (and (pseudo-termp x)
                      (symbol-listp ans))
                 (symbol-listp (free-vars1 x ans))))
      :hints
      ((\"Goal\" :induct (symbol-listp-free-vars1-induction flg x ans)))
      :rule-classes nil)

  And finally, we may derive the theorems we are interested in as
  immediate corollaries.

    (defthm symbol-listp-free-vars1
      (implies (and (pseudo-termp x)
                    (symbol-listp ans))
               (symbol-listp (free-vars1 x ans)))
      :hints ((\"Goal\" :by (:instance symbol-listp-free-vars1-flg
                                     (flg nil)))))

    (defthm symbol-listp-free-vars1-lst
      (implies (and (pseudo-term-listp x)
                    (symbol-listp ans))
               (symbol-listp (free-vars1-lst x ans)))
      :hints ((\"Goal\" :by (:instance symbol-listp-free-vars1-flg
                                     (flg t)))))

  You may find [community-books] that help you to automate this kind of
  reasoning about mutually recursive functions.  See for example
  [make-flag].")
 (MV
  (BASICS ACL2-BUILT-INS)
  "Returning a multiple value

  [47mMv[0m is the mechanism provided by ACL2 for returning two or more
  values.  Logically, [47m(mv x1 x2 ... xn)[0m is the same as [47m(list x1 x2
  ... xn)[0m, a list of the indicated values.  However, ACL2 avoids the
  cost of building this list structure, with the cost that [47mmv[0m may
  only be used in a certain style in definitions: if a function ever
  returns using [47mmv[0m (either directly, or by calling another function
  that returns a multiple value), then this function must always
  return the same number of values.

  For more explanation of the multiple value mechanism, see [mv-let].
  Also see [mv-list] for a way to convert a multiple value into an
  ordinary list.

  ACL2 does not support the Common Lisp construct [47mvalues[0m, whose logical
  meaning seems difficult to characterize.  [47mMv[0m is the ACL2 analogue
  of that construct.


Subtopics

  [Mv-let]
      Calling multi-valued ACL2 functions

  [Mv-list]
      Converting [multiple-value] result to a single-value list

  [Mv-nth]
      The mv-nth element (zero-based) of a list

  [Mv?]
      Return one or more values

  [Mv?-let]
      Calling possibly multi-valued ACL2 functions")
 (MV-LET
  (MV BASICS ACL2-BUILT-INS)
  "Calling multi-valued ACL2 functions

    Example Form:
    (mv-let (x y z)              ; local variables
            (mv 1 2 3)           ; multi-valued expression
            (declare (ignore y)) ; optional declarations
            (cons x z))          ; body

  The form above binds the three ``local variables,'' [47mx[0m, [47my[0m, and [47mz[0m, to
  the three results returned by the multi-valued expression and then
  evaluates the body.  The result is [47m'(1 . 3)[0m.  The second local, [47my[0m,
  is [declare]d [47mignore[0md.  The multi-valued expression can be any ACL2
  expression that returns [47mk[0m results, where [47mk[0m is the number of local
  variables listed.  Often however it is simply the application of a
  [47mk[0m-valued function.  [47mMv-let[0m is the standard way to invoke a
  multi-valued function and then manipulate the values returned.

    General Form:
    (mv-let (var1 ... vark)
            term
            body)
    or
    (mv-let (var1 ... vark)
            term
            (declare ...) ... (declare ...)
            body)

  where the [47mvari[0m are distinct variables, [47mterm[0m is a term that returns [47mk[0m
  results and mentions only variables bound in the environment
  containing the [47mmv-let[0m expression, and [47mbody[0m is a term mentioning
  only the [47mvari[0m and variables bound in the environment containing the
  [47mmv-let[0m.  Each [47mvari[0m must occur in [47mbody[0m unless it is [declare]d
  [47mignore[0md or [47mignorable[0m in one of the optional [47m[declare][0m forms, unless
  this requirement is turned off; see [set-ignore-ok].  The value of
  the [47mmv-let[0m term is the result of evaluating [47mbody[0m in an environment
  in which the [47mvari[0m are bound, in order, to the [47mk[0m results obtained by
  evaluating [47mterm[0m in the environment containing the [47mmv-let[0m.

  Here is an extended example that illustrates both the definition of a
  multi-valued function and the use of [47mmv-let[0m to call it.  Consider a
  simple binary tree whose interior nodes are [47m[cons][0mes and whose
  leaves are non-[47m[cons][0mes.  Suppose we often need to know the number,
  [47mn[0m, of interior nodes of such a tree; the list, [47msyms[0m, of symbols
  that occur as leaves; and the list, [47mints[0m, of integers that occur as
  leaves.  (Observe that there may be leaves that are neither symbols
  nor integers.)  Using a multi-valued function we can collect all
  three results in one pass.

  Here is the first of two definitions of the desired function.  This
  definition is ``primitive recursive'' in that it has only one
  argument and that argument is reduced in size on every recursion.

    (defun count-and-collect (x)

    ; We return three results, (mv n syms ints) as described above.

      (cond ((atom x)

    ; X is a leaf.  Thus, there are 0 interior nodes, and depending on
    ; whether x is a symbol, an integer, or something else, we return
    ; the list containing x in as the appropriate result.

             (cond ((symbolp x) (mv 0 (list x) nil))
                   ((integerp x)(mv 0 nil      (list x)))
                   (t           (mv 0 nil      nil))))
            (t

    ; X is an interior node.  First we process the car, binding n1, syms1, and
    ; ints1 to the answers.

               (mv-let (n1 syms1 ints1)
                       (count-and-collect (car x))

    ; Next we process the cdr, binding n2, syms2, and ints2.

                       (mv-let (n2 syms2 ints2)
                               (count-and-collect (car x))

    ; Finally, we compute the answer for x from those obtained for its car
    ; and cdr, remembering to increment the node count by one for x itself.

                               (mv (1+ (+ n1 n2))
                                   (append syms1 syms2)
                                   (append ints1 ints2)))))))

  This use of a multiple value to ``do several things at once'' is very
  common in ACL2.  However, the function above is inefficient because
  it [append]s [47msyms1[0m to [47msyms2[0m and [47mints1[0m to [47mints2[0m, copying the list
  structures of [47msyms1[0m and [47mints1[0m in the process.  By adding
  ``accumulators'' to the function, we can make the code more
  efficient.

    (defun count-and-collect1 (x n syms ints)
      (cond ((atom x)
             (cond ((symbolp x) (mv n (cons x syms) ints))
                   ((integerp x) (mv n syms (cons x ints)))
                   (t (mv n syms ints))))
            (t (mv-let (n2 syms2 ints2)
                       (count-and-collect1 (cdr x) (1+ n) syms ints)
                       (count-and-collect1 (car x) n2 syms2 ints2)))))

  We claim that [47m(count-and-collect x)[0m returns the same triple of
  results as [47m(count-and-collect1 x 0 nil nil)[0m.  The reader is urged
  to study this claim until convinced that it is true and that the
  latter method of computing the results is more efficient.  One
  might try proving the theorem

    (defthm count-and-collect-theorem
      (equal (count-and-collect1 x 0 nil nil) (count-and-collect x))).

  Hint: the inductive proof requires attacking a more general theorem.

  ACL2 does not support the Common Lisp construct [47mmultiple-value-bind[0m,
  whose logical meaning seems difficult to characterize.  [47mMv-let[0m is
  the ACL2 analogue of that construct.  Also see [mv] and see
  [mv-list]."
)
 (MV-LIST
  (MV ACL2-BUILT-INS)
  "Converting [multiple-value] result to a single-value list

    Example Forms:
    ; Returns the list (3 4):
    (mv-list 2 (mv 3 4))

    ; Returns a list containing the three values returned by var-fn-count:
    (mv-list 3 (var-fn-count '(cons (binary-+ x y) z) nil))

    General form:
    (mv-list n term)

  Logically, [47m(mv-list n term)[0m is just [47mterm[0m; that is, in the logic
  [47mmv-list[0m simply returns its second argument.  However, the
  evaluation of a call of [47mmv-list[0m on explicit values always results
  in a single value, which is a ([47mnil[0m-terminated) list.  For
  evaluation, the term [47mn[0m above (the first argument to an [47mmv-list[0m
  call) must ``essentially'' (see below) be an integer not less than
  2, where that integer is the number of values returned by the
  evaluation of [47mterm[0m (the second argument to that [47mmv-list[0m call).

  We say ``essentially'' above because it suffices that the translation
  of [47mn[0m to a term (see [trans]) be of the form [47m(quote k)[0m, where [47mk[0m is
  an integer greater than 1.  So for example, if [47mterm[0m above returns
  three values, then [47mn[0m can be the expression [47m3[0m, or [47m(quote 3)[0m, or even
  [47m(mac 3)[0m if [47mmac[0m is a macro defined by [47m(defmacro mac (x) x)[0m.  But [47mn[0m
  cannot be [47m(+ 1 2)[0m, because even though that expression evaluates to
  [47m3[0m, nevertheless it translates to [47m(binary-+ '1 '2)[0m, not to [47m(quote
  3)[0m.

  [47mMv-list[0m is the ACL2 analogue of the Common Lisp construct
  [47mmultiple-value-list[0m.

  [31;1mFunction: [0m<mv-list>

    (defun mv-list (input-arity x)
      (declare (xargs :guard t)
               (ignore input-arity))
      x)")
 (MV-NTH
  (MV ACL2-BUILT-INS)
  "The mv-nth element (zero-based) of a list

  [47m(Mv-nth n l)[0m is the [47mn[0mth element of [47ml[0m, zero-based.  If [47mn[0m is greater
  than or equal to the length of [47ml[0m, then [47mmv-nth[0m returns [47mnil[0m.

  [47m(Mv-nth n l)[0m has a [guard] that [47mn[0m is a non-negative integer.

  [47mMv-nth[0m is equivalent to the Common Lisp function [47m[nth][0m (although
  without the guard condition that the list is a [47m[true-listp][0m), but
  is used by ACL2 to access the nth value returned by a multiply
  valued expression.  So, if you do proofs about functions that
  involve [47m[mv-let][0m, you may see calls of [47mmv-nth[0m in the prover output.
  For example, the following are logically equivalent:

    (mv-let (n1 n2)
            (mv (+ x y) (* x y))
            (- n1 n2))

    (let ((var (list (+ x y) (* x y))))
      (let ((n1 (mv-nth 0 var))
            (n2 (mv-nth 1 var)))
        (- n1 n2)))

  Here is a similar such example involving the ACL2 [state].  The
  following two forms are logically equivalent, but the second is
  only legal in contexts such as theorems (and proofs) rather than
  function definitions, since it violates single-threadedness
  restrictions (more on this below; also see [state] and see
  [stobj]).

    (mv-let (erp val state)
            (read-object ch state)
            (value (list erp val)))

    (let ((erp (mv-nth 0 (read-object ch state)))
          (val (mv-nth 1 (read-object ch state)))
          (state (mv-nth 2 (read-object ch state))))
      (value (list erp val)))

  [47mMv-nth[0m is given some special treatment by the prover.  To control
  that behavior see [theories-and-primitives].

  Finally, we elaborate on the single-threadedness issue above.  If
  [47mEXPR[0m is an expression that is multiply valued, then the form
  [47m(mv-nth n EXPR)[0m is illegal both in definitions and in forms
  submitted directly to the ACL2 loop.  Indeed, [47mEXPR[0m cannot be passed
  as an argument to any function ([47mmv-nth[0m or otherwise) in such an
  evaluation context.  The reason is that ACL2 code compiled for
  execution does not actually create a list for multiple value
  return; for example, the [47mread-object[0m call above logically returns a
  list of length 3, but when evaluated, it instead stores its three
  returned values without constructing a list.  The upshot is that it
  is generally best not to call [47mmv-nth[0m directly, but rather to use
  [47m[mv-let][0m, which generates [47mmv-nth[0m calls for reasoning but not for
  Lisp evaluation.  However, if you really want to use [47mmv-nth[0m
  directly to access a multiply-valued result, then --- at the cost
  of computational efficiency --- you can use [47m[mv-list][0m, writing
  [47m(mv-nth n (mv-list k EXPR))[0m for suitable [47mk[0m, where [47mmv-list[0m converts
  a multiple value result into the corresponding list; see [mv-list].

  [31;1mFunction: [0m<mv-nth>

    (defun mv-nth (n l)
      (declare (xargs :guard (and (integerp n) (>= n 0))))
      (if (atom l)
          nil
        (if (zp n)
            (car l)
          (mv-nth (- n 1) (cdr l)))))")
 (MV?
  (MV ACL2-BUILT-INS)
  "Return one or more values

  [47mMv?[0m is designed to work with [47mmv?-let[0m, generalizing how [47m[mv][0m works
  with [47m[mv-let][0m by allowing the binding of a single variable.  For
  example, the following form is legal.

    (mv?-let (y)
             (mv? (f x))
             (declare (type integer y))
             (g x y z))

  The expression above is equivalent to the following expression,
  because [47m(mv? form)[0m expands to [47mform[0m for any expression, [47mform[0m.

    (let ((y (f x)))
      (declare (type integer y))
      (g x y z))

  Logically, [47m(mv? x)[0m is the same as [47mx[0m, while [47m(mv? v1 v2 ...)[0m is the
  same as [47m(list v1 v2 ...)[0m.  Also see [mv] and see [mv?-let].")
 (MV?-LET
  (MV ACL2-BUILT-INS)
  "Calling possibly multi-valued ACL2 functions

  [47mMv?-let[0m is a macro that extends the macro [47m[mv-let][0m by allowing a
  single variable to be bound.  Thus, the syntax is the same as that
  of [47m[mv-let][0m except that [47mmv?-let[0m is permitted to bind a single
  variable to a form that produces a single value.  The macros
  [47mmv?-let[0m and [47m[mv?][0m are provided to facilitate the writing of macros
  that traffic in expressions that could return one or more
  (multiple) values.

  For example, the form

    (mv?-let (y)
             (f x)
             (declare (type integer y))
             (g x y z))

  is equivalent to the following form.

    (let ((y (f x)))
      (declare (type integer y))
      (g x y z))

  Calls of [47mmv?-let[0m and of [47m[mv-let][0m are equivalent when the first
  argument contains at least two variables; see [mv-let] for
  documentation.  In the case of binding a single variable, the
  general form is

    (mv?-let (var)
             term
             (declare ...) ... (declare ...)
             body)

  and this is equivalent to the following form (see [let]).

    (let ((var term))
      (declare ...) ... (declare ...)
      body)

  Also see [mv?].")
 (NAME
  (EVENTS)
  "Syntactic rules on logical names

    Examples                 Counter-Examples

    PRIMEP               91         (not a symbolp)
    F-AC-23              :CHK-LIST  (in KEYWORD package)
    1AX                  *PACKAGE*  (in the Lisp Package)
    |Prime Number|       1E3        (not a symbolp)

  Many different ACL2 entities have names, e.g., functions, macros,
  variables, constants, packages, theorems, [theories], etc.  Package
  names are strings.  All other names are symbols and may not be in
  the [47m\"KEYWORD\"[0m package.  Moreover, names of functions, macros,
  constrained functions, and constants, other than those that are
  predefined, must not be in the ``main Lisp package'' (which is
  ([47m\"LISP\"[0m or [47m\"COMMON-LISP\"[0m, according to whether we are following
  CLTL1 or CLTL2).  An analogous restriction on variables is given
  below.

  [47mT[0m, [47mnil[0m, and all names above except those that begin with ampersand
  (&) are names of variables or constants.  [47mT[0m, [47mnil[0m, and those names
  beginning and ending with star (*) are constants.  All other such
  names are variables.

  Note that names that start with ampersand, such as [47m&rest[0m, may be
  lambda list keywords and are reserved for such use whether or not
  they are in the CLTL constant [47mlambda-list-keywords[0m.  (See pg 82 of
  CLTL2.)  That is, these may not be used as variables.  Unlike
  constants, variables may be in the main Lisp package as long as
  they are in the original list of imports from that package to ACL2,
  the list [47m*common-lisp-symbols-from-main-lisp-package*[0m, and do not
  belong to a list of symbols that are potentially ``global.'' This
  latter list is the value of [47m*common-lisp-specials-and-constants*[0m.

  Our restrictions pertaining to the main Lisp package take into
  account that some symbols, e.g., [47mlambda-list-keywords[0m and [47mboole-c2[0m,
  are ``special.'' Permitting them to be bound could have harmful
  effects.  In addition, the Common Lisp language does not allow
  certain manipulations with many symbols of that package.  So, we
  stay away from them, except for allowing certain variables as
  indicated above.")
 (NAME_THE_FORMULA_ABOVE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Name the Formula Above

  When the theorem prover explicitly assigns a name, like [47m*1[0m, to a
  formula, it has decided to prove the formula by induction.")
 (NAT-LISTP
  (NUMBERS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of natural numbers

  The predicate [47mnat-listp[0m tests whether its argument is a true list of
  natural numbers.

  [31;1mFunction: [0m<nat-listp>

    (defun nat-listp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (eq l nil))
            (t (and (natp (car l))
                    (nat-listp (cdr l))))))")
 (NATP
  (NUMBERS ACL2-BUILT-INS)
  "A recognizer for the natural numbers

  The natural numbers is the set of all non-negative integers,
  [47m{0,1,2,3,...}[0m.  [47mNatp[0m returns [47mt[0m if and only its argument is a
  natural number, and [47mnil[0m otherwise.

  The community book [arithmetic/natp-posp] has some lightweight rules
  for reasoning about [47mposp[0m and [47mnatp[0m, and is included in the
  [arithmetic-1] library.  For a somewhat heavier and more
  comprehensive alternative, you may wish to instead see the
  [arith-equivs] book.

  [31;1mFunction: [0m<natp>

    (defun natp (x)
      (declare (xargs :guard t))
      (and (integerp x) (<= 0 x)))")
 (NEAR-MISSES
  (DEBUGGING)
  "Approximate event name matches

    General Form:

    (near-misses name)

  where [47mname[0m is a symbol.  Community books [47m\"xdoc/spellcheck\"[0m and
  [47m\"system/event-names\"[0m are used automatically (by temporarily
  including them) to compute a list of names of [events] that
  approximate the given name.  Example:

    ACL2 !>(near-misses nt)
    (NOT NTH)
    ACL2 !>")
 (NESTED-STOBJS
  (STOBJ)
  "Using [stobj]s that contain stobjs

  For this topic we assume that you already understand the basics of
  single-threaded objects in ACL2.  See [stobj], and in particular,
  see [defstobj], which notes that a stobj field can itself be a
  stobj, an array or hash-tablle of stobjs, or a [stobj-table].  The
  present [documentation] topic expands on that point.  However, we
  ignore stobj-table fields here; see [stobj-table] for such
  documentation.

  Our presentation is in five sections.  First we augment the
  documentation for [47m[defstobj][0m by explaining how stobjs may be
  specified for fields in a new stobj definition.  Then we explain an
  aliasing problem, which accounts for a prohibition against making
  direct calls to accessors and updaters involving stobj fields of
  stobjs.  Next, we introduce an ACL2 primitive, [47mstobj-let[0m, which
  provides the only way to read and write stobj components of stobjs.
  The fourth section provides precise documentation for [47mstobj-let[0m.
  We conclude by discussing the use of [47mstobj-let[0m with abstract stobjs
  (see [defabsstobj]); the discussion below ignores abstract stobjs
  until reaching that section.

  See also ACL2 community book [47mdemos/modeling/nested-stobj-toy-isa.lisp[0m
  for a worked example, which applies nested stobj structures to the
  problem of defining interpreters.  A variety of small additional
  examples may be found in ACL2 community book
  [47mbooks/system/tests/nested-stobj-tests.lisp[0m; and yet another, this
  one using [47m[swap-stobjs][0m to exchange stobj fields of a stobj, is in
  [47mbooks/demos/swap-stobj-fields.lisp[0m.  For further discussion, you
  are welcome to read the ``Essay on Nested Stobjs'', a long comment
  in ACL2 source file [47mother-events.lisp[0m.  However, this documentation
  topic is intended to be self-contained for those familiar with
  [stobj]s.


SECTION: Extension of [47m[defstobj][0m to permit [stobj]s within stobjs

  Recall that the [47m:type[0m keyword of a [47m[defstobj][0m field descriptor can be
  a ``type-indicator'' that specifies the type of the field as a
  type-spec (see [type-spec]).  For example, the following specifies
  an integer field, a field that is an array of bytes, and a field
  that is a hash table whose values are integers.

    (defstobj st
      (int-field :type integer :initially 0)
      (ar-field :type (array unsigned-byte (10)) :initially 0)
      (ht-field :type (hash-table eql nil integer) :initially 0))

  But the [47m:type[0m of a stobj field descriptor may instead be based on a
  stobj.  For example, the following sequence of three [events] is
  legal.  The first field descriptor of [47mtop[0m, named [47msub1-field[0m,
  illustrates one new kind of value for [47m:type[0m: the name of a
  previously-introduced stobj, which here is [47msub1[0m. The second field
  descriptor of [47mtop[0m, named [47msub2-ar-field[0m, illustrates a second new
  kind of value for [47m:type[0m: an array whose elements are specified by
  the name of a previously-introduced stobj, in this case, the stobj
  [47msub2[0m.  The third field descriptor is analogous to the second, but
  with a hash table instead of an array.  (See [stobj-table] for the
  fourth new kind of value for [47m:type[0m.)

    (defstobj sub1 fld1)
    (defstobj sub2 fld2)
    (defstobj top
      (sub1-field :type sub1)
      (sub2-ar-field :type (array sub2 (10)))
      (sub2-ht-field :type (hash-table equal nil sub2)))

  The [47m:initially[0m keyword is illegal for fields whose [47m:type[0m is a stobj,
  an array of stobjs, or a hash table of stobjs (or, not further
  discussed here, a [stobj-table]).  For a stobj field, the initial
  value is provided by a corresponding call of the stobj creator for
  that stobj.  For a field that is an array of stobjs, the stobj
  creator is called once for each element of the array, so that the
  array elements are distinct.  For example, each element of
  [47msub2-ar-field[0m in the example above is initially provided by a
  separate call of [47mcreate-sub2[0m.  Each initial element is thus unique,
  and in particular is distinct from the initial global value of the
  stobj.  Similarly, the initial global stobj for [47msub1[0m is distinct
  from the initial [47msub1-field[0m field of the global stobj for [47mtop[0m, as
  these result from separate calls of [47mcreate-sub1[0m.

  For a hash-table field, the [47m:initially[0m keyword is not actually used
  for the initial hash table, which is empty.  Instead, the
  [47m:initially[0m keyword typically determines the value returned when an
  accessor is applied to a key that is not bound --- but not for a
  hash table with stobj values.  In that case, a fresh copy of the
  indicated stobj is returned when applying the accessor to an
  unbound key.

  When a stobj is used in a field of another stobj, we may refer to the
  former field as a ``child stobj'' and the latter stobj as a
  ``parent stobj''.  So in the example above, [47msub1-field[0m is a child
  stobj of type [47msub1[0m for parent stobj [47mtop[0m, [47msub2-ar-field[0m is an array
  of child stobjs of type [47msub2[0m for parent stobj [47mtop[0m, and
  [47msub2-ht-field[0m is a hash table of child stobjs of type [47msub2[0m for
  parent stobj [47mtop[0m.  A child stobj has the same structural shape as
  the global stobj of its type, but as explained above, these are
  distinct structures.  We follow standard terminology by saying
  ``isomorphic'' to indicate the same structural shape.  So for
  example, (the value of) [47msub1-field[0m is isomorphic to [47msub1[0m, though
  these are distinct structures.

  ACL2 enforces the following restriction, which can allow for greater
  efficiency in the raw Lisp code generated for [47mstobj-let[0m forms, as
  per the discussion below about clearing memoization tables.  If the
  parent stobj is introduced by [47m[defstobj][0m using keyword argument
  [47m:non-memoizable t[0m, then this is required to have been the case for
  every child stobj as well.


SECTION: An aliasing problem

  Before introducing [47mstobj-let[0m below, we provide motivation for this
  ACL2 primitive.

  Consider the following [events].

    (defstobj child fld)
    (defstobj parent
      (fld2 :type child))

  Now suppose we could evaluate the following code, to be run
  immediately after admitting the two [47m[defstobj][0m events above.

    (let* ((child (fld2 parent))
           (child (update-fld 3 child)))
      (mv child parent))

  Now logically there is no change to [47mparent[0m: [47mparent[0m is passed through
  unchanged.  We can indeed prove that fact!

    (thm (equal (mv-nth 1
                        (let* ((child (fld2 parent))
                               (child (update-fld 3 child)))
                          (mv child parent)))
                parent))

  But recall that stobjs are updated with destructive assignments.
  That is, we really are updating [47m(fld2 parent)[0m to be the new value
  of [47mchild[0m, whether this is explained logically or not.  Thus,
  evaluation of the above [47m[let*][0m form does in fact change the actual
  global stobj, [47mparent[0m.

  (Aside: Here is an explanation involving raw Lisp, for those who
  might find this useful.  We escape to raw Lisp and execute the
  following.

    (let ((parent (cdr (assoc-eq 'parent *user-stobj-alist*))))
      (let* ((child (fld2 parent))
             (child (update-fld 4 child)))
        (mv child parent)))

  Then, in raw Lisp, [47m(fld (fld2 (cdr (assoc-eq 'parent
  *user-stobj-alist*))))[0m evaluates to [47m4[0m, illustrating the destructive
  update.  End of Aside.)

  Such aliasing can permit a change to a child stobj to cause a
  logically-inexplicable change to the parent stobj.  Similarly,
  unfettered accessing of stobj fields can result in logically
  inexplicable changes to the child stobj when the parent stobj is
  changed.  Thus, ACL2 disallows direct calls of stobj accessors and
  updaters for fields whose [47m:type[0m is a stobj or an array or hash
  table of stobjs (or a [stobj-table]).  Instead, ACL2 provides
  [47mstobj-let[0m for reading and writing such fields in a sound manner.


SECTION: Accessing and updating stobj fields of stobjs using
[47mstobj-let[0m

  ACL2 provides a primitive, [47mstobj-let[0m, to access and update stobj
  fields of stobjs, in a manner that avoids the aliasing problem
  discussed above.  In this section we provide an informal
  introduction to [47mstobj-let[0m, using examples, to be followed in the
  next section by precise documentation.

  We begin by returning to a slight variant of the example above.

    (defstobj child fld)
    (defstobj parent
      (fld2 :type child)
      fld3)

  The following form returns the result of updating the [47mfld2[0m field of
  [47mparent[0m, which is a stobj isomorphic to [47mchild[0m, to have a value of 3.
  Below we explain the terms ``bindings'', ``producer variables'',
  ``producer'', and ``consumer'', as well as how to understand this
  form.

    (stobj-let
     ((child (fld2 parent)))  ; bindings
     (child)                  ; producer variable(s)
     (update-fld 3 child)     ; producer
     (update-fld3 'a parent)) ; consumer

  The four lines under ``[47mstobj-let[0m'' just above can be understood as
  follows.

    * Bindings:
          Bind [47mchild[0m to [47m(fld2 parent)[0m.

    * Producer variable(s) and producer:
          Then bind the variable, [47mchild[0m, to the value of the producer,
          [47m(update-fld 3 child)[0m.

    * Implicit update of parent:
          Update [47mfld2[0m of [47mparent[0m with the producer variable, [47mchild[0m.

    * Consumer:
          Finally, return [47m(update-fld3 'a parent)[0m.

  Thus, the logical expansion of the [47mstobj-let[0m form above is the
  following expression, though this is approximate (see below).

    (let ((child (fld2 parent))) ; bindings
      (let ((child (update-fld 3 child))) ; bind producer vars to producer
        (let ((parent (update-fld2 child parent))) ; implicit update of parent
          (update-fld3 'a parent))))

  The bindings always bind distinct names to child stobjs of a unique
  parent stobj, where the child stobj corresponds to the [47m:type[0m
  associated with the indicated accessor in the [47m[defstobj][0m form for
  the parent stobj.  Thus in this case, for the unique binding,
  variable [47mchild[0m is bound to the stobj of `type' [47mchild[0m for accessor
  [47mfld2[0m of the parent stobj, [47mparent[0m.  We refer to [47mchild[0m from the
  bindings as a ``stobj-let-bound variable''.  Note also that the
  ``implicit extra step'' mentioned above is generated by
  macroexpansion of [47mstobj-let[0m; it logically updates the parent with
  new child values, just before calling the consumer.  Implementation
  note for those using [memoization]: destructive updating in raw
  Lisp lets us omit this implicit extra step, though the raw Lisp
  code generated for [47mstobj-let[0m will clear the memoization table for
  every function taking the parent stobj as an input, if any child
  stobj bound in the bindings is among the producer variables ---
  unless the parent stobj was introduced by [47m[defstobj][0m using keyword
  argument [47m:non-memoizable t[0m.

  The form above is equivalent to the form displayed just below, which
  differs only in specifying an explicit stobj updater corresponding
  to the stobj accessor, [47mfld2[0m.  Here we show the default updater
  name, whose name has [47m\"UPDATE-\"[0m prepended to the name of the
  accessor.  But if the [47m:RENAMING[0m field of the [47mdefstobj[0m event
  specified a different updater name corresponding to [47mfld2[0m, then that
  would need to be included where we have added [47mupdate-fld2[0m below.

    (stobj-let
     ((child (fld2 parent) update-fld2)) ; bindings, including updater(s)
     (child)                  ; producer variables
     (update-fld 3 child)     ; producer
     (update-fld3 'a parent)) ; consumer

  You can experiment using [47m:[0m[47m[trans1][0m to see the single-step
  macroexpansion of a [47mstobj-let[0m form in the logic.  For example, here
  is how that works for a [47mstobj-let[0m form that binds three fields and
  updates two of them.  Notice that because more than one field is
  updated, an [47m[mv-let][0m form is generated to bind the two fields to
  their values returned by the producer, rather than a [47m[let][0m form as
  previously generated.  First, let's introduce some events.

    (defstobj child1 child1-fld)
    (defstobj child2 child2-fld)
    (defstobj child3 child3-fld)
    (defstobj mom
      (fld1 :type child1)
      (fld2 :type child2)
      (fld3 :type child3))
    ; Silly stub:
    (defun update-last-op (op mom)
      (declare (xargs :stobjs mom))
      (declare (ignore op))
      mom)
    (defun new-mom (mom)
      (declare (xargs :stobjs mom))
      (stobj-let
       ((child1 (fld1 mom))
        (child2 (fld2 mom))
        (child3 (fld3 mom)))
       (child1 child3)
       (let* ((child1 (update-child1-fld 'one child1))
              (child3 (update-child3-fld 'three child3)))
         (mv child1 child3))
       (update-last-op 'my-compute mom)))

  Now let's look at the single-step macroexpansion of the above
  [47mstobj-let[0m form.

    ACL2 !>:trans1 (stobj-let
                    ((child1 (fld1 mom))
                     (child2 (fld2 mom))
                     (child3 (fld3 mom)))
                    (child1 child3)
                    (let* ((child1 (update-child1-fld 'one child1))
                           (child3 (update-child3-fld 'three child3)))
                      (mv child1 child3))
                    (update-last-op 'my-compute mom))
     (PROGN$
      (LET
       ((CHILD1 (FLD1 MOM))
        (CHILD2 (FLD2 MOM))
        (CHILD3 (FLD3 MOM)))
       (DECLARE (IGNORABLE CHILD1 CHILD2 CHILD3))
       (MV-LET
          (CHILD1 CHILD3)
          (CHECK-VARS-NOT-FREE (MOM)
                               (LET* ((CHILD1 (UPDATE-CHILD1-FLD 'ONE CHILD1))
                                      (CHILD3 (UPDATE-CHILD3-FLD 'THREE CHILD3)))
                                     (MV CHILD1 CHILD3)))
          (LET* ((MOM (UPDATE-FLD1 CHILD1 MOM))
                 (MOM (UPDATE-FLD3 CHILD3 MOM)))
                (CHECK-VARS-NOT-FREE (CHILD1 CHILD2 CHILD3)
                                     (UPDATE-LAST-OP 'MY-COMPUTE MOM))))))
    ACL2 !>

  If you try to evaluate a [47mstobj-let[0m form directly in the top-level
  loop, rather than from within a function body, you will get an
  error.  The example above illustrates how [47mstobj-let[0m may be used in
  function bodies; here is another example, presented using an edited
  log.

    ACL2 !>(defstobj child fld)

    Summary
    Form:  ( DEFSTOBJ CHILD ...)
    Rules: NIL
    Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
     CHILD
    ACL2 !>(defstobj parent
             (fld2 :type child)
             fld3)

    Summary
    Form:  ( DEFSTOBJ PARENT ...)
    Rules: NIL
    Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
     PARENT
    ACL2 !>(defun f (parent)
             (declare (xargs :stobjs parent))
             (stobj-let
              ((child (fld2 parent)))   ; bindings
              (child)                   ; producer variables
              (update-fld 3 child)      ; producer
              (update-fld3 'a parent))) ; consumer
    [[output omitted]]
     F
    ACL2 !>(f parent)
    <parent>
    ACL2 !>(defun check-f (parent)
             ; returns the value of the field of the child stobj
             (declare (xargs :stobjs parent))
             (stobj-let
              ((child (fld2 parent))) ; bindings
              (val)                   ; producer variables
              (fld child)             ; producer
              val))                   ; consumer
    [[output omitted]]
     CHECK-F
    ACL2 !>(check-f parent)
    3
    ACL2 !>

  Notice that the second function defined above, [47mcheck-f[0m, uses a
  [47mstobj-let[0m form that returns an ordinary value: it reads a value
  from a child stobj, but does not write to the child stobj, as
  indicated by the lack of a child stobj among the producer
  variables.  So for that [47mstobj-let[0m form, there is no implicit extra
  step.

  We labeled a [47mstobj-let[0m expansion above as ``approximate'' for two
  reasons, which we give here informally.  (Now you know how to apply
  [47m:[0m[47m[trans1][0m to that [47mstobj-let[0m call to see the precise expansion.)
  First, [47mstobj-let[0m declares the stobj-let-bound variables to be
  [47mignorable[0m for the top [47mlet[0m bindings.  Second, and more importantly,
  [47mstobj-let[0m imposes the following restrictions on the producer and
  consumer, to avoid the aliasing problem: it disallows references to
  the parent stobj in the producer and it also disallows references
  to any bound stobj (i.e., bound in the bindings) in the consumer.

  We conclude this section with examples based on a slight variation of
  the nested stobj example from the first section above.  These
  events can also be found in ACL2 community book
  [47mbooks/system/tests/nested-stobj-tests.lisp[0m, immediately under the
  following comment:

    ; As promised in :doc stobj-let, we begin with an example from that :doc.

  Note that some lemmas were needed in order to complete the [guard]
  proof for the function [47mupdate-top[0m, which may be found in the above
  file; they are omitted below.

  First we introduce three stobjs.

    (defstobj kid1 fld1)
    (defstobj kid2 fld2)
    (defstobj mom
      (kid1-field :type kid1)
      (kid2-ar-field :type (array kid2 (5)))
      last-op)

  The next function takes a given index and a [47mmom[0m stobj, and swaps the
  value stored in the stobj in [47mmom[0m's [47mkid2-ar-field[0m array at that
  index with the value stored in the stobj in [47mmom[0m's [47mkid1-field[0m field.

    (defun mom-swap-fields (index mom)
      (declare (xargs :stobjs mom
                      :guard (and (natp index)
                                  (< index (kid2-ar-field-length mom)))))
      (stobj-let
       ((kid1 (kid1-field mom))
        (kid2 (kid2-ar-fieldi index mom)))
       (kid1 kid2)
       (let* ((val1 (fld1 kid1))
              (val2 (fld2 kid2))
              (kid1 (update-fld1 val2 kid1))
              (kid2 (update-fld2 val1 kid2)))
         (mv kid1 kid2))
       (update-last-op 'swap mom)))

  Function [47mmom.kid1-fld1[0m stores a given value in the given [47mmom[0m's
  [47mkid1-fld1[0m field.

    (defun mom.kid1-fld1 (val mom)
      (declare (xargs :stobjs mom))
      (stobj-let
       ((kid1 (kid1-field mom)))
       (kid1)
       (update-fld1 val kid1)
       (update-last-op val mom)))

  We next combine the two functions above, according to an [47mop[0m argument,
  as indicated by the following definition.

    (defun update-mom (op mom)
      (declare (xargs :stobjs mom))
      (cond ((and (consp op)
                  (eq (car op) 'swap)
                  (natp (cdr op))
                  (< (cdr op) (kid2-ar-field-length mom)))
             (mom-swap-fields (cdr op) mom))
            (t (mom.kid1-fld1 op mom))))

  The following checker function uses a [47mstobj-let[0m form like the ones
  above, a major difference being that the producer variable is not a
  stobj, since the producer does not modify any stobjs.

    (defun check-update-mom (index val1 val2 last-op mom)
        (declare (xargs :stobjs mom
                        :mode :program
                        :guard
                        (or (null index)
                            (and (natp index)
                                 (< index (kid2-ar-field-length mom))))))
        (and (equal (last-op mom) last-op)
             (stobj-let
              ((kid1 (kid1-field mom))
               (kid2 (kid2-ar-fieldi index mom)))
              (val) ; producer variables
              (and (equal val1 (fld1 kid1))
                   (equal val2 (fld2 kid2)))
              val)))

  Now let us run our update function to populate some fields within the
  [47mmom[0m stobj.

    (let* ((mom ; set mom to (3 (x0 x1 x2 x3 x4))
             (update-mom 3 mom))
            (mom ; set mom to (x1 (x0 3 x2 x3 x4))
             (update-mom '(swap . 1) mom))
            (mom ; set mom to (7 (x0 3 x2 x3 x4))
             (update-mom 7 mom))
            (mom ; set mom to (x0 (7 3 x2 x3 x4))
             (update-mom '(swap . 0) mom))
            (mom ; set mom to (5 (7 3 x2 x3 x4))
             (update-mom 5 mom))
            (mom ; set mom to (7 (5 3 x2 x3 x4))
             (update-mom '(swap . 0) mom)))
       mom)

  Are the above values of 7, 5, and 3 as expected, with a last
  operation being a swap?  Yes!

    ACL2 !>(and (check-update-mom 0 7 5 'swap mom)
                (check-update-mom 1 7 3 'swap mom))
    T
    ACL2 !>

  Notice that above, we never tried to access two different entries of
  the array.  This can be done, but we need to bind two different
  stobjs to those fields.  Fortunately, congruent stobjs make this
  possible; see [defstobj], in particular the discussion of congruent
  stobjs.  Since we want to bind two stobjs to values in the array
  that are isomorphic to the stobj [47mkid2[0m, we introduce a stobj
  congruent to [47mkid2[0m.

    (defstobj kid2a fld2a :congruent-to kid2)

  Then we can define our swapping function as follows.  The [guard]
  proof obligation includes the requirement that the two indices be
  distinct, again to avoid an aliasing problem.

    (defun mom-swap-indices (i1 i2 mom)
      (declare (xargs :stobjs mom
                      :guard (and (natp i1)
                                  (< i1 (kid2-ar-field-length mom))
                                  (natp i2)
                                  (< i2 (kid2-ar-field-length mom))
                                  (not (equal i1 i2)))))
      (stobj-let
       ((kid2 (kid2-ar-fieldi i1 mom))
        (kid2a (kid2-ar-fieldi i2 mom)))
       (kid2 kid2a)
       (let* ((val2 (fld2 kid2))
              (val2a (fld2 kid2a))
              (kid2 (update-fld2 val2a kid2))
              (kid2a (update-fld2 val2 kid2a)))
         (mv kid2 kid2a))
       mom))

  The aforementioned community book,
  [47mbooks/system/tests/nested-stobj-tests.lisp[0m, contains a
  corresponding checker immediately following this definition.  Also
  see that book for an analogous example using a hash-table field in
  place of an array field; search there for ``hash tables with stobj
  value types''.


SECTION: Precise documentation for [47mstobj-let[0m

    General Form:
    (stobj-let
     BINDINGS
     PRODUCER-VARIABLES
     PRODUCER
     CONSUMER)

  where [47mPRODUCER-VARIABLES[0m is a non-empty true list of legal variable
  names without duplicates, [47mPRODUCER[0m and [47mCONSUMER[0m are expressions,
  and [47mBINDINGS[0m is a list subject to the following requirements.

  [47mBINDINGS[0m is a non-empty true list of tuples, each of which has the
  form [47m(VAR ACCESSOR)[0m or [47m(VAR ACCESSOR UPDATER)[0m.  Each [47mVAR[0m may occur
  only once, and to avoid aliasing, the same [47mACCESSOR[0m may not be
  bound more than once if at least one of the variables to which it's
  bound is among the [47mPRODUCER-VARIABLES[0m.  There is a stobj name, [47mST[0m,
  previously introduced by [47m[defstobj][0m (not [47m[defabsstobj][0m), such that
  each [47maccessor[0m is of the form [47m(ACC ST)[0m or [47m(ACCi I ST)[0m, with the same
  stobj name ([47mST[0m) for each binding.  Each of these accessors and (if
  supplied) updaters is a stobj accessor for the same stobj, which is
  typically [47mST[0m but may be a stobj congruent to [47mST[0m.  In the case [47m(ACC
  ST)[0m, [47mACC[0m is the accessor for a scalar (hence not array, hash-table,
  or stobj-table) field.  In the case [47m(ACC I ST)[0m, [47mACC[0m is the accessor
  for an array or hash-table field and [47mI[0m is either a symbol, a
  natural number, or a list [47m(quote C)[0m.  If [47mUPDATER[0m is supplied, then
  it is a symbol that is the name of the stobj updater for the field
  of [47mST[0m accessed by [47mACCESSOR[0m.  If [47mUPDATER[0m is not supplied, then for
  the discussion below we consider it to be, implicitly, the symbol
  in the same package as the function symbol [47mACC[0m of [47mACCESSOR[0m,
  obtained by prepending the string [47m\"UPDATE-\"[0m to the [47m[symbol-name][0m of
  [47mACC[0m unless the name of [47mACC[0m ends in [47m\"-GET\"[0m (suggesting a hash-table
  field access), in which case the implicit [47mUPDATER[0m is obtained by
  replacing the suffix [47m\"-GET\"[0m with [47m\"-PUT\"[0m.  Finally, [47mACCESSOR[0m has a
  [signature] specifying a return value that is either [47mVAR[0m or is a
  stobj that is congruent to [47mVAR[0m. (This means that only stobjs may be
  bound in these bindings.)

  If the conditions above are met, then the General Form expands to one
  of the expressions below, depending on whether the list
  [47mPRODUCER-VARIABLES[0m has one member or more than one member,
  respectively.  (But see below for extra code, denoted ``[47m<check>[0m'',
  that may be inserted if there are stobj array or hash-table
  accesses in [47mBINDINGS[0m.)  We observe the following conventions.

    * Let [47mBINDINGS'[0m be the result of dropping each updater (if any) from
      [47mBINDINGS[0m, that is, replacing each tuple [47m(VAR ACCESSOR UPDATER)[0m
      in [47mBINDINGS[0m by [47m(VAR ACCESSOR)[0m.

    * Let [47mSTOBJ-LET-BOUND-VARIABLES[0m be the list of variables [47mVAR[0m discussed
      above, that is, [47m(strip-cars BINDINGS)[0m.

    * Let [47mUPDATES[0m be the result of mapping through [47mPRODUCER-VARIABLES[0m and,
      for each variable [47mVAR[0m that has a binding [47m(VAR ACCESSOR UPDATER)[0m
      in [47mBINDINGS[0m (where [47mUPDATER[0m may be implicit, as discussed
      above), collect into [47mUPDATES[0m the tuple [47m(ST (UPDATER VAR ST))[0m.

  For [47mPRODUCER-VARIABLES[0m = [47m(PRODUCER-VAR)[0m:

    (let BINDINGS'
      (declare (ignorable . STOBJ-LET-BOUND-VARIABLES))
      (let ((PRODUCER-VAR PRODUCER))
        (let* UPDATES
          CONSUMER)))

  Otherwise:

    (let BINDINGS'
      (declare (ignorable . STOBJ-LET-BOUND-VARIABLES))
      (mv-let PRODUCER-VARS
              PRODUCER
              (let* UPDATES
                CONSUMER)))

  Moreover, ACL2 places restrictions on the resulting expression: [47mST[0m
  must not occur free in [47mPRODUCER[0m when at least one variable in
  [47mSTOBJ-LET-BOUND-VARIABLES[0m occurs in [47mPRODUCER[0m; and every variable in
  [47mSTOBJ-LET-BOUND-VARIABLES[0m must not occur free in [47mCONSUMER[0m.  If one
  of these conditions is violated, you will see an error message
  saying that ``It is forbidden to use'' the variable where it should
  not occur free.

  [47mStobj-let[0m forms can be evaluated using ordinary objects in theorem
  contexts, much as any form.  They can also, of course, appear in
  function bodies.  However, a [47mstobj-let[0m form cannot be evaluated
  directly in the top-level loop or other top-level contexts for
  execution (such as during [47m[make-event][0m expansion).

  Finally, let [47mFORM[0m denote the form displayed above (either case).
  When [47mFORM[0m appears in the body of a definition then in some cases,
  its translation into logic is an expression of the form [47m(PROG2$
  <check> FORM[0m'), where [47mFORM'[0m is the translation of [47mFORM[0m.  (See
  [term] for a discussion of translation.)  The [47m<check>[0m expression
  generates an extra [guard] proof obligation, which guarantees that
  no aliasing occurs in [47mBINDINGS[0m for two variables bound to accesses
  of the same stobj array or hash table, when at least one of the two
  variables is a producer variable.  When ACL2 determines that no
  such aliasing is possible, for example because all the array or
  hash-table accesses use distinct numeric indices or because there
  are no producer variables, then [47mFORM[0m does not undergo such
  replacement.  Warning: The use of [47m:[0m[47m[trans1][0m will not show this
  addition of a check.  But you can see it after admitting the
  definition of [47mFN[0m (perhaps using [47m[skip-proofs][0m if you are having
  difficulty admitting the definition), as follows.

    (untranslate (body 'FN nil (w state)) nil (w state))


SECTION: Using [47mstobj-let[0m with abstract stobjs

  This section shows how an abstract stobj may be considered to have
  child stobj accessors and updaters that may be used with [47mstobj-let[0m,
  in essentially in the same way that a child stobj of a concrete
  stobj may be accessed and updated with [47mstobj-let[0m.

  Below we assume familiarity with abstract stobjs; see [defabsstobj].
  We begin with a specification of child stobj accessor/updater pairs
  for abstract stobjs.  We then present an example.  Finally we
  conclude by discussing aspects of [47mstobj-let[0m specific to abstract
  stobjs.

  Child stobj accessors and updaters for abstract stobjs

  The documentation for [47m[defabsstobj][0m notes a function spec in the
  [47m:EXPORTS[0m may introduce a child stobj accessor by including the
  keyword, [47m:UPDATER[0m, whose value is the corresponding child stobj
  updater.  Here we flesh out that brief summary.

  An abstract stobj [47mst[0m is considered to have a child stobj with
  accessor [47macc[0m and updater [47mupd[0m if the [47mdefabsstobj[0m event introducing
  [47mst[0m has a pair of function specs of the following form.

    (acc :logic acc$a :exec acc$c :updater upd) ; and optionally, other keywords
    (upd :logic upd$a :exec upd$c)              ; and optionally, other keywords

  It is required that [47macc$c[0m is a child stobj accessor for the
  foundational stobj, [47mst$c[0m, of [47mst[0m.  It is also required that [47mupd$c[0m is
  the child stobj updater of [47mst$c[0m that corresponds to [47macc$c[0m.  We may
  call [47macc[0m and [47mupd[0m a child stobj accessor/updater pair for [47mst[0m.  Note
  that [47mst$c[0m may itself be an abstract stobj, in which case its
  exports [47macc$c[0m and [47mupd$c[0m must be a child stobj accessor/updater pair
  for [47mst$c[0m.

  For [47macc[0m and [47macc$c[0m as above, [47macc[0m is considered to be a scalar accessor
  if [47macc$c[0m is a scalar accessor, and otherwise [47macc[0m is an array or
  hash-table accessor (unless it is a stobj-table accessor, discussed
  elsewhere; see [stobj-table]); similarly for [47mupd[0m, which therefore
  is a scalar accessor if and only if [47macc[0m is a scalar accessor.

  A child stobj accessor/updater pair may be used in [47mstobj-let[0m in the
  same way when the parent is an abstract stobj as when the parent is
  a concrete stobj.

  Example uses of [47mstobj-let[0m for an abstract stobj

  The following basic example comes from the [community-book],
  [47mbooks/system/tests/abstract-stobj-nesting/two-usuallyequal-nums-stobj-simpler.lisp[0m,
  which is based on a book contributed by Sol Swords.  This example
  introduces an abstract stobj with child stobj fields, and uses
  [47mstobj-let[0m to read and write those fields.  For even simpler
  examples that illustrate array and hash-table fields, see community
  books [47mabsstobj-with-arrays.lisp[0m and [47mabsstobj-with-hash-tables.lisp[0m
  in the same directory as above.

  We start by introducing a concrete stobj with two child stobj fields,
  each of which represents a natural number, together with a ``valid
  bit'' that, when true, asserts the equality of those two numbers.

    (defstobj n$ (n$val :type (integer 0 *) :initially 0))
    (defstobj n$2 (n$val$c :type (integer 0 *) :initially 0)
      :congruent-to n$)
    (defstobj two-usuallyequal-nums$c
      (uenslot1$c :type n$) ; stobj slot ;
      (uenslot2$c :type n$2) ; stobj slot ;
      (uenvalid$c :type (member t nil) :initially nil))

  We represent this concrete stobj abstractly using a cons structure of
  the form [47m(valid slot1 . slot2)[0m for the valid bit and the two
  numbers.  Here is the recognizer for that abstract stobj.

    (defun-nx two-usuallyequal-nums$ap (x)

    ; A two-usuallyequal-nums contains three fields (valid slot1 . slot2).  Valid
    ; is Boolean, and slot1 and slot2 are n$ stobjs that must be equal if valid is
    ; T.

      (declare (xargs :guard t))
      (and (consp x)
           (consp (cdr x))
           (let* ((valid (car x))
                  (slot1 (cadr x))
                  (slot2 (cddr x)))
             (and (booleanp valid)
                  (n$p slot1)
                  (n$p slot2)
                  (implies valid
                           (equal slot1 slot2))))))

  The next step is to define functions in support of the abstract stobj
  that we intend to introduce.  Here is one such definition.

    (defun-nx update-uenslot1$a (n$ x)
      (declare (xargs :guard (and (two-usuallyequal-nums$ap x)
                                  (or (not (uenvalid$a x))
                                      (non-exec (equal (n$val n$)
                                                       (n$val (uenslot2$a x))))))
                      :stobjs n$))
      (cons (car x) (cons n$ (cddr x))))

  After introducing such functions we introduce our abstract stobj as
  follows (see the aforementioned book if you want details).  Notice
  the use of the [47m:updater[0m keyword, which identifies child stobj
  fields of the new abstract stobj.  Thus, [47muenslot1[0m accesses a child
  stobj field of the [47mtwo-usuallyequal-nums[0m stobj, and that field is
  updated by the specified [47m:updater[0m, [47mupdate-uenslot1[0m; similarly for
  [47muenslot2[0m and its corresponding updater, [47mupdate-uenslot2[0m.

    (defabsstobj two-usuallyequal-nums
      :exports
      ((uenslot1 :logic uenslot1$a :exec uenslot1$c :updater update-uenslot1)
       (uenslot2 :logic uenslot2$a :exec uenslot2$c :updater update-uenslot2)
       (uenvalid :logic uenvalid$a :exec uenvalid$c)
       (update-uenslot1 :logic update-uenslot1$a :exec update-uenslot1$c)
       (update-uenslot2 :logic update-uenslot2$a :exec update-uenslot2$c)
       (update-uenvalid :logic update-uenvalid$a :exec update-uenvalid$c)))

  We may now use [47mstobj-let[0m in the same way that we use it for concrete
  stobjs with child stobj fields.  That point is illustrated by the
  following definition, which accesses the numbers in the two child
  stobj fields.

    (defun fields-of-two-usuallyequal-nums (two-usuallyequal-nums)
      (declare (xargs :stobjs two-usuallyequal-nums))
      (stobj-let
    ; bindings:
       ((n$  (uenslot1 two-usuallyequal-nums))
        (n$2 (uenslot2 two-usuallyequal-nums)))
    ; producer variable:
       (n1 n2)
    ; producer:
       (mv (n$val n$) (n$val n$2))
    ; consumer:
       (list :n n1 :n2 n2 :valid (uenvalid two-usuallyequal-nums))))

  Here is what we get when we we this function before updating the
  abstract stobj.

    ACL2 !>(fields-of-two-usuallyequal-nums two-usuallyequal-nums)
    (:N 0 :N2 0 :VALID NIL)
    ACL2 !>

  We can update the abstract stobj by first setting the valid bit to
  nil, so that we can sequentially update the two child stobjs.  We
  say more about that point below.

    (defun update-two-usuallyequal-nums (n two-usuallyequal-nums)
      (declare (xargs :guard (natp n)
                      :stobjs two-usuallyequal-nums))
      (let* ((two-usuallyequal-nums (update-uenvalid nil two-usuallyequal-nums)))
        (stobj-let ((n$ (uenslot1 two-usuallyequal-nums))
                    (n$2 (uenslot2 two-usuallyequal-nums)))
                   (n$ n$2)
                   (let* ((n$ (update-n$val n n$))
                          (n$2 (update-n$val n n$2)))
                     (mv n$ n$2))
                   (update-uenvalid t two-usuallyequal-nums))))

  To see why we first update the valid bit to [47mnil[0m, consider the logical
  translation of the [47mstobj-let[0m form above.

    ACL2 !>(untranslate (body 'update-two-usuallyequal-nums nil (w state))
                        nil
                        (w state))
    (LET
     ((TWO-USUALLYEQUAL-NUMS (UPDATE-UENVALID NIL TWO-USUALLYEQUAL-NUMS)))
     (LET
      ((N$ (UENSLOT1 TWO-USUALLYEQUAL-NUMS))
       (N$2 (UENSLOT2 TWO-USUALLYEQUAL-NUMS)))
      (MV-LET
       (N$ N$2)
       (LET* ((N$ (UPDATE-N$VAL N N$))
              (N$2 (UPDATE-N$VAL N N$2)))
             (LIST N$ N$2))
       (LET*
            ((TWO-USUALLYEQUAL-NUMS (UPDATE-UENSLOT1 N$ TWO-USUALLYEQUAL-NUMS))
             (TWO-USUALLYEQUAL-NUMS (UPDATE-UENSLOT2 N$2 TWO-USUALLYEQUAL-NUMS)))
            (UPDATE-UENVALID T TWO-USUALLYEQUAL-NUMS)))))
    ACL2 !>

  We can see that if the valid bit were [47mt[0m before doing any updates,
  then the guard proof obligation would fail for the first child
  stobj update, made with [47mupdate-uenslot1[0m (as defined above; see its
  guard).

  The update works, as shown in the log below.

    ACL2 !>(update-two-usuallyequal-nums 17 two-usuallyequal-nums)
    <two-usuallyequal-nums>
    ACL2 !>(fields-of-two-usuallyequal-nums two-usuallyequal-nums)
    (:N 17 :N2 17 :VALID T)
    ACL2 !>

  Aspects of [47mstobj-let[0m specific to abstract stobjs

  As suggested by the example above, [47mstobj-let[0m operates about the same
  whether the parent stobj is a concrete stobj or an abstract stobj.
  In this section we discuss some differences.

  One difference is that the only field accessors in the [47mBINDINGS[0m are
  child stobj field accessors.  After all those are the only exported
  functions for an abstract stobj that may be considered to
  correspond to fields..

  Another difference is in the aliasing checks.  Recall that for an
  abstract stobj [47mst[0m, each child stobj accessor has an [47m:EXEC[0m function
  that is a child stobj accessor of the foundational stobj, [47mst$c[0m, for
  [47mst[0m.  If [47mst$c[0m is itself an abstract stobj then the [47m:EXEC[0m function
  for [47mst$c[0m is a child stobj accessor for the foundation of [47mst$c[0m; and
  so on.  At the end of this chain we have a child stobj accessor for
  a concrete stobj, which we may call the underlying concrete child
  stobj accessor.  The aliasing checks are actually done with respect
  to the underlying concrete child stobj accessors that correspond to
  the accessors in the [47mBINDINGS[0m.  After all, under the hood those
  concrete stobj functions are the ones that are actually executed on
  the ``live'' stobj.

  Another aspect of [47mstobj-let[0m specific to abstract stobjs is how aborts
  are handled.  If an abort occurs in the middle of a [47mstobj-let[0m that
  updates child stobjs, when the parent stobj is an abstract stobj,
  you may be put into an illegal state, with instructions for how to
  continue at your own risk.  See [illegal-state].


Subtopics

  [Stobj-table]
      A [stobj] field mapping stobj names to stobjs")
 (NEVER-MEMOIZE
  (MEMOIZE)
  "Mark a function as unsafe to memoize.

  Logically, this function just returns [47mnil[0m.  But execution of
  [47m(never-memoize fn)[0m records that [47mfn[0m must never be memoized, so that
  any attempt to memoize [47mfn[0m will fail.

  Any function can be marked as unsafe to memoize; in fact, [47mfn[0m need not
  even be defined at the time it is marked.

  This is useful for prohibiting the memoization of functions that are
  known to involve destructive functions like [47mnreverse[0m.")
 (NEWLINE
  (IO PRINC$)
  "Print a newline to a given output channel

  This function is simply a wrapper around a call to [princ$] for the
  purpose of printing the ASCII character 0x0A, also known as a
  newline or line feed.

  [31;1mFunction: [0m<newline>

    (defun newline (channel state)
     (declare
          (xargs :guard (and (symbolp channel)
                             (open-output-channel-p channel
                                                    :character state))))
     (princ$ #\\Newline channel state))")
 (NFIX
  (NUMBERS ACL2-BUILT-INS)
  "Coerce to a natural number

  [47mNfix[0m simply returns any natural number argument unchanged, returning
  [47m0[0m on an argument that is not a natural number.  Also see [ifix],
  see [rfix], see [realfix], and see [fix] for analogous functions
  that coerce to an integer, a rational number, a real, and a number,
  respectively.

  [47mNfix[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<nfix>

    (defun nfix (x)
      (declare (xargs :guard t))
      (if (and (integerp x) (>= x 0)) x 0))")
 (NFIX-LIST (POINTERS) "See [l<].")
 (NIL-GOAL
  (DEBUGGING)
  "How to proceed when the prover generates a goal of [47mNIL[0m

  Failed proofs generally conclude with lists of key checkpoints.  (See
  [set-gag-mode] or [introduction-to-key-checkpoints] for an
  introduction to the notion of ``key checkpoint''.)  These lists may
  sometimes be annotated as follows.

    [NOTE: A goal of NIL was generated.  See :DOC nil-goal.]

  This [documentation] topic gives some ideas about how to think about
  the situation described by that message, that is: some goal has
  reduced to [47mNIL[0m.

  Suppose that you see the above NOTE.  If you look at the proof log,
  you will see a message saying that a goal of [47mNIL[0m has been
  generated.  This may indicate that the original goal is not a
  theorem, since most of the prover's activity is typically to
  replace a goal by an equivalent conjunction of its child subgoals.
  However, if some ancestor of the [47mNIL[0m goal has undergone a process
  other than simplification or destructor elimination --- that is,
  fertilization (heuristic use of equalities), generalization, or
  elimination of irrelevance --- then it is quite possible that the
  prover got to the [47mNIL[0m goal by replacing a goal by a stronger (and
  perhaps false) conjunction of child subgoals.

  Let's dig a bit deeper by considering two cases for production of a
  [47mNIL[0m subgoal.  First consider the case that the subgoal is a key
  checkpoint at the top level or under a top-level induction --- that
  is, a key checkpoint listed in the proof [summary].  In that case,
  the original conjecture is very likely not a theorem.  Otherwise,
  if you are using [gag-mode] (which is the case by default), then
  you may need to issue the command [47m:[0m[47m[pso][0m (``Print Saved Output'')
  to see whether the goal was strengthened from one that was
  originally a theorem; but here is what may be a better idea.
  Instead, it may be best to focus on the key checkpoints printed in
  the summary to see if they suggest useful [rewrite] rules to prove.

  If some [47mNIL[0m subgoal is under a key checkpoint at the top level or
  under a top-level induction, then as discussed above, the original
  conjecture is probably not a theorem.  Therefore, in that case,
  ACL2 always prints a [47mNIL[0m subgoal first in a list of checkpoints
  printed in the [summary], so that a [47mNIL[0m subgoal comes quickly to
  your attention.")
 (NINTH
  (NTH ACL2-BUILT-INS)
  "Ninth member of the list

  See any Common Lisp documentation for details.")
 (NO-DUPLICATESP
  (LISTS ACL2-BUILT-INS)
  "Check for duplicates in a list

    General Forms:
    (no-duplicatesp x)
    (no-duplicatesp x :test 'eql)   ; same as above (eql as equality test)
    (no-duplicatesp x :test 'eq)    ; same, but eq is equality test
    (no-duplicatesp x :test 'equal) ; same, but equal is equality test

  [47m(no-duplicatesp lst)[0m is true if and only if no member of [47mlst[0m occurs
  twice in [47mlst[0m.  The optional keyword, [47m:TEST[0m, has no effect
  logically, but provides the test (default [47m[eql][0m) used for comparing
  elements of [47mlst[0m.

  The [guard] for a call of [47mno-duplicatesp[0m depends on the test.  In all
  cases, the argument must satisfy [47m[true-listp][0m.  If the test is
  [47m[eql][0m, then the argument must satisfy [47m[eqlable-listp][0m.  If the test
  is [47m[eq][0m, then the argument must satisfy [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mno-duplicatesp[0m and its variants:

      [47m(no-duplicatesp-eq x lst)[0m is equivalent to [47m(no-duplicatesp x lst
      :test 'eq)[0m;

      [47m(no-duplicatesp-equal x lst)[0m is equivalent to [47m(no-duplicatesp x lst
      :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mno-duplicatesp-equal[0m.

  [31;1mFunction: [0m<no-duplicatesp-equal>

    (defun no-duplicatesp-equal (l)
      (declare (xargs :guard (true-listp l)))
      (cond ((endp l) t)
            ((member-equal (car l) (cdr l)) nil)
            (t (no-duplicatesp-equal (cdr l)))))")
 (NO-DUPLICATESP-EQ (POINTERS)
                    "See [no-duplicatesp].")
 (NO-DUPLICATESP-EQUAL (POINTERS)
                       "See [no-duplicatesp].")
 (NO-OP (POINTERS)
        "See [hints] for information about the keyword [47m:no-op[0m.")
 (NO-THANKS
      (POINTERS)
      "See [hints] for information about the keyword [47m:no-thanks[0m.")
 (NON-EXEC
  (GUARD ACL2-BUILT-INS)
  "Mark code as non-executable

  [47mNon-exec[0m is a macro such that logically, [47m(non-exec x)[0m is equal to [47mx[0m.
  However, the argument to a call of [47mnon-exec[0m need not obey the usual
  syntactic restrictions for executable code, and indeed, evaluation
  of a call of [47mnon-exec[0m will result in an error.  Moreover, for any
  form occurring in the body of a function (see [defun]) that is a
  call of [47mnon-exec[0m, no guard proof obligations are generated for that
  form.

  The following example, although rather contrived, illustrates the use
  of [47mnon-exec[0m.  One can imagine a less contrived example that
  efficiently computes return values for a small number of fixed
  inputs and, for other inputs, returns something logically
  ``consistent'' with those return values.

    (defun double (x)
      (case x
        (1 2)
        (2 4)
        (3 6)
        (otherwise (non-exec (* 2 x)))))

  We can prove that [47mdouble[0m is compliant with Common Lisp (see [guard])
  and that it always computes [47m(* 2 x)[0m.

    (verify-guards double)
    (thm (equal (double x) (* 2 x)))

  We can evaluate double on the specified arguments.  But a call of
  [47mnon-exec[0m results in an error message that reports the form that was
  supplied to [47mnon-exec[0m.

    ACL2 !>(double 3)
    6
    ACL2 !>(double 10)

    ACL2 Error in TOP-LEVEL:  ACL2 has been instructed to cause an error
    because of an attempt to evaluate the following form (see :DOC non-
    exec):

      (* 2 X).

    To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

    ACL2 !>

  During proofs, the error is silent; it is ``caught'' by the proof
  mechanism and generally results in the introduction of a call of
  [47m[hide][0m during a proof.

  Also see [defun-nx] for a utility that makes every call of a function
  non-executable, rather than a specified form.  The following
  examples contrast [47mnon-exec[0m with [47m[defun-nx][0m, in particular
  illustrating the role of [47m[non-exec][0m in avoiding guard proof
  obligations.

    ; Guard verification fails:
    (defun-nx f1 (x)
      (declare (xargs :guard t))
      (car x))

    ; Guard verification succeeds after changing the guard above:
    (defun-nx f1 (x)
      (declare (xargs :guard (consp x)))
      (car x))

    ; Guard verification succeeds:
    (defun f2 (x)
      (declare (xargs :guard t))
      (non-exec (car x)))

    ; Evaluating (g1) prints \"Hello\" before signaling an error.
    (defun g1 ()
      (f1 (cw \"Hello\")))

    ; Evaluating (g2) does not print before signaling an error.
    (defun g2 ()
      (non-exec (cw \"Hello\")))

    ; Evaluating (h1) gives a guard violation for taking reciprocal of 0.
    (defun h1 ()
      (f1 (/ 1 0)))

    ; Evaluating (h2) does not take a reciprocal, hence there is no guard
    ; violation for that; we just get the error expected from using non-exec.
    (defun h2 ()
      (non-exec (/ 0)))")
 (NON-EXECUTABLE
   (POINTERS)
   "See [xargs] for information about the keyword [47m:non-executable[0m.")
 (NON-LINEAR-ARITHMETIC
  (LINEAR)
  "Non-linear Arithmetic

  This documentation topic is divided into two parts.  We first discuss
  the practical aspect of how to use the non-linear arithmetic
  extension to ACL2, and then the theory behind it.  We assume that
  the reader is familiar with the material in [47m[linear-arithmetic][0m and
  that on [47m:[0m[47m[linear][0m rules.

  We begin our discussion of how to use non-linear arithmetic with a
  simple example.  Assume that we wish to prove:

    (thm
     (implies (and (rationalp x)
                   (rationalp y)
                   (rationalp z)
                   (< 0 y)
                   (< x (* y z)))
              (< (floor x y) z)))

  Note that [47m(floor x y) <= (/ x y)[0m.  Note also that if we divide both
  sides of [47mx < (* y z)[0m by [47my[0m, since [47m0 < y[0m, we obtain [47m(/ x y) < z[0m.  By
  chaining these two inequalities together, we get the inequality we
  desired to prove.

  We now proceed with our example session:

    (skip-proofs
     (progn

    ; Since the truth of this theorem depends on the linear properties
    ; of floor, we will need the linear lemma:

       (defthm floor-bounds-1
           (implies (and (rationalp x)
                         (rationalp y))
                    (and (< (+ (/ x y) -1)
                            (floor x y))
                         (<= (floor x y)
                             (/ x y))))
           :rule-classes ((:linear :trigger-terms ((floor x y)))))

    ; We now disable floor, so that the linear lemma will be used.

       (in-theory (disable floor))

    ; We create five rewrite rules which we will use during non-linear
    ; arithmetic.  The necessity for these is due to one of the differences in
    ; ACL2's behavior when non-linear arithmetic is turned on.  Although
    ; the conclusions of linear lemmas have always been rewritten before
    ; they are used, now, when non-linear arithmetic is turned on, the
    ; conclusions are rewritten under a different theory than under ``normal''
    ; rewriting.  This theory is also used in other, similar, circumstances
    ; described below.

       (defthm |arith (* -1 x)|
           (equal (* -1 x)
                  (- x)))

       (defthm |arith (* 1 x)|
           (equal (* 1 x)
                  (fix x)))

       (defthm |arith (* x (/ x) y)|
           (equal (* x (/ x) y)
                  (if (equal (fix x) 0)
                      0
                      (fix y))))

       (defthm |arith (* y x)|
           (equal (* y x)
                  (* x y)))

       (defthm |arith (fix x)|
           (implies (acl2-numberp x)
                    (equal (fix x)
                           x))))
     )  ; End skip-proofs.

    ; We disable the above rewrite rules from normal use.

    (in-theory (disable |arith (* -1 x)|
                        |arith (* 1 x)|
                        |arith (* x (/ x) y)|
                        |arith (* y x)|
                        |arith (fix x)|))

    ; We create an arithmetic-theory.  Note that we must give a quoted
    ; constant for the theory --- none of the normal [47m[theory-functions][0m
    ; are applicable to in-arithmetic-theory.

    (in-arithmetic-theory '(|arith (* -1 x)|
                            |arith (* 1 x)|
                            |arith (* x (/ x) y)|
                            |arith (* y x)|
                            |arith (fix x)|))

    ; We turn non-linear arithmetic on.

    (set-non-linearp t)

    ; We can now go ahead and prove our theorem.

    (thm
     (implies (and (rationalp x)
                   (rationalp y)
                   (rationalp z)
                   (< 0 y)
                   (< x (* y z)))
              (< (floor x y) z)))

  The above example illustrates the two practical requirements for
  using non-linear arithmetic in ACL2.  First, one must set up an
  arithmetic-theory.  Usually, one would not set up an
  arithmetic-theory on one's own but would instead load a library
  book or books which do so.  Second, one must turn the non-linear
  arithmetic extension on.  This one must do explicitly --- no book
  can do this for you.

  For a brief discussion of why this is so, even though
  [47m(set-non-linearp t)[0m is an embeddable event, see
  [ACL2-defaults-table] (in particular, the final paragraph).  (Note
  that [47m(set-non-linearp t)[0m modifies the [47macl2-defaults-table[0m.)  Also
  see [set-non-linearp], see [embedded-event-form], and see [events].

  You can also enable non-linear arithmetic with the hint [47m:nonlinearp
  t[0m.  See [hints].  We, in fact, recommend the use of a hint which
  will enable nonlinear arithmetic only when the goal has stabilized
  under rewriting.  Using [47m[default-hints][0m can make this easier.

    (defun nonlinearp-default-hint (stable-under-simplificationp hist pspv)
      (cond (stable-under-simplificationp
             (if (not (access rewrite-constant
                              (access prove-spec-var pspv :rewrite-constant)
                              :nonlinearp))
                 '(:computed-hint-replacement t :nonlinearp t)
               nil))
            ((access rewrite-constant
                     (access prove-spec-var pspv :rewrite-constant)
                     :nonlinearp)
             (if (not (equal (caar hist) 'SETTLED-DOWN-CLAUSE))
                 '(:computed-hint-replacement t :nonlinearp nil)
               nil))
            (t nil)))

    (set-default-hints '((nonlinearp-default-hint stable-under-simplificationp
                                                  hist pspv)))

  This has proven to be a helpful strategy which allows faster proof
  times.

  We now proceed to briefly describe the theory behind the non-linear
  extension to ACL2.  In [47m[linear-arithmetic][0m it was stated that,
  ``[L]inear polynomial inequalities can be combined by
  cross-multiplication and addition to permit the deduction of a
  third inequality....'' That is, if

    0 < poly1,
    0 < poly2,

  and [47mc[0m and [47md[0m are positive rational constants, then

    0 < c*poly1 + d*poly2.

  Similarly, given the above,

    0 < poly1*poly2.

  In the linear arithmetic case, we are taking advantage of the facts
  that multiplication by a positive rational constant does not change
  the sign of a polynomial and that the sum of two positive
  polynomials is itself positive.  In the non-linear arithmetic case,
  we are using the fact that the product of two positive polynomials
  is itself positive.

  For example, suppose we have the three assumptions:

    p1:  3*x*y + 7*a < 4
    p2:            3 < 2*x  or p2': 0 < -3 + 2*x
    p3:            1 < y    or p3': 0 < -1 + y,

  and we wish to prove that [47ma < 0[0m.  As described elsewhere (see
  [linear-arithmetic]), we proceed by assuming the negation of our
  goal:

    p4:            0 <= a,

  and looking for a contradiction.

  There are no cancellations which can be performed by linear
  arithmetic in the above situation.  (Recall that two polynomials
  are canceled against each other only when they have the same
  largest unknown.)  However, [47mp1[0m has a product as its largest
  unknown, and for each of the factors of that product there is a
  poly that has that factor as a largest unknown.  When non-linear
  arithmetic is enabled, ACL2 will therefore multiply [47mp1'[0m and [47mp2'[0m
  obtaining

    p5:            0 < 3 + -2*x + -3*y + 2*x*y.

  The addition of this polynomial will allow cancellation to continue
  and, in this case, we will prove our goal.  Thus, just as ACL2 adds
  two polynomials together when they have the same largest unknown of
  opposite signs in order to create a new ``smaller'' polynomial; so
  ACL2 multiplies polynomials together when the product of their
  largest unknowns is itself the largest unknown of another
  polynomial.  As the use of [47m:[0m[47m[linear][0m lemmas to further seed the
  arithmetic database may allow cancellation to proceed, so may the
  use of non-linear arithmetic.

  This multiplication of polynomials is the motivation for an
  arithmetic-theory distinct from the normal one.  Because this may
  be done so often, and because the individual factors have
  presumably already been rewritten, it is important that this be
  done in an efficient way.  The use of a small, specialized, theory
  helps avoid the repeated application of rewrite rules to already
  stabilized terms.


Subtopics

  [Set-non-linearp]
      To turn on or off non-linear arithmetic reasoning")
 (NONLINEARP
      (POINTERS)
      "See [hints] for information about the keyword [47m:nonlinearp[0m.")
 (NONNEGATIVE-INTEGER-QUOTIENT
  (NUMBERS ACL2-BUILT-INS)
  "Natural number division function

    Example Forms:
    (nonnegative-integer-quotient 14 3) ; equals 4
    (nonnegative-integer-quotient 15 3) ; equals 5

  [47m(nonnegative-integer-quotient i j)[0m returns the integer quotient of
  the integers [47mi[0m and (non-zero) [47mj[0m, i.e., the largest [47mk[0m such that [47m(* j
  k)[0m is less than or equal to [47mi[0m.  Also see [floor], see [ceiling] and
  see [truncate], which are derived from this function and apply to
  rational numbers.

  The [guard] of [47m(nonnegative-integer-quotient i j)[0m requires that [47mi[0m is
  a nonnegative integer and [47mj[0m is a positive integer.

  [31;1mFunction: [0m<nonnegative-integer-quotient>

    (defun nonnegative-integer-quotient (i j)
      (declare (xargs :guard (and (integerp i)
                                  (not (< i 0))
                                  (integerp j)
                                  (< 0 j))))
      (if (or (= (nfix j) 0) (< (ifix i) j))
          0
        (+ 1
           (nonnegative-integer-quotient (- i j)
                                         j))))")
 (NONTAUTOLOGICAL_SUBGOALS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Prover output omits some details

  The theorem prover's proof output is intended to suggest an outline
  of the reasoning process employed by its proof engine, which is
  virtually always more than is necessary for the ACL2 user.  In
  particular, the output often omits subgoals that are sufficiently
  trivial, including tautologies.")
 (NORMALIZATION (POINTERS)
                "See [normalize].")
 (NORMALIZE
  (XARGS)
  "Storing simplified [definition] bodies and [guard]s

  By default, when you submit a [47m[defun][0m form, the body is simplified
  for certain later uses.  This simplification is sometimes called
  ``normalization''; the ACL2 system function that accomplishes this
  task is [47mnormalize[0m.  Consider the following examples, where we make
  two definitions and then show their bodies using [47m:[0m[47m[pf][0m..

    ACL2 !>(defun f1 (x y)
             (cons (implies x y) (integerp 3)))
    [.. output omitted ..]
     F1
    ACL2 !>(defun f2 (x y)
             (declare (xargs :normalize nil))
             (cons (implies x y) (integerp 3)))
    [.. output omitted ..]
     F2
    ACL2 !>:pf f1
    (EQUAL (F1 X Y) (IF X (IF Y '(T . T) '(NIL . T)) '(T . T)))
    ACL2 !>:pf f2
    (EQUAL (F2 X Y) (CONS (IMPLIES X Y) (INTEGERP 3)))
    ACL2 !>

  We see that the body of [47mf1[0m has undergone the default simplification
  (with [47mnormalize[0m), while the body of [47mf2[0m has not because of the
  [47m[xargs][0m in its [47mdefun[0m form.

  The example above illustrates that normalization consists of the
  following three parts:

    * propagation upward of [47mif[0m tests;

    * potential simplification with type reasoning (see [TYPE-REASONING]);
      and

    * the expansion of calls of a few built-in functions like [47m[implies][0m
      (the full list is the value of the constant,
      [47m*expandable-boot-strap-non-rec-fns*[0m).

  We have seen an example where type reasoning (see [TYPE-REASONING])
  can be expensive.  So when ACL2 normalizes [definition] bodies and
  [guard]s, it establishes a [backchain-limit] for [type-set]
  reasoning of 1, unless that limit is currently 0.  (The global
  default is to have no limit.)

  Also see the [community-books] utility [47m[install-not-normalized][0m.")
 (NORMED
  (HONS)
  "Normed objects are ACL2 Objects that are \"canonical\" or \"unique\" in a
  certain sense.

  In Common Lisp, we can tell whether an ACL2 object is [31;1mnormed[0m or not,
  but there is no way for an ordinary ACL2 function to see whether an
  object is normed.  Hence, whether or not an object is normed is an
  implementation-level concept.

  The fundamental property of normed objects is that if A and B are
  both normed, then [47m(equal A B)[0m holds if and only if [47m(eql A B)[0m holds.
  For strings and conses, [47m(eql A B)[0m holds only when [47m(eq A B)[0m, so any
  normed conses or strings are [47m[equal][0m precisely when they are [47m[eq][0m.
  The potential benefits of having normed objects include:
  constant-time equality comparisons, reduced memory usage, fast
  association lists, and function memoization.

  Note that in our implementation, all symbols, characters, and numbers
  are automatically normed, and whenever a cons is normed its car and
  cdr must also be normed.

  The Meaning of Normed in Common Lisp.

  Recall that the ACL2 Objects are certain \"good\" Common Lisp symbols,
  characters, strings, and numbers, and the conses which can be
  recursively formed from these good atoms.

  Not all properties of these objects are visible in the ACL2 logic.
  An example of an invisible property is the pointer identity of an
  object.  For example, suppose we write the following.

    (defconst *x* (cons 1 2))
    (defconst *y* (cons 1 2))

  In Common Lisp, [47m[cons][0m is guaranteed to provide a new pair that is
  distinct from any previously created pair, so we know that *x* and
  *y* will be distinct objects and we will be able to tell them apart
  from one another using [47meq[0m.  But this difference is not visible in
  the ACL2 logic, and no ACL2 function can tell *x* apart from *y*.

  The normed-ness of an object is a similarly invisible property.  In
  Common Lisp, invisible to ACL2, we maintain a data structure called
  a \"Hons Space\" that records which objects are normed.  So, being
  normed is not an intrinsic property of an object, but instead is
  determined by whether the object is mentioned in this Hons Space.

  Notes about Garbage Collection.

  The Hons Space includes tables with pointers to every normed cons and
  string.  One consequence of this is that normed objects cannot be
  reclaimed by Lisp's ordinary garbage collector, even after they
  have become unreachable from the perspective of an ACL2 program.

  For CCL and GCL users only, [47m[hons-wash][0m is a special kind of garbage
  collection that allows normed conses to be reclaimed.  For other
  Lisps, the only option is to occasionally, manually clear out these
  Hons Space tables with [47m[hons-clear][0m.")
 (NOT
  (BASICS ACL2-BUILT-INS)
  "Logical negation

  [47mNot[0m is the ACL2 negation function.  The negation of [47mnil[0m is [47mt[0m and the
  negation of anything else is [47mnil[0m.

  [47mNot[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<not>

    (defun not (p)
      (declare (xargs :guard t))
      (if p nil t))")
 (NOTE-1-1
  (RELEASE-NOTES)
  "Acl2 Version 1.1 Notes

  The new features are extensively documented.  The relevant topics
  are:

  It is especially important to read all of the [documentation] for
  [books] before trying to use books.  However, the new [47m:more[0m keyword
  command is so handy for reading long [documentation] strings that
  we recommend you start with [47m:[0m[47m[doc][0m more if reading at the terminal.
  Some documentation has been written for [guard]s which you might
  find interesting.")
 (NOTE-1-2
  (RELEASE-NOTES)
  "Acl2 Version 1.2 Notes

  Hacker mode has been eliminated and [programming] mode has been
  added.  [Programming] mode is unsound but does syntax checking and
  permits redefinitions of names.  See [47m:[0m[47m[doc][0m [47mload-mode[0m and [47m:[0m[47m[doc][0m
  [47mg-mode[0m.

  The arguments to [47m[ld][0m have changed.  [47m[Ld][0m is now much more
  sophisticated.  See [ld].

  For those occasions on which you wish to look at a large list
  structure that you are afraid to print, try [47m(walkabout x state)[0m,
  where [47mx[0m is an Acl2 expression that evaluates to the structure in
  question.  I am afraid there is no [documentation] yet, but it is
  similar in spirit to the Interlisp structure editor.  You are
  standing on an object and commands move you around in it.  E.g., 1
  moves you to its first element, 2 to its second, etc.; 0 moves you
  up to its parent; [47mnx[0m and [47mbk[0m move you to its next sibling and
  previous sibling; [47mpp[0m prettyprints it; [47m[q][0m exits returning [47mnil[0m; [47m[=][0m
  exits returning the thing you're standing on; [47m(= symb)[0m assigns the
  thing you're standing on to the [state] global variable [47msymb[0m.

  Several new [hints] have been implemented, including [47m:by[0m and [47m:do-not[0m.
  The old [47m:do-not-generalize[0m has been scrapped in favor of such new
  [hints] as [47m:do-not[0m [47m(generalize elim)[0m.  [47m:By[0m lets you say ``this goal
  is subsumed by'' a given lemma instance.  The [47m:by[0m hint also lets
  you say ``this goal can't be proved yet but skip it and see how the
  rest of the proof goes.'' See [hints].")
 (NOTE-1-3
  (RELEASE-NOTES)
  "Acl2 Version 1.3 Notes

  [Programming] mode has been eliminated.  Instead, all functions have
  a ``color'' which indicates what can be done with the function.
  For example, [47m:red[0m functions can be executed but have no axioms
  describing them.  Thus, [47m:red[0m functions can be introduced after
  passing a simple syntactic check and they can be redefined without
  undoing.  But nothing of consequence can be proved about them.  At
  the other extreme are [47m:gold[0m functions which can be executed and
  which also have passed both the termination and the [guard]
  verification proofs.  The color of a function can be specified with
  the new [47m[xargs][0m keyword, [47m:color[0m, which, if omitted defaults to the
  global setting of [47mld-color[0m.  [47mLd-color[0m replaces [47mload-mode[0m.  Setting
  [47mld-color[0m to [47m:red[0m causes behavior similar to the old [47m:g-mode[0m.
  Setting [47mld-color[0m to [47m:gold[0m causes behavior similar to the old
  [47m:v-mode[0m.  It is possible to prototype your system in [47m:red[0m and then
  convert [47m:red[0m functions to [47m:[0m[47mblue[0m individually by calling
  [47m[verify-termination][0m on them.  They can then be converted to [47m:gold[0m
  with [47m[verify-guards][0m.  This allows us to undertake to verify the
  termination and [guard]s of system functions.  See [47m:[0m[47m[doc][0m color for
  an introduction to the use of colors.

  Type prescription rules have been added.  Recall that in Nqthm, some
  [47m[rewrite][0m rules were actually stored as ``[type-prescription]s.''
  Such rules allow the user to inform Nqthm's primitive type
  mechanism as to the kinds of shells returned by a function.
  Earlier versions of Acl2 did not have an analogous kind of rule
  because Acl2's type mechanism is complicated by [guard]s.  Version
  1.3 supports [47m[type-prescription][0m rules.  See [type-prescription].

  Three more new [rule-classes] implement congruence-based rewriting.
  It is possible to identify a binary relation as an equivalence
  relation (see [equivalence]), to show that one equivalence relation
  refines another (see [refinement]) and to show that a given
  equivalence relation is maintained when rewriting a given function
  call, e.g., [47m(fn ...xk...)[0m, by maintaining another equivalence
  relation while rewriting the [47mk[0mth argument (see [congruence]).  If [47mr[0m
  has been shown to be an [equivalence] relation and then [47m(implies
  hyps (r (foo x) (bar x)))[0m is proved as a [47m:[0m[47m[rewrite][0m rule, then
  instances of [47m(foo x)[0m will be replaced by corresponding instances of
  [47m(bar x)[0m provided the instance occurs in a slot where the
  maintenance of [47mr-equivalence[0m is known to be sufficient and [47mhyps[0m can
  be established as usual.

  In Version 1.2, [rule-classes] were simple keywords, e.g., [47m:[0m[47m[rewrite][0m
  or [47m:[0m[47m[elim][0m.  In Version 1.3, [rule-classes] have been elaborated to
  allow you to specify how the theorem ought to be used as a rule.
  That is, the new [rule-classes] allows you to separate the
  mathematical statement of the formula from its interpretation as a
  rule.  See [rule-classes].

  Rules used to be named by symbols, e.g., [47m[car][0m and [47mcar-cons[0m were the
  names of rules.  Unfortunately, this was ambiguous because there
  are three rules associated with function symbols: the symbolic
  definition, the executable-counterpart, and the
  [type-prescription]; many different rules might be associated with
  theorems, depending on the rule classes.  In Version 1.3 rules are
  named by ``[rune]s'' (which is just short hand for ``rule names'').
  Example [rune]s are [47m(:definition car)[0m, [47m(:executable-counterpart
  car)[0m, and [47m(:type-prescription car . 1)[0m.  Every rule added by an
  event has a different name and you can [enable] and [disable] them
  independently.  See [rune] and see [theories].

  The identity function [47m[force][0m, of one argument, has been added and
  given a special interpretation by the functions responsible for
  establishing hypotheses in backchaining: When the system fails to
  establish some hypothesis of the form [47m(force term)[0m, it simply
  assumes it is true and goes on, delaying until later the
  establishment of term.  In particular, pushes a new subgoal to
  prove term in the current context.  When that subgoal is attacked,
  all of the resources of the theorem prover, not just rewriting, are
  brought to bear.  Thus, for example, if you wish to prove the rule
  [47m(implies (good-statep s) (equal (exec s n) s'))[0m and it is your
  expectation that every time [47mexec[0m appears its first argument is a
  [47mgood-statep[0m then you might write the rule as [47m(implies (force
  (good-statep s)) (equal (exec s n) s'))[0m.  This rule is essentially
  an unconditional rewrite of [47m(exec s n)[0m to [47ms'[0m that spawns the new
  goal [47m(good-statep s)[0m.  See [force].  Because you can now specify
  independently how a theorem is used as a rule, you need not write
  the [47m[force][0m in the actual theorem proved.  See [rule-classes].

  Version 1.3 supports a facility similar to Nqthm's [47m[break-lemma][0m.
  See [break-rewrite].  You can install ``[monitor]s'' on [rune]s
  that will cause interactive breaks under certain conditions.

  Acl2 also provides ``[wormhole]s'' which allow you to write functions
  that cause interaction with the user but which do not require that
  you have access to [47m[state][0m.  See [wormhole].

  The rewriter now automatically backchains to stronger recognizers.
  There is no user hook to this feature but it may simplify some
  proofs with which older versions of Acl2 had trouble.  For example,
  if the rewriter is trying to prove [47m(rationalp (foo a b c))[0m it is
  now smart enough to try lemmas that match with [47m(integerp (foo a b
  c))[0m.")
 (NOTE-1-4
  (RELEASE-NOTES)
  "Acl2 Version 1.4 Notes

  Once again [47m[ld][0m only takes one required argument, as the [47mbind-flg[0m has
  been deleted.

  Three commands have been added in the spirit of [47m:[0m[47m[pe][0m.  [47m:[0m[47m[Pe!][0m is
  similar to [47m:[0m[47m[pe][0m but it prints all [events] with the given name,
  rather than just the most recent.  The command [47m:[0m[47m[pf][0m prints the
  corollary formula corresponding to a name or [rune].  The command
  [47m:[0m[47m[pl][0m (print lemmas) prints rules whose top function symbol is the
  given name.  See [pe!], see [pf], and see [pl].

  Book naming conventions have been changed somewhat.  The
  once-required [47m.lisp[0m extension is now prohibited!  Directories are
  supported, including a notion of ``connected book directory''.  See
  [book-name].  Also, the second argument of [47m[certify-book][0m is now
  optional, defaulting to [47m0[0m.

  [Compilation] is now supported inside the Acl2 loop.  See [comp] and
  see [set-compile-fns].

  The default color is now part of the Acl2 [world]; see [47m:[0m[47m[doc][0m
  [47mdefault-color[0m.  [47mLd-color[0m is no longer an [47m[ld][0m special.  Instead,
  colors are [events]; see the documentation for [47mred[0m, [47mpink[0m, [47mblue[0m, and
  [47mgold[0m.

  A [table] exists for controlling whether Acl2 prints comments when it
  [force]s hypotheses of rules; see [47m:[0m[47m[doc][0m [47mforce-table[0m.  Also, it is
  now possible to turn off the forcing of assumptions by disabling
  the definition of [force]; see [force].

  The event [47mdefconstant[0m is no longer supported, but a very similar
  event, [47m[defconst][0m, has been provided in its place.  See [defconst].

  The event for defining [congruence] relations is now [47m[defcong][0m
  (formerly, [47mdefcon[0m).

  Patterns are now allowed in [47m:expand[0m [hints].  See the documentation
  for [47m:expand[0m inside the documentation for [hints].

  We have improved the way we report rules used by the simplifier.  All
  [rune]s of the same type are reported together in the running
  commentary associated with each goal, so that for example,
  executable-counterparts are listed separately from definitions, and
  rewrite rules are listed separately from [linear] rules.  The
  preprocessor now mentions ``simple'' rules; see [simple].

  The mechanism for printing warning messages for new rewrite rules,
  related to subsumption, now avoids worrying about nonrecursive
  function symbols when those symbols are [disable]d.  These messages
  have also been eliminated for the case where the old rule is a
  [47m:[0m[47m[definition][0m rule.

  Backquote has been modified so that it can usually provide
  predictable results when used on the left side of a rewrite rule.

  Time statistics are now printed even when an event fails.

  The Acl2 trace package has been modified so that it prints using the
  values of the Lisp globals [47m*print-level*[0m and [47m*print-length*[0m
  (respectively).

  [Table] has been modified so that the [47m:clear[0m option lets you replace
  the entire [table] with one that satisfies the [47mval[0m and key guards
  (if any); see [table].

  We have relaxed the translation rules for [47m:measure[0m [hints] to
  [47m[defun][0m, so that the same rules apply to these terms that apply to
  terms in [47m[defthm][0m [events].  In particular, in [47m:measure[0m [hints]
  [47m[mv][0m is treated just like [47m[list][0m, and [47m[state][0m receives no special
  handling.

  The [loop-stopper] test has been relaxed.  The old test required that
  every new argument be strictly less than the corresponding old
  argument in a certain [term-order].  The new test uses a
  lexicographic order on term lists instead.  For example, consider
  the following rewrite rule.

    (equal
     (variable-update var1
                      val1 (variable-update var2 val2 vs))
     (variable-update var2
                      val2 (variable-update var1 val1 vs)))

  This rule is permutative.  Now imagine that we want to apply this
  rule to the term

    (variable-update u y (variable-update u x vs)).

  Since the actual corresponding to both [47mvar1[0m and [47mvar2[0m is [47mu[0m, which is
  not strictly less than itself in the [term-order], this rule would
  fail to be applied in this situation when using the old test.
  However, since the pair [47m(u x)[0m is lexicographically less than the
  pair [47m(u y)[0m with respect to our [term-order], the rule is in fact
  applied using our new test.

  Messages about [events] now contain a space after certain left
  parentheses, in order to assist emacs users.  For example, the
  event

    (defthm abc (equal (+ (len x) 0) (len x)))

  leads to a [summary] containing the line

    Form:  ( DEFTHM ABC ...)

  and hence, if you search backwards for ``[47m(defthm abc[0m'', you won't
  stop at this message.

  More tautology checking is done during a proof; in fact, no goal
  printed to the screen, except for the results of applying [47m:use[0m and
  [47m:by[0m [hints] or the top-level goals from an induction proof, are
  known to Acl2 to be tautologies.

  The [47m[ld-query-control-alist][0m may now be used to suppress printing of
  queries; see [ld-query-control-alist].

  Warning messages are printed with short summary strings, for example
  the string ``[47mUse[0m'' in the following message.

    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 FOO) in the hint provided for Goal.  See :DOC using-
    enabled-rules.

  At the end of the event, just before the time is printed, all such
  summary strings are printed out.

  The keyword command [47m:u[0m has been introduced as an abbreviation for
  [47m:[0m[47m[ubt][0m [47m:[0m[47m[max][0m.  Printing of query messages is suppressed by [47m:u[0m.

  The keyword [47m:cheat[0m is no longer supported by any event form.

  Some irrelevant formals are detected; see [irrelevant-formals].

  A bug in the application of metafunctions was fixed: now if the
  output of a metafunction is equal to its input, the application of
  the metafunction is deemed unsuccessful and the next metafunction
  is tried.

  An example has been added to the documentation for [equivalence] to
  suggest how to make use of [equivalence] relations in rewriting.

  The following Common Lisp functions have been added to Acl2:
  [47m[alpha-char-p][0m, [47m[upper-case-p][0m, [47m[lower-case-p][0m, [47m[char-upcase][0m,
  [47m[char-downcase][0m, [47m[string-downcase][0m, [47m[string-upcase][0m, and
  [47mdigit-charp-p[0m.

  A documentation section called [47m[proof-builder][0m has been added for the
  interactive facility, whose documentation has been slightly
  improved.  See in particular the documentation for [proof-builder],
  [47m[verify][0m, and [macro-command].

  A number of [events] that had been inadvertently disallowed in
  [books] are now permitted in [books].  These are: [47m[defcong][0m,
  [47mdefcor[0m, [47m[defequiv][0m, [47m[defrefinement][0m, [47m[defstub][0m, and
  [47m[verify-termination][0m.")
 (NOTE-1-5
  (RELEASE-NOTES)
  "Acl2 Version 1.5 Notes

  Acl2 now allows ``complex rationals,'' which are complex numbers
  whose real parts are rationals and whose imaginary parts are
  non-zero rationals.  See [complex].

  A new way of handling [47m[force][0md hypotheses has been implemented.
  Rather than cause a case split at the time the [47m[force][0m occurs, we
  complete the main proof and then embark on one or more ``forcing
  rounds'' in which we try to prove the [force]d hypotheses.  See
  [forcing-round].  To allow us to compare the new handling of
  [47m[force][0m with the old, Version 1.5 implements both and uses a flag
  in [47m[state][0m to determine which method should be used.  Do [47m(assign
  old-style-forcing t)[0m if you want [47m[force][0m to be handled as it was in
  Version 1.4.  However, we expect to eliminate the old-style forcing
  eventually because we think the new style is more effective.  To
  see the difference between the two approaches to forcing, try
  proving the associativity of [append] under both settings of
  [47mold-style-forcing[0m.  To get the new behavior invoke:

    (thm (implies (and (true-listp a) (true-listp b))
                  (equal (append (append a b) c)
                         (append a (append b c)))))

  Then [47m(assign old-style-forcing t)[0m and invoke the [47mthm[0m [command] above
  again.

  A new [47m:cases[0m [hints] allows proof by cases.  See [hints].

  [47m[Include-book][0m and [47m[encapsulate][0m now restore the
  [47m[ACL2-defaults-table][0m when they complete.  See [include-book] and
  see [encapsulate].

  The [guard]s on many Acl2 primitives defined in [47maxioms.lisp[0m have been
  weakened to permit them to be used in accordance with lisp custom
  and tradition.

  It is possible to attach heuristic filters to [47m:[0m[47m[rewrite][0m rules to
  limit their applicability.  See [syntaxp].

  A tutorial has been added (but as of Version_3.6.1 it has become
  obsolete).

  [Events] now print the Summary paragraph listing [rune]s used, time,
  etc., whether they succeed or fail.  The format of the ``[failure]
  banner'' has been changed but still has multiple asterisks in it.
  [47mThm[0m also prints a Summary, whether it succeeds or fails; but [47mthm[0m is
  not an event.

  A new event form [47m[skip-proofs][0m has been added; see [skip-proofs].

  A user-specific customization facility has been added in the form of
  a book that is automatically included, if it exists on the current
  directory.  See [ACL2-customization].

  A facility for conditional metalemmas has been implemented; see
  [meta].

  The acceptable values for [47m[ld-skip-proofsp][0m have changed.  In the old
  version (Version 1.4), a value of [47mt[0m meant that proofs and [47m[local][0m
  [events] are to be skipped.  In Version 1.5, a value of [47mt[0m means
  proofs (but not [47m[local][0m [events]) are to be skipped.  A value of
  [47m'[0m[47m[include-book][0m means proofs and [47m[local][0m [events] are to be
  skipped.  There are two other, more obscure, acceptable values.
  See [ld-skip-proofsp].

  In order to turn off the forcing of assumptions, one should now
  [disable] the [47m:[0m[47m[executable-counterpart][0m of [47m[force][0m (rather than the
  [47m:[0m[47m[definition][0m of [47m[force][0m, as in the previous release); see [force].

  The macros [47m[enable-forcing][0m and [47m[disable-forcing][0m make it convenient
  to [enable] or [disable] forcing.  See [enable-forcing] and see
  [disable-forcing].

  The new commands [47m:[0m[47m[pr][0m and [47m:[0m[47m[pr!][0m print the rules created by an event
  or command.  See [pr] and see [pr!].

  The new [history] [command]s [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m will replace a
  compound [command] such as an [47m[encapsulate][0m or [47m[include-book][0m by
  the sequence of [events] in it.  That is, they ``[puff] up'' or
  ``lift'' the subevents of a [command] to the [command] level,
  eliminating the formerly superior [command] and lengthening the
  [history].  This is useful if you want to ``partially undo'' an
  [47m[encapsulate][0m or book or other compound [command] so you can
  experiment.  See [puff] and see [puff*].

  Theory expressions now are allowed to use the free variable [47m[world][0m
  and prohibited from using the free variable [47m[state][0m.  See
  [theories], although it is essentially the same as before except it
  mentions [47m[world][0m instead of [47m[state][0m.  See [world] for a discussion
  of the Acl2 logical [world].  Allowing [47m[in-theory][0m [events] to be
  state-sensitive violated an important invariant about how [books]
  behaved.

  [47m[Table][0m keys and values now are allowed to use the free variable
  [47m[world][0m and prohibited from using the free variable [47m[state][0m.  See
  the note above about theory expressions for some explanation.

  The macro for minus, [47m[-][0m, used to expand [47m(- x 3)[0m to [47m(+ x -3)[0m and now
  expands it to [47m(+ -3 x)[0m instead.  The old macro, if used in the
  left-hand sides of rewrite rules, produced inapplicable rules
  because the constant occurs in the second argument of the [47m[+][0m, but
  potential target terms generally had the constant in the first
  argument position because of the effect of [47mcommutativity-of-+[0m.

  A new class of rule, [47m:linear-alias[0m rules, allows one to implement the
  Nqthm package and similar hacks in which a [disable]d function is
  to be known equivalent to an arithmetic function.

  A new class of rule, [47m:built-in-clause[0m rules, allows one to extend the
  set of clauses proved silently by [47m[defun][0m during measure and
  [guard] processing.  See [built-in-clause].

  The new command [47m[pcb!][0m is like [47m[pcb][0m but sketches the [command] and
  then prints its subsidiary [events] in full.  See [pcb!].

  [47m:[0m[47m[Rewrite][0m class rules may now specify the [47m:[0m[47m[loop-stopper][0m field.
  See [rule-classes] and see [loop-stopper].

  The rules for how [loop-stopper]s control permutative rewrite rules
  have been changed.  One effect of this change is that now when the
  built-in commutativity rules for [47m[+][0m are used, the terms [47ma[0m and [47m(-
  a)[0m are permuted into adjacency.  For example, [47m(+ a b (- a))[0m is now
  normalized by the commutativity rules to [47m(+ a (- a) b)[0m; in Version
  1.4, [47mb[0m was considered syntactically smaller than [47m(- a)[0m and so [47m(+ a
  b (- a))[0m is considered to be in normal form.  Now it is possible to
  arrange for unary functions be be considered ``invisible'' when
  they are used in certain contexts.  By default, [47m[unary--][0m is
  considered invisible when its application appears in the argument
  list of [47m[binary-+][0m.  See [loop-stopper] and see :DOC
  set-invisible-fns-table.

  Extensive documentation has been provided on the topic of Acl2's
  ``term ordering.'' See [term-order].

  Calls of [47m[ld][0m now default [47m[ld-error-action][0m to [47m:return[0m rather than to
  the current setting.

  The [command] descriptor [47m:x[0m has been introduced and is synonymous
  with [47m:[0m[47m[max][0m, the most recently executed [command].  [History]
  [command]s such as [47m:[0m[47m[pbt][0m print a [47m:x[0m beside the most recent
  [command], simply to indicate that it [31;1mis[0m the most recent one.

  The [command] descriptor [47m:x-23[0m is synonymous with [47m(:x -23)[0m.  More
  generally, every symbol in the keyword package whose first
  character is [47m#\\x[0m and whose remaining [characters] parse as a
  negative integer is appropriately understood.  This allows [47m:[0m[47m[pbt][0m
  [47m:x-10[0m where [47m:[0m[47m[pbt][0m [47m(:max -10)[0m or [47m:[0m[47m[pbt][0m [47m(:here -10)[0m were previously
  used.  The old forms are still legal.

  The order of the arguments to [47m[defcong][0m has been changed.

  The simplifier now reports the use of unspecified built-in type
  information about the primitives with the phrase ``primitive type
  reasoning.'' This phrase may sometimes occur in situations where
  ``propositional calculus'' was formerly credited with the proof.

  The function [47m[pairlis][0m has been replaced in the code by a new
  function [47m[pairlis$][0m, because Common Lisp does not adequately
  specify its [47m[pairlis][0m function.

  Some new Common Lisp functions have been added, including [47m[logtest][0m,
  [47m[logcount][0m, [47m[integer-length][0m, [47m[make-list][0m, [47m[remove-duplicates][0m,
  [47m[string][0m, and [47m[concatenate][0m.  The source file
  [47m/slocal/src/acl2/axioms.lisp[0m is the ultimate reference regarding
  Common Lisp functions in Acl2.

  The functions [47m[defuns][0m and [47m[theory-invariant][0m have been documented.
  See [defuns] and see [theory-invariant].

  A few symbols have been added to the list [47m*acl2-exports*[0m.

  A new key has been implemented for the [47m[ACL2-defaults-table][0m,
  [47m:irrelevant-formals-ok[0m.  See [set-irrelevant-formals-ok].

  The connected book directory, [47m[cbd][0m, must be nonempty and begin and
  end with a slash.  It is set (and displayed) automatically upon
  your first entry to [47m[lp][0m.  You may change the setting with
  [47m[set-cbd][0m.  See [cbd].

  [47m:[0m[47m[oops][0m will undo the last [47m:[0m[47m[ubt][0m.  See [oops].

  Documentation has been written about the ordinals.  See :DOC
  [47me0-ordinalp[0m and see :DOC [47me0-ord-<[0m.  [Note added later: Starting
  with Version_2.8, instead see [o-p] and see [o<].

  The color [events] --- (red), (pink), (blue), and (gold) --- may no
  longer be enclosed inside calls of [47m[local][0m, for soundness reasons.
  In fact, neither may any event that sets the [47m[ACL2-defaults-table][0m.
  See [embedded-event-form].

  See [ld-keyword-aliases] for an example of how to change the exit
  keyword from [47m:[0m[47m[q][0m to something else.

  The attempt to install a [monitor] on [47m:[0m[47m[rewrite][0m rules stored as
  simple abbreviations now causes an error because the application of
  abbreviations is not tracked.

  A new message is sometimes printed by the theorem prover, indicating
  that a given simplification is ``specious'' because the subgoals it
  produces include the input goal.  In Version 1.4 this was detected
  but not reported, causing behavior some users found bizarre.  See
  [specious-simplification].

  [47m:[0m[47m[Definition][0m rules are no longer always required to specify the
  [47m:clique[0m and [47m:controller-alist[0m fields; those fields can be defaulted
  to system-determined values in many common instances.  See
  [definition].

  A warning is printed if a macro form with keyword arguments is given
  duplicate keyword values.  Execute [47m(thm t :doc nil :doc \"ignored\")[0m
  and read the warning printed.

  A new restriction has been placed on [47m[encapsulate][0m.  Non-[47m[local][0m
  recursive definitions inside the [47m[encapsulate][0m may not use, in
  their tests and recursive calls, the constrained functions
  introduced by the [47m[encapsulate][0m.  See [subversive-recursions].
  (Note added in Version 2.3: Subversive recursions were first
  recognized by us here in Version 1.5, but our code for recognizing
  them was faulty and the bug was not fixed until Version 2.3.)

  The [events] [47m[defequiv][0m, [47m[defcong][0m, [47m[defrefinement][0m, and
  [47m[defevaluator][0m have been reimplemented so that they are just macros
  that expand into appropriate [47m[defthm][0m or [47m[encapsulate][0m [events];
  they are no longer primitive [events].  See the [documentation] of
  each affected event.

  The [47mdefcor[0m event, which was a shorthand for a [47m[defthm][0m that
  established a [corollary] of a named, previously proved event, has
  been eliminated because its implementation relied on a technique we
  have decided to ban from our code.  If you want the effect of a
  [47mdefcor[0m in Version 1.5 you must submit the corresponding [47m[defthm][0m
  with a [47m:by[0m hint naming the previously proved event.

  Error reporting has been improved for inappropriate [47m[in-theory][0m
  [hints] and [events], and for syntax errors in rule classes, and
  for non-existent filename arguments to [47m[ld][0m.

  Technical Note: We now maintain the Third Invariant on [47mtype-alists[0m,
  as described in the Essay on the Invariants on Type-alists, and
  Canonicality.  This change will affect some proofs, for example, by
  causing a to rewrite more quickly to [47mc[0m when [47m(equiv a b)[0m and [47m(equiv
  b c)[0m are both known and [47mc[0m is the canonical representative of the
  three.")
 (NOTE-1-6
  (RELEASE-NOTES)
  "Acl2 Version 1.6 Notes

  A new key has been implemented for the [47m[ACL2-defaults-table][0m,
  [47m:ignore-ok[0m.  See [set-ignore-ok].

  It is now legal to have color [events], such as [47m(red)[0m, in the
  [portcullis] of a book.  More generally, it is legal to set the
  [47m[ACL2-defaults-table][0m in the [portcullis] of a book.  For example,
  if you execute [47m:red[0m and then certify a book, the event [47m(red)[0m will
  show up in the [portcullis] of that book, and hence the definitions
  in that book will all be red (except when overridden by appropriate
  declarations or [events]).  When that book is included, then as
  always, its [portcullis] must first be ``raised,'' and that will
  cause the default color to become red before the [events] in the
  book are executed.  As always, the value of [47m[ACL2-defaults-table][0m
  immediately after execution of an [47m[include-book][0m, [47m[certify-book][0m,
  or [47m[encapsulate][0m form will be the same as it was immediately before
  execution (and hence, so will the default color).  See [portcullis]
  and, for more about books, see [books].

  A theory [47m[ground-zero][0m has been defined to contain exactly those
  rules that are [enable]d when Acl2 starts up.  See [ground-zero].

  The function [47m[nth][0m is now [enable]d, correcting an oversight from
  Version 1.5.

  Customization files no longer need to meet the syntactic restrictions
  put on [books]; rather, they can contain arbitrary Acl2 forms.  See
  [ACL2-customization].

  Structured directory names and structured file names are supported;
  see especially the documentation for [pathname], [book-name], and
  [47m[cbd][0m.

  Acl2 now works with some Common Lisp implementations other than akcl,
  including Lucid, Allegro, and MCL.

  A facility has been added for displaying proof trees, especially
  using emacs; see [proof-tree].

  There is a considerable amount of new [documentation], in particular
  for the printing functions [47m[fmt][0m, [47m[fmt1][0m, and [47m[fms][0m, and for the
  notion of Acl2 term (see [term]).

  It is possible to introduce new well-founded relations, to specify
  which relation should be used by [47m[defun][0m, and to set a default
  relation.  See [well-founded-relation-rule].

  It is possible to make functions suggest new inductions.  See
  [induction].

  It is possible to change how Acl2 expresses [type-set] information;
  in particular, this affects what clauses are proved when [force]d
  assumptions are generated.  See [type-set-inverter].

  A new restriction has been added to [47m[defpkg][0m, having to do with
  undoing.  If you undo a [47m[defpkg][0m and define the same package name
  again, the imports list must be identical to the previous imports
  or else an explanatory error will occur.  See
  [package-reincarnation-import-restrictions].

  [47m[Theory-invariant][0m and [47m[set-irrelevant-formals-ok][0m are now embedded
  event forms.

  The command [47m:[0m[47m[good-bye][0m may now be used to quit entirely out of Lisp,
  thus losing your work forever.  This command works in akcl but may
  not work in every Common Lisp.

  A theory [47m[ground-zero][0m has been added that contains exactly the
  [enable]d rules in the [startup] theory.  See [ground-zero].

  [47mDefine-pc-macro[0m and [47mdefine-pc-atomic-macro[0m now automatically define
  [47m:red[0m functions.  (It used to be necessary, in general, to change
  color to [47m:red[0m before invoking these.)

  For a proof of the well-foundedness of [47me0-ord-<[0m on the [47me0-ordinalp[0ms,
  see [proof-of-well-foundedness].  [Note added later: Starting with
  Version_2.8, [47m[o<][0m and [47m[o-p][0m replace [47me0-ord-<[0m and [47me0-ordinalp[0m,
  respectively.]

  Free variables are now handled properly for hypotheses of
  [47m:[0m[47m[type-prescription][0m rules.

  When the system is loaded or saved, [47m[state][0m is now bound to
  [47m*the-live-state*[0m.

  [47m[Certify-book][0m has been modified so that when it compiles a file, it
  loads that object file.

  [47m[Defstub][0m has been modified so that it works when the color is hot
  ([47m:red[0m or [47m:pink[0m).

  Several basic, but not particularly commonly used, [events] have been
  added or changed.  The obscure axiom [47msymbol-name-intern[0m has been
  modified.  The definition of [47mfirstn[0m has been changed.  [47m[Butlast][0m is
  now defined.  The definition of [47m[integer-length][0m has been modified.
  The left-hand side of the rewrite rule [47mrational-implies2[0m has been
  changed from [47m(* (numerator x) (/ (denominator x)))[0m to [47m(* (/
  (denominator x)) (numerator x))[0m, in order to respect the fact that
  [47m[unary-/][0m is invisible with respect to [47m[binary-*][0m.  See
  [loop-stopper].

  The `preprocess' process in the waterfall (see [hints] for a
  discussion of the [47m:do-not[0m hint) has been changed so that it works
  to avoid case-splitting.  The `simplify' process refuses to force
  (see [force]) when there are [47m[if][0m terms, including [47m[and][0m and [47m[or][0m
  terms, in the goal being simplified.

  The function [47mapply[0m is no longer introduced automatically by
  translation of user input to internal form when functions are
  called on inappropriate explicit values, e.g., [47m(car 3)[0m.

  The choice of which variable to use as the measured variable in a
  recursive definition has been very slightly changed.")
 (NOTE-1-7
  (RELEASE-NOTES)
  "ACL2 Version 1.7 (released October 1994) Notes

  [47m[Include-book][0m now takes (optionally) an additional keyword argument,
  indicating whether a compiled file is to be loaded.  The default
  behavior is unchanged, except that a warning is printed when a
  compiled file is not loaded.  See [include-book].

  A markup language for [documentation] strings has been implemented,
  and many of the source files have been marked up using this
  language (thanks largely to the efforts of Laura Lawless).  See
  markup.  Moreover, there are translators that we have used to
  provide versions of the ACL2 [documentation] in info (for use in
  emacs), html (for Mosaic), and tex (for hardcopy) formats.

  A new event [47mdefdoc[0m has been implemented.  It is like [47m[deflabel][0m, but
  allows redefinition of [doc] strings and has other advantages.  See
  [47mdefdoc[0m.

  We used to ignore corollaries when collecting up the axioms
  introduced about constrained functions.  That bug has been fixed.
  We thank John Cowles for bringing this bug to our attention.

  The macro [47m[defstub][0m now allows a [47m:[0m[47m[doc][0m keyword argument, so that
  [documentation] may be attached to the name being introduced.

  A new command [47m[nqthm-to-ACL2][0m has been added to help Nqthm users to
  make the transition to ACL2.  See [nqthm-to-ACL2], which also
  includes a complete listing of the relevant tables.

  Many function names, especially of the form ``foo[47m-lst[0m'', have been
  changed in order to support the following convention, for any
  ``foo'':

  [47m(foo-listp lst)[0m represents the notion [47m(for x in lst always foop x)[0m.

  A complete list of these changes may be found at the end of this
  note.  All of them except [47msymbolp-listp[0m and [47mlist-of-symbolp-listp[0m
  have the string ``[47m-lst[0m'' in their names.  Note also that
  [47mkeyword-listp[0m has been renamed [47m[keyword-value-listp][0m.

  Accumulated persistence has been implemented.  It is not connected to
  [47m:[0m[47m[brr][0m or rule monitoring.  See [accumulated-persistence].

  [47m:Trigger-terms[0m has been added for [47m:[0m[47m[linear][0m rule classes, so you can
  hang a [linear] rule under any addend you want.  See [linear],
  which has been improved and expanded.

  ACL2 now accepts [47m256[0m [characters] and includes the Common Lisp
  functions [47m[code-char][0m and [47m[char-code][0m.  However, ACL2 controls the
  lisp reader so that [47m#\\c[0m may only be used when [47mc[0m is a single
  standard character or one of [47mNewline[0m, [47mSpace[0m, [47mPage[0m, [47mRubout[0m, [47mTab[0m.  If
  you want to enter other [characters] use [47m[code-char][0m, e.g., [47m(coerce
  (list (code-char 7) (code-char 240) #a) 'string)[0m.  See
  [characters].  Note: our current handling of [characters] makes the
  set of theorems different under Macintosh Common Lisp (MCL) than
  under other Common Lisps.  We hope to rectify this situation before
  the final release of ACL2.

  A new [table], [47m[macro-aliases-table][0m, has been implemented, that
  associates macro names with function names.  So for example, since
  [47m[append][0m is associated with [47m[binary-append][0m, the form [47m(disable
  append)[0m it is interpreted as though it were [47m(disable
  binary-append)[0m.  See [macro-aliases-table], see [add-macro-alias]
  and see [remove-macro-alias].

  The implementation of conditional metalemmas has been modified so
  that the metafunction is applied before the hypothesis metafunction
  is applied.  See [meta].

  The Common Lisp functions [47m[acons][0m and [47m[endp][0m have been defined in the
  ACL2 logic.

  We have added the symbol [47m[declare][0m to the list [47m*acl2-exports*[0m, and
  hence to the package [47m\"ACL2-USER\"[0m.

  A new hint, [47m:restrict[0m, has been implemented.  See [hints].

  It used to be that if [47m:[0m[47m[ubt][0m were given a number that is greater than
  the largest current [command] number, it treated that number the
  same as [47m:[0m[47m[max][0m.  Now, an error is caused.

  The [table] [47m:force-table[0m has been eliminated.

  A command [47m:[0m[47m[disabledp][0m (and macro [47m[disabledp][0m) has been added; see
  [disabledp].

  [Compilation] via [47m:[0m[47m[set-compile-fns][0m is now suppressed during
  [47m[include-book][0m.  In fact, whenever the [state] global variable
  [47m[ld-skip-proofsp][0m has value [47m'[0m[47m[include-book][0m.

  Here are some less important changes, additions, and so on.

  Unlike previous releases, we have not proved all the theorems in
  [47maxioms.lisp[0m; instead we have simply assumed them.  We have deferred
  such proofs because we anticipate a fairly major change in Version
  1.8 in how we deal with [guard]s.

  We used to (accidentally) prohibit the ``redefinition'' of a [table]
  as a function.  That is no longer the case.

  The check for whether a [corollary] follows tautologically has been
  sped up, at the cost of making the check less ``smart'' in the
  following sense: no longer do we expand primitive functions such as
  [47m[implies][0m before checking this propositional implication.

  The [command] [47m[ubt!][0m has been modified so that it never causes or
  reports an error.  See [ubt!].

  ACL2 now works in Harlequin LispWorks.

  The user can now specify the [47m:trigger-terms[0m for [47m:[0m[47m[linear][0m rules.  See
  [linear].

  The name of the system is now ``ACL2''; no longer is it ``Acl2''.

  The raw lisp counterpart of [47m[theory-invariant][0m is now defined to be a
  no-op as is consistent with the idea that it is just a call of
  [47m[table][0m.

  A bug was fixed that caused [proof-builder] [instructions] to be
  executed when [47m[ld-skip-proofsp][0m was [47mt[0m.

  The function [47m[rassoc][0m has been added, along with a corresponding
  function used in its [guard], [47mr-eqlable-alistp[0m.

  The [47m[in-theory][0m event and hint now print a warning not only when
  certain ``primitive'' [47m:[0m[47m[definition][0m rules are [disable]d, but also
  when certain ``primitive'' [47m:[0m[47m[executable-counterpart][0m rules are
  [disable]d.

  The modified version of [47mtrace[0m provided by ACL2, for use in raw Lisp,
  has been modified so that the lisp special variable [47m*trace-alist*[0m
  is consulted.  This alist associates, using [47m[eq][0m, values with their
  print representations.  For example, initially [47m*trace-alist*[0m is a
  one-element list containing the pair [47m(cons state
  '|*the-live-state*|)[0m.

  The system now prints an observation when a form is skipped because
  the default color is [47m:red[0m or [47m:pink[0m.  (Technically: [47mwhen-cool[0m has
  been modified.)

  Additional protection exists when you submit a form to raw Common
  Lisp that should only be submitted inside the ACL2 read-eval-print
  loop.

  Here is a complete list of the changes in function names described
  near the top of this note, roughly of the form

    foo-lst --> foo-listp

  meaning: the name ``[47mfoo-lst[0m'' has been changed to ``[47mfoo-listp[0m.''

    symbolp-listp    --> symbol-listp
    list-of-symbolp-listp  --> symbol-list-listp
                           {for consistency with change to symbol-listp}
    rational-lst     --> rational-listp
                         {which in fact was already defined as well}
    integer-lst      --> integer-listp
    character-lst    --> character-listp
    stringp-lst      --> string-listp
    32-bit-integer-lst   --> 32-bit-integer-listp
    typed-io-lst     --> typed-io-listp
    open-channel-lst --> open-channel-listp
    readable-files-lst   --> readable-files-listp
    written-file-lst --> written-file-listp
    read-file-lst    --> read-file-listp
    writeable-file-lst   --> writable-file-listp
                         {note change in spelling of ``writable''}
    writeable-file-lst1  --> writable-file-listp1
    pseudo-termp-lst     --> pseudo-term-listp
    hot-termp-lst --> hot-term-listp {by analogy with pseudo-term-listp}
    weak-termp-lst   --> weak-term-listp
    weak-termp-lst-lst   --> weak-termp-list-listp
    ts-builder-case-lstp -> ts-builder-case-listp
    quotep-lst       --> quote-listp
    termp-lst        --> term-listp
    instr-lst        --> instr-listp
    spliced-instr-lst    --> spliced-instr-listp
    rewrite-fncallp-lst  --> rewrite-fncallp-listp
    every-occurrence-equiv-hittablep1-lst -->
                every-occurrence-equiv-hittablep1-listp
    some-occurrence-equiv-hittablep1-lst  -->
                some-occurrence-equiv-hittablep1-listp
                {by analogy with the preceding, even though it's a
                 ``some'' instead of ``all'' predicate]
    almost-quotep1-lst   --> almost-quotep1-listp
    ffnnames-subsetp-lst --> ffnnames-subsetp-listp
    boolean-lstp     --> boolean-listp
    subst-expr1-lst-okp  --> subst-expr1-ok-listp")
 (NOTE-1-8
  (RELEASE-NOTES)
  "ACL2 Version 1.8 (May, 1995) Notes

  See [note-1-8-update] for yet more recent changes.

  [Guard]s have been eliminated from the ACL2 logic.  A summary is
  contained in this brief note.  Also see [defun-mode] and see
  [set-guard-checking].

  [Guard]s may be included in [defuns] as usual but are ignored from
  the perspective of admission to the logic: functions must terminate
  on all arguments.

  As in Nqthm, primitive functions, e.g., [47m[+][0m and [47m[car][0m, logically
  default unexpected arguments to convenient values.  Thus, [47m(+ 'abc
  3)[0m is [47m3[0m and [47m(car 'abc)[0m is [47mnil[0m.  See [programming], and see the
  [documentation] for the individual primitive functions.

  In contrast to earlier versions of ACL2, Version 1.8 logical
  functions are executed at Nqthm speeds even when [guard]s have not
  been verified.  In versions before 1.8, such functions were
  interpreted by ACL2.

  Colors have been eliminated.  Two ``[defun-mode]s'' are supported,
  [47m:[0m[47m[program][0m and [47m:[0m[47m[logic][0m.  Roughly speaking, [47m:[0m[47m[program][0m does what
  [47m:red[0m used to do, namely, allow you to prototype functions for
  execution without any proof burdens.  [47m:[0m[47m[Logic][0m mode does what [47m:blue[0m
  used to do, namely, allow you to add a new definitional axiom to
  the logic.  A global [default-defun-mode] is comparable to the old
  default color.  The system comes up in [47m:[0m[47m[logic][0m mode.  To change
  the global [defun-mode], type [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m at the
  top-level.  To specify the [defun-mode] of a [47m[defun][0m locally use

     [47m(declare (xargs :mode mode))[0m.

  The [prompt] has changed.  The initial [prompt], indicating [47m:[0m[47m[logic][0m
  mode, is

    ACL2 !>

  If you change to [47m:[0m[47m[program][0m mode the [prompt] becomes

    ACL2 p!>

  [Guard]s 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.  If a [guard] is specified, as with [47m[xargs][0m
  [47m:[0m[47m[guard][0m, then it is ``verified'' at defun-time (unless you also
  specify [47m[xargs][0m [47m:verify-guards nil[0m).  [Guard] verification means
  what it always has: the input [guard] is shown to imply the
  [guard]s on all subroutines in the body.  If the [guard]s of a
  function are verified, then a call of the function on inputs
  satisfying the [guard] can be computed directly by Common Lisp.
  Thus, verifying the [guard]s on your functions will allow them to
  execute more efficiently.  But it does not affect their logical
  behavior and since you will automatically get Nqthm speeds on
  unverified logical definitions, most users will probably use
  [guard]s either as a specification device or only use them when
  execution efficiency is extremely important.

  Given the presence of [guard]s in the system, two issues are
  unavoidable.  Are [guard]s verified as part of the [47m[defun][0m process?
  And are [guard]s checked when terms are evaluated?  We answer both
  of those questions below.

  Roughly speaking, in its initial [state] the system will try to
  verify the [guard]s of a [47m[defun][0m if a [47m:[0m[47m[guard][0m is supplied in the
  [47m[xargs][0m and will not try otherwise.  However, [guard] verification
  in [47m[defun][0m can be inhibited ``locally'' by supplying the [47m[xargs][0m
  [47m:[0m[47m[verify-guards][0m [47mnil[0m.  ``Global'' inhibition can be obtained via
  the [47m:[0m[47m[set-verify-guards-eagerness][0m.  If you do not use the [47m:[0m[47m[guard][0m
  [47m[xargs][0m, you will not need to think about [guard] verification.

  We now turn to the evaluation of expressions.  Even if your functions
  contain no [guard]s, the primitive functions do and hence you have
  the choice: when you submit an expression for evaluation do you
  mean for [guard]s to be checked at runtime or not?  Put another
  way, do you mean for the expression to be evaluated in Common Lisp
  (if possible) or in the 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, should
  [47m(car 'abc)[0m cause a [guard] violation error or return [47mnil[0m?

  The top-level ACL2 loop has a variable which controls which sense of
  execution is provided.  To turn ``[guard] checking on,'' by which
  we mean that [guard]s are checked at runtime, execute the top-level
  form [47m:set-guard-checking t[0m.  To turn it off, do [47m:set-guard-checking
  nil[0m.  The status of this variable is reflected in the [prompt].

    ACL2 !>

  means [guard] checking is on and

    ACL2 >

  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

    ACL2 !>(car 'abc)

  will signal an error, while

    ACL2 >(car 'abc)

  will return [47mnil[0m.

  Note that whether or not [guard]s are checked at runtime is
  independent of whether you are operating in [47m:[0m[47m[program][0m mode or
  [47m:[0m[47m[logic][0m mode and whether theorems are being proved or not.
  (Although it must be added that functions defined in [47m:[0m[47m[program][0m
  mode cannot help but check their [guard]s because no logical
  definition exists.)

  Version 1.8 permits the verification of the [guard]s of theorems,
  thus insuring that all instances of the theorem will evaluate
  without error in Common Lisp.  To verify the [guard]s of a theorem
  named [47mname[0m execute the event

    (verify-guards name).

  If a theorem's [guard]s have been verified, the theorem is guaranteed
  to evaluate without error to non-[47mnil[0m in Common Lisp (provided
  resource errors do not arise).

  Caveat about [47m[verify-guards][0m: [47m[implies][0m is a function symbol, so in
  the term [47m(implies p q)[0m, [47mp[0m cannot be assumed true when [47mq[0m is
  evaluated; they are both evaluated ``outside.'' Hence, you cannot
  generally verify the [guard]s on a theorem if [47m[implies][0m is used to
  state the hypotheses.  Use [47m[if][0m instead.  In a future version of
  ACL2, [47m[implies][0m will likely be a macro.

  See sum-list-example.lisp for a nice example of the use of Version
  1.8.  This is roughly the same as the documentation for
  [guard-example].

  We have removed the capability to do ``old-style-forcing'' as existed
  before Version 1.5.  See [note-1-5].

  NOTE: Some low level details have, of course, changed.  One such
  change is that there are no longer two distinct type prescriptions
  stored when a function is admitted with its [guard]s verified.  So
  for example, the type prescription [rune] for [47m[binary-append][0m is
  now

    (:type-prescription binary-append)

  while in Versions 1.7 and earlier, there were two such [rune]s:

    (:type-prescription binary-append . 1)
    (:type-prescription binary-append . 2)

  Nqthm-style forcing on [linear] arithmetic assumptions is no longer
  executed when forcing is [disable]d.

  Functional instantiation now benefits from a trick also used in
  Nqthm: once a [constraint] generated by a [47m:functional-instance[0m
  lemma instance (see [lemma-instance]) has been proved on behalf of
  a successful event, it will not have to be re-proved on behalf of a
  later event.

  [47m[1+][0m and [47m[1-][0m are now macros in the logic, not functions.  Hence, for
  example, it is ``safe'' to use them on left-hand sides of rewrite
  rules, without invoking the common warning about the presence of
  nonrecursive function symbols.

  A new [documentation] section [file-reading-example] illustrates how
  to process forms in a file.

  A new [proof-builder] command [47mforwardchain[0m has been added; see
  [ACL2-pc::forwardchain].

  It is now possible to use quantifiers.  See [defun-sk] and see
  [defchoose].

  There is a new event [47m[set-inhibit-warnings][0m, which allows the user to
  turn off warnings of various types.  see [set-inhibit-warnings].

  An unsoundness relating [47m[encapsulate][0m and [47m:functional-instance[0m
  [hints] has been remedied, with a few small effects visible at the
  user level.  The main observable effect is that [47m[defaxiom][0m and
  non-local [47m[include-book][0m [events] are no longer allowed in the
  scope of any [47m[encapsulate][0m event that has a non-empty [signature].

  When [47m[certify-book][0m is called, we now require that the default
  [defun-mode] (see [default-defun-mode]) be [47m:[0m[47m[logic][0m.  On a related
  note, the default [defun-mode] is irrelevant to [47m[include-book][0m; the
  mode is always set to [47m:[0m[47m[logic][0m initially, though it may be changed
  within the book and reverts to its original value at the conclusion
  of the [47m[include-book][0m.  A bug in [47m[include-book][0m prevented it from
  acting this way even though the [documentation] said otherwise.

  The [documentation] has been substantially improved.  A new section
  ``Programming'' contains [documentation] of many useful functions
  provided by ACL2; see [programming].  Also, the [documentation] has
  been ``marked up'' extensively.  Thus in particular, users of
  Mosaic will find many links in the [documentation].

  The symbols [47m[force][0m, [47m[mv-nth][0m, and [47macl2-count[0m have been added to the
  list [47m*acl2-exports*[0m.

  We now permit most names from the main Lisp package to be used as
  names, except for names that define functions, macros, or
  constants.  See [name].

  We have changed the list of imports from the Common Lisp package to
  ACL2, i.e., the list [47m*common-lisp-symbols-from-main-lisp-package*[0m,
  to be exactly those external symbols of the Common Lisp package as
  specified by the draft Common Lisp standard.  In order to
  accommodate this change, we have renamed some ACL2 functions as
  shown below, but these and other ramifications of this change
  should be transparent to most ACL2 users.

    warning      --> warning$
    print-object --> print-object$

  Proof trees are no longer enabled by default.  To start them up,
  [47m:[0m[47m[start-proof-tree][0m.

  We have added the capability of building smaller images.  The easiest
  way to do this on a Unix (trademark of AT&T) system is: [47mmake small[0m.

  Here we will put some less important changes, additions, and so on.

  We have added definitions for the Common Lisp function [47m[position][0m
  (for the test [47m[eql][0m), as well as corresponding versions
  [47m[position-equal][0m and [47m[position-eq][0m that use tests [47m[equal][0m and [47m[eq][0m,
  respectively.  See [position], see [position-equal], and see
  [position-eq].

  The [47m[defthm][0m event [47mrational-listp-implies-rationalp-car[0m no longer
  exists.

  We fixed a bug in the hint mechanism that applied [47m:by[0m, [47m:cases[0m, and
  [47m:use[0m [hints] to the first induction goal when the prover reverted
  to proving the original goal by induction.

  We fixed a bug in the handling of [47m(set-irrelevant-formals-ok :warn)[0m.

  In support of removing the old-style forcing capability, we deleted
  the initialization of [state] global [47mold-style-forcing[0m and deleted
  the definitions of [47mrecover-assumptions[0m,
  [47mrecover-assumptions-from-goal[0m, [47mremove-assumptions1[0m,
  [47mremove-assumptions[0m, and [47msplit-on-assumptions[0m, and we renamed
  [47msplit-on-assumptions1[0m to [47msplit-on-assumptions[0m.

  The special value [47m'none[0m in the [proof-builder] commands [47mclaim[0m and [47m[=][0m
  has been replaced by [47m:none[0m.

  A bug in the handling of [hints] by subgoals has been fixed.  For
  example, formerly a [47m:do-not[0m hint could be ``erased'' by a [47m:use[0m hint
  on a subgoal.  Thanks go to Art Flatau for noticing the bug.

  The functions [47mweak-termp[0m and [47mweak-term-listp[0m have been deleted, and
  their calls have been replaced by corresponding calls of
  [47m[pseudo-termp][0m and [47mpseudo-term-listp[0m.  The notion of [47m[pseudo-termp][0m
  has been slightly strengthened by requiring that terms of the form
  [47m(quote ...)[0m have length 2.

  Performance has been improved in various ways.  At the prover level,
  backchaining through the recognizer alist has been eliminated in
  order to significantly speed up ACL2's rewriter.  Among the other
  prover changes (of which there are several, all technical): we no
  longer clausify the input term when a proof is interrupted in favor
  of inducting on the input term.  At the [io] level, we have
  improved performance somewhat by suitable declarations and
  proclamations.  These include technical modifications to the macros
  [47m[mv][0m and [47m[mv-let][0m, and introduction of a macro [47mthe-mv[0m analogous to
  the macro [47m[the][0m but for forms returning multiple values.

  The function [47mspaces[0m now takes an extra argument, the current column.

  A bug in the [proof-builder] [47mequiv[0m command was fixed.

  The function [47mintersectp[0m has been deleted, because it was essentially
  duplicated by the function [47m[intersectp-equal][0m.

  We now proclaim functions in AKCL and GCL before compiling [books].
  This should result in somewhat increased speed.

  The function [47mrepeat[0m has been eliminated; use [47m[make-list][0m instead.

  The [proof-builder] command [47mexpand[0m has been fixed so that it
  eliminates [47m[let][0m (lambda) expressions when one would expect it to.

  A new primitive function, [47m[mv-nth][0m, has been introduced.  [47m[Mv-nth][0m is
  equivalent to [47m[nth][0m and is used in place of [47m[nth][0m in the
  translation of [47m[mv-let][0m expressions.  This allows the user to
  control the simplification of [47m[mv-let][0m expressions without
  affecting how [47m[nth][0m is treated.  In that spirit, the rewriter has
  been modified so that certain [47m[mv-nth][0m expressions, namely those
  produced in the translation of [47m(mv-let (a b c)(mv x y z) p)[0m, are
  given special treatment.

  A minor bug in [47muntranslate[0m has been fixed, which for example will fix
  the printing of conjunctions.

  [47mTranslate[0m now takes a [47mlogicp[0m argument, which indicates whether it
  enforces the restriction that [47m:[0m[47m[program][0m mode functions do not
  occur in the result.

  The modified version of [47mtrace[0m provided by ACL2, for use in raw Lisp,
  has been modified so that the lisp special variable [47m*trace-alist*[0m
  has a slightly different functionality.  This alist associates,
  using [47m[eq][0m, symbols with the print representations of their values.
  For example, initially [47m*trace-alist*[0m is a one-element list
  containing the pair [47m(cons 'state '|*the-live-state*|)[0m.  Thus, one
  may cons the pair [47m(cons '*foo* \"It's a FOO!\")[0m on to [47m*trace-alist*[0m;
  then until [47m*foo*[0m is defined, this change will have no effect, but
  after for example

    (defconst *foo* 17)

  then [47mtrace[0m will print [47m17[0m as [47m\"It's a FOO!\"[0m.

  [47mTrace[0m also traces the corresponding logic function.

  [Proof-tree] display has been improved slightly in the case of
  successful proofs and certain event failures.

  The function [47mpositive-integer-log2[0m has been deleted.

  The macro [47m[skip-proofs][0m now prints a warning message when it is
  encountered in the context of an [47m[encapsulate][0m event or a book.
  See [skip-proofs].

  Some functions related to [47mthe-fn[0m and [47mwormhole1[0m now have [defun-mode]
  [47m:[0m[47m[program][0m, but this change is almost certain to be inconsequential
  to all users.")
 (NOTE-1-8-UPDATE
  (RELEASE-NOTES)
  "ACL2 Version 1.8 (Summer, 1995) Notes

  ACL2 can now use Ordered Binary Decision Diagram technology.  See
  [bdd].  There is also a [proof-builder] [47mbdd[0m command.

  ACL2 is now more respectful of the intention of the function [47m[hide][0m.
  In particular, it is more careful not to dive inside any call of
  [47m[hide][0m during equality substitution and case splitting.

  The [47m[ld][0m special (see [ld]) [47m[ld-pre-eval-print][0m may now be used to
  turn off printing of input forms during processing of [47m[encapsulate][0m
  and [47m[certify-book][0m forms, by setting it to the value [47m:never[0m, i.e.,
  [47m(set-ld-pre-eval-print :never state)[0m.  See [ld-pre-eval-print].

  The TUTORIAL documentation section (now obsolete) has, with much help
  from Bill Young, been substantially improved to a bona fide
  introduction.

  The term pretty-printer has been modified to introduce [47m(<= X Y)[0m as an
  abbreviation for [47m(not (< Y X))[0m.

  Forward chaining and linear arithmetic now both benefit from the
  evaluation of ground subterms.

  A new macro [47m[set-inhibit-output-lst][0m has been defined.  This should
  be used when setting the [state] global [47minhibit-output-lst[0m; see
  [set-inhibit-output-lst] and see [proof-tree].

  The test for redundancy in definitions includes the [guard] and type
  declarations.  See [redundant-events].

  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?

  Here we will put some less important changes, additions, and so on.

  A bug has been fixed so that now, execution of [47m:comp t[0m (see [comp])
  correctly handles non-standard characters.

  A bug in [47m[digit-char-p][0m has been fixed, so that the ``default'' is
  [47mnil[0m rather than [47m0[0m.

  [47m[True-listp][0m now tests the final [47m[cdr][0m against [47mnil[0m using [47m[eq][0m instead
  of [47m[equal][0m, for improved efficiency.  The logical meaning is,
  however, unchanged.

  [47m[Put-assoc-equal][0m has been added to the logic (it used to have
  [47m:[0m[47m[defun-mode][0m [47m:[0m[47m[program][0m, and has been documented.")
 (NOTE-1-9
  (RELEASE-NOTES)
  "ACL2 Version 1.9 (Fall, 1996) Notes

  By default, when the system is started it is illegal to use the
  variable [47m[state][0m as a formal parameter of a function definition.
  The aim is to prevent novice users from stumbling into the
  Byzantine syntactic restrictions on that variable symbol.  Use

    :set-state-ok t

  or, equivalently,

    (set-state-ok t)

  to switch back to the old default mode.  See [set-state-ok]

  [47mSet-state-ok[0m is an event that affects the ACL2 defaults table (see
  [ACL2-defaults-table]).  Recall that when books are included, the
  defaults table is restored to its pre-inclusion state.  Thus, while
  a [47mset-state-ok[0m form will permit the book to define a [47mstate[0m-using
  function, it will not permit the user of the book to make such a
  definition.  We recommend putting [47m(set-state-ok t)[0m in any book that
  defines a [47mstate[0m using function.

  Books certified under Version 1.8 must be recertified under Version
  1.9.  See :DOC version.

  The simplifier has been made to look out for built-in clauses,
  whereas in past versions such clauses were only noticed by the
  ``preprocessor'' at the top of the waterfall.  THIS CHANGE MAY
  PREVENT OLD SCRIPTS FROM REPLAYING!  The undesirable side-effect is
  caused by the fact that [47m:HINTS[0m require you to refer to clauses by
  their exact name (see [goal-spec]) and because the new simplifier
  proves more clauses than before, the goals produced have different
  names.  Thus, if a script uses [47m:HINTS[0m that refer to clauses other
  than \"Goal\", e.g., \"Subgoal 1.3\" then the hint may be applied to a
  different subgoal than originally intended.

  The use of built-in-clauses has been made more efficient.  If a set
  of clauses arise often in a piece of work, it might be advantageous
  to build them in even if that results in a large set (hundreds?) of
  built-in clauses.  See [built-in-clause]

  Wormholes can now be used in :logic mode functions. See [wormhole]

  It is now possible to provide ``computed hints.'' For example, have
  you ever wished to say ``in all goals with a name like this, :use
  that'' or ``if this term is in the subgoal, then :use that''?
  Well, see [computed-hints] and the extraordinarily long example in
  see [using-computed-hints].

  [47mHide[0m terms may be rewritten with :rewrite rules about [47mhide[0m.  See
  [hide], where we also now explain why [47mhide[0m terms are sometimes
  introduced into your proof attempts.

  A bug that sometimes caused the ``non-lazy IF'' hard error message
  was fixed.

  A bug that sometimes caused a hard error in forward chaining was
  fixed.

  A bug in print-rules (:pr) was fixed.

  We report the use of :executable-counterparts in the evaluation of
  SYNTAXP forms.

  Some documentation errors were fixed.

  A bug in parent-tree tracking in add-literal-and-pt was fixed.

  A bug in ok$, go$ and eval$ was fixed.

  Clausify now optimizes (mv-nth 'k (list x0 ... xk ... xn)) to xk.")
 (NOTE-2-0
  (RELEASE-NOTES)
  "ACL2 Version 2.0 (July, 1997) Notes

  This is the first version of ACL2 released under the copyright of the
  University of Texas (UT).  Future releases of ACL2 will be made
  from UT rather than Computational Logic, Inc. (CLI).  Version 2.0
  is just Version 1.9 as released by CLI, with a few bugs fixed.

  A bug causing an infinite loop was fixed in functional instantiation.
  The bug manifested itself when two conditions occurred
  simultaneously: First, the functional substitution replaces a
  function symbol, e.g., [47mFOO[0m, with a [47mLAMBDA[0m expression containing a
  free variable (a variable not among in the [47mLAMBDA[0m formals).  And,
  second, in one of the constraints being instantiated there is a
  call of the function symbol [47mFOO[0m within the scope of another [47mLAMBDA[0m
  expression.  Unless you used such a functional substitution, this
  bug fix will not affect you.

  Less important notes:

  The implementation of [47mPRINC$[0m was changed so that it was no longer
  sensitive to the external setting of [47m*print-base*[0m and other Common
  Lisp special variables.

  Typographical errors were fixed in the documentation.")
 (NOTE-2-1
  (RELEASE-NOTES)
  "ACL2 Version 2.1 (December, 1997) Notes

  The identity function [47m[case-split][0m has been added.  It is similar to
  [47m[force][0m but causes an immediate split of the top-level goal on
  whether the indicated hypothesis is true.

  Less important notes:

  Minor bugs in the documentation were fixed.")
 (NOTE-2-2
  (RELEASE-NOTES)
  "ACL2 Version 2.2 (August, 1998) Notes

  Important changes:

  A bug was fixed in the compile command, [47m:comp[0m.  The compiled code
  produced by [47m:comp[0m in previous versions could be wildly incorrect
  because of a confusion between the printer and the reader regarding
  what was the current Lisp [47m*package*[0m.  This bug could manifest
  itself only if you used the [47m:comp[0m command to compile previously
  uncompiled functions while the current package was different from
  [47m\"ACL2\"[0m.  What happened in that situation depended upon what symbols
  were imported into your current package.  The most likely behavior
  is that the compiler would break or complain or the resulting
  compiled code would call functions that did not exist.

  There have been no other important changes to the code.

  However, this release contains some useful new books, notably those
  on the [47mbooks[0m subdirectories [47mcli-misc[0m and [47mihs[0m.  Both have [47mREADME[0m
  files.  The [47mihs[0m books provide support for integer hardware
  specifications.  These books were crucial to Bishop Brock's
  successful modeling of the Motorola CAP.  We thank Bishop for
  producing them and we thank all those who worked so hard to get
  these books released.  We highly recommend the [47mihs[0m books to those
  modeling ALUs and other arithmetic components of microprocessors or
  programming languages.

  In previous versions of ACL2, the arithmetic books, found on
  [47mbooks/arithmetic/[0m, included the addition of several unproved axioms
  stating properties of the rationals that we believed could be
  derived from our ``official'' axioms but which we had not
  mechanically proved.  The axioms were found in the book
  [47mrationals-with-axioms.lisp[0m, which was then used in the uppermost
  arithmetic books [47mtop.lisp[0m and [47mtop-with-meta.lisp[0m.  John Cowles has
  now provided us with ACL2 proofs of those ``axioms'' and so in this
  release you will find both [47mrationals-with-axioms.lisp[0m and
  [47mrationals-with-axioms-proved.lisp[0m.  The former is provided for
  compatibility's sake.  The latter is identical but contains [47mdefthm[0ms
  where the former contains [47mdefaxiom[0ms.  The top-most books have been
  rebuilt using ``[47m-axioms-proved[0m'' book.  Thanks John.

  Less important notes:

  Bishop Brock found a bug in [47mtranslated-acl2-unwind-protectp4[0m.  Jun
  Sawada reported a bug in linear arithmetic that caused us not to
  prove certain trivial theorems concluding with [47m(not (equal i j))[0m.
  We have fixed both.

  We now prohibit definitions that call certain event commands such as
  [47mDEFTHM[0m and [47mTABLE[0m because our Common Lisp implementations of them
  differ from their ACL2 meanings (so that compiled books can be
  loaded correctly and efficiently).

  Minor bugs in the documentation were fixed.")
 (NOTE-2-3
  (RELEASE-NOTES)
  "ACL2 Version 2.3 (October, 1998) Notes

  Important changes:

  Versions of ACL2 preceding this one contain a subtle soundness bug!
  We found a flaw in our detection of [subversive-recursions].  The
  bug allowed some subversive recursions to slip through undetected.

  We believe it would have been difficult to have exploited this flaw
  inadvertently.  In particular, the following five conditions are
  necessary.
  (1) Introduce a constrained function, say [47mf[0m, via an [47mencapsulate[0m.
  (2) In the same encapsulation, define a clique of mutually recursive
  functions.  This clique must be non-[47mlocal[0m and in [47m:logic[0m mode.
  (3) In that mutually recursive clique, use the constrained function
  [47mf[0m (perhaps indirectly) so that the termination argument for the
  clique depends on properties of the [3mwitness[0m for [47mf[0m.  Thus, [47mf[0m or some
  other function dependent upon [47mf[0m, must be used in an argument in a
  recursive call or in a term governing a recursive call.
  Furthermore, the use of [47mf[0m must be such that the termination proof
  cannot be done without exploiting properties of the witness for [47mf[0m.
  Other uses of the constrained functions in the clique are ok.
  (4) Fail to include the exploited properties of [47mf[0m among the
  constraints of the encapsulation.
  (5) Later, outside the encapsulation, explicitly use a functional
  instantiation in which [47mf[0m is replaced by a function not enjoying the
  crucial properties.
  See [subversive-recursions] for details.

  Less important notes:

  We have begun to write some introductory tutorial material for those
  who wish to learn to program in ACL2.  Most of this material is
  HTML-based.  See the Hyper-Card on the ACL2 home page.

  The documentation of [47m[verify-guards][0m was improved to explain why one
  might wish to verify the ``guards'' of a [47mdefthm[0m event.  The missing
  documentation was noticed by John Cowles.

  A bug was fixed in cross fertilization.  The bug caused the system to
  report that it had substituted one term for another when in fact no
  substitution occurred.  The bug was noticed by Bill McCune.")
 (NOTE-2-4
  (RELEASE-NOTES)
  "ACL2 Version 2.4 (August, 1999) Notes

  Important changes:

  We corrected a soundness bug in Version 2.3 related to the handling
  of [47m[immediate-force-modep][0m.  The bad behavior was noticed by Robert
  Krug.  Thanks!

  We corrected a bug that permitted [47m[verify-guards][0m to accept a
  function even though a subfunction had not yet had its guards
  verified.  Thanks to John Cowles for noticing this.

  User defined single-threaded objects are now supported.  See [stobj].

  Less important notes:

  We corrected a bug that prevented the intended expansion of some
  recursive function calls.

  We changed the handling of the primitive function [47m[illegal][0m, which is
  logically defined to be [47mnil[0m but which is programmed to signal an
  error, so that when it is evaluated as part of a proof, it does not
  signal an error.  The old handling of the function prevented some
  guard proofs involving [47m[the][0m or [47m[let][0ms with internal declarations.

  We corrected a bug that permitted some [47mLOCAL[0m [47mDEFAXIOM[0m events to slip
  into certified books.

  We corrected a bug that prevented the correct undoing of certain
  [47mDEFPKG[0m forms.

  Changes were made to support CMU Lisp.  Pete Manolios helped with
  these changes.

  Changes were made to make the make files more compatible with Allegro
  Common Lisp.  Jun Sawada, who has been a great help with keeping
  ACL2 up and running at UT on various platforms, was especially
  helpful.  Thanks Jun.")
 (NOTE-2-5
  (RELEASE-NOTES)
  "ACL2 Version 2.5 (June, 2000) Notes

  Important Changes:

  Concurrent with the release of ACL2 Version 2.5 is the publication of
  two books about ACL2.  See the ``Books and Papers about ACL2 and
  Its Applications'' on the ACL2 Home Page.

  The [47mbooks[0m subdirectory now contains many new certifiable books,
  including solutions to the exercises in the two published books and
  full scripts for the case studies.  See [47mbooks/README.html[0m.

  Improved Unix [47mMakefile[0m support for book certification has also been
  written.  See [47mbooks/README.html[0m.

  The list of symbols in [47m*acl2-exports*[0m has been considerably expanded.
  If you have packages built by importing [47m*acl2-exports*[0m you might
  want to look carefully at the new value of that constant.  The new
  value includes all [47m:logic[0m mode functions as of Version 2.5, as well
  as all documented macros and all built-in theorem names.

  [47m[Include-book][0m and [47m[certify-book][0m were modified to have some
  additional keyword arguments.  It is possible to certify a book
  containing [47m[defaxiom][0m and/or [47m[skip-proofs][0m events and get warning
  messages or errors signaled, according to the settings of these new
  flags.  In addition, it is possible to specify in [47minclude-book[0m
  whether the book must be certified (under penalty of error if not).
  The default values of these new arguments cause warnings to be
  printed rather than errors signaled.

  The above change involved altering the form of certificate files.
  When books certified under previous versions are included, more
  warnings will be generated because these books are considered
  possibly to contain [47mdefaxiom[0m and/or [47mskip-proofs[0m events.

  We anticipate further changes to this aspect of books and consider
  the current mechanisms (for controlling whether warnings or errors
  are signaled) just a prototype.  See also the discussion below of
  ``soundness related'' warnings.  Your suggestions are welcome.

  A discrepancy between ACL2 and Common Lisp was fixed, having to do
  with [47mdeclare ignore[0m.  In past versions of ACL2, a formal parameter
  of a [47mdefun[0m was considered ignored if it was not used in the body,
  the guard or the measure of the [47mdefun[0m.  That meant that a variable
  used only in the guard could not be declared ignored in ACL2; but
  some Common Lisp compilers would complain because the variable was
  not used in the body.  Now, ACL2 considers a variable ignored if it
  is not used in the body.

  ACL2 can now be built in releases 5.0 and later of Allegro Common
  Lisp.  (Other releases of Allegro Common Lisp and of other lisps
  continue to be supported as well.)  This includes Allegro Common
  Lisp running on Windows 98 platforms.  John Cowles helped us do
  some testing and answered questions for us.  Thanks John!

  We incorporated Ruben Gamboa's changes to allow the building of a
  variant, ACL2(r), of ACL2, in which the user can reason about the
  real numbers using non-standard analysis.  See [real].  Note that
  ACL2(r) and ACL2 have different underlying theories, and books
  certified in one system may not be included in the other.  For
  backward compatibility and to ensure a smooth transition, ACL2 is
  built by default, not ACL2(r).  This is a compile-time switch; see
  the makefile for instructions.  There should be no changes to ACL2
  resulting from the capability of building ACL2(r) from the same
  sources.  Also see [acknowledgments] for more on the history of
  ACL2(r).

  A large number of bugs (some affecting soundness) were fixed, and
  many small new features were added.  See below.

  Less Important Changes:

  Some warnings are now considered ``soundness related,'' namely, those
  that advise you that an uncertified book has been included or that
  a book containing [47mDEFAXIOM[0m or [47mSKIP-PROOFS[0m events.  (Technically,
  [47mDEFAXIOM[0ms do not imperil soundness in the proof- theoretic sense,
  though they may imperil the validity of theorems.  But you should
  know when a book has added an axiom to your logic!)  In previous
  versions of ACL2, all warnings were inhibited if the token [47mwarning[0m
  was included in the argument to [47m[set-inhibit-output-lst][0m.  Now,
  soundness related warnings are printed even if [47mwarning[0ms have been
  inhibited.  To inhibit all warnings, supply the token [47mwarning![0m to
  [47mset-inhibit-output-lst[0m.

  Several bugs in [47m[defstobj][0m were fixed, relating to the possibility
  that some of the subfunctions introduced by the [47mdefstobj[0m were
  already defined.

  [47m:[0m[47m[Puff][0m no longer tries to expand [47m[defstobj][0m events.  Previously, the
  attempt would cause a hard error.

  A soundness bug was fixed.  The bug might have been exercised if you
  had an alternative definition (implies hyps (equiv (fn ...) body))
  in which equiv is an equivalence relation other than EQUAL.  In
  this case, calls of fn might have been expanded to body in places
  that were not equiv-hittable.

  An obscure soundness bug was fixed.  The bug was exercised only if
  you had a metafunction with a computed hypothesis (i.e., a ``meta
  hypothesis function''), the hypothesis contained a free variable,
  i.e., a variable not involved in the term being rewritten, and the
  free variable occurred in the output of the metafunction.  The
  possibility of this bug was brought to our attention by Robert
  Krug.

  We fixed a bug in the handling of [47mhide[0m related to the question of
  whether a variable symbol occurs in a term.  The old code did not
  find the variable and could cause the system to throw away a
  hypothesis about it on the grounds that it was never mentioned.
  Rob Sumners helped discover this problem.

  The handling of [47m:[0m[47m[elim][0m rules was generalized, permitting arbitrary
  known equivalence relations instead of merely [47mequal[0m in the
  concluding equality.

  The printing of runes (rule names; see [rune]) used has been made
  \"deterministic,\" both in proof output and in proof attempt
  summaries, by sorting the runes before printing.

  The handling of free variables has been improved for hypotheses such
  as [47m(< 0 X)[0m, and more generally, any hypotheses involving a
  comparison with [47m0[0m (even for example [47m(< X 1)[0m where [47mX[0m is known to be
  an integer, which is handled as [47m(<= X 0)[0m).  Thanks to Robert Krug
  for bringing relevant examples to our attention.

  A new value, [47m:comp[0m, has been implemented for the [47m:load-compiled-file[0m
  keyword of [47m[include-book][0m.  If this value is supplied, then a
  compiled file will always be loaded, even if that requires creating
  the compiled file first.

  The event [47minclude-book[0m now generates a warning when a compiled file
  is expected but not found (see [include-book]).  Formerly, it only
  did so when executed at the top level; it failed to generate the
  warning when executed on behalf of a surrounding [47minclude-book[0m
  command.

  Certain redefinition warnings generated by Allegro Common Lisp have
  been eliminated.

  A new key has been implemented for the [47m[ACL2-defaults-table][0m,
  [47m:bogus-mutual-recursion-ok[0m, set with
  [47m:[0m[47m[set-bogus-mutual-recursion-ok][0m.  Thanks to David Russinoff for
  pointing out the utility of such a key.

  A bug was fixed in [47m[defun-sk][0m that prevented its generated events
  from being accepted when guard verification is being performed.
  Thanks to Bill Young for bringing this problem to our attention.  A
  second bug was brought to our attention by Pete Manolios, which was
  causing certain [47m[defun-sk][0m events to be rejected.  That problem has
  been fixed, and an \"Infected\" warning has also been eliminated.

  The command [47m[good-bye][0m now works with Allegro Common Lisp.

  A low-level bug was fixed that could, for example, cause an error
  such as \"Error: Expected 5 args but received 4 args\" when
  interrupting a [47mlocal[0m event.

  A bug has been fixed in the [proof-builder] related to definition
  expansion.  Thanks to Pete Manolios for bringing this to our
  attention with a simple example.

  A bug has been fixed related to the [47m:[0m[bdd] hint in the presence of
  [equivalence] relations.  Thanks to Pete Manolios for bringing this
  to our attention with a simple example.

  The functions [47m[position][0m and [47m[position-equal][0m formerly required the
  second argument to be a true list.  In accordance with Common Lisp,
  we now also allow the second argument to be a string.  This could
  cause earlier proofs about these functions to fail unless
  [47m[true-listp][0m is known to hold where necessary.

  Robert Krug wrote a patch, which has been incorporated, to prevent
  certain infinite loops that can arise in linear arithmetic.
  Thanks, Robert!

  The macro [47m[let*][0m no longer requires the bound variables to be
  distinct.

  An obscure bug was fixed related to congruence rules.  The bug would
  sometimes cause ACL2 to behave as though no rules (other than
  equality) were available for some argument positions.  Thanks to
  Pete Manolios for bringing this bug to our attention.

  Documentation topics have been added for [47m[hard-error][0m and [47m[prog2$][0m,
  and the documentation for [47m[illegal][0m has been improved.  Thanks to
  Rob Sumners for a useful suggestion in the examples in
  documentation for [47mprog2$[0m and a fix in documentation for [47m[sublis][0m.

  The event form [47m[certify-book][0m was made more secure, in that it can
  now catch attempts to write a book to disk during its
  certification.  Thanks to Rob Sumners for pointing out the
  insecurity of the existing mechanism.

  A Y2K problem was fixed with our applicative handling of dates.

  Accessors and updaters for [47m[stobj][0ms have been made more efficient
  when the underlying lisp is Allegro Common Lisp, by the use of
  appropriate simple array declarations.

  A raw Lisp break had been possible when a certified book that had no
  guard verification was included in a session after
  [47m([0m[47m[set-verify-guards-eagerness][0m[47m 2)[0m.  This has been fixed.

  The keyword command [47m:[0m[47m[comp][0m can now be used to compile only raw Lisp
  functions, excluding executable counterparts, by supplying the
  argument [47m:raw[0m.

  Rewrite rule [47mnth-of-character-listp[0m was removed from source file
  axioms.lisp since it is essentially subsumed by [47mcharacterp-nth[0m.

  Printing has been sped up.  In one example the improvement was over
  50% in both Allegro and GCL.

  We now allow printing in a \"downcase\" mode, where symbols are printed
  in lower case.  All printing functions except [47mprint-object$[0m now
  print characters in lower case for a symbol when the ACL2 state
  global variable [47mprint-case[0m has value [47m:downcase[0m and vertical bars
  are not necessary for printing that symbol.  See [io] for a
  discussion of the macros [47macl2-print-case[0m and [47mset-acl2-print-case[0m.
  The default printing remains unchanged, i.e., symbols are printed
  in upper case when vertical bars are not required.

  A low-level printing function ([47mprin1$[0m) was modified so that it is not
  sensitive to various Common Lisp globals related to printing.  So
  for example, the function [47m[fmt][0m is no longer sensitive to the value
  of Common Lisp global [47m*print-case*[0m.  (The preceding paragraph
  explains how to control the case for printing in ACL2.)

  The definition of [47m[array1p][0m was fixed so that the [47m:maximum-length[0m of
  an array must be strictly greater than the number specified in the
  [47m:dimensions[0m field; they may no longer be equal.  This was always
  the intention; the documentation (see [arrays]) has remained
  unchanged.  The corresponding change was also made to [47m[array2p][0m.
  Allegro Common Lisp formerly caused an error when [47m[compress1][0m was
  called on an array where the numbers above were equal; now, we get
  a guard violation instead, which is appropriate.

  In the context of theories, a name now represents not just the
  corresponding [47m:definition[0m [rune], as it has done in earlier
  versions of ACL2, but also the corresponding [47m:[0m[47m[induction][0m rune.
  See [theories] for a discussion of runic designators.  Most users
  will rarely, if ever, notice this change.  One situation where this
  change will make a difference is after executing [47m(in-theory
  (current-theory 'foo))[0m followed by [47m(in-theory (enable bar))[0m, where
  function [47mbar[0m is introduced after event [47mfoo[0m, and [47mbar[0m is recursively
  defined.  The latter [47m[in-theory][0m form now enables the rune
  [47m(:induction bar)[0m, which implies that the prover can use the
  induction scheme stored at definition time for [47mbar[0m.  Formerly, the
  rune [47m(:induction bar)[0m was not enabled by [47m(in-theory (enable bar))[0m,
  and hence the induction scheme for [47mbar[0m was ignored even when
  explicit [47m:induct[0m hints were supplied.

  You may now supply [47m[xargs][0m keyword pair [47m:normalize nil[0m in order to
  prevent certain definitions from ``hanging'' when there are many
  [47mif[0m-subexpressions.  see [defun].

  We now translate type declarations of [47mreal[0m into guards, as we have
  already done for other types such as [47mrational[0m.  For example,
  [47m(declare (type real x))[0m generates the [guard] [47m(rationalp x)[0m.  See
  [type-spec].

  The theorem prover now behaves reasonably under the combination of
  specifying a value of [47mt[0m both for [47m:[0m[47m[otf-flg][0m and for a hint
  [47m:do-not-induct[0m.  Previously, it aborted the first time it would
  have otherwise pushed a goal for induction, but now, it will
  continue and wait until all induction subgoals have been pushed
  before it aborts.

  We changed slightly the definition of [47m[round][0m.  However, we believe
  that the new definition is equivalent to the old.

  The definition of Common Lisp function [47m[substitute][0m has been added.

  The following changes have been made in the use of file names within
  ACL2.  We thank Warren Hunt and John Cowles for running some tests
  of these changes on Macintosh and Windows 98 platforms
  (respectively).

      (1) Names of directories and files now use a syntax like that used
      for Unix (trademark of AT&T), where directories are separated
      using the ``[47m/[0m'' character even when the operating system is not
      Unix or Linux.  See [pathname].  ACL2 also continues to support
      its notion of [3mstructured pathnames[0m from Version 2.4 and before,
      but might not do so in future releases and hence no longer
      documents such syntax.

      (2) The command [47m:[0m[47m[set-cbd][0m may now take a relative pathname as an
      argument.

      (3) When the macro [47m[ld][0m is given a file name as a value for
      [47m[standard-oi][0m, then if that file name is a relative pathname it
      refers to the result of prepending the connected book directory
      (see [pathname], see [cbd], and see [set-cbd]) in order to
      obtain an absolute pathname.  Similarly for the [47mld[0m specials
      [47m[standard-co][0m and [47m[proofs-co][0m.

  It is no longer necessary to issue [47m:[0m[47m[set-state-ok][0m[47m t[0m if you include a
  [stobj] declaration for [47m[state][0m, for example:

    (declare (xargs :stobjs state))

  See [declare-stobjs].

  The [proof-builder] has been cleaned up a bit, including the
  documentation and the capability (once again) to define pc-macro
  commands (see [define-pc-macro]) and proof-builder meta commands
  (see [define-pc-meta]).

  Recall that events generate summaries that include a line beginning
  with ``[47mWarnings:[0m'', which is followed (on the same line) by zero or
  more brief strings that summarize the warnings generated by that
  event.  Formerly, this warnings summary for an [47m[encapsulate][0m or
  [47m[include-book][0m event did not include the summary strings for
  warnings generated by subsidiary events.  This has been fixed.

  Macro [47m[cw][0m has been documented and now expands to a call of a
  [47m;[0m[47m[logic][0m mode function.  See [cw] for a way to print to the screen
  without having to involve the ACL2 [47m[state][0m.  Thanks to Rob Sumners
  for suggesting that we document this useful utility.

  Functions [47mduplicates[0m, [47madd-to-set-equal[0m, [47mintersection-eq[0m, [47mevens[0m, and
  [47modds[0m are now [47m:[0m[47m[logic][0m mode functions.")
 (NOTE-2-5{R}
  (RELEASE-NOTES)
  "ACL2 Version 2.5(r) (June, 2000) Notes

  Important changes to non-standard version:

  Please see [note-2-5] for changes to Version 2.5 of ACL2.  We hope to
  write more documentation for ACL2(r) in the future.")
 (NOTE-2-6
  (RELEASE-NOTES)
  "ACL2 Version 2.6 (November, 2001) Notes

  Because of the large number of modifications, we have divided up the
  Version 2.6 notes into the following subtopics.

    * New functionality (see [note-2-6-new-functionality])

    * Changes in proof engine (see [note-2-6-proofs])

    * Changes in rules and definitions (see [note-2-6-rules])

    * Guard-related changes (see [note-2-6-guards])

    * proof-builder changes (see [note-2-6-proof-builder])

    * System-level changes (see [note-2-6-system])

    * Other (minor) changes (see [note-2-6-other])


Subtopics

  [Note-2-6-guards]
      ACL2 Version 2.6 Notes on Guard-related Changes

  [Note-2-6-new-functionality]
      ACL2 Version 2.6 Notes on New Functionality

  [Note-2-6-other]
      ACL2 Version 2.6 Notes on Other (Minor) Changes

  [Note-2-6-proof-builder]
      ACL2 Version 2.6 Notes on proof-builder Changes

  [Note-2-6-proofs]
      ACL2 Version 2.6 Notes on Changes in Proof Engine

  [Note-2-6-rules]
      ACL2 Version 2.6 Notes on Changes in Rules and Constants

  [Note-2-6-system]
      ACL2 Version 2.6 Notes on System-level Changes")
 (NOTE-2-6-GUARDS
  (NOTE-2-6)
  "ACL2 Version 2.6 Notes on Guard-related Changes

  When you [47m[declare][0m that a function treats certain formals as
  [47m:[0m[47m[stobj][0m[47ms[0m, the [guard] of the function is automatically extended to
  include the corresponding stobj-recognizer calls.  For example, if
  a definition includes [47m(declare (xargs :stobjs (ST)))[0m then the guard
  of the function is changed by the addition of the conjunct [47m(ST-P
  ST)[0m.

  One impact of this is that if you use the built-in ACL2 [47m[state][0m as a
  formal parameter of a function, [47m(STATE-P STATE)[0m is added to the
  guard.  This may introduce a guard where there was none in previous
  versions of the system.  In older versions, therefore, no attempt
  would be made to [47m[verify-guards][0m, while in the new version, we
  would attempt guard verification.  You may wish to add [47m(declare
  (xargs :verify-guards nil))[0m to such definitions.

  A related change affects users who do not use stobjs or [47mstate[0m.  In
  previous versions of the system --- as now --- a [47mtype[0m declaration
  extended the guard you provided explicitly.  Thus, if you wrote
  [47m(declare (type integer n))[0m then [47m(INTEGERP n)[0m was added to your
  guard.  This is still the case and [47m:stobjs[0m recognizers are
  similarly added.  But in older versions of the system we ``added''
  the conjuncts without checking whether they were already present in
  the guard you provided.  This sometimes produced such guards as
  [47m(and (integerp n) (integerp n))[0m where the first was produced by
  your [47mtype[0m declaration and the second was your [47m:guard[0m.  We now
  eliminate redundant conjuncts; this may rearrange the order of the
  conjuncts.

  The guard conjectures for functions using [47mstobj[0ms have been simplified
  somewhat by taking advantage of the syntactic restrictions checked
  for single-threaded objects.

  The following functions have been modified so that character and
  string arguments are restricted to standard characters.  (See
  [standard-char-p] and see [standard-char-listp].)

      [47m[upper-case-p][0m [47m[lower-case-p][0m [47m[char-upcase][0m [47m[char-downcase][0m
      [47mstring-downcase1[0m [47m[string-downcase][0m [47mstring-upcase1[0m
      [47m[string-upcase][0m [47m[char-equal][0m [47mstring-equal1[0m [47m[string-equal][0m

  Also, function [47mstandard-string-alistp[0m replaces function
  [47mstring-alistp[0m, with concomitant changes in the guard to
  [47m[assoc-string-equal][0m, and in variable [47m*acl2-exports*[0m.  Also, lemma
  [47mstandard-string-alistp-forward-to-alistp[0m replaces lemma
  [47mstring-alistp-forward-to-alistp[0m.  There is a new lemma
  [47mstandard-char-p-nth[0m, which has also been added to [47m*acl2-exports*[0m.

  The guard had been inadvertently omitted from the definition of the
  function [47m[substitute][0m (and its subroutine [47msubstitute-ac[0m).  This
  omission has been corrected; also, the guard is slightly stronger
  than the documentation had claimed (and that has been corrected).")
 (NOTE-2-6-NEW-FUNCTIONALITY
  (NOTE-2-6)
  "ACL2 Version 2.6 Notes on New Functionality

  A fundamental change is the provision of the ``nu-rewriter'' for
  simplifying expressions composed of [47mNTH[0m, [47mUPDATE-NTH[0m, and
  [47mUPDATE-NTH-ARRAY[0m applications and [47mLET[0m expressions and other calls
  of non-recursive functions or [47mLAMBDA[0m expressions involving those
  symbols.  The nu-rewriter applies the obvious rewrite rule for [47m(NTH
  i (UPDATE-NTH j v s))[0m and the analogous rule for [47mUPDATE-NTH-ARRAY[0m.
  See nu-rewriter.  The nu-rewriter can be enabled with
  [47mset-nu-rewriter-mode[0m.

  A new flag has been added to the [47mxargs[0m of [47m[defun][0m permitting the
  declaration that the function is [47mnon-executable[0m.  The usage is
  [47m(declare (xargs :non-executable t))[0m and the effect is that the
  function has no executable counterpart.  On the positive side: the
  function is permitted to use single-threaded object names and
  functions arbitrarily, as in theorems rather than as in executable
  definitions.  Such functions are not permitted to declare any names
  [47m:[0m[47m[stobj][0m[47ms[0m but accessors, etc., may be used, just as in theorems.

  A new flag has been added to permit the system to abbreviate output
  by introducing [47mLET*[0m notation identifying common subterms.  The
  formula being proved is not affected; this flag changes its
  displayed form only.  See [set-let*-abstractionp].

  A ``raw mode'' has been added, primarily for faster loading of
  applications.  see [set-raw-mode].

  Functions [47m[alphorder][0m and [47m[lexorder][0m have been put in [47m:[0m[47m[logic][0m mode.
  [47mLexorder[0m is now a total order ordering of the ACL2 universe, and
  theorems are included to that effect.  Thanks to Pete Manolios for
  suggesting the idea and providing events to use, and to Rob Sumners
  for assistance with some modifications.  See also the new book
  [47mbooks/misc/total-order[0m for an irreflexive total order.

  The ACL2 user can now make system calls to the host operating system.
  See [sys-call] and see [sys-call-status].  Thanks to Rob Sumners
  for working out this idea with Pete Manolios and Robert Krug, who
  we also thank, and for working out the implementation with us.

  It is no longer required to use absolute [pathname]s in
  [47m[include-book][0m forms that have been executed before a
  [47m[certify-book][0m.  Any relative pathname strings in such contexts
  will be expanded into absolute pathnames before they are saved in
  the [47m[portcullis][0m of the [47m[certificate][0m of the book being certified.

  ACL2 can now be built on top of Allegro Common Lisp 6.0, and also on
  Windows platforms on top of Allegro Common Lisp and GCL.  Thanks to
  Pete Manolios and Vinay K. Siddhavanahalli for their help with
  Windows.

  Rob Sumners has designed and provided an initial implementation for
  two improvements to [47m[defstobj][0m (also see [stobj]).  First, array
  fields can now be resized.  Resize and length functions are
  provided for array fields, which can be used to resize stobj array
  fields dynamically.  The recognizers for array fields have been
  simplified to accommodate this change, so that they only check that
  each element of the array field has the specified type.  Second,
  performance has been improved for stobjs with a large number of
  fields, by changing their Common Lisp implementation to store the
  fields in a simple vector instead of a list.

  Now [stobj]s may be bound locally; see [with-local-stobj].  Thanks to
  Rob Sumners, who encouraged us to implement this capability, was an
  early user of it, and participated usefully in discussions on its
  design.

  New functions [47m[fms!][0m, [47m[fmt!][0m, and [47m[fmt1!][0m are the same as their
  respective functions without the ``[47m![0m,'' except that the ``[47m![0m''
  functions are guaranteed to print forms that can be read back in
  (at a slight readability cost).

  We added [47m[extended-metafunctions][0m, metafunctions which allow [47m[state][0m
  and context sensitive rewriting to some extent.  We thank Robert
  Krug for pushing for and on this idea.

  The documentation has been improved.  In particular, a new
  documentation topic provides a gentle introduction to ACL2 [47m[arrays][0m
  --- see [arrays-example] --- and additional documentation has been
  provided for getting started with proof trees in emacs --- see
  [proof-tree].

  New Makefile targets [47mfasl[0m and [47mo[0m have been added to the [47mbooks/[0m
  directory of the distribution.  For example, you might first
  certify books using an ACL2 built on top of GCL (which creates
  compiled files with suffix [47mo[0m).  Then, when standing in the [47mbooks/[0m
  directory, you might execute the command

      make fasl ACL2=my-allegro-acl2

  which will create compiled ([47m.fasl[0m) files for Allegro Common Lisp,
  assuming that [47mmy-allegro-acl2[0m starts up an ACL2 built on that
  Common Lisp.

  The macro [47m[let*][0m now allows variables to be declared ignored.  See
  [let*] and see [let].

  The user may now control backchaining.  This feature was designed and
  primarily implemented by Robert Krug (though the authors of ACL2
  are responsible for any errors); thanks, Robert!  See
  [backchain-limit].

  It is now possible to ``slow down'' the rate at which case splits are
  generated by the simplifier.  See [set-case-split-limitations].

  Accesses to [stobj]s using [47m[nth][0m or [47m[update-nth][0m are now displayed
  using symbolic constants instead of numeric indices.  For example,
  given the event

    (defstobj foo a b :renaming ((b c)))

  then the term [47m(nth 0 foo)[0m will be displayed (for example, during
  proofs) as [47m(nth *a* foo)[0m while [47m(nth 1 foo)[0m will be displayed as
  [47m(nth *c* foo)[0m.  The [47m[defstobj][0m event now correspondingly introduces
  a [47m[defconst][0m event for each field accessor function, introducing a
  constant whose name is obtained from the accessor's name by
  prefixing and suffixing a ``[47m*[0m,'' as in the example above: accessor
  [47ma[0m generates [47m(defconst *a* 0)[0m and accessor [47mc[0m generates [47m(defconst *c*
  1)[0m. See [nth-aliases-table] for how to extend this feature for
  alternate names of [stobj]s.

  Computed hints have been improved.  It is now possible to detect
  within a computed hint whether the goal clause is stable under
  simplification; it is also possible for a computed hint to change
  the list of available hints.  See [computed-hints].

  It is now possible to provide ``default hints'' that are appended to
  the hints explicitly provided.  See [set-default-hints].

  Using computed hints (see [computed-hints]) and default hints (see
  [set-default-hints]) it is possible to implement a book that
  supports ``priority phased simplification.'' Using this book you
  can assign priorities to your rules and cause the theorem prover to
  simplify each goal maximally under all the rules of one priority
  before enabling rules of the next priority.  See
  [47mbooks/misc/priorities.lisp[0m.

  The macro [47m[defabbrev][0m has been improved to allow [47m[declare][0m forms and
  documentation strings and to do more error-checking.  Thanks to Rob
  Sumners for designing this enhancement and providing the first
  implementation.  See [defabbrev].

  Further changes were made to support CMU Lisp.  Wolfhard Buss helped
  with these changes.

  A new table was added that is used when printing proof output, so
  that nests of right-associated calls of a binary function are
  replaced by corresponding macro calls, as has been the case for
  [47m[binary-+][0m and [47m[+][0m, [47m[binary-append][0m and [47m[append][0m, and so on.  See
  [add-binop].

  Operators [47m[logand][0m, [47m[logior][0m, [47m[logxor][0m, and [47m[logeqv][0m are now macros
  (formerly, they were functions) that call corresponding binary
  functions (e.g., [47mbinary-logand[0m) defined in source file
  [47m\"axioms.lisp\"[0m.  Thanks to Rob Sumners for this enhancement.  Proof
  output will however continue to show calls of [47m[logand][0m, [47m[logior][0m,
  [47m[logxor][0m, and [47m[logeqv][0m.

  Function [47m([0m[47m[allocate-fixnum-range][0m[47m fixnum-lo fixnum-hi)[0m sets aside
  more \"permanent\" fixnums in GCL.

  ACL2 now runs under [47mCLISP[0m.  Thanks to Wolfhard Buss and Sam Steingold
  for their assistance with the port.

  Michael ``Bogo'' Bogomolny has created a search engine, accessible
  from the ACL2 home page.  For that purpose he modified the HTML
  translator to create one file per topic (a good idea in any case).
  Thanks, Bogo!

  An emacs file of potential (but optional) use for ACL2 users may be
  found in [47memacs/emacs-acl2.el[0m.  In particular, this file supports
  the use of proof trees (see [proof-tree]).

  Some [books] have been added or modified.  In particular, Robert Krug
  has contributed [47mbooks/arithmetic-2/[0m, which provides an alternative
  to the existing collection of books about arithmetic,
  [47mbooks/arithmetic/[0m.  For a discussion of the distributed books see
  the link to [47mREADME.html[0m in the installation instructions.")
 (NOTE-2-6-OTHER
  (NOTE-2-6)
  "ACL2 Version 2.6 Notes on Other (Minor) Changes

  Warning strings are now case-insensitive.  See
  [set-inhibit-warnings].

  ACL2 causes a warning when an [in-theory] hint or event causes a
  0-ary function's definition to be disabled but its
  [47m:[0m[47m[executable-counterpart][0m to be enabled.

  A minor modification has been made to [47m[defstobj][0m that can have a
  positive impact on performance in Allegro Common Lisp.  (For Lisp
  hackers: the stobj name was formerly declared special, and that was
  disabling Allegro's tail-merging routing for compilation of some
  recursive functions using stobjs.)  The downside is that stobj
  names can no longer be evaluated in raw Lisp.  However, raw Lisp is
  not the right place to be evaluating ACL2 forms anyhow; see
  [set-raw-mode].  We thank Rob Sumners for bringing this issue to
  our attention.

  Before Version 2.6, there has been the following problem with
  [47m[defstub][0m and [47m[encapsulate][0m in the case that the current package is
  not the ACL2 package.  If a [signature] was specified using the
  symbol [47m=>[0m, then that symbol had to have been imported into the
  current package from the ACL2 package when the current package was
  defined.  There are no longer any package restrictions on the use
  of [47m=>[0m.  Thanks to John Cowles for bringing this problem to our
  attention.

  Bugs in [47m[defun-sk][0m have been fixed.  [47mDefun-sk[0m forms introducing
  functions of no arguments were failing to be admitted, for example:
  [47m(defun-sk always-p1 () (forall (x) (p1 x)))[0m.  Thanks to John Cowles
  for bringing this problem to our attention.  Also, [47mdefun-sk[0m failed
  on an example in the documentation (see
  [tutorial4-defun-sk-example]), as pointed out by Matyas Sustik;
  this bug has been fixed as well.

  The trace mechanism has been fixed to handle [stobj]s, and to avoid
  the printing of so-called [3menabled structures[0m.

  The [47m[brr][0m command [47m:type-alist[0m now produces more readable output.

  An [47m[include-book][0m of an uncertified book no longer loads an
  associated compiled file.

  We added a few checks to make sure that the underlying lisp is
  suitable, for example checking that the reader is case-insensitive
  and reads in symbols with upper-case names where appropriate.

  We now warn when forcing (see [force]) or immediate force mode (see
  [immediate-force-modep]) change state between enabled and disabled.
  Also see [enable-immediate-force-modep] and see
  [disable-immediate-force-modep] for information about these new
  macros, which may be used to control immediate force mode.

  We have eliminated the use of a low-level raw Lisp constant,
  [47m*most-recent-multiplicity*[0m.  Our test suite saw a speed-up of
  approximately 2% as a result for an ACL2 image built on GCL (but no
  significant speed-up for an ACL2 image built on Allegro Common
  Lisp).  We thank Rob Sumners for suggesting this improvement.

  Fixnum declarations are now realized as [47m(signed-byte 29)[0m instead of
  [47m(signed-byte 27)[0m.  We check that the underlying Common Lisp
  recognizes objects of type [47m(signed-byte 29)[0m as fixnums, with the
  exception of CLISP, which is said to have an efficient bignum
  implementation.

  A new documentation topic [functional-instantiation-example]
  illustrates functional instantiation.

  A bug has been fixed in the monitoring of runes (see [monitor]).
  Thanks to Dave Greve for sending an example that clearly showed the
  problem.

  A warning is now issued when it is detected that a
  [47m:[0m[47m[type-prescription][0m rule may not be as strong as it appears
  because it is not sufficient to prove itself by type reasoning.

  An error is caused for rules of class [47m:[0m[47m[meta][0m when the function
  symbol [47mIF[0m is among the [47m:trigger-fns[0m.  ([47mIF[0m was ignored anyhow; the
  point of this change is to avoid misleading the user.)

  A minor bug has been fixed in [47m:[0m[47m[pr][0m, evident for example if this
  command was applied to [47mIF[0m.

  A minor hole in [47m:[0m[47m[set-bogus-mutual-recursion-ok][0m did not permit the
  acceptance of [47m[mutual-recursion][0m forms that include constant
  function definitions.  This has been fixed.  Thanks to Eric Smith
  for coming up with a simple example illustrating the problem.

  The temporary files \"TMP.lisp\" and \"TMP1.lisp\" written out by [47m:[0m[47m[comp][0m
  are now written to the connected book directory (see [cbd]).

  Previously, the Allegro compiler was not eliminating tail recursion
  for executable counterparts of functions, because of the way one of
  its flags had been set.  As a result, calls of functions whose
  guards had not been verified could run out of stack space when this
  was not necessary.  This situation has been fixed.

  Executable counterparts could have slow array accesses.  This has
  been fixed (specifically, constants are no longer replaced with
  their values in the definitions of executable counterparts).

  Various improvements have been made to the documentation.  Thanks in
  particular to Eric Smith for pointing out a numbers of places where
  fixes were in order.

  File \"mcl-acl2-startup.lisp\" has been updated, thanks to feedback
  from Philippe Georgelin.

  Inefficiencies in GCL fixnum computations were remedied for macros [47m+f[0m
  and [47m*f[0m.  Thanks to Rob Sumners for pointing out this issue.")
 (NOTE-2-6-PROOF-BUILDER
  (NOTE-2-6)
  "ACL2 Version 2.6 Notes on proof-builder Changes

  The proof-builder command [47m=[0m, when used with no arguments, now reports
  which hypothesis is being used.

  The output from [proof-builder] command [47mtype-alist[0m has been improved.

  A slight change has been made to the [proof-builder] for commands
  [47mpromote[0m, [47mcasesplit[0m, [47mequiv[0m, and [47m=[0m, so that terms of the form [47m(if x
  nil y)[0m are recognized as conjunctions, [47m(and (not x) y)[0m.  Thanks to
  Pete Manolios for suggesting that we consider such a change.

  There is a new [proof-builder] command [47mprint-all-concs[0m that prints
  all the conclusions of the unproved goals.

  A new [47m[proof-builder][0m command, [47mrunes[0m, has been added.  It reports the
  [rune]s that have participated in the interactive proof up to the
  current point.")
 (NOTE-2-6-PROOFS
  (NOTE-2-6)
  "ACL2 Version 2.6 Notes on Changes in Proof Engine

  Certain optimizations are performed when converting terms to clausal
  form.  For example, [47m(< 0 1)[0m is known to be [47mt[0m, [47m(HARD-ERROR ctx str
  alist)[0m is known to be [47mnil[0m, and [47m(INTEGERP n)[0m is known to imply
  [47m(RATIONALP n)[0m.

  In earlier versions of ACL2, the conversion of a term to clausal form
  expanded [47mLAMBDA[0m applications.  That may no longer occur.  Some
  proofs may slow down (or fail) because your [47mLAMBDA[0m-expressions are
  not expanded away when you ``expected'' them to be.

  Robert Krug found a soundness bug in our linear arithmetic package.
  The bug was caused by the derivation of an equation from two
  inequalities without taking adequate precautions to ensure that
  both sides of the inequalities were numeric.  Robert also kindly
  provided a fix which we adopted.  Thanks Robert!

  We fixed a bug that could prevent the application of a metatheorem.

  A bug has been fixed that had caused bogus forcing rounds (see
  [forcing-round]).  The bug could occur when the hypothesis of a
  rule was forced (see [force]) before the prover decided to start
  over and prove the original goal by induction.  Thanks to Rob
  Sumners for drawing our attention to this problem.

  Some low-level fixes have been made that prevent certain infinite
  loops, based on reports by users.  We thank Yunja Choi, Matt
  Wilding, and Pete Manolios for reporting such problems.

  An obscure potential soundness hole has been fixed by redoing the way
  evaluation takes place in the ACL2 loop and during theorem proving.
  We expect that users will see no difference based on this change.
  (Those interested in the details can see the long comment ``Essay
  on Evaluation in ACL2'' in source file interface-raw.lisp.)

  A small change was made in computation for a heuristic that controls
  backchaining.  This will speed up proofs dramatically in a very few
  cases but should have a very small impact in general.

  The simplifier has been modified to avoid eliminating hypotheses of
  goals that can be established by contextual (specifically,
  type-set) reasoning alone.  We believe that this change will
  generally strengthen ACL2's reasoning engine, although on rare
  occasions a lemma that formerly was provable may require user
  assistance.  Thanks to Robert Krug for suggesting this change and
  providing its implementation.

  Case splits are now limited, by default.  This may allow some proof
  attempts to provide output where previously the prover would appear
  to ``go out to lunch.'' For a more complete discussion, including
  instructions for how users can control case splitting, see
  [set-case-split-limitations].

  A bug has been fixed in the handling of [47m:[0m[47m[type-prescription][0m rules by
  the [bdd] package.  Thanks to Rob Sumners for discovering this bug
  and supplying a helpful example.

  ACL2 may now use the built-in induction scheme for a function symbol
  even if that function symbol is disabled.  Formerly, if a function
  symbol was disabled then its induction scheme was only considered
  if an explicit induction hint was supplied, other than [47m:induct t[0m.

  We eliminated the rule-class [47mlinear-alias[0m.  This rule class was
  seldom used and complicated the linear arithmetic decision
  procedure in ways that made it difficult to extend to handle some
  non-linear special cases.  The only use of the rule-class that we
  know of was in our own [47mNqthm[0m books, which were an attempt to
  provide an embedding of the Nqthm logic and theorem prover into
  ACL2.  But that facility was also practically never used, as far as
  we know.  So both [47mlinear-alias[0m rules and the [47mNqthm[0m books have been
  eliminated.

  In earlier versions of ACL2, when the [47mIF[0m-form of [47m(AND p q)[0m was
  assumed true --- as when rewriting the [47malpha[0m expression in [47m(IF (AND
  p q) alpha beta)[0m --- the assumption mechanism did not deduce that [47mp[0m
  and [47mq[0m are true, only that their conjunction, in its [47mIF[0m-form, is
  true.  This has long been known as a deficiency in both ACL2 and
  the earlier Nqthm but it was tedious to do better when one
  considered the full range of [47mIF[0m-forms one might encounter in the
  test of another [47mIF[0m.  Rather than code all the cases, we just waited
  until clausification got rid of them.  Robert Krug developed a
  pretty nice treatment of the general case and we added it in this
  version.  This also involved a surprising number of changes
  elsewhere in the system because the improved handling of
  assumptions caused the theorem prover often to ``erase'' hypotheses
  provided by [47m:use[0m hints because it could simplify them to [47mt[0m.  Thank
  you Robert!

  In response to a suggestion from Robert Krug, we added [47mmfc-ap[0m so that
  extended metafunctions can take advantage of linear arithmetic.
  See [extended-metafunctions].

  There is less delay in printing goals.  In previous versions, a goal
  was not printed until its subgoals were created (or the goal was
  proved).  Now, the goal is printed essentially as soon as it is
  created.

  A small technical change has been made in the function [47m[term-order][0m,
  to give priority on the function symbol count over the weighting of
  constants.  So for example, while previously the term [47m(f)[0m preceded
  the constant 2, that is no longer the case.  If this change is
  noticed at all, it will probably be noticed in how so-called
  [3mpermutative[0m rewrite rules are applied; see [loop-stopper].  Thanks
  to Robert Krug for suggesting this improvement and providing part
  of the implementation.")
 (NOTE-2-6-RULES
  (NOTE-2-6)
  "ACL2 Version 2.6 Notes on Changes in Rules and Constants

  The following symbols have been added to the list constant
  [47m*common-lisp-specials-and-constants*[0m: [47mREPLACE[0m, [47mFILL[0m, [47mCHARACTER[0m, [47m=[0m,
  [47mBREAK[0m, and [47mPRIN1[0m.  This was done in support of ports to Allegro 6.0
  and Windows platforms (see [note-2-6-new-functionality]).

  The list of symbols in [47m*acl2-exports*[0m has been modified, for example
  to include [47mshow-accumulated-persistence[0m and the legal arguments to
  [47m[set-inhibit-output-lst][0m.

  Functions [47m[zp][0m and [47m[zip][0m are now handled slightly differently.  They
  are are now disabled, but each comes with a [47m:[0m[47m[rewrite][0m rule that
  allows their expansion on non-variable terms, and also with a
  [47m:[0m[47m[compound-recognizer][0m rule that avoids the need for opening up
  these functions when applied to variables.  The resulting behavior
  should be very similar to the behavior of previous versions, except
  that case splits will be avoided when these functions are applied
  to variables.

  Function [47mstandard-string-alistp[0m replaces function [47mstring-alistp[0m.  For
  further discussion, see [note-2-6-guards].

  Rules of class [47m:[0m[47m[rewrite][0m whose conclusion is a term of the form
  [47m(equal lhs rhs)[0m have always been stored in the expected way: [47mlhs[0m
  rewrites to [47mrhs[0m.  This way of storing [47m:rewrite[0m rules has been
  extended to allow [47m[=][0m, [47m[eq][0m, or [47m[eql][0m in place of [47m[equal][0m.

  Rewrite rule [47mnth-update-nth[0m, in source file [47maxioms.lisp[0m, has been
  strengthened.

  A new rewrite rule [47mequal-constant-+[0m has been added to the book
  [47marithmetic/equalities[0m.  This should generally be a beneficial
  change, but existing proofs involving the arithmetic books could
  conceivably be affected.

  Function [47m[symbol-package-name][0m and constant [47m*main-lisp-package-name*[0m
  have undergone small changes.  This change should rarely be noticed
  by users and is discussed elsewhere; see [note-2-6-system].

  We mention here that proofs involving [stobj]s may need to be
  modified because of changes in auxiliary functions generated by
  [47m[defstobj][0m.  (These changes were made in support of a new resizing
  capability, mentioned elsewhere in these release notes; see
  [note-2-6-new-functionality].

  In the distributed book directory [47mbooks/arithmetic/[0m, the book
  [47mrationals-with-axioms-proved.lisp[0m has been renamed [47mrationals.lisp[0m.

  (ACL2(r) only) Rewrite rules [47mrealp-+[0m, [47mrealp-*[0m, [47mrealp-unary--[0m, and
  [47mrealp-unary-/[0m have been added in analogy to existing rules
  [47mrationalp-+[0m, [47mrationalp-*[0m, [47mrationalp-unary--[0m, and [47mrationalp-unary-/[0m.
  Thanks to Jun Sawada for suggesting this change.

  The definition of [47m[aref1][0m has been modified slightly.  Previously, if
  [47m*my-a*[0m were an array then [47m(aref1 'some-name *my-a* :header)[0m would
  evaluate to the [47mcdr[0m of the [47m[header][0m of [47m*my-a*[0m rather than to its
  [47m[default][0m.  See [arrays].

  Changes have been made in the [47mihs[0m books, based on suggestions from
  Jun Sawada, that support its use with ACL2(r) (see [real]).  The
  primary change is to replace calls of [47m[rationalp][0m with calls of
  [47m[real/rationalp][0m, which should have no effect on users of standard
  ACL2.")
 (NOTE-2-6-SYSTEM
  (NOTE-2-6)
  "ACL2 Version 2.6 Notes on System-level Changes

  We modified the tracking of [47m[skip-proofs][0m events and the use of
  [47m[state][0m global [47mld-skip-proofsp[0m in order to avoid some soundness
  issues.  For example, [47m[skip-proofs][0m events buried in
  locally-included books are now tracked.  The ``Essay on
  Skip-proofs'' in source file [47maxioms.lisp[0m gives several examples of
  dicey behavior that is no longer supported.

  We fixed a problem with some of the makefiles, so that recursive
  invocations of `make' now use the version of `make' specified on
  the command line.

  Files were fixed to help non-Unix/Linux users with book
  certification.  Thanks to John Cowles for finding some problems and
  suggesting fixes to [47mbooks/certify-numbers.lisp[0m,
  [47mbooks/arithmetic/certify.lsp[0m, and [47mbooks/cowles/certify.lsp[0m.  We
  thank Scott Burson for noticing and fixing some other such
  problems.  Moreover, a bdd test was being ignored entirely in
  Version 2.5; this problem has been fixed as well.

  A minor change in system function save-acl2-in-allegro will allow
  this function to continue to work in Allegro CL versions starting
  (someday) with 10.0.  Thanks to Art Flatau for suggesting such a
  fix.

  The [47mbooks/case-studies/[0m directory has been removed.  These books are
  in support of the first (1998) ACL2 workshop, and are accessible
  via the {ACL2 home page |
  http://www.cs.utexas.edu/users/moore/acl2/}.  Also, the
  [47mbooks/cli-misc[0m directory has been renamed [47mbooks/misc[0m, and the
  [47mbooks/nqthm[0m directory has been removed.

  The notion of ACL2 version has been slightly modified to catch
  unsoundness due to implementation dependencies.  See [version].
  Another change to eliminate such unsoundness is that built-in
  symbols now have a [47m[symbol-package-name][0m of [47m\"COMMON-LISP\"[0m;
  formerly, this string was [47m\"LISP\"[0m for ACL2 images built on GCL.  See
  [symbol-package-name].  At a low level, the (undocumented) constant
  [47m*main-lisp-package-name*[0m is now [47m\"COMMON-LISP\"[0m; before, it was
  [47m\"LISP\"[0m for GCL.")
 (NOTE-2-6{R}
  (RELEASE-NOTES)
  "ACL2 Version 2.6(r) (November, 2001) Notes

  Important changes to non-standard version: None since Version 2.5.

  Please see [note-2-6] for changes to Version 2.6 of ACL2.  We hope to
  write more documentation for ACL2(r) in the future.")
 (NOTE-2-7
  (RELEASE-NOTES)
  "ACL2 Version 2.7 (November, 2002) Notes

  The Version_2.7 notes are divided into the subtopics below.  Here we
  give only a brief summary of a few of the changes that seem most
  likely to impact existing proofs.  Not included in this brief
  summary, but included in the subtopics, are descriptions of
  improvements (including bug fixes and new functionality) that
  should not get in the way of existing proof efforts.

  In particular, please see [note-2-7-new-functionality] for discussion
  of a number of new features that you may find useful.

  Acknowledgments and elaboration, as well as other changes, can be
  found in the subtopics listed below.

  Bug fixes (see [note-2-7-bug-fixes])

    * Three soundness bugs were fixed.  These bugs were probably rarely
      hit, so users may well not notice these changes.

    * [47m[Certify-book][0m now requires [47m:skip-proofs-ok t[0m (respectively,
      [47m:defaxioms-okp t[0m) if there are [47m[skip-proofs][0m (respectively,
      [47m[defaxiom][0m) events in the book or any included sub-books.

    * When [47m:by[0m hints refer to a definition, they now use the original body
      of that definition rather than the simplified (``normalized'')
      body.

    * When [47m[ld][0m is applied to a stringp file name, it now temporarily sets
      the connected book directory (see [cbd]) to the directory of
      that file while evaluating forms in that file.

  New functionality (see [note-2-7-new-functionality])

    * ACL2 now works harder to apply [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules with
      free variables in the hypotheses.  See
      [note-2-7-new-functionality], in particular its first two
      paragraphs, for details.  [Forward-chaining] also does more
      with free variables.

  Changes in proof engine (see [note-2-7-proofs])

    * Some prover heuristics have changed slightly.  Among other
      consequences, this can cause subgoal [hints] to change.  For
      example, suppose that the Version_2.6 proof of a particular
      theorem generated \"Subgoal 2\" and \"Subgoal 1\" while Version_2.7
      only generates the second of these.  Then a subgoal hint
      attached to \"Subgoal 1\" in Version_2.6 would have to be
      attached to \"Goal'\" in Version_2.7.  (See [goal-spec].)  The
      full topic has details (see [note-2-7-proofs]).

  Changes in rules and definitions (see [note-2-7-rules])

    * The package name of a generated variable has changed for [47m[defcong][0m.

  Guard-related changes (see [note-2-7-guards])

    * [47m[Guard][0m verification formerly succeeded in a few cases where it
      should have failed.

    * Guards generated from type declarations now use functions
      [47msigned-byte-p[0m and [47munsigned-byte-p[0m, now defined in source file
      [47maxioms.lisp[0m and formerly defined rather similarly under
      [47mbooks/ihs/[0m.

  proof-builder changes (see [note-2-7-proof-builder])

    * See the above doc topic.

  System-level changes (see [note-2-7-system])

    * See the above doc topic.

  Other changes (see [note-2-7-other])

    * A new [47m[table][0m, [47m[invisible-fns-table][0m, takes the place of the handling
      of invisible functions in the [47m[ACL2-defaults-table][0m,

    * The [47m[theory-invariant][0m event has been modified so that the default
      action is an error rather than a warning.

    * Proof output that reports destructor elimination no longer uses the
      word ``generalizing''.

  Again, please proceed to the subtopics for more thorough release
  notes.


Subtopics

  [Note-2-7-bug-fixes]
      ACL2 Version 2.7 Notes on Bug Fixes

  [Note-2-7-guards]
      ACL2 Version 2.7 Notes on Guard-related Changes

  [Note-2-7-new-functionality]
      ACL2 Version 2.7 Notes on New Functionality

  [Note-2-7-other]
      ACL2 Version 2.7 Notes on Miscellaneous Changes

  [Note-2-7-proof-builder]
      ACL2 Version 2.7 Notes on proof-builder Changes

  [Note-2-7-proofs]
      ACL2 Version 2.7 Notes on Changes in Proof Engine

  [Note-2-7-rules]
      ACL2 Version 2.7 Notes on Changes in Rules and Constants

  [Note-2-7-system]
      ACL2 Version 2.7 Notes on System-level Changes")
 (NOTE-2-7-BUG-FIXES
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on Bug Fixes

  Francisco J. Martin-Mateos emailed us a soundness bug (!) in our
  handling of functional instantiation (for example see
  [functional-instantiation-example]).  We are grateful for that
  email, which clearly illustrated the problem.  It is included just
  below the definition of [47mpush-clause[0m in ACL2 source file [47mprove.lisp[0m,
  where we have fixed the bug.  This bug was fixed in a re-release of
  Version 2.6 in February, 2002.

  Rob Sumners emailed us a soundness bug (!) in function
  [47mcommutative-p1[0m, which is used by the ACL2 [bdd] package.  We are
  grateful for his help; his email gave a proof of nil and also
  pointed to the problem function.  This bug was fixed in a
  re-release of Version 2.6 in February, 2002.

  We discovered and fixed a soundness bug illustrated by the book
  below, which was certifiable in Version 2.6 and ends in a proof of
  [47mnil[0m.  The event [47m(verify-guards foo)[0m should have been rejected,
  because [47mfoo[0m calls a function whose guards have not been verified,
  namely, [47mbar[0m.  However, ACL2 did not notice the call of function [47mbar[0m
  in the body of [47mfoo[0m because it was looking in the simplified
  (normalized) body of [47mfoo[0m rather than in the original body of [47mfoo[0m.
  During processing of the book below, the logical definition of [47mzp[0m
  is used before [47m(verify-guards foo)[0m, and [47m(zp -3)[0m reduces to [47mt[0m in the
  logic.  After [47m(verify-guards foo)[0m, ACL2 simplifies [47m(foo -3)[0m by
  going into raw Lisp, where [47m(zp -3)[0m is evaluated and reduces to [47mnil[0m.

    (in-package \"ACL2\")
    (defun bar (x)
      (zp x))
    (defthm zp-false-on-negatives
      (implies (< x 0)
               (bar x))
      :rule-classes :type-prescription)
    (defun foo (x)
      (declare (xargs :guard (rationalp x)
                      :verify-guards nil))
      (if (< x 0)
          (if (bar x) 0 1) ; simplified body reduces this line to 0
        17))
    (defthm foo-of-minus-3-is-0
      (equal (foo -3) 0)
      :rule-classes nil)
    (verify-guards foo)
    (defthm foo-of-minus-3-is-1
      (equal (foo -3) 1)
      :rule-classes nil)
    (defthm bug
      nil
      :rule-classes nil
      :hints ((\"Goal\" :use (foo-of-minus-3-is-0 foo-of-minus-3-is-1))))

  The above bug exploited the fact that [47m[zp][0m has a different definition
  in raw Lisp than in the logic for arguments that violate its
  guard).  The following example caused a hard error in raw Lisp,
  though not a soundness error.

    (in-package \"ACL2\")
    (defun bar (x)
      (cons (car x) (car x)))
    (defun foo (x)
      (declare (xargs :guard t
                      :verify-guards nil))
      (if (bar x) x nil))
    (verify-guards foo)
    (defthm bug
      (equal (foo 3) t)
      :rule-classes nil)

  We have made a minor change to the notion of the [3mformula[0m of a
  function symbol, related to the change above, which however is
  unlikely to be noticeable.

  In order to make it harder to hit problems like the guard problem
  above, we have slightly modified the raw Lisp definition of [47m[zp][0m.

  A [47m[break-rewrite][0m command, [47m:ancestors[0m, was broken, but has been
  fixed.  Thanks to Eric Smith for bringing the problem to our
  attention, and to Robert Krug for supplying the final part of the
  fix.

  Some [proof-builder] commands caused errors when all goals have
  already been proved.  This has been fixed.  Thanks to Matt Wilding
  for reporting this bug.

  Fixed a bug in [47m:[0m[47m[comp][0m.  When compiling uncompiled functions with
  very large definitions, ACL2 was inserted a backslash ([47m\\[0m) character
  into generated files.

  Fixed the [47m:type-alist[0m [47m:[0m[47m[brr][0m command (see [brr-commands]), whose
  output was difficult to read when typed after an [47m:eval[0m..

  Fixed some clumsy handling of errors when including an uncertified
  book, for example, with the error message when including an
  uncertified book with a bad [47m[deftheory][0m event.  Thanks to Eric
  Smith for pointing out this problem.

  Two modifications to [47m[certify-book][0m now cause it to reflect natural
  expectations with respect to soundness.  First, it now has default
  values of [47mnil[0m instead of [47mt[0m for keyword arguments [47m:skip-proofs-okp[0m
  and [47m:defaxioms-okp[0m.  Thanks to Robert Krug for suggesting this
  change and the ACL2 seminar at the University of Texas for
  discussing it.  Second, when [47m:skip-proofs-okp[0m (respectively,
  [47m:defaxioms-okp[0m) is [47mnil[0m, either explicitly or by default, then
  [47m[skip-proofs][0m commands (respectively, [47m[defaxiom][0m events) are
  disallowed inside any included books, regardless of the keyword
  parameters passed to [47m[include-book][0m.  This had not been the case
  for previous versions of ACL2, regardless of the values of
  [47m:skip-proofs-okp[0m or [47m:defaxioms-okp[0m passed to [47m[include-book][0m.

  Improved warnings and errors for [47m[certify-book][0m and [47m[include-book][0m to
  mention the [portcullis] as a possible source of [47m[skip-proofs][0m and
  [47m[defaxiom][0ms.

  ACL2 formerly caused an error when [hints] in a [47m:[0m[47m[corollary][0m were not
  well-formed.  This situation could arise as follows when certifying
  a book.  A lemma FOO is proved [47m[local][0mly to the book (or, is
  present in a sub-book that is included locally).  The [47m:corollary[0m of
  a subsequent theorem, BAR, disables that rule in a hint.  When BAR
  is proved, this is not a problem.  But [47m[certify-book][0m makes a
  second pass after processing the events in a book: it essentially
  does an [47m[include-book][0m.  During the [47minclude-book[0m pass, FOO is not
  known (because it was [47m[local][0m), and therefore ACL2 fails to process
  the [47m[disable][0m of FOO in an [47m[in-theory][0m hint.  The fix is that
  during [47m[include-book][0m, [hints] are ignored in corollaries just as
  they have been for the main theorem (or definition).

  It was possible for guard verification to succeed where it should
  have failed.  We have fixed the bug (which was in source function
  (ironically named!) [47mfcons-term-smart[0m).  Thanks to Robert Krug for
  sending us an example of bungled guard verification.  It turns out
  that this bug was also present in Version_2.6.

  The [proof-builder] command [47m=[0m has been improved.  Formerly, it could
  fail to apply when certain [47m[implies][0m terms were in the context.
  Thanks to Pete Manolios for bringing this problem to our attention.

  The command [47m[add-binop][0m failed to work.  This has been fixed.  Thanks
  to Rob Sumners for pointing out this problem.  Also see
  [note-2-7-other] for a discussion of how this and another [table]
  are no longer part of the [47m[ACL2-defaults-table][0m.

  Book certification could cause a segmentation fault in cases where
  the certification world (see [certify-book]) has a very large
  number of events.  This has been fixed.

  We now allow empty [47m:use[0m [hints] and empty hints, as requested by Eric
  Smith.  Examples:

    (\"Goal\" :use ())
    (\"Goal\")

  A large [47m[mutual-recursion][0m nest could cause a stack overflow when
  executing either [47m:pr FN[0m, [47m:pr! FN[0m, or [47m:monitor (:definition FN) t[0m,
  where [47mFN[0m is in that large mutual recursion nest.  This has been
  fixed (implementation detail: function [47mactual-props[0m has been made
  tail-recursive).  NOTE: If you just want the definition of [47mFN[0m,
  [47m:[0m[47m[pf][0m[47m FN[0m can be much faster than [47m:[0m[47m[pr][0m[47m FN[0m if [47mFN[0m is in a large
  [47m[mutual-recursion][0m.

  Hard Lisp errors could occur when including uncertified books.  This
  has been fixed; ACL2 now does syntax-checking formerly omitted when
  including uncertified books.

  Previously, the evaluation of [47m[defstobj][0m and [47m[mutual-recursion][0m forms
  could cause ``undefined'' warnings when the form was compiled.
  This has been fixed.  Thanks to Eric Smith for bringing a
  [47mmutual-recursion[0m example to our attention.

  A bug has been fixed in the syntactic check for valid [47m:[0m[47m[loop-stopper][0m
  values.  Formerly, valid [47m:loop-stopper[0m values were erroneously
  restricted to lists of length at most 2 (a minor problem, since
  these lists typically have length 1), and the function symbol(s)
  need not have been defined in the current ACL2 [world].  Thanks to
  Eric Smith for sending an example to demonstrate the latter
  problem.

  Functions definitions that are [47m:non-executable[0m (see [xargs]) had
  never been recognized as redundant, but this has been fixed.
  Thanks to Vernon Austel for pointing out this problem.

  Compilation using [47m:[0m[47m[comp][0m now compiles user-defined [47m:[0m[47m[program][0m mode
  functions.  Formerly only [47m:[0m[47m[logic][0m mode functions could be compiled
  using [47m:comp[0m.

  Handling of [47m:by[0m hints has been improved in essentially three ways.
  The primary change is that now, when the current goal exactly
  matches the supplied lemma instance, the subsumption test will
  always succeeds (see [hints], in particular the discussion of [47m:by[0m).
  Second, certain proof failures involving [47m:by[0m [hints] were failing
  silently, with duplicate messages ``As indicated by the hint, this
  goal is subsumed by....'' This could happen when the original goal
  was among the goals generated by applying the hint.  This problem
  has been fixed by no longer considering this proof step to be
  specious (see [specious-simplification]).  Third and finally, when
  the [lemma-instance] refers to a definition, the original body of
  that definition is used rather than the simplified (``normalized'')
  body.

  In addition to the above, we now recognize more cases of specious
  simplification (see [specious-simplification]).  Thanks to Eric
  Smith for bringing this issue to our attention.

  Fixed building of ACL2 under CLISP so that (1) the appropriate ACL2
  startup message is printed out when ACL2 starts up, and (2) the
  lisp process supplied to make, e.g., LISP=/usr/bin/clisp, is the
  one written out to the saved ACL2 file.  Thanks to Dave Greve and
  Noah Friedman for suggesting (2).  Also, ACL2 now works with CLISP
  2.30.  We have accommodated a change in CLISP's handling of streams
  and its package-locking mechanism, as well as certain non-standard
  characters that formerly could cause CLISP 2.30 to break, even when
  those characters are in comments.

  Eliminated compiler warnings for CMU Lisp.

  Fixed an incorrect error supplied when book certification proceeded
  so quickly that the file write dates of the book ([47m.lisp[0m file) and
  the corresponding compiled file are equal.  Now that error only
  occurs if the compiled file has a strictly earlier write date,
  which probably should never happen.

  Fixed an infinite loop when executing [47mmake clean-books[0m (and hence
  `make' with targets that call [47mclean-books[0m, namely,
  [47mcertify-books-fresh[0m, [47mregression-fresh[0m, and
  [47mregression-nonstd-fresh[0m), which could occur when any subdirectories
  of [47mbooks/[0m are missing --- even [47mworkshops/[0m, which is intended to be
  optional.  Thanks to Pete Manolios for pointing out this bug.

  The [47m[include-book][0m command now works properly even when filenames, or
  their directories or parent directories (etc.) are links.  Thanks
  to Matt Wilding for pointing out this problem.

  The commands [47m:[0m[47m[puff][0m [47m:[0m[47m[puff*][0m have been fixed.  Formerly, there was a
  bug when [47m:puff[0m or [47m:puff*[0m caused the execution of an [47m[include-book][0m
  for an absolute [pathname], [47mP[0m, that was other than the current
  connected book directory (see [cbd]).  When including [47mP[0m, any
  subsidiary [47m[include-book][0m with a relative pathname would be
  erroneously considered relative to the current [47m[cbd][0m rather than
  relative to the directory of [47mP[0m.  Thanks to Pete Manolios and Matt
  Wilding for pointing out this problem.

  It had been possible in a ``large'' ACL2 image to call
  [47m[verify-termination][0m successfully on built-in function [47m[sys-call][0m,
  with undesirable results.  This hole has been plugged.  Thanks to
  Rob Sumners for pointing out this problem.  The new function [47m[gc$][0m
  must also stay in [47m:[0m[47m[program][0m mode.

  ACL2 no longer warns when certifying a book based on [47m[local][0m
  functions whose [guard]s have not yet been verified.  Thanks to
  Pete Manolios for pointing out this issue.

  An occasional ``slow array warning'' had been possible during proofs.
  The following sequence shows how to evoke that warning in previous
  versions.

    (in-theory (disable binary-append))
    (in-theory (enable binary-append))
    (in-theory (disable binary-append))
    (ubt 2)
    (thm (equal (car (cons x y)) x))

  (See [note-2-7-other] for a discussion of a change to [47m[compress1][0m in
  support of this fix; however, users should not need to read that
  discussion.)

  The raw Lisp code for [47m[defchoose][0m had a small bug, which was only
  evidenced in CLISP implementations as far as we know.  It has been
  fixed.

  When [47m[ld][0m is applied to a stringp file name, it now temporarily sets
  the connected book directory (see [cbd]) to the directory of that
  file while evaluating forms in that file.  To see the effect of
  this change, imagine a subdirectory [47m\"sub\"[0m of the current directory,
  and imagine executing [47m(ld \"sub/foo.lisp\")[0m, where file [47mfoo.lisp[0m
  contains the form [47m(include-book \"bar\")[0m.  Presumably the intention
  was to consider the file [47mbar.lisp[0m in the same directory, [47msub/[0m, as
  [47mfoo.lisp[0m.  [47mLd[0m now honors that intention, but in previous versions
  [47m\"bar.lisp\"[0m would have been a reference to a file in the current
  directory, not in [47msub/[0m.

  For users of [47mrun-acl2[0m [perhaps there are none!]: A fix has been
  provided by a Debian user via Camm Maguire so that acl2-mode will
  work in Xemacs, which apparently uses variable [47mlisp-mode-shared-map[0m
  rather than [47mshared-lisp-mode-map[0m.

  ACL2 has, for a long time (always?), had a mechanism for avoiding
  re-proving [constraint]s generated by [47m:functional-instance[0m
  [lemma-instance]s in [47m:use[0m and [47m:by[0m hints.  But this mechanism had
  not applied to defined (as opposed to constrained) functions.  This
  has been fixed.  Thanks to Francisco J. Martin-Mateos (ChesKo) for
  pointing out this problem by sending a clear example.")
 (NOTE-2-7-GUARDS
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on Guard-related Changes

  It was possible for guard verification to succeed where it should
  have failed.  See the discussion under [note-2-7-bug-fixes].

  There have been changes in the guards generated from type
  declarations for the following cases.  Thanks to Dave Greve and
  Matt Wilding for suggesting such changes.

    (type (signed-byte n) val)
    (type (unsigned-byte n) val)
    (type (integer m n) val)

  The following examples illustrate the changes.

    (type (signed-byte 4) x)
    ==> [old] (AND (INTEGERP X) (<= -8 X) (<= X 7))
    ==> [new] (SIGNED-BYTE-P 4 X)

    (type (unsigned-byte 4) x)
    ==> [old] (AND (INTEGERP X) (<= 0 X) (<= X 15))
    ==> [new] (UNSIGNED-BYTE-P 4 X)")
 (NOTE-2-7-NEW-FUNCTIONALITY
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on New Functionality

  ACL2 now has a more powerful technique for relieving a [47m:[0m[47m[rewrite][0m or
  [47m:[0m[47m[linear][0m rule's hypothesis that contains free variables.  A new
  [documentation] section has been written describing the handling
  free variables in rules; see [free-variables].  In brief, the
  primary change is that when a free-variable match for the current
  hypothesis fails to allow subsequent hypotheses to be relieved,
  then additional matches may be attempted until they have all been
  tried.  Also see [rule-classes] (discussion of [47m:match-free[0m).  Also
  see [set-match-free-error], see [set-match-free-default], and see
  [add-match-free-override] for interfaces provided to the user for
  controlling the way ACL2 deals with free variables in hypotheses.
  We thank Rob Sumners for several helpful discussions about the
  designs of those interfaces, as well as Eric Smith and Robert Krug
  for helpful related discussions.  Robert Krug also found a
  performance bug in a preliminary version, for which we are
  grateful.

  WARNING: Book certification attempts may take much longer now that,
  by default, ACL2 looks for more free variable matches (see
  paragraph just above).  You can get the old behavior by inserting
  the form

    (set-match-free-default :once)

  just after the initial [47m[in-package][0m form.  However, rules from
  included books that have free variables can still slow down
  certification.  This can be fixed by inserting

    (add-match-free-override :once t)

  before the first event in the file that generates a proof.

  [Forward-chaining] has been made more powerful in the presence of
  free variables (see [free-variables]), thanks to a contribution by
  Erik Reeber.  Both before and now, when an attempt is made to
  relieve (prove) a hypothesis of a [47m:forward-chaining[0m rule in the
  case that at least one variable in that hypothesis is not yet
  bound, ACL2 looks in the current context for an instance of that
  hypothesis.  If it finds one, then it binds the unbound variables
  and continues to the next hypothesis.  What is new is that ACL2 can
  now look for multiple instances of that hypothesis.  Consider the
  following example; an explanation is below.

    (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))

    ; fails in Version_2.6; succeeds in in Version_2.7
    (thm (implies (and (op a b) (op b c) (op b e)) (op a c)))

  Before Version_2.7, the proof of the [47mthm[0m above fails.  When the
  [47m:forward-chaining[0m rule [47mtransitivity-of-op[0m binds [47mx[0m to [47ma[0m and [47my[0m to [47mb[0m,
  it then looks for an instance of [47m(op y z)[0m in the current context,
  with [47my[0m bound to [47mb[0m but [47mz[0m unbound.  It happens to find [47m(op b e)[0m
  before [47m(op b c)[0m, and it then adds [47m(op a e)[0m to the context.  But
  starting with Version_2.7, it continues to look for additional
  instances and finds [47m(op b c)[0m in the context as well, chaining
  forward to [47m(op a c)[0m and thus proving the theorem.

  A new macro, [47m[bind-free][0m, provides a simple way to get much or most
  of the power of [meta]functions.  Thanks to Eric Smith for coming
  up with the idea and to Robert Krug for providing an implementation
  (which we modified only very slightly) and documentation. See
  [bind-free] and see [bind-free-examples].

  With the addition of [47m[bind-free][0m (mentioned above), [47m[syntaxp][0m has
  become a macro, although that change should be transparent to the
  user.  More importantly, the argument of [47msyntaxp[0m may now refer to
  variables [47mmfc[0m and [47mstate[0m, giving [47msyntaxp[0m some of the power of
  extended metafunctions; see [syntaxp] and see
  [extended-metafunctions].  Thanks to Robert Krug for implementing
  that extension.  Also, the argument of [47m[syntaxp][0m may now include
  calls of [47m:[0m[47m[program][0m mode functions.  See [syntaxp] and see
  [syntaxp-examples] (thanks to Robert Krug for updating the former
  and creating the latter documentation).

  The linear-arithmetic decision procedure (see [linear-arithmetic])
  has now been extended so that ACL2 can reason about non-linear
  arithmetic as well (see [non-linear-arithmetic] for how to turn on
  this feature).  We thank Robert Krug for the initial implementation
  of this, and Eric Smith for finding a couple of bugs in it.

  Some [47m[trace][0m utilities have been made available in the ACL2 loop.

    * Function [47m[trace$][0m (and also [47m[untrace$][0m) calls the corresponding
      underlying Lisp routine [47mtrace[0m (and [47muntrace[0m), which however
      continues (as it has for some time) to be enhanced for GCL and
      Allegro CL.

    * Macro [47m[open-trace-file][0m causes trace output to go to a specified
      file.  Macro [47m[close-trace-file][0m causes trace output to go to
      the screen (which is the default).

    * Macro [47mwith-error-trace[0m (or, [47mwet[0m for short) causes a backtrace to be
      written out for many failures, including guard violations.  See
      [trace], see [trace$], and see :DOC [47mwet[0m [** NOTE: eliminated
      after Version 3.3].

  A new [47m[theory][0m, [47m[minimal-theory][0m has been provided (see [theories]).
  It can be particularly useful for speeding up proofs involving [47m:use[0m
  [hints].

  New [47m[events][0m [47m[defund][0m and [47m[defthmd][0m behave exactly like [47m[defun][0m and
  [47m[defthm][0m, respectively, except that these new events disable the
  new name.

  The new macro [47m[with-output][0m can be used to suppress output that would
  normally result from evaluation of a form.

  The form [47m([0m[47m[pstack][0m[47m)[0m can give the user an idea of what the prover has
  been up to during a proof, or after a user-aborted proof.
  Moreover, by evaluating [47m(verbose-pstack t)[0m (see [verbose-pstack])
  one can get [trace]-like information about prover functions,
  including time summaries, printed to the screen during a proof.
  Thanks to Bill Legato and Robert Krug for initiating this work and
  to Robert for providing some initial implementation.

  The new command [47m:[0m[47m[comp-gcl][0m is identical in functionality, except
  that it always leaves [47m.c[0m and [47m.h[0m files when compiling in GCL.
  Thanks to Rob Sumners and Vernon Austel for suggesting such a
  capability.

  The macro [47m[e/d][0m provides a convenient way to [47m[enable][0m some rules and
  [47m[disable][0m others.  It was formerly in a book supplied with the
  distribution, [47mbooks/ihs/ihs-init.lisp[0m, written by Bishop Brock (who
  we thank for providing this useful macro).

  New distributed books include those in [47mbooks/ordinals/[0m,
  [47mbooks/rtl/rel3/[0m, and [47mbooks/misc/simplify-defuns.lisp[0m (which is
  documented in [47mbooks/misc/simplify-defuns.txt[0m).

  The [47m:expand[0m hint now accepts a special value, [47m:LAMBDAS[0m, that tells
  the ACL2 rewriter to expand all lambda applications ([47m[let][0m
  expressions).  See [hints].

  A new function [47m[zpf][0m has been added as a fast test against 0 for
  nonnegative fixnums.

  A new macro [47m[gc$][0m allows the user to call the garbage collector of
  the underlying Common Lisp.  Thanks to Rob Sumners for suggesting
  this feature.

  It is now possible to [47m[monitor][0m [simple] (abbreviation) rules.
  However, as a warning explains, they are still not considered
  monitored during preprocessing; see [monitor].  Thanks to Robert
  Krug for providing this improvement.

  The second argument of [47m[certify-book][0m, if supplied, formerly had to
  be either [47mt[0m or a non-negative integer.  Now it can be the symbol [47m?[0m,
  in the [47mACL2[0m package, indicating that the usual check should be
  suppressed on the number of commands that have been executed to
  create the world in which [47m[certify-book][0m was called.")
 (NOTE-2-7-OTHER
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on Miscellaneous Changes

  Made several minor [documentation] improvements.  We are grateful to
  Eric Smith for suggesting (most of) these.

  Improved [47m(show-bdd)[0m (see [bdd]) to give more useful feedback when
  there are ``leaf'' terms not known to be Boolean.

  Sped up processing of large mutual-recursion nests.  In one large
  example the speedup was roughly two orders of magnitude.

  Modified event printing so that if both [47m'prove[0m and [47m'event[0m are
  inhibited, then events are no longer printed on behalf of
  [47m[certify-book][0m, [47m[encapsulate][0m, or [47m[defstobj][0m.  Thanks to Eric Smith
  for prompting consideration of such a change.

  The following technical change was made to support [47mwith-error-trace[0m
  and [47mwet[0m (see [note-2-7-new-functionality]), but may be of interest
  to those who do low-level programming using the ACL2 logical
  [47m[world][0m.  The [47m'unnormalized-body[0m property is now stored not only
  for functions defined in [47m:[0m[47m[logic][0m mode, but also for functions
  defined by the user in [47m:[0m[47m[program][0m mode.  ([47m:Program[0m mode Functions
  built into ACL2 still have their [47m'unnormalized-body[0m property
  omitted, in order to save space.)

  The handling of ``invisible'' functions for purposes of controlling
  rewriting (see [loop-stopper]) has been moved to a new table; see
  [invisible-fns-table].  Macros that access and modify this table
  are called ``[47m...-invisible-fns-table[0m'' in place of their former
  names, ``[47m...-invisible-fns-alist[0m.'' This feature was formerly
  implemented in the [47m[ACL2-defaults-table][0m, which prevented a book
  from exporting lists of invisible functions intended to work with
  the [rewrite] rules developed in the book.  Thanks to Eric Smith
  and Rob Sumners for suggesting this change.  See
  [set-invisible-fns-table] (formerly [47mset-invisible-fns-alist[0m), and
  also see [add-invisible-fns] and see [remove-invisible-fns], which
  provides ways to incrementally add to and remove from this table,
  respectively.  The handling of printing binary function call nests
  using macros (See [add-binop]) has also been moved out of the
  [47m[ACL2-defaults-table][0m as suggested by Eric and Rob, but this
  feature didn't work anyhow (see [note-2-7-bug-fixes]).
  Incidentally, the symbols [47mbinop-table[0m, [47m[add-binop][0m, and
  [47m[remove-binop][0m have all been added to the list [47m*acl2-exports*[0m (see
  [ACL2-user]), [47m[add-invisible-fns][0m and [47m[remove-invisible-fns][0m have
  been added to that list, and [47mset-invisible-fns-alist[0m has been
  replaced in that list by [47m[set-invisible-fns-table][0m.  Function
  [47minvisible-fns-alistp[0m is no longer defined and has been removed from
  [47m*acl2-exports*[0m.

  We now enforce the stated restriction on the pairings in
  [47mmacro-aliases-table[0m (see [macro-aliases-table]), namely, that it
  associates names of macros with names of functions (with respect to
  the current ACL2 logical [world]).  We make a similar requirement
  on [47m[invisible-fns-table][0m.

  The [47m[theory-invariant][0m event has been modified so that the default
  action is an error rather than a warning.  Thanks to Eric Smith for
  suggesting this change.  Also, the value returned upon successful
  execution of a [47m[theory-invariant][0m event is now the key.

  Proof output that reports destructor elimination no longer uses the
  word ``generalizing''.  This small change may help in browsing
  proof output, since now ``generaliz'' takes you to true uses of
  generalization.  Thanks to Matyas Sustik for suggesting such a
  change.

  The command [47m:[0m[47m[pl][0m now prints an abbreviated controller-alist for
  [47m;[0m[47m[definition][0m rules.  Formerly the output from [47m:pl[0m could be
  overwhelming when the supplied function was part of a large
  [47m[mutual-recursion][0m nest.

  The defaults for keyword parameters of [47m[certify-book][0m have changed.
  See [note-2-7-bug-fixes], in particular, the discussion there of
  two modifications to [47mcertify-book[0m.

  Technical changes have been made to [47m[compress1][0m and [47m[compress2][0m that
  should usually be invisible to users.  The next paragraph describes
  them in detail, only for completeness (i.e., that description can
  be ignored by most users).  But first, here is an example showing
  an effect on users.  The slow array warning was not there
  previously.  Notice that the warning only arises if the event form
  is changed.  The solution is to be sure that redundant [47m[defconst][0m
  forms are syntactically identical.

    ACL2 !>(defconst *a* (compress1 'demo
                                    '((:header :dimensions (5)
                                               :maximum-length 15
                                               :default uninitialized
                                               :name demo)
                                      (1 . one)
                                      (0 . zero))))

    Summary
    Form:  ( DEFCONST *A* ...)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     *A*
    ACL2 !>(aref1 'demo *a* 0)
    ZERO
    ACL2 !>(defconst *a* (compress1 'demo
                                    '((:header :dimensions (5)
                                               :maximum-length 15
                                               :default uninitialized
                                               :name demo)
                                      (1 . one)
                                      (0 . zero))))

    This event is redundant.  See :DOC redundant-events.

    Summary
    Form:  ( DEFCONST *A* ...)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     :REDUNDANT
    ACL2 !>(aref1 'demo *a* 0)
    ZERO
    ACL2 !>(defconst *a* (compress1 'demo
                                    '((:header :dimensions (5)
                                               :maximum-length 15
                                               :default uninitialized
                                               :name demo)
                                      (0 . zero)
                                      (1 . one))))

    This event is redundant.  See :DOC redundant-events.

    Summary
    Form:  ( DEFCONST *A* ...)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     :REDUNDANT
    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
    ACL2 !>

  As before, the von Neumann structure stored in the [47m'acl2-array[0m
  property of the array name contains the array list object in its
  [47m[car][0m.  However, previously it was the case that [47mcompress1[0m and
  [47mcompress2[0m did not update that [47mcar[0m when its new value would be equal
  to its old value.  This was done largely in support of some
  type-set tables defined using [47m[defconst][0m in [47mtype-set-b.lisp[0m.  The
  new versions of [47m[compress1][0m and [47m[compress2][0m are simpler in that no
  such exception is made in the case of equal lists, although instead
  the entire compression process is short-circuited when the input
  array list object is [47m[eq][0m to the [47mcar[0m of the [47m'acl2-array[0m property.
  This change was made because the equality test was causing a ``slow
  array access'' warning to be printed in rare cases during proofs,
  as described elsewhere (see [note-2-7-bug-fixes]).

  We no longer distribute documentation specific to Lucid Emacs.  The
  Info documentation in directory [47mdoc/EMACS/[0m works well both for Gnu
  Emacs and XEmacs.

  A little-advertised macro, [47mvalue[0m, has long been allowed for top-level
  forms in [books]; see [embedded-event-form].  This has been
  replaced by a new macro, [47mvalue-triple[0m.  The two have the same
  semantics at the top-level of books, where [47m[state][0m is ``live''.
  However, [47mvalue-triple[0m should be used at the top-level of a book,
  while [47mvalue[0m should be used in function definitions (as before).
  This change eliminates a warning put out by the Allegro Common Lisp
  compiler for top-level [47mvalue[0m forms in [books].")
 (NOTE-2-7-PROOF-BUILDER
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on proof-builder Changes

  Output from the [proof-builder] can now be inhibited by supplying the
  symbol [47mproof-builder[0m in the list given to [set-inhibit-output-lst].")
 (NOTE-2-7-PROOFS
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on Changes in Proof Engine

  An improvement in the linear arithmetic heuristics has been provided
  by Robert Krug.  For information about this change, search for the
  comment in [47madd-linear-lemma[0m (file [47mrewrite.lisp[0m) that begins as
  follows.

    ; Previous to Version_2.7, we just went ahead and used the result of

  Thanks, Robert!  Also thanks to Eric Smith for providing a motivating
  example.

  The non-linear-arithmetic addition (see [non-linear-arithmetic]) led
  to several small changes in the linear-arithmetic decision
  procedure (see [linear-arithmetic]).  Two of these changes could
  affect existing proofs.

      First, when we are setting up the initial arithmetic database (which
      we call the ``pot-lst''), we have always scanned it to see if
      there were any pairs of inequalities from which we could derive
      a previously unknown equality.  In some cases we added this
      equality to the clause and in others we used it to rewrite the
      clause, substituting one side of the equality for the other
      throughout the clause.  Previously, the heuristics that we used
      to determine whether we performed the substitution differed
      from those used in several other places in the code.  This has
      now been regularized, and similar heuristics are now used
      throughout the code.

      The second change to the linear-arithmetic decision procedure is that
      we now explicitly add inequalities derived from type reasoning
      to the pot-lst.  Previously, we performed cancellations against
      these inequalities without adding them to the pot-lst.  This
      change results in there being more inequalities in the pot-lst
      than before, and so more chances for there to be a pair of
      inequalities from which an equality can be derived.  In effect,
      certain simple consequences of the current goal (see
      [type-set]) may now be added as hypotheses of the goal or used
      to perform equality substitutions.

  A slight improvement has been made to the way certain rewrite rules
  are stored.  It was already the case that a rewrite rule rule whose
  conclusion [47mC[0m is not a call of a known equivalence relation (or
  [47m[eq][0m, [47m[eql][0m, or [47m[=][0m) is stored as [47m(iff C t)[0m, except that if ACL2
  can determine (using its [47m[type-set][0m mechanism) that [47mC[0m is Boolean,
  then the rule is stored as [47m(equal C t)[0m.  The improvement is that if
  [47mC[0m and [47mC'[0m are Boolean, then a rule stated as [47m(iff C C')[0m is stored as
  [47m(equal C C')[0m.  Thanks to Pete Manolios for providing an example
  that led us to consider this improvement.

  The heuristic use of equalities (fertilization) has been modified.
  Previously, ACL2 would sometimes substitute using an equality but
  keep the equality, and then undo the substitution by using the
  equality again.  Now, when ACL2 keeps an equality after using it,
  it puts the equality inside a call of [47m[hide][0m.  Descendants of that
  goal that are unchanged by simplification will have this call of
  [47m[hide][0m removed so that the equality can once again contribute to
  the proof.  This change can cause some proofs to succeed that
  otherwise would fail.  In the unlikely event that a proof fails
  that formerly succeeded, the following hint on \"Goal\" may fix the
  problem (see [hints]):

    :expand ((:free (x) (hide x)))

  We have refined the heuristics employed when an [47m[if][0m form is assumed
  true or false.  Our previous attempt (see [note-2-6-proofs] for the
  original announcement) was not as general as we had believed.  We
  have also improved some low-level code responsible for rewriting [47mIF[0m
  expressions.  In earlier versions of ACL2, it was possible to have
  the truth or falsity of an [47mIF[0m expression explicitly recorded in the
  type-alist, and yet not use this information during rewriting.
  This problem has been corrected.  Thanks to Robert Krug for
  noticing this problem and implementing the fix.

  We have sped up the rewriter in some cases where there are large
  collections of mutually-recursive functions (see
  [mutual-recursion]).  (Implementation notes: technically, we have
  modified the way function [47mbeing-openedp[0m operates on the [47mfnstack[0m,
  and we have modified [47m*current-acl2-world-key-ordering*[0m as described
  in the essay above its definition.)

  [Forward-chaining] is now done in the preprocessing phase of proof
  attempts (see the discussion of [47m:DO-NOT[0m --- see [hints]).  This is
  part of a technical change, made in support of translation of type
  declarations to [guard]s (see [note-2-7-guards]).  Previously,
  whenever ACL2 checked for [built-in-clause]s, it then looked for a
  contradiction using [47m[type-set][0m reasoning if it did not find a
  suitable built-in clause.  The change is to perform
  forward-chaining in such cases (i.e., when a built-in clause is not
  found).

  A couple of changes have been made in the generation of goals for
  [forcing-round]s.  Thanks to Eric Smith for bringing issues to our
  attention that led to these changes.  For one, [guard]s are no
  longer relevant in such goal generation.  Formerly, the addition of
  a guard could make a proof fail that otherwise succeeded.
  Secondly, contextual information is now always kept when it
  involves a constrained constant, i.e., a zero-ary function
  introduced in the signature of an [47m[encapsulate][0m.")
 (NOTE-2-7-RULES
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on Changes in Rules and Constants

  The [47m[defcong][0m macro has been slightly changed.  The difference is
  that the variable generated with suffix [47m-EQUIV[0m will now be in the
  same package as the name of the variable from which it is
  generated, rather than always belonging to the ACL2 package.
  Thanks to Hanbing Liu for suggesting this change.  (Note that a
  couple of books have been modified to accommodate this change,
  e.g., [47mbooks/finite-set-theory/set-theory[0m.)

  In Version_2.6, a change was made for rules of class [47m:[0m[47m[rewrite][0m whose
  conclusion is a term of the form [47m(EQV lhs rhs)[0m, where [47mEQV[0m is [47m[=][0m,
  [47m[eq][0m, or [47m[eql][0m: the rule was stored as though [47mEQV[0m were [47m[equal][0m.
  (See [note-2-6-rules].)  This change has been extended to rules of
  class [47m:[0m[47m[definition][0m.")
 (NOTE-2-7-SYSTEM
  (NOTE-2-7)
  "ACL2 Version 2.7 Notes on System-level Changes

  ACL2 now runs (once again) under LispWorks, specifically, LispWorks
  4.2.0.  However, we needed a patch, which presumably will be
  unnecessary after 4.2.7.  From LispWorks support:

      Users with LispWorks4.2.7 should ask us at lisp-support@xanalys.com
      for the transform-if-node patch. It will be helpful if they
      quote (Lisp Support Call #11372) when doing so. Also, they must
      send a bug form generated from their LispWorks image:
      instructions at
      http://www.lispworks.com/support/bug-report.html.

  File [47mbooks/Makefile-generic[0m has been improved so that failed attempts
  to certify a book will cause the `make' to fail.  Previously, an
  existing [47m.cert[0m file was left in place, and that sufficed for the
  `make' to be considered a success.  Now, the old [47m.cert[0m file is
  first removed when recertification is found to be necessary.

  A change has been made to source file [47macl2.lisp[0m to accommodate GCL
  2.4.3.  (ACL2 Version 2.6 does not work with some versions of GCL
  2.4.3.)

  The error message has been improved when certain forms are typed to
  raw Lisp and the ACL2 loop has never been entered (with [47m([0m[47m[lp][0m[47m)[0m).

  The following symbols in the ACL2 package have been made untouchable,
  meaning that they are not available to the user: [47mev-fncall[0m, [47mev[0m,
  [47mev-lst[0m, [47mev-acl2-unwind-protect[0m, [47mev-fncall![0m, and
  [47muser-stobj-alist-safe[0m.  The reason is that these functions can not
  be called safely except under certain restrictions.  If you want to
  call the ACL2 evaluator, consider using the built-in system
  functions [47mtrans-eval[0m or simple-translate-and-eval.

  CLISP Version_2.30 implements a notion of ``locking'' the \"LISP\"
  package that is incompatible with building ACL2.  (CLISP
  Version_2.27 does not appear to have had this feature.)  We have
  gotten around this problem by unlocking the \"LISP\" package in ACL2
  images built on such CLISPs.

  Automatic proclaiming for GCL, which has (for a long time) been done
  for functions in compiled books, has been improved.  Formerly, the
  only time a non-trivial output type (i.e., other than [47mt[0m) was
  inferred was when macroexpansion produced an explicit call of
  [47m[the][0m.  Now, [47m[if][0m expressions can also generate non-[47mt[0m output types.
  Consider the following example.

    (defmacro the-fixnum (n)
      (list 'the '(signed-byte 29) n))
    (defmacro 1+f (x)
      (list 'the-fixnum
            (list '1+ (list 'the-fixnum x))))
    (defun foo (x)
      (declare (type (unsigned-byte 27) x))
      (if (zp x)
          0
        (1+f (foo (1-f x)))))

  Formerly, the [47mproclaim[0m forms for [47mfoo[0m, before and after this
  improvement, are as shown below.

    (PROCLAIM '(FTYPE (FUNCTION ((UNSIGNED-BYTE 27)) T) FOO))                ;old
    (PROCLAIM '(FTYPE (FUNCTION ((UNSIGNED-BYTE 27)) (SIGNED-BYTE 29)) FOO)) ;new

  Compiler info messages sent to error stream were eliminated for
  CMUCL.")
 (NOTE-2-7{R}
  (RELEASE-NOTES)
  "ACL2 Version 2.7(r) (November, 2002) Notes

  In source file [47maxioms.lisp[0m, in order for proofs to succeed, ([47mmake
  proofs[0m), the definitions of [47m[ACL2-count][0m and [47mexplode-atom[0m have been
  modified slightly, and lemma [47mstandard-numberp-one[0m [modified after
  Version_3.4 to become [47mstandardp-one[0m] has been given [47m:rule-classes
  nil[0m.

  All [47m[skip-proofs][0m forms have been eliminated from the nonstd books,
  thanks to Ruben Gamboa.

  The directory [47mbooks/sqrt/[0m, which was intended for ACL2(r), has been
  moved to [47mbooks/nonstd/sqrt/[0m and added as appropriate to
  [47mbooks/nonstd/Makefile[0m.

  Please see [note-2-7] for changes to Version_2.7 of ACL2.")
 (NOTE-2-8
  (RELEASE-NOTES)
  "ACL2 Version 2.8 (March, 2004) Notes

  BRIEF SUMMARY.

  The Version_2.8 notes are divided into the indicated subtopics.  Here
  we give only a brief summary of just a few of the major new
  features and changes that seem most likely to impact existing
  proofs.  Not included in this brief summary, but included in the
  subtopics, are descriptions of many improvements (including bug
  fixes and new functionality) that should not get in the way of
  existing proof efforts.  In the description below we also omit
  discussion of changes that will become clear by way of error
  messages if they affect you.

  In particular, please see [note-2-8-new-functionality] for discussion
  of a number of new features that you may find useful.

  Acknowledgments and elaboration, as well as other changes, can be
  found in the subtopics listed below.

  Some of the bug fixes (see [note-2-8-bug-fixes])

    * Some soundness bugs were fixed.

    * The handling of free variables in hypotheses (see [free-variables])
      of rewrite and linear rules had a bug that prevented some
      proofs from going through.  Now that this bug has been fixed,
      you may find some proofs running much more slowly than before.
      You can use [47m[accumulated-persistence][0m and
      [47m[add-match-free-override][0m to remedy this situation; see
      [note-2-8-bug-fixes] for details.

    * The [default-hints] in the current logical [world] are no longer
      ignored by [47m[verify-guards][0m.

    * Forms violating guard-checking such as [47m(defconst *silly* (car 3))[0m are
      now allowed in [books].

  Some of the new functionality (see [note-2-8-new-functionality])

    * WARNING: You may find that [47mcontrol-d[0m (in emacs, [47mcontrol-c control-d[0m)
      can throw you completely out of Lisp where it had not formerly
      done so.

    * ACL2 now starts up inside the ACL2 loop --- that is, [47m([0m[47m[lp][0m[47m)[0m is
      executed automatically --- when built on CLISP or Allegro CL.
      This was already the case for GCL and CMUCL, and it still is
      not true for LispWorks.

    * See [note-2-8-ordinals] for a discussion of a significant change in
      ordinal representation, and in particular, for how to preserve
      existing proofs that depend on the previous ordinal
      representation.

    * Macros [47m[mbe][0m (``must be equal''), [47m[mbt][0m (``must be true''), and
      [47m[defexec][0m have been introduced, which allow the user to attach
      alternate executable definitions to functions.

    * The user can now control multiple matching for free variables in
      hypotheses for [47m:[0m[47m[forward-chaining][0m rules, as has already been
      supported for [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules.

    * It is no longer necessary to specify [47m(set-match-free-error nil)[0m in
      order to avoid errors when a rule with free variables in its
      hypotheses is missing the [47m:match-free[0m field.

    * The form [47m(break-on-error)[0m causes, at least for most Lisps, entry into
      the Lisp debugger whenever ACL2 causes an error.

    * A new [47m[table][0m has been provided so that advanced users can override
      the built-in [47muntranslate[0m functionality.  See
      [user-defined-functions-table].

    * The [47m[pstack][0m (`process [prover] stack'') mechanism, formerly denoted
      [47mcheckpoints[0m, has been improved.  One of these improvements is
      to show actual parameters with [47m(pstack t)[0m rather than formals.

    * The [47m[defstobj][0m event is now allowed to take an [47m:inline[0m argument,
      which can speed up execution.

    * Macro [47m[cw-gstack][0m no longer takes arguments for the [47mgstack[0m or
      [47m[state][0m.  To print terms in full rather than abbreviated:
      [47m(cw-gstack :evisc-tuple nil)[0m.

    * The [47m[include-book][0m event now has an additional (optional) keyword,
      [47m:dir[0m.  In particular, [47m(include-book \"foo/bar\" :dir :system)[0m
      will include the indicated book after prepending the path of
      the built-in [47mbooks/[0m directory.  You will probably not find [47m:dir
      :system[0m to be useful if you move the executable image or
      distributed books; see [include-book], in particular its
      ``soundness warning''.

    * The printing of results in raw mode (see [set-raw-mode]) may now be
      partially controlled by the user: see [47madd-raw-arity[0m.  [Note
      added 2021: this utility has been removed and is no longer
      necessary.]

    * For those using Unix/Linux `make': A [47mcert.acl2[0m file can contain forms
      to be evaluated before an appropriate [47m[certify-book][0m command is
      invoked automatically (not included in [47mcert.acl2[0m).

  Some of the changes in the proof engine (see [note-2-8-proofs])

    * ACL2 now prevents certain rewriting loops; see [rewrite-stack-limit].

    * Small changes have been made to heuristics for controlling rewriting
      during proofs by induction and in handling certain ``weak''
      [compound-recognizer] rules.

    * The handling of free variables in a hypothesis of a [rewrite] rule
      (see [free-variables]) has been improved in the case that the
      hypothesis is of the form [47m(equiv x y)[0m, where [47mequiv[0m is a known
      equivalence relation (see [equivalence]).

    * We have modified how the ACL2 simplifier handles the application of a
      defined function symbol to constant arguments, by avoiding the
      introduction of [hide] when evaluation fails if the term can be
      rewritten.

    * The generation of \"Goal\" for recursive (and mutually-recursive)
      definitions now uses the subsumption/replacement limitation
      (default 500).  See [case-split-limitations].

    * Default hints now apply to hints given in definitions, not just
      theorems.  See [default-hints].

    * Linear arithmetic now uses the conclusions of [47m[forward-chaining][0m
      rules, and [47m[type-set][0m now uses a small amount of linear
      reasoning when deciding inequalities.

  Some of the changes in rules, definitions, and constants (see
  [note-2-8-rules])

    * See the above doc topic.

  Guard-related changes are described in see [note-2-8-bug-fixes]

  Some of the proof-builder changes (see [note-2-8-proof-builder])

    * Added new [proof-builder] commands [47mwrap1[0m, [47mwrap[0m, and [47mwrap-induct[0m, to
      combine multiple conjuncts or goals.

    * The [47mtype-alist[0m command now takes optional arguments that control
      whether or not the governors and/or conclusion are used in
      computing the context.

  Some of the system-level changes (see [note-2-8-system])

    * ACL2 now runs on OpenMCL and on MCL 5.0.

  Some of the other changes (see [note-2-8-other])

    * Emacs file [47memacs/emacs-acl2.el[0m has been updated (see [note-2-8-other]
      for details).

    * When [47m:pl[0m is given a term other than a symbol, it will print all
      rewrite rules that match that term.

    * A new function, [47m[pkg-witness][0m, returns a symbol in the given package.

    * The list constant [47m*acl2-exports*[0m has been extended.

    * A new release of the rtl library has been included: [47mbooks/rtl/rel4/[0m.
      See the [47mREADME[0m file in that directory.

  Again, please proceed to the subtopics for more thorough release
  notes.


Subtopics

  [Note-2-8-bug-fixes]
      ACL2 Version 2.8 Notes on Bug Fixes

  [Note-2-8-guards]
      ACL2 Version 2.8 Notes on Guard-related Changes

  [Note-2-8-new-functionality]
      ACL2 Version 2.8 Notes on New Functionality

  [Note-2-8-ordinals]
      ACL2 Version 2.8 Notes on Changes to the Ordinals

  [Note-2-8-other]
      ACL2 Version 2.8 Notes on Miscellaneous Changes

  [Note-2-8-proof-builder]
      ACL2 Version 2.8 Notes on proof-builder Changes

  [Note-2-8-proofs]
      ACL2 Version 2.8 Notes on Changes in Proof Engine

  [Note-2-8-rules]
      ACL2 Version 2.8 Notes on Changes in Rules, Definitions, and
      Constants

  [Note-2-8-system]
      ACL2 Version 2.8 Notes on System-level Changes")
 (NOTE-2-8-BUG-FIXES
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on Bug Fixes

  We have fixed a soundness bug in the tautology checker's handling of
  expressions of the form [47m(not (not x))[0m.  This bug has gone back at
  least as far as Version_2.4.  All of the regression tests passed
  after the fix, without modification.  So we hope that this bug has
  rarely bitten anyone.  Thanks to Qiang Zhang for sending us a proof
  of [47mnil[0m that led us to this fix: [47m(thm (equal (and p q) (not (or (not
  p) (not q)))))[0m.  And thanks to Matyas Sustik for an observation
  that led to an improvement of our initial fix.

  The preceding version (2.7) introduced a soundness bug in handling of
  ACL2 [arrays], in which functions [47m[compress1][0m and [47m[compress2][0m were
  returning the input alist rather than compressing it appropriately.
  Here is a proof of [47mnil[0m that no longer succeeds, based on a bug
  report from Warren Hunt, whom we thank for bringing this problem to
  our attention.

    (defthm bad
      (not (let* ((ar2 (aset1 'my-array ar1 3 10))
                  (ar3 (compress1 'my-array ar2))
                  (ar4 (reverse (reverse ar2)))
                  (ar5 (compress1 'my-array ar4)))
             (and (equal ar2 ar4)
                  (not (equal ar3 ar5)))))
      :rule-classes nil)
    (defthm contradiction
      nil
      :rule-classes nil
      :hints ((\"Goal\" :use
               ((:instance bad
                           (ar1 (compress1 'my-array
                                           '((3 . 5)
                                             (:HEADER :DIMENSIONS (5)
                                                      :MAXIMUM-LENGTH 6
                                                      :DEFAULT 0
                                                      :NAME MY-ARRAY)))))))))

  On a related note, a new function [47m[flush-compress][0m can be used for
  subtle control of under-the-hood raw Lisp support for fast array
  access, although we expect it to be very rare that users need this
  extra support.

  Previous versions have had two soundness bugs that can occur when
  using the [proof-builder]:

    * The first bug pertains to the [47mexpand[0m command, and hence [47mx[0m and [47mx-dumb[0m
      commands (which call [47mexpand[0m); see [proof-builder-commands].
      The bug can occur when applying the above commands when the
      current term is a call of a constrained function symbol for
      which there is a [47m:[0m[47m[definition][0m rule.  Now, the [47mexpand[0m command
      will succeed only when the function symbol of the current term
      is a defined function symbol, in which case the original
      definition is always used, in analogy to how the [47m:expand[0m hint
      works in the prover; see [hints].  Thanks to John Erickson for
      sending an example that led us to wonder if there might be a
      soundness problem.

    * The second bug pertains to the [47ms[0m command (and commands that call it,
      e.g., [47ms-prop[0m).  The proof-builder forms a context out of the
      top-level hypotheses and the [47mif[0m-terms governing the current
      term.  If there is a contradiction in the top-level hypotheses,
      the proof-builder can appropriately consider the goal to be
      proved, and it does so.  But formerly, the criterion was
      weaker: the contradiction could involve the combination of the
      top-level hypotheses and [47mif[0m-term governors.  Thanks to Rob
      Sumners for noticing this bug.

  A soundness bug could be provoked in some Lisps by applying [47m[defpkg][0m
  to the empty string.  This has been disallowed.

  We fixed a soundness bug related to packages caused by a failure to
  track axioms introduced [47m[local][0mly on behalf of [47m[defpkg][0m events.
  See [hidden-death-package].

  We fixed a soundness bug caused by a failure to check that a
  [47m:[0m[47m[type-prescription][0m rule can be processed when proofs are skipped
  or under a [47m[defequiv][0m event.  The former case can occur when
  processing an [47m[encapsulate][0m or [47m[include-book][0m event, where the rule
  could depend on a [47m[local][0m [47m:[0m[47m[compound-recognizer][0m rule preceding the
  proposed [47m:[0m[47m[type-prescription][0m rule under the same [47m[encapsulate][0m or
  [47m[include-book][0m event.  See [local-incompatibility] for such an
  example.

  We fixed a potential soundness bug relating to reclassifying a
  [47m:program[0m mode function to [47m:logic[0m mode (as done by
  [47m[verify-termination][0m or the submission of an appropriate
  ``redundant'' definition) without adequate checking that [47m[stobj][0m
  usage was identical.  Allegedly redundant definitions must now
  preserve the [47mstobjs[0m declaration as well as the formals, body, guard
  and type declarations.  We thank Vernon Austel for pointing out
  this problem.

  It was possible to get a raw Lisp error by introducing a [47m[local][0mly
  defined function with [guard] verification inhibited and then
  subsequently introducing the same definition non-locally without
  that inhibition.  The following example will clarify.

    (encapsulate nil
      (local
        (defun foo (x) (declare (xargs :guard t :verify-guards nil)) (car x)))
      (defun foo (x) (declare (xargs :guard t)) (car x)))
    ; The following causes a raw lisp error because ACL2 runs the Common Lisp
    ; definition of foo, because it thinks that foo's guard of t was verified.
    (thm (equal (foo 3) xxx))

  Thanks to Jared Davis for bringing this problem to our attention.  We
  are particularly grateful to Jared because his example exploited
  this bug by applying it to a function defined using [47m[mbe][0m
  (introduced in this same version, 2.8), in order to prove [47mnil[0m!

  The sort of error message shown below can legitimately occur when
  certifying a book in a certification world where there was an
  [47m[include-book][0m command with a relative pathname (see [pathname]).
  However, it was occurring more often than necessary.  This has been
  fixed.

      ACL2 Error in (CERTIFY-BOOK \"foo\" ...): The certification world has
      include-book commands for book \"bar\" that correspond to
      different full pathnames, namely \"/u/dir1/bar\" and
      \"/u/dir2/bar\".  ACL2 cannot currently certify a book in such a
      world.  To work around this problem, use an absolute pathname
      for at least one of these books (see :DOC pathname).

  Bugs were fixed in [47m[with-output][0m, in particular related to the use of
  values [47m:all[0m.  Also, documentation for [47mwith-output[0m has been
  improved.  Thanks to Vernon Austel for pointing out the bugs.

  Fixed a lisp error occurring when [47mbash[0m proof-builder command was
  given illegal syntax, e.g., [47m(bash ((\"Goal\" :in-theory (enable
  binary-append))))[0m instead of [47m(bash (\"Goal\" :in-theory (enable
  binary-append)))[0m.

  We added an appropriate guard to [47m[find-rules-of-rune][0m, which will
  avoid hard lisp errors when this function is called on non-[rune]
  arguments.  Thanks to Eric Smith for pointing out this issue.

  It was possible for a redundant [47m[include-book][0m form (see
  [redundant-events]) to leave a [command] in the ACL2 logical
  [world] and to cause (re-)loading of a compiled file.  These
  behaviors have been fixed.  In particular, if [47mbook1[0m has already
  been included in the current ACL2 [world] and [47m(include-book
  \"book1\")[0m occurs in [47mbook2[0m, then the compiled file for [47mbook1[0m will not
  be loaded again when [47mbook2[0m is included.  Thanks to Dave Greve for
  bringing our attention to these problems, and to Eric Smith for
  bringing up a special case earlier (where \"//\" occurred in the
  book-name).

  The summary printed at the end of a proof had not listed [47m:[0m[47m[induction][0m
  rules used in a proof.  This has been corrected.

  The use of proof trees in emacs redefined `[47mcontrol-c control-c[0m' in
  such a way that in telnet mode, the telnet session was interrupted
  and perhaps could not be continued.  This has been fixed.

  Source function [47mload-theory-into-enabled-structure[0m contained a
  guard-violating call of [47m[compress1][0m.  Thanks to Vernon Austel for
  bringing this problem to our attention; even though this bug was
  benign (as he pointed out), we like keeping the source code free of
  guard violations.

  A number of proof-builder atomic macros caused a hard error when all
  goals have already been proved.  This has been fixed.  Thanks to
  John Erickson for sending an example of the issue.

  A bug has been fixed in [47m[add-match-free-override][0m.  Formerly, a
  [47m[table][0m [guard] violation occurred when calling
  [47m[add-match-free-override][0m more than once with first argument other
  than [47m:clear[0m.

  Definitions of functions involving large constants could cause stack
  overflows.  This has been fixed, at least in some of the most
  egregious cases (by making a source function [47mfn-count-evg[0m
  tail-recursive).  Thanks to Jared Davis for bringing this problem
  to our attention.

  Evaluation of computed hints could cause stack overflows.  This has
  been fixed.  Thanks to Eric Smith for bringing this problem to our
  attention.

  Evaluation of [47m:[0m[47m[monitor][0m on [47m:[0m[47m[definition][0m [rune]s is now fast even if
  the specified function is part of a very large [47m[mutual-recursion][0m
  nest.  Thanks to Eric Smith for sending an example showing that
  this wasn't always the case.

  Fixed a bug in [47mbooks/bdd/cbf.lisp[0m that was causing certification of
  distributed bdd books to fail when the connected book directory
  (see [cbd]) differs from the current working directory.  Thanks to
  Scott Guthery for bringing this bug to our attention and supplying
  a helpful log.

  Duplicate rule names have been eliminated from warnings generated
  upon the use of enabled [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m rules.  Thanks
  to Eric Smith for pointing out this problem.

  The trace utilities (see [trace]), as modified for GCL and Allegro
  Common Lisp, had failed to show more than the first return value
  for so-called ``[47m*1*[0m'' functions (essentially,
  [executable-counterpart] functions) when they were returning
  multiple values (via [mv]).  This has been fixed.  Thanks to Erik
  Reeber for pointing out this problem.  Also, it is now possible to
  refer to [47marglist[0m in [trace$] forms when ACL2 is built on GCL, not
  just when ACL2 is built on Allegro Common Lisp.

  Uses of [47m[hide][0m introduced during proofs by failed attempts to
  evaluate constrained functions (see [hide]) are now tracked, so
  that the [rune] [47m(:DEFINITION HIDE)[0m will show up in the summary.

  The following bug, introduced back in Version 2.7, has been fixed.
  The bug applied only to GCL and may well not have affected anyone.
  But the function proclamation computed by ACL2 for compilation
  usually had an output type of [47mnil[0m where it should have been [47mt[0m.

  The macro [47m[gc$][0m had a bug exhibited when it was supplied one or more
  arguments.  This has been fixed.

  The macro [47m[defabbrev][0m broke when supplied a string and no
  documentation, e.g., [47m(defabbrev foo () \"\")[0m.  Thanks to Rob Sumners
  for noticing this problem and providing a fix, which we have
  incorporated.

  For ACL2 executables built on Allegro Common Lisp, a Lisp error
  occurred when [47m[trace$][0m was called on other than a defined function
  symbol.  Now ACL2 prints a more useful error message.

  The proof-builder no longer accepts a [47m([0m[47m[verify][0m[47m)[0m command when some
  function symbol in the original goal no longer exists in the
  current ACL2 logical [world].  Thanks to John Erickson for bringing
  this issue to our attention.

  The function [47mld-redefinition-action[0m may now be called by the user.
  Thanks to Vernon Austel for suggesting that we remove this symbol
  from the list of so-called untouchables.

  The handling of free variables in hypotheses (see [free-variables])
  of rewrite and linear rules had a bug that prevented some proofs
  from going through.  Here is a simple example, essentially provided
  by Diana Moisuc, who we thank for bringing this issue to our
  attention.  The proof of the [47m[thm][0m below had failed, but now will
  succeed.  This particular bug prevented, for example, the [47m:all[0m
  behavior from occurring when the first hypothesis of the rule does
  not have free variables.  NOTE: Now that this bug has been fixed,
  you may find some proofs running much more slowly than before.  You
  can use [47m[accumulated-persistence][0m to locate rules that are slowing
  down your proofs because of excessive attention to free variables,
  and then execute [47m[add-match-free-override][0m for those rules (or,
  just change the rules themselves to specify [47m:once[0m in the
  [47m:[0m[47m[rule-classes][0m).

    (defstub foo1 (* ) => *)
    (skip-proofs
     (defthm aux-foo1
       (implies (and (integerp a)
                     (integerp i)
                     (equal (foo1 0)  (list 0 i)))
                (equal (foo1 a) (list 0 (+ a i))))
       :rule-classes ((:rewrite :match-free :all))))
    (thm
     (implies (and (integerp i)
                   (integerp a)
                   (equal (foo1 0) (list 0 i)))
              (equal (foo1 a) (list 0 (+ a i)))))

  Formerly, creation of large arrays could cause an error in the
  underlying Common Lisp implementation without helpful messages for
  the user.  Now, we check Common Lisp restrictions on arrays and
  print a helpful error message if they are violated, namely: each
  dimension must be less than the value of Common Lisp constant
  [47marray-dimension-limit[0m, and the product of the dimensions must be
  less than the value of Common Lisp constant [47marray-total-size-limit[0m.
  Thanks to Warren Hunt for bringing this issue to our attention.
  Note: this change also removes a former restriction of [47m[stobj][0m
  array fields to size smaller than 2^28-1, provided the underlying
  Lisp can support larger arrays.

  The [default-hints] in the current logical [world] were ignored by
  [47m[verify-guards][0m.  This has been fixed.  Thanks to Jared Davis for
  pointing out this bug and sending a helpful example.

  The [47m[brr][0m mechanism has been cleaned up in order to avoid hard errors
  and infinite loops that can arrive when typing interrupts
  ([47mcontrol-c[0m) or end-of-files ([47mcontrol-d[0m) inside the [47m[brr][0m loop.
  Thanks to Dave Greve, Olga Matlin, Eric Smith, and Serita Van
  Groningen for bringing this issue to our attention.  As a
  byproduct, if you type [47mcontrol-d[0m (or if inside emacs, [47mcontrol-c
  control-d[0m), you may now quit entirely out of ACL2 and lisp (see
  [good-bye]) in some cases where you formerly would not have, for
  example when sitting at the ACL2 prompt (which formerly, in Allegro
  Common Lisp for example, would merely take you into raw Lisp rather
  than quitting everything).

  We have eliminated structural flaws in the HTML documentation pages
  that could make them unreadable in some browsers.  Thanks to Bill
  Young for bringing this issue to our attention and to Joe Hendrix
  for diagnosing the problem.

  The [proof-builder] could run very slowly after many instructions in
  a given session.  This has been fixed; thanks to Art Flatau for
  bringing this problem to our attention.  (Implementation detail: We
  now keep tag-trees duplicate-free when we accumulate them into
  state.  This change could have minor speed advantages for some
  top-level proofs too, not just in the proof-builder.)

  The printing of accesses to stobjs using nth or update-nth has been
  done using symbolic constants since ACL2 Version_2.6.  However,
  there was a bug that prevented this feature from working for
  [47m[update-nth][0m except at a top-level call.  This has been fixed.
  Thanks to Julien Schmaltz for bringing this problem to our
  attention.  For example, consider these events:

    (defstobj st field0 field1)
    (thm (equal (nth 1 (update-nth 0 17 st)) (car (cons xxx yyy)))
         :hints ((\"Goal\" :in-theory (disable nth update-nth))))

  Before the fix, the proof attempt of the above silly thm printed the
  following.

    (NTH 1 (UPDATE-NTH *FIELD0* 17 ST))

  After the fix, we instead see the following.

    (NTH *FIELD1* (UPDATE-NTH *FIELD0* 17 ST))

  It is now possible to certify and subsequently include [books] that
  require guard-checking to be off.  For example, the book can
  contain the form [47m(defconst *silly* (car 3))[0m even though [47m3[0m fails to
  satisfy the guard of [47m[car][0m.  Formerly, it was necessary to execute
  [47m:[0m[47m[set-guard-checking][0m[47m nil[0m before a [47m[certify-book][0m or [47m[include-book][0m
  in order for such a form to be handled without error.  Thanks to
  Hanbing Liu for bringing this problem to our attention.

  Fixed a [proof-builder] bug that could probably cause a strange
  error, ``Attempt to access the plist field''.  Thanks to Bill Young
  for bringing this problem to our attention.

  Fixed a [proof-builder] bug that was failing to record applications
  of rewrite rules using the proof-builder's [47m:rewrite[0m command,
  causing the proof summary to omit mention of that rule (for
  example, when using the proof-builder's [47m:exit[0m command to generate
  an [47m:instructions[0m hint).  Thanks to Bill Young for pointing out this
  bug.

  Modernized some of the proof-tree emacs and infix printing stuff,
  thanks to suggestions made by Camm Maguire.")
 (NOTE-2-8-GUARDS
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on Guard-related Changes

  All the guard-related changes may be found elsewhere; in particular,
  see [note-2-8-bug-fixes].")
 (NOTE-2-8-NEW-FUNCTIONALITY
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on New Functionality

  WARNING: You may find that [47mcontrol-d[0m (in emacs, [47mcontrol-c control-d[0m)
  can throw you completely out of Lisp where it had not formerly done
  so.

  (CLISP and Allegro CL only) ACL2 now starts up inside the ACL2 loop
  --- that is, [47m([0m[47m[lp][0m[47m)[0m is executed automatically --- when built on
  CLISP or Allegro CL.  This was already the case for GCL and CMUCL,
  and it still is not true for LispWorks.  Thanks to Joe Corneli for
  bringing the CLISP command-line option [47m\"-i\"[0m to our attention, which
  led to this CLISP change and inspired reconsideration of how to do
  this for Allegro CL.

  Pete Manolios and Daron Vroon have changed the representation of
  ordinals in ACL2, defined algorithms for ordinal arithmetic, and
  created a library of theorems to reason about ordinal arithmetic.
  We thank them for these nice contributions.  See
  [note-2-8-ordinals] for details, in particular, for how to preserve
  existing proofs that depend on the previous ordinal representation.

  Sometimes users create rules of class [47m:[0m[47m[rewrite][0m that cause an
  infinite loop in the ACL2 rewriter.  This has lead to Lisp stack
  overflows and even segmentation faults.  Now, the depth of calls of
  functions in the ACL2 rewriter is limited, and under user control.
  See [rewrite-stack-limit].

  Macros [47m[mbe][0m (``must be equal'') and [47m[mbt][0m (``must be true'') have
  been introduced, which allow the user to attach fast executable
  definitions to (presumably slower) [47m:[0m[47m[logic][0m mode functions.  Thanks
  to Vernon Austel for a key idea.  Also provided is a macro
  [47m[defexec][0m, which employs [47m[mbe][0m but enforces the requirement that
  the executable definition also terminates.  Thanks to Jose Luis
  Ruiz Reina for collaborating in the design and development of
  [47m[defexec][0m, and for useful comments from a number of others as well
  in the development of [47mmbe[0m including Joe Hendrix and Rob Sumners.

  Definitions have been added for functions [47m[rassoc-eq][0m and
  [47m[rassoc-equal][0m, which are like [47m[rassoc][0m but use different tests and
  have different guards.  (Compare [47m[assoc-eq][0m and [47m[assoc-equal][0m,
  which are in similar relation to [47m[assoc][0m.)

  The user can now control multiple matching for free variables in
  hypotheses for [47m:[0m[47m[forward-chaining][0m rules, as has already been
  supported for [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules.  For
  [47m:forward-chaining[0m rules, ``free variables'' are those in the
  hypotheses not bound by a given trigger term.  As for [47m:rewrite[0m and
  [47m:linear[0m rules, free-variable matching may be limited to the first
  successful attempt by specifying [47m:match-free :once[0m with
  [47m:forward-chaining[0m in the [47m:[0m[47m[rule-classes][0m, and
  [47m[add-match-free-override][0m may be used to modify the behavior of an
  existing rule.  Thanks to Erik Reeber for most of the
  implementation of these new capabilities, as well as significant
  assistance with a corresponding new documentation topic (see
  [free-variables-examples-forward-chaining]).

  It is no longer necessary to specify [47m(set-match-free-error nil)[0m in
  order to avoid errors when a rule with free variables in its
  hypotheses is missing the [47m:match-free[0m field.  (This was already
  true during book certification, but now it is the case in
  interactive sessions as well.)

  The form [47m(break-on-error)[0m causes, at least for most Lisps, entry into
  the Lisp debugger whenever ACL2 causes an error.  See
  [break-on-error].  Thanks to John Erickson for providing
  encouragement to provide this feature.

  A new [47m[table][0m has been provided so that advanced users can override
  the built-in [47muntranslate[0m functionality.  See
  [user-defined-functions-table].

  The [47m[pstack][0m mechanism (formerly denoted [47mcheckpoints[0m) has been
  improved.  The ``process [prover] stack,'' or pstack, is
  automatically printed when proofs abort.  Evaluation of function
  calls on explicit arguments during proofs is now tracked.  Actual
  parameters are shown with [47m(pstack t)[0m rather than formals.  Thanks
  to Bill Legato for suggesting the first two of these improvements
  and, in general, encouraging changes that make ACL2 easier to use.

  The [47m[defstobj][0m event is now allowed to take an [47m:inline[0m argument,
  which can speed up execution.  Thanks to Rob Sumners for suggesting
  and implementing this new feature.

  Macro [47m[assert$][0m has been added in order to make it easy to write
  assertions in one's code.  Semantically, [47m(assert$ test form)[0m is the
  same as [47mform[0m, but it causes a hard error (using [47m[illegal][0m) if [47mtest[0m
  evaluates to [47mnil[0m.

  Macro [47m[cw-gstack][0m no longer takes arguments for the gstack or
  [47m[state][0m.  However, it now takes a keyword argument (which is
  optional), [47m:evisc-tuple[0m, that can be used to control how it prints
  terms.  In particular, [47mcw-gstack[0m abbreviates large terms by
  default, but [47m(cw-gstack :evisc-tuple nil)[0m causes terms to be
  printed in full.  Thanks to Robert Krug and Eric Smith for
  requesting this improvement.

  The advanced user now has more control over the evisceration of
  terms.  See [ld-evisc-tuple], in particular the new paragraph on
  ``The printing of error messages and warnings.''

  The [47m[include-book][0m event now has an additional (optional) keyword,
  [47m:dir[0m.  The value of [47m:dir[0m should be a keyword that is associated
  with an absolute directory pathname to be used in place of the
  current book directory (see [cbd]) for resolving the first argument
  of [47minclude-book[0m to an absolute pathname.  At start-up, the only
  such keyword is [47m:system[0m, so that for example [47m(include-book
  \"arithmetic/top\" :dir :system)[0m will include the book
  [47m\"arithmetic/top\"[0m under the [47m\"books/\"[0m directory of your ACL2
  installation.  But you can associate ``projects'' with keywords
  using [47m[add-include-book-dir][0m, e.g., [47m(add-include-book-dir
  :my-project \"/u/smith/project0/\")[0m.  See [add-include-book-dir] and
  also see [delete-include-book-dir] and see [include-book].  Note:
  You will probably not find [47m:dir :system[0m to be useful if the
  distributed books are not placed in the path of their original
  location, pointed to by [47m:dir :system[0m, which will often happen if
  the executable image is obtained from another site.  Also see
  [include-book], in particular its ``soundness warning''.

  The printing of results in raw mode (see [set-raw-mode]) may now be
  partially controlled by the user: see [47madd-raw-arity[0m.  [Note added
  2021: this utility has been removed and is no longer necessary.]
  Also, newlines are printed when necessary before the value is
  printed.

  For those using Unix/Linux `make': A [47mcert.acl2[0m file can contain forms
  to be evaluated before an appropriate [47m[certify-book][0m command is
  invoked automatically (not included in [47mcert.acl2[0m).

  Jared Davis has contributed a new set of books for ordered finite set
  theory to the standard distribution,
  [47mbooks/finite-set-theory/osets-0.81/[0m.  See the [47mREADME[0m file in that
  directory.  Thanks, Jared.

  Robert Krug has contributed two related changes (thanks, Robert!) in
  support of stronger arithmetic reasoning.  First, one can now
  enable and disable nonlinear arithmetic with a [47m:nonlinearp[0m hint,
  which will override the default provided by [47m[set-non-linearp][0m
  (initially, [47mnil[0m).  See [hints].  Second, [computed-hints] can now
  have access to the [47mHISTORY[0m, [47mPSPV[0m, and [47mCTX[0m variables of the
  waterfall, which (for example) allows the writing of a hint which
  will enable nonlinear arithmetic on precisely those goals that are
  [47mstable-under-simplificationp[0m.  See [computed-hints].

  Robert Krug has contributed a new set of arithmetic books to the
  standard distribution, [47mbooks/arithmetic-3/[0m.  See the [47mREADME[0m file in
  that directory.  Thanks, Robert.")
 (NOTE-2-8-ORDINALS
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on Changes to the Ordinals

  Please see [ordinals].")
 (NOTE-2-8-OTHER
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on Miscellaneous Changes

  Execution of [47m[table][0m events has been sped up in many cases by
  avoiding excessive consing.

  ACL2 now warns if [47m:[0m[47m[rewrite][0m (or [47m:[0m[47m[definition][0m) rules contain free
  variables on the right-hand side.  Thanks to Dave Greve for raising
  this issue.

  Emacs file [47memacs/emacs-acl2.el[0m has been updated to better comprehend
  the notion of the ``ACL2 shell'', which is the buffer to which ACL2
  forms are written by commands defined in the above file.  Thus,
  command [47mcontrol-t e[0m has been modified always to write to the ACL2
  shell (which is [47m\"*shell*\"[0m by default), and the following new
  commands have been defined.

      o control-t c
      Set the ACL2 shell to the current buffer.  o control-t b
      Change to the ACL2 shell.

  The commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pr][0m may now be given a macro name that
  corresponds via the [47mmacro-aliases-table[0m to a function name, so that
  for example [47m:pl append[0m is treated the same as [47m:pl binary-append[0m.  A
  more interesting improvement, for [47m:pl[0m only, is that [47m:pl[0m may now
  take any term.  When [47m:pl[0m is given a term other than a symbol, it
  will print all rewrite rules that match that term.  Thanks to David
  Russinoff, Robert Krug, and Bill Legato for getting this going.

  A new function, [47m[pkg-witness][0m, returns a symbol in the given package.

  The installation instructions have been updated, for example to give
  more guidance on obtaining Lisp implementations and to mention the
  acl2-help mailing list.

  Jared Davis has suggested some symbols to be added to [47m*acl2-exports*[0m,
  and we have done so.  Thanks, Jared.

      o [47mMFC[0m (used in [47m[syntaxp][0m and [47m[extended-metafunctions][0m; thanks also to
      Robert Krug for this one) o [47mID[0m, [47mCLAUSE[0m, [47mWORLD[0m, and
      [47mSTABLE-UNDER-SIMPLIFICATIONP[0m (used in [47m[computed-hints][0m) o
      [47m[set-default-hints][0m

  The command [47m:[0m[47m[pe][0m has been improved so that when the event is inside
  an included book, the path of included books (from the top-level
  book down to the one containing the event) is shown.  Thanks to
  Eric Smith (perhaps among others) for pointing out the utility of
  this improvement.

  A new release of the rtl library has been included: [47mbooks/rtl/rel4/[0m.
  See the [47mREADME[0m file in that directory.")
 (NOTE-2-8-PROOF-BUILDER
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on proof-builder Changes

  Added new [proof-builder] commands [47mwrap1[0m, [47mwrap[0m, and [47mwrap-induct[0m.
  [47mWrap[0m replaces multiple goals by their conjunction: [47m(wrap instr1
  instr2 ...)[0m employs [47mwrap1[0m so that the indicated instructions create
  only at most one new goal.  [47mWrap-induct[0m is a simple example of the
  use of [47mwrap[0m, so that induction creates only one goal (the
  conjunction of the base and induction steps).  [47mWrap1[0m can be used
  immediately after a prover call ([47mbash[0m, [47mprove[0m, [47mreduce[0m, [47mbdd[0m, or
  [47minduct[0m) to collapse the new goals into one.  See
  [proof-builder-commands].

  The [proof-builder] command [47m=[0m failed to work as expected when a
  governing [47mIF[0m-test of the current term is T.  This has been fixed
  (by fixing source function [47mconjuncts-of[0m).  Thanks to Yoann
  Padioleau for bringing this problem to our attention.

  The [47mtype-alist[0m command now takes optional arguments that control
  whether or not the governors and/or conclusion are used in
  computing the context that is printed (see
  [proof-builder-commands], specifically subtopic [47mtype-alist[0m).
  Thanks to Rob Sumners for suggesting this improvement.

  The macro [47m[toggle-pc-macro][0m has always taken an optional second
  argument of [47matomic-macro[0m or [47mmacro[0m.  However, this was not clearly
  documented, and those two symbols had to be in the [47mACL2[0m package.
  Both of these problems have been remedied.  Thanks to John Erickson
  for bringing the lack of documentation of the second argument to
  our attention.")
 (NOTE-2-8-PROOFS
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on Changes in Proof Engine

  ACL2 now prevents certain rewriting loops; see [rewrite-stack-limit].

  During the computation of [47m[constraint][0ms for functional instantiation,
  [47m(prog2$ term1 term2)[0m and [47m(the type term2)[0m are now treated as [47mterm2[0m.

  A change has been made in heuristics for controlling rewriting during
  proofs by induction.  Formerly, during induction proofs, ACL2
  suppressed rewriting of certain ``induction hypothesis'' terms, and
  forced expansion of certain ``induction conclusion'' terms, until
  rewriting had stabilized.  This meddling with the rewriter is still
  turned off when rewriting has stabilized, but it is now turned off
  earlier once an ancestor has been through the rewriter and the
  current goal is free of ``induction conclusion'' terms.  Thanks to
  Dave Greve and Matt Wilding for providing an example and associated
  analysis that led us to look for a heuristic modification.

  A change has been made in the heuristics for handling certain
  ``weak'' [compound-recognizer] rules when building contexts.  Those
  who want to dig deeply into this change are welcome to look at the
  code following the call of [47mmost-recent-enabled-recog-tuple[0m in the
  code for function [47massume-true-false[0m in the ACL2 sources.

  The handling of free variables in a hypothesis of a [rewrite] rule
  (see [free-variables]) has been improved in the case that the
  hypothesis is of the form [47m(equiv x y)[0m, where [47mequiv[0m is a known
  equivalence relation (see [equivalence]).  Previously, if the
  rewriter was attempting to rewrite the hypothesis [47m(equiv x y)[0m of a
  rewrite rule, in a context where [47mx'[0m is an instance of [47mx[0m, then the
  rewriter could fail to notice a term [47m(equiv x' y')[0m true in the
  current context where [47my'[0m is an instance of [47my[0m, in the case that [47mx'[0m
  precedes [47my'[0m in the [47m[term-order][0m.  This has been remedied.  This
  improvement applies regardless of whether [47mx[0m, [47my[0m, or (we believe)
  both are already fully instantiated in the present context.  Thanks
  to Joe Hendrix for bringing up an example and to Vernon Austel for
  providing another, simple example.

  A very minor change has been made to the rewriter in the case that an
  equality appears on the left-hand side of a [47m:[0m[47m[rewrite][0m rule.
  Formerly, when such an equality [47m(equal x y)[0m was commuted to [47m(equal
  y x)[0m in order for the rule to match the current term, then all
  equalities on the instantiated right-hand side of the rule were
  commuted, except for those occurring inside another equality.  The
  instantiated right-hand side is no longer modified.  It seems very
  unlikely that this change will cause proofs to fail, though we
  cannot completely rule out that possibility.

  We have modified how the ACL2 simplifier handles the application of a
  defined function symbol to constant arguments in certain cases,
  which we now describe.  As before, ACL2 attempts to simplify such a
  function application by evaluation, provided the
  [47m:[0m[47m[executable-counterpart][0m of the function is enabled.  And as
  before, if that evaluation fails due to a subroutine call of a
  constrained function (introduced by [47m[encapsulate][0m), ACL2 may wrap a
  call of [47mhide[0m around this function application.  (See [hide].)  But
  now, ACL2 attempts to apply definitions and rewrite rules in the
  case that this evaluation fails, and only if the resulting term is
  unchanged does ACL2 wrap [47m[hide][0m around this function application.
  Thanks to Matt Wilding for bringing up the idea of this
  modification.

  The generation of \"Goal\" for recursive (and mutually-recursive)
  definitions now uses the subsumption/replacement limitation
  (default 500).  See [case-split-limitations].

  Default hints now apply to hints given in definitions, not just
  theorems.  See [default-hints].

  Thanks to Robert Krug for implementing the following two improvements
  involving linear arithmetic reasoning: linear arithmetic now uses
  the conclusions of [47m[forward-chaining][0m rules, and [47m[type-set][0m now
  uses a small amount of linear reasoning when deciding inequalities.")
 (NOTE-2-8-RULES
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on Changes in Rules, Definitions, and
  Constants

  The [theory] [47m[minimal-theory][0m has been changed by adding the
  [definition] [rune] for [47m[mv-nth][0m to the theory.  A corresponding
  change has been made to the theory warning mechanism, which was
  failing to warn if the definition of [47mmv-nth[0m is disabled, even
  though calls of [47mmv-nth[0m can be expanded by special-purpose code in
  the rewriter.  Thanks to Serita Van Groningen for pointing out this
  problem with the theory warning mechanism.

  The [47m[defevaluator][0m event has been modified so that in the body of the
  evaluator function, to add a new case [47m(ATOM X)[0m (returning [47mnil[0m) has
  been inserted immediately after the case [47m(EQ (CAR X) 'QUOTE)[0m.  This
  is a no-op semantically but may speed up proofs.  Thanks to Warren
  Hunt for suggesting this change.

  A new form of [47m:[0m[47m[compound-recognizer][0m rule is now allowed:

    (if (fn x) concl1 concl2)

  This is equivalent to an existing form:

    (and (implies (fn x) concl1)
         (implies (not (fn x)) concl2))

  Thanks to Josh Purinton for bringing this to our attention.

  Rewrite rules [47mrealpart-+[0m and [47mimagpart-+[0m have been added in order to
  simplify the [47m[realpart][0m and [47m[imagpart][0m (respectively) of a sum.
  They follow from a theorem [47madd-def-complex[0m that equates a sum with
  the complex number formed by adding real and imaginary parts.  All
  three of these theorems may be found in source file [47maxioms.lisp[0m.
  Thanks to Eric Smith for raising a question leading to these
  additions, as well as to Joe Hendrix and Vernon Austel for helpful
  suggestions.")
 (NOTE-2-8-SYSTEM
  (NOTE-2-8)
  "ACL2 Version 2.8 Notes on System-level Changes

  ACL2 now runs on OpenMCL, ``an opensourced Common Lisp
  implementation, derived from Digitool's Macintosh Common Lisp
  product.'' Thanks to Greg Wright and Robert Krug for doing most of
  the work for this port.

  When [47m([0m[47m[lp][0m[47m)[0m is first executed, the underlying raw Lisp package will
  change to [47m\"ACL2\"[0m (if that is not already the current package in raw
  Lisp).  This is a minor change that will probably not be noticed,
  since up to now it has probably been the case that the ACL2
  executable starts up with [47m\"ACL2\"[0m as the underlying raw Lisp
  package.  But this change was made because we have been informed
  that ACL2 executables based on OpenMCL need not start up with
  [47m\"ACL2\"[0m as the underlying raw Lisp package.

  ACL2 now runs on MCL 5.0.  Thanks to Pascal Costanza for updates to
  the instructions in file [47mmcl-acl2-startup.lisp[0m and for an update to
  the ACL2 sources (parameter [47m*compiled-file-extension*[0m).")
 (NOTE-2-8{R}
  (RELEASE-NOTES)
  "ACL2 Version 2.8(r) (March, 2003) Notes

  The [47mMakefile[0m has been modified by adding a new target, [47mclean-links[0m.
  This can be used in order to remove all soft links, which is useful
  if the directory is copied or moved to a new location or if there
  are file system changes that cause problems with link pathnames.

  Please also see [note-2-8] for changes to Version_2.8 of ACL2.")
 (NOTE-2-9
  (RELEASE-NOTES)
  "ACL2 Version 2.9 (October, 2004) Notes


Table of Contents

    * BUG FIXES

    * NEW FUNCTIONALITY

    * CHANGES IN PROOF ENGINE

    * GUARD-RELATED CHANGES

    * PROOF-BUILDER CHANGES

    * SYSTEM-LEVEL CHANGES

    * BOOK CHANGES

    * MISCELLANEOUS CHANGES

  [31;1mBUG FIXES.[0m

  We fixed a soundness bug due to a conflict between user-supplied
  package names and internal package names (obtained by prepending a
  Lisp constant, [47m*1*-package-prefix*[0m) and user-supplied package
  names.  For example, the form [47m(defpkg \"ACL2_*1*_MYPKG\" ())[0m is no
  longer legal.  Thanks to Robert Krug for asking a question that led
  directly to the discovery of this bug.

  We fixed a soundness bug that allows [47m:[0m[47m[logic][0m mode functions to call
  [47m:[0m[47m[program][0m mode functions.  The fix furthermore prevents functions
  with [guard]s verified from calling functions with guards not
  verified.  We had thought we already prevented all this, but there
  was a problem with the interaction of [47m[local][0m definitions and
  redundancy checking (see [redundant-events]).

  We fixed a soundness bug that could occur when built-in functions
  were called during macroexpansion (a hole in so-called
  ``safe-mode'').

  Fixed a minor bug in system functions [47mgenvar1[0m and [47mgenvar[0m, where [47m[eq][0m
  had been used in place of [47m[eql][0m.  This bug was discovered during
  the plugging of a hole in safe-mode, mentioned just above.

  We fixed handling of the [47m:inline[0m keyword for [47m[defstobj][0m, which
  previously could cause raw Lisp errors in OpenMCL and CMU Common
  Lisp.  Thanks to John Matthews for bringing this issue to our
  attention.

  Calls of [47m[include-book][0m could result in a state for which some
  function definitions were not compiled that should have been.  The
  result could be performance degradation or even stack overflows.
  This situation could arise in the following two ways.

      o Inclusion of a book with an absolute pathname that differs from the
      absolute pathname at certification time, presumably because of
      the use of soft links.  Thanks to Bob Boyer and Warren Hunt for
      bringing a stack overflow to our attention that led us to this
      fix.

      o Large [47m[mutual-recursion][0m nests (more than 20 functions) are
      executed in a superior book.

  We fixed some performance bugs that can increase the speed of
  [47m[include-book][0m calls by a factor of close to 2.  Thanks to Eric
  Smith for asking if we could speed up [47m[include-book][0m processing; we
  have done so in the past, but primarily focusing on large
  [47m[mutual-recursion][0m nests (which have nothing in particular to do
  with the current improvements).  Also, thanks to Rob Sumners for a
  very useful remark early in the process that kept us from drawing
  an incorrect conclusion at that point.

  We fixed [47m:[0m[47m[pl][0m so that it can be run on a form that returns multiple
  values, which it could not do previously.  Thanks to Eric Smith for
  pointing out this problem.

  Fixed a bug in the Allegro ACL2 trace utility (see [trace$]) that was
  causing ``[47m10>[0m'' to be printed as ``[47m9>[0m'', ``[47m11>[0m'' to be printed as
  ``[47m10 >[0m'', ``[47m12>[0m'' to be printed as ``[47m11 >[0m'', and so on.

  Fixed a [proof-builder] bug that was preventing the use of the [47mDV[0m
  command (or a numerical command) on [47m[let][0m expressions.  Thanks to
  Bill Young for pointing out this problem.

  Fixed a bug in a comment on how to set [47mACL2_BOOKS_DIR[0m in the
  makefile.  Thanks to Dave Greve for pointing out this problem.

  Fixed a potential soundness bug in the linear arithmetic routines.
  Thanks to Jared Davis for noticing this problem and to Robert Krug
  for implementing the fix.  (Technical details: We had been assuming
  that polynomials were being normalized --- see the definition of
  good-polyp in linear-a.lisp --- but this assumption was false.)

  When the macro [47m[open-trace-file][0m is opened twice in succession, it
  now automatically closes the first trace output channel before
  opening another.

  It is now possible to use `make' to build ACL2 on Windows systems
  that support `make'.  Thanks to Pete Manolios and Mike Thomas for
  pointing out the problem, to Jared Davis and Mike for helping us to
  analyze the problem, and to Jared for testing the fix.

  Fixed a bug in the [guard] of [47m[with-output][0m that was causing a
  needless guard violation.

  [31;1mNEW FUNCTIONALITY.[0m

  The new events [47m[add-default-hints][0m and [47m[remove-default-hints][0m allow
  one to append to or subtract from the current list of default
  hints.  The event [47m[set-default-hints][0m continues to set the list of
  default hints, discarding the previous value of the
  [47m[default-hints][0m.  Note that [47m[set-default-hints][0m is still [47m[local][0m to
  the [47m[encapsulate][0m or book in which it occurs, and
  [47m[add-default-hints][0m has the same property, although neither is
  implemented any longer using the [47m[ACL2-defaults-table][0m.  New events
  [47m[add-default-hints!][0m, [47m[remove-default-hints!][0m, and
  [47m[set-default-hints!][0m are the same as [47m[add-default-hints][0m,
  [47m[remove-default-hints][0m, and [47m[set-default-hints][0m, respectively,
  except that the former three events are not [47m[local][0m to their
  enclosing [47m[encapsulate][0m or book.  Thanks to Jared Davis for
  suggesting these enhancements.

  OpenMCL's tracing routines have been modified in a similar manner as
  those of Allegro CL.  Thanks to Robert Krug for providing this
  enhancement.

  Guard-checking can now be caused to happen on recursive calls.  See
  ``GUARD-RELATED CHANGES'' below for details.

  Advanced users can now inhibit compilation of so-called ``*1*
  functions'' with the [47m:comp[0m command; see [comp].  Thanks to Rob
  Sumners for suggesting this enhancement.

  Added new legal argument [47mhard?[0m for the [47m[er][0m macro, which is now
  documented.  See [er].  Thanks to Rob Sumners for a discussion
  leading to this change.  Also, the three legal first arguments to
  [47m[er][0m --- [47mhard[0m, [47mhard?[0m, and [47msoft[0m --- may now be in any package
  (thanks to Jared Davis for bringing this issue to our attention).

  We have removed the requirement that for a rule's hypothesis
  [47m(bind-free term var-list)[0m, at least one variable must occur free in
  [47mterm[0m.  For example, the expression [47m(bind-free (bind-divisor a b)
  (x))[0m was legal because [47ma[0m and [47mb[0m occur free in [47m(bind-divisor a b)[0m;
  but [47m(bind-free (foo (bar)) (x))[0m was not legal.  The latter is no
  longer disallowed. (Technical note: this allows [47m[bind-free][0m to be
  used to create explicit substitutions in metafunction hypotheses.)

  The following two enhancements have been implemented for rules of
  class [47m:[0m[47m[meta][0m.  Thanks to Eric Smith for requesting more control of
  reasoning with [47m:[0m[47m[meta][0m rules, which led to these enhancements, and
  to him and Robert Krug for helpful discussions.

      o It is now possible to control backchaining in rules of class
      [47m:[0m[47m[meta][0m by providing a [47m:backchain-limit-lst[0m argument, as was
      already allowed for rules of class [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m.
      See [rule-classes].  However, unlike those other two rule
      classes, the value for [47m:backchain-limit-lst[0m is prohibited from
      being a non-empty list; it must be either [47mnil[0m or a non-negative
      integer.

      o (For advanced users.) It is now legal for hypothesis metafunctions
      to generate, in essence, calls of [47m[syntaxp][0m and [47m[bind-free][0m,
      handled essentially as they are handled in hypotheses of
      [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules.  We say ``essentially''
      primarily because both [47m[syntaxp][0m and [47m[bind-free][0m are actually
      macros, but hypothesis metafunctions must generate translated
      terms (see [term]).  The enterprising advanced user can call
      [47m:[0m[47m[trans][0m to see examples of translated terms corresponding to
      calls of [47m[syntaxp][0m and [47m[bind-free][0m.

  A new command [47m:[0m[47m[trans!][0m has been added, which is like [47m:[0m[47m[trans][0m except
  that [47m:[0m[47m[trans!][0m ignored issues of single-threadedness.  See
  [trans!].  Thanks to Eric Smith for suggesting this addition.

  The [47m:[0m[47m[pf][0m command now works when the argument is the name of a macro
  associated with a function by [macro-aliases-table].

  [31;1mCHANGES IN PROOF ENGINE.[0m

  The simplifier has been changed slightly in order to avoid using
  [forward-chaining] facts derived from a literal (essentially, a
  top-level hypothesis or conclusion) that has been rewritten.  As a
  practical matter, this may mean that the user should not expect
  forward-chaining to take place on a term that can be rewritten for
  any reason (generally function expansion or application of rewrite
  rules).  Formerly, the restriction was less severe:
  forward-chaining facts from a hypothesis could be used as long as
  the hypothesis was not rewritten to [47mt[0m.  Thanks to Art Flatau for
  providing an example that led us to make this change; see the
  comments in source function [47mrewrite-clause[0m for details.

  The rewriter has been modified to work slightly harder in relieving
  hypotheses.  Thanks to Eric Smith for providing an example that
  inspired the following, which illustrates the issue.  Suppose we
  introduce functions [47mfoo[0m and [47mbar[0m with the (non-[47m[local][0m) properties
  shown below.

    (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)))

  Consider what happens when ACL2's rewriter is used to prove the
  following theorem.

    (thm (foo (bar y)))

  With ACL2's inside-out rewriting, [47m(bar y)[0m is first considered, but
  rewrite rule [47mbar-holds-propositionally[0m does not apply because the
  context requires preserving equality, not mere Boolean ([47miff[0m)
  equivalence.  Then the rewriter moves its attention outward and
  sees the term [47m(foo (bar y))[0m.  It attempts to apply the rule
  [47mfoo-holds[0m, in a context created by binding its variable [47mx[0m to the
  term [47m(bar y)[0m.  It then attempts to relieve the hypothesis [47mx[0m of rule
  [47mfoo-holds[0m in that context.  Before this change, ACL2 basically
  assumed that since rewriting was inside out, then [47m(bar y)[0m had
  already been rewritten as much as possible, so the rewrite of [47mx[0m in
  the aforementioned context (binding [47mx[0m to [47m(bar y)[0m) simply returned
  [47m(bar y)[0m, and the attempt to relieve the hypothesis of [47mfoo-holds[0m
  failed.  The change is essentially for ACL2's rewriter to make a
  second pass through the rewriter when the attempt fails to rewrite
  a variable to [47mt[0m, this time using the fact that we are in a Boolean
  context.  (We mention that source function [47mrewrite-solidify-plus[0m
  implements this idea, for those who want to dig deeply into this
  issue.)  In our example, that means that the rewriter considers
  [47m(bar y)[0m in a Boolean context, where it may apply the rule
  [47mbar-holds-propositionally[0m to relieve the hypothesis successfully.

  When [47m([0m[47m[set-non-linearp][0m[47m t)[0m has been executed, [non-linear-arithmetic]
  can now be applied in some cases for which it previously was not.
  Thanks to Robert Krug for supplying this modification and to Julien
  Schmaltz for providing a motivating example.

  We modified the rewriter to avoid certain infinite loops caused by an
  interaction of the opening of recursive functions with equality
  reasoning.  (This change is documented in detail in the source
  code, in particular functions [47mrewrite-fncall[0m and
  [47mfnstack-term-member[0m.)  Thanks to Fares Fraij for sending us an
  example that led us to make this change.

  The [47m:[0m[47m[executable-counterpart][0m of function [47m[hide][0m is now disabled when
  ACL2 starts up.  This removes an anomaly, for example that

    (thm (not (equal 1 (* (hide 0) a))))

  succeeded while

    (thm (equal (foo (equal 1 (* (hide 0) a))) (foo nil)))

  failed.  Now both fail.

  The theory [47m*s-prop-theory*[0m is no longer used by the [3mproof-builder[0m; it
  has been replaced by [47m(theory '[0m[47m[minimal-theory][0m.  We have left the
  constant [47m*s-prop-theory*[0m defined in the source code in support of
  existing books, however.  This change eliminates annoying theory
  warnings printed upon invocation of [proof-builder] commands
  [47ms-prop[0m, [47msl[0m, and [47msplit[0m.

  Terms are now kept in an internal form that avoids calls of primitive
  functions (built-ins without explicit definitions; see code for
  [47mcons-term[0m for details), in favor of the constants that result from
  evaluating those calls.  So for example, the internal form for
  [47m(cons 1 2)[0m is [47m(quote (1 . 2))[0m.  This change was made at around the
  same time as changes in support of [47m[bind-free][0m; see above.  One
  consequence is that the splitting of goals into cases (technically,
  source function [47mclausify[0m and even more technically, source function
  [47mcall-stack[0m) has been modified, which can cause subgoal numbers to
  change.

  [31;1mGUARD-RELATED CHANGES.[0m

  Guard-checking can now be caused to happen on recursive calls, where
  this was formerly not the case for [47m:[0m[47m[program][0m mode functions and,
  perhaps more important, for [47m:[0m[47m[logic][0m mode functions whose [guard]s
  have not been verified.  Moreover, a warning is printed when ACL2
  does not rule out the exclusion of guard-checking on recursive
  calls.  See [set-guard-checking].  Thanks to David Rager for
  bringing this issue to our attention, and to Rob Sumners and the
  Univ. of Texas ACL2 seminar in general for their feedback.

  Guard violations are reported with less of the offending term hidden.
  Thanks to Jared Davis for suggesting that we look at this issue.

  [31;1mPROOF-BUILDER CHANGES.[0m

  We fixed the [proof-builder] so that diving works as you might expect
  for a macro call [47m(op a b c)[0m representing [47m(binary-op a (binary-op b
  c))[0m.  In the past, if the current term was of the form [47m(append t1
  t2 t3)[0m, then [47m(DV 3)[0m (and [47m3[0m) would dive to [47mt3[0m even though the
  corresponding function call is [47m(binary-append t1 (binary-append t2
  t3))[0m.  This is still the case, but now this behavior holds for any
  macro associated with a function in [47mbinop-table[0m (see [add-binop]).
  Moreover, users can now write customized diving functions; see
  [dive-into-macros-table], and also see
  [47mbooks/misc/rtl-untranslate.lisp[0m for example calls to
  [47m[add-dive-into-macro][0m.  Of course, the old behavior can still be
  obtained using the [proof-builder]'s [47mDIVE[0m command; see
  [proof-builder-commands].

  The [47mrunes[0m command in the [proof-builder] now shows only the [rune]s
  used by the most recent primitive or macro command (as shown by
  [47m:comm[0m), unless it is given a non-[47mnil[0m argument.  Also,
  [proof-builder] command [47mlemmas-used[0m has been added as, in essence,
  an alias for [47mrunes[0m.

  (The following two items are also mentioned above under ``BUG
  FIXES.'')

  Fixed a [proof-builder] bug that was preventing the use of the [47mDV[0m
  command (or a numerical command) on [47m[let][0m expressions.  Thanks to
  Bill Young for pointing out this problem.

  The theory [47m*s-prop-theory*[0m is no longer used by the [3mproof-builder[0m; it
  has been replaced by [47m(theory '[0m[47m[minimal-theory][0m.  We have left the
  constant [47m*s-prop-theory*[0m defined in the source code in support of
  existing books, however.  This change eliminates annoying theory
  warnings printed upon invocation of [proof-builder] commands
  [47ms-prop[0m, [47msl[0m, and [47msplit[0m.

  [31;1mSYSTEM-LEVEL CHANGES.[0m

  Fixed a problem with building ACL2 on CMUCL in some systems (source
  function [47msave-acl2-in-cmulisp[0m).  Thanks to Bill Pase for bringing
  this to our attention.

  The installation instructions have been extended to include
  instructions for building on GCL in Mac OS X.  Thanks to Jun Sawada
  and Camm Maguire.

  Initial pre-allocation of space has been updated for GCL to reflect
  more current GCL executables (we considered GCL 2.6.1-38).  This
  can help avoid running out of memory for large ACL2 sessions.

  The main [47mMakefile[0m has been replaced by [47mGNUmakefile[0m, in order to
  enforce the use of GNU `make'.  If you use another `make' program,
  you'll get an error message that may help you proceed.

  (GCL only) SGC is no longer turned on for GCL 2.6 sub-versions
  through 2.6.3 if [47msi::*optimize-maximum-pages*[0m is bound to [47mT[0m, due to
  an apparent issue with their interaction in those sub-versions.
  Also, we have eliminated preallocation for all versions after 2.6.1
  because GCL doesn't need it (comments are in source function
  [47msave-acl2-in-akcl[0m).  Thanks to Camm Maguire for excellent GCL help
  and guidance, and to Camm and Bob Boyer for useful discussions.

  We have removed support for so-called ``small'' images.  Thus,
  [47m:[0m[47m[doc][0m, [47m:[0m[47m[pe][0m and [47m:[0m[47m[pc][0m, [47m[verify-termination][0m, and other commands
  are fully supported in ACL2 saved images.  Because of this and
  other changes in the generation of the so-called ``*1*'' logical
  functions, related to guards (as described above in -GUARD-RELATED
  CHANGES'', and related to the discussion of safe-mode in ``BUG
  FIXES'' above), image sizes have increased substantially.

  We no longer [47mtime[0m or run ``[47mnice[0m'' the certification of individual
  books.  The file [47mbooks/Makefile-generic[0m had done these by default,
  and some individual distributed and workshop book directories had
  [47mMakefile[0ms that did so as well.  Thanks to Mike Thomas, who pointed
  out the lack of [47mnice[0m on some Windows systems (and we decided on
  this simple solution).  Overall targets in [47mbooks/Makefile[0m still
  [47mtime[0m their runs by default, and the particular [47mtime[0m program is now
  controlled by a [47mMakefile[0m variable.

  Failures during [47mmake certify-books[0m or [47mmake regression[0m now show up in
  the log as ``[47m**CERTIFICATION FAILED**[0m'', regardless of the
  operating system (as long as it supports `make').  Formerly, one
  searched for ``[47m**[0m'' but this did not appear in openMCL runs.

  We have eliminated ``Undefined function'' warnings that could occur
  in OpenMCL.

  [31;1mBOOK CHANGES.[0m

  Reconciled the definitions of [47mfirstn[0m in [47mbook/misc/csort.lisp[0m,
  [47mbooks/bdd/bdd-primitives.lisp[0m,
  [47mbooks/ordinals/ordinal-definitions.lisp[0m, and
  [47mbooks/data-structures/list-defuns.lisp[0m.  Thanks to Ray Richards for
  bringing this issue to our attention.

  Distributed book [47mbooks/misc/defpun[0m now can handle [stobj]s where it
  did not previously.  Thanks to John Matthews for bringing this
  issue to our attention.

  The \"make\" variable [47mCOMPILE_FLG[0m in file [47mbooks/Makefile-generic[0m
  formerly only had an effect if there was a [47mcert.acl2[0m file present.
  That oversight has been remedied.

  File [47m\"books/arithmetic/certify.lsp\"[0m was missing a [47m[certify-book][0m
  command for [47m\"natp-posp\"[0m.  Thanks to John Cowles for noticing this
  deficiency and supplying a fix.  (This file is of use to those who
  want to certify the [47m\"books/arithmetic/\"[0m books without using
  [47m\"make\"[0m.)

  A few small changes have been made to [47m\"books/rtl/rel4\"[0m.

  Small changes were made to books [47mmisc/symbol-btree[0m and
  [47mmisc/rtl-untranslate[0m.  In particular, the definition of
  [47msymbol-btreep[0m was strengthened.

  We made a minor fix to [47mbooks/ordinals/e0-ordinal.lisp[0m, adding
  [47m(verify-guards ob+)[0m and hence [47m(verify-guards ocmp)[0m as well.  This
  was necessitated by the fix prohibiting functions with guards
  verified from calling functions with guards not verified (see also
  the related discussion under ``BUG FIXES'' above).

  [31;1mMISCELLANEOUS CHANGES.[0m

  Further sped up processing of large [47m[mutual-recursion][0m nests
  (extending what was done for Version_2.7), perhaps by a factor of
  two in some cases.

  As promised in Version_2.5 (see [note-2-5]), structured pathnames are
  no longer supported.  So for example, the argument to
  [47m[include-book][0m must now be a string constant.

  Some documentation has been improved, for [stobj]s thanks to
  suggestions by John Matthews and much of the rest thanks to
  feedback from Eric Smith.

  The function [47m[current-package][0m is now available to users (it has been
  taken off the list of so-called ``untouchables'').  Thanks to Jared
  Davis for bringing this issue to our attention.

  The documentation for topic [using-computed-hints-7] has been
  improved.  Thanks to Doug Harper and Eric Smith for inspiring this
  improvement.

  We added several symbols to [47m*acl2-exports*[0m: [47m[cw][0m, [47m[er][0m, [47m[intern$][0m,
  [47m[set-case-split-limitations][0m, and [47m[set-difference-eq][0m.  Thanks to
  Jared Davis for suggesting most of these.

  Now, a [47m[table][0m event that sets the value for a key, [47m(table tbl key
  val :put)[0m, is redundant (see [redundant-events]) when it does not
  change the value associated with an existing key of the table.  In
  particular, [47m[define-pc-macro][0m is now fully redundant when it does
  not change an existing [proof-builder] macro-command definition.
  Thanks to Bill Young for bringing the latter issue to our
  attention.

  The definitions of unused system functions [47mev-w[0m and [47mev-w-lst[0m have
  been deleted.

  ACL2 now prints a warning if a [47m[defpkg][0m event introduces a package
  name with lower-case letters, since there is opportunity for later
  confusion in that case.  Thanks to Frederic Peschanski for bringing
  this problem to our attention and Sandip Ray for encouragement.

  ACL2 now works in Version 19 of CMU Common Lisp.

  The function [47m[sys-call][0m has been modified so that for ACL2 built on
  Allegro Common Lisp in Unix or Linux, the existing environment is
  used.  Thanks to Erik Reeber for bringing this issue to our
  attention.

  The function [47m[disabledp][0m can now be given a macro name that has a
  corresponding function; see [macro-aliases-table].  Also,
  [47m[disabledp][0m now has a [guard] of [47mt[0m but causes a hard error on an
  inappropriate argument.")
 (NOTE-2-9-1
  (RELEASE-NOTES)
  "ACL2 Version 2.9.1 (December, 2004) Notes

  (GCL only) A bug in [47m[symbol-package-name][0m has been fixed that could
  be exploited to prove [47mnil[0m, and hence is a soundness bug.  Thanks to
  Dave Greve for sending us an example of a problem with [47m[defcong][0m
  (see below) that led us to this discovery.

  ACL2 now warns when [47m[defcong][0m specifies [47m[equal][0m as the first
  equivalence relation, e.g., [47m(defcong equal iff (member x y) 2)[0m.
  The warning says that the rule has no effect because [47m[equal][0m
  already refines all other equivalence relations.  Formerly, this
  caused an error unless [47m:event-name[0m was supplied (see [defcong]),
  and in fact the error was a nasty raw Lisp error on GCL platforms
  due to some mishandling of packages by ACL2 that has been fixed
  (see the paragraph about [47m[symbol-package-name][0m above).  Thanks to
  Dave Greve for sending a helpful example in his report of this
  problem.

  (GCL only) The build process was broken for GCL 2.6.0 (and perhaps
  some earlier versions), and has been fixed.  Thanks to Jose Luis
  Ruiz-Reina for bringing this problem to our attention.

  (GCL only) We have increased the hole size to at least 20% of
  max-pages, which may eliminate some garbage collection at the
  expense of larger virtual memory (not larger resident memory or
  larger image).  Thanks to Camm Maguire for helpful explanations on
  this topic.

  We have clarified the [guard] warning message that is printed during
  evaluation of recursively-defined functions whose [guard]s have not
  been verified, for example:

    ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking may be inhibited
    on some recursive calls of executable counterparts (i.e., in the ACL2
    logic), including perhaps EVENLP.  To check guards on all recursive
    calls:
      (set-guard-checking :all)
    To leave behavior unchanged except for inhibiting this message:
      (set-guard-checking :nowarn)

  And, ACL2 no longer prints that message when the [guard] was
  unspecified for the function or was specified as [47mT[0m.  Thanks to
  Serita Nelesen for bringing the latter issue to our attention.
  Finally, ACL2 now prints such a warning at most once during the
  evaluation of any top-level form; thanks to Bill Young for pointing
  out this issue.

  The function [47m[verbose-pstack][0m has been enhanced to allow specified
  prover functions [31;1mnot[0m to be traced.  See [verbose-pstack].

  Added [47m[lp][0m, [47mwet[0m, and [47m[set-non-linearp][0m to [47m*acl2-exports*[0m, and hence
  to the [47m\"[0m[47m[ACL2-user][0m[47m\"[0m package.

  The distributed book [47mbooks/arithmetic-3/bind-free/integerp.lisp[0m has
  been modified in order to prevent potential looping; specifically,
  the definition of function [47mreduce-integerp-+-fn-1[0m.  Thanks to
  Robert Krug for providing this change.

  A small improvement was made in the [47mwet[0m failure message when the
  error occurs during translation to internal form.  Thanks to Jared
  Davis for pointing out the obscurity of some [47mwet[0m error messages.

  We have improved ACL2's evaluation mechanism for the function
  [47mbad-atom<=[0m, which now is specified to return [47mnil[0m if neither
  argument is a so-called ``bad atom'' (as recognized by function
  [47mbad-atom[0m).  The following events had caused a hard error, for
  example.  (We're sorry that [47mbad-atom[0m and [47mbad-atom<=[0m are not
  documented, but we also consider it unlikely that anyone needs such
  documentation; otherwise, please contact the implementors.)

    (defun foo (x y) (declare (xargs :guard t)) (bad-atom<= x y))
    (defun bar (x y) (declare (xargs :guard t)) (foo x y))
    (thm (equal (bar 3 4) 7))

  We have also changed the guard on [47m[alphorder][0m to require both
  arguments to be atoms.

  For forms [47m(local x)[0m that are skipped during [47m[include-book][0m, or during
  the second pass of [47m[certify-book][0m or [47m[encapsulate][0m, ACL2 had
  nevertheless checked that [47mx[0m is a legal event form.  This is no
  longer the case.

  The [proof-builder] now does non-linear arithmetic when appropriate.
  It had formerly ignored [47m[set-non-linearp][0m executed in the ACL2
  command loop.

  Incremental releases are now supported.  See [version] and {obsolete
  after Version 4.3} set-tainted-okp.  Thanks to Hanbing Liu for
  discovering a flaw in our original design.

  The pattern-matching algorithm for [47m:[0m[47m[rewrite][0m rules has been made
  slightly more restrictive, thanks to a suggestion and examples from
  Robert Krug.  For example, previously one could get an infinite
  loop as follows.

    (defstub foo (x) t)
    (defaxiom foo-axiom
      (equal (foo (+ 1 x))
             (foo x)))
    (thm (foo 0)) ; or replace 0 by any integer!

  That is because the term [47m(foo 0)[0m was considered to match against the
  pattern [47m(foo (+ 1 x))[0m, with [47mx[0m bound to [47m-1[0m.  While such matching is
  sound, it leads to an infinite loop since it allows [47mfoo-axiom[0m to
  rewrite [47m(foo 0)[0m to [47m(foo -1)[0m, and then [47m(foo -1)[0m to [47m(foo -2)[0m, and so
  on.  The fix is to insist that the new value, in this case [47m-1[0m, is
  no larger in size according to [47m[ACL2-count][0m than the old value, in
  this case [47m0[0m.  Since that test fails, the match is considered to
  fail and the loop no longer occurs.  An analogous fix has been made
  for multiplication, where now we only match when the new term is
  still a non-zero integer.  That change avoids a loop here.

    (defstub foo (x) t)
    (defaxiom foo-axiom
      (equal (foo (* 2 x))
             (foo x)))
    (thm (foo 0)) ; or try (thm (foo 4))

  Added macro [47mfind-lemmas[0m in [47mbooks/misc/find-lemmas.lisp[0m (see brief
  documentation there) for finding all lemmas that mention all
  function symbols in a given list.

  [47m:Restrict[0m [hints] now work for [47m:[0m[47m[definition][0m rules, though they
  continue to be ignored by the preprocessor and hence you may want
  to use [47m:do-not '(preprocess)[0m with any restrict hints.  Thanks to
  John Matthews for pointing out the lack of support for [47m:definition[0m
  rules in [47m:restrict[0m hints.

  Some books have been updated.  In particular, there is a new
  directory [47mbooks/workshops/2004/[0m in workshops distribution, for the
  2004 ACL2 workshop.  There is also a new version of Jared Davis's
  ordered sets library, formerly in
  [47mbooks/finite-set-theory/osets-0.81/[0m but now in
  [47mbooks/finite-set-theory/osets/[0m.

  Fixed a bug in the (under-the-hood) raw Lisp definition of
  [47m[defchoose][0m, which had been causing a warning in CMU Common Lisp.

  [Technical improvements related to the use of ``[47mmake dependencies[0m''
  for certifying distributed books:]
  File [47mbooks/Makefile-generic[0m now does a better job with ``[47mmake
  dependencies[0m,'' specifically with respect to handling [47m*.acl2[0m files
  and handling [47m[include-book][0m commands with [47m:dir :system[0m.  Regarding
  the latter, suppose for example that book [47mbasic.lisp[0m contains the
  line:

    (include-book \"arithmetic/top-with-meta\" :dir :system)

  Then [47mmake dependencies[0m would generate the following line:

    basic.cert: $(ACL2_SRC_BOOKS)/arithmetic/top-with-meta.cert

  Thus, if [47m:dir :system[0m is used with [47m[include-book][0m, the corresponding
  [47mMakefile[0m should define the variable [47mACL2_SRC_BOOKS[0m.  A standard
  [47mMakefile[0m header for a books directory could thus be as follows.

    # The following variable should represent the ACL2 source directory.  It is the
    # only variable in this Makefile that may need to be edited.
    ACL2_SRC = ../../../../../..

    ACL2_SRC_BOOKS = $(ACL2_SRC)/books
    include $(ACL2_SRC_BOOKS)/Makefile-generic
    ACL2 = $(ACL2_SRC)/saved_acl2h

  Finally, the ``[47m-s[0m'' flag may now be omitted when running ``[47mmake
  dependencies[0m.''")
 (NOTE-2-9-2
  (RELEASE-NOTES)
  "ACL2 Version 2.9.2 (April, 2005) Notes

  Also see [note-2-9-1] for other changes since the last
  non-incremental release (Version_2.9).

  There was a bug in non-linear arithmetic (see
  [non-linear-arithmetic]) that caused the following error:

    ACL2 !>(include-book \"rtl/rel4/lib/top\" :dir :system)
    ....
    ACL2 !>(set-non-linearp t)
     T
    ACL2 !>(thm
     (implies (and (bvecp a 77)
                   (bvecp b 50))
              (bvecp (fl (/ (* a b) (expt 2 23)))
                     104))
     :hints ((\"Goal\" :in-theory (enable bvecp))))

    [Note:  A hint was supplied for the goal above.  Thanks!]

    By the simple :definition BVECP, the :executable-counterparts of EXPT
    and UNARY-/ and the simple :rewrite rule ASSOCIATIVITY-OF-* we reduce
    the conjecture to

    Goal'
    (IMPLIES (AND (INTEGERP A)
                  (<= 0 A)
                  (< A 151115727451828646838272)
                  (INTEGERP B)
                  (<= 0 B)
                  (< B 1125899906842624))
             (BVECP (FL (* A B 1/8388608)) 104)).

    HARD ACL2 ERROR in VARIFY:  This should not have happened.  The supposed
    variable, '1/8388608, is instead a constant.

    ACL2 !>

  Thanks to Robert Krug for providing a fix for the above error.

  Guard-checking was being inhibited (since v2-9) for calls of built-in
  primitives on explicit values, e.g., [47m(car 3)[0m.  This has been fixed.

  Guard-related warnings could be printed during proofs (this bug was
  introduced in Version_2.9.1).  These warnings have been eliminated.

  Compound-recognizer rules [47mnatp-compound-recognizer[0m and
  [47mposp-compound-recognizer[0m are now built into ACL2 for predicates
  [47m[natp][0m and [47m[posp][0m, and hence have been deleted from book
  [47mnatp-posp.lisp[0m (where they were called [47mnatp-cr[0m and [47mposp-cr[0m,
  respectively).

  The function [47mfile-clock-p[0m, which recognizes a component of the ACL2
  [47m[state][0m, is now defined using [47m[natp][0m instead of [47m[integerp][0m.  Thanks
  to Jared Davis for suggesting this change.  (Technical explanation
  about functions in ACL2 source file [47maxioms.lisp[0m: With a [47mfile-clock[0m
  of -1, the call of [47mmake-input-channel[0m in [47mopen-input-channel[0m will
  create a channel that can't be closed; see the guard of
  [47mclose-input-channel[0m.)

  (Allegro CL users only) Support is now provided for building an
  Allegro CL application, provided you have an Allegro CL dynamic
  runtime license.  (Our belief is that with such a license, many
  users can use the same application, rather than each user needing a
  separate license.)  See new GNUmakefile target [47mallegro-app[0m and file
  [47mbuild-allegro-exe.cl[0m for more information.

  The new home page now contains a link to a new page
  [47mother-releases.html[0m, which contains information about other ACL2
  releases.  (This is in one's local home page, but may not show up
  on the central ACL2 home page until the next non-incremental
  release.)  Thanks to Warren Hunt for suggesting this addition.

  We thank Erik Reeber for suggesting a solution to output redirection
  using [47m[sys-call][0m, which we have described at the end of its
  documentation.

  A new documentation topic fixes the flawed argument for
  conservativity of the [47m[defchoose][0m event that appears in Appendix B
  of Kaufmann and Moore's paper, ``Structured Theory Development for
  a Mechanized Logic'' (Journal of Automated Reasoning 26, no. 2
  (2001), pp. 161--203).  See [conservativity-of-defchoose].  Thanks
  to John Cowles and Ruben Gamboa for helpful feedback on drafts of
  this note.

  The solution to exercise 6.15 in [47mbooks/textbook/chap6/solutions.txt[0m
  has been fixed.  Thanks to Aaron Smith for pointing out the
  problem.

  A new documentation topic [defun-sk-example] gives a little more help
  in using [47m[defun-sk][0m effectively.  Thanks to Julien Schmaltz for
  presenting this example as a challenge.

  (GCL only) There is now a way to speed up GCL builds of ACL2, at the
  cost of perhaps a percent or so in performance of the resulting
  image.  Using `make' one supplies the following.

    LISP='gcl -eval \"(defparameter user::*fast-acl2-gcl-build* t)\"

  Various makefiles have been improved in several ways.

      (1) Parallel book certification, using GNU make's [47m-j[0m option, can be
      used.

      (2) Book certifications now stops at the first failure if
      [47mbooks/Makefile[0m or [47mbooks/Makefile-generic[0m is used, and returns
      non-zero exit status.  However, the various make targets in the
      ACL2 source directory ([47mregression[0m, [47mcertify-books[0m, etc.) still
      continue past failures unless you provide [47mACL2_IGNORE=' '[0m on
      the `make' command line.

      (3) The build process has been modified (file [47mGNUmakefile[0m) so that it
      stops upon a failed compile or a failed initialization.

      (4) The automatic dependency generation (from ``[47mmake dependencies[0m''
      has been improved so that commands of the form [47m(ld
      \"my-book.lisp\")[0m in [47m.acl2[0m files cause the appropriate
      dependencies to be generated.

  Thanks to comments from several users that led to the above Makefile
  improvements: Ray Richards, Doug Harper, and the Rockwell ACL2
  users for (1) and (2) (and inspiring (4)), and David Rager for (2)
  and (3).  In particular, Doug Harper sent a replacement for the
  [47m.date[0m mechanism, which was interfering with [47mmake -n[0m; so, these
  files are no longer written.

  A mechanism has been added for saving output.  In particular, you can
  now call [47m[ld][0m on a file with output turned off, for efficiency, and
  yet when a proof fails you can then display the proof attempt for
  the failed (last) event.  See set-saved-output.  Another new
  command --- see [set-print-clause-ids] --- causes subgoal numbers
  to be printed during proof attempts when output is inhibited.

  Documentation has been added for using ACL2's makefile support to
  automate the certification of collections of books.  See
  [books-certification-classic].

  Fixed a bug in [47m[sys-call-status][0m that was causing hard Lisp errors.

  Improved [47m[cw-gstack][0m to allow a [47m:frames[0m argument to specify a range
  of one or more frames to be printed.  see [cw-gstack].

  Fixed a bug in [proof-builder] command [47mforwardchain[0m.  Thanks to
  Ming-Hsiu Wang for bringing this bug to our attention.

  We have provided a mechanism for saving an executable image.  See
  [saving-and-restoring] and see [save-exec].  We have eliminated
  obsolete functions [47mnote-lib[0m and [47mmake-lib[0m.

  Modified the [47m[ground-zero][0m [theory] so that it contains all of the
  built-in rules (in ACL2 source file [47maxioms.lisp[0m).  It had formerly
  failed to include rules from some definitions and theorems near the
  end of [47maxioms.lisp[0m.

  A new event, [47m[set-enforce-redundancy][0m, allows the enforcement of
  [47m[defthm][0m, [47m[defun][0m, and most other events during book development.
  See [set-enforce-redundancy].

  A bug has been fixed that had allowed [47m[deftheory][0m [events] to cause a
  hard Lisp error when calling [47m[union-theories][0m on ill-formed
  theories after, for example:

    :set-guard-checking nil
    (in-theory (union-theories '((:rewrite no-such-rule))
                               (current-theory 'ground-zero)))

  The handling of [guard] checking has been modified somewhat in a way
  that should only very rarely affect users.  (An ``Essay on Guard
  Checking'' in the ACL2 source code explains this point to anyone
  interested in implementation details.)

  (GCL ONLY) Removed the -dir setting in the ACL2 wrapper script for
  GCL.  This should generally have no effect for most users, but it
  eliminates a potential source of error down the road.

  Several interesting new definitions and lemmas have been added to the
  rtl library developed at AMD, and incorporated into
  [47mbooks/rtl/rel4/lib/[0m.  Other book changes include a change to lemma
  [47mtruncate-rem-elim[0m in [47mbooks/ihs/quotient-remainder-lemmas.lisp[0m, as
  suggested by Jared Davis.

  The macro [47m[real/rationalp][0m may now be referred to in [47m[in-theory][0m
  [events] and [hints], thanks to a new [47m[add-macro-alias][0m event.
  Thanks to Jared Davis for this suggestion.

  ACL2 terms of the form [47m(if p 'nil 't)[0m are now printed as [47m(not p)[0m,
  where in some setting they had been printed as [47m(and (not p) t)[0m.
  Thanks to Robert Krug for this improvement.

  (GCL ONLY) Added profiling support, based heavily on code supplied by
  Camm Maguire.  See file [47msave-gprof.lsp[0m for instructions.  Thanks to
  Camm, and also to David Hardin for inspiring this addition.

  Added support for preprocessing before printing (untranslating) a
  term.  See [user-defined-functions-table], in particular the
  discussion of [47muntranslate-preprocess[0m.  Thanks to Jared Davis for
  inspiring this addition, and for providing a book that takes
  advantage of it ([47mbooks/misc/untranslate-patterns.lisp[0m).

  The documentation has been improved for explaining how [rune]s are
  assigned; see [rune].  Thanks to Robert Krug for pointing out
  inaccuracies in the existing documentation.")
 (NOTE-2-9-3
  (RELEASE-NOTES)
  "ACL2 Version 2.9.3 (August, 2005) Notes

  Also see [note-2-9-1] and see [note-2-9-2] for other changes since
  the last non-incremental release (Version_2.9).

  We fixed a soundness bug that exploited the ability to define
  [47m:[0m[47m[program][0m mode functions that are improperly guarded, and then to
  use those functions in [47m[defconst][0m forms.  The fix is to evaluate
  [47m[defconst][0m forms using the same ``safe-mode'' that is used in
  macroexpansion (see [guards-and-evaluation]).  Here is a proof of
  [47mnil[0m that succeeded in Allegro Common Lisp (but not, for example,
  GCL).  See also a long comment in source function [47mdefconst-fn[0m for
  an example that does not require the use of [47m:set-guard-checking[0m.

    :set-guard-checking nil ; execute before certifying the book below

    (in-package \"ACL2\")

    (encapsulate
     ()
     (local (defun f1 ()
              (declare (xargs :mode :program))
              (char-upcase (code-char 224))))
     (local (defconst *b* (f1)))
     (defun f1 ()
       (char-upcase (code-char 224)))
     (defconst *b* (f1))
     (defthm bad
       (not (equal *b* (code-char 224)))
       :rule-classes nil))

    (defthm ouch
      nil
      :hints ((\"Goal\" :use bad))
      :rule-classes nil)

  We fixed a soundness hole due to the fact that the \"LISP\" package
  does not exist in OpenMCL.  We now explicitly disallow this package
  name as an argument to [47m[defpkg][0m.  Thanks to Bob Boyer and Warren
  Hunt for bringing an issue to our attention that led to this fix.

  ACL2 now requires all package names to consist of standard characters
  (see [standard-char-p], none of which is lower case.  The reason is
  that we have seen at least one lisp implementation that does not
  handle lower case package names correctly.  Consider for example
  the following raw lisp log (some newlines omitted).

    >(make-package \"foo\")
    #<\"foo\" package>
    >(package-name (symbol-package 'FOO::A))
    \"foo\"
    >(package-name (symbol-package '|FOO|::A))
    \"foo\"
    >

  Distributed book [47mbooks/textbook/chap10/compiler[0m, as well as workshop
  books in directory [47mbooks/workshops/2004/cowles-gamboa/support/[0m,
  were modified to accommodate the above change.

  Added [47mnewline[0m, [47m[add-to-set-eql][0m, [47mthe-fixnum[0m, and [47mthe-fixnum![0m to
  [47m*acl2-exports*[0m.  Thanks to Jared Davis for bringing these to our
  attention.

  Added a line to [47macl2.lisp[0m to support CMUCL running on Mac OSX, thanks
  to a suggestion from Fabricio Chalub Barbosa do Rosario.

  The executable scripts for saved ACL2 images now include [47m$*[0m, so that
  command-line arguments will be passed along.

  (For GCL profiling only) Fixed a colon ([47m:[0m) that should have been a
  semicolon ([47m;[0m) in file [47msave-gprof.lsp[0m.  Thanks to David Hardin for
  pointing out this bug.

  The documentation for [47m:[0m[47m[elim][0m rules has been expanded and improved,
  thanks to useful feedback from Hanbing Liu.

  Fixed a bug in the guard for function [47minclude-book-dir[0m.

  For those who want to experiment with an alternate implementation of
  [47m[mv][0m and [47m[mv-let][0m, there is now support for under-the-hood
  implementation of these in terms of raw Lisp functions [47mvalues[0m and
  [47mmultiple-value-bind[0m, respectively.  The regression suite has seen
  about a 10% speed-up in Allegro CL and about an 8% slowdown in GCL
  for builds with this change.  See the makefile ([47mGNUmakefile[0m) for
  examples of how to build ACL2 by including the feature,
  [47m:acl2-mv-as-values[0m.  Source file [47minit.lsp[0m has been renamed to
  [47minit.lisp[0m in support of this change (technical detail: otherwise
  GCL loads the init file too soon, before its [47m-eval[0m argument is
  evaluated).  Thanks to David Rager for inspiring this change, by
  pointing out the problematic use of globals by the existing [47m[mv][0m
  implementation from the standpoint of supporting parallel
  evaluation.  This capability is experimental: there is likely to be
  some remaining work to be done on it.

  A change related to the one just above is that we now limit the
  maximum number of arguments to any call of [47m[mv][0m to 32.  Thanks to
  Bob Boyer for raising a question that lead to this change.

  Eliminated some compiler warnings in OpenMCL.

  In the rtl library ([47mbooks/rtl/rel4/[0m), functions [47mbits[0m and [47msetbits[0m have
  had their [guard]s improved (as they had been too restrictive,
  especially for [47msetbits[0m).

  A new function [47m[time$][0m permits timing of forms, by using (under the
  hood) the host Common Lisp's [47mtime[0m utility.

  We fixed an infinite loop that could occur during destructor
  elimination (see [elim]).  Thanks to Sol Swords to bringing this to
  our attention and sending a nice example, and to Doug Harper for
  sending a second example that we also found useful.

  The method of speeding up GCL-based builds (see [note-2-9-2]) has
  changed slightly from Version_2.9.2.  Now, in the `make' command:

    LISP='gcl -eval \"(defparameter user::*fast-acl2-gcl-build* t)\"

  We improved the pretty-printer's handling of keywords.  For example,
  before this change one might see the following printed by ACL2.

    (MODIFY TH S :KEY1 VAL1 :KEY2
            (IF (IF X Y Z) AAAAAAAAAA BBBBBBB))

  Now, the above might print as follows.  Notice that we have avoided
  breaking after a keyword (see [keywordp]) that is preceded by other
  forms on the same line.

    (MODIFY TH S
            :KEY1 VAL1
            :KEY2 (IF (IF X Y Z) AAAAAAAAAA BBBBBBB))

  See [note-2-9-3-ppr-change] for a detailed discussion of this change.

  (GCL ONLY) Evaluation in a break is no longer inhibited by ACL2 when
  built on top of GCL, so GCL now matches other Common Lisps in this
  respect.

  For ACL2 built on most host Common Lisps, you will see the string
  [47m[RAW LISP][0m in the prompt, at least at a break, to emphasize that
  one is inside a break and hence should probably quit from the
  break.  See [breaks].

  Jared Davis suggested improvements to lemmas [47mlen-update-nth[0m (in
  source file [47maxioms.lisp[0m) and [47mappend-true-listp-type-prescription[0m
  (in [47mbooks/meta/term-defuns.lisp[0m), which have been incorporated.
  The former required a change in [47mbooks/workshops[0m book
  [47m2004/ruiz-et-al/support/q-dag-unification.cert[0m, which has been
  made.

  The [proof-builder] command [47mrewrite[0m allows further binding of free
  variables in hypotheses, with new optional argument
  [47minstantiate-free[0m.  proof-builder command [47mshow-rewrites[0m ([47msr[0m) gives
  corresponding additional information.  Documentation for these
  commands has been improved; see [proof-builder-commands].  Thanks
  to John Matthews and Bill Young for suggestions and feedback
  leading to these improvements.

  Fixed downcase printing so that the package name of a symbol is also
  downcased.  For example, after execution of [47m(defpkg \"FOO\" nil)[0m and
  [47m(set-acl2-print-case :downcase)[0m, [47m'foo::ab[0m will print back as the
  same, rather than as [47m'FOO::ab[0m.

  It is now possible to control the output so that numbers are printed
  in binary, octal, or hex, though the default is still radix 10.
  See [set-print-base].  Note that in support of this change,
  built-in functions [47m[explode-nonnegative-integer][0m and [47mexplode-atom[0m
  now take an extra [47mprint-base[0m argument.  Different support for radix
  conversion may be found in a book newly contributed by Jun Sawada,
  [47mbooks/misc/radix.lisp[0m.

  Built-in axiom [47mcar-cdr-elim[0m is now only an [47m:[0m[47m[elim][0m rule.  It was
  formerly both an [47m:elim[0m rule and a [47m:[0m[47m[rewrite][0m rule.  A new rule,
  [47mcons-car-cdr[0m, takes the place of the old [47m:rewrite[0m rule, but is
  instead a hypothesis-free rule that can cause a case split (see
  source file [47maxioms.lisp[0m).  Thanks to Jared Davis for suggesting
  this change.

  Lemmas about [47m[alphorder][0m ([47malphorder-reflexive[0m, [47malphorder-transitive[0m,
  [47malphorder-anti-symmetric[0m, and [47malphorder-total[0m) are now available.
  (They had been [47m[local][0m in source file [47maxioms.lisp[0m.)  Thanks to
  Serita Nelesen for bringing this issue to our attention.

  ACL2 has, for some time, printed a space in the event summary after
  the open parenthesis for a [47m[defthm][0m event, in order to ease
  backward searching for the original form, for example [47m(defthm bar
  ...)[0m:

    Form:  ( DEFTHM BAR ...)

  The intention was that this extra space should be printed for every
  event form; but it was missing in some cases, for example, for
  [47m[verify-guards][0m.  This has been fixed.

  In analogy to [47m[include-book][0m, now [47m[ld][0m takes the (optional) keyword
  argument [47m:dir[0m.  Thanks to Jared Davis for providing an
  implementation of this feature and to Eric Smith and Jeff Marshall
  for requesting this feature.

  We fixed a bug in [47m[include-book][0m that could cause an error when
  redefinition is on, for example:

    (set-ld-redefinition-action '(:warn! . :overwrite) state)
    (include-book \"/u/acl2/books/arithmetic/top\")

  The behavior of [47m[include-book][0m now matches the documentation:
  handling of compiled files for uncertified [books] will follow the
  same rules as for certified books.  In particular, if you create an
  object file in raw Lisp for some book, then including that book
  will load that object file.  Thanks to Jared Davis for bringing
  this issue to our attention.

  New documentation explains the interaction of redefinition and
  redundancy.  See [redundant-events] --- the ``Note About
  Unfortunate Redundancies'' is new.  Thanks to Grant Passmore for
  providing examples that led us to write this additional
  documentation.

  Solutions to exercises in { How To Prove Theorems Formally |
  http://www.cs.utexas.edu/users/moore/publications/how-to-prove-thms}
  are now available in distributed book
  [47mbooks/misc/how-to-prove-thms.lisp[0m.  Also in that directory may be
  found a new book [47mhanoi.lisp[0m that contains a solution to the Towers
  of Hanoi problem.


Subtopics

  [Note-2-9-3-ppr-change]
      Change in pretty-printing for ACL2 Version_2.9.3")
 (NOTE-2-9-3-PPR-CHANGE
  (NOTE-2-9-3)
  "Change in pretty-printing for ACL2 Version_2.9.3

  We have improved pretty-printing in ACL2 Version_2.9.3 to handle
  keywords a little differently.  To see a discussion of the basics
  of this change, see [note-2-9-3].  In this note we describe it in
  considerable detail.

  Those who wish to understand the ACL2 pretty-printer's implementation
  can now find considerably more comments on it in the source code.
  In this note, we do not focus on the implementation.  Rather, we
  motivate the change and show how the improved prettyprinter
  performs.

  Why do we want better keyword handling?  Imagine a macro that builds
  a new state from an old state by changing the values in the
  affected fields, leaving everything else unchanged.  One could
  write

    (modify th s :key1 val1 :key2 val2 :key3 val3)

  where the three keys identify fields in the state.

  To make it easier to read new concrete states, we may have a function
  that prints them ``relative'' to a given base state, expressing the
  new state as a modification of the given base state.  So we may
  find ourselves prettyprinting modify forms like that above.

  The previous prettyprinter will sometimes print the form above as
  follows.

    (modify th s :key1
            val1
            :key2 val2 :key3 val3)

  This can be unpleasant to read, because of the way [47m:key1[0m and [47mval1[0m are
  separated.  Here is an example of the old prettyprinter and the new
  one, both printing an expression from the ACL2 source code in a
  width of 40:

    Old:
    (ADD-TO-TAG-TREE
     'ASSUMPTION
     (MAKE
      ASSUMPTION :TYPE-ALIST TYPE-ALIST
      :TERM TERM :REWRITTENP REWRITTENP
      :IMMEDIATEP IMMEDIATEP :ASSUMNOTES
      (LIST
       (MAKE
            ASSUMNOTE :CL-ID
            NIL :RUNE RUNE :TARGET TARGET)))
     TTREE)

    New:
    (ADD-TO-TAG-TREE
         'ASSUMPTION
         (MAKE ASSUMPTION
               :TYPE-ALIST TYPE-ALIST
               :TERM TERM
               :REWRITTENP REWRITTENP
               :IMMEDIATEP IMMEDIATEP
               :ASSUMNOTES
               (LIST (MAKE ASSUMNOTE
                           :CL-ID NIL
                           :RUNE RUNE
                           :TARGET TARGET)))
         TTREE)

  Basically the change we made forces the prettyprinter to print each
  [47m:key[0m on a new line unless they all fit on a single line.  So we
  would now get either

    (modify th s :key1 val1 :key2 :val2 :key3 val3)

  or

    (modify th s
            :key1 val1
            :key2 val2
            :key3 val3)

  Furthermore, we fixed it so that if [47mval1[0m (say) is a big s-expression
  we may still print it on the same line as its key.  The old
  prettyprinter enforced the rule that if you wanted to print [47m(foo a
  b)[0m and [47mb[0m gets broken up into several lines, then it has to start on
  a new line.  Thus, we'd never print

    (foo a (bbb
            (mum x)))

  but would print instead

    (foo a
         (bbb
          (mum x)))

  Now, if a is a keyword, we can print the first way.

  So here are some nice examples of prettyprinted keyword forms.  All
  of these are printed for a page of width 40.

    <--            40 chars               ->
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    (MODIFY TH S :KEY1 V1 :KEY2 V2)

    (MODIFY TH S :KEY1 V1 :KEY2 V2 :KEY3 V3)

    (MODIFY TH S1                               ; Because of the extra char
            :KEY1 V1                            ; in S1 the flat size exceeds
            :KEY2 V2                            ; 40 and we break it.
            :KEY3 V3)

  The old ppr would have printed this as:

    (MODIFY
         TH S1 :KEY1 V1 :KEY2 V2 :KEY3 V3)

  Returning to new examples:

    <--            40 chars               ->
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    (MODIFY TH S
            :KEY1 (IF (IF X Y Z) AAAA BBBB)
            :KEY2 VAL2
            :KEY3 VAL3)

  Now we extend [47mAAAA[0m and [47mBBBB[0m by one char each, so it would overflow
  the right margin if printed as above, and we get:

    <--            40 chars               ->
    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    (MODIFY
         TH S
         :KEY1 (IF (IF X Y Z) AAAAX BBBBX)
         :KEY2 VAL2
         :KEY3 VAL3)

  If we make these names even longer we force the value off the line
  containing [47m:key1[0m:

    (MODIFY
         TH S
         :KEY1
         (IF (IF X Y Z) AAAAXXXXX BBBBXXXXX)
         :KEY2 VAL2
         :KEY3 VAL3)

  Here are some examples from the ACL2 source code, printed in 40
  characters:

    (DEFTHM
     ALPHORDER-ANTI-SYMMETRIC
     (IMPLIES (AND (NOT (CONSP X))
                   (NOT (CONSP Y))
                   (ALPHORDER X Y)
                   (ALPHORDER Y X))
              (EQUAL X Y))
     :HINTS
     ((\"Goal\"
       :IN-THEORY
       (UNION-THEORIES
        '(STRING< SYMBOL<)
        (DISABLE
           CODE-CHAR-CHAR-CODE-IS-IDENTITY))
       :USE
       ((:INSTANCE SYMBOL-EQUALITY (S1 X)
                   (S2 Y))
        (:INSTANCE BAD-ATOM<=-ANTISYMMETRIC)
        (:INSTANCE
             CODE-CHAR-CHAR-CODE-IS-IDENTITY
             (C Y))
        (:INSTANCE
             CODE-CHAR-CHAR-CODE-IS-IDENTITY
             (C X)))))
     :RULE-CLASSES
     ((:FORWARD-CHAINING
       :COROLLARY
       (IMPLIES
          (AND (ALPHORDER X Y)
               (NOT (CONSP X))
               (NOT (CONSP Y)))
          (IFF (ALPHORDER Y X) (EQUAL X Y)))
       :HINTS
       ((\"Goal\"
         :IN-THEORY (DISABLE ALPHORDER))))))

  Here is that same one, printed in a width of 60.

    (DEFTHM
     ALPHORDER-ANTI-SYMMETRIC
     (IMPLIES (AND (NOT (CONSP X))
                   (NOT (CONSP Y))
                   (ALPHORDER X Y)
                   (ALPHORDER Y X))
              (EQUAL X Y))
     :HINTS
     ((\"Goal\"
         :IN-THEORY
         (UNION-THEORIES
              '(STRING< SYMBOL<)
              (DISABLE CODE-CHAR-CHAR-CODE-IS-IDENTITY))
         :USE ((:INSTANCE SYMBOL-EQUALITY (S1 X)
                          (S2 Y))
               (:INSTANCE BAD-ATOM<=-ANTISYMMETRIC)
               (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C Y))
               (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY
                          (C X)))))
     :RULE-CLASSES
     ((:FORWARD-CHAINING
          :COROLLARY (IMPLIES (AND (ALPHORDER X Y)
                                   (NOT (CONSP X))
                                   (NOT (CONSP Y)))
                              (IFF (ALPHORDER Y X) (EQUAL X Y)))
          :HINTS ((\"Goal\" :IN-THEORY (DISABLE ALPHORDER))))))

  Just for comparison, here is the above printed in 60 columns by the
  old prettyprinter.

    (DEFTHM
     ALPHORDER-ANTI-SYMMETRIC
     (IMPLIES (AND (NOT (CONSP X))
                   (NOT (CONSP Y))
                   (ALPHORDER X Y)
                   (ALPHORDER Y X))
              (EQUAL X Y))
     :HINTS
     ((\"Goal\" :IN-THEORY
              (UNION-THEORIES
                   '(STRING< SYMBOL<)
                   (DISABLE CODE-CHAR-CHAR-CODE-IS-IDENTITY))
              :USE
              ((:INSTANCE SYMBOL-EQUALITY (S1 X)
                          (S2 Y))
               (:INSTANCE BAD-ATOM<=-ANTISYMMETRIC)
               (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY (C Y))
               (:INSTANCE CODE-CHAR-CHAR-CODE-IS-IDENTITY
                          (C X)))))
     :RULE-CLASSES
     ((:FORWARD-CHAINING
           :COROLLARY
           (IMPLIES (AND (ALPHORDER X Y)
                         (NOT (CONSP X))
                         (NOT (CONSP Y)))
                    (IFF (ALPHORDER Y X) (EQUAL X Y)))
           :HINTS
           ((\"Goal\" :IN-THEORY (DISABLE ALPHORDER))))))

  Of course, given that you cannot tell for sure whether the keywords
  you're seeing are part of a keyword/value parameter list or part of
  some constant containing random keywords, the prettyprinter can't
  solve the problem perfectly.  We just tried to make it work nicely
  on well-formed keyword/value parameter lists.

  For example, here is a form printed by each prettyprinter.

    Old:
    (MEMBER
     X
     '(:MONDAY
          :MON :TUESDAY :TUES :WEDNESDAY
          :WED :THURSDAY :THURS :FRIDAY
          :FRI :SATURDAY :SAT :SUNDAY :SUN))

    New:
    (MEMBER X
            '(:MONDAY :MON
                      :TUESDAY :TUES
                      :WEDNESDAY :WED
                      :THURSDAY :THURS
                      :FRIDAY :FRI
                      :SATURDAY :SAT
                      :SUNDAY :SUN))

  The new way is not how one would print it by hand!  But then, neither
  is the old way.")
 (NOTE-2-9-4
  (RELEASE-NOTES)
  "ACL2 Version 2.9.4 (February, 2006) Notes

  Also see [note-2-9-1], see [note-2-9-2], and see [note-2-9-3] for
  other changes since the last non-incremental release (Version_2.9).

  A soundness bug has been fixed that was due to inadequate checking of
  [47m:[0m[47m[meta][0m rules in the presence of [47m[local][0m [events].  Specifically, a
  [47mlocal[0m [47m[defevaluator][0m event is insufficient for supporting a [47m:meta[0m
  rule (an example is shown in source function [47mchk-acceptable-rules[0m).
  Thanks to Dave Greve and Jared Davis for bringing this bug to our
  attention, by sending a proof of [47mnil[0m that exploited this bug.  The
  fix is to check legality of [47m:meta[0m rules even when skipping proofs
  during an [47m[include-book][0m event or the second pass of an
  [47m[encapsulate][0m event.

  Fixed problem with parallel make for workshop books by adding a
  dependency line to [47mbooks/workshops/2003/Makefile[0m.

  Default hints (see [set-default-hints]) no longer prevent the use of
  [47m:INSTRUCTIONS[0m (see [proof-builder]).  Thanks to Jared Davis for
  pointing out this problem.

  New functions [47m[remove-eq][0m and [47m[remove-equal][0m have been defined, in
  analogy to [47m[remove][0m.  These two symbols have also been added to
  [47m*acl2-exports*[0m.  Thanks to David Rager for pointing out that
  [47mremove-equal[0m was missing.  Moreover, the definitions of [47mdelete1-eq[0m
  and [47mdelete1-equal[0m have been eliminated.  Function [47mremove1-eq[0m, now
  in [47m:[0m[47m[logic][0m mode in source file [47maxioms.lisp[0m, serves in place of
  [47mdelete1-eq[0m, with corresponding new function definitions for
  [47m[remove1][0m and [47m[remove1-equal][0m.

  The symbol [47m[assert$][0m has been added to [47m*acl2-exports*[0m.  Thanks to
  Jared Davis for the suggestion.

  Added SBCL support.  Thanks to Juho Snellman for significant
  assistance with the port.  Thanks to Bob Boyer for suggesting the
  use of feature [47m:acl2-mv-as-values[0m with SBCL, which can allow
  thread-level parallelism in the underlying lisp; we have done so
  when feature [47m:sb-thread[0m is present.

  We have continued to incorporate suggestions for wording improvements
  in documentation and error messages.  Thanks to all who send these
  suggestions, especially to Eric Smith, who has suggested the vast
  majority of them.

  Made a small improvement to errors and warnings caused on behalf of
  [set-enforce-redundancy], to indicate when an event of the same
  name already exists.

  Fixed a bug in [47mbooks/misc/rtl-untranslate.lisp[0m that was causing a
  guard violation when adding a new entry for an existing key.

  Fixed a bug in translation to internal form that caused [47m[defun-sk][0m
  and [47m[defchoose][0m to have difficulties handling ignored variables in
  [47m[let][0m forms.  Thanks to Sandip Ray for bringing this issue to our
  attention with a helpful example.

  The form [47m(push :acl2-mv-as-values *features*)[0m has been added in
  source file [47macl2-init.lisp[0m for SBCL and OpenMCL only, in order to
  support parallel execution (looking to the future...).

  Default-hints (see [set-default-hints]) were being ignored inside the
  [proof-builder], but no longer.  Thanks to John Erickson for
  bringing this problem to our attention and providing a simple
  example of it.

  Modified the [47mTAGS[0m [47m\"make\"[0m target (specifically, function [47mmake-tags[0m) so
  that it is gracefully skipped if the [47metags[0m program is not found.
  Thanks to David Rager for pointing out this issue.

  Sandip Ray has re-worked the supporting materials for his ACL2
  Workshop 2003 talk (originally with John Matthews and Mark Tuttle),
  to run in a few minutes.  The result is in
  [47mworkshops/2003/ray-matthews-tuttle/support/[0m and is included in the
  full ACL2 regression suite.  Thanks, Sandip.

  Debian releases of ACL2 had created superfluous [47m.cert.final[0m files
  when certifying books.  This has been fixed; thanks to Jared Davis
  for noticing this problem.

  Jared Davis has pointed out that ``If you add a [47m:backchain-limit-lst
  0[0m to a rewrite rule whose hypotheses are all forced, then ACL2
  `really assumes them' without trying to relieve them right there
  through rewriting.'' Relevant documentation has been added for
  [47m:backchain-limit-lst[0m; see [rule-classes].

  A new version of the rtl library has been included in
  [47mbooks/rtl/rel5/[0m.  Thanks to David Russinoff for contributing hand
  proofs for the new lemmas, and to Matt Kaufmann for carrying out
  their mechanization.

  Fixed a bug in [47m[save-exec][0m that was failing to set the initial [47mcbd[0m
  according to the current directory when starting up ACL2.  Thanks
  to Camm Maguire for bringing our attention to this problem.

  Variables introduced during [47mlet*[0m abstraction are now in the current
  package.  Thanks to Jared Davis for suggesting such a change.  See
  [set-let*-abstractionp].

  It is now allowed for two definitions to be considered the same from
  the standpoint of redundancy (see [redundant-events]) when one
  specifies a [47m:[0m[47m[guard][0m of [47mt[0m and the other has no explicit [47m:guard[0m
  (hence, the guard is implicitly [47mt[0m).  Thanks to Jared Davis for
  bringing this issue to our attention.

  (For users of [47memacs/emacs-acl2.el[0m) There have been a few enhancements
  to distributed file [47memacs/emacs-acl2.el[0m (skip this paragraph if you
  don't use that file):

      o [47mControl-t q[0m continues to compare windows ignoring whitespace, but
      now, a prefix argument can be given to control case is also
      ignored (ignore case if positive, else use case).

      o [47mControl-t Control-l[0m has been defined to be similar to [47mControl-t l[0m,
      except that proofs are skipped and output is suppressed.

      o [47mControl-t u[0m has been defined to print, to the shell buffer, a
      [47m:[0m[47m[ubt!][0m form for the command containing the cursor.

      o Control-t Control-f buries the current buffer.

      o [47mMeta-x new-shell[0m now puts the new shell buffer in [47mshell-mode[0m
      (thanks to David Rager for noticing this issue).

  Linear arithmetic has been modified so that we do not generate the
  equality [47m(equal term1 term2)[0m from the pair of inequalities [47m(<=
  term1 term2)[0m and [47m(<= term2 term1)[0m in the case that we would have to
  [47m[force][0m both [47mterm1[0m and [47mterm2[0m to be [47m[ACL2-numberp][0ms.  Thanks to Dave
  Greve for providing a motivating example and to Robert Krug for
  providing a fix.

  The event [47m[delete-include-book-dir][0m had not been allowed inside
  [books] and [47m[encapsulate][0m forms.  This was an oversight, and has
  been fixed.

  Sandip Ray has contributed a new library of books to support proofs
  of partial and total correctness of sequential programs based on
  assertional reasoning, in [47mbooks/symbolic/[0m.  This work is based on
  the paper J. Matthews, J S. Moore, S. Ray, and D. Vroon, ``A
  Symbolic Simulation Approach to Assertional Program Verification,''
  currently in draft form.  In particular, the books include the
  macro [47mdefsimulate[0m, which automatically transforms inductive
  assertion proofs of correctness of sequential programs to the
  corresponding interpreter proofs.  See the [47mREADME[0m in that
  directory.

  We have changed the implementation of [47m:dir :system[0m for [47m[ld][0m and
  [47m[include-book][0m.  This change will not affect you if you build an
  ACL2 executable in the normal manner, leaving in place the [47mbooks/[0m
  subdirectory of the source directory; nor will it affect you if you
  download a GCL Debian binary distribution.  The change is that if
  environment variable [47mACL2_SYSTEM_BOOKS[0m is set, then it specifies
  the distributed books directory, i.e., the directory determined by
  [47m:dir :system[0m.  You may find it convenient to set this variable in
  your ACL2 script file (typically, [47msaved_acl2[0m).  If it is set when
  you build ACL2, the generated script for running ACL2 will begin by
  setting [47mACL2_SYSTEM_BOOKS[0m to that value.  Thanks to various people
  who have discussed this issue, in particular Jared Davis who sent
  an email suggesting consideration of the use of an environment
  variable, and to Eric Smith who helped construct this paragraph.
  (Note that this use of [47mACL2_SYSTEM_BOOKS[0m replaces the use of
  [47mACL2_SRC_BOOKS[0m described previously; see [note-2-9-1].)

  ACL2 now automatically deletes files [47mTMP*.lisp[0m created during the
  build process and created by [47m:[0m[47m[comp][0m.  If you want these to be
  saved, evaluate [47m(assign keep-tmp-files t)[0m in the ACL2 loop or in
  raw Lisp.  The [47mclean[0m target for the standard `make' process for
  certifying books (see [books-certification-classic]) will however
  delete all files [47mTMP*.*[0m.

  The [47mTMP[0m files discussed just above now generally include the current
  process ID in their names, e.g., [47mTMP@16388@1.lisp[0m instead of
  [47mTMP1.lisp[0m.  Thanks to Bob Boyer for suggesting this measure, which
  will reduce the possibility that two different processes will
  attempt to access the same temporary file.

  Now, [47m:[0m[47m[pe][0m will print the information formerly printed by [47m:pe![0m,
  slightly enhanced to work for logical names that are strings, not
  just symbols.  Thanks to Warren Hunt for leading us to this change
  by suggesting that [47m:pe nth[0m print the definition of [47m[nth][0m.

  We eliminated spurious warnings that could occur in raw mode in
  OpenMCL or CMUCL when [stobj]s are present.  We thank Juho Snellman
  for pointing out the relevant bug and appropriate fix.

  [47mMfc-rw[0m now takes a third argument that can specify an arbitrary known
  equivalence relation; see [extended-metafunctions].  Thanks to Dave
  Greve for discussions suggesting this improvement.

  A small modification to a symbol-reading function allows
  documentation string processing on Windows systems that use CR/LF
  for line breaks.  Thanks to William Cook for bringing this issue to
  our attention.

  The documentation has been improved on how to control the printing of
  ACL2 terms.  See [user-defined-functions-table].  Thanks to Sandip
  Ray for asking a question that led to the example presented there.

  We fixed an inefficiency that could cause an [47m[ld][0m command to seem to
  hang at its conclusion.  Thanks to Sandip Ray for pointing out this
  problem.

  We checked that ACL2 runs under LispWorks 4.4.5, and have inhibited
  redefinition warnings.

  Two changes have been made on behalf of congruence-based reasoning.
  Thanks to Dave Greve for examples and discussions that have led to
  these changes, and to Eric Smith and Vernon Austel, who also sent
  relevant examples.

      o When a call of the new unary function [47m[double-rewrite][0m is
      encountered by the rewriter, its argument will be rewritten
      twice.  This solves certain problems encountered in
      congruence-based rewriting.  Warnings for [47m:[0m[47m[rewrite][0m and
      [47m:[0m[47m[linear][0m rules will suggest when calls of [47m[double-rewrite][0m on
      variables in hypotheses are likely to be a good idea.  See
      [double-rewrite].

      o Hypotheses of the form [47m(equiv var (double-rewrite term))[0m, where
      [47mequiv[0m is a known [equivalence] relation and [47mvar[0m is a free
      variable (see [free-variables]), will bind [47mvar[0m to the result of
      rewriting [47mterm[0m twice.  Previously, hypotheses of the form
      [47m(equal var term)[0m would bind a free variable [47mvar[0m, but the call
      had to be of [47mequal[0m rather than of an arbitrary known
      equivalence relation.

  The following improvements were made in support of ACL2 on top of
  OpenMCL.

      o New versions of OpenMCL that do not have [47m:mcl[0m in Lisp variable
      [47m*features*[0m will now work with ACL2.  Thanks to David Rager for
      bringing this issue to our attention.

      o Added support for OpenMCL 1.0 for 64-bit DarwinPPC/MacOS X, thanks
      to Robert Krug.

      o Fixed tracing in OpenMCL so that the level is reset to 1 even if
      there has been an abort.

      o Added support in OpenMCL for [47mWET[0m.

      o Incorporated suggestions from Gary Byers for printing the ``Welcome
      to OpenMCL'' prompt before initially entering the ACL2 loop
      and, and for setting useful environment variable
      [47mCCL_DEFAULT_DIRECTORY[0m in the ACL2 script.

  Fixed a long-standing bug in forward-chaining, where variable-free
  hypotheses were being evaluated even if the
  [executable-counterpart]s of their function symbols had been
  disabled.  Thanks to Eric Smith for bringing this bug to our
  attention by sending a simple example that exhibited the problem.

  Improved reporting by the [break-rewrite] utility upon failure to
  relieve hypotheses in the presence of free variables, so that
  information is shown about the attempting bindings.  See
  [free-variables-examples-rewrite].  Thanks to Eric Smith for
  requesting this improvement.  Also improved the [break-rewrite]
  loop so that terms, in particular from unifying substitutions, are
  printed without hiding subterms by default.  The user can control
  such hiding (``evisceration''); see :DOC [47mset-brr-term-evisc-tuple[0m.

  A new directory [47mbooks/defexec/[0m contains books that illustrate the use
  of [47m[mbe][0m and [47m[defexec][0m.  Thanks to the contributors of those books
  (see the [47mREADME[0m file in that directory).

  The directories [47mbooks/rtl/rel2[0m and [47mbooks/rtl/rel3[0m are no longer
  distributed.  They are still available by email request.
  (Subdirectory [47mrel1/[0m supports some of the optional [47mworkshop/[0m books,
  so it is still distributed.)

  Added book [47mbooks/misc/sticky-disable.lisp[0m to manage [theories] that
  might otherwise be modified adversely by [47m[include-book][0m.  Thanks to
  Ray Richards for a query that led to our development of this tool.

  The commands [47m(exit)[0m and [47m(quit)[0m may now be used to quit ACL2 and Lisp
  completely; in fact they macroexpand to calls of the same function
  as does [47m[good-bye][0m (which is now a macro).  Thanks to Jared Davis
  for suggesting the new aliases.  (OpenMCL-only comment:) These all
  work for OpenMCL even inside the ACL2 loop.

  The macro [47mwet[0m now hides structure by default on large expressions.
  However, a new optional argument controls this behavior, for
  example avoiding such hiding if that argument is [47mnil[0m.  Thanks to
  Hanbing Liu for pointing out that [47mwet[0m was not helpful for very
  large terms.

  We have fixed a bug in the forward-chaining mechanism that, very
  rarely, could cause a proof to be aborted needlessly with an
  obscure error message.  Thanks to Jared Davis for sending us an
  example that evoked this bug.

  Fixed a bug that was causing proof output on behalf of
  [47m:functional-instance[0m to be confusing, because it failed to mention
  that the number of constraints may be different from the number of
  subgoals generated.  Thanks to Robert Krug for pointing out this
  confusing output.  The fix also causes the reporting of rules used
  when silently simplifying the constraints to create the subgoals.

  Fixed a bug in handling of leading [47m./[0m in pathnames, as in:
  [47m(include-book \"./foo\")[0m.  Thanks to Jared Davis for bringing this
  bug to our attention.

  Made a small fix for handling of free variables of
  [47m:[0m[forward-chaining] rules, which had erroneously acted as though a
  hypothesis [47m(equal var term)[0m can bind the variable [47mvar[0m.

  A small change has been made for [47m:[0m[47m[type-prescription][0m rules for
  hypotheses of the form [47m(equal var term)[0m, where [47mvar[0m is a free
  variable and no variable of [47mterm[0m is free (see [free-variables]).
  As with [47m:[0m[47m[rewrite][0m and [47m:[0m[47m[linear][0m rules, we now bind [47mvar[0m to [47mterm[0m
  even if [47m(equal u term)[0m happens to be known in the current context
  for some term [47mu[0m.  Also as with [47m:rewrite[0m and [47m:linear[0m rules, similar
  handling is given to hypotheses [47m(equiv var (double-rewrite term))[0m
  where [47mequiv[0m is a known [equivalence] relation.

  We changed the handling of free variables in hypotheses of [47m:[0m[47m[rewrite][0m
  rules being handled by the [proof-builder]'s [47mrewrite[0m ([47mr[0m) command,
  in complete analogy to the change described just above for
  [47m:[0m[47m[type-prescription][0m rules.

  The installation instructions have been updated for obtaining GCL on
  a Macintosh.  Thanks to Robert Krug for supplying this information
  and to Camm Maguire for simplifying the process by eliminating the
  [47mgettext[0m dependency.

  The macro [47m[comp][0m is now an event, so it may be placed in [books].

  Previously, a [47m[save-exec][0m call could fail because of file permission
  issues, yet ACL2 (and the underlying Lisp) would quit anyhow.  This
  has been fixed.  Thanks to Peter Dillinger for bringing this
  problem to our attention.

  Jared Davis, with assistance from David Rager, has updated his
  ordered sets library, [47mbooks/finite-set-theory/osets/[0m.  See file
  [47mCHANGES.html[0m in that directory.

  A new function, [47m[reset-kill-ring][0m, has been provided for the rare
  user who encounters memory limitations.  See [reset-kill-ring].")
 (NOTE-2-9-5
  (RELEASE-NOTES)
  "Changes in Version 3.0 since Version 2.9.4

  Fixed a bug in [47m[cw-gstack][0m that was causing a hard error when
  attempting to report on a forced assumption.  Thanks to Jared Davis
  for pointing this out and sending an example that helped us to
  determine a fix.

  Added [47m[set-backchain-limit][0m to the set of legal [events] that can be
  placed in [47m[encapsulate][0m forms and [books].  Thanks to John Cowles
  for bringing this issue to our attention.

  Fixed a bug that broke [47mwet[0m.  Thanks to David Rager for bringing this
  bug to our attention.

  Guard verification now evaluates ground subexpressions (those with no
  free variables) when computing the guard conjecture for the body of
  a function.  Thanks to Jared Davis for useful conversations leading
  to this change.  See [verify-guards], in particular its ``Note on
  computation of guard conjectures and evaluation'' near the end of
  that topic, for more details.

  Added a warning when a [47m[theory-invariant][0m is redefined.  Thanks to
  Jared Davis for suggesting a warning in this case and providing an
  informative example.  Also, [47m[theory-invariant][0ms are now maintained
  more completely, as they are checked at the end of every event
  except for events executed on behalf of an [47m[include-book][0m or the
  second pass of an [47m[encapsulate][0m.

  Fixed the handling of runic designators to match their specification
  (see [theories]), so that disabling the name of a [47m[defthm][0m event
  [47m[disable][0ms all rules generated for that event.

  (For those who do numerous builds using feature [47m:acl2-mv-as-values[0m,
  currently only OpenMCL and multi-threaded SBCL by default:) You can
  speed up builds by adding the following parameter to `make', under
  conditions described in [47mGNUmakefile[0m: [47mUSE_ACL2_PROCLAIMS=:REUSE[0m.

  Arranged that traced functions (see [trace$]) are automatically
  untraced when events are undone (for example see [ubt]), at least
  for most underlying Common Lisp implementations.

  The macro [47m[defun-sk][0m now creates non-executable functions, which
  allows [47m[stobj][0ms to be used where they had previously been
  prohibited.  More generally, the user now has control over
  [47m[declare][0m forms to be used by the underlying [47m[defun][0m'd function;
  see [defun-sk].  Thanks to Sandip Ray for pointing out the need for
  such a modification.

  [47m:[0m[47m[Definition][0m rules are now treated, at least by default, as truly
  first-class definitions.  In particular, [47m:expand[0m [hints] use the
  latest [47m:[0m[47m[definition][0m rule by default.  You may specify
  [47m:install-body nil[0m to get the previous behavior of [47m:definition[0m
  rules; See [definition], and you may choose a previously-installed
  [47m:definition[0m rule to provide the current body; see [set-body].  Also
  see [rule-classes] for details of the [47m:install-body[0m field, and see
  [hints] to see a new [47m:with[0m directive for controlling expansion.
  The [47m:with[0m directive for [47m:expand[0m hints can even direct the use of a
  [47m:[0m[47m[rewrite][0m rule for expansion!  Thanks to various people, including
  Sandip Ray and Rob Sumners, for discussions on the issue of the
  applicability of [47m:definition[0m rules for [47m:expand[0m [hints].

  [Constraint]s for functional instantiation now use the original
  definition rather than a simplified (``normalized'') version of it.

  Fixed a bug that caused the prompt to stay the same when
  guard-checking is off (see [set-guard-checking]) and raw-mode is
  changed (see [set-raw-mode]).

  Lemma names in directory [47mbooks/ordinals[0m have been changed by
  replacing [47m/\\[0m with [47m&[0m and replacing [47m\\/[0m with [47mV[0m.  We made this change
  because backslash is an escape character and hence disappears
  unless it is itself escaped.

  Fixed [proof-tree] output so that failed non-proof events do not
  cause the proof-tree to be re-printed.  Thus for example, if you
  have already advanced the checkpoint marker, it will not be reset
  by subsequent failed non-proof events.  Thanks to Pete Manolios and
  Peter Dillinger for bringing this bug to our attention.

  Fixed a bug that was preventing the printing of [stobj] fields as
  constants instead of numbers in certain cases.  (Note that this bug
  only affected printing, not soundness.) Thanks to Eric Smith for
  bringing this problem to our attention and providing the following
  example (which now works fine).

    (defstobj st fld1 fld2)
    (in-theory (disable update-nth))
    (defund run (st)
      (declare (xargs :stobjs (st))) ;adding this didn't seem to help..
      st)

    ;works great; *fld1* prints as  *fld1*
    (thm (equal (update-nth *fld1* 'abc st)
                (car (cons x y))))

    ;*fld1* gets printed as 0, presumably because the call to run intervenes.
    (thm (equal (update-nth *fld1* 'abc (run st))
                (car (cons x y))))

  The macro [47m[progn][0m now allows the use of macros defined within its
  bodies even when at the event level, as illustrated by the
  following example.

    (progn (defmacro my-defun (&rest args)
             `(defun ,@args))
           (my-defun g (x) x))

  Thanks to Anna Slobodova for bringing this issue to our attention.  A
  related change is that all arguments of [47m[progn][0m must now be
  embedded event forms (see [embedded-event-form]), so use [47m[er-progn][0m
  instead if this is not the case.

  The change to [47m[progn][0m mentioned above also fixes a bug in handling
  [local] events inside a [47m[progn][0m that is inside an [47m[encapsulate][0m or
  in a book.  For example, the following form formerly caused an
  error.

    (encapsulate
     ()
     (defun foo (x) x)
     (progn (local (defun bar (x) x))
            (defun abc (x) x)))

  We fixed two bugs in [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m.  The first, brought to our
  attention by Eric Smith (who we thank), caused a cryptic error
  message when puffing a command with no subsidiary stored events;
  try, for example, [47m(encapsulate () (value-triple 3))[0m.  The second
  was due to a failure to restore the [47m[ACL2-defaults-table][0m.  Suppose
  for example that we have certified the book [47mfoo.lisp[0m, which
  contains [47m([0m[47m[program][0m[47m)[0m followed by some definitions and/or theorems.
  Now suppose we start ACL2 and execute the following.

    (include-book \"foo\")
    (defthm test-thm
      (equal x x)
      :rule-classes nil)

  If we now execute [47m:[0m[47m[puff][0m[47m 1[0m, ACL2 will roll back the world to before
  the [47m[include-book][0m; then ``puff'' the include-book, which will
  leave us in [47m:[0m[47m[program][0m mode; and finally skip re-execution of the
  [47m[defthm][0m because such [events] are skipped in [47m:[0m[47m[program][0m mode.  The
  fix is to re-install the [47m[ACL2-defaults-table][0m immediately after
  the [47m[include-book][0m to its pre-[47m[include-book][0m value.

  A new event, [47m[make-event][0m, provides something like macros that take
  state.  For example, one can use it to put tests into certified
  books, do proof search, and generate new function names.  Many
  examples appear in directory [47mbooks/make-event/[0m.  See [make-event].
  Thanks to Bob Boyer and Jared Davis for useful feedback and to
  Warren Hunt, David Rager, and Sandip Ray for helpful discussions
  leading to some of the examples in directory [47mbooks/make-event/[0m.

  In support of [47m[make-event][0m, which is described in the preceding
  paragraph, [47mcertify-book[0m has a new keyword argument,
  [47m:save-expansion[0m, that controls whether the result of expanding
  [47m[make-event][0m forms is written out to a file.  See [certify-book];
  and for a discussion of book expansion files, see [make-event].

  We fixed a soundness bug that did not correctly detect [47m[local][0m
  events.  For example, the following event was admitted.

    (encapsulate
     ()
     (local
      (encapsulate
       ()
       (local (progn (program))) ; or, (local (with-output :off summary (program)))
       (set-irrelevant-formals-ok t)
       (defun foo (x)
         (declare (xargs :measure (acl2-count x)))
         (1+ (foo x)))))
     (defthm inconsistent
       nil
       :hints ((\"Goal\" :use foo))
       :rule-classes nil))

  A new value for [guard] checking, [47m:none[0m, is now allowed.  If you
  execute [47m:[0m[47m[set-guard-checking][0m[47m :none[0m, then no guard checking will
  take place (but raw Lisp code will not be executed in this case).
  As a result, you should never see a guard violation, even for calls
  of [47m:[0m[47mprogram[0m mode functions.  We thank Pete Manolios, who has long
  wanted this feature, and also Peter Dillinger, for asking for it.
  New documentation explains the interaction between the [defun-mode]
  and the value supplied to [47m:[0m[47m[set-guard-checking][0m.  See
  [guard-evaluation-table], see [guard-evaluation-examples-script],
  and see [guard-evaluation-examples-log].

  In the course of adding the [guard]-checking value [47m:none[0m described in
  the paragraph above, we eliminated an optimization that eliminated
  guard checking for some recursive calls of [47m:[0m[logic] mode
  mutually-recursive functions that have not had their guards
  verified.  But we doubt that this change will be noticed by any
  users!)

  The ACL2 hyper-card has been enhanced, thanks to David Rager, with a
  listing of ``Useful EMACS Commands'' to match comments in
  [47memacs/emacs-acl2.el[0m.

  Users contributed books following the [47mReadme.lsp[0m methodology:
  [47mdata-structures/memories[0m and [47municode[0m (Jared Davis), [47mproofstyles[0m
  (Sandip Ray and J Moore).

  Made some improvements to [47mbooks/Makefile-generic[0m (a file discussed
  elsewhere; see [books-certification-classic]).  In particular,
  improved handling of [47m.acl2[0m files for [47mdependencies[0m target.

  (Only OpenMCL and, with feature [47m:acl2-mv-as-values[0m, GCL) Fixed a bug
  that was causing proclaiming to fail when definitions are submitted
  interactively.

  The default stack size has been increased for several lisps.

  (Very technical) A restriction has been weakened on the use of
  [47m[local][0m [stobj]s under a call of an ACL2 evaluator ([47mtrans-eval[0m or
  [47msimple-translate-and-eval[0m).  Now, the error can only take place for
  [47m[stobj][0m names that occur in the term being evaluated.  Thanks to
  Erik Reeber for bringing this issue to our attention.

  The notion of ``ancestor'' has been changed slightly.  This notion is
  used by extended metafunctions and [break-rewrite] (see
  [extended-metafunctions] and see [brr@]), and also with backchain
  limits (see [backchain-limit] and see [set-backchain-limit]).
  Basically, each time a hypothesis is encountered during application
  of a [rewrite] rule, that hypothesis is pushed (after instantiating
  and negating) onto the current list of ancestors before it is
  rewritten.  However, hypotheses of the form [47m(equal var term)[0m, where
  [47mvar[0m is free (see [free-variables]), had not been included in the
  ancestors (similarly for [47m(equiv var (double-rewrite term))[0m where
  [47mequiv[0m is a known [equivalence] relation).  Now such ``binding
  hypotheses'' are included in a special way in ancestors data
  structures.  In particular, [47m(null (mfc-ancestors mfc))[0m will now be
  true if and only if the term being rewritten is part of the current
  goal as opposed to a hypothesis from a rule encountered during
  backchaining, even if that hypothesis is a binding hypothesis.
  Thanks to Dave Greve for bringing this issue to our attention.

  Termination and induction analysis now continue through both
  arguments of [47m[prog2$][0m, not just the second.  (Normally, the
  gathering up of [47m[if][0m tests stops at function calls; but it
  continued through the second argument of [47m[prog2$][0m, and now it will
  continue through both arguments.)  Thanks to Sol Swords for
  discussion leading to this change.

  The ACL2 distribution is now kept on the http server rather than the
  ftp server (but the home page has not been moved).  Thanks to
  Robert Krug for letting us know that some ACL2 users have found it
  inconvenient to fetch ACL2 using ftp.

  The file [47mbooks/README.html[0m has been renamed to [47mbooks/Readme.html[0m,
  since some browsers don't show the former in the directory listing.")
 (NOTE-2-9{R}
  (RELEASE-NOTES)
  "ACL2 Version 2.9(r) (October, 2004) Notes

  No changes have been made for support of non-standard analysis, other
  than a minor modification or two in [47mbooks/nonstd/[0m books.

  Please also see [note-2-9] for changes to Version_2.9 of ACL2.")
 (NOTE-3-0
  (RELEASE-NOTES)
  "ACL2 Version 3.0 (June, 2006) Notes

  Please see [note-2-9-5] for a description of changes since Version
  2.9.4.  These include the new [47m[make-event][0m feature, a soundness bug
  fix, an improvement for [47m:expand[0m [hints], evaluation in the logic by
  way of [47m:[0m[47m[set-guard-checking][0m[47m :none[0m, and many other improvements.

  More generally, there have been several incremental releases since
  Version 2.9: see [note-2-9-1], see [note-2-9-2], see [note-2-9-3],
  see [note-2-9-4], and see [note-2-9-5].

  A very few users have contributed books following the instructions on
  the web.  We expect that when more contributions come in, we will
  give more attention to the question of how to organize the
  distributed and workshop books.  For now, we have simply added the
  new contributions according to the old-style distribution
  methodology.")
 (NOTE-3-0-1
  (RELEASE-NOTES)
  "ACL2 Version 3.0.1 (August, 2006) Notes

  NOTE!  New users can ignore these release notes, because the
  documentation has been updated to reflect all changes that are
  recorded here.

  Fixed a soundness bug, introduced in the previous release, due to a
  failure to disallow [47m[table][0m [events] that set the
  [47m[ACL2-defaults-table][0m in a [47m[local][0m context.  Here is a proof of [47mnil[0m
  that exploits the bug.

    (encapsulate ()
     (local (program))
     (defun foo ()
       (declare (xargs :measure 17))
       (+ 1 (foo))))
    (thm
     nil
     :hints ((\"Goal\" :in-theory (disable foo (foo)) :use foo)))

  Fixed a bug in the alternatives to [47m[good-bye][0m, which are the [47m[exit][0m
  and [47m[quit][0m commands.  Thanks to Jared Davis and Peter Dillinger for
  pointing this out right away.

  The definition of [47m[len][0m has been highly optimized in raw Lisp.
  Thanks to Bob Boyer and Warren Hunt for suggesting such an
  improvement and providing a lot of help in coming up with the
  current implementation.

  The clause subsumption algorithms have been improved, both to improve
  efficiency during warnings for [47m:[0m[47m[rewrite][0m rules and to punt when
  the subsumption computation for induction appears to be blowing up.
  Thanks to Robert Krug for bringing this issue to our attention and
  supplying a useful example.

  A bug has been fixed that prevented [47m[time$][0m from working properly in
  OpenMCL and multi-threaded SBCL (actually, in any ACL2 image where
  feature [47m:acl2-mv-as-values[0m is present).  Thanks to Sol Swords for
  bringing this problem to our attention.

  A [type-spec] of the form [47m(satisfies pred)[0m carries the requirement
  that [47mpred[0m be a unary function symbol in the current ACL2 [world];
  otherwise, it is illegal.  Thanks to Dave Greve for pointing out
  that Common Lisp has this requirement.

  Installed a fix provided by Gary Byers (for ACL2 source function
  [47minstall-new-raw-prompt[0m), for OpenMCL, that fixes an issue exposed
  in some versions of OpenMCL when compiler optimization is off.

  Fixed a bug in contributed book [47mmisc/untranslate-patterns.lisp[0m that
  was causing calls of [47madd-untranslate-pattern[0m to be rejected in
  [books].  Thanks to Ray Richards for pointing out this bug and to
  Jared Davis for assisting in the fix.

  Fixed a bug in [47m[defstobj][0m when keywords [47m:initially[0m and [47m:resizable[0m are
  both supplied.  In this case, the definition of the resizing
  function mistakenly failed to quote the [47m:initially[0m value, even
  though this value is not to be evaluated.  One could even get an
  error in this case, as in the following example supplied by Erik
  Reeber, whom we thank for bringing this bug to our attention:

    (defstobj $test
      (test-x :type (array t (5)) :initially (0) :resizable t))

  A new feature, [47m[with-prover-time-limit][0m, allows the setting of time
  limits during proofs.  This is [31;1mnot[0m a general-purpose time-limit
  utility, nor is it guaranteed to implement a strict bound; it only
  attempts to limit time approximately during proofs.  Thanks to Pete
  Manolios and Daron Vroon, who made the most recent request for such
  a feature, and to Robert Krug for a helpful discussion.

  (GCL only) Fixed a bug in the procedure for building a profiling
  image.  Thanks to Sol Swords for bringing this bug to our attention
  and to Eric Smith for bringing a subsequent problem to our
  attention.

  Handling of [theories] can now use significantly less time and space.
  A regression suite run took about 25% longer before this change
  than it did after making this change (and also the ones in the next
  two paragraphs).  Thanks to Vernon Austel for bringing this issue
  to our attention and for supplying code, quite some time ago, that
  provided detailed, useful implementation suggestions.  Also thanks
  to the folks at Rockwell Collins, Inc. for pushing the limits of
  the existing implementation, thus encouraging this improvement.

  Fixed a performance bug in obtaining executable counterpart symbols.

  We now avoid certain computations made on behalf of warnings, when
  such warnings are disabled.

  We have relaxed the checks made when including an uncertified book,
  to match the checks made when including a certified book.  Thanks
  to Eric Smith for suggesting this change.

  Fixed a bug in [47m:[0m[47m[pso][0m (see set-saved-output) that caused an error
  when printing the time summary.

  Made fixes to avoid potential hard Lisp errors caused by the use of
  [47m:[0m[47m[program][0m mode functions.  The fix was to use a ``safe mode,''
  already in use to prevent such errors during macroexpansion; see
  [guards-and-evaluation].  However, such errors were possible during
  evaluation of macro [guard]s, for example as follows:

    (defun foo (x)
      (declare (xargs :mode :program))
      (car x))
    (defmacro mac (x)
      (declare (xargs :guard (foo 3)))
      x)
    (defun g (x)
      (mac x))

  A similar issue existed for calls of [47m[defpkg][0m, [47m[in-theory][0m, [47m[table][0m,
  [47m[make-event][0m, and [47mvalue-triple[0m, but has been fixed for all but
  [47min-theory[0m and [47mmake-event[0m, where technical issues have caused us to
  defer this change.

  Fixed a bug in [47mwet[0m that caused problems in OpenMCL, and perhaps other
  Lisp implementations, when the argument to [47mwet[0m calls, or depends
  on, certain built-ins including [47m[prog2$][0m, [47m[time$][0m, [47m[mbe][0m, and
  [47m[must-be-equal][0m.  Thanks to David Rager for bringing this problem
  to our attention.

  The file [47mbooks/Makefile-generic[0m has been improved so that when book
  certification fails with `make', the failure message contains the
  book filename.

  Documentation has been written to explain how to avoid an expensive
  immediate rewrite of the result of applying a [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[meta][0m
  rule.  See [meta].  Thanks to Robert Krug for supplying this trick,
  and to Eric Smith and Dave Greve for useful discussions.

  (OpenMCL only) OpenMCL-based ACL2 image names formerly had extension
  [47m\".dppccl\"[0m, which was correct only for some platforms (including
  32-bit Darwin PPC).  That has been fixed, thanks to a suggestion
  from Gary Byers.

  It is now legal to attach both a [47m:use[0m and a [47m:cases[0m hint at the same
  goal.  Thanks to Eric Smith for (most recently) requesting this
  feature.

  It is now permissible to include the same symbol more than once in
  the imports list of a [47m[defpkg][0m form (i.e., its second argument).
  Also, the evaluation of [47m[defpkg][0m forms with long import lists now
  uses a reasonably efficient sorting routine to check for two
  different symbols with the same name (see also
  [47mbooks/misc/sort-symbols.lisp[0m).  If you currently call a function
  like [47mremove-duplicates-eql[0m for your imports list, as had been
  suggested by a [47m[defpkg][0m error message, then you may experience some
  speed-up by removing that call.  Thanks to Eric Smith for helping
  to discover this issue through profiling.

  Made miscellaneous efficiency improvements not listed above (for
  example, following a suggestion of Eric Smith to avoid checking for
  so-called ``bad Lisp objects'' during [47m[include-book][0m, which saved
  almost 3% in time on one large example).

  Modified the notion of ``untouchable'' to separate the notion of
  untouchable functions and macros from the notion of untouchable
  state global variables.  See [push-untouchable].  Thanks to Bob
  Boyer for sending an example, [47m(put-global 'ld-evisc-tuple t state)[0m,
  that suggested to us the need for more restrictive handling of
  untouchables.  In particular, many [47mld[0m specials (see [ld]) are now
  untouchable.  You may be able to work around this restriction by
  calling [47m[ld][0m; see for example the change to
  [47mbooks/misc/expander.lisp[0m.  But please contact the ACL2 implementors
  if this sort of workaround does not appear to be sufficient for
  your purposes.

  Fixed a bug in function [47mset-standard-oi[0m (see [standard-oi]).

  Fixed a bug in the use of [47m[ld-evisc-tuple][0m.  The bad behavior was an
  improper use of the print-level and print-length components of the
  tuple (specifically, taking its [47m[caddr][0m and [47m[cadddr][0m instead of
  taking its [47m[cadr][0m and [47m[caddr][0m).  Thanks to Bob Boyer for bringing
  this bug to our attention.

  A new argument to the [47mcompile-flg[0m argument of [47m[certify-book][0m, [47m:all[0m,
  causes creation of a file to be compiled in place of the given
  book, where that file contains not only a copy of the book (with
  [47m[make-event][0m forms expanded) but also contains definitions of the
  so-called ``executable counterparts'' of the functions defined in
  the book.  Then, functions defined in the book will be run compiled
  when including the book, even for functions whose [guard]s have not
  been verified, or are in [47m:program[0m mode and running in so-called
  ``safe mode'' (for example, during expansion of macros).  The
  default behavior, value [47mt[0m of [47mcompile-flg[0m, is unchanged.  Moreover,
  a new [47m:comp![0m argument of [47m[include-book][0m now compiles the executable
  counterparts when creating the book's compiled file, and unlike
  [47m:comp[0m, always deletes the old compiled file first so that one
  always gets a fresh compile.

  Now, [47m[certify-book][0m gives a \"Guards\" warning only for [47m:[0m[47m[logic][0m mode
  functions that are defined in the given book but have not had their
  guards verified.  Previously, it also warned about such functions
  that were defined in the certification world or in sub-books.

  A new command, [47m[redo-flat][0m, facilitates the debugging of failed
  [47m[encapsulate][0m and [47m[progn][0m forms by evaluating preliminary forms in
  order to leave one at the point of failure.  See [redo-flat].
  Thanks to Ray Richards and others for asking for such a utility,
  and to Sandip Ray for useful discussions.

  We have changed the automatic declaration of function types (still
  done in GCL and OpenMCL only, for now).  Our motivation was to
  avoid the assumption that Common Lisp functions return one value
  when ACL2 says that they do; thanks to Bob Boyer for bringing this
  issue to our attention with the example of defining [47m(foo x y)[0m to be
  [47m(floor x y)[0m.  ACL2 was saying that [47mfoo[0m returns a single value, but
  because [47mfloor[0m returns two values in raw Lisp, so does [47mfoo[0m.  Other
  changes to automatic declaration include comprehending [47m[defund][0m,
  not just [47m[defun][0m.

  A new function, [47m[mod-expt][0m, computes [47m(mod (expt base exp) m)[0m, and
  does so efficiently in some implementations (currently only in GCL
  2.7.0, which is not yet released).  Thanks to Warren Hunt for
  suggesting such an addition.

  New functions [47m[getenv$][0m and [47m[setenv$][0m have been made available for
  reading and writing environment variables.  Thanks to Jun Sawada
  for requesting these utilities.

  The query utility [47m:[0m[47m[pl][0m has been improved in several ways.  As
  before, [47m:[0m[47m[meta][0m rules are only printed if the argument is a symbol;
  but the information printed for them is now more appropriate.  The
  following are changes for the case that the argument is not a
  symbol, but rather, a term.  (1) Rules are displayed that have
  [equivalence] relations other than [47m[equal][0m.  (2) All matching
  [47m:[0m[47m[definition][0m rules are displayed, where previously [47m:definition[0m
  rules were only shown if they were ``simple'' rules (sometimes
  known as ``abbreviations''); see [simple].  (3) The ``Equiv'' field
  is printed for terms, not just symbols.  (4) The substitution is
  shown that, when applied to the left-hand side of the rule, will
  yield the specified term.  Thanks to Eric Smith for suggesting
  these changes.

  The [proof-builder] command [47m;show-rewrites[0m has been improved to match
  the changes described above for [47m:[0m[47m[pl][0m.  In particular,
  [47m:[0m[47m[definition][0m rules that are not ``[simple]'' are now displayed by
  the [proof-builder]'s [47mshow-rewrites[0m (and [47msr[0m) command, and the
  [proof-builder]'s [47mrewrite[0m command has been correspondingly modified
  to accept these [47m:definition[0m rules.

  Fixed `make' targets [47mcopy-distribution[0m, [47mcopy-workshops[0m, and
  [47mcopy-nonstd[0m so that they should also work for non-developers.

  Fixed a bug that was causing [47m:[0m[47m[pr][0m to display [47m[syntaxp][0m hypotheses
  oddly in some cases, in particular [47m(syntaxp (let ...))[0m.  (The
  problem was in the ``untranslate'' display of the internal form of
  [47msyntaxp[0m calls.)  Thanks to Robert Krug for bringing this problem to
  our attention.  We also removed the restriction on [47m[bind-free][0m that
  its argument could not be a variable, a constant, or (more
  interestingly) a [47m[lambda][0m application (i.e., a [47m[let][0m or [47m[mv-let][0m
  expression).")
 (NOTE-3-0-1{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.0.1(r) (August, 2006) Notes

  No significant changes have been made since Version 3.0 for support
  of non-standard analysis in particular.

  Please also see [note-3-0-1] for changes to Version 3.0.1 of ACL2.")
 (NOTE-3-0-2
  (RELEASE-NOTES)
  "ACL2 Version 3.0.2 (December, 2006) Notes

  NOTE!  New users can ignore these release notes, because the
  documentation has been updated to reflect all changes that are
  recorded here.

  Fixed soundness bugs in the handling of primitive function
  [47m[pkg-witness][0m, and improved its documentation.  (The executable
  counterpart returned an incorrect default value, and the axiom
  [47msymbol-package-name-pkg-witness-name[0m needed [47mpkg-name[0m to be other
  than [47m\"\"[0m in order to avoid the default value of \"ACL2\".)  As
  fallout, a new built-in [47m:[0m[47m[forward-chaining][0m rule,
  [47msymbol-package-name-of-symbol-is-not-empty-string[0m, now asserts that
  the [47m[symbol-package-name][0m of a symbol is never [47m\"\"[0m.  Thanks to Mike
  Gordon for bringing these soundness bugs to our attention by
  attempting to prove translations of ACL2 axioms in HOL4.

  Fixed a soundness bug in linear arithmetic, due to incomplete
  tracking of forced assumptions while deriving inequalities.  Thanks
  to Robert Krug for providing a fix and a proof of [47mnil[0m before the
  fix.

  Fixed a soundness bug in the redundancy criterion for [47m[defun][0m events,
  which has been modified; see [redundant-events].  This bug is
  illustrated below.  Thanks to Peter Dillinger and Jared Davis for
  contributions to an email thread that led us to discover this bug.
  The solution is that for a definition to be redundant with an
  earlier definition, ACL2 no longer ignores [47m:[0m[47m[measure][0m [47m[xargs][0m
  except when skipping proofs (e.g., during [47m[include-book][0m).
  However, a new ``measure'', [47m(:? v1 ... vk)[0m, is supported, for
  specifying a measured subset of the set of formals, i.e., a set of
  formals that serves as the set of parameters for some valid
  measure.

    (encapsulate
     ()

     (local (defun foo (x y)
              (declare (xargs :measure (acl2-count y)))
              (if (and (consp x) (consp y))
                  (foo (cons x x) (cdr y))
                y)))

    ; So the following is redundant -- but it guesses a measure
    ; of (acl2-count x), which isn't right!
     (defun foo (x y)
       (if (and (consp x) (consp y))
           (foo (cons x x) (cdr y))
         y)))

    ; end of encapsulate

    ; Now we prove a non-theorem by exploiting the bug above,
    ; erroneously replacing formal y by a constant in the induction
    ; scheme hinted below.  (This should not be allowed, as y should be
    ; labeled as a measured formal.)

    (defthm bad
      (atom x)
      :rule-classes nil
      :hints ((\"Goal\" :induct (foo x '(3)))))

    ; It's easy to get a contradiction by instantiating the
    ; non-theorem just above.
    (defthm contradiction
      nil
      :rule-classes nil
      :hints ((\"Goal\" :use ((:instance bad (x '(7)))))))

  Fixed a bug in [47m:[0m[47m[pl][0m and the [proof-builder]'s [47mshow-rewrites[0m ([47msr[0m)
  command that was causing a Lisp break.  For [47m:[0m[47m[pl][0m, also improved
  the display of unifying substitutions, modified output to take
  binding hypotheses [47m(equal var term)[0m into account properly, and
  arranged for inclusion of [meta] rules that modify the given term.
  Thanks to Eric Smith for bringing these issues to our attention.

  Introduced new utilities for undoing [command]s, [47m:[0m[47m[ubu][0m and [47m:[0m[47m[ubu!][0m,
  which are analogous to [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubt!][0m (respectively) except
  that they only undo back up to, but not including, the indicated
  command.

  Fixed a performance bug, pointed out by Eric Smith, that was negating
  efforts made for the preceding release to avoid computation for
  disabled warnings.

  Added [47m[time$][0m and [47mvalue-triple[0m to [47m*acl2-exports*[0m.  Thanks to Bob
  Boyer and Erik Reeber (respectively) for bringing these issues to
  our attention.

  Improved the automatic proclaiming of function types for GCL and
  OpenMCL, specifically to use an output format consistent with the
  Common Lisp spec.  Thanks to Bob Boyer for bringing this issue to
  our attention.

  Added [47mbooks/misc/transfinite.lisp[0m, which deals with transfinite
  induction in ACL2.  Thanks to Eric Smith for contributing this
  book.

  Added [47mbooks/misc/process-book-readme.lisp[0m to the distribution.
  Thanks to Sandip Ray for pointing out its omission.

  Added contributions [47mbooks/concurrent-programs/bakery/[0m and
  [47mbooks/concurrent-programs/german-protocol/[0m.  These contributions
  can be used as tutorials, especially by new ACL2 users, for
  learning how to model concurrent protocols in ACL2 and the steps
  involved in reasoning about their correctness.  Thanks to Sandip
  Ray for these contributions.  See the [47mReadme.lsp[0m files in these
  directories.

  Theory invariants may now involve the variable [47mENS[0m instead of the
  variable [47mTHEORY[0m.  The practical effect of this change is that any
  expression of the form [47m(MEMBER-EQUAL rune THEORY)[0m occurring in a
  [47m[theory-invariant][0m expression should be replaced by [47m(ACTIVE-RUNEP
  rune)[0m.  See [theory-invariant].  Thanks to Eric Smith and Dave
  Greve for pointing out an inefficiency in the handling of theory
  invariants that led to this change, which can speed up their
  handling by orders of magnitude on large examples, and to Eric for
  testing this change and pointing out problems with an early
  implementation of it.

  Theory invariants (see [theory-invariant]) are no longer checked on
  theories defined by [47m[deftheory][0m [events].  After all, one can
  define a theory with [47mdeftheory[0m that is not intended to be used as
  the current theory, but rather is intended to be combined with
  other [theories] (see [theory-functions]).  Thanks to Eric Smith
  for bringing this issue to our attention.

  [47m[Theory-invariant][0m errors had been reported with very little detail
  when warnings were inhibited.  This problem has been fixed; thanks
  to Eric Smith for bringing it to our attention and providing an
  example.  We have also improved the handling of redundancy for
  [47m[theory-invariant][0m [events].

  The macro [47m[defun-sk][0m now has a new optional keyword, [47mrewrite[0m, that
  can be used to change the form of the [47m:[0m[47m[rewrite][0m rule generated
  when the quantifier is [47m[forall][0m.  Thanks to Eric Smith and Sandip
  Ray for useful discussions on this topic.  We have also slightly
  modified the [hints] for the [47m[defthm][0m event underneath a [47mdefun-sk[0m
  in order to make the proof more reliably efficient.

  A new event, [47m[reset-prehistory][0m, allows setting of a barrier before
  which undoing is illegal.  An argument to this macro allows the
  barrier to be made permanent; otherwise, it can be removed with
  [47m:[0m[47m[ubt-prehistory][0m.  Thanks to Peter Dillinger for useful
  conversations leading to the addition of [47m[reset-prehistory][0m.

  A new query, [47m([0m[47m[wormhole-p][0m[47m [0m[47m[state][0m[47m)[0m, allows users to determine
  whether or not they are in a [47m[wormhole][0m.  Thanks to Peter Dillinger
  for providing this utility.

  [47mValue-triple[0m no longer evaluates its form during [47m[include-book][0m, and
  in raw Lisp its calls trivially macroexpand to [47mnil[0m, without any
  consideration of its argument.  This change avoids errors and
  warnings when [stobj] names occur in the argument.

  We fixed what could be considered a soundness hole that could occur
  by exploiting redefinition in a particular way.  Thanks to Peter
  Dillinger for raising a question that led to discovery of this
  hole.

  A bug has been fixed in handling of illegal [theory] expressions.
  Thanks to Eric Smith, who reported this problem and provided the
  example [47m(in-theory '((:definition natp) (:rewrite doesntexist)))[0m to
  show how a hard error could occur.

  Improved error reporting by [47m[certify-book][0m when the certification
  [world] contains inadmissible forms.

  Modified [47m[defchoose][0m to add two new keyword arguments.  There is now
  a [47m:doc[0m keyword argument; previously, an optional documentation
  string (see [47mdoc-string[0m) was to be placed just before the body,
  without a keyword.  There is also a [47m:strengthen[0m argument that
  strengthens the axiom added, which allows for the definition of
  ``fixing'' functions for equivalence relations that choose
  canonical representatives of equivalence classes.  See [defchoose].
  Thanks for Dave Greve for useful discussions that led us to this
  [47m:strengthen[0m enhancement.

  Added [47mbooks/misc/bash.lisp[0m, which provides utilities for simplifying
  a goal into a list of subgoals (as documented at the top of that
  file).  Thanks to Dave Greve for requesting this utility and
  suggesting refinements to its functionality, which have been
  incorporated.

  (For Emacs users only) The command [47mmeta-x new-shell[0m provided by file
  [47memacs/emacs-acl2.el[0m now puts you in shell-mode, which for example
  supports directory tracking.  Thanks to Jared Davis for suggesting
  this change.

  Fixed some mishandling of [stobj]s by [47m[make-event][0m expansion.

  Introduced a new event, [47m[defttag][0m, that introduces a ``trust tag''
  (``ttag'') allowing for extensions of ACL2 and for the use of
  generally unsafe ACL2 constructs.  Thanks to Peter Dillinger,
  Sandip Ray, and Erik Reeber for useful discussions on [47mdefttag[0m and
  the following related items.

      A new event, [47m[remove-untouchable][0m, can be used to give users access
      to system functions and data structures.  We also fixed a bug
      in [47m[push-untouchable][0m; and, it no longer is a no-op in
      [47m:[0m[47m[program][0m mode.  Thanks to Peter Dillinger for proposing
      [47m[remove-untouchable][0m and suggesting that it and
      [47m[push-untouchable][0m be functional in [47m:[0m[47m[program][0m mode.

      Raw-mode (see [set-raw-mode]) no longer disables [47m[certify-book][0m.
      However, [47m[set-raw-mode][0m is now disallowed unless there is an
      active ttag (see [defttag]).  If you want to execute
      [47m([0m[47m[set-raw-mode][0m[47m t)[0m and there is no active ttag, consider
      executing [47m([0m[47m[set-raw-mode-on!][0m[47m)[0m instead.

      Redefinition of system functions is disallowed unless there is an
      active ttag.  However, [47m[redef!][0m now introduces [47m(defttag
      :redef!)[0m in order to allow redefinition of system functions.

      A new event, [47m[progn!][0m, is a legal embedded event form that can go in
      [books] and both [47m[encapsulate][0m and [47m[progn][0m forms (see
      [embedded-event-form]), and is similar to [47m[progn][0m except that
      it allows arbitrary forms.  Thus, a [47m[progn!][0m form is
      potentially dangerous and can only be evaluated if there is an
      active ttag.

      See [ttags-seen] for information about how to find the ttags known in
      the current ACL2 [world], and for related caveats.

      A new book created with Peter Dillinger, [47mbooks/misc/hacker.lisp[0m
      (added after Version_3.3: now [47mbooks/hacking/hacker.lisp[0m), uses
      [47m[progn!][0m to define utilities [47mwith-raw-mode[0m and
      [47mwith-redef-allowed[0m, which respectively allow raw Lisp
      evaluation and redefinition to take place within a certifiable
      book (!).

  Macro [47m[with-output][0m is no longer allowed in function bodies because
  it does not have (and has never had) any effect in raw Lisp.  See
  [with-output] for a workaround.

  Fixed a bug in redundancy of [47m[defstobj][0m in raw Lisp, which caused an
  error when certifying a book with a redundant [47m[defstobj][0m event
  whose [47m[stobj][0m had already been modified.  Here is an example:

    (defstobj st fld)
    (update-fld 3 st)
    (certify-book \"foo\" 1) ; where foo.lisp contains (defstobj st fld)

  New books illustrating [47m[make-event][0m have been contributed in
  directory [47mbooks/make-event/[0m: [47mdotimes.lisp[0m (David Rager),
  [47mstobj-test.lisp[0m, and [47mlogical-tangent.lisp[0m (Peter Dillinger).

  Modified [47mprint-object$[0m (see [io]) so that it no longer prints an
  extra space at the end.

  Replaced the ``draconian restriction to avoid capture'' that had
  prevented some [47m:functional-instance[0m [hints] from being legal.  The
  corresponding check now only requires that no variable free in the
  functional substitution is captured by a [47m[let][0m or [47m[mv-let][0m (or
  [47m[lambda][0m) binding.  See [lemma-instance].

  Added new extended metafunction, [47mmfc-rw+[0m, which is equivalent to
  [47mmfc-rw[0m except that it takes an alist argument, which may be useful
  for efficiency.  See [extended-metafunctions].  Thanks to Robert
  Krug for suggesting this more efficient variant of [47mmfc-rw[0m.

  Added support for the [47mignorable[0m [47m[declare][0m form.

  We now cause an error on a call of [47mopen-input-channel[0m (see [io]) with
  an argument string whose first character is the [47m|[0m character.
  Thanks to Bob Boyer for providing an example (several months ago)
  showing the danger of such calls, namely that the following command
  would log you out and kill all of your processes when running on
  top of GCL in Linux:
  [47m(open-input-channel \"|kill -9 -1\" :object state)[0m

  Restricted the use of [47m[make-event][0m to contexts in which it can be
  tracked properly, under legal [events] (see [embedded-event-form]).
  Thanks to Peter Dillinger for bringing an example to our attention
  that led to this fix.

  Fixed a bug that was avoiding [guard]-checking for the functions
  [47m[compress1][0m and [47m[compress2][0m.  Thanks to David Rager for bringing
  this bug to our attention.

  Added an error message when a [47m[defun][0m or [47m[mutual-recursion][0m event
  fails, to clarify whether failure is for the [measure] conjecture
  or for the [guard] conjecture.  Thanks to David Rager for
  requesting clarification for such failures.

  Fixed a bug in reporting of [guard] violations (hard Lisp error) when
  certain macros (for example, [47m[cond][0m) are used in the [guard].
  Thanks to Jared Davis for bringing this problem to our attention
  and providing assistance with the solution, in particular by
  providing a helpful example.

  Grant Passmore has contributed a resolution/paramodulation prover
  written in ACL2, in directory [47mbooks/deduction/passmore/[0m.  Thanks,
  Grant.

  Improved the error message when illegal theories are encountered.

  Improved the suppression of output for [47minhibit-output[0m arguments of
  routines in the book [47mbooks/misc/expander.lisp[0m.  Thanks to Qiang
  Zhang for pointing out the possibility for improvement here.

  Added a new directory [47mbooks/arithmetic-3/extra/[0m that extends
  [47mbooks/arithmetic-3[0m with additional rules, contributed by Alex
  Spiridonov with guidance from Robert Krug.  WARNING: This directory
  is under development.  It may undergo large changes in future
  releases, so please consider it experimental and subject to change.
  Feedback is welcomed.

  As part of the work mentioned just above, Robert Krug and Alex
  Spiridonov contributed improvements to [47mbooks/arithmetic-3/[0m:

      o A new rule [47m|(* (/ x) (/ (expt x n)))|[0m in [47mbind-free/collect.lisp[0m,
      which is important for reducing [47mcollect-*[0m expressions though it
      slowed down one proof (see comment above this rule in
      [47mbind-free/collect.lisp[0m).

      o Slight improvements of rules [47mintegerp-mod[0m and [47mrationalp-mod[0m in
      [47mfloor-mod/floor-mod.lisp[0m.

      o To avoid conflict with [47mbooks/rtl/rel6/arithmetic/[0m, renamed rule
      [47mmod-minus[0m to [47mmod-neg[0m in [47mfloor-mod/floor-mod.lisp[0m, and renamed
      [47mintegerp-+-reduce-leading-constant[0m to
      [47mintegerp-+-reduce-leading-rational-constant[0m in
      [47mbind-free/integerp.lisp[0m.

  (GCL on Windows only) Made a low-level change to avoid multiplying
  stacks for GCL on Windows, since GCL 2.6.6 broke while doing this.

  Fixed bugs in linear arithmetic (rarely evidenced, it seems)
  involving using [47m<[0m to compare complex rational constants.  Thanks to
  Robert Krug for helping with the fixes.

  Added a new event, [47m[assert-event][0m, for checking that forms evaluate
  to non-[47mnil[0m values.  Thanks to Peter Dillinger for suggesting and
  collaborating on this addition.")
 (NOTE-3-0{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.0(r) (June, 2006) Notes

  No significant changes have been made since Version 2.9 for support
  of non-standard analysis in particular.

  Please also see [note-3-0] for changes to Version 3.0 of ACL2.")
 (NOTE-3-1
  (RELEASE-NOTES)
  "ACL2 Version 3.1 (December, 2006) Notes

  NOTE!  New users can ignore these release notes, because the
  documentation has been updated to reflect all changes that are
  recorded here.

  Please see [note-3-0-2] for a description of changes since Version
  3.0.1, and also see [note-3-0-1] for additional changes since
  Version 3.0.")
 (NOTE-3-1{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.1(r) (December, 2006) Notes

  No significant changes have been made since Version 3.0 for support
  of non-standard analysis in particular.

  Please also see [note-3-1] for changes to Version 3.1 of ACL2.")
 (NOTE-3-2
  (RELEASE-NOTES)
  "ACL2 Version 3.2 (April, 2007) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Before this release, a raw Lisp error could put the ACL2 user into
  the debugger of the host Common Lisp.  Now, such cases will
  generally put the user back at the top-level loop after an
  informative message.  For details, see [set-debugger-enable]; also
  see [break$].

  Fixed a soundness bug that was allowing unknown packages to sneak
  into a book and wreak havoc.  Thanks to Peter Dillinger for sending
  an interesting example that led us to an exploration resulting in
  finding this bug.  (A comment in the source code for [47mnote-3-2[0m shows
  such an example.)  That example led us to fix a couple of other
  bugs related to packages.  See [hidden-death-package] if you are
  generally interested in such issues, and for associated examples,
  see comments in [47mnote-3-2[0m in the ACL2 source code.

  Fixed subtle soundness bugs related to [47m:[0m[47m[meta][0m rules by restricting
  evaluators (see [defevaluator]), as discussed in a new
  documentation topic: see [evaluator-restrictions].

  Fixed a soundness bug that was allowing redefinition from [47m:[0m[47m[logic][0m to
  [47m:[0m[47m[program][0m mode.  This prohibition had been in ACL2 for awhile but
  was accidentally removed in the preceding version.

  Fixed a soundness bug related to [47m[trace$][0m.  Thanks to Peter Dillinger
  for bringing it to our attention and for useful discussions, and
  providing a proof of [47mnil[0m, the essence of which is illustrated as
  follows:

    (value-triple (trace$ (bar :entry (defun foo () 17))))

  Thus, [47m[trace$][0m could be used to cause destructive raw Lisp behavior.
  Now, [47mtrace$[0m fails unless it is either given a list of symbols or
  else there is an active trust tag (see [defttag]); otherwise,
  consider using [47mtrace![0m instead.

  Closed a loophole that could be viewed as compromising soundness.  It
  was possible to write files during book certification by exploiting
  [47m[make-event][0m expansion, but that is no longer the case by default.
  A new function [47m[open-output-channel!][0m is identical as a function to
  [47mopen-output-channel[0m, except that the new function may be called
  even during [47m[make-event][0m expansion and [47m[clause-processor][0m [hints],
  but requires that there is an active trust tag (see [defttag]).
  Thanks to Peter Dillinger for producing a convincing example
  (forging a [certificate] during book certification; see
  [open-output-channel!]) and to him, Sandip Ray, and Jared Davis for
  useful discussions on the topic.

  Added book [47mbooks/defexec/reflexive/reflexive.lisp[0m to illustrate
  reflexive functions.

  ACL2 now generates scripts that invoke the saved image with [47mexec[0m.
  (Previously this was only done for GCL and CLISP.)  The benefit of
  this change can be to avoid the lingering of ACL2 processes after
  enclosing processes have exited.  Thanks to Peter Dillinger for
  pointing out this issue.

  ACL2 has a better implementation of [47m([0m[47m[good-bye][0m[47m)[0m (hence of synonyms
  [47m([0m[47m[quit][0m[47m)[0m and [47m([0m[47m[exit][0m[47m)[0m).  As a result, you should now be able to
  exit ACL2 and Lisp from within the ACL2 read-eval-print loop with
  any of the above; formerly, this was not supported for some Lisp
  implementations, and was slow in OpenMCL.  Thanks to SBCL developer
  Harald Hanche-Olsen for useful advice.

  Fixed a bug in raw-mode (see [set-raw-mode]) that was causing hard
  errors when evaluating calls of [47m[er-progn][0m, or of macros expanding
  to such calls.

  Fixed a few Makefile dependencies, necessary only for parallel
  `make'.

  A new book, [47mmisc/defpun-exec-domain-example.lisp[0m, provides an example
  showing how partial functions which return a unique value for
  arguments in a specified domain can be efficiently executed with
  ACL2.  Execution is achieved using the [47m[mbe][0m construct.  Thanks to
  Sandip Ray for providing this example.

  Existing function [47m[mod-expt][0m computes [47m(mod (expt base exp) mod)[0m with
  great efficiency in GCL, but not in other Lisps.  Now, the book
  [47marithmetic-3/floor-mod/mod-expt-fast.lisp[0m defines a function
  [47mmod-expt-fast[0m that should provide significantly improved
  performance for such expressions in other Lisps as well, though
  still probably not as fast as when using [47mmod-expt[0m in GCL.  Thanks
  to Warren Hunt, with contributions from Robert Krug, for providing
  this book,

  Modified macro [break-on-error] to print an error message before
  entering a break, and to cause a hard error if the underlying Lisp
  cannot handle it (formerly, a raw Lisp break would occur).  Thanks
  to Bob Boyer for bringing these issues to our attention.

  The book [47mbooks/misc/defpun.lisp[0m, as well as other books related to
  the [47mdefpun[0m macro, has been modified to avoid namespace collisions
  by prefixing function symbol names with [47m\"DEFPUN-\"[0m; for example [47mbase[0m
  has been replaced by [47mdefpun-base[0m.  Thanks to Dave Greve for
  providing a first version of this update to [47mdefpun.lisp[0m.

  A theory, [47mbase[0m, in [47mbooks/arithmetic-3/bind-free/top.lisp[0m, has been
  renamed [47marithmetic-3-bind-free-base[0m, to avoid potential name
  conflicts.

  Fixed [47mbooks/arithmetic-3/bind-free/banner.lisp[0m to print (as before) a
  message about how to turn on non-linear arithmetic, by modifying
  the call of [47mvalue-triple[0m to use [47m:on-skip-proofs t[0m.  Thanks to
  Robert Krug for bringing this issue to our attention.

  Modified [47mbooks/Makefile-subdirs[0m and [47mbooks/Makefile-psubdirs[0m so that
  they can be used with [47mbooks/Makefile-generic[0m.  Thus, one can set
  things up so that `make' can be used to certify books both in the
  current directory and subdirectories, for example as follows.

    ACL2 = ../../saved_acl2

    arith-top: top all
    all: top

    DIRS = pass1 bind-free floor-mod
    include ../Makefile-subdirs
    include ../Makefile-generic

    top.cert: top.lisp
    top.cert: bind-free/top.cert
    top.cert: floor-mod/floor-mod.cert
    top.cert: floor-mod/mod-expt-fast.cert

  An experimental extension of ACL2 is under development by Bob Boyer
  and Warren Hunt to support function memoization, hash conses, and
  an applicative version of hash tables.  The default build of ACL2
  does not include this extension, other than simple logic
  definitions of functions in new source file [47mhons.lisp[0m.  Future
  versions of ACL2 may fully incorporate this experimental extension.

  The [47m[defevaluator][0m event macro has been modified primarily by adding
  a new constraint as follows, where [47mevl[0m is the evaluator.  The idea
  is that for the evaluation of a function call, one may replace each
  argument by the quotation of its evaluation and then also replace
  the alist environment with [47mnil[0m.

    (DEFTHMD UNHIDE-evl-CONSTRAINT-0
      (IMPLIES (AND (CONSP X)
                    (SYNTAXP (NOT (EQUAL A ''NIL)))
                    (NOT (EQUAL (CAR X) 'QUOTE)))
               (EQUAL (evl X A)
                      (evl (CONS (CAR X)
                                 (KWOTE-LST (UNHIDE-evl-LIST (CDR X) A)))
                           NIL))))

  In order to support this change, there is another change: an
  evaluator maps [47mnil[0m to [47mnil[0m (note [47m(AND X (CDR (ASSOC-EQ X A)))[0m in
  place of [47m(CDR (ASSOC-EQ X A))[0m below).

    (DEFTHM UNHIDE-evl-CONSTRAINT-1
      (IMPLIES (SYMBOLP X)
               (EQUAL (UNHIDE-evl X A)
                      (AND X (CDR (ASSOC-EQ X A))))))

  With the new [47m[defevaluator][0m, Dave Greve has been able to do a proof
  about beta reduction that seemed impossible before (see
  [47mbooks/misc/beta-reduce.lisp[0m).  Thanks to Dave for suggesting an
  initial version of this change.

  Explicit compilation is now avoided for OpenMCL, resulting in fewer
  files to manage (no more files resulting from compilation) and,
  according to some tests, slightly faster run times.  See
  [compilation].  Thanks to Bob Boyer and Warren Hunt for suggesting
  this possibility.

  Now, the [47mterm-evisc-tuple[0m (see [ld-evisc-tuple]) is overridden by
  state global [47muser-term-evisc-tuple[0m in all cases.  Formerly, this
  was only the case when [47mterm-evisc-tuple[0m was called with non-[47mnil[0m
  first argument.

  Symbols with the dot ([47m.[0m) character are generally no longer printed
  with vertical bars.  For example, before this change:

    ACL2 !>'ab.c
    |AB.C|
    ACL2 !>

  After this change:

    ACL2 !>'ab.c
    AB.C
    ACL2 !>

  Thanks to Jared Davis for suggesting this improvement.

  Fixed bugs in [47mguard[0m verification for theorems.  The following
  examples illustrate these bugs.  If either theorem's body is
  executed in raw Lisp there is likely to be a hard Lisp error, even
  though [47m[verify-guards][0m was supposed to ensure against that
  behavior.

    ; Example: Verify-guards failed to check that all functions in the theorem
    ; had already been guard-verified.
    (defun my-car (x) (car x))
    (defthm my-car-compute-example (equal (my-car 3) (my-car 3)))
    (verify-guards my-car-compute-example)

    ; Example: Verify guards of a theorem whose body uses state improperly.
    (defthm bad-state-handler
      (if (state-p state)
          (equal (car state) (car state))
        t)
      :rule-classes nil)
    (verify-guards bad-state-handler)

  See [gcl] for an example, developed with Warren Hunt and Serita
  Nelesen, that shows how to get fast fixnum (small integer)
  arithmetic operations in GCL.

  Fixnum declarations are now realized as [47m(signed-byte 30)[0m and
  [47m(unsigned-byte 29)[0m instead of what was generally [47m(signed-byte 29)[0m
  and [47m(unsigned-byte 28)[0m.  MCL users may thus find better performance
  if they switch to OpenMCL.  Note that some definitions have changed
  correspondingly; for example, [47m[zpf][0m now [47m[declare][0ms its argument to
  be of type [47m(unsigned-byte 29)[0m instead of [47m(unsigned-byte 28)[0m.  A few
  [books] may thus need to be adjusted; for example, changes were
  made to books in [47mbooks/data-structures/memories/[0m.

  ACL2's rewriter now avoids removing certain true hypotheses and false
  conclusions.  When a hypothesis rewrites to true or a conclusion
  rewrites to false, ACL2 formerly removed that hypothesis or
  conclusion.  Now, it only does such removal when the hypothesis or
  conclusion is either a call of [47m[equal][0m or an equivalence relation
  (see [equivalence]), or else is sufficiently trivial (roughly,
  either redundant with another hypothesis or conclusion or else
  trivially true without considering the rest of the goal).  A
  specific example may be found in source file [47msimplify.lisp[0m; search
  for ``; But we need to do even more work''.  Thanks to Robert Krug
  for providing the idea for this improvement and its initial
  implementation.  As is common with heuristic changes, you may find
  it necessary on occasion to rename some subgoals in your [hints].
  And in this case, you might also find it necessary on rare
  occasions to add [47m:do-not '(generalize)[0m [hints].

  A new function, [47mmfc-relieve-hyp[0m, allows (for example) for more
  powerful [47m[bind-free][0m hypotheses, by providing an interface to the
  rewriter's routine for relieving hypotheses.  See
  [extended-metafunctions].  Thanks to Robert Krug for providing the
  idea for this feature and its initial implementation.

  Two improvements have been made to non-linear arithmetic (see
  [non-linear-arithmetic]).  One allows for deducing strict
  inequality ([47m<[0m) for the result of certain polynomial
  multiplications, where previously only non-strict inequality ([47m<=[0m)
  was deduced.  A second allows the use of the product of two
  polynomials when at least one of them is known to be rational.  We
  had previously restricted the use of the product to the case where
  both were known to be rational.  Thanks to Robert Krug for these
  improvements.

  (OpenMCL and Allegro CL only) Fixed ACL2's redefinitions of raw Lisp
  [47mtrace[0m and [47muntrace[0m in OpenMCL and Allegro CL so that when given no
  arguments, they return the list of traced functions.  For [47mtrace[0m,
  this is an ANSI spec requirement.  Note that [47m[trace$][0m and
  [47m[untrace$][0m continue to return [47mnil[0m in the ACL2 loop.

  Fixed a bug that was allowing the symbol [47m&whole[0m to appear in other
  than the first argument position for a [47m[defmacro][0m event, in
  violation of the Common Lisp spec (and leading to potentially
  surprising behavior).  Thanks to Peter Dillinger for bringing this
  bug to our attention.

  It had been illegal to use [47m[make-event][0m under some calls of [47m[ld][0m.
  This has been fixed.  Thanks to Jared Davis for bringing this issue
  to our attention with a simple example, in essence:

    (ld '((defmacro my-defun (&rest args) `(make-event '(defun ,@args)))
          (my-defun f (x) x)))

  ACL2 no longer prohibits certain [47m[make-event][0m forms when including
  uncertified [books].  Thanks to Peter Dillinger for first bringing
  this issue to our attention.

  Hard errors arose when using [break-rewrite] stack display commands,
  in particular [47m:path[0m and [47m:frame[0m, from inside the [proof-builder].
  This has been fixed.

  Fixed a bug that could cause functions that call system built-ins
  [47mf-put-global[0m, [47mf-get-global[0m, or [47mf-boundp-global[0m to cause a raw Lisp
  error even when proving theorems.  Thanks to Peter Dillinger, for
  reporting such a failure for the form [47m(thm (w '(1 2 3)))[0m.

  Renamed the formal parameters of function [47mset-equal[0m in distributed
  book [47mbooks/arithmetic-3/bind-free/normalize.lisp[0m so that more
  distributed books can be included together in the same session.  In
  particular books [47mbooks/data-structures/set-theory[0m and
  [47mbooks/arithmetic-3/extra/top-ext[0m can now be included together.
  Thanks to Carl Eastlund for bringing this problem to our attention
  and to Robert Krug for suggesting the formals renaming as a fix.

  Metafunctions must now be executable.  See [meta].

  New utilities allow for user-defined simplifiers at the goal level,
  both verified and unverified (``trusted''), where the latter can
  even be defined by programs outside ACL2.  See [clause-processor],
  which points to a new directory [47mbooks/clause-processors/[0m that
  contains examples of these new utilities, including for example a
  system (``SULFA'') contributed by Erik Reeber that implements a
  decision procedure (thanks, Erik).  Also see
  [proof-builder-commands] for the new [proof-builder] command
  [47mclause-processor[0m (or for short, [47mcl-proc[0m).

  The rewriter has been tweaked to run faster in some cases involving
  very large terms.  Thanks to Eric Smith and Jared Davis for
  providing a helpful example that helped us locate the source of
  this inefficiency.

  Added [47mbooks/make-event/defspec.lisp[0m.  This book shows how one can
  mimic certain limited forms of higher-order statements in ACL2 by
  use of macros, [47m[make-event][0m, and [47m[table][0m events.  Thanks to Sandip
  Ray for his contribution.

  A new release of the RTL library, [47mbooks/rtl/rel7/[0m, replaces the
  previous version, [47mbooks/rtl/rel6/[0m.  Thanks to Hanbing Liu and David
  Russinoff for providing this new version.

  We thank David Russinoff for providing a proof of the law of
  quadratic reciprocity.  See [47mbooks/quadratic-reciprocity/Readme.lsp[0m.

  Eliminated a slow array warning (see [slow-array-warning]) that could
  occur when exiting a [wormhole] after executing an [47m[in-theory][0m
  event in that wormhole.  Thanks to Dave Greve for bringing this
  problem to our attention.

  A new accessor, [47m(mfc-rdepth mfc)[0m, provides a new field, the remaining
  rewrite stack depth, which has been added to metafunction context
  structures; see [extended-metafunctions].  Thanks to Eric Smith for
  suggesting this addition.

  The algorithms were modified for collecting up rule names and other
  information used in proofs, into so-called ``tag-trees''.
  Tag-trees are now free of duplicate objects, and this change can
  dramatically speed up some proofs that involve many different
  rules.  Thanks to Eric Smith for doing some profiling that brought
  this issue to our attention, and for reporting that this change
  reduced proof time on an example by about 47% (from 3681.46
  reported seconds down to 1954.69).

  All legal [47mxargs[0m keywords may now be used in [47m[verify-termination][0m
  [events].  In particular, this is the case for [47m:normalize[0m.

  (SBCL and CMUCL only) Fixed a problem with stobj array resizing
  functions that was causing a hard error in ACL2 images built on
  SBCL or CMUCL.

  A new [table], [47m[evisc-table][0m, allows you to introduce print
  abbreviations, for example for large constants.  Moreover, a new
  reader macro --- [47m#,[0m --- makes it convenient to reference constants
  even inside a quote.  See [evisc-table].  Thanks to Bob Boyer and
  Warren Hunt for useful discussions leading to this feature.

  The macros in [47mbooks/misc/expander.lisp[0m now have a new keyword
  argument, [47m:simplify-hyps-p[0m.  The default behavior is as before, but
  now case splitting from hypothesis simplification can be avoided.
  For details, evaluate [47m(include-book \"misc/expander\" :dir :system)[0m
  and then [47m:doc!  defthm?[0m and [47m:doc! symsym[0m.  Thanks to Daron Vroon
  for sending a question that prompted this additional functionality.

  ACL2 failed to apply [47m:[0m[47m[restrict][0m hints to rules of class
  [47m:[0m[47m[definition][0m, except for the simplest sorts (see [simple]).  This
  has been fixed.  Thanks to Jared Davis for pointing out this bug by
  sending a small example.

  Added a new [47m:msg[0m argument to [47massert-event[0m; see [assert-event].  The
  implementation of [47mvalue-triple[0m has been modified to support this
  change.

  Fixed a bug in macro [47mio?[0m that now allows the [47mcommentp[0m argument to be
  [47mt[0m.  This provides a way other than [47mcw[0m to print without modifying
  state, for example as follows.  (Warning: Certain errors may leave
  you in a [wormhole], in which case use [47m:a![0m to abort.)

    ACL2 !>(prog2$ (io? event t state
                        ()
                        (fms \"Howdy~%\" nil *standard-co* state nil))
                   (+ 3 4))

    Howdy
    7
    ACL2 !>:set-inhibit-output-lst (proof-tree event)
     (PROOF-TREE EVENT)
    ACL2 !>(prog2$ (io? event t state
                        ()
                        (fms \"Howdy~%\" nil *standard-co* state nil))
                   (+ 3 4))
    7
    ACL2 !>

  ACL2 now disallows calls of [47m[progn!][0m inside function bodies, just as
  it already disallowed such calls of [47m[progn][0m, since in both cases
  the Common Lisp meaning differs from the ACL2 meaning.

  Redefinition of system functions now always requires an active trust
  tag (see [defttag]).  This restriction was intended before, but
  there was a hole that allowed a second redefinition without an
  active trust tag.  Thanks to Peter Dillinger for pointing out this
  bug.

  [47m[Verify-termination][0m has been disabled for a few more built-in
  functions that are in [47m:[0m[47m[program][0m mode.  (If you are curious about
  which ones they are, evaluate [47m(f-get-global
  'built-in-program-mode-fns state)[0m.)  [Note added for Version_3.4:
  This state global has been changed to 'program-fns-with-raw-code.]
  Moreover, such functions now will execute only their raw Lisp code,
  so for example they cannot be called during macroexpansion.  Thanks
  to Peter Dillinger and Sandip Ray for useful discussions on details
  of the implementation of this restriction.

  New untouchable state global variables, [47mtemp-touchable-vars[0m and
  [47mtemp-touchable-fns[0m, can control the enforcement of untouchability.
  See [remove-untouchable].  Thanks to Peter Dillinger for suggesting
  these features.

  The ``TTAG NOTE'' string was being printed by [47m[encapsulate][0m events
  whenever an active trust tag was already in effect (see [defttag]),
  even if the encapsulate event contained no [47m[defttag][0m event.  This
  has been fixed.  Thanks to Peter Dillinger for a query leading to
  this fix.

  Fixed a bug in [47m[progn!][0m that could leave the user in raw-mode (see
  [set-raw-mode]).  This could occur when certifying a book with a
  [47mcompile-flg[0m value of [47mt[0m (see [certify-book]), when that book
  contained a [47m[progn!][0m event setting raw-mode to [47mt[0m without setting
  raw-mode back to [47mnil[0m:

    (progn! (set-raw-mode t) ...)")
 (NOTE-3-2-1
  (RELEASE-NOTES)
  "ACL2 Version 3.2.1 (June, 2007) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  (OpenMCL and multi-threaded SBCL only) Fixed a soundness bug in the
  evaluation of [47m[mbe][0m forms in the presence of Lisp feature
  [47m:acl2-mv-as-values[0m.  Thanks to Sol Swords for reporting this
  problem and sending a simple proof of [47mnil[0m (which can be found in a
  comment in the ACL2 sources, in [47m(deflabel note-3-2-1 ...)[0m).

  Added a new utility, [47m[dmr][0m (Dynamically Monitor Rewrites), for
  watching the activity of the rewriter and some other proof
  processes.  See [dmr].  We thank Robert Krug for useful
  contributions.

  Fixed a bug in evaluation of calls of [47m[with-prover-time-limit][0m.

  Fixed the writing of executable scripts when building ACL2, so that
  the build-time value of environment variable [47mACL2_SYSTEM_BOOKS[0m is
  no longer written there.  Thanks to Dave Greve for discussing this
  change.

  Fixed bugs in [47m:[0m[47m[pl][0m (which are similarly present in the
  [proof-builder]'s [47msr[0m ([47mshow-rewrites[0m) command.  The first bug was
  evident from the following forms sent by Robert Krug, which caused
  an error.

    (include-book \"arithmetic-3/floor-mod/floor-mod\" :dir :system)
    :pl (mod (+ 1 x) n)

  The second bug was due to a failure to take note of which rules are
  disabled, and could be seen by executing the following (very
  slow!).

    (defstub modulus () t)
    (include-book \"arithmetic-3/floor-mod/floor-mod\" :dir :system)
    :pl (mod (+ x y) (modulus))

  Modified [47m[certify-book][0m so that by default, all
  executable-counterpart functions (sometimes called ``*1*
  functions'') are compiled.  This is the behavior that was already
  supported with a [47mcompile-flg[0m argument of [47m:all[0m; the change is that
  argument [47mt[0m now has this behavior as well (and [47m:all[0m is supported
  only for legacy purposes).  A new value for [47mcompile-flg[0m, [47m:raw[0m,
  gives the behavior formerly produced by value [47mt[0m, namely where
  executable-counterpart functions are not compiled.  The above
  changes are irrelevant if compilation is suppressed; see
  [compilation].  Finally, if environment variable [47mACL2_COMPILE_FLG[0m
  is set, then after converting to upper-case this environment
  variable's value of [47m\"T\"[0m, [47m\"NIL\"[0m, or [47m\":RAW\"[0m will determine the value
  of the optional [47mcompile-flg[0m argument to be [47mt[0m, [47mnil[0m, or [47m:raw[0m,
  respectively, when this argument is not explicitly supplied.

  Modified [47m[include-book][0m so that [47m:comp[0m argument now acts like [47m:comp![0m,
  i.e., compiling a file that includes the file together with all
  executable counterpart (so-called ``*1*'') functions.  A new
  argument, [47m:comp-raw[0m, has the behavior that [47m:comp[0m had formerly,
  i.e., compiling the actual book only.

  The function [47m[nonnegative-integer-quotient][0m is now computed in raw
  Lisp by calling [47m[floor][0m on its arguments.  This change was
  suggested by Peter Dillinger, in order to avoid stack overflows
  such as reported by Daron Vroon.  A new book,
  [47mbooks/misc/misc2/misc.lisp[0m, contains a proof of equivalence of
  [47m[nonnegative-integer-quotient][0m and [47m[floor][0m, and serves as a
  repository for other miscellaneous proofs, including those
  justifying ACL2 modifications such as this one.

  Enhanced [47m[accumulated-persistence][0m to break down results by useful
  vs.  useless rule applications.  In particular, this provides
  information about which rules were ever applied successfully, as
  requested by Bill Young.

  Added coverage of [47m:[0m[47m[meta][0m rules to the [47m[accumulated-persistence][0m
  statistics.

  Fixed a bug that was causing a [47m:[0m[47m[clause-processor][0m hint to fire on a
  subgoal of the goal to which it was attached, when the original
  application didn't change the clause.  Thanks to Dave Greve for
  pointing out this bug and providing a useful example.

  Fixed a bug in handling of computed [hints] related to the
  [47mstable-under-simplificationp[0m parameter (see [computed-hints]).
  There were actually two bugs.  A minor but confusing bug was that
  the same goal was printed twice upon application of such a hint.
  The major bug was that [47m:use[0m [hints] (as well as other ``top''
  hints: [47m:by[0m, [47m:cases[0m, and [47m:clause-processor[0m) were not being applied
  properly.  Thanks to Jared Davis for sending an example some time
  ago that showed the duplicate printing, and to Dave Greve for
  sending an example showing mis-application of [47m:[0m[47m[clause-processor][0m
  [hints].  Note that you may find that existing computed hints using
  the [47mstable-under-simplificationp[0m parameter no longer have the same
  behavior; see a comment about computed hints in [47mnote-3-2-1[0m, ACL2
  source file [47mld.lisp[0m, for an example of how you might want to fix
  such computed hints.

  David Russinoff has contributed an updated version of
  [47mbooks/quadratic-reciprocity/[0m including minor modifications of the
  treatment of prime numbers and a proof that there exist infinitely
  many primes.  Thanks to David for contributing this work, and to
  Jose Luis Ruiz-Reina for posing the challenge.

  Reduced the sizes of some [certificate] ([47m.cert[0m) files by relaxing the
  test that allows original [47m[defpkg][0m [events] to be placed there,
  rather than evaluating the import list term into an explicit list
  of symbols.

  Improved execution efficiency slightly for function [47mrcdp[0m in file
  [47mbooks/misc/records.lisp[0m, by using [47m[mbe][0m to introduce a
  tail-recursive body.

  The executable script generated by [47m[save-exec][0m (and by the normal
  build process) now includes a time stamp as a comment.  Thanks to
  Jared Davis for suggesting this change in order to support his use
  of [47momake[0m.  In the process, we also arranged that the startup banner
  for an executable created by [47m[save-exec][0m shows all of the build
  (save) times, not just the one for the original image.

  Sped up most redundant [47m[defpkg][0m [events] by avoiding evaluation and
  sorting of the imports list in the case of identical event forms.
  And, for [47m[defpkg][0m events that are not redundant, sped up their
  processing in Allegro CL (and perhaps other Lisps, but apparently
  not GCL) by using our own [47mimport[0m function.

  Modified [47m[add-include-book-dir][0m so that it refuses to associate a
  keyword with a different directory string than one it is already
  bound to.  See [delete-include-book-dir] for how to remove the
  existing binding first.  Thanks to Robert Krug for pointing out
  that without this change, one can find it difficult to debug a
  failure due to rebinding a keyword with [47m[add-include-book-dir][0m.

  Added a new value for the [47m:do-not-induct[0m hint (see [hints]),
  [47m:otf-flg-override[0m, which causes ACL2 to ignore the [47m:[0m[47m[otf-flg][0m when
  considering whether to abort the proof because of a [47m:do-not-induct[0m
  hint.  Thanks to Daron Vroon for suggesting such an addition.

  Modified the printing of messages for entering and exiting raw mode
  (see [set-raw-mode]), so that in particular they are inhibited
  during [47m[include-book][0m or whenever [47mobservation[0ms are inhibited (see
  [set-inhibit-output-lst]).  Thanks to Peter Dillinger for
  suggesting such a change.

  (For system hackers only.)  The handling of [events] of the form
  [47m(progn! (state-global-let* ...))[0m had a bug that was causing
  bindings to be evaluated twice.  Moreover, the use of system
  function [47m[state-global-let*][0m is suspect in raw Lisp.  We have
  eliminated special treatment of [47mstate-global-let*[0m by [47mprogn![0m in
  favor of a new keyword argument, [47mstate-global-bindings[0m, that
  provides the intended functionality.  See [progn!].  Moreover,
  special handling that allowed [47m[make-event][0m forms under
  [47mstate-global-let*[0m has been removed; the desired effect can be
  obtained using (progn! :state-global-bindings ...).  Thanks to
  Peter Dillinger for pointing out the above bug and collaborating on
  these changes.

  Incorporated backward-compatible enhancements to
  [47mbooks/misc/expander.lisp[0m from Daron Vroon (documented near the top
  of that file).

  The specification of [47m:backchain-limit-lst[0m had required that only a
  single ([47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, or [47m:[0m[47m[meta][0m) rule be generated.  We
  have weakened this restriction to allow more than one rule provided
  that each rule has the same list of hypotheses.  For example, the
  rule class [47m(:rewrite :backchain-limit-lst 1)[0m is now legal for the
  corollary formula [47m(implies (f x) (and (g x) (h x)))[0m, where this was
  not formerly the case.  Thanks to Dave Greve for bringing this
  issue to our attention.")
 (NOTE-3-2-1{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.2.1(r) (June, 2007) Notes

  Please also see [note-3-2-1] for changes to Version 3.2.1 of ACL2.")
 (NOTE-3-2{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.2(r) (April, 2007) Notes

  Changed the default distributed [books] directory for ACL2(r) from
  [47mbooks/[0m to [47mbooks/nonstd/[0m.  See [include-book], in particular the
  discussion of ``Distributed Books Directory''.

  Added directory [47mbooks/arithmetic-3/[0m and its subdirectories to
  [47mbooks/nonstd/[0m.  (But a chunk of theorems from
  [47marithmetic-3/extra/ext.lisp[0m are ``commented out'' using
  #-:non-standard-analysis because they depend on [47mbooks/rtl/rel7/[0m,
  which is not yet in [47mbooks/nonstd/[0m; feel free to volunteer to remedy
  this!)

  Incorporated changes from Ruben Gamboa to some (linear and
  non-linear) arithmetic routines in the theorem prover, to
  comprehend the reals rather than only the rationals.

  Please also see [note-3-2] for changes to Version 3.2 of ACL2.")
 (NOTE-3-3
  (RELEASE-NOTES)
  "ACL2 Version 3.3 (November, 2007) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 3.2.1 into new
  features, bug fixes, prover algorithm enhancements, and
  miscellaneous.  Also see [note-3-2-1] for other changes since
  Version 3.2.

  [31;1mNEW FEATURES[0m

  A new ``gag-mode'' provides less verbose, more helpful feedback from
  the theorem prover, in support of The Method (see [the-method]).
  See [set-gag-mode].  We recommend the use of gag-mode, which may
  become the default in future ACL2 releases, and we welcome
  suggestions for improvement.  We thank Robert Krug and Sandip Ray
  for helpful feedback in the design of [gag-mode].  Note that when
  proofs fail, then even without gag-mode and even if proof output is
  inhibited, the summary will contain a useful listing of so-called
  ``key checkpoints'' (see [set-gag-mode]).

  Added support for a leading `[47m~[0m' in filenames.  Thanks to Bob Boyer
  for suggesting this enhancement.  Note that since `[47m~/[0m' depends on
  the user, it is disallowed in [books] to be certified (see
  [certify-book]), since otherwise an [47m[include-book][0m form in a book,
  [47mb[0m, could have a different meaning at certification time than at the
  time [47m[include-book][0m is later executed on book [47mb[0m.

  Made a change to allow [47m(time$ FORM)[0m and [47m(with-prover-time-limit TIME
  FORM)[0m when [47mFORM[0m includes [47m[make-event][0m calls that change the ACL2
  [world].  Thanks to Jared Davis for requesting such support for
  [47m[time$][0m.

  Computed [hints] (see [computed-hints]) may now produce a so-called
  ``error triple'', i.e., a result of the form [47m(mv erp val state)[0m,
  where a non-[47mnil[0m [47merp[0m causes an error, and otherwise [47mval[0m is the value
  of the hint.  It remains legal for a computed hint to return a
  single ordinary value; indeed, the symbol form of a computed hint
  must still be a function that returns an ordinary single value.

  New hints provide additional control of the theorem prover, as
  follows.  See [hints] for more details, and see new distributed
  book directory [47mbooks/hints/[0m for examples, in particular file
  [47mbasic-tests.lisp[0m in that directory for simple examples.

      o The hint [47m:OR (hints-1 ... hints-k)[0m causes an attempt to prove the
      specified goal using each [47mhints-i[0m in turn, 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.

      o A custom hint is a keyword that the user associates with a
      corresponding hint-generating function by invoking
      [47m[add-custom-keyword-hint][0m.  Thus, a custom hint may be viewed
      as a convenient sort of computed hint.

      o A custom hint, [47m:MERGE[0m, is implemented in distributed book
      [47mbooks/hints/merge.lisp[0m.  It is useful for combining hints.

      o A sophisticated yet useful custom hint is the [47m:CONSIDER[0m hint
      implemented in distributed book [47mbooks/hints/consider-hint.lisp[0m.
      With this hint, you can for example give the equivalent of a
      [47m:USE[0m hint without the need to supply an instantiation.  Include
      that book in order to see documentation online with [47m:doc
      consideration[0m, and see the book
      [47mbooks/hints/consider-hint-tests.lisp[0m for examples.

  A new hint, [47m:[0m[47m[reorder][0m, allows the specification of which subgoals
  are to be considered first.  Thanks to Sandip Ray for putting
  forward this idea.

  Enhanced [47mset-saved-output[0m by supporting a second argument of [47m:same[0m,
  which avoids changing which output is inhibited.

  Added macros [47mthm?[0m and [47mnot-thm?[0m to distributed book
  [47mbooks/make-event/eval.lisp[0m, so that it's easy to test within a
  certified book that a proof attempt succeeds or that it fails.

  Added printing function [47m[cw!][0m, which is analogous to [47m[cw][0m just as
  [47m[fmt!][0m is to [47m[fmt][0m, i.e., printing so that the result can be read
  back in.  Thanks to Jared Davis for suggesting this enhancement
  (after doing his own implementation).

  The ACL2 customization file can now be specified using environment
  variable [47mACL2-CUSTOMIZATION[0m [note: starting with Version_4.0,
  [47mACL2_CUSTOMIZATION[0m].  See [ACL2-customization].  Thanks to Peter
  Dillinger for requesting this feature.

  Added new emacs capabilities for proof trees (all documented in
  emacs):

      o New function start-proof-tree-noninteractive, for example
      (start-proof-tree-noninteractive \"*shell*\")

      o C-z o Switch to another frame

      o C-z b Switch to prooftree buffer

      o C-z B Switch to prooftree buffer in \"prooftree-frame\" frame

  Added Common Lisp function, [47msearch[0m, as a macro in [47m[logic][0m mode, with
  limited support for keyword arguments.  Thanks to Warren Hunt for
  requesting this addition.

  Sandip Ray has contributed a book, [47mbooks/make-event/defrefine.lisp[0m,
  that provides a collection of macros to aid in reasoning about ACL2
  functions via refinement.

  Wrote and incorporated new utility for listing all the theorems in an
  included book.  See [47mbooks/misc/book-thms.lisp[0m.  Thanks to Jared
  Davis for requesting this functionality.

  The new distributed book [47mmisc/defp.lisp[0m generalizes the [47m[defpun][0m
  macro to allow more general forms of tail recursion.

  (Low-level printing improvement) A new function,
  [47mset-ppr-flat-right-margin[0m, allows the right margin for certain
  kinds of ``flat'' printing to exceed column 40.  Thanks to Jared
  Davis for pointing out that state global variables
  [47m'fmt-hard-right-margin[0m and [47m'fmt-soft-right-margin[0m are not alone
  sufficient to extend the right margin in all cases.

  The event [47m[add-include-book-dir][0m can now take a relative pathname as
  an argument.  Formerly, it required an absolute pathname.

  A new book, [47mbooks/misc/defopener.lisp[0m, provides a utility creating a
  theorem that equates a term with its simplification.

  ACL2 now provides limited support for the Common Lisp primitive [47mFLET[0m,
  which supports local function bindings.  See [flet].  Thanks to
  Warren Hunt for requesting this feature.

  Added a definition of [47m[boole$][0m, a close analogue of Common Lisp
  function [47mboole[0m.  Thanks to Bob Boyer for providing an initial
  implementation.

  [31;1mBUG FIXES[0m

  Fixed [47m[defstobj][0m to inhibit a potentially useless theory warning.

  Fixed a bug in the application of [47m[certify-book][0m to relative
  pathnames for files in other than the current directory.  Thanks to
  Amr Helmy for bringing this bug to our attention.

  Fixed a bug in [47m:[0m[47m[pl][0m and [47m:[0m[47m[pr][0m for displaying rules of class [47m:[0m[47m[meta][0m.
  Thanks to Jared Davis for finding this bug and providing a fix.

  Formerly, [47m[set-default-backchain-limit][0m was not a legal event form
  for [47m[encapsulate][0m forms and [books].  This has been fixed.  Thanks
  to Robert Krug and Sandip Ray for bringing this bug to our
  attention.

  Fixed the handling of [hints] in [proof-builder] commands for the
  prover, such as [47mbash[0m --- see [proof-builder-commands] --- so that
  the user can override the default settings of hints, in particular
  of [47m:do-not[0m and [47m:do-not-induct[0m hints attached to [47m\"Goal\"[0m.  This fix
  also applies to the distributed book [47mmisc/bash.lisp[0m, where Robert
  Krug noticed that he got an error with [47m:hints ((\"Goal\" :do-not
  '(preprocess)))[0m; we thank Robert for pointing out this problem.

  Fixed a bug in handling of [stobj]s occurring in guards of functions
  whose [guard]s have been verified.  In such cases, a raw Lisp error
  was possible when proving theorems about non-''live'' [stobj]s.  We
  thank Daron Vroon for sending us an example that highlighted this
  bug.  The following (simpler) example causes such an error in
  previous versions of ACL2.

    (defstobj st fld)
    (defun foo (st)
      (declare (xargs :stobjs st :guard (fld st)))
      st)
    (thm (equal (foo '(3))
                '(3)))

  The [dmr] feature for dynamic monitoring of rewrites had a bug, where
  the file used for communicating with emacs was the same for all
  users, based on who built the ACL2 executable image.  This has been
  fixed.  Thanks to Robert Krug for bringing this bug to our
  attention.

  Fixed a bug in some warnings, in particular the warning for including
  an uncertified book, that was giving an incorrect warning summary
  string.

  Inclusion of uncertified books erroneously re-used [47m[make-event][0m
  expansions that were stored in stale [certificate]s.  This is no
  longer the case.  Thanks to Jared Davis for bringing this bug to
  our attention.

  Fixed a bug that was disallowing calls of [47m[with-output][0m in [events]
  that were executing before calling [47m[certify-book][0m.

  Modified the functionality of [47mbinop-table[0m so other than binary
  function symbols are properly supported (hence with no action based
  on right-associated arguments).  See [add-binop].

  Fixed small [proof-builder] issues related to packages.  Emacs
  commands [47mctrl-t d[0m and [47mctrl-t ctrl-d[0m now work properly with colon
  (`[47m:[0m') and certain other punctuation characters.  The [47mp-top[0m command
  now prints ``[47m***[0m'' regardless of the current package.

  Fixed a bug that allowed [47m[certify-book][0m to succeed without specifying
  value [47mt[0m for keyword argument [47m:skip-proofs-okp[0m, even with
  [47m[include-book][0m [events] in the certification [world] depending on
  events executed under [47m[skip-proofs][0m.

  Improved [47m[show-accumulated-persistence][0m in the following two ways.
  Thanks to Robert Krug and Bill Young for requesting these
  improvements and for providing useful feedback.

      o It can provide more complete information when aborting a proof.

      o The [47m:frames[0m reported for a rule are categorized as ``useful'' and
      ``useless'' according to whether they support ``useful'' or
      ``useless'' [47m:tries[0m of that rule, respectively.  See
      [accumulated-persistence] for further explanation.

  Modified [47m[make-event][0m so that the reported time and warnings include
  those from the expansion phase.  In analogy with [47m[encapsulate][0m and
  [47m[progn][0m, the rules reported still do not include those from
  subsidiary events (including the expansion phase).  A related
  change to [47m[ld][0m avoids resetting summary information (time,
  warnings) with each top-level form evaluation; [events] already
  handle this information themselves.

  Fixed [47m[set-inhibit-output-lst][0m so that all warnings are inhibited
  when [47mwarning![0m but not [47mwarning[0m is included in the list.  Formerly,
  only soundness-related warnings were inhibited in this case.
  Thanks to Eric Smith for bringing this bug to our attention.

  Distributed directory [47mdoc/HTML/[0m now again includes installation
  instructions (which was missing in Version_3.2.1), in
  [47mdoc/HTML/installation/installation.html[0m.

  Some fixes have been made for [proof-tree] support.

      o [Proof-tree] output is no longer inhibited automatically during
      [47m[certify-book][0m, though it continues to be inhibited by default
      (i.e., ACL2 continues to start up as though
      [47m[set-inhibit-output-lst][0m has been called with argument
      [47m'(proof-tree)[0m).

      o Fixed a bug in Xemacs support for [proof-tree] help keys [47mC-z h[0m and
      [47mC-z ?[0m.

      o Fixed a bug in [proof-tree]s that was failing to deal with the case
      that a goal pushed for proof by induction is subsumed by such a
      goal to be proved later.  Now, the proof-tree display regards
      such subsumed goals as proved, as is reported in the theorem
      prover's output.

  Fixed a bug that was disallowing [47m[value-triple][0m forms inside
  [47m[encapsulate][0m forms in a certification [world] (see [portcullis]).

  If the [47m:load-compiled-file[0m argument of a call of [47m[include-book][0m is
  [47m:comp[0m, then an existing compiled file will be loaded, provided it
  is more recent than the corresponding book (i.e., [47m.lisp[0m file).  A
  bug was causing the compiled file to be deleted and then
  reconstructed in the case of [47m:comp[0m, where this behavior was
  intended only for [47m:comp![0m.

  Fixed a bug that was avoiding compilation of some executable
  counterparts (sometimes called ``*1* functions'') during
  [47m[certify-book][0m, and also during [47m[include-book][0m with
  [47m:load-compiled-file[0m value of [47m:comp[0m or [47m:comp![0m).  Thanks to Eric
  Smith for sending a small example to bring this bug to our
  attention.

  Incorporated a fix from Eric Smith for a typo (source function
  [47mancestors-check1[0m) that could cause hard Lisp errors.  Thanks, Eric!

  Fixed the following issues with packages and book [certificate]s.
  See [hidden-death-package] if you are generally interested in such
  issues, and for associated examples, see comments on ``Fixed the
  following issues with packages'' in [47mnote-3-3[0m in the ACL2 source
  code.

      o Reduced the size of [47m.cert[0m files by eliminating some unnecessary
      [47m[defpkg][0m events generated for the [portcullis].

      o Fixed a bug that has caused errors when reading symbols from a
      [portcullis] that are in undefined packages defined in locally
      included books.

      o Fixed a bug that could lead to failure of [47m[include-book][0m caused by
      a subtle interaction between [47m[set-ignore-ok][0m and [47m[defpkg][0m
      events generated for the [portcullis] of a [certificate].

  [31;1mPROVER ALGORITHM ENHANCEMENTS[0m

  Non-linear arithmetic (see [non-linear-arithmetic]) has been improved
  to be more efficient or more powerful in some cases.  Thanks to
  Robert Krug for contributing these improvements.

  Improved certain (so-called ``[47m[type-set][0m'') reasoning about whether
  or not expressions denote integers.  Thanks to Robert Krug for
  contributing code to implement this change, along with examples
  illustrating its power that are now distributed in the book
  [47mbooks/misc/integer-type-set-test.lisp[0m.

  Improved ACL2's heuristics for relieving hypotheses, primarily to use
  linear reasoning on conjuncts and disjuncts of the test of an [47m[if][0m
  expression.  For example, given a hypothesis of the form [47m(if (or
  term1 term2) ...)[0m, ACL2 will now use linear reasoning to attempt to
  prove both [47mterm1[0m and [47mterm2[0m, not merely for [47mterm2[0m.  Thanks to Robert
  Krug for supplying examples illustrating the desirability of such
  an improvement and for useful discussions about the fix.

  Made a slight heuristic change, so that when a hypothesis with [47m[let][0m
  or [47m[mv-let][0m subterms (i.e. [47m[lambda][0m subterms) rewrites to [47mt[0m, then
  that hypothesis is necessarily eliminated.  Thanks to Jared Davis
  for sending an example that led us to develop this change, and
  thanks to Robert Krug for a helpful discussion.

  [31;1mMISCELLANEOUS[0m

  Added documentation on how to use [47m[make-event][0m to avoid duplicating
  expensive computations, thanks to Jared Davis.  See
  [using-tables-efficiently].

  Modified the error message for calls of undefined functions to show
  the arguments.  Thanks to Bob Boyer for requesting this
  enhancement.

  Modified utilities [47m:[0m[47m[pr][0m, [47m:[0m[47m[pr!][0m, [47m:[0m[47m[pl][0m, and [47m:[0m[47m[show-bodies][0m to
  incorporate code contributed by Jared Davis.  That code defines
  low-level source functions [47minfo-for-xxx[0m that collect information
  about rules, which is thus available to advanced users.

  Dynamic monitoring of rewrites (see [dmr]) has been improved in the
  following ways, as suggested by Robert Krug.

      o Some stale entries from the rewrite stack are no longer printed, in
      particular above [47mADD-POLYNOMIAL-INEQUALITIES[0m.

      o An additional rewrite stack entry is made when entering non-linear
      arithmetic (see [non-linear-arithmetic]).

      o An [47mADD-POLYNOMIAL-INEQUALITIES[0m entry is printed with a counter, to
      show how often this process is called.

  Modified [47m[save-exec][0m so that the newly-saved image will have the same
  raw Lisp package as the existing saved image.  This is a very
  technical change that will likely not impact most users; for
  example, the package in the ACL2 read-eval-print loop (see [lp])
  had already persisted from the original to newly-saved image.
  Thanks to Jared Davis for suggesting this change.

  Changed [47m[make-event][0m expansion so that changes to [47m[gag-mode][0m,
  [47m[set-print-clause-ids][0m, [47mset-fmt-soft-right-margin[0m, and
  [47mset-fmt-hard-right-margin[0m will persist after being evaluated during
  [47mmake-event[0m expansion.  (Specifically,
  [47m*protected-system-state-globals*[0m has been modified; see
  [make-event-details].)  Thanks to Jared Davis for bringing this
  issue to our attention.

  Output from the [proof-builder] is now always enabled when invoking
  [47m[verify][0m, even if it is globally inhibited (see
  [set-inhibit-output-lst]).

  Improved the message printed when an [47m:induct[0m hint fails, to give more
  information in some cases.  Thanks to Rex Page for suggesting where
  an improvement could be made and providing useful feedback on an
  initial improvement.

  Added a warning for [congruence] rules (see [defcong]) that specify
  [47m[iff][0m as the second equivalence relation when [47m[equal][0m can be used
  instead.  Those who heed these warnings can eliminate certain
  subsequent [47m[double-rewrite][0m warnings for [rewrite] rules with
  conclusions of the form [47m(iff term1 term2)[0m, and hence implicitly for
  Boolean conclusions [47mterm1[0m that are interpreted as [47m(iff term1 t)[0m.
  Thanks to Sarah Weissman for sending us an example that highlighted
  the need for such a warning.

  Modified macro [47m:[0m[47m[redef!][0m (which is for system implementors) so that
  it eliminates untouchables.

  Several improvements have been made to the experimental
  hons/memoization version of ACL2.  See [hons-and-memoization].

  The distributed books directory, [47m(@ distributed-books-dir)[0m, is now
  printed in the start-up message.")
 (NOTE-3-3{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.3(r) (November, 2007) Notes

  Please also see [note-3-3] for changes to Version 3.3 of ACL2.")
 (NOTE-3-4
  (RELEASE-NOTES)
  "ACL2 Version 3.4 (August, 2008) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 3.3 into changes
  to existing features, new features, bug fixes, new and updated
  books, and Emacs support.  Each change is described just once,
  though of course many changes could be placed in more than one
  category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  Fixed a long-standing potential infinite loop in the rewriter.
  Thanks to Sol Swords for sending a concise example illustrating the
  looping behavior.  (Those interested in details are welcome to look
  at the comment about loop behavior in source function
  [47mrewrite-equal[0m.)

  Incorporated a slight strengthening of non-linear arithmetic
  contributed by Robert Krug (thanks, Robert).  With non-linear
  arithmetic enabled, the problem was essentially that ACL2 made the
  following ``optimization'': given inequalities [47m(< a u)[0m and [47m(< b v)[0m,
  for positive rational constants [47ma[0m and [47mb[0m terms [47mu[0m and [47mv[0m of which at
  least one is known to be rational, infer [47m(< (* a b) (* u v))[0m.
  Without this optimization, however, ACL2 now infers the stronger
  inequality obtained by direct multiplication of the two given
  inequalities.  To see the effect of this change, submit the event
  [47m(set-non-linearp t)[0m followed by:

    (thm (implies (and (rationalp x) (< 3 x)
                       (rationalp y) (< 4 y))
                  (< 0 (+ 12 (* -4 x) (* -3 y) (* x y)))))

  The utility [47m[set-checkpoint-summary-limit][0m has been modified in
  several ways: it now takes a single argument (no longer takes
  [47m[state][0m as an argument); a natural number [47mn[0m abbreviates the pair [47m(n
  . n)[0m; the argument is no longer evaluated, but it still optionally
  may be quoted; and a new value, [47mt[0m, suppresses all printing of the
  checkpoint summary.  Thanks to Jared Davis for suggesting most of
  these improvements.

  There was formerly a restriction on [47m[mbe][0m that the [47m:exec[0m argument may
  not contain a call of [47m[mbe][0m.  This restriction has been removed,
  thanks to a request from Jared Davis and Sol Swords.  Thanks also
  to Sandip Ray, who pointed out that this restriction may have been
  in place in order that [47m[defexec][0m can guarantee termination using
  the [47m:exec[0m code; its [documentation] has therefore been updated to
  clarify this situation.

  Rules of class [47m:[0m[47m[rewrite][0m are now stored by performing certain
  logical simplifications on the left side of the conclusion: [47m(prog2$
  X Y)[0m is replaced by [47mY[0m, [47m(mbe :logic X :exec Y)[0m is replaced by [47mX[0m
  (more precisely, the analogous change is made to the generated call
  of [47m[must-be-equal][0m); and [47m(the TYPE X)[0m is replaced by [47mX[0m (again, the
  change is actually made on the macroexpanded form).  Thanks to
  Jared Davis and Sol Swords for requesting this change.  An
  analogous change has also been made for rules of class
  [47m:[0m[47m[forward-chaining][0m.

  The [47m[trace$][0m utility has been reimplemented to work independently of
  the underlying Lisp trace.  It thus works the same for every host
  Lisp, except as provided by an interface to the underlying host
  Lisp trace (the [47m:native[0m option).  Note that the host Lisp trace
  continues to be modified for GCL, Allegro CL, and CCL (OpenMCL);
  see [trace].  See [trace$] for updated detailed documentation on
  tracing options, many of which are new, for example an [47m:evisc-tuple[0m
  option that can be set to [47m:no-print[0m if you want the function traced
  without the usual entry and exit printing.  The previous [47m[trace$][0m
  had some issues, including the following, which have all been
  fixed.  Thanks to Peter Dillinger for assistance in determining
  desired functionality of the new [47m[trace$][0m and for helping to test
  it.

      Recursive calls were not always shown in the trace for two reasons.
      (1) Compiler inlining could prevent recursive calls from being
      shown in the trace, in particular in CCL (OpenMCL).  Thanks to
      Jared Davis and Warren Hunt for pointing out this issue and
      requesting a fix, and to Bob Boyer and Gary Byers for relevant
      helpful discussions.  (2) ACL2's algorithm for producing
      executable counterparts prevented tracing of recursive calls
      even after [47m(set-guard-checking :none)[0m.  Thanks to Peter
      Dillinger for requesting a fix.

      It was possible to exploit a bug in the interaction of multiple
      values and trace to prove a contradiction.  An example is in a
      comment in [47m(deflabel note-3-4 ...)[0m in the ACL2 source code.

      Certain large structures could cause expensive computations for
      printing even when a [47m:cond[0m condition was specified and
      evaluated to [47mnil[0m.

      [47m[Trace!][0m now suppresses printing of the event summary, and returns
      the value that would be returned (if there is an active trust
      tag) by the corresponding call of [47m[trace$][0m.

      Some bugs have been fixed in the underlying native trace installed by
      ACL2 for GCL, Allegro CL, and CCL (OpenMCL), including the
      following.  In GCL it had been impossible to use the variable
      [47mARGLIST[0m in a [47m:cond[0m expression.  In Allegro CL and CCL, a
      [47m[trace$][0m bug mishandled tracing non-ACL2 functions when
      directives such as [47m:entry[0m and [47m:exit[0m were supplied.  GCL trace
      now hides the world even when tracing non-ACL2 functions.
      Tracing in CCL no longer causes a Lisp error when untracing a
      traced function defined outside the ACL2 loop; for example
      [47m(trace$ len1)[0m followed by [47m(untrace$ len1)[0m no longer causes an
      error.

  The macro [47mwet[0m has been changed, for the better we think.  see [wet].

  The generation of goals for [forcing-round]s has been changed to
  avoid dropping assumptions formerly deemed ``irrelevant''.  (A
  simple example may be found in a comment in source function
  [47munencumber-assumption[0m, source file [47mprove.lisp[0m.)  Thanks to Jared
  Davis for sending us an example that led us to make this change.

  Modified the implementation of [47m[make-event][0m so that in the
  [certificate] of a book, [47m[local][0m events arising from [47m[make-event][0m
  forms are elided.  For example, if [47m(make-event <form>)[0m expands to
  [47m(local <expanded-form>)[0m, then where the latter had been stored in
  the certificate, now instead [47m(local (value-triple :ELIDED))[0m will be
  stored.  Thanks to Eric Smith for requesting this improvement.  He
  has reported that a preliminary version of this improvement shrunk
  a couple of his [47m.cert[0m files from perhaps 40MB each to about 140K
  each.

  Now, a [47m[table][0m event that sets the entire table, [47m(table tbl nil alist
  :clear)[0m, is redundant (see [redundant-events]) when the supplied
  [47malist[0m is equal to the current value of the table.  Thanks to Peter
  Dillinger for requesting this change.

  The event constructor [47m[progn!][0m now returns the value that is returned
  by evaluation of its final form if no error occurs, except that it
  still returns [47mnil[0m if that final evaluation leaves ACL2 in raw-mode.

  [47m:[0m[47m[Pso][0m and [47m:[0m[47m[psog][0m have been improved so that they show the key
  checkpoint summary at the end of a failed proof.  (For a discussion
  of key checkpoints, see [set-gag-mode].)  As a result, a call of
  [47m[set-checkpoint-summary-limit][0m now affects subsequent evaluation of
  [47m:[0m[47m[pso][0m and [47m:[0m[47m[psog][0m.  In particular, you no longer need to
  reconstruct a proof (by calling [47m[thm][0m or [47m[defthm][0m) in order to see
  key checkpoints that were omitted due to the limit; just call
  [47m[set-checkpoint-summary-limit][0m and then run [47m:pso[0m or [47m:psog[0m.

  The [proof-builder] behaves a little differently under [gag-mode].
  Now, proof-builder commands that call the theorem prover to create
  new proof-builder goals, such as [47mbash[0m and [47minduct[0m (see
  [proof-builder-commands]), will show key checkpoints when in
  [gag-mode].  As before, proof-builder commands [47mpso[0m and [47mpso![0m (and
  now, also [47mpsog[0m) --- see [pso], see [psog], and see [pso!] --- can
  then show the unedited proof log.  However, unlike proof attempts
  done in the ACL2 loop, such proof attempts will not show a summary
  of key checkpoints at the end, because from a prover perspective,
  all such goals were considered to be temporarily ``proved'' by
  giving them ``byes'', to be dispatched by later proof-builder
  commands.

  A little-known feature had been that a [measure] of [47m0[0m was treated as
  though no measure was given.  This has been changed so that now, a
  [measure] of [47mnil[0m is treated as though no measure was given.

  Expanded [47m*acl2-exports*[0m to include every documented symbol whose name
  starts with [47m\"SET-\"[0m.  Thanks to Jared Davis for remarking that
  [47m[set-debugger-enable][0m was omitted from [47m*acl2-exports*[0m, which led to
  this change.

  The [trace] mechanism has been improved so that the [47m:native[0m and
  [47m:multiplicity[0m options can be used together for Lisps that support
  the trace [47m:exit[0m keyword.  These Lisps include GCL and Allegro CL,
  whose native trace utilities have been modified for ACL2.  For SBCL
  and CCL (OpenMCL), which use the built-in Lisp mechanism for
  returning multiple values in ACL2 (see [mv]), the use of
  [47m:multiplicity[0m with [47m:native[0m remains unnecessary and will be ignored.
  In support of this change, the modification of native Allegro CL
  tracing for ACL2 was fixed to handle [47m:exit[0m forms correctly that
  involve [47m[mv][0m.

  [31;1mNEW FEATURES[0m

  The command [47m:[0m[47m[redef!][0m is just like [47m:[0m[47m[redef][0m, but prints a warning
  rather than doing a query.  The old version of [47m:redef![0m was for
  system hackers and has been renamed to [47m:[0m[47m[redef+][0m.

  Introduced a new utility for evaluating a function call using the
  so-called executable counterpart --- that is, executing the call in
  the logic rather than in raw Lisp.  See [ec-call].  Thanks to Sol
  Swords for requesting this utility and participating in its
  high-level design.

  See [print-gv] for a new utility that assists with debugging guard
  violations. Thanks to Jared Davis for requesting more tool
  assistance for debugging guard violations.

  Improved the guard violation error message to show the positions of
  the formals, following a suggestion of Peter Dillinger.

  Added new [47m[guard-debug][0m capability to assist in debugging failed
  attempts at [guard] verification.  See [guard-debug].  Thanks to
  Jared Davis for requesting a tool to assist in such debugging and
  to him, Robert Krug, and Sandip Ray for useful discussions.

  New utilities provide the formula to be proved by [47m[verify-guards][0m.
  See [verify-guards-formula] and see [guard-obligation], Thanks to
  Mark Reitblatt for making a request leading to these utilities.
  These utilities can be applied to a term, not just an event name;
  thanks to Peter Dillinger for correspondence that led to this
  extension.

  A new utility causes runes to be printed as lists in proof output
  from simplification, as is done already in proof summaries.  See
  [set-raw-proof-format].  Thanks to Jared Davis for requesting this
  utility.

  An experimental capability allows for parallel evaluation.  See
  [parallelism].  Thanks to David Rager for providing an initial
  implementation of this capability.

  Defined [47m[xor][0m in analogy to [47m[iff][0m.  Thanks to Bob Boyer, Warren Hunt,
  and Sol Swords for providing this definition.

  Improved distributed file [47mdoc/write-acl2-html.lisp[0m so that it can now
  be used to build HTML documentation files for [documentation]
  strings in user [books].  See the comment in the definition of
  macro [47macl2::write-html-file[0m at the end of that file.  Thanks to
  Dave Greve and John Powell for requesting this improvement.

  It is now possible to specify [47m:[0m[47m[hints][0m for non-recursive function
  definitions (which can be useful when definitions are automatically
  generated).  See [set-bogus-defun-hints-ok].  Thanks to Sol Swords
  for requesting such a capability.

  Keyword argument [47m:dir[0m is now supported for [47m[rebuild][0m just as it has
  been for [47m[ld][0m.

  We relaxed the criteria for functional substitutions, so that a
  function symbol can be bound to a macro symbol that corresponds to
  a function symbol in the sense of [47m[macro-aliases-table][0m.  So for
  example, a functional substitution can now contain the doublet [47m(f
  +)[0m, where previously it would have been required instead to contain
  [47m(f binary-+)[0m.

  We now allow arbitrary packages in raw mode (see [set-raw-mode]) ---
  thanks to Jared Davis for requesting this enhancement --- and more
  than that, we allow arbitrary Common Lisp in raw mode.  Note
  however that for arbitrary packages, you need to be in raw mode
  when the input is read, not just when the input form is evaluated.

  Two new keywords are supported by the [47m[with-output][0m macro.  A
  [47m:gag-mode[0m keyword argument suppresses some prover output as is done
  by [47m[set-gag-mode][0m.  Thanks to Jared Davis for asking for a
  convenient way to set [gag-mode] inside a book, in particular
  perhaps for a single theorem; this keyword provides that
  capability.  A [47m:stack[0m keyword allows sub-[events] of [47m[progn][0m or
  [47m[encapsulate][0m to ``pop'' the effect of a superior [47m[with-output][0m
  call.  Thanks to Peter Dillinger for requesting such a feature.
  See [with-output].

  The command [47m[good-bye][0m and its aliases [47m[exit][0m and [47m[quit][0m now all take
  an optional status argument, which provides the Unix exit status
  for the underlying process.  Thanks to Florian Haftmann for sending
  a query to the ACL2 email list that led to this enhancement.

  Keyword commands now work for macros whose argument lists have lambda
  list keywords.  For a macro with a [47mlambda[0m list keyword in its
  argument list, the corresponding keyword command reads only the
  minimum number of required arguments.  See [keyword-commands].

  It is now legal to [47m[declare][0m variables [47mignorable[0m in [47m[let*][0m forms, as
  in [47m(let* ((x (+ a b)) ...) (declare (ignorable x)) ...)[0m.  Thanks to
  Jared Davis for requesting this enhancement.

  Added a warning when more than one hint is supplied explicitly for
  the same goal.  It continues to be the case that only the first
  hint applicable to a given goal will be applied, as specified in
  the user-supplied list of [47m:hints[0m followed by the
  [47m[default-hints-table][0m.  Thanks to Mark Reitblatt for sending a
  question that led both to adding this clarification to the
  [documentation] and to adding this warning.

  You may now use [47m[set-non-linear][0m, [47m[set-let*-abstraction][0m,
  [47mset-tainted-ok[0m, and [47m[set-ld-skip-proofs][0m in place of their versions
  ending in ``[47mp[0m''.  Thanks to Jared Davis for suggesting
  consideration of such a change.  All ``[47mset-[0m'' utilities now have a
  version without the final ``[47mp[0m'' (and most do not have a version
  with the final ``[47mp[0m'').

  Added a \"Loop-Stopper\" warning when a [47m:[0m[47m[rewrite][0m rule is specified
  with a [47m:[0m[47m[loop-stopper][0m field that contains illegal entries that
  will be ignored.  Thanks to Jared Davis for recommending such a
  warning.

  Added a substantial documentation topic that provides a beginner's
  guide to the use of quantification with [47m[defun-sk][0m in ACL2.  Thanks
  to Sandip Ray for contributing this guide, to which we have made
  only very small modifications.  See [quantifier-tutorial].

  [47m[Defun-sk][0m now allows the keyword option [47m:strengthen t[0m, which will
  generate the extra constraint that is generated for the
  corresponding [47mdefchoose[0m event; see [defchoose].  Thanks to Dave
  Greve for suggesting this feature.

  [31;1mBUG FIXES[0m

  Fixed a soundness bug related to the use of [47m[mbe][0m inside
  [47m[encapsulate][0m events.  An example proof of [47mnil[0m (before the fix) is
  in a comment in [47m(deflabel note-3-4 ...)[0m in the ACL2 source code.
  We therefore no longer allow calls of [47m[mbe][0m inside [47m[encapsulate][0m
  events that have non-empty [signature]s.

  Fixed a bug related to the definition of a function supporting the
  macro [47m[value-triple][0m.  Although this bug was very unlikely to
  affect any user, it could be carefully exploited to make ACL2
  unsound:

    (defthm fact
      (equal (caadr (caddr (value-triple-fn '(foo 3) nil nil)))
             'value) ; but it's state-global-let* in the logic
      :rule-classes nil)
    (defthm contradiction
      nil
      :hints ((\"Goal\" :use fact :in-theory (disable (value-triple-fn))))
      :rule-classes nil)

  Non-[47m[local][0m definitions of functions or macros are no longer
  considered redundant with built-ins when the built-ins have special
  raw Lisp code, because ACL2 was unsound without this restriction!
  A comment about redundant definitions in source function
  [47mchk-acceptable-defuns[0m shows how one could prove [47mnil[0m without this
  new restriction.  Note that system utility [47m:[0m[47m[redef+][0m removes this
  restriction.

  Although ACL2 already prohibited the use of certain built-in
  [47m:[0m[47m[program][0m mode functions for [47m[verify-termination][0m and during
  macroexpansion, we have computed a much more complete list of
  functions that need such restrictions, the value of constant
  [47m*primitive-program-fns-with-raw-code*[0m.  [This constant was renamed
  [47m*initial-program-fns-with-raw-code*[0m after Version 8.0.]

  Modified what is printed when a proof fails, to indicate more clearly
  which event failed.

  Fixed a problem with [47m[dmr][0m in CCL (OpenMCL) that was causing a raw
  Lisp break after an interrupt in some cases.  Thanks to Gary Byers
  for a suggestion leading to this fix.

  Fixed bugs in [proof-builder] code for dealing with free variables in
  hypotheses.

  Upon an abort, the printing of [47m[pstack][0m and [gag-mode] summary
  information for other than GCL was avoided when inside a call of
  [47m[ld][0m.  This has been fixed.

  (Windows only) Fixed bugs for ACL2 built on SBCL on Windows,
  including one that prevented [47m[include-book][0m parameters [47m:dir :system[0m
  from working, and one that prevented certain compilation.  Thanks
  to Peter Dillinger for bringing these to our attention and
  supplying a fix for the second.  Thanks also to Andrew Gacek for
  bringing [47m[include-book][0m issues to our attention.  Also, fixed
  writing of file [47msaved_acl2[0m at build time so that for Windows,
  Unix-style pathnames are used.

  Fixed a hard Lisp error that could occur with keywords as [47m[table][0m
  names, e.g., [47m(table :a :a nil :put)[0m.  Thanks to Dave Greve for
  bringing this problem to our attention and providing this example.

  Fixed handling of [47m:OR[0m [hints] so that proof attempts under an [47m:OR[0m
  hint do not abort (reverting to induction on the original input
  conjecture) prematurely.  Thanks to Robert Krug for pointing out
  this problem and pointing to a possible initial fix.

  (SBCL and CLISP only) It is now possible to read symbols in the
  [47m\"COMMON-LISP\"[0m package inside the ACL2 command loop (see [lp]).
  This could cause a raw Lisp error in previous versions of ACL2
  whose host Common Lisp was SBCL or CLISP.  Thanks to Peter
  Dillinger for bringing this issue to our attention.

  Fixed a bug that was preventing certain [hints], such as [47m:do-not[0m
  hints, from being used after the application of an [47m:or[0m hint.
  Thanks to Robert Krug for bringing this bug to our attention.

  (Hons version only) Fixed a bug in the interaction of [47m[memoize][0m
  ([47m[hons][0m version only) with event processing, specifically in
  interaction with failures inside a call of [47m[progn][0m or
  [47m[encapsulate][0m.  Thanks to Jared Davis for bringing this bug to our
  attention and sending an example.  A simplified example may be
  found in a comment in source function [47mtable-cltl-cmd[0m, source file
  [47mhistory-management.lisp[0m; search for ``Version_3.3'' there.

  Fixed [47m[cw-gstack][0m so that its [47m:evisc-tuple[0m is applied to the top
  clause, instead of using [47m(4 5 nil nil)[0m in all cases.  If no
  [47m:evisc-tuple[0m is supplied then [47m(term-evisc-tuple t state)[0m is used
  for the top clause, as it is already used for the rest of the
  stack.

  Fixed a bug in the interaction of [proof-tree]s with [47m:induct[0m hint
  value [47m:otf-flg-override[0m.  Thanks to Peter Dillinger for reporting
  this bug and sending an example that evokes it.

  Fixed bugs in [47m:[0m[47m[pr][0m and [47m[find-rules-of-rune][0m for the case of rule
  class [47m:[0m[47m[elim][0m.  Thanks to Robert Krug and Jared Davis for bringing
  these related bugs to our attention.

  Improved failure messages so that the key checkpoints are printed
  only once when there is a proof failure.  Formerly, a proof failure
  would cause the key checkpoints to be printed for every
  [47m[encapsulate][0m or [47m[certify-book][0m superior to the proof attempt.

  Fixed a bug in generation of [guard]s for calls of [47m[pkg-witness][0m.
  Thanks to Mark Reitblatt for sending an example showing this bug.
  The bug can be in play when you see the message: ``HARD ACL2 ERROR
  in MAKE-LAMBDA-APPLICATION: Unexpected unbound vars (\"\")''.  A
  distillation of Mark's example that causes this hard error is as
  follows.

    (defun foo (x)
      (declare (xargs :guard t))
      (let ((y x)) (pkg-witness y)))

  The [47m[cond][0m macro now accepts test/value pairs of the form [47m(T val)[0m in
  other than the last position, such as the first such pair in [47m(cond
  (t 1) (nil 2) (t 3))[0m.  Thanks to Jared Davis for sending this
  example and pointing out that ACL2 was sometimes printing goals
  that have such a form, and hence cannot be submitted back to ACL2.
  A few macros corresponding to [47m[cond][0m in some books under [47mbooks/rtl[0m
  and [47mbooks/bdd[0m were similarly modified.  (A second change will
  probably not be noticeable, because it doesn't affect the final
  result: singleton [47m[cond][0m clauses now generate a call of [47m[or][0m in a
  single step of macroexpansion, not of [47m[if][0m.  For example, [47m(cond (a)
  (b x) (t y))[0m now expands to [47m(OR A (IF B X Y))[0m instead of [47m(IF A A
  (IF B X Y))[0m.  See the source code for [47mcond-macro[0m for a comment
  about this change.)

  Fixed a bug in the interaction of [proof-builder] command [47mDV[0m,
  including numeric (``diving'') commands, with the [47m[add-binop][0m
  event.  Specifically, if you executed [47m(add-binop mac fn)[0m with [47mfn[0m
  having arity other than 2, a [proof-builder] command such as 3 or
  [47m(dv 3)[0m at a call of [47mmac[0m could have the wrong effect.  We also fixed
  a bug in diving with [47mDV[0m into certain [47mAND[0m and [47mOR[0m calls.  Thanks to
  Mark Reitblatt for bringing these problems to our attention with
  helpful examples.

  Fixed a couple of bugs that were causing an error, ``HARD ACL2 ERROR
  in RENEW-NAME/OVERWRITE''.  Thanks to Sol Swords for bringing the
  first of these bugs to our attention.

  Fixed a bug that could cause [47m[certify-book][0m to fail in certain cases
  where there are [47m[local][0m [47m[make-event][0m forms.

  Fixed a bug in [47m[start-proof-tree][0m that could cause Lisp to hang or
  produce an error.  Thanks to Carl Eastlund for sending an example
  to bring this bug to our attention.

  Fixed a bug in the proof output, which was failing to report cases
  where the current goal simplifies to itself or to a set including
  itself (see [specious-simplification]).

  Fixed a bug in [47m[with-prover-time-limit][0m that was causing a raw Lisp
  error for a bad first argument.  Thanks to Peter Dillinger for
  pointing out this bug.

  The following was claimed in [47m:doc[0m [47m[note-3-3][0m, but was not fixed until
  the present release:
  Distributed directory [47mdoc/HTML/[0m now again includes installation
  instructions, in [47mdoc/HTML/installation/installation.html[0m.

  In certain Common Lisp implementations --- CCL (OpenMCL) and
  LispWorks, at least --- an interrupt could leave you in a break
  such that quitting the break would not show the usual summary of
  key checkpoints.  This has been fixed.

  [31;1mNEW AND UPDATED BOOKS[0m

  Updated [47mbooks/clause-processors/SULFA/[0m with a new version from Erik
  Reeber; thanks, Erik.

  Added new books directory [47mtools/[0m from Sol Swords.  See
  [47mbooks/tools/Readme.lsp[0m for a summary of what these books provide.

  The distributed book [47mbooks/misc/file-io.lisp[0m includes a new utility,
  [47mwrite-list![0m, which is like [47mwrite-list[0m except that it calls
  [47m[open-output-channel!][0m instead of [47m[open-output-channel][0m.  Thanks to
  Sandip Ray for requesting this utility and assisting with its
  implementation.

  Added [47mrecord-update[0m macro supplied by Sandip Ray to distributed book
  [47mbooks/misc/records.lisp[0m.

  Sandip Ray has contributed books that prove soundness and
  completeness of different proof strategies used in sequential
  program verification.  Distributed directory [47mbooks/proofstyles/[0m has
  three new directories comprising that contribution: [47msoundness/[0m,
  [47mcompleteness/[0m, and [47mcounterexamples/[0m.  The existing
  [47mbooks/proofstyles/[0m directory has been moved to its subdirectory
  [47minvclock/[0m.

  Jared Davis has contributed a profiling utility for ACL2 built on CCL
  (OpenMCL).  See [47mbooks/misc/oprof.lisp[0m.  Thanks, Jared.

  ACL2 utilities [47m[getprop][0m and [47m[putprop][0m take advantage of
  under-the-hood Lisp (hashed) property lists.  The new book
  [47mbooks/misc/getprop.lisp[0m contains an example showing how this works.

  Added the following new book directories: [47mbooks/paco/[0m, which includes
  a small ACL2-like prover; and [47mbooks/models/jvm/m5[0m, which contains
  the definition of one of the more elaborate JVM models, M5, along
  with other files including JVM program correctness proofs.  See
  files [47mReadme.lsp[0m in these directories, and file [47mREADME[0m in the
  latter.

  Added [3mbooks[0m about sorting in [47mbooks/sorting[0m.  See [47mReadme.lsp[0m in that
  directory for documentation.

  Added book [47mbooks/misc/computed-hint-rewrite.lisp[0m to provide an
  interface to the rewriter for use in computed hints.  Thanks to
  Jared Davis for requesting this feature.

  Jared Davis has provided a pseudorandom number generator, in
  [47mbooks/misc/random.lisp[0m.

  Robert Krug has contributed a new library, [47mbooks/arithmetic-4/[0m, for
  reasoning about arithmetic.  He characterizes it as being more
  powerful than its predecessor, [47mbooks/arithmetic-3/[0m, and without its
  predecessor's rewriting loops, but significantly slower than its
  predecessor on some theorems.

  Incorporated changes from Peter Dillinger to verify guards for
  functions in [47mbooks/ordinals/lexicographic-ordering.lisp[0m (and one in
  [47mordinal-definitions.lisp[0m in that directory).

  A new directory, [47mbooks/hacking/[0m, contains a library for those who
  wish to use trust tags to modify or extend core ACL2 behavior.
  Thanks to Peter Dillinger for contributing this library.  Obsolete
  version [47mbooks/misc/hacker.lisp[0m has been deleted.  Workshop
  contribution [47mbooks/workshops/2007/dillinger-et-al/code/[0m is still
  included with the workshops/ tar file, but should be considered
  deprecated.

  In [47mbooks/make-event/assert.lisp[0m, changed [47massert![0m and [47massert!-stobj[0m to
  return [47m(value-triple :success)[0m upon success instead of
  [47m(value-triple nil)[0m, following a suggestion from Jared Davis.

  [31;1mEMACS SUPPORT[0m

  Changed [47memacs/emacs-acl2.el[0m so that the fill column default (for the
  right margin) is only set (still to 79) in lisp-mode.

  Modified Emacs support in file [47memacs/emacs-acl2.el[0m so that names of
  events are highlighted just as [47m[defun][0m has been highlighted when it
  is called.  Search in the above file for [47mfont-lock-add-keywords[0m for
  instructions on how to eliminate this change.

  The name of the temporary file used by some Emacs utilities defined
  in file [47memacs/emacs-acl2.el[0m has been changed to have extension [47m.lsp[0m
  instead of [47m.lisp[0m; thus it is now [47mtemp-emacs-file.lsp[0m.  Also, `make'
  commands to `clean' books will delete such files (specifically,
  [47mbooks/Makefile-generic[0m has been changed to delete
  [47mtemp-emacs-file.lsp[0m).")
 (NOTE-3-4{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.4(r) (August, 2008) Notes

  Please also see [note-3-4] for changes to Version 3.4 of ACL2.

  Fixed makefiles, [47mbooks/nonstd/Makefile[0m and [47mGNUmakefile[0m.  The old
  set-up seemed to work fine as long as all books certified, but it
  was really broken, for example only certifying some of the books in
  [47mbooks/nonstd/nsa/[0m, and then only when required by books in other
  directories.  Also fixed the ``[47mclean[0m'' target to clean links rather
  than to make links.")
 (NOTE-3-5
  (RELEASE-NOTES)
  "ACL2 Version 3.5 (May, 2009) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 3.4 into the
  following categories: changes to existing features, new features,
  heuristic improvements, bug fixes, new and updated books, Emacs
  support, and experimental [47m[hons][0m version.  Each change is described
  in just one category, though of course many changes could be placed
  in more than one category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  Many improvements have been made to ACL2's ``evisceration'' mechanism
  for hiding substructures of objects before they are printed, and to
  related documentation:

      o A new documentation topic explains evisc-tuples.  See
      [evisc-tuple].

      o A new interface, [47m[set-evisc-tuple][0m, has been provided for setting
      the four global evisc-tuples.  See [set-evisc-tuple].

      o A new mode, ``iprinting'', allows eviscerated output to be read
      back in.  See [set-iprint].

      o Function [47mdefault-evisc-tuple[0m has been deprecated and will probably
      be eliminated in future releases; use [47mabbrev-evisc-tuple[0m
      instead.  Also eliminated is the brr-term-evisc-tuple (also the
      user-brr-term-evisc-tuple).  The term-evisc-tuple controls
      printing formerly controlled by the brr-term-evisc-tuple or
      user-brr-term-evisc-tuple.

      o ACL2 output is done in a more consistent manner, respecting the
      intention of those four global evisc-tuples.  In particular,
      more proof output is sensitive to the term-evisc-tuple.  Again,
      see [set-evisc-tuple].

      o A special value, [47m:DEFAULT[0m, may be provided to [47m[set-evisc-tuple][0m in
      order to restore these [evisc-tuple]s to their original
      settings.

      o (Details for heavy users of the evisc-tuple mechanism) (1) There
      are no longer [state] globals named [47muser-term-evisc-tuple[0m or
      [47muser-default-evisc-tuple[0m.  (2) Because of the above-mentioned
      [47m:DEFAULT[0m, if you have referenced state globals directly, you
      should use accessors instead, for example [47m(abbrev-evisc-tuple
      state)[0m instead of [47m(@ abbrev-evisc-tuple)[0m.  (3) For uniformity,
      [47m[set-trace-evisc-tuple][0m now takes a second argument, [47mstate[0m.

  Improved [47m[break-on-error][0m in several ways.  First, it breaks earlier
  in a more appropriate place.  Thanks to Dave Greve for highlighting
  this problem with the existing implementation.  Also,
  [47m[break-on-error][0m now breaks on hard errors, not only soft errors
  (see [er], options [47mhard[0m and [47mhard?[0m).  Thanks to Warren Hunt and Anna
  Slobodova for sending an example that showed a flaw in an initial
  improvement.  Finally, new options cause printing of the call stack
  for some host Common Lisps.  See [break-on-error].  Thanks to Bob
  Boyer for requesting this feature.

  [47m[Trace!][0m may now be used in raw Lisp (though please note that all
  soundness claims are off any time you evaluate forms in raw Lisp!).
  Thanks to Bob Boyer for feedback that led to this enhancement.

  ACL2 now searches for file [47macl2-customization.lsp[0m in addition to (and
  just before) its existing search for [47macl2-customization.lisp[0m; See
  [ACL2-customization].  Thanks to Jared Davis for suggesting this
  change, which supports the methodology that files with a [47m.lisp[0m
  extension are certifiable books (thus avoiding the need to set the
  [47mBOOKS[0m variable in makefiles; see [books-certification-classic]).

  Improved the error message for illegal [47m[declare][0m forms of the form
  [47m(type (satisfies ...))[0m.  Thanks to Dave Greve for sending an
  example highlighting the issue.

  If trace output is going to a file (because [47m[open-trace-file][0m has
  been executed), then a note will be printed to that effect at the
  time that a call of [47m[trace$][0m or [47m[trace!][0m is applied to one or more
  [trace] specs.

  The notion of redundancy (see [redundant-events]) has been made more
  restrictive for [47m[mutual-recursion][0m events.  Now, if either the old
  or new event is a [47m[mutual-recursion][0m event, then redundancy
  requires that both are [47m[mutual-recursion][0m events that define the
  same set of function symbols.  Although we are not aware of any
  soundness bugs fixed by this modification, nevertheless we believe
  that it reduces the risk of soundness bugs in the future.

  The definition of [47mtrace*[0m has been moved to a book, [47mmisc/trace1.lisp[0m.
  A new version, used in ACL2s, is in book [47mmisc/trace-star.lisp[0m.
  [Trace] utilities [47m[trace$][0m and [47m[trace!][0m are still built into ACL2.
  [Note: File [47mmisc/trace1.lisp[0m was deleted after Version 4.2.]

  Certain [certificate] files will now be much smaller, by printing in
  a way that takes advantage of structure sharing.  Certifying the
  following example produces a [47m.cert[0m file of over 3M before this
  change, but less than 1K after the change.

    (defun nest (i)
      ;; Makes an exponentially-sized nest of conses i deep.
      (if (zp i)
          nil
        (let ((next (nest (1- i))))
          (cons next next))))

    (make-event
     `(defconst *big* ',(nest 20)))

  Thanks to Sol Swords for providing the above example and to him as
  well as to Bob Boyer, Jared Davis, and Warren Hunt for encouraging
  development of this improvement.  We have also applied this
  improvement to the printing of function definitions to files on
  behalf of [47m[certify-book][0m and [47m[comp][0m.

  Names of symbols are now printed with vertical bars according to the
  Common Lisp spec.  Formerly, if the first character of a symbol
  name could be the first character of the print representation of a
  number, then the symbol was printed using vertical bars ([47m|..|[0m)
  around its name.  Now, a much more restrictive test for ``potential
  numbers'' is used, which can result in fewer such vertical bars.
  Base 16 is now carefully considered as well; see [set-print-base].
  Thanks to Bob Boyer for requesting this improvement.  Note that
  macros [47mset-acl2-print-base[0m and [47mset-acl2-print-case[0m have been
  replaced by functions; see [set-print-base] and see
  [set-print-case].

  The ACL2 reader now supports `[47m#.[0m' syntax in place of the `[47m#,[0m syntax
  formerly supported.  Thanks to Bob Boyer for requesting this
  change.  See [sharp-dot-reader].  NOTE that because of this change,
  `[47m#.[0m' no longer causes an abort; instead please use [47m(a!)[0m or
  optionally, if in the ACL2 loop, [47m:a![0m; see [a!].

  Some small changes have been made related to [gag-mode]:

      o [Gag-mode] now suppresses some messages that were being printed
      upon encountering disjunctive splits from [47m:OR[0m [hints].  Thanks
      to Sol Swords for suggesting this improvement.

      o ACL2 had printed ``[47mQ.E.D.[0m'' with all output suppressed and
      [47m[gag-mode][0m enabled.  Now, ``[47mQ.E.D.[0m'' will be suppressed when
      [47mPROVE[0m and [47mSUMMARY[0m output are suppressed, even if [47mgag-mode[0m is
      enabled.

      o The use of [47m[set-gag-mode][0m had drastic effects on the inhibited
      output (see [set-inhibit-output-lst]), basically inhibiting
      nearly all output (even most warnings) when turning on gag-mode
      and enabling all output except [47mproof-tree[0m output when turning
      off gag-mode.  Now, [47m[set-gag-mode][0m only inhibits or enables
      proof ([47mPROVE[0m) output, according to whether gag-mode is being
      turned on or off (respectively).  The related utility
      [47mset-saved-output[0m has also been modified, basically to eliminate
      [47m:all[0m as a first argument and to allow [47mt[0m and [47m:all[0m as second
      arguments, for inhibiting prover output or virtually all
      output, respectively (see set-saved-output).

  A [47m[defstub][0m event [signature] specifying output of the form [47m(mv ...)[0m
  now introduces a [47m:[0m[47m[type-prescription][0m rule asserting that the new
  function returns a [47m[true-listp][0m result.  Thanks to Bob Boyer for
  sending the following example, which motivated this change.

    (defstub census (*) => (mv * *))
    (defn foo (x)
      (mv-let (a1 a2)
              (census x)
              (list a1 a2)))

  Improved the efficiency of [47m[string-append][0m so that in raw Lisp, it
  calls [47m[concatenate][0m.  Thanks to Jared Davis for suggesting this
  change, including the use of [47m[mbe][0m.  A minor change was made to the
  definition of [47m[concatenate][0m to support this change, and the lemma
  [47mappend-to-nil[0m was added (see below).

  The checksum algorithm used for [certificate] files of [books] has
  been changed.  Thanks to Jared Davis for contributing the new code.
  This change will likely not be noticed unless one is using the
  experimental [47m[hons][0m version of ACL2, where it can greatly speed up
  book certification and inclusion because of function memoization
  (of source function [47mfchecksum-obj[0m).

  Fewer calls are made to the checksum algorithm on behalf of
  [47m[certify-book][0m and a few other operations.  Thanks to Jared Davis
  for providing data that helped lead us to these changes.

  Formatted printing directives [47m~p[0m, [47m~q[0m, [47m~P[0m, and [47m~Q[0m are deprecated,
  though still supported.  See [fmt].  Instead, please use [47m~x[0m, [47m~y[0m,
  [47m~X[0m, and [47m~Y[0m (respectively).  As a by-product, rule names in proof
  output are no longer hyphenated.

  A new keyword, [47m:multiplicity[0m, is available for tracing raw Lisp
  functions using the ACL2 [trace] utility.  See [trace$].

  Users may now control whether or not a slow array access results in a
  warning printed to the screen (which is the default, as before),
  and if so, whether or not the warning is followed by a break.  See
  [slow-array-warning].

  On linux-like systems (including Mac OS X and SunOS), [47m:[0m[47m[comp][0m will
  now write its temporary files into the [47m\"/tmp\"[0m directory, which is
  the value of [47m[state][0m global [47m'tmp-dir[0m.  You can change that
  directory with [47m(assign tmp-dir \"<your_temp_directory_path>\")[0m.

  The messages printed for uncertified books have been enhanced.
  Thanks to Jared Davis for requesting such an improvement.

  A function definition that would be redundant if in [47m:[0m[47m[logic][0m mode is
  now considered redundant even if it (the new definition) is in
  [47m:[0m[47m[program][0m mode.  That is, if a definition is ``downgraded'' from
  [47m:logic[0m to [47m:program[0m mode, the latter ([47m:program[0m mode) definition is
  considered redundant.  Previously, such redundancy was disallowed,
  but we have relaxed that restriction because of a scenario brought
  to our attention by Jared Davis: include a book with the [47m:logic[0m
  mode definition, and then include a book with the [47m:program[0m mode
  definition followed by [47m[verify-termination][0m.  Thanks, Jared.

  The ACL2 reader no longer accepts characters other than those
  recognized by [47m[standard-char-p][0m except for [47m#\\Tab[0m, [47m#\\Page[0m, and
  [47m#\\Rubout[0m (though it still accepts strings containing such
  characters).  As a result, no [47m[make-event][0m expansion is allowed to
  contain any such unacceptable character or string.  Thanks to Sol
  Swords for sending an example that led us to make this restriction.
  A simple example is the following book:

    (in-package \"ACL2\")
    (defconst *my-null* (code-char 0))
    (make-event `(defconst *new-null* ,*my-null*))

  For this book, a call of [47m[certify-book][0m formerly broke during the
  compilation phase, but if there was no compilation, then a call of
  [47m[include-book][0m broke.  Now, the error occurs upon evaluation of the
  [47m[make-event][0m form.

  ACL2 now collects up [guard]s from [47m[declare][0m forms more as a user
  might expect, without introducing an unexpected ordering of
  conjuncts.  We thank Jared Davis for sending us the following
  illustrative example, explained below.

    (defun f (x n)
      (declare (xargs :guard (and (stringp x)
                                  (natp n)
                                  (= (length x) n)))
               (type string x)
               (ignore x n))
      t)

  Formerly, a guard was generated for this example by unioning the
  conjuncts from the [47m:guard[0m onto a list containing the term [47m(string
  x)[0m generated from the [47mtype[0m declaration, resulting in an effective
  guard of:

    (and (natp n)
         (= (length x) n)
         (stringp x))

  The guard of this guard failed to be verified because [47m(stringp x))[0m
  now comes after the call [47m(length x)[0m.  With the fix, contributions
  to the guards are collected up in the order in which they appear.
  So in the above example, the effective guard is the specified
  [47m:guard[0m; the contribution [47m(stringp x)[0m comes later, and is thus
  dropped since it is redundant.  NOTE by the way that if [47m:guard[0m and
  [47m:stobjs[0m are specified in the same [47m[xargs][0m form, then for purposes
  of collecting up the effective guard as described above, [47m:stobjs[0m
  will be treated as though it comes before the [47m:guard[0m.

  Modified [47m[close-output-channel][0m to try to do a better job flushing
  buffers.  Thanks to Bob Boyer for helpful correspondence.

  The notion of ``subversive recursion'' has been modified so that some
  functions are no longer marked as subversive.  See
  [subversive-recursions], in particular the discussion elaborating
  on the notion of ``involved in the termination argument'' at the
  end of that [documentation] topic.

  Formerly, [47m:[0m[47m[type-prescription][0m rules for new definitions inside
  [47m[encapsulate][0m forms were sometimes added as [constraint]s.  This is
  no longer the case.  See also discussion of the ``soundness bug in
  the forming of constraints'', which is related.

  [31;1mNEW FEATURES[0m

  It is now possible to affect ACL2's termination analysis (and
  resulting induction analysis).  Thanks to Peter Dillinger for
  requesting this feature.  The default behavior is essentially
  unchanged.  But for example, the following definition is accepted
  by ACL2 because of the use of the new [47m:ruler-extenders[0m features;
  See [ruler-extenders].

    (defun f (x)
      (declare (xargs :ruler-extenders :all))
      (cons 3
            (if (consp x)
                (f (cdr x))
              nil)))

  The following lemma was added in support of the improvement to
  [47m[string-append][0m described above:

    (defthm append-to-nil
      (implies (true-listp x)
               (equal (append x nil)
                      x)))

  A mechanism has been provided for users to contribute documentation.
  See [managing-ACL2-packages] for an example, which contains a link
  to an external web page on effective use of ACL2 packages, kindly
  provided by Jared Davis.  ACL2 [documentation] strings may now link
  to external web pages using the new symbol, [47m~url[0m; see markup.  Of
  course, those links appear in the web version of the documentation,
  but you made need to take a bit of action in order for these to
  appear as links in the Emacs Info version; see [documentation].

  Added [47m[intersectp][0m (similar to [47m[intersectp-eq][0m and
  [47m[intersectp-equal][0m).

  The user now has more control over how ACL2 prints forms; See
  [print-control].  Thanks to Bob Boyer for useful discussions
  leading to this enhancement.

  Some Common Lisp implementations only allow the syntax
  [47mpkg-name::expression[0m when [47mexpression[0m is a symbol.  The ACL2 reader
  has been modified to support a package prefix for arbitrary
  expressions; see [sharp-bang-reader].  Thanks to Hanbing Liu for a
  query that led to this feature and to Pascal J. Bourguignon for
  suggesting an implementation.

  Ill-formed [documentation] strings need not cause an error.  See
  [47mset-ignore-doc-string-error[0m.  Thanks to Bob Boyer for requesting
  this feature.

  Type declarations are now permitted in [47mlet*[0m forms; see [let*], see
  [declare], and see [type-spec].

  (For Lisp programmers) Macro [47mwith-live-state[0m has been provided for
  programmers who refer to free variable [47mSTATE[0m, for example with
  macros that generate uses of [47mSTATE[0m, and want to avoid compiler
  warnings when evaluating in raw Lisp.  For example, the following
  form can be submitted either inside or outside the ACL2 loop to get
  the desired effect (see [47mdoc-string[0m): [47m(with-live-state (f-put-global
  'doc-prefix \" \" state))[0m.  For another example use of this macro,
  see the definition of [47mtrace$[0m (ACL2 source file [47mother-events.lisp[0m).

  (System hackers only) Added [47m:[0m[47m[redef-][0m to undo the effect of
  [47m:[0m[47m[redef+][0m.  See [redef-].

  Function [47m[random$][0m is a built-in random number generator.  See
  [random$].  Thanks to Sol Swords for requesting this feature and
  providing an initial implementation.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  Sped up [guard] generation for some functions with large if-then-else
  structures in their bodies.  Thanks to Sol Swords for sending an
  illustrative example.

  Sped up [guard] generation in some cases by evaluating ground
  (variable-free) subexpressions.  Thanks to Bob Boyer for sending a
  motivating example: [47m(defn foo (x) (case x ((1 2) 1) ((3 4) 3) ...
  ((999 1000) 999)))[0m.

  Modified slightly a heuristic association of ``size'' with constants,
  which can result in significant speed-ups in proofs involving
  constants that are very large [47mcons[0m trees.

  Added a restriction in the linear arithmetic procedure for deleting
  polynomial inequalities from the linear database.  Formerly, an
  inequality could be deleted if it was implied by another
  inequality.  Now, such deletion requires that certain heuristic
  ``parent tree'' information is at least as restrictive for the
  weaker inequality as for the stronger.  Thanks to Dave Greve for
  bringing a relevant example to our attention and working with us to
  figure out some surprising behavior, and to Robert Krug for making
  a key observation leading to the fix.

  (GCL especially) Improved compiled code slightly by communicating to
  raw Lisp the output type when a function body is of the form [47m(the
  character ...)[0m.  This tiny improvement will probably only be
  observed in GCL, if at all.

  Applied a correction suggested by Robert Krug to the variant of
  [47m[term-order][0m used in parts of ACL2's arithmetic reasoning.

  [31;1mBUG FIXES[0m

  Fixed bugs in the handling of [47m[flet][0m expressions, one of which had
  the capability of rendering ACL2 unsound.  Thanks to Sol Swords for
  pointing out two issues and sending examples.  One example
  illustrated how ACL2 was in essence throwing away outer [47m[flet][0m
  bindings when processing an inner [47mflet[0m.  We have exploited that
  example to prove a contradiction, as follows: this book was
  certifiable before this fix.

    (in-package \"ACL2\")

    (defun a (x)
      (list 'c x))

    ; Example from Sol Swords, which failed to be admitted (claiming that
    ; function A is undefined) without the above definition of A.
    (defun foo1 (x y)
       (flet ((a (x) (list 'a x)))
         (flet ((b (y) (list 'b y)))
           (b (a (list x y))))))

    (defthm not-true
      (equal (foo1 3 4)
             '(b (c (3 4))))
      :hints ((\"Goal\"
               :in-theory
               (disable (:executable-counterpart foo1))))
      :rule-classes nil)

    (defthm contradiction
      nil
      :hints ((\"Goal\" :use not-true))
      :rule-classes nil)

  Sol's second example, below, pointed to a second bug related to
  computing output signatures in the presence of nested [47mflet[0m
  expressions, which we have also fixed: this form failed before the
  fix.

    :trans (flet ((foo (a) (list (flet ((bar (b) b)) a)))) x)

  Fixed a subtle soundness bug in the forming of constraints from
  deduced type prescriptions.  As a result, when ACL2 prints a
  warning message labeling encapsulated functions as ``subversive'',
  ACL2 will no longer deduce [47m:[0m[47m[type-prescription][0m rules for those
  functions.  Examples that exploit the bug in ACL2 Version_3.4 may
  be found in comments in ACL2 source function
  [47mconvert-type-set-to-term[0m (file [47mother-processes.lisp[0m) and especially
  in function [47mputprop-type-prescription-lst[0m (file [47mdefuns.lisp[0m).  For
  more on the general issue of ``subversive recursions,'' see
  [subversive-recursions].)

  Fixed a soundness bug in the handling of inequalities by the
  [type-set] mechanism, which was using the inequality database
  inside the body of a [47m[lambda][0m.

  Fixed a long-standing soundness bug in [47m[compress1][0m and [47m[compress2][0m,
  whose raw Lisp code gave the logically incorrect result in the case
  of a single entry other than the [47m[header][0m, where that entry mapped
  an index to the [47m[default][0m value.  Also fixed soundness bugs in
  [47m[compress1][0m, in the case of [47m:order >[0m, where the raw Lisp code could
  drop the [47m[header][0m from the result or, when the input alist had
  entries in ascending order, fail to return an alist in descending
  order.  For example, the following book certified successfully.

    (in-package \"ACL2\")
    (defthm true-formula-1
      (equal (compress1 'a '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5
                                      :DEFAULT 1 :NAME A :ORDER <)
                             (1 . 1)))
             '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5
                        :DEFAULT 1 :NAME A :ORDER <)))
      :hints ((\"Goal\" :in-theory (disable (compress1))))
      :rule-classes nil)
    (defthm ouch-1
      nil
      :hints ((\"Goal\" :use true-formula-1))
      :rule-classes nil)
    (defthm true-formula-2
      (equal (compress1 'a '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5
                                      :DEFAULT NIL :NAME A :ORDER >)
                             (1 . 1)
                             (2 . 2)))
             '((:HEADER :DIMENSIONS (4) :MAXIMUM-LENGTH 5
                        :DEFAULT NIL :NAME A :ORDER >)
               (2 . 2)
               (1 . 1)))
      :hints ((\"Goal\" :in-theory (disable (compress1))))
      :rule-classes nil)
    (defthm ouch-2
      nil
      :hints ((\"Goal\" :use true-formula-2))
      :rule-classes nil)
    (defthm true-formula-3
      (equal (compress1 'a '((:HEADER :DIMENSIONS (3) :MAXIMUM-LENGTH 4
                                      :NAME A :ORDER >)
                             (1 . B)
                             (0 . A)))
             '((:HEADER :DIMENSIONS (3) :MAXIMUM-LENGTH 4
                        :NAME A :ORDER >)
               (1 . B)
               (0 . A)))
      :hints ((\"Goal\" :in-theory (disable (compress1))))
      :rule-classes nil)
    (defthm ouch-3
      nil
      :hints ((\"Goal\" :use true-formula-3))
      :rule-classes nil)

  Fixed a soundness bug involving measured subsets and
  [47m[verify-termination][0m, by changing [47m[verify-termination][0m so that it
  uses [47m[make-event][0m.  See [verify-termination], in particular the
  discussion about [47m[make-event][0m near the end of that [documentation]
  topic.  Peter Dillinger first raised the idea to us of making such
  a change; when we found this soundness bug, we were certainly happy
  to do so!

  Fixed a bug that could cause a hard Lisp error but not, apparently,
  unsoundness.  The bug was in the lack of attention to the order of
  guard and type declarations when checking for redundancy.  In the
  following example, the second definition was redundant during the
  first pass of the [47m[encapsulate][0m form.  The second definition,
  however, was stored on the second pass with a guard of [47m(and (consp
  (car x)) (consp x))[0m, which caused a hard Lisp error when evaluating
  [47m(foo 3)[0m due to a misguided attempt to evaluate [47m(car 3)[0m in raw Lisp.
  The fix is to restrict redundancy of definitions so that the guard
  and type declarations must be in the same order for the two
  definitions.

    (encapsulate
     ()
     (local (defun foo (x)
              (declare (xargs :guard (consp x)))
              (declare (xargs :guard (consp (car x))))
              x))
     (defun foo (x)
       (declare (xargs :guard (consp (car x))))
       (declare (xargs :guard (consp x)))
       x))
    ; Now we get a hard Lisp error from evaluation of the guard of foo:
    (foo 3)

  Fixed a bug in the guard violation report for function
  [47m[intern-in-package-of-symbol][0m.  Thanks to Dave Greve for bringing
  this bug to our attention.

  Made a change to allow certain [hints], in particular certain
  [47m:[0m[47m[clause-processor][0m hints, that had previously caused errors during
  termination proofs by viewing the function being defined as not yet
  existing.  Thanks to Sol Swords for bringing this issue to our
  attention with a nice example.

  ACL2 now properly handles interrupts (via control-c) issued during
  printing of the checkpoint summary.  Previously it was possible on
  some platforms to make ACL2 hang when interrupting both during a
  proof and during the ensuing printing of the checkpoint summary.
  Thanks to Jared Davis and Sol Swords for bringing this problem to
  our attention.

  Fixed a bug that was preventing, inside some book [47m\"b\"[0m, the use of a
  [47m:dir[0m argument to [47m[include-book][0m that refers to a directory defined
  using [47m[add-include-book-dir][0m earlier in the book [47m\"b\"[0m.  (We found
  this ourselves, but we thank John Cowles for observing it
  independently and sending us a nice example.)

  (GCL and CCL only) Fixed a bug in certain under-the-hood type
  inferencing.  Thanks to Sol Swords for sending an example using
  [stobj]s defined with the [47m:inline[0m keyword, along with a helpful
  backtrace in CCL, and to Gary Byers for his debugging help.

  Fixed a bug in [47m[print-gv][0m, which was mishandling calls of functions
  with more than one argument.

  Fixed a bug in the handling of [47m[and][0m and [47m[or][0m terms by the
  [proof-builder] command [47mDV[0m, including numeric (``diving'')
  commands.  Thanks for Mark Reitblatt for bringing this problems to
  our attention with a helpful example.

  Fixed printing of goal names resulting from the application of [47m:OR[0m
  [hints] so that they aren't ugly when working in other than the
  [47m\"ACL2\"[0m package.  Thanks to Sol Swords for bringing this issue to
  our attention.

  Fixed [proof-tree] printing so that interrupts will not cause
  problems with hiding ordinary output because of incomplete
  proof-tree output.  Thanks to Peter Dillinger for pointing out this
  issue.

  Fixed a hard error that could be caused by mishandling a [47m[force][0md
  hypothesis during [forward-chaining].  Thanks to Peter Dillinger
  for bringing this bug to our attention by sending a useful example.

  Fixed a bug that could cause simplifications to fail because of
  alleged ``specious simplification.'' This bug could appear when
  deriving an equality from the linear arithmetic database, and then
  attempting to add this equality to the current goal's hypotheses
  when it was already present.  Thanks to Eric Smith for sending a
  helpful example (in July 2005!) that helped us debug this issue.

  Fixed a bug in processing of [47m:[0m[47m[type-set-inverter][0m rules.

  Fixed a bug that was causing an error, at least for an underlying
  Lisp of CCL (OpenMCL), when [47m[ec-call][0m was applied to a term
  returning multiple values.  Thanks to Sol Swords for sending an
  example that brought this bug to our attention.

  Fixed handling of array orders to treat keyword value [47m:order :none[0m
  correctly from an array's [47m[header][0m.  Previously, there were two
  problems.  One problem was that [47m:order :none[0m was treated like the
  default for [47m:order[0m, [47m<[0m, while [47m:order nil[0m was treated in the manner
  specified by [47m:order :none[0m (see [arrays]).  Now, both [47m:order :none[0m
  and [47m:order nil[0m are treated as [47m:order nil[0m had been treated, i.e., so
  that there is no reordering of the alist by [47m[compress1][0m.  The other
  problem with this case of [47m:order[0m was that the [47m:maximum-length[0m field
  of the [47m[header][0m was not being respected: the length could grow
  without bound.  Now, as previously explained (but not previously
  implemented) --- see [arrays] --- a [47m[compress1][0m call made on behalf
  of [47maset1[0m causes a hard error if the header of the supplied array
  specifies an [47m:order[0m of [47m:none[0m or [47mnil[0m.

  An [47mignorable[0m [47m[declare][0m form had caused an error in some contexts when
  it should have been allowed.  In particular, this problem could
  arise when using an [47mignorable[0m declaration at the top level in a
  [47m[defabbrev][0m form.  It could also arise upon calling
  [47m[verify-termination][0m when the corresponding [47m[defun][0m form contained
  an [47mignorable[0m declaration at the top level.  These bugs have been
  fixed.

  Contrary to existing documentation (see [make-event-details]), the
  value of ``[47m[ld][0m special variable'' [47m[ld-skip-proofsp][0m was always set
  to [47mnil[0m during [47m[make-event][0m expansion, not merely when the
  [47mmake-event[0m form has a non-[47mnil[0m value for keyword parameter
  [47m:check-expansion[0m.  This has been fixed.  Thanks to Sol Swords for
  bringing this issue to our attention.

  We have disallowed the certification of a book when not at the
  top-level, either directly in the top-level loop or at the top
  level of [47m[ld][0m.  Before this restriction, the following would
  certify a book with a definition such as [47m(defun foo (x) (h x))[0m that
  calls function [47mh[0m before defining it, if the certification was by
  way of the form such as:

    (er-progn (defun h (x) x) (certify-book \"my-book\"))

  But a subsequent [47m[include-book][0m of [47m\"my-book\"[0m would then fail, because
  [47mh[0m is not defined at the top level.

  Printing with [47m[fmt][0m directive [47m~c[0m now works properly even when the
  print-base is other than 10.  Thanks to Sol Swords for reporting
  this bug and providing a fix for it.

  (SBCL, CMUCL, and CCL only) Fixed a bug in [47m[sys-call-status][0m in the
  case that the underlying Common Lisp is SBCL, CMUCL, or CCL
  (OpenMCL).  Thanks to Jun Sawada for bringing this bug to our
  attention and providing a fix.

  Fixed a bug that was preventing [47m[local][0m [47m[defstobj][0m events in
  [47m[encapsulate][0m events.  Thanks to Jared Davis for bringing this bug
  to our attention.

  Fixed a bug evidenced by error message ``Unexpected form in
  certification world'', which could result from attempting to
  certify a book after evaluating an [47m[encapsulate][0m form with a local
  [47m[defmacro][0m.  Thanks to Jared Davis for pointing out this bug and
  sending the example:

    (encapsulate
     ()
     (local (defmacro foo (x) `(table foo 'bar ,x)))
     (local (foo 3)))

  Formerly, evaluating a [47m[trace$][0m form inside a [wormhole] such as the
  [break-rewrite] loop could leave the user in a bad state after
  returning to the top level, in which that function could not be
  untraced.  This has been fixed.  Note however that when you proceed
  from a break in the [break-rewrite] loop, the tracing state will be
  the same as it was when you entered that break: all effects of
  calling [47m[trace$][0m and [47m[untrace$][0m are erased when you proceed from
  the break.

  A [47m:[0m[47m[guard][0m of [47m(and)[0m is no longer ignored.  Thanks to Sol Swords for
  bringing this bug to our attention.

  A bug has been fixed that could result in needlessly weak induction
  schemes in the case that a recursive call is made in the first
  argument of [47m[prog2$][0m.  This has been fixed by including [47m[prog2$][0m as
  a default ruler-extender in the new ruler-extenders feature (see
  above, and see [ruler-extenders]).  For details on this bug see
  Example 11 in distributed book
  [47mbooks/misc/misc2/ruler-extenders-tests.lisp[0m.

  (For CCL/OpenMCL on Windows) ACL2 should now build on CCL (OpenMCL)
  on Windows.  Thanks to David Rager for bringing this issue to our
  attention and helping with a fix that worked for CCL 1.2, and to
  the CCL team for improving handling of Windows-style filenames in
  CCL 1.3.

  [31;1mNEW AND UPDATED BOOKS[0m

  See {ReleaseVersionNumbers |
  https://code.google.com/p/acl2-books/wiki/ReleaseVersionNumbers}
  for a list of books in Version 3.5 of ACL2 but not Version 3.4.

  Run the shell command

     [47msvn log -r 94:HEAD[0m

  to see all changes to [47mbooks/[0m since the release of Version 3.4.

  Here are just a few highlights.

  Thanks largely to Jared Davis, many [47mMakefile[0ms have been improved to
  do automatic dependency analysis.  See
  [books-certification-classic] for how to get your own [47mMakefile[0ms to
  do this by adding a line: [47m-include Makefile-deps[0m.

  Libraries [47mbooks/arithmetic-4/[0m and [47mbooks/rtl/rel7/[0m have been
  eliminated from the default book certification ([47mmake regression[0m),
  in favor of new libraries [47mbooks/arithmetic-5/[0m and [47mbooks/rtl/rel8/[0m
  contributed by Robert Krug and Hanbing Liu, respectively.  They and
  Jun Sawada have arranged the compatibility of these libraries;
  i.e., it is possible to evaluate both of the following in the same
  session:

    (include-book \"arithmetic-5/top\" :dir :system)
    (include-book \"rtl/rel8/lib/top\" :dir :system)

  Library [47mbooks/rtl/rel1/[0m is no longer certified by default (though it
  is still distributed in support of ACL2(r); see [real]).

  [31;1mEMACS SUPPORT[0m

  Slightly modified [47mControl-t e[0m (defined in [47memacs/emacs-acl2.el[0m) to
  comprehend the notion of an ``ACL2 scope'', and added [47mControl-t o[0m
  to insert a superior [47m[encapsulate][0m defining such a scope.  See the
  Emacs documentation for [47mControl-t e[0m (generally obtained after
  typing [47mControl-h k[0m).

  Modified distributed file [47memacs/emacs-acl2.el[0m so that if you put the
  following two forms in your [47m~/.emacs[0m file above the form that loads
  [47memacs/emacs-acl2.el[0m, then Emacs will not start up a shell.  Thanks
  to Terry Parks for leading us to this modification.

    (defvar acl2-skip-shell nil)
    (setq acl2-skip-shell t)

  [31;1mEXPERIMENTAL HONS VERSION[0m

  Bob Boyer and others have contributed numerous changes for the
  experimental ``[47mhons[0m'' version of ACL2 (see [hons-and-memoization]).

  The ACL2 [47m[state][0m can now be queried with [47mhons-enabledp[0m so that a
  result of [47mt[0m says that one is in the experimental [47mhons[0m version,
  while [47mnil[0m says the opposite.")
 (NOTE-3-5{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.5(r) (May, 2009) Notes

  Please also see [note-3-5] for changes in Version 3.5 of ACL2.

  This release incorporates improvements from Ruben Gamboa in support
  for non-standard analysis in ACL2(r), in the following ways:

  ACL2(r) now supports non-classical objects that are not also numeric,
  e.g., non-classical cons pairs.  Consequently, the built-in
  [47mstandard-numberp[0m has been replaced with [47m[standardp][0m.

  If [47mf[0m is a classical function, the value [47m(f x1 ... xn)[0m is guaranteed
  to be standard when the [47mxi[0m are standard.  ACL2(r) can now recognize
  this fact automatically, using [47mdefun-std[0m.  For example, the
  following can be used to assert that the square root of 2 is a
  standard value.

    (defthm-std sqrt-2-rational
      (standardp (acl2-sqrt 2)))

  More generally, the expression [47m(f x1 ... xn)[0m can contain free
  variables, but the result is guaranteed to be standard when the
  variables take on standard variables, as in the following:

    (defthm-std sqrt-x-rational
      (implies (standardp x)
               (standardp (acl2-sqrt x))))

  A potential soundness bug in [47m[encapsulate][0m was fixed.  Specifically,
  when a classical, constrained function is instantiated with a
  lambda expression containing free variables, it may produce
  non-standard values depending on the values of the free variables.
  This means that the functional instantiation cannot be used to
  justify a non-classical theorem.  For example, consider the
  following sequence:

    (encapsulate
      ((f (x) t))
      (local (defun f (x) x)))
    (defthm-std f-x-standard
      (implies (standardp x)
               (standardp (f x))))
    (defthm plus-x-standard
      (implies (standardp x)
               (standardp (+ x y)))
      :hints ((\"Goal\"
               :use ((:functional-instance f-x-standard
                                           (f (lambda (x) (+ x y))))))))
    (defthm plus-x-eps-not-standard
      (implies (standardp x)
               (not (standardp (+ x (/ (i-large-integer)))))))
    (defthm nil-iff-t
      nil
      :hints ((\"Goal\"
              :use ((:instance plus-x-standard
                               (y (/ (i-large-integer))))
                    (:instance plus-x-eps-not-standard)))))

  ACL2(r) also supports the introduction of non-classical functions
  with [47m[defchoose][0m.  These behave just as normal functions introduced
  with [47m[defchoose][0m, but they have a non-classical choice property.

  Finally, ACL2(r) now comes with a revamped library supporting
  non-standard analysis, still distributed separately as
  [47mbooks/nonstd/[0m.  The new library uses [47m[defchoose][0m to state more
  natural and useful versions of the IVT, MVT, etc.  It also supports
  the introduction of inverse functions, e.g., logarithms.  Finally,
  the library has much more extensive support for differentiation.")
 (NOTE-3-6
  (RELEASE-NOTES)
  "ACL2 Version 3.6 (August, 2009) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 3.5 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, distributed books, Emacs
  support, and experimental [hons-and-memoization] version.  Each
  change is described in just one category, though of course many
  changes could be placed in more than one category.

  Note that (starting with ACL2 Version 3.5) LispWorks is no longer
  supported as a platform for ACL2, as the LispWorks compiler could
  not handle the ACL2 sources; see comments in the ACL2 sources about
  ``function size'' being ``too large''.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  In the [47m[xargs][0m [47m[declare][0m form, the function symbol (or symbols,
  plural, in the case of [47m[mutual-recursion][0m) being defined may now be
  used in the specified [47m:measure[0m and [47m:[0m[47m[guard][0m terms.  Note that, the
  definition(s) of the new symbol(s) are still not used in the
  termination proof.  Thanks to Daron Vroon for discussions leading
  to this addition for the measure and to Dave Greve for requesting
  such an enhancement for the guard.

  Processing of the [47m:guard-hints[0m in an [47m[xargs][0m [47m[declare][0m form is now
  delayed until the start of [guard] verification.  As a result, the
  function symbol(s) being defined may now be used as one might
  expect in such hints, for example in an [47m:in-theory[0m form.  Thanks to
  Jared Davis for suggesting that we make such an improvement and
  providing an example.

  Made a low-level change to [47m[make-event][0m in support of the ACL2s
  utility ``[47mdynamic-make-event[0m''.  Thanks to Peter Dillinger for
  explaining the issue leading to this change.

  Modified the failure message printed when a measure conjecture fails
  to be proved, to indicate whether or not the hint [47m:ruler-extenders
  :all[0m would create a different measure conjecture.  Thanks to Peter
  Dillinger for suggesting such a modification.

  A call of [47m[add-default-hints][0m had added hints to the end of the
  current list of default hints.  Now, it adds them to the beginning
  of that list, so that they are tried first.  However,
  [47m[add-default-hints][0m now takes a keyword argument, [47m:at-end[0m.  If that
  argument is supplied and evaluates to other than [47mnil[0m, then the
  previous behavior occurs.

  When [47m[save-exec][0m is used to save ACL2 images, the build dates are now
  printed on separate lines at startup and in the executable script.
  Thanks To Bob Boyer for requesting some newlines.

  [47m[Forward-chaining][0m rules are now generated so that every [47m[let][0m (also
  [47m[let*][0m and [47m[lambda][0m) expression is expanded away, as is every call
  of a so-called ``guard holder'' ([47m[must-be-equal][0m, [47m[prog2$][0m,
  [47m[ec-call][0m, [47m[the][0m).  These were formerly only expanded away in the
  conclusion.  Thanks to Konrad Slind for a helpful email leading to
  this change.

  [47m[Current-theory][0m now causes a hard error when applied to a name not
  found in the current ACL2 logical [world], rather than simply
  returning [47mnil[0m.

  When the underlying Common Lisp is GCL, ACL2 no longer uses the [47m#n=[0m
  reader macro when writing out certain files, including
  [certificate] files.  In all other Lisps, it now uses the [47m#n=[0m
  ``print-circle'' feature not only for [certificate] files and
  ``[47mexpansion.lsp[0m'' files written for example in support of
  [47m[make-event][0m, but also for files written in support of [47m:[0m[47m[comp][0m.
  This is all managed with new [state] global variable
  [47mprint-circle-files[0m; see [print-control].  Thanks to Dave Greve for
  pointing out that GCL is limited by default to 1024 indices for
  [47m#n=[0m.

  [31;1mNEW FEATURES[0m

  A documentation topic explains in some detail how [hints] work with
  the ACL2 proof ``waterfall'': see [hints-and-the-waterfall].  This
  topic may be useful to those who write computed hints (see
  [computed-hints]) or other advanced hints.

  Added a new hint keyword, [47m:no-thanks[0m, that avoids printing the usual
  ``Thanks'' message for [hints].  Thanks to Peter Dillinger for
  requesting this feature.

  Added a new hint keyword, [47m:backtrack[0m, that checks the goals produced
  by processing a goal, and can cause the goal to be re-processed
  using a new hint.  See [hints].  Thanks to Pete Manolios for a
  conversation that led to the idea of this hint.

  Added a new class of hints, [override-hints], that is similar to
  [default-hints], except that override-hints are always applied,
  even if the user has supplied a hint explicitly for the goal.  See
  [override-hints].  Thanks to Pete Manolios and Harsh Raju Chamarthi
  for useful discussions on this topic, including its application to
  testing.

  When a goal ready to be pushed for proof by induction is given the
  new hint ``[47m:do-not-induct :otf[0m'', it is indeed pushed for proof by
  induction, rather than causing immediate failure as in the case of
  the hint ``[47m:do-not-induct t[0m''.  Instead, the proof fails when the
  goal is later picked to be proved by induction.  Thanks to Peter
  Dillinger for discussions leading to this feature.

  Related to computed hints only: Each history entry in the list stored
  in variable [47mHIST[0m (see [computed-hints]) now has a [47m:CLAUSE[0m field,
  which provides access to a goal's parent, parent's parent, and so
  on (within the same induction and forcing round only).

  It is now possible to inhibit warnings produced by [47m[in-theory][0m
  [events] and [hints] that occur when certain built-in definitions
  and executable-counterparts are disabled: just evaluate [47m(assign
  verbose-theory-warning nil)[0m.  Thanks to Jared Davis (and probably
  others in the past) for requesting such a mechanism.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  A source function ([47mlinearize-lst[0m) was replaced by tail-recursive
  code, which can avoid a stack overflow.  Thanks to Dave Greve for
  sending a helpful example.

  The heuristics for limiting [forward-chaining] have been slightly
  relaxed, to allow derivations based on the occurrence of all
  arguments of the forward-chaining rule's conclusion in the goal
  (after stripping leading calls of [47mNOT[0m).  Thanks to Dave Greve for
  contributing this improvement and providing a motivating example.

  We simplified induction schemes by eliminating each hypothesis of the
  form [47m(not (equal term (quote const)))[0m for which some other
  hypothesis in the same case equates term with some (presumably
  other) quoted constant.  Thanks to Dave Greve for requesting an
  improvement of this sort.

  [31;1mBUG FIXES[0m

  Fixed a soundness bug related to redundancy of [47m[encapsulate][0m events
  (see [redundant-events]) and [ruler-extenders].  A proof of [47mnil[0m in
  ACL2 Version 3.5 appears in a comment in [47m(deflabel note-3-6 ...)[0m in
  the ACL2 source code.  The fix is to insist that in order for one
  [47m[encapsulate][0m event to be redundant with another, they must be
  evaluated with the same [default-ruler-extenders].  Analogous to
  this issue of [default-ruler-extenders] for [47m[encapsulate][0ms is an
  issue of the [default-verify-guards-eagerness], which has similarly
  been fixed.

  Fixed soundness bugs related to the handling of
  [subversive-recursions] for [constraint]s.  Proofs of [47mnil[0m in ACL2
  Version 3.5 appear in a comment in [47m(deflabel note-3-6 ...)[0m in the
  ACL2 source code.

  Fixed a bug that could cause the following error during calls of
  [47m[certify-book][0m in the presence of calls of [47m[skip-proofs][0m in the
  book:

    ACL2 Warning [Skip-proofs] in

    HARD ACL2 ERROR in FMT0: Illegal Fmt Syntax.  The tilde-@ directive at
    position 0 of the string below is illegal because its variable evaluated
    to 0, which is neither a string nor a list.

    \"~@0\"

  Thanks to Dave Greve for reporting this bug and making available a
  very helpful test case.

  The [47m:corollary[0m of a rule (see [rule-classes]) failed to use the
  [47m[default-hints][0m of the logical [world].  This has been fixed.

  (CCL only) We removed a call, for CCL 1.3 (and beyond) only, of
  foreign function [47msync[0m in the closing of output channels.  Thanks to
  Daron Vroon for reporting issues with such a call on a non-Intel
  platform.

  Fixed a bug in reporting failures when monitoring rewrite rules with
  free variables in the hypotheses, that could cause a hard Lisp
  error (from which ACL2 continues, however).  Thanks to Eric Smith
  for sending a very helpful example with his bug report.

  Fixed the handling of [47m:induct[0m [hints], which had thrown away hint
  information from parent goals.  For example, the [47m[thm][0m form below
  failed to prove even though the second hint is in some sense
  superfluous; induction occurs automatically at [47m\"Goal'\"[0m even without
  the hint on that.  The failure was due to discarding the hint
  information on [47m\"Goal\"[0m.

    (in-theory (disable append))
    (thm (equal (cdr (cons a (append (append x y) z))) (append x y z))
         :hints
         ((\"Goal\" :in-theory (enable append))
          (\"Goal'\" :induct t) ; failed unless this line is commented out
          ))

  Fixed a bug in the [47m[args][0m command that was failing to show the
  formals of primitives (built-in functions like [47mconsp[0m that do not
  come with explicit definitions).  Thanks to John Cowles for
  pointing out this bug.  (At a lower level, the bug was that
  primitives failed to have [47m'stobjs-in[0m or [47m'stobjs-out[0m properties.)

  Fixed bugs in the utility supporting moving directories of certified
  books, sometimes used in Debian builds (as described in source
  function [47mmake-certificate-file[0m).  Thanks to Alan Dunn for pointing
  out such a bug, in paths associated with [47m[defpkg][0m events in
  [portcullis] commands in [certificate]s (which are used for error
  reporting).  There were also bugs, now fixed, that prevented
  renaming some book paths.  Please note that this mechanism is not
  guaranteed to be sound; in particular, it can probably misbehave
  when macros are used to generate portcullis events.  However, it
  seems likely that such issues will be very rare.

  Eliminated warnings that could arise when tracing a function with
  [47m[trace$][0m.  Now, when [47m[trace$][0m is applied to a function without
  option [47m:native[0m, that function's declarations and documentation are
  discarded.

  Fixed a bug that could cause a failure when building an executable
  image using SBCL as the underlying Common Lisp.  Thanks to Jun
  Sawada for reporting this failure.  We made a similar fix for
  CMUCL.

  Fixed a bug in [47m[save-exec][0m in the case that an absolute pathname is
  supplied.  Thanks to Jared Davis for bringing this bug to our
  attention.

  Fixed a bug in the use of [47m[trace$][0m with the [47m:native[0m and [47m:multiplicity[0m
  options that caused hard errors for some underlying Lisps.

  Fixed a bug in the interaction of [47m[trace$][0m and [47m:[0m[47m[comp][0m, which caused
  error as [47m[comp][0m tried to re-trace functions that it temporarily
  untraced.

  [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m

  See {ReleaseVersionNumbers |
  https://code.google.com/p/acl2-books/wiki/ReleaseVersionNumbers}
  for a list of books in Version 3.6 of ACL2 but not Version 3.5.
  For [3mchanges[0m to existing books rather than [3madditions[0m, see the {log
  entries | http://code.google.com/p/acl2-books/source/list} starting
  with revision r286 up through revision r329.

  It is no longer required to specify a value for environment (or
  `make') variable [47mACL2_SYSTEM_BOOKS[0m when running `make' in the
  distributed book directory, even when that directory is not under
  the directory containing the ACL2 executable.  Thanks to Peter
  Dillinger for providing this improvement, by modifying
  [47mbooks/Makefile-generic[0m and, as needed, distributed book Makefiles.

  Thanks to Peter Dillinger, some books in support of the ACL2 Sedan
  (ACL2s) are more easily available for ACL2 users who do not use
  ACL2s.  See [ACL2-sedan].

  [31;1mEMACS SUPPORT[0m

  If the following form is evaluated before the load of
  [47memacs/emacs-acl2.el[0m, then variables are now set to reflect the
  directory containing that file.

    (if (boundp '*acl2-sources-dir*)
        (makunbound '*acl2-sources-dir*))

  Fixed info-dir-entry line in generated info file (by patching
  [47mdoc/write-acl2-texinfo.lisp[0m).  Thanks to Alan Dunn for providing
  this patch.

  [31;1mEXPERIMENTAL HONS VERSION[0m

  Bob Boyer and others have contributed numerous changes for the
  experimental ``[47mhons[0m'' version of ACL2 (see [hons-and-memoization]).
  A number of these have been crafted to work specifically with CCL
  (Clozure Common Lisp, formerly OpenMCL), which is now required as
  the underlying Lisp for the ``[47mhons[0m'' version of ACL2.

  A heuristic (source function [47mtoo-many-ifs[0m has been made more scalable
  (for the non-HONS version as well, in fact), but with no functional
  change.  Thanks to Jared Davis for noticing performance issues and
  suggesting fixes.

  Other changes including the following, quoting Bob Boyer:

      The CCL CASE macro now does better than a dumb linear search in some
      CASEes.

      SH and CSH are functions to talk to the underlying Gnu-Linux from
      CCL.  Good for repeated calling when you simply cannot afford
      the copying cost of a FORK because you are using, say, a dozen
      gigabytes.

      Added CCL compiler-macros for IF and OR, to support some 'coverage'
      analysis, cf. IF-REPORT, extending the profiling.

      Introduced the type 'mfixnum' so that things like counting honses and
      counting calls to memoized or profiled functions can run fast
      in CCL 64 bits and yet still run at all under 32 bits.

      Moved all HONSes to CCL's newish static space, which permits the
      address of a cons to be used as a hash key, as in most Lisps.
      (CCL moves most conses and most everything when it does a
      compacting-gc.)

      Quite a few changes in the memoize-fn reporting.

      Added a timer facility, cf. call-with-timeout.  Good for running
      under throttle some gross thoughts like 'Is it true that you
      can't fit 12 pigeons into 11 holes' on some propositional
      calculus systems/functions.

      Added rwx-size, pid-owner-cmdlines, rss, and proc-stat to help see
      what is really going on virtually in Gnu-Linux.

      Fixed at least one bug in compact-print-file and helped make its
      integration into ACL2's read-object$ a little more sound.
      Still worried some about *print-readably* vs. readtable-case.
      Does anyone else stay awake late at night worrying about
      readtable-case?

      Revised how the *watch-dog-process* interrupts the main process for
      the thousandth time, cf. watch.  Haven't changed it in weeks,
      which means that (a) it is getting tolerable or (b) I've run
      out of gas.")
 (NOTE-3-6-1
  (RELEASE-NOTES)
  "ACL2 Version 3.6.1 (September, 2009) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  The essential changes to ACL2 since Version 3.6 are the two bug fixes
  described below.  There was also some functionality-neutral code
  refactoring, as requested by Daron Vroon in support of the ACL2
  Sedan (see [ACL2-sedan]).  Also see {ReleaseVersionNumbers |
  https://code.google.com/p/acl2-books/wiki/ReleaseVersionNumbers}
  for a list of books in Version 3.6.1 of ACL2 but not Version 3.6.
  For [3mchanges[0m to existing books rather than [3madditions[0m, see the {log
  entries | http://code.google.com/p/acl2-books/source/list} starting
  with revision r329 up through revision 350.

  Fixed a soundness bug in the handling of [ruler-extenders],
  specifically in the handling of [47m[let][0m-expressions.  Thanks to Pete
  Manolios, who sent us a proof of [47mnil[0m, essentially as follows.  In
  the termination proof for [47mfoo[0m below, the binding of [47mx[0m to [47m(cons t x)[0m
  was not substituted into the recursive call of [47mfoo[0m for purposes of
  the termination proof.

    (defun foo (x)
      (declare (xargs :ruler-extenders :all))
      (let ((x (cons t x)))
        (if (endp (cdr x))
            x
          (cons t (foo (cdr x))))))

    (defthm foo-bad
      nil
      :hints ((\"Goal\"
               :use ((:instance foo (x '(3))))
               :in-theory (disable foo (foo))))
      :rule-classes nil)

  Fixed a typo in code supporting [ruler-extenders] (specifically,
  swapped arguments in a recursive call of ACL2 source function
  [47mget-ruler-extenders2[0m, which could cause problems for functions
  defined using [47m[mutual-recursion][0m).  Thanks to Daron Vroon for
  bringing this bug to our attention, pointing out the swapped
  arguments.")
 (NOTE-3-6{R}
  (RELEASE-NOTES)
  "ACL2 Version 3.6(r) (August, 2009) Notes

  Please also see [note-3-6] for changes in Version 3.6 of ACL2.")
 (NOTE-4-0
  (RELEASE-NOTES)
  "ACL2 Version 4.0 (July, 2010) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 3.6.1 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, distributed books, Emacs
  support, and experimental versions.  Each change is described in
  just one category, though of course many changes could be placed in
  more than one category.  Also see [note-3-6-1] for other changes
  since Version 3.6.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  There have been extensive changes to the handling of compiled files
  for books, which may generally be invisible to most users.  The
  basic idea is that when compiled files are loaded on behalf of
  [47m[include-book][0m, they are now loaded before events in the book are
  processed, not afterwards.  This can speed up calls of
  [47minclude-book[0m, especially if the underlying Lisp compiles all
  definitions on the fly (as is the case for CCL and SBCL).  One
  functional change is that for keyword argument [47m:load-compiled-file[0m
  of [47m[include-book][0m, the values [47m:comp-raw[0m, [47m:try[0m, and [47m:comp![0m are no
  longer legal.  (Note that the handling of [47m:comp-raw[0m was actually
  broken, so it seems that this value wasn't actually used by anyone;
  also, the handling of [47m:comp![0m formerly could cause an error in some
  Lisp platforms, including SBCL.)  Another change is that if
  [47m[include-book][0m is called with [47m:load-compiled-file t[0m, then each
  sub-book must have a compiled file or a so-called ``expansion
  file''; see [book-compiled-file].  In the unlikely event that this
  presents a problem, the makefile provides a way to build with
  compilation disabled; see [compilation].  Users of raw mode (see
  [set-raw-mode]) will be happy to know that [47m[include-book][0m now works
  if there is an up-to-date compiled file for the book, since
  [47m[portcullis][0m commands are now incorporated into that compiled file.
  The mechanism for saving expansion files has changed, and the
  [47m:save-expansion[0m argument of [47m[certify-book][0m has been eliminated; see
  [certify-book].  More discussion of ACL2's new handling of book
  compilation is described in a new documentation topic; see
  [book-compiled-file].

  It was possible to get a hard Lisp error when certifying a book with
  a redundant [47m[defconst][0m form whose term is not identical to the
  existing [47m[defconst][0m form for the same name.  The following example
  illustrates the problem, which has been fixed (as part of the
  change in handling of compiled files for books, described above).
  Imagine that after the initial [47m(in-package \"ACL2\")[0m form, file
  [47mfoo.lisp[0m has just the form [47m(defconst *a* (append nil nil))[0m.  Then
  before the fix, we could have:

    ACL2 !>(defconst *a* nil)
    [[output omitted]]
    ACL2 !>(certify-book \"foo\" 1)
    [[initial output omitted]
    * Step 5:  Compile the functions defined in \"/v/joe/foo.lisp\".
    Compiling /v/joe/foo.lisp.
    End of Pass 1.
    End of Pass 2.
    OPTIMIZE levels: Safety=0 (No runtime error checking), Space=0, Speed=3
    Finished compiling /vjoe/foo.lisp.
    Loading /v/joe/foo.lisp

    Error: Illegal attempt to redeclare the constant *A*.

  The [47m[wormhole][0m facility has been changed to repair a bug that allowed
  guard violations to go undetected.  The major change has to do with
  the treatment of what used to be called the ``pseudo-flag''
  argument which has been replaced by a quoted lambda expression.
  See [note-4-0-wormhole-changes] for help in converting calls of
  [47m[wormhole][0m.  Also see see [wormhole] and see [wormhole-eval].

  The function [47massign-wormhole-output[0m has been eliminated but its
  functionality can be provided by [47m[wormhole-eval][0m.

  The ACL2 tutorial has been greatly expanded, for example to include a
  self-contained discussion of rewriting.  See [ACL2-tutorial].

  Formerly, the [47m[mbe][0m macro and [47m[must-be-equal][0m function were
  disallowed in any definition within an encapsulate having a
  non-empty signature.  Now, these are allowed provided the
  definition has been declared to be non-executable (see [defun-nx]).
  As a result, [47m[defevaluator][0m [events] may now include
  [47m[must-be-equal][0m among the function symbols known by the evaluator;
  this had not previously been allowed.  Thanks to Sol Swords for
  discussions leading to this relaxation for [47m[defevaluator][0m.

  [47m[Princ$][0m now prints strings more efficiently.  Thanks to Jared Davis
  for suggesting the improvements to [47mprinc$[0m.

  The use of [47m[xargs][0m declaration [47m:non-executable t[0m no longer requires
  the absence of [47m[state][0m or declared [47m[stobj][0ms among the formal
  parameters of a function definition.  As before, the use of
  [47m:non-executable t[0m turns off single-threadedness checking for the
  body, and also as before, attempts to execute the function will
  fail.  Thanks to Sol Swords for requesting this relaxation (for
  automatic generation of so-called ``flag functions'' for
  definitions using [47m[mutual-recursion][0m).

  The [documentation] has been improved for explaining to advanced
  users the details of the ACL2 hint mechanism; see
  [hints-and-the-waterfall], and see the example about
  [47mnonlinearp-default-hint[0m in distributed book
  [47mbooks/hints/basic-tests.lisp[0m.  Thanks to Robert Krug for useful
  discussions, in particular suggesting the above example as one to
  be explained with the documentation.

  The [47mtime$[0m macro has been enhanced to allow user control of the timing
  message that is printed, and of when it is printed.  See [time$].
  Thanks to Jared Davis for providing the essential design, helpful
  documentation (largely incorporated), and an initial implementation
  for raw Lisp.

  The [47m:ttags[0m argument to [47m[include-book][0m had been required when
  including a certified book that uses trust tags.  This is no longer
  the case: essentially, [47m:ttags[0m defaults to [47m:all[0m except that warnings
  will be printed.  Thanks to Jared Davis for requesting such a
  relaxation, and to him and Sandip Ray for useful discussions.

  The definition of [47m[mv-let][0m has been modified so that the single-step
  macroexpansion (see [trans1]) of its calls can be evaluated.
  Thanks to Pete Manolios for bringing this evaluation issue to our
  attention and ensuing discussions.

  All calls of so-called ``guard-holders'' --- [47m[prog2$][0m,
  [47m[must-be-equal][0m (from calls of see [mbe]), [47m[ec-call][0m, and [47m[mv-list][0m
  --- are now removed before storing hypotheses of rules of class
  [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[linear][0m.  Thanks to Sol Swords for requesting this
  enhancement and sending the following example in the case of
  [rewrite] rules.

    (defthm foo
      (prog2$ (cw \"asdf\")
              (and (equal (car (cons x y)) x)
                   (equal (cdr (cons x y)) y))))

  The handling of [47m[fmt][0m directive [47m~s[0m has been modified so that if the
  argument is a symbol that would normally be printed using vertical
  bars ([47m|[0m), then that symbol is printed as with [47m~f[0m.  Thanks to Jared
  Davis for providing the following example showing that treatment of
  [47m~s[0m was a bit unexpected: [47m(cw \"~s0.~%\" '|fo\\|o|)[0m.

  Error messages have been improved for ill-formed terms (in ACL2's
  so-called ``translation'' routines).  Thanks to Jared Davis for
  requesting such an enhancement.

  Modified [47m[defun-sk][0m so that it executes in [47m:[0m[47m[logic][0m mode.
  Previously, evaluation of a [47m[defun-sk][0m event in [47m:[0m[47m[program][0m mode
  caused a somewhat inscrutable error, but now, [47m:[0m[47m[program][0m mode is
  treated the same as [47m:[0m[47m[logic][0m mode for purposes of [47m[defun-sk][0m.

  The ``system hacker'' commands [47m([0m[47m[redef+][0m[47m)[0m and [47m([0m[47m[redef-][0m[47m)[0m are now
  embedded event forms (see [embedded-event-form]), hence may be used
  in [books] as well as in [47m[progn][0m and [47m[encapsulate][0m [events].  Also,
  these two commands are now no-ops in raw Lisp.

  The function symbol [47mworldp[0m (in the [47m\"ACL2\"[0m package) has been renamed
  to [47mplist-worldp[0m.

  The function [47mgc$-fn[0m (resulting from macroexpansion of [47m[gc$][0m) is now
  in [47m:[0m[47m[logic][0m mode.  Thanks to Jared Davis for requesting this
  change.

  The user now has control over whether compilation is used, for
  example whether or not [47m[certify-book][0m compiles by default, using
  function [47mset-compiler-enabled[0m.  See [compilation].

  Modified the conversion of relative to absolute pathnames in
  [portcullis] [command]s for book certification.  Now, more
  pathnames remain as relative pathnames.

  The [47m\"Ttags\"[0m warning that can be printed by [47m[include-book][0m is now
  given even if [47m[set-inhibit-output-lst][0m has specified `[47mwarning[0m'.  To
  suppress it, specify [47mwarning![0m instead, for example,
  [47m(set-inhibit-output-lst '(acl2::warning! acl2::proof-tree))[0m.

  On occasion, ACL2 prints the message ``Flushing current installed
  world'' as it cleans up when certain actions (installing a [world])
  are interrupted.  This operation has been sped up considerably.  If
  your session includes many [events], you can probably speed up any
  such operation further by invoking [47m[reset-prehistory][0m.  Thanks to
  Jared Davis for sending a query that led us to make this
  improvement.

  Calls of the form [47m(ec-call (must-be-equal logic exec))[0m are no longer
  allowed, since we do not have confidence that they would be handled
  correctly.

  The underlying function for [47m[good-bye][0m (and hence for [47m[exit][0m and
  [47m[quit][0m) is now in [47m:[0m[47m[logic][0m mode.  Thanks to Jared Davis for
  requesting this enhancement.

  We now require that every function symbol in the [signature] of an
  [47m[encapsulate][0m event have a [47m:[0m[47m[logic][0m mode definition at the end of
  the first pass, not merely a [47m:[0m[47m[program][0m mode definition (which
  formerly was sufficient).  You can still define such a function in
  [47m:program[0m mode, provided it is followed by a [47m:logic[0m mode definition
  (where of course both definitions are [local], since we are
  discussing functions introduced in the [signature]).  Thanks to
  Carl Eastlund for bringing this issue to our attention.  (Note: An
  analogous modification has been made for [47m:[0m[47m[bdd][0m [hints] as well.)

  The following functions now have raw Lisp implementations that may
  run faster than their ACL2 definitions: [47m[assoc-eq][0m, [47m[assoc-equal][0m,
  [47m[member-eq][0m, [47m[member-equal][0m, [47msubsetp-eq[0m, [47m[subsetp-equal][0m,
  [47m[remove-eq][0m, [47m[remove-equal][0m, [47m[position-eq][0m, and [47m[position-equal][0m.
  Thanks to Jared Davis for suggesting that we consider such an
  improvement.

  We now avoid infinite loops caused when tracing functions that
  implement [47m[trace$][0m.  Thanks to Rob Sumners and Eric Smith for
  useful discussions.

  The implementation of [47m[trace!][0m has been modified slightly, to
  accommodate the fix for ``some holes in the handling of trust
  tags'' described later, below.

  This item applies unless the host Lisp is GCL.  An interrupt
  (control-c) will now cause a proof to exit normally in most cases,
  by simulating a timeout, as though [47m[with-prover-time-limit][0m had
  been called with a time-limit of 0.  If the first interrupt doesn't
  terminate the proof, a second one should do so (because a
  different, more ``severe'' mechanism is used after the first
  attempt).  As a result, [47m[redo-flat][0m should work as one might expect
  even if a proof is interrupted.  Thanks to Dave Greve for
  requesting this enhancement to [47m[redo-flat][0m.  Technical note: for
  reasons related to this change, time-limits are no longer checked
  in evaluator functions ([47mev-fncall[0m, [47mev[0m, [47mev-lst[0m, [47mev-fncall-w[0m, [47mev-w[0m,
  and [47mev-w-lst[0m).

  It is now legal for [proof-builder] [macro-command]s to appear in
  [47m:[0m[47m[instructions][0m that are used in place of [47m:[0m[47m[hints][0m.  Thanks to
  Sandip Ray for (most recently) requesting this feature.

  The value of [47m:command-conventions[0m for [47m[ld][0m special variable
  [47mld-post-eval-print[0m is now treated as though it were [47mt[0m if the value
  [47m[ld][0m special variable [47mld-error-triples[0m is [47mnil[0m.  The following
  example illustrates this change.

    ACL2 !>(ld-post-eval-print state) ; default
    :COMMAND-CONVENTIONS
    ACL2 !>(ld-error-triples state) ; default
    T
    ACL2 !>(set-ld-error-triples nil state)
    *** Then, before the change:
    ACL2 !>(mv t 3 state)
     3
    *** Instead, after the change:
    ACL2 !>(mv t 3 state)
    (T 3 <state>)

  The default behavior of [47m[ld][0m has been changed.  Formerly when an
  error occurred that halted a subsidiary call of [47mld[0m, then the parent
  [47mld[0m would continue.  That is no longer the case.  Consider the
  following example.

    (ld '((ld '((defun f (x) x)
                (defun bad (x)) ; ERROR -- missing the body
                ))
          (defun g (x) x)))

  Formerly, [47mg[0m would be defined in the resulting logical [world].  Now,
  the error halts not only the inner [47mld[0m but also the outer [47mld[0m.  See
  [ld], and for details of the new default value for
  [47m:ld-error-action[0m, [47m:RETURN![0m, see [ld-error-action].  Also see the
  paragraph below about a new utility, [47m:[0m[47m[p!][0m.  Thanks to Robert Krug
  and Sandip Ray for helpful discussions.

  Environment variable [47mACL2-CUSTOMIZATION[0m has been replaced by
  [47mACL2_CUSTOMIZATION[0m --- that is, the hyphen has been replaced by an
  underscore --- so that it can be set conveniently in the [47mbash[0m
  shell.  See [ACL2-customization].

  The ``[47mWarnings:[0m'' summary is now omitted when there are no warnings,
  where formerly ``[47mWarnings: None[0m'' was printed.  Thanks to Jared
  Davis for suggesting this change.

  We have modified the generation of [47mconstraint[0ms for [47m[encapsulate][0m
  [events] in two primary ways, neither of them likely to affect many
  users.  One change is that the virtual movement of definitions and
  theorems to in front of an [47m[encapsulate][0m event, or of definitions
  to behind that event, is no longer inhibited in the case of nested
  encapsulates with non-empty [signature]s.  The following example
  illustrates the other change, as discussed below.

    (encapsulate
     ((f (x) t))
     (local (defun f (x) x))
     (defun g (x) (cons x (f x)))
     (defun h (x) (g x))
     (defthm h-is-f (equal (car (h x)) x)))

  Previously, the [constraint] on [47mf[0m and [47mh[0m was essentially the
  conjunction of the definition of [47mh[0m and the theorem [47mh-is-f[0m.  Now,
  the definition of [47mg[0m is conjoined as well; moreover, [47mg[0m receives the
  same [constraint] as do [47mf[0m and [47mh[0m, where previously [47mg[0m was only
  constrained by its definition.  While we are not aware of a
  soundness bug caused by the previous approach, the new approach
  follows more precisely the intended notion of [constraint].

  The use of [47m[trace$][0m (or [47m[trace!][0m) option [47m:multiplicity[0m had been
  required when option [47m:native[0m was supplied.  This is no longer the
  case.  Also, a bug has been fixed that had prevented [47m:multiplicity[0m
  from working properly in GCL and Allegro CL.

  Several errors have been eliminated that formerly occurred when the
  constraints for a function symbol were unknown because it was
  constrained using a dependent clause-processor (see
  [define-trusted-clause-processor].  Now, it is assumed that the
  [47msupporters[0m argument in a [47m[define-trusted-clause-processor][0m event is
  such that every ancestor of any function symbol constrained by the
  ``promised encapsulate'' of that event among, or ancestral in,
  those [47msupporters[0m.  Thanks to Sol Swords, Sandip Ray, and Jared
  Davis for helpful discussions.

  The notion of [constraint] for functions introduced by [47m[defun][0m has
  been modified slightly.  No longer do we remove from the body of
  the definition calls of so-called ``guard-holders'': [47m[prog2$][0m,
  [47m[must-be-equal][0m, [ec-call], and [mv-list], and uses of [47mthe-error[0m
  generated by [47m[the][0m.  Also, we now expand calls of [47mthe-error[0m with
  the same aggressive heuristics applied to a number of other
  functions (technically, adding it to the list
  [47m*expandable-boot-strap-non-rec-fns*[0m).

  [31;1mNEW FEATURES[0m

  A new event, [47m[defattach][0m, allows evaluation of calls of constrained
  ([47m[encapsulate][0md) functions.  In particular, users can now, in
  principle, soundly modify ACL2 source code; please feel free to
  contact the ACL2 implementors if you are interested in doing so.
  See [defattach].

  Eric Smith has noticed that if you exit the [break-rewrite] loop
  using [47m:[0m[47m[a!][0m during an [47m[ld][0m of a file, then all changes to the
  logical [world] are discarded that were made during that call of
  [47m[ld][0m.  A new utility, [47m:[0m[47m[p!][0m, pops just one level instead, and
  avoids discarding that work.  (This change is related to an item
  above, ``The default behavior of [47m[ld][0m has been changed.'') Thanks
  to Eric for pointing out this issue.

  New function [47m[mv-list][0m is the identity function logically, but
  converts multiple values to lists.  The first argument is the
  number of values, so an example form is as follows, where [47mfoo[0m
  returns three values: [47m(mv-list 3 (foo x y))[0m.  Thanks to Sol Swords
  for requesting this feature and for reporting a soundness bug in
  one of our preliminary implementations.

  A new [47m[state][0m global variable, [47mhost-lisp[0m, has as its value a keyword
  whose value depends on the underlying Common Lisp implementation.
  Use [47m(@ host-lisp)[0m to see its value.

  It is now possible to write [documentation] for HTML without error
  when there are links to nonexistent documentation topics.  See the
  comments in macro [47macl2::write-html-file[0m at the end of file
  [47mdoc/write-acl2-html.lisp[0m.  When there are such errors, they should
  be easier to understand than previously.  Thanks to Alan Dunn for
  providing the initial modifications.

  It is now possible to inhibit specified parts of the Summary printed
  at the conclusion of an event.  See [set-inhibited-summary-types].
  Also see [with-output], in particular the discussion of the new
  [47m:summary[0m keyword.  Thanks to Sol Swords for requesting more control
  over the Summary.

  A new [47m:[0m[47m[hints][0m keyword, [47m:case-split-limitations[0m, can override the
  default case-split-limitations settings (see
  [set-case-split-limitations]) in the simplifier.  Thanks to Ian
  Johnson for requesting this addition and providing an initial
  implementation.

  It is now possible to defer and avoid some ttag-related output; see
  [set-deferred-ttag-notes].  Thanks to Jared Davis for requesting
  less verbosity from ttag-related output.

  A new [command], [47m:[0m[47m[pl2][0m, allows you to restrict the rewrite rules
  printed that apply to a given term.  See [pl2].  Thanks to Robert
  Krug for requesting such a capability.

  ACL2 now provides a utility for canonicalizing filenames, so that
  soft links are resolved; see [canonical-pathname].  Moreover, ACL2
  uses this utility in its own sources, which can eliminate some
  issues.  In particular, [47m[include-book][0m with argument [47m:ttags :all[0m no
  longer breaks when given a book-name differing from the book-name
  that was used at certification time; thanks to Sol Swords for
  reporting that problem.  Also, certain errors have been eliminated
  involving the combination of packages in the certification world
  and trust tags; thanks to Jared Davis for sending an example of
  that problem.

  You can now suppress or enable guard-checking for an individual form;
  see [with-guard-checking].  Thanks to Sol Swords for requesting
  this feature.

  The [47m[walkabout][0m utility has been documented (thanks to Rob Sumners
  for suggesting this documentation).  This utility can make it easy
  to explore a large [47mcons[0m tree.  New interactive commands [47m(pp n)[0m and
  [47m(pp print-level print-length)[0m have been added to restrict how much
  of the current object is displayed.  See [walkabout].

  Rules of class [47m:[0m[47m[type-prescription][0m may now be provided a
  [47m:backchain-limit-lst[0m keyword.  The default behavior is unchanged,
  but now [47m[type-set][0m is sensitive not only to the new
  [47m:backchain-limit-lst[0m of a [47m:[0m[47m[type-prescription][0m rule (if supplied)
  but to the [47m[default-backchain-limit][0m of the current logical
  [world].  Setting of backchain-limits can now specify either the
  new (type-set) limit or the old limit (for rewriting); see
  [set-default-backchain-limit] and see [set-backchain-limit].
  Moreover, the functions [47m[default-backchain-limit][0m and
  [47m[backchain-limit][0m now take a second argument of [47m:ts[0m or [47m:rewrite[0m to
  specify which backchain-limit is desired.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  The so-called ``too-many-ifs'' heuristic has been modified.  Such a
  heuristic has been employed in ACL2 (and previous Boyer-Moore
  provers) for many years, in order to limit the introduction of
  calls of [47m[if][0m by non-recursive functions.  Most users need not be
  concerned with this change, but two proofs in the regression suite
  (out of thousands) needed trivial adjustment, so user proofs could
  need tweaking.  In one application, this modification sped up
  proofs by 15%; but the change in runtime for the regression suite
  is negligible, so such speedups may vary.  Thanks to Sol Swords for
  providing a test from ACL2 runs at Centaur Technology, which was
  useful in re-tuning this heuristic.

  Guard proof obligations could have size quadratic in the number of
  clauses in a [47m[case][0m statement.  This inefficiency has been removed
  with a change that eliminates a hypothesis of the form [47m(not (eql
  term constant))[0m when there is already a stronger hypothesis,
  equating the same term with a different constant.  Thanks to Sol
  Swords for bringing this problem to our attention and suggesting an
  alternate approach to solving it, which we may consider in the
  future if related efficiency problems persist.

  We adjusted the heuristics for determining induction schemes in the
  presence of [ruler-extenders], when handling calls of a function
  symbol that is a ruler-extender, in either of two cases: either the
  function takes only one argument; or the function is [47m[prog2$][0m or
  [47m[ec-call][0m, and the first argument contains no recursive call.
  These cases are treated more directly as though the ruler-extender
  call is replaced by the unique (in the case of [47m[prog2$][0m and
  [47m[ec-call][0m, the second) argument.

  A new [47m:[0m[47m[type-prescription][0m rule, [47mtrue-listp-append[0m, has been added:

    (implies (true-listp b)
             (true-listp (append a b)))

  If you are interested in the motivation for adding this rule, see
  comments in [47mtrue-listp-append[0m in ACL2 source file [47maxioms.lisp[0m.

  The use of [47m:forward-chaining[0m lemmas has been improved slightly.  In
  previous versions, a conclusion derived by forward chaining was
  discarded if it was derivable by type-set reasoning, since it was
  ``already provable.'' But this heuristic prevented the conclusion
  from triggering further forward chaining.  This has been fixed.
  Thanks to Dave Greve for pointing out this problem.

  The fundamental utility that turns an [47mIF[0m expression into a set of
  clauses has been optimized to better handle tests of the form
  [47m(equal x 'constant)[0m and their negations.  This eliminates an
  exponential explosion in large case analyses.  But it comes at the
  inconvenience of sometimes reordering the clauses produced.  The
  latter aspect of this change may require you to change some Subgoal
  numbers in proof hints.  We apologize for the inconvenience.

  Certification can now run faster (specifically, the compilation
  phase) for books with very large structures generated by
  [47m[make-event][0m, when there is significant sharing of substructure,
  because of a custom optimization of the Lisp reader.  Thanks to Sol
  Swords for bringing this efficiency issue to our attention.

  Jared Davis reported inefficiency in certain [47m[make-event][0m evaluation
  due to a potentially expensive ``bad lisp object'' check on the
  expansion produced by the [47mmake-event[0m.  This check has been
  eliminated except in the case that the expansion introduces
  packages (for example, by including a book during the expansion
  phase that introduces packages).  Thanks to Jared for providing a
  helpful example.

  The application of rules of class [47m:[0m[47m[induction][0m had the potential to
  loop (as commented in ACL2 source function [47mapply-induction-rule[0m).
  This has been fixed.  Thanks to Daron Vroon and Pete Manolios for
  sending nice examples causing the loop.

  Heuristics have been tweaked so that false goals may be simplified to
  [47mnil[0m that had formerly been left unchanged by simplification,
  perhaps resulting in useless and distracting proofs by induction.
  Thanks to Pete Manolios for pointing out this issue by sending the
  following example: [47m(thm (<= (+ 1 (acl2-count x)) 0))[0m.  (Technical
  explanation: When every literal in a clause simplifies to [47mnil[0m, even
  though we might not normally delete one or more such literals, we
  will replace the entire clause by the false clause.)

  Improved the efficiency of the built-in function, [47m[take][0m.  Thanks to
  Bob Boyer for suggesting this improvement.

  ACL2 can now use evaluation to relieve hypotheses when applying
  [47m:[0m[47m[type-prescription][0m rules.  Thanks to Peter Dillinger and Dave
  Greve for requesting this enhancement, and to Robert Krug for a
  relevant discussion long ago.

  Evaluation has been sped up during theorems for calls of [47m[mv-let][0m, by
  avoiding repeated evaluation of the expression to which its
  variables are bound.  Thanks to Sol Swords for requesting this
  improvement and sending an illustrative example.

  Modified a heuristic to avoid the opening up non-recursive function
  calls on calls of [47m[hide][0m involving [47m[if][0m-expressions.  For example,
  the [47m[thm][0m form below is now admitted

    (defun bar (x)
      (cons x x))
    (thm (equal (bar (hide (if a b c)))
         (cons (hide (if a b c)) (hide (if a b c)))))

  [31;1mBUG FIXES[0m

  Fixed a soundness bug in destructor elimination, which was preventing
  some cases from being generated.  Thanks to Eric Smith for
  reporting this bug and sending a helpful example.  (Technical
  detail: the fixes were in ACL2 source functions
  [47mapply-instantiated-elim-rule[0m and [47meliminate-destructors-clause1[0m, and
  comments in the former contain Eric's example.)

  Fixed a bug that supported a proof of [47mnil[0m by exploiting the fact that
  [portcullis] [command]s were not included in check-sum computations
  in a book's [certificate].  For such a proof of [47mnil[0m, see the
  relevant comment in the ACL2 source file [47mld.lisp[0m under [47m(deflabel
  note-4-0 ...)[0m.

  Changed the implementation of [47m[add-include-book-dir][0m.  The previous
  implementation could allow relative pathnames to be stored in the
  [portcullis] [command]s of [certificate]s of [books], which perhaps
  could lead to unsoundness (though we did not try to exploit this to
  prove [47mnil[0m).  Thanks to Jared Davis for reporting a bug in our first
  new implementation.  An additional change to both
  [47m[add-include-book-dir][0m and [47m[delete-include-book-dir][0m is that these
  now work in raw-mode (see [set-raw-mode]).  (Thanks to Dave Greve
  for suggesting a reduction in the warnings we produced related to
  raw-mode.)  Note that it is no longer permitted to make a direct
  call of the form [47m(table acl2-defaults-table :include-book-dir-alist
  ...)[0m; use [47m[add-include-book-dir][0m instead.

  Fixed a soundness bug related to [47m[xargs][0m keyword [47m:non-executable[0m.
  New macros, [47mdefun-nx[0m and [47mdefund-nx[0m, have been provided for
  declaring functions to be non-executable; see [defun-nx].  While we
  expect this bug to occur only rarely if at all in practice, the
  following example shows how it could be evoked.

    ;;;;;;;;;;;;;;;;;;;;
    ;;; Book sub.lisp
    ;;;;;;;;;;;;;;;;;;;;
    (in-package \"ACL2\")
    (defun f ()
      (declare (xargs :guard t
                      :non-executable t))
      (mv-let (a b c)
              (mv 3 4)
              (declare (ignore a b))
              c))
    (defun g ()
      (declare (xargs :guard t))
      (prog2$ (mv-let (x y z)
                      (mv 2 3 4)
                      (declare (ignore x y z))
                      nil)
              (f)))
    (defthm g-nil
      (equal (g) nil)
      :hints ((\"Goal\" :in-theory (disable (f))))
      :rule-classes nil)
    ;;;;;;;;;;;;;;;;;;;;
    ;;; Book top.lisp
    ;;;;;;;;;;;;;;;;;;;;
    (in-package \"ACL2\")
    (include-book \"sub\")
    (defthm contradiction
      nil
      :hints ((\"Goal\" :use g-nil))
      :rule-classes nil)

  The modification described above pertaining to [47m[defun-nx][0m also
  prevents execution of non-executable functions that have been
  [trace]d.  The following example illustrates the problem; now, the
  following [47m[defun][0m of [47mg[0m is illegal, and the problem disappears if
  [47m[defun-nx][0m is used instead.

    (defun g (x) ; Use defun-nx to avoid an error after Version_3.6.1.
      (declare (xargs :guard t :non-executable t))
      x)
    (g 3) ; causes error, as expected
    (trace$ g)
    (g 3) ; returned 3 before the bug fix; after fix, causes error as expected

  A hard error was possible when attempting to include an uncertified
  book containing [events] of the form [47m(make-event '(local ...))[0m.
  This has been fixed.  Thanks to Sol Swords for bringing this issue
  to our attention.

  Fixed a bug in the heuristic improvement described for Version_3.6
  (see [note-3-6]) as ``We simplified induction schemes....'' The bug
  had prevented, in unusual cases such as the following (notice the
  impossible case), a proof by induction.

    (defun foo (a x)
      (and (consp x)
           (case a
             (0 (foo (car x) (cdr x)))
             (1 (foo (cdr x) (car x)))
             (0 (foo a (cons x x))))))
    (in-theory (disable (:type-prescription foo)))
    (thm (atom (foo a x)))

  Macro [47m[cw-gstack][0m did not work with an [47m:evisc-tuple[0m argument.  This
  has been fixed by changing [47mcw-gstack[0m so that it now evaluates its
  arguments.  Thanks to Sol Swords for bringing this bug to our
  attention.

  Fixed a bug in [47m:[0m[47m[pso][0m during the printing of failure messages for
  termination proofs.

  Fixed a bug in the handling of [47m#.[0m (see [sharp-dot-reader]).  Thanks
  to Bob Boyer for bringing this bug to our attention.

  Replaced a hard Lisp error with a clean error, in certain cases that
  a [47m:[0m[47m[hints][0m value is erroneously supplied as a non-[47mnil[0m atom.
  Example: [47m(thm (equal x x) :hints 3)[0m.

  Fixed a bug in the interaction of function tracing with conversion of
  a function from [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m mode.  The following example
  illustrates what had been wrong.

    (defun f (x)
      (declare (xargs :mode :program))
      (car x))
    (f 3) ; raw Lisp hard error
    (trace$ f)
    (f 3) ; raw Lisp hard error (still)
    (defun f (x) (car x)) ; upgrade f to :logic mode
    (f 3) ; clean guard violation; f is no longer traced
    (trace$) ; uh oh - f is shown as traced
    (untrace$ f)
    (f 3) ; OUCH: hard Lisp error because old :program mode definition of
          ; the executable counterpart (sometimes called *1*f) was restored!

  Made a fix so that when building ACL2 with `make' option
  [47mACL2_SAFETY=3[0m, there will no longer be any safety-0 compiled code
  generated.  Thanks to Gary Byers for bringing this bug to our
  attention.

  Fixed a bug in the handling of [override-hints] that generate custom
  keyword hints (see [custom-keyword-hints]) involving the variable
  [47mstable-under-simplificationp[0m.  Thanks to Ian Johnson for bringing
  this bug to our attention with explanation that included a helpful
  example, included as comment in the ACL2 source code for function
  [47mapply-override-hint[0m.

  The [47msaved_acl2[0m script in CLISP could contain unexpected characters
  where simple newlines were expected.  Dave Greve found this in a
  Cygwin environment on Windows.  Thanks to Dave for reporting this
  bug and experimenting with a fix, and thanks to the CLISP folks for
  providing helpful information.

  Fixed a bug that could make [47m:[0m[47m[oops][0m cause an error.  Also, the [47m[oops][0m
  command can no longer take you back before a [47m[reset-prehistory][0m
  event.

  (GCL only) Fixed a bug that could occur when calling [47mtrace[0m in raw
  Lisp in GCL.

  Proof summaries have been improved, so that they account for [rune]s
  used in rewriting that takes place when generating goals to be
  proved in a forcing round.  Thanks to Jared Davis for sending us an
  example illustrating this issue.

  Fixed a bug that (at least in CCL) could put extra backslashes (`[47m\\[0m')
  in a pathname that ACL2 writes out to the executable script created
  by a build.  Thanks to Gary Byers for explaining that the CCL
  behavior is legal (for our previous use of Common Lisp function
  [47mmerge-pathnames[0m).

  We closed some holes in the handling of trust tags (also known as
  ``ttags''; see [defttag]) by [47m[include-book][0m.  The following example
  illustrates this rather subtle situation.  Consider the following
  book.

    (in-package \"ACL2\")
    (make-event
     (er-progn
      (encapsulate
       ()
       (defttag :foo)
       (value-triple \"Imagine something bad here!\"))
      (value '(value-triple :some-value)))
     :check-expansion t)

  Formerly, the following commands succeeded.

    (certify-book \"test3\" 0 t :ttags :all)
    :u
    (include-book \"test3\" :ttags nil)

  But because of [47m[make-event][0m keyword argument [47m:check-expansion t[0m, we
  know that the event [47m(defttag :foo)[0m is evaluated by the above
  [47m[include-book][0m form, and hence the [47m:ttags[0m argument of [47minclude-book[0m,
  above, should have specified [47m:foo[0m.  The problem was that [47m[defttag][0m
  forms evaluated during [47m[make-event][0m expansion did not contribute to
  the trust tag information stored in the book's [certificate].
  Note: Because of this change, one should avoid using [47m[make-event][0m
  with [47m:check-expansion t[0m when the expansion would introduce a
  [47m[defttag][0m event during [47m[include-book][0m but not [47m[certify-book][0m time.
  For an example illustrating this issue, see [make-event-details],
  specifically the new version of the section labeled ``A note on
  ttags'' at the end of that [documentation] topic.

  Closed a small loophole that had the potential, in rare
  circumstances, to violate atomicity of under-the-hood updates for
  ACL2 [arrays].

  The following example was formerly allowed, but resulted in a
  guard-verified function (here, [47mg[0m) whose guard proof obligation is
  not a theorem outside the [47m[encapsulate][0m event.  We now disallow
  [guard] verification for functions introduced non-[local]ly inside
  an [47m[encapsulate][0m event unless we determine that the proof
  obligations hold outside the [47m[encapsulate][0m event as well.

    (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)))

  The use of [47m:[0m[47m[comp][0m on [stobj] functions had potentially caused a hard
  Lisp error; for example, this could occur when [47m(defstobj foo fld)[0m
  was followed by [47m:comp foop[0m.  This has been fixed.

  Fixed a bug that could cause a raw Lisp error when the first argument
  of [47m[with-local-stobj][0m is not a symbol.

  It had been possible to use the reserved keyword
  :computed-hints-replacement as the name of a custom keyword hint
  (see [custom-keyword-hints]).  This has been fixed.  Thanks to Dave
  Greve, who pointed out a confusing hint error message (which has
  also been fixed) that led us to this issue.

  Fixed a bug that could cause a hard Lisp error, instead of a graceful
  ACL2 error, if keyword [47m:backchain-limit-lst[0m in a rule class is
  given a cons that is not a true list, such as [47m(1 . 1)[0m.

  Eliminated an error that could occur when redefining a function as a
  macro and then compiling, as in the example below.

    (defun foo (x) x)
    :redef!
    (defmacro foo (x) x)
    :comp t

  Thanks to Eric Smith for sending the above example in his bug report.

  Fixed a bug that could result in an assertion when a
  [clause-processor] causes an error.

  [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m

  See the {log entries |
  http://code.google.com/p/acl2-books/source/list} for a record of
  books changed or added since the preceding release, with log
  entries.

  We note in particular the new [47msystem/[0m directory, which begins to
  specify ACL2 system code in anticipation of opening the
  architecture of ACL2 (see [defattach] for a relevant tool).  Some
  system functions were changed slightly (but with the expectation of
  not generally affecting ACL2 behavior) in support of the
  development of this directory.  Those interested in contributing to
  further such efforts are invited to contact the ACL2 implementors.

  New utilities have been provided for certifying most of the
  distributed books with more `make'-level parallelism.  For example,
  we have obtained close to a 12x reduction in time by using `[47mmake -j
  24 regression-fast[0m' on a 24-processor machine.  For more
  information see [47mbooks/make-targets[0m, or to include the
  [47mbooks/workshops[0m in the regression run, see
  [47mbooks/regression-targets[0m.  Thanks to Sol Swords for providing these
  nice utilities.

  The top-level makefile, [47mGNUmakefile[0m, has been fixed so that the build
  processes (which are inherently sequential) will ignore the [47m-j[0m
  option of `make'.  Note that regressions can still, however, be
  done in parallel, as the [47m-j[0m option will be passed automatically to
  the appropriate `make' command.

  [31;1mEMACS SUPPORT[0m

  [31;1mEXPERIMENTAL VERSIONS[0m

  The HONS version, supported primarily by Bob Boyer and Warren Hunt
  (see [hons-and-memoization]), has undergone numerous improvements.
  For example, keyword argument [47m:FORGET[0m is now supported when calling
  [47m[memoize][0m from within the ACL2 loop, and system function [47mworse-than[0m
  is [memoize]d with the [47m:condition[0m that both terms are function
  applications (clearing the memo-table after each prover
  invocation).  Thanks to Jared Davis and Sol Swords for
  investigating the memoization of [47mworse-than[0m, and with suitable
  [47mcondition[0m.  Thanks also to Jared Davis for contributing structural
  modifications to the implementation of [47m[hons][0m.

  David Rager contributed modifications to the parallel version (see
  [parallelism]), which include taking advantage of atomic increments
  available at least since Version 1.0.21 of SBCL and Version 1.3 of
  CCL.


Subtopics

  [Note-4-0-wormhole-changes]
      How to convert calls of wormhole for Version 4.0")
 (NOTE-4-0-WORMHOLE-CHANGES
  (NOTE-4-0)
  "How to convert calls of wormhole for Version 4.0

  Here we describe how to convert an ``old-style'' call of [47m[wormhole][0m
  --- that is, a call suitable for ACL2 versions preceding 4.0 --- in
  which the [47mpseudo-flag[0m was [47mt[0m.  In order to convert such a call

    (wormhole t 'name input form ...)

  to a new-style call, the following steps must be carried out.  Note
  that the wormhole name must always be quoted now.

  First, eliminate the first argument, [47mt[0m, and add a new second argument
  that is the quoted lambda expression

    '(lambda (whs) (set-wormhole-entry-code whs :ENTER))

  Setting the entry code to [47m:ENTER[0m is not necessary if you maintain the
  invariant (after initialization) that it is always [47m:ENTER[0m.  In that
  case, the simpler quoted lambda will suffice:

    '(lambda (whs) whs)

  Second, change the [47mform[0m argument so that instead of talking about the
  state global variable [47mwormhole-output[0m it talks about the state
  global variable [47mwormhole-status[0m.  Look for [47m(@ wormhole-output)[0m,
  [47m(assign wormhole-output ...)[0m, [47m(f-get-global 'wormhole-output ...)[0m
  and [47m(f-put-global 'wormhole-output ...)[0m in [47mform[0m and replace them
  with expressions involving [47mwormhole-status[0m.

  However, remember that the old data stored in [47mwormhole-output[0m is now
  in the [47mwormhole-data[0m component of the [47mwormhole-status[0m.  Thus, for
  example, an old use of [47m(@ wormhole-output)[0m will typically be
  replaced by [47m(wormhole-data (@ wormhole-status))[0m and an old use of
  [47m(assign wormhole-output ...)[0m will typically be replaced by

    (assign wormhole-status (set-wormhole-data (@ wormhole-status) ...))

  In summary, an old-style call like

    (wormhole t 'name
              input
              '(...1 (@ wormhole-output) ...2
                ...3 (assign wormhole-output ...4) ...5)
              ...6)

  can become

    (wormhole 'name
              '(lambda (whs) (set-wormhole-entry-code whs :ENTER))
              input
              '(...1 (wormhole-data (@ wormhole-status)) ...2
                ...3 (assign wormhole-status
                            (set-wormhole-data (@ wormhole-status)
                                               ...4) ...5)
              ...6)

  In any case, and especially if your [47mwormhole[0m call had a [47mpseudo-flag[0m
  other than [47mt[0m, we recommend that you see [wormhole].")
 (NOTE-4-0{R}
  (RELEASE-NOTES)
  "ACL2 Version 4.0(r) (July, 2010) Notes

  Please see [note-4-0] for changes in Version 4.0 of ACL2.")
 (NOTE-4-1
  (RELEASE-NOTES)
  "ACL2 Version 4.1 (September, 2010) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 4.1 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, distributed books, Emacs
  support, and experimental versions.  Each change is described in
  just one category, though of course many changes could be placed in
  more than one category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  The [guard] associated with calls of the macro, [47m[search][0m, has been
  weakened so that now, given strings are no longer restricted to
  contain only standard characters unless the [47m:test[0m argument is
  [47m[char-equal][0m.

  Modified the writing of ``hidden [47m[defpkg][0m'' forms into [certificate]
  files (see [hidden-defpkg]), to support moving certificate files
  for distributed books, as is done by ACL2s (see [ACL2-sedan]) and
  Debian releases of ACL2.  Thanks to Camm Maguire for reporting a
  problem with Debian releases of ACL2 that led to this change.

  Expanded the constant [47m*acl2-exports*[0m by adding [47mintersection-equal[0m to
  the list.  Thanks to Jared Davis for requesting this change.

  The [47m:[0m[47m[comp][0m utility now compiles functions that have code
  conditionalized for raw Lisp only (presumably because a trust tag
  was active when they were defined).  Previously, this was not the
  case when [47m:comp[0m was applied to more than a single function symbol.

  [31;1mNEW FEATURES[0m

  A new macro, [47m[top-level][0m, allows evaluation directly in the top level
  loop for forms that normally need to be evaluated inside function
  bodies, such as [47m[with-local-stobj][0m.  See [top-level].  Thanks to
  Jared Davis for requesting such a utility.

  Added [47m[count][0m, a Common Lisp function, to ACL2.  In support of that
  addition, also added rewrite rule [47meqlablep-nth[0m.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  [None this time.]

  [31;1mBUG FIXES[0m

  We fixed a soundness bug that could occur when a function that
  returns multiple values is called in its own guard.  Thanks to Sol
  Swords for reporting this bug and sending a small self-contained
  example, which is included in a comment in the function
  [47mchk-acceptable-defuns1[0m in ACL2 source file [47mdefuns.lisp[0m.

  It was possible to cause an error when giving theory hints during
  redefinition of functions.  This has been fixed.  Thanks to Ian
  Johnson for sending an example that nicely illustrated this
  problem.

  Fixed system function [47mio?[0m for the case that formal parameter [47mcommentp[0m
  is [47mt[0m and [47mvars[0m is non-empty.  Thanks to David Rager for bringing to
  our attention the fact that [47mio?[0m was broken for such a combination
  of parameters.

  Not exactly a bug fix, but: [47m[defun-sk][0m was breaking when a [47m:[0m[47m[guard][0m
  is specified, so we have improved the documentation (see
  [defun-sk]) to explain how to provide verified guards for a
  function introduced by [47m[defun-sk][0m.  Thanks to Jared Davis for
  bringing this issue to our attention.

  Made a fix to the handling of interrupts, which in rare cases might
  have left one in a state where all subsequent proof attempts were
  labeled as ``Aborting due to an interrupt''.

  Fixed [47m:[0m[47m[pso][0m and related utilities, so that when proof output is
  redirected to a file, all summary output goes to that file rather
  than to the terminal.

  (GCL on Windows only) Removed an inappropriate check, resulting in an
  error about ``pathname-device,'' that could prevent Windows GCL
  builds of ACL2.  Thanks to Camm Maguire for reporting this problem
  and a helpful discussion.

  (Windows only) Modified the computation of canonical pathnames to
  avoid issues of case-insensitivity, in particular for the drive
  (e.g., [47m\"C:\"[0m vs. [47m\"c:\"[0m).  Thanks to Harsh Raju Chamarthi for
  reporting this issue and helping with its debugging.

  (Windows only) The value of [47m(@ distributed-books-dir)[0m no longer will
  be missing the Windows drive prefix, for example, [47m\"C:\"[0m.  Thanks to
  Harsh Raju Chamarthi for reporting this issue and helping with its
  debugging.

  [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m

  See the {log entries |
  http://code.google.com/p/acl2-books/source/list} for a record of
  books changed or added since the preceding release, with log
  entries.

  Modified [47mbooks/Makefile-generic[0m by adding a new [47mBOOKS_SKIP_COMP[0m
  variable, which is used in [47mMakefile[0ms in some subdirectories of
  [47mbooks/[0m, in order to avoid errors when compiling certified books for
  multiple Lisps.

  [31;1mEMACS SUPPORT[0m

  Distributed file [47memacs/emacs-acl2.el[0m has been modified so that the
  forms [47mcontrol-t e[0m and [47mcontrol-t control-e[0m now pick up package
  markers (see [sharp-bang-reader]), in the following sense: if the
  top-level form is preceded by a line starting with [47m#![0m, then that
  line is included in the inserted string.  Thanks to Jared Davis for
  suggesting this enhancement and providing a preliminary
  implementation.

  [31;1mEXPERIMENTAL VERSIONS[0m

  For the [47mHONS[0m version there have been some changes to [47m[memoize][0m:

      [47m[Memoize][0m accepts a new keyword, [47m:recursive[0m, that is a synonym for
      the existing keyword [47m:inline[0m.  Thanks to Sol Swords for
      requesting this addition.  Moreover, it is now enforced that
      these keywords have Boolean values.

      [47m[Memoize][0m may now be called on [47m:[0m[47m[program][0m mode functions.  Thanks to
      Sol Swords for requesting this enhancement.

      A bug has been fixed.  Now, if [47m[memoize][0m is called with a
      [47m:condition-fn[0m (with value other than [47mnil[0m or [47mt[0m), then the
      [guard] of the memoized function and the [47m:condition-fn[0m must be
      the same.  Previously, one could exploit the lack of such a
      check to get a hard Lisp error, for example as follows.

        (defun f (x) (declare (xargs :guard t)) x)
        (defun cf (x) (declare (xargs :guard (consp x))) (car x))
        (memoize 'f :condition-fn 'cf)
        (f 3)

      Memoization is now illegal for built-in functions that use underlying
      raw Lisp in their implementations.  To see why, consider the
      form [47m(gc$)[0m, which is a macro call expanding to [47m(gc$-fn nil)[0m.
      Previously, after evaluation of [47m(memoize 'gc$-fn)[0m, a call of
      [47mgc$[0m would no longer call the garbage collector, which had been
      invoked by raw Lisp code.  Now, evaluation of [47m(memoize 'gc$-fn)[0m
      causes an error.")
 (NOTE-4-1{R}
  (RELEASE-NOTES)
  "ACL2 Version 4.1(r) (September, 2010) Notes

  Please see [note-4-1] for changes in Version 4.1 of ACL2.")
 (NOTE-4-2
  (RELEASE-NOTES)
  "ACL2 Version 4.2 (January, 2011) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 4.2 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, distributed books, Emacs
  support, and experimental versions.  Each change is described in
  just one category, though of course many changes could be placed in
  more than one category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  The [47m[accumulated-persistence][0m utility can now do finer-grained
  tracking, providing data for individual hypotheses and the
  conclusion of a rule.  See [accumulated-persistence].  To try this
  out, evaluate the form [47m(accumulated-persistence :all)[0m; then see
  [accumulated-persistence] for a discussion of display options using
  [47mshow-accumulated-persistence[0m.  Thanks to Dave Greve for suggesting
  this new capability and collaborating on its design and
  implementation.

  The [47m[defattach][0m utility now permits the use of [47m:[0m[47m[program][0m mode
  functions, though this requires the use of a trust tag (see
  [defttag]).  See [defattach] and for discussion of the new
  capability, see [defproxy], which explains how part of this change
  involves allowing [47m:[0m[47m[program][0m mode functions to be declared
  [non-executable].

  Redefinition (see [ld-redefinition-action]) is no longer permitted
  for functions that have attachments (see [defattach]).  In such
  cases, the attachment must be removed first, e.g. with [47m(defattach
  foo nil)[0m.

  Made small changes to [47m[mv-nth][0m and [47m[defun-sk][0m in order to permit
  guard verification of functions introduced with more than one
  quantified variable in a [47m[defun-sk][0m form.  The change to [47m[mv-nth][0m
  is to weaken the [guard] by eliminating the requirement that the
  second argument satisfy [47m[true-listp][0m, and replacing the call of
  [47m[endp][0m in the definition body by a corresponding call of [47m[atom][0m.
  The new definition of [47m[mv-nth][0m is thus logically equivalent to the
  old definition, but with a weaker guard.  Thanks to Sol Swords for
  sending the following example, for which the final [47m[verify-guards][0m
  form had failed but now succeeds.

    (defstub foo (a b c) nil)
    (defun-sk forall-a-b-foo (c)
       (declare (xargs :guard t :verify-guards nil))
       (forall (a b) (foo a b c)))
    (verify-guards forall-a-b-foo)

  The implementations of [47m[prog2$][0m, [47m[time$][0m, [47m[with-prover-time-limit][0m,
  [47m[with-guard-checking][0m, [47m[mbe][0m (and [47m[must-be-equal][0m), and [47m[ec-call][0m
  have changed.  See the discussion below of the new utility,
  [47m[return-last][0m.  A consequence is that [47m[trace$][0m is explicitly
  disallowed for these and related symbols, which formerly could
  cause hard Lisp errors, because they are now macros.  Tracing of
  return-last is also disallowed.  Another consequence is that time$
  now prints a more abbreviated message by default, but a version of
  the old behavior can be obtained with [47m:mintime nil[0m.

  The following utilities no longer print an observation about raw-mode
  transitions: [47mset-raw-mode-on[0m, [47m[set-raw-mode-on!][0m, [47m[set-raw-mode][0m,
  and [47mset-raw-mode-off[0m.  Thanks to Jared Davis for suggestion this
  change in the case of [47m[include-book][0m (which proved awkward to
  restrict to that case).

  The system function [47mtranslate-and-test[0m now permits its [47mLAMBDA[0m form to
  refer to the variable [47mWORLD[0m, which is bound to the current ACL2
  logical [world].

  Modified abort handling to avoid talking about an interrupt when the
  error was caused by a Lisp error rather than an interrupt.

  The value of the constant [47m*acl2-exports*[0m, which is still a list, has
  been extended significantly, though only with the addition of
  symbols that one might reasonably have expected all along to belong
  to this list.  A new distributed book,
  [47mbooks/misc/check-acl2-exports.lisp[0m, checks (at certification time)
  that no documented constant, macro, or function symbol in the
  [47m\"ACL2\"[0m package has been accidentally omitted from [47m*acl2-exports*[0m.
  Thanks to Dave Greve for helpful discussions related to this
  change.

  Improved the built-in `[47muntranslate[0m' functions to produce [47mlet*[0m
  expressions when appropriate (more to help with tools that call
  [47muntranslate[0m and the like, than to help with proof output).

  The utility [47m[redo-flat][0m now works for [47m[certify-book][0m failures, just
  as it continues to work for failures of [47m[encapsulate][0m and [47m[progn][0m.

  The following only affects users who use trust tags to add to list
  values of either of the [47m[state][0m global variables
  [47mprogram-fns-with-raw-code[0m or [47mlogic-fns-with-raw-code[0m.  For
  functions that belong to either of the above two lists, [47mtrace$[0m will
  supply a default value of [47m:fncall[0m to keyword [47m:notinline[0m, to avoid
  discarding raw-Lisp code for the function.

  The [guard] of the macro [47m[intern][0m has been strengthened so that its
  second argument may no longer be either the symbol
  [47m*main-lisp-package-name*[0m or the string [47m\"COMMON-LISP\"[0m.  That change
  supports another change, namely that the following symbols in the
  [47m\"COMMON-LISP\"[0m package are no longer allowed into ACL2: symbols in
  that package that are not members of the list constant
  [47m*common-lisp-symbols-from-main-lisp-package*[0m yet are imported into
  the [47m\"COMMON-LISP\"[0m package from another package.  See [pkg-imports]
  and see [symbol-package-name].  To see why we made that change,
  consider for example the following theorem, which ACL2 was able to
  prove when the host Lisp is GCL.

    (let ((x \"ALLOCATE\") (y 'car))
      (implies (and (stringp x)
                    (symbolp y)
                    (equal (symbol-package-name y)
                           \"COMMON-LISP\"))
               (equal (symbol-package-name (intern-in-package-of-symbol x y))
                      \"SYSTEM\")))

  Now suppose that one includes a book with this theorem (with
  [47m:[0m[47m[rule-classes][0m [47mnil[0m), using an ACL2 built on top of a different
  host Lisp, say CCL, that does not import the symbol
  [47mSYSTEM::ALLOCATE[0m into the [47m\"COMMON-LISP\"[0m package.  Then then one can
  prove [47mnil[0m by giving this theorem as a [47m:use[0m hint.

  The axioms introduced by [47m[defpkg][0m have changed.  See the discussion
  of [47m[pkg-imports][0m under ``NEW FEATURES'' below.

  The error message for free variables (e.g., in definition bodies and
  guards) now supplies additional information when there are
  governing IF conditions.  Thanks to Jared Davis for requesting this
  enhancement and collaborating in its design.

  The command [47m:[0m[47m[redef-][0m now turns off redefinition.

  Improved proof output in the case of a [47m:[0m[47m[clause-processor][0m hint that
  proves the goal, so that the clause-processor function name is
  printed.

  The [47m[proof-builder][0m command `[47mthen[0m' now stops at the first failure (if
  any).

  It is no longer permitted to submit definitions in [47m:logic[0m mode for
  merely part of an existing [47m[mutual-recursion][0m event.  Such an
  action left the user in an odd state and seemed a potential
  soundness hole.

  The function [47m[break$][0m is now in [47m:[0m[47m[logic][0m mode.  Thanks to Jared Davis
  for requesting this enhancement.

  The macro [47m[verify-termination][0m now provides clearer output in the
  case that it is redundant.  More important perhaps, as a courtesy
  it now causes an error when applied to a constrained function,
  since presumably such an application was unintended (as the
  constrained function could never have been in [47m:[0m[47m[program][0m mode).
  Note that if one desires different behavior, one can create one's
  own version of [47m[verify-termination][0m (but with a different name).

  Improved the [guard]s for the following functions, often weakening
  them, to reflect more precisely the requirements for calling [47m[eq][0m:
  [47malist-difference-eq[0m, [47mintersection-eq[0m, [47mintersection1-eq[0m,
  [47m[intersectp-eq][0m, [47mnot-in-domain-eq[0m, [47mset-difference-assoc-eq[0m,
  [47mset-equalp-eq[0m, and [47m[union-eq][0m.  Thanks to Jared Davis for pointing
  out this issue for [47m[intersectp-eq][0m.

  (CCL only) Made a change that can reduce the size of a compiled file
  produced by [47m[certify-book][0m when the host Lisp is CCL, by discarding
  source information (for example, discarding [47m[local][0m events).

  [31;1mNEW FEATURES[0m

  See the discussion above about new statistics that can be gathered by
  the [47m[accumulated-persistence][0m utility.

  A new hint, [47m:[0m[47m[instructions][0m, allows use of the [proof-builder] at the
  level of [hints] to the prover.  Thanks to Pete Manolios for
  requesting this feature (in 2001!).  See [instructions].

  (For system hackers) There are new versions of system functions
  [47mtranslate1[0m and [47mtranslate[0m, namely [47mtranslate1-cmp[0m and [47mtranslate-cmp[0m
  respectively, that do not take or return [47m[state][0m.  See the Essay on
  Context-message Pairs for relevant information.  Thanks to David
  Rager for collaborating on this enhancement.

  A new utility, [47m[return-last][0m, is now the unique ACL2 function that
  can pass back a multiple value result from one of its arguments.
  Thus, now the following are macros whose calls ultimately expand to
  calls of [47m[return-last][0m: [47m[prog2$][0m, [47m[time$][0m,
  [47m[with-prover-time-limit][0m, [47m[with-guard-checking][0m, [47m[mbe][0m (and
  [47m[must-be-equal][0m), and [47m[ec-call][0m.  With an active trust tag, an
  advanced user can now write code that has side effects in raw Lisp;
  see [return-last].  Thanks to Jared Davis for requesting this
  feature.

  A new function, [47m[pkg-imports][0m, specifies the list of symbols imported
  into a given package.  The axioms for [47m[defpkg][0m have been
  strengthened, taking advantage of this function.  Now one can prove
  theorems using ACL2 that we believe could not previously be proved
  using ACL2, for example the following.

    (equal (symbol-package-name (intern-in-package-of-symbol str t))
           (symbol-package-name (intern-in-package-of-symbol str nil)))

  Thanks to Sol Swords for a helpful report, which included the example
  above.  See [pkg-imports] and see [defpkg].

  Added function [47m[no-duplicatesp-eq][0m.

  Added a new hint keyword, [47m:[0m[47m[backchain-limit-rw][0m, to control the level
  of backchaining for [rewrite], [meta], and [linear] rules.  This
  overrides, for the current goal and (as with [47m:[0m[47m[in-theory][0m hints)
  descendant goals, the default [backchain-limit] (see
  [set-backchain-limit]).  Thanks to Jared Davis for requesting this
  feature.

  Support is now provided for creating and certifying books that do not
  depend on trust tags, in the case that the only use of trust tags
  is during [47m[make-event][0m expansion.  See [set-write-ACL2x].  Thanks
  to Sol Swords for reporting a couple of bugs in a preliminary
  implementation.

  Function [47m(file-write-date$ filename state)[0m has been added, giving the
  write date of the given file.

  See [forward-chaining-reports] for how to get new reports on the
  forward chaining activity occurring in your proof attempts.  Thanks
  to Dave Greve for inspiring the addition of this utility.

  It is now possible to use ACL2's printing utilities to return
  strings, by opening output channels to the keyword [47m:STRING[0m rather
  than to filenames.  See [io].  Thanks to Jared Davis for a helpful
  conversation that led us to add this feature.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  We have slightly improved the handling of [47m:[0m[forward-chaining] rules
  that contain free variables.  Formerly, such rules might fire only
  once, when the first match for a free variable is discovered, and
  would not fire again even if subsequent forward chaining made
  available another match.  This made it difficult to predict whether
  a rule with free variables would fire or not, depending as it did
  on the order in which newly derived conclusions were added.  The
  new handling is a little slower but more predictable.  Thanks to
  Dave Greve for sending a helpful example that led us to consider
  making such an improvement.

  We have slightly improved the so-called ``[type-set]'' heuristics to
  work a bit harder on terms of the form [47m(rec term)[0m, where [47mrec[0m is a
  so-called ``compound-recognizer'' function, that is, a function
  with a corresponding enabled [47m:[0m[47m[compound-recognizer][0m rule.  Thanks
  to Jared Davis for sending a helpful example (found, in essence, in
  the modified function [47mtype-set-rec[0m, source file [47mtype-set-b.lisp[0m).

  We made three heuristic improvements in the way contexts (so-called
  ``type-alists'') are computed from goals (``clauses'').  Although
  these changes did not noticeably affect timing results for the ACL2
  regression suite, they can be very helpful for goals with many
  hypotheses.  Thanks to Dave Greve for sending a useful example (one
  where we found a goal with 233 hypotheses!).

  The algorithm for substituting alists into terms was modified.  This
  change is unlikely to affect many users, but in one example it
  resulted in a speed-up of about 21%.  Thanks to Dave Greve for
  supplying that example.

  Sped up [47m[include-book][0m a bit by memoizing checksums of symbols.
  (This change pertains to ``normal'' ACL2 only, not the [47m[hons][0m
  version (see [hons-and-memoization], where such memoization already
  occurred.)  We found about a 23% speed-up on an example from Dave
  Greve.

  Made a small change to the algorithm used to prove hypotheses of
  [47m:[0m[47m[type-prescription][0m rules (ACL2 source function
  [47mtype-set-relieve-hyps[0m).  One change avoids a linear walk through
  the context (the ``type-alist'' structure), while the other could
  avoid storing unnecessary [47m[force][0md assumptions (into the so-called
  ``tag-tree'').

  [31;1mBUG FIXES[0m

  Fixed a long-standing soundness bug caused by the interaction of
  [47m[force][0md hypotheses with destructor [elim]ination.  The fix was to
  avoid using forcing when building the context (so-called
  ``type-alist'') when the goal is considered for destructor
  elimination; those who are interested can see a discussion in
  source function [47meliminate-destructors-clause1[0m, which includes a
  proof of [47mnil[0m that no longer succeeds.  A similar fix was made for
  generalization, though we have not exploited the previous code to
  prove [47mnil[0m in that case.

  Fixed a bug that allowed book certification to ignore [47mskip-proofs[0m
  around [47m[encapsulate][0m [events].  Thus, a book could contain an event
  of the form [47m(skip-proofs (encapsulate ...))[0m, and a call of
  [47m[certify-book][0m on that book could succeed even without supplying
  keyword [47m:skip-proofs-okp t[0m.  This bug was introduced in Version 3.5
  (May, 2009).

  Fixed a bug that could occur when including a book that attempts to
  redefine a function as a macro, or vice-versa.  (For details of the
  issue, see the comment in the definition of variable
  [47m*hcomp-fn-macro-restore-ht*[0m in source file [47mother-events.lisp[0m.)

  (Windows only) Fixed handling of the Windows drive so that an
  executable image saved on one machine can be used on another, even
  with a different drive.  Thanks to Harsh Raju Chamarthi for
  reporting this issue and doing a lot of testing and collaboration
  to help us get this right.

  Made a change to avoid possible low-level errors, such as bus errors,
  when quitting ACL2 by calling [47m[good-bye][0m or its synonyms.  This was
  occurring in CCL, and we are grateful to Gary Byers for helping us
  find the source of those errors (which basically was that ACL2 was
  attempting to quit while already in the process of quitting).

  Fixed a bug in [47m[with-guard-checking][0m, which was being ignored in
  function bodies.

  Fixed a bug in [47m[top-level][0m, which was not reverting the logical
  [world] when an error resulted from evaluation of the given form.
  Thanks to Jared Davis for bringing this bug to our attention.

  Fixed a long-standing bug (back through Version 2.7) that was
  discarding changes to the connected book directory (see [cbd]) when
  exiting and then re-entering the top-level ACL2 loop (with [47m[lp][0m).

  In some host Lisps, it has been possible to be in a situation where
  it is impossible to interrupt checkpoint printing during the
  summary.  We had thought this solved when the host Lisp was CCL,
  but Sol Swords sent us an example (for which we are grateful)
  illustrating that this behavior could occur.  This has been fixed.

  Fixed a bug in a proof obligation generated for [47m:[0m[47m[meta][0m and
  [47m:[0m[47m[clause-processor][0m rules, that the [guard] on the metafunction or
  clause-processor function, [47mfn[0m, holds under suitable assumptions.
  Those assumptions include not only that the first argument of [47mfn[0m
  satisfies [47m[pseudo-termp][0m, but also that all [stobj] inputs satisfy
  the corresponding stobj recognizer predicates.  We had erroneously
  considered stobj outputs of [47mfn[0m instead of stobj inputs.  Thanks to
  Sol Swords for bringing this bug to our attention with a simple
  example, and correctly pointing us to the bug in our code.

  Fixed the following bugs in [47m[defattach][0m.  We hadn't always been
  applying the full functional substitution when generating guard
  proof obligations.  We had been able to hit an assertion when
  reattaching to more than one function.  Attachment was permitted in
  the case of an untouchable function (see [remove-untouchable]).
  Finally, the guard proof obligation could fail in the case that the
  two functions have different formal parameter lists, as in the
  following example.

    (encapsulate
     ((foo (x) x :guard (symbolp x)))
     (local (defun foo (x) x)))
    (defun bar (x2)
      (declare (xargs :guard (symbolp x2)))
      x2)
    (defattach foo bar)

  Fixed a raw Lisp error that could be caused by including a book using
  [47m[make-event][0m to define a function symbol in a locally-introduced
  package.  An example appears in a comment in ACL2 source function
  [47mwrite-expansion-file[0m.

  Made a change that can prevent an error near the end of book
  certification when the underlying Host Lisp is Allegro Common Lisp,
  in the case that environment variable [47mACL2_SYSTEM_BOOKS[0m has been
  set to the name of a directory with a parent that is a soft link.
  Thanks to Dave Greve for supplying an example to led us to this
  fix, which involves avoiding Allegro CL's implementation of the
  Common Lisp function, [47mtruename[0m.

  Fixed a bug that was failing to substitute fully using bindings of
  free variables in [47m[force][0md hypotheses.  A related change is that
  instead of binding such a free variable to a new variable of the
  form [47m???-Y[0m, the new variable is now of the form [47mUNBOUND-FREE-Y[0m.

  Fixed a bug that could inhibit the printing of certain theory
  warnings (and probably, in the other direction, cause inappropriate
  such printing).

  We eliminated excessive [47m\"Raw-mode\"[0m warnings about
  [47m[add-include-book-dir][0m that could be generated by the use of
  raw-mode during [47m[include-book][0m.  Thanks to Dave Greve for bringing
  this issue to our attention.

  Fixed the printing of results from forms within an [47m[encapsulate][0m, so
  that they are abbreviated according to the [47m[ld-evisc-tuple][0m.

  It is now possible to evaluate [stobj]-related forms after evaluating
  [47m:[0m[47m[set-guard-checking][0m [47m:none[0m or [47m:[0m[47m[set-guard-checking][0m [47mnil[0m, even in
  cases where such evaluation formerly caused a guard violation due
  to a bug in ACL2.  Here is an example of an error that no longer
  occurs.

    ACL2 !>(defstobj st fld)

    Summary
    Form:  ( DEFSTOBJ ST ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     ST
    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 >(fld st)

    ACL2 Error in TOP-LEVEL:  The guard for the function call (FLD ST),
    which is (STP ST), is violated by the arguments in the call (FLD ST).
    [... etc. ...]

  You can understand how things now work by imagining that when a
  function introduced by [47m[defstobj][0m is called, [47m[guard][0m-checking
  values of [47m:none[0m or [47mnil[0m are temporarily converted to [47mt[0m.  Thanks to
  Pete Manolios, Ian Johnson, and Harsh Raju Chamarthi for requesting
  this improvement.

  Fixed a bug in which the wrong attachment could be made when the same
  function has an attachment in a book and another in the
  certification world of that book (possibly even built into ACL2),
  if the load of a compiled file is aborted because a sub-book's
  compiled file is missing.  The bug has been present since the time
  that [47m[defattach][0m was added (Version_4.0).  An example may be found
  in a comment in the [47m[deflabel][0m for [47mnote-4-2[0m (ACL2 source file
  [47mld.lisp[0m).

  The [47m:[0m[47m[doc][0m and related utilities now cause a clean error when
  provided other than a symbol.  Thanks to Jared Davis for pointing
  out the raw Lisp error that had occurred in such cases.

  It had been the case that in raw-mode (see [set-raw-mode]), it was
  possible to confuse [47m[include-book][0m when including a book in a
  directory different from the current directory.  This has been
  fixed.  Thanks to Hanbing Liu for bringing this problem to our
  attention with a small example.

  [31;1mNEW AND UPDATED BOOKS AND RELATED INFRASTRUCTURE[0m

  Many changes have been made to the distributed books, thanks to an
  active ACL2 community.  You can contribute books and obtain updates
  between ACL2 releases by visiting the ACL2 Books web page.  [Note:
  This release note is obsolete, as it referenced the now-invalid
  URL, [47mhttp://acl2-books.googlecode.com/[0m.]

  There is new [47mMakefile[0m support for certifying just some of the
  distributed books.  See [books-certification-classic], in
  particular discussion of the variable [47mACL2_BOOK_DIRS[0m.  Thanks to
  Sandip Ray for requesting this enhancement.

  The [documentation] for [47m[make-event][0m now points to a new book,
  [47mbooks/make-event/defrule.lisp[0m, that shows how [47mmake-event[0m can be
  used to do macroexpansion before generating [events].  Thanks to
  Carl Eastlund for useful interaction on the acl2-help mailing list
  that led us to add this example.

  [31;1mEMACS SUPPORT[0m

  Incorporated a version of changes from Jared Davis to the [47mcontrol-t f[0m
  emacs utility (distributed file [47memacs/emacs-acl2.el[0m), so that one
  can fill a format string from anywhere within the string.

  [31;1mEXPERIMENTAL VERSIONS[0m

  We refrain from listing changes here to experimental versions, other
  than an enhancement to the [hons] version that can reduce sizes of
  [certificate] files, by applying [47m[hons-copy][0m to introduce structure
  sharing (ACL2 source function [47mmake-certificate-file1[0m).")
 (NOTE-4-2{R}
  (RELEASE-NOTES)
  "ACL2 Version 4.2(r) (January, 2011) Notes

  Please see [note-4-2] for changes in Version 4.2 of ACL2.")
 (NOTE-4-3
  (RELEASE-NOTES)
  "ACL2 Version 4.3 (July, 2011) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 4.2 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, changes at the system level and
  to distributed books, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  Significant changes have been made for list-processing primitives
  such as [47m[member][0m and [47m[assoc][0m; see [equality-variants].  In summary:
  instead of separate functions based on [47m[eq][0m, [47m[eql][0m, and [47m[equal][0m,
  there is essentially just one function, which is based on [47m[equal][0m;
  the [47m[eq][0m and [47m[eql][0m variants are logically just the [47m[equal][0m variant.
  For example, [47m[member-eq][0m and [47m[member][0m are macros that generate
  corresponding calls of [47m[member-equal][0m in the logic, although in raw
  Lisp they will execute using tests [47m[eq][0m and [47m[eql][0m, respectively.
  References to any of these in logical contexts such as [theories]
  are now references to the function based on [47m[equal][0m; for example,
  the hint [47m:in-theory (disable member)[0m is completely equivalent to
  the hint [47m:in-theory (disable member-equal)[0m.  Distributed books have
  been modified as necessary to accommodate this change.  While the
  need for such changes was relatively infrequent, changes were for
  example needed in contexts where terms are manipulated directly;
  for example, [47m[defevaluator][0m needs to mention [47m[member-equal][0m rather
  than [47m[member][0m, just as it was already the case to mention, say,
  [47m[binary-append][0m rather than [47m[append][0m.  Again, see
  [equality-variants] for more information about equality variants.

  A few improvements were made in support of the modified treatment of
  equality variants discussed above.  The changes include the
  following.

      o We now allow the use of macro aliases (see [macro-aliases-table] in
      [47m:trigger-fns[0m of rules (see [rule-classes]).

      o We now remove so-called ``guard holders'' (including calls of
      [47m[return-last][0m, hence of [47m[mbe][0m) in [47m:trigger-terms[0m of rules.

      o We also remove guard holders in formulas of [47m:[0m[47m[congruence][0m and
      [47m[type-prescription][0m rules.

      o Macros [47munion-eq[0m and [47mintersection-eq[0m can now take any positive
      number of arguments, and [47m[union-eq][0m can take zero arguments.
      (Thanks to Jared Davis for requesting this enhancement.)  The
      same can be said for new macros [47m[union$][0m and [47m[intersection$][0m,
      respectively.

      o A few changes were made to built-in theorems from source file
      [47maxioms.lisp[0m, in particular disabling [47m:[0m[47m[type-prescription][0m rule
      [47mconsp-assoc-equal[0m (formerly two enabled rules, [47mconsp-assoc-eq[0m
      and [47mconsp-assoc[0m) but adding this theorem as a [47m:forward-chaining[0m
      rule, and similarly for
      [47mtrue-list-listp-forward-to-true-listp-assoc-equal[0m (and
      eliminating rule
      [47mtrue-list-listp-forward-to-true-listp-assoc-eq[0m; and disabling
      rule [47mtrue-listp-cadr-assoc-eq-for-open-channels-p[0m.  Also,
      theorem [47mall-boundp-preserves-assoc[0m has been renamed to
      [47mall-boundp-preserves-assoc-equal[0m and also strengthened.

      o Some [guard]s were slightly improved (logically weaker or the
      same).

  Improved [47mget-output-stream-string$[0m to allow for a context and to do
  genuine error printing instead of using [47m[cw][0m.  See [io].

  Added the symbols [47m[flet][0m and [47m[with-local-stobj][0m to [47m*acl2-exports*[0m.

  A small change was made to the processing of more than one [47m:[0m[47m[guard][0m
  declaration for the same function.  In particular, a guard of [47mt[0m is
  essentially ignored.

  Attachments are now allowed during evaluation of the first argument
  of [47m[prog2$][0m even in contexts (such as proofs) during which the use
  of attachments is normally prohibited.  More generally, the second
  of the three arguments of [47m[return-last][0m has this property, except
  in the case of [47m[mbe][0m (or related macros like [47m[mbe1][0m), where the
  [47mexec[0m argument may provide the value.  Thanks to Sol Swords for
  useful discussions leading us to implement this enhancement.

  The restriction has been removed that prohibited the use of [47m[mbe][0m
  inside [47m[encapsulate][0m [events] with a non-empty [signature].  This
  restriction was introduced in Version 3.4, but has not been
  necessary since Version 4.0, when we first started disallowing
  [guard] verification for functions introduced non-[local]ly inside
  such [47m[encapsulate][0m events.

  We weakened the checks involving common ancestors for evaluator and
  [meta] (and [clause-processor]) functions (see
  [evaluator-restrictions]) so that except in the [47m[mbe][0m case, the
  next-to-last argument of [47m[return-last][0m is not considered.  Thanks
  to Sol Swords for bringing this issue to our attention.

  The macro [47m[append][0m no longer requires at least two arguments.  Thanks
  to Dave Greve for requesting this enhancement.

  (Mostly for system hackers) Now, [47m[break-on-error][0m breaks at a more
  appropriate (earlier) time for certain system functions that do not
  return state, such as [47mtranslate11[0m.  Thanks to David Rager for
  requesting this improvement.

  [47m[Show-accumulated-persistence][0m may take a new argument, [47m:runes[0m, which
  simply causes an alphabetical list of [rune]s to be printed out.

  Improved [47m[trace$][0m so that [47m:entry[0m, [47m:exit[0m, and [47m:cond[0m forms may
  reference [47mstate[0m even if the function being traced does not include
  [47mstate[0m as a formal.

  The system function [47macl2x-expansion-alist[0m now takes a second
  argument, namely [47m[state][0m.  This change allows for more flexibility
  in the sorts of attachments that can be made to this function (see
  [defattach]).  Thanks to Jared Davis and Sol Swords for requesting
  this enhancement and providing a preliminary implementation.

  An obscure [proof-builder] change, unlikely to affect users, replaces
  the state global variables [47merp[0m, [47mval[0m, [47mprint-macroexpansion-flg[0m, and
  [47mprint-prompt-and-instr-flg[0m by [47mpc-erp[0m, [47mpc-val[0m,
  [47mpc-print-macroexpansion-flg[0m, and [47mpc-print-prompt-and-instr-flg[0m,
  respectively.

  [State] globals [47mfmt-hard-right-margin[0m and [47mfmt-soft-right-margin[0m are
  now untouchable (see [set-fmt-hard-right-margin] and see
  [push-untouchable]).  If you bind these [47mstate[0m globals with
  [47m[state-global-let*][0m, then you will need to do so with appropriate
  setters to restore their values, for example as follows.

    (state-global-let*
     ((fmt-hard-right-margin 500 set-fmt-hard-right-margin)
      (fmt-soft-right-margin 480 set-fmt-soft-right-margin))
     ...)

  The error message has been improved for the case of evaluating an
  undefined function that has an attachment (see [defattach]).
  Thanks to Jared Davis for sending the following example, which
  illustrates the additional part of the message.

    ACL2 !>(defstub foo (x) t)
    [[... output omitted ...]]
    ACL2 !>(defattach foo identity)
    [[... output omitted ...]]
    ACL2 !>(defconst *x* (foo 3))

    ACL2 Error in ( DEFCONST *X* ...):  ACL2 cannot ev the call of undefined
    function FOO on argument list:

    (3)

    Note that because of logical considerations, attachments (including
    IDENTITY) must not be called in this context.

    [[... additional output omitted ...]]

  The directory string supplied to [47m[add-include-book-dir][0m no longer
  must terminate with the `[47m/[0m' character, as had been required in some
  Lisp implementations.  Thanks to Sol Swords for bringing this issue
  to our attention.

  We no longer print induction schemes with [gag-mode]; use [47m:[0m[47m[pso][0m if
  you want to see them.  Thanks to Dave Greve for this suggestion.

  It is now legal to supply a constant for a [stobj] array dimension.
  See [defstobj].  Thanks to Warren Hunt for requesting this
  enhancement.

  We cleaned up a few issues with [47m[defpkg][0m.

      o It is no longer illegal to submit a [47m[defpkg][0m form in raw-mode (see
      [set-raw-mode]).  Thanks to Jun Sawada for reporting an example
      in which an [47m[include-book][0m form submitted in raw-mode caused an
      error because of a `hidden' [47m[defpkg][0m form (see
      [hidden-defpkg]).  There will no longer be an error in such
      cases.

      o It had been the case that [local]ly including a book could make it
      possible to use a package defined by that book.  Consider for
      example the following book, [47mfoo.lisp[0m.

        (in-package \"ACL2\")
        (local (include-book \"arithmetic/top\" :dir :system))

      After certifying this book, it had been possible to admit the
      following events in a new session.

        (include-book \"foo\")
        (defconst acl2-asg::*foo* 3)
        (defconst *c* 'acl2-asg::xyz)

      In Version_4.3, neither of these [47m[defconst][0m events is admitted.

      o A hard Lisp error is now avoided that had been possible in rare
      cases when including books with hidden packages (see
      [hidden-defpkg]). An example may be found in a comment in the
      [47m[deflabel][0m for [47mnote-4-3[0m (in ACL2 source file [47mld.lisp[0m).

  The undocumented (but sometimes useful) functions [47mpackn1[0m and [47mpackn[0m
  are now [guard]-verified [47m:[0m[47m[logic][0m mode functions.  Thanks to Sandip
  Ray for requesting this enhancement.

  It had been the case that when including a book, functions defined in
  the book's certification [world] (that is, in its [portcullis]
  [command]s) were typically not given compiled code.  That has been
  fixed.

  The commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pl2][0m have been improved, primarily by
  printing information for more rule classes.  See [pl] and see
  [pl2].  See also the item below about the new [proof-builder]
  command, [47mshow-type-prescriptions[0m.

  [31;1mNEW FEATURES[0m

  New macros [47m[mv?-let][0m and [47m[mv?][0m extend the functionality of [47m[mv-let][0m
  and [47m[mv][0m (respectively) to the case of a single value.

  Macro [with-local-state] is available for system programmers who wish
  bind [47m[state][0m locally, essentially using [with-local-stobj].  But
  this should only be done with extreme care, and it requires an
  active trust tag; see [with-local-state].

  Formatted printing functions now have analogues that print to strings
  and do not take an output channel or [47m[state][0m as arguments.  See
  [printing-to-strings].

  The system function [47mancestors-check[0m is now available for verified
  modification by users, i.e., attachment using [47m(defattach
  ancestors-check <your_function>)[0m.  Thanks to Robert Krug for
  providing the necessary proof support, which we modified only in
  small ways.

  New macros, [47mobservation-cw[0m and [47mwarning$-cw[0m, provide formatted
  printing of [47m[observation][0ms and warnings (respectively) without
  [47m[state][0m.  Thanks to Harsh Raju Chamarthi and David Rager for
  requests leading to these utilities.  [47mObservation-cw[0m is now used in
  some of the distributed books (thanks to Robert Krug for useful
  interaction for that).

  The [proof-builder] command [47mtype-alist[0m (see [proof-builder-commands])
  now takes an optional third argument that causes the production of
  forward-chaining reports (see [forward-chaining-reports]).  Thanks
  to Dave Greve for requesting such an enhancement.

  The reports generated by forward-chaining,
  [forward-chaining-reports], have been changed to indicate when a
  conclusion reached by forward chaining is [47mREDUNDANT[0m with respect to
  the type information already known.  Thanks to Dave Greve for
  suggesting this enhancement.

  The utility [47m[with-prover-time-limit][0m is now legal for [events] (see
  [embedded-event-form]).  For example, the following is now legal.

    (encapsulate
     ()
     (with-prover-time-limit
      2
      (defthm append-assoc
        (equal (append (append x y) z)
               (append x (append y z))))))

  The new utility [47m[with-prover-step-limit][0m is analogous to the utility
  [47m[with-prover-time-limit][0m, but counts ``prover steps'' rather than
  checking for time elapsed.  See [with-prover-step-limit].  Also see
  [set-prover-step-limit] to provide a default step-limit.  Note that
  just as [47m[with-prover-time-limit][0m may now be used to create
  [events], as discussed just above, [47m[with-prover-step-limit][0m may
  also be used to create [events].  Thanks to Carl Eastlund for
  requesting support for step-limits.

  The macro [47m[progn$][0m is analogous to [47m[prog2$][0m, but allows an arbitrary
  number of arguments.  For example:

    ACL2 !>:trans1 (progn$ (f1 x) (f2 x) (f3 x))
     (PROG2$ (F1 X) (PROG2$ (F2 X) (F3 X)))
    ACL2 !>

  Thanks to David Rager for contributing this macro.

  The macro [47m[defattach][0m may now be supplied the argument [47m:skip-checks
  :cycles[0m.  In this case, as with argument [47m:skip-checks t[0m, a trust
  tag is required (see [defttag]), and no logical claims are made.
  The effect is to avoid the usual check that the extended ancestor
  relation has no cycles (see [defattach]).  Thanks to Dave Greve for
  requesting this feature.

  You can now limit the printing of subgoal names when using
  [47m:[0m[47m[set-gag-mode][0m[47m :goals[0m.  See [set-print-clause-ids].  Thanks to
  Karl Hoech for a suggestion leading to this enhancement.

  A new [proof-builder] command, [47mshow-type-prescriptions[0m, or [47mst[0m for
  short, provides information about [47m:[0m[47m[type-prescription][0m rules that
  match a given term.  Thanks to Dave Greve for requesting this
  enhancement.  See also the item above about related improvements to
  commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pl2][0m.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  ACL2 now avoids some repeated attempts to rewrite hypotheses of
  rewrite rules.  See [set-rw-cache-state] for a discussion of this
  behavior and how to avoid it.  The default behavior has been
  observed to reduce by 11% the overall time required to complete a
  regression.  Here are the directories that had the top three time
  decreases and top three time increases, shown in seconds.

    -368 coi/gacc (1064 down to 696: decrease of 35%)
    -220 workshops/1999/ste (664 down to 444: decrease of 33%)
    -148 unicode (331 down to 183: decrease of 45%)
    ....
      +7 workshops/2002/cowles-flat/support (229 up to 236: increase of 3%)
      +8 workshops/1999/ivy/ivy-v2/ivy-sources (508 up to 516: increase of 2%)
     +12 workshops/2009/hardin/deque-stobj (78 up to 91: increase of 17%)

  The so-called ``ancestors check,'' which is used to limit
  backchaining, has been strengthened so that two calls of [47m[equal][0m
  are considered the same even if their arguments appear in the
  opposite order.  Thanks to Robert Krug for providing an
  implementation and a useful discussion.

  The check for [irrelevant-formals] in processing of [47m[defun][0ms has been
  made more efficient.  Thanks to Eric Smith for reporting this issue
  in 2001 (!) and thanks to Warren Hunt for recently sending an
  example.  For that example, we have seen the time for the
  [irrelevant-formals] check reduced from about 10 seconds to about
  0.04 seconds.

  (GCL only) The macro [47m[mv][0m has been modified so that certain fixnum
  boxing can be avoided.

  (Allegro CL only) We have set to [47mnil[0m four Allegro CL variables that
  otherwise enable storing of certain source information (for
  details, see the discussion of ``cross-referencing'' in ACL2 source
  file [47macl2-init.lisp[0m).  As a result of this change we have about a
  6% speedup on the regression suite, but a 27% time reduction on an
  example that includes a lot of books.

  Exhaustive matching for the case of [free-variables] has been
  extended to [type-prescription] rules, in analogy to the default
  setting [47m:match-free :all[0m already in place for [rewrite], [linear],
  and [forward-chaining] rules.  See
  [free-variables-type-prescription].  Thanks to Dave Greve for
  requesting this enhancement.

  [31;1mBUG FIXES[0m

  A soundness bug was fixed in some raw-Lisp code implementing the
  function, [47m[take][0m.  Thanks to Sol Swords for pointing out this bug
  with (essentially) the following proof of [47mnil[0m.

    (defthmd take-1-nil-logic
      (equal (take 1 nil) '(nil))
      :hints((\"Goal\" :in-theory (disable (take)))))
    (thm nil :hints ((\"Goal\" :use take-1-nil-logic)))

  Calls of [47m[mbe][0m in ``safe-mode'' situations --- i.e., during
  evaluation of [47m[defconst][0m, [47m[value-triple][0m, and [47m[defpkg][0m forms, and
  during macroexpansion --- are now guard-checked.  Thus, in these
  situations both the [47m:logic[0m and [47m:exec[0m forms will be evaluated, with
  an error if the results are not equal.  Formerly, only the [47m:logic[0m
  form was evaluated, which was a soundness bug that could be
  exploited to prove [47mnil[0m.  For such a proof and a bit of further
  explanation, see the example at the top of the comments for
  [47m(deflabel note-4-3 ..)[0m in ACL2 source file [47mld.lisp[0m.

  It had been possible to prove [47mnil[0m by proving the following theorem
  using ACL2 built on CCL and then proving its negation using ACL2
  built on a different host Lisp.

    (defthm host-lisp-is-ccl
      (equal (cdr (assoc 'host-lisp *initial-global-table*))
             :ccl)
      :rule-classes nil)

  This hole has been plugged by moving the setting of [47m'host-lisp[0m out of
  the constant [47m*initial-global-table*[0m.

  Fixed [47m[trace$][0m for arguments that are [stobj] accessors or updaters.
  It also gives an informative error in this case when the accessor
  or updater is a macro (because the introducing [47m[defstobj][0m event
  specified [47m:inline t[0m).

  Avoided a potential error that could occur when no user home
  directory is located.  Our previous solution for Windows simply
  avoided looking for ACL2 customization files (see
  [ACL2-customization]) and [47macl2-init.lsp[0m files in a user's home
  directory.  With this change, we handle such files the same for
  Windows as for non-Windows systems: we always look for ACL2
  customization files (see [ACL2-customization]) and [47macl2-init.lsp[0m
  files in a user's home directory, but only if such a directory
  exists.  Thanks to Hanbing Liu for reporting this issue.

  (GCL only) Fixed a bug that prevented the use of
  [47m[get-output-stream-string$][0m when the host Lisp is GCL.

  Fixed [47m[with-live-state][0m to work properly for executable counterparts
  (so-called ``*1*'' functions).

  Fixed a bug in the error message caused by violating the [guard] of a
  macro call.

  Fixed a bug in an error message that one could get when calling
  [47m[defattach][0m with argument [47m:skip-checks t[0m to attach to a [47m:[0m[47m[program][0m
  mode function symbol that was introduced with [47m[defun][0m.  (This is
  indeed an error, but the message was confusing.)  Thanks to Robert
  Krug for bringing this bug to our attention.

  Fixed a bug in the loop-checking done on behalf of [47m[defattach][0m, which
  could miss a loop.  For an example, see the comment about
  loop-checking in the comments for [47m(deflabel note-4-3 ..)[0m in ACL2
  source file [47mld.lisp[0m.

  Terms of the form [47m(hide <term>)[0m without free variables could be
  simplified, contrary to the purpose of [47m[hide][0m.  This is no longer
  the case, Thanks to Dave Greve for reporting this issue.

  An infinite loop could occur when an error was encountered in a call
  of [47m[wormhole-eval][0m, for example with the following form, and this
  has been fixed.

    (wormhole-eval 'demo
                   '(lambda ()
                      (er hard 'my-top \"Got an error!\"))
                   nil)

  Fixed a bug in detection of package redefinition.  While we have no
  example demonstrating this as a soundness bug, we cannot rule it
  out.

  Fixed a bug in the message produced by an erroneous call of [47m[flet][0m.
  Thanks to Jared Davis for reporting this bug and sending a helpful
  example.

  For a failed [47m[defaxiom][0m or [47m[defthm][0m event, we now avoid printing
  [rune]s that are used only in processing proposed rules to be
  stored, but not in the proof itself.  Thanks to Dave Greve for
  sending us an example that led us to make this fix.

  ACL2 did not reliably enforce the restriction against non-[47m[local][0m
  [47m[include-book][0m [events] inside [47m[encapsulate][0m events, as illustrated
  by the following examples.

    ; not permitted (as expected)
    (encapsulate () (include-book \"foo\"))

    ; permitted (as expected)
    (encapsulate () (local (include-book \"foo\")))

    ; formerly permitted (surprisingly); now, not permitted
    (local (encapsulate () (include-book \"foo\")))

  Moreover, the corresponding error message has been fixed.  Thanks to
  Jared Davis and Sandip Ray for relevant discussions.

  When [47m[include-book][0m is given a first argument that is not a string, a
  more graceful error now occurs, where previously an ugly raw Lisp
  error had occurred.  Thanks to Eric Smith for bringing this bug to
  our attention.

  Fixed a bug in an error message that was printed when an unexpected
  expression has occurred where a [47m[declare][0m form is expected.

  (Since all functions are compiled when the host Lisp is CCL or SBCL,
  the following bug fix did not occur for those host Lisps.)  After
  evaluation of [47m([0m[47m[set-compile-fns][0m[47m t)[0m, all defined functions are
  expected to run with compiled code; but this was not the case for
  functions exported from an [47m[encapsulate][0m event.  This has been
  fixed.

  It had been the case that the [47m:[0m[47m[puff][0m command was broken for
  [47m[include-book][0m form whose book had been certified in a world with
  an [47m[add-include-book-dir][0m event.  This has been fixed.

  Evaluation of [stobj] updaters (see [defstobj]) may no longer use
  attachments (see [defattach]).  This is a subtle point that will
  likely not affect many users.  Thanks to Jared Davis for bringing
  this issue to our attention; a slight variant of his example
  appears in a comment in ACL2 source function [47moneify-cltl-code[0m.

  It had been the case that even when a [stobj] creator function was
  declared to be untouchable (see [push-untouchable]), a
  [47m[with-local-stobj][0m form based on that same stobj was permitted.
  Now, such forms are not admitted.  Thanks to Jared Davis for a
  query leading to this fix.

  Fixed a buggy message upon [guard] violations, which was suggesting
  the use of [47m(set-guard-checking :none)[0m in some cases when
  guard-checking was already set to [47m:none[0m.

  It had been possible to get a hard Lisp error when computing with
  [47m[ec-call][0m in [books].  The following is an example of such a book,
  whose certification no longer causes an error.

    (in-package \"ACL2\")
    (defun f (x) x)
    (defconst *c* (ec-call (f 3)))
    (defun g (x) (cons x x))

  The command [47m:[0m[47m[pl2][0m, and also the [proof-builder] commands [47mrewrite[0m and
  [47mshow-rewrites[0m (and hence their respective aliases [47mr[0m and [47msr[0m), now
  take rule-id arguments that can be [47m:[0m[47m[definition][0m [rune]s.  These
  commands dealt with definition rules already, e.g.

    :pl2 (append x y) binary-append

  but they did not allow explicit specification of [47m:definition[0m runes,
  e.g.:

    :pl2 (append x y) (:definition binary-append)

  The following example illustrates a bug in the processing of
  (admittedly obscure) [hints] of the form [47m:do-not-induct name[0m, where
  [47mname[0m is not [47mt[0m, [47m:otf-flg-override[0m, [47m:otf[0m, or [47mnil[0m.  In this example,
  ACL2 had essentially ignored the hint and reverted to prove the
  original goal by induction, rather than to skip the goal
  temporarily as is expected for such hints.  Thanks to David Rager
  for a helpful discussion.

    (thm (and (equal (append (append x y) z) (append x y z))
              (equal (append (append x2 y2) z2) (append x2 y2 z2)))
         :hints ((\"Subgoal 1\" :do-not-induct some-name)))

  Fixed a slight bug in the definitions of built-in [47m[theories][0m.  For
  example, in a fresh ACL2 session the value of the following form is
  [47mnil[0m, but formerly included several [47m:[0m[47m[definition][0m [rune]s.

    (let ((world (w state)))
      (set-difference-theories (function-theory :here)
                               (function-theory 'ground-zero)))

  [31;1mCHANGES AT THE SYSTEM LEVEL AND TO DISTRIBUTED BOOKS[0m

  Many changes have been made to the distributed books, as recorded in
  svn logs under the `Source' and 'Updates' links at the {ACL2 Books
  | http://acl2-books.googlecode.com/} web page.  Here we list some
  of the more significant changes.

      o A large library has been graciously contributed by the formal
      verification group at Centaur Technology.  See [47mbooks/centaur/[0m
      and, in particular, file [47mbooks/centaur/README[0m, which explains
      how the library depends on the experimental HONS extension (see
      [hons-and-memoization]).

      o Among the new books is an illustration of [47m[defattach][0m,
      [47mbooks/misc/defattach-example.lisp[0m, as well as a variant of
      defattach that avoids the need for [guard] verification,
      [47mbooks/misc/defattach-bang.lisp[0m.

      o Distributed book [47mbooks/misc/trace1.lisp[0m has been deleted.  It had
      provided slightly more friendly [trace] output for new users,
      but distributed book [47mbooks/misc/trace-star.lisp[0m may be better
      suited for that purpose.

  ACL2 can once again be built on LispWorks (i.e., as the host Lisp),
  at least with LispWorks 6.0.  Thanks to David Rager for useful
  conversations.  Several changes have been made from previous
  LispWorks-based ACL2 executables:
  o ACL2 now starts up in its read-eval-print loop.
  o You can save an image with [47m[save-exec][0m.
  o Multiprocessing is not enabled.
  o The stack size is managed using a LispWorks variable that causes
  the stack to grow as needed.
  o When ACL2 is built a script file is written, as is done for other
  host Lisps.  Thus, (assuming that no [47mPREFIX[0m is specified),
  [47msaved_acl2[0m is just a small text file that invokes a binary
  executable, which for Lispworks is [47msaved_acl2.lw[0m.

  The HTML documentation no longer has extra newlines in <pre>
  environments.

  Statistics on ACL2 code size may be found in distributed file
  [47mdoc/acl2-code-size.txt[0m.  This file and other information can be
  found in a new [documentation] topic, [about-ACL2].

  Fixed the build process to pay attention to environment variable
  [47mACL2_SYSTEM_BOOKS[0m (which may be supplied as a command-line argument
  to `make').  An ACL2 executable can thus now be built even when
  there is no [47mbooks/[0m subdirectory if a suitable replacement directory
  is supplied.

  Some warnings from the host Lisp are now suppressed that could
  formerly appear.  For example, the warnings shown below occurs in
  Version 4.2 using Allegro CL, but not in Version 4.3.

    ACL2 !>(progn (set-ignore-ok t)
                  (set-irrelevant-formals-ok t)
                  (defun bar (x y)
                    x))
    [[.. output omitted ..]]
     BAR
    ACL2 !>:comp bar
    ; While compiling BAR:
    Warning: Variable Y is never used.
    ; While compiling (LABELS ACL2_*1*_ACL2::BAR ACL2_*1*_ACL2::BAR):
    Warning: Variable Y is never used.
     BAR
    ACL2 !>

  [31;1mEMACS SUPPORT[0m

  The distributed Emacs file [47memacs/emacs-acl2.el[0m now indents calls of
  [47mer@par[0m and [47mwarning$@par[0m the same way that calls of [47mdefun[0m are
  indented.

  [31;1mEXPERIMENTAL VERSIONS[0m

  The parallel version (see [parallelism]) now supports parallel
  evaluation of the ``waterfall'' part of the ACL2 prover; see
  [set-waterfall-parallelism].  Thanks to David Rager for doing the
  primary design and implementation work.

  A new macro, [47m[spec-mv-let][0m, supports speculative and parallel
  execution in the parallel version, courtesy of David Rager.

  Among the enhancements for the HONS version (see
  [hons-and-memoization]) are the following.

      [47m[Memoize][0md functions may now be traced (see [trace$]).  Thanks to Sol
      Swords for requesting this enhancement.

      [47m[Memoize-summary][0m and [47m[clear-memoize-statistics][0m are now [47m:[0m[47m[logic][0m
      mode functions that return [47mnil[0m.  Thanks to Sol Swords for this
      enhancement.

      [47m[Memoize][0m is now explicitly illegal for constrained functions.
      (Already such memoization was ineffective.)

      A new keyword argument, [47m:AOKP[0m, controls whether or not to allow
      memoization to take advantage of attachments; see [memoize] and
      for relevant background, see [defattach].

      [47m[Memoize][0m is now illegal by default for [47m:[0m[47m[logic][0m mode functions that
      have not had their guards verified.  See [memoize] (keyword
      [47m:ideal-okp[0m) and see [ACL2-defaults-table] (key
      [47m:memoize-ideal-okp[0m) for an explanation of this restriction and
      how to avoid it.

      [History] commands such as [47m:[0m[47m[pe][0m and [47m:[0m[47m[pbt][0m now display ``[47mM[0m'' or
      ``[47mm[0m'' to indicate memoized functions.  See [pc].")
 (NOTE-4-3{R}
  (RELEASE-NOTES)
  "ACL2 Version 4.3(r) (July, 2011) Notes

  Please see [note-4-3] for changes in Version 4.3 of ACL2.")
 (NOTE-5-0
  (RELEASE-NOTES)
  "ACL2 Version 5.0 (August, 2012) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 4.3 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, changes at the system level and
  to distributed books, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  NOTE: ACL2 is now distributed under Version 2 of the GNU General
  Public License.  [Added later: The license has changed since
  Version_5.0.  See LICENSE.]  Formerly, any later version had been
  acceptable.  Moreover, books are no longer distributed from a
  University of Texas website, but rather, from Google Code at the
  {ACL2 Books Downloads |
  http://code.google.com/p/acl2-books/downloads/} page.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  A fatal error now occurs if environment variable [47mACL2_CUSTOMIZATION[0m
  has a value other than [47mNONE[0m or the empty string, but is not the
  name of an existing file.  Thanks to Harsh Raju Chamarthi for
  requesting such a change.

  Functions [47mread-acl2-oracle[0m (and [47mread-acl2-oracle@par[0m), [47mread-run-time[0m,
  and [47mmain-timer[0m are no longer untouchable (see
  [remove-untouchable]).

  We now avoid certain duplicate conjuncts in the [constraint] stored
  for [47m[encapsulate][0m [events].  For example, the constraint stored for
  the following event formerly included [47m(EQUAL (FOOP (CONS X Y))
  (FOOP Y))[0m and [47m(BOOLEANP (FOOP X))[0m twice each, but no more.

    (encapsulate
     ((foop (x) t))
     (local (defun foop (x) (declare (ignore x)) t))
     (defthm foop-constraints
       (and (booleanp (foop x))
            (equal (foop (cons x y)) (foop y)))
       :rule-classes
       ((:type-prescription :corollary (booleanp (foop x)))
        (:rewrite :corollary (equal (foop (cons x y)) (foop y))))))

  The [47m:[0m[47m[guard][0m for a constrained function (see [signature]) may now
  mention function symbols introduced in the same [47m[encapsulate][0m event
  that introduces that function.  Thanks to Nathan Wetzler for a
  helpful discussion leading to this improvement.

  The test for redundancy (see [redundant-events]) of [47m[encapsulate][0m
  [events] has been improved in cases involving redefinition (see
  [ld-redefinition-action]).  Thanks to Jared Davis for providing the
  following example, which illustrates the problem.

    (redef!)

    (encapsulate ()
      (defun g (x)
        (+ 3 x)))

    (g 0) ; 3, as expected

    (encapsulate ()
      (defun g (x)
        (+ 4 x)))

    (g 0) ; 4, as expected

    ; Unfortunately, the following was flagged as redundant because it agreed
    ; with the first encapsulate above.  That has been fixed; now, it is
    ; recognized as not being redundant.
    (encapsulate ()
      (defun g (x)
        (+ 3 x)))

  The test for redundancy of [47m[defun][0m and [47m[defconst][0m events has been
  improved in the case that redefinition is active.  In that case,
  redundancy now additionally requires that the ``translated'' body
  is unchanged, i.e., even after expanding macro calls and replacing
  constants (defined by [47m[defconst][0m) with their values.  Thanks to Sol
  Swords for requesting this enhancement, and to Jared Davis for
  pointing out a bug in a preliminary change.  See
  [redundant-events], in particular the ``Note About Unfortunate
  Redundancies''.  Note that this additional requirement was already
  in force for redundancy of [47m[defmacro][0m events.

  The macro [47m[defmacro-last][0m and the [table] [47m[return-last-table][0m have
  been modified so that when they give special treatment to a macro
  [47mmac[0m and its raw Lisp counterpart [47mmac-raw[0m, a call [47m(return-last
  'mac-raw ...)[0m can be made illegal when encountered directly in the
  top level loop, as opposed to inside a function body.  See
  [return-last].  Thanks to Harsh Raju Chamarthi for showing us an
  example that led us to make this improvement.

  We removed a barrier to admitting function definitions, as we explain
  using the following example.

    (defun foo (m state)
      (declare (xargs :stobjs state))
      (if (consp m)
          (let ((state (f-put-global 'last-m m state)))
            (foo (cdr m) state))
        state))

  Previously, ACL2 complained that it could not determine the outputs
  of the [47m[let][0m form, as is necessary in order to ensure that [47m[state][0m
  is returned by it.  ACL2 now works harder to solve this problem as
  well as the analogous problem for [47m[mv-let][0m and, more generally for
  [47m[mutual-recursion][0m.  (The main idea is to reverse the order of
  processing the [47m[if][0m branches if necessary.)  We thank Sol Swords
  for contributing a version of the above example and requesting this
  improvement.

  It is no longer the case that [47m[break-on-error][0m causes a Lisp break
  when encountering an error during translation of user input into
  internal (translated) form (see [term]).  The reason is that an
  improvement to the translation process, specifically the one
  described in the preceding paragraph, allows certain backtracking
  from ``errors'', which are intended to be silent rather than
  causing breaks into raw Lisp.  Thanks to Jared Davis for sending an
  example leading to this change.

  (CCL and SBCL only) When the host Lisp is CCL or SBCL, then since all
  functions are compiled, a [47m[certify-book][0m command will no longer
  load the newly-compiled file (and similarly for [47m[include-book][0m with
  argument [47m:load-compiled-file :comp[0m).

  [47m[Set-write-acl2x][0m now returns an error triple and can take more
  values, some of which automatically allow including uncertified
  books when [47m[certify-book][0m is called with argument :acl2x t.

  The environment variable [47mCOMPILE_FLG[0m has been renamed
  [47mACL2_COMPILE_FLG[0m; see [certify-book].

  The macros [47m[defthmd][0m and [47m[defund][0m no longer return an error triple
  with value [47m:SKIPPED[0m when proofs are being skipped.  Rather, the
  value returned is the same as would be returned on success when
  proofs are not skipped.

  For those who use [47m[set-write-ACL2x][0m: now, when [47m[certify-book][0m is
  called without a [47m:ttagsx[0m argument supplied, then the value of
  [47m:ttagsx[0m defaults to the (explicit or default) value of the [47m:ttags[0m
  argument.

  The [47m:[0m[47m[pl][0m and [47m:[0m[47m[pl2][0m [command]s can now accept [term]s that had
  previously been rejected.  For example, the command [47m:pl (member a
  (append x y))[0m had caused an error, but now it works as one might
  reasonably expect, treating [47m[member][0m as [47m[member-equal][0m (see
  [equality-variants] for relevant background).  Thanks to Jared
  Davis for reporting this problem by sending the above example.

  We have eliminated some hypotheses in built-in [rewrite] rules
  [47mcharacterp-nth[0m and [47mordered-symbol-alistp-delete-assoc-eq[0m.

  Added the symbols [47m[f-get-global][0m, [47m[f-put-global][0m, and
  [47m[state-global-let*][0m to [47m*acl2-exports*[0m.

  Added to the [guard]s of [47m[push-untouchable][0m and [47m[remove-untouchable][0m
  the requirement that the second argument must be a Boolean.  Thanks
  to Jared Davis for sending an example that led to this change.

  The built-in function [47mstring-for-tilde-@-clause-id-phrase[0m has been
  put into [47m:[0m[47m[logic][0m mode and had its guards verified, as have some
  subsidiary functions.  A few new rules have been added in support
  of this work; search for [47mstring-for-tilde-@-clause-id-phrase[0m in
  ACL2 source file [47mboot-strap-pass-2.lisp[0m if interested.  Thanks to
  David Rager for contributing an initial version of this
  improvement.

  All trust tags are now in the [keyword] package.  The [47m[defttag][0m event
  may still take a symbol in an arbitrary package, but the trust tag
  created will be in the keyword package (with the same [47m[symbol-name][0m
  as the symbol provided).  Similarly, non-[47mnil[0m symbols occurring in
  the [47m:ttags[0m argument of an [47m[include-book][0m or [47m[certify-book][0m command
  will be converted to corresponding keywords.  See [defttag].

  There have been several changes to [gag-mode].  It is now is
  initially set to [47m:goals[0m, suppressing most proof commentary other
  than key checkpoints; see [set-gag-mode].  (As before, see [pso]
  for how to recover the proof output.)  Also, top-level induction
  schemes are once again printed when gag-mode is on, though these as
  well as printing of guard conjectures can be abbreviated
  (``eviscerated'') with a new [evisc-tuple]; see [set-evisc-tuple],
  in particular the discussion there of [47m:GAG-MODE[0m.  Finally, the
  commentary printed within [gag-mode] that is related to
  [forcing-round]s is now less verbose.  Thanks to Dave Greve and
  David Rager for discussions leading to the change in the printing
  of induction schemes under gag-mode; thanks to Warren Hunt for an
  email that led us to similar handling for printing of guard
  conjectures; and thanks to Robert Krug for a suggestion that led us
  to restore, in abbreviated form, important information about the
  sources of forcing round goals.

  An error now occurs if [47m[ld][0m is called while loading a compiled book.
  See [calling-ld-in-bad-contexts].  Thanks to David Rager for
  reporting a low-level assertion failure that led us to make this
  change.

  The [proof-builder] interactive loop is more robust: most errors will
  leave you in that loop, rather than kicking you out of the
  proof-builder and thus back to the main ACL2 read-eval-print loop.
  Thanks to David Hardin for suggesting this improvement in the case
  of errors arising from extra right parentheses.

  The summary at the end of a proof now prints the following note when
  appropriate:

    [NOTE: A goal of NIL was generated.  See :DOC nil-goal.]

  See [nil-goal].

  Improved [47m[dmr][0m to show the function being called in the case of
  explicit evaluation: ``[47m(EV-FNCALL function-being-called)[0m''.

  It is now permitted to bind any number of [stobjs] to themselves in
  the bindings of a [47m[let][0m expression.  But if any stobj is bound to
  other than itself in [47m[let][0m bindings, then there still must be only
  one binding in that [47mLET[0m expression.  The analogous relaxation holds
  for [47m[lambda][0m expressions.  Thanks to Sol Swords for requesting such
  a change, which was needed for some code generated by macro calls.

  The macro [47m[top-level][0m now returns without error; See [top-level].
  Formerly, this macro always returned an error triple [47m(mv t ..
  state)[0m, which meant that normal calls of [47m[ld][0m would stop after
  encountering a call of [47mtop-level[0m.  Thanks to Jared Davis for
  bringing this issue to our attention.

  It is no longer the case that when you specify [47m[xargs][0m keyword
  [47m:non-executable t[0m in a [47m[defun][0m form rather than using [47m[defun-nx][0m,
  then the form of the body need match only the shape [47m(prog2$
  (throw-nonexec-error ... ...) ...)[0m.  We now require that the body
  of the definition of a function symbol, [47mfn[0m, with formals [47m(x1 ...
  xk)[0m, be of the form [47m(prog2$ (throw-nonexec-error 'fn (list x1 ...
  xk)) ...)[0m.  This fixes the following odd behavior, which could be
  considered a bug.  Consider a book that contains the following two
  events.

    (defun foo (x)
      (declare (xargs :guard t :non-executable t :mode :logic))
      (prog2$ (throw-nonexec-error 'bar (list x))
              (cons 3 x)))
    (defn h (x)
      (foo x))

  After certifying this book and then including it in a new session,
  the behavior occurred that is displayed below; notice the mention
  of [47mBAR[0m.  However, if the two forms were submitted directly in the
  loop, then the error message had mentioned [47mFOO[0m instead of [47mBAR[0m.
  This discrepancy has been eliminated, by rejecting the proposed
  definition of [47mfoo[0m because the name in the first argument of
  [47mthrow-nonexec-error[0m was [47m'bar[0m where now it must be [47m'foo[0m.

    ACL2 !>(h 3)

    ACL2 Error in TOP-LEVEL:  ACL2 cannot ev the call of undefined function
    BAR on argument list:

    (3)

    To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

    ACL2 !>

  A tautology checker used in the ACL2 sources (function [47mif-tautologyp[0m)
  has been limited somewhat in the effort it makes to recognize a
  tautology.  While we expect it to be rare for the effect of this
  change to be noticeable, we thank Sol Swords for sending us an
  example that motivated this change: a [guard] verification that
  took about 5 seconds in Version_4.3 now takes, on the same machine,
  about 0.07 seconds.

  The behavior of backquote ([47m`[0m) has been changed slightly to be
  compatible with its behavior in raw Lisp.  The change is to allow
  the use of comma-atsign ([47m,@[0m) at the end of a list, as in the
  following example.

    (let ((x 3) (y 2) (z 7)) `(,x ,y ,@z))

  Formerly, evaluation of this form had caused a guard violation in the
  ACL2 loop unless guard-checking was off (i.e., [47m[set-guard-checking][0m
  was invoked with [47mnil[0m or [47m:none[0m), in which case it returned [47m(3 2)[0m.
  But we observed evaluation of this form to return [47m(3 2 . 7)[0m in
  every host Lisp on which ACL2 runs (Allegro CL, CCL, CLISP, CMUCL,
  GCL, LispWorks, and SBCL).  Now, ACL2 behaves like these Lisps.

  A call of the [47m[theory][0m macro had previously returned [47mnil[0m when applied
  to other than the name of name of a previously executed [47m[deftheory][0m
  event.  Now, a hard error occurs.

  The [table] [47mbinop-table[0m has been replaced by the table
  [47m[untrans-table][0m.  However, [47m[add-binop][0m and [47m[remove-binop][0m continue
  to have the same effect as before.  See [add-macro-fn], which is a
  new feature discussed below.

  The function [47m[booleanp][0m is now defined using [47m[eq][0m instead of [47m[equal][0m,
  which may increase its efficiency.  Thanks to Jared Davis for this
  change.

  For pairs [47m(key . val)[0m in the [47m[macro-aliases-table][0m, there had been a
  requirement that [47mval[0m is a known function symbol.  Now, it only
  needs to be a symbol.  (This change was made to support the new
  feature, [47m[defun-inline][0m, described elsewhere in these release
  notes.)

  [31;1mNEW FEATURES[0m

  A new ``tau system'' provides a kind of ``type checker.'' See
  [tau-system].  Thanks to Dave Greve for supplying a motivating
  example (on which this system can provide significant speedup), and
  to Sol Swords for sending a very helpful bug report on a
  preliminary implementation.

  Users may now arrange for additional summary information to be
  printed at the end of [events].  [Note added at Version_6.1:
  Formerly we pointed here to [47mprint-summary-user[0m, but now, see
  [finalize-event-user]; also see [note-6-1]].  Thanks to Harsh Raju
  Chamarthi for requesting this feature and participating in a design
  discussion.

  A new, advanced [proof-builder] command, [47mgeneqv[0m, shows the generated
  equivalence relation at the current subterm.  Thanks to Dave Greve
  for an inquiry leading to this enhancement.

  A new reader macro, [47m#u[0m, permits the use of underscore characters in a
  number.  See [sharp-u-reader].  Thanks to Jared Davis for
  requesting this capability.

  New [proof-builder] commands [47mpl[0m and [47mpr[0m provide interfaces to the ACL2
  commands [47m:[0m[47m[pl][0m and [47m:[0m[47m[pr][0m, respectively.  These can be useful if you
  want to see trivially-proved hypotheses, as now clarified in the
  [proof-builder] documentation for its [47mshow-rewrites[0m command.  See
  [proof-builder-commands].  Thanks to Pete Manolios for suggesting
  such clarification and capability.

  It is now legal to call [non-executable] functions without the usual
  [signature] restrictions imposed on executable code.  For example,
  the third event below was not admissible, but now it is.

    (defstobj foo fld)
    (defun-nx id (x)
      x)
    (defun f (foo)
      (declare (xargs :stobjs foo :verify-guards nil))
      (cons 3 (id foo)))

  Thanks to Jared Davis for requesting this enhancement, in particular
  for calling non-executable functions in the [47m:logic[0m part of an [47m[mbe][0m
  call.  Here is Jared's example, which is admissible now but
  formerly was not.

    (defstobj foo (fld))
    (defun-nx my-identity (x) x)
    (defun my-fld (foo)
      (declare (xargs :stobjs foo))
      (mbe :logic (my-identity foo)
           :exec (let ((val (fld foo)))
                   (update-fld val foo))))

  A new macro, [47m[non-exec][0m, allows the use of non-executable code, for
  example inside ordinary function definitions.  Thanks to Sol Swords
  for requesting this enhancement.

  A new ``provisional certification'' process is supported that can
  allow [books] to be certified before their included sub-books have
  been certified, thus allowing for potentially much greater
  `make'-level parallelism.  See [provisional-certification].  Thanks
  to Jared Davis for requesting this feature and for helpful
  discussions, based in part on rudimentary provisional certification
  schemes that he developed first at Rockwell Collins and later for
  his `Milawa' project.  Also, thanks to Jared and to Sol Swords for
  testing this feature and for providing a fix for a bug in a
  preliminary implementation, and thanks to Sol for providing
  performance feedback and a crucial suggestion that led to an
  improved implementation.

  Event summaries now show the names of events that were mentioned in
  [hints] of type [47m:use[0m, [47m:by[0m, or [47m:clause-processor[0m.  See
  [set-inhibited-summary-types].  Thanks to Francisco J. Martin
  Mateos for requesting such an enhancement (actually thanks to the
  community, as his request is the most recent but this has come up
  from time to time before).

  ACL2 now stores a data structure representing the relation ``Event A
  is used in the proof of Event B.'' See [dead-events], which
  explains this data structure and mentions one application: to
  identify dead code and unused theorems.  Thanks to Shilpi Goel for
  requesting such a feature and for helpful feedback.

  A new [documentation] topic provides a guide to programming with
  state; see [programming-with-state].  Thanks to Sarah Weissman for
  suggesting that such a guide might be useful, and to David Rager
  for helpful feedback on a preliminary version.  There also has been
  some corresponding reorganization of the documentation as well as
  creation of additional documentation (e.g., see
  [state-global-let*]).  Now, most built-in functions and macros
  commonly used in programs (as opposed to [events] like [47m[defun][0m, for
  example) are subtopics of a new topic --- see [ACL2-built-ins] ---
  which is a subtopic of [programming], a topic that in turn has
  considerably fewer direct subtopics than before.

  It is now possible to bind extra variables in a [47m:USE[0m hint, thus
  avoiding the error message: ``The formula you wish to instantiate,
  ..., mentions only the variable(s) ...''.  See [lemma-instance], in
  particular the discussion of keyword [47m:extra-bindings-ok[0m.  Thanks to
  Sol Swords for requesting such an enhancement.

  The function [47mread-object-suppress[0m is like [47mread-object[0m except that it
  avoids errors and discards the value read.  See [io].

  A [stobj] may now be passed as an argument where another stobj is
  expected if the two are ``congruent''.  See [defstobj], in
  particular, its discussion of the new [47m:congruent-to[0m keyword of
  [47mdefstobj[0m.  Thanks to Sol Swords for requesting this enhancement and
  for useful discussions contributing to its design.

  A new top-level utility has been provided that shows the assembly
  language for a defined function symbol; see [disassemble$].  Thanks
  to Jared Davis for requesting such a utility and to Shilpi Goel for
  pointing out an inconvenience with the initial implementation.
  Note that it uses the distributed book [47mbooks/misc/disassemble.lisp[0m,
  which users are welcome to modify (see [community-books]).

  The macro [47mset-accumulated-persistence[0m is an alias for
  [47m[accumulated-persistence][0m.  Thanks to Robert Krug for suggesting
  this addition.

  A new [documentation] topic lists lesser-known and advanced ACL2
  features, intended for those with prior ACL2 experience who wish to
  extend their knowledge of ACL2 capabilities.  See
  [advanced-features].  Thanks to Warren Hunt and Anna Slobodova for
  requesting such information.

  A new macro, [47m[deftheory-static][0m, provides a variant of [47m[deftheory][0m
  such that the resulting theory is the same at [47m[include-book][0m time
  as it was at [47m[certify-book][0m time.  Thanks to Robert Krug for
  helpful discussions on this new feature and for updating his
  [47mbooks/arithmetic-5/[0m distributed books to use this feature.

  A new event, [47m[defabsstobj][0m, provides a new way to introduce
  single-threaded objects (see [stobj] and see [defstobj]).  These
  so-called ``abstract [stobj]s'' permit user-provided logical
  definitions for primitive operations on stobjs, for example using
  an alist-based representation instead of a list-based
  representation for array fields.  Moreover, the proof obligations
  guarantee that the recognizer is preserved; hence the
  implementation avoids executing the recognizer, which may be an
  arbitrarily complex invariant that otherwise would be an expensive
  part of [guard] checks.  Thanks to Warren Hunt for a request
  leading us to design and implement this new feature, and thanks to
  Rob Sumners for a request leading us to implement a related
  utility, [47m[defabsstobj-missing-events][0m.  See [defabsstobj].  Also
  thanks to Sol Swords for sending an example exhibiting a bug in the
  initial implementation, which has been fixed.

  A new command, [47m:psof <filename>[0m, is like [47m:pso[0m but directs proof
  replay output to the specified file.  For large proofs, [47m:[0m[47m[psof][0m may
  complete much more quickly than [47m:[0m[47m[pso][0m.  see [psof].  More
  generally, a new utility, [47m[wof][0m (an acronym for ``With Output
  File''), directs standard output and proofs output to a file; see
  [wof].

  The new macro [47m[defnd][0m defines a function with [47m:[0m[47m[guard][0m [47mt[0m and
  [disable]s that function, in analogy to how [47m[defund][0m defines with
  [47m[defun][0m and then [disable]s.  Thanks to Shilpi Goel for requesting
  this feature.

  The [47m:[0m[47m[pl2][0m command now shows [47m:[0m[47m[linear][0m rules; and a new
  [proof-builder] command, [47mshow-linears[0m (equivalently, [47msls[0m), is an
  analogue of the [proof-builder] [47mshow-rewrites[0m ([47msr[0m) command, but for
  [linear] rules.  Thanks to Shilpi Goel for requesting this new
  proof-builder command.  Finally, a corresponding new proof-builder
  command, [47mapply-linear[0m ([47mal[0m), is an analogue of the [proof-builder]
  [47mrewrite[0m ([47mr[0m) command, but for [linear] rules.

  The macros [47m[add-macro-fn][0m and [47m[remove-macro-fn][0m replace macros
  [47m[add-binop][0m and [47m[remove-binop][0m, respectively, though the latter
  continue to work.  The new macros allow you to decide whether or
  not to display calls of binary macros as flat calls for
  right-associated arguments, e.g., [47m(append x y z)[0m rather than
  [47m(append x (append y z))[0m.  See [add-macro-fn].

  It is now possible to request that the host Lisp compiler inline
  calls of specified functions, or to direct that the host Lisp
  compiler not inline such calls.  See [defun-inline] and see
  [defun-notinline].  We thank Jared Davis for several extensive,
  relevant conversations, and for finding a bug in a preliminary
  implementation.  We also thank others who have engaged in
  discussions with us about inlining for ACL2; besides Jared Davis,
  we recall such conversations with Rob Sumners, Dave Greve, and
  Shilpi Goel.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  Reading of ACL2 [47m[arrays][0m (see [aref1], see [aref2]) has been made
  more efficient (as tested with CCL as the host Lisp) in the case of
  consecutive repeated reads of the same named array.  Thanks to
  Jared Davis and Sol Swords for contributing this improvement.

  Slightly modified the induction schemes stored, so that calls of
  so-called ``guard-holders'' (such as [47m[mbe][0m and [47m[prog2$][0m --- indeed,
  any call of [47m[return-last][0m --- and [47m[the][0m) are expanded away.  In
  particular, calls of equality variants such as [47m[member][0m are treated
  as their corresponding function calls, e.g., [47m[member-equal][0m; see
  [equality-variants].  Guard-holders are also now expanded away
  before storing [constraint]s for [47m[encapsulate][0m [events], which can
  sometimes result in simpler constraints.

  Improved the performance of [47m[dmr][0m (technical note: by modifying raw
  Lisp code for function [47mdmr-flush[0m, replacing [47mfinish-output[0m by
  [47mforce-output[0m).

  We now avoid certain rewriting loops.  A long comment about this
  change, including an example of a loop that no longer occurs, may
  be found in source function [47mexpand-permission-result[0m.

  Slightly strengthened [type-set] reasoning at the level of literals
  (i.e., top-level hypotheses and conclusions).  See the comment in
  ACL2 source function [47mrewrite-atm[0m about the ``use of dwp = t'' for
  an example of a theorem provable only after this change.

  Strengthened the ability of [type-set] reasoning to make deductions
  about terms being integers or non-integer rationals.  The following
  example illustrates the enhancement: before the change, no
  simplification was performed, but after the change, the conclusion
  simplifies to [47m(foo t)[0m.  Thanks to Robert Krug for conveying the
  problem to us and outlining a solution.

    (defstub foo (x) t)
    (thm ; should reduce conclusion to (foo t)
     (implies (and (rationalp x)
                   (rationalp y)
                   (integerp (+ x (* 1/3 y))))
              (foo (integerp (+ y (* 3 x))))))

  [31;1mBUG FIXES[0m

  Fixed a class of soundness bugs involving each of the following
  functions: [47m[getenv$][0m, [47mget-wormhole-status[0m, [47m[cpu-core-count][0m,
  [47m[wormhole-p][0m, [47m[random$][0m, [47mfile-write-date$[0m, and [47mserialize-read-fn[0m,
  and (for the HONS version of ACL2) [47m[clear-memoize-table][0m and
  [47m[clear-memoize-tables][0m as well as (possible soundness bug)
  [47mserialize-write-fn[0m.  For example, we were able to admit the
  following events, but that is no longer the case (neither for
  [47mgetenv$[0m as shown, nor analogously for other functions listed
  above).

    (defthm not-true
      (stringp (cadr (getenv$ \"PWD\" (build-state))))
      :rule-classes nil)

    (defthm contradiction
      nil
      :hints ((\"Goal\"
               :in-theory (disable (getenv$))
               :use not-true))
      :rule-classes nil)

  Fixed a soundness bug involving [47mwith-live-state[0m, which could cause an
  error in the use of [47m[add-include-book-dir][0m or
  [47m[delete-include-book-dir][0m in a book or its [portcullis] commands.
  See [with-live-state], as the documentation for this macro has been
  updated; in particular it is now untouchable (see
  [remove-untouchable]) and is intended only for system hackers.
  Thanks to Jared Davis for reporting a bug in the use of
  [47m[add-include-book-dir][0m after our first attempt at a fix.

  Fixed a soundness bug based on the use of [47m[skip-proofs][0m together with
  the little-used argument [47mk=t[0m for [47m[certify-book][0m.  An example proof
  of [47mnil[0m appears in a comment in the ACL2 sources, in [47m(deflabel
  note-5-0 ...)[0m.

  Fixed a soundness bug that allowed users to define new
  [proof-builder] primitive commands.  Before this fix, a book
  proving [47mnil[0m could be certified, as shown in a comment now in the
  introduction of the [table] [47mpc-command-table[0m in source file
  [47mproof-builder-a.lisp[0m.

  (Technical change, primarily related to [47m[make-event][0m:) Plugged a
  security hole that allowed [books]' [certificate]s to be
  out-of-date with respect to [47m[make-event][0m expansions, but not
  recognized as such.  The change is to include the so-called
  expansion-alist in the certificate's checksum.  An example appears
  in a comment in the ACL2 sources, in [47m(deflabel note-5-0 ...)[0m.

  Fixed a bug in [guard] verification due to expanding calls of
  primitives when translating user-level terms to internal form, so
  called ``translated terms'' (see [term]).  While we have not
  observed a soundness hole due to this bug, we have not ruled it
  out.  Before the bug fix, the following event was admissible, as
  guard verification succeeded (but clearly should not have).

    (defun f ()
      (declare (xargs :guard t))
      (car (identity 3)))

  For those who want details about this bug, we analyze how ACL2
  generates [guard] proof obligations for this example.  During that
  process, it evaluates ground subexpressions.  Thus, [47m(identity '3)[0m
  is first simplified to [47m'3[0m; so a term must be built from the
  application of [47mcar[0m to [47m'3[0m.  Guard-checking is always turned on when
  generating guard proof obligations, so now, ACL2 refuses to
  simplify [47m(car '3)[0m to [47m'nil[0m.  However, before this bug fix, when ACL2
  was building a term by applying [47mcar[0m to argument [47m'3[0m, it did so
  directly without checking guards; source code function [47mcons-term[0m is
  `smart' that way.  After the fix, such term-building reduction is
  only performed when the primitive's guard is met.

  While calls of many event macros had been prohibited inside
  executable code, others should have been but were not.  For
  example, the following was formerly allowed.

    (defun foo (state)
      (declare (xargs :mode :program :stobjs state))
      (add-custom-keyword-hint :my-hint (identity nil)))
    (foo state) ; Caused hard raw Lisp error!

  Thus, several event macros (including for example
  [47m[add-custom-keyword-hint][0m) may no longer be called inside
  executable code.

  Fixed an assertion that could occur, for example, after reverting to
  prove the original goal by induction and generating a goal of [47mNIL[0m.
  Thanks to Jared Davis for sending us a helpful example to bring
  this bug to our attention.

  It was possible for [47m[defstobj][0m to generate raw Lisp code with
  excessively restrictive type declarations.  This has been fixed.
  Thanks to Warren Hunt for reporting this bug and sending an example
  that illustrates it.  See [stobj-example-2] for examples of such
  raw Lisp code; now, one finds [47m(and fixnum (integer 0 *))[0m where
  formerly the type was restricted to [47m(integer 0 268435455)[0m.

  Fixed a bug, ignoring the use of [47m:computed-hint-replacement[0m in
  certain cases involving a combination of computed hints and custom
  keyword hints.  Thanks to Robert Krug for reporting this bug and
  sending a very helpful example.

  Fixed a bug in the output from [47m[defattach][0m, which was failing to list
  previous [events] in the message about ``bypassing constraints that
  have been proved when processing the event(s)''.

  (GCL only) Fixed a bug in [47m[set-debugger-enable][0m (which was only a bug
  in GCL, not an issue for other host Lisps).

  Fixed ACL2 trace output to indent properly for levels above 99 (up to
  9999).  Thanks to Warren Hunt for bringing this bug to our
  attention.

  Fixed a bug in the reporting of times in event summaries --- probably
  one that has been very long-standing!  The times reported had often
  been too small in the case of compound [events], notably
  [47m[include-book][0m.  Thanks to everyone who reported this problem (we
  have a record of emails from Eric Smith and Jared Davis on this
  issue).

  Fixed a bug in [47m:expand[0m [hints], where the use of [47m:lambdas[0m could
  prevent other parts of such a hint.  For example, the following
  invocation of [47m[thm][0m failed before this fix was made.

    (defund foo (x) (cons x x))
    (thm (equal (car (foo x)) x)
    :hints ((\"Goal\" :expand (:lambdas (foo x)))))

  Certain ``program-only'' function calls will now cause hard Lisp
  errors.  (The rather obscure reason for this fix is to support
  logical modeling of the ACL2 evaluator.  A relevant technical
  discussion may be found in source function [47moneify-cltl-code[0m, at the
  binding of variable [47mfail_program-only-safe[0m.)

  There was an unnecessary restriction that [47m[flet][0m-bound functions must
  return all [stobj]s among their inputs.  For example, the following
  definition was rejected because [47mstate[0m was not among the outputs of
  [47mh[0m.  This restriction has been removed.

    (defun foo (state)
      (declare (xargs :stobjs state))
      (flet ((h (state) (f-boundp-global 'x state)))
        (h state)))

  We fixed a bug, introduced in the preceding release (Version 4.3), in
  the check for irrelevant formals (see [irrelevant-formals]).  That
  check had been too lenient in its handling of lambda ([let])
  expressions, for example allowing the following definition to be
  admitted in spite of its first formal parameter obviously being
  irrelevant.

    (defun foo (x clk)
      (if (zp clk)
          :diverge
        (let ((clk (1- clk)))
          (foo x clk))))

  Fixed a bug in the [47mmini-proveall[0m target in [47mGNUmakefile[0m.  The fix
  includes a slight change to the [47m:mini-proveall[0m [command] (an extra
  event at the end).  Thanks to Camm Maguire for reporting this bug.

  Fixed a bug that occurred when [47m[certify-book][0m was called after using
  [47m[set-fmt-soft-right-margin][0m or [47m[set-fmt-hard-right-margin][0m to set a
  small right margin.

  Fixed [47m[set-inhibit-warnings][0m so that it takes effect for a subsequent
  [47m[include-book][0m event.  Thanks to Jared Davis and David Rager for
  queries that led to this fix.

  Hard Lisp errors are now avoided for certain [47m:[0m[47m[rewrite][0m rules: those
  whose [equivalence] relation is other than [47mequal[0m when the rule is
  originally processed, but is no longer a known equivalence relation
  when the rule is to be stored.  Thanks to Jared Davis for sending a
  useful example, a minor variant of which is included in a comment
  in source function [47minterpret-term-as-rewrite-rule[0m (file
  [47mdefthm.lisp[0m).

  Fixed a bug in the ACL2 evaluator (source function [47mraw-ev-fncall[0m),
  which was unlikely to be exhibited in practice.

  Fixed a hard Lisp error that could occur for ill-formed [47m:[0m[47m[meta][0m
  [rule-classes], e.g., [47m(:meta :trigger-fns '(foo))[0m.

  It is now an error to include a [stobj] name in the [47m:renaming[0m alist
  (see [defstobj]).

  Some bogus warnings about non-recursive function symbols have been
  eliminated for rules of class [47m:[0m[47m[type-prescription][0m.

  (Allegro CL host Lisp only) Fixed an obsolete setting of compiler
  variable [47mcomp:declared-fixnums-remain-fixnums-switch[0m, which may
  have been responsible for intermittent (and infrequent) checksum
  errors encountered while including books during certification of
  the regression suite.

  Fixed a [proof-builder] bug that could result in duplicate goal names
  in the case of forced hypotheses.  An example showing this bug,
  before the fix, appears in a comment in the ACL2 sources, in
  [47m(deflabel note-5-0 ...)[0m.

  We fixed a bug in a prover routine involved in [type-set]
  computations involving linear arithmetic.  This bug has been around
  since at least as far back as Version_3.3 (released November,
  2007).  We are not aware of any resulting unsoundness, though it
  did have the potential to weaken the prover.  For example, the
  following is proved now, but was not proved before the bug was
  fixed.

    (thm
     (implies (and (rationalp x)
                   (rationalp y)
                   (integerp (+ (* 1/3 y) x)))
              (integerp (+ y (* 3 x))))
     :hints ((\"Goal\" :in-theory (disable commutativity-of-+))))

  Although all bets are off when using redefinition (see
  [ld-redefinition-action]), we wish to minimize negative effects of
  its use, especially raw Lisp errors.  The examples below had caused
  raw Lisp errors, but no longer.

    (defstobj st fld :inline t)
    (redef!)
    (defstobj st new0 fld)
    (u)
    (fld st) ; previously an error, which is now fixed

    ; Fresh ACL2 session:
    (redef!)
    (defun foo (x) x)
    (defmacro foo (x) `(quote ,x))
    (u)

    ; Fresh ACL2 session:
    (redef!)
    (defmacro foo (x) (cons 'list x))
    (defun foo (x) x)

  Fixed a bug that could cause hard Lisp errors in an [47m[encapsulate][0m
  event.  Thanks to Sol Swords for sending an example that exhibited
  this bug.  Here is a simpler such example; the bug was in how it
  was checked whether the [guard] for a guard-verified function
  (here, [47mg[0m) depends on some function introduced in the [signature] of
  the [47m[encapsulate][0m (here, the function [47mf[0m).

    (encapsulate
     ((f (x) t))
     (local (defun f (x) (declare (xargs :guard t)) x))
     (defun g (x)
       (declare (xargs :guard (if (integerp x) (f x) t)))
       x))

  Fixed a bug in [47mmfc-relieve-hyp[0m that we believe could prohibit its use
  on the last hypothesis.  Thanks to Sol Swords for reporting this
  bug and providing a fix.

  The syntax [47m#![0m (see [sharp-bang-reader]) was broken after a skipped
  readtime conditional.  For example, the following input line caused
  an error.

    #+skip #!acl2(quote 3)

  This bug has been fixed.

  Fixed a bug in the [break-rewrite] utility, which was evidenced by
  error messages that could occur when dealing with free variables.
  An example of such an error message is the following; we thank
  Robert Krug for sending us an example that produced this error and
  enabled us to produce a fix.

    HARD ACL2 ERROR in TILDE-@-FAILURE-REASON-PHRASE1:  Unrecognized failure
    reason, ((MEM-ARRAY . X86) (ADDR QUOTE 9)).

  We fixed an obscure bug that we believe could interfere with
  [47m[defproxy][0m because of an incorrect [47m(declaim (notinline <function>))[0m
  form.

  [31;1mCHANGES AT THE SYSTEM LEVEL AND TO DISTRIBUTED BOOKS[0m

  Improvements have been made related to the reading of characters.  In
  particular, checks are now done for ASCII encoding and for the
  expected [47m[char-code][0m values for [47mSpace[0m, [47mTab[0m, [47mNewline[0m, [47mPage[0m, and
  [47mRubout[0m.  Also, an error no longer occurs with certain uses of
  non-standard characters.  For example, it had caused an error to
  certify a book after a single [portcullis] [command] of [47m(make-event
  `(defconst *my-null* ,(code-char 0)))[0m; but this is no longer an
  issue.  Thanks to Jared Davis for helpful correspondence that led
  us to make these improvements.

  The character encoding for reading from files has been fixed at
  ISO-8859-1.  See [character-encoding].  Thanks to Jared Davis for
  bringing this portability issue to our attention (as this change
  arose in order to deal with a change in the default character
  encoding for the host Lisp, CCL), and pointing us in the right
  direction for dealing with it.  In many cases, the character
  encoding for reading from the terminal is also ISO-8859-1; but this
  is not guaranteed.  In particular, when the host Lisp is SBCL this
  may not be the case.

  Although the HTML documentation is distributed with ACL2, it had not
  been possible for users to build that documentation without
  omitting graphics, for example on the ACL2 home page.  That has
  been fixed, as files [47mgraphics/*.gif[0m are now distributed.

  Compiler warnings are suppressed more completely than they had been
  before.  For example, the following had produced a compiler warning
  when the host Lisp is CCL, but no longer does so.

    (defun f () (car 3))
    (trace$ f)

  Removed support for ``tainted'' [certificate]s.  One reason is that
  there are rarely incremental releases.  A stronger reason is that
  for the compatibility of a new release is with the previous
  non-incremental release, it's not particularly relevant whether or
  not the new release is incremental.

  The `make' variable [47mBOOKS[0m can now be defined above the line that
  includes Makefile-generic.  (For relevant background, see
  [books-certification-classic].)

  (SBCL only) ACL2 images built on SBCL now have an option,
  [47m--dynamic-space-size 2000[0m, that can avoid space problems that could
  previously have caused the session to die.

  The default value for variable [47mLISP[0m in file [47mGNUmakefile[0m is now [47mccl[0m.
  Thus, if you use `make' in the standard way to build an ACL2
  executable, the default host Lisp is [47mccl[0m rather than [47mgcl[0m.

  [31;1mEMACS SUPPORT[0m

  [31;1mEXPERIMENTAL VERSIONS[0m

  For the version supporting the reals, ACL2(r) (see [real]), the
  supporting function [47mfloor1[0m has been defined in raw Lisp.  This
  avoids an error such as in the following case.

    (defun f () (declare (xargs :guard t)) (floor1 8/3))
    (f) ; had caused raw Lisp error, before the fix

  Among the enhancements for the parallel version, ACL2(p) (see
  [parallelism]), are the following.  We thank David Rager for his
  work in developing ACL2(p) and these improvements in particular.

      The macro [47mset-parallel-evaluation[0m has been renamed
      [47m[set-parallel-execution][0m.

      Calls of the macro [47m[set-waterfall-printing][0m are no longer [events],
      so may not be placed at the top level of [books].  However, it
      is easy to create events that have these effects; see
      [set-waterfall-printing].  Note that now, [47m:[0m[47m[ubt][0m and similar
      commands do not change the settings for either
      waterfall-parallelism or waterfall-printing.

      The implementation of [47m[deflock][0m has been improved.  Now, the macro it
      defines can provide a lock when invoked inside a
      [guard]-verified or [47m:[0m[47m[program][0m mode function.  Previously, this
      was only the case if the function definition was loaded from
      raw Lisp, typically via a compiled file.

      The underlying implementation for waterfall parallelism (see
      [set-waterfall-parallelism]) has been improved.  As a result,
      even the largest proofs in the regression suite can be run
      efficiently in [47m:resource-based[0m waterfall parallelism mode.
      Among these improvements is one that can prevent machines from
      rebooting because operating system limits have been exceeded;
      thanks to Robert Krug for bringing this issue to our attention.

      There is also a new flag for configuring the way waterfall
      parallelism behaves once underlying system resource limits are
      reached.  This flag is most relevant to [47m:full[0m waterfall
      parallelism.  see [set-total-parallelism-work-limit] for more
      information.

      The [47m[dmr][0m utility has the same behavior in ACL2(p) as it has in ACL2
      unless waterfall-parallelism has been set to a non-[47mnil[0m value
      (see [set-waterfall-parallelism]), in which case statistics
      about parallel execution are printed instead of the usual
      information.

      The user can now build the regression suite using waterfall
      [parallelism].  See the distributed file
      [47macl2-customization-files/README[0m for details, and see
      [unsupported-waterfall-parallelism-features] for a disclaimer
      related to building the regression suite using waterfall
      parallelism.

      When building ACL2 with both the hons and parallelism extensions
      (what is called ``ACL2(p)'' or, equivalently, ``ACL2(hp)''),
      the functions that are automatically memoized by the hons
      extension are now automatically unmemoized and memoized when
      the user toggles waterfall parallelism on and off,
      respectively.

      Calling [47m[set-waterfall-parallelism][0m with a flag of [47mt[0m now results in
      the same settings as if it were called with a flag of
      [47m:resource-based[0m, which is now the recommended mode for
      waterfall parallelism.  Thanks to Shilpi Goel for requesting
      this feature.

      The prover now aborts in a timely way in response to interrupts
      issued during a proof with waterfall parallelism enabled.
      (This had often not been the case.)  Thanks to Shilpi Goel for
      requesting this improvement.

  Among the enhancements for the HONS extension (see
  [hons-and-memoization]) are the following.

      The compact-print code has been replaced by new serialization
      routines contributed by Jared Davis.  This may improve
      performance when including books that contain [47m[make-event][0ms
      that expand to very large constants.  You can also now save
      objects to disk without going into raw lisp; see [serialize]
      for details.

      Printing of certain messages has been sped up (by using Lisp function
      [47mforce-output[0m in place of [47mfinish-output[0m).  Thanks to Jared Davis
      for contributing this improvement.

      [Stobj] array writes are perhaps twice as fast.

      It is now permitted to [memoize] functions that take user-defined
      [stobj]s as inputs, provided that no [stobj]s are returned.
      Even if stobjs are returned, memoization is permitted provided
      the condition is [47mnil[0m, as when profiling (see [profile]).
      Thanks to Sol Swords for an observation that led to this
      improvement and for useful conversations, including follow-up
      leading us to improve our initial implementation.

      Fixes have been made for memoizing with a non-[47mnil[0m value of
      [47m:ideal-okp[0m.  Errors had occurred when memoizing with a
      [47m:condition[0m other than [47mt[0m for a [47m:[0m[47m[logic][0m mode function that had
      not been [guard]-verified, even with a non-[47mnil[0m value of
      [47m:ideal-okp[0m; and after successfully memoizing such a function
      (without such [47m:condition[0m), it had not been possible to
      [47m[unmemoize][0m it.  Thanks to Sol Swords for reporting issues with
      the [47m:ideal-okp[0m argument of [47m[memoize][0m.

      If a book defined a function that was subsequently [memoize]d in that
      book, the function would no longer behaves as memoized upon
      completion of book certification (unless that [47m[certify-book][0m
      command was undone and replaced by evaluation of a
      corresponding [47m[include-book][0m command).  This has been fixed.
      Thanks to David Rager for pointing out the problem by sending
      an example.

      We now support ACL2(h) built not only on 64-bit CCL but also on all
      supported host Ansi Common Lisps (i.e., all supported host
      Lisps except GCL).  Thanks to Jared Davis for doing much of the
      work to make this improvement.  Note that performance will
      likely be best for 64-bit CCL; for some Lisps, performance may
      be much worse, probably depending in part on the underlying
      implementation of hash tables.")
 (NOTE-6-0
  (RELEASE-NOTES)
  "ACL2 Version 6.0 (December, 2012) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 5.0 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, changes at the system level,
  Emacs support, and experimental versions.  Each change is described
  in just one category, though of course many changes could be placed
  in more than one category.

  NOTE.  But we start with one major change that is outside the usual
  categories:

  [31;1mLICENSE change[0m

  The ACL2 license has been changed from GPL Version 2 to a 3-clause
  BSD license, found in the [47mLICENSE[0m file distributed with ACL2.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  Function [47m[fmt-to-string][0m and similar functions (see
  [printing-to-strings]) now use the default right margin settings;
  formerly the right margin had been set at 10,000.  If you want the
  former behavior, you can use the [47m:fmt-control-alist[0m, as illustrated
  below.

    (fmt-to-string \"~x0\"
                   (list (cons #\\0 (make-list 30)))
                   :fmt-control-alist
                   `((fmt-soft-right-margin . 10000)
                     (fmt-hard-right-margin . 10000)))

  The use of attachments (see [defattach]) has been made more
  efficient, avoiding some low-level checks (Common Lisp `[47mboundp[0m'
  checks).  Thanks to Shilpi Goel for constructing an example that we
  used to help direct us to remove inefficiency.  The following
  results for that example --- a Fibonacci program run on a machine
  interpreter in raw-mode (see [set-raw-mode]) --- give a sense of
  the potential speedup, though we note that a full ACL2(h)
  regression showed no significant speedup.

    ; Time before the change:
    ; 0.89 seconds realtime, 0.90 seconds runtime

    ; Time after the change:
    ; 0.75 seconds realtime, 0.75 seconds runtime

    ; Time when cheating to avoid the cost of attachments, by redefining a
    ; function to BE its attachment (so, this gives a lower bound on possible
    ; execution time):
    ; 0.72 seconds realtime, 0.72 seconds runtime

  Functions [47mread-acl2-oracle[0m and [47mread-acl2-oracle@par[0m are no longer
  untouchable (see [remove-untouchable]).  We reported this change
  for Version_5.0 but it was not made; thanks to Jared Davis for
  bringing this to our attention.  Function [47mget-timer[0m also is no
  longer untouchable.

  The function [47m[butlast][0m now behaves more reasonably on arguments
  violating its [guard].  For example, [47m(butlast '(1 2 3) -1)[0m is now
  provably equal to [47m(1 2 3)[0m instead of to [47m(1 2 3 nil)[0m.  Thanks to
  Jared Davis for suggesting a change to the definition of [47mbutlast[0m.

  The utilities [47mmfc-ts[0m and [47mmfc-ap[0m (see [extended-metafunctions])
  formerly never used forcing (see [force]).  Now, by default,
  forcing is allowed during execution of these functions if and only
  if it is permitted in the rewriting environment where they are
  called.  Moreover, these and the [47mmfc-xx[0m utilities --- [47mmfc-rw[0m,
  [47mmfc-rw+[0m, and [47mmfc-relieve-hyp[0m --- are now macros that take
  (optional) keyword arguments [47m:forcep[0m and [47m:ttreep[0m.  The [47m:forcep[0m
  argument is [47m:same[0m by default, providing the forcing behavior
  inherited from the environment (as described above); but it can be
  the symbol [47mt[0m or [47mnil[0m, indicating that forcing is to be enabled or
  disabled, respectively.  The [47m:ttree[0m argument is [47mnil[0m by default, but
  when it is [47mt[0m, then a second value is returned, which is a tag-tree.
  See [extended-metafunctions].

  Many improvements have been made to the tau-system (see
  [tau-system]), including support for arithmetic intervals bounded
  by constants.  Thus, for example, [47m(and (<= 0 x) (<= x 15))[0m is a tau
  predicate.  The [documentation] has also been improved (see
  [introduction-to-the-tau-system]). Also see [time-tracker-tau] for
  discussion of how the new [47m[time-tracker][0m utility can help discover
  ways to detect slowdown related to the tau-system.

  The [47m[defthm][0m [events] printed by [47m[defabsstobj][0m, namely those that
  remain to be proved, are now given with [47m:rule-classes nil[0m since
  there is probably no intention to use them as rules.  Thanks to
  Robert Krug for suggesting that we consider this change.

  The formal parameters for a macro definition (see [defmacro]) may now
  include [47m[state][0m and user-defined [47m[stobj][0ms.  (However, macro formals
  may not be declared as stobjs; see [xargs].)  Thanks to Jose Luis
  Ruiz-Reina for raising this issue and to Rob Sumners for helpful
  conversations --- both of these nearly 10 years ago!

  The utilities [47m[defun-inline][0m, [47m[defun-notinline][0m, [47m[defund-inline][0m, and
  [47m[defund-notinline][0m have been simplified, by taking advantage of the
  lifting of restrictions on formal parameters of macro definitions
  mentioned above (involving symbols that happen to be [stobj]
  names).  Now, when any of the above four utilities is called with a
  given set of formal parameters, those formals will be used not only
  for the generated [47m[defun][0m event but also for the generated
  [47m[defmacro][0m event.  (Previously, they had been renamed for the
  [47m[defmacro][0m event in order to respect the stobj name restriction
  that no longer exists.)  Thanks to Jared Davis for pointing out the
  value of making this change.

  The [events] [47m[add-invisible-fns][0m and [47m[remove-invisible-fns][0m now
  convert arguments as appropriate using the [47m[macro-aliases-table][0m.
  For example, the event [47m(add-invisible-fns append car)[0m is now legal
  (though probably not a good idea), because [47madd-invisible-fns[0m is now
  sensitive to the fact that [47m[append][0m maps to [47m[binary-append][0m in the
  [47m[macro-aliases-table][0m.

  When [47m:[0m[47mpe[0m is applied to a built-in function that does not have a
  defining event, such as [47m[symbolp][0m, [47m:pe[0m now gives more useful output
  that points to the documentation instead of printing a call of
  [47mENTER-BOOT-STRAP-MODE[0m.  Thanks to Anthony Knape for bringing this
  issue to our attention.

  The macros [47m[memoize][0m and [47m[unmemoize][0m now cause a warning rather than
  an error in ACL2 (and work as before in ACL2(h)).

  Terms are now parsed into [47m:[0m[47m[type-prescription][0m rules in a manner that
  removes [47m[let][0m bindings both at the top level and in the conclusion
  (but still not in the hypotheses of the rule).  See
  [type-prescription].  Thanks to Jared Davis for requesting such an
  enhancement.

  Printing of numbers is now appropriately sensitive to the print
  radix; see [set-print-radix].  Thanks to Shilpi Goel for requesting
  this enhancement.

  The system function [47mexplode-atom[0m no longer includes the radix
  indicator.  The new function [47mexplode-atom+[0m may be used for that
  purpose.

  [31;1mNEW FEATURES[0m

  Among the new features for system hackers are analogues of system
  function [47msimple-translate-and-eval[0m that do not return [47m[state][0m.
  (Thanks to David Rager for requesting this feature and helpful
  conversations on its implementation.)  This and other low-level
  changes are typically documented in comments in the corresponding
  release note event, which in this case is [47m(deflabel note-6-0 ...)[0m.

  More built-in functions are now [guard]-verified (and in [47m:[0m[47m[logic][0m
  mode).  Furthermore, a mechanism exists for marking yet more
  built-in functions as guard-verified based on [books] contributed
  by users; see Part II of
  {http://www.cs.utexas.edu/users/moore/acl2/open-architecture/ |
  http://www.cs.utexas.edu/users/moore/acl2/open-architecture/}.  The
  current state of that enterprise may be viewed by evaluating the
  constant [47m*system-verify-guards-alist*[0m, which associates a community
  book name with a list of functions.  When ACL2 is built in the
  normal way, each of those functions is marked as guard-verified
  when ACL2 is started up; but a special developer build can be used
  to check that the indicated book, together with its sub-books,
  proves that those functions are guard-verified.

  Metatheorems (see [meta]) may now have additional hypotheses, called
  ``meta-extract hypotheses'', that allow metafunctions to depend on
  the validity of certain terms extracted from the context or the
  logical [world].  See [meta-extract].  Thanks to Sol Swords for
  providing an initial implementation, together with very helpful
  discussions as well as a community book,
  [47mbooks/clause-processors/meta-extract-user.lisp[0m, that extends the
  power of meta-extract hypotheses.

  New utilities [47moracle-funcall[0m, [47moracle-apply[0m, and [47moracle-apply-raw[0m call
  a function argument on specified arguments.  Thanks to Jared Davis
  for requesting this utility.

  A new utility makes it convenient to track time spent inside
  specified function calls or, more generally, during specified
  evaluation.  See [time-tracker].

  New runic designators make it easy to refer to macro names when
  building theories.  Thus, for example, the object [47m(:i append)[0m may
  be used in theory expressions to designate the [rune] [47m(:induction
  binary-append)[0m.  See [theories].  Thanks to Jared Davis for a
  useful discussion leading to this enhancement.

  [47m[Defabsstobj][0m [events] now take an optional [47m:congruent-to[0m keyword
  argument, much like [47m[defstobj][0m.  Thanks to Sol Swords for
  requesting this feature and for suggesting a very nice optimization
  that avoids the need to prove additional lemmas.

  [47m[Flet][0m may now include [47minline[0m and [47mnotinline[0m declarations.  Thanks to
  Jared Davis for requesting this feature.

  The utility [47mgc-verbose[0m controls printing of messages by the garbage
  collector, for certain host Lisps.  See [gc-verbose].  Thanks to
  Shilpi Goel for requesting this utility.

  Added definitions of functions [47m[nat-listp][0m and [47m[ACL2-number-listp][0m.
  Thanks to Harsh Raju Chamarthi for requesting these additions.
  Many community books had varying definitions of these functions;
  these additions guarantee that all books must agree on how these
  two functions are defined.  (Some community books have been changed
  in order that they remain certifiable, given these additions.)
  Note that a few built-in [47m:[0m[47m[forward-chaining][0m rules were modified in
  order to accommodate these additions, and the definition of
  [47m[integer-listp][0m was modified to call [47m[eq][0m instead of [47m[equal][0m, like
  the other such definitions.

  See [get-command-sequence] for a new utility that returns a list of
  [command]s between two given command descriptors.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  We obtained a substantial speedup --- 13% observed for the regression
  suite, and 8% observed for the ACL2(h) regression suite --- by
  tweaking the [break-rewrite] implementation to eliminate virtually
  all of its overhead when it is not in use (the default, which holds
  until [47m:[0m[47m[brr][0m[47m t[0m is evaluated).  Thanks to David Rager for a
  conversation involving ACL2(p) performance statistics that
  suggested looking at changing [break-rewrite] to boost performance.

  The heuristics for automatically expanding recursive function calls
  have been changed during proofs by induction.  Now, during
  induction, more terms that suggested the induction scheme are
  automatically expanded.  Thanks to David Rager for providing an
  example and having discussions with us that spurred us to develop
  this heuristic improvement.

  [31;1mBUG FIXES[0m

  Fixed a soundness bug in [47m[defabsstobj][0m based on [47m[guard][0ms that
  violated single-threadedness restrictions.  Thanks to Sol Swords
  for bringing this bug to our attention and supplying a proof of
  [47mnil[0m, which we include as a comment in source file [47mld.lisp[0m, in
  [47m(deflabel note-6-0 ...)[0m.  We also thank Sol for helpful discussions
  about [guard]s of functions introduced by [47mdefabsstobj[0m, which has
  led us to enhance the [documentation]; see [defabsstobj].

  Fixed a soundness bug in [47m[defabsstobj][0m based on interrupted updates
  of abstract stobjs.  As part of the fix a new keyword, [47m:PROTECT[0m,
  has been introduced for [47mdefabsstobj[0m exports, along with a new
  top-level [47mdefabsstobj[0m keyword, [47m:PROTECT-DEFAULT[0m; see [defabsstobj].
  We do some analysis that we expect will avoid the use of [47m:PROTECT[0m
  in many cases, which is fortunate since the use of [47m:PROTECT t[0m may
  cause a slight slowdown in (abstract) stobj updates.  Thanks to Sol
  Swords for bringing this bug to our attention and supplying a proof
  of [47mnil[0m, which we include as a comment in source file
  [47mother-events.lisp[0m, in the definition of function
  [47mset-absstobj-debug[0m.

  Fixed a raw Lisp error that occurred when tracing a [3mstobj[0m resize
  function, thanks to an error report from Warren Hunt, Marijn Heule,
  and Nathan Wetzler.

  Fixed a raw Lisp error that occurred for certain ill-formed
  signatures, as in the following example.

    ACL2 !>(encapsulate
               (((f (*) => * :guard t)))
               (local (defun f (x) (consp x))))

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    Error:  value (F (*) => * :GUARD T) is not of the expected type SYMBOL.
    ***********************************************

  The notion of ``error triple'' (see [error-triple]) had been
  implemented ambiguously, with the result that for a [stobj], [47mst[0m,
  the result of evaluating the following two forms was the same: [47m(mv
  nil st state)[0m and [47m(mv t st state)[0m.  Of course, these are just
  examples; in general, a result of [47m(mv erp val state)[0m was sometimes
  treated as an error triple even when [47mval[0m is a [stobj].  Now, [47m(mv
  erp val state)[0m is an error triple only when [47merp[0m and [47mval[0m are
  ordinary (non-[stobj]) values.  Thanks to Warren Hunt and Marijn
  Heule for bringing this problem to our attention.

  The ``with-error-trace'' utility, [47m[wet][0m, now works in the non-error
  case when given a form that returns multiple values.  (Note however
  that [47m[state][0m will be printed as [47mREPLACED-STATE[0m; and similarly, a
  user-defined [stobj], say [47mST[0m, will be printed as [47mREPLACED-ST[0m.)

  Some possible error messages for [47m[defabsstobj][0m have been fixed that
  had been ill-formed.  Thanks to Sol Swords for bringing this bug to
  our attention.

  Fixed a bug that sometimes caused the times displayed in the summary
  for [47m[certify-book][0m to be smaller than the actual times.

  Fixed a bug in the [guard]s to system functions [47mfmt-char[0m and [47mfmt-var[0m,
  which are no longer [47m:[0m[47m[logic][0m-mode, guard-verified functions.

  (GCL only) Fixed a bug present in Gnu Common Lisp for [47m#u[0m (see
  [sharp-u-reader]).

  [31;1mCHANGES AT THE SYSTEM LEVEL[0m

  The [state] global variable [47m'distributed-books-dir[0m has been renamed
  [47m'system-books-dir[0m.  On a related note, the [documentation] now
  refers to ``community books'' rather than ``distributed books'',
  and there is a corresponding new documentation topic; see
  [community-books].

  Fixed a bug in the implementation of [47m[wet][0m (which is actually in the
  community book [47mbooks/misc/wet.lisp[0m).

  A directory, [47minterface/[0m, is no longer part of the ACL2 distribution.
  Rather, it is a subdirectory of the ACL2 community books.  Thus, if
  you fetch those books in the usual way (see the installation
  instructions on the ACL2 home page), you will find a directory
  [47mbooks/interface/[0m.  Subdirectory [47memacs/[0m of that [47minterface[0m directory
  provides Emacs support for [proof-tree]s as well an [47macl2-mode[0m.
  This change has been reflected in ACL2 file [47memacs/emacs-acl2.el[0m, so
  users will probably not be impacted if they load that file into
  Emacs.

  The community books file [47mbooks/Makefile-generic[0m now causes, by
  default, a backtrace to be printed when there is a raw Lisp error.

  Some changes have been made to how regressions are run, i.e., to how
  the community books are certified.  (1) The standard regression now
  includes community books directory [47mbooks/centaur[0m.  To skip these
  (for example, a Windows system has encountered difficulty with them
  even after installing Perl), include [47mACL2_CENTAUR=skip[0m with your
  `make' command.  (2) A new `make' (or environment) variable,
  [47mACL2_JOBS[0m, specifies the number of parallel jobs to run, serving as
  a replacement for the [47m-j[0m argument of `make' that works for all
  community books, including those under directory [47mcentaur[0m; see
  [books-certification-classic].  (3) It is no longer necessary to do
  an ACL2(h) regression in order to build a copy of the documentation
  generated by Jared Davis's xdoc utility at
  [47mbooks/xdoc-impl/manual/preview.html[0m; a vanilla ACL2 regression will
  build this manual.  (4) It is no longer necessary to set the [47mACL2[0m
  environment variable for ACL2(h) regressions if you want to use the
  executable [47msaved_acl2h[0m in the ACL2 sources directory.

  The ACL2 home page now has a search utility for documentation and
  books.  Thanks to Shilpi Goel and David Rager for feedback on a
  preliminary version of this utility.

  (only for SBCL with 64-bit ACL2(h)) The value of SBCL command line
  option [47m--dynamic-space-size[0m for ACL2(h) on 64-bit platforms has
  been increased from 2000 to 16000 (as explained in a comment in the
  ACL2 source definition of [47m*sbcl-dynamic-space-size*[0m).

  [31;1mEMACS SUPPORT[0m

  [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m

  Among the enhancements for ACL2(r) (see [real]) are the following.

      Thanks to Ruben Gamboa for his helpful role in making the following
      improvements made with Ruben Gamboa in support for non-standard
      analysis in ACL2(r).

      Constrained functions can now be introduce as non-classical.  See
      [signature].

      [47m[Defun-sk][0m now takes a new keyword argument, [47m:CLASSICALP[0m, that
      determines whether or not the named function is classical.  See
      [defun-sk].

      Incorporated a bug fix from Ruben Gamboa for [47m[ceiling][0m.  The default
      (for `bad' arguments) had been 1, but now we follow normal ACL2
      practice by returning 0 in that case.

  Among the enhancements for the HONS extension (see
  [hons-and-memoization]) are the following.

      Macros [47m[with-fast-alist][0m, [47m[with-stolen-alist][0m, and
      [47m[fast-alist-free-on-exit][0m are now defined in ACL2(h), rather
      than being defined in the community book
      [47m\"books/centaur/misc/hons-extra.lisp\"[0m.  Thanks to Jared Davis
      and Sol Swords for donating this code, and thanks to Jared for
      helpful discussions leading to this change.

  Among the enhancements for ACL2(p) (see [parallelism]) are the
  following.  We thank David Rager for his work in developing ACL2(p)
  and for his helpful role in these improvements.

      A bug has been fixed that could leave one in a [wormhole], awaiting
      input, after an error, such as an error in an [47m:in-theory[0m hint
      during a proof.  Thanks to Shilpi Goel for bringing this bug to
      our attention.

      A key checkpoint for a given goal is now printed only once.
      Previously, if a key checkpoint led to more than one goal
      pushed for proof by induction, the key checkpoint would be
      printed once for each such goal during the proof, and also once
      for each such goal in the summary at the end.")
 (NOTE-6-1
  (RELEASE-NOTES)
  "ACL2 Version 6.1 (February, 2013) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 6.0 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, changes at the system level,
  Emacs support, and experimental versions.  Each change is described
  in just one category, though of course many changes could be placed
  in more than one category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  More system functions are in [47m:[0m[47m[logic][0m mode, [guard]-verified.
  Evaluate

    (strip-cars (cdr (assoc-equal \"system/top\" *system-verify-guards-alist*)))

  for the list of functions checked to be guard-verifiable in the
  community books.  (NOTE added after Version_8.3: The form is now
  [47m(strip-cars *system-verify-guards-alist*)[0m.)  Thanks to those who
  have contributed to this effort, as shown in file headers in
  directory [47msystem/[0m of the community books.

  The macro [47m[defund][0m now avoids an error when [47m:mode :program[0m has been
  specified in an [47m[xargs][0m form of a [47m[declare][0m form, for example:
  [47m(defund f (x) (declare (xargs :mode :program)) x)[0m.  It does this by
  avoiding the generation of [47m[in-theory][0m [events] in such cases.
  Thanks to David Rager and Jared Davis for requesting such a change,
  and for ensuing helpful discussions.

  Added a field [47m:UNIFY-SUBST[0m to metafunction contexts (see
  [extended-metafunctions]), accessed with function [47mmfc-unify-subst[0m.
  Thanks to Sol Swords for requesting this enhancement.

  The functions [47m[sys-call][0m and [47m[sys-call-status][0m are now
  [guard]-verified [47m:[0m[47m[logic][0m-mode functions.

  It had been the case that if any supporter of a dependent clause
  processor (see [define-trusted-clause-processor]) is among the
  ancestors of a given formula, then it was illegal to apply
  functional instantiation (see [lemma-instance]) to that formula.
  Now, this is illegal only if some such supporter is in the domain
  of the functional substitution.

  The tau system (see [tau-system], or if you are unfamiliar with the
  tau system, see [introduction-to-the-tau-system]) now allows the
  user to define and verify functions that compute bounds on
  arithmetic expressions.  See [bounders].

  The utility [47mprint-summary-user[0m has been replaced by
  [47m[finalize-event-user][0m, which is described below.  If you previously
  attached a function to [47mprint-summary-user[0m, say
  [47mmy-print-summary-user[0m, then you can get the effect you had
  previously as follows.

    (defun my-finalize-event-user (state)
      (declare (xargs :mode :logic :stobjs state))
      (prog2$ (my-print-summary-user state)
              state))
    (defattach finalize-event-user my-finalize-event-user)

  It had been the case that when you [47m[ld][0m a file, the connected book
  directory (see [cbd]) was set to the canonical pathname of that
  file's directory for the duration of the [47mLD[0m call.  This could cause
  problems, however, if the file is actually a soft link: an
  [47m[include-book][0m form in the book with a relative pathname for the
  book would be resolved with respect to the absolute pathname for
  that link, which is probably not what was intended.  So soft links
  are no longer followed when computing the above connected book
  directory.  The following example, which is how we discovered this
  problem, may clarify.  We attempted to execute the form [47m(ld
  \"top.lisp\")[0m using ACL2(r) (see [real]) in community books directory
  [47mnonstd/arithmetic/[0m, where all of the [47m.lisp[0m files are soft links to
  files in [47marithmetic/[0m.  Thus, the form [47m(include-book \"equalities\")[0m
  attempted to include [47marithmetic/equalities[0m instead of
  [47mnonstd/arithmetic/equalities[0m, which caused an error.

  We no longer document the use of value [47m:START[0m for
  [47m[with-prover-step-limit][0m.  This value has always been used by the
  ACL2 implementation and may have semantics that change with new
  ACL2 versions.  If you have reason to use this value, please
  contact the ACL2 implementors.

  [31;1mNEW FEATURES[0m

  By default, the prover now gives information about case splits.  See
  [splitter].  Thanks to many ACL2 users, most recently David Rager,
  for requesting such a capability.  Also thanks to David Rager and
  Jared Davis for helpful discussions, and thanks to Robert Krug for
  feedback on the initial implementation and documentation that led
  us to make improvements.

  New utilities [47m[initialize-event-user][0m and [47m[finalize-event-user][0m allow
  the user to run [state]-modifying code at the start and end of
  [events].  Thanks to Harsh Raju Chamarthi for requesting these
  capabilities.  Note that [47m[finalize-event-user][0m replaces
  [47mprint-summary-user[0m.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  Several heuristic improvements have been made to the tau system, even
  if you do not explicitly use the new capability for computing
  bounds on arithmetic expressions, mentioned above.  See
  [tau-system], or if you are unfamiliar with the tau system, see
  [introduction-to-the-tau-system].

  [31;1mBUG FIXES[0m

  A soundness bug has been fixed that exploited the use of expansion
  files (see [book-compiled-file]) together with [47m[defstobj][0m.  For an
  example illustrating this bug, see the comment about
  ``Expansion/Defstobj Bug'' in the form [47m(deflabel note-6-1 ...)[0m in
  ACL2 source file [47mld.lisp[0m.

  We fixed a soundness bug involving system function
  [47m[canonical-pathname][0m and (most likely) other functions in the
  former value of constant [47m*unattachable-primitives*[0m.  Thanks to
  Jared Davis and Sol Swords for bringing this bug to our attention
  by way of an example.  We include a very slight variant of that
  example in a comment within the form [47m(deflabel note-6-1 ...)[0m in
  ACL2 source file [47mld.lisp[0m.

  There was a soundness bug that allowed attachments to prove [47mnil[0m in a
  consistent logical [world] involving [47m[defaxiom][0m [events].  This has
  been fixed, by requiring that no function symbol ancestral in a
  [47m[defaxiom][0m formula is allowed to get an attachment.  See
  [defattach], in particular discussion of ``a restriction based on a
  notion of a function symbol syntactically supporting an event'',
  which concludes with a proof of [47mnil[0m that is no longer possible.

  (ACL2(h) only) We fixed a soundness bug in the interaction of
  memoization with congruent stobjs, in cases where the [47m:congruent-to[0m
  field of [47m[defstobj][0m was not the canonical representative in the
  congruence class.  For an example illustrating this bug, see the
  comment about ``memoize/congruent stobj bug'' in the form [47m(deflabel
  note-6-1 ...)[0m in ACL2 source file [47mld.lisp[0m.

  Functions defined by [47m[defstobj][0m had failed to be compiled when
  certifying books, except in host Lisps that compile on-the-fly
  (CCL, SBCL).  This has been fixed for all host Lisps.  A related
  change, probably less significant, was made for [47m[defabsstobj][0m.
  Thanks to Sol Swords for reporting bugs that turned out to be
  mistakes in a preliminary implementation of this change.

  Fixed an assertion error involving linear arithmetic.  Thanks to Sol
  Swords for sending an example illustrating the bug (now appearing
  as a comment in ACL2 source function [47mlinearize1[0m).

  Fixed a bug that was breaking the ACL2s build mechanism (see
  [ACL2-sedan]) by causing certain needless evaluation of ``hidden
  [47m[defpkg][0m'' forms in [certificate] files when executing a call of
  [47m[include-book][0m.  The bug could also affect rare error messages
  arising from ill-formed [certificate] files.  Thanks to Harsh Raju
  Chamarthi for bringing this bug to our attention by sending us an
  example script of the sort that was breaking during an ACL2s build.

  Fixed handling of pathnames by some low-level code (system function
  [47mour-truename[0m) that could cause errors, for example for host-Lisp
  GCL on some platforms when environment variable [47mHOME[0m points to a
  non-existent directory.  Thanks to Camm Maguire for bringing this
  issue to our attention and helping with the debugging.

  Fixed a coding bug in generation of stobj resizing functions for a
  stobj named [47mOLD[0m.  The following example illustrates the bug.

    (defstobj old
      (fld :type (array (unsigned-byte 31) (8))
            :initially 0 :resizable t))
    (resize-fld 10 old)
    ; The following returned 8 but should have returned 10:
    (fld-length old)

  Fixed a bug in [47m[defabsstobj-missing-events][0m (which macroexpanded
  incorrectly).  Thanks to Sol Swords for bringing this bug to our
  attention.

  Fixed two bugs in the handling of step-limits.  Thanks to Hanbing Liu
  for bringing the main such bug to our attention, which was that
  ACL2 could report a step-limit violation during [47m[certify-book][0m (in
  fact, during any compound event such as a call of [47m[encapsulate][0m or
  [47m[progn][0m), even without direct user involvement in managing
  step-limits (see [set-prover-step-limit] and see
  [with-prover-step-limit]).  The other bug was that a bad argument
  to [47m[set-prover-step-limit][0m could result in a raw Lisp error, for
  example: [47m(progn (set-prover-step-limit '(a b)))[0m.

  [31;1mCHANGES AT THE SYSTEM LEVEL[0m

  The [47mbooks/[0m directory no longer needs to exist in order to build an
  ACL2 executable.  Thanks to Robert Krug for pointing out that the
  installation instructions had suggested that this was already the
  case.

  Many changes have been made to the [community-books].  For example,
  some community books now include [47mstd/lists/rev.lisp[0m, which contains
  the rule [47mrevappend-removal[0m, which may cause some proofs involving
  [47m[revappend][0m to fail where they formerly succeeded, or vice-versa.
  When a proof fails that formerly succeeded, it may be useful for
  you to look over the [rune]s printed in the event summary.

  [31;1mEMACS SUPPORT[0m

  [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m

  For ACL2(p), [47m[wormhole-eval][0m is now locked by default; thanks to
  David Rager for suggesting this change.  But there is a way to
  avoid the lock; see [wormhole-eval].  In particular, the lock is
  avoided in the implementations of [accumulated-persistence] and
  [forward-chaining-reports], which are not supported in ACL2(p) (see
  [unsupported-waterfall-parallelism-features]).")
 (NOTE-6-2
  (RELEASE-NOTES)
  "ACL2 Version 6.2 (June, 2013) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 6.1 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, changes at the system level,
  Emacs support, and experimental versions.  Each change is described
  in just one category, though of course many changes could be placed
  in more than one category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  The macro [47m[top-level][0m has been changed, so that evaluation of a form
  [47m(top-level x)[0m results in an error when evaluation of [47mx[0m results in
  an error.  Thanks to Jared Davis for observing that when evaluating
  a file using [47m[ld][0m, an interrupt of a call of a [47m[top-level][0m call in
  that file would not prevent evaluation of later forms in the file.

  The macro [47m[the][0m no longer causes an error when [guard]-checking is
  [47m:NONE[0m.  For example, it had been the case that evaluation of [47m(the
  integer t)[0m always caused an error; but now, there is no error after
  executing command [47m:[0m[47m[set-guard-checking][0m[47m :NONE[0m.  Thanks to Jared
  Davis for asking for a way to avoid such errors.

  The error printed when attempting to ``reincarnate'' a package ---
  that is, to define a package that is not part of the ACL2 logical
  [world] but exists in raw Lisp because it was once part of the
  world --- is now much more instructive.  In particular, it shows
  pathnames for the previous and proposed [47m[defpkg][0m events, and it
  shows the symbols that are imported by one but not the other.
  Thanks to Jared Davis for requesting this improvement.

  Functions [47m[open-input-channel][0m and [47m[open-output-channel][0m no longer
  cause an error when failing to open a channel because of a
  permissions problem, but instead return [47m(mv nil state)[0m.  Thanks to
  Jared Davis for requesting this change.  (Note: this change does
  not apply if the host Lisp is non-ANSI, i.e., if the host Lisp is
  non-ANSI GCL.)

  The advanced [meta-extract] mechanisms, provided for using facts from
  the [world] or metafunction context, have been enhanced in the
  following ways, in collaboration with Sol Swords.  See
  [meta-extract] for more details.

      It is now permissible to use calls of [47mmeta-extract-global-fact[0m in
      hypotheses of [47m[clause-processor][0m rules, much as they are used
      in hypotheses of [47m[meta][0m rules.  See [meta-extract].  Thanks to
      Sol Swords for requesting this feature.

      The utility [47mmeta-extract-global-fact[0m is now a macro, which expands to
      a corresponding call of the new function,
      [47mmeta-extract-global-fact+[0m.  This new function takes an
      alternate, extra [state] as an argument; it is not to be
      executed, and it operates on the alternate state, whose logical
      [world] is intended to be the same as that of the ``live''
      (usual) state.

      A new sort of value for the [47mobj[0m argument is supported for
      [47mmeta-extract-global-fact[0m (and [47mmeta-extract-global-fact+[0m), which
      results in a term equating a function application to its
      result.  See [meta-extract], in particular the discussion of
      [47m:fncall[0m.

  It is now possible for [47mtrace$[0m to avoid printing prefixes of the form
  [47m\"n> \"[0m and [47m\"<n \"[0m, while also (optionally) avoiding indentation.  See
  [trace$], in particular the discussion of [47m:fmt![0m.  Thanks to Shilpi
  Goel for requesting this feature.

  It was possible for the [guard-debug] feature to generate duplicate
  calls of [47mextra-info[0m in hypotheses generated for guard verification.
  We have eliminated duplicates of this sort.

  When [47m[in-theory][0m returns without error, it returns a value
  [47m(:NUMBER-OF-ENABLED-RUNES k)[0m, where [47mk[0m is the length of the new
  current theory.  (Formerly, [47mk[0m was returned.)  This value is thus
  printed when an [47min-theory[0m event is submitted at the top level.
  Thanks to Gisela Rossi for feedback that led us to make this
  change.

  A new keyword parameter for [47m[ld][0m is [47m:ld-missing-input-ok[0m.  Its
  default value is [47mnil[0m, which causes an error, as before, upon
  failure to open a specified file.  Other legal values are [47mt[0m and
  [47m:WARN[0m; see [ld-missing-input-ok] and see [ld].

  Extended [47m*acl2-exports*[0m, in particular adding [47mUNSIGNED-BYTE-P[0m and
  [47mSIGNED-BYTE-P[0m (thanks to a suggestion by Jared Davis)

  Even if the function [47mf[0m is defined to take one or more [stobj]
  arguments, the form [47m(ec-call (f ...))[0m is now legal if all arguments
  of the call of [47mf[0m are non-stobj objects, in any context where only
  ordinary object return values are expected.

  When the second argument of [47m[certify-book][0m is a symbol, that symbol
  formerly needed to be [47m?[0m or [47mt[0m, in the [47m\"ACL2\"[0m package.  Now, the
  [symbol-package-name] of the second argument is ignored: any symbol
  whose [symbol-name] is [47m\"?\"[0m or [47m\"T\"[0m is treated the same in that
  argument position as the symbol [47m?[0m or [47mt[0m in the [47m\"ACL2\"[0m package,
  respectively.  Thanks to Warren Hunt and Nathan Wetzler for
  suggesting consideration of a more relaxed criterion for that
  second argument.

  (For system hackers, not standard ACL2 users:) Utilities
  [47m[initialize-event-user][0m and [47m[finalize-event-user][0m now each take a
  list of three arguments, [47m(ctx body state)[0m.  Thanks to Harsh Raju
  Chamarthi for requesting this change.

  [31;1mNEW FEATURES[0m

  It is now permissible to specify a [stobj] field that is itself
  either a stobj or an array of stobjs.  A new primitive,
  [47m[stobj-let][0m, is provided in order to access or update such fields;
  see [stobj-let].  Thanks to Warren Hunt and Sol Swords for
  requesting the ability to specify nested stobjs.

  New accessor function [47m(mfc-world mfc)[0m returns the world component of
  a metafunction context.  See [extended-metafunctions].

  A new [47m[xargs][0m keyword, [47m:SPLIT-TYPES[0m, can be used to ``split'' the
  [type] declarations from the [guard] in the following sense.  By
  default, or when [47m:SPLIT-TYPES[0m has value [47mnil[0m, one gets the existing
  behavior: the terms corresponding to type declarations are
  conjoined into the guard.  However, if [47m:SPLIT-TYPES t[0m is specified,
  then that is not the case; instead, guard verification will require
  that these terms are proved under the hypothesis that the guard
  holds.  In this way, one can add type declarations to assist the
  host Lisp compiler without cluttering the function's guard.  See
  [xargs].  Thanks to Jared Davis for requesting this feature.

  Advanced users may want to see
  [quick-and-dirty-subsumption-replacement-step] for a way to turn
  off a prover heuristic.  Thanks to those who have mentioned to us
  potential issues with this heuristic, most recently Dave Greve.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  We made changes to the ``ancestors check'' heuristic (source function
  [47mancestors-check-builtin[0m), as follows.

      The heuristic could prevent a [rewrite] rule's hypothesis from being
      rewritten to true, even when that hypothesis is of the form
      [47m(force <term>)[0m.  Now, forcing will take place as expected; see
      [force].  Thanks to Robert Krug for bringing this issue to our
      attention and sending an example, which we include as a comment
      in the ACL2 source code (see [47m(deflabel note-6-2 ...)[0m).

      The heuristic is now delayed until after we check whether the
      hypothesis is already known, using [type-set] reasoning alone
      (in particular, not using rewriting), to be true or to be
      false.  We believe that this is now the ``right'' order for
      those two operations.  We saw a slight speed up in the
      regression tests (about a percent) with this change, but that
      might be in the noise.

      A technical change makes the heuristic slightly less aggressive in
      preventing backchaining.  Roughly speaking, ordering checks
      based on function symbol counts could suffice to permit
      backchaining, where now variable counts also suffice.  Thanks
      to Robert Krug for showing us an example where backchaining led
      to a term with no free variables that was nevertheless subject
      to the ancestors check, preventing it from being rewritten.

      (For those who use [47m[defattach][0m to attach to [47mancestors-check[0m) We have
      used [47mdefrec[0m to introduce an `[47mancestor[0m' data structure.  A new
      function, [47mstrip-ancestor-literals[0m, should be used to obtain the
      literals from a list of ancestors, although [47mstrip-cars[0m will
      still work at this time.

  When we rewrite the current literal of the current clause we assume
  the falsity of the other literals and of the conclusions produced
  by forward chaining.  We have changed the order in which those
  assumptions are made, which affects the type-alist used during
  rewriting.  This has three effects: the new type-alist, which is
  sometimes stronger than the old one, may allow additional rules to
  fire, the choice of free vars may be different, and the order of
  the literals in forced subgoals may be different.  Should
  ``legacy'' proofs fail under the new type-alist, we recommend
  looking for rules that are fired in the new proof that were not
  fired (on that same subgoal) in the old one.  Thanks to Dave Greve
  for sending us an example that led us to make this change.

  [31;1mBUG FIXES[0m

  We fixed a soundness bug that could be exploited by calling system
  functions [47macl2-magic-mfc[0m or [47macl2-magic-canonical-pathname[0m.  Thanks
  to Sol Swords for bringing this bug to our attention.

  We fixed a soundness bug in the handling of [stobj]s, in which
  strings were recognized as stobjs in raw Lisp.  Thanks to Jared
  Davis for sending us a proof of [47mnil[0m that exploited this bug.  We
  now have a much simpler example of this bug, as follows.

    (defstobj st fld)
    (defthm bad (stp \"abc\") :rule-classes nil)
    (defthm contradiction
      nil
      :hints ((\"Goal\" :in-theory (disable (stp)) :use bad))
      :rule-classes nil)

  We fixed bugs in extended metafunctions (see
  [extended-metafunctions]).  The macro [47mmfc-ap[0m no longer takes a
  [47m:TTREEP[0m keyword argument, because this argument could allow
  returning a tag tree that does not properly account for forcing.
  The remaining [47mmfc-xx[0m macros --- [47mmfc-relieve-hyp[0m, [47mmfc-rw+[0m, [47mmfc-rw[0m,
  and [47mmfc-ts[0m --- still take a [47m:TTREEP[0m keyword argument, but the
  corresponding functions when [47m:TTREEP[0m is [47mt[0m ---
  [47mmfc-relieve-hyp-ttree[0m, [47mmfc-rw+-ttree[0m, [47mmfc-rw-ttree[0m, and
  [47mmfc-ts-ttree[0m --- were introduced with incorrect output signatures.
  A complication is that [47mmfc-relieve-hyp-ttree[0m was improperly defined
  in raw Lisp in a way that actually matched the incorrect signature!
  All of these bugs have been fixed.  Perhaps any of them could have
  made it possible to prove [47mnil[0m, though we have not tried to do so.

  (Windows only) On Windows, it had been possible for ACL2 not to
  consider two pathnames to name the same file when the only
  difference is the case of the drive, e.g., `[47mC:[0m' vs. `[47mc:[0m'.  This has
  been fixed.  Thanks to Sol Swords for reporting this issue.

  Fixed a bug in the storing of rules for the tau system; see
  [tau-system].  (The error message mentions
  PARTITION-SIGNATURE-HYPS-INTO-TAU-ALIST-AND-OTHERS.)  Thanks to Sol
  Swords for reporting this bug and sending a simple example to
  illustrate it.

  It had been possible to admit the missing [47m[defthm][0m events printed by
  [47m[defabsstobj][0m, and yet get an error when subsequently submitting
  the same [47mdefabsstobj[0m event, stating: ``Note discrepancy with
  existing formula''.  The problem could occur when an expression of
  the form [47m(or X Y)[0m occurred in one of those missing events, because
  ACL2 created it from the term [47m(if X 't Y)[0m but then translated [47m(or X
  Y)[0m to [47m(if X X Y)[0m, resulting in a mismatch.  This has been fixed.
  Thanks to Jared Davis for reporting this bug using a simple
  example.

  A hard Lisp error was possible for certain illegal functional
  substitutions (see [lemma-instance]).  Thanks to Sol Swords for
  reporting this bug.

  We fixed a bug in the case that an exported function of a
  [47m[defabsstobj][0m event had a [guard] of [47mt[0m.  Thanks to Jared Davis for
  sending a simple example when reporting this bug.

  We now avoid an infinite loop that could occur when attempting to
  close the standard character output channel (see [standard-co]).
  Instead, an error message explains how to accomplish what was
  probably intended.  Thanks to Shilpi Goel for bringing this issue
  to our attention.

  (Windows only) Fixed a bug that was causing a hard error on Windows
  when ACL2 encountered filenames starting with the tilde character
  ([47m~[0m), for example, [47m(ld \"~/acl2-customization.lsp\")[0m.  Thanks to Sol
  Swords for bringing this bug to our attention.  Also thanks to
  Harsh Raju Chamarthi for a useful conversation that led to a better
  fix than our first one.

  [31;1mCHANGES AT THE SYSTEM LEVEL[0m

  ACL2 may now be built on recent versions of a new host Lisp, ANSI Gnu
  Common Lisp (GCL).  Traditional (non-ANSI) GCL was the original
  host Lisp underlying ACL2, and we are grateful for GCL support that
  we received from the late Bill Schelter and, more recently and
  particularly for ANSI GCL, from Camm Maguire.

  The `make' process suggested for book certification has changed
  substantially, thanks in large part to contributions from Jared
  Davis and Sol Swords.  We have seen the new process provide better
  performance on machines with many cores, and we expect maintenance
  advantages such as eliminating the need for Makefiles in individual
  book directories.  The ``classic'' process, which was based on
  community books file [47mbooks/Makefile-generic[0m, is still supported
  (see [books-certification-classic]) but may disappear in a future
  release of ACL2.  See [books-certification].  Most changes should
  be invisible to the user, other than improved `make'-level
  parallelism, with the exception of the following.

      o Variable [47mACL2_JOBS[0m is no longer supported, nor is it necessary;
      simply use `make' option `-j' instead.

      o Regressions now use `make' option [47m-k[0m by default, which causes the
      regression to keep going after errors, rather than [47m-i[0m, which
      ignores errors.  If you encounter problems because of this
      change, use [47mACL2_IGNORE=-i[0m with your `make' command.

      o The `regression' target works for the experimental extension,
      ACL2(h) (see [hons-and-memoization]); target `regression-hons'
      no longer exists.

  Please let us know if you run into problems with the new
  infrastructure, as we consider the legacy infrastructure to be
  deprecated and we will probably eliminate much of it in the future.
  In particular, circular dependencies were formerly prohibited at
  the directory level, but that is no longer the case, and we expect
  such cycles to occur in the future.

  Although ACL2 users don't typically modify raw Lisp variables, we
  have arranged to reset Lisp variable [47m*default-pathname-defaults*[0m if
  necessary at startup so that it will not interfere with ACL2, in
  particular by messing up the initial connected book directory (see
  [cbd]).  Thanks to Jared Davis, Sol Swords, and Raymond Toy for
  helping us to identify this issue.

  [31;1mEMACS SUPPORT[0m

  [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m

  In ACL2(h), [47m[print-object$][0m no longer uses the serialize printer
  except in system applications as before (e.g., write out [47m.cert[0m
  files).  Thanks to Dave Greve for bringing this issue to our
  attention.

  Jared Davis contributed changes related to the [47m[memoize][0m utility of
  ACL2(h), including some low-level changes as well as the following.

  o [47m[Never-memoize][0m specifies that a given function should never be
  memoized.

  o Removed [47mmemoize-let[0m, which may never have ever been used.

  o Removed the [47m:inline[0m keyword option to memoize, which was just an
  alias for the [47m:recursive[0m option.

  For ACL2(p), some anomalous behavior may no longer occur because
  prover calls (more specifically, trips through the ACL2
  ``waterfall'') will return only after all sub-computations
  (threads) have finished.  Thanks to David Rager for contributing
  this improvement.

  ACL2(pr), which includes [parallelism] (as for ACL2(p)) and
  non-standard analysis support for the [real]s (as for ACL2(r)), now
  builds and can certify the community [47mnonstd/[0m books.  Thanks to
  David Rager for his contribution to this capability.")
 (NOTE-6-3
  (RELEASE-NOTES)
  "ACL2 Version 6.3 (October, 2013) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes since Version 6.2 into the
  following categories of changes: existing features, new features,
  heuristic improvements, bug fixes, changes at the system level,
  Emacs support, and experimental versions.  Each change is described
  in just one category, though of course many changes could be placed
  in more than one category.

  [31;1mCHANGES TO EXISTING FEATURES[0m

  The evaluation of a term from a [47m[bind-free][0m hypothesis had been
  expected to produce an alist binding free variables to terms.
  While that is still legal, it is also legal for that evaluation to
  produce a list of such alists: then each is considered, until one
  of them permits all remaining hypotheses to be relieved.  See
  [bind-free].  Thanks to Sol Swords for requesting this enhancement.

  ACL2 continues to provide a way to specify keyword command
  abbreviations for the top-level loop; see [ld-keyword-aliases].
  However, [47m[ld-keyword-aliases][0m is now a [table] rather than a
  [state] global; it is thus no longer a so-called [ld] special.  The
  functionality of [47mset-ld-keyword-aliases[0m has essentially been
  preserved, except that it is now an event (see [events]), hence it
  may appear in a book; it is [local] to a book (or [47m[encapsulate][0m
  event); and the [47m[state][0m argument is optional, and deprecated.  A
  non-local version ([47mset-ld-keyword-aliases![0m) has been added, along
  with corresponding utilities [47madd-keyword-alias[0m and
  [47madd-keyword-alias![0m for adding a single keyword alias.  See
  [ld-keyword-aliases].  Thanks to Jared Davis for correspondence
  that led us to make this change.

  The [proof-builder] command [47m(exit t)[0m now exits without a query (but
  still prints an event to show the [47m:INSTRUCTIONS[0m).  Thanks to Warren
  Hunt for feedback leading us to make this change.

  We made the following minor changes to the behavior of [47mdmr[0m; see
  [dmr].  First, if [47mdmr[0m monitoring is enabled, then [47m(dmr-start)[0m will
  have no effect other than to print a corresponding observation, and
  if monitoring is disabled, then [47m(dmr-stop)[0m will have no effect
  other than to print a corresponding observation.  Second, it had
  been the case that when [47m(dmr-start)[0m is invoked, the debugger was
  always automatically enabled with value [47mt[0m (see
  [set-debugger-enable]), and the debugger remained enabled when
  [47m(dmr-stop)[0m was invoked.  Now, the debugger is only enabled by
  [47m(dmr-start)[0m if it is not already enabled and does not have setting
  [47m:never[0m.  Moreover, if such automatic enabling takes place, then the
  old setting for the debugger is restored by [47m(dmr-stop)[0m unless
  [47m[set-debugger-enable][0m has first been called after that automatic
  enabling.  Finally, if the value of [state] global variable
  [47m'debugger-enable[0m is [47m:bt[0m, then the new value will be [47m:break-bt[0m, not
  [47mt[0m.

  When a call of [47m[progn][0m is executed in the ACL2 loop, its constituent
  [events] and their results are printed, just as was already done
  for calls of [47m[encapsulate][0m.  Thanks to Jared Davis for a
  conversation causing us to consider this change.

  (CCL only) When [47m[set-debugger-enable][0m is invoked with an argument
  that prints a backtrace and CCL is the host Lisp, the backtrace
  will be limited to 10,000 stack frames.  (We have seen more than
  65,000 stack frames before this change.)  This limit is the value
  of raw Lisp variable [47m*ccl-print-call-history-count*[0m, which may be
  assigned another positive integer value to serve as the maximum
  number of stack frames to be printed.

  Improvements have been made pertaining to the disabling (inhibiting)
  of individual types of warning.  Now, inhibited warnings are
  implemented in a straightforward way using a separate [table] for
  this purpose, the [47minhibit-warnings-table[0m, rather than using the
  [47m[ACL2-defaults-table][0m.  See [set-inhibit-warnings], and see
  [set-inhibit-warnings!] for a variant that is not [47m[local][0m to an
  [47m[encapsulate][0m or a book in which it occurs.  Thanks to Sol Swords
  for sending examples showing how [47m[set-inhibit-warnings][0m did not
  always behave as one might reasonably expect when books are
  involved.

  It had been the case that [47m[lp][0m took a single argument, [47m'raw[0m.  This
  argument was not documented and also caused an error, so it has
  been eliminated.

  The functionality of [47m[make-event][0m has been significantly expanded.
  First: if the expansion is of the form [47m(:OR e1 e2 ...)[0m, then event
  forms [47me1[0m, [47me2[0m, and so on are evaluated, in order, until the
  evaluation of some [47mek[0m completes without error.  In that case, the
  expansion is treated simply as [47mek[0m.  With this capability,
  alternative expansions can be attempted and the successful one does
  not need to be evaluated again.  See the new version of community
  book [47mbooks/make-event/proof-by-arith.lisp[0m for an example.  Second,
  an expansion may be of the form [47m(:DO-PROOFS e)[0m, in which case the
  event [47me[0m is evaluated with proofs [31;1mnot[0m skipped; see
  [ld-skip-proofsp].  Third, new keyword [47m:EXPANSION?[0m can be used to
  avoid storing expansions in certificate files.  See [make-event].

  When a [47m[defun][0m event prints a failure message in the summary, that
  message now indicates when the failure is due to a failed proof of
  guard verification or a failed proof of the measure theorem.
  Thanks to Shilpi Goel for requesting this enhancement.

  [31;1mNEW FEATURES[0m

  ACL2 can now be instructed to time activities using real time (wall
  clock time) instead of run time (typically, cpu time).  See
  [get-internal-time].  Thanks to Jared Davis for asking to be able
  to obtain real-time reports in event summaries.

  A new utility, [47m[sys-call+][0m, is similar to existing utility [47m[sys-call][0m
  in that it executes a command.  Unlike [47msys-call[0m, however, [47msys-call+[0m
  returns values that include output from the command (in addition to
  the exit status), rather than simply printing the command.  See
  [sys-call+].

  The new macro [47m[verify-guards+][0m extends the functionality of
  [47m[verify-guards][0m by permitting macro-aliases (see
  [macro-aliases-table]).  See [verify-guards+].  Thanks to Jared
  Davis for requesting this feature and suggesting the use of
  [47m[make-event][0m in its implementation.  We have also modified
  [47m[verify-guards][0m to print a friendlier error message when its
  argument is a macro-alias.

  See [last-prover-steps] for a new utility that returns the number of
  prover steps most recently taken.

  [31;1mHEURISTIC IMPROVEMENTS[0m

  The processing of [47m:use[0m and [47m:by[0m [hints] has been changed in the
  following two rather subtle ways, thanks to suggestions from Sol
  Swords.

      o For [47m:by[0m hints, the simplest check was an equality check, rather
      than a more general subsumption check.  That equality check was
      made after removing so-called ``guard holders''
      ([47m[must-be-equal][0m, [47m[prog2$][0m, [47m[ec-call][0m, [47m[the][0m) from both the
      previous theorem and the purported theorem.  Now, guard-holder
      removal has been strengthened, so that the results are also put
      into so-called quote-normal form, for example replacing [47m(cons
      '3 '4)[0m by [47m'(3 . 4)[0m.

      o For a [lemma-instance] provided to a [47m:use[0m or [47m:by[0m hint that is a
      [47m:functional-instance[0m, if a [47m:do-not[0m hint (see [hints]) has
      specified that [47mpreprocess-clause[0m is not to be used, then
      preprocessing will not be used on the constraints.

  We eliminated certain warnings about being ``weak'' for every
  [47m:[0m[47m[type-prescription][0m rule whose conclusion designates that the
  function call can be equal to one of its arguments, e.g., [47m(or
  (integerp (foo y)) (equal (foo y) y))[0m.  In many cases (such as the
  one above), such warnings about ``weak'' simply aren't correct.

  [31;1mBUG FIXES[0m

  Fixed a soundness bug that was permitting a [stobj] to be bound by a
  [47m[let][0m or [47m[mv-let][0m form, without being among the outputs of that
  form.  Thanks to Jen Davis and Dave Greve for reporting this bug.
  Their report included an example which forms the basis for a proof
  of [47mnil[0m, included as a comment in the form [47m(deflabel note-6-3 ...)[0m
  in ACL2 source file [47mld.lisp[0m.

  (GCL only) Fixed an obscure soundness bug due to an error in the GCL
  implementation of [47m[set-debugger-enable][0m.  For details, see the
  relevant comment in the ACL2 source code under [47m(deflabel note-6-3
  ...)[0m.

  Fixed a bug in the case of a field of a (concrete) stobj that is an
  abstract stobj (see [nested-stobjs]).  Thanks to David Rager for
  bringing this bug to our attention.

  Splitter output for type [47mif-intro[0m (see [splitter]) could formerly
  occur even when at most one subgoal is generated.  This has been
  fixed.

  Fixed a bug in [47m[wof][0m, hence in [47m[psof][0m (which uses [47mwof[0m), that was
  causing the printing of a bogus error message.

  A small logical bug has been fixed in the logical definition of
  [47m[sys-call-status][0m.  Formerly it always returned [47m(mv nil state)[0m
  whenever the oracle of the state is non-empty (see [state]).

  Fixed a bug that was causing an error upon evaluation of the form
  [47m(set-prover-step-limit nil)[0m.  Thanks to David Russinoff for
  reporting this error.

  The [47m:measure[0m (if supplied) is now ignored when checking redundancy
  with respect to a non-recursive definition that is not defined
  within a [47m[mutual-recursion][0m.  (See [redundant-events] and see
  [xargs].)  It had been possible to get a low-level ACL2 error in
  this situation.  Thanks to Jared Davis for reporting this bug with
  a helpful example.

  Eliminated a potential error when using [47m[comp][0m to compile an
  uncompiled function defined under [47m[progn!][0m, which we observed in
  LispWorks.

  [31;1mCHANGES AT THE SYSTEM LEVEL[0m

  The ACL2 sources are now publicly available between ACL2 releases,
  using svn; see the new ``[47macl2-devel[0m'' project hosted by Google code
  at [47mhttp://acl2-devel.googlecode.com[0m.  Although such a copy of ACL2
  is likely to work well with the latest svn (trunk) revision of the
  ACL2 community books (see [community-books]), please take seriously
  the warning message printed at startup: ``The authors of ACL2
  consider svn distributions to be experimental; they may be
  incomplete, fragile, and unable to pass our own regression.'' That
  message also provides instructions for bug reports.  If you decide
  to use svn versions of either the community books or ACL2, then you
  should use both, as they tend to be kept in sync.  We fully expect
  ACL2 releases to continue from time to time, as usual.  Thanks to
  Jared Davis for his efforts in setting up the new acl2-devel
  project and svn repository, and to him and David Rager for
  convincing us to distribute ACL2 sources via svn between releases.

  Thanks to a suggestion from Jared Davis, over 30 built-in functions
  are now declared to be inline in order to boost performance.  (The
  list may be found by searching ACL2 source file [47maxioms.lisp[0m for
  ``[47m(declaim (inline[0m''.)

  Better support has been provided for command line arguments,
  especially those supplied directly by the user when calling ACL2.
  For one, problems with quoting have been solved using [47m\"$@\"[0m in place
  of [47m$*[0m.  Also, the function [47m[save-exec][0m now allows specification of
  arguments, both for the host Lisp as well as ``inert'' arguments
  that can be passed along to calls of programs (as with [47m[sys-call][0m).
  A keyword argument, [47m:return-from-lp[0m, specifies a form to evaluate
  before quitting the read-eval-print loop at startup.  See
  [save-exec].  Also see the source function [47muser-args-string[0m and its
  comments, source file [47macl2-init.lisp[0m, for more information.  Thanks
  to Jared Davis for suggesting the use of [47m\"$@\"[0m, as well as
  modifications to [47m[save-exec][0m and helpful conversations about that.

  A rather extensive overhaul has taken place for the function
  proclaiming mechanism.  As before, this is only used when the host
  Lisp is GCL.  However, building an executable is now faster for
  some Lisps, including GCL, by avoiding repeated recompilation and
  perhaps repeated initialization.

  (CCL only) We increased stack sizes when the host Lisp is CCL.  The
  default for recent CCL versions is equivalent to specifying `[47m-Z 2M[0m'
  on the command line, but saved ACL2 scripts (including experimental
  versions ACL2(h), ACL2(p), ACL2(r), and combinations of them) to
  `[47m-Z 64M[0m', representing a 32-fold increase.  Thanks to Jared Davis
  for pointing us to community books file
  [47mbooks/centaur/ccl-config.lsp[0m and to Sol Swords for helpful
  discussions.

  (SBCL only) Fixed [47msave-exec[0m for host Lisp SBCL to provide the same
  export of variable [47mSBCL_HOME[0m that was provided in the original
  [47msaved_acl2[0m script.

  (GCL only) We made changes, following suggestions from Camm Maguire
  (whom we thank for these suggestions), to support ACL2 builds on
  recent versions of GCL (2.6.8 and 2.6.10; we recommend against
  using GCL 2.6.9, since issues there were fixed in 2.6.10).
  Specifically, we no longer set the hole size, and we allocate
  contiguous pages sufficient to run an ACL2 regression without
  failing due to memory limitations.

  [31;1mEMACS SUPPORT[0m

  Modified file [47memacs/emacs-acl2.el[0m to eliminate some warnings that
  were appearing in a recent Emacs version, replacing [47m(end-of-buffer)[0m
  by [47m(goto-char (point-max))[0m and [47mnext-line[0m by [47mforward-line[0m.  Thanks
  to Warren Hunt for bringing the warnings to our attention.

  [31;1mEXPERIMENTAL/ALTERNATE VERSIONS[0m

  (Allegro CL only) ACL2(h) now avoids blow-ups in hash table sizes
  that could be caused by [fast-alist-fork].  Thanks to Jared Davis
  for helping to debug this problem, and to David Rager for
  contributing the community book
  [47mbooks/parsers/earley/earley-parser.lisp[0m, which highlighted this
  problem.

  (SBCL only) Fixed a bug that was causing a Lisp break after turning
  on [waterfall-parallelism].  Thanks to David Rager for confirming
  that our proposed fix is correct.")
 (NOTE-6-4
  (RELEASE-NOTES)
  "ACL2 Version 6.4 (January, 2014) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 6.3 into
  the following categories of changes: existing features, new
  features, heuristic improvements, bug fixes, changes at the system
  level, Emacs support, and experimental versions.  Each change is
  described in just one category, though of course many changes could
  be placed in more than one category.

  See also [note-6-4-books] for a summary of changes made to the ACL2
  Community Books since ACL2 6.3, including the build system.


Changes to Existing Features

  [Gag-mode] no longer saves prover output when [47mPROVE[0m output is
  inhibited (see [set-inhibit-output-lst]).  This may improve
  performance slightly when certifying community books using their
  [47mMakefile[0m or [build::cert.pl]; in particular, GCL 2.6.8 running on a
  Mac can now certify the book
  [47mbooks/tau/bounders/elementary-bounders.lisp[0m without running out of
  space, even without explicitly turning off [gag-mode] (which had
  been done shortly before the Version 6.3 release).

  When [include-book] fails to find a readable [certificate] ([47m.cert[0m)
  file, the error message now distinguishes between the case that
  this file is missing and the case that read permission is missing.

  (GCL only) Time reporting has been improved when the host Lisp is Gnu
  Common Lisp.  A key change was made in the computation of runtime
  (for example, to report in event summaries), so that it includes
  the ``child runtime''.  See [get-internal-time].  Also, the utility
  [47m[time$][0m now gives improved information by including child runtime
  information, which can be significant; for example, it probably
  includes compile time, while the ``seconds runtime'' statistic
  (still) does not.  Recent versions of GCL might also provide system
  runtime and child system runtime.  See [time$].  Thanks to Camm
  Maguire for suggesting these improvements to [47mtime$[0m and providing an
  initial implementation for them.

  Fixed a bug in an ACL2 system function, [47mour-truename[0m, which returns
  the ``true name'' for a file name, when supplied with an optional
  second argument.  Thanks to Camm Maguire for bringing this bug to
  our attention.

  The wording in theory warnings has been improved, to avoid giving the
  impression that you are newly disabling a built-in rule in the case
  that it merely remains disabled.

  As requested by Sol Swords, erroneous evaluations of system function
  [47mmagic-ev-fncall[0m that had produced a message, [47mmsg[0m, will now also
  return that message.  The following example, sent by Sol,
  illustrates the fix: before, evaluation of [47m(magic-ev-fncall 'cons
  '(a) state nil nil)[0m printed a message (to the comment window) and
  then returned [47m(mv t nil)[0m, but now it returns [47mmv t <msg>[0m, where
  [47m<msg>[0m denotes the message (printed with the [47m[fmt][0m [47m~@[0m directive).

  Fixed [47m:[0m[47m[pbt][0m to avoid printing the bodies of [47m[defconst][0m forms.
  Thanks to Jared Davis for pointing out the large output when the
  body is a large character string.

  A new output type, [47mhistory[0m, now controls the printing of
  history-related information; see [47m[set-inhibit-output-lst][0m.  The
  unused output type, [47mexpansion[0m, is no longer supported, i.e., is no
  longer a member of the list [47m*valid-output-names*[0m.  Because of this
  change, printing of information when undoing, as by [47m:[0m[47m[u][0m, will now
  take place even when [47mevent[0m output is inhibited (if [47mhistory[0m output
  is not inhibited); we thank Sol Swords for requesting that change.

  The [47m:[0m[47m[loop-stopper][0m field of a rule of class [47m:[0m[47m[rewrite][0m, should still
  be a list of lists [47m(var1 var2 fn1 fn2 ... fnk)[0m, where [47mvar1[0m and [47mvar2[0m
  are variables and the [47mfni[0m are symbols.  But formerly each [47mfni[0m was
  required to be a function symbol; now, it can be a macro alias for
  a function symbol (see [47m[add-macro-alias][0m).  For example, the
  following is a valid [47m:[0m[47m[loop-stopper][0m field: [47m((x y +))[0m.

  The restrictions on utilities [47moracle-apply[0m and [47moracle-funcall[0m have
  been updated in order to avoid potentially confusing or
  inappropriate results, by imposing the following new requirements
  on their first argument, which must still be a function symbol.
  That symbol must not be [47mif[0m (formerly the illegal symbol was
  [47m[return-last][0m); it must not be a key of the alist,
  [47m*ttag-fns-and-macros*[0m; it must not be untouchable (see
  [47m[remove-untouchable][0m); and it must not be a [47m[stobj][0m creator (see
  [47m[defstobj][0m).

  The [table] guard on [47m[dive-into-macros-table][0m has been strengthened
  in order to avoid calling untouchable functions (see
  [47m[remove-untouchable][0m).


New Features

  We have added a tool for writing out useful information about a
  book's event names when certifying the book.  See [bookdata].
  Thanks to Dave Greve for requesting this tool and participating in
  its specification.

  There are new analogues of [47m[add-include-book-dir][0m and
  [47m[delete-include-book-dir][0m: [47m[add-include-book-dir!][0m and
  [47m[delete-include-book-dir!][0m, respectively.  The new utilities are
  similar to their existing counterparts, except that their effects
  are not [local] to enclosing [books] or [47m[encapsulate][0m events.
  Thanks to Shilpi Goel for requesting this enhancement.

  The class of [congruence] rules has been broadened considerably, so
  that one can restrict to patterns.  For example, a congruence rule
  can now state that an equivalence is maintained for the term
  [47m(mv-nth 1 (f (cons u v) y 'a))[0m when rewriting [47my[0m.  See
  [patterned-congruence].  Thanks to Sol Swords for requesting this
  feature.


Heuristic Improvements

  (None to report this time.)


Bug Fixes

  Fixed a soundness bug in the handling of hypotheses of conditional
  [47m:[0m[47m[definition][0m rules invoked during rewriting by applying [47m:[0m[47m[expand][0m
  [hints].  See (defxdoc note-6-4 ...) in community book
  [47msystem/doc/acl2-doc.lisp[0m for a proof of [47mnil[0m in ACL2 Version_6.3
  that exploits this bug.

  It had been possible to update a [stobj] (either an ordinary stobj or
  an abstract stobjs) so that it no longer satisfies its recognizer
  predicate.  This soundness bug has been fixed.  Thanks to Jared
  Davis and Sol Swords for pointing out this bug, making useful
  observations about the issue, and sending proofs of [47mnil[0m, one of
  which may be found in a Lisp comment in the defxdoc form for
  [47mnote-6-4[0m.

  Fixed a long-standing soundness bug (found at least as far back as
  Version 1.9!) in the checking done for [congruence] rules.  There
  had failed to be a check that the new variable on the right-hand
  side of the conclusion is indeed new.  The following example is
  shown in detail as a comment in function
  [47minterpret-term-as-congruence-rule[0m, ACL2 source file [47mdefthm.lisp[0m,
  where it is used to prove [47mnil[0m in Version 6.3.

    (implies (e y1 y2)
             (equal (h y2 y1)
                    (h y2 y2)))

  Fixed a bug in the ACL2 character reader that was causing an
  end-of-file error when reading from a string ending in [47m\"#\\c\"[0m, for [47mc[0m
  a character or non-terminating sequence of characters.  Thanks to
  Jared Davis for sending the following example, whose evaluation in
  raw Lisp had caused an error.

    (let* ((*readtable* *acl2-readtable*)
           (stream (make-string-input-stream \"#\\\\a\"))
           (x1 (read stream nil :EOF))
           (x2 (read stream nil :EOF)))
      (list x1 x2))

  (GCL only) Improved the automatic proclaiming mechanism used for GCL
  builds, in particular to avoid computing a return type when a term
  is detected that could come from a call of [47m[non-exec][0m, and to do a
  more complete job for calls of [47m[return-last][0m.

  (CCL only) A CCL bug was treating filenames of the form [47m\"~/user/...\"[0m
  as [47m\"~/...\"[0m.  Thanks to Gary Byers for sending us a CCL-specific
  form that is now included in the ACL2 sources, which avoids this
  problem.

  Attempts to submit [47m[congruence][0m rules had unfortunate consequences in
  the case that the function ``symbol'' is [47m[if][0m or [47m[quote][0m: for [47mif[0m,
  rules were appropriately ignored because of the special handling
  that ACL2 already gives to calls of [47m[if][0m for congruence-based
  reasoning, while for [47mquote[0m, it was possible to get a hard Lisp
  error.  Now, attempts to submit such rules will result in a clear
  ACL2 error.

  It had been possible to get a confusing raw Lisp error when
  submitting a [47m[defstobj][0m event whose first argument is not a symbol,
  as in: [47m(defstobj (fld :type integer :initially 0))[0m.  That user
  error is now reported gracefully by ACL2.

  When an [47m[include-book][0m form is executed for a non-existent book, we
  no longer get a bogus warning about a missing compiled file.  (Of
  course the compiled file is missing when the book itself is
  missing!  So there's no need to report this fact.)  Thanks to Caleb
  Eggensperger for bringing this issue to our attention.


Changes at the System Level

  The ACL2 system [documentation] has been reworked for the [xdoc]
  framework developed by Jared Davis.  While the ACL2 User's Manual
  can still be built, it is now possible for the ACL2 community to
  contribute to the ACL2 system documentation, in community book
  [47mbooks/system/doc/acl2-doc.lisp[0m; see comments near the top of that
  book.  Now that both the ACL2 system documentation and much of the
  community books documentation are written in [xdoc] format, we hope
  the ACL2 community will add links from the ACL2 system
  documentation topics to book documentation topics.  Note that
  [47m:[0m[doc] still works at the terminal, but it is based on the new
  system, and other terminal-based access to the documentation has
  been eliminated (for example [47m:more[0m).  Thanks to Jared for all his
  work contributing to this enhancement.

  Fixed community books [47mbooks/Makefile-generic[0m and also [47mbooks/Makefile[0m,
  which now has filename [47mbooks/GNUmakefile[0m, to work with Cygwin
  (Windows).  Thanks to Harsh Raju Chamarthi for his substantial
  help.

  The guard for system function [47mev-fncall-w[0m now includes an arity
  check.


EMACS Support

  There is now an Emacs utility for browsing the hypertext
  documentation for ACL2 and the community books.  This browser,
  ACL2-Doc, essentially serves as a replacement for Emacs Info, which
  can no longer be used to browse the documentation.  ACL2-Doc can be
  used not just for the ACL2 User's Manual but also for the
  ACL2+Books Manual.  It is loaded automatically into Emacs if you
  load the file [47memacs/emacs-acl2.el[0m.  See [ACL2-doc] and
  [documentation].


Experimental/Alternate Versions

  (None to report this time.)")
 (NOTE-6-5
  (RELEASE-NOTES)
  "ACL2 Version 6.5 (August, 2014) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 6.4 into
  the following categories of changes: existing features, new
  features, heuristic improvements, bug fixes, changes at the system
  level, Emacs support, and experimental versions.  Each change is
  described in just one category, though of course many changes could
  be placed in more than one category.

  See also [note-6-5-books] for a summary of changes made to the ACL2
  Community Books since ACL2 6.4, including the build system.


Changes to Existing Features

  The [47m[brr@][0m command now supports inputs [47m:initial-ttree[0m and
  [47m:final-ttree[0m.  Thanks to David Rager for a request leading to these
  enhancements.  See [ttree] for a discussion of the tag-tree
  structures returned for these inputs.

  (GCL only) A restriction for structure-sharing (as described in a
  remark, ``Remark on print-circle-files''; see [print-control])
  involving GCL has been removed, since this is no longer required
  for the latest GCL versions (2.6.8 and 2.6.10).  Thanks to Jared
  Davis and Camm Maguire for useful discussions and this GCL
  improvement.

  The keyword commands [47m:exit[0m and [47m:quit[0m are disabled inside [brr], in
  order to avoid accidental exits from ACL2.  Thanks to David Rager
  for suggesting such a change.

  For calls of [47m[make-event][0m made during the [47m[include-book][0m phase of
  [47m[certify-book][0m, keyword [47m:check-expansion[0m no longer causes
  evaluation of the first argument of [47mmake-event[0m; rather, the value
  of [47m:check-expansion[0m is simply used as the expansion.  Thanks to Sol
  Swords for suggesting this change, which made it reasonable to
  ignore such [47mmake-event[0m forms when determining the ``rolling back''
  before that [47minclude-book[0m phase, as described in the next section.

  The form [47m(reset-prehistory nil)[0m now is a no-op if [state] global
  [47m'[0m[47mskip-reset-prehistory[0m has a non-[47mnil[0m value.  Thanks to Sol Swords
  for requesting this feature (in support of infrastructure for
  certifying the [community-books]).

  The output from [47m:[0m[47m[pr][0m, [47m:[0m[47m[pr!][0m, [47m:[0m[47m[pl][0m, and [47m:[0m[47m[show-bodies][0m has been
  tweaked.  Thanks to a suggestion from Ben Selfridge, such output
  now shows the hypotheses (the [47mHyps[0m field) above the left-hand side
  and right-hand side of a [rewrite] rule ([47mLhs[0m and [47mRhs[0m,
  respectively).  The [47mEquiv[0m field has also been moved up before the
  [47mLhs[0m field in such output for rewrite rules, and this field has been
  added for [elim] rules.  Finally, the [47mHyps[0m field now appears above
  the [47mTerm[0m field in such output for [type-prescription] rules.

  Rules of class [47m:[0m[47m[linear][0m may now be [monitor]ed.  Thanks to David
  Rager for requesting this enhancement.

  When forcing (see [47m[force][0m) is applied, we now always see the
  appropriate [executable-counterpart] [rune],
  [47m(:executable-counterpart force)[0m, in the proof output and summary;
  this hadn't previously been the case.  Thanks to Robert Krug for
  bringing this issue to our attention.

  The default value for the [47m:write-port[0m keyword argument of
  [47m[certify-book][0m is now [47mt[0m, as was already claimed by the
  documentation.  Thus, a [47m.port[0m file will be written when a book is
  certified, making it more likely that a subsequent [47m[include-book][0m
  will complete without error even if the book has been modified
  without recertification.  Note that a change by Sol Swords to the
  build system for the [community-books] now sets an environment
  variable to guarantee that [47mwrite-port[0m is true, independent of this
  change.  On a related note: the unadvertised environment variable
  [47mACL2_WRITE_PORT[0m is now handled more appropriately, by interning its
  upcased argument into the ACL2 package.

  The following changes can make it easier to include books that are
  uncertified or have corrupted compiled files.  Thanks to Sol Swords
  for sending helpful, relevant examples and for subsequent
  discussions helping to lead to these changes.

    * It is no longer illegal to call [47mset-compiler-enabled[0m within [books].
      See [compilation], which shows how to do this in order to avoid
      loading the compiled file not only for a book specified by
      [47m[include-book][0m but also for all books included under that book.
      Also see [compilation] for an analogous utility,
      [47m(set-port-file-enabled nil state)[0m, to avoid loading [47m.port[0m
      files.  (For background on [47m.port[0m files, see
      [uncertified-books]).

    * In situations where it is legal to include an uncertified book
      (typically, any time other than during [47m[certify-book][0m, ACL2
      nonetheless could fail to do so when an error occurred while
      reading a [certificate] file.  ACL2 can now instead include the
      book successfully as an uncertified book.

    * When hard raw Lisp errors occur during loading of compiled files on
      behalf of an [47m[include-book][0m event, that event can now complete
      successfully much as though the compiled file were simply
      missing.

  (SBCL only) The function [47m[setenv$][0m is now supported in SBCL, which
  had been the one supported host Lisp for which [47msetenv$[0m had not been
  supported.  Thanks to Jared Davis for pointing the way to this
  improvement.

  Built-in [equality-variants] have been modified in order to support
  suitable guard-checking.  For example, evaluation of the form
  [47m(member-eq 3 '(4 5))[0m, or equivalently, [47m(member 3 '(4 5) :test 'eq)[0m,
  had produced a value of [47mnil[0m, but now we get what one should have
  expected: a guard violation (since [47m[member-eq][0m is intended to
  compare symbols).  Thanks to Yan Peng for raising a question on the
  acl2-help mailing list that led us to make this improvement.

  When the [47m:[0m[47m[pe][0m command is supplied the macro alias for a function
  symbol (see [macro-aliases-table]), the system will now print
  [events] not only for the macro symbol but also for the
  corresponding function symbol.  Thanks to Cuong Chau, Jared Davis,
  Shilpi Goel, Sol Swords, and Warren Hunt for requesting this
  enhancement.

  Some evaluations of forms [47m(mbe :logic L :exec E)[0m are more efficient
  or avoid guard violations, by evaluation of the [47m:exec[0m form ([47mE[0m)
  instead of the [47m:logic[0m form ([47mL[0m).  If the [47m[mbe][0m call is in a
  [47m:[0m[47m[program][0m mode function definition, the [47m:exec[0m code will be
  evaluated, where unlike before, this is true even when
  guard-checking is [47m:all[0m or [47m:none[0m (see [set-guard-checking]).  If the
  [47mmbe[0m call is in a [47m:[0m[47m[logic][0m mode function definition, the change is
  that the [47m:exec[0m code will be evaluated when there is a superior call
  of a [47m:program[0m mode function, except when guard-checking is [47m:all[0m or
  [47m:none[0m or in a couple of technical cases (see a comment in the
  source code for constant [47m**1*-as-raw*[0m [formerly [47m*mbe-as-exec*[0m] for
  details).  This use of [47m:exec[0m code had been defeated when the
  superior [47m:program[0m mode function had an ``invariant-risk'' of making
  ill-guarded stobj updates.  However, there is no change in the case
  of safe-mode, which is used during evaluation of [47m[defconst][0m,
  [47m[value-triple][0m, and [47m[defpkg][0m forms, and during macroexpansion: the
  [47m:logic[0m and [47m:exec[0m forms are still both evaluated and checked for
  equality.  Thanks to Jared Davis for reporting this issue and for
  helpful chats about it.  For more information, see the comment
  about ``mbe and invariant-risk'' in the form [47m(defxdoc note-6-5 ...)[0m
  in [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m.

  The utility [47m[save-exec][0m has a new (optional) keyword argument,
  [47m:init-forms[0m, which specifies a list of forms to evaluate when first
  entering the ACL2 read-eval-print loop, [47m[lp][0m.  Thanks to Jared
  Davis for requesting this enhancement.


New Features

  A [47m[defstobj][0m event may now include the keyword argument
  [47m:non-memoizable[0m.  When its value if [47mt[0m, then for ACL2(h) builds (see
  [hons-and-memoization]), code will run somewhat faster.  In a
  little test doing just reads and writes to a stobj array in
  ACL2(h), it took 26% less time when the stobj to be written was
  introduced by [47m[defstobj][0m using [47m:non-memoizable t[0m.  Thanks to Warren
  Hunt for requesting this feature and helping to develop the test.

  See [47m[set-print-base-radix][0m for a utility that may be preferable to
  [47m[set-print-base][0m, since it essentially calls [47m[set-print-radix][0m
  automatically.  Thanks to David Rager, Shilpi Goel, and David
  Hardin for participating in an acl2-help mailing list discussion
  that motivated this feature.


Heuristic Improvements

  One of the steps performed by [47m[certify-book][0m has traditionally been
  to check for local incompatibilities (see [local-incompatibility])
  after admitting all the events in the book.  This step involved
  rolling back the logical [world] to what it was at the start of
  certification, and then including the book (see [include-book]).
  As an optimization, we now avoid rolling back the world more than
  necessary; see [47m[certify-book][0m, specifically the discussion of Step
  3.  We thank Sol Swords for requesting this optimization and for
  making a suggestion that improved it, pertaining to [47m[make-event][0m
  (described above).  We also thank Jared Davis for alerting us to an
  issue that turned out to be caused by a bug in our initial
  implementation.  Sol has reported a nearly 20% reduction in time
  for certifying a certain large collection of books.

  The test for redundancy of [47m[encapsulate][0m [events] has been made more
  efficient.  Also, while the criterion itself remains unchanged, the
  documentation has been made more accurate; see
  [redundant-encapsulate].  We observed more than a 2% reduction in
  time for the ``everything'' regression target, but we observed more
  than 23% of the time eliminated for the form [47m(time$ (include-book
  \"doc/top\" :dir :system))[0m after building the documentation.  Thanks
  to David Rager for bringing that particular book to our attention,
  as one that took a long time to include.

  The function [47m[pairlis$][0m is now tail-recursive, hence potentially more
  efficient.  More precisely, its definition for the logic remains
  unchanged, but using [47m[mbe][0m, for execution it calls a new
  tail-recursive function, [47mpairlis$-tailrec[0m.  Thanks to Jared Davis
  for requesting this improvement.

  [Linear] arithmetic has been strengthened slightly so that
  immediately after simplification has ``settled down'' (see
  [hints-and-the-waterfall]), the unrewritten conclusion of a
  [47m:[0m[47m[linear][0m rule may be used when normally this would not be the
  case.  Thanks to Robert Krug for reminding us of examples we had
  encountered that could benefit from some such a change, and for
  pointing us to some relevant source code.  This improvement
  generally causes an extra pass through the simplifier; hence we
  have observed approximately a 2% slowdown in the regression suite.
  Note that machinery is now in place for installing additional
  ``desperation heuristics''; perhaps the ACL2 community will have
  some to suggest.


Bug Fixes

  We fixed a soundness bug in how the [tau-system] processed calls of
  [47mif[0m.  Thanks to Dmitry Nadezhin for reporting this bug by sending a
  simple example that exploited it to prove [47mnil[0m.  To see that
  example, see the comment about ``tau soundness bug'' in the form
  [47m(defxdoc note-6-5 ...)[0m in [community-books] file
  [47mbooks/system/doc/acl2-doc.lisp[0m.

  We fixed a soundness bug for nested [stobj]s (see [stobj-let]).  In
  the case of a stobj producer variable that is not a child stobj, it
  had been possible to update that stobj without returning it.
  Thanks to Sol Swords for reporting this bug and providing a
  corresponding proof of [47mnil[0m, which is included in a comment in the
  form [47m(defxdoc note-6-5 ...)[0m in [community-books] file
  [47mbooks/system/doc/acl2-doc.lisp[0m.)

  We fixed a soundness bug in the case of a [stobj] with a field that
  is a resizable array of stobjs.  Thanks to Sol Swords for sending a
  proof of [47mnil[0m exploiting this bug, together with some helpful
  analysis attributing the bug to a mistake in the generated logical
  definition of the corresponding resize function.  (His example is
  included in a comment in the form [47m(defxdoc note-6-5 ...)[0m in
  [community-books] file [47mbooks/system/doc/acl2-doc.lisp[0m.)

  (ACL2(h) only) We fixed a soundness bug involving the interaction of
  [47m[stobj-let][0m and [47m[memoize][0m, which thus is only a bug in ACL2(h) (see
  [hons-and-memoization]), not in ACL2.  The fix was to add code to
  [47mstobj-let[0m that clears the memoization table for the parent stobj if
  any child stobj is updated.  An example proof of [47mnil[0m before this
  fix may be found in the ACL2 source file [47mtranslate.lisp[0m, in a
  comment in the function [47mstobj-let-fn-raw[0m.

  (Allegro CL and CMUCL only) We fixed bugs in function [47m[princ$][0m when
  invoked in an ACL2 image with Allegro CL or CMUCL as the host Lisp
  implementation.  In Allegro CL, when printing a complex number in
  base 16, lower case characters were produced, for example printing
  [47m#C(c d)[0m instead of the characters predicted by the axioms, namely
  [47m#C(C D)[0m.  In some recent versions of CMUCL, after executing the
  forms [47m(set-print-base 16 state)[0m and [47m(set-print-case :downcase
  state)[0m, hex digits were printed in lower case, unlike other host
  Lisps and contrary to the ACL2 axioms: for example, 1000 base 10
  was printed as [47m3e8[0m rather than as predicted by the ACL2 axioms,
  [47m3E8[0m.  Thanks to Jared Davis for bringing these bugs to our
  attention, and also for pointing out excessive printing of a big
  note about such printing in Allegro CL.  We now avoid that note
  altogether, which had warned that printing numbers in base 16 can
  be slow for Allegro CL.  In fact, that performance issue has been
  eliminated: for example, after evaluating [47m(defconst *c* (expt 2
  200000))[0m and [47m(set-print-base 16 state)[0m, the form [47m(time$ (pprogn
  (princ$ *c* *standard-co* state) state))[0m reports taking about 3
  seconds before the change but about 1/100 seconds after the change.
  Thanks to David Margolies of Franz Inc. for passing along a remark
  from a colleague that showed how to make this improvement.

  The utility [47m[sys-call+][0m can now only be called if there is an active
  [trust-tag], which is the restriction that was already in place for
  [47m[sys-call][0m.  This plugs a potential soundness hole.

  We have made several system functions untouchable (see
  [remove-untouchable]), in order to prevent soundness bugs.  We
  thank Jared Davis and Sol Swords for sending us an example that
  used a call of one of these functions to prove [47mnil[0m.  We have placed
  that example into a comment in Community Books file
  [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-6-5 ...)[0m.

  The [47mbrr[0m command, [47m:wonp[0m, had not been installed for use after [47m:eval[0m
  even though this was claimed in the documentation (see
  [brr-commands]).  This has been fixed.  Thanks to David Rager for
  bringing this issue to our attention.

  Fixed a bug in [47m[make-event][0m that could cause [47m[include-book][0m to fail
  with a bogus message about ``the set of ttags permitted in the
  current context.'' Thanks to Sol Swords and Anna Slobodova for
  reporting this bug, and to Sol for sending a small example that
  illustrated the problem.

  Fixed a bug that was wrongly disallowing certain calls of exported
  functions for abstract stobjs (see [defabsstobj]).  Thanks to Sol
  Swords for reporting this bug, supplying an example illustrating
  the bug, and suggesting a nice fix.  A slight variant of his
  example is included in a comment in Community Books file
  [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc note-6-5 ...)[0m.

  When a macro symbol [47mmac[0m was a macro-alias for a function symbol [47mf[0m
  (see [macro-aliases-table]), then the form [47m(verify-guards+ mac)[0m
  caused an error when encountered while including an uncertified
  book.  This problem has been fixed.  Thanks to Jared Davis for
  pointing out the problem and sending a simple example to illustrate
  it.  Technical Note: the actual problem was that [47m[verify-guards+][0m
  generates a call of [47m[make-event][0m with an [47m:expansion?[0m argument, and
  that argument needed to be ignored (as it now is, after the fix)
  when including an uncertified book.

  The [47m[walkabout][0m utility could cause hard Lisp errors when the current
  package is other than [47m\"ACL2\"[0m.  This has been fixed.  Thanks to Sol
  Swords for bringing this bug to our attention and suggesting a fix.


Changes at the System Level

  (SBCL only) Fixed the executable script generated for SBCL so that
  [47mSBCL_HOME[0m is set to the SBCL [47mobj/sbcl-home/[0m directory if it exists,
  since that fix seems needed for some recent versions of SBCL
  (1.1.14 in particular).

  File [47mGNUmakefile[0m in the ACL2 sources directory wasn't passing the
  value of shell variable [47mACL2[0m from target [47mcertify-books-fresh[0m to
  target [47mcertify-books[0m, and similarly for target
  [47mbooks/system/doc/render-doc.cert[0m (invoked by target [47mDOC[0m).  This has
  been fixed.  We thank Jared Davis and Camm Maguire for helpful
  discussions.

  The \"make DOC\" command was not completing correctly when variable
  [47mACL2[0m was not set.  Also, for host Lisp CMUCL at least, it stalled
  at the terminal unless a quit command was issued twice (as ACL2 was
  stuck without exiting).  Those problems have been resolved.  Thanks
  to Jim Ward for bringing these issues to our attention

  Improved the error message when encountering an illegal comma while
  reading input (i.e., for a comma not within a suitable nesting of
  backquotes).  Thanks to Jared Davis for bringing this issue to our
  attention and for a helpful discussion.

  (GCL only) Arranged for state global [47m'tmp-dir[0m to be set to GCL's
  [47msi::*tmp-dir*[0m, even on Windows; this may be important for
  compilation on Windows.  Thanks to Camm Maguire for pointing out
  the need to set [47m'tmp-dir[0m for ACL2 built on GCL on mingw.

  (GCL only) Now, [47m[gc$][0m may be called with no arguments, in which case
  the missing argument for [47msystem::gc[0m is [47mt[0m.


EMACS Support

  Improvements to the [ACL2-Doc] browser include the following.

    * A new `[47mw[0m' command displays the topic name in the minibuffer, together
      with the manual name (ACL2+Books Manual or ACL2 User's Manual).

    * Improved the `[47mcontrol-t .[0m' command so that the default topic is
      selected just as in acl2-doc mode.  (Technically: the same
      syntax table is used for `[47mcontrol-t .[0m' as is used in the
      [47macl2-doc[0m buffer for that command and the `[47mg[0m' command.)

    * Improved the search commands so that the display doesn't move when
      the next occurrence is already displayed on the screen.

    * Eliminated the deprecated commands `[47mControl-x a A[0m', `[47mControl-x a a[0m',
      and `[47mControl-t G[0m'.


Experimental/Alternate Versions

  For ACL2(r), Ruben Gamboa found a bug in constraints for functions
  introduced with [47mdefun-std[0m, and also kindly provided a fix, which
  has been incorporated.

  Modified ACL2(hp) so that two system functions that had been
  [47m[unmemoize][0md when turning on [waterfall-parallelism] ---
  [47mfchecksum-obj[0m and [47mexpansion-alist-pkg-names-memoize[0m --- now remain
  memoized.  This can greatly improve performance when using ACL2(hp)
  with [waterfall-parallelism] on, in particular community book
  [47mbooks/system/doc/render-doc-combined.lisp[0m.

  Made miscellaneous small improvements to ACL2(h).

  The utilities [47mhons-shrink-alist[0m and [47mhons-shrink-alist![0m have
  essentially been renamed to [47m[fast-alist-fork][0m and
  [47m[fast-alist-fork!][0m, respectively.  The old names are deprecated but
  remain as macros that are macro-aliases for the respective new
  names (see [macro-aliases-table]).  New utilities,
  [47m[fast-alist-clean][0m and [47m[fast-alist-clean!][0m are similar to the above
  but take just one argument and, if it is a fast alist, associates
  the result with the hash table link of that argument.  Thanks to
  Jared Davis for providing a concrete proposal, together with the
  new names, for what had been only a concept.")
 (NOTE-7-0
  (RELEASE-NOTES)
  "ACL2 Version 7.0 (January, 2015) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 6.5 into
  the following categories of changes: existing features, new
  features, efficiency improvements, bug fixes, changes at the system
  level, Emacs support, and experimental versions.  Each change is
  described in just one category, though of course many changes could
  be placed in more than one category.

  A particularly major change with this release is that by default,
  ACL2 executables are [hons-enabled]: see [hons-and-memoization].
  We expect this change to be backward compatible for current ACL2
  users, other than a change to the name of the executable, as
  described below.

    * As before, there are two ways to build ACL2: either [hons-enabled],
      to produce ACL2(h) with executable name [47msaved_acl2h[0m; or not
      hons-enabled, to produce ``classic ACL2'', which we now call
      ACL2(c), with executable name [47msaved_acl2[0m.  [Note: These
      defaults were changed after Version_7.0.]

    * Unlike before, the default build of ACL2 is now ACL2(h), hence with
      name [47msaved_acl2h[0m [after Version_7.0, once again [47msaved_acl2[0m].
      It is still possible to build ACL2(c) (hence with name
      [47msaved_acl2[0m) [after Version_7.0, [47msaved_acl2c[0m], but this is not
      the default.

    * The change to building ACL2(h) by default may require you to change
      scripts and environment variables to point to [47msaved_acl2h[0m
      rather than [47msaved_acl2[0m.  [This change is only for Version_7.0,
      not later versions.]

  Note that after the next ACL2 release, we might only support
  [hons-enabled] ACL2 builds.

  See also [note-7-0-books] for a summary of changes made to the ACL2
  Community Books since ACL2 6.5, including the build system.


Changes to Existing Features

  Three new theorems have been built into ACL2 to allow some additional
  simple arithmetic reasoning.  For example, the following failed
  before this change, typically causing the user to include an
  arithmetic book; but that is no longer necessary.

    (thm (implies (natp x)
                  (equal (expt 2 (+ 1 -1 x))
                         (expt 2 x))))

  Thanks to Jared Davis for suggesting these, and for providing seven
  small modifications to the community books to keep proofs from
  failing after the changes.  (So, if you have a proof failure
  involving `plus' ([47m+[0m) that formerly succeeded, consider disabling
  one or more of these rules.)  Here are the three new built-in
  theorems.

  [31;1mTheorem: [0m<commutativity-2-of-+>

    (defthm commutativity-2-of-+
      (equal (+ x (+ y z)) (+ y (+ x z))))

  [31;1mTheorem: [0m<fold-consts-in-+>

    (defthm fold-consts-in-+
      (implies (and (syntaxp (quotep x))
                    (syntaxp (quotep y)))
               (equal (+ x (+ y z)) (+ (+ x y) z))))

  [31;1mTheorem: [0m<distributivity-of-minus-over-+>

    (defthm distributivity-of-minus-over-+
      (equal (- (+ x y)) (+ (- x) (- y))))

  [Type-set] reasoning has been improved for a few built-in functions,
  including [47mfirst-n-ac[0m, [47m[substitute][0m, [47m[nthcdr][0m, and [47m[subseq][0m, and
  thus for some functions whose computed type depends on one of
  these: for example, [47m[take][0m and therefore, also [47m[butlast][0m and
  [47m[subseq-list][0m, are now known to return [47m[true-listp][0m results.
  Thanks to Jared Davis for a request that led us to these changes.
  In particular, the definitions of [47mfirst-n-ac[0m and [47msubstitute-ac[0m have
  been modified to call [47m[revappend][0m instead of [47m[reverse][0m, and the
  following [47m:[0m[47m[type-prescription][0m rules have been added to source file
  [47maxioms.lisp[0m (and can be seen using [47m:[0m[pe]).

    * true-listp-first-n-ac-type-prescription

    * stringp-substitute-type-prescription

    * true-listp-substitute-type-prescription

    * true-listp-nthcdr-type-prescription

    * stringp-subseq-type-prescription

    * true-listp-subseq-type-prescription

  Technical note on the above change: in some cases, the built-in
  [47m:[0m[47m[type-prescription][0m rule has been changed, essentially for the
  better, but new rules have also been added.  Consider for example
  the function, [47m[substitute][0m.  This function calls [47msubstitute-ac[0m,
  which in turn now calls [47m[revappend][0m instead of [47m[reverse][0m, which
  allows ACL2 to deduce a [47m:type-prescription[0m rule saying that
  [47msubstitute[0m returns a string or a true-list.  However, new
  [47m:type-prescription[0m rules [47mstringp-substitute-type-prescription[0m and
  [47mtrue-listp-substitute-type-prescription[0m allow the stronger
  conclusion that [47msubstitute[0m returns a string or true-list,
  respectively depending on whether [type-set] reasoning can deduce
  that the given sequence is or is not a string.  The deduced
  [47m:type-prescription[0m rule can still be of some use in cases that
  type-set reasoning cannot establish whether or not the input
  sequence is a string.

  We removed support for processing legacy [documentation] strings
  (those starting with [47m\":Doc-Section\"[0m), since the [xdoc] system has
  been stable for some time.  Thanks to Jared Davis for assisting in
  that effort and to David Rager for his encouragement.  The ACL2
  system and [community-books] still have code to support such
  processing, but it is essentially commented out: specifically, each
  such piece of code is prefixed by [47m#+acl2-legacy-doc[0m.  We expect to
  delete such code entirely before the next release.

  The [47m[with-output][0m macro now takes a new keyword, [47m:evisc[0m, that
  specifies [evisc-tuple]s.  Thanks to Warren Hunt for requesting a
  way to submit [47m[defun][0m forms in a way that avoids printing large
  [guard] goals during guard verification.  The following example
  illustrates a way to arrange this.

    (defmacro defun/ (&rest args)
     (mv-let (evisc args)
             (cond ((eq (car args) :evisc)
                    (mv (cadr args) (cddr args)))
                   (t (mv '(:gag-mode (evisc-tuple 3 4 nil nil)) args)))
             `(with-output :evisc ,evisc
                           (defun ,@args))))

    ; example:
    (defun/ h (x)
     (declare (xargs :guard t))
     (append (cons (make-list 10) x) x))

  The utility [47m:[0m[47m[pl2][0m no longer automatically instantiates free
  variables; similarly for calls of [47m:[0m[47m[pl][0m on a term.  Thanks to Eric
  Smith for sending an example showing the problem with the previous
  implementation.

  When the [ld-evisc-tuple] is non-[47mnil[0m, the utilities [47m:[0m[47m[pe][0m, [47m:[0m[47m[pc][0m, and
  [47m:[0m[47m[pcb!][0m now abbreviate their output accordingly.  See
  [set-evisc-tuple].  Thanks to David Rager for bringing the need for
  this change to our attention.

  The utility [47m[disabledp][0m now accepts runic abbreviations such as [47m(:d
  append)[0m.  (See [theories] for a discussion of runic abbreviations.)
  Thanks to Shilpi Goel for requesting this enhancement.

  Gc-verbose now takes an optional second argument, which is only
  relevant when the host Lisp is CCL, where that argument specifies
  verbosity for EGC.

  Nests of [47m[car][0m and [47m[cdr][0m calls are now printed (``untranslated'')
  differently.  The old method availed itself of all 28 of the
  car-cdr macros.  The new method only introduces 6 of them: [47mcadr[0m,
  [47mcaddr[0m, [47mcadddr[0m, [47mcddr[0m, [47mcdddr[0m, [47mcddddr[0m.  It never introduces such
  macros as [47mcaar[0m or [47mcddaar[0m, preferring [47mcar[0ms and [47mcdr[0ms when necessary.
  Lisp programmers tend to recognize [47mcadr[0m, [47mcaddr[0m, and [47mcadddr[0m as the
  accessors for the 1st, 2nd, and 3rd (0-based) elements of a list.
  See community book [47mbooks/system/untranslate-car-cdr.lisp[0m for
  further discussion and a correctness proof.

  It is now possible to create more efficient [47m:[0m[47m[meta][0m rules by writing
  metafunctions that create ``implicit hypotheses.'' See
  [meta-implicit-hypothesis].

  We improved a few built in rules: [47mlower-case-p-char-downcase[0m,
  [47mupper-case-p-char-upcase[0m, [47mlower-case-p-forward-to-alpha-char-p[0m, and
  [47mupper-case-p-forward-to-alpha-char-p[0m.  We also improved the rule
  [47malpha-char-p-forward-to-characterp[0m by replacing it with two rules,
  [47malpha-char-p-forward-to-standard-char-p[0m and
  [47mstandard-char-p-forward-to-characterp[0m.  The new rules are, as
  before, in ACL2 source file [47maxioms.lisp[0m.

  The reader macro sharp-comma ([47m#,[0m), which has been deprecated since
  ACL2 Version 3.5 (May, 2009), has been eliminated.  Use sharp-dot
  ([47m#.[0m) instead; see [sharp-dot-reader].

  A [47m[defthm][0m or [47m[defaxiom][0m event is now redundant when there is already
  a syntactically identical event in the logical [world], even if the
  rules suggested by the two [events] differ.  See
  [redundant-events].  Thanks to Jared Davis and Sol Swords for
  sending the following example, which illustrates the change.
  Previously, the final event was not redundant, and hence failed.
  Now, it is redundant, even though the [47m:typed-term[0m suggested by the
  new [47m[type-prescription][0m rule is [47m(booleanp (foop x))[0m where the
  existing rule's [47m:typed-term[0m is [47m(foop x)[0m.

    (defund foop (x) (consp x))

    (defthm booleanp-of-foop
      (booleanp (foop x))
      :rule-classes :type-prescription)

    (in-theory (disable booleanp-compound-recognizer))

    (defthm booleanp-of-foop
      (booleanp (foop x))
      :rule-classes :type-prescription)

  In the case that summary output is inhibited but error output is not
  (see [set-inhibited-summary-types]), failed [events] did not print
  an error message.  Now they do.

  When a call of [encapsulate] with empty [signature] introduces no
  [events], it now has no effect on the ACL2 logical [world].
  Formerly, such an [encapsulate] form would create an event even in
  this case.  For example, the form [47m(encapsulate nil (local (defun f
  (x) x)))[0m formerly created an event in the world, as well as a
  [command] when executed at the top-level; but now it is truly a
  no-op.  See [encapsulate].  Note: An idiom sometimes used for
  testing is [47m(encapsulate () (local ...) (local ...) ...)[0m, that is, a
  trivial encapsulate where each sub-event is [local].  With this
  change, that idiom is now properly supported.  (Formerly, the
  second such encapsulate was considered redundant with the first;
  but that is no longer the case, since the first will not be stored
  in the [world].)

  We replaced an error with a warning for cases where a classic
  [congruence] rule is unnecessary.  Thanks to Jared Davis for
  sending us an example suggesting the need for a change.  (See ACL2
  source function [47mchk-acceptable-congruence-rule[0m for his example and
  more explanation.)

  We removed support for three [47m[declare][0m forms that had been permitted
  in ACL2(h) only, but were not advertised: [47mdynamic-extent[0m, [47minline[0m
  and [47mnotinline[0m, because they seem difficult or impossible to support
  correctly.  For alternatives to using [47minline[0m and [47mnotinline[0m
  declarations, see [defun-inline] and [defun-notinline].

  The nu-rewriter contained special provisions for rewriting
  expressions composed of [47m[nth][0m, [47m[update-nth][0m, and
  [47m[update-nth-array][0m, together with [47m[let][0m expressions and other
  applications of non-recursive functions or [47m[lambda][0m expressions.
  An email query was sent to the acl2 mailing list on 10/24/2014,
  giving people an opportunity to object to the removal of this
  feature.  Nobody objected, so we have removed it in order to
  simplify the ACL2 code base.  Thanks to David Rager for suggesting
  this sort of code clean-up.  Note that some system functions, for
  example [47mall-equal[0m, have been deleted in support of this change.

  [Guard]s have been added for some system functions that support the
  implementation of the [tau-system]: [47mlower-bound-<=[0m, [47mupper-bound->=[0m,
  [47mlower-bound->[0m, [47mupper-bound-<[0m, and [47msqueeze-k[0m.  Thanks to Dmitry
  Nadezhin for supplying these improvements (which he also used in
  modifications to the community book,
  [47mbooks/tau/bounders/elementary-bounders.lisp[0m).


New Features

  The new command [47m:btm[0m has been added to the list of valid
  [brr-commands], to show the bottom-most frame in the path.  Thanks
  to David Rager for requesting this feature.

  A new [47m[xargs][0m keyword, [47m:[0m[47m[measure-debug][0m, decorates each termination
  proof goal with [47m[extra-info][0m calls that show the source of the
  goal.  Thanks to Jared Davis (first in 2008!), Sol Swords, and Anna
  Slobodova for requesting this feature.

  A new reader macro, [47m#{\"\"\"...\"\"\"}[0m, has been contributed by Jared Davis
  to support the writing of strings without escape characters.  See
  his community book [47mbooks/system/fancy-string-reader-test.lisp[0m for
  examples.

  (For those who program in raw Lisp) A new Lisp variable,
  [47m*hard-error-is-error*[0m, has a default of [47mnil[0m that preserves existing
  behavior; but it can be set to a non-[47mnil[0m value in order to cause
  so-called ACL2 ``hard errors'' to result in Lisp errors whose
  condition, when printed with [47mformat[0m directive [47m~a[0m, is the same error
  message that ACL2 would otherwise print.  See [hard-error].  Thanks
  to Jared Davis for requesting this feature.

  A new value for [47m[include-book][0m keyword argument [47m:uncertified-okp[0m is
  [47m:ignore-certs[0m, which specifies that all certificate files are to be
  ignored during inclusion of this book and all of its sub-books.
  See [include-book].  Thanks to Sol Swords for requesting this
  feature and for helpful discussions on its details.


Efficiency Improvements

  The heuristics have changed for guessing the [47m:typed-term[0m field for a
  [47m:[0m[47m[type-prescription][0m rule when that field is not explicitly
  specified.  Specifically, consider the case that the conclusion of
  the rule is a function call [47m(p u)[0m for some term [47mu[0m, such that there
  is an enabled [47m[compound-recognizer][0m rule for [47mp[0m.  Formerly, the
  [47m:typed-term[0m was [47mu[0m in this case.  Now, it must be the case that the
  most recent enabled such [47m[compound-recognizer][0m rule is `strong', in
  the following sense: if [47mts1[0m is the [type-set] implied by assuming
  the conclusion true and if [47mts2[0m is the [type-set] implied by
  assuming the conclusion false, then [47mts1[0m and [47mts2[0m are complementary.
  Thanks to Jared Davis for an email that prompted us to make this
  change.

  We have made several efficiency improvements (arguably heuristic in
  nature), which may apply in many settings but especially in
  handling of several forms during the execution of [47m[include-book][0m
  --- most notably [47mwith-output[0m forms, as [47m(with-output ... FORM)[0m is
  now essentially just [47mFORM[0m during [47minclude-book[0m.  For some details,
  including statistics showing up to 1/3 of [47m[include-book][0m time
  eliminated by these changes (and even significant time saved
  outside [47minclude-book[0m), see the comment about ``efficiency
  improvements'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m,
  form [47m(defxdoc note-7-0 ...)[0m.  Thanks to Sol Swords for noticing
  inefficiencies that led us to these improvements, and for helpful
  discussions.

  The [dmr] utility has been made much more efficient, yielding a
  performance penalty of perhaps 10% instead of perhaps more than a
  factor of 30 (3000%).

  We made a low-level implementation tweak that resulted in a speed-up
  of 2.6% in wall-clock time for a CCL-based regression (using
  ``[47mmake[0m'' with [47m-j 8[0m and target ``everything'').  (Technical note: We
  eliminated the Lisp special variable [47m*attached-fn-called*[0m, using
  another variable [47m*aokp*[0m instead.  Special variable bindings can
  apparently be expensive!)

  Some space has been saved in ACL2 executables by avoiding the
  duplication of certain constants.  Specifically: for each event
  [47m(defconst name (quote val))[0m in the ACL2 source files, [47mval[0m is stored
  in the Lisp image in several places, but not all of these had been
  identical: they were all [47m[equal][0m, but not all [47m[eq][0m.  (We believe
  that these were already all [47meq[0m for user-defined [47m[defconst][0m events.)
  For example, in Linux builds of ACL2(h) on host Lisp CCL, we have
  seen a space saving of approximately 18.9 MB, which is 12.6%.
  Thanks to Jared Davis for pointing out duplicate strings that he
  noticed using his [spacewalk] tool.


Bug Fixes

  We fixed two bugs in [47m[spec-mv-let][0m.  The first was pointed out to us
  by Jared Davis using essentially the following example, where the
  result should be [47mnil[0m given that [47mspec-mv-let[0m is intended to have the
  semantics of [47m[mv?-let][0m.

    ACL2 !>(set-ignore-ok t)
     T
    ACL2 !>(let ((a t)
                 (xval nil))
             (spec-mv-let (yval)
                          xval
                          (mv?-let (xval)
                              a
                              (if xval
                                  yval
                                nil))))
    T
    ACL2 !>

  The second [47m[spec-mv-let][0m bug was to allow the two lists of bound
  variables to intersect.  In the following example, given that
  [47mspec-mv-let[0m is semantically just [47mmv?-let[0m, the result should have
  been 46, not 34.  This has been fixed.  Thanks to David Rager for
  encouraging these two fixes and checking them over.

    ACL2 !>(set-ignore-ok t)
     T
    ACL2 !>(spec-mv-let
            (x)
            17
            (mv?-let (x)
                23
                (if t
                    (+ x x)
                  \"bad\")))
    34
    ACL2 !>

  The guard for function [alpha-char-p] was strengthened to require
  that its argument is a standard character.  The previous guard
  required only that the argument is a character, and was a soundness
  bug; for a proof of [47mnil[0m before this fix, see the comment about
  ``alpha-char-p'' in Community Books file [47msystem/doc/acl2-doc.lisp[0m,
  form [47m(defxdoc note-7-0 ...)[0m.

  Errors were possible when evaluating functions [47m[pkg-imports][0m and
  [47m[pkg-witness][0m while including a book with a compiled (or expansion)
  file.  Such errors have been eliminated.

  Fixed a bug in [47moracle-apply-raw[0m.

  (GCL CLtL1 only) Fixed a bug that was preventing
  [47m[set-debugger-enable][0m from taking full effect in non-ANSI GCL.

  (GCL only) The utility [47m[gc-verbose][0m was broken, but has been fixed.

  Fixed a bug in [provisional-certification] that incorrectly caused an
  error during the convert step for [47m[verify-guards+][0m forms.  More
  generally, this error occurred when encountering a [47m[make-event][0m
  form with a non-[47mnil[0m value supplied for the [47m:expansion?[0m keyword.
  Thanks to David Rager for reporting this bug.

  A raw Lisp error could occur with [guard]-checking turned off,
  because type declarations were mistakenly left in the executable
  counterparts (so-called ``*1* functions'') when ACL2 processed
  function definitions.  The following example shows how a type
  violation could occur in some Lisps (we saw this in SBCL but not in
  CCL, for example).

    (defun f (x)
      (declare (xargs :guard (natp x)))
      (let ((y (1+ x)))
        (declare (type (integer 0 *) y))
        y))
    (set-guard-checking nil)
    ; Possible raw Lisp error:
    ; \"The value -2 is not of type UNSIGNED-BYTE.\"
    (f -3)

  Thanks to Jared Davis for sending us an example that brought this bug
  to our attention.

  Fixed a bug that was causing a low-level assertion, saying:
  ``Implementation error: see 'replace-free-rw-cache-entry.'' Thanks
  to Anna Slobodova for bringing this bug to our attention via an
  example, and to Sol Swords for simplifying that example.

  The [iprint] feature, which allows abbreviated output to be read back
  in, did not work as one might expect when using the [break-rewrite]
  feature (see [brr]).  Thanks to David Rager for reporting this
  problem.  More generally: the problem was that values associated
  with [iprint] indices during a [wormhole], for example after
  breaking on a [rewrite] rule, were forgotten when exiting the
  wormhole.  (Technical note for those interested: the fix restores
  the main iprinting structure after exiting a wormhole, just before
  reading the next top-level form.  That restoration uses raw Lisp,
  with logic-only code based on [47m[read-ACL2-oracle][0m.)  The example
  below failed before the fix but now works.

    (set-evisc-tuple (evisc-tuple 3 3 nil nil)
                     :iprint t
                     :sites :all)
    (defthm my-rule (equal (car (cons x x)) x))
    (brr t)
    (monitor '(:rewrite my-rule) t)
    (thm (equal (car (cons a a)) a) :hints ((\"Goal\" :do-not '(preprocess))))
    ; Now entering a :brr break:
    (make-list 10) ; printed without evisceration
    ; Set evisceration with iprinting:
    (set-evisc-tuple (evisc-tuple 3 3 nil nil)
                     :iprint t
                     :sites :all)
    (make-list 10) ; printed with evisceration
    (a!) ; quit break-rewrite
    ; The following formerly caused a hard Lisp error, because although #@3#
    ; was printed in the output from (make-list 10) just above, iprint index 3
    ; was lost when exiting the break-rewrite wormhole.  Now, this works
    ; because iprinting information from the wormhole is retained.
    '#@3#

  There was a bug in how so-called ``hidden packages'' were handled by
  [47m[encapsulate][0m forms (see [hidden-death-package]), which was
  preventing package axioms from being visible in certain contexts.
  (Technical remark: packages that were hidden after the second pass
  but not the first were treated as not-hidden, even though their
  package axioms were not introduced.)  That, in turn, could cause an
  [47m[include-book][0m form to fail when the book contains a
  [47m[deftheory-static][0m form.  Here is an example failure.  First, in a
  fresh ACL2 session evaluate the form [47m(defpkg \"FOO\" nil)[0m and then
  evaluate the form [47m(certify-book \"foo\" 1)[0m, where file [47mfoo.lisp[0m is as
  follows.

    (in-package \"ACL2\")
    (defun foo::foo (x) x)
    (deftheory-static foo-theory
      (current-theory :here))

  Now evaluate the following sequence of forms.  In previous versions
  of ACL2, the final ([47m[include-book][0m) form failed.

    (encapsulate () (local (include-book \"foo\")) (defun h (x) x))
    (encapsulate () (local (include-book \"foo\")) (defun h2 (x) x))
    (include-book \"foo\") ; failed before the fix

  We have cleaned up handling of interrupts and aborts when inside the
  [break-rewrite] loop, or indeed any [wormhole].  Thanks to David
  Russinoff for bringing to our attention a case in which ACL2 quit a
  proof with ``Aborting due to an interrupt'' when in fact no
  interrupts had taken place.  Here is an example where that no
  longer happens but did, previously.  (For a different example, see
  the comment in the ACL2 sources definition of macro
  [47mbind-acl2-time-limit[0m.)

    (defun foo (x) (cons x x))
    (brr t)
    (monitor '(:definition foo) t)
    (thm (equal (foo y) z))
    (defun h (x) (declare (xargs :mode :program)) (car x))
    ; Raw Lisp error:
    (h 3)
    ; Previously, unexpected proof abort \"due to interrupt\":
    (thm (equal (append (append x y) x y) (append x y x y)))

  When aborting with [47m:[0m[47m[a!][0m inside the [break-rewrite] loop from within
  the [proof-builder], a raw Lisp error could subsequently occur
  saying, ``Attempt to execute *wormhole-cleanup-form* twice!''.
  This has been fixed.  Thanks to Sol Swords for reporting a bug in
  our original fix.  Here is an example that formerly caused that
  behavior.

    (defthm silly (implies (null x) (equal (append x y) y)))
    (defconst *c* (make-list 10))
    :brr t
    :monitor (:rewrite silly) t
    (verify (equal (append x (append *c* y)) (append y (append *c* x))))
    bash
    :go
    :a!
    bash ; formerly caused error

  The utility [47m[redo-flat][0m no longer worked when interrupting a proof
  (with Control-c), due to a bug in Version 7.0.  This has been
  fixed.  Thanks to Dave Greve for reporting this problem.


Changes at the System Level

  As mentioned near the top of this [documentation] topic, default
  builds of ACL2 are now [hons-enabled].

  (GCL only) GCL Versions prior to 2.6.12 are no longer supported.

  Modified code used in distributing Debian releases that allows books
  certified in one directory to be distributed in another.  This
  change, together with the fact that such relocation is [31;1mnot[0m truly
  supported, is explained in comments in source function
  [47mmake-certificate-file-relocated[0m.  Thanks to Camm Maguire for
  discussions leading to this change.

  (GCL only) Modified how home directory is calculated.  Thanks to Camm
  Maguire for help in making this change.

  (SBCL only) Fixed a check done at build time that was preventing
  builds in SBCL 1.2.2 because of its new backquote implementation.
  Thanks to Harsh Raju Chamarthi and Pete Manolios for bringing this
  issue to our attention.

  Development snapshots of ACL2 (and of the [community-books]) are now
  available between releases from {an ACL2 github repository |
  https://github.com/acl2/acl2}; they are no longer available via
  svn.  Thanks to David Rager and Jared Davis for taking the lead on
  this conversion.  As a result, the banner printed at startup for
  those snapshots has changed slightly.  For a quick start guide for
  using git with ACL2, see [git-quick-start].

  (CCL only) Control-d now quits ACL2 in raw Lisp just as it has done
  for a long time in the loop and, for ACL2(h) (i.e., [hons-enabled]
  ACL2), even in raw Lisp.

  (Should essentially affect GCL only) Significant re-work has been
  done for function proclaiming, which is still only done when the
  host Lisp is GCL.  In particular, the build process now has extra
  steps even for other Lisps though for them, the extra steps are
  trivial (technical details may be found in the comment labeled
  ``Essay on Proclaiming'' in source file acl2-fns.lisp).  We now use
  GCL's automatic proclaiming mechanism to calculate function types
  during the build (boot-strap), as we have seen it perform better
  than our own.  Thanks to Camm Maguire for helpful discussions, in
  particular for explaining that mechanism and for pointing out that
  the re-proclaiming that had been done previously during the build
  could lead to buggy behavior.

  For Makefile targets for testing such as [47mregression[0m, the default ACL2
  image used is now the same one that would be built for the same
  Makefile variables.  In particular, the command [47mmake regression[0m is
  equivalent to [47mmake regression ACL2_HONS=h[0m, which uses the
  executable [47msaved_acl2h[0m, not [47msaved_acl2[0m as was formerly the case.
  Thanks to Harsh Raju Chamarthi for finding a bug in a first attempt
  to make this change.


EMACS Support


Hons-enabled and Experimental Versions

  (For [hons-enabled] executables only) Fixed a soundness bug related
  to function memoization.  For a proof of [47mnil[0m exploiting this bug in
  Version 6.5, see the comment about ``pons-addr-of-argument'' in
  Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc
  note-7-0 ...)[0m.  Thanks to Jared Davis for improving our original
  fix: by noting its applicability to [47m[hons-clear][0m (not just
  [47m[hons-wash][0m); by tweaking our fix so that it works even if a
  [47mcontrol-c[0m interrupts ([47mhons-clear[0m or) [47mhons-wash[0m; and later by
  finding another bug in source function [47mpons-addr-of-argument[0m and
  suggesting a fix, which we incorporated.

  (For [hons-enabled] executables only) Fixed a soundness bug due to
  the fact that function [47mnever-memoize-fn[0m returned [47mnil[0m in the logic
  but returned [47mt[0m in raw Lisp.  For a proof of [47mnil[0m exploiting this bug
  in Version 6.5, see the comment about ``never-memoize-fn'' in
  Community Books file [47msystem/doc/acl2-doc.lisp[0m, form [47m(defxdoc
  note-7-0 ...)[0m.

  Static honsing for [hons-enabled] ACL2, an efficiency enhancement
  formerly only available for CCL, is now incorporated into builds on
  sufficiently recent GCL versions.

  ACL2 executables that were [hons-enabled] could fail to use
  previously-compiled definitions for [47m[memoize][0md functions when
  [47m[include-book][0m is invoked.  This has been fixed.

  (For [hons-enabled] executables only built on other than CCL or SBCL)
  Calls of [47m[memoize][0m only compile the memoized definition when the
  original function is compiled, rather than unconditionally as
  before.

  Several changes been made to function memoization (see [memoize]).
  Here is a list of changes visible at the user level; for
  implementation details, see [note-7-0-memoize].

    * It is now legal to call [47m[memoize][0m on functions with special raw-Lisp
      code (such as [47m[len][0m) provided the value of the [47m:inline[0m keyword
      argument is [47mnil[0m.

    * Bug fix: Fixed bug that was making [47m[memsum][0m attribute the count of
      making of hash tables to ``Heap bytes allocated'' instead of to
      ``Number of calls to mht.''

    * Memoize keyword [47m:trace[0m is no longer supported, as the [47m[trace$][0m
      utility provides much more flexibility.

    * Bug fix: Fixed a bug in handling of the [47m:commutative[0m argument of
      [47m[memoize][0m that could cause a hard Lisp error.  For a book that
      exhibits this bug, see the comment about ``:commutative'' in
      Community Books file [47msystem/doc/acl2-doc.lisp[0m, in the form
      [47m(defxdoc note-7-0 ...)[0m.

    * When [47m[memoize][0m is called with keyword argument [47m:commutative[0m having
      value [47mt[0m, the benefit of that argument can apply to rational
      number arguments even when not using static honsing.  Moreover,
      now only one argument needs to be a rational or to be
      ``static'' according to the implementation (technically: to
      have an [47mhl-staticp[0m value).

    * Bug fix: Calls of [47m[memoize][0m with keyword argument [47m:commutative t[0m were
      sometimes inappropriately treated as redundant
      [redundant-events].  This has been fixed.  Here is a simple
      example of what formerly went wrong.

          (defn f (x y) (equal x y))
          (memoize 'f :commutative t)
          (unmemoize 'f)
          (memoize 'f :commutative t) ; was redundant, so did not memoize

    * (For those who memoized directly in raw Lisp) [47mMemoize-fn[0m now requires
      its first argument to be a defined (fboundp) function symbol.
      (It seemed odd and needlessly arcane to allow memoize-fn to
      define an undefined function.)

    * (For those who memoized directly in raw Lisp) [47mMemoize-fn[0m now causes
      an error when it fails.

    * Bug fix: It had been possible to lose a memoization setting of [47m:aokp
      t[0m when many functions were memoized.  For an example, see the
      comment about ``rememoize-all'' in Community Books file
      [47msystem/doc/acl2-doc.lisp[0m, in the form [47m(defxdoc note-7-0 ...)[0m.

    * We eliminated undocumented utilities [47mmemoize-on[0m and [47mmemoize-off[0m,
      which were not used as far as we know.

    * When a memoized function call fails to satisfy the specified
      condition, that call is no longer counted as a ``hit'', at
      least by default.  This can be changed with raw Lisp variable,
      [47m*condition-nil-as-hit*[0m.

    * The utility [47m[memsum][0m had reported one more pons call and (CCL only)
      one more byte than was correct, and could perhaps report one
      call when there were actually zero.  That has all been fixed.

    * Bug fix: Some sorting of results based on ``self'' time and ``other
      functions'' time had been wrong.  (Technical remark: the
      problem was that the implementation confused ``ticks'' with
      ``time''.)  This has been fixed.

    * Statistics reporting (see [memsum]) often has a more uniform look.
      It is now done with a right margin of 79 instead of 70.  For
      [47m[memsum][0m, thanks to a suggestion from Warren Hunt, the [47mdefun[0m
      formerly printed to start each entry is now omitted, and after
      the name is printed at the start, a newline is printed before
      the ``hits'' or ``hits/calls'' information is printed.  A
      related change: when [47m*report-hits*[0m and [47m*report-calls*[0m are both
      [47mnil[0m, ``calls'' is no longer printed.  Other cosmetic changes
      were also made to [47m[memsum][0m output.

    * The output from [47m[memsum][0m on the line ``Time of all outermost calls''
      no longer includes a percentage, which had been at best
      misleading and at worst nonsensical.  Suppose for example that
      [47mf[0m calls [47mg[0m, which does all the work.  Then [47mmemsum[0m had reported
      50% of the ``Time of all outermost calls'' for each of [47mf[0m and [47mg[0m,
      even though 100% of the time was spent under each.

    * On Mac OS (Darwin), the physical memory is now accurately computed
      (using shell command ``sysctl hw.memsize'', which works in some
      versions of Mac OS, maybe all recent ones; tested on 10.6 and
      10.7).  Before, the physical memory value had been assumed to
      be 2^32 bytes.  The physical memory value is used in CCL for
      triggering garbage collections.  (Technical remark: this is
      implemented in function [47mstart-sol-gc[0m.)

    * Bug fix: in the pons summary, misses had been reported instead of
      hits on the ``hits/calls'' line.

    * Fixed [47m[memsum][0m so that package names are printed with the symbols.
      Also, printing is done with respect to the current package, not
      the [47m\"ACL2\"[0m package.

    * It is now legal to [profile] functions that take [47m[state][0m as an
      argument.  Thanks to Sol Swords for requesting this change.  In
      the course of making this change, we took a conservative
      approach and put the same requirement regarding illegal
      memoization of functions involving user-defined [47m[stobj][0ms: that
      is, when memoization must have value [47mnil[0m for the [47m:condition[0m
      keyword, it must also have value [47mnil[0m for the [47m:inline[0m keyword.
      We can perhaps remove this additional restriction if necessary.

    * For every built-in memoized function defined in the ACL2 logic, the
      memoization is done in the usual way (during the ACL2 build),
      using the [47m[memoize][0m event during the ACL2 build.  Such
      functions can thus be [47m[unmemoize][0md by users in the usual way.
      Thanks to David Rager for requesting this enhancement.

    * A new [47mmemoize[0m keyword, [47m:stats[0m, can control whether statistics will be
      saved for reporting with [47m(memsum)[0m.

    * Memoization in [hons-enabled] ACL2(p) is no longer affected by calls
      of [47m[set-waterfall-parallelism][0m.

  (ACL2(p) only, either [hons-enabled] or not) The function
  [Cpu-core-count] is now sensitive to environment variable
  [47mACL2_CORE_COUNT[0m.  See [cpu-core-count].  Thanks to Jared Davis for
  requesting this enhancement.

  Support for multi-threading has been added for memoization.  Thanks
  to Jared Davis for contributing an initial implementation.  Note
  that this may slow down [hons-enabled] ACL2(p) by several percent
  on memoization-intensive applications.  Undocumented function
  [47mmf-multiprocessing[0m is available for low-level system hackers to
  turn on/off this feature, which by default is off for
  [hons-enabled] ACL2 and on for [hons-enabled] ACL2(p).

  (ACL2(p) only, either [hons-enabled] or not) We fixed a bug in
  [47m[pand][0m, which we believe was also a bug in [47m[por][0m, [47m[pargs][0m, and
  [47m[plet][0m. (Technical remark: this bug had a low-level cause,
  pertaining to maintenance of a Lisp variable, [47m*ld-level*[0m, that
  holds the number of nested calls of [47m[ld][0m.)  Thanks to Jared Davis
  for reporting this bug and to David Rager for assisting in its
  repair.  Below is a slightly simplified version of Jared's example,
  which formerly caused an assertion error but now works as expected.

    (defmacro pand* (x y)
      `(spec-mv-let (yval)
                    ,y
                    (mv?-let (xval)
                             ,x
                             (if xval
                                 yval
                               nil))))
    (defn f3 (x)
      (pand* x x))
    (defn f4 (x)
      (pand x
            (f3 x)))
    (value-triple (f4 5))

  (Only for [hons-enabled] executables on Windows) Certain memory
  management is avoided on Windows (technically: by avoiding a call
  of source function [47mstart-sol-gc[0m), where it was causing errors.
  Thanks to Harsh Raju Chamarthi and Sol Swords for testing on
  Windows that led us to this change.


Subtopics

  [Note-7-0-memoize]
      ACL2 Version 7.0 Notes on Changes to Memoization Implementation")
 (NOTE-7-0-MEMOIZE
  (NOTE-7-0)
  "ACL2 Version 7.0 Notes on Changes to Memoization Implementation

  See [memoize] for a user-level introduction to function memoization.
  Here we summarize technical changes made in Version 7.0 of ACL2 to
  the implementation of function memoization; most ACL2 users should
  have no need to read further in this topic.  We thank Jared Davis
  for helpful conversations.

  The function [47mmemoize-init[0m now resets the table [47m*memo-max-sizes*[0m,
  which is used when creating memo tables and pons tables.  This
  change may be irrelevant, since generally memoize-init is only
  called at startup.  But it seemed appropriate to reset it along
  with all other globals involved in the memoization implementation.

  Lisp variable *print-pretty* is no longer globally set to [47mt[0m by
  certain memoization code.  Probably this change will not generally
  be observable.

  The utility [47m[clear-memoize-statistics][0m now resets data for the pons
  summary, but implementation function [47mclear-memo-tables[0m no longer
  does so (it only calls [47mclear-memoize-tables[0m).

  Avoided some recklessness in computing statistics related to ponsing
  (specifically, replaced [47mvery-unsafe-incf[0m by macro [47msafe-incf-pons[0m,
  which is a wrapper for [47msafe-incf[0m).

  [47mClear-memo-tables[0m no longer takes [47m&rest[0m arguments, since it is merely
  a wrapper for [47m[clear-memoize-tables][0m, which does not (and did not)
  take [47m&rest[0m arguments.

  For the utility [47mpons-summary[0m, we no longer use [47mour-syntax-nice[0m; so
  far example, [47m*print-case*[0m is not bound to [47m:downcase[0m.

  Function [47minternal-real-ticks[0m (formerly [47minternal-real-time[0m) now uses
  [47m[logand][0m in its implementation, which should improve performance.
  It also replaces, for non-static-hons implementations, the call
  [47m(get-internal-real-time)[0m by [47m(the mfixnum (get-internal-real-time))[0m,
  which can also help performance.

  More principled, consistent use is made of [47mour-syntax[0m for suitable
  printing.

  Added ``TO DO'' comments near the top of source file
  [47mmemoize-raw.lisp[0m.  Thanks to Jared Davis for suggesting some of
  these.

  We improved many comments in source file [47mmemoize-raw.lisp[0m.

  We did some renaming, including the following (note that this is
  probably not a complete list):

    - number-of-arguments       -> mf-len-inputs
    - number-of-return-values   -> mf-len-outputs
    - *compute-array*           -> *callers-array*
    - maybe-count-pons-calls    -> incf-pons-calls
    - maybe-count-pons-misses   -> incf-pons-misses
    - print-alist               -> mf-print-alist
    - shorten                   -> mf-shorten
    - outside-p                 -> outside-caller-p
    - ofni                      -> mf-make-symbol
    - ofnum                     -> mf-num-to-string
    - internal-real-time        -> internal-real-ticks
    - dcls                      -> mf-dcls
    - hl-without-interrupts     -> without-interrupts [which already existed]
    - *ma-initial-max-symbol-to-fixnum* -> *initial-max-symbol-to-fixnum*
    - REPLACEMENT:
      *initial-max-memoize-fns* -> *initial-2max-memoize-fns*

  We eliminated some dead code, including the following functions
  (probably not a complete list): [47mour-syntax-brief[0m, [47mofnm[0m, [47muses-state[0m,
  [47mglobal-restore-memoize[0m, [47mprine-alist[0m, [47mset-gc-threshold[0m, [47mour-gctime[0m,
  and [47mshort-symbol-name[0m, and all variants of format functions with
  names starting with \"of\" except for [47mofni[0m (now [47mmf-make-symbol[0m) and
  [47mofnum[0m (now [47mmf-num-to-string[0m).  Also, we moved [47mmemoize-here-come[0m to
  community book [47mbooks/centaur/memoize/old/profile-raw.lsp[0m.
  Regarding [47mour-syntax-brief[0m: there had been one call, in
  [47mprint-call-stack[0m, but that call did not seem appropriate so we
  deleted it.

  The variable [47m*count-pons-calls*[0m was deleted.  It had been set to [47mt[0m
  and was only used during macroexpansion of [47mincf-pons-calls[0m and
  [47mincf-pons-misses[0m (formerly [47mmaybe-count-pons-calls[0m and
  [47mmaybe-count-pons-misses[0m), where that macroexpansion was done at
  ACL2 build time --- hence user setting of [47m*count-pons-calls*[0m had no
  effect.

  We eliminated a needless error check that prevented loading
  [47mmemoize-raw.lisp[0m without [47m#+hons[0m, since we don't currently ever
  expect to try to do that.

  Miscellaneous additional code cleanup has been done.  Here is a
  (probably very incomplete) list.

    * [47mFloat-ticks/second-init[0m uses a default rather than duplicating the
      default's code, and has improved treatment of errors.

    * Removed unused [47m:before[0m field of [47mmemoize-info-ht-entry[0m record.

    * The implementations of [47mnumber-of-arguments[0m and
      [47mnumber-of-return-values[0m (now called [47mmf-len-inputs[0m and
      [47mmf-len-outputs[0m, respectively) have been made cleaner, in
      particular, starting with an empty
      [47m*number-of-arguments-and-values-ht*[0m.

    * New macros such as [47mma-index[0m provide some abstraction, to give the
      illusion that [47m*memoize-call-array*[0m is two-dimensional.

    * We broke up some definitions, in particular substantially shortening
      [47mmemoize-fn[0m by moving parts of it into new functions
      [47mmemoize-fn-inner-body[0m, [47mmemoize-fn-outer-body[0m, and
      [47mmemoize-fn-def[0m.  A benefit: it is easy to see the definition
      that is actually created when memoizing, by tracing
      [47mmemoize-fn-def[0m.

    * Added raw Lisp interface function [47mmf-note-arity[0m for informing
      [47mmemoize-fn[0m of input and output arities.

    * [47mCoerce-index[0m asserts that an index is in range rather than treating
      an out-of-range index as a symbol.

    * We renamed some variables to make them clearer.  In particular, it is
      whether a variable stores time or ticks.

    * We now make complete and correct (we hope) the use of suitable [47mfixnum[0m
      and [47mmfixnum[0m declarations, many of which had been missing or
      incorrect.

    * Both [47m[memoize][0m and [47m[unmemoize][0m are now safe for control-c and
      unexpected errors.

    * We no longer set [47mccl::*save-definitions*[0m or
      [47mccl::*fasl-save-definitions*[0m to [47mt[0m.  This may improve
      performance, but it may require explicitly calling
      [47mmf-note-arity[0m, as is now done in [47mbooks/centaur/aig/bddify.lisp[0m.
      However, this removes CCL-only behavior; in particular, we
      removed dependence on #+Clozure in
      [47mbooks/centaur/aig/bddify.lisp[0m for profiling [47mcount-branches-to[0m.

    * We use [47m#+ccl[0m instead of [47m#+Clozure[0m, for consistency with most of the
      rest of ACL2.

    * We no longer set [47mccl::*save-source-locations*[0m or
      [47mccl::*record-source-file*[0m to [47mt[0m, as there is no clear advantage
      to doing so, and in fact there is a comment near the end of
      source file [47macl2.lisp[0m suggesting that there could be slowdown
      from setting (at least) the first of these variables to [47mt[0m.

    * We slightly modified [47minternal-real-time[0m to improve its performance
      (see comments there).

    * We fixed a performance bug in function [47maddr-for[0m (parenthesis error
      was needlessly putting us in the ``large-case'').

    * Fixed a typo: declaim of fixnum type for [47m*initial-max-memoize-fns*[0m
      had instead been for nonexistent variable
      [47m*initial-2max-memoize-fns*[0m.

    * In [47mmemoize-fn[0m, we removed support for [47m:condition[0m to be a function
      symbol, which was at best confused.

    * The table [47m*never-memoize-ht*[0m is now populated mostly automatically,
      by [47minitialize-never-memoize-ht[0m.

    * Slight optimization: the form [47m(update-attached-fn-called
      ,*attached-fn-temp*)[0m, which had been in the definition of
      [47mmemoize-fn[0m but now is in [47mmemoize-fn-inner-body[0m, is conditioned
      on [47m,*attached-fn-temp*[0m.")
 (NOTE-7-1
  (RELEASE-NOTES)
  "ACL2 Version 7.1 (May, 2015) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 7.0 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  The default build is [hons-enabled], as for the previous release; but
  the generated executable is now [47msaved_acl2[0m, as discussed below.
  Please note that ACL2(c) (``classic ACL2'', i.e., ACL2 that is not
  [hons-enabled]) now builds as [47msaved_acl2c[0m, is deprecated, and will
  likely be unsupported or even eliminated in future releases.

  See also [note-7-1-books] for a summary of changes made to the ACL2
  Community Books since ACL2 7.0, including the build system.


Changes to Existing Features

  For both [47m[add-include-book-dir][0m and [47m[add-include-book-dir!][0m, the
  second argument is no longer evaluated (which we think could
  perhaps have been exploited to get unsound behavior, by arranging
  for the value of the second argument to depend on [47m[state][0m).
  Moreover, that argument can not only be a string, but also can be a
  [3msysfile[0m: an object [47m(:system . filename)[0m, where [47mfilename[0m is a file
  name.  When filename is a relative pathname, the meaning of such an
  object is the file with that pathname under the system books
  directory.

  The event summary had not been printed when a proof is interrupted
  (that is, with Control-C).  Now, summary information is printed for
  two summary types (see for example [set-inhibited-summary-types]):
  rules and hint-events.

  By default, [47m(memsum)[0m is now truncated to 100 entries rather than to
  20 entries.  (Implementation note: raw Lisp variable
  [47m*memoize-summary-limit*[0m is 100 instead of 20.)

  Calls of [47mTHE[0m no longer cause a [guard] violation when guard-checking
  is [47mnil[0m.  Also see [the] and see [set-guard-checking].

  Type declarations for [47m[let][0m and [47m[mv-let][0m forms are now
  [guard]-checked.  Consider for example the definition: [47m(defun foo
  () (let ((x t)) (declare (type integer x)) x))[0m.  Previously,
  evaluation of the call [47m(foo)[0m had failed to result in a guard
  violation error; now, it does, provided guard-checking is on (i.e.,
  not [47mnil[0m or [47m:none[0m; see [set-guard-checking]).

  The symbols [47mctx[0m, [47mhist[0m, [47mpspv[0m, [47munquote[0m, and [47mvalue[0m have been added to
  [47m[*ACL2-exports*][0m.  Thanks to Jared Davis for suggesting these
  additions.

  Consider [47m:use[0m or [47m:by[0m [hints] in which a variable bound using the
  [47m:instance[0m keyword is in the wrong package.  For example, for the
  hint [47m:use ((:instance foo (x 3)))[0m, suppose that the lemma [47mfoo[0m
  mentions the variable [47mbar::x[0m, but not [47mx[0m.  This situation formerly
  caused an error, but now, [47mx[0m indicates the variable [47mbar::x[0m from the
  lemma [47mfoo[0m.  See [lemma-instance], in particular Condition (4),
  which has been updated accordingly.  Thanks to David Rager for a
  remark that led us to implement this enhancement.

  The [47m[ld][0m special [47mld-error-action[0m may now have a value [47m(:exit N)[0m,
  where [47mN[0m is a natural number.  If an error occurs for a call of [47mld[0m,
  then this value causes the ACL2 process to quit with exit status [47mN[0m.
  See [ld-error-action].  Note that [47mld-error-action[0m is set to this
  new value when using the [47mcert.pl[0m utility provided with the
  community books; see [build::pre-certify-book-commands].  Thanks to
  David Rager for presenting an example showing how this change can
  make it easier to locate certain certification failures, and thanks
  to Sol Swords for helping in the design of this enhancement.

  A \"[Theory]\" warning is still printed when [definition]s of certain
  built-in functions, such as [47m[mv-nth][0m, are [disable]d; similarly for
  some built-in [executable-counterpart] rules.  However, we now
  print such warnings only when the disabling occurs, rather than
  every time an [47m[in-theory][0m event or hint is evaluated.  For example,
  if you evaluate [47m(in-theory (disable mv-nth))[0m followed by [47m(in-theory
  (disable append))[0m, then the second event will no longer produce a
  warning about [47mmv-nth[0m.  Thanks to Eric Smith for (most recently)
  suggesting such a change.

  (SBCL only) ACL2 built on SBCL now reports bytes usage, both in
  [47m[time$][0m and in [47m[memsum][0m, essentially exactly as has already been
  done for ACL2 built on CCL.  Thanks to Jared Davis for suggesting
  this enhancement.

  (SBCL only) [Fast-alists] can now be garbage collected (we believe)
  in SBCL, as they had already been done in CCL.  (Implementation
  note: The change was to use weak hash tables in the implementation
  of SBCL fast-alists.)  Thanks to Jared Davis for suggesting this
  enhancement.

  The utility [47m[ec-call][0m can now be applied to calls of symbols
  introduced with [47m[defun-inline][0m, or with [47m[define][0m using keyword
  argument [47m:inline t[0m, thanks to a request from Jared Davis.  For
  example, the following is now legal.

    (defun-inline foo (x)
      (cons x x))

    (defun bar (x)
      (ec-call (foo x)))

  The [proof-builder] is now sensitive to the current
  [case-split-limitations].


New Features

  The Common Lisp function [47m[sleep][0m is now defined in ACL2.  Thanks to
  Jared Davis for requesting this addition.

  Custom error messages may now be created for guard violations.  See
  [set-guard-msg].

  The new macro [47m[assert*][0m is like [47m[assert$][0m, except that [47massert*[0m only
  generates a [guard] proof obligation, not a runtime check.  [47mAssert*[0m
  is defined using a new macro [mbt*], which is a variant of [47m[mbt][0m: a
  call of [47mmbt*[0m logically returns [47mt[0m, but generates the same [guard]
  proof obligation as [47mmbt[0m.  Thanks to Shilpi Goel for a query that
  led us to add these macros.


Heuristic and Efficiency Improvements

  We fixed an inefficiency that could occur in calls of [program]-mode
  functions that update [stobj]s.  See the discussion of
  invariant-risk in the [documentation] topic, [program-wrapper].
  Thanks to Jared Davis for bringing this issue to our attention.

  We improved the ``worse-than'' heuristic, providing modest speed-up
  and eliminating the use of memoization for it.  Thanks to Jared
  Davis for useful discussions on the topic, and to Camm Maguire for
  an observation that led us to do some investigations that led to
  this improvement.  For more information see comments in source
  function [47mworse-than-builtin-clocked[0m (source file [47mtype-set-b.lisp[0m).

  We avoid the cost of translating ACL2 terms (see [term]) to
  user-level syntax after applying the ``preprocess'' simplifier (see
  [hints-and-the-waterfall]), and also after applying either [47m:use[0m or
  [47m:by[0m [hints].  Thanks to David Rager for helpful discussions towards
  this change.  Note: On rare occasions, this might change the prover
  flow as follows.

    * Consider the case that the input goal, \"Goal\", simplifies with the
      ``preprocess'' simplifier to a new goal that prints the same as
      \"Goal\".  Formerly, this case avoided labeling the new goal as
      \"Goal'\"; it was as though the new goal was actually the user
      input.  The new criterion for avoiding \"Goal'\" is somewhat
      weaker: the internal syntax must suitably match for \"Goal\" and
      its simplification, rather than their displayed forms.

    * Consider the application of a [47m:use[0m or [47m:by[0m hint.  In such cases, the
      resulting constraint (if any) is simplified with the
      ``preprocess'' simplifier.  Formerly, the rules used by that
      simplifier were not recorded if the printed version of the
      simplified constraint was equal to the original constraint,
      which was really a bug since the comparison was between the
      user-level syntax of the simplified constraint and the internal
      syntax of the original constraint.  Now, ACL2 compares the
      internal syntax of each.

  We fixed an inefficiency that could occur in processing of
  [47m[make-event][0m forms.  Thanks to Sol Swords for reporting and
  diagnosing the problem.  (Technical note: The fix involves
  avoiding, in most cases, looking up world global [47m'boot-strap-flg[0m by
  using a new state global instead of the same name.)

  We changed the heuristics for equality substitution so that so-called
  [3mcross-fertilization[0m, where an equality substitution is made on only
  one side of the goal's conclusion, is not made when generalization
  is turned off, as with the hint [47m:do-not '(generalize)[0m.  Instead,
  the equality is used throughout the goal in that case.  Thanks to
  David Hardin for bringing an example to our attention that led us
  to make this change.

  Some clause-building (essentially, goal-building) operations already
  avoided duplication, but now consider clauses to be ``duplicates''
  when the only difference is commuted arguments of [47m[equal][0m or [47m[iff][0m.
  (Note: This change was made in support of [47m[assert*][0m and [47m[mbt*][0m,
  mentioned above.)

  (SBCL only) It had been the case for host Lisp SBCL that the use of
  [47m[defun-inline][0m to define functions in [books] had failed to result
  in inlined code, when those functions were called after including
  those books.  This has been fixed (and appears not to have been a
  problem for host Lisp CCL).  Thanks to Jared Davis for bringing
  this issue to our attention.


Bug Fixes

  A potential soundness issue could result from the application of
  [meta]functions and [clause-processor]s: although ACL2 checked that
  their outputs contain only legal [term]s, it did not check for the
  absence of calls of certain ``forbidden'' function symbols.  For
  example, [sys-call] should be prohibited unless there is an active
  trust tag (see [defttag]), but a metafunction was able to introduce
  a call of [47msys-call[0m.  We have added the necessary checks, in a way
  that we hope has negligible impact on performance.  To avoid that
  impact or to learn more about this issue, see
  [set-skip-meta-termp-checks]; this new utility, which requires a
  trust tag, avoids not only the new checks but even the
  above-mentioned checks for legal terms.

  The edited log below illustrates a bug that we have fixed, involving
  the processing of [47m[include-book][0m [events] in the certification
  [world] whose filename starts with the tilde ([47m~[0m) character.

    ~/temp/incl$ cat sub/bad.acl2
    (include-book \"~/acl2/acl2/books/arithmetic/top\")
    ~/temp/incl$ acl2h
    [[.. output elided ..]]
    ACL2 !>(ld \"sub/bad.acl2\")
    [[.. output elided ..]]
    ACL2 !>(certify-book \"foo\" 1)


    HARD ACL2 ERROR in ABSOLUTE-PATHNAME-STRING-P:  Implementation error:
    Forgot to apply expand-tilde-to-user-home-dir before calling absolute-
    pathname-string-p. Please contact the ACL2 implementors.



    ACL2 Error in TOP-LEVEL:  Evaluation aborted.  To debug see :DOC print-
    gv, see :DOC trace, and see :DOC wet.

    ACL2 !>

  Fixed several issues with the [47m:puff[0m command, and updated its
  documentation accordingly.  See [puff].

  Fixed a bug in the [proof-builder]'s [47mwrap[0m command.  Thanks to Keshav
  Kini for sending a simple example that illustrated this bug.

  (Allegro CL only) Fixed a bug in [47m[trace!][0m, which for example was
  evidenced when evaluating [47m(trace! (nth :native t))[0m.

  Fixed a bug in the printing of user-level terms that failed to
  account for [47m[untrans-table][0m entries for [47m[nth][0m, [47m[update-nth][0m, and
  [47m[update-nth-array][0m, when printing the first argument as a symbolic
  constant corresponding to a [stobj] argument.  Thanks to Warren
  Hunt for reporting this issue with an example much like the
  following.  When submitting the forms below, ACL2 output for the
  final form displayed the user-level term [47m(update-nth *fld* v st)[0m
  instead of the expected form, [47m(!nth *fld* v st)[0m.

    (defstobj st fld)

    (defmacro !nth (x y z)
      `(update-nth ,x ,y ,z))

    (add-macro-fn !nth update-nth)

    (thm (equal (update-fld v st)
                xxx)
         :hints ((\"Goal\" :in-theory (disable update-nth))))

  Fixed a failure to [guard]-check [type] declarations for [47m[let][0m and
  [47m[mv-let][0m forms.  Consider for example:

    (defun foo (x)
      (let ((a (car x)))
        (declare (type string a))
        a))

  Previously, the call [47m(foo '(3 4))[0m did not cause a guard violation,
  even though it should have done so.  (Indeed, the event
  [47m(verify-guards foo)[0m failed, and continues to fail.)

  Fixed a bug in redundancy checking for [47m[mutual-recursion][0m events that
  specify [47m:[0m[47m[ruler-extenders][0m in an [47m[xargs][0m [47m[declare][0m form.  Thanks to
  Sol Swords for sending an example that illustrates the bug: a
  [47m[mutual-recursion][0m event that, when executed twice, caused an error
  the second time rather than being redundant (see
  [redundant-events]).  The bug was actually in how ACL2 stores
  information about the [ruler-extenders] used in definitions: the
  [47m:ruler-extenders[0m specified for the first [47m[defun][0m was being
  mistakenly stored for the second [47mdefun[0m.  This mishandling of
  redundancy for [47m[mutual-recursion][0m events appears to be the only
  consequence of that bug.

  The following bug was probably not observable, but violated our claim
  that the system behaves as logically specified.  When a [guard]
  check failed during execution, the error message that was printed
  could differ slightly from what is logically specified.  (Technical
  detail: the error actually printed by source function [47mev-fncall-rec[0m
  was appropriately showing the original guard, but the specification
  function [47mev-fncall-rec-logical[0m was showing the untranslation of the
  translated guard.)  This has been fixed.

  The [47msave[0m and [47mretrieve[0m commands for the [proof-builder] (see
  [ACL2-pc::save] and [ACL2-pc::retrieve]) now cause an error when
  the supplied name is not a symbol; similarly for the [47m:event-name[0m
  argument of [47m[verify][0m.  The behavior wasn't as expected for
  non-symbol names; for example, after issuing the instruction [47m(save
  'abc)[0m in the [proof-builder], the command [47m(retrieve 'abc)[0m failed to
  resume the proof-builder session.  (Notice the erroneous use of the
  quoted symbol [47m'abc[0m, i.e., [47m(quote abc)[0m, rather than of the symbol
  [47mabc[0m.)  Thanks to Keshav Kini for bringing this problem to our
  attention.

  We fixed the following two bugs in the processing of backchain limits
  stored for rules.  Thanks to Dave Greve for bringing these to our
  attention.

    * For rules of class [47m:[0m[47m[type-prescription][0m, the specification of
      [47m:backchain-limit-lst[0m within the [47m:[0m[47m[rule-classes][0m could be
      ignored or cause a hard Lisp error.

    * For rules of class [47m:[0m[47m[meta][0m, preceding calls of
      [47m[set-default-backchain-limit][0m were ignored.

  Fixed a bug in the processing of certain operations on pathnames
  containing [47m\"..\"[0m.


Changes at the System Level

  By default, the ACL2 executable once again is named [47msaved_acl2[0m,
  though unlike previous versions, this executable is [hons-enabled].
  Correspondingly, the ACL2(c) executable (that is, the executable
  that is not [hons-enabled]) is by default [47msaved_acl2c[0m.  Thanks to
  David Hardin for suggesting these changes.

  Links from the home page to user's manual topics now point to the
  ACL2+Books combined manual, not the ACL2 (only) User's Manual,
  except for the one link that explicitly points to the latter.
  Thanks to David Hardin for feedback leading to this change, which
  was incorporated into the ACL2 Version 7.0 home page several days
  after the release of that version.

  Garbage collection notification has been turned off by default, not
  only for ACL2(c) as before, but also for (the default build)
  ACL2(h).  Thanks to Eric Smith for suggesting this change.  See
  [ACL2-customization] and see [gc-verbose] for how to turn such
  notification back on in your own environment.

  It is now possible to move the system books directory after
  certifying its books, without invalidating their status as
  certified.  Users should generally not notice this change.  We
  thank Harsh Raju Chamarthi and Camm Maguire for reporting problems
  with hacks we have produced over the years to support distribution
  of books with their [certificate] files.  Those hacks are no longer
  necessary: as a byproduct of this change, we have deleted both the
  [community-books] directory [47mbooks/fix-cert/[0m and the source function
  [47mmake-certificate-file-relocated[0m.  For a bit more detail see the
  final remark in the topic [full-book-name].  We also thank Eric
  Smith, Jared Davis, and Sol Swords for reporting bugs in our
  initial implementations of this enhancement.

  The [47mcertify-books[0m target for [47mmake[0m now excludes other expensive
  directories in addition to [47mworkshops[0m.

  (SBCL only) Modified the handling of environment variable [47mSBCL_HOME[0m.
  Thanks to Jared Davis for pointing out a problem leading to this
  change, namely, failure on his platform when evaluating [47m(require
  :sb-sprof)[0m in raw Lisp.

  Intended compiler optimizations are now guaranteed to be in place.
  We observed, thanks to communication from Jared Davis, that when
  ACL2 is built using SBCL 1.2.10, ACL2 starts up without the
  compiler optimizations that had been installed during the build.
  Perhaps that has been true for other SBCL versions or even other
  Lisps.  Now, ACL2 explicitly restores those optimizations when it
  starts up.  We observed a 5% time reduction for SBCL-based
  regression after this change.

  Environment variable [47mACL2_WRITE_PORT[0m is now ignored when doing
  [provisional-certification].  Thanks to Sol Swords for discussing
  this issue, which arose from a failure in [community-books]
  directory [47mbooks/workshops/2011/verbeek-schmaltz/sources/[0m, which
  uses [provisional-certification].

  (GCL only) A few tweaks were made in support of GCL changes starting
  with pre-releases of GCL 2.6.13 in late April 2015 (but these
  tweaks are backward compatible with older GCL releases).  Resulting
  ACL2 builds for a new GCL show dramatic speed-ups for a single
  user, perhaps cutting between a third and half the time, with less
  dramatic improvements when running regressions with [47m-j 8[0m.  Thanks
  to Camm Maguire for pointing us to the changes and for improving
  GCL.


EMACS Support

  The commands [47mControl-t e[0m and [47mControl-t Control-e[0m, defined in file
  [47memacs/emacs-acl2.el[0m, now check that the [47m*acl2-shell*[0m buffer exists,
  has a live process, and has a last line matching the specification
  in [47m*acl2-insert-pats*[0m, which has Emacs documentation (using
  [47mControl-h v[0m) but is set to a default based on shell prompts.
  Thanks to David Rager, Jared Davis, and Shilpi Goel for helpful
  discussions leading to this change.

  We installed the following two patches to file [47memacs/emacs-acl2.el[0m,
  both contributed by Keshav Kini.

    * Emacs highlighting for forms starting with \"[47m(def[0m\" now works when the
      \"[47mdef[0m\" symbol has a package prefix, for example,
      \"[47m(fty::deflist[0m\".

    * The Control-d character is no longer explicitly bound to the default,
      [47mdelete-char[0m, but instead is unbound in [47mcomint-mode-map[0m, so that
      the global binding of Control-d will take effect.  Thus, users
      who bind Control-d themselves will no longer have that binding
      overridden in shell-mode (or comint-mode).

  We made several improvements to the [ACL2-doc] Emacs browser for ACL2
  [documentation].

    * Fixed a bug that could occur when Emacs variable
      [47mlarge-file-warning-threshold[0m is [47mnil[0m.  Thanks to Bob Boyer for
      bringing this bug to our attention.

    * Links are now in color (blue, by default).  See [ACL2-doc] for
      instructions on how to change or remove this color.  Thanks to
      Jared Davis for suggesting the use of color.  We are open to
      suggestions for improvements; this might be just a first step.

    * Allow limiting search and index commands to ancestors (sub-topics,
      sub-sub-topics, etc.) of a command (including the command
      itself), by supplying a prefix argument.

    * New [47m\"p\"[0m, [47m\"<\"[0m, and [47mControl-TAB[0m commands are analogues of [47m\"n\"[0m, [47m\",\"[0m, and
      [47mTAB[0m --- for search, index, and next-link commands, respectively
      --- to go backward instead of forward.


Experimental Versions

  (For ACL2(p) users only; see [parallelism]) If parallel execution is
  enabled (see [set-parallel-execution]), as it is by default in
  ACL2(p), then [47mhons-wash[0m and [47mhons-clear[0m may be no-ops (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 [47m[hons-wash!][0m or [47m[hons-clear!][0m,
  which however require a [trust-tag].  Thanks to Bob Boyer for
  bringing this issue to our attention.")
 (NOTE-7-2
  (RELEASE-NOTES)
  "ACL2 Version 7.2 (January, 2016) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 7.1 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  See also [note-7-2-books] for a summary of changes made to the ACL2
  Community Books since ACL2 7.1, including the build system.


Changes to Existing Features

  The utility [47m[with-guard-checking][0m is now limited to forms that do not
  reference the ACL2 [state].  A related new utility,
  [47m[with-guard-checking-error-triple][0m, may be used for forms that
  evaluate to [error-triple]s.  For an example showing a bug when
  [47mwith-guard-checking[0m was applied to forms that access [state], see
  the comment about ``with-guard-checking'' in Community Books file
  [47msystem/doc/acl2-doc.lisp[0m, in the form [47m(defxdoc note-7-2 ...)[0m.  We
  thank Jared Davis for sending us an example showing that our
  preliminary fix was not adequate; for details, and for how a trust
  tag can avoid the new restriction (at the potential cost of
  unsoundness), see the remark for advanced users in the
  documentation for [with-guard-checking].

  Several built-in functions are now in [47m:[0m[47m[logic][0m mode with [guard]s
  verified: [47m[term-order][0m, [47mmerge-sort-term-order[0m, [47m[arity][0m, [47m[termp][0m,
  [47m[term-listp][0m, and [47m[term-list-listp][0m --- new functions [47marities-okp[0m
  and [47mplist-worldp-with-formals[0m; and (thanks to Eric Smith for the
  suggestions) [47mcollect-by-position[0m, [47mmake-lambda-application[0m, [47m>=-len[0m,
  [47mall->=-len[0m, [47mstrip-cadrs[0m, and [47malist-to-doublets[0m.  (Technical note:
  This enhancement followed the usual process: adding or extending
  community books in directory [47mbooks/system/[0m, including any new such
  books in [47mbooks/system/top.lisp[0m, and updating source constant
  [47m*system-verify-guards-alist*[0m.)

  Deprecated utilities [47mclear-hash-tables[0m and [47mwash-memory[0m have been
  eliminated.  For [47mclear-hash-tables[0m, you can get the same effect by
  first invoking [47m[clear-memoize-tables][0m, and then invoking either
  [47m(hons-clear t)[0m or instead, if your executable uses static honsing,
  [47m(hons-wash)[0m.  For [47mwash-memory[0m you can invoke [47m(clear-memoize-tables)[0m
  and then [47m(hons-wash)[0m.  Thanks to Jared Davis for helpful
  discussions.

  The [command]s [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubu][0m have been changed.  Their previous
  functionality is available with the commands [47m:[0m[47m[ubt?][0m and [47m:[0m[47m[ubu?][0m,
  respectively.  Now, [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubu][0m behave much more like [47m:[0m[47m[ubt!][0m
  and [47m:[0m[47m[ubu!][0m (which have not been changed), in that they do not
  cause queries; however, unlike [47m:[0m[47m[ubt!][0m and [47m:[0m[47m[ubu!][0m, the [command]s
  [47m:[0m[47m[ubt][0m and [47m:[0m[47m[ubu][0m do report errors.  Thanks to Eric Smith for
  requesting this change.

  Now, [47m:[0m[47m[puff*][0m has an optional argument that can avoid rollback of the
  world when there is an error.  See [puff*].

  After invoking [47m:[0m[47m[redef][0m and redefining functions in a
  [47m[mutual-recursion][0m event, it was necessary to answer [47mY[0m repeatedly
  in order to complete the redefinitions.  A new option, [47mY![0m, will
  complete the remaining such redefinitions without further query.
  Thanks to Eric Smith for requesting this feature.

  A harmless but somewhat annoying superfluous declaration [47m(DECLARE
  (XARGS :NON-EXECUTABLE T))[0m was, by default, included in the
  generated [47m[defun][0m for a [47m[defun-sk][0m event.  This has been fixed.
  Thanks to Eric Smith for bringing this issue to our attention.

  The [proof-builder] command [47mshow-rewrites[0m (or [47msr[0m; see
  [ACL2-pc::show-rewrites]) now shows additional bindings of free
  variables that would be generated when a third argument of [47mt[0m is
  supplied for the [47mrewrite[0m (or [47mr[0m; see [ACL2-pc::rewrite]) command.
  Thanks to Ben Selfridge for noting that this information was
  missing.  Note that we also made a few trivial formatting changes
  for [47msr[0m.

  The redundancy check for [47m[encapsulate][0m [events] has changed in two
  small ways.  One change is described below (see ``Redundancy
  checking for [47m[encapsulate][0m'').  The other change is the redundancy
  check now properly identifies a previous subsidiary [47m[make-event][0m
  form with its expansion, ignoring the [47mrecord-expansion[0m wrapper.
  See the example labeled ``Redundant after Version_7.1 (as of
  mid-September 2015)'' in community book
  [47mbooks/make-event/local-elided.lisp[0m.

  A new mechanism for controlling the checking for [invariant-risk]
  replaces the raw Lisp global variable [47m*ignore-invariant-risk*[0m,
  which is obsolete.  See [set-check-invariant-risk].  In particular,
  the default is now to print a (new) warning when encountering
  potential slowdown due to invariant-risk.  Note that more functions
  are now subject to the invariant-risk check; see the discussion
  below in the section on Bug Fixes that pertains to invariant-risk.

  The (undocumented) system utility [47mwith-ubt![0m, which continues to be
  used in [47m[trace!][0m and [47m[disassemble$][0m and is now also used in
  [47m[set-check-invariant-risk][0m, now binds [ld] special
  [47m[ld-pre-eval-print][0m to [47mnil[0m.  Thus, when [47mwith-ubt![0m is invoked,
  subsidiary forms will not be printed to the screen even when the
  above LD special is non-nil.

  Formerly, [47m[certify-book][0m, [47m[include-book][0m, and [47m[puff][0m operated with
  guard-checking off; technically, with [state] global
  [47mguard-checking-on[0m bound to [47mnil[0m.  Now, that value is bound to [47mt[0m,
  which matches the default value in the top-level loop.  Thanks to
  Eric Smith for suggesting this change to [47mcertify-book[0m and to Jared
  Davis for a helpful conversation about it.

  For [guard] proof obligations, all conjuncts from [stobj]
  declarations (supplied as [47m:stobjs[0m keywords in [47m[xargs][0m declarations)
  preceded all other conjuncts (i.e., from [47m[type][0m declarations or
  [47m[xargs][0m [47m:guard[0m declarations).  Previously, this was only true
  within a given [47m[declare][0m form.  Thanks to Dave Greve for bringing
  this issue to our attention.

  A new runic abbreviation has been added: [47m:r[0m, which abbreviates
  [47m:rewrite[0m.  For example, you may use [47m(:r app-assoc)[0m in a theory
  expression to denote the [rune] [47m(:rewrite app-assoc)[0m.  See
  [theories].

  It is now possible to [monitor] rules by supplying a symbol or other
  runic designator other than a theory (see [theories]), thus
  relaxing the previous requirement that a [rune] is supplied.  For
  example, the form [47m:monitor nth t[0m is legal, as is [47m:monitor (:d nth)
  t[0m, where before the corresponding command would necessarily have
  been [47m:monitor (:definition nth) t[0m.  Thanks to Eric Smith for
  requesting this enhancement.

  Suitable [warnings] are now printed when attempting to [monitor]
  [simple] rules of class [47m:[0m[47m[definition][0m.  These had only been printed
  for simple rules of class [47m:[0m[47m[rewrite][0m, because of potential
  inefficiency in computing for such warnings in the case of large
  [47m[mutual-recursion][0m [events], but that problem has been addressed in
  the ACL2 source code using [fast-alists].

  ACL2 sometimes produces smaller [47m.cert[0m files, by avoiding certain
  macroexpansion.  Formerly, for each macro call encountered in a
  certification world or [make-event] expansion, ACL2 performed
  repeated single-step macroexpansion until an event form was
  obtained, and replaced the original form with that result.  The
  reason for this replacement was to modify certain [47m[include-book][0m
  forms involving relative pathnames (though only under specific
  conditions).  Now, no such replacement is made except when such a
  modification is made to an [47minclude-book[0m call.  This change could
  result in smaller [certificate] ([47m.cert[0m) files; for example, if a
  [portcullis] [command] is a macro call, [47m(foo)[0m, that expands into a
  very large [47m[defun][0m or [47m[defthm][0m event, the certificate file will
  contain [47m(foo)[0m rather than its macroexpansion.  Of course, this
  change could result in longer times for processing an
  [47m[include-book][0m forms, because now macroexpansion may need to be
  done when they are processed; but such macroexpansion has always
  been necessary for all forms [3mwithin[0m a book, so such behavior is at
  least more consistent than before.  If you really want a portcullis
  macro call to be expanded, wrap it in a [47m[make-event][0m call, for
  example, [47m(make-event '(foo))[0m instead of [47m(foo)[0m.

  The macros [47m[defund][0m and [47m[defthmd][0m now produce less output.  In fact,
  the output is the same as for [47m[defun][0m and [47m[defthm][0m, respectively,
  except for the printing of the return value, which (as before)
  looks like [47m(:DEFUND NAME)[0m or [47m(:DEFTHMD NAME)[0m.  Thanks to Jared
  Davis for suggesting such a change.

  Remaining traces of legacy documentation have generally been
  eliminated, including all vestiges of the obsolete command, [47mdefdoc[0m.
  ([Documentation] is now generally provided through the [xdoc]
  system.)  In particular, optional and keyword arguments, [47mdoc[0m, have
  been eliminated for the following macros.

    * [47m[defabsstobj][0m

    * [47m[defabsstobj-missing-events][0m

    * [47m[defaxiom][0m

    * [47m[defchoose][0m

    * [47m[deflabel][0m

    * [47m[defstobj][0m

    * [47m[defstub][0m

    * [47m[deftheory][0m

    * [47m[defthm][0m

    * [47mdefthm-std[0m (defined only in ACL2(r); see [real])

    * [47m[defttag][0m

    * [47m[in-arithmetic-theory][0m

    * [47m[include-book][0m

    * [47m[push-untouchable][0m

    * [47m[regenerate-tau-database][0m

    * [47m[remove-untouchable][0m

    * [47m[reset-prehistory][0m

    * [47m[thm][0m

    * [47m[verify-guards][0m

  Note that [47m[defabbrev][0m, [47m[defconst][0m, [47m[defmacro][0m, [47m[defpkg][0m, and [47m[defun][0m
  may still be supplied documentation strings, as a nod to Common
  Lisp.  In particular, for [47mdefun[0m and [47mdefmacro[0m this can ease the
  porting of Common Lisp code to ACL2.

  Several source-level definitions have changed, many of them
  unadvertised.  Some are for unadvertised event commands like
  [47mdefthm-fn[0m, which no longer have a [47mdoc[0m argument (see ``traces of
  legacy documentation have generally been eliminated'' above).
  Others, like [47mflambda-applicationp[0m, are macros that were formerly
  defined with [47m[defabbrev][0m but now are defined with [47m[defmacro][0m;
  thanks to Eric Smith for suggesting such simplifications.

  In prover output, terms of the form [47m(not (not expr))[0m had been printed
  simply as [47mexpr[0m.  That could cause confusion; for example, the
  following form would lead to the checkpoint [47m(EQUAL (ALISTP X)
  (ALISTP X))[0m, where actually the checkpoint was [47m(EQUAL (NOT (NOT
  (ALISTP X))) (ALISTP X))[0m.  This ``feature'' has been eliminated.
  Thanks to Shilpi Goel for bringing this issue to our attention and
  supplying an illustrative example.

  A warning was formerly printed when encountering a macro call with
  duplicate keys, for example [47m(foo 3 :y 4 :y 5)[0m where [47m:y[0m is a keyword
  argument of the macro, [47mfoo[0m.  Now, this is an error by default, in
  order to make it easier for users to catch bugs due to accidental
  repetition of a keyword argument.  However, the utility
  [47m[set-duplicate-keys-action][0m can be used to allow such duplicate
  keys, with or without a warning.  Thanks to Jared Davis for
  requesting these changes.

  Warnings are no longer printed for [47m:use[0m hints applied to functional
  instances of enabled rules.  Thanks to Eric Smith for suggesting
  this change.

  The second (optional) argument of [47mshow-accumulated-persistence[0m may
  now have a new value, [47m:list[0m, which causes the results to be
  displayed as a single list with entries of the form [47m(frames tries
  xrune)[0m.  Thanks to David Rager for requesting a way to display
  useless [rune]s, sorted in a manner that can help with automating
  the creation of [47min-theory[0m forms that [47mdisable[0m unnecessary runes;
  also thanks for his helpful discussions in designing its
  functionality.  See [accumulated-persistence]; in particular,
  [47m(show-accumulated-persistence :useless :list)[0m can display a list of
  runes to consider disabling.

  The utility [47m[print-gv][0m now takes additional keyword arguments,
  [47m:conjunct[0m and [47m:substitute[0m, which respectively show a specific
  conjunct of the [guard] evaluation that produced [47mnil[0m, and avoid
  [47m[flet][0m in favor of substituting actuals (even at the risk of
  duplication).  See [print-gv], and see [set-print-gv-defaults] for
  a utility that sets default values for the keyword arguments.
  Thanks to Eric Smith for requesting these enhancements and for
  helpful discussions.  Note that the system default value for the
  [47m:evisc-tuple[0m keyword is now the value of the form
  [47m(print-gv-evisc-tuple)[0m.

  [State] global variable [47mglobal-enabled-structure[0m is now untouchable
  (see [remove-untouchable]).

  Users may see a change in the order, number, and size of termination
  proof obligations because of an optimization that removes trivial
  equality tests generated by [47m[case][0m and [47m[cond][0m statements.  (The
  removal of the tests can affect subsumption, which is how the order
  and number of proof obligations may change.)

  Once again, all documented constant, function, and macro symbols in
  the [47m\"ACL2\"[0m package are included in the constant, [47m[*ACL2-exports*][0m.
  Community book [47mbooks/misc/check-acl2-exports.lisp[0m has been updated
  for the current documentation system to enforce this invariant in
  the future.  Thanks to Jared Davis for pointing out that the symbol
  [47m[extend-pe-table][0m was missing from [47m*acl2-exports*[0m and would be a
  good addition; that led us to this change.  As also suggested by
  Jared, we added the symbols [47m[exists][0m and [47m[forall][0m to
  [47m*acl2-exports*[0m, as well.

  The quantifier [47m[forall][0m or [47m[exists][0m used in the body of a [47m[defun-sk][0m
  call must now be in the [47m\"ACL2\"[0m package.  Many users will not notice
  this change, since the symbols [47mforall[0m and [47mexists[0m in the [47m\"ACL2\"[0m
  package are now in the list [47m[*ACL2-exports*][0m; see the paragraph
  just above.  Thanks to Alessandro Coglio for a remark leading to
  this change.

  Definitions are no longer redundant that have different values
  specified for their [47m[xargs][0m keyword, [47m:normalize[0m.  (See
  [redundant-events].)  Although we are not aware of a need to make
  this change, this change eliminates a possible unsoundness.

  It is now the case that [47mopen-output-channel[0m and [47mopen-output-channel![0m
  will attempt to create missing directories as needed.  (This had
  formerly been observed to be the case in CCL but not other Lisp
  implementations.)  Thanks to Jared Davis for requesting this
  enhancement.


New Features

  It is now possible to make ACL2 avoid the well-formedness checks done
  when metafunctions and clause processors are run.  By default, when
  a metafunction or clause processor is run, ACL2 calls [47m[termp][0m or
  [47m[term-list-listp][0m, respectively, on the new value to make sure it
  is well-formed.  Now, if you prove and provide a
  [47m:[0m[47m[well-formedness-guarantee][0m with the [47m:meta[0m or [47m:clause-processor[0m
  rule-class, you can skip these checks.  This can speed up the use
  of metafunctions and clause processors on big terms and formulas.

  It is now possible to ensure the integrity of statistics produced by
  [47m[memsum][0m after functions are [memoize]d.  See
  [protect-memoize-statistics].  Thanks to Alessandro Coglio for
  noticing oddities in those statistics and to Jared Davis for
  providing an implementation of this new feature.

  Function [47m[read-file-into-string][0m provides an efficient way to return
  the contents of a file as a string, without returning an ACL2
  [state].  Thanks to Jared Davis for pointing out a logical flaw in
  the initial implementation.

  A new function, [47mget-skipped-proofs-p[0m, can tell system programmers
  whether or not a given event name was introduced with proofs
  skipped, as with [47m[skip-proofs][0m or using [47m[set-ld-skip-proofsp][0m.  See
  [system-utilities].  Thanks to Eric Smith for requesting such a
  capability.

  A new [table] permits the association of names with substitute event
  forms, for use by [history] commands that print event forms,
  including [47m:[0m[47m[pe][0m, [47m:[0m[47m[pc][0m, [47m:[0m[47m[pcb][0m, and [47m:[0m[47m[pcb!][0m.  See
  [extend-pe-table].  Thanks to Eric Smith for requesting such a
  capability.  Note that [47m:[0m[47m[pe!][0m now avoids use of this table.

  A new macro, [47mffn-symb-p[0m, has been introduced and then used in the
  source code to simplify some definitions.  Thanks to Jared Davis
  for a remark that led us to define and introduce this macro.  See
  [system-utilities] for a description of this and many other
  low-level system utilities.

  It is now possible to give [hints] that specify the use of
  termination or [guard] theorems for existing function symbols.  See
  [lemma-instance], [termination-theorem-example], and
  [guard-theorem-example].  Also see [gthm] and [tthm] for related
  query utilities.  Thanks to Alessandro Coglio and Eric Smith for
  requesting these features.

  See [set-print-gv-defaults] for a new utility for setting default
  values for the keyword arguments of [47m[print-gv][0m.  Thanks to Eric
  Smith for requesting this feature and for helpful discussions.

  For [history] commands and the function [47m[disabledp][0m, the notion of
  ``[disable]d'' is now computed inside the [break-rewrite] loop with
  respect to the [enable]d status at the current point of the current
  proof attempt, rather than with respect to the global state.
  Thanks to David Rager for suggesting this enhancement.  Note that
  this change only affects [history] commands and [47m[disabledp][0m, not
  other utilities (for example [47m[tau-status][0m and [47m[guard-obligation][0m).x

  New system utility [47m[getpropc][0m is a convenient abbreviation for
  [47m[getprop][0m.

  A new utility causes some warnings to be printed in a ``raw''
  s-expression format.  See [set-raw-warning-format].  Thanks to
  Shilpi Goel for requesting this utility.

  The macro [47maccumulated-persistence-oops[0m undoes the effect of
  accidentally clearing statistics with [47m(accumulated-persistence t)[0m
  or [47m(accumulated-persistence :all)[0m.  See [accumulated-persistence].
  Thanks to Jared Davis for requesting this feature.


Heuristic and Efficiency Improvements

  The redundancy check for [47m[defconst][0m has been sped up in cases with a
  very large term, as in the following example.  Thanks to David
  Rager and Jared Davis for helpful related discussions.

    (defun make-tree (n)
      (declare (type (integer 0 *) n))
      (if (zp n)
          nil
        (let ((x (make-tree (1- n))))
          (cons x x))))
    (make-event
    `(defconst *a* (hons-copy ',(make-tree 50))))
    ; Redundant, and formerly very slow:
    (make-event
    `(defconst *a* (hons-copy ',(make-tree 50))))

  Processing of [47m[defpkg][0m forms may be faster, thanks to a change
  suggested by Jared Davis (who observed significant speedup in
  SBCL).

  Optimizations have been made that can speed up [47m[include-book][0m for
  some large books, as follows.  In particular, for the form [47m(time$
  (include-book \"centaur/sv/tutorial/alu\" :dir :system))[0m we have seen
  a 25% reduction (on Mac OS) for the first item below, and an
  additional 29% reduction (also on Mac OS) for the second item.

    * Various optimizations have been made for [theory] manipulation,
      including some to make processing more efficient for [47m[defund][0m
      and [47m[defthmd][0m.  Thanks to Sol Swords for bringing this issue to
      our attention in GitHub Issue #401 and for reporting bugs in
      our initial implementations.

    * Redundancy checking for [47m[encapsulate][0m [events] can be much faster.
      The only functional change (with one small exception, described
      in an item above) is to check for a sub-event of the proposed
      [47mencapsulate[0m event that is attempting to introduce a new name;
      if no such name is found, then the redundancy check is skipped,
      and the proposed [47mencapsulate[0m event is evaluated.  This new
      check is quite thorough (see [redundant-encapsulate]), so we
      expect it to be rare that an [47mencapsulate[0m event that was
      formerly redundant is no longer redundant.

  [Certify-book] is faster in some cases; for example, we found the
  time required to certify a book whose only event is [47m(include-book
  \"centaur/gl/gl\" :dir :system)[0m was reduced from 57 seconds to 10
  seconds.  (Implementation note: The change was to avoid installing
  worlds in function [47mdefpkg-items[0m.  That had probably been done in
  order to speed up calls of [47msimple-translate-and-eval[0m in
  [47mdefpkg-items-rec[0m, but that speed-up seems to be dwarfed by the
  expense of [47mextend-world1[0m in such cases.)

  We tweaked a part of the so-called ``clausify'' process for doing
  Boolean simplification towards producing subgoals of a given goal,
  namely, the so-called ``subsumption-replacement-loop''
  (specifically, source function [47mfind-subsumer-replacement[0m).  Thanks
  to Jared Davis for helpful discussions that led us to make this
  change.

  [47m[Defevaluator][0m is faster, especially so when many functions are to be
  interpreted by the new evaluator.  The new version is a refactored
  version of community book [47mbooks/tools/defevaluator-fast.lisp[0m used
  with the permission of its original authors Sol Swords and Jared
  Davis.  Thanks!

  The Common Lisp code generated for [stobj] accessors and updaters has
  been improved in the case that the [47m:type[0m is [47mT[0m or of the form [47m(array
  T ...)[0m.  In particular, we have seen efficiency improvements for
  host Lisp CCL when the value read from or written to the array is a
  fixnum (integers that are sufficiently small in absolute value).
  Thanks to Bob Boyer and Gary Byers for helpful discussions that led
  to this improvement.


Bug Fixes

  We fixed a soundness bug pertaining to [local] [47m[defpkg][0m [events].
  See community books directory [47mmisc/hidden-defpkg-checks/[0m for an
  example that exploits this bug to prove [47mnil[0m in Version 7.1 and
  perhaps some other previous ACL2 versions.  Thanks to Sol Swords
  for helping us set up that test (specifically, suggesting addition
  of the comment ``[47m; no_port[0m'' after an [47m[include-book][0m call that is
  not to be put into a [47m.port[0m file).

  The use of [47m[set-deferred-ttag-notes][0m during [47m[make-event][0m expansion
  could cause some TTAG NOTE messages never to be printed.  Thanks to
  Jared Davis for a remark that led us to discover this bug, which
  could be considered a soundness bug since the TTAG NOTE mechanism
  is a key part of the soundness story.  With this change, the
  effects of [47mset-deferred-ttag-notes[0m persist past [47mmake-event[0m
  expansion.

  It was possible to use [47m:[0m[47m[program][0m mode functions to write past the
  end of an array, leading to unsoundness.  This has been fixed.
  Now, updaters for [stobj] array fields are marked as having
  so-called ``invariant-risk'', even when the element type of the
  array is [47mt[0m (unconstrained).  Also marked with invariant-risk are
  built-in functions [47m[aset1][0m and [47m[aset2][0m.  See [program-wrapper],
  [invariant-risk] and [set-check-invariant-risk], which is discussed
  above in the section Changes to Existing Features.  Thanks to Jared
  Davis and Sol Swords for sending an example to illustrate the bug.

  When ACL2 was interrupted while debugging was on (see
  [set-debugger-enable]), it was possible later to get the following
  error repeatedly:

    HARD ACL2 ERROR in TIME-TRACKER:  It is illegal to specify :START for
    tag :TAU, because tracking for this tag is already in an active state.

  This problem has been fixed, by defining a new keyword argument for
  [47m[time-tracker][0m, [47m:start![0m, and using it to track the use of the
  [tau-system]; see [time-tracker] and [time-tracker-tau].

  ACL2 would cause an error at startup when the value of environment
  variable [47mACL2_SYSTEM_BOOKS[0m was a string starting with the tilde
  character ([47m~[0m).  This has been fixed.  Thanks to Shilpi Goel and
  Warren Hunt for bringing this bug to our attention.

  (GCL only) It had not been possible to define a [stobj] with more
  than 64 fields in GCL.  We have removed that restriction.
  (Technical note: GCL disallows calls of the function, [47mvector[0m, with
  more than 64 arguments.  So instead we now build a list of stobj
  fields that is coerced to a vector, rather than calling [47mvector[0m
  directly.)

  Fixed [47m[deftheory-static][0m by declaring the [world] to be [47mignorable[0m,
  thus avoiding errors for forms that don't reference the world.
  Thanks to Jared Davis for pointing out this bug with the example,
  [47m(deftheory-static my-theory '(car-cons))[0m.

  Fixed a bug that was causing the [47mhiding-cars[0m component of the
  [47m[ld-evisc-tuple][0m to be ignored when printing evaluation results.

  We avoid an error in the case that [47m[skip-proofs][0m is used around a
  definition with no tests above a recursive call, as in the
  following example.

    (skip-proofs (defun foo (x)
                  (declare (xargs :measure (acl2-count x)))
                  (identity
                   (cond ((zp x) 17)
                         (t (foo (1- x)))))))

  Thanks to Dave Greve for bringing this bug to our attention.  Note
  that such a definitional event may be unsound (not surprisingly,
  because of the use of [47mskip-proofs[0m).  For example, the following
  form succeeds: [47m(thm nil :hints ((\"Goal\" :induct (foo x))))[0m.

  Several improvements have been made to avoid errors in the execution
  of [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m.  Thanks to Eric Smith for reporting this
  issue.  (Technical implementation note: a bug in source function
  [47mfind-longest-common-retraction1-event[0m, used in reverting logical
  [world]s, was fixed in support of this work.)

  When the [47m[default-defun-mode][0m was [47m:[0m[47m[logic][0m, then a [47m[mutual-recursion][0m
  form with [47m[xargs][0m declaration of [47m:[0m[47m[program][0m mode, which also had
  one or more [47m[defund][0m [events], would cause a error when attempting
  to [disable] new function symbols after admitting their
  definitions.  This has been fixed.  Thanks to Jared Davis for
  bringing this bug to our attention (GitHub Issue #464).

  We fixed some printing bugs for [47m:[0m[47m[psof][0m, [47m:[0m[47m[pso][0m, and raw proof format
  (see [set-raw-proof-format]).  Both [47m:[0m[47m[psof][0m and [47m:[0m[47m[pso][0m were
  printing explicit splitter notes (see [splitter]) --- and worse
  yet, and thanks to David Rager for pointing this out, [47m:[0m[47m[psof][0m was
  printing them to the terminal.  Those explicit splitter notes were
  not appropriate during proof replay, where instead parenthetical
  phrases like ``[47m(if-intro)[0m'' are sufficient; those phrases continue
  to be printed during proof replay, just as when [gag-mode] is off.
  Raw proof format had a couple of whitespace bugs, but more
  important was its failure to indicate any information about
  splitters; so now it prints the same explicit splitter notes as are
  printed for gag-mode.

  Insufficient checking has been fixed for [signature]s.  Thanks to
  Jared Davis for sending the example [47m((f * *) => * :formals (x)
  :guard (natp x))[0m, which was not flagged as illegal by ACL2 even
  though the specified arity of 2 did not match the length of the
  specified [47m:formals[0m.  There could also be mismatches between the
  [stobj]s specified, for example, with [47m(((f * st1) => * :formals (x
  st2) :guard (natp x)))[0m, that were not flagged as illegal.

  The inclusion of uncertified books was leading to some incorrect
  messages about other books that are also uncertified.  This has
  been fixed (though the messages can still be verbose at times).
  Thanks to Eric Smith for sending an example to bring this problem
  to our attention.

  There were some incorrect error messages produced for bad calls of
  [47m[ec-call][0m; these have been fixed.

  Fixed a bug in [memoization] that could occur when multiprocessing is
  turned on, as in the call [47m(acl2::mf-multiprocessing t)[0m in community
  book [47mbooks/centaur/vl/server/server-raw.lsp[0m.  Thanks to Sol Swords
  for reporting a bad report from [47m[memsum][0m when profiling function
  [47minclude-book-fn[0m before including system book [47m\"doc/top\"[0m.

  [Guard] violation error messages printed [47m'ACL2_INVISIBLE::|The Live
  State Itself|[0m where they should have printed [47mSTATE[0m; similarly for
  the utility [47m[print-gv][0m, which also failed to print entirely in
  user-level ``untranslated'' syntax.  These problems have been
  fixed.  Thanks to Eric Smith for bringing the ``[47mSTATE[0m'' bug to our
  attention.

  Infinite loops occurred for calls of [47m(close-output-channel
  *standard-co* state)[0m after redirecting standard output using
  [47mset-standard-co[0m.  A clean error now occurs instead.

  We fixed a bug in [47m[state-global-let*][0m --- actually, in its supporting
  system utility [47macl2-unwind-protect[0m --- that allowed capture of a
  lexical variable, [47mtemp[0m, to produce bad results, for example as
  follows.

    (defun foo (temp state)
      (declare (xargs :stobjs state :mode :program))
      (state-global-let*
       ((x 3))
       (pprogn
        (fms \"TEMP = ~x0~%X = ~x1~%\" (list (cons #0 temp) (cons #1 (@ x)))
             *standard-co* state nil)
        (value nil))))
    (foo 17 state) ; should show TEMP = 17 and X = 3, but caused Lisp error

  ACL2 no longer prints a message for a failed [47m:induct[0m hint (in the
  case that [gag-mode] is off), saying that a definition is
  [disable]d when that is not the case.

  (CCL only, probably only 32-bit CCL) We fixed a bug manifested with
  an error, ``is not of the expected type (UNSIGNED-BYTE 32).''
  (Technical note: Function [47mccl::set-lisp-heap-gc-threshold[0m requires
  a fixnum, but was passed a bignum.)  Thanks to Harsh Raju Chamarthi
  for sending us a log that exhibited this bug, namely
  [47mbooks/oracle/stv-invariant-extraction-pitfall/alu.lisp[0m, which seems
  to have evoked the bug by using an unusually large amount of
  memory.

  One might reasonably expect that for a [rewrite] or [linear] rule
  with a hypothesis of the form [47m(force ...)[0m or [47m(case-split ...)[0m, an
  attempt to relieve that hypothesis should be successful when
  forcing is enabled.  The situation is a bit tricky if the
  hypothesis has free variables, but even then, one would expect
  success if the [47m:match-free[0m value is the default, [47m:all[0m, or if no
  suitable bindings are found.  Such attempts had however not always
  been successful; but they are now, and the relevant documentation
  on [free-variables] has been clarified.  For an example exhibiting
  the bug, see the comment about ``free variables'' in Community
  Books file [47msystem/doc/acl2-doc.lisp[0m, in the form [47m(defxdoc note-7-2
  ...)[0m.

  An inappropriate warning has been eliminated for some
  [type-prescription] rules, for example the following.

    (defthm foo
      (implies (alistp mem)
               (or (equal (assoc loc mem) nil)
                   (consp (assoc loc mem))))
      :rule-classes :type-prescription)

  The warning had claimed that the rule ``may be weaker than you
  expect'' because the theorem itself ``is not provable using
  type-set reasoning''.  But the theorem is provable when
  [guard-holders] are removed, as could generally be expected; so
  now, the check is applied after removing guard-holders from the
  theorem.

  The [guard]s stored for [macros] now include [type] declarations.
  Formerly the guards stored for macros were based only on the
  [47m:[0m[47m[xargs][0m [47m:guard[0m keyword.  Consider for example the following
  definition.

    (defmacro foo (x)
      (declare (type integer x))
      x)

    (defun bar (y)
      (foo y))

  Formerly, no error occurred when processing the definition of [47mbar[0m,
  because the guard stored for [47mfoo[0m was [47mt[0m.  Now, the guard stored for
  [47mfoo[0m is [47m(integerp x)[0m; since the variable [47my[0m is not an integer (it is
  a symbol), the attempted [47m[defun][0m for [47mbar[0m causes an error.


Changes at the System Level

  ACL2 is now defined to incorporate its [hons-enabled] features.  We
  formerly supported building ACL2 without these features, resulting
  in so-called Classic ACL2, also called ``ACL2(c)''.  Such builds
  are no longer supported: although it is still technically possible
  to build ACL2(c), we do not stand behind such builds; in
  particular, we do not test them, and we have removed the
  [47mGNUmakefile[0m target, [47msaved_acl2c[0m.

  (CCL only) Starting with CCL Version 16384, EGC (the ephemeral
  garbage collector) is enabled in ACL2 by default, in place of a
  ``[47mstart-sol-gc[0m'' memory management scheme, but with some of the
  delay in full garbage collection that had been provided by that
  scheme.  That scheme is still available to users, under a different
  name and inside the ACL2 loop; see [set-gc-strategy].  (Note that
  both [47mset-gc-strategy[0m and [47mgc-strategy[0m have been added to
  [47m[*ACL2-exports*][0m.)  Thanks to Gary Byers for CCL improvements
  leading to this change, and to him, Bob Boyer, Jared Davis, and Sol
  Swords for helpful discussions.  The default behavior can be
  restored to the previous behavior at ACL2 build time, by setting
  [47mMake[0m variable [47mACL2_EGC_ON=nil[0m when building an ACL2 executable.

  A new mechanism allows importing of theorems into the ACL2 source
  code, thus extending the existing mechanism for importing
  termination and guard verification for system functions (see the
  item above about [47m[term-order][0m, [47mmerge-sort-term-order[0m, and so on).
  Using this mechanism, some theorems have been imported from a new
  community book, [47mbooks/system/termp.lisp[0m.  (For an example of how
  ACL2 developers use this mechanism, see the call of [47msystem-events[0m
  in ACL2 source file [47mboot-strap-pass-2.lisp[0m.)

  File [47mGNUmakefile[0m in the (top-level) ACL2 sources directory now sets
  environment variable [47mTIME_CERT[0m so that regressions will generate
  timing information.

  (SBCL only) The [47m--control-stack-size[0m argument for ACL2 executables
  saved for SBCL is now 64 (formerly 16).  Thanks to Jared Davis for
  requesting this increase.

  The existing utility [47m[get-event-data][0m is now documented.  Moreover,
  it can be used for determining whether an interrupt (Control-C)
  occurred during execution of an event.  (This capability is used in
  a new utility, [47m[removable-runes][0m.)  See [get-event-data].

  The startup banner now shows the git commit hash for development
  snapshots.  Thanks to Bob Boyer for suggesting such a modification
  and to Jared Davis for bringing to our attention the appropriate
  git command for retrieving the hash.

  (CMUCL only) It is now the case for CMUCL that [47m[setenv$][0m modifies the
  environment of the underlying Lisp process.  Thanks to Jared Davis
  for this suggestion, and for pointing out that CCL and SBCL [at
  least] already have this behavior.

  A new optimize declaration for [47m[defun][0m, [47m(:stack-access 3)[0m, can result
  in some speed up for evaluations done when the host Lisp is CCL
  (but is likely to be a no-op in other host Lisps).  Thus, you may
  write: [47m(defun foo (x) (declare (optimize (:stack-access 3))) ...)[0m.
  Thanks to Gary Byers and the CCL team for their excellent compiler
  work, including the new [47mstack-access[0m feature, and to Bob Boyer and
  Warren Hunt for helpful discussions.  To build ACL2 on CCL with
  this feature, add the variable setting [47mACL2_STACK_ACCESS=3[0m to the
  [47mmake[0m command that you invoke to build ACL2.  NOTE: The use of
  ACL2_STACK_ACCESS relies on recognition by CCL of the [47m:stack-access[0m
  keyword for optimize expressions, hence will only have effect for
  CCL versions starting with 16678.

  (CMUCL only) Updated saved_acl2 for CMUCL to use maximum heap for CMU
  Common Lisp snapshot-2016-01 and beyond.  Thanks to Raymond Toy for
  updating CMUCL such that one can specify with [47m-dynamic-space-size 0[0m
  that the maximum heap is used.


EMACS Support

  We made several improvements in the [ACL2-doc] browser.

    * A bug has been fixed in the [47mS[0m command ([47macl2-doc-re-search[0m).

    * The help message is displayed more often (but only, we think, when
      appropriate) in the echo area (i.e., below the mode line).

    * The [47mq[0m command ([47macl2-doc-quit[0m) now can be run from any buffer in
      [47macl2-doc[0m mode, for example after typing the [47mH[0m command.
      Moreover, all such buffers will be buried after [47mq[0m; formerly, if
      you quit from the main [47macl2-doc[0m buffer you could have been left
      in the [47macl2-doc-history[0m buffer.

  [47m[Verify-termination][0m calls are now indented like [47m[defun][0m calls.
  Thanks to Alessandro Coglio for suggesting this change to
  [47memacs/emacs-acl2.el[0m.

  The [ACL2-doc] Emacs browser now allows handling of topics with
  square brackets.  This fix was necessary because a new topic,
  [47mSV::4VEC-[=[0m, broke acl2-doc; it wouldn't initialize.  The fix
  simply replaces characters [47m#\\[[0m and [47m#\\][0m with [47m#\\<[0m and [47m#\\>[0m,
  respectively.  It's not a perfect fix, but it seems awkward to try
  to escape [47m#\\[[0m (which Emacs Lisp thinks starts a vector).  See
  community book [47msystem/doc/render-doc-base.lisp[0m.


Experimental Versions

  Fixed some interleaved output that could appear with
  [waterfall-parallelism] enabled.  Thanks to Eric Smith for
  reporting this problem and to David Rager for a helpful chat.")
 (NOTE-7-3
  (RELEASE-NOTES)
  "ACL2 Version 7.3 (December, 2016) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 7.2 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  Changes to the
  [books] are no longer summarized in a documentation topic, but can
  be found by browsing the {ACL2+Books GitHub repository |
  https://github.com/acl2/acl2/}, in particular, the raw {commit log
  | https://github.com/acl2/acl2/commits/master}.


Changes to Existing Features

  The name of ACL2's interactive goal manager has been changed from
  ``proof-checker'' to ``(interactive) proof-builder''.  Thanks to
  several people in the ACL2 community for feedback leading to this
  more descriptive name.  In particular, we thank Stephen Westfold
  for noting that as a new user, references in the [documentation] to
  ``proof-checker'' didn't help him to realize that ACL2 has an
  interactive proof capability similar to what is found in some other
  interactive theorem provers.

  Now, [set-raw-warning-format] causes all warnings to be printed in a
  raw format, not merely those warnings for which custom
  raw-warning-format code has been developed.  Thanks to Shilpi Goel
  for recommending this enhancement.

  Utilities for formatted printing to strings no longer take an
  [47m:[0m[47m[iprint][0m keyword argument, and they never print using [iprinting].
  See [printing-to-strings].  The reason is that for each iprint
  index, [47mi[0m, that is bound during creation of the result string, that
  binding would disappear after the string is returned; so it would
  be misleading or an error to read [47m#@i#[0m after that return.  For a
  similar reason, when raw Lisp errors occur because variable
  [47m*hard-error-is-error*[0m is non-[47mnil[0m (see [hard-error]), iprinting is
  not used.

  Any [47m:[0m[47m[measure][0m supplied in an [47m[xargs][0m declaration of a [47m[defun][0m form
  must be a legal [term].  Formerly, this requirement only applied to
  [47m:[0m[47m[logic][0m mode definitions, but now it also applies to [47m:[0m[47m[program][0m
  mode definitions.  Thanks to Jared Davis for pointing out that this
  restriction wasn't applied to [47m:program[0m mode definitions.

  For a [47m[defun][0m form, it is now illegal by default for a non-recursive
  definition to have a [47m:[0m[47m[measure][0m in an [47m[xargs][0m declaration (other
  than [47m:measure nil[0m, which means ``no measure'') unless the
  definition is within a [47m[mutual-recursion][0m.  Thanks to Eric Smith
  for suggesting this restriction.  See [set-bogus-measure-ok] for a
  way to avoid this new default behavior.

  Several symbols have been added to the list [47m[*ACL2-exports*][0m.

  It is now legal to specify a [47m:clause-processor[0m hint using a symbol,
  regardless of the signature of the relevant clause-processor
  function.  A symbol had only been legal when that function took a
  single input.  Now, the function may also take a hint argument
  followed by zero or more [47mstobj[0m arguments, in which case the hint is
  implicitly [47mnil[0m and the stobjs are passed appropriately.  See
  [clause-processor].  Thanks to Eric Smith for requesting this
  enhancement.

  By default, the checksum values in [certificate] files for [books]
  have been replaced by a faster (though somewhat less secure)
  mechanism.  See [book-hash] for an explanation, including a way to
  restore the use of checksums.  (Our experiments in certifying all
  community [books] showed about a 7% reduction in total time.
  Speed-up for [47m[include-book][0m may be somewhat greater; for example,
  on a modern Macbook Pro the form

    (time$ (include-book \"centaur/vl/mlib/datatype-tools\" :dir :system))

  took 21.67 seconds after certifying books in a default manner, but
  only 15.80 seconds after certifying books using
  [47mACL2_BOOK_HASH_ALISTP=t[0m --- a 27% reduction.)  Thanks to Bob Boyer
  for emphasizing slowdown from checksum computation, to Jared Davis
  and Eric Smith for several helpful emails, and to the ACL2
  community in general for continuing to push for faster evaluation
  of [47m[include-book][0m calls.

  The utility [47m[show-accumulated-persistence][0m now prints results in base
  10 with radix [47mnil[0m (see [set-print-base] and [set-print-radix]).
  Thanks to Sol Swords for pointing out the odd printing that
  formerly could result when evaluating [47m(set-print-base-radix 16
  state)[0m before calling [47mshow-accumulated-persistence[0m.

  We have changed how ACL2 automatically computes [type-prescription]
  rules for [47m[defun][0m forms --- so-called ``runic type-prescriptions''
  --- in the following cases:

    * (1) when including a certified book; and

    * (2) in the second pass for a call of [47m[encapsulate][0m or [47m[certify-book][0m.

  For (1), ACL2 retrieves runic type-prescriptions from the book's
  [certificate].  For (2), ACL2 combines the runic type-prescription
  rule that is computed as usual with the rule previously computed in
  the first pass.  Because of (1), the runic type-prescription rule
  for a function symbol introduced by an included book is no longer
  sensitive to the current logical [world]; previously, for example,
  that rule could be different if one first includes other books.
  Also, some [47m[include-book][0m calls may complete more quickly because
  of (1); for example, we saw a reduction in time of 4.7% for
  [47m(include-book \"doc/top\" :dir :system)[0m.  Because of (2), runic
  type-prescriptions may be stronger than was previously the case.
  Thanks to Jared Davis for suggesting this enhancement and for
  helpful discussions during its development.  This change can be
  viewed as just one of the hundreds of heuristic components of ACL2
  that need not be understood in any detail by users; that said,
  those who are curious about implementation details are welcome to
  read the comment entitled ``Essay on Cert-data'' in the ACL2 source
  code.

  The utility [47m[save-exec][0m now causes an error if the directory of its
  first argument does not exist; for example, [47m(save-exec
  \"subdir/my-acl2\")[0m causes an error if there is no subdirectory
  [47m\"subdir\"[0m of the current directory.  Thanks to Jared Davis for
  pointing out that some Lisps (in particular, CCL) would create a
  missing directory in such a case, while others (in particular,
  SBCL) would not.

  Slightly improved the printing of terms (the so-called
  ``[untranslate]'' utility) to avoid producing terms of the form
  [47m(not (not u))[0m in some cases.  Thanks to Eric Smith for feedback
  leading to this change.

  The function being defined (or functions, plural, if using
  [47m[mutual-recursion][0m) may now be among the declared
  [ruler-extenders].  Thanks to Alessandro Coglio for an email that
  led us to make this change.

  The utility [47m:[0m[47m[pso][0m, along with other proof-replay utilities including
  [47m[psof][0m and [47m[psog][0m, now works with [47m[defthmd][0m and [47m[defund][0m.  More
  generally, saved proofs are only wiped out by newer proofs, not by
  other [events] such as [47m[in-theory][0m events.

  The [47m:exec[0m code in calls of [47m[mbe][0m no longer affects termination proofs
  or induction schemes produced for function definitions.  This had
  formerly only been the case for certain ``top-level'' calls in the
  if-then-else structure of the definition's body.

  The macro [47mlogicalp[0m is now deprecated, replaced by the function symbol
  [47mlogicp[0m.  (For efficiency, [47mlogicp[0m is inlined in raw Lisp; [47mlogicalp[0m
  is for now simply a macro abbreviating [47mlogicp[0m.)  Moreover, these
  utilities no longer call the function [47msymbol-class[0m.  (See
  [system-utilities] for discussion of such utilities.)  The latter
  change, which avoids consideration of the [47m'theorem[0m property of a
  symbol, can be helpful in proofs; indeed, this change simplifies
  reasoning about the new function [47mlogic-fnsp[0m (see the ``Bug Fixes''
  section below).

  Several improvements have been made for utilities that show guard
  proof obligations.

    * The low-level system utility [47m[guard-obligation][0m no longer returns
      [47m[state][0m.  Thanks to Alessandro Coglio for requesting this
      enhancement.

    * The utilities [47m[verify-guards-formula][0m and [47m[guard-obligation][0m take a
      new argument, [47mrrp[0m (``return redundant p'').  When this argument
      is [47mnil[0m, which is the default for [47mverify-guards-formula[0m, these
      utilities will avoid returning the symbol [47m'redundant[0m even in
      the case that the given function symbol is already
      guard-verified.  Thanks to Eric Smith for requesting this
      enhancement.

    * Documentation has been improved for utilities that show guard proof
      obligations, in particular with the addition of a new topic,
      [guard-formula-utilities], which explains their differences.

    * The utilities [47m[guard-theorem][0m and [47m[gthm][0m now do some simplification
      of the guard theorem by default.  See [guard-theorem] and
      [gthm].  Thanks to Alessandro Coglio and Eric Smith for useful
      discussions.

    * The utility [47m[gthm][0m has two improvements: it takes a second optional
      argument, [47mguard-debug[0m; and it returns a single value (an
      untranslated [term]), rather than an [error-triple] whose value
      component is that untranslated term.  The function
      [47m[guard-theorem][0m has been changed to support the new optional
      argument.

  Some recursive, [logic]-mode built-in functions did not have proper
  [measure]s stored in the ACL2 logical [world]: specifically, those
  whose suitability for logic mode is established in the community
  book [47mbooks/system/top.lisp[0m and the books included under that book.
  This has been fixed for all such functions except for the two
  ([47mmerge-sort-term-order[0m and [47mmerge-term-order[0m) whose measures use
  functions defined only in books, not in ACL2.  Thanks to Eric Smith
  for a request leading to this enhancement.  (If you are interested
  in implementation-level information about the mechanism tying books
  to verification of termination and guards for built-in functions,
  see comments in source-code constant [47m*system-verify-guards-alist*[0m.)

  The utilities [47m[print-gv][0m and [47m[set-print-gv-defaults][0m now accept a
  natural number for the keyword argument, [47m:substitute[0m, so that only
  certain large repeated terms cause the result to use [47m[flet][0m.  See
  [print-gv].  Thanks to Eric Smith for suggesting such a change and
  helping to design it.

  ACL2 formerly caused a raw Lisp error when attempting to define a
  function that was already defined in raw Lisp but not in ACL2.  Now
  an ordinary ACL2 error occurs instead.  Thanks to Eric Smith for a
  question leading to this change.

  Functions [47mall-ffn-symbs[0m and [47mall-ffn-symbs-lst[0m are now in
  [guard]-verified [47m:[0m[47m[logic][0m mode.  Thanks to Eric Smith for a helpful
  relevant conversation.  Several other functions are now in
  guard-verified [47m:logic[0m mode, thanks to discussions with Eric and
  also Alessandro Coglio, including [47mformalized-varlistp[0m, [47mlatest-body[0m,
  [47mlogical-namep[0m, [47mmacro-args[0m, [47mstobjs-out[0m, [47mtermify-clause-set[0m,
  [47mthrow-nonexec-error-p[0m, and [47mthrow-nonexec-error-p1[0m.  For a complete
  list, compare the old and new values of constant
  [47m*system-verify-guards-alist*[0m.

  It had been necessary to evaluate [47m(set-state-ok t)[0m in order to call
  [47m[verify-termination][0m on a [47m:[0m[47m[program][0m mode function that takes
  [47m[state][0m as a formal parameter but does not declare [47mstate[0m explicitly
  as a [stobj].  Thanks to Eric Smith for pointing out this issue.
  Here is an example that had failed but now succeeds.

    (set-state-ok t)
    (defun foo (state) (declare (xargs :mode :program)) state)
    (set-state-ok nil)
    (verify-termination foo) ; formerly failed

  To evaluate a form [47m(set-iprint t :hard-bound N)[0m, ACL2 will first
  replace [47mt[0m by [47m:reset-enable[0m.  This behavior has been expanded to
  apply to [47m(set-iprint nil :hard-bound N)[0m and [47m(set-iprint :same
  :hard-bound N)[0m as well: the first argument will be converted to
  [47m:reset[0m or [47m:reset-enable[0m.  See [set-iprint].  This change fixes a
  bug in the interaction between hard-bounds and rollovers.  For an
  example that formerly exhibited this bug, see a comment about
  ``hard-bounds and rollovers'' in [47m(defxdoc note-7-3 ...)[0m in
  community book [47mbooks/system/doc/acl2-doc.lisp[0m.

  The following improvements have been made to [47m[defun-sk][0m.  See
  [defun-sk] for detailed documentation.

    * [47mDefun-sk[0m now modifies the [pe-table], with the effect that if you
      introduce a function [47mNAME[0m with [47mdefun-sk[0m, then subsequent
      evaluation of [47m:pe NAME[0m will show the [47mdefun-sk[0m form rather than
      the underlying [47mdefun[0m form.  As usual, you can invoke [47m:[0m[47m[pe!][0m
      instead, in order to see that [47mdefun[0m form.

    * When [47mdefun-sk[0m was supplied with keyword argument [47m:strengthen t[0m, the
      name of the generated theorem was always in the [47m\"ACL2\"[0m package.
      Now it is in the same package as the function symbol being
      defined.  Thanks to Alessandro Coglio for suggesting this
      change.

    * [47mDefun-sk[0m now accepts [47m[declare][0m forms immediately after the formal
      parameters, as is the case for [47m[defun][0m.  Thanks to Eric Smith
      for suggesting this enhancement.  The [47m:witness-dcls[0m keyword is
      still supported as well, but may become deprecated in the
      future.

    * An issue involving [guard] verification for [47mdefun-sk[0m forms has been
      addressed.  Thanks to Alessandro Coglio for suggesting this
      improvement.

    * Syntax checking now produces improved error messages for [47mdefun-sk[0m.

  The error message for a call of a undefined symbol now mentions
  defined symbols in other packages with the same name, in case that
  is what the user intended.  The message also points to a new
  documentation topic, [near-misses], which provides a way (using
  certain books) to find approximate matches that are defined.
  Thanks to Jared Davis for suggesting such a change.

  ACL2 now accepts [47m#\\Return[0m as legal notation for the character with
  [47m[char-code][0m 13, and it prints that character as [47m#\\Return[0m rather
  than moving the cursor (e.g., to the beginning of the line).
  Thanks to Alessandro Coglio, Eric McCarthy, and Eric Smith for
  requesting this change, to help with the printing of failed
  subgoals that mention this character.

  The macro [47m[good-bye][0m no longer requires its argument to be a
  (natural) number.  Any argument is now valid, and as before, is
  evaluated; if that argument is not an integer, it is treated as 0.
  The same change applies to the aliases for [47m[good-bye][0m, namely
  [47m[exit][0m and [47m[quit][0m.  Thanks to Eric Smith for suggesting this
  change.

  When some subgoal in a set of key checkpoints is [47mNIL[0m, then such a
  subgoal will be printed first in the corresponding list, provided
  of course that the list isn't entirely ignored because of a
  checkpoint-summary-limit of 0.  See [nil-goal], which has been
  updated.  Thanks to Eric Smith for suggesting that [47mNIL[0m subgoals
  should be seen in the checkpoints in spite of the
  checkpoint-summary-limit (see [SET-CHECKPOINT-SUMMARY-LIMIT]).

  A new keyword argument, [47m:ctx[0m, is available for [47mvalue-triple[0m.  See
  [value-triple].

  [Definition] rules with non-[47mnil[0m values of [47m:install-body[0m (the default)
  are now permitted to have equivalence relations other than [47m[equal][0m.

  For macros such as [47m[prog2$][0m that invoke [47m[return-last][0m, an argument to
  be evaluated with attachments (see [defattach]) was failing to use
  attachments in some cases involving non-guard-verified functions.
  This has been fixed.  For an example, see the relevant comment in
  the form [47m(defxdoc note-7-3 ...)[0m in community book
  [47mbooks/system/doc/acl2-doc.lisp[0m.

  The [47m:[0m[47m[termination-theorem][0m [lemma-instance] has been improved so that
  old function symbols may be replaced with corresponding new
  function symbols, either automatically or explicitly by the user.
  See [lemma-instance] and see [termination-theorem-example].  Thanks
  for Alessandro Coglio and Eric Smith for helpful discussions,
  including pointing out the previous deficiency.

  A new key, [47m:user[0m, is now legal for the [47m[ACL2-defaults-table][0m.  Its
  value must be an association list.  The key is reserved for users,
  who may assume that the ACL2 system does not give it any special
  handling; see [ACL2-defaults-table].  Thanks to Eric Smith for a
  helpful discussion leading to this change.

  A new macro, [47m(with-guard-checking-event x form)[0m, is now legal for
  event contexts; see [embedded-event-form].  Thanks to Eric Smith
  for helpful discussions leading to this change.

  For many years, it has been the case that when a [constraint] is
  proved that arises from a [47m:functional-instance[0m lemma instance (see
  [lemma-instance]), that information is stored so that the same
  constraint is not re-proved on behalf of a later such lemma
  instance.  However, this had not been the case when the original
  lemma instance was inside an [47m[encapsulate][0m event.  Now, that
  information is stored provided the [47mencapsulate[0m event has an empty
  [signature] list and is not ``empty'' (that is, stores at least one
  event).  Thanks to Eric Smith for sending us an example to point
  out this problem.

  The [proof-builder]'s [47mbash[0m and [47mreduce[0m commands no longer fail when
  the [47m:hints[0m for [47m\"Goal\"[0m include [47m:do-not-induct t[0m.  Thus, it is no
  longer necessary to edit out such [47m:do-not-induct[0m [hints] when
  editing a proof-builder command by copying hints from an event
  being developed.

  By default, the [proof-builder] command [47m:s[0m now uses contextual
  information when doing linear arithmetic.  The new keyword argument
  [47m:linear[0m can be set to [47mnil[0m to get the previous behavior.  See
  [ACL2-pc::s].  Thanks to Eric Smith for requests that led us to
  make this change.

  Warning and error messages produced upon [47m[theory-invariant][0m
  violations now include additional explanation.  Thanks to David
  Hardin and Grant Passmore for helpful remarks leading us to make
  this change.  Those messages also now show where the theory
  invariant was defined: a book pathname, or ``top-level'' if
  directly in the loop.

  The summary of ``Key checkpoint'' goals, at the end of a failed proof
  attempt, has been improved.  It now indicates, inside the ``***''
  banners, every case in which proof has been aborted due to a
  [47m:DO-NOT-INDUCT[0m hint or generation of a goal of [47mNIL[0m.

  The [proof-builder] command, [47mnoise[0m, no longer prints [proof-tree]
  information, which can be obtained with the new command, [47mnoise![0m.
  The [47mquiet[0m command is unchanged, but a [47mquiet![0m command turns off the
  printing of goal identifiers (as with [47m[set-print-clause-ids][0m).

  When [47m[defund][0m and [47m[defthmd][0m [events] fail, their output no longer
  concludes with distracting output that mentions [47m[with-output][0m.


New Features

  New optional arguments allow the [47m[pso][0m utility to restrict output to
  a single goal or a segment of the output (say, between two
  specified goals); similarly for related utilities [47m[pso!][0m, [47m[psof][0m,
  and [47m[psog][0m.  Thanks to David Rager for a recent query leading to
  this enhancement.

  The function [47m[cons-with-hint][0m provides an alternative to [cons] that
  can sometimes avoid consing.  Thanks to Jared Davis and Sol Swords
  for suggesting this function and providing an implementation and
  documentation.  A few ACL2 source functions now call
  [47mcons-with-hint[0m.

  Function [47m[file-length$][0m computes efficiently the number of bytes in a
  specified file.

  Function [47m[delete-file$][0m deletes a given file.  Thanks to Eric Smith
  for requesting this utility.

  New macros [47m[active-or-non-runep][0m and [47m[incompatible!][0m are similar to
  [47m[active-runep][0m and [47m[incompatible][0m (respectively), except that the
  new macros essentially consider non-[rune]s to be enabled.  Thanks
  to Eric Smith for feedback leading to these additions.

  It is now possible to [47m[declare][0m formal parameters of [47m[defun][0m events
  to be irrelevant.  See [irrelevant-formals].  Thanks to Eric Smith
  for requesting this feature.

  The [47m[deftheory][0m event now accepts a new keyword, [47m:redundant-okp[0m, to
  allow a limited form of redundancy (see [redundant-events]).
  Thanks to Eric Smith for requesting such support.  A new macro,
  [47m[defthy][0m, abbreviates [47mdeftheory[0m calls by adding [47m:redundant-okp t[0m.

  The [47m[fmt][0m family of functions has a new tilde directive, [47m~S[0m, which
  behaves like [47m~s[0m except that margins are ignored.  Thanks to Jared
  Davis for requesting this feature.

  The iprinting utility has a new keyword option, [47m:share[0m, which causes
  iprint indices to be re-used (using so-called ``iprint sharing''
  and ``iprint eager sharing'').  See [set-iprint].  Thanks to David
  Rager for suggesting a notion of iprint sharing.

  A new function, [47m[set-serialize-character-system][0m, can be used to turn
  off (or on) the [serialize-write] capability, which is on by
  default, for writing certain files during book certification,
  including [certificate] files.  This capability has been useful for
  working around issues with 32-bit CCL; thanks to Waqar Ahmed for
  working through that issue with us.

  ACL2 now supports the reading of rational numbers expressed in
  floating-point (scientific notation) syntax, using prefixes [47m\"#f\"[0m
  and [47m\"#fx\"[0m for base 10 and base 16, respectively.  See
  [sharp-f-reader].  Thanks to Dmitry Nadezhin for suggesting this
  enhancement.


Heuristic and Efficiency Improvements

  The raw-Lisp definition of [47m[defpkg][0m has been modified in a way that
  may improve performance for some host Lisps.  Thanks to Bob Boyer
  for emails pointing to the (surprising) use of compilation by
  [47m[include-book][0m in CCL, which is eliminated (at least in some cases)
  by this change.

  [Type-set] reasoning has been improved in several basic ways.

    * The first, for which we thank Jared Davis and Sol Swords for
      providing an example, is illustrated in a comment in the form
      [47m(defxdoc note-7-3 ...)[0m in Community Books file
      [47msystem/doc/acl2-doc.lisp[0m)

    * When [definition] bodies and [guard]s are simplified, as they are by
      default --- see the new documentation for [normalize] ---
      [type-set] reasoning is now subjected to a [backchain-limit] of
      1 (unless it is already 0 globally).  Thanks to Jared Davis for
      sending an example, for which [47m[include-book][0m time has been cut
      to less than 10% of what it had been, without changing the
      results of [normalization].  (That said, regression timings
      suggest that this change will not be noticed for most books.)

    * The collection of primitive [type-set]s supported by ACL2 has been
      changed, by splitting the type of positive integers into two
      sets: the set consisting solely of the number 1, and the set of
      integers greater than 1.  Thanks to Jared Davis for suggesting
      this change, and to him and Sol Swords for pointing out
      deficiencies in our initial implementation.  For a discussion
      of changes made to community books to accommodate this change,
      see the comment immediately above the form [47m(defxdoc note-7-3
      ...)[0m in community book [47mbooks/system/doc/acl2-doc.lisp[0m.  Note
      that ACL2 has a newly-added function, [47m[bitp][0m, whose built-in
      [compound-recognizer] rule specifies that the value recognized
      by [47mbitp[0m is either [47m0[0m or [47m1[0m, that is, a member of the union of the
      primitive types [47m{0}[0m and [47m{1}[0m.
        [31;1mTheorem: [0m<bitp-compound-recognizer>

          (defthm bitp-compound-recognizer
            (equal (bitp x)
                   (or (equal x 0) (equal x 1)))
            :rule-classes :compound-recognizer)

      ACL2 can reason a bit more powerfully about existing functions in
      some cases.  For example, it now proves the following theorem
      without including any books, which was not the case previously.

          (thm (implies (and (rationalp x) (not (integerp x)))
                        (< 1 (denominator x))))

      You may need to change some of your books, however.  For example, if
      you want to [disable] a function that always returns 1, then as
      was previously the case for such functions that always return 0
      instead (or t, or nil), you'll want to disable the
      [type-prescription] rule for that function, too.

    * When a term of the form [47m(integerp (+ k term))[0m is assumed true or
      false, for an integer constant [47mk[0m, ACL2 now essentially attempts
      to add suitable type information for [47mterm[0m rather than for [47m(+ k
      term)[0m.  (Source function [47mstrengthen-recog-call[0m shows precisely
      what is done.)  We also made analogous improvements for terms
      of the form [47m(rationalp (+ k term))[0m and [47m(rationalp (* k term))[0m.
      Example theorem now provable that was not provable previously:

          (thm (implies (and (zp k) ; either k <= 0 or k is not an integer
                             (integerp (+ 1 k))
                             (< 0 (+ 1 k))
                             (acl2-numberp k))
                        (equal 2 (+ 2 (* 2 k)))))

  We eliminated a rather technical check during book certification.  (A
  bit of technical detail: we check for hidden packages in
  [47m[make-event][0m expansions, and an optimization eliminated that check
  for events in the book occurring before the first such event that
  introduced a new package, if any.  But if no events in the book
  introduced a new package, then we were checking all such
  expansions; now, we check none of them.)

  Calls of the utility [47m[clear-memoize-table][0m formerly discarded
  relevant hash tables, building new ones when necessary.  Now, the
  hash tables are typically retained but cleared (using Common Lisp
  function [47mclrhash[0m), although heuristics may determine that tables
  are ``too large'', in which case the former discarding behavior
  applies.  Thanks to Jared Davis and Sol Swords for contributing
  this change, which they found to speed up certain computations
  significantly.  We expect that it will likely not slow others down
  significantly.  Note that (as they have pointed out) the behavior
  of related utility [47m[clear-memoize-tables][0m remains unchanged; it
  continues to discard relevant hash tables.

  The generation of raw Lisp definitions of [stobj] creator functions
  have been made potentially more efficient for stobjs with many
  fields.  Thanks to Sol Swords and Jared Davis for reporting this
  issue and suggesting a fix, which we adopted (in source function
  [47mdefstobj-raw-init[0m) with some small changes.

  We now avoid certain inefficiencies with [47m[mbe][0m.  The definition of [47mf8[0m
  below has taken 83.63 seconds in Version 7.2 built on CCL as the
  host Lisp, but with that same machine and host Lisp the time was
  merely 0.11 second after this change.  (Technical note: the
  explosion was in the time required to compile the so-called ``*1*
  function''.)

    (defmacro id (x) `(mbe :logic (identity ,x) :exec (identity ,x)))
    (defun f8 (x) (id (id (id (id (id (id (id (id x)))))))))

  The heuristics for the ``eliminate-irrelevance'' clause processor
  (see [hints]) no longer drop applications of zero-ary functions or
  their negations, e.g., [47m(P)[0m or [47m(NOT P)[0m.  Thanks to Marijn Heule for
  feedback that led us towards modifying our initial change (twice!).

  Several low-level efficiency improvements, which can speed up
  [read-object], may also speed up some other operations.

    * Finding a package from a string can be faster (low-level raw Lisp
      function [47mfind-package-fast[0m).

    * The implementation of low-level raw Lisp function [47mbad-lisp-objectp[0m
      was tweaked to use type recognizers, which are faster in some
      Lisps than corresponding recognizer predicates; for example,
      the test [47m(consp x)[0m has been replaced by the test [47m(typep x
      'cons)[0m.

    * New raw Lisp function [47mbad-lisp-consp[0m processes conses on behalf of
      [47mbad-lisp-objectp[0m, and now [47mbad-lisp-consp[0m is memoized at startup
      instead of [47mbad-lisp-objectp[0m.  Note that we continue to use
      memoization option [47m:forget t[0m, which throws away memoization
      information when exiting the top-level call of the function.
      With this change, we avoid the overhead of memoization when
      checking non-cons values, which was perhaps of limited value
      anyhow.  There could be slowdown when large EQ strings occur
      repeatedly inside a cons pair, but we expect such slowdown to
      be at most negligible in practice.

    * New utility [47m[set-bad-lisp-consp-memoize][0m can turn off memoization of
      the new raw Lisp function [47mbad-lisp-consp[0m.


Bug Fixes

  A soundness bug exploited the possibility that pathnames contain
  illegal ACL2 characters.  Consider the following bash shell
  commands, which create a file whose name is the euro sign and
  create a soft link, [47m\"foo\"[0m, to that file.  Thanks to Eric McCarthy
  for helpful discussions showing us how to create such a file, which
  ultimately led us to discover this bug.

    mkdir $'\\xe2\\x82\\xac'
    ln -s $'\\xe2\\x82\\xac' foo

  Then the following book certified on a Mac, but now one gets an error
  message complaining about a character with code 8364.

    (in-package \"ACL2\")
    (make-event
     `(defconst *c* ,(char (canonical-pathname \"foo\" t state) 44)))
    (defthm bad
      nil
      :rule-classes nil
      :hints ((\"Goal\"
               :in-theory (theory 'minimal-theory)
               :use ((:instance char-code-linear (x *c*))))))

  The utility [47m[getenv$][0m now causes an error if the value it would
  otherwise return is not an ACL2 string, for example because it
  contains a character whose [47m[char-code][0m exceeds 255.  Many other
  changes, less visible to the user, have been made in how ACL2 deals
  with strings that come from outside ACL2, in particular, file names
  (see the related item just above).

  The handling of [meta]functions allowed an invariant to be violated,
  that conjectures in the prover are always 100% [logic] mode.  An
  example is in a comment in the ACL2 source code under [47m(deflabel
  note-7-3 ...)[0m.  We have not exploited this bug to show that it
  leads to unsoundness, but that seems possible.  Our fix is to
  extend the checks that all applications of metafunctions and
  [clause-processor]s produce [term]s, to check additionally that
  those terms are all in logic mode.  An analogous change applies to
  [well-formedness-guarantee]s, using new functions [47m[logic-termp][0m,
  [47m[logic-term-listp][0m, and [47m[logic-term-list-listp][0m, where [47mlogic-termp[0m
  checks not only [47m[termp][0m but also the new predicate [47mlogic-fnsp[0m, and
  similarly for the others ([47mlogic-term-listp[0m calls [47mlogic-fns-listp[0m
  and [47mlogic-term-list-listp[0m calls [47mlogic-fns-list-listp[0m).

  A bug has been fixed that could cause hard Lisp error when using the
  [iprint] utility.  Specifically, calling [47m[set-iprint][0m with a small
  [47m:hard-bound[0m could cause a hard Lisp error during ``rollover'', as
  with the following example.

    (set-iprint :reset-enable :hard-bound 200)
    (set-iprint t :hard-bound 1000)
    (f-get-global 'iprint-ar state)
    (set-evisc-tuple (evisc-tuple 3 4 nil nil) :iprint t :sites :all)
    (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)))
    (pso)
    (pso)
    (pso)

  Thanks to David Rager for bringing this bug to our attention and for
  describing how it occurred in his environment.  The fix is to
  convert the argument [47mt[0m of [47m[set-iprint][0m to [47m:reset-enable[0m when
  keyword argument [47m:hard-bound[0m is supplied.

  The keyword [47m:computed-hints-replacement[0m appeared in the source code a
  few times where [47m:computed-hint-replacement[0m was intended.  This has
  been fixed.  We are not aware of any examples in practice where
  this makes a noticeable difference; in particular, no
  [community-books] were modified to accommodate this fix.

  Redefinition can support certain uses of [47m[make-event][0m within
  [47m[encapsulate][0m forms, where formerly an error occurred.  (Technical
  note: Small examples appear as comments in source function
  [47mchk-embedded-event-form[0m; search there for ``redefinition''.)
  Thanks to Jared Davis for sending us an example that exhibited this
  problem.  Strictly speaking, we don't really view this as a bug; we
  have clarified in the documentation for [ld-redefinition-action]
  that redefinition may behave in unexpected ways.

  We now avoid creating directories when reading rather than writing:

    * It is no longer the case that [47m[include-book][0m creates a directory when
      attempting to include a book in a non-existent directory.
      Thanks to Jared Davis for bringing this bug to our attention.

    * In Version 7.2, we arranged that [47mopen-output-channel[0m and
      [47mopen-output-channel![0m attempt to create directories as needed.
      Unfortunately, that change also caused this behavior for
      [47mopen-input-channel[0m.  That has been fixed.  Thanks to Sol Swords
      for pointing out that certifying books in CCL using [47mcert.pl[0m
      could cause creation of directories when including books; with
      this fix, that is no longer the case.

  When submitting a call of [47m[define-trusted-clause-processor][0m with an
  unsuitable signature, the resulting error message was causing a raw
  Lisp error.  This has been fixed.  Thanks to Eric Smith for
  reporting this bug.

  Contrary to its documentation, a [47m[define-trusted-clause-processor][0m
  event was never redundant in the case that the values for keyword
  arguments [47m:label[0m and [47m:partial-theory[0m were both [47mnil[0m (or omitted).
  Thanks to Eric Smith for pointing out this bug.  Now, redundancy of
  the resulting [47m[encapsulate][0m event succeeds because a subsidiary
  [47m[deflabel][0m event is generated by default.  (The previous behavior
  can be obtained by explicitly supplying the keyword argument [47m:label
  nil[0m.)  Also, the obsolete keyword argument, [47m:doc[0m, has been deleted
  for [47mdefine-trusted-clause-processor[0m.

  It had been possible to get a [slow-array-warning] from computed
  hints (see [computed-hints]) that directly modify so-called enabled
  structures.  This has been fixed by providing a suitable way for
  users to call system function [47mload-hint-settings-into-rcnst[0m, as is
  done in the [community-books] utility [easy-simplify-term], which
  calls a function [47measy-simplify-term1-fn[0m that updates an enabled
  structure.  Thanks to Jared Davis for sending an example that
  exhibited this problem through the computed hint
  [47m[logbitp-reasoning][0m.  Also thanks to Sol Swords for a helpful
  discussion that brought our attention to the community book
  mentioned above.

  Avoided an assertion [47m(ASSERT$ ACTUAL-ELEMENT ...)[0m that could occur
  when including uncertified books, in particular when an included
  sub-book was originally certified in a different directory from
  where it now resides.  Thanks to Eric Smith for reporting this bug
  and sending a helpful example.

  Fixed function [47mget-skipped-proofs-p[0m so that it returns [47mnil[0m on
  built-in functions.  Thanks to Eric Smith for bringing up this
  issue, for example by pointing out that [47m(get-skipped-proofs-p 'len
  (w state))[0m evaluated to [47mt[0m; now, it evaluates to [47mnil[0m.

  The utility [47m[unmonitor][0m was failing to carry out its task when
  applied to a [rune].  This was due to a bug in ACL2 source function
  [47mdelete-assoc-equal-lst[0m, which has been fixed.

  The utility [47m:[0m[47m[psof][0m now prints the [47mRules[0m, [47mHint-events[0m, and [47mSplitter
  rules[0m fields to the specified file instead of the terminal.  It
  also prints the interactive [proof-builder] prompt to that file
  instead of the terminal.

  On rare occasions it seems that after book certification, the
  compiled file was older than the corresponding [47m.cert[0m file, which
  prevented subsequent [47m[include-book][0m forms from loading that
  compiled file.  (Technical note: The problem was that we
  erroneously relied on Lisp function [47mrename-file[0m to preserve
  write-dates.)  This has been fixed.  Thanks to Gary Byers for
  confirming that Lisp does not guarantee that [47mrename-file[0m preserves
  write-dates, and to Camm Maguire for reporting a related failure.

  We fixed the [47m:[0m[47m[puff][0m command so that it will no longer fail on
  [47m[include-book][0m commands followed by later [47minclude-book[0m events.
  Thanks to Eric Smith for reporting the problem via a helpful
  example.

  Some symbols were printed in a way that could not be read back in,
  but are now printed with surrounding [47m|...|[0m.  Thanks to Sol Swords
  for reporting this problem for symbols with the Tab character.  Now
  that we are more careful to print symbols readably in every host
  Lisp, but in a consistent manner for all host Lisps, you may find
  more symbols printed with surrounding [47m|...|[0m than is necessary for
  your host Lisp.

  It was possible to corrupt the system by evaluating ill-[guard]ed
  arguments on [program]-mode functions with raw Lisp code when
  guard-checking is off.  For example, after evaluating the forms
  [47m(set-guard-checking nil)[0m and [47m(verbose-pstack 23)[0m, the form [47m(thm
  (equal x x))[0m caused a raw Lisp error.  Now, the ill-guarded call
  above of [47m[verbose-pstack][0m causes a guard violation, even with
  guard-checking off.

  In host Lisps that do not compile on-the fly --- that is, in host
  Lisps other than CCL and SBCL --- an error occurred when trying to
  evaluate certain calls of [47m[comp][0m, including [47m(comp t)[0m during
  [47m[make-event][0m expansion.  This has been fixed; here is an example
  that can be evaluated successfully now but not formerly.

    (make-event (er-progn (comp t)
                          (value '(value-triple nil))))

  ACL2 now avoids some needless escaping of symbol names with vertical
  bars, as in the case of [47mcar[0m in base 16, among others supplied by
  Eric Smith, whom we thank for the bug report:

    ACL2 !>(set-print-base-radix 16 state)
    <state>
    ACL2 !>'car
    |CAR|
    ACL2 !>

  Vertical bars are used for symbols whose names are so-called
  ``potential numbers'', which Common Lisp defines using several
  criteria.  Consecutive letters disqualify a token from being a
  potential number, and ACL2's mistake was in failing to treat
  characters [47m#\\A[0m through [47m#\\F[0m as letters.

  We fixed a bug in the interaction between iprinting and brr.  For an
  example, see the comment about ``interaction between iprinting and
  brr'' in the form [47m(defxdoc note-7-3 ...)[0m in community book
  [47mbooks/system/doc/acl2-doc.lisp[0m.  Thanks to Shilpi Goel for pointing
  out a somewhat related problem introduced by a change originally
  made after Version_7.2, which also has been fixed.

  The documentation for [47m[ld][0m specified that ``If [47m[standard-co][0m and
  [47m[proofs-co][0m are equal strings, only one channel to that file is
  opened and is used for both.'' This was only the case when
  [47mproofs-co[0m was a canonical absolute (full) pathname.  This has been
  fixed; now, the criterion is that [47mstandard-co[0m and [47mproofs-co[0m are
  strings that represent the same file.

  It is no longer illegal for [47m[defstub][0m to use an old style output
  signature with variables that are not among the formals.  For
  example, the following is now legal (note that [47mu[0m is not among the
  list [47m(x y)[0m of formal parameters): [47m(defstub foo (x y) (mv u x))[0m.
  Thanks to Eric Smith for pointing out that this behavior is allowed
  by the documentation (specifically, see the discussion of ``Old
  Style'' in the documentation for [signature]).

  We fixed a bug in the implementation of [47m[defattach][0m, which could
  cause the wrong constraints to be generated in the case of more
  than one function argument.

  For a proposed [definition] rule with a missing (or empty) [47m:CLIQUE[0m
  but a non-empty [47m:CONTROLLER-ALIST[0m, the error message was
  ill-formed.  This has been fixed.

  Calls of the macro [47m[add-custom-keyword-hint][0m are no longer illegal
  [events] in the context of [47m[local][0m.

  Tweaked [47m[break-on-error][0m to avoid rare error involving [47mSTATE[0m.


Changes at the System Level

  It was possible for a backtrace to be printed to the terminal by SBCL
  and CMUCL, even when output is redirected to a file.  This has been
  fixed.  Moreover, we now print, just above a backtrace (with ACL2
  function [47mprint-call-history[0m), the full pathname of the book under
  certification, in case this problem arises again.  Also, limited
  the number of frames in CMUCL to the default in SBCL, namely, 1000.

  When building the executable with `[47mmake[0m', ACL2 now prints a message
  of the form ``[47mSuccessfully built <ACL2_executable_pathname>[0m'' as
  the last line of the log.  Thanks to Eric Smith for suggesting this
  change.  Note that the exit status continues to be 0 upon success
  and non-zero upon failure.

  An error now occurs when attempting to build ACL2 or certify the
  [community-books] (in the usual way, using [47mmake[0m) in a directory
  whose name contains at least one space.  Thanks to Eric Smith for
  discussion leading to this change.  Although the issue may only be
  with the infrastructure for certifying community books, we cause an
  error for the ACL2 build as well, to make installers aware of the
  problem with spaces as soon as possible; thus, we added this check
  in both the top-level [47mGNUmakefile[0m and in [47mbooks/GNUmakefile[0m.  Note
  that the installation instructions (file
  [47minstallation/installation.html[0m) already said to install ACL2 ``in a
  directory whose pathname does not contain whitespace''; now, this
  requirement is enforced.  (If some in the community would like to
  update the infrastructure for certifying books to support spaces in
  the build directory, they are welcome to do so and then remove the
  check for spaces in [47mbooks/GNUmakefile[0m, at which time we would be
  happy to remove corresponding code in the top-level [47mGNUmakefile[0m as
  well.)

  The [47mrdtsc[0m feature is now used in function [memoization] not only for
  host Lisp CCL but also for SBCL.  Thanks to Bob Boyer for
  suggesting this change and providing helpful code.

  With a trust tag, it is now possible to apply [47m[verify-termination][0m to
  functions with under-the-hood raw Lisp code.  See
  [verify-termination-on-raw-program-okp].

  An argument has been added to the built-in function, [47mrecursivep[0m.  The
  old call [47m(recursivep fn wrld)[0m has been replaced by the equivalent
  new call [47m(recursivep fn t wrld)[0m in some community books.  See
  [system-utilities] for a discussion of [47mrecursivep[0m.  Thanks to
  Alessandro Coglio for suggesting this change.

  There is now some documentation on ACL2 system development [formerly
  in the topic, system-development, and its subtopics; now expanded
  into the Developer's Guide (see [DEVELOPERS-GUIDE])].  These
  replace the pages under web directory
  [47mhttp://www.cs.utexas.edu/users/moore/acl2/open-architecture/[0m.
  Thanks to Eric Smith for encouraging us to move that documentation
  to XDOC.

  The Common Lisp variable [47m*debug-io*[0m is now used in printing
  backtraces, but also is bound to [47m*standard-output*[0m when entering
  the ACL2 read-eval-print loop, which is done at start-up (see
  [lp]).  These changes avoid unfortunate printing of backtraces when
  certifying certain books that mess with [47m*debug-io*[0m using trust tags
  (see [DEFTTAG]), such as community book (see [COMMUNITY-BOOKS]).
  [47mbooks/centaur/vl2014/server/server.lisp[0m.  Thanks to Jared Davis for
  a tip that helped us to debug that issue (ACL2 GitHub Issue #634).

  We improved ACL2's implementation of the [47m#.[0m read macro so that it no
  longer prints additional errors after the first.  Also, the error
  message now mentions :DOC [sharp-dot-reader], pointing in
  particular to a relevant remark when the failure occurs during book
  certification.

  (SBCL only) Increased the value of [47m--dynamic-space-size[0m written to
  the executable scripts to 24000, from 16000, in support of building
  the manual.


EMACS Support

  The text-based display of [documentation] has been improved, that is,
  for output from [47m:[0m[47m[doc][0m at the terminal and also for the [47m[ACL2-doc][0m
  Emacs browser.

    * Links are inserted much more reliably.  That is, the surrounding of
      text by square brackets for text-based display now virtually
      always creates links that can be followed to topics in the
      [ACL2-doc] browser.  In particular, that browser now handles
      names properly that contain the [47m:[0m character.

    * Text in square brackets, for example [1], is no longer recognized as
      a link (though Emacs still highlights it).  Thanks to Mihir
      Mehta for pointing out this issue.

    * Automatic insertion of links for expressions [47m@('(name ...)')[0m, as
      [47m@('([name] ...)')[0m, should not happen for text-based display.
      This was however done when generating short strings for
      subtopics in [ACL2-doc]; that no longer happens.

    * The [47msee?[0m directive (see [xdoc::preprocessor]) now inserts links; it
      did not do so before (for text-based display).

    * Certain ``raw'' topics, such as DEFXDOC-RAW, are now included that
      formerly were only included in the web-based manual.

    * Text within ``[47m<stv> ... </stv>[0m'' is now replaced by the text ``[47m{STV
      display}[0m''.  A general mechanism is in place for extending this
      behavior to other tags (see [47mxdoc-tag-elide-alist[0m [after Version
      8.5, [47mxdoc-tag-alist[0m]) in [community-books] file
      'books/xdoc/display.lisp').

    * In the [ACL2-doc] browser, when the ``i'' ([47macl2-doc-index[0m) command is
      invoked without a prefix argument, the mode line shows the
      number of matches.  (The remaining matches continue to be
      accessible using the ``,'' [47m(acl2-doc-index-next)[0m command.)

  Incorporated changes to [47memacs/emacs-acl2.el[0m put forward by Keshav
  Kini (thanks!), as follows.

    * Now, [47mmeta-x new-shell[0m avoids buffer names that already exist.

    * An error occurs when attempting to switch to a non-existent ACL2
      shell buffer, rather than creating such a buffer with no
      process.

    * For a new shell, call [47mshell[0m instead of [47mmake-comint[0m.

    * Did a bit of refactoring and improved some error messages.


Experimental Versions

  As before, [brr] does not work in ACL2(p) with
  [waterfall-parallelism] enabled; see
  [unsupported-waterfall-parallelism-features].  But now it is an
  error to try to enable both brr and waterfall-parallelism.  Thanks
  to David Rager for helpful discussions pertaining to this change.")
 (NOTE-7-4
  (RELEASE-NOTES)
  "ACL2 Version 7.4 (March, 2017) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 7.3 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  Changes to the
  [books] can be found by browsing the {ACL2+Books GitHub repository
  | https://github.com/acl2/acl2/}, in particular, the raw {commit
  log | https://github.com/acl2/acl2/commits/master}.  Also note that
  with each release, some built-in functions that were formerly in
  [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode functions.


Changes to Existing Features

  The utility [47m[read-file-into-string][0m is now a macro, not a function.
  It no longer takes [47mstate[0m as an argument (though its expansion reads
  the state), and it has new keyword arguments that allow one to read
  successive segments of the file.  See [read-file-into-string].

  The test has been slightly relaxed for determining whether any
  supporting events are missing for [47m[defabsstobj][0m.  Thanks to Sol
  Swords for sending an example to illustrate the issue, together
  with analysis of the problem.


New Features


Heuristic and Efficiency Improvements

  We now avoid the [invariant-risk] slowdown in the case of a [47m:[0m[47m[logic][0m
  mode function with guard [47mt[0m.  For relevant examples see
  [program-wrapper].

  A technical change in the handling of [type-set] computations can, in
  rare cases, result in better built-in [type-prescription] rules for
  functions.


Bug Fixes

  Fixed a soundness bug, introduced about 10 years ago, that could
  occur with [47m:use[0m or [47m:by[0m [lemma-instance]s when a variable occurs
  free in a lambda of a functional substitution.  For an explanation
  see a comment in [47m(defxdoc note-7-4 ...)[0m in community book
  [47mbooks/system/doc/acl2-doc.lisp[0m; also, a proof of [47mnil[0m (in Version
  7.3) that exploits this bug can be found in a comment in the
  definition of function [47mremove-capture-in-constraint-lst[0m in the ACL2
  source code.  This may be the first time that a proved ``theorem''
  in the [community-books] has been discovered to be a non-theorem
  ([47mtr-to-array-of-array-to-tr[0m in
  [47mbooks/projects/legacy-defrstobj/typed-records.lisp[0m).  Thanks to Sol
  Swords for pointing out that this directory of books isn't used
  elsewhere; we temporarily excluded it from the regression by adding
  a [47mcert_pl_exclude[0m file, until Sol Swords repaired the proof a
  couple of days later.  Also thanks to Ruben Gamboa for fixing
  proofs in the [47mnonstd/[0m books that failed after the bug fix.

  Fixed a bug in [proof-builder] commands [47mx[0m and [47mexpand[0m, which usually
  gave a misleading error message when attempting to expand a
  constrained function.

  Fixed bugs in the tracking and disabling of [compound-recognizer]
  rules.  Thanks to Dmitry Nadezhin for pointing out this bug,
  indeed, sending an example and analyzing it to point to system
  function [47mterm-and-typ-to-lookup[0m, which was indeed the one that had
  the bug.

  Avoided a rare error in [47m[hons-wash][0m that has happened when there is a
  second garbage collection after [47mhons-wash[0m has commenced.  Thanks to
  Keshav Kini for telling us about the problem and providing a patch,
  which we used almost verbatim.


Changes at the System Level

  An ACL2 customization file is no longer loaded by default (when it
  exists) when invoking `[47mmake[0m' from the top-level ACL2 directory.
  This change is not necessary for `[47mmake regression[0m' because the
  build system for the books already takes care of it.  However we
  need this change for `[47mmake DOC[0m', at the least; thanks to Eric Smith
  for bringing our attention to a failure of `[47mmake DOC[0m'.

  (Really a books change, but affects building the manual:) By default,
  it is now an error if when saving the ACL2+books or ACL2-only
  manuals (web-based or text-based), a syntax error (marked by ``xdoc
  error'') is encountered.  See [47m[xdoc::save][0m and
  [47m[xdoc::save-rendered][0m: both now have an error argument with default
  [47mnil[0m so that by default, those new errors are not signaled; but in
  accordance with the change above, that new error argument is [47mt[0m for
  the standard ways of building the ACL2+books and ACL2-only manuals.
  Also, two arguments have been eliminated for [47mxdoc::save-rendered[0m.

  An invocation of `[47mmake update[0m' to build an ACL2 executable initiates
  a build only when necessary (that is, when at least one source file
  or supporting file, like [47mGNUmakefile[0m, has changed).  Thanks to Eric
  Smith for the suggestion.  Removed the following `[47mmake[0m' targets,
  which were suspect after this change (the first definitely no
  longer worked) and are unnecessary: [47msaved_acl2[0m, [47msaved_acl2p[0m,
  [47msaved_acl2r[0m, and [47msaved_acl2pr[0m.  WARNING: [47mmake update[0m should be used
  with care, since it does not rebuild the desired executable when it
  already exists and is more recent than the sources.  For example,
  if you change Lisp implementations without changing the [47mPREFIX[0m
  variable --- perhaps even only changing the version of your Lisp
  --- then use [47mmake[0m or [47mmake large[0m, not [47mmake update[0m.

  New `[47mmake[0m' target [47mclean-all[0m removes all generated files in the main
  ACL2 directory and its [47mdoc/[0m subdirectory, while existing target
  [47mclean[0m, which has been renamed [47mclean-lite[0m, cleans all of those
  except files [47m*saved_acl2*[0m (and [47mdoc.lisp.backup[0m), essentially as
  before.  Thanks to Eric Smith for suggestions leading to this
  change, and to Keshav Kini for suggesting consideration of target
  [47mdistclean[0m as an alias for [47mclean-all[0m, which it now is.  The target
  [47mclean[0m is deprecated but, consistent with prior usage, acts as
  [47mclean-lite[0m for now.

  A successful build using `[47mmake[0m' shows only four lines for [47m'fgrep -i
  compiler make.log[0m' instead of five.

  (GCL only) Installed a patch from Camm Maguire (GCL maintainer) to
  fix a GCL compiler bug.  Also turned off SGC to avoid an ``mprotect
  failure'' error (community book
  [47mbooks/centaur/fty/tests/deftagsum-scale.lisp[0m).

  Fixed a bug that was causing an assertion failure, instead of a clean
  error, when attempting to apply [47m:[0m[47m[monitor][0m to undefined primitives,
  e.g., [47m:monitor cons t[0m.  Thanks to Keshav Kini for reporting this
  bug and sending us an initial fix.

  Fixed a bug in the [break-rewrite] commands [47m:go![0m and [47m:go$[0m, which was
  causing an error message to be printed.


EMACS Support

  Made minor [ACL2-doc] improvements: fixed a bug in `[47mu[0m' command's
  error message when already at the top topic; fixed a bug that was
  displaying the \"Parent list:\" field in reverse order; and
  eliminated the warning when loading a large manual (combined manual
  is at about 70M bytes now; new threshold is 80M bytes).

  Improved [ACL2-doc] to work with other manuals; see [ACL2-doc],
  specifically Section ``Selecting a Manual''.  Note that the command
  for initially bringing up the ACL2 User's Manual, instead of the
  ACL2+Books manual, has changed from [47m(defvar *acl2-doc-top-default*
  'TOP)[0m to [47m(defvar *acl2-doc-manual-name* 'acl2-only)[0m.

  Added new [ACL2-doc] commands, `[47m/[0m' and `[47mW[0m', to go to an ACL2
  definition.  By default the search is through both the ACL2 sources
  and books.  The search can be continued even outside acl2-doc by
  using a numeric prefix argument with [47mcontrol-t /[0m, which is just the
  `[47m/[0m' command made available outside acl2-doc.  These two commands
  differ only in the defaults presented in the minibuffer.  The
  default for `[47m/[0m' is based on the text at the cursor.  (This is much
  like the similar built-in Emacs command, [47mmeta-.[0m; indeed, `[47m/[0m' is
  next to `[47m.[0m' on standard keyboards.)  For `[47mW[0m', the default is based
  on the page's topic name (as shown by the `[47mw[0m' command).  See
  [ACL2-doc] for details.

  Installed a patch for [47mcontrol-t control-e[0m from Keshav Kini, so that
  when there are more than two windows and one has the ACL2 shell
  buffer showing, then that one receives the form.  Consider for
  example windows A, B, and C, where the cursor is showing in A and
  the shell buffer is showing in C.  Previously, the shell buffer
  could be placed in B to receive the form.  Now, the form will go
  into C.

  The [47m:evisc-tuple[0m keyword for [47m[trace$][0m was being ignored when [47m:native
  t[0m was also supplied.  Since the use of [47m:native t[0m sends the tracing
  command to raw Lisp, this wasn't really a bug, since no raw Lisp we
  know of supports the [47m:evisc-tuple[0m keyword.  However, we have
  improved our custom modifications of the native [47mtrace[0m for host
  Lisps CCL and Allegro CL so that [47m:evisc-tuple[0m is no longer ignored
  for these Lisps.


Experimental Versions

  A new rewrite rule for ACL2(r), [47mrealp-implies-acl2-numberp[0m, is
  analogous to the existing rule [47mrationalp-implies-acl2-numberp[0m.
  Thanks to Dmitry Nadezhin for suggesting the addition of this rule,
  which he observed is necessary for some ACL2(r) proofs.")
 (NOTE-8-0
  (RELEASE-NOTES)
  "ACL2 Version 8.0 (December, 2017) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 7.4 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  [note-8-0-books] for a summary of changes made to the ACL2
  Community Books since ACL2 7.4, including the build system.  Also
  note that with each release, some built-in functions that were
  formerly in [47m:[0m[47m[program][0m mode are now [guard]-verified [47m:[0m[47m[logic][0m mode
  functions.


Changes to Existing Features

  The macro, [47m[case-match][0m, now treats keywords as constants when they
  occur in patterns.  For example, the following form evaluates to 3
  where formerly an error occurred:

    (let ((x '(:foo 3)))
      (case-match x
        ((:foo y) y)
        (& 17)))

  Thanks to Keshav Kini for suggesting this improvement.

  Several changes have been made to [47m[sys-call][0m and [47m[sys-call+][0m, and a
  new utility, [47m[sys-call*][0m, has been added.  These stem from feedback
  from an observation by Eric Smith: [47msys-call[0m could invoke the
  operating system when simplifying terms (see [sys-call] for an
  example).  We thank Eric for helpful discussions.  Changes include:

    * When [47m[sys-call][0m is invoked during a proof (from a prover call or
      invocation of the [proof-builder]), it no longer can make a
      (potentially dangerous) call to the operating system.  If such
      an invocation occurs during evaluation of a clause-processor or
      metafunction, an error will be signaled.

    * [47m[Sys-call+][0m continues to call the OS during proofs, but now it only
      does so when applied to the actual ``live'' ACL2 [state].

    * A new utility, [47m[sys-call*][0m, combines some features of [47m[sys-call][0m and
      [47m[sys-call+][0m; it takes [47mstate[0m and takes effect even during proofs
      like [47msys-call+[0m, but like [47msys-call[0m it does not capture output.
      Thus, it can be a good choice in place of [47msys-call[0m for
      clause-processors and metafunctions, now that [47msys-call[0m would
      cause an error.

    * The guards are no longer [47mt[0m.  Now, the guard for all three functions
      specifies the application of a string (the command) to a true
      list of strings (the arguments).

    * The [executable-counterpart] of [47m[sys-call][0m is disabled by default.

  Several symbols have been added to the list [47m[*ACL2-exports*][0m,
  including [47mLET[0m (thanks to Eric Smith for that suggestion).

  When a single-threaded object is being used where an ordinary object
  is expected, the error message has been improved to show the
  enclosing form.  Moreover, such an error message can now appear
  when congruent stobjs are involved, where formerly the error was
  blamed on the shape of the result.  Thanks to Sol Swords for
  bringing the latter problem to our attention with a helpful
  example.  (See a comment in ACL2 source function [47mtranslate11-call[0m
  for a simplified version of that example.)

  The banner printed when there is a raw Lisp error now points to a new
  [documentation] topic, [raw-lisp-error].  Thanks to Keshav Kini for
  most recently pointing out that [47m[fmt][0m can cause a raw Lisp error.

  When suppressing output of all types other than [47merror[0m --- see
  [set-inhibit-output-lst] --- then errors may be reported with
  considerably less noise than before, because of the following
  changes.  Thanks to Eric Smith, Alessandro Coglio, and Stephen
  Westfold for helpful discussions and feedback.

    * When all output is inhibited except error output, the generic failure
      message for events is suppressed for [47m[encapsulate][0m, [47m[progn][0m,
      [47m[progn!][0m, and [47m[make-event][0m.

    * When a call of [47m[make-event][0m specifies keyword [47m:on-behalf-of[0m with
      value [47m:quiet[0m or [47m:quiet![0m, an error for [47mmake-event[0m expansion is
      generally suppressed; see [make-event-details].

    * A failed call of [47m[progn][0m no longer prints [47m\"PROGN failed!\"[0m; similarly
      for [47m[progn!][0m.

  Some warnings have been made more compact for including uncertified
  books.  Thanks to Eric Smith for suggesting such an improvement.

  The (minimal) support for infix printing has been removed.  (See the
  Essay on infix printing in ACL2 source file [47maxioms.lisp[0m for more
  information.)  However, as a result it is now possible to call
  certain functions during evaluation of [47m[defconst][0m forms, and during
  macroexpansion --- in general, during any evaluation when so-called
  ``safe mode'' is active and a function with raw Lisp code is
  encountered.  For example, the following form was formerly rejected
  but is now accepted.

    (defconst *c* (fms-to-string \"abc~x0\" (list (cons #\\0 (expt 2 4)))))

  Thanks to Eric Smith for suggesting such a change.

  The role of [ruler-extenders] for redundancy of [47m[defun][0m forms has
  been simplified; see [redundant-events].  Thanks to Alessandro
  Coglio for contributing a patch for this change.  Moreover, there
  was a bug: the redundancy check for definitions could allow the new
  definition to be redundant even when it specified more than one
  value for [47m:ruler-extenders[0m, which is illegal.  This has been fixed.
  Thanks to Alessandro Coglio for bringing this issue to our
  attention.

  Modified the built-in rule [47mcomplex-0[0m to one that is simpler but
  equivalent, and modified the definition of [47m[conjugate][0m so that it
  always returns a number (essentially by ``fixing'' its argument).
  We thank Keshav Kini for suggesting such changes, and for helpful
  discussions we also thank Alessandro Coglio and Sol Swords, who
  suggested the definition of [47mconjugate[0m that we ultimately installed.

  The system-level utility, [47mtrans-eval[0m, now prints a warning by default
  when its call modifies a user-defined [47m[stobj][0m.  This feature can be
  defeated but it may be best to allow the warning to be printed.
  See [trans-eval] and, especially, see
  [user-stobjs-modified-warnings].  A related change is that in order
  to call [47m[ld][0m in the body of a definition, a new keyword argument,
  [47m:ld-user-stobjs-modified-warning[0m, must be supplied.  See [ld].
  (Note: This issue was raised some time ago by Sol Swords.)

  Substantially improved error messages for illegal applications of
  theory functions (see [THEORY-FUNCTIONS]) [47m[enable][0m, [47m[disable][0m,
  [47m[set-difference-theories][0m, [47m[union-theories][0m, and
  [47m[intersection-theories][0m.

  Theory warnings have been enhanced to report enabling or disabling of
  the definition [rune] for an undefined [primitive] like [cons].
  Thanks to Eric Smith for pointing out that ACL2 quietly lets one
  enable or disable undefined primitives to no effect, and also for
  feedback leading to improvements on the initial implementation of
  this change.  For details, see [theories-and-primitives],
  specifically the last section, which pertains to primitives.

  Removed the symbol [47mlet-beta-reduce[0m from the list
  [47m*initial-untouchable-fns*[0m because [47mlet-beta-reduce[0m is not a known
  function symbol.

  The [47m:do-not-induct[0m hint no longer accepts keyword arguments other
  than [47m:otf-flg-override[0m and [47m:otf[0m, which would produce illegal
  theorem names in the report of skipped goals.  Thanks to Eric Smith
  for a query that led us to clean this up.

  Duplicate hypotheses have been eliminated for events generated by
  [47m[defabsstobj][0m.  Thanks to David Rager for bringing this issue to
  our attention and for helpful conversations.

  It is now legal for the bindings of a [47m[stobj-let][0m form to call
  accessors of a stobj, [47mst1[0m, on a stobj [47mst2[0m that is congruent to [47mst1[0m.
  See [nested-stobjs].  Thanks to Sol Swords for requesting and
  explaining this feature, implementing it, and providing tests.  To
  see tests, search for ``how congruent stobjs may be used in
  stobj-let'' in [community-book]
  [47mbooks/system/tests/nested-stobj-tests.lisp[0m.

  A low-level error starting with ``HARD ACL2 ERROR in
  FIND-MAPPING-PAIRS-TAIL'' has been eliminated.  This error could
  formerly occur when using redefinition; see comments in ACL2 source
  function [47mfind-mapping-pairs-tail1[0m for two simple examples.  We
  thank Yan Peng for bringing this issue to our attention.  Note that
  although we make some effort to support redefinition, we do not
  guarantee that it always works well; for a relevant warning, see
  [ld-redefinition-action].

  Several related changes have been made in ``second-order''
  capabilities.

    * The function [47m[magic-ev-fncall][0m could invoke functions that should not
      be invoked because they require a trust tag (see [defttag]) or
      they are untouchable (see [push-untouchable]).  A check is now
      in place to prevent this; see [magic-ev-fncall].  For example,
      evaluation of the form [47m(magic-ev-fncall 'sys-call '(\"pwd\" nil)
      state t nil)[0m no longer prints the current directory; instead it
      results in an error.

    * It was possible for system function [47mev-fncall-w[0m to subvert such a
      check by placing it under a [program-wrapper]; so [47mev-fncall-w[0m
      is now untouchable.

    * A new function, [47mev-fncall-w![0m, always performs the check, and may be
      used in place of [47mev-fncall-w[0m.  But consider instead using the
      documented [logic]-mode function [47m[magic-ev-fncall][0m.

    * The first argument of [47mmagic-ev-fncall[0m no longer needs to be in
      [logic] mode.

    * [47mMagic-ev-fncall[0m can execute considerably more quickly than before;
      thanks to Eric Smith for sending an example that helped us to
      implement this improvement.

    * Both [47moracle-apply[0m and [47moracle-funcall[0m have been eliminated.  Use
      [47m[magic-ev-fncall][0m where you would otherwise use one of those.

  Expressions in [table] [events] may now use not only the variable,
  [47mWORLD[0m, but also the variable, [47mENS[0m.  See [table].


New Features

  A new utility, [47m[apply$][0m, provides a weak version of the Common Lisp
  second-order utility, [47mapply[0m.  Using this new primitive the user can
  define functions like [47mmap[0m, which can apply certain function symbols
  and lambda expressions.

  Added utility [47m[checkpoint-summary-limit][0m.  Thanks to Mihir Mehta for
  an email leading to this addition.

  A new utility, [47m[set-register-invariant-risk][0m, provides a way to avoid
  inclusion of the [invariant-risk] check in code generated by ACL2
  for executable-counterpart functions (see [evaluation]).  The
  effect of [47mset-register-invariant-risk[0m is limited to the enclosing
  book or [47m[encapsulate][0m event.  Thanks to Eric Smith for a discussion
  leading to this feature.

  The new functions [47mread-object-with-case[0m and
  [47mprint-object$-preserving-case[0m are variants of [47mread-object[0m and
  [47mprint-object$[0m, respectively.  The function [47mread-object-with-case[0m
  lets you specify that case is preserved, inverted, or converted to
  lower case or (as with [47mread-object[0m) to upper case.  The function
  [47mprint-object$-preserving-case[0m prints symbols without escaping them
  for case; for example, the symbol in the current package with name
  [47m\"abc\"[0m is printed as [47mabc[0m, not as [47m|abc|[0m as would be printed by
  [47mprint-object$[0m.  See [io].

  New macro [47mwith-output![0m is the same as [47m[with-output][0m except for two
  differences: [47mwith-output![0m can be called in code, but it does not
  generate an event form.

  Now [47mcomplex-definition[0m is a disabled rewrite rule (formerly
  [rule-classes] [47mnil[0m).  Also added (enabled) rules
  [47mdefault-pkg-imports[0m, [47mdefault-code-char[0m, and
  [47mdefault-intern-in-package-of-symbol[0m.  All of these may be found in
  ACL2 source file [47maxioms.lisp[0m.  Thanks to Keshav Kini for email that
  led us to add these rules.

  New function [47m[get-enforce-redundancy][0m queries the [world] on whether
  redundancy is being enforced.  Thanks to Eric Smith for requesting
  this feature.

  It is now possible to obtain output that is less likely to depend on
  the directory where it was created, by evaluating the form [47m(assign
  script-mode t)[0m.  (This capability supports the new tool,
  [47m[run-script][0m.)

  We added support for more detailed reports on the progress of
  forward-chaining.  However these reports are only available on an
  experimental basis by redefining the system function [47mforward-chain1[0m
  as directed by a comment at the top of that [47mdefun[0m.  Users who find
  this level of reporting useful are encouraged to tell us as we
  could incorporate it into the documentation topic,
  [forward-chaining-reports].

  Normally, hard error messages (see [er]) are not inhibited.  A new
  [state] global, [47mINHIBIT-ER-HARD[0m, inhibits hard error messages when
  [47mERROR[0m output is inhibited; see [set-inhibit-output-lst].


Heuristic and Efficiency Improvements

  The checking done for [invariant-risk] has been relaxed, so that it
  no longer causes any slowdown in calls of [47m:[0m[47m[logic][0m-mode functions.

  A low-level system function, [47mcross-prod[0m (which is used by
  [tau-system]), now uses tail-recursion, which may avoid some stack
  overflows.

  [Forward-chaining] was improved so that if a [47m:forward-chaining[0m rule
  produces a conclusion that is a disjunction, the system watches for
  later [type-set] information about the disjuncts.  E.g., if we
  forward-chain to [47m(OR p q)[0m and later in the same forward-chaining
  process [47mq[0m becomes false, then [47mp[0m is made true.  We thank Dave Greve
  for providing an example requiring this.

  An optimization for removing [stobj] recognizers, long applied to
  bodies of executable definitions, is now also applied to [guard]s.
  Thanks to Sol Swords for suggesting this change and its
  implementation.

  The function [47m[resize-list][0m is now defined using [47m[mbe][0m so that its
  execution is tail-recursive.  Thanks to Martin Simmons of LispWorks
  Technical Support for diagnosing a stall in the certification of
  community book [47mbooks/centaur/truth/perm4.lisp[0m as being due to a
  stack overflow caused by an invocation of [47mresize-list[0m.  Based on
  his advice we no longer automatically grow the stack in LispWorks;
  this will ease debugging when compilation is done with safety 3.
  The maximum stack size is 399998, at least in our 64-bit LispWorks
  build.


Bug Fixes

  Soundness bugs have been fixed in the handling of [47m[stobj-let][0m, due to
  aliasing that could take place by binding two different but
  congruent stobjs to the same stobj.  To see examples, search for
  ``soundness'' in [community-book]
  [47mbooks/system/tests/nested-stobj-tests.lisp[0m.  We are very grateful
  to Sol Swords not only for bringing this to our attention, but
  especially for his contributions to a fix through helpful
  conversations and by providing code and examples.

  A bug in the [proof-builder]'s command, [47mrewrite[0m (or equivalently, [47mr[0m;
  see [ACL2-pc::rewrite]), avoided creating necessary subgoals, which
  can presumably be unsound.  That bad behavior could occur when the
  third (and optional) argument of that command was a non-[47mnil[0m value
  other than [47mt[0m.

  The built-in evaluator functions for ACL2 relied on a system
  function, [47mev-fncall-w[0m, that was not a function!  We do not see how
  to exploit this oddity to prove [47mnil[0m, since [47mev-fncall-w[0m is
  guaranteed never to be in [logic] mode.  However, it is clearly
  undesirable.  In the following example, the two [47mev-fncall-w[0m calls
  gave different answers on the same inputs --- [47m(mv nil 7)[0m and [47m(mv
  nil 12)[0m --- but now the second call results in an error.

    (defun foo (x y) (+ x y))
    (assign old-w (w state))
    (ev-fncall-w 'foo '(3 4) (@ old-w) nil nil nil t nil)
    (u)
    (defun foo (x y) (* x y))
    (ev-fncall-w 'foo '(3 4) (@ old-w) nil nil nil t nil)

  The check for the requisite theorems supporting a [47m[defabsstobj][0m event
  included a case where the check was too weak, and it also could
  cause an unexpected assertion.  The first of these could probably
  cause unsoundness.  Thanks to Sol Swords for finding these issues
  and providing fixes.

  A small change in [47m[defstobj][0m can lead to improved automation for some
  [47m[guard][0m proofs involving [47m[stobj-let][0m.  Thanks to Sol Swords for
  sending an example, which guided us to add a test (as suggested by
  Eric Smith) in community book
  [47msystem/tests/nested-stobj-formals.lisp[0m.

  Formatted printing (with [47m[fmt][0m, [47m[cw][0m, etc.) failed to respect
  newlines encountered while processing [47m~s[0m and [47m~S[0m directives.  This
  has been fixed; see [47mbooks/system/tests/fmt-to-string.lisp[0m for
  examples that behave well now but formerly did not.  Thanks to Eric
  Smith for pointing out this problem and sending, in essence, the
  following example.

    (cw \"~s0\"
        (string-append-lst
         (make-list 100
                    :initial-element
                    (coerce '(#\\A #\\B #\\C #\\D #\\E #\\F
                              #\\G #\\H #\\I #\\J #\\Newline)
                            'string))))

  A bug that was in the [tau-system] is illustrated by the following
  example sent by Grant Passmore, in which tau discovers that the
  function being defined always returns [47mnil[0m, hence implies
  everything.  Tau no longer causes an error in this situation.

    (defun f (x) (> x 0))
    (defun g (x) (< x 0))
    (defun h (x) (and (f x) (g x)))

  Moreover, tau ``knows'' that the function [47mh[0m above is contradictory,
  as evidenced by the successful proof of the [47mthm[0m below.

    (thm
     (implies (h x) (consp x))
     :hints ((\"Goal\" :in-theory '((:e tau-system)))))

  Fixed a bug in [47m:[0m[47m[pe!][0m that could result in an error in [47m:pe!  :here[0m
  when the most recent command is an [47m[encapsulate][0m event.

  It was possible to be in raw-mode, when including an uncertified book
  with a call of [47m[progn!][0m that first sets raw-mode [47m[set-raw-mode][0m and
  then causes a raw Lisp error.  This has been fixed.

  It is now possible to invoke [47m[verify-termination][0m without an error
  occurring due to the presence of untouchable variables or functions
  in the definition (which hadn't prevented earlier admission in
  [program] mode).  Thanks To Eric Smith for bringing this issue to
  our attention.

  ACL2 has supported, and continues to support, [47m[defun][0m forms that
  include the ACL2 [state] as an argument without declaring [47mstate[0m
  explicitly to be a [stobj].  This is done by first evaluating
  [47m(set-state-ok t)[0m.  But in that case, the guard for such a function
  erroneously failed to include [47m(state-p state)[0m, which can have
  unfortunate consequences; see
  [47mbooks/system/tests/state-p-in-guard.lisp[0m in the [community-books].
  This has been fixed.  Thanks to Alessandro Coglio for contributing
  a fix and for helpful conversations.

  Fixed bugs in reporting of errors and warnings by [47m[defchoose][0m when
  pertaining to ignored variables.  Thanks to Eric Smith for bringing
  one of these to our attention.

  Fixed a bug in the [proof-builder]: [hints] on the [47mprove[0m command were
  not being passed down to induction.  Thanks to Mihir Mehta for
  bringing this bug to our attention with a reproducible example.

  Fixed a low-level bug (in source functions [47mnote-relieve-hyp-failure[0m),
  discovered by using the new community book
  [47mbooks/system/check-system-guards.lisp[0m.  That book, which is useful
  for system development, checks all top-level calls of built-in
  functions that are in [logic] mode, [guard]-verified.


Changes at the System Level

  When building the combined manual, an error occurs if there is more
  than the single expected broken link.  Thanks to Alessandro Coglio
  for helpful discussions.  [3mNotes.[0m (1) This uses a new keyword
  argument available in [47m[xdoc::save][0m, [47m:broken-links-limit[0m.  (2) There
  is no such limit for saving the text-based manual.

  As usual, several [documentation] improvements have been made, for
  example, clarification made in the topic [local-incompatibility]
  thanks to Keshav Kini and Yan Peng.  A new documentation topic,
  [evaluation], is probably long overdue: it explains ACL2 evaluation
  with a focus on the notions of the ``executable-counterpart
  function'' (sometimes called the ``*1* function'') and the
  ``submitted function'' (sometimes called the ``raw-Lisp
  function'').

  Environment variable [47mSBCL_USER_ARGS[0m allows one to pass
  runtime-options to calls of ACL2 built on SBCL, without having to
  call [47m[save-exec][0m.  Thanks to Sol Swords for requesting this
  capability.  Example:

    (export SBCL_USER_ARGS=\"--lose-on-corruption\" ; ./sbcl-saved_acl2)

  There is a new documentation topic, [talks], which has a link from
  the ACL2 home page (with Applications, Tours, and Tutorials/Demos).
  Additional contributions to this topic are welcomed!

  For SBCL, the runtime option [47m--disable-ldb[0m is now supplied by the
  [47msaved_acl2[0m script, which avoids passing control to the lowest-level
  ([47mldb[0m) debugger (from which recovery is probably impossible).
  Without this option, a parallel run of [47mcert.pl[0m (see
  [build::cert.pl]) can stall out when a single failure passes
  control to the [47mldb[0m debugger.

  Some infinite loops are now avoided in the debugger for SBCL (and
  perhaps some other Lisp implementations).  Thanks to Keshav Kini
  for sending an example and suggesting a fix, which we incorporated,
  as well as for helpful conversations.  Implementation note: the
  definition of constant [47m*our-standard-io*[0m in ACL2 source file
  [47minterface-raw.lisp[0m explains the issue.

  Warnings were being produced by [47m[include-book][0m in CCL, and perhaps
  some other Lisps, when including a book that redefines a function
  as a macro or vice-versa.  We have eliminated those raw Lisp
  warnings.

  It is now checked that the [47mbooks/[0m directory exists before attempting
  any operations using [47m'make'[0m on that directory.  Thanks to Keshav
  Kini for suggesting this check, since there are source-only
  distributions, without the books.

  (SBCL only) The setting of environment variable [47mSBCL_HOME[0m has been
  tweaked to be more robust.  In particular, we expect it to be
  unnecessary, and even inadvisable, to set [47mSBCL_HOME[0m manually.
  Thanks to Keshav Kini for contributing this change.

  (CMUCL only) ACL2 Version 8.0 cannot be reliably run on CMUCL, so we
  have disabled building ACL2 on CMUCL.  The CMUCL implementor is
  aware of the problem, and we are hoping for a fix before the next
  ACL2 release

  The [state] global variables, [47mserialize-character-system[0m and
  [47mserialize-character[0m, are now preserved after [47m[make-event][0m
  expansion.  This change for [47mserialize-character-system[0m allows the
  use of [47mmake-event[0m to avoid a stack overflow when writing out a
  [certificate] file; see [set-serialize-character-system].


EMACS Support

  Now, tags table [47mTAGS-acl2-doc[0m is automatically built when building
  the manual unless environment variable [47mTAGS_ACL2_DOC[0m has value
  [47mSKIP[0m.  It can also be built by using the new event
  [47m[xdoc::save-rendered-event][0m.  See [ACL2-doc] and see
  [xdoc::save-rendered-event].  Thanks to Eric Smith and David Rager
  for discussions leading to this enhancement.  That tags table can
  also be built when building ACL2; see [ACL2-doc].

  Made miscellaneous fixes for [ACL2-doc]: added [47mShift-<tab>[0m (more
  precisely, [47m<backtab>[0m to do the same thing as [47mControl-<tab>[0m (thanks
  to Eric McCarthy for the suggestion), avoided the use of [47msetf[0m (not
  always defined without requiring the [47mcl[0m package), avoided a
  potential error (when variable [47mlarge-file-warning-threshold[0m is
  [47mnil[0m), and avoided an infinite loop on some platforms when quitting
  acl2-doc.

  Defined `[47mmeta-,[0m' in [47memacs/emacs-acl2.el[0m to be Emacs function
  [47mtags-loop-continue[0m, which is how it has traditionally been defined
  by Emacs but might be defined differently in some versions of Emacs
  25 (and perhaps later).  [31;1mNOTE[0m: Put [47m(setq
  *preserve-tags-loop-continue* t)[0m in your [47m.emacs[0m file before loading
  ACL2 file [47memacs/emacs-acl2.el[0m, if you want to avoid redefining
  `[47mmeta-,[0m'.  Thanks to Keshav Kini and Mihir Mehta for helpful
  discussions.

  Removed both non-ascii characters from [47memacs/emacs-acl2.el[0m.  Thanks
  to Keshav Kini for the suggestion.

  For documentation printed at the terminal with [47m:[0m[47m[doc][0m, links
  (enclosed in in square brackets, ``[..]'') continue to be printed
  with respect to the [47m\"ACL2\"[0m package (that is, as though the current
  package were [47m\"ACL2\"[0m).  Now, however, where a link formerly might be
  printed as ``[acl2::foo]'', it is now printed as ``[foo]''; that
  is, a package prefix of [47m\"ACL2\"[0m (regardless of case) is not printed.


Experimental Versions

  Improved [type-set] reasoning for the function, [47m[imagpart][0m.  Thanks
  to Keshav Kini for identifying the problem and suggesting a code
  change, and for sending an example of a theorem that formerly
  failed to be proved in ACL2(r).

  Improved [type-set] reasoning for the function, [47m[complex][0m.  Thanks to
  Keshav Kini for identifying the problem and sending a patch, which
  we installed, together with examples of theorems that formerly
  failed to be proved in ACL2(r) but now prove, in particular:

    (thm (implies (and (real/rationalp a)
                       (not (rationalp a)))
                  (not (complex-rationalp (complex a b)))))

  Since [47m[wormhole][0m uses a lock (and has for some time), we modified
  [47m[observation-cw][0m so that it uses the same wormhole printing in
  ACL2(p) (instead of using [47m[cw][0m) that is used in regular ACL2.
  Thanks to David Rager for a helpful discussion.  If you see an
  increase in hangs while using ACL2(p), please contact the
  implementors.

  Fixed an infinite loop that could be caused with parallelism enabled
  when there is an error, when Lisp variable [47m*hard-error-is-error*[0m
  has been set to a non-[47mnil[0m value in raw Lisp (see [hard-error]).")
 (NOTE-8-1
  (RELEASE-NOTES)
  "ACL2 Version 8.1 (September, 2018) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 8.0 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  [note-8-1-books] for a summary of changes made to the ACL2
  Community Books since ACL2 8.0, including the build system.  Also
  note that with each release, it is typical that the value of
  constant [47m[*ACL2-exports*][0m has been extended, and that some built-in
  functions that were formerly in [47m:[0m[47m[program][0m mode are now
  [guard]-verified [47m:[0m[47m[logic][0m mode functions.


Changes to Existing Features

  The evaluation of [table] guards now allows attachments.  This is
  important for the implementation of [47m[apply$][0m (see below).

  A new keyword argument for [47m[defun-sk][0m, [47m:constrain[0m, can specify that
  the newly-introduced function is constrained rather than defined.
  See [defun-sk].  Note that by constraining the function we make it
  possible to attach to it, and also to introduce it as a
  [guard]-verified function.  We also made a minor change to
  [47mdefun-sk[0m, by moving the call of [47m[extend-pe-table][0m out of the
  generated [47m[encapsulate][0m form.

  (Of interest only to users of [47m[apply$][0m.)  When invoking [47m[defwarrant][0m
  or [47m[defun$][0m, a so-called `[warrant]' is introduced.  Warrants are
  now always [guard]-verified, with a guard of [47mt[0m.  Moreover, warrants
  are now executable in the top-level loop; for example, after
  successfully processing [47m(defwarrant foo)[0m or [47m(defun$ foo ...)[0m,
  [47m(warrant foo)[0m will evaluate to [47mt[0m in the loop.  (Note: each warrant
  has an attachment, [47mtrue-apply$-warrant[0m, that always returns [47mt[0m; see
  [defattach].)  Thanks to Dmitry Nadezhin for requesting these
  enhancements.

  It is now required to include the system book
  [47mprojects/apply/apply-lemmas.lisp[0m before evaluating a call of [47mdefun$[0m
  or [47m[defwarrant][0m.  This requirement, which is enforced with an error
  that prints the necessary [47m[include-book][0m form, avoids stack
  overflows that could occur when that book is not included.

  When performing [47m[make-event][0m expansion under a surrounding [local]
  context, it is no longer illegal to set the [ACL2-defaults-table].
  For example, the following event formerly caused an error but is
  now legal.

    (local (make-event (er-progn (set-ignore-ok t)
                                 (defun foo (x) x)
                                 (value `(value-triple ,(length (w state)))))))

  Information printed when giving [47m:use[0m [hints] has been improved for
  the case that a [lemma-instance] is a [47m:[0m[47m[termination-theorem][0m or a
  [47m:[0m[47m[guard-theorem][0m.  Formerly, only the name was shown in the
  `[47mHint-events[0m' [summary] and in the proof output; now, one will see
  ``names'' of the form [47m(:termination-theorem NAME)[0m and
  [47m(:guard-theorem NAME)[0m.

  We improved redundancy checking for [47m[defun][0m forms so that it is not
  sensitive to whether [47m[state][0m has a [47m:stobjs[0m declaration.

  The [warnings] for weak [type-prescription] rules have been
  eliminated.  These warnings were issued when a rule was
  insufficient to prove itself by [type-set] reasoning, but it seems
  more appropriate to parse the formula into a type-prescription rule
  before applying that check (for example, expanding away
  [guard-holders], which was already done, and beta reducing lambda
  applications, which was not).  Then the chance of not proving the
  result seems remote.  Thanks to Keshav Kini for an example and a
  conversation leading to this improvement.

  The [checksum] computation that can support certifying or including
  [books] --- which is not used by default, but see [book-hash] for
  how to enable it --- has been improved.  Specifically, at least one
  of the [community-books] (namely, [47mbooks/centaur/aignet/rwlib.lisp[0m)
  formerly caused a stack overflow (with host Lisp SBCL, at least)
  before making this change.  (Technical note: the change is to avoid
  memoization for calls of [47mfchecksum-obj[0m with stack depth exceeding
  [47m10000[0m.)  Thanks to Keshav Kini for reporting this issue and for
  related helpful communications.

  When a [break-rewrite] command such as [47m:eval[0m or [47m:go[0m shows that a rule
  fails because a [backchain-limit] is exceeded, more information is
  printed than before.  Now, the responsible rule(s) or global
  backchain-limit is indicated.  Thanks to Alessandro Coglio and Eric
  Smith for requesting this enhancement.

  The fancy string reader now accepts a string with three string quotes
  followed by a closing curly brace.  See [fancy-string-reader], in
  particular the final paragraph.  Thanks to Sol Swords for
  contributing this enhancement.

  The ACL2 [47m[untranslate][0m function, which converts the internal
  representation of [term]s to user-level syntax, can now return
  calls of [47m[mbe][0m, [47m[mbt][0m, [47m[ec-call][0m, [47m[cw][0m, [47m[time$][0m, and [47m[mv-let][0m.
  Thanks to Alessandro Coglio, Eric Smith, and Stephen Westfold for
  discussions leading to some of these changes.  Such terms rarely
  occur in practice because definitional bodies are stored with calls
  of [guard-holders] and [47mcw[0m expanded.  However, here is an example of
  how they could arise.  First consider the following definition.

    (defun g (n)
      (declare (xargs :normalize nil))
      (ec-call (natp n)))

  Here is a log before the change.

    ACL2 !>(verify (equal (g x) yyy))
    ->: 1
    ->: p
    (G X)
    ->: x-dumb
    ->: p
    (LET ((N X)) (EC-CALL1 NIL (NATP N)))
    ->:

  After the change, the log instead ends as follows.

    ->: p
    (LET ((N X)) (EC-CALL (NATP N)))
    ->:

  It is now illegal by default to attach to built-in functions.  To
  overcome this default behavior, see [defattach-system].

  Improvements have been made to functions in the [47m[fmt][0m family,
  including for example [47m[fms][0m, [47m[fmt-to-string][0m, and [47m[cw][0m.  (Also see
  discussion of [47m[fmx-cw][0m under ``New Features,'' below.)

    * Many [guard]s have been strengthened, for example to imply that the
      [47malist[0m argument must satisfy [47m[character-alistp][0m.  Thanks to Eric
      Smith for pointing out that an expression like [47m(fmt-to-string
      \"~x0\" 3)[0m could cause a raw Lisp error (rather than causing a
      guard violation).

    * Eliminated raw Lisp errors from ill-formed calls.  Thanks to Jared
      Davis for pointing out this problem in 2010 (!) with the
      example [47m(cw \"Bad: ~&0.~%\" 5)[0m, and for Eric Smith for prodding
      us much more recently with the example [47m(cw \"~&0\" 'x)[0m.

    * The utility [47m[fmx][0m no longer prints an initial newline.  Of course, a
      call [47m(fmx \"<some-string>\" ...)[0m can be modified to generate an
      initial newline (thus providing the former behavior) by adding
      the newline tilde-directive, [47m\"~%\"[0m, that is, [47m(fmx
      \"~%<some-string>\" ...)[0m.

  The previously-undocumented built-in-function, [47m[packn][0m, now has a
  slightly different behavior.  Formerly, it always returned a symbol
  in the [47m\"ACL2\"[0m package.  Now, the package of the symbol returned is
  the package of the first symbol in [47mlst[0m whose package is not
  [47m\"COMMON-LISP\"[0m if any, else [47m\"ACL2\"[0m.  Thanks to Keshav Kini for
  suggesting this change and providing its implementation.

  The [guard] on [47m[apply$][0m (also the guard on [47mapply$-lambda[0m) has been
  strengthened to require that a [lambda] be applied to the correct
  number of arguments.  The under-the-hood implementation for
  applying lambdas has been made slightly more efficient as a result,
  though that improvement may usually be trivial.  Perhaps more
  important is that guard verification may now catch bugs in the
  application of lambdas that were missed previously.

  The [47m:dir[0m argument to [47m[ld][0m was previously ignored when the first
  argument of the call of [47mld[0m is not a string.  Now, that is an error.
  If you get this error, just remove the (previously ignored) [47m:dir[0m
  argument.

  The function [47m[magic-ev-fncall][0m sometimes printed a message in the
  error case in addition to returning that message.  It now only
  returns that message.  Thanks to Sol Swords for bringing to our
  attention that certification of a community book,
  [47mbooks/projects/x86isa/proofs/popcount/popcount.lisp[0m, was printing a
  warning about [47m\"Meta-level function Problem\"[0m for thousands of lines.

  The definition of [47m[msgp][0m has been strengthened to require that for a
  [47mcons[0m pair, the [47mcdr[0m must satisfy [47m[character-alistp][0m.

  The [proof-builder] command, [47mquiet![0m, now inhibits all output except
  [47merror[0m output (and that too, if already inhibited).

  Warnings have been modified that are labeled ``[Non-rec]'', generated
  for rules with problematic occurrences of non-recursive function
  symbols.  Now they take into account rules of class [47m:[0m[47m[definition][0m.
  Thanks to Mihir Mehta for bringing this issue to our attention.

  It is no longer required to specify [47m:install-body nil[0m in a
  [definition] rule when the function symbol is a member of the value
  of the constant [47m*definition-minimal-theory*[0m.  Thanks to Eric Smith
  for pointing out that the utility, [47m[install-not-normalized][0m, was
  failing on, for example, [47m[eq][0m.  This change fixes that problem.
  Technical note for system hackers only: Because of this change, the
  value of [47m(body fn t wrld)[0m is no longer guaranteed to get the
  original definition of [47mfn[0m when fn is in
  [47m*definition-minimal-theory*[0m; for that purpose use the new utility,
  [47mbbody[0m.

  Many error messages now show variables according to order of
  appearance, where formerly the order was reversed.  Thanks to Eric
  Smith for supplying an example of a top-level form, [47m+ a b c[0m, for
  which the error message reported variables in reverse order:
  ``Global variables, such as C, B and A, are not allowed.'' The
  message now says ``A, B, and C'' instead of ``C, B and A.''

  For [47m[value-triple][0m, the keyword argument [47m:on-skip-proofs[0m provides new
  behavior if it is given the value, [47m:interactive[0m.  In that case,
  evaluation is still done under a call of [47m[skip-proofs][0m, as when the
  value of [47m:on-skip-proofs[0m is [47mt[0m; but evaluation is skipped when the
  reason proofs are being skipped is only that a book is being
  included or the second pass is being made through an [47m[encapsulate][0m.
  Thanks to Eric Smith for requesting this feature.

  Both [47m[fmt-to-comment-window][0m and [47mfmt-to-comment-window![0m have an extra
  argument, [47mprint-base-radix[0m, which is the same as the first argument
  to the new utilities, [47m[cw-print-base-radix][0m and
  [47m[cw-print-base-radix!][0m (see below).

  The undocumented constants [47m*primitive-program-fns-with-raw-code*[0m,
  [47m*primitive-logic-fns-with-raw-code*[0m, and
  [47m*primitive-macros-with-raw-code*[0m have been renamed respectively to
  [47m*initial-program-fns-with-raw-code*[0m,
  [47m*initial-logic-fns-with-raw-code*[0m, and
  [47m*initial-macros-with-raw-code*[0m.  Thanks to Alessandro Coglio for
  suggesting these improved names.

  The [47m[save-exec][0m utility now utilizes a relative pathname in the
  [47msaved_acl2[0m script, which can allow it and a corresponding image
  file to be moved, even across filesystems --- though if there is an
  image file, then probably the Lisp executable must have the same
  pathname even after the move.  Thanks to Eric Smith for suggesting
  this capability and providing a hint for how to implement it, to
  Sol Swords for pointing out a limitation of the initial
  implementation, and to {this website |
  https://serverfault.com/questions/40144/how-can-i-retrieve-the-absolute-filename-in-a-shell-script-on-mac-os-x}
  for making that solution robust.

  The [47m[defevaluator][0m macro, and more generally the notion of evaluator,
  have been changed to include two new [constraint]s inserted after
  constraints 0 through 5.  The new constraints are as follows, where
  [47m<ev>[0m refers to the evaluator.

    (IMPLIES (AND (NOT (CONSP X)) (NOT (SYMBOLP X)))
             (EQUAL (<ev> X A) NIL))
    (IMPLIES (AND (CONSP X) (NOT (CONSP (CAR X))) (NOT (SYMBOLP (CAR X))))
             (EQUAL (<ev> X A) NIL))

  These new constraints generated by [47m[defevaluator][0m are named
  [47m<ev>-CONSTRAINT-6[0m and [47m<ev>-CONSTRAINT-7[0m unless the keyword argument
  [47m:namedp t[0m is supplied, in which case they are named
  [47m<ev>-OF-NONSYMBOL-ATOM[0m and [47m<ev>-OF-BAD-FNCALL[0m.  Thus by default (or
  if [47m:namedp[0m is [47mnil[0m), this change increases by one the indices on
  constraints for the specified function symbols, because they start
  at 8 instead of 6 --- [47m<ev>-CONSTRAINT-8[0m, [47m<ev>-CONSTRAINT-9[0m, and so
  on.  Note that if you use functional instantiation to prove a
  theorem about one evaluator given a theorem about another
  evaluator, you'll need to enable the new rules (i.e.,
  [47mev-constraint-6[0m and [47mev-constraint-7[0m or, if you use option [47m:namedp
  t[0m, [47mev-of-nonsymbol-atom[0m and [47mev-of-bad-fncall[0m).  Thanks to Sol
  Swords for both suggesting and implementing this extension.

  [47m[Let][0m-expressions are no longer eliminated from right-hand sides of
  [rewrite] rules.  See [rewrite].  This change improves efficiency
  of the rewriter in some cases, by retaining subexpressions shared
  on the right-hand side as the rewrite rule is applied.  Thanks to
  Eric Smith for requesting this change.

  It was possible to declare a function symbol to be [untouchable] and
  yet still execute it using [47m[apply$][0m, thus violating the spirit of
  untouchables.  That is no longer allowed.  Here is an example of
  such execution that was formerly permitted, but is no longer.

    (include-book \"projects/apply/apply-lemmas\" :dir :system)
    (defun$ f (x) (declare (xargs :guard t)) (cons x x))
    (push-untouchable f t)
    (apply$ 'f '(3))


New Features

  The [summary] now shows, by default, the list of doublets [47m(f g)[0m for
  which [47mf[0m is a system function with attachment [47mg[0m (see [defattach]),
  when [47mg[0m differs from the initial attachment to [47mf[0m.

  (Warning: The following describes advanced features that can likely
  be ignored by most users.  They are available using the new
  utility, [47m[defattach-system][0m.)  Three new system-level functions may
  be given attachments: [47mremove-trivial-equivalences-enabled-p[0m,
  [47massume-true-false-aggressive-p[0m, and [47mrewrite-if-avoid-swap[0m.  (Thanks
  to Eric Smith for suggesting these, and to him and Alessandro
  Coglio for helpful discussions.)  By default, these have the
  attachments [47mconstant-t-function-arity-0[0m,
  [47mconstant-nil-function-arity-0[0m, and [47mconstant-nil-function-arity-0[0m,
  respectively, which provide the existing system behavior.  But
  these attachments may be changed by the user.

    * [47mRemove-trivial-equivalences-enabled-p[0m may receive the attachment
      [47mconstant-nil-function-arity-0[0m to avoid the
      [47mremove-trivial-equivalences[0m heuristic, which substitutes the
      equality (or even equivalence) of a variable to a term into the
      rest of the goal.  (However, perhaps similar heuristics will
      still be used, for example as part of the [tau-system].)

    * [47mAssume-true-false-aggressive-p[0m may receive the attachment
      [47mconstant-t-function-arity-0[0m to strengthen the rewriter's use of
      the [type-alist] when diving into [47mif[0m terms.  A common use is to
      rewrite what amounts to [47m(if (or test1 test2) (if test1 _ x) _)[0m;
      then the [type-alist] will note that [47mtest2[0m is true when
      rewriting [47mx[0m.  This change 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.

    * [47mRewrite-if-avoid-swap[0m may receive the attachment
      [47mconstant-t-function-arity-0[0m to cause the rewriter ---
      specifically, source function [47mrewrite-if[0m --- to avoid swapping
      true and false branches of a call of [47mIF[0m, which could formerly
      happen when the test is a call of [47mNOT[0m.

  When the environment variable [47mACL2_CUSTOMIZATION_QUIET[0m is set and not
  [47m\"\"[0m, there will generally be no output from ACL2 customization.  A
  special value of [47m\"all\"[0m for this variable will cause continued
  minimal output after startup.  See [ACL2-customization].

  New utilities, [47m[fmx-cw][0m and [47m[fmx!-cw][0m, are essentially the same as
  [47m[cw][0m and [47m[cw!][0m (respectively), except that [47mfmx-cw[0m and [47mfmx!-cw[0m are
  well-[guard]ed, which can catch errors in the use of
  tilde-directives.  Thanks to Eric Smith for requesting such a
  capability.  For example:

    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 !>

  New utilities, [47m[cw-print-base-radix][0m and [47m[cw-print-base-radix!][0m, are
  like [47m[cw][0m and [47m[cw!][0m, respectively, except for an additional
  argument that specifies the print-base and, optionally, the
  print-radix.  Thanks to Eric Smith for requesting
  [47m[cw-print-base-radix][0m.

  A new event macro, [47m[set-in-theory-redundant-okp][0m, allows [47m[in-theory][0m
  events to be [redundant], which prevents [47m[defund][0m and [47m[defthmd][0m
  [events] from laying down [47m[command][0m markers (as seen, for example,
  using [47m:[0m[47m[pbt][0m).  Thanks to Eric Smith for asking for a way for
  [47min-theory[0m events to be redundant.


Heuristic and Efficiency Improvements

  The implementation of [wormhole]s has been tweaked to avoid an
  efficiency problem.  In the old implementation, an update to the
  wormhole status was avoided in the case of equal old and new status
  values.  That update avoided some consing, but the equality test
  could be very slow; indeed, [47m:[0m[47m[print-gv][0m could be slow because of
  its use of wormholes.  The new wormhole implementation ---
  specifically, the new raw Lisp implementation of [47m[wormhole-eval][0m
  --- avoids that equality test, and also can avoid consing by its
  use of destructive operations.  That fixes one reason [47m:print-gv[0m
  could be slow; a second change, made to the implementation of
  [47m:print-gv[0m, is to pass [47mnil[0m as the wormhole-status ([47mwhs[0m) argument of
  [47mmake-wormhole-status[0m.  See [make-wormhole-status] for a discussion
  of how that use of [47mnil[0m can avoid an expensive equality test.
  Thanks to Alessandro Coglio and Eric Smith for sending an example
  that illustrated the problem.

  The following improvements have been made for evaluating calls of the
  form [47m(apply$ '(lambda ...) ...)[0m.

    * An optimization had failed to be fully in place, causing such calls
      to run slowly.  That optimization compiles and caches ``tame
      compliant'' lambdas: lambda forms whose [guard]s are verified
      by the [tau-system] and that are [3mtame[0m (see [apply$]).  The
      optimization had been used in the unadvertised use of ``The
      Rubric'' prior to the release of ACL2 Version 8.0.  Warnings
      about non-tame-compliant lambdas will now appear when
      appropriate, as had been the case in Version 7.4.

    * The optimization above has been improved so that instead of three
      cache lines, there is an efficient implementation using 1000
      cache lines.  That is probably many more than are needed, but
      the large size is harmless.  The additional cache lines
      dramatically improve speed when more than three lambdas are
      actively being applied; see [community-books] file
      [47mbooks/system/tests/apply-timings.lisp[0m.

    * ACL2 no longer causes an error when the cache is in an inconsistent
      state; instead, the cache is suitably reset quietly.

  Rewriting of calls of [47m[implies][0m has been optimized in the cases that
  the rewritten arguments are equal or at least one is a constant.
  Thanks to Eric Smith for pointing out an incompleteness in the
  rewriting of [47mimplies[0m calls.

  The algorithm has been tweaked for generating a [type-prescription]
  rule to store for a given definition, so that the rule is sometimes
  stronger than was previously the case.


Bug Fixes

  There was a soundness bug in the automatic functional instantiation
  that can be applied for a [47m:termination-theorem[0m [lemma-instance].
  Thanks to Eric Smith for sending an example to illustrate this bug,
  for suggesting its cause, and for permission to include that
  example in a comment in the ACL2 sources definition of the
  constant, [47m*non-instantiable-primitives*[0m.

  Bugs have been fixed in the [tau-system] that caused unsoundness
  (going all the way back through Version 6.0, released December,
  2012).  The problem was with conversion of a non-strict inequality
  with 0 to a strict inequality when the quantity is known not to be
  0; for example, [47m(<= x 0)[0m was converted to [47m(< x 0)[0m when [47mx[0m was known
  to be non-zero.  But of course, this conversion is only valid when
  [47mx[0m is known to be a number.  Thanks to Yan Peng for sending an
  example that illustrates the bug, which in its essence was the
  ability of ACL2 to prove this formula, which for example is false
  when [47mx = t[0m: [47m(or (< x 0) (= x 0) (> x 0))[0m.  If you encounter a
  failure in a proof that formerly succeeded, the fix might be to add
  a call of [47m[ACL2-numberp][0m to the hypotheses of your theorem.

  Fixed two bugs in [47m[apply$][0m: we now [47m[disable][0m the
  [executable-counterpart] of [47mgood-bye-fn[0m to prevent quitting ACL2
  entirely during a proof, and we avoid the error ``ACL2 cannot ev
  the call of non-executable function ANCESTORS-CHECK...'' by
  allowing attachments to be used when checking table guards (as
  discussed above).  Thanks to Dmitry Nadezhin for sending replayable
  examples that exhibited these bugs.

  Fixed [guard]s for functions [47m[enabled-runep][0m, [47m[enabled-numep][0m,
  [47mdisabledp-fn[0m, and [47mdisabledp-fn-lst[0m, thus eliminating bogus guard
  violations.  Thanks to Alessandro Coglio and Eric Smith for sending
  an example that illustrated the bug for [47menabled-runep[0m.  Technical
  note: this fix was made by replacing calls of [47mbounded-nat-alistp[0m
  (which is no longer defined) by calls of [47mnat-alistp[0m (which is newly
  defined).  We also made a corresponding tweak to the definition of
  [47menabled-numep[0m.

  Warnings labeled with ``Double-rewrite'' failed to take into account
  patterned [congruence] rules.  This has been fixed.  Thanks to
  Mihir Mehta for pointing out the problem with a helpful example.

  It is now possible, once again, to [monitor] rules of class
  [47m:[0m[47m[linear][0m.  This capability has (accidentally) been unavailable
  since Version 7.4.  Thanks to Dmitry Nadezhin for reporting the bug
  with a helpful example.

  It was possible for users to change the attachments to built-in
  functions [47mbadge-userfn[0m and [47mapply$-userfn[0m, which support the
  implementation of [47m[apply$][0m.  This is now prevented.

  For [47m[defequiv][0m, a [47m:doc[0m keyword argument was allegedly (in the
  documentation) supported but caused an ugly error.  The [47m:doc[0m
  keyword argument is now fully eliminated.  Thanks to Eric Smith for
  pointing out this issue.

  Fixed [47m:[0m[47m[pso][0m and related utilities [47m:[0m[47m[pso!][0m, [47m:[0m[47m[psof][0m, and [47m:[0m[47m[psog][0m, to
  avoid printing some error messages.  Thanks to Keshav Kini for
  sending us an example to bring this bug to our attention.  Also
  tweaked these utilities to avoid accumulating later event failure
  messages into the saved output for a previous proof attempt, and to
  avoid some bogus output when invoked before the first proof attempt
  of the session.

  When an invocation of [47m[defthmd][0m resulted in a macroexpansion error,
  the failure did not cause an error message to be printed.  This has
  been fixed.  Related tweaks improve error reporting, including a
  clearer error message when attempting to supply [47m:rule-classes nil[0m
  with [47mdefthmd[0m.  Thanks to Keshav Kini for reporting these issues.

  When [47m[defattach][0m was provided the argument [47m:skip-checks nil[0m, a hard
  error was signaled.  This has been fixed.

  The [47m[case-match][0m macro did not properly handle the [47m!sym[0m construct
  when the symbol, [47m!sym[0m, is not in the [47m\"ACL2\"[0m package.  This has been
  fixed.  Thanks to Alessandro Coglio for reporting this bug.

  Fixed handling of some guard violation error messages for built-in
  functions.  For example, the form [47m(apply$-lambda 3 nil)[0m produces a
  guard violation, but before this fix, the error message reported an
  implementation error.

  Fixed the [47m:[0m[47m[puff][0m command to avoid certain errors involving [local]
  [events].

  Redundancy notes could be seen during [47m[include-book][0m while loading
  the compiled file for a book.  These notes (along with, perhaps,
  some other output) have been eliminated.  Thanks to Eric Smith for
  pointing us to this problem with a reproducible example.

  We eliminated an obscure hard error mentioning the source function
  [47massume-true-false-if[0m, which could occur in the middle of a proof.
  Thanks to Dave Greve for pointing out this problem by sending us an
  illustrative example that we could run.

  It was possible to get a raw Lisp error from ill-formed calls of
  [47m[ec-call][0m not intended for execution, for example, [47m(defun foo (x)
  (non-exec (ec-call x)))[0m.  This has been fixed.

  Certain syntactic requirements are normally applied to function
  bodies but not to theorems.  However, these were being applied
  under calls of [47m[flet][0m.  Consider the following example.

    (thm
     (flet ((foo (x) (car x)))
       (foo (mv-nth 1 (mv x x)))))

  This was rejected with an error: ``The expected number of return
  values for (MV X X) is 1 but the actual number of return values is
  2.'' This has been fixed.  Thanks to Eric Smith for bringing this
  problem to our attention.

  A bug has been fixed in the logical definition of the function,
  [47mread-file-into-string2[0m, which supports the macro,
  [47m[read-file-into-string][0m.  Thanks to Keshav Kini for finding this
  bug and to Mihir Mehta for a query leading to Keshav's
  investigation.

  The previous release was supposed to include a new utility,
  [47m[checkpoint-summary-limit][0m, but that was missing.  Thanks to Keshav
  Kini for pointing this out (and supplying the expected
  implementation).

  Fixed a bug in the guard for built-in function [47mwarning1-cw[0m, which
  could be seen for example by evaluating the form [47m(warning$-cw
  'my-ctx \"The :REWRITE rule ~x0 loops forever.\" 'foo)[0m.  Thanks to
  Keshav Kini for bringing this issue to our attention.

  The definitions of the macros [47m[logand][0m, [47m[logior][0m, [47m[logxor][0m, and
  [47m[logeqv][0m were such that when any of these was applied to a single
  argument, the expansion was simply that argument.  For example,
  [47m(logand (foo a))[0m expanded to [47m(foo a)[0m.  These definitions failed to
  reflect the fact that in Common Lisp, an error may be signaled if
  that single argument does not evaluate to an integer.  For example,
  the following definition was admitted: [47m(defun f (x) (declare (xargs
  :guard t)) (logand x))[0m; yet a raw Lisp error was signaled when
  attempting to evaluate [47m(f 'x)[0m, in ACL2 built on Allegro Common
  Lisp.  This bug has been fixed: now, when any of these four macros
  is applied to a single argument, [47ma[0m, the expansion is [47m(the integer
  a)[0m.  Thanks to Eric Smith for bringing this bug to our attention.

  Fixed [47m:[0m[47m[args][0m to avoid hard ACL2 error when applied to [47mIF[0m and to
  provide a clearer error message for Common Lisp functions not in
  ACL2.  Thanks to Eric McCarthy for sending examples to point out
  these issues.

  A bug has been fixed that could cause an error when processing a
  legal [47m[flet][0m form, because the processing of a binding could
  interfere inappropriately with the processing of a subsequent
  binding, as in the following example.

    (defun f (x) x)
    (flet ((f (x) (cons x x))
           (g (x) (f x))) ; processed with bad binding of stobjs-out for f
      (g 3))

  Fixed an error message saying that ``It is illegal for supporters of
  DEFAXIOM events to receive attachments'' that failed during
  printing.  Thanks to Nathan Guermond for sending an example to
  point out this bug.


Changes at the System Level

  Fixed the use of `[47m<a href='URL'>...</a>[0m' so that if [47mURL[0m has the
  ampersand character in it, all will be well for both the web-based
  manual and text-based rendering (as when [47m:[0m[47m[doc][0m is used at the
  terminal or [47m[ACL2-doc][0m is used) provided that character is written
  as [47m&amp;[0m in the documentation string.  Previously, the web-based
  manual could fail to display the page for [47m&[0m in the documentation
  string, while with [47m&amp;[0m used, the web-based manual could display
  the page but the text-based rendering showed [47m&amp;[0m instead of
  simply [47m&[0m.  Thanks to Cuong Chau for pointing out that the topic
  [47m[double-rewrite][0m was not being displayed in the online manual (back
  when [47m&[0m was used in the URL in the documentation string).

  The \"clean\" target of \"make\" has been deprecated since ACL2 Version
  7.4 (released in March, 2017). Its replacement is target
  \"clean-lite\"; or, use target \"clean-all\" (or equivalently,
  \"distclean\") if you want a more thorough cleaning.

  (SBCL only) ACL2 has been updated so that it builds on recent SBCL
  versions.  In particular, the build was broken for SBCL 1.4.7, as
  SBCL changed the ``RDTSC'' timing capability used in [memoization].
  Thanks to Keshav Kini for help with this issue, which has been
  resolved in ACL2 source file [47mmemoize-raw.lisp[0m, as explained in the
  comment there about ``read-cycle-counter''.

  (CCL only) Raw Lisp error messages now mention the caller.  Thanks to
  Eric Smith for pointing out that this information wasn't being
  provided in the ACL2 loop even though it was being provided in raw
  Lisp.


EMACS Support

  Removed setting of the buffer coding system from [47memacs/emacs-acl2.el[0m.
  Thanks to Keshav Kini for suggesting this change.  This should
  avoid certain modifications of ``unusual'' characters when saving a
  file.


Experimental Versions

  The utility [47m[with-local-state][0m no longer causes an error in ACL2(p)
  with [parallel-execution] enabled.  Thus, neither do
  [47m[fmt-to-string][0m and related utilities, which call [47mwith-local-state[0m.")
 (NOTE-8-2
  (RELEASE-NOTES)
  "ACL2 Version 8.2 (May, 2019) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 8.1 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  [note-8-2-books] for a summary of changes made to the ACL2
  Community Books since ACL2 8.1, including the build system.  Also
  note that with each release, it is typical that the value of
  constant [47m[*ACL2-exports*][0m has been extended, and that some built-in
  functions that were formerly in [47m:[0m[47m[program][0m mode are now
  [guard]-verified [47m:[0m[47m[logic][0m mode functions.


Changes to Existing Features

  The built-in function [47m[fix-true-list][0m is now a macro that expands to
  a new built-in function, [47m[true-list-fix][0m, whose definition follows
  the efficient definition of [list-fix] that was in [community-book]
  [47mbooks/std/lists/list-fix.lisp[0m.  In that book, [list-fix] is now a
  macro that expands to [47mtrue-list-fix[0m.  The use of macro-aliases (see
  [add-macro-alias]) should generally make this change backward
  compatible for users of [47m[list-fix][0m.  Thanks to Mihir Mehta for
  taking the lead on implementing these changes and to Jared Davis
  for permission to integrate definitions and documentation from his
  Kookamara books into the ACL2 sources.

  Made some improvements pertaining to [47m[apply$][0m:

    * A quoted lambda object that may ultimately be passed as the
      ``function'' for a call of [47m[apply$][0m may now have a [47m[declare][0m
      form.  See also the discussion of [47mlambda$[0m below.

    * The macro [47m[warrant][0m no longer causes an error for the 800+ ACL2
      primitives that are built into the definition of [47m[apply$][0m.
      Instead, it simply avoids generating (needless) conjuncts for
      those primitives.

    * The rewriter can now evaluate ground terms that involve calls of
      [47m[apply$][0m or [47m[badge][0m on user-defined function symbols.  Note
      that correctness of such an evaluation depends on the truth of
      corresponding warrants, which will be [force]d if not known.

    * The event formerly named [47mdef-warrant[0m is now [47m[defwarrant][0m.  This event
      may now be [redundant]; hence [47m[defun$][0m may also be redundant.

    * The [47m:[0m[47m[args][0m command now prints the [badge] and [warrant] for a
      function, and it avoids printing a package prefix in the case
      of [unknown-constraints].

    * The optimization for caching ``tame compliant'' lambdas, introduced
      in the preceding release (see [note-8-1]), has been improved.

  It is no longer illegal to supply an abstract stobj as the so-called
  ``foundational'' (formerly ``concrete'') stobj in a [47m[defabsstobj][0m
  event.  Thanks to Sol Swords for initiating a discussion leading to
  this enhancement.

  Calls of the function [47msynp[0m were formerly required to result from
  macroexpansion of [47m[syntaxp][0m or [47m[bind-free][0m calls, or at least
  nearly so.  That restriction has been lifted, although the
  restrictions on calls of [47msynp[0m, [47msyntaxp[0m, and [47mbind-free[0m remain for
  hypotheses of rules of class [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, and
  [47m:[0m[47m[linear][0m, or resulting from evaluation of hypotheses of [47m:[0m[47m[meta][0m
  rules.  Thanks to Sol Swords for requesting this change, so that
  [47m[defevaluator][0m forms can include [47msynp[0m.

  For calls of [47m:[0m[47m[pso][0m and related utilities ([47m:[0m[47m[pso!][0m, [47m:[0m[47m[psof][0m, and
  [47m:[0m[47m[psog][0m), the Time reported in the summary is now the original
  time, not time related to running [47m:[0m[47m[pso][0m.

  The macro [47mdelete-assoc[0m has been renamed [47m[remove1-assoc][0m, to reflect
  more clearly that at most one pair is removed, and also for
  consistency with Common Lisp nomenclature (where ``delete''
  operations are generally destructive and ``remove'' operations are
  not).  Moreover, other functions and macros whose name has prefix
  [47m\"DELETE-ASSOC\"[0m have been similarly renamed to have prefix
  [47m\"REMOVE1-ASSOC\"[0m; for example, [47mdelete-assoc-eq[0m has been renamed
  [47mremove1-assoc-eq[0m.  (The old [47m\"DELETE-ASSOC\"[0m-based names still exist
  as macros --- indeed, as macro-aliases for their renamed versions
  (see [add-macro-alias]) --- but those may be deleted in the
  future.)  Analogous functions and macros have been introduced that
  remove all pairs with a given key, rather than only one; see
  [remove-assoc].  (These and related theorems formerly appeared in
  the [community-book], [47mbooks/centaur/misc/remove-assoc.lisp[0m.)
  Thanks to Alessandro Coglio for a query and subsequent discussion
  leading to these changes.

  The [system-utilities] [47mall-ffn-symbs[0m and [47mall-ffn-symbs-lst[0m are now
  defined just as macro abbreviations for calls of system utility
  [47mall-fnnames1[0m, thus eliminating some source code duplication.  We
  may deprecate [47mall-ffn-symbs[0m and [47mall-ffn-symbs-lst[0m in the future.

  The implementation of [47m[verify-termination][0m has been improved so that
  it no longer can generate (expand to) the form [47m(value-triple
  :redundant)[0m.  Redundancy is now handled for [47mverify-termination[0m by
  checking redundancy of the generated [47m[defun][0m form.  For an example
  that failed before this change, see [community-book]
  [47mbooks/system/tests/verify-termination/top.lisp[0m.

  Improvements have been made to the [summary] printed on conclusion of
  an event.  It had been possible to have duplicates in the
  [47m\"Hint-events\"[0m field of the summary; that has been fixed.  Also, the
  handling of [47m:[0m[47m[instructions][0m within [hints] has changed in the
  following two ways, to be consistent with the use of [47m:instructions[0m
  at the top level (rather than within [47m:hints[0m).  The [47m\"Rules\"[0m and
  [47m\"Hint-events\"[0m fields of the summaries incorporate information from
  calls of the [proof-builder].  Also, the [47m\"Hint-events\"[0m field no
  longer contains [47m(:CLAUSE-PROCESSOR PROOF-BUILDER-CL-PROC)[0m.

  A new variable, [47mTRACE-LEVEL[0m, may be used in calls of [47mtrace$[0m; see
  [trace$].  This replaces the use of the state global variable of
  the same name, which has been eliminated, thus avoiding an error
  involving [47mTRACE-LEVEL[0m that is mentioned below.

  [47m[Defun-sk][0m is now sensitive to the [default-verify-guards-eagerness],
  and guard verification is always delayed to near the end of the
  generated event to avoid failures due to the small theory present
  at [47mdefun[0m time.  Thanks to Alessandro Coglio for emails on leading
  to these improvements.  Some additional small tweaks have been made
  to [47mdefun-sk[0m, in particular to check that there are not two or more
  distinct values associated with [47m[xargs][0m keywords [47m:verify-guards[0m,
  [47m:non-executable[0m, or (even if not distinct) [47m:guard-hints[0m.

  The function [47m[integer-range-p][0m now uses a [47m[type][0m [declaration] in
  place of the [47m:[0m[47m[guard][0m, which may slightly improve efficiency.
  Thanks to Eric Smith for suggesting this possibility.

  The macro, [47m[thm][0m, may now be used in event contexts, in particular in
  calls of [47m[encapsulate][0m and [47m[progn][0m and in [books].  (See
  [embedded-event-form].)  Thanks to Ruben Gamboa for an email that
  led to this change.

  The [47m:[0m[47m[pf][0m command now does a more complete job of showing induction
  schemes for induction rules.  (Some corresponding code cleanup has
  also been done.)

  [Warnings] about using [enable]d rules have been improved.  Now, when
  using an [executable-counterpart] rule (which, admittedly, is
  unusual; it is equivalent to using the corresponding [definition]
  rule), the warning will correctly recommend disabling the
  definition rule instead of the executable-counterpart rule.

  The logical definition of [47mread-file-into-string2[0m (in support of
  [47m[read-file-into-string][0m) has been simplified, and no longer
  involves [untouchable] functions symbols.  Thanks to Mihir Mehta
  for a query that led to this enhancement.

  The built-in function [47m[take][0m now has a recursive definition, exactly
  along the lines of the old theorem [47mtake-redefinition[0m from the
  community book [47mbooks/std/lists/take.lisp[0m (written by Jared Davis);
  this theorem has now been removed.  The definition of [47mtake[0m uses
  [47m[mbe][0m, where the [47m:exec[0m component calls [47mfirst-n-ac[0m as before for
  execution efficiency.  We thank Mihir Mehta for providing this
  enhancement, including updates to the books.


New Features

  A new macro, [47m[loop$][0m, is an ACL2 version of the Common Lisp [47mloop[0m
  macro.

  A new construct, [47mlambda$[0m, may be used in place of [47mlambda[0m to be passed
  as the ``function'' for a call of [47m[apply$][0m.  The syntactic
  requirements for such uses of [47mlambda$[0m are much less strict than for
  quoted [47mlambda[0m objects; in particular, the body need not be in
  translated form (see [term]).

  A new macro, [47m[partial-encapsulate][0m, allows one to introduce
  constrained functions without specifying all of the [constraint]s.
  This functionality was already available using a trust tag, by way
  of a rather convoluted application of
  [47m[define-trusted-clause-processor][0m; however, [47m[partial-encapsulate][0m
  may be used without a trust tag.  See [partial-encapsulate], which
  in particular points to an example of typical usage, in
  [47mbooks/demos/partial-encapsulate.lisp[0m.  Thanks to Sol Swords for
  requesting such a capability.

  There is now, by default, a limit of 9 on the nesting depth of
  inductions; see [induction-depth-limit] and to modify this default,
  see [set-induction-depth-limit].

  A new [evisc-tuple], the [47m[brr-evisc-tuple][0m, controls printing inside
  the break-rewrite loop.  See [brr-evisc-tuple] and
  [set-evisc-tuple].

  Many of the [brr-commands] now abbreviate (``eviscerate'') by default
  using the new [47m[brr-evisc-tuple][0m (see above), and for each for those
  a corresponding command with suffix ``+'' print in full.  For
  example, such commands include [47m:path[0m and [47m:path+[0m; see [brr-commands]
  for the full list of commands.  Thanks to Stephen Westfold and
  others at the 2018 Developer's Workshop for discussing this issue.

  A new signature is legal for [47m[clause-processor][0ms, to support the
  return of rules and event names to be printed in the summary.  See
  [make-summary-data].

  [47m[Apply$][0m now handles functions that return multiple values.  This has
  widespread ramifications.  The structure of badges has changed.
  There is no longer an ``authorization-flag'' and there is now an
  ``out-arity'' slot in the badge.  See [badge].  Every badged
  non-primitive function symbol now has a warrant.  If [47mfn[0m is a
  warranted function symbol and returns more than one result then
  [47m(apply$ 'fn ...)[0m returns a list of the results, just as [47mfn[0m does in
  the logic.  See [47m[apply$][0m.  The warrant of a multi-valued function
  is just like that for a single-valued function except that
  [47m[mv-list][0m is used to coerce the output of the multi-valued function
  to a list.  See [47m[warrant][0m.  All [47mLAMBDA[0m objects and [47m[lambda$][0m
  expressions must be single-valued, but can use multi-valued
  functions to compute that value.


Heuristic and Efficiency Improvements

  [47m[Make-event][0m expansions have often been reduced in size.  (Technical
  note: [47mrecord-expansion[0m has been inserted only on expansions done
  directly under [47m[encapsulate][0m events, and some changes have also
  been made in how and when [local] events are elided from
  expansions.)  The reduction in total sizes of [47m.cert[0m files for a
  complete (``everything'') regression was 8.8%, though in some cases
  the reduction was substantially larger: for example, the size of
  [47mbooks/centaur/fty/tests/deftranssum.cert[0m was reduced from
  22,474,113 bytes to 16,910,530 bytes, a reduction of nearly 25%.

  A tweak to the rewriter can significantly speed up the use of
  hypothesis-free [meta] rules on large terms.  Thanks to Mertcan
  Temel for sending an example that motivated this change, whose time
  was cut from 67 seconds to 19 seconds.

  Some small optimizations have been made for the generation of
  executable-counterpart (so-called ``*1*'') code (see [evaluation]).

  It has long been the case that certain prover routines, including
  handling of output from [meta] functions, transformed results into
  so-called ``quote-normal form'', where for example the [term] [47m(cons
  '3 '4)[0m is replaced by [47m(quote (3 . 4))[0m.  Now, that transformation
  avoids recurring inside calls of [47m[hide][0m.  We thank Mertcan Temel,
  who had a class of examples that motivated this change.  One such
  example took 856.27 seconds of `prove' time before this change, but
  only 270.14 seconds after this change, thus eliminating 68.5% of
  the time.

  Proofs involving very large terms could be slowed down by checking
  those terms for calls of [47m[if][0m, in support of reporting [splitter]s
  of type if-intro.  That check is now limited by avoiding subterms
  that are calls of [47m[hide][0m.  Thanks to Mertcan Temel for supplying
  examples, one of which exhibited a proof time of 302.06 seconds
  that was reduced to 123.57 seconds with this change, and thanks to
  Sol Swords and Alessandro Coglio for helpful comments on possible
  enhancements.


Bug Fixes

  Fixed a bug, probably a soundness bug (though we haven't tried to
  prove [47mnil[0m by exploiting it).  The bug is in the computation of the
  ``immediate-canonical-ancestors'' of a function symbol, which is
  used in the implementations of [memoization] and [47m[defattach][0m, as
  well as in interactions between attachments and both [47m[defaxiom][0m
  events and [47m:[0m[47m[meta][0m rules.  Thanks to Sol Swords for pointing out
  this bug and presenting a helpful example.

  Fixed three [proof-builder] bugs:

    * Fixed the proof-builder command, [47mdv[0m (see [ACL2-pc::dv]), for diving
      into calls of [47m[list][0m and [47m[list*][0m.

    * Fixed a bug in the proof-builder command, [47mgeneqv[0m.  Thanks to Shilpi
      Goel for reporting this bug with an example.

    * The proof-builder numeric ``diving'' commands [47m1[0m, [47m2[0m, [47m3[0m, etc. --- and
      more generally, the [47mdv[0m command --- were broken when the current
      subterm is of the form [47m(if 't .. ..)[0m.  This has been fixed.
      Thanks to Keonho Lee for reporting this bug.

  Eliminated a hard error labeled as ``Implementation error'' that
  could occur when submitting a [47m:[0m[47m[congruence][0m rule during the second
  pass of [47m[encapsulate][0m or the local incompatibility check in Step 3
  of [47m[certify-book][0m.  The error occurred when the equivalence
  relation of the rule had been defined locally, hence was missing
  during that second pass or local incompatibility check.  Now, a
  useful ordinary (``soft'') error occurs, with a useful message.
  Thanks to Nathan Guermond for reporting this bug with a helpful
  example.

  It had been possible to enter an infinite loop after certain errors
  involving [wormhole]s and state global variables; now, a clean
  error occurs instead.  The specific error motivating this change
  involved the combination of both tracing certain system functions
  (for example, [47mpop-accp-fn[0m) and calling [47m[accumulated-persistence][0m.
  That specific error has been eliminated by the change to [47m[trace$][0m
  involving variable [47mTRACE-LEVEL[0m that is mentioned in an item above.

  Fixed a bogus error produced by [47mdefchoose[0m forms containing unused
  variables with [47mignorable[0m declarations.  Also eliminated an extra
  warning in the case of more than one bound variable with at least
  one of them unused, which could occur after [47m(set-ignore-ok :warn)[0m
  has been evaluated.  Thanks to Sol Swords for finding these bugs
  and for supplying code that we installed to fix them.

  Fixed an inefficiency in book certification due to calling
  [47m[fast-alist-free-on-exit][0m on the wrong objects.  Thanks to Sol
  Swords for pointing out this problem.

  The [47mmake TAGS[0m command could fail to do a proper check that the [47metags[0m
  program is installed, resulting in a failure when attempting to
  build an ACL2 executable.  This has been fixed.  Thanks to Johannes
  Altmanninger for reporting this problem in GitHub Issue #955.

  When a function that calls [47m[apply$][0m (or [47m[apply$-userfn][0m, [47m[badge][0m, or
  [47m[badge-userfn][0m) has been [memoize]d with a non-[47mnil[0m value for
  argument [47m:aokp[0m, its memo table may need to be flushed when removing
  a [badge].  (Such removal typically occurs by undoing a call of
  [47m[defun$][0m or [47m[defwarrant][0m, perhaps because they are [local] to an
  [47m[encapsulate][0m event or to a book.)  However, such flushing was not
  being done.  That has been fixed.  See new [community-book]
  [47mbooks/system/tests/apply-with-memoization.lisp[0m for examples.  Among
  the changes made to the source files that are related to this fix:
  the ``Essay on Memoization with Attachments'' has been enhanced to
  discuss the implementation of such flushing; and functions
  [47mdoppelganger-apply$-userfn[0m and [47mdoppelganger-badge$-userfn[0m (formerly
  called [47mconcrete-apply$-userfn[0m and [47mconcrete-badge$-userfn[0m), which
  are still not advertised, are now introduced with
  [47m[partial-encapsulate][0m (hence have unknown constraints) and are now
  [untouchable].


Changes at the System Level

  The [documentation] topic, [system-utilities], is now about only
  utilities that pertain to the ACL2 system implementation, rather
  than arbitrary built-in utilities.  Thus, each of the following now
  has its own topic, rather than being described in
  [system-utilities].  (Thanks to Alessandro Coglio for suggesting
  this reorganization.)

    * [47m[alist-keys-subsetp][0m

    * [47m[alist-to-doublets][0m

    * [47m[cons-count-bounded][0m

    * [47m[evens][0m

    * [47m[keyword-listp][0m

    * [47m[merge-sort-lexorder][0m

    * [47m[odds][0m

    * [47m[packn][0m

    * [47m[packn-pos][0m

    * [47m[pairlis-x2][0m

    * [47m[pairlis-x1][0m

  Documentation pertaining to [47m[apply$][0m and related topics has been
  extended significantly.

  (GCL only) Eliminated compiler output (by setting GCL raw Lisp
  variables [47m*compile-verbose*[0m and [47m*load-verbose*[0m to [47mnil[0m).

  A new documentation topic, [efficiency], suggests some ways to speed
  up proofs and evaluation.  The ACL2 community is encouraged to
  extend (and more generally, improve) this topic!

  (LispWorks only) Bytes allocated are now reported in LispWorks
  (formerly, only in CCL and SBCL) by [47m[time$][0m and [47m[memsum][0m.

  A new documentation topic, [make-event-example-3], explains the new
  implementation of [47m[thm][0m, thus providing insight into several common
  implementation techniques used with [47m[make-event][0m.

  A new documentation topic, [rule-classes-introduction], provides a
  basic guide to which sorts of rules to create from your theorems.
  Thanks to Mihir Mehta for encouraging the development of this
  topic.

  Fixed ``[47mmake STATS[0m'' (which is invoked by ``[47mmake DOC[0m'') to generate a
  result file [47mdoc/acl2-code-size.txt[0m that gives accurate statistics
  on code size on Linux.  (The relevant [47mgrep[0m commands in file
  [47mdoc/create-acl2-code-size[0m needed the [47m-a[0m option on Linux.)

  Updated the CCL installation instructions formerly at :DOC
  ccl-updates.  The topic is now [ccl-installation].  This now
  replaces the installation instructions file [47minstallation/ccl.html[0m;
  thus, the ACL2 community is now welcome to improve these
  instructions.  Thanks to Eric Smith for discussion that led to this
  change and to Keshav Kini and Alessandro Coglio for helpful
  feedback.

  The makefile target [47mcertify-books[0m has been deprecated in both
  [47mGNUmakefile[0m and [47mbooks/GNUmakefile[0m.  Thanks to the acl2-books email
  list (in particular we got feedback from Alessandro Coglio, Shilpi
  Goel, David Rager, Eric Smith, and Sol Swords, all helpful) for
  working through this issue.

  A message is now printed when loading file [47m~/acl2-init.lsp[0m at
  startup.


EMACS Support

  Fixed the [ACL2-doc] browser so that it can handle topic names with
  the single-quote ([47m'[0m) and comma ([47m,[0m) characters, by escaping them.

  Fixed Emacs support for the [proof-builder] dive command (see
  [ACL2-pc::dive]), [47mcontrol-t control-d[0m, to eliminate trailing zeros,
  since those are (and have been) disallowed by that command.

  A new [47m[ACL2-doc][0m command is the question-mark character ([47m?[0m), which
  goes to a page with one-line command summaries.  Thanks to Warren
  Hunt for a request leading to this enhancement.


Experimental Versions")
 (NOTE-8-3
  (RELEASE-NOTES)
  "ACL2 Version 8.3 (April, 2020) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 8.2 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  [note-8-3-books] for a summary of changes made to the ACL2
  Community Books since ACL2 8.2, including the build system.  Also
  note that with each release, it is typical that the value of
  constant [47m[*ACL2-exports*][0m has been extended, and that some built-in
  functions that were formerly in [47m:[0m[47m[program][0m mode are now
  [guard]-verified [47m:[0m[47m[logic][0m mode functions.


Changes to Existing Features

  It is now permitted for an evaluator to be ancestral in a
  metafunction or clause-processor.  See [evaluator-restrictions], or
  see the source code comment ``Essay on Correctness of Meta
  Reasoning'', for discussion of the remaining restrictions.  Thanks
  to Sol Swords for requesting this improvement and for many helpful
  discussions.  Moreover, he found a bug in a proof in the above
  Essay, which has been fixed; he made a key observation that led to
  completion of that fix.  Also thanks to Rob Sumners for helpful
  discussions.

  The [accumulated-persistence] utility no longer overcounts
  accumulated frames due to nested (recursive) rule applications.
  Although that shortcoming was documented, it was unfortunate and we
  thank Sol Swords for an email that nudged us into making this
  improvement and provided helpful insight, and Eric Smith for
  suggesting this improvement more than 10 years ago (!).

  In a (new-style) signature, any symbol whose [47m[symbol-name][0m is [47m\"*\"[0m now
  designates a non-[stobj] argument.  Formerly, only the symbol [47m*[0m in
  the [47m\"ACL2\"[0m package could be used in that way.  Thanks to Jared
  Davis for suggesting (in 2007!) that we consider such a change.

  More functions can now be given [warrant]s.  In particular: the
  requirement of a natural number measure for recursive definitions
  has been relaxed to allow lexicographic combinations of natural
  numbers as defined by the [47mllist[0m function in the Community Books at
  [47mbooks/ordinals/[0m, and it is possible to warrant some functions that
  use local [stobj]s as long as they don't call [47m[apply$][0m.  See
  [defwarrant].

  The function [47m[symbol-name-lst][0m is now a [guard]-verified [logic]-mode
  function (formerly it was a [program]-mode function).  Thanks to
  Alessandro Coglio for suggesting that it might be good to document
  this function, which led us to this change (and to its being
  documented).

  The pattern language for the macro, [47m[case-match][0m, now includes the
  case [47m(quote~ sym)[0m, where [47msym[0m is a symbol and this case matches any
  symbol whose [47m[symbol-name][0m is [47m(symbol-name sym)[0m.

  The following symbols, when used in special syntactic roles in the
  macro [47m[loop$][0m, may be in any package: [47mfor[0m, [47min[0m, [47mon[0m, [47mfrom[0m, [47mto[0m, [47mby[0m,
  [47mof-type[0m, [47mwhen[0m, [47muntil[0m, [47msum[0m, [47mcollect[0m, [47malways[0m, [47mthereis[0m, and [47mappend[0m.
  Thanks to Mertcan Temel for requesting this enhancement.

  [47m:Expand[0m [hints] now act more reliably for [equality-variants], by
  expanding away [guard-holders].  Thanks to Sol Swords for supplying
  this enhancement and sending the following example that works now
  but formerly failed:

    (defthm member-of-cons
      (equal (member x (cons x y)) (cons x y))
      :hints((\"Goal\" :in-theory (disable member)
              :expand ((member x (cons x y))))))

  An analogous improvement has been made for [47m:by[0m, [47m:use[0m, and [47m:hands-off[0m
  hints.

  The macros [47m[defequiv][0m, [47m[defrefinement][0m, and [47m[defcong][0m now conform to
  the following principle discussed in a new [documentation] topic,
  [packages-for-generated-symbols]: ideally, utilities generate
  symbols in the [47m[current-package][0m, at least by default.  These three
  macros now have a [47m:package[0m keyword argument whose default value is
  [47m:current[0m; with this value the macros conform to the above
  principle.  See their [documentation] topics.  To get the previous
  behavior, use the [47m:legacy[0m value.  (Another way to deal with
  failures caused by this change may be to fix packages when
  referring to generated symbols, such as changing [47macl2::x-equiv[0m to
  [47mx-equiv[0m.)  In particular, the [47m:legacy[0m option was used to update
  definitions in the [community-books] for macros that generate
  [47m[defcong][0m forms.  Also, all three macros now do some error-checking
  (rather than leaving that entirely to the generated [47m[defthm][0m form),
  and the unsupported [47m:doc[0m keyword argument has been removed from
  these macros.  Thanks to Pete Manolios for suggesting all of these
  changes, and for providing not only implementations but also
  modifications to the [community-books].

  The translation of a term [47m(and t u0)[0m is [47m(if 't u1 'nil)[0m, where [47mu1[0m is
  the translation of [47mu0[0m.  That term, [47m(if 't u1 'nil)[0m, is now
  generally displayed to the user (``[untranslate]d'') as [47m(and t u0)[0m,
  but formerly it was displayed as [47mu0[0m, which could be confusing.
  Thanks to Stephen Westfold, who sent an example showing how, when
  using the [proof-builder]'s [47mREWRITE[0m command to replace a subterm [47ma0[0m
  by [47mt[0m in a term [47m(and a b)[0m could lead to confusion, since the
  resulting [47m(and t b)[0m was printed only as [47mb[0m.  Note: For Boolean
  contexts, the analogous change was also made for terms [47m(and u0 t)[0m.

  It no longer causes an error to call [47m[trans-eval][0m on an expression
  that references a locally-bound [47m[stobj][0m, that is, one bound by
  [47m[with-local-stobj][0m or [47m[stobj-let][0m.  The user is responsible for
  understanding that when calling [47mtrans-eval[0m, all stobj variables in
  the supplied expression refer to globally-bound stobjs, that is,
  stobjs stored in the [47muser-stobj-alist[0m field of the ACL2 [47m[state][0m.
  See the new documentation topic,
  [trans-eval-and-locally-bound-stobjs], for relevant discussion.
  (Another topic, [user-stobjs-modified-warnings], may also be
  helpful for understanding the interaction of [47mtrans-eval[0m with
  stobjs.)  Thanks to Sol Swords for suggesting this change and
  convincing us of its suitability.

  The [47m[defstobj][0m event now supports [stobj]s with fields that are hash
  tables in raw Lisp but are represented logically as association
  lists.  Thanks to Sol Swords for providing not only the design but
  also the implementation, which was moved from community book
  [47mbooks/add-ons/hash-stobjs.lisp[0m into the ACL2 sources (with small
  modifications to both the new code and existing code).  That book
  still provides lemmas that may be helpful for reasoning about
  hash-table fields, as well as some tests.  See also [47m[defstobj][0m.

  Added suitable [guard]s, with custom error messages, to
  [47m[add-invisible-fns][0m and to [47m[remove-invisible-fns][0m.  Also removed
  confusing messages for each in the case of redundancy.  Thanks to
  Pete Manolios for pointing us to a bug in the documentation for the
  latter (which we have fixed), which led us to the addition of
  guards.

  The notion of [3muntouchable[0m macro is no longer directly supported.
  Specifically: the form [47m(push-untouchable SYM t)[0m is now illegal if
  [47mSYM[0m is already the name of a macro; and after this call of
  [47m[push-untouchable][0m it is illegal to define [47mSYM[0m as a macro.
  However, a macro can be made effectively untouchable by defining it
  with the new utility, [47m[defmacro-untouchable][0m.  Note that the
  alleged support for untouchable macros was already incomplete, as
  explained in an example in the form [47m(defxdoc note-8-3 ...)[0m in
  [community-book] [47mbooks/system/doc/acl2-doc.lisp[0m.

  The [event] macro, [47m[thm][0m, is now treated like [47m[defthm][0m in the
  following way: if keyword [47m:hints[0m is supplied, then the hints are
  checked syntactically when skipping proofs (see [ld-skip-proofsp])
  except during [47m[include-book][0m or the second pass of [47m[encapsulate][0m.
  For example, evaluation of the form [47m(thm (equal x x) :hints
  bad-hints)[0m now causes an error after evaluating
  [47m(set-ld-skip-proofsp t state)[0m, while before this change, it did
  not.

  The default slow-alist-action (see [slow-alist-warning]) is now
  [47m:break[0m instead of [47m:warning[0m in ACL2.  (It remains [47m:warning[0m in
  ACL2(p); see [unsupported-waterfall-parallelism-features].)

  For a user-defined [47m:[0m[47m[induction][0m rule to be applied, it is no longer
  required for the induction scheme associated with a recursive
  definition to be enabled.  For an example of the effect of this
  change, see the [community-book],
  [47mbooks/system/tests/induction-rule-with-disabled-scheme.lisp[0m.
  Thanks to Pete Manolios for reporting this issue, including the
  sending of the events in that book.  Also see [induction] (as that
  documentation has been updated).

  An undocumented kind of [fake-rune] is no longer reported by
  [47m[show-accumulated-persistence][0m.  Thanks to Eric Smith for bringing
  this issue to our attention.

  The algorithm for removing [guard-holders] has been modified to avoid
  diving into calls of [47m[hide][0m.  However, it is possible to obtain the
  former behavior; see [guard-holders].

  Since its earliest years, ACL2 uses evaluation to simplify ground
  terms (terms with no free variables).  ACL2 would sometimes
  generate a call of [47m[hide][0m around a term that fails to evaluate
  because of an attempt to call a constrained function.  Now, that
  call incorporates a comment saying which constrained function is
  responsible for the failure.  See [comment].  Also see [hide] for
  how to fix proof failures caused by this new behavior by using
  [47m:expand[0m [hints] or even by turning off this new behavior using
  [47m[defattach][0m.  Thanks to Rob Sumners (in 2003), Francisco J.
  Martin-Mateos (in 2004), and Anna Slobodova (in 2005), perhaps
  among others, for discussions leading to this enhancement.

  Both [47m:[0m[47m[puff][0m and [47m:[0m[47m[puff*][0m have been made more robust.  Related
  changes include:

    * A new table, [47mpuff-included-books[0m, generally prevents the same book
      from being puffed more than once.

    * Book directories are tracked more carefully, which can prevent
      errors.

    * We no longer allow [47m:puff*[0m to puff non-trivial [47m[encapsulate][0m events.
      (For a technical discussion of reasons for this change, see
      comments in function [47mpuffed-command-sequence[0m in ACL2 source
      file [47mld.lisp[0m.)

    * Changes to the [47m[ACL2-defaults-table][0m no longer persist outside the
      scope of a puffed [47mencapsulate[0m event.

    * A [47m[theory-invariant][0m event no longer stores the event [47m(in-theory
      (current-theory :here))[0m in the [world].


New Features

  A new [47m[xargs][0m keyword, [47m:guard-simplify[0m (default [47mt[0m), controls certain
  simplifications that may be applied to the guard conjecture while
  generating the initial goal.  Setting it to [47mnil[0m skips all
  simplifications that depend on the set of currently [enable]d
  rules.  See [verify-guards].  Thanks to Sol Swords for designing
  this feature and providing its implementation, along with
  documentation and corresponding adjustments to the community books.

  Now [47m[defstub][0m accepts the same keywords as [47m[encapsulate][0m, both for
  the new-style signatures and for the old-style signatures.  Thanks
  to Alessandro Coglio for suggesting and implementing this
  enhancement.

  New function [47m(maybe-flush-and-compress1 name ar)[0m calls
  [47m(flush-compress name)[0m and then returns [47m(compress1 name ar)[0m, except
  that all this is skipped if the given array is already compressed.

  A new utility, [47m[swap-stobjs][0m, does what its name suggests: it swaps
  [stobj]s.  Thus, if [47mst1[0m and [47mst2[0m are stobjs then after returning
  from execution of a call [47m(swap-stobjs st1 st2)[0m of [47mswap-stobjs[0m, the
  global value of stobj [47mst1[0m will be the old value of [47mst2[0m and the
  global value of stobj [47mst2[0m will be the old value of [47mst1[0m.  See
  [swap-stobjs].  Thanks to Sol Swords for requesting this feature
  and for helpful discussions about it.

  By invoking [47m(set-absstobj-debug :ignore)[0m, which requires an active
  trust tag (see [defttag]), one can defeat invariance checks for
  abstract stobj fields that otherwise are protected by specifying
  [47m:protect t[0m (or by using the [47m:protect-default[0m keyword to get that
  effect).  See [defabsstobj].  Thanks to Sol Swords for suggesting
  consideration of adding some such capability.  In a few preliminary
  tests we found an average drop of about 3.5% in the time it took to
  run the tests.

  It is now permitted to define functions in which recursive calls
  occur from inside [47m[loop$][0m statements.  See [47m[loop$-recursion][0m.  Such
  functions do not automatically suggest induction schemes.
  Furthermore, care must be taken when formulating inductively
  provable theorems about such functions.  See
  [loop$-recursion-induction] and [47m[definductor][0m.

  You can now change the second line in the startup banner for a GitHub
  version of ACL2 obtained between releases.  See [startup-banner].
  Thanks to Andrew Walter for requesting this enhancement.


Heuristic and Efficiency Improvements

  ACL2 keeps a complete list of all the runes in the tau database (see
  [introduction-to-the-tau-system]).  Formerly this list was
  duplicate-free, but that is no longer the case.  As a result we
  have seen some faster performance; in particular, this change has
  cut 17% from the time to include the community book,
  [47m\"centaur/sv/top\"[0m.

  Made slight efficiency improvement for [table] update ([47m:put[0m) events.

  Improved efficiency of the maintenance of [stobj]-related arrays (the
  so-called stobj accessor arrays) by using the new function,
  [47m[maybe-flush-and-compress1][0m.  That code is related to printing
  stobj field accesses using field names rather than indices.  (For
  background on printing untranslated terms, see [term].)  For
  example, after evaluating the form [47m(defstobj st fld)[0m, the form

    (thm (equal (fld st) xxx)
         :hints ((\"Goal\" :in-theory (disable nth))))

  produces the (untranslated) goal [47m(EQUAL (NTH *FLD* ST) XXX)[0m rather
  than [47m(EQUAL (NTH 0 ST) XXX)[0m.  A further change has been to reduce
  the frequency of ensuring that those [arrays] are up-to-date.
  (Technical note: this latter change is to source function
  [47mupdate-wrld-structures[0m, which has an explanatory comment, including
  an example of a 2.6% time reduction.)

  Improved the speed of [theory] updates by avoiding repeated length
  computations.  As a result, we have seen about a 5% time reduction
  on MacOS, and between 3% and 4% on Linux, for executing the form,
  [47m(include-book \"centaur/sv/top\" :dir :system)[0m.

  The definition of the macro [47m[ec-call][0m has been tweaked to speed up
  compilation in some cases when the host Lisp is SBCL.  In
  particular, for admitting the definition of [47mapply$-prim[0m in
  [community-book] [47mbooks/projects/apply-model-2/apply-prim.lisp[0m with
  host Lisp SBCL, we have seen the time decrease from 1294.33 seconds
  to 8 seconds.

  A heuristic for ``lazy'' rewriting of calls of [47mmv-nth[0m has been made
  much more efficient in some cases.  Thanks to Sol Swords for
  investigating performance issues leading him to implement such a
  change, and for making modifications to [community-books] so that
  they continue to certify after the change.  Those interested in
  implementation details may start with source function
  [47msimplifiable-mv-nth1[0m.

  The raw Lisp representation of [stobj]s has been improved to avoid
  some indirection in two ways: a scalar field (one that is not an
  array or hash table) with non-trivial type had been wrapped in a
  one-element array, but no longer; and if there is only one field,
  and it is an array or hash table, then that field is the entire
  stobj.  (The first change is however avoided when the host Lisp is
  GCL.)  Thanks to Warren Hunt and Sol Swords for suggesting these
  changes.  Technical note: in the course of making these changes, a
  bug was exposed in source function [47mraw-ev-fncall[0m; that has been
  fixed.

  Reduced the computation and consing for [theory] management, which
  might reduce time by a percent or two when including some books.
  (Technical note.  The idea was to expand the cases in which the use
  of [47m[compress1][0m is replaced by more efficient code.  That code is
  specific to enabled structures and may be found in ACL2 source
  function [47mupdate-enabled-structure-array[0m.  We also arranged, in
  [47mload-theory-into-enabled-structure[0m, to double the array size when
  that exceeds the expansion by a minimal suitable multiple of 500.)

  Changed how [compound-recognizer] rules are stored in the logical
  [world] (per function symbol, rather than in a single alist), which
  a few experiments suggest might reduce time by a couple percent or
  so.

  A tweak was made to how properties are ordered when stored in the
  ACL2 logical [world], which experiments show provides small
  speed-ups.  (Technical note: the change is to constant
  [47m*current-acl2-world-key-ordering*[0m, and also, functions
  [47m[symbol-class][0m and [47m[logicp][0m avoid calling [47m[getprop][0m for the symbol,
  [47mcons[0m.)

  ACL2 now avoids [summary] calculations during [47m[include-book][0m.  We
  have seen this change cut more than 9% of the time for the event
  [47m(include-book \"centaur/sv/top\" :dir :system)[0m.

  We now avoid translation of [47m[default-hints][0m for termination proofs
  during [47m[include-book][0m.  We have seen this change cut more than 4%
  of the time for the event [47m(include-book \"centaur/sv/top\" :dir
  :system)[0m.

  ACL2 now saves, in [certificate] files, the translated bodies of
  [47m[defun][0m and [47m[defthm][0m [events].  (See [term] for a discussion of
  translated terms.)  This can speed up [47m[include-book][0m; for example,
  we have measured approximately a 3% reduction in time for the
  event, [47m(include-book \"centaur/sv/top\" :dir :system)[0m, but with a
  space trade-off of about 41% more bytes allocated.  (Implementation
  note: the relevant algorithms and code are discussed in an expanded
  version of the Essay on Cert-data in the ACL2 source code.)  Thanks
  to Eric Smith for pointing out a bug (which we then fixed) in a
  preliminary implementation of this feature.

  Some stack overflows may be avoided by a change to a built-in system
  function, [47mcons-count-bounded-ac[0m, so that it is now tail recursive
  as it CDRs the list, rather than as it takes the CAR.  Thanks to
  Shilpi Goel for reporting the problem with an example and to Sol
  Swords for suggesting this fix.  That example exhibited a second
  stack overflow, due to a built-in memoized system function that is
  no longer called when computing a call of the built-in system
  function, [47mpkg-names[0m.

  The second pass of [47m[encapsulate][0m now uses [fast-alists] when
  calculating new triples in the logical [world] (in ACL2 system
  function [47mnew-trips[0m).  We have seen this change result in cutting
  the time by 4.7% and the bytes allocated by 34% for including the
  community book, [47m\"centaur/sv/top\"[0m.

  Computation of the [guard] proof obligation has been sped up in some
  cases involving evaluation of ground terms (terms without free
  variables).  Thanks to Warren Hunt for sending us an example that
  prompted us to make this change.


Bug Fixes

  As noted in the documentation for [lemma-instance], ACL2 may avoid
  proving some constraints required for [functional-instantiation]
  that were previously proved.  There was such support even in the
  case that the previous proof was done on behalf of a [47m[defattach][0m
  event, but that support has been made more complete (by keeping
  more functional substitutions in canonical form).

  A hard Lisp error has been fixed that could occur (probably only
  rarely) after adding rules of class [47m:[0m[47m[definition][0m that introduce
  recursion.

  The function [47m[meta-extract-formula][0m could return a non-trivial value
  (i.e., not [47m'T[0m) when applied to a [program]-mode function.  We thank
  Sol Swords for reporting this bug with a proof of [47mnil[0m that
  exploited it.  This soundness bug has been fixed.  That work led us
  to fix the following related bugs (which could also be soundness
  bugs, though we have not checked).  First, the function
  [47m[fncall-term][0m could similarly return a non-trivial value when
  applied to a program-mode function.  Second, the utility [47m[mfc-rw][0m,
  as well as other such [47mmfc-xx[0m utilities in support of
  [extended-metafunctions] and [47m[meta-extract-contextual-fact][0m, could
  be called on terms containing program-mode function symbols.

  Eliminated an error occurring when attempting to compute the guard
  proof obligation for a constrained function, in particular, when
  using the [47m:[0m[47m[gthm][0m utility on such a function (also see
  [guard-theorem]).  Thanks to Alessandro Coglio for pointing out
  this bug and for noting that [47mt[0m could be a reasonable result for the
  guard theorem in such cases.

  Fixed ACL2 raw Lisp error caused by [add-default-hints!].  Thanks to
  Pete Manolios for debugging this problem.

  Fixed a bug in the [proof-builder] command [47mapply-linear[0m (and its
  abbreviation, [47mal[0m), which was making it impossible to save an event
  after an interactive session that includes such a command.  Thanks
  to Mihir Mehta for bringing this bug to our attention and sending
  an example.

  Fixed a bug in [47m[defun-sk][0m, which was generating a [47m[verify-guards][0m or
  [47mverify-guards?[0m event with [47m:guard-hints[0m instead of [47m:hints[0m.  Thanks
  to Alessandro Coglio for reporting this bug and providing the fix.

  The use of [47m:stack :pop[0m in the macro [47m[with-output][0m failed to restore
  [gag-mode] properly.  For example, the use of [47m(with-output :stack
  :push :gag-mode nil (with-output :stack :pop <form>))[0m failed to run
  [47m<form>[0m with the existing value for gag-mode (default: [47m:goals[0m).
  Thanks to Mihir Mehta for a query that led us to make this fix.
  Technical note: state global [47minhibit-output-lst-stack[0m is now a list
  of pairs [47m(inhibit-output-lst . gag-mode)[0m; see [with-output].

  The [proof-builder]'s [47mDV[0m command was broken for expressions of the
  form [47m(if t term1 term2)[0m; for example, [47m(verify (if t x y))[0m followed
  by [47m1[0m, [47m2[0m, or [47m3[0m caused a raw Lisp error.  Thanks to Stephen Westfold
  for bringing this bug to our attention and pointing out the fix.

  We fixed a bug in the implementation of [47m[encapsulate][0m that could
  cause a hard ACL2 error (``Unexpected expansion-alist ... for
  second pass of encapsulate'').  Thanks to Pete Manolios for sending
  an example that exhibited this bug.  (A slightly simplified version
  of his example may be found in a comment in the definition of
  function [47mencapsulate-pass-2[0m, ACL2 source file [47mother-events.lisp[0m.)

  [47m[Defstobj][0m now provides a suitable error message, instead of an
  implementation error, when new names are duplicated after renaming.
  Here are examples that now have improved error messages.

    (defstobj st x :renaming ((create-st x)))
    (defstobj st fld :renaming ((fld create-st)))
    (defstobj st fld1 fld2 :renaming ((fld1 fld) (fld2 fld)))

  We fixed an obscure error message when attempting to [memoize] either
  [47mIF[0m or [47mRETURN-LAST[0m, and we improved the [memoize] documentation to
  mention these and other restrictions on what can be memoized.

  Fixed erroneous [type] declarations in array copying functions.
  (Technical notes.  (1) It's not clear that these bugs have ever had
  any effect.  (2) Those source code functions have been renamed by
  dropping their [47m\"stobj-\"[0m prefixes from [47mstobj-copy-array-xxx[0m, now
  that one of them has application to other than stobjs, in new code
  mentioned above for enabled structures.)

  Fixed the process of translating the [type-spec], [47mstandard-char[0m, into
  a [term].  For example, the following definition failed but now
  succeeds:
  [47m(defun foo (x) (declare (type standard-char x)) (cons 3 x))[0m.

  Fixed a bug that could cause the wrong [stobj] to be displayed by
  [47m[print-gv][0m, when congruent stobjs with a single bit-array field are
  involved.  See a comment in ACL2 source function
  [47mapply-user-stobj-alist-or-kwote[0m for an example of this bug.

  When including a book that is uncertified because of a stale
  [certificate] file, ACL2 was inappropriately using information
  about [type-prescription] rules (specifically, those computed by
  the system at definition time) that was stored in that certificate.
  This has been fixed, thanks to a bug report from Eric Smith about a
  related feature mentioned above, on saving translated bodies in
  certificate files.  Moreover, the relevant system function,
  [47minclude-book-fn1[0m, has been modified to do a better job of ignoring
  certificate files of uncertified books.

  The utility [47mset-saved-output[0m has been badly broken for years, but
  without complaints (other than from one of us shortly before the
  release), suggesting that it hasn't been directly called by users.
  So we have eliminated it.


Changes at the System Level

  The makefile target [47mcertify-books[0m has been removed from [47mGNUmakefile[0m
  and [47mbooks/GNUmakefile[0m.  It was deprecated in the preceding release,
  where we thanked the acl2-books email list (in particular we got
  feedback from Alessandro Coglio, Shilpi Goel, David Rager, Eric
  Smith, and Sol Swords, all helpful) for working through this issue.

  The keyword [47m:ACL2[0m is now a member of the Lisp global, [47m*features*[0m,
  which allows other programs to use read-time conditionals [47m#+acl2[0m /
  [47m#-acl2[0m to indicate the presence or absence of ACL2.  Thanks to
  Andrew Walter for suggesting that this might be useful, for example
  for Quicklisp code.


EMACS Support

  The command `[47mCtl-t p[0m' now works in Emacs 25.

  The [ACL2-doc] browser for ACL2+books documentation can be extended
  with a new command, [47mU[0m, to open a URL (or in some cases, a file) in
  a browser.  See file [47memacs/acl2-doc-open-url.el[0m for more
  information.


Experimental Versions")
 (NOTE-8-4
  (RELEASE-NOTES)
  "ACL2 Version 8.4 (August, 2021) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 8.3 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  [note-8-4-books] for a summary of changes made to the ACL2
  Community Books since ACL2 8.3, including the build system.  Also
  note that with each release, it is typical that the value of
  constant [47m[*ACL2-exports*][0m has been extended, and that some built-in
  functions that were formerly in [47m:[0m[47m[program][0m mode are now
  [guard]-verified [47m:[0m[47m[logic][0m mode functions.


Changes to Existing Features

  [47m[Apply$][0m, [47m[lambda$][0m, and [47m[loop$][0m may be used with [badge]d [47m:[0m[47m[program][0m
  mode functions in top-level evaluation.  To assign a badge to a
  [47mprogram[0m mode function, use the new feature [47m[defbadge][0m.

  For calls of the form [47m(HIDE (COMMENT \"...\" ...))[0m, the string is a bit
  more descriptive.  See [comment] and see [hide].  Thanks to Mark
  Greenstreet for helpful discussions leading to this change.

  The [events] [47m[defun-nx][0m and [47m[defund-nx][0m now [disable] the
  [executable-counterpart] [rune] for the new function symbol.  Thus,
  after either of these introduces function symbol [47mf[0m, the ACL2
  rewriter will no longer attempt to simplify a call of [47mf[0m on concrete
  arguments by using evaluation (unless of course that
  executable-counterpart is enabled first).  Thanks to Mark
  Greenstreet for an email leading to this change.  The
  implementation of this change also fixes a bug: when the
  [default-defun-mode] is program mode, [47m[defund-nx][0m now [disable]s
  the definition [rune] for the new function, but that was not
  previously the case.

  Some built-in functions supporting the macro, [47m[position][0m, now [47m[fix][0m
  (coerce) their accumulator argument to a natural number.  Thanks to
  Mihir Mehta for supplying the initial such changes, for the purpose
  of avoiding numeric type hypotheses.  After that, thanks to email
  correspondence from Warren Hunt, we added built-in
  [47m:[0m[47m[type-prescription][0m rules for those same functions so that ACL2
  [type-set] reasoning infers that [47mposition[0m always returns either [47mnil[0m
  or a natural number.

  The macro [47m[defconst][0m no longer accepts an optional documentation
  string (which was already being ignored).  Thanks to Eric Smith and
  Alessandro Coglio for suggesting this change, which avoids
  potential confusion; consider for example [47m(defconst *c* () \"abc\")[0m.

  Two improvements have been made in support of the [47m[case-match][0m macro.
  (1) The built-in constant [47m[*ACL2-exports*][0m now includes the [47m\"ACL2\"[0m
  package symbol, [47mquotep~[0m.  (2) The built-in function
  [47msymbol-name-equal[0m is now a [guard]-verified [47m:[0m[47m[logic][0m mode function.
  Thanks to Stephen Westfold for email leading to these changes: for
  (1), pointing out that the special role of [47mquotep~[0m for the
  [47m[case-match][0m macro applies only to that [47m\"ACL2\"[0m package symbol, not
  to other symbols with the same name; and for (2), pointing out that
  the expansion of a [47mcase-match[0m call that invokes [47mquotep~[0m for
  matching was introducing [47m:[0m[47m[program][0m mode code.

  A call of [47m[comment][0m is more often inserted when the prover inserts a
  call of [47m[hide][0m.  See [comment] for a discussion of such ways in
  which [47mcomment[0m is used.

  When a [rewrite] rule's conclusion is of the form [47m(equiv term1 term2)[0m
  where [47mequiv[0m is a known [equivalence] relation, ACL2 generally
  creates the rule to rewrite an instance of [47mterm1[0m to the
  corresponding instance of [47mterm2[0m, in a context where it is
  sufficient to preserve [47mequiv[0m.  However, if that rule is illegal,
  for example because it would rewrite a variable, then the rule is
  effectively treated as [47m(equal (equiv term1 term2) t)[0m.  This
  behavior is not new, but now an explanatory [observation] is
  printed when this happens, as for [47mfoo[0m in the following example.
  Thanks to Mihir Mehta for suggesting such an enhancement.

    (defun my-equiv (x y) (equal x y))
    (defequiv my-equiv)
    (in-theory (disable my-equiv)) ; optional (avoids warnings for the next form)
    (defthm foo (my-equiv x (car (cons x x))))

  A trust tag (see [defttag]) is now required to set the [ld-prompt] to
  a non-Boolean value, other than the [brr] prompt, since that can
  cause printing of the prompt to modify state in rather arbitrary
  ways.

  Improved translation of function calls, especially those that involve
  congruent [stobj]s, including better error messages, much improved
  code comments, and simplified code.  Thanks to Sol Swords for
  sending an example with a misleading error message.

  The error message has been improved when a [47m:[0m[47m[linear][0m rule is illegal
  due to simplification of its conclusion to a constant by ground
  evaluation.  Thanks to Eric Smith for suggesting such an
  improvement.

  It is no longer an error to repeat a [47m[defun-sk][0m event after removing
  or adding the [xargs] [declaration], [47m:guard t[0m; the latter is now
  essentially redundant.  It is similarly no longer an error to
  repeat a [47mdefun-sk[0m event by adding, removing, or changing keyword
  [47m:guard-hints[0m in an [47mxargs[0m declaration.  Thanks to Alessandro Coglio
  for reporting these issues.

  The set of [47m[apply$][0m primitives has been expanded.  These are built-in
  function symbols that do not need a [warrant] when reasoning about
  the application of [47mapply$[0m to them or using them in [47m[loop$][0m.  Thanks
  to Alessandro Coglio for noting that some built-in [47m:[0m[47m[logic][0m-mode
  functions do not have warrants, in particular, [47m[sublis-var][0m.

  Improved [47m[defwarrant][0m to be a no-op for [47m[apply$][0m primitives.

  ACL2 now points out when specious simplification takes place; see
  [specious-simplification].  Formerly this was the case only with
  [gag-mode] turned off; still, [47mprove[0m output needs to be on for any
  such message to be printed (see [set-inhibit-output-lst]).  Thanks
  to Mihir Mehta for a query that led to this enhancement.

  For [47m[fmt][0m directives [47m~f[0m and [47m~F[0m, ACL2 now uses the alist component of
  the [47mevisc-tuple[0m argument and the global [47m[evisc-table][0m.  Previously
  it used these only for directives [47m~x[0m, [47m~y[0m, [47m~X[0m, and [47m~Y[0m (and
  deprecated directives [47m~p[0m etc.; see [fmt]).  Thanks to Eric Smith
  for a query leading to this enhancement.

  Reporting has been improved when encountering possible invariance
  violations for abstract [stobj]s.  Now, when that happens an
  ``illegal-state'' is entered, as indicated by the prompt, and
  instructions are printed for how to proceed at your own risk.  See
  [illegal-state].

  A [47m[table][0m's guard may now reference the ACL2 [state].  Thus, it may
  now be a term involving (at most) the variables [47mWORLD[0m, [47mENS[0m, and
  [47mSTATE[0m.

  It is now always redundant to [47m[unmemoize][0m a function symbol that is
  not currently [memoize]d.  See [redundant-events].

  The ``basic'' ruler-extenders (see [rulers]) now include not only the
  symbols [47m[return-last][0m and [47m[mv-list][0m but also the symbol [47m[if][0m.  As
  before, the termination analysis always continues through the true
  and false branches of [47mIF[0m calls; but now, by default, it also
  continues through the first argument of an [47mIF[0m call.  Thanks to Eric
  Smith for suggesting this improvement and testing it on some
  proprietary books.

  When supplying [47mstate[0m as an argument to [47m[defun-nx][0m (or [47m[defund-nx][0m),
  it is no longer necessary to declare [47mstate[0m as a [stobj] or use
  [47m[set-state-ok][0m.  Thanks to Eric Smith for suggesting the
  possibility of this change.

  It had been the case that if [47m[defun-nx][0m or [47m[defund-nx][0m is used for a
  recursive definition, and that form specifies a value for
  [47m:ruler-extenders[0m that omits [47m[return-last][0m (see [rulers] for
  relevant background), then the definition generally fails to be
  admitted.  (This is due to the generated [47m[defun][0m's use of [47m[prog2$][0m,
  which is a macro that abbreviates a call of [47m[return-last][0m, which
  blocks the termination analysis.)  That has been fixed, by ensuring
  that [47mdefun-nx[0m and [47mdefund-nx[0m arrange that [47mreturn-last[0m is always
  among the ruler-extenders of the generated [47m[defun][0m form.  Thanks to
  Eric Smith for noticing this issue and for a helpful discussion.

  Improved handling of [linear] rules: cause an error with a helpful
  message when a linear rule is no longer created during
  [47m[include-book][0m or the second pass of an [47m[encapsulate][0m form, and
  optimize by avoiding certain calculations when the [47m:trigger-terms[0m
  keyword is supplied.  Thanks to Eric Smith for sending an example
  that illustrates the former issue, essentially as included in a
  comment in [community-book] [47mbooks/system/doc/acl2-doc.lisp[0m, form
  [47m(defxdoc note-8-4 ...)[0m.

  The [event] macros [47m[value-triple][0m and [47m[assert-event][0m have been
  changed to be more flexible, in particular by providing an option
  to allow the given form to return multiple values.  They are also
  more efficient, as they no longer evaluate using [safe-mode] by
  default.  (Technical note: As a consequence of implementation
  changes, one will rarely if ever see ``hard'' errors (see [er])
  from these utilities.)  Thanks to Eric Smith for requesting that a
  single utility encompass what is provided by the built-in utility
  [47m[assert-event][0m and the [community-books] utilities [47m[assert!][0m and
  [47m[assert!-stobj][0m.  That single utility is now [47m[assert-event][0m, which
  in turn uses [47mvalue-triple[0m to check the supplied assertion.

  The ACL2 [47m[bdd][0m package can now reason using the implicit rewrite rule
  [47m(equal (consp (cons x y)) t)[0m.  Thanks to Warren Hunt for requesting
  this enhancement.

  The [event] macro [47m[with-output][0m has been improved with several
  changes and new features (and correspondingly, so has
  [47mwith-output![0m).  In addition to improvements to its documentation,
  these include the following; see [47m[with-output][0m for more
  information.

    * The keyword argument [47m:summary[0m has been replaced by keyword arguments
      [47m:summary-on[0m and [47m:summary-off[0m, which control inhibited summary
      types in analogy to how keyword arguments [47m:on[0m and [47m:off[0m control
      inhibited output.

    * The keyword arguments [47m:on[0m and [47m:off[0m may now take value [47mnil[0m.

    * So-called ``on-off specs'', [47m(:on-off sym1 ... symk)[0m are now allowed
      for keyword arguments [47m:on[0m and [47m:off[0m, which let you turn on or
      off all output types except the specified [47msymi[0m.  On-off specs
      are similarly supported for keyword arguments [47m:summary-on[0m and
      [47m:summary-off[0m.

    * There is a new keyword for [47m[with-output][0m, [47m:ctx[0m, which supports a sort
      of global override of [event] contexts.  See [with-output] and
      see [ctx].

    * There is better error checking, in particular for duplicate keywords.

  The value returned by a successful event [47m(encapsulate ... ev_i ...
  ev_n)[0m is no longer always [47mT[0m.  See [encapsulate].

  Two event macros produce much less output than before, as follows.
  Thanks to Alessandro Coglio for requesting these changes and to him
  and Eric Smith for helpful discussions.

    * [47m[Defstub][0m is not only quieter but also does a bit more error
      checking.

    * [47m[Defun-sk][0m has a new [47m:verbose[0m argument for when output is desired
      after all.

  For the [47m:logic[0m and [47m:exec[0m components of a [47m[defabsstobj][0m export,
  [signature]s no longer need to match.  Thanks to Sol Swords for
  suggesting this improvement.  Now, the only such requirements are
  that the lengths of the input signatures are equal and the lengths
  of the output signatures are equal.

  The utility [47m[set-guard-checking][0m now prints messages to [47m(standard-co
  state)[0m rather than to [47m*standard-co*[0m.  (Of course, these are the
  same by default.)

  In a proposed [linear] rule, hypotheses that are calls of [47m[bind-free][0m
  are now accounted for when considering whether each of the
  [47m:trigger-terms[0m has sufficient free variables (see [linear], in
  particular condition (b) there, and see [bind-free]).  Thanks to
  Dave Greve for reporting this issue.  The example below has the
  indicated failure in ACL2 Version 8.3 but is now accepted.

    (defstub f (x) t)
    (defstub g (x) t)

    ; The following two events are the same except that the first supplies
    ; :trigger-terms while the second does not (instead computing trigger terms
    ; heuristically).  These should either both fail or both succeed; now they
    ; both succeed.

    ; FAILED, but now SUCCEEDS after the fix since then variables y and z are
    ; considered to occur (free) in the hypotheses when determining
    ; whether the hypotheses and trigger term include enough variables to cover
    ; those in the conclusion.
    (defaxiom ax1
      (implies (bind-free '((z . z))) ; or, (bind-free '((z . z)) (y z))
               (< (f x) (g y)))
      :rule-classes ((:linear :trigger-terms ((f x)))))

    ; SUCCEEDED even before the fix: the bind-free hypothesis fools ACL2
    ; into believing that otherwise-free variables may be bound by the
    ; bind-free alist.
    (defaxiom ax2
      (implies (bind-free '((z . z))) ; or, (bind-free '((z . z)) (y z))
               (< (f x) (g y)))
      :rule-classes :linear)

  The report for [47m:[0m[47m[brr][0m when a hypothesis fails to be relieved shows
  repeated attempts to bind free variables not only as before ---
  that is, when a hypothesis has free variables --- but also when the
  hypothesis is a call of [47m[bind-free][0m that returns a list of
  substitutions.  Thanks to Dave Greve for bringing up this issue.

  It is now an error for a [47m:[0m[47m[linear][0m rule's conclusion to generate a
  polynomial whose terms are all determined to be non-numeric.
  Thanks to Eric Smith for suggesting such a check.  Here is an
  example of such a rule that was formerly admitted but useless but
  now causes an error.

    (defthm bad-rule
            (equal (< (foo x) x) nil)
            :rule-classes :linear)

  In executable code, calls of [47m[hide][0m in [47m[let][0m-bindings or [47m[lambda][0m
  bodies are no longer considered to represent [47m[ignore][0m declarations.
  We thank Alessandro Coglio for raising and discussing this issue.
  Below is a log, based on that discussion, that was produced using
  ACL2 before this change.  After this change, the second and third
  calls of [47m:[0m[47m[trans][0m will now result in errors, as noted in comments
  below.  Previously ACL2 treated the [47mhide[0m calls in those two input
  expressions as though they represented [47mignore[0m declarations, in the
  sense of translation of the first form shown below.  That is still
  the case when translating for theorems rather than executable code;
  for details see the ``Essay on Using Hide for Ignored
  Let-bindings'' in the ACL2 source code.

    ACL2 !>:trans (let ((x 0)) (declare (ignore x)) 1)

    ((LAMBDA (X) '1) (HIDE '0))

    => *

    ACL2 !>:trans ((LAMBDA (X) '1) (HIDE '0)) ; error after this change

    ((LAMBDA (X) '1) (HIDE '0))

    => *

    ACL2 !>(untranslate '((LAMBDA (X) '1) (HIDE '0)) nil (w state))
    (LET ((X (HIDE 0))) 1)
    ACL2 !>:trans (LET ((X (HIDE 0))) 1) ; error after this change

    ((LAMBDA (X) '1) (HIDE '0))

    => *

    ACL2 !>

  The [47m[defabsstobj][0m keyword, [47m:CONCRETE[0m, has been changed to
  [47m:FOUNDATION[0m.  Although the use of [47m:CONCRETE[0m is still supported in
  this release (Version 8.4), it generates a warning that this usage
  is deprecated and will likely not be supported after this release.
  Also, documentation and comments now typically speak of
  ``foundational stobj'' for the underlying stobj of the abstract
  stobj (which can be supplied explicitly by the [47m:FOUNDATION[0m keyword)
  rather than ``corresponding concrete stobj''; this reflects the
  fact that the foundational stobj may itself be an abstract stobj
  (which is not new for this release).

  Strengthened error-checking for [47m[stobj-let][0m to insist that if an
  updater is supplied explicitly in a binding, then it must be a
  valid updater.  This check was formerly made only if the variable
  bound in that binding is among the producer variables (see
  [nested-stobjs]).  For example, the following now causes an error,
  but it was formerly accepted in spite of the fact that [47mxyz[0m is not
  the updater for the accessor, [47mtop1-fld[0m; in fact [47mxyz[0m is not even
  defined!

    (defstobj sub1 sub1-fld1)
    (defstobj top1 (top1-fld :type sub1))
    (defun f1 (top1)
      (declare (xargs :stobjs top1))
      (stobj-let
       ((sub1 (top1-fld top1) xyz)) ; bad updater!
       (val)
       (sub1-fld1 sub1)
       val))

  The function symbol [47msymbol<[0m replaces the function symbol [47msymbol-<[0m.
  More generally, for every built-in function symbol and theorem name
  containing [47m\"SYMBOL-<\"[0m, that string in its [47m[symbol-name][0m is replaced
  by [47m\"SYMBOL<\"[0m.  The function [47mlogical-defun[0m is similarly replaced by
  [47mget-defun-event[0m.  Thanks to Alessandro Coglio for suggesting these
  changes.  Note that the old function names still work in ACL2
  Version 8.4, as they are macro-aliases for the corresponding new
  function names (see [add-macro-alias]); however, they are
  deprecated and will probably not be supported in later ACL2
  versions.  (A deprecation warning is printed each time one of those
  macros is expanded.)

  The keyword [47m:witness-dcls[0m of [47m[defun-sk][0m is deprecated and will
  probably be unsupported in future ACL2 releases.  Use [47m[declare][0m
  forms instead; see [47m[defun-sk][0m.


New Features

  It is now possible to assign [47m[badge][0ms to [47m:[0m[47m[program][0m mode functions,
  which allows them to be used by [47m[apply$][0m, [47m[lambda$][0m and [47m[loop$][0m
  during top-level evaluation.  See [47m[defbadge][0m, which assigns badges
  but not [warrant]s and which can handle both [47m:[0m[47m[program][0m and
  [47m:[0m[47m[logic][0m mode functions.

  A new option for [47m[certify-book][0m, provided with keyword option
  [47m:useless-runes[0m or environment variable [47mACL2_USELESS_RUNES[0m, makes it
  possible to speed up repeated certification of a book, sometimes
  substantially.  See [useless-runes].  Thanks to Sol Swords for
  reporting a bug (in ACL2 source function [47mread-file-iterate-safe[0m)
  and supplying a fix, which we have incorporated.  Also thanks to
  Eric Smith for requesting that each tuple in a generated
  ``useless-runes'' file be printed on a single line starting after a
  space, thus supporting grep-like tools.  Finally, thanks to
  Alessandro Coglio and Eric Smith for discussions leading to
  creation of [47m.sys/[0m subdirectories to hold useless-runes files.

  A new keyword for [47m[defstobj][0m, [47m:non-executable[0m, can be given value [47mt[0m
  to skip memory allocation for the new [stobj], by avoiding creation
  of a ``live'' (mutable) stobj.  See [defstobj].  Thanks to Warren
  Hunt for encouraging development of this feature.

  The rewriter now rewrites the bodies of certain quoted [lambda]
  objects.  However, some restrictions apply.  See
  [rewrite-lambda-object].  In addition some new lemmas and a new
  metafunction have been added to the book [47mprojects/apply/top[0m, which
  users are still encouraged to include in sessions dealing with
  [47m[apply$][0m.  The new metafunction is named [47mrelink-fancy-scion[0m and can
  also cause [47mlambda[0m objects to be transformed.  See the discussion of
  that metafunction in [rewrite-lambda-object].

  Added [47m[toggle-inhibit-warning][0m and [47m[toggle-inhibit-warning!][0m to add
  or delete a warning string from the [47minhibit-warnings-table[0m, rather
  than setting that entire table as is done by
  [47m[set-inhibit-warnings][0m.

  It is now possible to instruct the prover to respect requests to
  [disable] the [definition] of the primitive, [47m[mv-nth][0m, rather than
  continuing to expand that definition.  See
  [theories-and-primitives], in particular the note for advanced
  users at the end of that topic.  Thanks to Alessandro Coglio for
  requesting this feature.

  A new utility, [47m[memoize-partial][0m, allows memoization for functions
  that were admitted by adding a formal parameter that decreases on
  each recursive call (sometimes called a ``limit'' or a ``clock'').
  Normally that extra parameter can severely impede the utility of
  memoization; however, the function actually executed does not have
  that extra parameter.  This allows for more memoization hits.
  Thanks to Mertcan Temel for an inquiry leading to this enhancement,
  and for helpful discussions.

  A new rule-class (see [rule-classes]) has been added, named
  [47m:[0m[47m[rewrite-quoted-constant][0m.  Rules in this class can cause the
  rewriter to replace one quoted constant by an equivalent one under
  a given [equivalence] relation.  See [rewrite-quoted-constant].

  The [47m[loop$][0m parser produces more informative error messages on
  ill-formed [47mloop$[0m statements.

  A new [47m[memoize][0m keyword, [47m:invoke[0m, supports the replacement of calls
  of one function by another.  In that sense it is similar to
  [47m[defattach][0m; the difference is that with [47m(memoize f :invoke g)[0m, it
  is necessary first to prove the equality of [47mf[0m and [47mg[0m; therefore,
  ACL2 will compute calls of [47mf[0m by calling [47mg[0m even during proofs.  In
  particular, the tool [add-io-pairs] is built on top of this
  capability; it allows evaluating a function call by fast lookup of
  a verified input-output pair.  Thanks to Eric McCarthy, Alessandro
  Coglio, and Eric Smith for requesting the latter capability and
  providing helpful feedback.

  A new [xargs] keyword for [47m[defun][0m, [47m:type-prescription[0m, can be
  supplied as a formula in the shape of a [type-prescription] rule.
  It is checked to be implied by the built-in type-prescription rule
  computed for the newly-defined function.  Thus, it can serve as
  documentation for the expected type returned by the function; if
  the implication is not equivalence, a warning is printed.  Thanks
  to Alessandro Coglio and Eric Smith for the suggestion.

  [Table]s may now supply custom error messages for table [47m:guard[0m
  failures.  This is accomplished by supplying a table [47m:guard[0m that
  returns two values instead of one.  For a return [47m(mv okp msg)[0m, if
  [47mokp[0m is non-[47mnil[0m then the table guard is considered to be true, that
  is, it has the same meaning as a non-[47mnil[0m single-value return.
  Also, [47m(mv nil nil)[0m has the same meaning and effect as a [47mnil[0m
  single-value return: the table guard fails, and a generic error
  message is printed about the illegal key/value pair.  The new case
  is a return of [47m(mv nil msg)[0m, where [47mmsg[0m should be a [47m[msgp][0m --- a
  string or a cons suitable for printing with the [47m[fmt][0m directive,
  [47m~@[0m.  In that case, [47mmsg[0m is printed (using the [47m[fmt][0m directive, [47m~@[0m)
  instead of a generic error message.  This new feature is now used
  in some built-in tables.  See [table].

  The [proof-builder] command [47m[type-alist][0m has a new optional argument
  that supports printing the type-alist in an alist format.  Thanks
  to Mihir Mehta for requesting this feature.

  A new summary type, [47mREDUNDANT[0m, controls whether a message is printed
  indicating a redundant event (see [redundant-events]), which
  however will still always take place if [47mEVENT[0m output is not
  inhibited (see [set-inhibit-output-lst]).  See [summary].

  A [47mdefabsstobj[0m event may now specify child [stobj] fields, for use by
  [47m[stobj-let][0m.  See [defabsstobj], and see [community-books] file
  [47mbooks/system/tests/abstract-stobj-nesting/README[0m for a brief guide
  to the examples in that directory.  Thanks to Sol Swords for
  requesting this feature and helping to design it, as well as for
  his helpful discussions, feedback, and test files.

  The [47m:congruent-to[0m keyword is now supported for [47m[defabsstobj][0m.

  [47m[Stobj-let][0m now allows aliases in the bindings in some cases where
  this is safe because updating is not involved.  Thanks to Sol
  Swords for suggesting such a change.

  Added a function [47m[ctxp][0m to recognize valid contexts, which are used
  for printing error message (see [ctx]).  Thanks to Eric Smith for
  requesting this addition and to Alessandro Coglio for suggesting
  that it be disabled, for efficiency.

  The utilities [47m[brr][0m and [47m[monitor][0m now each take an optional argument
  that avoids output.  A new utility, [47m[monitor!][0m, is a combination of
  these two with their new optional arguments of [47mt[0m, thus also
  avoiding output.  Thanks to Eric Smith for requesting a version of
  [47mmonitor[0m that turns on [47mbrr[0m.

  A new utility, [47m[get-guard-checking][0m, returns the [guard]-checking
  value most recently installed, either [47mt[0m (when the ACL2 executable
  was built) or presumably by [47m[set-guard-checking][0m.  Thanks to Eric
  McCarthy for suggesting this utility.

  The function [47m[aset1-trusted][0m may be used in place of [47m[aset1][0m to avoid
  [invariant-risk], but is therefore [untouchable].

  Added a new utility, [47m[print-object$+][0m, that is like [47m[print-object$][0m
  but instead of taking [47mSTATE[0m, [47m[print-object$+][0m is a macro that takes
  keyword arguments to customize the output.  See [print-object$+].
  Thanks to Eric Smith for requesting such additional print control.


Heuristic and Efficiency Improvements

  We changed the lightweight ``preprocess'' simplifier for ``[simple]''
  rules in the prover's [waterfall], in the case that the term is the
  application of a defined function symbol to constant (quoted)
  arguments.  As before, if the [executable-counterpart] rule for
  that function symbol is [enable]d, then the call is evaluated in
  Lisp; and if that evaluation fails (typically because a constrained
  function is called), then an attempt is made to rewrite the term by
  applying a [simple] rule.  The change is for how failure is
  handled, that is, in the case that evaluation fails and the term is
  not rewritten.  Formerly, the term was surrounded by a call of
  [47m[hide][0m.  Now, that is only done by the main rewriter, not by the
  ``preprocess'' simplifier.  Thanks to Eric Smith for a
  communication on the acl2-help list, on a thread started by Mark
  Greenstreet, that led us towards making this change.  Mark's failed
  proof now succeeds after this change, but here is a simpler
  example.  Formerly, the commented-out [47m:do-not[0m hint was required for
  the proof of the [47m[thm][0m call below to succeed, because the
  definition of [47mg[0m is not simple and hence the ``preprocess''
  simplifier replaced [47m(g 3)[0m by a term [47m(hide (comment ...) (g 3))[0m
  before the rewriter could apply the definition of [47mg[0m.

    (defstub f (x) t)
    (defun g (x) (cons x (f x)))
    (thm (equal (car (g 3)) 3)
         ;; :hints ((\"Goal\" :do-not '(preprocess)))
         )

  The ACL2 rewriter has a ``being-openedp'' heuristic that prevents
  loops, by saving a stack based on what is currently being
  rewritten.  This can prevent the use of a [definition] or [rewrite]
  rule.  Now the heuristic is turned off when the term's function
  symbol has a non-recursive definition and simplification has just
  settled down (see [hints-and-the-waterfall]).  To restore the old
  behavior, i.e., to use the heuristic in all cases --- thus
  providing backward compatibility when a proof fails --- evaluate
  the form: [47m(defattach-system being-openedp-limited-for-nonrec
  constant-nil-function-arity-0)[0m.

  When a command executed in a logical [world], [47mw[0m, is interrupted, the
  world is reverted to [47mw[0m.  That reversion process could be very slow
  if the interrupt was taken during the installation of the new
  world, as indicated by the messages:

    Flushing current installed world.
    Reversing the new world.
    Installing the new world.

  That process has been sped up significantly.  Moreover, the new
  process avoids a bug reported by Eric Smith, who we thank for
  sending an example of how the process was interacting badly with
  [47m[reset-prehistory][0m.  Code implementing that interaction was
  introduced in Version 4.0 to speed up the process; that code has
  been eliminated, as it is no longer necessary.

  ACL2's [type-set] reasoning has been slightly strengthened to
  comprehend Boolean combinations of strong [compound-recognizer]
  calls on a single variable when building a context (a so-called
  [type-alist]).  (By a ``strong compound-recognizer call'' we mean a
  unary function that recognizes a union of primitive ACL2 types and
  has, either explicitly or implicitly, a corresponding
  [compound-recognizer] rule; examples include [47m[stringp][0m, [47m[integerp][0m,
  and [47m[true-listp][0m.)  In particular, this change can strengthen the
  result of [forward-chaining].  Thanks to Eric Smith, who raised
  this issue by providing an example that we include in a comment,
  inside the form [47m(defxdoc note-8-4 ...)[0m in [community-book]
  [47mbooks/system/doc/acl2-doc.lisp[0m.

  [Type-set] reasoning also has been improved for inequalities to take
  more advantage of the fact that the number 1 constitutes a
  singleton type.  For example, after evaluating [47m(defstub foo (x) t)[0m
  ACL2 is now able to prove [47m(implies (< 2 x) (equal (foo (bitp x))
  (foo nil)))[0m where previously it could not.  In fact [47m2[0m can now be
  replaced by any rational number that is at least 1.

  The function [47m[compress1][0m has been made more efficient in the
  following ways.

    * [47mCompress1[0m is now faster when the [47m:ORDER[0m specified by the given
      [array]'s [header] is [47m<[0m or [47m>[0m and the alist is properly ordered:
      header first, then ascending (for [47m:ORDER <[0m) or descending (for
      [47m:ORDER >[0m) order of indices, with no value in the alist equal to
      the [47m:DEFAULT[0m specified by the header.  In particular, this can
      cut the time to run [47mcompress1[0m on an alist containing only the
      header by more than half, which addresses a request made by
      Eric Smith (whom we thank for bringing this efficiency issue to
      our attention).

    * For the change noted just above, Eric also noticed that when the
      [default] is [47mnil[0m then there was no speedup.  This led us to fix
      an existing bug (technical description: for an array with
      default [47mnil[0m, the alist was never considered to be in order).

    * Functions [47m[compress1][0m and [47m[compress2][0m no longer require the new and
      old dimensions to agree in order that the underlying raw lisp
      array is reused.  Now it suffices for the new dimension (for
      [47mcompress1[0m; each dimension for [47mcompress2[0m) to be at least as
      great as the old.  (You can still avoid reuse of the raw Lisp
      array by using [47m[flush-compress][0m.)  Thanks to Eric Smith for
      suggesting this change.

  We found that [47m[accumulated-persistence][0m was measurably slowing down
  ACL2 even when it is off.  We modified its implementation and
  measured a time reduction of 3.7% for a proof-intensive book.  The
  modification includes a documented efficiency tweak to
  [47m[wormhole-eval][0m.

  The [linear-arithmetic] heuristics have long taken advantage of
  negated equality hypotheses.  These heuristics have been
  strengthened to take further such advantage.  Thanks to Warren Hunt
  for sending an example proof attempt that failed before this change
  but now succeeds, and for his encouragement to pursue an
  improvement to linear arithmetic that can benefit such proof
  attempts.

  The removal of [guard-holders] has been augmented to include removal
  of certain ``trivial'' lambda applications.  See [guard-holders],
  in particular for how to restore the legacy behavior.  Thanks to
  Alessandro Coglio for an example and Eric Smith for a subsequent
  suggestion that led to this enhancement.


Bug Fixes

  A soundness bug, present since [47m[loop$][0m was introduced, was fixed. The
  bug was manifested when the keyword [47m:guard[0m was used as the [47mloop$[0m
  body, as in [47m(loop$ for v in lst collect :guard)[0m.  (Note: It's not
  clear that this bug could be used to prove [47mnil[0m.)

  A soundness bug was fixed by changing [47m[defabsstobj][0m to avoid using
  [47m[mbe][0m in the definitions generated for the logic.  The problem was
  that the [47m:logic[0m and [47m:exec[0m forms are not actually equal (they
  correspond, in the sense of the correspondence predicate), and this
  can be exploited by using a [47m:[0m[47m[guard-theorem][0m [lemma-instance].  For
  an example proof of [47mnil[0m in Version 8.3, see a comment about a
  [47mdefabsstobj[0m bug in the form [47m(defxdoc note-8-4 ...)[0m in file
  [47mbooks/system/doc/acl2-doc.lisp[0m.

  A soundness bug was fixed in the functions that print to strings,
  such as [47mfmt-to-string[0m; see [printing-to-strings].  The bug was a
  dependence of the result on the ACL2 [state], even though [47mstate[0m is
  not an argument to these functions.  More specifically, the
  dependence was on the [47m[current-package][0m and the global
  [47m[evisc-table][0m.  For examples see [community-books]
  [47mbooks/system/tests/fmt-to-string.lisp[0m and
  [47mbooks/system/tests/fmt-to-string-pkg.lisp[0m.  Note: We also
  strengthened the [guard]s on these functions to require that the
  keys of the [47mfmt-control-alist[0m alist argument are all appropriate;
  in particular, the symbol [47mcurrent-package[0m in the [47m\"ACL2\"[0m package is
  a suitable key, but for example the keyword [47m:current-package[0m is
  not.

  It was possible to prove [47mnil[0m by counterfeiting [47mrecord-expansion[0m
  calls, which are normally only created by the implementation in
  support of [47m[make-event][0m calls.  This soundness bug has been fixed.
  (The bug was perhaps impossible to hit in ordinary usage, where
  [47mrecord-expansion[0m is not used explicitly.)  A proof of [47mnil[0m before
  this fix may be found in a comment in ACL2 source function,
  [47mcorresponding-encaps[0m.

  The mechanism for tracking [warrant]s needed during a proof had a
  bug, which might be a soundness bug if one uses [47m[apply$][0m or
  [47m[loop$][0m.  That bug has been fixed.

  Fixed a bug that was preventing use of the RDTSC hardware instruction
  in SBCL on most x86-based platforms, and possibly erroneously
  attempting to make use of that instruction on some other platforms.
  Thanks to Keshav Kini for a query that led to this fix.  Also
  restricted RDTSC to x86-based platforms, thanks to a suggestion by
  Curtis Dunham, to enable Arm builds of ACL2.

  The use of [47m[apply$][0m on calls of [47m[if][0m no longer cause raw Lisp errors.
  (The same is true for calls of the subroutine [47mapply$-prim[0m of
  [47mapply$[0m.)  For example, these calls now evaluate without error:
  [47m(apply$ 'if '(nil nil nil))[0m and [47m(apply$-prim 'if '(nil nil nil))[0m.

  We made the following fixes to the [47m[accumulated-persistence][0m utility.

    * Applications of [type-prescription] rules that were erroneously
      labeled as ``useless'' are now appropriately labeled as
      ``useful''.

    * The documentation for [47m[accumulated-persistence][0m now correctly states
      that the form [47m(accumulated-persistence-oops)[0m undoes the
      clearing effect of [47m(accumulated-persistence t)[0m, rather than of
      [47m(accumulated-persistence nil)[0m.

    * Uses of [definition] rules because of [47m:[0m[47m[expand][0m hints, either
      explicitly given by the user or generated by ACL2's heuristics
      for doing induction, were not being recorded by
      [47m[accumulated-persistence][0m.  They are now.

  Fixed a bug that was causing books to be included as ``uncertified''
  after their certification stored checksums (see [book-hash]).
  Thanks to Keshav Kini for reporting this bug.

  ACL2 could occasionally simplify subterms of a call of [47m[hide][0m even
  without any applicable rules or [47m:expand[0m [hints].  (Technical note:
  the problematic source function was [47mnormalize[0m.)  We considered this
  to be a bug, so it has been fixed.

  The notion of redundancy for [47m[defstobj][0m [events] was too weak, as
  evidenced by the following example.  Consider the following book,
  named [47m\"bug.lisp\"[0m.

    (in-package \"ACL2\")
    (defstobj st fld)
    (defun foo (st) (declare (xargs :stobjs st)) (fld st))

  After certifying this book, a raw Lisp error could occur after
  evaluating the following forms, because the compiled definition of
  [47mfoo[0m from including the book referenced a function, [47mfld[0m, which is
  now a macro.

    (defstobj st fld :inline t)
    (include-book \"bug\") ; The defstobj event in this book is redundant here.
    (foo st)

  The bug has been fixed by requiring a redundant [47m[defstobj][0m event to
  be syntactically identical to the pre-existing corresponding
  [47m[defstobj][0m event.

  A raw Lisp error would occur when the value of an [47m:[0m[47m[instructions][0m
  hint is not a true (null-terminated) list.  ACL2 now produces an
  informative error message in that case.

  Improved [47m:[0m[47mprint-gv[0m to do its computation in the ACL2 [world] in which
  the [guard] violation took place.  See [print-gv]; in particular,
  that topic concludes with a discussion of this issue.  Thanks to
  Eric Smith for reporting this issue along with a simple example.

  The following [47m[defun-sk][0m bugs were fixed.

    * The [guard] was being ignored (that is, treated as [47mt[0m) when
      [47m:constrained t[0m was specified in a [47mdefun-sk[0m event.  Thanks to
      Alessandro Coglio for reporting this bug.

    * [47m[Defun-sk][0m could fail when the formal parameters include [stobj]s or
      [47mstate[0m.

    * [47m[Defun-sk][0m provided no direct way to allow formals to be ignored.
      Now, [47mignorable[0m [declaration]s are permitted.

  For Lisps that do not compile on the fly (that is, Lisps other than
  CCL and SBCL), evaluation of [47m:comp t[0m effectively unmemoized
  functions that were not already compiled.  This has been fixed.

  When a [stobj] hash-table's ``init'' function was called with size 0,
  an error could occur for host Lisp GCL, complaining that size 0 is
  not allowed for hash-tables.  This has been fixed by using size 1
  instead of 0 in this case.

  Reporting by [break-rewrite] has been fixed for cases when failure is
  due to a hypothesis with a [backchain-limit] of 0.  There were
  actually two such bugs: one due to improper handling of [linear]
  rules (which might have occurred even for other backchain-limits
  besides 0), and one due to the erroneous assumption that
  backchaining has only just begun at the point of failure.  Thanks
  to Mihir Mehta for sending an example that exhibited both bugs.  A
  discussion of the second bug, including a simple example, may be
  found in a comment in the ACL2 source function,
  [47mtilde-@-failure-reason-phrase1-backchain-limit[0m.

  [47m:OR[0m [hints] that contain a single list (which satisfies
  [47m[keyword-value-listp][0m) were being mishandled.  This has been fixed.
  Thanks to Dave Greve who sent an example [47m[defthm][0m event specifying
  [47m:hints ((\"Goal\" :or ((:in-theory (e/d () ()) :nonlinearp t))))[0m,
  which formerly caused a Lisp error.

  Fixed a bug in tracking the [cbd] that could cause failures of
  [47m[include-book][0m in raw-mode.  Thanks to Warren Hunt for a query
  leading to this fix.

  Fixed a bug that was preventing some deep [patterned-congruence]
  rules from being applied.  This could occur when on the left-hand
  side, the outermost function symbol is the same as the next
  function symbol going in towards the variable that differs on the
  right-hand side.  Thanks to Mihir Mehta for reporting this bug and
  including a replayable example.

  Fixed several issues with [47m[fmt][0m (and related printing utilities)
  pertaining to linebreaks.  These include the following, many of
  which are illustrated in a new file,
  [47msystem/tests/fmt-tests-input.lsp[0m (search there for ``2020'').

    * A space past the [47m[fmt-soft-right-margin][0m now results in a linebreak
      even in the case of tilde-space (`[47m~ [0m').

    * As before, for punctuation after a tilde-x (`[47m~x[0m') directive, ACL2
      avoids printing in column 0 after a linebreak.  This desirable
      behavior now extends to the case that `[47m~x[0m' is inside a
      tilde-atsign (`[47m~@[0m') directive.  For example, after
      [47m(set-fmt-hard-right-margin 10 state)[0m try either [47m(fmx \"~@0.\"
      (msg \"~x0\" '(ab de gh)))[0m or (fmx \"~#0~[~x0~/~x0~].\" '(ab de
      gh)).

    * Spaces are respected after tilde-y (`[47m~y[0m') directives.  For example,
      [47m(cw \"~y0 A~%\" 3 4)[0m now prints the letter [47mA[0m in column 2 rather
      than column 0.  Thanks to Eric Smith and Alessandro Coglio for
      suggesting this change.

    * An extra character is sometimes permitted before deciding that a
      tilde-x (`[47m~x[0m') directive causes a linebreak.

    * Tilde directives that cause no printing are often ignored when
      deciding whether to keep a punctuation mark with a
      pretty-printed expression.  For example, when setting both
      right margins (soft and hard) to 10, the following no longer
      prints a comma in column 0: [47m(fmx \"~x0~@1, more~%\" 'aaaaaaaaaa
      \"\")[0m.

    * Fixed a [47m[double-rewrite][0m warning, which was breaking the word ``is''.
      Thanks to Mihir Mehta for pointing this out.

  After setting [state] global [47mtrace-co[0m, for example with [47m(f-put-global
  'trace-co (@ standard-co) state)[0m (say, after setting standard-co to
  an open output channel), printing of the trace level such as ``[47m1>[0m''
  and ``[47m<1[0m'' will now go to that channel.  Formerly, this could fail
  after setting [47mtrace-co[0m directly rather than using
  [47m[open-trace-file][0m.

  There are improvements to [47m[certify-book][0m and [47m[include-book][0m, which
  pertain to the loading of compiled files by [47minclude-book[0m before
  events in the book are processed.  That process supports
  preservation of [hons]es and [fast-alists], and reporting of
  ``stolen'' alists (see for example [with-stolen-alist]).  Relevant
  tests, with implementation-level comments, may be found in the new
  [community-books] directory,
  [47mbooks/system/tests/early-load-of-compiled/[0m.  Thanks to Sol Swords
  for helpful discussions.

  Improved a utility that builds sets of clauses, which improves the
  reliability of using a [lemma-instance] of the form [47m(:guard-theorem
  <name> nil)[0m.  Thanks to Eric Smith for reporting this problem with
  a simple example, and to Dave Greve for following up with a related
  example; both now work as one would expect.

  Fixed printing of the ACL2 [state] in error messages, specifically
  when executing a non-executable function.

  Fixed a bug that could cause a raw Lisp error when processing a
  [linear] rule with a [47m[bind-free][0m hypothesis, when that hypothesis
  does not specify a list of variables (in its second argument).
  Thanks to Dave Greve for reporting this bug by sending a simple
  example.  (Technical note: the fix was in the definition of source
  function all-vars-in-hyps.)

  For [47m[defabsstobj][0m, a suitable error now occurs when the [47m:LOGIC[0m
  version of an abstract [stobj] export has the foundational stobj as
  a formal parameter that is declared as a [stobj].  Formerly, a
  confusing hard error could occur in this case.

  An unfortunate ``Proof skipped'' could be printed during the
  [47minclude-book[0m phase of [47m[certify-book][0m for certain uses of
  [47m[make-event][0m, including calls of [47m[thm][0m.  This has been fixed.

  Fixed an implementation error that was being reported when a
  [47m[stobj-let][0m form updates two array fields each with at least two
  indices that are not all natural numbers.  For an example that
  caused this error, see [community-book]
  [47mbooks/system/tests/nested-stobj-two-updates.lisp[0m.

  Fixed a bug in resizing [stobj] arrays whose elements are specified
  to be [47m(signed-byte 30)[0m or a subtype of that type.  Thanks to Eric
  Smith for reporting this bug with a reproducible example.

  For a [47m[stobj-let][0m call occurring in other than a definition body, the
  top-level bindings of variables to child stobj accessors was
  treated as [47m[let*][0m rather than as [47m[let][0m.  That was at odds with the
  documentation, and has been fixed.

  Fixed a bug that caused an error when attempting to redefine a
  function for which a [47m:[0m[47m[compound-recognizer][0m rule has been proved.
  Thanks to Eric McCarthy for reporting this bug (GitHub Issue #1273)
  with a reproducible example.

  Raw mode now does a better job of maintaining global [stobj] values.
  Here is an example that illustrates the fix; also see
  [set-raw-mode], which has been extended to explain a related but
  remaining issue.

    (defstobj st2 (ar :type (array t (8)) :resizable t))
    (set-raw-mode-on!)
    (resize-ar 20 st2)
    (ar-length st2) ; formerly 8, but now 20 as expected

  For any [47m[proof-builder][0m command of the form [47m(= term1 term2 atom ...)[0m,
  the keyword arguments were ignored.  This has been fixed, and also
  the documentation for [47m[ACL2-pc::=][0m has been improved.

  Consider when a [community-book] is included using an ACL2 executable
  different from the one that certified the book, with those two
  executables being located in different directories.  The book is
  now considered to be uncertified in that case.  To avoid this issue
  see [include-book] for a discussion of environment variable
  [47mACL2_SYSTEM_BOOKS[0m.


Changes at the System Level

  (SBCL only) Filenames are now read as ASCII (specifically,
  ISO-8859-1) when the host Lisp is SBCL, which formerly was not the
  case.  Thanks to Stephen Westfold for suggesting this change.

  ACL2 can once again be built on CMU Common Lisp (CMUCL) (though we
  have only done minimal testing).  The problem turned out to be with
  ACL2, not CMUCL: low-level Lisp code in the ACL2 sources was
  destructively modifying a quoted constant.  (For implementation
  details, see [47m*fncall-cache*[0m in source file [47mtranslate.lisp[0m.)  The
  bug was discovered when considering modification of the build
  process to compile ACL2 source files when the host Lisp is SBCL.
  Thanks to Stas Boukarev for pointing us in the right direction to
  debug this error.

  There is now a way to save the untranslated bodies of built-in
  [47m:[0m[47m[program][0m mode functions.  WARNING: This is not officially
  supported!  But it may be useful for tools such as a linter.  See
  [47mGNUmakefile[0m: search there for [47m:acl2-save-unnormalized-bodies[0m, where
  you will see that a more general capability is actually available
  for evaluating forms before the build begins.  Thanks to Eric Smith
  for correspondence leading to this enhancement.

  Starting with ACL2 Version 7.0, the availability of hash consing (see
  [47m[hons][0m) and the other features described in [hons-and-memoization]
  have been part of a default ACL2 build; meanwhile, support for
  ``classic'' ACL2 has essentially been discontinued.  These features
  require a certain Lisp action (implementation note: pushing [47m:hons[0m
  onto [47m*features*[0m) that had been done during the ACL2 build by the
  `[47mmake[0m' process (with code in [47mGNUmakefile[0m).  Now that action is
  taken unconditionally in the ACL2 source code.  Thanks to Petter
  Gustad for reporting an error when attempting to build ACL2 without
  using `[47mmake[0m'; this change should fix that bug.  With this change
  you can no longer attempt to build ``classic'' ACL2(c) without
  editing ACL2 source file [47minit.lisp[0m; environment variable [47mACL2_HONS[0m
  no longer has any effect.  (On a related technical note: An obscure
  feature [47m:memoize-hack[0m seems not to be used anywhere, and has been
  eliminated.)

  (SBCL only) Handling in ACL2 of the SBCL ``read-cycle-counter'' has
  been modified to reflect its handling in recent SBCL versions
  (starting around late 2018 or early 2019).  This avoids an ACL2
  build error on some platforms.  Thanks to John R. Strohm for
  reporting such a problem (on a Raspberry Pi).

  (SBCL only) Increased the number of special variables that can be
  created, which allowed community book
  [47mbooks/kestrel/apt/schemalg-template-proofs.lisp[0m to certify.

  Fixed builds that use a relative pathname for the LISP environment
  variable (for host Lisps CCL, SBCL, Allegro CL, and CMUCL; GCL and
  LispWorks didn't seem to have this problem).  Thanks to Mihir Mehta
  for bringing this issue to our attention; and thanks to Andrew
  Walter for reporting a problem with our first solution for SBCL and
  proposing an alternative, which we adopted.

  Fixed the process for running ACL2 without building an executable
  image.  Some initialization that was missing from that process is
  now included.  Also, added the missing command, (lp), to the
  instructions in section ``Running Without Building an Executable
  Image'' on the ``Obtaining and Installing ACL2'' web page
  (accessible from the ``Obtaining, Installing, and License'' link on
  the ACL2 home page).  Thanks to Petter Gustad for an inquiry
  leading to these improvements.

  When invoking `[47mmake[0m' to build the ACL2 executable, output from the
  build process is now written to file [47mmake.log[0m.  The terminal output
  is now minimal.  If there is already a file [47mmake.log[0m, it is first
  moved to [47mmake.log.bak[0m.  See file [47mGNUmakefile[0m for additional
  documentation.  Thanks to Alessandro Coglio and Eric Smith for
  suggesting this change, and to David Rager for pointing out
  associated changes to make for Jenkins builds.

  The startup banner now has a cleaner look (see [startup-banner]).
  Thanks to Alessandro Coglio and Eric Smith for key suggestions for
  improvement.

  (CCL only) When an attempt to build ACL2 fails, a more informative
  error message is printed when the error is caused by invoking CCL
  as a soft link on the Unix PATH rather than as a regular file.
  Thanks to Mertcan Temel for feedback leading to this change.

  A script [47mbin/acl2[0m has been added below the main ACL2 directory.  It
  may be used in place of [47msaved_acl2[0m, invoked from any directory.  If
  the [47mbin[0m subdirectory is on one's Unix [47mPATH[0m then of course [47macl2[0m will
  invoke this script (unless a different [47macl2[0m is in a directory that
  is earlier on that path).  Thanks to Alessandro Coglio for
  suggesting that an [47macl2[0m script be made available with ACL2, and to
  him and Eric Smith for subsequent discussions on that topic.

  When an error occurs while loading an [ACL2-customization] file, ACL2
  quits with exit code 1.  Thanks to Eric Smith for suggesting the
  quit and to Eric McCarthy for suggesting exit code 1 in that case.

  ACL2 now does a more thorough job of doing proofs when ``[47mmake
  proofs[0m'' is executed.  In particular, proofs were formerly skipped
  but are now performed for [47m[defun][0m forms containing the explicit
  [47m[xargs][0m [declaration], [47m:mode :logic[0m, and for [47m[defthm][0m events
  evaluated with [default-defun-mode] [47m:logic[0m outside the so-called
  ``pass 2 files''.


EMACS Support

  The [ACL2-doc] search commands (`[47ms[0m' and `[47mS[0m') were seen to use all
  available memory on a linux system, during the process of
  initializing the [47macl2-doc-search[0m buffer that is used for doing the
  searching.  That problem has been solved: that buffer is now loaded
  from a file that is built by the manual-building process and is
  downloaded by the acl2-doc `[47mD[0m' command.

  Highlighting in lisp-mode (inside Emacs) has been improved, both by
  recognizing more keywords and by highlighting of some new
  arguments, in particular the first argument of [47mdefthm[0m.  Thanks to
  Vivek Ramanathan, both for pointing out the [47mdefthm[0m issue and for
  suggesting code that was incorporated into the changes.

  The [ACL2-doc] browser now queries when first loading an ACL2+books
  manual if you have a newer web-based version.  A ``yes'' response
  will use the (out-of-date) manual, while a ``no'' response will
  generally produce a new query asking if you want to download the
  manual from the web.  This change was made in support of building
  the manual more quickly, as the acl2-doc manual is no longer built
  by default.  See [ACL2-doc] for how to do that build and other
  details.  Thanks to Alessandro Coglio, Eric Smith, and Sol Swords
  for discussions about speeding up the build of the manual.

  Fixed certain hangs in the [ACL2-doc] browser.  For example, when
  standing on whitespace near the left margin of topic
  [*ACL2-exports*], the '[47mg[0m' command could formerly hang.


Experimental Versions

  ACL2(p) now runs much more reliably on host Lisp SBCL (by taking
  advantage of a locking mechanism provided by SBCL).  Thanks to
  David Rager for providing this improvement.

  In ACL2(p), [47m[set-waterfall-parallelism][0m no longer causes an error
  when there are [47m[override-hints][0m if the argument is the existing
  value of the [state] global, [47m'waterfall-parallelism[0m, or upon a
  transition of [waterfall-parallelism] to [47mnil[0m.  Thanks to David
  Rager for raising this issue (see GitHub Issue #1171) and
  discussing its resolution.")
 (NOTE-8-5
  (RELEASE-NOTES)
  "ACL2 Version 8.5 (July, 2022) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 8.4 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  [note-8-5-books] for a summary of changes made to the ACL2
  Community Books since ACL2 8.4, including the build system.  Also
  note that with each release, it is typical that the value of
  constant [47m[*ACL2-exports*][0m has been extended, and that some built-in
  functions that were formerly in [47m:[0m[47m[program][0m mode are now
  [guard]-verified [47m:[0m[47m[logic][0m mode functions.


Changes to Existing Features

  Weakened hypotheses from built-in theorems (thus strengthening them)
  [47msymbol-equality[0m, [47mtrue-listp-first-n-ac-type-prescription[0m,
  [47mordered-symbol-alistp-getprops[0m, [47madd-pair-preserves-all-boundp[0m, and
  [47msymbol<-asymmetric[0m.  Eliminated built-in theorem
  [47mmain-timer-type-prescription[0m entirely (that rule was already
  deduced by ACL2 at definition time).  Simplified guards slightly
  for built-in functions [47mserialize-write-fn[0m and [47mserialize-read-fn[0m.
  Thanks to Eric Smith for correspondence, based on his linter,
  leading to these improvements.

  The utility [47m[without-evisc][0m formerly always (or nearly always)
  returned the [error-triple] [47m(mv nil :invisible state)[0m after
  printing the result.  Now it generally returns [47m(mv t nil state)[0m
  when evaluation of the given form causes an error.  See
  [without-evisc].  Thanks to Karthik Nukala and Eric Smith for
  reporting the former (undesirable) behavior.

  One would get an error when including an uncertified book when a
  [47m:type-prescription[0m specified in an [47m[xargs][0m [declaration] failed a
  validity check, even when no such failure occurs when that book is
  certified.  (That could happen because type-prescription
  information from locally included books is saved in the book's
  [certificate] file and is used when checking such
  [47m:type-prescription[0m declarations.)  This situation now generates a
  warning rather than an error.  Thanks to Karthik Nukala and Eric
  Smith for sending an example that pointed out this problem.

  Output from [47m:[0m[47m[oops][0m may now be inhibited as [47mOBSERVATION[0m output, by
  using [47m[set-inhibit-output-lst][0m or [47m[with-output][0m.

  [Raw-mode] has been fixed so that reasonable results are printed when
  multiple values are returned by a function defined in raw-mode or
  raw Lisp (rather than in the logic).  The following examples
  illustrate the problem and the fixed behavior.  The utilities
  [47madd-raw-arity[0m and [47mremove-raw-arity[0m are no longer necessary (and
  they had no effect anyhow, at least in recent ACL2 versions), so
  they have been removed.

    (defstobj st fld)
    (set-raw-mode-on!)
    (defun f1 (st) st)
    (f1 st) ; printed a vector; now prints <st>
    (defun f2 (state) state)
    (f2 state) ; printed ACL2_INVISIBLE::|The Live State Itself|;
               ; now prints <state>
    (defun bar (x st state) (mv x st state))
    (bar 3 st state) ; printed 3; now prints (3 <st> <state>)

  The keyword [47m:concrete[0m for [47m[defabsstobj][0m and the keyword [47m:witness-dcls[0m
  for [47m[defun-sk][0m are no longer supported, as they were deprecated in
  ACL2 Version 8.4 in favor of [47m:foundation[0m and [47m[declare][0m forms,
  respectively.  Also: the following symbols, deprecated in ACL2
  Version 8.4, are no longer names of [events].

    logical-defun
    merge-sort-symbol-<
    merge-symbol-<
    strict-merge-sort-symbol-<
    strict-merge-sort-symbol-<-cdrs
    strict-merge-symbol-<
    strict-symbol-<-sortedp
    symbol-<

  The string [47m\"Proof succeeded\"[0m or [47m\"Proof skipped\"[0m was formerly printed
  when [47mSUMMARY[0m output is not inhibited (see
  [set-inhibit-output-lst]), but now that printing takes place
  instead when [47mPROVE[0m output is not inhibited.  Thanks to Pete
  Manolios for pointing out a printing issue that is resolved with
  this change.

  Some error messages were improved for the [proof-builder], primarily
  when refusing a command to dive into an [47mOR[0m expression.  Thanks to
  Warren Hunt for bringing this issue to our attention.

  There was a restriction on certain events, notably [47m[defconst][0m and
  [47m[defmacro][0m events, to ensure that they are not ancestrally
  dependent on [47m[loop$][0m or [47m[lambda$][0m expressions.  That restriction
  has been removed in the case that the body of the event is a quoted
  constant.

  A [47m[defwarrant][0m event may complete more quickly because a generated
  hint now [disable]s the function.

  Functions that take or return [stobj]s may now have [badge]s and
  [warrant]s.  One cannot (yet) take advantage of these in general
  because one cannot put a [stobj] into a list, as required for the
  second argument of [47m[apply$][0m.  However, this change supports the use
  of stobjs in [47m[loop$][0m expressions that use the new keyword, [47mDO[0m.

  The function [47mthe-check[0m, which is generated by calls of [47m[the][0m, is now
  a [guard-holder].

  Printing of checkpoints now takes place any time [47mSUMMARY[0m output is
  enabled (see [set-inhibit-output-lst].  Formerly, both [47mSUMMARY[0m and
  [47mERROR[0m output needed to be enabled.  Related tweaks, probably not
  user-visible, were made in support of utilities for obtaining and
  displaying checkpoints programmatically: see [checkpoint-list]
  (which mentions related utilities as well), and we thank to Eric
  Smith for requesting such utilities.

  The guard formula utilities (see [guard-formula-utilities]) continue
  to perform simplification as before, except that way to specify the
  level of simplification has changed.  Thanks to Eric Smith for a
  query and subsequent discussion that led to these changes.  See
  [guard-simplification] for a detailed explanation; below is a
  summary.  (The reason for these changes is that the value [47mT[0m
  formerly meant different things in the two cases below --- all
  simplification and limited simplification, respectively --- and the
  value [47mNIL[0m also meant different things in those two cases ---
  limited simplification and no simplification, respectively.)

    * For [47m[xargs][0m keyword [47m:guard-simplify[0m and related utilities
      [47m[guard-obligation][0m and [47m[verify-guards-formula][0m:
      The default value for simplification remains [47mT[0m.  However, the value
      is now [47m:LIMITED[0m for specifying reduced simplification; formerly
      it was [47mNIL[0m, which is now illegal.

    * For [47m:[0m[47m[guard-theorem][0m [lemma-instance]s and the related utility [47m[gthm][0m
      (also the low-level utility, [47mguard-theorem[0m):
      The default simplification is unchanged but now corresponds to a new
      default value, [47m:LIMITED[0m; formerly it was [47mT[0m, which is now
      illegal.  The value [47mNIL[0m continues to be appropriate for
      avoiding simplification.

  Improved [47m[untranslate][0m so that when untranslating a translated
  [term], an attempt is made to call [47m[mv][0m where appropriate.  Thanks
  to Alessandro Coglio and Eric Smith for requesting this
  enhancement.  The improvement also restores type declarations under
  [47m[let][0m, [47m[let*][0m, and [47m[mv-let][0m (see [declare] and [type-spec]); and it
  also restores [47m[ignore][0m declarations in [47m[let][0m and [47m[let*][0m forms,
  where previously that was only the case for [47m[mv-let][0m forms.  In
  addition, a new utility, [47m[maybe-convert-to-mv][0m, may be called
  explicitly to convert an untranslated term to one that calls [47mmv[0m in
  leaves reached via transversal of the true and false branches of
  its top-level [47mIF[0m tree, where the traversal appropriately passes
  through [47m[let][0m, [47m[let*][0m, and [47m[mv-let][0m forms, as well as calls of
  [47m[prog2$][0m, [47m[mbe][0m, [47m[mbt][0m, [47m[ec-call][0m, [47m[time$][0m, and a few other macros
  related to [47m[return-last][0m as well as [47mreturn-last[0m itself.  See
  examples under a comment about ``preserving executability'' in the
  [community-book], [47mbooks/system/tests/untranslate.lisp[0m.  (Note: The
  changes also include a bug fix that avoids generating an [47m[mv-let][0m
  expression when there are fewer than two bound variables.)

  The second argument of [47m[certify-book][0m is no longer allowed to be the
  symbol, [47mT[0m, or any symbols whose [47m[symbol-name][0m is [47m\"T\"[0m.  (This option
  seems to have been essentially unused but it complicated the source
  code.)

  When an [event] fails while [useless-runes] are being read, the
  failure message now makes note of that fact.  See
  [useless-runes-failures].  Thanks to Mertcan Temel for pointing out
  that such failures may present a confusing problem for (especially)
  new users.

  Failed attempts to [47m[memoize][0m or [47m[profile][0m now generally result in
  less noisy error output.  Also, a more useful error message is
  printed when attempting to [47m[memoize][0m or [47m[profile][0m a function that
  is introduced either by [47m[defabsstobj][0m or by [47m[defstobj][0m with keyword
  argument [47m:inline t[0m, and hence is a macro in raw Lisp; thanks to
  Shilpi Goel for suggesting this improvement.

  When the [break-rewrite] utility reports rewriting a hypothesis to
  [47mnil[0m, it adds a note pointing to a new :doc topic, [tail-biting],
  that explains a way that this can happen.


New Features

  A new [47m[loop$][0m keyword, [47mDO[0m, supports an imperative style of
  programming in loops.  In particular, [47mDO[0m [47mloop$[0m expressions may use
  [47msetq[0m and [47mmv-setq[0m for assigning to one or several variables
  (respectively), they may reference and return [stobj]s, and they
  may return multiple values.  See [loop$].

  One can now suppress output from [47m[cw][0m, [47m[cw!][0m,
  [47m[fmt-to-comment-window][0m, and [47m[fmt-to-comment-window!][0m, and from
  utilities that use these such as [47m[time$][0m, by inhibiting a new
  output type, [47mCOMMENT[0m.  (Thus, that symbol has been added to the
  value of [47m*valid-output-names*[0m.)  See [set-inhibit-output-lst] and
  [with-output].  Thanks to Eric McCarthy for a conversation via
  GitHub Issue #1293 that led to this enhancement.  Moreover, new
  macros [47m[cw+][0m and [47m[cw!+][0m and new functions [47m[fmt-to-comment-window+][0m
  and [47m[fmt-to-comment-window!+][0m never suppress output; the [47m\"+\"[0m suffix
  is intended to indicate that feature.  Thus, these new utilities
  behave like the previous utilities without the [47m\"+\"[0m suffix.  Thanks
  to Eric Smith, Karthik Nukala, and Alessandro Coglio for observing
  inappropriate suppression of output from the utility [47m[er-soft+][0m and
  the connection of this problem to the addition of the [47mCOMMENT[0m
  output type; it was resolved by using [47mfmt-to-comment-window+[0m in
  place of [47mfmt-to-comment-window[0m in the implementation of a utility
  underlying [47mer-soft+[0m (see [community-book]
  [47mbooks/tools/er-soft-logic.lisp[0m).

  You can now arrange that an interrupt will kill a proof immediately
  by evaluating [47m(assign abort-soft nil)[0m, and you can restore the
  default behavior --- where an interrupt instructs the proof to quit
  cleanly at an appropriate opportunity --- by evaluating [47m(assign
  abort-soft t)[0m.  Note that this can interfere with [47m:[0m[47m[redo-flat][0m; see
  [abort-soft].  Thanks to Eric Smith for reporting an inability to
  abort a series of proof attempts using the [47m[prove$][0m utility, which
  led to this enhancement.

  A [stobj] may now have a field of type [47mSTOBJ-TABLE[0m, which associates
  arbitrary stobj names with corresponding stobjs.  As of this
  writing, that feature should be considered experimental; see
  [stobj-table].  Thanks to Rob Sumners for suggesting the idea and
  to him and Sol Swords for useful design discussions.

  The utility [47m[wet][0m has a new keyword option, [47m:fullp[0m, that allows it to
  work even when there is a raw Lisp error.  Thanks to Eric Smith for
  requesting that [47mwet[0m be able to work in such cases.

  Rewriting of [lambda] objects (see [rewrite-lambda-object]) may now
  be [disable]d, by disabling the [executable-counterpart] [rune] for
  (trivial function), [47mrewrite-lambda-modep[0m --- for example, with a
  hint [47m:in-theory (disable (:e rewrite-lambda-modep))[0m.  Also improved
  a couple of warnings and a bit of documentation pertaining to such
  rewriting.

  The undocumented [47mlast-ld-result[0m feature has been replaced by a new
  documented feature, a [ld-history] that records command
  input/output history.  Thanks to Eric Smith for requesting this
  feature.

  The [47m[ld][0m utility accepts a new keyword argument, [47m:useless-runes[0m,
  which functions much the same as does the [47m:useless-runes[0m keyword
  argument of [47m[certify-book][0m.  See [useless-runes].  Thanks to Eric
  Smith for requesting this feature (which may have been requested
  previously as well).

  A new [event], [47m[set-inhibit-er][0m, allows the user to turn off error
  output of various types.  The related utility [47m[toggle-inhibit-er][0m
  can turn on or off a single type of error output.  Non-[local]
  versions of these utilities are [47m[set-inhibit-er!][0m and
  [47m[toggle-inhibit-er!][0m.  Many error messages cannot yet be controlled
  this way, but this may be remedied somewhat with community
  feedback.  Thanks to Eric Smith for a request to inhibit step-limit
  error output, which led to this enhancement.

  The functions [47m[l<][0m, [47mlexp[0m, and [47md<[0m, originally defined in
  [community-book] [47mbooks/ordinals/lexicographic-book.lisp[0m, are now
  built into ACL2.  However, it is still useful to include an
  ordinals book, for example [community-book]
  [47mbooks/ordinals/ordinals[0m, if you want to reason about such
  functions.

  A [stobj] field of [47mHASH-TABLE[0m type may now specify an element type;
  for example, [47m(hash-table eql nil integer)[0m specifies a test of [47meql[0m,
  no size restriction, and the element type, [47minteger[0m, indicating that
  only integers are stored in the hash table.  The [47m:initially[0m keyword
  of such a field is no longer ignored, but instead provides the
  value returned when looking up a key that is not bound in the hash
  table.  Moreover, the element type may be a stobj, indicating that
  the values in the hash table are all instances of that child stobj;
  see [nested-stobjs].  In that case, the [47m:initially[0m keyword would be
  meaningless because one always gets a fresh instance of the child
  stobj when looking up an unbound key; hence [47m:initially[0m is illegal
  for any hash-table field with a stobj element type.  Thanks to Rob
  Sumners for requesting this enhancement and for helpful discussions
  about its design.

  It is now possible to certify a book in a logical [world] that
  contains [local] [events].  Thus, a book's [certificate] file may
  include local events among its [portcullis] commands, which will be
  skipped when including the book.  A key application of this new
  capability is to save an ACL2 executable (using [47m[save-exec][0m) after
  [local]ly including set [47mB[0m of books at the top level, and then ---
  in fresh ACL2 sessions started by running that executable ---
  certify other books that may include some books of [47mB[0m.  Those
  inclusions would then be [redundant] during certification of a
  book, but not later when the book is included.  If [47mB[0m is a large set
  of large books, then this process can be much more efficient than
  doing certifications from a basic ACL2 executable, which would
  involve running [47m[include-book][0m on all required books from [47mB[0m.  Of
  course, one could previously have saved such an executable and
  certified books on top of it, but then all of [47mB[0m would be included
  whenever including those books, which could be slow and also could
  result in many more rules than desired.  Thanks to Sol Swords and
  others at Intel Corp. for requesting this enhancement and engaging
  in initial discussions.

  The new macro [47m[trust-mfc][0m supports testing [extended-metafunctions]
  outside the prover.  Thanks to Sol Swords for requesting such a
  utility.

  A new macro, [47m[with-global-stobj][0m, allows reading and writing of a
  [stobj] in the body of a function without having to pass it as a
  formal parameter, by accessing the stobj from the ACL2 [state].
  See [with-global-stobj].  Thanks to Rob Sumners and Sol Swords for
  requesting this feature (originally, to support a global
  [stobj-table]) and for helpful discussions about its design.

  The [meta-extract] feature has been extended to allow [linear] lemmas
  to be extracted from the [world] and trusted by clause processors
  and metafunctions.  In particular, a new sort of value for the [47mobj[0m
  argument is supported for [47mmeta-extract-global-fact[0m (and
  [47mmeta-extract-global-fact+[0m), which results in a term representing a
  linear lemma extracted from a function symbol's [47mlinear-lemmas[0m
  property.  See [meta-extract], in particular the discussion of
  [47m:linear-lemma[0m.  Thanks to Sol Swords for providing this
  enhancement.

  A new utility, [47m[disable-ubt][0m, is similar to [47m(reset-prehistory t)[0m
  except that it does not change command numbering.

  Added a built-in [47m:[0m[47m[forward-chaining][0m rule,
  [47msymbol-listp-forward-to-eqlable-listp[0m, which replaces the rule
  [47msymbol-listp-forward-to-true-listp[0m.  Note that the old rule is
  subsumed,together with other rules, by the new one.  Thanks to
  Warren Hunt for observing that not built into ACL2 as a
  [47m:forward-chaining[0m rule.


Heuristic and Efficiency Improvements

  Improved the efficiency of some computations involving calls of
  [47m[defattach][0m with option [47m:aokp t[0m, in particular, of [47m[include-book][0m
  events for books including such calls.  Thanks to Mertcan Temel for
  reporting this efficiency issue and sending an [47minclude-book[0m event,
  whose execution time was reduced from 24 seconds to 10 seconds by
  this change.

  Evaluation of some large forms caused stack overflows (from ACL2
  source function [47mbad-lisp-consp[0m).  This is probably much less likely
  now.  Thanks to Eric Smith for reporting this issue to the
  acl2-help list with a helpful example, which formerly caused a
  stack overflow for ACL2 built on SBCL but no longer does so.

  The function [47m[princ$][0m now prints characters more rapidly.

  In some cases, [47m[include-book][0m calls may run a bit faster thanks to a
  couple of small changes.  The primary change is for heuristic
  [loop-stopper] generation when the conclusion of a [rewrite] rule
  contains a [lambda] expression.  Formerly all such expressions were
  expanded away.  Now, they are expanded away in the left-hand side,
  and both the unexpanded and expanded versions of the left-hand side
  are compared to the unexpanded right-hand side (see the final
  Remark in the [loop-stopper] documentation).  We have seen a 7%
  reduction of time for the event, [47m(include-book
  \"projects/x86isa/top\" :dir :system)[0m.

  Book certification has (in the past, and still) an optimization that
  avoids needless rolling back of the [world] during the
  [47m[include-book][0m phase; see [certify-book], in particular the
  discussion of ``roll back''.  Any [local] event within an
  [47m[encapsulate][0m form was reason to roll back the world to before that
  [47mencapsulate[0m event.  That is no longer the case unless the
  [47m[encapsulate][0m form introduces packages in the first pass through
  that [47mencapsulate[0m form that are hidden or missing after the second
  pass through it, presumably because of a [local] [47minclude-book[0m event
  in that [47mencapsulate[0m form.

  The function [47m[len][0m is significantly more efficient than before.
  (Also, its raw Lisp implementation is simpler, though as before it
  causes an error for extremely (impossibly?) long lists (in Lisp
  parlance, whose length is not a fixnum).)  Thanks to Stephen
  Westfold for encouraging this change and suggesting a suitable
  [47mdeclaim[0m form, and thanks to Eric Smith for providing helpful tests.


Bug Fixes

  A soundness bug in [47m[defstobj][0m has been fixed that allowed a field to
  contain the [type-spec] [47m(SATISFIES pred)[0m when [47mpred[0m has a [guard]
  other than [47mt[0m, which generated an unsound guard theorem.  Thanks to
  Eric Smith for sending the following example.

    (defstobj s (field :type (satisfies evenp) :initially 4))

    (defthm bad
      nil
      :rule-classes nil
      :hints ((\"Goal\" :use (:instance (:guard-theorem fieldp) (x t)))))

  A soundness bug was due to incompleteness of the prohibition against
  [local] [portcullis] [command]s.  For an example, see a comment in
  the form [47m(defxdoc note-8-5 ...)[0m, [community-books] file
  [47mbooks/system/doc/acl2-doc.lisp[0m.  This has been fixed by allowing
  local events among the portcullis commands (and treating them
  properly; see relevant discussion, including how [47m[save-exec][0m may be
  helpful, in the ``New Features'' section above).

  The use of [47m[set-guard-checking][0m before calling [47m[certify-book][0m was
  making it possible for a subsequent [47m[include-book][0m to fail for that
  book.  For example, in a fresh ACL2 session one could evaluate the
  [command] [47m(set-guard-checking :none)[0m followed by [47m(table foo 0 (car
  3))[0m, and then certify a book; but including that book would then
  fail with a [guard] violation, because the [47mset-guard-checking[0m call
  was not saved in the [certificate] file, hence was not evaluated
  when attempting to include the book.  This has been fixed by
  treating that situation much as [local] [portcullis] commands are
  now treated (see discussion about that in the ``New Features''
  section above).  The situation is explained now in the final Remark
  in the documentation for [local-incompatibility].

  Fixed an error that could occur when the [break-rewrite] utility is
  displaying failure information for an attempt to apply a [linear]
  rule containing [free-variables].  Thanks to Karthik Nukala and
  Eric Smith for sending a bug report with a replayable example.

  Strengthened syntax checking for accessor expressions in [47m[stobj-let][0m
  bindings.  See a comment about this in [47m(defxdoc note-8-5 ...)[0m.

  The writing of [useless-runes] files was sensitive to the global
  [evisc-table], which could cause failures when reading those files.
  This has been fixed.

  An error could occur when encountering a [redundant] [47m[defwarrant][0m
  event while including a book.  This has been fixed, by arranging
  that a [47mdefwarrant[0m event always expands to the same [47m[encapsulate][0m
  form.

  An assertion error was fixed, occurring with a call of [47m[certify-book][0m
  when the value of environment variable [47m\"ACL2_USELESS_RUNES\"[0m was
  (erroneously) [47m\"0\"[0m.

  When the [hints] specified for a goal include [47m:do-not-induct NAME[0m for
  some symbol [47mNAME[0m other than [47mt[0m, [47m:otf[0m, [47m:otf-flg-override[0m, or [47mnil[0m,
  then that goal is to be skipped, giving it a ``bye'' as with a [47m:by[0m
  hint.  This would fail however when the [induction-depth-limit] is
  reached: that is, the proof would fail immediately rather than
  continuing so that the skipped goal is printed upon failure at the
  end.  The following example now has the desired behavior; thanks to
  Alessandro Coglio for raising this issue by sending a
  [proof-builder] example, where the [47m:induct[0m command failed for (as
  it turns out) the same reason.

    (set-induction-depth-limit 1)
    (thm (equal (append (append x y) z) (append x y z))
         :hints ((\"Goal\"
                  :induct t :do-not-induct foo :do-not *do-not-processes*)))

  Fixed a bug in processing macro arguments with more than one
  occurrence of the symbol, [47m:allow-other-keys[0m.  Thanks to Eric Smith
  for pointing out this bug and providing a fix.  Here is an example
  that was failing but is now handled without error (notice that
  [47m:allow-other-keys[0m is in a value position, not a keyword position,
  so the duplication is legal).

    ACL2 !>(defmacro foo (x &key y) `(list ,x ,y))

    Summary
    Form:  ( DEFMACRO FOO ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     FOO
    ACL2 !>(foo 3 :y 4 :z 5 :allow-other-keys t :w :allow-other-keys)


    ACL2 Error in macro expansion:  ACL2 prohibits multiple :allow-other-
    keys because implementations differ significantly concerning which
    value to take.

    ACL2 !>:q

    Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
    ? (foo 3 :y 4 :z 5 :allow-other-keys t :w :allow-other-keys)
    (3 4)
    ?

  Pretty-printed output could be misaligned when an output string
  specified by the [evisc-table] contains a newline.  Such output is
  now printed a bit differently, with reasonable alignment.

  Printing of results has been improved in [raw-mode] in cases of
  [multiple-value] return, so that [stobj] names are used even when
  at least one returned value is not an ACL2 object.

  The [trace] level is no longer reset when entering [break-rewrite] or
  any other [wormhole].  Thanks to Khairul Azhar Kasmiran for raising
  this issue and pointing to relevant source code ({GitHub Issue
  #1395 | https://github.com/acl2/acl2/issues/1395}).

  When the [47m:[0m[47m[pr!][0m command prints [47m:[0m[47m[rewrite][0m rules about the
  [47m[pkg-imports][0m of one or more [packages], it now prints such rules
  only for relevant packages, not ones introduced earlier than
  specified by the argument of [47m:pr![0m (as was done previously).  Thanks
  to Eric Smith for bringing this bug to our attention.

  A bug in [47m[defattach][0m has been fixed, which was causing the keywords
  within an argument [47m(fi gi :kwdi1 vali1 ...)[0m to be associated with
  the wrong such argument.

  When printing the name of a symbol or package that consists entirely
  of '[47m.[0m' (dot) characters, the name is escaped with vertical bars,
  for example, [47m|..|[0m.  Note that the CL HyperSpec, Section 2.3.4
  Symbols as Tokens says: ``Any token that is not a potential number,
  does not contain a package marker, and does not consist entirely of
  dots will always be interpreted as a symbol.'' Thanks to Eric
  McCarthy and Eric Smith for pointing out that there can be errors
  when reading such a name when it is not escaped.

  It was possible to get a violation of fast alist discipline (see
  [slow-alist-warning] when certifying a book that uses [47m[must-fail][0m.
  This has been fixed.

  It had been possible to undo commands (for example, using [47m:[0m[47m[ubt][0m when
  inside the [break-rewrite] interactive loop.  This destroyed the
  utility of that loop by erasing keyword aliases (see
  [ld-keyword-aliases]).  Thanks to Warren Hunt for reporting this
  problem.  The solution uses the new utility mentioned above,
  [47m[disable-ubt][0m, which may be useful for other [47m[wormhole][0m invocations
  that take advantage of the [47m[ld-keyword-aliases][0m [table].


Changes at the System Level

  The [hons-enabled] features of ACL2 ([47m[hons][0m, [memoization], and
  [fast-alists]) have been included in ACL2 builds by default since
  Version 7.0 (January, 2015) and in all ACL2 builds since Version
  7.2 (January, 2016).  Now, essentially all support for building
  ACL2 without these features has been removed.  The function
  [47m(hons-enabledp state)[0m and the feature [47m:hons[0m both remain, but are
  always true and are deprecated, scheduled for removal very soon
  after the next release.  The feature [47m:acl2-mv-as-values[0m was always
  true when feature [47m:hons[0m was present, hence was always true; so it
  has been removed (and [47m#-acl2-mv-as-values[0m code has been
  eliminated).

  For ACL2 builds when the host Lisp is SBCL, the Lisp optimization
  level is now 1 for [47mSPACE[0m, which apparently can result in more
  inlining than the former level of 0, and which has been seen to
  speed up an application while reducing memory bytes allocated.  The
  default optimization level for [47mSPACE[0m can be set to 1 for any Lisp
  at build time by running [47mmake[0m with argument [47mACL2_SPACE=1[0m, and the
  level can be set similarly to any legal value, for example by using
  [47mACL2_SPACE=3[0m for level 3.  We can easily change the default for
  other Lisps as well, and might do so when there is evidence that
  this would be useful.

  The function [47mbind-macro-args[0m, and several of its subfunctions, are
  now in [47m:[0m[47m[logic][0m mode with verified [guard]s.  Thanks to Eric Smith
  for verifying guards as per [verify-guards-for-system-functions].

  ACL2 will now generally signal an error if a filename contains
  consecutive directory separators, i.e., [47m\"//\"[0m (in non-Windows
  systems).

  (SBCL only) A build-time parameter was changed so that some non-x86
  64-bit platforms, notably Arm, are built with [47m--dynamic-space-size
  32000[0m, as for x86-64 platforms, instead of [47m2000[0m.  Thanks to Stephen
  Westfold for pointing out this oversight.

  A new documentation topic, [guarantees-of-the-top-level-loop],
  explains the logical meaning of evaluation in the ACL2
  read-eval-print loop, including discussion of attachments (see
  [defattach]), [badge]s, [warrant]s.

  The implementation of backquote has been optimized to use quoted
  expressions for constant subterms (other than [lambda] objects)
  rather than consing new structure.  This can give a significant
  reduction in code size.  Thanks to Stephen Westfold for providing
  his implementation.

  When an error is encountered while reading an expression, the
  remaining input is cleared.  Thanks to Eric McCarthy for pointing
  out that this wasn't the case, giving the example, [47m(LET ((. 3)) (+
  . 4))[0m, as one that was giving many errors.

  (CCL only) Disabled raw lisp compiler macro for [47mmemq[0m.  For example,
  the following definition no longer causes a raw Lisp error when
  submitted to ACL2: [47m(defun foo (x) (member-eq x 'a))[0m.  Thanks to
  Shannon Spires for the suggestion.


EMACS Support

  It is now possible to have more than one [ACL2-doc] buffer.  A new
  buffer is created by using [47mShift-<Return>[0m to follow a link.
  Commands that are naturally specific to a given buffer (such as
  searching and going back) are buffer-local.  Thanks to Mayank
  Manjrekar for the idea and for supplying an implementation
  (including documentation), which has been incorporated into the
  [ACL2-doc] source file, [47macl2-doc.el[0m (loaded from a suitable
  directory; see [emacs]).

  A bug has been fixed in [ACL2-doc] that would cause an error when
  attempting to bring up the acl2-only manual.

  The key binding Control-TAB has been removed for the [ACL2-doc]
  browser, to avoid conflict with other uses of that key.  Thanks to
  Alessandro Coglio for the idea.

  New [47m[ACL2-doc][0m command [47mG[0m is similar to [47mg[0m, prompting for a topic name,
  but puts that topic into a new buffer.  Thanks to Warren Hunt for
  requesting this feature.

  When [47m[ACL2-doc][0m fails in an attempt to download the manual, a more
  helpful error message says how to attempt the download outside
  Emacs, and the minibuffer points to an Emacs variable holding that
  message, [47macl2-doc-download-error[0m (which is also described in the
  [ACL2-doc] documentation topic).  Thanks to Warren Hunt for
  discussion leading to this enhancement.

  Files from the [47memacs/[0m directory in the ACL2 distribution have been
  copied to directory [47mbooks/emacs/[0m.  The original [47memacs/[0m directory
  will continue to be maintained for Emacs 24 (though those who have
  used it comfortably with more recent versions may wish to continue
  to load files from the [47memacs/[0m directory).  The [47mbooks/emacs/[0m
  directory is intended for use with recent versions of ACL2, and the
  ACL2 community is welcome to modify it.  Thanks to Warren Hunt for
  noting that users of recent Emacs versions could experience
  problems using files maintained for Emacs 24.


Experimental Versions

  An error could formerly occur when using the precomputed
  [useless-runes] files in ACL2(r).  The [useless-runes] feature has
  now been turned off for ACL2(r).  Thanks to Eric McCarthy for this
  change.

  Warnings about ``fast alist discipline violated'' (see
  [slow-alist-warning]) could appear in ACL2(p) when [useless-runes]
  were being read, say using [47m[certify-book][0m option [47m:useless-runes
  :read[0m.  These have been eliminated.  Note that they didn't show up
  during regressions in Version 8.4 because the use of ``[47mmake[0m'' was
  set up to avoid using useless-runes with ACL2(p).")
 (NOTE-8-6
  (RELEASE-NOTES)
  "ACL2 Version 8.6 (October, 2024) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 8.5 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  [note-8-6-books] for a summary of changes made to the ACL2
  Community Books since ACL2 8.5, including the build system.

  [3mDARPA Note.[0m The following statement applies to items below that are
  marked with ``See DARPA Note above'': Release was approved by DARPA
  with ``DISTRIBUTION STATEMENT A. Approved for public release.
  Distribution is unlimited.''


Changes to Existing Features

  Some built-in functions that were formerly in [47m:[0m[47m[program][0m mode are now
  [guard]-verified [47m:[0m[47m[logic][0m mode functions.  Among the most
  significant such built-in functions are the following.

    * [47mOne-way-unify[0m (see [47mbooks/system/brr-near-missp.lisp[0m)

    * [47m[Genvar][0m (see [47mbooks/system/brr-near-missp.lisp[0m)

    * [47m[Fmt][0m, [47m[error1][0m (which supports macros [47m(er soft ...)[0m and [47m[er-soft][0m),
      and related printing utilities --- and some code was modified
      to support their conversion to [47m:[0m[47m[logic][0m mode [See DARPA Note
      above.]

  Note that because of the [47m[error1][0m change noted above, [47m(er soft ...)[0m
  can now be used in [47m:logic[0m mode code.

  The connected book directory (that is, the [cbd]) now elaborates
  relative [pathname]s to absolute pathnames not only for book
  operations, but for all file operations.  For example,
  [47m(open-input-channel \"foo\" :character state)[0m now interprets filename
  [47m\"foo\"[0m relative to the cbd, where formerly it was generally
  interpreted relative to the directory in which ACL2 was invoked.
  (Technical note: ACL2 accomplishes the new behavior by arranging
  that [47m[set-cbd][0m modifies not only the cbd but also the Lisp global,
  [47m*default-pathname-defaults*[0m.)  Thanks to Alessandro Coglio, Eric
  McCarthy, and Eric Smith for suggesting consideration of such a
  change and for helpful discussions.

  The function [47mhons-enabledp[0m is no longer defined, and [47m:hons[0m has been
  removed from the Lisp global, [47m*features*[0m (so, readtime conditionals
  [47m#+hons[0m and [47m#-hons[0m should be avoided, especially since [47m#+hons[0m is
  always false even though the system is [hons-enabled]).  These were
  both deprecated in the preceding release (ACL2 Version 8.5).  Note
  that the [hons-enabled] features of ACL2 have been included in all
  builds by default since Version 7.0 (January, 2015) and in all
  builds since Version 7.2 (January, 2016).

  The [proof-builder] now takes into account various aspects of
  rewriting specified by the logical [world] that it formerly ignored
  (pertaining to [match-free], [case-split-limitations],
  [untouchable] functions, non-linear arithmetic (see
  [set-non-linearp]), the [backchain-limit] for rewriting, and the
  [rw-cache-state]).

  The utilities [47mset-inhibit-er-soft[0m, [47mset-inhibit-er-soft![0m,
  [47mtoggle-inhibit-er-soft[0m, and [47mtoggle-inhibit-er-soft![0m have been
  renamed by dropping the suffix ``[47m-soft[0m'', hence they are now the
  following, respectively: [47mset-inhibit-er[0m, [47mset-inhibit-er![0m,
  [47mtoggle-inhibit-er[0m, and [47mtoggle-inhibit-er![0m.  The relevant table has
  similarly been renamed from [47minhibit-er-soft-table[0m to
  [47minhibit-er-table[0m.  These changes reflect their relevance for the
  new utilities, [47m[er-hard][0m and [47m[er-hard][0m, in addition to [47m[er-soft][0m.

  The macro [47m[warrant][0m now [47m[force][0ms the warrants listed.

  [47m:[0m[47m[Induction][0m rules now support the use of [47m[syntaxp][0m hypotheses.

  The utility [47m[read-file-into-string][0m has been improved in the
  following ways.

    * The value of the [47m:start[0m argument may now be any natural number less
      than the length of the input file.  (Formerly one needed to use
      this utility to read the preceding bytes first, which can be
      much slower.)  Thanks to Eric McCarthy, Eric Smith, and Grant
      Jurgensen for requesting this improvement and for helpful
      discussions.

    * While the default behavior is the same for when the corresponding
      Lisp stream is closed, a new keyword argument, [47m:close[0m, can be
      supplied to control that behavior.

    * Miscellaneous clean-up has been made in the implementation.

    * Restrictions have been tightened a bit to avoid what could be
      considered a soundness bug.  See discussion about that in the
      section on ``Bugs'' below.

  The [47m[trace$][0m option [47m:evisc-tuple :print[0m, which continues to use raw
  Lisp printing, has undergone the following improvements when
  printing entry and exit values.  Thanks to Eric McCarthy for a
  query that led to these improvements.

    * Values are now pretty-printed.

    * Array values are no longer displayed as [stobj]s.  (This includes
      stobjs themselves, since they are arrays.)

  The use of [47m(:executable-counterpart rewrite-lambda-modep)[0m to control
  the behavior of lambda object rewriting by the prover (see
  [rewrite-lambda-object]) has been elaborated.

  Warnings for non-recursive functions in left-hand sides of rewrite
  rules (similarly for linear, forward-chaining, and
  type-prescription rules) now consider bodies of lambda objects that
  could be rewritten (see [rewrite-lambda-object]).

  The output is more informative when [47m:[0m[47m[pr][0m is applied to an undefined
  primitive, such as [47mcar[0m or [47mbinary-+[0m, or a macro-alias for one of
  those, such as [47m+[0m.  Thanks to Eric Smith for pointing out odd output
  for examples like [47m:pr binary-+[0m.

  The definition of [47m[pseudo-termp][0m has been simplified by dropping a
  superfluous [47m[true-listp][0m check.  Thanks for the suggestion from
  Eric Smith.  A new lemma, [47mpseudo-termp-consp-forward[0m, has been
  added to prevent some existing proofs from failing due to the
  change.

  The failure message regarding [useless-runes] (see
  [useless-runes-failures]) has been restricted to the case that a
  proof was attempted by the event (though there may be rare
  exceptions).  Thanks to Eric Smith for requesting such a change.

  Certain guard proof obligations for [47mDO[0m [47m[loop$][0ms (so-called special
  conjectures (e), (f), and (g)) have been combined into one
  conjecture with a conjunction of three conditions in the conclusion
  to speed up proofs.  See the comment starting with ``Special
  conjectures (e), (f), and (g)'' in the function [47mspecial-conjectures[0m
  in the source file [47mhistory-management.lisp[0m.

  The rewriter has been changed to handle certain calls of [47mev$[0m faster.
  See [rewriting-calls-of-apply$-ev$-and-loop$-scions].

  A few new lemmas have been added to the standard [47mapply$[0m book to
  simplify applications of [47massoc-equal-safe[0m faster.

  [Time-limit] and [theory-invariant] errors may now be inhibited much
  as [step-limit] errors, by using [47m(set-inhibit-er \"Time-limit\")[0m or
  [47m(set-inhibit-er \"Theory\")[0m, respectively.  Thanks to Eric Smith for
  requesting this enhancement and its use in the implementation of
  the utility, [47m[prove$][0m.

  A new command, [47m(cmds c1 c2 ... cn)[0m, has been added to [47m[walkabout][0m.

  The documentation for [redundant-events] includes the following,
  which however was not enforced when the new event is in [47m:[0m[47m[program][0m
  mode; that has been fixed.

    4. If either the old or new event is a mutual-recursion event, then
       redundancy requires that both are mutual-recursion events
       that define the same set of function symbols.

  A new feature, called ``transparent'' functions, can allow one to
  avoid the restriction on a rule of class [47m:[0m[47m[meta][0m or
  [47m:[0m[47m[clause-processor][0m that there are no common ancestors of its
  evaluator and meta function.  See [evaluator-restrictions] for
  relevant background, and see [transparent-functions] for
  documentation of the new feature.  Thanks to Mertcan Temel for
  requesting a way to work around that restriction, and thanks to Sol
  Swords for suggesting (and naming) the notion of transparent
  functions.  We are also grateful to Sol for providing a very
  helpful sketch of a correctness proof.

  When there is an attachment to a common ancestor of the evaluator and
  meta function of a proposed rule of class [47m:[0m[47m[meta][0m or
  [47m:[0m[47m[clause-processor][0m, the resulting error message now includes
  ancestor paths leading from the evaluator or meta function to a
  common ancestor.

  A new [47m[walkabout][0m command, [47mup[0m, moves up a level and exits the
  [47mwalkabout[0m loop when already at the top level.  It is thus
  equivalent to the existing command, [47m0[0m, which is still supported
  although [47mup[0m is highlighted in the documentation; see [walkabout]).
  Thanks to Eric Smith for suggesting [47mup[0m.

  Arranged that [iprinting] that takes place during [break-rewrite] or
  [47m[cw][0m is better reflected outside break-rewrite.  For examples, see
  [community-books] input file
  [47mbooks/system/tests/iprint-and-brr-input.lsp[0m, which contains
  comments on problematic interactions between break-rewrite and
  iprinting in Version 8.5, and which generates (via the [47m[run-script][0m
  utility) the output in file [47miprint-and-brr-log.txt[0m in that
  directory.  Note that [47m[read-object][0m now updates data structures so
  that it can read back in what was just printed by [47m[cw][0m; see a
  comment in the definition of [47mread-object[0m in the ACL2 source code.

  When a defined function has a [47m[declare][0m form with [47m(optimize ...)[0m,
  that is now included in a declare form of the
  executable-counterpart function (see [evaluation]), which had not
  been the case.

  It had been the case that for type [declaration]s of [47m[flet][0m
  definitions in a surrounding [47m[defun][0m form, they were dropped in the
  [47mdefun[0m form's executable-counterpart (see [evaluation]).  Now they
  are included.

  The behavior of [47m[pso][0m and related utilities ([47m[pso!][0m, [47m[psof][0m, and
  [47m[psog][0m) has been modified to avoid introducing warnings that were
  not originally printed.  For example, the output generated by [47m:pso[0m
  below no longer prints the warning that had been suppressed for the
  [47mdefthm[0m event below.

    (set-inhibit-output-lst '(warning proof-tree))
    (defthm foo t
      :hints ((\"Goal\" :use car-cons))
      :rule-classes nil)
    :pso

  The above change has additional, small output effects, probably for
  the better.  For example, output from the form [47m(with-output :off
  (error summary) (thm (equal x y)))[0m no longer prints the line shown
  below (at the end).

    ACL2 Error [Failure] in ( THM ...):  See :DOC failure.

  When an event fails, then if it involves definition [rune]s for
  [47m[loop$][0m [scion]s, the failure message may suggest including the
  book [47mprojects/apply/top[0m if it hasn't already been included.  That
  book provides quite a few lemmas about [47m[loop$][0m scions.

  Replaced [47m[length][0m calls in the defun of [47m[pseudo-termp][0m with calls of
  a new macro, [47mlen$[0m, which is a call of [47m[mbe][0m that invokes [47m[length][0m
  in the [47m:exec[0m code and [47m[len][0m in the [47m:logic[0m code.  Thanks to Eric
  Smith for requesting such an enhancement, and for discussing
  specifics of it, so as to avoid the need for at least one
  unfortunate rule that if [47m(pseudo-termp term)[0m then [47m(not (stringp
  (cdr term)))[0m, apparently needed because [47mlength[0m behaves specially on
  strings.

  When there is an error from evaluation of a form encountered by [47m[ld][0m,
  in a session where the value of [47m[ld-error-triples][0m is the default
  of [47mt[0m and the value of [47m[ld-error-action][0m is of the form [47m(:EXIT N)[0m,
  then ACL2 quits with exit status [47mN[0m in some cases where formerly it
  did not.  The following explanation is rather technical; see
  [ld-error-action] for relevant background.

      This behavior was already present in the case that the ``error on
      evaluation'' was from an evaluation result [47m(mv erp val state)[0m
      where [47merp[0m is non-[47mnil[0m; but it has been extended to the case that
      [47merp[0m is [47mnil[0m and [47mval[0m is of the form [47m(:STOP-LD . x)[0m, as is
      returned by default by [47mld[0m upon an evaluation error.  A key
      effect of this change is for the case that a [47m.acl2[0m file
      produces an error from a call of [47m[build::cert.pl][0m.  The
      following example illustrates; explanation follows below.

        ;;; foo.acl2
        (ld '((defun g (x) y)) :ld-error-action :return!)

        ;;; foo.lisp
        (in-package \"ACL2\")

      Before this change, the command `[47mcert.pl foo[0m' resulted in a hard Lisp
      error (as seen in [47mfoo.cert.out[0m).  To see why, first note that
      [47mcert.pl[0m executes a sequence of commands as follows (several
      omitted as shown with ``[47m...[0m'').

        ...
        (set-ld-error-action (quote (:exit 1)) state)
        ...
        ; instructions from .acl2 file foo.acl2:
        (ld '((defun g (x) y)) :ld-error-action :return!)
        ...
        #!ACL2 (set-ld-error-action (quote :continue) state)
        ...

      The call of [47mld[0m above returns [47m(mv nil (:STOP-LD 2) state)[0m.  Because
      [47mld-error-action[0m at the top level no longer has the default
      value of [47m:CONTINUE[0m, that result is considered an error (see
      [ld-error-action]) and top-level evaluation halts.  Before this
      change, then ACL2 did not quit since the value was of the form
      [47m(mv nil _ state)[0m; instead, ACL2 would quit the top-level call
      of [47mld[0m, leaving us in raw Lisp.  But in raw Lisp, the [47m#![0m reader
      macro (see [sharp-bang-reader]) is undefined; hence an error
      would be signaled.  After the fix, the return value of [47m(mv nil
      (:STOP-LD 2) state)[0m is treated as an error, so because
      [47mld-error-action[0m is [47m(:EXIT N)[0m, ACL2 immediately exits with
      status [47mN[0m.

  The pretty-printer has been improved by a contribution from Stephen
  Westfold to support appropriate indentation, including more
  conventional pretty-printing for calls of common macros such as
  [47m[defun][0m and [47m[defmacro][0m.  See [ppr-special-syms]; we thank Stephen
  also for supplying the substance of that documentation.  Thanks too
  to Stephen for suggesting several user-defined macros to be
  pretty-printed with this mechanism, which we have modified by
  adding suitable [47m[table][0m events (e.g., for [47m[define][0m).

  Runtime [guard] violation messages from [47mDO[0m [47m[loop$][0m expressions are
  now much more readable.  They also now include a pointer to the
  [do-loop$] documentation, which has new, relevant explanation
  (first in brief, later in detail) regarding such messages.

  Four obsolete fields of the ACL2 [state] have been removed:
  [47mbig-clock-entry[0m, [47mt-stack[0m, [47m32-bit-integer-stack[0m, and
  [47mlist-all-package-names-lst[0m, as have some related built-in,
  undocumented definitions and theorems, including [47mold-check-sum-obj[0m
  and supporting functions.

  Improved [47m[hide][0m calls in prover output from failed execution of
  [warrant]s, by adding suitable notes about attachments or warrant
  functions not being executable during proofs.  Thanks to Eric
  McCarthy for a remark that led to this change.

  State globals [47minhibit-output-lst[0m, [47minhibited-summary-types[0m, and
  [47mld-level[0m are now [untouchable].  The macros
  [47m[set-inhibit-output-lst][0m and [47m[set-inhibited-summary-types][0m still
  allow you to modify the values of these variables.  Thanks to Peter
  Dillinger for correspondence (years ago!) leading to these changes.

  The macro [47m[state-global-let*][0m no longer requires explicitly supplying
  a setter for certain built-in [state] global variables.  See
  [47m[state-global-let*][0m.

  A proposed [47m[defaxiom][0m [event] is no longer [redundant] with an
  existing [47m[defthm][0m event.  Before this change, the following book
  could (perhaps unfortunately) be certified, even without
  [47m[certify-book][0m option [47m:skip-proofs-okp t[0m.

    (in-package \"ACL2\")
    (local (defthm foo (equal (car (cons x x)) x)))
    (defaxiom foo (equal (car (cons x x)) x))

  The prover sometimes reduces a goal without hypotheses (technically
  speaking, a one-element [clause]) to [47mnil[0m using type reasoning (see
  [TYPE-REASONING]).  This heuristic has not changed, but formerly
  there was no explanation given.  Now ACL2 reports the rules (of
  class [47m:[0m[47m[type-prescription][0m) that were used.

  The default for [47m[memoize][0m keyword argument [47m:verbose[0m has been changed
  from [47mt[0m to [47mnil[0m, which (by default) eliminates noise from the output.

  When a proof attempt is halted so that it reverts to prove the
  original goal by induction, the top-level checkpoints are printed
  under the [summary] under the banner, ``[47mKey checkpoints before
  reverting to proof by induction[0m''.  This was normally the case
  already, but not in the special case that the proof is eventually
  aborted either because a goal of [47mNIL[0m is produced or because proof
  by induction is not allowed (due to a [47m:DO-NOT-INDUCT[0m hint or an
  [induction-depth-limit] being exceeded).  Thanks to Eric Smith for
  a chat that helped lead to this improvement.

  For most built-in [table]s, error messages for guard failures have
  been improved, by use of a new macro that is also available to ACL2
  users: [47m[set-table-guard][0m.  That utility may be used to set a
  [table] guard in a way that produces a user-friendly error message
  when the guard fails.

  The prover may now print a parenthetical remark about ``dropping
  false conclusion''.  That remark points to a new documentation
  topic, which provides explanation: see [clause].

  [State] global [47mtrace-co[0m is now untouchable.

  ACL2 now warns when the hypothesis of a [type-prescription] or
  [forward-chaining] rule is a call of [47m[syntaxp][0m or [47m[bind-free][0m,
  since these get no special treatment for such rules.

  The utility [47m[get-event-data][0m now returns data from the proof done on
  behalf of a [47m[thm][0m event, rather than from the surrounding
  [47m[make-event][0m call used for implementing [47mthm[0m.  Thanks to Eric Smith
  for requesting this change.

  In the case that a proof is interrupted after [47m(set-debugger-enable t)[0m
  and then aborted, ACL2 formerly printed failures in a special way,
  in particular showing the [pstack].  This is no longer the case:
  all [event] failures are printed in the same way.

  A new key, [47mEVENT[0m, is available for [47m[get-event-data][0m.  Thanks to Eric
  Smith for a discussion leading to this addition.

  Most ACL2 reader errors are now ACL2 hard errors rather than raw Lisp
  errors (as they were formerly).  As a result, such errors can
  sometimes be ``caught'' by suitable programming.  Thanks to Grant
  Jurgensen and Eric Smith for requesting this change.  Note that
  input is still flushed in these cases, perhaps more thoroughly than
  before.

  [47m[Break-rewrite][0m, [47m[brr-commands][0m, [47m[monitor][0m, and [47m[unmonitor][0m have been
  radically changed but in a largely backwards compatible way.  It is
  now possible to cause interactive breaks when a monitored rule is
  tried but fails to match the target.  See [47m[monitor][0m, in particular,
  see the ``near-miss'' break criteria in [47m[monitor][0m for a discussion.
  Changes to [47m[break-rewrite][0m largely just correct anomalous behavior.
  One significant behavioral change is that the list of monitored
  runes is locally bound by [47mbreak-rewrite[0m, so that while it can be
  changed in inferior breaks, when control returns to superior levels
  (and to the top-level) the list of monitored runes is unchanged.
  Related changes are discussed in the following three items.  [See
  DARPA Note above for this work, including the following three
  items.]

    * The [47m[brr][0m-command [47m:[0m[47m[p!][0m (see [brr-commands]) has been redefined so
      that in [break-rewrite] it is a no-op.  (Actually, it did not
      always work as advertised in [break-rewrite]!  Its behavior
      outside of break-rewrite is unchanged.)  A comment in the
      source code definition of [47mp![0m explains why.

    * The function [47mget-wormhole-status[0m is deprecated, and its new name is
      [47m[get-persistent-whs][0m.

    * The macro [47mshow-brr-evisc-tuple[0m has been eliminated, but
      [47m[brr-evisc-tuple][0m is available instead.

  The definition of [47mbounded-integer-alistp[0m has been modified by adding
  a guard [47m(posp n)[0m and removing the [47m(integerp n)[0m test from the body
  of its [47m[defun][0m.  [See DARPA Note above.]

  As before, when calling [47m[break$][0m from a [wormhole] --- for example
  when inside [break-rewrite] --- one is left at a raw Lisp prompt.
  However, when returning from that prompt (e.g., with [47m:q[0m if the host
  Lisp is CCL), one no longer stays in the wormhole, as noted by a
  message, ``Aborting to top level from a wormhole break (see :DOC
  wormhole).'' [See DARPA Note above.]

  The function [47miprint-oracle-updates[0m, which is called by [47m[read-object][0m,
  is now [disable]d, because it was made more complicated to
  accommodate the conversion of function [47meviscerate-top[0m into [47m:[0m[47m[logic][0m
  mode.  [See DARPA Note above.]

  The utilities [47m:[0m[47m[pe][0m and [47m:[0m[47m[pr][0m now provide more useful output when
  applied to function symbols that are built into ACL2 without a
  defining event.  Thanks to Warren Hunt for discussions leading to
  this improvement.

  The [47m[guard][0ms and bodies have changed slightly for some built-in
  function definitions, as follows.

    * For functions [47m[princ$][0m, [47mprin1$[0m, [47m[explode-atom][0m, and [47mexplode-atom+[0m,
      the guard now requires of the first argument only that it be an
      atom; it no longer must be a ``good atom'', i.e., a number, a
      character, a string, or a symbolp.  As a result, the definition
      bodies of [47m[princ$][0m, [47mprin1$[0m, and [47m[explode-atom][0m have been
      tweaked slightly.

    * The guards for [47mpackn1[0m, [47m[packn-pos][0m, [47mfind-first-non-cl-symbol[0m, and
      [47m[packn][0m have similarly been weakened to require only
      [47m[atom-listp][0m instead of [47mgood-atom-listp[0m, and the definition of
      [47mgood-atom-listp[0m has been removed.

    * The guard for [47m(prin1$ x channel state)[0m now requires [47m(symbolp
      channel)[0m; it was a bug that this conjunct was formerly omitted.

    * Several functions that take [47m[state][0m had guards requiring that
      built-in [state] globals --- those bound in
      [47minitial-global-table[0m --- are bound in the global-table of the
      [state] (using [47mf-boundp-global[0m or [47mboundp-global[0m).  However, the
      predicate [47mstate-p1[0m, which recognizes ACL2 [state]s, implies
      that these conditions all hold; so, they have been removed from
      those guards.  Such a test has also been removed from the
      definition of [47mmain-timer[0m.

  The utility, [47m[break-on-error][0m, now causes a much cleaner error when
  invoked in [raw-mode].  The installation of breaks by
  [47mbreak-on-error[0m works even in raw-mode --- it's just that evaluation
  of a call of [47mbreak-on-error[0m must not take place in raw-mode.  Also,
  the effect of [47mbreak-on-error[0m, to cause breaks on errors, works
  better after entering raw-mode than it did previously, when
  evaluation of a form [47m(er hard ....)[0m would fail to enter the
  debugger: that has been fixed.  Evaluation of [47m(er soft ....)[0m
  continues to invoke such breaks whether or not in raw-mode.  A new
  aspect of [47mbreak-on-error[0m is that breaks occur not only for hard and
  soft errors, but also when aborting to the top level (which is what
  happens when [47m(er hard ...)[0m is called in raw-mode).  Thanks to Eric
  McCarthy for reporting issues that led to these improvements.

  When [47m[ld][0m is invoked with a non-[47mnil[0m value of keyword
  [47m:ld-missing-input-ok[0m and the input file is missing, the value
  returned is now [47m:missing-input[0m instead of [47m:eof[0m.

  When [47m[defbadge][0m is applied to a function symbol that is built into
  ACL2 with a [badge], such as [47m[nth][0m, the result is a no-op and an
  [observation] is printed to that effect.  (Formerly the [47mbadge-table[0m
  was needlessly extended and ACL2 reported that the function symbol
  was being given a badge.)

  Suppose that a [47m[verify-guards][0m event for a defined function symbol,
  [47mfn[0m, does not include a [47m:hints[0m keyword, but the existing definition
  of [47mfn[0m includes a [47m:guard-hints[0m keyword in its [47m[xargs][0m [declaration].
  Then, unlike previously, the value of that [47m:guard-hints[0m keyword is
  now used as the value of [47m:hints[0m for that [47mverify-guards[0m event.  The
  keywords [47m:guard-debug[0m and [47m:guard-simplify[0m of [47mverify-guards[0m
  similarly now default to values of the corresponding [47mxargs[0m in the
  old definition, if supplied there.  This change brings the behavior
  of [47mverify-guards[0m in line with that of [47m[verify-termination][0m.  See
  [verify-guards] for a discussion of the case of [47m[mutual-recursion][0m,
  where only the definition of [47mfn[0m is relevant for keyword values, not
  other definitions in its clique.

  A hint of the form [47m:induct X[0m is now an error if [47mX[0m is an atom other
  than [47mt[0m or a quoted constant, since those do not suggest any
  induction scheme.  Thanks to Eric Smith for raising the question of
  what [47m:induct nil[0m should do and helping with examples showing that
  the current behavior is not really consistent.  Thanks to
  Alessandro Coglio for suggesting that [47m:induct nil[0m cause an error
  since it serves no purpose and could be confused with
  [47m:do-not-induct t[0m, which is quite different.

  The built-in [47m[defaxiom][0m events [47mcode-char-char-code-is-identity[0m and
  [47mchar-code-code-char-is-identity[0m no longer have [47m[force][0md hypotheses.
  Thanks to Alessandro Coglio for pointing out that these [rewrite]
  rules were rather unique as built-in rewrite rules that force
  hypotheses.  Note that the original versions of these two rules,
  stated as [47m[defthm][0m events with suffix [47m\"-FORCED\"[0m added to the names,
  may be found in community book
  [47mbooks/std/basic/code-char-char-code-with-force.lisp[0m; including this
  books (perhaps [local]ly) may rescue a proof that now fails because
  of the change.

  Fixed an induction message when limiting the number of cases, in
  particular, replacing ``we had to fold ... into a single
  IF-expression'' by ``we had to termify ... (see :DOC termify)'' and
  explaining in the new [documentation] topic, [termify].

  It is now legal to introduce more than one [elim] rule for the same
  function symbol.  Thanks to Eric Smith for pointing out that the
  current implementation was inconsistent in accepting a replacement
  [elim] rule when including a book but not at the top level.

  It is no longer illegal to read a [stobj] when in a [wormhole] state,
  for example, when inside [break-rewrite].

  In [gag-mode] (which is on by default), when the prover notes that a
  forcing round is pending, it now lists the names of the rules that
  are responsible.

  A hash-table or stobj-table field of a [stobj] may now specify a size
  that is a constant symbol with a suitable value.  See [defstobj]
  and see [stobj-table].  The meaning is the same as if the size had
  been given as the value of that constant.  Thanks to Warren Hunt
  for requesting this enhancement.

  The fifth formal of [47m[do$][0m now represents the values returned rather
  than a default value.  This change supports a bug fix; see the item
  below regarding ``About a bug in DO$ in ACL2 Version 8.5''.

  The sixth and seventh arguments of [47m[do$][0m have been combined into a
  record that also contains a list of the names of all the [47m[stobj][0ms
  in the [47mDO[0m [47mloop$[0m.  In the new record, the measure term is stored in
  untranslated form.  The record is only used in the hard error
  produced when the evaluation of a [47mDO$[0m term fails to terminate and
  is not relevant to the logical value of the [47mDO$[0m term.

  It is now legal for the parent stobj of a [47m[stobj-let][0m expression to
  occur free in the producer when no producer variable is bound in
  the bindings.  For an example, see the section ``Allow the parent
  stobj of a stobj-let expression to occur free in the producer when
  no variable bound in the bindings occurs in the producer.'' in
  [community-book] [47mbooks/system/tests/nested-stobj-tests.lisp[0m.

  Built-in function [47mbounded-integer-alistp2[0m has been modified to remove
  [47m[integerp][0m tests on formals [47mi[0m and [47mj[0m from the body and instead
  require them to satisfy [47m[posp][0m in the [guard].

  ACL2 versions of Lisp `fixnum' notions have been made more generous.
  Specifically, the value of [47m*fixnum-bits*[0m has been increased from 30
  to 61, which has increased the value of [47m(fixnum-bound)[0m from 2^29-1
  to 2^60-1.  Thanks to Eric Smith for requesting an increase.  One
  effect of this change is to increase the value of
  [47m*default-step-limit*[0m accordingly, so that the steps computed by
  [with-prover-step-limit] will no longer be limited to fewer than
  2^29.
      [31;1mNOTE[0m.  The previous such ``fixnum'' behavior can be obtained by
      building ACL2 with environment variable [47mACL2_SMALL_FIXNUMS[0m set
      to a non-empty value.  In fact, such a setting is necessary for
      a 32-bit Lisp such as CMUCL.  However, such ACL2 builds are not
      as fully tested as the usual builds and thus may be less
      reliable, and they are not guaranteed to work compatibly with
      ordinary ACL2 builds on the same set of books.

  Changed the bound [47m*maximum-positive-32-bit-integer*[0m that was used for
  array lengths (and eliminated that constant), replacing it by the
  larger value from macro call [47m(array-maximum-length-bound)[0m, which is
  the same as [47m(fixnum-bound)[0m, i.e., [47m1152921504606846975[0m.  Thanks to
  Eric Smith for suggesting that we consider such a change and for
  updating books under [47mbooks/kestrel/[0m.  Note: For CMUCL (or any
  32-bit Lisp) the bound has actually decreased, since [47m(fixnum-bound)[0m
  is [47m2^30-1[0m in that case.

  The [47m[case-match][0m macro now generates an [47mignorable[0m [47m[declare][0m form in a
  clause, for any variable occurring more than once in the pattern.
  This can free the user from the need to do so.  The following
  example illustrates this change: it now evaluates without error,
  but before this change one needed to add [47m(declare (ignorable x))[0m or
  [47m(declare (ignore x))[0m as shown.

    (let ((e '(a a))) ; same problem for '(a b) instead of '(a a)
      (case-match e
        ((x x)
         ;; Formerly needed (declare (ignorable x)) or (declare (ignore x)) here.
         t)
        (& nil)))

  The [guard]s for functions that operate on characters or strings
  sometimes insisted that the inputs contain only standard
  characters.  That restriction has been lifted, and the definitions
  of [47m[alpha-char-p][0m, [47m[upper-case-p][0m, [47m[lower-case-p][0m, [47m[char-downcase][0m,
  and [47m[char-upcase][0m have been adjusted to handle non-standard
  characters.

  The predicate [47mstate-p[0m, which recognizes ACL2 [state] objects, now
  requires that [47m[print-base-p][0m hold of state global [47mprint-base[0m.
  Also, function [47mprint-base-p[0m is now [disable]d by default.

  The predicate [47mstandard-string-alistp[0m has been deleted, while a
  related predicate [47m[string-alistp][0m has been added.

  The [break-rewrite] facility will now cause an interactive break on a
  monitored rewrite rule if the rule's equivalence relation fails to
  refine any of the equivalence relations known to be permitted while
  rewriting the target.  See [geneqv] for a discussion of how
  [congruence] rules are used to compute permitted equivalence
  relations and [refinement-failure] for advice about how to
  investigate and fix refinement failures during rewriting.

  The message for evaluation failures during proofs has been modified
  slightly, clarifying the case of substitution and, especially,
  suggesting :DOC [comment] for explanations (which has been updated
  accordingly).  Thanks to David Russinoff for an acl2-help list
  query leading to this improvement.

  It is no longer illegal for a [47m[defstobj][0m event both to specify
  keyword argument [47m:NON-EXECUTABLE T[0m and to use the [47m:CONGRUENT-TO[0m
  keyword argument.

  [47mLambda[0m objects in positions of [ilk] [47m:FN[0m are now subjected to a size
  limitation.  See [47m[explain-giant-lambda-object][0m.


New Features

  ACL2 now supports floating-point operations.  See [df].  Regarding
  this new feature: Release was approved by DARPA with ``DISTRIBUTION
  STATEMENT A. Approved for public release. Distribution is
  unlimited.'' Note for system programmers: the new [3mdf expressions[0m
  affect translation as well as stobjs-in and stobjs-out; see
  [system-utilities], specifically discussion mentioning ``df''.
  Thanks to Warren Hunt for his encouragement and support in this
  effort, towards ACL2 usage in scientific computations.

  The new zero-ary attachable system function, [47m[heavy-linear-p][0m, allows
  for enhanced use of [linear-arithmetic] during rewriting,
  specifically with the test (first) argument of a call of [47mIF[0m.
  Thanks to Eric Smith for suggesting the development of such a
  feature, which can be useful in rewriting-based tools.

  There is a new `[47mmake[0m' target to build an ACL2 executable using
  [47msave-exec[0m.  See [save-exec], in particular the new discussion at
  the end of that topic.  Thanks to Eric Smith for requesting such a
  utility.

  New utilities [47m[get-cpu-time][0m and [47m[get-real-time][0m return the cpu time
  and real (wall clock) time that has elapsed since the start of the
  ACL2 session.  Thanks to Eric McCarthy for suggesting the addition
  of such utilities.

  The new utility [47m[er-hard][0m is analogous to [47m[er-soft][0m, but for hard
  errors instead of soft errors (see [er]).

  A new command, [47m:[0m[47m[tc][0m (translate and clean), has been added.  It
  translates a given form and then ``cleans it up'', returning a
  logically equivalent but often simpler term in which logically
  irrelevant but operationally important tags have been removed.  The
  variants [47m:[0m[47m[tca][0m and [47m:[0m[47m[tcp][0m use different degrees of ``cleaning.''
  These are particularly useful for seeing the logical meanings of
  [47m[loop$][0m terms as well as terms involving [47m[mbe][0m and [47m[return-last][0m.

  A directory of [books] may now be relocated so that those books are
  still treated as certified.  This is supported by a new
  [47m[project-dir-alist][0m, which associates keywords with ``project
  directories'' and is set using environment variable [47mACL2_PROJECTS[0m;
  see [project-dir-alist].  By default, the [47mproject-dir-alist[0m has
  only one entry, which associates the keyword [47m:SYSTEM[0m with the
  [community-books] directory, [47mbooks/[0m.  The [47mproject-dir-alist[0m
  generalizes the notion of system books directory, assigning meaning
  to the [47m:dir[0m argument of [47m[include-book][0m and [47m[ld][0m and to [sysfile]
  arguments of [47m[add-include-book-dir][0m and [47m[add-include-book-dir!][0m.
  Thanks to Sol Swords for requesting such a capability and for
  helpful design discussions.  (Technical Note: Implementation-level
  changes are summarized in comments in the form [47m(defxdoc note-8-6
  ...[0m) in [community-book] [47msystem/doc/acl2-doc.lisp[0m.)

  A new [break-rewrite] command, [47m:pot-list[0m, shows the list of the
  polynomials that are assumed in the current context.  See
  [brr-commands] and see [brr@].  Thanks to Alessandro Coglio and
  Eric Smith for conversations leading to this enhancement.

  It is now possible to cause [47m[make-event][0m to do proofs during its
  expansion phase even in a context where proofs are generally
  skipped (see [ld-skip-proofsp]).  See [make-event], in particular
  the discussion there labeled as ``(4)''.  Thanks to Eric Smith for
  requesting such a feature.

  The induction mechanism in the prover can now deduce induction
  suggestions from some [47mDO[0m [47mloop$[0ms.  See
  [stating-and-proving-lemmas-about-loop$s] for a brief discussion.

  A new [47m:[0m[47m[linear][0m rule, [47macl2-count-car-cdr-linear[0m, is now built into
  ACL2, as follows.  Thanks to Eric Smith for suggesting this
  improvement (slightly renamed here) to what we originally added.

  [31;1mTheorem: [0m<acl2-count-car-cdr-linear>

    (defthm acl2-count-car-cdr-linear
      (implies (consp x)
               (equal (acl2-count x)
                      (+ 1 (acl2-count (car x))
                         (acl2-count (cdr x)))))
      :rule-classes :linear)

  The Common Lisp utility, [47m[macrolet][0m, is now supported in ACL2.
  Thanks to Alessandro Coglio for discussion leading us to make this
  addition.  See [macrolet].

  The utilities [47m[with-output][0m and [47m[with-output!][0m have been enhanced in
  the following two ways; see [with-output] for details.

    * A new keyword, [47m:inhibit-er-hard[0m, can be supplied a non-[47mnil[0m value to
      turn off hard errors when error output is inhibited.  Thanks to
      Eric Smith for a conversation leading to this enhancement.

    * The keyword [47m:off[0m for the utility [47m[with-output][0m (also [47m[with-output!][0m)
      can take on a new value, [47m:all![0m, which is treated exactly the
      same as using arguments [47m:off :all :gag-mode nil
      :inhibit-er-hard t[0m.

  The new utility [47m[with-cbd][0m creates a scope for an indicated value of
  the connected book directory (see [cbd]).  Calls of [47mwith-cbd[0m are
  allowed in [books] as well as in [47m[encapsulate][0m and [47m[progn][0m
  [events]; see [embedded-event-form].  Thanks to Sol Swords for
  requesting that [47mwith-cbd[0m be legal in embedded events.  Thanks to
  Sol Swords and Mertcan Temel for reporting a bug in an initial
  implementation.

  The new utility, [47m[with-current-package][0m, evaluates a given form with
  respect to an indicated [current-package].  Thanks to Sol Swords
  for requesting this utility.

  See [fast-cert] for a ``fast-cert'' mode for faster, but possibly
  unsound, book certification, in particular when using a saved
  executable that contains [local] events.  Thanks to Sol Swords for
  requesting such a capability and for helpful design discussions.

  Added utility [47m[set-warnings-as-errors][0m, which can change [warnings]
  to hard [errors].  Thanks to Mark Greenstreet for the idea and for
  discussions that were helpful in refining it.

  A new [47m[ld][0m special, [47m[ld-always-skip-top-level-locals][0m, has the effect
  of skipping [47m[local][0m top-level forms.  Thanks to Sol Swords for
  requesting such a capability, to support faster loading of [47m.port[0m
  files by the build system (see [47m[build::cert.pl][0m).

  The symbol, [47mnumber[0m, is now a legal [type-spec].

  It is now permitted for a [stobj] [47ms[0m to occur more than once as an
  actual parameter in a function call, provided each such occurrence
  is in a position where a stobj congruent to [47ms[0m is expected (possibly
  [47ms[0m itself).  Thanks to Sol Swords for providing a relevant example,
  which appears in a comment in the definition of function
  [47mstobjs-in-out[0m in the ACL2 sources.

  A new utility, [with-brr-data], together with related query
  utilities, allows one to find the source of a term in prover
  output.  Thanks to Sol Swords for requesting something like this in
  2008 (!) and to Eric Smith for requesting a related utility (see
  [community-books] [47mkestrel/utilities/brr-data-failures.lisp[0m and
  [47mkestrel/utilities/brr-data-all.lisp[0m).  See [with-brr-data].

  [47m[Make-event][0m takes a new keyword, [47msave-event-data[0m.  When that keyword
  is non-[47mnil[0m, event-data from the expansion saved is preserved; see
  the new section at the end of [make-event-details].  This new
  feature was motivated by the desire to preserve a proof's
  event-data in calls of [47m[thm][0m, as described in the ``Changes''
  section above.

  New utilities allow one to explore what has changed when an event
  fails in a book that formerly certified.  See [saving-event-data].
  Thanks to Eric Smith for requesting such a capability and for
  helpful bug reports for early versions of these utilities.

  A new legal value for [47m[set-verify-guards-eagerness][0m, [47m3[0m, causes guard
  verification even when [47m:verify-guards nil[0m has been [declare]d.
  This can be helpful when a [47m[verify-termination][0m event in a book is
  intended to verify [guard]s but a [local]ly included book declares
  [47m:verify-guards nil[0m in the corresponding [47mverify-termination[0m event.
  (Technical note: That issue occurs because [47mverify-termination[0m
  invokes [47m[make-event][0m, and the expansion is saved when locally
  including the sub-book.)

  When environment variable [47mACL2_WRITE_BOOKDATA[0m has a non-empty value,
  then files of the form [47m*__bookdata.out[0m will be written; see
  [bookdata] for explanation and an exception.  Thanks to Eric Smith
  for requesting this enhancement.

  [47m[Thm][0m now takes an optional [47m:instructions[0m keyword argument, like
  [47m[defthm][0m.  Thanks to Warren Hunt for requesting this enhancement.

  New utilities [47m[trans*][0m and [47m[trans*-][0m can show repeated
  macroexpansions of a form leading to its final translation, where
  [47mtrans*[0m also shows [47m[make-event][0m expansions.  Thanks to Warren Hunt
  for requesting a utility that does repeated macroexpansion.

  A new command has been added to the [proof-builder-commands], to
  display the linear arithmetic database.  See [ACL2-pc::pot-lst].
  Thanks to Dave Greve for bringing forward the idea of such a
  command.

  The utility [47m[set-raw-proof-format][0m now takes a new legal value,
  [47m:clause[0m, which is like [47mt[0m except that in addition to printing
  [rune]s as lists in output from the simplifier, it prints all goals
  as [clause]s.  Thanks to Eric Smith for encouraging such an
  enhancement.

  It is possible to cause ACL2 to increase its effort in
  [type-reasoning].  See [set-dwp].  Thanks to Eric Smith for
  correspondence leading to this feature.

  The new documentation topic, [induction-coarse-v-fine-grained],
  discusses how appropriately setting ruler-extenders can sometimes
  improve the induction scheme suggested by a recursive function,
  especially one involving [47m[let][0m and [47m[let*][0m bindings containing
  conditional recursive calls.  For that new topic, new related books
  [47mbooks/demos/ppr1-experiments.lisp[0m and
  [47mbooks/demos/ppr1-experiments-thm-1-ppr1.lisp[0m, and related edits of
  existing :DOC topics ([advanced-features], [definductor], [defun],
  [induction], [rulers], [verify-termination], and [xargs]): Release
  was approved by DARPA with ``DISTRIBUTION STATEMENT A. Approved for
  public release. Distribution is unlimited.''

  A new supported value for [47m(@ script-mode)[0m, [47mskip-ldd-n[0m, directs the
  [47m[run-script][0m tool to prevent [history] commands such as [47m:[0m[47m[pe][0m from
  printing event numbers.  That can make the output less sensitive to
  ACL2 changes.  For an example, see the use of [47m(assign script-mode
  'skip-ldd-n)[0m in [community-book] file
  [47mbooks/demos/floating-point-input.lsp[0m.

  A new [stobj] field keyword, [47m:element-type[0m, is legal for an array
  field.  It specifies the raw Lisp element type of the array.  Its
  value can be the element type specified by the value of the [47m:type[0m
  for that array field.  That is the default value, and the other
  legal value is [47mt[0m, but these may change in the future.  See
  [defstobj] and see [defstobj-element-type].

  A new [47mbrr[0m command, [47m:[0m[47m[explain-near-miss][0m, when issued in a break
  caused by a near miss, will try to pinpoint how the rule's pattern
  failed to match the current target.

  A new utility, [47m[compare-objects][0m, highlights the differences between
  two [47mcons[0m-trees.

  Now [47m[defabsstobj][0m accepts the [47m:non-executable[0m keyword, in analogy to
  support for that keyword by defstobj.  Thanks to Yahya Sohail and
  Warren Hunt for discussions leading to this enhancement.

  New functions [47m[add-global-stobj][0m and [47m[remove-global-stobj][0m change
  whether there is a global (``live'') stobj for a given stobj name,
  thus modifying the effect of the keyword [47m:non-executable[0m of events
  [47m[defstobj][0m and [47m[defabsstobj][0m.  Thanks to Yahya Sohail and Warren
  Hunt for discussions leading to the addition of these utilities.

  A new [47m[defabsstobj][0m keyword, [47m:attachable[0m, allows a single abstract
  [stobj] to have more than one foundation and associated functions
  for execution, without the need to recertify the book that
  introduces the stobj.  See [47m[attach-stobj][0m.  Thanks to Warren Hunt
  and Yahya Sohail for requesting this feature.  We thank Sol Swords,
  Warren, and especially Yahya for helpful input on its high-level
  design.


Heuristic and Efficiency Improvements

  Added a ``desperation heuristic'' to compute a stronger context, for
  the extra try at simplification made after a goal is not changed by
  simplification.  Thanks to Warren Hunt and Vivek Ramanathan for
  supplying an example of a theorem whose proof had a surprising
  failure but now succeeds.  (Technical Remark describing this
  change: When a [clause] has most recently settled down at the time
  that the simplify process is invoked (a so-called ``desperation
  heuristics'' attempt), then the literals are reordered before
  building the [type-alist], so that the literals that involve at
  most one variable precede the other literals.)

  Generation of guard [clause]s (and, probably rarely, other goals) has
  been sped up in certain extreme cases.  For details, see
  [system-attachments], specifically the discussion of
  CONJOIN-CLAUSE-SETS-BOUND in the ``Summary of attachable system
  functions''.  Thanks to Alessandro Coglio for sending an example
  that led to our discovery of the quadratic behavior eliminated by
  this change.

  Duplicate entries in [type-alist]s (proof contexts) are now avoided
  in many cases.  (Implementation note: some calls extending the
  type-alist with an existing term/type-set pair are now avoided in
  source function [47massume-true-false-rec[0m.)  Thanks to Eric Smith for
  pointing out that there can be type-alists with many consecutive
  identical entries.

  Sped up macroexpansion for several common macros, with roughly a 2%
  to 3% speedup observed for including several large books during
  development of this change.

  Tweaked [linear-arithmetic] to avoid consideration of an equality
  between two terms that are both known (via their [type-set]s) to be
  non-numeric.

  The utility [47m[set-cbd][0m is more efficient when setting to the current
  [47m[cbd][0m, including the common case of calls to [47mset-cbd[0m by [47m[ld][0m and
  (hence) [47m[wormhole][0m.

  New built-in [rewrite] rules [47mall-boundp-initial-global-table-alt[0m and
  [47mall-boundp-initial-global-table[0m may help with reasoning about
  [47mstate-p1[0m.  Use [47m:[0m[47m[pe][0m to see their [events].  The latter is
  [disable]d by default and may useful to [enable] when developing
  proofs that rely on built-in [state] globals being bound.

  ACL2 has a procedure for evaluating ground [term]s (terms without
  free variables) that is used in the generation of [guard]
  obligations as well as in [linear-arithmetic] and
  [forward-chaining].  This procedure was not used on subterms of
  bodies of [lambda] expressions, but now it is.  Thanks to Eric
  Smith for requesting this enhancement (in particular for generation
  of guard obligations).

  The ACL2 [type-reasoning] mechanism has been strengthened slightly
  for an [47mif[0m expression being assumed true or false, when that
  expression has a subterm of the form [47m(equal term 'c)[0m, or [47m(equal 'c
  term)[0m and [47mc[0m is [47m0[0m, [47m1[0m, [47mt[0m, or [47mnil[0m.  Thanks to Warren Hunt for sending
  an example involving [forward-chaining] that led to this
  improvement.  [31;1mIMPORTANT NOTE:[0m If this change causes a proof to fail
  that formerly succeeded, you can fix it by preceding it with the
  following (implicitly [local]) event.

    (defattach-system use-enhanced-recognizer constant-nil-function-arity-0)

  For a book's event of the form [47m(defconst *NAME* (quote VAL))[0m that
  results from [47m[make-event][0m expansion, [47mVAL[0m is no longer duplicated
  between that book's [certificate] file and its compiled file.
  Thanks to Sol Swords for requesting this enhancement.  This lack of
  duplication also applies to any such [47mdefconst[0m event in a book that
  is in the scope of a [47m[progn][0m or [47m[encapsulate][0m event when there is
  at one [47mmake-event[0m call in that scope; similarly for such [47mdefconst[0m
  events within calls of [47m[skip-proofs][0m, [47m[with-output][0m,
  [47m[with-guard-checking][0m, or [47m[with-prover-step-limit][0m.

  Each new stobj was being created twice at [47m[include-book][0m time, once
  when the book's compiled file is loaded and once when the
  [47m[defstobj][0m or [47m[defabsstobj][0m event is processed.  The former
  initialization is unnecessary and has been eliminated.

  A limit has been placed on generation of equality hypotheses by
  linear arithmetic.  For example, if a goal has hypotheses
  (technically: negative literals) [47m(<= term1 term2)[0m and [47m(<= term2
  term1)[0m, it may generate the hypothesis [47m(equal term1 term2)[0m.  This
  is now indicated by the phrase \"equality generation from
  inequalities\" found in proof output if you have evaluated the form
  [47m(set-gag-mode nil)[0m, and it is now indicated in the proof [summary]
  by the presence of the [rune], [47m(:FAKE-RUNE-FOR-LINEAR-EQUALITIES
  NIL)[0m.  By default, there is a limit of five ``levels'' of such
  equality generation, for example in goals [47m\"Subgoal 2\"[0m, [47m\"Subgoal
  2.1\"[0m, [47m\"Subgoal 2.1.3.4.5\"[0m, [47m\"Subgoal 2.1.3.4.5'\"[0m, and [47m\"Subgoal
  2.1.3.4.5''\"[0m --- in general, such addition of equalities can only
  be performed five times along a chain of goals where each is a
  descendent (not necessarily an immediate subgoal) of the one
  before, and each induction and forcing round provides a fresh
  start.  You can change that default from 5 to [47mn[0m, where [47mn[0m is a
  natural number, by evaluating the following form.

    (table equational-polyp-limit-table t n)

  Thanks to Eric Smith for sending an example with looping behavior,
  which motivated the change above (as a way to break such loops).


Bug Fixes

  Fixed a soundness bug based on rules of class [47m:[0m[47m[meta][0m or
  [47m:[0m[47m[clause-processor][0m that would be exported from an [47m[encapsulate][0m
  event with a non-[47mnil[0m [signature] list.  A proof of [47mnil[0m in Version
  8.5 may be found in the [community-books] file,
  [47mbooks/system/tests/transparent-functions-input.lsp[0m; search for this
  paragraph there.

  Fixed a soundness bug in [47m[open-input-channel][0m and
  [47m[open-output-channel][0m.  The [guard] in each case required the first
  argument, a file name, to be a string; but these functions pass
  that argument to a function --- [47mmake-input-channel[0m and
  [47mmake-output-channel[0m, respectively --- that required the string to
  contain only standard characters (see [standard-char-p]).  That was
  possible because [47mopen-input-channel[0m and [47mopen-output-channel[0m were
  invoked under [47m[skip-proofs][0m in the ACL2 sources.  This bug has been
  fixed, and those uses of [47mskip-proofs[0m eliminated, with removal of
  the restriction to standard characters for virtually all guards,
  including the guards for Common Lisp functions [47m[char-downcase][0m and
  [47m[char-upcase][0m.  Thanks to Eric Smith for reporting this bug,
  including a proof of [47mnil[0m by giving a [47m:use[0m hint for an [47m:instance[0m of
  [47m(:guard-theorem open-input-channel)[0m.  Eric also supplied events,
  incorporated into ACL2 source file [47maxioms.lisp[0m, that removed the
  [47m[skip-proofs][0m wrappers from five definitions.

  Fixed a soundness bug that exploited incorrect generation of raw Lisp
  code for the recognizer of a [stobj] field of a stobj.  More
  precisely, the bug occurred when a concrete stobj has a field whose
  type is the name of either a concrete or abstract stobj.  Here is
  an example.

      First certify the following book, sub.lisp.

        (in-package \"ACL2\")
        (defstobj lo lo-fld)
        (defstobj hi (hi-fld :type lo))

      Then before the bug was fixed, the following book was certifiable.

        (in-package \"ACL2\")
        (include-book \"sub\")
        (defthm thm1 ; logically correct
          (hi-fldp '(nil))
          :rule-classes nil
          :hints ((\"Goal\" :in-theory (disable (:e hi-fldp)))))
        (defthm thm2 ; \"proved\" by unsound execution
          (not (hi-fldp '(nil)))
          :rule-classes nil)
        (thm ; proof of nil
         nil
         :hints ((\"Goal\" :use (thm1 thm2))))

  It was probably a soundness bug to allow a [47m[defaxiom][0m event to
  designate a rule of class [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m in its
  [47m:[0m[47m[rule-classes][0m.  That is no longer allowed; [47m[skip-proofs][0m may be
  used instead if one believes that the proposed formula is a
  theorem.

  The function [47m[read-file-into-string][0m has been modified to avoid what
  might be considered a soundness bug.  The change involves causing
  an error for two reads of the same file without first incrementing
  the file-clock of the [state].  See [read-file-into-string] for
  details, in particular for how to avoid that error by evaluating
  [47m(increment-file-clock state)[0m after calling [47mread-file-into-string[0m.
  Formerly the error was avoided if the write-date of the file didn't
  change between the two reads, but the following example shows how
  this permitted two calls with identical arguments to produce
  different results, logically causing [47mread-file-into-string[0m to
  violate the axiom [47mx = x[0m.

      First run the following shell commands.

        echo 'test1' > tmp1.txt ; echo 'test2' > tmp2.txt
        cp -p tmp1.txt tmp.txt

      Then start ACL2 and run a command as follows.

        ACL2 !>(read-file-into-string \"tmp.txt\")
        \"test1
        \"
        ACL2 !>

      Now suspend ACL2 with [47mcontrol-Z[0m and run the following shell command.

        cp -p tmp2.txt tmp.txt

      Now resume ACL2 with [47mfg[0m, and optionally submit some trivial form
      (say, [47m3[0m) just to get the prompt back.  Note that the file-clock
      of the [47mstate[0m hasn't changed.  (Probably the [47mstate[0m hasn't
      changed; at any rate, the parts of the state relevant to
      [47mread-file-into-string[0m haven't changed.)  So the following call
      has arguments identical to those in the corresponding call
      above, yet yields a different result.

        ACL2 !>(read-file-into-string \"tmp.txt\")
        \"test2
        \"
        ACL2 !>

      After the change to [47mread-file-into-string[0m, its call just above causes
      an error.

  Plugged a potential soundness hole in [47m[defwarrant][0m (though we have
  not actually observed unsoundness), with changes that will probably
  be invisible to users.  Thanks to Sol Swords for bringing this
  issue to our attention.

  Fixed a bug in system function [47mbounded-integer-listp[0m, which may have
  allowed illegal [proof-builder] commands to be attempted.  Thanks
  to Grant Jurgensen for pointing out this bug.

  Consider calls of [47m[defthm][0m and [47m[thm][0m that create subgoals before
  reverting to prove the original goal by induction.  The Rules
  summary printed at the end should exclude rules used only before
  the start of that induction proof.  That was formerly the case for
  [47mdefthm[0m but not [47mthm[0m, but now it is the case for both.  You can see
  the change for the following call, whose Rules summary formerly
  included [47m(:ELIM CAR-CDR-ELIM)[0m but no longer does so.

    (thm
     (equal (append (append x y) z)
            (append x y z))
     :hints ((\"Goal\"
              :expand ((:free (b) (append x b))
                       (:free (a b) (append (cons (car x) a) b))))))

  Fixed bugs in the definition of source macro [47mposition-ac[0m.  Thanks to
  Eric Smith for pointing them out.

  Several improvements were made to the [47mFOR[0m [47m[loop$][0m utility (also see
  [for-loop$], to reflect more accurately the Common Lisp [47mloop[0m
  utility.  This matters because in [guard]-verified code, [47mloop$[0m
  becomes [47mloop[0m.  Here are the most user-visible such changes.

    * Run-time [guard]-checking for [47m[loop$][0m operators [47mSUM[0m and [47mAPPEND[0m did
      not include a check that the value produced at each iteration
      is a number or true list, respectively.  That has been fixed so
      that, for example, the expression [47m(loop$ for v in '(1 a 2) sum
      v)[0m now causes a guard violation (because [47ma[0m is not a number),
      where previously it did not.

    * For a form [47m(loop$ for tail on lst ...)[0m, the target term, [47mlst[0m, no
      longer needs to satisfy [47m[true-listp][0m.  For example, the form
      [47m(loop$ for tail on '(a b . c) collect tail)[0m no longer causes a
      [guard] violation.

    * Run-time [guard]-checking for an expression [47m(loop$ for tail on lst
      ...)[0m now includes a check for the target, [47mlst[0m, that its final
      tail (i.e., [47m(last-cdr lst)[0m) satisfies the declared type of the
      corresponding iteration variable.  For example, evaluation of
      the [47m[loop$][0m expression below now produces a guard violation as
      shown, but it formerly did not produce a guard violation.

          ACL2 !>(loop$ for tail of-type cons on '(a b c) collect tail)


          ACL2 Error [Evaluation] in TOP-LEVEL:  The guard condition
          (CONSP LOOP$-LAST-CDR), which was generated from a type declaration,
          has failed.
          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 !>

      Corresponding run-time checking was added for the types of the lower
      and upper bounds [47mlo[0m and [47mhi[0m, the increment [47minc[0m, and the last
      value tested, in expressions [47m(loop$ for i from lo to hi by inc
      ...)[0m.

  Fixed a low-level bug in source function
  [47mtranslate-declaration-to-guard1-gen[0m that was incorrectly creating
  untranslated [term]s in some cases from [type] declarations of the
  form [47m(type (signed-byte _) _)[0m or [47m(type (unsigned-byte _) _)[0m.  Here
  is an example of an event that is rejected without the bug fix.

    (defun foo (n)
      (apply$ (lambda$ (x)
                       (declare (type (signed-byte 8) x)
                                (xargs :guard (signed-byte-p 8 x) :split-types t))
                       (+ 3 x))
              (nfix n)))

  Suppose a book is certified in a [world] where a [portcullis]
  [command] generates a [47m[local][0m call of [47m[make-event][0m.  Then that
  event is now ignored when subsequently including that book.
  Previously it may not have been ignored, because the [47mlocal[0m wrapper
  could be ignored when writing the book's [certificate].

  Some handling of exceptional cases in [hints] has been cleaned up, as
  follows.  Thanks to Eric Smith for a discussion that led to these
  changes.

    * [Warnings] for repeating a goal name in the hints now appear even
      when the repetition is only up to case.  For example, such a
      warning is generated now for [47m:hints ((\"Goal\" :use foo) (\"GOAL\"
      :use bar))[0m where formerly it was not.  The discussion of this
      situation in documentation topic [hints] has been improved.

    * It was incorrectly documented in topic [hints], in the discussion of
      [47m:do-not[0m hints, that it is illegal to associate a goal name with
      the empty list of [hints], as in [47m(\"Goal\")[0m.  This behavior was
      actually allowed; an empty such hint was simply ignored.  This
      continues to be allowed (for backward compatibility) but the
      documentation has been updated; also, these empty hints are now
      ignored for purposes of the warnings mentioned above (formerly
      they were considered when looking for repetition of goal
      names).

  A bug in the [brr] commands [47m:eval$[0m, [47m:go$[0m, and [47m:ok$[0m was fixed so they
  now behave as described in the documentation for [brr-commands].

  When a certified book is included, the logical [world] will no longer
  be marked as having seen a [47m[skip-proofs][0m call due to [47m[ld][0m special
  [47m[ld-skip-proofsp][0m having a non-[47mnil[0m value at that time.  Thus, that
  situation no longer disqualifies such a world from supplying the
  [portcullis] commands to a book to be certified without keyword
  argument [47m:skip-proofs-okp t[0m of [47m[certify-book][0m.  Thanks to Sol
  Swords for pointing out this bug.

  Fixed a bug that was causing calls of [47m[wormhole][0m to signal an error.

  Fixed a bug that could cause a [47m[do-loop$][0m expressions to be
  inappropriately rejected due to an allegedly ignored variable.  An
  example is below.

    (include-book \"projects/apply/top\" :dir :system)
    ; BUG: The following was formerly necessary, but no longer is.
    (set-ignore-ok t)
    (defun f (a b)
      (loop$ with x = a with y = b
             do
    ; The use of (set-ignore-ok t) was needed, but shouldn't have been,
    ; whether or not the next line is included.
             :measure (+ (len x) (len y))
             (cond ((consp y)
                    (let ((z y))
                      (progn (setq y (cdr x))
                             (setq x (cdr z)))))
                   (t (return y)))))

  Fixed the failed redundancy check when setting a [table] guard that
  returns two values.  For example, the form [47m(table foo nil nil
  :guard (mv t nil))[0m was not formerly seen as [redundant] when
  evaluating it a second time.

  Fixed a bug that was causing [47m[cw-gstack][0m to report ``Rewriting (to
  simplify) the first argument'' when rewriting the second argument
  of a call of [47m[implies][0m, and fixed an analogous bug for
  [47m[return-last][0m.

  Fixed a bug in [47m[intersection$][0m that prevented it from being called
  with keyword argument [47m:test 'equal[0m.  Thanks to Anna Slobodova for
  bringing this bug to our attention.

  Certain error messages from [47m[translate][0m and [47m[untranslate][0m are now
  inhibited when they should be (where formerly they weren't).
  Thanks to Eric Smith for bringing this problem to our attention.

  Fixed a bug that in rare cases, for direct prover calls (e.g., with
  [47m[prove$][0m, could cause an error reporting ``HARD ACL2 ERROR in
  pop-warning-frame''.  Thanks to Eric Smith for bringing this bug to
  our attention.  Note that with this change, then when an [event]'s
  evaluation causes a hard error (see [er] and [hard-error]):
  [summary] information may be printed that was formerly omitted; and
  a superfluous extra failure message may be omitted that was
  formerly printed.

  The function [47m[delete-file$][0m executed in a way that diverged from its
  logical definition: successful deletion caused return values of [47m(mv
  t state)[0m but this was provably impossible according to the logical
  definition.  This has been fixed.

  Fixed the [useless-runes] feature to work properly when reading a
  useless-runes file while certifying a book in a package other than
  the [47m\"ACL2\"[0m package.  The fix is to ensure that the useless-runes
  file is read while in the [47m\"ACL2\"[0m package, which is the same package
  used when the file was written.

  Fixed a bug in handling of the [47m[ld][0m keyword [47m:ld-missing-input-ok[0m, by
  eliminating an error in the case that the specified input file's
  directory does not exist.  The fix avoids executing some of the [47mld[0m
  code that was formerly executed.  Thanks to Alessandro Coglio and
  Eric Smith for bringing this bug to our attention.

  An error formerly occurred if one first evaluated [47m(defwarrant FN)[0m for
  some [47mFN[0m and then attempted to include a certified book containing
  [47m(defbadge FN)[0m.  That has been fixed.  Thanks to Mertcan Temel for
  reporting this bug.  Such a [47m[defbadge][0m event is now a no-op, which
  is reported by an [47m[observation][0m except during [47m[include-book][0m and
  except during the second pass of an [47m[encapsulate][0m event.  Moreover,
  the [47m[defwarrant][0m event now returns the value [47m:WARRANTED[0m instead of
  [47mT[0m --- more precisely, it returns a [value-triple] whose value
  component is [47m:WARRANTED[0m --- and similarly for [47m[defbadge][0m and
  [47m:BADGED[0m.

  We fixed a bug that caused the [tau-system] sometimes to cause a raw
  Lisp error when the [executable-counterpart]s of certain primitive
  recognizers were [disable]d.  Thanks to Eric Smith for reporting
  this bug and providing an example of it.

  We fixed a bug that might cause suitable induction schemes to be
  eliminated because of inappropriate consideration of [47m:[0m[47m[definition][0m
  rules.

  Some [proof-builder] commands, including [47m:claim[0m and [47m:casesplit[0m, are
  more robust (specifically, when claiming or splitting on certain
  terms that are trivially true).  Thanks to Drew Walter for
  supplying an illustrative example.

  A bug in [47m[trace$][0m could trigger raw Lisp errors when the [47m:entry[0m,
  [47m:exit[0m, or [47m:cond[0m option specified an ill-guarded expression.  For
  example, after evaluating [47m(defun f (x) x)[0m and then [47m(trace$ (f
  :entry (car x)))[0m, evaluation of [47m(f 3)[0m caused a raw Lisp error due
  to evaluation of [47m[car][0m on the value, 3.  This has been fixed.
  (Technical Remark: the fix was to replace the expression with the
  same ``oneify'' process that is used for generating definitions of
  executable-counterpart functions; [evaluation].)

  Eliminated the built-in [47m:[0m[47m[type-prescription][0m rule [47mtrue-listp-take[0m,
  thanks to Eric Smith, who pointed out that the same rule is already
  installed as the built-in [47m:type-prescription[0m rule for [47m[take][0m.

  Fixed a bug in handling of [47m[do-loop$][0m expressions that return
  multiple values, when encountered during proofs.  An example
  labeled with ``Version 8.5'' is near the end of [community-book]
  [47mprojects/apply/loop-tests.lisp[0m.

  A bug in [47m[do$][0m, hence in [47m[do-loop$][0m expressions, was that
  single-threadedness (for [stobj]-based computations) can be
  violated when a loop terminates prematurely because the measure
  fails to decrease.  The bug, which has been fixed, is explained in
  detail in a comment in ACL2 source file [47mapply.lisp[0m, entitled
  ``About a bug in DO$ in ACL2 Version 8.5''.

  Fixed a bug in [47m[fmt][0m and related functions, where a right square
  bracket immediately following a [47m~&[0m or [47m~v[0m directive failed to be
  printed, for example: [47m(fmx \"hello ~&0]~|\" '(world))[0m.

  Fixed a bug that could cause an implementation error during a proof,
  when printing a term with a [47m[do$][0m call.  (The bug was in
  untranslating certain applications of [47m[nth][0m, [47m[update-nth][0m, or
  [47m[update-nth-array][0m during a proof.)

  [47m[With-global-stobj][0m no longer produces an invalid result when its
  first argument names a non-executable [stobj].  Previously, the
  call of [47mread-state[0m below could return the nonsensical result
  637624320.

    (defstobj st fld :non-executable t)
    (defun read-state (state)
      (declare (xargs :stobjs state))
      (with-global-stobj st (fld st)))
    (read-state state)

  Fixed two bugs when attempting to redefine with [47m[defabsstobj][0m.  The
  visible bug was a printing error.  A second bug, not visible to the
  user because of the first bug, was a low-level bug that prevented
  one of the supporting names from being recorded in the [world] as a
  supporter of the given stobj.


Changes at the System Level

  The `[47mmake[0m' target, [47msave-exec[0m, now builds [47mcustom-saved_acl2[0m
  unconditionally.  Thanks to Grant Jurgensen for pointing out (in
  GitHub Issue #1422) that there can be untracked implicit
  dependencies that make this necessary.

  Implementations underlying the functions [47m[sys-call][0m, [47m[sys-call+][0m, and
  [47m[sys-call*][0m have been cleaned up.  In particular, we now expect
  them to indicate precisely the case of a non-error process return
  as follows: 0 for [47m[sys-call-status][0m, and [47mnil[0m for the first return
  value of [47msys-call+[0m and [47msys-call*[0m.  Also, a bug has been fixed for
  [47msys-call+[0m in the case of GCL as the host Lisp.  Thanks to Eric
  Smith for queries leading to these changes.

  Significantly extended documentation topic [system-attachments],
  which now lists all built-in system attachments, many with brief
  documentation.  Thanks to Eric Smith for suggesting this
  enhancement.

  Significant new [documentation] topics, together with subtopics and
  books supporting those topics, include the following.  [See DARPA
  Note above.]

    * [Start-here] provides a guide for those getting started with ACL2.

    * [Recursion-and-induction] has been extensively modified from past,
      standalone versions by J Moore, and is now integrated with the
      rest of the [documentation].  Thanks to Vivek Ramanathan for
      helpful feedback.

    * [Gentle-introduction-to-acl2-programming] has also been updated from
      past standalone versions and integrated into the rest of the
      documentation.

    * [Loop$-primer] provides an extensive primer on the the ACL2 [47m[loop$][0m
      feature.

    * [Type-reasoning] gives a basic introduction to what has sometimes
      been called ``type-set reasoning'' but is now generally
      referred to as ``type reasoning''.  This new topic is now
      referenced in many other built-in documentation topics.  Thanks
      to Warren Hunt for communication leading to this new topic.

    * [Soundness] discusses what we can conclude when we use ACL2 to prove
      a formula or to compute the value of an expression.

  Allow [47m[ld][0m output in [raw-mode] to go to other than the channel,
  [47m*standard-co*[0m.  Thanks to Vivek Ramanathan and Warren Hunt for an
  example illustrating the issue.

  (For system hackers only) The feature [47m:acl2-loop-only[0m is now true
  inside the ACL2 read-eval-print loop.  Therefore, the function [47mlp![0m
  is no longer supported or necessary, since [47m(lp)[0m enters the loop
  with feature [47m:acl2-loop-only[0m true, just as [47m(lp!)[0m did previously.

  (CCL only) [Stobj] array code now has a workaround for a {CCL bug |
  https://github.com/Clozure/ccl/issues/446} found by Yahya Sohail,
  in the case of reading a stobj array of integers where the element
  type includes at least one negative number and one non-fixnum.
  That bug has been around since at least as far back as 2017, and
  was fixed on June 12, 2023.  For those using a CCL version with the
  bug, this fix may slow down such stobj array reads a bit in the
  case described above; one measurement showed about 37% more time
  for such a read.  Thanks to Yahya for the bug report, to Warren
  Hunt for encouraging a workaround, and to the CCL developers (in
  particular Gary Palter) for fixing the CCL bug.

  The undocumented utility, [47mthm-fn[0m --- which is used in several
  [community-books] --- now has an additional formal (at the end),
  [47mevent-form[0m.  That argument can generally be passed as [47mnil[0m for
  appropriate behavior.

  Code for [47m[set-cbd][0m has been tweaked to add assurance that the [47m[cbd][0m
  always ends in a forward slash (`[47m/[0m'), as specified.  Thanks to
  Stephen Westfold for a comment leading to this modification.

  Updated file [47mGNUmakefile[0m in the top-level directory so that when an
  ACL2 executable is built, files are updated in subdirectory
  [47mbooks/build/[0m to support the use of [47m[build::cert.pl][0m.  Thanks to
  Eric Smith for the idea, and thanks to Eric and also Sol Swords for
  help with the implementation.

  The notion of ACL2 [state] is formalized in function [47mstate-p1[0m, which
  has implicitly changed because it depends on the constant
  [47m*initial-global-table*[0m, whose value has changed.  That constant's
  value, which is still an alist, now includes additional pairs,
  which are from the constant [47m*initial-ld-special-bindings*[0m; thus,
  [47m*initial-global-table*[0m now specifies a value for each so-called
  ``[47m[ld][0m special''.

  The previous ACL2 release (Version 8.5) arranged that when a raw Lisp
  error is encountered, any available input is cleared from the input
  channel.  However, this can lead to discarding of valid input or an
  attempt to read values from within a comment; see [community-books]
  files [47mclear-input-1.lsp[0m and [47mclear-input-2.lsp[0m, respectively, in
  directory [47mbooks/system/tests/[0m.  So now, input is cleared on error
  only when reading from the terminal (technically, from
  [47m[*standard-oi*][0m).

  Improved certain build-time error messages.  These improvements are
  particularly helpful when the host Lisp is SBCL or CMUCL, so that
  the error message is printed properly into make.log (instead of
  showing up as an error call at the terminal), and also when the
  host Lisp is LispWorks, so that verbose debugging information is
  avoided (since these are ACL2 errors for which that information is
  very unlikely to be helpful).  Thanks to Alessandro Coglio for a
  recent Zulip query that led us to make this change.

  A new documentation topic and its subtopics describe uses of ACL2 and
  its predecessor, Nqthm, in modeling state machines.  See
  [operational-semantics], which notes that others are welcome to add
  to these topics; see the discussion of ``Request for Suggestions
  from ACL2 Users''.  The new topic incorporates an annotated
  bibliography pointing to more than 40 topics in a new [47m\"BIB\"[0m
  package.


EMACS Support

  A set of tools for assisting in the conversion of certain HTML to
  [47m[xdoc][0m may be found, without much documentation, in
  [47memacs/html-to-xdoc.el[0m.  [See DARPA Note above.]

  When new [ACL2-doc] buffers are created by using the [47mG[0m or
  [47mShift-<Return>[0m commands, their name reflects the topic name, e.g.,
  [47macl2-doc<REWRITE>[0m if the topic visited in the new buffer is
  [47mREWRITE[0m.  Note that the new buffer name stays the same even if
  other topics are visited there; its name reflects its topic at the
  time it was created.  Thanks to Warren Hunt for requesting such an
  enhancement.  Note that the former behavior can be restored by
  evaluating the form [47m(setq *acl2-doc-short-new-buffer-names* t)[0m in
  Emacs.

  The initialization file for recent Emacs versions,
  [47mbooks/emacs/emacs-acl2.el[0m, now correctly loads related files ---
  notably [47macl2-doc.el[0m --- from that same directory, rather than from
  the [47memacs/[0m directory that is directly under the top level of the
  ACL2 distribution.

  [Documentation] printed to the terminal or in the [ACL2-Doc] Emacs
  browser can respect certain [xdoc::markup] that was formerly
  ignored, but is no longer (by default), as follows.

    * Fonts are largely respected.  For example, text marked as underline
      is now underlined, and text marked as having typewriter font
      now has a grey background.  This closes GitHub Issue 1487.
      Thanks to Grant Jurgensen for helpful feedback on the original
      plan, which had been to use delimiting underscores rather than
      Select Graphic Rendition (SGR) control sequences.  See
      [xdoc::terminal] for details and for ways to customize
      behavior, including avoidance of SGR.

    * Images now appear in [ACL2-Doc] (but not with [47m:[0m[47mdoc[0m at the terminal),
      instead of [47m{IMAGE}[0m, on systems that can display graphics inside
      Emacs.  Thanks to Warren Hunt for requesting this enhancement.

  The documentation for [ACL2-Doc] says of the search commands [47ms[0m and [47mS[0m,
  ``go to that topic with the cursor put immediately after the found
  text''.  But the cursor was at the end of the found text, not
  immediately after it.  That has been fixed.

  For the [ACL2-doc] browser, the download ([47mD[0m) command now accesses, by
  default, an [47mhttps[0m address instead of an [47mhttp[0m address.  Thanks to
  Warren Hunt for suggesting this change.

  In [ACL2-doc], modified the [47mTAB[0m and [47mShift-TAB[0m (sometimes known as
  [47m<backtab>[0m) commands so that they alert the user when wrapping.


Experimental Versions

  The note ``Note: No checkpoints to print.'' that might be printed on
  proof failure is now the same in ACL2(p) as in ACL2, unless
  [waterfall-parallelism] is enabled (in which case ``no
  checkpoints'' is followed by `` from gag-mode'' as before).")
 (NOTE-8-7
  (RELEASE-NOTES)
  "ACL2 Version 8.7 (xxx, 20xx) Notes

  NOTE!  New users can ignore these release notes, because the
  [documentation] has been updated to reflect all changes that are
  recorded here.

  Below we roughly organize the changes to ACL2 since Version 8.6 into
  the following categories of changes: existing features, new
  features, heuristic and efficiency improvements, bug fixes, changes
  at the system level, Emacs support, and experimental versions.
  Each change is described in just one category, though of course
  many changes could be placed in more than one category.

  Note that only ACL2 system changes are listed below.  See also
  note-8-7-books for a summary of changes made to the ACL2 Community
  Books since ACL2 8.6, including the build system.


Changes to Existing Features


New Features


Heuristic and Efficiency Improvements

  Applications that use functions with floating-point inputs or outputs
  (see [df]) may generate less memory usage, at least in SBCL
  releases strictly after SBCL Version 2.9 and SBCL github versions
  after mid-October, 2024.  Thanks to Stas Boukarev for enhancing
  SBCL to support this improvement (made by adding suitable
  proclaiming in ACL2).


Bug Fixes

  Fixed a soundness bug in the [proof-builder] that could cause goals
  from [47m[force][0md hypotheses to be created incorrectly.  (This bug has
  been around for at least 10 years and probably for 30 years!)

  A Lisp error is now avoided when saving event-data (see
  [saving-event-data] and submitting certain ill-formed attempts at
  [events].  Thanks to Eric Smith for sending the following example.

    (assign event-data-fal 'event-data-fal)
    (defuns foo (x) x)

  Fixed a bug in the interaction of [47m[memoize-partial][0m with utilities
  [47m[save-and-clear-memoization-settings][0m and
  [47m[restore-memoization-settings][0m.  The latter utilities no longer
  have an effect on functions created by [47m[memoize-partial][0m (or, and
  this is quite obscure, on memoization from calls of [47m[memoize][0m with
  a non-[47mnil[0m value of the keyword, [47m:total[0m).

  An attachable stobj (see [attach-stobj]) was created by the
  executable ([47m:EXEC[0m) function associated with its stobj creator (see
  [defabsstobj]), even when that stobj was given an attachment.  This
  bug has been fixed: the stobj is now created by the [47m:EXEC[0m of the
  attachment's creator.


Changes at the System Level

  Modifications have been made that allow ACL2 to be hosted on GCL
  Version 2.7.0 and presumably later [gcl] versions; previously only
  GCL versions before 2.7.0 could host ACL2.  Essentially the only
  user-visible change (other than error prevention) is the
  introduction of [47m[list$][0m, a macro equivalent to [47m[list][0m that can be
  used without a GCL 2.7.0 restriction on the number of arguments.
  The most sweeping implementation-level change is the replacement of
  an array in support of so-called [3mstatic honses[0m, the [3msbits array[0m, by
  a structure that avoids a reduced bound on array dimensions imposed
  by GCL 2.7.0.  Details may be found in a Lisp comment in the form
  [47m(defxdoc note-8-7 ...)[0m in [community-books] file
  [47mbooks/system/doc/acl2-doc.lisp[0m.  Thanks to Camm Maguire for his
  help with this project, including (but by no means limited to) his
  contribution of a new sbits implementation.


EMACS Support


Experimental Versions")
 (NOTE1 (POINTERS) "See [note-1-1].")
 (NOTE2 (POINTERS) "See [note-1-2].")
 (NOTE3 (POINTERS) "See [note-1-3].")
 (NOTE4 (POINTERS) "See [note-1-4].")
 (NOTE5 (POINTERS) "See [note-1-5].")
 (NOTE6 (POINTERS) "See [note-1-6].")
 (NOTE7 (POINTERS) "See [note-1-7].")
 (NOTE8 (POINTERS) "See [note-1-8].")
 (NOTE8-UPDATE (POINTERS)
               "See [note-1-8-update].")
 (NOTE9 (POINTERS) "See [note-1-9].")
 (NQTHM-TO-ACL2
  (ACL2-TUTORIAL)
  "ACL2 analogues of Nqthm functions and commands

    Example Forms:
    :nqthm-to-acl2 prove-lemma   ; Display ACL2 topic(s) and/or print
                                 ; information corresponding to Nqthm
                                 ; PROVE-LEMMA command.
    (nqthm-to-acl2 'prove-lemma) ; Same as above.

    General Form:
    (nqthm-to-acl2 name)

  where [47mname[0m is a notion documented for Nqthm: either a function in the
  Nqthm logic, or a command.  If there is corresponding information
  available for ACL2, it will be printed in response to this command.
  This information is not intended to be completely precise, but
  rather, is intended to help those familiar with Nqthm to make the
  transition to ACL2.

  We close with two tables that contain all the information used by
  this [47mnqthm-to-acl2[0m command.  The first shows the correspondence
  between functions in the Nqthm logic and corresponding ACL2
  functions (when possible); the second is similar, but for commands
  rather than functions.

    Nqthm functions  -->     ACL2
    ----------------------------------------
    ADD1          -->  1+
    ADD-TO-SET    -->  ADD-TO-SET-EQUAL and ADD-TO-SET-EQ
    AND           -->  AND
    APPEND        -->  APPEND and BINARY-APPEND
    APPLY-SUBR    -->  No correspondent, but see the documentation for
                       DEFEVALUATOR and META.
    APPLY$        -->  No correspondent, but see the documentation for
                       DEFEVALUATOR and META.
    ASSOC         -->  ASSOC-EQUAL, ASSOC and ASSOC-EQ
    BODY          -->  No correspondent, but see the documentation for
                       DEFEVALUATOR and META.
    CAR           -->  CAR
    CDR           -->  CDR
    CONS          -->  CONS
    COUNT         -->  ACL2-COUNT
    DIFFERENCE    -->  -
    EQUAL         -->  EQUAL, EQ, EQL and =
    EVAL$         -->  No correspondent, but see the documentation for
                       DEFEVALUATOR and META.
    FALSE         -->  Nqthm's F corresponds to the ACL2 symbol NIL.
    FALSEP        -->  NOT and NULL
    FORMALS       -->  No correspondent, but see the documentation for
                       DEFEVALUATOR and META.
    GEQ           -->  >=
    GREATERP      -->  >
    IDENTITY      -->  IDENTITY
    IF            -->  IF
    IFF           -->  IFF
    IMPLIES       -->  IMPLIES
    LEQ           -->  <=
    LESSP         -->  <
    LISTP         -->  CONSP
    LITATOM       -->  SYMBOLP
    MAX           -->  MAX
    MEMBER        -->  MEMBER-EQUAL, MEMBER and MEMBER-EQ
    MINUS         -->  - and UNARY--
    NEGATIVEP     -->  MINUSP
    NEGATIVE-GUTS -->  ABS
    NLISTP        -->  ATOM
    NOT           -->  NOT
    NUMBERP       -->  ACL2-NUMBERP, INTEGERP and RATIONALP
    OR            -->  OR
    ORDINALP      -->  O-P
    ORD-LESSP     -->  O<
    PACK          -->  See intern and coerce.
    PAIRLIST      -->  PAIRLIS$
    PLUS          -->  + and BINARY-+
    QUOTIENT      -->  /
    REMAINDER     -->  REM and MOD
    STRIP-CARS    -->  STRIP-CARS
    SUB1          -->  1-
    TIMES         -->  * and BINARY-*
    TRUE          -->  The symbol T.
    UNION         -->  UNION-EQUAL and UNION-EQ
    UNPACK        -->  See symbol-name and coerce.
    V&C$          -->  No correspondent, but see the documentation for
                       DEFEVALUATOR and META.
    V&C-APPLY$    -->  No correspondent, but see the documentation for
                       DEFEVALUATOR and META.
    ZERO          -->  The number 0.
    ZEROP         -->  ZP



    Nqthm commands   -->     ACL2
    ----------------------------------------
    ACCUMULATED-PERSISTENCE
                  -->  ACCUMULATED-PERSISTENCE
    ADD-AXIOM     -->  DEFAXIOM
    ADD-SHELL     -->  There is no shell principle in ACL2.
    AXIOM         -->  DEFAXIOM
    BACKQUOTE-SETTING
                  -->  Backquote is supported in ACL2, but not
                       currently documented.
    BOOT-STRAP    -->  GROUND-ZERO
    BREAK-LEMMA   -->  MONITOR
    BREAK-REWRITE -->  BREAK-REWRITE
    CH            -->  PBT
                       See also :DOC history.
    CHRONOLOGY    -->  PBT
                       See also :DOC history.
    COMMENT       -->  DEFLABEL
    COMPILE-UNCOMPILED-DEFNS
                  -->  COMP
    CONSTRAIN     -->  See :DOC encapsulate and :DOC local.
    DATA-BASE     -->  Perhaps the closest ACL2 analogue of DATA-BASE
                       is PROPS.  But see :DOC history for a collection
                       of commands for querying the ACL2 database
                       (``world'').  Note that the notions of
                       supporters and dependents are not supported in
                       ACL2.
    DCL           -->  DEFSTUB
    DEFN          -->  DEFUN and DEFMACRO
    DEFTHEORY     -->  DEFTHEORY
    DISABLE       -->  DISABLE
    DISABLE-THEORY
                  -->  See :DOC theories.  The Nqthm command
                       (DISABLE-THEORY FOO) corresponds roughly to the
                       ACL2 command
                       (in-theory (set-difference-theories
                                    (current-theory :here)
                                    (theory 'foo))).
    DO-EVENTS     -->  LD
    DO-FILE       -->  LD
    ELIM          -->  ELIM
    ENABLE        -->  ENABLE
    ENABLE-THEORY -->  See :DOC theories.  The Nqthm command
                       (ENABLE-THEORY FOO) corresponds roughly to the
                       ACL2 command
                       (in-theory (union-theories
                                    (theory 'foo)
                                    (current-theory :here))).
    EVENTS-SINCE  -->  PBT
    FUNCTIONALLY-INSTANTIATE
                  -->  ACL2 provides a form of the :USE hint that
                       corresponds roughly to the
                       FUNCTIONALLY-INSTANTIATE event of Nqthm. See
                       :DOC lemma-instance.
    GENERALIZE    -->  GENERALIZE
    HINTS         -->  HINTS
    LEMMA         -->  DEFTHM
    MAINTAIN-REWRITE-PATH
                  -->  BRR
    MAKE-LIB      -->  There is no direct analogue of Nqthm's notion of
                       ``library.''  See :DOC books for a description
                       of ACL2's mechanism for creating and saving
                       collections of events.
    META          -->  META
    NAMES         -->  NAME
    NOTE-LIB      -->  INCLUDE-BOOK
    PPE           -->  PE
    PROVE         -->  THM
    PROVEALL      -->  See :DOC ld and :DOC certify-book.  The latter
                       corresponds to Nqthm's PROVE-FILE,which may be
                       what you're interested in,really.
    PROVE-FILE    -->  CERTIFY-BOOK
    PROVE-FILE-OUT
                  -->  CERTIFY-BOOK
    PROVE-LEMMA   -->  DEFTHM
                       See also :DOC hints.
    R-LOOP        -->  The top-level ACL2 loop is an evaluation loop as
                       well, so no analogue of R-LOOP is necessary.
    REWRITE       -->  REWRITE
    RULE-CLASSES  -->  RULE-CLASSES
    SET-STATUS    -->  IN-THEORY
    SKIM-FILE     -->  LD-SKIP-PROOFSP
    TOGGLE        -->  IN-THEORY
    TOGGLE-DEFINED-FUNCTIONS
                  -->  EXECUTABLE-COUNTERPART-THEORY
    TRANSLATE     -->  TRANS and TRANS1
    UBT           -->  UBT and U
    UNBREAK-LEMMA -->  UNMONITOR
    UNDO-BACK-THROUGH
                  -->  UBT
    UNDO-NAME     -->  See :DOC ubt.  There is no way to undo names in
                       ACL2 without undoing back through such names.
                       However, see :DOC ld-skip-proofsp for
                       information about how to quickly recover the
                       state.")
 (NTH
  (LISTS ACL2-BUILT-INS)
  "The nth element (zero-based) of a list

  [47m(Nth n l)[0m is the [47mn[0mth element of [47ml[0m, zero-based.  If [47mn[0m is greater than
  or equal to the length of [47ml[0m, then [47mnth[0m returns [47mnil[0m.

  [47m(Nth n l)[0m has a [guard] that [47mn[0m is a non-negative integer and [47ml[0m is a
  [47m[true-listp][0m.

  [47mNth[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<nth>

    (defun nth (n l)
      (declare (xargs :guard (and (integerp n)
                                  (>= n 0)
                                  (true-listp l))))
      (if (endp l)
          nil
        (if (zp n)
            (car l)
          (nth (- n 1) (cdr l)))))


Subtopics

  [Eighth]
      Eighth member of the list

  [Fifth]
      Fifth member of the list

  [First]
      First member of the list

  [Fourth]
      Fourth member of the list

  [Ninth]
      Ninth member of the list

  [Nth-aliases-table]
      A [table] used to associate names for nth/update-nth printing

  [Rest]
      Rest ([47m[cdr][0m) of the list

  [Second]
      Second member of the list

  [Seventh]
      Seventh member of the list

  [Sixth]
      Sixth member of the list

  [Tenth]
      Tenth member of the list

  [Third]
      Third member of the list")
 (NTH-ALIASES-TABLE
  (STOBJ NTH UPDATE-NTH)
  "A [table] used to associate names for nth/update-nth printing

    Example:
    (table nth-aliases-table 'st0 'st)

  This example associates the symbol [47mst0[0m with the symbol [47mst[0m.  As a
  result, when the theorem prover prints terms of the form [47m(nth n
  st0)[0m or [47m(update-nth n val st0)[0m, where [47mst[0m is a [stobj] whose [47mn[0mth
  accessor function is [47mf-n[0m, then it will print [47mn[0m as [47m*f-n*[0m.

    General Form:
    (table nth-aliases-table 'alias-name 'name)

  This event causes [47malias-name[0m to be treated like [47mname[0m for purposes of
  the printing of terms that are calls of [47mnth[0m and [47mupdate-nth[0m.  (Note
  however that [47mname[0m is not recursively looked up in this table.)
  Both must be symbols other than [47m[state][0m.  See [term], in particular
  the discussion there of untranslated terms.

  For a convenient way to add entries to this [table], see
  [add-nth-alias].  To remove entries from the [table] with ease, see
  [remove-nth-alias].


Subtopics

  [Add-nth-alias]
      Associate one symbol with another for printing of [47m[nth][0m/[47m[update-nth][0m
      terms

  [Remove-nth-alias]
      Remove a symbol alias for printing of [47m[nth][0m/[47m[update-nth][0m terms")
 (NTHCDR
  (LISTS ACL2-BUILT-INS)
  "Final segment of a list

  [47m(Nthcdr n l)[0m removes the first [47mn[0m elements from the list [47ml[0m.

  The following is a theorem.

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

  For related functions, see [take] and see [butlast].

  The [guard] of [47m(nthcdr n l)[0m requires that [47mn[0m is a nonnegative integer
  and [47ml[0m is a true list.

  [47mNthcdr[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<nthcdr>

    (defun nthcdr (n l)
      (declare (xargs :guard (and (integerp n)
                                  (<= 0 n)
                                  (true-listp l))))
      (if (zp n) l (nthcdr (+ n -1) (cdr l))))")
 (NULL
  (BASICS ACL2-BUILT-INS)
  "Recognizer for the empty list

  [47mNull[0m is the function that checks whether its argument is [47mnil[0m.  For
  recursive definitions it is often preferable to test for the end of
  a list using [47m[endp][0m instead of [47mnull[0m; see [endp].

  [47mNull[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<null>

    (defun null (x)
      (declare (xargs :guard t))
      (eq x nil))")
 (NUMBER-SUBTREES
  (HONS-AND-MEMOIZATION ACL2-BUILT-INS)
  "[47m(number-subtrees x)[0m returns the number of distinct subtrees of X, in
  the sense of [47m[equal][0m

  In the logic, [47mnumber-subtrees[0m is defined as the length of
  [47m[cons-subtrees][0m.

  Under the hood, we first [47m[hons-copy][0m X to obtain a normed version,
  then count the number of unique conses in X using an EQ hash table.

  [31;1mFunction: [0m<number-subtrees>

    (defun number-subtrees (x)
      (declare (xargs :guard t))
      (len (cons-subtrees x 'number-subtrees)))")
 (NUMBERS
  (PROGRAMMING)
  "Numbers in ACL2 and operations on them

  See [numbers-introduction] for introductory background.  See
  [arithmetic] for libraries of [books] for arithmetic reasoning.


Subtopics

  [*]
      Multiplication macro

  [+]
      Addition macro

  [-]
      Macro for subtraction and negation

  [/]
      Macro for division and reciprocal

  [/=]
      Test inequality of two numbers

  [1+]
      Increment by 1

  [1-]
      Decrement by 1

  [<]
      Less-than

  [<=]
      Less-than-or-equal test

  [=]
      Test equality of two numbers

  [>]
      Greater-than test

  [>=]
      Greater-than-or-equal test

  [Abs]
      The absolute value of a real number

  [ACL2-number-listp]
      Recognizer for a true list of numbers

  [ACL2-numberp]
      Recognizer for numbers

  [Allocate-fixnum-range]
      Set aside fixnums in GCL

  [Ash]
      Arithmetic shift operation

  [Bitp]
      A recognizer for the set of bits, {0,1}

  [Boole$]
      Perform a bit-wise logical operation on 2 two's complement integers

  [Ceiling]
      Division returning an integer by truncating toward positive infinity

  [Char-code]
      The numeric code for a given character

  [Code-char]
      The character corresponding to a given numeric code

  [Complex]
      Create an ACL2 number

  [Complex-rationalp]
      Recognizes complex rational numbers

  [Complex/complex-rationalp]
      Recognizer for complex numbers

  [Conjugate]
      Complex number conjugate

  [Denominator]
      Divisor of a ratio in lowest terms

  [Df]
      Support for floating-point operations

  [Evenp]
      Test whether an integer is even

  [Explode-nonnegative-integer]
      The list of [characters] in the radix-r form of a number

  [Expt]
      Exponential function

  [Fix]
      Coerce to a number

  [Floor]
      Division returning an integer by truncating toward negative infinity

  [Ifix]
      Coerce to an integer

  [Imagpart]
      Imaginary part of a complex number

  [Int=]
      Test equality of two integers

  [Integer-length]
      Number of bits in two's complement integer representation

  [Integer-listp]
      Recognizer for a true list of integers

  [Integer-range-p]
      Recognizer for integers between two bounds.

  [Integerp]
      Recognizer for whole numbers

  [Logand]
      Bitwise logical `and' of zero or more integers

  [Logandc1]
      Bitwise logical `and' of two ints, complementing the first

  [Logandc2]
      Bitwise logical `and' of two ints, complementing the second

  [Logbitp]
      The [47mi[0mth bit of an integer

  [Logcount]
      Number of ``on'' bits in a two's complement number

  [Logeqv]
      Bitwise logical equivalence of zero or more integers

  [Logior]
      Bitwise logical inclusive or of zero or more integers

  [Lognand]
      Bitwise logical `nand' of two integers

  [Lognor]
      Bitwise logical `nor' of two integers

  [Lognot]
      Bitwise not of a two's complement number

  [Logorc1]
      Bitwise logical inclusive or of two ints, complementing the first

  [Logorc2]
      Bitwise logical inclusive or of two ints, complementing the second

  [Logtest]
      Test if two integers share a `1' bit

  [Logxor]
      Bitwise logical exclusive or of zero or more integers

  [Max]
      The larger of two numbers

  [Min]
      The smaller of two numbers

  [Minusp]
      Test whether a number is negative

  [Mod]
      Remainder using [47m[floor][0m

  [Mod-expt]
      Exponential function

  [Nat-listp]
      Recognizer for a true list of natural numbers

  [Natp]
      A recognizer for the natural numbers

  [Nfix]
      Coerce to a natural number

  [Nonnegative-integer-quotient]
      Natural number division function

  [Numbers-introduction]
      Numbers in ACL2

  [Numerator]
      Dividend of a ratio in lowest terms

  [Oddp]
      Test whether an integer is odd

  [Plusp]
      Test whether a number is positive

  [Pos-listp]
      Recognizer for a true list of positive integers

  [Posp]
      A recognizer for the positive integers

  [Random$]
      Obtain a random value

  [Rational-listp]
      Recognizer for a true list of rational numbers

  [Rationalp]
      Recognizer for rational numbers (ratios and integers)

  [Real/rationalp]
      Recognizer for rational numbers (including real number in ACL2(r))

  [Realfix]
      Coerce to a real number

  [Realpart]
      Real part of a complex number

  [Rem]
      Remainder using [47m[truncate][0m

  [Rfix]
      Coerce to a rational number

  [Round]
      Division returning an integer by rounding off

  [Sharp-d-reader]
      Read a rational number as a representable rational (see [df])

  [Sharp-f-reader]
      Read a rational number in floating-point syntax

  [Sharp-u-reader]
      Allow underscore characters in numbers

  [Signed-byte-p]
      Recognizer for signed integers that fit in a specified bit width

  [Signum]
      Indicator for positive, negative, or zero

  [The-number]
      Coerce an expected number to a number

  [Truncate]
      Division returning an integer by truncating toward 0

  [Unary--]
      Arithmetic negation function

  [Unary-/]
      Reciprocal function

  [Unsigned-byte-p]
      Recognizer for natural numbers that fit in a specified bit width

  [Zero-test-idioms]
      How to test for 0

  [Zerop]
      Test an acl2-number against 0

  [Zip]
      Testing an ``integer'' against 0

  [Zp]
      Testing a ``natural'' against 0

  [Zpf]
      Testing a nonnegative fixnum against 0")
 (NUMBERS-INTRODUCTION
  (NUMBERS)
  "Numbers in ACL2

  ACL2 numbers are precisely represented and unbounded.  They can be
  partitioned into the following subtypes:

    ACL2 Numbers
     |
     |- Rationals
     |  |
     |  |- Integers
     |  |  |- Positive integers                 3
     |  |  |- Zero                              0
     |  |  |- Negative Integers                 -3
     |  |
     |  |- Non-Integral Rationals
     |  |  |
     |  |  |- Positive Non-Integral Rationals   19/3
     |  |  |- Negative Non-Integral Rationals   -22/7
     |
     |- Complex Rational Numbers                 #c(3 5/2) ; i.e., 3 + (5/2)i

  Signed integer constants are usually written (as illustrated above)
  as sequences of decimal digits, possibly preceded by [47m+[0m or [47m-[0m.
  Decimal points are not allowed.  Integers may be written in binary,
  as in [47m#b1011[0m (= 23) and [47m#b-111[0m (= -7).  Octal may also be used,
  [47m#o-777[0m = -511.  Non-integral rationals are written as a signed
  decimal integer and an unsigned decimal integer, separated by a
  slash.  Complex rationals are written as #c(rpart ipart) where
  rpart and ipart are rationals.

  Of course, 4/2 = 2/1 = 2 (i.e., not every rational written with a
  slash is a non-integer).  Similarly, #c(4/2 0) = #c(2 0) = 2.

  The common arithmetic functions and relations are denoted by [47m+[0m, [47m-[0m, [47m*[0m,
  [47m/[0m, [47m=[0m, [47m<[0m, [47m<=[0m, [47m>[0m and [47m>=[0m.  However there are many others, e.g., [47mfloor[0m,
  [47mceiling[0m, and [47mlognot[0m.  See any Common Lisp language documentation.

  The primitive predicates for recognizing numbers are illustrated
  below.  The following ACL2 function will classify an object, x,
  according to its numeric subtype, or else return 'NaN (not a
  number).  We show it this way just to illustrate programming in
  ACL2.

    (defun classify-number (x)
      (cond ((rationalp x)
             (cond ((integerp x)
                    (cond ((< 0 x) 'positive-integer)
                          ((= 0 x) 'zero)
                          (t 'negative-integer)))
                   ((< 0 x) 'positive-non-integral-rational)
                   (t 'negative-non-integral-rational)))
            ((complex-rationalp x) 'complex-rational)
            (t 'NaN)))")
 (NUMBERS_IN_ACL2
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Numbers in ACL2

  ACL2 numbers are precisely represented and unbounded.  They can be
  partitioned into the following subtypes:

    ACL2 Numbers
     |
     |- Rationals
     |  |
     |  |- Integers
     |  |  |- Positive integers                 3
     |  |  |- Zero                              0
     |  |  |- Negative Integers                 -3
     |  |
     |  |- Non-Integral Rationals
     |  |  |
     |  |  |- Positive Non-Integral Rationals   19/3
     |  |  |- Negative Non-Integral Rationals   -22/7
     |
     |- Complex Rational Numbers                 #c(3 5/2) ; i.e., 3 + (5/2)i

  Signed integer constants are usually written (as illustrated above)
  as sequences of decimal digits, possibly preceded by [47m+[0m or [47m-[0m.
  Decimal points are not allowed.  Integers may be written in binary,
  as in [47m#b1011[0m (= 23) and [47m#b-111[0m (= -7).  Octal may also be used,
  [47m#o-777[0m = -511.  Non-integral rationals are written as a signed
  decimal integer and an unsigned decimal integer, separated by a
  slash.  Complex rationals are written as #c(rpart ipart) where
  rpart and ipart are rationals.

  Of course, 4/2 = 2/1 = 2 (i.e., not every rational written with a
  slash is a non-integer).  Similarly, #c(4/2 0) = #c(2 0) = 2.

  The common arithmetic functions and relations are denoted by [47m+[0m, [47m-[0m, [47m*[0m,
  [47m/[0m, [47m=[0m, [47m<[0m, [47m<=[0m, [47m>[0m and [47m>=[0m.  However there are many others, e.g., [47mfloor[0m,
  [47mceiling[0m, and [47mlognot[0m.  See any Common Lisp language documentation.

  The primitive predicates for recognizing numbers are illustrated
  below.  The following ACL2 function will classify an object, x,
  according to its numeric subtype, or else return 'NaN (not a
  number).  We show it this way just to illustrate programming in
  ACL2.

    (defun classify-number (x)
      (cond ((rationalp x)
             (cond ((integerp x)
                    (cond ((< 0 x) 'positive-integer)
                          ((= 0 x) 'zero)
                          (t 'negative-integer)))
                   ((< 0 x) 'positive-non-integral-rational)
                   (t 'negative-non-integral-rational)))
            ((complex-rationalp x) 'complex-rational)
            (t 'NaN)))")
 (NUMERATOR
  (NUMBERS ACL2-BUILT-INS)
  "Dividend of a ratio in lowest terms

  Completion Axiom ([47mcompletion-of-numerator[0m):

    (equal (numerator x)
           (if (rationalp x)
               (numerator x)
             0))

  [Guard] for [47m(numerator x)[0m:

    (rationalp x)")
 (NVARIABLEP (POINTERS)
             "See [system-utilities].")
 (O-FINP
  (ORDINALS ACL2-BUILT-INS)
  "Recognizes if an ordinal is finite

  We introduce the function [47mo-finp[0m which returns [47mt[0m for any ordinal that
  is finite, else [47mnil[0m.  This function is equivalent to the function
  [47m[atom][0m, and is introduced so that we can [47m[disable][0m its definition
  when dealing with ordinals (also see [make-ord]).

  [31;1mFunction: [0m<o-finp>

    (defun o-finp (x)
      (declare (xargs :guard t))
      (atom x))")
 (O-FIRST-COEFF
  (ORDINALS ACL2-BUILT-INS)
  "Returns the first coefficient of an ordinal

  An ACL2 ordinal is either a natural number or, for an infinite
  ordinal, a list whose elements are exponent-coefficient pairs (see
  [o-p]).  In the latter case, this function returns the [47m[cdr][0m of the
  first pair in the list.  In the case of a natural number, this
  function returns the ordinal itself (since a natural number, n, can
  be thought of as (w^0)n).

  For the corresponding exponent, see [o-first-expt].

  [31;1mFunction: [0m<o-first-coeff>

    (defun o-first-coeff (x)
      (declare (xargs :guard (or (o-finp x) (consp (car x)))))
      (if (o-finp x) x (cdar x)))")
 (O-FIRST-EXPT
  (ORDINALS ACL2-BUILT-INS)
  "The first exponent of an ordinal

  An ACL2 ordinal is either a natural number or, for an infinite
  ordinal, a list whose elements are exponent-coefficient pairs (see
  [o-p]).  In the latter case, this function returns the [47m[car][0m of the
  first pair in the list.  In the case of a natural number, the value
  returned is 0 (since a natural number, [47mn[0m, can be thought of as
  (w^0)n).

  For the corresponding coefficient, see [o-first-coeff].

  [31;1mFunction: [0m<o-first-expt>

    (defun o-first-expt (x)
      (declare (xargs :guard (or (o-finp x) (consp (car x)))))
      (if (o-finp x) 0 (caar x)))")
 (O-INFP
  (ORDINALS ACL2-BUILT-INS)
  "Recognizes if an ordinal is infinite

  [47mO-infp[0m is a macro.  [47m(O-infp x)[0m opens up to [47m(not (o-finp x))[0m.")
 (O-P
  (ORDINALS ACL2-BUILT-INS)
  "A recognizer for the ordinals up to epsilon-0

  Using the nonnegative integers and lists we can represent the
  ordinals up to [47mepsilon-0[0m. The ordinal representation used in ACL2
  has changed as of Version_2.8 from that of Nqthm-1992, courtesy of
  Pete Manolios and Daron Vroon; additional discussion may be found
  in ``Ordinal Arithmetic in ACL2'', {proceedings of ACL2 Workshop
  2003 | http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}.
  Previously, ACL2's notion of ordinal was very similar to the
  development given in ``New Version of the Consistency Proof for
  Elementary Number Theory'' in The Collected Papers of Gerhard
  Gentzen, ed. M.E. Szabo, North-Holland Publishing Company,
  Amsterdam, 1969, pp 132-213.

  The following essay is intended to provide intuition about ordinals.
  The truth, of course, lies simply in the ACL2 definitions of [47mo-p[0m
  and [47m[o<][0m.

  Very intuitively, think of each non-zero natural number as by being
  denoted by a series of the appropriate number of strokes, i.e.,

    0             0
    1             |
    2             ||
    3             |||
    4             ||||
    ...           ...

  Then ``[47momega[0m,'' here written as [47mw[0m, is the ordinal that might be
  written as

    w             |||||...,

  i.e., an infinite number of strokes.  Addition here is just
  concatenation.  Observe that adding one to the front of [47mw[0m in the
  picture above produces [47mw[0m again, which gives rise to a standard
  definition of [47mw[0m: [47mw[0m is the least ordinal such that adding another
  stroke at the beginning does not change the ordinal.

  We denote by [47mw+w[0m or [47mw*2[0m the ``[47mdoubly infinite[0m'' sequence that we
  might write as follows.

    w*2           |||||... |||||...

  One way to think of [47mw*2[0m is that it is obtained by replacing each
  stroke in [47m2[0m [47m(||)[0m by [47mw[0m.  Thus, one can imagine [47mw*3[0m, [47mw*4[0m, etc., which
  leads ultimately to the idea of ``[47mw*w[0m,'' the ordinal obtained by
  replacing each stroke in [47mw[0m by [47mw[0m.  This is also written as ``[47momega[0m
  squared'' or [47mw^2[0m, or:

     2
    w             |||||... |||||... |||||... |||||... |||||... ...

  We can analogously construct [47mw^3[0m by replacing each stroke in [47mw[0m by [47mw^2[0m
  (which, it turns out, is the same as replacing each stroke in [47mw^2[0m
  by [47mw[0m).  That is, we can construct [47mw^3[0m as [47mw[0m copies of [47mw^2[0m,

     3              2       2       2       2
    w              w  ...  w  ...  w  ...  w ... ...

  Then we can construct [47mw^4[0m as [47mw[0m copies of [47mw^3[0m, [47mw^5[0m as [47mw[0m copies of [47mw^4[0m,
  etc., ultimately suggesting [47mw^w[0m.  We can then stack [47momega[0ms, i.e.,
  [47m(w^w)^w[0m etc.  Consider the ``limit'' of all of those stacks, which
  we might display as follows.

           .
          .
         .
        w
       w
      w
     w
    w

  That is epsilon-0.

  Below we begin listing some ordinals up to [47mepsilon-0[0m; the reader can
  fill in the gaps at his or her leisure.  We show in the left column
  the conventional notation, using [47mw[0m as ``[47momega[0m,'' and in the right
  column the ACL2 object representing the corresponding ordinal.

    ordinal            ACL2 representation

    0                  0
    1                  1
    2                  2
    3                  3
    ...                ...
    w                 '((1 . 1) . 0)
    w+1               '((1 . 1) . 1)
    w+2               '((1 . 1) . 2)
    ...                ...
    w*2               '((1 . 2) . 0)
    (w*2)+1           '((1 . 2) . 1)
    ...                ...
    w*3               '((1 . 3) . 0)
    (w*3)+1           '((1 . 3) . 1)
    ...                ...

     2
    w                 '((2 . 1) . 0)
    ...                ...

     2
    w +w*4+3          '((2 . 1) (1 . 4) . 3)
    ...                ...

     3
    w                 '((3 . 1) . 0)
    ...                ...

     w
    w                 '((((1 . 1) . 0) . 1) . 0)
    ...                ...

     w  99
    w +w  +w4+3       '((((1 . 1) . 0) . 1) (99 . 1) (1 . 4) . 3)
    ...                ...

      2
     w
    w                 '((((2 . 1) . 0) . 1) . 0)

    ...                ...

      w
     w
    w                 '((((((1 . 1) . 0) . 1) . 0) . 1) . 0)
    ...               ...

  Observe that the sequence of [47mo-p[0ms starts with the natural numbers
  (which are recognized by [47m[natp][0m). This is convenient because it
  means that if a term, such as a measure expression for justifying a
  recursive function (see [o<]) must produce an [47mo-p[0m, it suffices for
  it to produce a natural number.

  The ordinals listed above are listed in ascending order.  This is the
  ordering tested by [47m[o<][0m.

  The ``[47mepsilon-0[0m ordinals'' of ACL2 are recognized by the recursively
  defined function [47mo-p[0m.  The base case of the recursion tells us that
  natural numbers are [47mepsilon-0[0m ordinals.  Otherwise, an [47mepsilon-0[0m
  ordinal is a list of [47m[cons][0m pairs whose final [47m[cdr][0m is a natural
  number, [47m((a1 . x1) (a2 . x2) ... (an . xn) . p)[0m.  This corresponds
  to the ordinal [47m(w^a1)x1 + (w^a2)x2 + ... + (w^an)xn + p[0m.  Each [47mai[0m
  is an ordinal in the ACL2 representation that is not equal to 0.
  The sequence of the [47mai[0m's is strictly decreasing (as defined by
  [47m[o<][0m). Each [47mxi[0m is a positive integer (as recognized by [47m[posp][0m).

  Note that infinite ordinals should generally be created using the
  ordinal constructor, [47m[make-ord][0m, rather than [47m[cons][0m. The functions
  [47m[o-first-expt][0m, [47m[o-first-coeff][0m, and [47m[o-rst][0m are ordinals
  destructors.  Finally, the function [47m[o-finp][0m and the macro [47m[o-infp][0m
  tell whether an ordinal is finite or infinite, respectively.

  The function [47m[o<][0m compares two [47mepsilon-0[0m ordinals, [47mx[0m and [47my[0m.  If both
  are integers, [47m(o< x y)[0m is just [47mx<y[0m.  If one is an integer and the
  other is a [47m[cons][0m, the integer is the smaller.  Otherwise, [47m[o<][0m
  recursively compares the [47m[o-first-expt][0ms of the ordinals to
  determine which is smaller.  If they are the same, the
  [47m[o-first-coeff][0ms of the ordinals are compared.  If they are equal,
  the [47m[o-rst][0ms of the ordinals are recursively compared.

  Fundamental to ACL2 is the fact that [47m[o<][0m is well-founded on
  [47mepsilon-0[0m ordinals.  That is, there is no ``infinitely descending
  chain'' of such ordinals.  See [proof-of-well-foundedness].

  [31;1mFunction: [0m<o-p>

    (defun o-p (x)
      (declare (xargs :guard t))
      (if (o-finp x)
          (natp x)
        (and (consp (car x))
             (o-p (o-first-expt x))
             (not (eql 0 (o-first-expt x)))
             (posp (o-first-coeff x))
             (o-p (o-rst x))
             (o< (o-first-expt (o-rst x))
                 (o-first-expt x)))))")
 (O-RST
  (ORDINALS ACL2-BUILT-INS)
  "Returns the rest of an infinite ordinal

  An ACL2 infinite ordinal is a list whose elements are
  exponent-coefficient pairs (see [o-p] and see [o-infp]).  The first
  exponent and first coefficient of an ordinal can be obtained by
  using [47m[o-first-expt][0m and [47m[o-first-coeff][0m respectively.  To obtain
  the rest of the ordinal (for recursive analysis), use the [47mo-rst[0m
  function. It returns the rest of the ordinal after the first
  exponent and coefficient are removed.

  [31;1mFunction: [0m<o-rst>

    (defun o-rst (x)
      (declare (xargs :guard (consp x)))
      (cdr x))")
 (O<
  (ORDINALS ACL2-BUILT-INS)
  "The well-founded less-than relation on ordinals up to [47mepsilon-0[0m

  If [47mx[0m and [47my[0m are both [47mo-p[0ms (see [o-p]) then [47m(o< x y)[0m is true iff [47mx[0m is
  strictly less than [47my[0m.  [47mo<[0m is well-founded on the [47m[o-p][0ms.  When [47mx[0m
  and [47my[0m are both nonnegative integers, [47mo<[0m is just the familiar ``less
  than'' relation ([47m[<][0m).

  [47mo<[0m plays a key role in the formal underpinnings of the ACL2 logic.
  In order for a recursive definition to be admissible it must be
  proved to ``terminate.'' By terminate we mean that the arguments to
  the function ``get smaller'' as the function recurs and this sense
  of size comparison must be such that there is no ``infinitely
  descending'' sequence of ever smaller arguments.  That is, the
  relation used to compare successive arguments must be well-founded
  on the domain being measured.

  The most basic way ACL2 provides to prove termination requires the
  user to supply (perhaps implicitly) a mapping of the argument
  tuples into the ordinals with some ``measure'' expression in such a
  way that the measures of the successive argument tuples produced by
  recursion decrease according to the relation [47mo<[0m.  The validity of
  this method rests on the well-foundedness of [47mo<[0m on the [47m[o-p][0ms.

  Without loss of generality, suppose the definition in question
  introduces the function [47mf[0m, with one formal parameter [47mx[0m (which might
  be a list of objects).  Then we require that there exist a measure
  expression, [47m(m x)[0m, that always produces an [47m[o-p][0m.  Furthermore,
  consider any recursive call, [47m(f (d x))[0m, in the body of the
  definition.  Let [47mhyps[0m be the conjunction of terms, each of which is
  either the test of an [47m[if][0m in the body or else the negation of such
  a test, describing the path through the body to the recursive call
  in question.  Then it must be a theorem that

    (IMPLIES hyps (O< (m (d x)) (m x))).

  When we say [47mo<[0m is ``well-founded'' on the [47m[o-p][0ms we mean that there
  is no infinite sequence of [47m[o-p][0ms such that each is smaller than
  its predecessor in the sequence.  Thus, the theorems that must be
  proved about [47mf[0m when it is introduced establish that it cannot recur
  forever because each time a recursive call is taken [47m(m x)[0m gets
  smaller.  From this, and the syntactic restrictions on definitions,
  it can be shown (as on page 44 in ``A Computational Logic'', Boyer
  and Moore, Academic Press, 1979) that there exists a function
  satisfying the definition; intuitively, the value assigned to any
  given [47mx[0m by the alleged function is that computed by a sufficiently
  large machine.  Hence, the logic is consistent if the axiom
  defining [47mf[0m is added.

  See [o-p] for a discussion of the ordinals and how to compare two
  ordinals.

  The definitional principle permits the use of relations other than [47mo<[0m
  but they must first be proved to be well-founded on some domain.
  See [well-founded-relation-rule].  Roughly put, alternative
  relations are shown well-founded by providing an order-preserving
  mapping from their domain into the ordinals.  See [defun] for
  details on how to specify which well-founded relation is to be
  used.

  [31;1mFunction: [0m<o<>

    (defun o< (x y)
      (declare (xargs :guard (and (o<g x) (o<g y))))
      (cond ((o-finp x) (or (o-infp y) (< x y)))
            ((o-finp y) nil)
            ((not (equal (o-first-expt x)
                         (o-first-expt y)))
             (o< (o-first-expt x) (o-first-expt y)))
            ((not (= (o-first-coeff x) (o-first-coeff y)))
             (< (o-first-coeff x) (o-first-coeff y)))
            (t (o< (o-rst x) (o-rst y)))))")
 (O<=
  (ORDINALS ACL2-BUILT-INS)
  "The less-than-or-equal relation for the ordinals

  [47mo<=[0m is a macro and [47m(o<= x y)[0m expands to [47m(not (o< y x))[0m.  See [o<].")
 (O>
  (ORDINALS ACL2-BUILT-INS)
  "The greater-than relation for the ordinals

  [47mO>[0m is a macro and [47m(o> x y)[0m expands to [47m(o< y x)[0m.  See [o<].")
 (O>=
  (ORDINALS ACL2-BUILT-INS)
  "The greater-than-or-equal relation for the ordinals

  [47mO>=[0m is a macro and [47m(o>= x y)[0m expands to [47m(not (o< x y))[0m.  See [o<].")
 (OBDD
  (BDD)
  "Ordered binary decision diagrams with rewriting

  See [bdd] for information on this topic.")
 (OBSERVATION
  (IO ACL2-BUILT-INS)
  "Print an observation

  Here is a typical application of [47mobservation[0m.

    ACL2 !>(let ((ctx 'top-level)
                 (name 'foo))
             (observation ctx
                          \"Skipping processing of name ~x0.\"
                          name))

    ACL2 Observation in TOP-LEVEL:  Skipping processing of name FOO.
    <state>
    ACL2 !>

  [47mObservation[0m prints an initial ``[47mACL2 Observation...: [0m'', and then
  prints the indicated message using formatted printing (see [fmt]).
  Notice in the example above that evaluation of a call of
  [47mobservation[0m returns [47m[state][0m.  Indeed, [47mobservation[0m is actually a
  macro whose expansion takes and returns the ACL2 [47m[state][0m.  A
  similar utility, [47mobservation-cw[0m, is available that does not take or
  return [47mstate[0m; rather, it returns [47mnil[0m as the suffix ``[47mcw[0m'' suggests
  that a ``comment window'' is the target of this printing, rather
  than the state.  For example:

    ACL2 !>(let ((ctx 'top-level)
                 (name 'foo))
             (observation-cw ctx
                             \"Skipping processing of name ~x0.\"
                             name))

    ACL2 Observation in TOP-LEVEL:  Skipping processing of name FOO.
    NIL
    ACL2 !>

  [47mObservation-cw[0m takes exactly the same arguments as [47mobservation[0m, but
  [47mobservation-cw[0m does its printing in a so-called ``wormhole''; see
  [wormhole].

    General Forms:
    (observation    ctx fmt-string fmt-arg1 fmt-arg2 ... fmt-argk)
    (observation-cw ctx fmt-string fmt-arg1 fmt-arg2 ... fmt-argk)

  where [47mctx[0m generally evaluates to a symbol (but see below), and
  [47mfmt-string[0m together with the [47mfmt-argi[0m are suitable for passing to
  [47m[fmt][0m.  Output begins and ends with a newline.

  Recall from the example above that the output from a call of
  [47mobservation[0m (or [47mobservation-cw[0m) begins with ``[47mACL2 Observation[0m''
  and additional characters ending in ``[47m: [0m'', for example ``[47m in
  TOP-LEVEL: [0m'', followed by formatted output produced from
  [47mfmt-string[0m with the given [47mfmt-argi[0m.  The characters printed
  immediately following the string ``[47mACL2 Observation[0m'' depend on the
  value of [47mctx[0m.  If [47mctx[0m is [47mnil[0m, nothing is printed.  If [47mctx[0m is a
  non-[47mnil[0m symbol, it is printed using [47m[fmt][0m directive [47m~x[0m.  If [47mctx[0m is
  a [47m[cons][0m pair whose [47m[car][0m is a symbol, formatted printing is
  applied to the string \"(~x0 ~x1 ...)\", where [47m#\\0[0m and [47m#\\1[0m are bound
  respectively to that car and cdr.  Otherwise, [47mctx[0m is printed using
  [47m[fmt][0m directive [47m~@[0m.

  We next discuss situations in which printing is inhibited for
  [47mobservation[0m and [47mobservation-cw[0m.  No printing is done when
  [47mobservation[0m is among the inhibited output types; see
  [set-inhibit-output-lst].  Moreover, no printing is done by
  [47mobservation[0m during [47m[include-book][0m.  If you want to avoid printing
  from [47mobservation-cw[0m during [47m[include-book][0m, then you need to manage
  that yourself.")
 (OBSERVATION-CW (POINTERS)
                 "See [observation].")
 (ODDP
  (NUMBERS ACL2-BUILT-INS)
  "Test whether an integer is odd

  [47m(oddp x)[0m is true if and only if [47mx[0m is odd, i.e., not even in the sense
  of [47m[evenp][0m.

  The [guard] for [47moddp[0m requires its argument to be an integer.

  [47mOddp[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<oddp>

    (defun oddp (x)
      (declare (xargs :guard (integerp x)))
      (not (evenp x)))")
 (ODDS
  (LISTS ACL2-BUILT-INS)
  "The odd-indexed members of a list

  The call [47m(odds x)[0m returns the restriction of the true-list [47mx[0m to its
  odd-indexed members (with zero-based indexing).  Note that if [47mx[0m is
  a list [47m(k1 a1 k2 a2 ... kn an)[0m that satisfies the predicate
  [47m[keyword-value-listp][0m, then [47m(odds x)[0m lists the values [47mai[0m of [47mx[0m.

  [31;1mFunction: [0m<odds>

    (defun odds (l)
      (declare (xargs :guard (true-listp l)))
      (evens (cdr l)))")
 (OK-IF
  (BREAK-REWRITE)
  "Conditional exit from [47mbreak-rewrite[0m

  Recall that one way to exit from a [break-rewrite] interactive break
  is to type the command [47m:ok[0m.  See [brr-commands].  The [47m:ok[0m command
  exits silently, without printing the result of attempting to apply
  the rule that caused the break.  The [47m:ok-if[0m command takes a term as
  an argument and is like [47m:ok[0m but exits only if the term evaluates to
  non-[47mnil[0m.

    Example Form:
    :ok-if (null (brr@ :wonp))

    General Form:
    :ok-if expr

  where [47mexpr[0m is a term involving no free variables other than [47mstate[0m and
  returning one non-[47mstate[0m result which is treated as Boolean.  This
  form is intended to be executed from within [47mbreak-rewrite[0m (see
  [break-rewrite]).

  Consider first the simple situation that the [47m(ok-if term)[0m is a
  command read by [47mbreak-rewrite[0m.  Then, if the term is non-[47mnil[0m,
  [47mbreak-rewrite[0m exits and otherwise it does not.

  More generally, [47mok-if[0m returns an ACL2 error triple [47m(mv erp val
  state)[0m.  (See [ld] or see [programming-with-state] for more on
  error triples.)  If any form being evaluated as a command by
  [47mbreak-rewrite[0m returns the triple returned by [47m(ok-if term)[0m then the
  effect of that form is to exit [break-rewrite] if term is non-[47mnil[0m.
  Thus, one might define a function or macro that returns the value
  of [47mok-if[0m expressions on all outputs and thus create a convenient
  new way to exit [47mbreak-rewrite[0m.

  The exit test, [47mterm[0m, generally uses [47mbrr@[0m to access context sensitive
  information about the attempted rule application.  See [brr@].
  [47mOk-if[0m is useful inside of command sequences produced by break
  conditions.  See [monitor].  [47m:ok-if[0m is most useful after an [47m:eval[0m
  command has caused [47mbreak-rewrite[0m to try to apply the rule because
  in the resulting break environment [47mexpr[0m can access such things as
  whether the rule succeeded, if so, what term it produced, and if
  not, why.  There is no need to use [47m:ok-if[0m before [47m:eval[0ming the rule
  since the same effects could be achieved with the break condition
  on the rule itself.  Perhaps we should replace this concept with
  [47m:eval-and-break-if[0m?  Time will tell.")
 (OLD-AND-NEW-EVENT-DATA (POINTERS)
                         "See [saving-event-data].")
 (ON_THE_NAMING_OF_SUBGOALS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "On the Naming of Subgoals

  [47mSubgoal *1/2[0m is the [31;1minduction step[0m from the scheme, obtained by
  instantiating the scheme with our conjecture.

  We number the cases ``backward'', so this is case ``2'' of the proof
  of ``*1''.  We number them backward so you can look at a subgoal
  number and get an estimate for how close you are to the end.")
 (OOPS
  (HISTORY)
  "Undo a [47m:u[0m or [47m:[0m[47m[ubt][0m

  The keyword [command] [47m:oops[0m will undo the most recent [47m:[0m[47m[ubt][0m (or [47m:u[0m,
  which we here consider just another [47m:[0m[47m[ubt][0m).  A second [47m:oops[0m will
  undo the next most recent [47m:[0m[47m[ubt][0m, a third will undo the [47m:[0m[47m[ubt][0m
  before that one, and a fourth [47m:oops[0m will return the logical [world]
  to its configuration before the first [47m:oops[0m.

  Consider the logical world (see [world]) that represents the current
  extension of the logic and ACL2's rules for dealing with it.  The
  [47m:[0m[47m[ubt][0m and [47m:u[0m [command]s ``roll back'' to some previous [world]
  (see [ubt]).  Sometimes these [command]s are used to inadvertently
  undo useful work and user's wish they could ``undo the last undo.''
  That is the function provided by [47m:oops[0m.

  [47m:Oops[0m is best described in terms of an implementation.  Imagine a
  ring of four [world]s and a marker ([47m*[0m) indicating the current ACL2
  [world]:

          *
        w0
      /    \\
    w3      w1
      \\    /
        w2

  This is called the ``kill ring'' and it is maintained as follows.
  When you execute an event the current [world] is extended and the
  kill ring is not otherwise affected.  When you execute [47m:[0m[47m[ubt][0m or
  [47m:u[0m, the current [world] marker is moved one step counterclockwise
  and that [world] in the ring is replaced by the result, say [47mw0'[0m, of
  the [47m:[0m[47m[ubt][0m or [47m:u[0m.

         w0
       /    \\
    *w0'     w1
       \\    /
         w2

  If you were to execute [events] at this point, [47mw0'[0m would be extended
  and no other changes would occur in the kill ring.

  When you execute [47m:oops[0m, the marker is moved one step clockwise.  Thus
  the kill ring becomes

          *
        w0
      /    \\
    w0'     w1
      \\    /
        w2

  and the current ACL2 [world] is [47mw0[0m once again.  That is, [47m:oops[0m
  ``undoes'' the [47m:[0m[47m[ubt][0m that produced [47mw0'[0m from [47mw0[0m.  Similarly, a
  second [47m:oops[0m will move the marker to [47mw1[0m, undoing the undo that
  produced [47mw0[0m from [47mw1[0m.  A third [47m:oops[0m makes [47mw2[0m the current [world].
  Note however that a fourth [47m:oops[0m restores us to the configuration
  previously displayed above in which [47mw0'[0m has the marker.

  In general, the kill ring contains the current [world] and the three
  most recent [world]s in which a [47m:[0m[47m[ubt][0m or [47m:u[0m were done.

  While [47m:[0m[47m[ubt][0m may appear to discard the information in the [events]
  undone, we can see that the [world] in which the [47m:[0m[47m[ubt][0m occurred is
  still available.  No information has been lost about that [world].
  But [47m:[0m[47m[ubt][0m does discard information!  [47m:[0m[47m[Ubt][0m discards the
  information necessary to recover from the third most recent [47m[ubt][0m!
  An [47m:oops[0m, on the other hand, discards no information, it just
  selects the next available [world] on the kill ring and doing
  enough [47m:oops[0mes will return you to your starting point.

  We can put this another way.  You can freely type [47m:oops[0m and inspect
  the [world] that you thus obtain with [47m:[0m[47m[pe][0m, [47m:[0m[47m[pc][0m, and other
  [history] [command]s.  You can repeat this as often as you wish
  without risking the permanent loss of any information.  But you
  must be more careful typing [47m:[0m[47m[ubt][0m or [47m:u[0m.  While [47m:oops[0m makes [47m:[0m[47m[ubt][0m
  seem ``safe'' because the most recent [47m:[0m[47m[ubt][0m can always be undone,
  information is lost when you execute [47m:[0m[47m[ubt][0m.

  We note that [47m:ubt[0m and [47m:u[0m may remove compiled definitions (but note
  that in some Lisps, including CCL (OpenMCL) and SBCL, functions are
  always compiled).  When the original world is restored using [47m:oops[0m,
  restored functions will not generally be compiled (except for Lisps
  as above), though the user can remedy this situation; see [comp].

  Finally, we note that our implementation of [47moops[0m can use a
  significant amount of memory, because of the saving of old logical
  [world]s.  Most users are unlikely to experience a memory problem,
  but if you do, then you may want to disable [47moops[0m by evaluating
  [47m(reset-kill-ring 0 state)[0m; see [reset-kill-ring].")
 (OPEN-INPUT-CHANNEL (POINTERS)
                     "See [io].")
 (OPEN-INPUT-CHANNEL-P (POINTERS)
                       "See [io].")
 (OPEN-OUTPUT-CHANNEL (POINTERS)
                      "See [io].")
 (OPEN-OUTPUT-CHANNEL!
  (IO ACL2-BUILT-INS)
  "When trust tags are needed to open output channels

  Use this function in place of [47mopen-output-channel[0m if you want to open
  a channel for output at times this would otherwise be prohibited,
  for example during [47m[make-event][0m expansion and [47m[clause-processor][0m
  [hints].  If this functionality doesn't quite seem like what you
  need, take a look at the definition of [47mopen-output-channel![0m in
  axioms.lisp, specifically the binding of [47m[state][0m global variable
  [47mwrites-okp[0m.  The following example, taken from (no longer
  available) community book [47mbooks/hons-archive/hons-archive.lisp[0m,
  illustrates the latter approach.

    (defmacro har-zip! (x filename &key sortp)
      \"See :doc hons-archive\"
      `(mv-let (erp val state)
               (progn!
                :state-global-bindings
                ((temp-touchable-vars t set-temp-touchable-vars))
                (state-global-let*
                 ((writes-okp t))
                 (let ((state (har-zip-fn ,x ,filename ,sortp state)))
                   (mv nil nil state))))
               (declare (ignore erp val))
               state))

  The book below illustrates the soundness loophole plugged in ACL2
  Version_3.2 related to file writes during book certification.

    ; The following example is adapted (with only very slight changes)
    ; from one written by Peter Dillinger.  It illustrates the prohibition
    ; against writing files enforced by with-output-channel during book
    ; certification (more specifically, during make-event expansion).

    ; This book certifies in ACL2 Version_3.1 before the fix discussed in the
    ; paragraph about it being ``possible to write files during book
    ; certification'' in :DOC NOTE-3-2.  The fix was actually made to ACL2
    ; function open-output-channel.

    ; After the fix, in order for certification to succeed one needs to do
    ; two things.  First, in raw lisp:
    ;   (push :after-writes-okp-fix *features*)
    ; Second, certify with this command:
    ;   (certify-book \"writes-okp\" 0 nil :ttags (:writes-okp))

    (in-package \"ACL2\")

    (local
     (defun write-objects-to-channel (obj-lst chan state)
       (declare (xargs :mode :program
                       :stobjs state
                       :guard (true-listp obj-lst)))
       (if (consp obj-lst)
           (pprogn (print-object$ (car obj-lst) chan state)
                   (write-objects-to-channel (cdr obj-lst) chan state)
                   state)
         state)))

    #+after-writes-okp-fix
    (defttag :writes-okp)

    (local
     (defun write-objects-to-file (obj-lst filename state)
       (declare (xargs :mode :program
                       :stobjs state
                       :guard (and (stringp filename)
                                   (true-listp obj-lst))))
       (mv-let (chan state)
               #-after-writes-okp-fix
               (open-output-channel filename :object state)
               #+after-writes-okp-fix
               (open-output-channel! filename :object state)
               (if chan
                   (pprogn (write-objects-to-channel obj-lst chan state)
                           (close-output-channel chan state)
                           (value :done))
                 (er soft 'write-object-to-file
                     \"Could not open for writing: ~x0\"
                     filename)))))

    (local
     (defconst *nil.lisp*
       '((in-package \"ACL2\")
         (defthm bad nil :rule-classes nil))))

    (local
     (defconst *nil.cert*
       '((IN-PACKAGE \"ACL2\")
         \"ACL2 Version 3.1\"
         :BEGIN-PORTCULLIS-CMDS
         :END-PORTCULLIS-CMDS
         NIL
         ((\"/home/peterd/test/nil.lisp\" \"nil\" \"nil\"
           ((:SKIPPED-PROOFSP) (:AXIOMSP) (:TTAGS)) . 134094174))
         62589544
         )))

    (local
     (make-event (er-progn
                  (write-objects-to-file *nil.lisp* \"nil.lisp\" state)
                  (write-objects-to-file *nil.cert* \"nil.cert\" state)
                  (value '(value-triple :invisible)))))

    (local (include-book
            \"nil\" :load-compiled-file nil))

    (defthm bad nil :rule-classes nil)")
 (OPEN-OUTPUT-CHANNEL-P (POINTERS)
                        "See [io].")
 (OPEN-TRACE-FILE
  (TRACE)
  "Redirect trace output to a file

    Example:
    (open-trace-file \"foo\") ; trace output will go to file foo

    General Form:
    (open-trace-file filename) ; trace output will go to file filename

  Output from [47m[trace$][0m normally goes to the screen, i.e.,
  [47m[standard-co][0m.  But it can be redirected to a file as shown above.
  See [close-trace-file] for how to send trace output back to the
  screen.

  [47mOpen-trace-file[0m does not work as would reasonably be expected during
  [47m[make-event][0m expansion.  Use [47m[open-trace-file!][0m instead within
  [47mmake-event[0m.")
 (OPERATIONAL-SEMANTICS
  (DOCUMENTATION ACL2 ABOUT-ACL2)
  "Modeling State Machines

  ``[3mThe meaning of a program is defined by its effect on the state
  vector[0m'' --- John McCarthy, Towards a Mathematical Science of
  Computation (1962).

  Users of ACL2 (see [bib::kmm00a] and [bib::kmm00b]) and its
  predecessor, Nqthm (see [bib::bm97]), have long modeled state
  machines and verified interesting properties of programs running on
  those machines.  The basic idea is to represent the state of the
  machine (including its programs) by an ACL2 object and then define
  an interpreter that computes a ``final'' state from an initial
  state.  In this documentation topic we fill out that sketch of the
  methodology without being specific about any particular machine.
  We then dive into details in subsidiary topics.


Request for Suggestions from ACL2 Users

  If you have ideas for additions or other improvements to the
  documentation of the ACL2 approach to operational semantics, please
  add suitable documentation or simply send your comments to the ACL2
  developers.  Note that we have intentionally limited our literature
  survey to models and proof methods in ACL2 and Nqthm.  Widening the
  focus to operational semantics in general is simply beyond the
  scope of this documentation topic.  But if you see omissions or
  errors in our discussion of ACL2 or Nqthm models and proof methods,
  please either fix them or bring them to our attention, making your
  suggestions as detailed as possible, e.g., what documentation topic
  are you looking at and precisely how would you change it?  If your
  change involves citing a paper or Nqthm or ACL2 file that we have
  left out, please include the appropriate bibliographic information
  as well as a URL to the paper or file if possible.  The following
  documentation topics are of concern:


Recommended Order of Topics

    * operational-semantics (the current topic)

    * [operational-semantics-1__simple-example]

    * [operational-semantics-2__other-examples]

    * [operational-semantics-3__annotated-bibliography]

    * [operational-semantics-4__how-to-find-things]

    * [operational-semantics-5__history-etc]


Prerequisites

  You won't be able to prove theorems about ACL2 functions interpreting
  another language unless you can prove theorems about ACL2
  functions.  An excellent way to test yourself is to think of a
  program you'd like to verify in that other programming language.
  Code a function in ACL2 that computes the same answer using the
  same algorithm, as nearly as possible in an applicative setting.
  So for example, if your program destructively modifies an array in
  that other programming language, perhaps model the array in ACL2 as
  a list but access elements with [47m[nth][0m and ``modify'' elements with
  [47m[update-nth][0m.  Then prove that the ACL2 function is correct with
  ACL2.  If you can do that, you're ready to try to embed that other
  language (or some fragment of it) in ACL2 and reason about such
  programs with ACL2.


Generic Description of the Methodology

  How Machines Are Modeled

  In the approach ACL2 users most often take to model state machines
  the first step is to represent the relevant parts of the machine's
  state as an ACL2 object.  Then the user defines a single-step (or
  ``small step'') function to compute the next state from the current
  one (and possibly some inputs).  Finally, the user defines a
  recursive function that iterates the single-step transition from a
  given initial state a given number of times or until some halting
  condition is detected in the state.  That function is often called
  the ``run'' function and is our operational semantic model.  See
  [operational-semantics-1__simple-example] for a model of an
  extremely simple machine, the way we configure ACL2 to prove things
  about it, some example proofs and other uses of the model.

  The argument that controls the maximum number of steps taken is often
  called a ``clock'' but it has nothing to do with the passage of
  time.  In some models the clock is just a natural number.  In
  others it may be a finite list of inputs to be successively
  transferred into the state on each cycle.  In any case, the clock
  guarantees that the run function terminates, which is a
  prerequisite for functions defined recursively in ACL2.  But do not
  be fooled into thinking that all programs running on the machine
  always terminate.  By appropriate use of quantification one can
  often prove that a given program never terminates or only
  terminates under certain pre-conditions.  This is discussed further
  in [operational-semantics-1__simple-example].

  Uses of Such a Model

  Such a model can be used as a prototype for the machine: the model
  can be executed on concrete states for testing purposes.  But
  because ACL2 is a formal system, it is also possible to do symbolic
  simulation of the model and to prove theorems involving the model.
  Such theorems might be loosely classified as being ``about'' a
  particular program running on the machine or ``about'' the machine
  itself.  An example of the first might be that a certain program
  for the machine computes the factorial function.  An example of the
  second might be that when the machine is run [47m(+ i j)[0m steps from
  state [47ms0[0m the result is the same as running it [47mi[0m steps from state [47ms0[0m
  to get some state, [47msi[0m, and then running it [47mj[0m steps from [47msi[0m.  Such
  theorems are sometimes called ``sequential execution'' or
  ``semi-colon'' theorems because they allow a long run to be broken
  up into a composition of shorter runs.  One can even prove theorems
  relating one such model to another.  But from the logical
  perspective there is no practical distinction between these
  ``kinds'' of theorems: they are just ordinary theorems about ACL2
  functions.

  Proving Theorems about A Model

  To facilitate such proofs it is common to develop a book of rewrite
  (and other kinds of) rules that do such things as normalize
  compositions of functions used in the construction of states and
  clock expressions.  The basic idea is to control the expansions of
  the step and run functions to contain case explosions that would
  otherwise occur.  E.g., we usually configure the ACL2 database so
  that

    * the step function only expands on a state when it is possible to
      determine what the ``next instruction'' is, rather than
      considering all possible cases,

    * when the clock is constant (or, more precisely, when it is possible
      to determine the explicit number of steps the clock will allow)
      the run function is eliminated by expanding it to a composition
      of steps, and

    * when the clock is given by a composition of functions, as in (+ 4
      (loop-clk x y z)), a sequential composition rule is used to
      break it into a composition of runs.

  Such a configuration of ACL2 generally makes it possible to prove
  certain styles of theorems by following a well-understood
  methodology.

  For example, to express a conjecture about the final state produced
  by a program on the machine, one might write an implication whose
  hypothesis characterizes an acceptable initial state and whose
  conclusion is an equality whose left-hand side is a call of run on
  that state and a clock expression that measures exactly how many
  steps it will take to reach the halt state or return, and whose
  right-hand side is the symbolic expression of the correct final
  state.  The two states just mentioned and the clock expression are
  usually terms involving variables denoting values found in relevant
  locations in the initial state.  A very strong total correctness
  theorem for a factorial program might be something like ``if a
  natural number, [47mn[0m, is found in the memory location used for the
  program's input, and the state is run [47m(clk n)[0m steps, then the halt
  flag is set in the resulting state, and [47m(fact n)[0m, aka, [3mn![0m, is found
  in the memory location used for the program's return value --- and
  the program counter is set to the correct next instruction and no
  other part of the state has changed.'' Alternatively, the theorem
  might only express some post-condition of the final state.  The
  examples in [operational-semantics-1__simple-example] will make
  this clearer.  The methodology for proving such theorems is
  demonstrated there too.

  The clock term, [47m(clk n)[0m above, is a constructive expression of an
  existential quantifier meaning ``there exists a clock that drives
  the machine from the given initial state to the given final
  state.'' It is also sometimes possible to prove that no such clock
  exists.  There are tools that can, for simple programs, generate
  appropriate clock terms.  Of course, the problem is undecidable.

  Proofs of such theorems are most often done by induction, appealing
  to similar lemmas about the effects of loops and subroutine calls.
  But proofs using inductive assertions and other mathematical
  techniques can be used.

  The methodology described above generally limits the human to
  creative contributions (like identifying invariants being
  maintained) and relegates to ACL2 the tedious unwinding of possibly
  long chains of symbolic computation.  The previously mentioned
  documentation topic, [operational-semantics-1__simple-example],
  carries out this entire program for a simple machine, explicates
  the methodology, and uses it to prove a variety of theorems.

  Following this approach, users of Nqthm and ACL2 have modeled and
  verified properties of many interesting machines.  More precise
  references to the work mentioned below as well as models and proofs
  about other machines --- and other kinds of properties, like
  absence of deadlock --- may be found in
  [operational-semantics-2__other-examples].

  Advice

  After you are familiar with how to use ACL2 and have studied some of
  the models described here, you are ready to try to develop your own
  models. We offer three pieces of advice.

    * Start small, e.g., model half a dozen routine instructions and master
      the methodology so that you can ``automatically'' prove things
      about simple programs.  Be sure that your proofs don't rely on
      the small size of the model; in particular, don't repeatedly
      enumerate all possible instructions.  Then add one new feature
      to the model and elaborate the methodology.  You will often
      find there are multiple ways to represent the state and state
      changes.  By starting small you will be able to iterate more
      quickly to find the best way to formalize new features and cope
      with the resulting complexity.

    * Consider the necessity of introducing multiple layers of abstraction.
      For example your most realistic model might have finite bounds
      on all resources, but it might be worth your while to
      ``duplicate'' the model with unbounded resources but with
      meters that record the maximal extent of the resources used.
      Then prove a theorem relating the two models.

    * As usual with ACL2, think carefully about how the prover will use the
      lemmas you prove.  They are not just expressing mathematical
      relations but are used operationally to transform the formulas
      being proved.


Overview of the Remaining Topics on Operational Semantics

  Our discussion of the details of operational semantics in ACL2 is
  structured as follows.

    * [operational-semantics-1__simple-example] --- carries out the
      generic methodology to formalize and prove theorems about a
      very simple machine, called M1.  M1 is a toy Java Virtual
      Machine (JVM) supporting just stack-based arithmetic and branch
      instructions.  We highly recommend this section, though users
      already familiar with this style of model may wish just to skim
      it.

    * [operational-semantics-2__other-examples] --- briefly summarizes some
      other examples of operational models with citations to the
      relevant source documents.  The topic has several goals.  One
      is to show how we can handle programming features omitted from
      M1, e.g., subroutine call and return, data types, threads,
      monitors, etc.  A second goal is to demonstrate that the
      methodology allows really large complex models, like of the JVM
      or the x86, that can be executed in ACL2 to emulate the machine
      in question and as the basis of formal proofs about the
      machine.  A third goal is to point out alternative ACL2 proof
      styles and tools that may be of use while trying to prove
      theorems about state machines.

    * [operational-semantics-3__annotated-bibliography] --- is just what it
      says: an annotated bibliography.  The annotations you see in
      this bibliography are akin simply to keywords.  But if you
      select a given citation you'll generally see a discussion of
      how the work fits into the scheme of things.  This section is
      an alternative way to browse through Nqthm and ACL2 examples of
      state machines, proofs, proof styles, and tools.

    * [operational-semantics-4__how-to-find-things] --- the various topics
      on operational semantics cite papers and files that are not
      part of the ACL2 documentation; for example, in these topics
      you might see utterances such as ``Nqthm source file
      [47mprove.lisp[0m'', ``ACL2 source file [47mrewrite.lisp[0m'', ``Nqthm proof
      script [47mexamples/hunt/fm8501.lisp[0m'' and ``ACL2 directory
      [47mbooks/models/jvm/m1/[0m''; this brief topic explains how to
      dereference these utterances.

    * [operational-semantics-5__history-etc] --- a discussion of early
      work in the 1970s and 1980s by members of the Boyer-Moore
      community to model state machines, and how that work influenced
      the evolution of Nqthm and ACL2.


Subtopics

  [Operational-semantics-1__simple-example]
      M1: definition, rules, clocks, proofs

  [Operational-semantics-2__other-examples]
      Examples of other models and proof techniques

  [Operational-semantics-3__annotated-bibliography]
      Annotated bibliography for operational-semantics

  [Operational-semantics-4__how-to-find-things]
      Citation conventions for doc operational-semantics

  [Operational-semantics-5__history-etc]
      A quick history of our style of modeling state machines")
 (OPERATIONAL-SEMANTICS-1__SIMPLE-EXAMPLE
  (OPERATIONAL-SEMANTICS)
  "M1: definition, rules, clocks, proofs


Organization of This Topic

  As a hypertext document, this topic is ``flat,'' not structured as a
  tree of subtopics.  We implemented it this way to make it easier to
  search.

    * Introduction

    * Setting up a Symbol Package

    * The Definition of M1

    * Programming M1

    * ``Teaching'' the Prover How to Control M1

          * Arithmetic

          * Resolving ``Reads'' and ``Writes''

          * Keeping ``Abstractions'' Abstract

          * Controlling Case Explosion due to Step

          * Clock Expressions

          * Expanding [47mm1[0m

    * Playing with Program *pi*: Execution, Symbolic Execution, and Proof
      of Correctness

          * The Clock for Factorial

          * Computing with M1

          * Symbolic Execution of M1 Code

          * Proving Theorems about M1 Programs

                * Step 0: The Specification

                * Step 1: The Semantic Function

                * Step 2: Relate the Semantic Function to the Code

                * Step 3: Relate the Semantic Function to the Specification

                * Step 4: Total Correctness

    * More M1 Programs and Proofs

    * More Elaborate Models of the JVM: From M1 to M6


Introduction

  In this topic we explain, by example, the most common way to
  formalize a computing machine in ACL2 and then reason about it. The
  machine we have in mind will be called ``M1'' and is a ``toy''
  version of the Java Virtual Machine or ``JVM.'' More precisely, it
  is a simple stack machine having a fixed number of registers,
  hereafter called ``local variables,'' and an execute-only program
  memory.  There will only be eight instructions.  We will then write
  and verify a factorial program for it and mention many more M1
  programs that have been verified --- and which we urge you to solve
  as practice problems.  Despite its simplicity, M1 is equivalent to
  a Turing machine and, in fact, that fact is among the theorems
  proved about M1.  Full references are given when we survey the M1
  results available.

  (Historical Aside: What we're calling M1 was called ``Small-Machine''
  in Nqthm.  See [bib::bm96] and the methodology described here was
  essentially fully developed before ACL2, Java, or the JVM came
  along.)

  M1 does not support bytecode verification, method invocation
  (procedure call) and return, data objects other than ACL2's
  unbounded numbers, threads, exceptions, and many other features of
  modern machines and languages.  However, M1 is an excellent place
  to start when learning how to formalize a machine and to prove
  theorems about it.  Furthermore, it is the starting place of a
  series of machine models in the JVM family that we explore more
  fully at the end of this documentation topic.

  Our discussion of this simple machine is quite long!  The reason is
  that we're not trying just to explain the M1 model and how to prove
  correctness theorems about M1 programs; we're trying to explain how
  to create your own model, how to configure ACL2 to manipulate it,
  and how to phrase correctness conjectures so that ACL2 can prove
  them.  We're using a simple machine as the vehicle.

  The ACL2 book defining M1 and all the necessary configuration lemmas,
  [47mmodels/jvm/m1/m1.lisp[0m, is less than 8K bytes, and the script for
  proving an M1 factorial program correct, [47mmodels/jvm/m1/fact.lisp[0m,
  is less than 6K bytes.  If we strip out the comments, those two
  files combined are less than 8K bytes or about 5 pages.  But this
  doc topic is about 64K bytes or about 35 pages.  So don't despair.
  It takes longer to explain how to do it than to do it!

  You can find the definition of M1 and all of the work done with it on
  the ACL2 directory [47mbooks/models/jvm/m1[0m.  It might be easiest to
  fire up your ACL2 system and do this.

    (include-book \"models/jvm/m1/m1\" :dir :system)
    (in-package \"M1\")

  Then, to see the definition of any symbol mentioned below you could
  just issue the [47m:[0m[47m[pe][0m command.  For example, to see the definition
  of the function [47mexecute-ILOAD[0m, aka [47mexecute-iload[0m, you could type
  [47m:pe execute-iload[0m to the interactive prompt in your ACL2 session.
  This doc topic will not exhibit all the functions but will give
  examples of each ``kind'' of function involved in M1.


Setting up a Symbol Package

  All of the functions defined to describe M1 are in a new symbol
  package named [47m\"M1\"[0m.  This allows us to avoid name clashes with
  functions like [47mpop[0m, [47mprogram[0m, and [47mpc[0m that are predefined in the
  default [47m\"ACL2\"[0m symbol package.

    (defpkg \"M1\"
      (set-difference-eq
        (union-eq *acl2-exports*
                  *common-lisp-symbols-from-main-lisp-package*)
        '(push pop pc program step nth update-nth nth-update-nth)))

  Note that we put all the usual ACL2 symbols and Common Lisp symbols
  in the new package, except for a few whose names clash with names
  we want to define for use in our model.

  See the ACL2 file [47mbooks/models/jvm/m1/m1.acl2[0m.


The Definition of M1

  See the ACL2 file [47mbooks/models/jvm/m1/m1.lisp[0m for all of the
  functions mentioned below.

  The [3mstate[0m, [47ms[0m, of M1 will be given by a list of four elements,
  accessed with the functions named below.

    * [47mpc[0m --- a natural number giving the position in [47m(program s)[0m of the
      next instruction

    * [47mlocals[0m --- a list containing the values, by position, of the local
      variables of the program

    * [47mstack[0m --- a list representing a stack of intermediate results, the
      [47mcar[0m being the topmost value

    * [47mprogram[0m --- a list of instructions (see below)

  States will be constructed with

    (defun make-state (pc locals stack program)
       (cons pc
             (cons locals
                   (cons stack
                         (cons program
                               nil)))))

  Thus, [47m(make-state pc locals stack program)[0m is just [47m(list pc locals
  stack program)[0m.  The state accessors just select the appropriate
  elements of a state, e.g., [47m(stack (make-state pc locals stack
  program))[0m is just [47mstack[0m.

  To ``abstractly'' treat a list as a stack we define

    (defun push (x y) (cons x y))   ; return a new stack with x on top of stack y
    (defun top (stack) (car stack)) ; return topmost element of stack
    (defun pop (stack) (cdr stack)) ; remove topmost element and return that stack

  To access and update the elements of a list by 0-based positions we
  define

    (defun nth (n list)
      (if (zp n)
          (car list)
        (nth (- n 1) (cdr list))))

    (defun update-nth (n v list)
      (if (zp n)
          (cons v (cdr list))
        (cons (car list)
              (update-nth (- n 1) v (cdr list)))))

  Thus, [47m(nth 3 '(10 20 30 40 50))[0m is [47m40[0m and [47m(update-nth 3 45 '(10 20 30
  40 50))[0m is [47m(10 20 30 45 50)[0m.

  The eight M1 instructions are

    * [47m(ICONST i)[0m --- push [47mi[0m onto the stack and advance the pc by 1

    * [47m(ILOAD i)[0m --- push the value of the [47mi[0mth local onto the stack and
      advance the pc by 1

    * [47m(ISTORE i)[0m --- pop the topmost value from the stack, store it as the
      value of the [47mi[0mth local, and advance the pc by 1

    * [47m(IADD)[0m --- pop the topmost value, [47mu[0m, and value just under it, [47mv[0m, from
      the stack, push [47m(+ v u)[0m onto the stack, and advance the pc by 1

    * [47m(ISUB)[0m --- pop the topmost value, [47mu[0m, and value just under it, [47mv[0m, from
      the stack, push [47m(- v u)[0m onto the stack, and advance the pc by 1

    * [47m(IMUL)[0m --- pop the topmost value, [47mu[0m, and value just under it, [47mv[0m, from
      the stack, push [47m(* v u)[0m onto the stack, and advance the pc by 1

    * [47m(GOTO i)[0m --- advance the pc by [47mi[0m

    * [47m(IFEQ i)[0m --- pop the topmost value from the stack and if it is 0,
      then advance the pc by [47mi[0m and otherwise advance the pc by 1

  In the case of both [47mGOTO[0m and [47mIFEQ[0m, the pc may be ``advanced'' by a
  negative amount.

  To access the components of an instruction we define

    (defun op-code (inst) (nth 0 inst))  ; return the op-code of instruction inst
    (defun arg1 (inst) (nth 1 inst))     ; return the operand of instruction inst

  For each instruction we define the function that takes the
  instruction and a state and returns the next state.  For example,

    (defun execute-ICONST (inst s)
      (make-state (+ 1 (pc s))
                  (locals s)
                  (push (arg1 inst) (stack s))
                  (program s)))

    (defun execute-ILOAD (inst s)
      (make-state (+ 1 (pc s))
                  (locals s)
                  (push (nth (arg1 inst)
                             (locals s))
                        (stack s))
                  (program s)))

    (defun execute-ISTORE (inst s)
      (make-state (+ 1 (pc s))
                  (update-nth (arg1 inst) (top (stack s)) (locals s))
                  (pop (stack s))
                  (program s)))

    (defun execute-IADD (inst s)
      (declare (ignore inst))
      (make-state (+ 1 (pc s))
                  (locals s)
                  (push (+ (top (pop (stack s)))
                           (top (stack s)))
                        (pop (pop (stack s))))
                  (program s)))

    (defun execute-IFEQ (inst s)
      (make-state (if (equal (top (stack s)) 0)
                      (+ (arg1 inst) (pc s))
                    (+ 1 (pc s)))
                  (locals s)
                  (pop (stack s))
                  (program s)))

  The other instructions are analogous.  Many users define an ACL2
  macro, typically named [47mmodify[0m that takes a machine state and some
  keyword argument and builds a new state from the given one, with
  new values for the keys specified with keywords.  So for example,
  in that idiom one might replace the [47mmake-state[0m call in [47mexecute-IADD[0m
  by

    (modify s :pc (+ 1 (pc s))
              :stack (push (+ (top (pop (stack s)))
                              (top (stack s)))
                           (pop (pop (stack s)))))

  omitting any mention of [47mlocals[0m and [47mprogram[0m because they are not
  changed.  But for beginners we prefer the [47mmake-state[0m idiom because
  it is more explicit.

  We wrap all those ``execute'' functions up into a big-switch.

    (defun do-inst (inst s)         ; do instruction inst to state s
      (if (equal (op-code inst) 'ILOAD)
          (execute-ILOAD  inst s)
          (if (equal (op-code inst) 'ICONST)
              (execute-ICONST  inst s)
              (if (equal (op-code inst) 'IADD)
                  (execute-IADD   inst s)
                  (if (equal (op-code inst) 'ISUB)
                      (execute-ISUB   inst s)
                      (if (equal (op-code inst) 'IMUL)
                          (execute-IMUL   inst s)
                          (if (equal (op-code inst) 'ISTORE)
                              (execute-ISTORE  inst s)
                              (if (equal (op-code inst) 'GOTO)
                                  (execute-GOTO   inst s)
                                  (if (equal (op-code inst) 'IFEQ)
                                      (execute-IFEQ   inst s)
                                      s)))))))))

  Observe that if [47mdo-inst[0m is called on an unknown instruction it
  returns the state unchanged.  Thus [47m(do-inst '(HALT) s)[0m is just [47ms[0m.

  To access the next instruction in a state we define

    (defun next-inst (s)
      (nth (pc s) (program s)))

  In some of our theorems about [47mm1[0m it is convenient to have a way to
  say ``the machine has reached the [47m(HALT)[0m instruction, i.e., the [47mpc[0m
  points to [47m(HALT)[0m,'' so we define

    (defun haltedp (s)
      (equal (next-inst s) '(HALT)))

  To ``step'' the machine just once we define

    (defun step (s)
      (do-inst (next-inst s) s))

  Finally we define [47mm1[0m to step [47mn[0m times.

    (defun m1 (s n)
      (if (zp n)
          s
          (m1 (step s) (- n 1))))

  In a model like this one, where we control the length of the run by a
  natural-number step count, we often call the second argument of [47mm1[0m
  the ``clock.'' One might think of it as counting ``cycles'' but not
  ``run time.'' Some authors call the argument ``fuel''.  In some
  models the ``clock'' might actually be a list and be called by a
  different name depending on how that list is used.  We've seen it
  called ``schedule'' (because it specifies which process is to step
  next), ``inputs'' (because it specifies what signals appear on
  certain pins in the each cycle), and ``oracle'' (because it
  specifies ``random'' choices).


Programming M1

  Below we exhibit an M1 program for computing factorial.  For
  convenience we define a constant with this program as its value so
  we can refer to it.  We name the constant ``pi'' for ``program''.
  In the comments to the right of the instructions we show the
  position (i.e., the corresponding pc) of the instruction and
  pseudocode for the nearby snippet of code.  In this program we will
  have just two local variables, called ``[47mn[0m'' and ``[47mans[0m'' in the
  pseudocode, in positions 0 and 1 respectively of the [47mlocals[0m.  We'll
  compute [47m(fact n)[0m and leave the result in [47mans[0m and on top of the
  stack.

    (defconst *pi*
                    ; pc    pseudo-code
      '((iconst 1)  ;  0                    [Block 1]
        (istore 1)  ;  1    ans := 1;

        (iload 0)   ;  2  loop:             [Block 2]
        (ifeq 10)   ;  3    if n=0 then goto exit (i.e., pc+10);

        (iload 1)   ;  4                    [Block 3]
        (iload 0)   ;  5
        (imul)      ;  6
        (istore 1)  ;  7    ans := ans * n;

        (iload 0)   ;  8                    [Block 4]
        (iconst 1)  ;  9
        (isub)      ; 10
        (istore 0)  ; 11    n := n - 1;

        (goto -10)  ; 12    goto loop;      [Block 5]

        (iload 1)   ; 13 exit:              [Block 6]
        (halt)))    ; 14   return ans;

  We've put blank lines in the display to break the program into
  blocks, which we've numbered.  We'll describe each block's effect
  now, just to drive home how [47mm1[0m behaves.  We will use these blocks
  in some examples later.

  Block 1 is the ``compilation'' of ``ans := 1;'' The [47m(iconst 1)[0m pushes
  [47m1[0m onto the stack and the [47m(istore 1)[0m pops it off into local 1, which
  we're calling ``[47mans[0m''.

  We have labeled the top of Block 2 ``[47mloop[0m.'' Although it is not
  syntactically obvious in this assembly-like code, subsequent code
  will jump back to [47mpc[0m 2.

  Block 2 is the compilation of ``if [47mn[0m=0, then goto exit,'' where we
  labeled [47mpc[0m 13 ``[47mexit[0m.'' In particular, the [47m(iload 0)[0m at [47mpc[0m 2 pushes
  the value of ``[47mn[0m'') onto the stack.  The instruction at [47mpc[0m 3, [47m(ifeq
  10)[0m, pops it off and tests it against [47m0[0m.  If [47mn[0m=0, the [47mifeq[0m
  increments the [47mpc[0m by 10, transferring control to [47mpc[0m 13.

  Block 3 is the compilation of ``ans := ans * n;''.  Walk that code
  segment to understand.

  Block 4 is the compilation of ``n := n - 1;''.

  Block 5 jumps back to [47mpc[0m 2 (i.e., [47mloop[0m).  In particular, the [47m(goto
  -10)[0m at [47mpc[0m 12 adds -10 to the [47mpc[0m.

  Block 6 is the compilation of ``return [47mans[0m.'' It just pushes local 1
  onto the stack and halts, leaving the [47mpc[0m at 14.

  If all we wanted to do with [47mm1[0m is run programs on it, we're done!  [47mM1[0m
  as defined above can be run on concrete input to produce concrete
  results.

  For example, to compute factorial of 6 we would start with this
  state:

    (make-state 0           ; pc - first instruction
                (list 6 0)  ; locals - n = 6, ans = 0
                nil         ; stack - empty
                *pi*)       ; program

  and run it with [47mm1[0m.  Of course, we need to specify the ``clock,'' the
  number of steps we want to take.  In the absence of any better
  idea, we could just try 1000 and see if the final state is at [47mpc[0m
  14, which is the [47m(HALT)[0m.

    M1 !>(m1 (make-state 0          ; pc
                         (list 6 0) ; locals
                         nil        ; stack
                         *pi*)      ; program
             1000)
    (14 (0 720)                     ; pc and locals
        (720)                       ; stack
        ((ICONST 1)                 ; program
         (ISTORE 1)
         (ILOAD 0)
         (IFEQ 10)
         (ILOAD 1)
         (ILOAD 0)
         (IMUL)
         (ISTORE 1)
         (ILOAD 0)
         (ICONST 1)
         (ISUB)
         (ISTORE 0)
         (GOTO -10)
         (ILOAD 1)
         (HALT)))

  Notice that the machine reached the [47m(HALT)[0m at [47mpc[0m 14 and [47m720[0m is on top
  of the stack.  We also may note that local 0 has been zeroed out
  and local 1 contains 720.

  We will deal with the clock situation more carefully later.  It
  should be noted that our definition of [47mm1[0m actually executes 1000
  steps if that's what the clock says.  In particular, the [47mHALT[0m
  instruction is a no-op, making no state change, and [47mm1[0m just
  continues to bang away while sitting on that instruction until the
  clock runs out.  We could, of course, define [47mm1[0m differently, so as
  to return [47ms[0m whenever when [47m(step s)[0m = [47ms[0m.  But we'll keep [47mm1[0m simple.


``Teaching'' the Prover How to Control M1

  We'll now turn our attention to configuring ACL2 to prove things
  about M1 programs.  This basically consists of proving lemmas to be
  used as [47m:[0m[47mrewrite[0m rules and, sometimes, disabling functions so that
  their calls don't expand automatically.  We'll explain the
  motivations of our configuration as we go, but true understanding
  of the motivation won't come until we prove an M1 program correct.
  Be patient.

  This section only exhibits some of the rules we introduce.  All of
  the necessary rules can be found in the same file in which M1 is
  defined, the ACL2 file [47mbooks/models/jvm/m1/m1.lisp[0m.  By the way,
  the sequence in which these definitions and lemmas appear below is
  not identical to the sequence in the [47mm1.lisp[0m file, but they're all
  there.  In telling the story we just found the sequence below a
  little more natural.

  Arithmetic

  To be able to reason about simple arithmetic, we include one of the
  standard arithmetic books.

    (include-book \"arithmetic-5/top\" :dir :system)

  Resolving ``Reads'' and ``Writes''

  The local variables are read and written positionally using [47mnth[0m and
  [47mupdate-nth[0m.  It is helpful to have the following lemmas to resolve
  reads after writes and eliminate shadowed writes.  (These lemmas
  are not necessary in most of our [47mm1[0m proofs because the locals are
  generally expressed as ``semi-concrete'' list (i.e., a [47mcons[0m tree
  with symbolic expressions in the [47mcar[0m positions) of a fixed length,
  like [47m(list a b c)[0m and reads and writes always address an explicitly
  specified position, like [47m2[0m, so even after a sequence of [47mm1[0m
  instructions storing values, the symbolic expression of the locals
  will be a fixed length semi-concrete list.  For example [47m(update-nth
  2 (+ u v) (list a b c d))[0m is automatically rewritten to [47m(list a b
  (+ u v) d)[0m just by the definition of [47mupdate-nth[0m.  But in more
  general situations, where the position of the local variable is not
  an explicit constant or the symbolic expression of the current
  values of the locals in the state is not an explicit [47mcons[0m tree, the
  lemmas below are crucial.

    (defthm nth-add1!
      (implies (natp n)
               (equal (nth (+ 1 n) list)
                      (nth n (cdr list)))))

    (defthm nth-update-nth
      (implies (and (natp i) (natp j))
               (equal (nth i (update-nth j v list))
                      (if (equal i j)
                          v
                        (nth i list)))))

    (defthm update-nth-update-nth-1
      (implies (and (natp i) (natp j) (not (equal i j)))
               (equal (update-nth i v (update-nth j w list))
                      (update-nth j w (update-nth i v list))))
      :rule-classes ((:rewrite :loop-stopper ((i j update-nth)))))

    (defthm update-nth-update-nth-2
      (equal (update-nth i v (update-nth i w list))
             (update-nth i v list)))

  Keeping ``Abstractions'' Abstract

  To allow us to reason about ``abstract'' structures represented by
  [47mcons[0mes, without expanding their definitions, we prove such lemmas
  as

    (defthm stacks
      (and (equal (top (push x s)) x)
           (equal (pop (push x s)) s)

    ; These next two are needed because some push expressions evaluate to
    ; list constants, e.g., (push 1 (push 2 nil)) becomes '(1 2) and '(1
    ; 2) pattern-matches with (cons x s) but not with (push x s).

           (equal (top (cons x s)) x)
           (equal (pop (cons x s)) s)))

  We prove the analogous rules about state accessors and [47mmake-state[0m,
  e.g., [47m(equal (pc (make-state pc locals stack program)) pc)[0m.  Then
  we disable all the defined functions just mentioned so they never
  expand.

  Controlling Case Explosion due to Step

  Next we introduce a crucial rule for controlling the expansion of
  [47mstep[0m.  The term [47m(step s)[0m can always be expanded into that
  big-switch that considers all the possible [47mop-code[0ms.  That is
  generally a disaster.  Think of what would happen if [47m(step (step
  s))[0m were automatically expanded when we have no information about
  [47ms[0m: the inner [47mstep[0m would introduce a 9-way case split and the outer
  one would turn that into an 81-way case split considering all of
  the possibilities for the first two instructions.  We want to
  expand [47mstep[0m only when we know something definite about the
  instruction that is to be executed.  So we prove this logically
  trivial theorem.

    (defthm step-opener
      (implies (consp (next-inst s))
               (equal (step s)
                      (do-inst (next-inst s) s))))

  The conclusion is just the definition of [47mstep[0m!  So the hypothesis is
  completely unnecessary from a logical perspective.  But
  operationally, if this rule has been proved and then [47mstep[0m is
  disabled, the rewriter will expand [47m(step s)[0m only if [47m(next-inst s)[0m
  can be proved to satisfy [47mconsp[0m.  The most common way for [47m(next-inst
  s)[0m to be a [47mconsp[0m is when both the [47mpc[0m and the [47mprogram[0m in state [47ms[0m are
  quoted constants and [47mprogram[0m is a well-formed program.  But we
  don't want to require exactly that because it is too restrictive.
  For example, in machine models supporting subroutine calls, the
  typical correctness theorem for a subroutine says very little about
  the entire ``program space'' but deals with an [47minvoke[0m- or [47mjsr[0m-type
  instruction to a place where the code for the subroutine is found.
  (If you inspect [47mbooks/models/jvm/m2/examples.lisp[0m and look at
  [47mexample4[0m you will see such a correctness theorem.)  As models get
  more complex you may have to adjust [47mstep-opener[0m accordingly, though
  this simple version is surprisingly effective.

  Having established [47mstep-opener[0m, we disable [47mstep[0m so that the only way
  it ever expands is when the [47mnext-inst[0m is provably a [47mconsp[0m.

    (in-theory (disable step))

  [31;1mSymbolic Execution Example 1[0m

  To illustrate the rules just described, consider the symbolic
  expression

    (step
      (step
        (make-state 0
                    (list n ans)
                    stack
                    *pi*    ; '((ICONST 1)  ;  0             [Block 1]
                            ;   (ISTORE 1)  ;  1   ans := 1;
                            ;   ...         ;  2
                            ;   ...)        ; ...
                    )))

  Note that the outer [47mstep[0m cannot be expanded because [47mstep[0m is disabled
  and we can't determine the [47mnext-instr[0m of the (unsimplified) inner
  [47mstep[0m.

  But [47mstep-opener[0m fires on the inner [47mstep[0m because [47mnext-inst[0m of the
  above [47mmake-state[0m just rewrites to [47m'(ICONST 1)[0m using the definitions
  of [47mpc[0m, [47mprogram[0m, and [47mnth[0m.  So the term above is rewritten to

    (step
      (make-state 1
                  (list n ans)
                  (push 1 stack)
                  *pi*    ; '((ICONST 1)    ;  0             [Block 1]
                          ;   (ISTORE 1)    ;  1   ans := 1;
                          ;   ...           ;  2
                          ;  ...)           ; ...
                  ))

  using [47mstep-opener[0m, [47mnext-inst[0m, [47mdo-inst[0m, [47mexecute-iconst[0m, [47mnth[0m, and
  [47mupdate-nth[0m.  [47mExecute-iconst[0m just advanced the [47mpc[0m from 0 to 1 and
  symbolically pushed a [47m1[0m into the [47mstack[0m.

  But now [47mstep-opener[0m can fire on that outer [47mstep[0m because we see that
  the [47mnext-inst[0m of this state is [47m(ISTORE 1)[0m.  So the term rewrites to

    (make-state 2
                (list n 1)
                stack
                *pi*    ; '((ICONST 1)      ;  0             [Block 1]
                        ;   (ISTORE 1)      ;  1   ans := 1;
                        ;   ...             ;  2
                        ;   ...)            ; ...
                )

  We've just symbolically executed the first two instructions of [47m*pi*[0m
  on a symbolic state containing two unspecified locals and an
  unspecified stack.  This simplification is completely automatic.

  [31;1mSymbolic Execution Example 2[0m

  We'll show one more symbolic execution of a snippet from program
  [47m*pi*[0m.  This time, let's start at top of the loop in [47m*pi*[0m, [47mpc[0m 2, and
  run down through the [47m(GOTO -10)[0m where the program jumps back to the
  loop.  That takes 11 [47mstep[0ms.  Furthermore, assume that [47mn[0m (local 0)
  is a non-0 natural number and [47mans[0m (local 1) is a natural number.

    (m1 (make-state 2 (list n ans) stack *pi*) 11)
    =
    (step
     (step
      (step
       (step
        (step
         (step
          (step
           (step
            (step
             (step
              (step
               (make-state 2
                           (list n ans)
                           stack
                           *pi*    ; '(...        ;  ...
                                   ;   (ILOAD 0)  ;  2 loop: [Block 2]
                                   ;   (IFEQ 10)  ;  3
                                   ;   (ILOAD 1)  ;  4       [Block 3]
                                   ;   (ILOAD 0)  ;  5
                                   ;   (IMUL)     ;  6
                                   ;   (ISTORE 1) ;  7
                                   ;   (ILOAD 0)  ;  8       [Block 4]
                                   ;   (ICONST 1) ;  9
                                   ;   (ISUB)     ; 10
                                   ;   (ISTORE 0) ; 11
                                   ;   (GOTO -10) ; 12       [Block 5]
                                   ;   ...)
                           ))))))))))))

  (Exceedingly deep nests of [47mstep[0ms can cause stack overflow in the ACL2
  rewriter.  We discuss this problem the presentation of the
  [47mm1-opener[0m lemma below.)

  We won't show the step-by-step results of this symbolic execution
  (thank goodness!), but the first two instructions just move the [47mpc[0m
  from 2 to 4 because [47mn[0m is not 0.  The next four replace [47mans[0m by [47m(*
  ans n)[0m, the next four replace [47mn[0m by [47m(- n 1)[0m, and the last [47mstep[0m sets
  the [47mpc[0m to the top of the loop at [47mpc[0m 2 again.  Despite the pushing
  and popping on the stack, by the time we get back to the top of the
  loop, the stack is unchanged.  The result is

    (make-state 2
                (list (- n 1) (* ans n))
                stack
                *pi*               ; '(...        ;  ...
                                   ;   (ILOAD 0)  ;  2 loop: [Block 2]
                                   ;   (IFEQ 10)  ;  3
                                   ;   (ILOAD 1)  ;  4       [Block 3]
                                   ;   (ILOAD 0)  ;  5
                                   ;   (IMUL)     ;  6
                                   ;   (ISTORE 1) ;  7
                                   ;   (ILOAD 0)  ;  8       [Block 4]
                                   ;   (ICONST 1) ;  9
                                   ;   (ISUB)     ; 10
                                   ;   (ISTORE 0) ; 11
                                   ;   (GOTO -10) ; 12       [Block 5]
                                   ;   ...)
                )

  We'll see this expression again later.  What's important is that with
  the [47mstep[0m rules we have in place, ACL2 will automatically do
  symbolic evaluation of concrete code sequences.

  Clock Expressions

  Many (most?) of our theorems about specific M1 programs will involve
  a clock expression which specifies exactly how many steps we want
  the machine to take.  It is not as hard as you might think to
  create functions that compute this --- provided you can prove that
  the clock function terminates, which is of course generally
  undecidable but frequently trivial.  And, proofs via clock
  functions are not only equivalent to proofs by inductive assertions
  but that has been proved with ACL2 and tools are provided to
  convert back and forth between the two proof styles (see
  [bib::rm04]).

  Clock functions for [47mm1[0m are recursive functions defined that use
  arithmetic expressions to compute the lengths of code segments.
  However, a key part of our strategy for controlling proofs is to
  use the structure of the clock function and its arithmetic
  expressions to decompose ``long'' runs of [47mm1[0m into compositions of
  shorter runs.  In order to do that, we must prevent the prover from
  rearranging our clocks!  That is, [47m(m1 s (+ i j))[0m will decompose
  differently than [47m(m1 s (+ j i))[0m, but the arithmetic library might
  rearrange the clock, e.g., by using the commutativity of addition.
  So instead of using [47m+[0m to express the the addition of two clocks we
  define [47mclk+[0m to be [47m+[0m, but we'll disable its definition to protect
  clocks from arithmetic reasoning.  We will arrange for [47mclk+[0m to take
  more than just two arguments and will reveal that it is
  associative.

    (defun binary-clk+ (i j)
      (+ (nfix i) (nfix j)))

    (defthm clk+-associative
      (equal (binary-clk+ (binary-clk+ i j) k)
             (binary-clk+ i (binary-clk+ j k))))

    (defmacro clk+ (&rest args)
      (if (endp args)
          0
          (if (endp (cdr args))
              (car args)
              `(binary-clk+ ,(car args)
                             (clk+ ,@(cdr args))))))

  Thus [47m(clk+ a b c)[0m is just an abbreviation for [47m(binary-clk+ a
  (binary-clk+ b c))[0m, and the prover will rewrite [47m(clk+ (clk+ a b)
  (clk+ d e))[0m to the [47mbinary-clk+[0m version of [47m(clk+ a b c d)[0m.

  The key fact about clocks and [47mm1[0m is captured in the following rewrite
  rule, which is sometimes called the ``sequential execution'' rule
  or the ``semi-colon rule.''

    (defthm m1-clk+
      (equal (m1 s (clk+ i j))
             (m1 (m1 s i) j)))

  Having proved this, we disable [47mbinary-clk+[0m so that we have complete
  control over how long runs decompose.

  Expanding [47mm1[0m

  Of course, [47mm1[0m must eventually expand.  The following rule effectively
  makes the prover open [47mm1[0m only when the clock is a natural number
  constant.  (We say ``effectively'' because we assume that all clock
  expressions are phrased in terms of [47mclk+[0m.)  The rule below exploits
  the fact that the prover sees [47m7[0m, for example, as [47m(+ 1 6)[0m.

    (defthm m1-opener
      (and (equal (m1 s 0) s)
           (implies (natp i)
                    (equal (m1 s (+ 1 i))
                           (m1 (step s) i)))))

  We then disable [47mm1[0m.

  [31;1mObscure Remark[0m: Experiments with the [47mcodewalker[0m tool (see the ACL2
  book [47mbooks/projects/codewalker/codewalker.lisp[0m, specifically the
  discussion of ``snorkling'') suggest that nests of [47mstep[0ms more than
  several hundred deep (depending on the complexity of [47mstep[0m) can
  cause stack overflow.  One way to handle that is to modify
  [47mm1-opener[0m, above, using a [47m[syntaxp][0m hypothesis so that it doesn't
  fire if [47mi[0m is, say, larger than 200.  Then prove a variant for
  ``large'' natural numbers, [47mi[0m, that transforms [47m(m1 s i)[0m into p [47m(m1
  (m1 s 200) (- i 200))[0m, using [47m[syntaxp][0m to limit the application to
  [47ms[0m terms that are [3mnot[0m calls of either [47mm1[0m or [47mstep[0m, and [47mi[0m terms that
  are quoted natural numbers.  This variant can be derived from
  [47mm1-clk+[0m.  (Note: a hint is necessary to keep our other rules from
  interfering with the obvious proof.)  The effect of this more
  sophisticated variant of [47mm1-opener[0m is that an expression like [47m(m1 s
  900)[0m is rewritten first to [47m(m1 (m1 s 200) 700)[0m; the sophisticated
  rule won't fire on the outer [47mm1[0m because it is applied to an [47mm1[0m
  term, but the conventional [47mm1-opener[0m will fire on the inner [47m(m1 s
  200)[0m because of the small clock.  That will reduce the inner [47mm1[0m to
  a semi-explicit state, and then another 200 steps will be taken
  from the 700, etc.  We do not recommend doing this until you start
  to get stack overflows, but we point out the possibility to
  highlight the tricks you can use to control expansions.

  But for the rest of this discussion we assume we just have the
  conventional [47mm1-opener[0m. The rules shown above have the effect of
  rewriting the following [47mm1[0m call successively into the last term
  below.

    (m1 (make-state 0 (list n ans) stack *pi*)
        (clk+ 2 (loop-clk n)))

    =                             {by m1-clk+}

    (m1 (m1 (make-state 0 (list n ans) stack *pi*)
            2)
        (loop-clk n))

    =                             {by m1-opener}

    (m1 (step (step (make-state 0 (list n ans) stack *pi*)))
        (loop-clk n))

    =                             {by step-opener}

    (m1 (make-state 2
                    (list n 1)
                    stack
                    *pi*)
        (loop-clk n))

  The last simplification above is just the symbolic evaluation of the
  first two instructions of [47m*pi*[0m, as we shown Symbolic Execution
  Example 1.

  We'll see the final [47mm1[0m expression again later, when we prove [47m*pi*[0m
  computes the factorial function.


Playing with Program *pi*: Execution, Symbolic Execution, and Proof
of Correctness

  In this section use program [47m*pi*[0m to compute factorial on a concrete
  state, essentially using our formal model as a prototype of the
  envisioned machine.  We show two examples, [47mn[0m = 6 and [47mn[0m = 1000.  The
  latter requires several thousand [47mm1[0m steps and allows us to time the
  execution speed of [47mm1[0m.  We then show the theorem prover doing
  symbolic execution of a snippet of [47m*pi*[0m to help us ``reverse
  engineer'' the loop.  Finally, we prove that when program [47m*pi*[0m is
  run on a natural number [47mn[0m in local 0, it halts and leaves [47m(fact n)[0m
  on top of the stack, where [47mfact[0m is defined in the classic recursive
  way.  In fact, we prove something stronger and explain why.

  The Clock for Factorial

  If we start at [47mpc[0m 0, how many steps must we take to reach the [47mhalt[0m?
  We take 2 steps to reach the instruction labeled [47mloop[0m at [47mpc[0m 2.
  We'll then travel around the loop some ``unknown'' number of times
  as a function of [47mn[0m before exiting and reaching the [47mHALT[0m.
  (Technically the iteration might also depend on [47mans[0m but in this
  case it does not.)  Let [47m(loop-clk n)[0m be the number of steps we take
  from [47mpc[0m 2 to the [47mHALT[0m.  After defining [47mloop-clk[0m we can define the
  clock for [47m*pi*[0m to be

    (defun clk (n)
      (clk+ 2
            (loop-clk n)))

  To derive a definition for [47mloop-clk[0m just walk the code starting at [47mpc[0m
  2.  The code tests whether [47mn[0m is zero and if so jump to 13 where it
  puts [47mans[0m on the stack and halt.  Thus, if [47mn[0m is zero, we take 3
  steps.  If [47mn[0m is not zero (which takes 2 steps to determine), we
  multiply [47mn[0m into [47mans[0m (at [47mpc[0ms 4-7, which takes 4 steps), decrement [47mn[0m
  (at [47mpc[0ms 8-11, which takes 4 steps), and then at [47mpc[0m 12 the code
  jumps back to loop (which takes 1 step).  So after a total of
  2+4+4+1 = 11 steps we're back at [47mpc[0m 2 having decremented [47mn[0m by 1.
  So here is how many steps we take from [47mpc[0m 2 to the [47mhalt[0m:

    (defun loop-clk (n)
      (if (zp n)
          3
          (clk+ 11
                (loop-clk (- n 1)))))

  Question: how many steps does it take to compute [47m6![0m?  Answer: [47m(clk 6)[0m
  = 71.

  Computing with M1

  If we fire up ACL2, include the [47mm1[0m book, select the [47m\"M1\"[0m symbol
  package, and define [47m*pi*[0m, [47mloop-clk[0m, and [47mclk[0m as shown above, we can
  use [47mm1[0m to compute various factorials.

    M1 !>(m1 (make-state 0           ; pc
                         (list 6 0)  ; locals n = 6 and ans = 0
                         nil         ; stack (empty)
                         *pi*)       ; program
             (clk 6))
    (14 (0 720)
        (720)
        ((ICONST 1)
         (ISTORE 1)
         (ILOAD 0)
         (IFEQ 10)
         (ILOAD 1)
         (ILOAD 0)
         (IMUL)
         (ISTORE 1)
         (ILOAD 0)
         (ICONST 1)
         (ISUB)
         (ISTORE 0)
         (GOTO -10)
         (ILOAD 1)
         (HALT)))

  Observe the final state: the [47mpc[0m is [47m14[0m, which points to the [47m(HALT)[0m.
  Local 0, i.e., [47mn[0m, has been zeroed out but local 1, i.e., [47mans[0m,
  contains [47m720[0m.  Furthermore, [47m720[0m has been pushed onto the stack.
  The [47mprogram[0m, of course, is unchanged.  And by the way, 720 =
  6*5*4*3*2*1.

  Of course, we can define factorial recursively in ACL2 and check the
  [47mm1[0m computation.

    M1 !>(defun fact (n)
           (if (zp n)
               1
               (* n (fact (- n 1)))))

    The admission of FACT is trivial, ...
    ...

    M1 !>(fact 6)
    720

  We can compute larger factorials with [47mm1[0m, of course.  Here's how we
  compute [47m1000![0m with [47mm1[0m.

    M1 !>(m1 (make-state 0 (list 1000 0) nil *pi*) (clk 1000))

  It takes SBCL about 0.02 seconds to compute the answer.  The answer
  is a natural number with 2,568 decimal digits, so we won't show it
  here, but you can try it on your own.  [47m(Clk 1000)[0m is 11,005, so
  during this particular computation, ACL2 was executing 550,250 M1
  instructions per second.  Our model would run faster if we used a
  single-threaded object (see [47mstobj[0m) to hold the state and faster
  still if we verified the guards of [47mm1[0m.  We point to discussions and
  examples of these ideas at the end of this topic.

  Symbolic Execution of M1 Code

  We can use the theorem prover to help us reverse engineer code.  For
  example, what does the loop in [47m*pi*[0m do?  We actually posed the
  question in Symbolic Execution Example 2 above, i.e., what is [47m(m1
  (make-state 2 (list n ans) stack *pi*) 11)[0m when [47mn[0m and [47mans[0m are
  natural numbers and [47mn[0m is not [47m0[0m.  We can pose a (non-)theorem to the
  prover to see.  The lefthand side of the equality just simplifies
  to the nest of 11 [47mstep[0ms from Symbolic Execution Example 2.  The
  righthand side, below, is the variable [47m???[0m, so this formula is
  obviously not a theorem, but the prover will simplify the formula
  and print the checkpoint.

    (thm (implies (and (natp n)
                       (< 0 n)
                       (natp ans))
                  (equal (m1 (make-state 2 (list n ans) stack *pi*) 11)
                         ???)))

  Of course, the proof attempt fails.  But if you look at the
  checkpoint you should recognize the simplified expression as being
  from Example 2.

    Goal''
    (IMPLIES (AND (INTEGERP N)
                  (<= 0 N)
                  (< 0 N)
                  (INTEGERP ANS)
                  (<= 0 ANS))
             (EQUAL (MAKE-STATE 2 (LIST (+ -1 N) (* ANS N))
                                STACK
                                '((ICONST 1)
                                  (ISTORE 1)
                                  (ILOAD 0)
                                  (IFEQ 10)
                                  (ILOAD 1)
                                  (ILOAD 0)
                                  (IMUL)
                                  (ISTORE 1)
                                  (ILOAD 0)
                                  (ICONST 1)
                                  (ISUB)
                                  (ISTORE 0)
                                  (GOTO -10)
                                  (ILOAD 1)
                                  (HALT)))
                    ???))

  Proving Theorems about M1 Programs

  In this section we prove that [47m*pi*[0m computes factorial.

  [31;1mStep 0: The Specification[0m We've already specified, informally, that
  we intend that [47m*pi*[0m computes [47m(fact n)[0m when [47mn[0m is a natural number.
  This is just shorthand for the more precise understanding that if
  we start at [47mpc[0m 0 with a natural, [47mn[0m, in local 0 and run program [47m*pi*[0m
  [47m(clk n)[0m steps, the final state has [47mpc[0m 14 (meaning execution reached
  the [47m(HALT)[0m), local 0 has been zeroed, local 1 contains [47m(fact n)[0m,
  and [47m(fact n)[0m is on top of the otherwise unchanged initial [47mstack[0m.

  [31;1mStep 1: The Semantic Function[0m Define an ACL2 function that ``does
  what the loop does.'' We sometimes call this the [3msemantic function[0m
  corresponding to the loop.

    (defun helper (n ans)
      (if (zp n)
          ans
          (helper (- n 1) (* ans n))))

  The function above captures [47m*pi*[0m's behavior from entry to the loop at
  [47mpc[0m 2 through the halt at [47mpc[0m 14.  Programs that have elaborate
  initialization and finalizations and/or multiple loops require
  defining a series of functions for each segment and loop.  But for
  this program, we can capture all of [47m*pi*[0m's behavior by calling the
  semantic function on the values the locals have upon entering the
  loop, i.e., [47m(helper n 1)[0m.

  [31;1mStep 2: Relate the Semantic Function to the Code[0m Prove that the loop
  does what we said it would do.

    (defthm loop-correct
      (implies (and (natp n)
                    (natp ans))
               (equal (m1 (make-state 2
                                      (list n ans)
                                      stack
                                      *pi*)
                          (loop-clk n))
                      (make-state 14
                                  (list 0 (helper n ans))
                                  (push (helper n ans) stack)
                                  *pi*))))

  This proof is completely ``automatic'' --- but only because we stated
  the theorem exactly right, in terms of [47mhelper[0m to ``explain'' what
  the loop is doing with the second local, [47mans[0m.  Once you get used to
  this style of proof, Step 2 is not really very creative: it just
  says what the program does operationally, using tail recursion in
  place of iteration.  Of course, recursion is ACL2's bread and
  butter.

  The proof of [47mloop-correct[0m is by the induction as suggested by [47m(helper
  n ans)[0m.  The induction scheme is

    (AND (IMPLIES (AND (NOT (ZP N))
                       (:P (* ANS N) (+ -1 N) STACK))
                  (:P ANS N STACK))
       (IMPLIES (ZP N) (:P ANS N STACK)))

  If you work it out you'll see that in the induction conclusion
  [47m(loop-clk n)[0m expands to [47m(clk+ 11 (loop-clk (- n 1)))[0m, and then the
  machinery we've been talking about reduces the induction conclusion
  to the induction hypothesis.  Do it for yourself.  You will see the
  simplifications done earlier in Symbolic Execution Example 2.
  (There is another basic case we haven't explicitly discussed: what
  happens when we're at the top of the loop but [47mn[0m is [47m0[0m?  That case is
  handled by symbolic execution: [47m(loop-clk n)[0m is 3, the [47mIFEQ[0m jumps to
  the exit to push [47mans[0m onto the stack and advance the [47mpc[0m to the
  [47m(HALT)[0m at 14.)

  [31;1mStep 3: Relate the Semantic Function to the Specification[0m

    (defthm helper-is-fact
      (implies (and (natp n)
                    (natp ans))
               (equal (helper n ans)
                      (* ans (fact n)))))

  This is proved ``automatically.''

  Generally speaking, Step 3 is the most creative step because it
  requires explaining how the ``iterative'' (tail-recursive)
  accumulation of the answer relates to the recursive computation of
  the answer.

  [31;1mStep 4: Total Correctness[0m Combine the foregoing into the statement of
  the total correctness of [47m*pi*[0m.

    (defthm correctness-of-*pi*
      (implies (natp n)
               (equal (m1 (make-state 0
                                      (list n ans)
                                      stack
                                      *pi*)
                          (clk n))
                      (make-state 14
                                  (list 0 (fact n))
                                  (push (fact n) stack)
                                  *pi*))))

  This is proved ``automatically'' because of our setup.

  [47m(Clk n)[0m expands to [47m(clk+ 2 (loop-clk n))[0m and the crucial [47mm1-clk+[0m
  (``sequential execution'') rule shows it is equivalent to

    (m1 (step (step (make-state 0
                                (list n ans)
                                stack
                                *pi*)))
        (loop-clk n))

  But then the [47mstep[0m rules can reduce that to:

    (m1 (make-state 2
                    (list n 1)
                    stack
                    *pi*)
        (loop-clk n))

  at which point the [47mloop-correct[0m lemma can fire and produce

    (make-state 14
                (list 0 (helper n 1))
                (push (helper n 1) stack)
                *pi*)

  and then [47m(helper n 1)[0m is rewritten [47m(fact n)[0m by [47mhelper-is-fact[0m and
  arithmetic, reducing the lefthand side to the righthand side.  (The
  above description is inaccurate only in the sequencing of the
  various rewrites.)  Q.E.D.

  Of course, from [47mcorrectness-of-*pi*[0m we can easily derive weaker but
  simpler results to ``advertise.''

    (defthm corollary-of-correctness-of-*pi*
      (implies (and (natp n)
                    (equal s_init (make-state 0 (list n ans) stack *pi*))
                    (equal s_fin (m1 s_init (clk n))))
               (and (equal (top (stack s_fin)) (fact n))
                    (equal (next-inst s_fin) '(HALT)))))

  Viewing these results from a higher level, one might argue that the
  corollary above is a ``better'' theorem than [47mcorrectness-of-*pi*[0m.
  It just says, simply, if you have an initial state poised to
  execute [47m*pi*[0m on [47mn[0m and you run it [47m(clk n)[0m steps to some ``final''
  state, that final state has [47m(fact n)[0m on top of the stack and is
  halted.  The full correctness result we proved says some
  ``irrelevant'' things: in the final state, [47mn[0m is 0, [47m(fact n)[0m is also
  in local 1, and the original stack is intact under the answer.

  But those facts are not irrelevant!  They (or something like them)
  are mathematically necessary for the inductive proof.  Remember,
  inductive proofs only work on sufficiently strong theorems.
  Furthermore, we really must care about these other issues even from
  the high level perspective.  If, for example, our program is just a
  subroutine of a larger system (on a machine that supports procedure
  call and return) we [3mreally need to know[0m that the stack is not
  disturbed since the results of prior computations may be sitting in
  it for use for future computations.  In a setting where we're
  concerned about privacy and security (in a machine with addressable
  memory) [3mwe really need to know[0m that information hasn't been moved
  from private space to public space.  In a setting where programs
  are in writable memory, [3mwe really need to know[0m that our program
  hasn't been overwritten by some subroutine.


More M1 Programs and Proofs

  The proofs described above can be seen in the ACL2 book
  [47mbooks/models/jvm/m1/fact.lisp[0m.  If the proof script here is taken
  as a template for all such proofs you'll find it a bit ``fragile''
  in the sense that lemmas proved in one step of the template may get
  in the way of proofs in subsequent steps.  That is generally dealt
  with by disabling certain lemmas when their work has been done.
  But, except for this issue of controlling rewriting a little more
  restrictively via disabling, this proof of the correctness of [47m*pi*[0m
  serves as a good template for clock-based total correctness proofs
  of single-loop [47mm1[0m programs.

  There are many other examples of proofs of [47mm1[0m programs on the
  directory [47mbooks/models/jvm/m1[0m.  Here is a brief guide.

    * [47mbooks/models/jvm/m1/template.lisp[0m: a ``robust'' template for proving
      the total correctness of one-loop [47mm1[0m programs.  The template is
      overly robust in the sense that it introduces often irrelevant
      intermediate functions, lemmas, and disable events.  In the
      vast majority of cases the proofs can be carried out with fewer
      events.  But until you understand how ACL2 behaves it's best to
      just rotely follow the template.

    * the files listed below contain simple one-loop [47mm1[0m programming and
      proof challenges.  Each file follows the template above.  We
      recommend that you [3mnot[0m look at the solutions and instead read
      the challenge programming/proof problem at the top of the file
      and then follow the template for yourself.  We also recommend
      you do these problems in the order listed, as they gradually
      get harder.

        * [47mbooks/models/jvm/m1/sum.lisp[0m

        * [47mbooks/models/jvm/m1/sumsq.lisp[0m

        * [47mbooks/models/jvm/m1/fact.lisp[0m

        * [47mbooks/models/jvm/m1/power.lisp[0m

        * [47mbooks/models/jvm/m1/expt.lisp[0m

        * [47mbooks/models/jvm/m1/alternating-sum.lisp[0m

        * [47mbooks/models/jvm/m1/alternating-sum-variant.lisp[0m

        * [47mbooks/models/jvm/m1/fib.lisp[0m

        * [47mbooks/models/jvm/m1/lessp.lisp[0m

        * [47mbooks/models/jvm/m1/even-solution-1.lisp[0m

        * [47mbooks/models/jvm/m1/even-solution-2.lisp[0m

        * [47mbooks/models/jvm/m1/sign.lisp[0m

    * the files below deal with two-loop programs in which the loops are
      nested.  The solutions use the same basic naming scheme as the
      template.

        * [47mbooks/models/jvm/m1/div.lisp[0m

        * [47mbooks/models/jvm/m1/bexpt.lisp[0m

    * [47mbooks/models/jvm/m1/m1-fact-on-neg-runs-forever.lisp[0m: we prove that
      if [47mn[0m is negative, the factorial program [47m*pi*[0m never reaches the
      halt.  This problem is probably not suitable for you to work
      out on your own.  But you can probably do others like it after
      understanding the proofs here.  We prove the theorem two
      different ways.  The first is a classic clock-style proof but
      the clock function decomposes an arbitrary natural number [47mk > 1[0m
      into the form 2 + 11 + 11 + ... + 11 + [47m(mod (- k 2) 11)[0m and
      then an inductive proof shows that the program never gets out
      of the loop --- and there's no [47mHALT[0m in the loop.  The second
      uses the inductive assertion style proof carried out directly
      by symbolic evaluation of the operational semantics and
      induction.  For an explanation of the use of inductive
      assertions with this style of operational semantics see
      [bib::moore03b].  That paper deals with the M5 machine (ACL2
      directory [47mbooks/models/jvm/m5/[0m) but is easily understood in the
      context of M1.

    * [47mbooks/models/jvm/m1/m1-half-via-inductive-assertions.lisp[0m: define a
      program that halves its natural number input and terminates iff
      the input was even.  Prove it.  This example is discussed in
      [bib::moore03b] as an M5 program.  It uses the inductive
      assertion method.

    * [47mbooks/models/jvm/m1/magic.lisp[0m illustrates the importance of
      termination.  It presents a program that just successively
      replaces the top of the stack by its successor, starting from
      [47m0[0m.  If you look at the state at the right moment, you can find
      any natural number you want on top of the stack.  So this
      program ``implements'' every natural valued function --- if
      terminating isn't a requirement!  In that sense, we prove this
      program implements fib and also implements factorial.  (Of
      course, we could also constrain a function to return a natural
      and prove that the program implements that function, but we
      don't bother.)

    * [47mbooks/models/jvm/m1/funny-fact.lisp[0m: this shows a two-loop program in
      which one loop follows another rather than being nested inside
      the other.  The first loop pushes successive naturals from [47mn[0m
      down to [47m1[0m onto the stack.  The second loop repeatedly
      multiplies the top two elements together.  Prove that
      implements factorial.  Note: this ``bytecode'' program violates
      a basic principle of the Java bytecode verifier, which insists
      that the stack is always the same length upon every arrival at
      every instruction.

    * [47mbooks/models/jvm/m1/wormhole-abstraction.lisp[0m: yet another proof of a
      factorial program, but it shows a way you can avoid explicitly
      specifying intermediate values you don't care about.  This idea
      was first demonstrated by Dave Greve of Collins Aerospace.

    * [47mbooks/models/jvm/m1/m1-with-stobj.lisp[0m: [47mM1[0m has been defined in a
      ``constructor'' style: every new state constructed as a list of
      four elements where all the elements are specified.  In more
      realistic machines, e.g., ACL2 directory
      [47mbooks/projects/x86isa/[0m, the state is a single-threaded object
      (see [stobj]) that is destructively modified to effect state
      changes.  This produces much more efficient runtime execution.
      However, it slightly changes the form of correctness proofs.
      In [47mm1-with-stobj.lisp[0m we define the M1 machine using a
      single-threaded object as the state.  Then, in

        * [47mbooks/models/jvm/m1/m1-with-stobj-clock-example.lisp[0m

      we implement multiplication by repeated additions (avoiding use of
      the [47mIMUL[0m instruction) on that version of M1 and prove it
      correct.

    * [47mbooks/models/jvm/m1/defsys.lisp[0m: a verifying compiler from a very
      simple ``Toy Lisp'' to [47mm1[0m.  Toy Lisp is just the subset of ACL2
      composed of variable symbols, quoted numeric constants, the
      function symbols [47m+[0m, [47m-[0m, [47m*[0m (primitively supported by M1), the
      form [47m(MV a1 ... an)[0m for returning multiple values, the form
      [47m(IFEQ a b c)[0m (which is just ACL2's [47m(if (equal a 0) b c)[0m), and
      calls of primitive and defined Toy Lisp functions.  The
      compiler takes a list of Toy Lisp ``modules,'' each of which
      specifies a symbolic name, formals, pre-conditions,
      post-conditions, and a Toy Lisp implementation.  An example
      module is

          (lessp :formals (x y)
                 :input (and (natp x)           ; pre-condition
                             (natp y))
                 :output (if (< x y) 1 0)       ; post-condition
                 :code (ifeq y                  ; Toy Lisp implementation
                             0
                             (ifeq x
                                   1
                                   (lessp (- x 1) (- y 1)))))

      The compiler implements a call/return protocol so that one Toy Lisp
      function can use another.  The compiler produces M1 code for
      each module.  In addition, it produces the clock function for
      each module and it generates events that prove that the M1 code
      implements input/output specification.  The result is an M1
      state poised to call the module [47mmain[0m on whatever arguments are
      on the [47mm1[0m [47mstack[0m. [31;1mWarning:[0m As of August, 2024, the comments in
      [47mdefsys.lisp[0m are out of date!

    * [47mbooks/models/jvm/m1/theorems-a-and-b.lisp[0m: a proof that M1 can
      compute anything a Turing machine can compute.  See the paper
      [bib::moore14].

    * The ACL2 file [47mbooks/projects/codewalker/README[0m describes a tool
      called ``codewalker.'' Codewalker is a utility for exploring
      code in any programming language specified by an ACL2
      operational model.  Three main facilities are provided: the
      abstraction of a piece of code into an ACL2 ``semantic
      function'' that returns the same machine state, the definition
      the ``clock function'' for the code, and the ``projection'' of
      the semantic function into another function that computes the
      final value of a given state component using only the values of
      the relevant initial state components.  No paper about
      codewalker is available.  But the first 50 pages of
      [47mcodewalker.lisp[0m is a comment providing documentation.  In
      addition, several examples are provided in other files.  For
      example, the ACL2 book [47mbooks/projects/codewalker/demo-fact.lisp[0m
      uses codewalker to verify an M1 factorial program.  By the way,
      the version of M1 used there is defined on the [47mcodewalker/[0m
      directory rather than the [47mbooks/models/jvm/m1/[0m directory to
      allow the two versions to drift apart.  The M1 used by the
      codewalker demo is defined in
      [47mbooks/projects/codewalker/m1-version-3.lisp[0m and it uses a
      single-threaded object (see [stobj]) representation of the
      state.


More Elaborate Models of the JVM: From M1 to M6

  M1 is only the start of a series of models of the JVM.  M1 lacks a
  bytecode verifier, method invocation, threads, and other features
  which are explored in the more elaborate models, all of which are
  found on the ACL2 directory [47mbooks/models/jvm/[0m.

    * The ACL2 directory [47mbooks/models/jvm/guard-verified-m1/[0m is another
      version of [47mm1[0m that differs in two ways.  First, instead of
      using the constructor style of creating new states (e.g., with
      [47m(list pc locals stack program)[0m) it uses a single-threaded
      object (see [stobj]).  This slightly changes the forms of
      correctness theorems and lemmas.  Second, the definition of [47mm1[0m
      on the [47mbooks/models/jvm/guard-verified-m1/[0m directory has been
      guard verified.  This involves attaching a guard to every
      ``[47mexecute[0m'' function and lifting that up to the level of the [47mm1[0m
      function.  The guards include the notion of a ``good state''
      which includes the notion of a well-formed program.  But that
      necessarily involves the requirement that, say, when every [47mIADD[0m
      instruction is encountered the stack has at least two numbers
      on it.  The [47mgood-statep[0m predicate is essentially a simple
      [3mbytecode verifier[0m for [47mm1[0m: it tells us that if a state is good
      (meaning, the program in it is good), then executing the
      program guarantees all the properties necessary for error-free
      execution.  Verifying the guards of this version of [47mm1[0m
      demonstrates ``verification of the bytecode verifier.'' The
      directory also contains the examples found in the unguarded
      version of [47mm1[0m on [47mbooks/models/jvm/m1[0m.  The reason we provide
      two functionally equivalent versions of [47mm1[0m is that when
      teaching how to use ACL2 to specify a machine operationally, it
      is easiest to start with the unguarded [47mm1[0m.

    * M2, on the ACL2 directory [47mbooks/models/jvm/m2/[0m is essentially M1 with
      method invocation (both static and virtual), return, and class
      instances including a demonstration of inheritance.  See
      [bib::moore99a].  In that paper the machine is named ``tjvm''
      for ``Toy JVM'' but its proper name is M2.  The paper and ACL2
      scripts illustrate how to reason about procedure call and
      return.

    * M5, on the ACL2 directory [47mbooks/models/jvm/m5/[0m is a closer
      approximation to the JVM.  M5 was written by George Porter, as
      an undergraduate project.  M5 supports 195 JVM instructions,
      including those for several kinds of arithmetic, arrays, and
      objects, threads and monitors.  The handling of integer
      arithmetic is accurate, e.g., all integers are bounded and
      addition, say, wraps around.  Floating point is not accurate
      and we regard it as a mere placeholder.  The directory contains
      proofs of properties for several M5 programs, including
      iterative and recursive ones (dealt with via clock-based
      proofs), some partial correctness proofs about programs that do
      not always terminate (dealt with via the inductive assertion
      method), and the correctness of an applicative insertion sort
      method (on Objects representing cons trees).  See [bib::mp02]
      and [bib::moore03a].  A proof of a mutual-exclusion property,
      called ``the Apprentice Challenge,'' is described in the papers
      and the corresponding books containing proofs are available on
      the [47mm5/[0m directory.

    * M6, on the ACL2 directory [47mbooks/models/jvm/m6/[0m is the best
      approximation to the JVM.  M6 was written as part of Hanbing
      Liu's PhD dissertation, supported by Sun Microsystems.  The M6
      state includes an ``external class table'' where classes reside
      until they are loaded.  M6 can execute most J2ME Java programs
      (except those with significant I/O or floating-point).  It was
      primarily designed to model dynamic class loading, class
      initialization, and bytecode verification.  The entire Sun CLDC
      API library (672 methods in 87 classes) was translated into the
      external representation and is available for loading,
      constituting about 500 pages of data.  The model included 21
      out of 41 native APIs that appeared in Sun's CLDC API library.
      The M6 description itself is about 160 pages of ACL2.  See
      [bib::liu06].


Quick Index to Related Topics

    * [operational-semantics]

    * operational-semantics-1__simple-example --- current topic

    * [operational-semantics-2__other-examples]

    * [operational-semantics-3__annotated-bibliography]

    * [operational-semantics-4__how-to-find-things]

    * [operational-semantics-5__history-etc]")
 (OPERATIONAL-SEMANTICS-2__OTHER-EXAMPLES
  (OPERATIONAL-SEMANTICS)
  "Examples of other models and proof techniques

  The topic [operational-semantics-1__simple-example] deals with a
  simple machine, M1, and focuses on the ``clock''-based proof style.
  In this section we point to other machine models, different ACL2
  proof styles, and tools in the ACL2 Community Books that may be of
  interest.

  We limit our discussion here to operational semantics.  But it is
  worth noting that a valuable way to explore the diversity of ACL2
  applications and extensions is to browse the ACL2 Workshop series.
  See the ``ACL2 Workshops, UT Seminar, and Course Materials'' link
  on the {ACL2 homepage |
  http://www.cs.utexas.edu/users/moore/acl2/}.  Then visit the
  Program for each workshop.  Many of the papers include supplemental
  material in the form of ACL2 proof scripts are in the ACL2
  Community Books regression suite and thus available locally if
  you've installed ACL2.  They're under the directory
  [47mbooks/workshops/[0m, which is organized by the year of the workshop
  and the name of the author(s), e.g.,
  [47mbooks/workshops/2023/passmore/[0m.


Other Machines

  As noted in [operational-semantics-5__history-etc], a ``handheld
  calculator'' was formalized in Chapter 17 [bib::bm79], using the
  precursor to Nqthm.  That machine was essentially M1 without the
  branch or jump instructions.  That is, all programs were just
  straightline sequences of stack-based arithmetic operations.  The
  Bendix 930 flight control computer discussed in [bib::bm80] was a
  more traditional von Neumann machine, also modeled in the precursor
  to Nqthm.  The 30 page model is listed in Section 15 of
  [bib::bm80].

  The Computational Logic, Inc. (CLI) Verified Stack was formalized and
  verified with Nqthm.  The CLI Verified Stack was a
  hardware-software stack consisting of a gate-level description of a
  microprocessor, its instruction set architecture, an
  assembler/linker/loader for a stack based assembly language with
  subroutine call and return, a compiler for a simple subset of a
  Pascal-like language, a simple operating system kernel, and some
  applications programs.  Each component of the stack was verified
  with respect to the component immediately below in such a way that
  the correctness theorems could be composed.  The result was that if
  a program in the high-level language was verified (with respect to
  the operational semantics of the high-level language) then
  compiling, assembling, linking, and loading the binary image onto
  the gate-level machine and running it would, with mathematical
  certainty, deliver the results verified at the high level.  The
  stack was described in the 1989 special issue of the [3mJournal of
  Automated Reasoning[0m, [bib::bhmy89].  In 1992, a hardware
  description language was formalized and another microprocessor was
  described and verified to implement a slightly different machine
  code.  That microprocessor was fabricated, the
  assembler/linker/loader was retargeted to the new machine code and
  verified, so that the entire stack was then ported to a fabricated
  microprocessor.  A second compiler (for a Lisp subset) and a
  game-playing applications program were also written and verified.
  The CLI Stack was a project by Bill Bevier, Bishop Brock, Art
  Flatau, Warren A. Hunt, Jr., Matt Kaufmann, J Moore, Matt Wilding,
  and Bill Young, of Computational Logic, Inc.

  The CLI Verified Stack convinced us that this style of operational
  semantics was viable not just for program verification but for
  stacking and relating machines.  For more details, including
  papers, books, dissertations, and proof scripts, start at the
  annotation for [bib::bhmy89] and visit the citations.

  [3m[Personal aside by Moore: I believe the CLI Verified Stack to be a
  seminal achievement in formal methods.][0m

  The most elaborate machine model created with Nqthm was of the
  Motorola MC68020, modeled by Yuan Yu [bib::yu92].  He and Boyer
  used that model to verify many MC68020 machine code programs
  produced by a variety of standard compilers.  Perhaps most notably
  they verified the machine code for Hoare's Quick Sort and 21 of the
  22 functions in the Berkeley Unix C string library (as compiled
  with [47mgcc -o[0m).  For a shorter description of the work, see
  [bib::by96].

  Of course, state machines are not limited to modeling computational
  engines.  See [bib::bgm90] for a real-time control problem
  formalized with a ``clocked'' state machine where the ``clock''
  specifies the change in the physical environment at each sampling
  cycle.  In addition, games can often be formalized with state
  machines where the ``clock'' specifies opponents' moves.
  Strategies can be analyzed via proof.  See the Nqthm script
  analyzing the game of Tic Tac Toe,
  [47mexamples/basic/tic-tac-toe.events[0m or [bib::wilding93] for a
  description of the verification of a winning strategy for the game
  of Nim.  See the ACL2 scripts for playing Towers of Hanoi,
  [Tutorial1-Towers-of-Hanoi], [47mbooks/misc/hanoi.lisp[0m, and the Bottle
  Game (played in the 1995 movie [3mDie Hard 2[0m),
  [47mbooks/projects/die-hard-bottle-game/top.lisp[0m.

  But for the rest of this discussion we focus on modeling and proving
  properties of compute engines with ACL2.

  The first major external applications of ACL2 after it was developed
  at Computational Logic, Inc., were at Motorola Government Systems,
  in Scottsdale, Arizona, between 1993 and 1997, and at Advanced
  Micro Devices, Inc. (AMD), in Austin, Texas, in 1995.  Only the
  first of these two projects employed operational semantics --- and
  it was a [3mtour de force[0m.

  A CLI employee, Bishop Brock, relocated to Scottsdale and embedded
  with a design group there to formalize the evolving design of the
  Motorola ``Complex Arithmetic Processor'' (CAP) digital signal
  processor (DSP), using the operational semantic techniques
  developed with Nqthm and described above.  A timeline of the entire
  ACL2 part of the CAP DSP project may be found in [bib::bkm96].

  Here is a brief description of the CAP design taken from Section 2.1
  of [bib::bkm96].

      The CAP design follows the `Harvard architecture', i.e., there are
      separate program and data memories.  The design includes 252
      programmer-visible data and control registers.  There are six
      independently addressable data and parameter memories.  The
      data memories are logically partitioned into `source' and
      `destination' memories; the sense of the memories may be
      switched under program control.  The arithmetic unit includes
      four multiplier-accumulators and a 6-adder array.  The CAP
      executes a 64-bit instruction word, which in the arithmetic
      units is further decoded into a 317-bit, low-level control
      word.  The instruction set includes no-overhead looping
      constructs and automatic data scaling.  As many as 10 different
      registers are involved in the determination of the next program
      counter.  A single instruction can simultaneously modify well
      over 100 registers.  In practice, instructions found in typical
      applications simultaneously modify several dozen registers.
      Finally, the CAP has a three-stage instruction pipeline which
      contains many programmer-visible pipeline hazards.

  Brock, with help from Warren Hunt, J Moore, and Matt Kaufmann,
  developed a bit- and cycle-accurate model of the CAP design.  We
  believe this was the first time an entire commercial microprocessor
  was formally specified, see [bib::bh99].

  Brock validated the design by running the ACL2 model against
  Motorola's SPW engineering model of the processor.  For example, he
  compared the results of executing an end-to-end application (a QPSK
  modem) on both the SPW model and the ACL2 model and found the final
  states bit-exact for all programmer visible registers.

  Before turning to the verification of CAP applications programs Brock
  undertook the logical elimination of the CAP pipeline.  He defined
  a predicate that syntactically detected pipeline hazards in
  microcode and he implemented a simpler ACL2 machine model without
  the pipeline.  Then, following Burch and Dill's method of comparing
  states after flushing the pipeline via symbolic evaluation, he
  proved with ACL2 that the two models were equivalent [3mprovided the
  microcode was hazard free[0m.

  Then Brock, [3met al[0m, proved several microcode programs correct, again
  following the proof methodology we sketched in section ``Proving
  Theorems about M1 Programs'' of
  [47moperational-semantics-1__simple-example[0m, where the main subtasks
  were our so-called Steps 2 and 3: verify that the execution of the
  pipeline-free model on hazard-free microcode implements semantic
  function of the program, and then verify that the semantic function
  implements the more abstract specification.  An example of the
  second (generally harder) step is described in [bib::bm05]. These
  two results could then be chained together, along with the
  verification (by execution) that the hazard predicate detected no
  hazards in the microcode and the proof of the equivalence (modulo
  the absence of hazards) of the pipelined and non-pipelined models,
  to conclude that the microcode runs correctly on the pipelined
  model.

  It is noteworthy that ACL2 executed the pipeline-free microcode
  interpreter several times faster than the hardware simulator could
  execute the SPW model --- with assurance that the answers were
  equivalent to the pipelined model on hazard-free microcode.  In
  addition, the ACL2 hazard predicate, being an executable ACL2
  function on microcode programs, 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
  [bib::bh99].  This can be considered another practical application
  of formal methods since the hazard detection predicate was formally
  verified to be a sufficient condition for the pipelined and
  non-pipelined machines to be equivalent.

  Unfortunately, Motorola canceled the entire CAP effort before the
  device was fabricated, despite the success of the formal methods
  component of the project. The ACL2 proof scripts are not in the
  ACL2 Community Books regression suite.

  We now move on to other operational models.  In
  [operational-semantics-1__simple-example] (and on the ACL2
  directory [47mbooks/models/jvm/m1/[0m) we describe a very simple
  operational definition of a machine, called M1, supporting a little
  stack-based arithmetic and some branch instructions.  That machine
  was used to teach students how to formalize machines and verify
  their programs.  M1 was the beginning of an evolutionary sequence
  of machines approximating an accurate model of the Java Virtual
  Machine.  The machines in that evolutionary sequence show how we
  can formalize and reason about method invocation (virtual and
  static), return, object creation including inheritance, threads,
  dynamic class loading, and bytecode verification.  The machines are
  described, with appropriate citations to papers and ACL2 books, in
  the final section of [operational-semantics-1__simple-example].

  The use of the inductive assertion method with an operational
  semantics of this style is quite interesting.  As noted in
  [bib::mmrv06], no other tools are required beyond the operational
  semantics and a theorem prover.  It is possible for the theorem
  prover to use the operational semantics directly to generate and
  prove the ``verification conditions'' one gets by exploring all
  possible program paths between assertions in the code.  One can use
  the method to prove either partial or total correctness, the former
  meaning ``correct if it terminates'' and the latter meaning
  ``terminating and correct at termination.''

  The most complicated machine formalized (as of 2024) with ACL2 is the
  x86 instruction set architecture.  The model evolved from simpler
  models, exploiting lessons learned from earlier Nqthm and ACL2
  work.  In the case of x86, the ``toy'' was the y86 as informally
  described in [bib::boh03].  The ACL2 directory [47mbooks/models/y86/[0m
  contains several models of the 32-bit y86 described in the First
  Edition of [bib::boh03].  In particular, see the ACL2 book
  [47mbooks/models/y86/y86-basic/y86/y86.lisp[0m, by Warren Hunt, for the
  model.  For a proof of correctness of Sean Anderson's bit twiddling
  ``population count'' in y86 machine code, see the ACL2 book
  [47mbooks/models/y86/y86-basic/py86/popcount.lisp[0m.  The proof of that
  particular straightline piece of code is just by symbolic
  evaluation and the ACL2 verified ``bit-blasting'' solver [gl] by
  Sol Swords.

  From the y86, the model of the x86 evolved through several iterations
  reported in [bib::hk12], [bib::ghk13], and [bib::ghkg14], to Shilpi
  Goel's monumental x86 model [bib::goel16] and [bib::ghk17].  The
  model specifies over 400 x86 instructions and the model includes
  architectural features like segmentation and paging.  It can be
  executed in either of two modes. When running in the
  application-program level, it executes about 3.3 million x86
  instructions per second.  When running in the system-level mode it
  executes about 912,000 x86 instructions per second.  The model has
  been validated extensively against actual x86 hardware, which is
  the reason so much attention has been paid to execution efficiency.
  X86 machine code programs have been verified.  See [bib::goel16]
  and [bib::ghk17].


Proof Methods and Tools

  The paper [bib::moore99b] shows how we can reason about a system
  involving multiple processes interacting with a shared memory.  The
  paper describes two operational models, one in which the model
  switches between multiple processes according to an ``oracle'' and
  the other which models just a single process but in which the
  memory changes ``spontaneously.'' The two models are then related
  by proved lemmas so that one can switch back and forth between
  views.  The lemmas are used to verify a safety property (using one
  model) and a progress property (using the other).  All the proofs
  are carried out via the clock-based methodology.

  We have focused on the clock-based proof methodology.  But an
  advantage of creating ``toy'' models is that it is easy to explore
  other proof methodologies and then try to apply them to larger
  models.

  The papers [bib::rm04] and [bib::rhmm07] establish that the
  clock-function approach to verification is equivalent to the use of
  inductive assertions and to stepwise invariants.  In fact, ACL2
  tools are provided for converting between clock-based proofs and
  inductive assertion-style proofs.

  The paper [bib::sawada00] describes the modeling and verification of
  a pipelined machine.  The paper [bib::manolios00] shows an
  alternative method based on Well-founded Equivalence Bisimulations.
  Briefly, it introduces a notion of correctness that implies that
  the instruction set architecture and micro-architecture machines
  have the same observable infinite paths, up to stuttering.

  The paper [bib::sh98] deals with a machine with precise exceptions
  and speculative execution.

  An ACL2 tool to help manage states in operational models is described
  in [bib::moore15] and a tool for determining whether two symbolic
  terms representing machine addresses may be equal is described in
  [bib::moore17].  These tools are available among the ACL2 Community
  Books.  A tool for deriving the meaning of and clock function for a
  piece of code from the code and the operational semantics model is
  described in the ACL2 file [47mbooks/projects/codewalker/README[0m.


Quick Index to Related Topics

    * [operational-semantics]

    * [operational-semantics-1__simple-example]

    * operational-semantics-2__other-examples --- current topic

    * [operational-semantics-3__annotated-bibliography]

    * [operational-semantics-4__how-to-find-things]

    * [operational-semantics-5__history-etc]")
 (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY
  (OPERATIONAL-SEMANTICS)
  "Annotated bibliography for operational-semantics

  This topic provides proper bibliographic citations to the work
  mentioned in the ACL2 documentation topic [operational-semantics]
  and its subtopics.  Each citation (e.g., [bib::bhmy89]) is a link,
  at which you may find additional information about the publication
  and its relation to operational semantics.  When Nqthm or ACL2
  files are mentioned you will have to dereference those names
  following the instructions in
  [operational-semantics-4__how-to-find-things].


Quick Index to Related Topics

    * [operational-semantics]

    * [operational-semantics-1__simple-example]

    * [operational-semantics-2__other-examples]

    * operational-semantics-3__annotated-bibliography --- current topic

    * [operational-semantics-4__how-to-find-things]

    * [operational-semantics-5__history-etc]


Subtopics

  [Bib::bevier87]
      W. R. Bevier, [3mVerified Operating System Kernel[0m
      [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/bevier.pdf)[0m, University
      of Texas at Austin, Ph.D. dissertation, 1987.
      [31;1mRelevance:[0m first verified operating system and a component of the CLI
      stack

  [Bib::bgm90]
      R. S. Boyer, M. W. Green, and J S. Moore, ``{The Use of a Formal
      Simulator to Verify a Simple Real Time Control Program |
      http://www.cs.utexas.edu/users/moore/publications/controller.pdf}'',
      in W.H.J. Feijen, A.J.M. van Gasteren, D. Gries, and J. Misra,
      editors, [3mBeauty is Our Business: A Birthday Salute to Edsger W.
      Dijkstra[0m, Springer-Verlag Texts and Monographs in Computer
      Science, pp. 54-66, 1990.
      [31;1mRelevance:[0m operational semantics modeling a hybrid physical/digital
      system

  [Bib::bh97]
      B. Brock and W. A. Hunt, Jr., ``{Formally Specifying and
      Mechanically Verifying Programs for the Motorola Complex
      Arithmetic Processor DSP |
      https://ieeexplore.ieee.org/document/628846}'', in [3m1997 IEEE
      International Conference on Computer Design[0m, IEEE Computer
      Society, pp. 31-36, October, 1997.
      [31;1mRelevance:[0m first public announcement of the CAP DSP formalization
      (this short article was superseded by [bib::bh99])

  [Bib::bh99]
      B. Brock and W. A. Hunt, Jr., ``{Formal Analysis of the Motorola CAP
      DSP'' |
      https://link.springer.com/chapter/10.1007/978-1-4471-0523-7_5#citeas},
      in M. Hinchey and J. Bowen, editors, [3mIndustrial-Strength Formal
      Methods[0m, Springer-Verlag, pp. 81-115, 1999.
      [31;1mRelevance:[0m first industrial application of operational semantics with
      ACL2 and the first complete formal specification of a
      commercially designed microprocessor

  [Bib::bhmy89]
      W.R. Bevier, W.A. Hunt, Jr., J S. Moore, and W.D. Young, [3mSpecial
      Issue on System Verification[0m, [3mJournal of Automated Reasoning[0m,
      [31;1m5[0m(4), pp. 409-530, 1989.
      [31;1mRelevance:[0m Computational Logic Inc. (CLI) Verified Stack --- a
      seminal achievement in formal methods and operational semantics

  [Bib::bkm96]
      B. Brock, M. Kaufmann, and J S. Moore, ``{ACL2 Theorems about
      Commercial Microprocessors |
      http://www.cs.utexas.edu/users/moore/publications/bkm96.pdf}'',
      in M. Srivas and A. Camilleri, editors, [3mFormal Methods in
      Computer-Aided Design (FMCAD'96)[0m, Springer-Verlag, LNCS [31;1m1166[0m,
      pp. 275-293, doi 10.1007/BFb0031816, 1996.
      [31;1mRelevance:[0m early (mid-1990s) applications of ACL2 in industry
      (Motorola CAP DSP via operational semantics and the AMD K5 FDIV
      via a shallow embedding)

  [Bib::bm05]
      B. Brock and J S. Moore, ``{A Mechanically Checked Proof of a
      Comparator Sort Algorithm |
      https://www.cs.utexas.edu/~moore/publications/csort/main.pdf}'',
      in M. Broy, J. Gruenbauer, D. Harel, and C. A. R. Hoare,
      editors, [3mEngineering Theories of Software Intensive Systems[0m,
      Springer NATO Science Series II, [31;1m195[0m, pp. 141-175, 2005.
      [31;1mRelevance:[0m an example of proving that the state transformation
      effected by running a CAP model on commercial microcode
      implements the high level specification

  [Bib::bm73]
      R. S. Boyer and J S. Moore, ``{Proving Theorems about LISP Functions
      |
      https://www.cs.utexas.edu/~moore/publications/bm-ijcai-73.pdf}'',
      in [3mProceedings of the Third International Joint Conference on
      Artificial Intelligence (IJCAI)[0m, Stanford University, pp.
      486-493, 1973.
      [31;1mRelevance:[0m journal article about the Edinburgh Pure Lisp Theorem
      Prover (PLTP)

  [Bib::bm79]
      R. S. Boyer and J S. Moore, [3m{A Computational Logic |
      https://archive.org/details/acl_20240626}[0m, Academic Press,
      1979.
      [31;1mRelevance:[0m implementation details of the prover that became Nqthm

  [Bib::bm80]
      R. S. Boyer and J S. Moore, ``{On Why It Is Impossible to Prove that
      the BDX930 Dispatcher Implements a Time-Sharing System |
      https://www.cs.utexas.edu/~moore/publications/BDX930-Report-1978-81.pdf}'',
      in Sections 14 and 15 of P.M. Melliar-Smith, K. Levitt, R.
      Schwartz, R. Boyer, J Moore, D. Hare, R. Shostak, M. Moriconi,
      M. Green, and W.D. Elliot, [3mInvestigation, Development, and
      Evaluation of Performance Proving for Fault-Tolerant Computer
      Final Report, covering the period September 1978 to June 1982[0m,
      SRI, July 1982.
      [31;1mRelevance:[0m operational semantic model of (a fragment) of a 1970s
      flight control computer

  [Bib::bm96]
      R. S. Boyer and J S. Moore, ``{Mechanized Formal Reasoning about
      Programs and Computing Machines |
      https://www.cs.utexas.edu/~moore/publications/bm96.pdf}'', in
      R. Veroff, editor, [3mAutomated Reasoning and Its Applications:
      Essays in Honor of Larry Wos[0m, MIT Press, 1966.
      [31;1mRelevance:[0m the basic Nqthm/ACL2 style of operational semantics as a
      book chapter

  [Bib::bm97]
      R. S. Boyer and J S. Moore, [3m{ A Computational Logic Handbook, Second
      Edition |
      https://drive.google.com/file/d/0B2yFYLn0Spf1TloxMjNxdzBWN1E/}[0m,
      Academic Press, New York, 1997.
      [31;1mRelevance:[0m Nqthm user's manual

  [Bib::boh03]
      R. E. Bryant and D. R. O'Hallaron, [3mComputer Systems: A Programmer's
      Perspective[0m, Prentice-Hall. First edition 2003, second edition
      2011, third edition 2015.
      [31;1mRelevance:[0mone of the most popular and influential textbooks on modern
      computer systems; its relevance here is that the book
      introduced the y86.

  [Bib::by96]
      R. S. Boyer and Y. Yu, ``{Automated Proofs of Object Code for a
      Widely Used Microprocessor |
      https://dl.acm.org/doi/10.1145/227595.227603}'', [3mJournal of the
      ACM[0m [31;1m43[0m(1), pp. 166-192, January, 1996.
      [31;1mRelevance:[0m operational model of the Motorola 68020 and verification
      of object code generated by commercial compilers

  [Bib::flatau92]
      A. D. Flatau [3mA verified implementation of an applicative language
      with dynamic storage allocation[0m
      [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/flatau.pdf)[0m, University
      of Texas at Austin, Ph.D. dissertation, 1992 (minus some
      appendices).
      [31;1mRelevance:[0m a second verified compiler hosted on the CLI Verified
      Stack

  [Bib::ghk13]
      S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Abstract Stobjs and
      Their Application to ISA Modeling |
      http://eptcs.org/content.cgi?ACL22013}'', in R. Gamboa and J.
      Davis, editors, [3mProceedings of ACL2 Workshop 2013[0m, Electronic
      Proceedings in Theoretical Computer Science, Volume 114, pp.
      54-69, 2013.
      [31;1mRelevance:[0m an ACL2 feature introduced to support operational semantic
      models

  [Bib::ghk17]
      S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Engineering a Formal,
      Executable x86 ISA Simulator for Software Verification |
      https://link.springer.com/chapter/10.1007/978-3-319-48628-4_8}'',
      in M. Hinchey, J. P. Bowen, and E.-R. Olderog, editors,
      [3mProvably Correct Systems[0m Springer, pp. 173-209, 2017.
      [31;1mRelevance:[0m operational model of the x86 at both the user- and
      system-level and code proofs

  [Bib::ghkg14]
      S. Goel, W. A. Hunt, Jr., M. Kaufmann, and S. Ghosh, ``{Simulation
      and Formal Verification of x86 Machine-Code Programs that Make
      System Calls |
      http://www.cs.utexas.edu/users/hunt/FMCAD/FMCAD14/proceedings/18_goel.pdf}'',
      in [3mProceedings of Formal Methods in Computer-Aided Design
      (FMCAD'14)[0m, pp. 91-98, 2014.
      [31;1mRelevance:[0m modeling and verifying machine-code programs that exhibit
      non-determinism

  [Bib::goel16]
      S. Goel, [3m{Formal Verification of Application and System Programs
      Based on a Validated x86 ISA Model |
      https://repositories.lib.utexas.edu/server/api/core/bitstreams/858b2f9b-5532-4b2a-bed1-fb889a265f6c/content}[0m,
      University of Texas at Austin, Ph.D. dissertation, 2016.
      [31;1mRelevance:[0m details of the x86 model

  [Bib::hb92]
      W. A. Hunt, Jr. and B. Brock, ``{A Formal HDL and its use in the
      FM9001 Verification |
      https://royalsocietypublishing.org/doi/abs/10.1098/rsta.1992.0024}'',
      [3mProceedings of the Royal Society[0m, North Holland, April, 1992.
      [31;1mRelevance:[0m a formalized hardware description language and the
      verification of a fabricated microprocessor described with it;
      this describes three foundational achievements in formal
      methods

  [Bib::hk12]
      W. A. Hunt, Jr. and M. Kaufmann, ``{Towards a Formal Model of the
      x86 ISA |
      http://apps.cs.utexas.edu/tech_reports/reports/tr/TR-2075.pdf}'',
      University of Texas at Austin, Computer Science Department
      Technical Report TR-12-07, May, 2012.
      [31;1mRelevance:[0m a ``toy model'' of the x86, built as a warm up exercise

  [Bib::hkms17]
      W. A. Hunt, Jr., M. Kaufmann, J S. Moore, and A. Slobodova,
      ``{Industrial hardware and software verification with ACL2 |
      https://royalsocietypublishing.org/doi/10.1098/rsta.2015.0399}''
      in P. Gardner, P. O'Hearn, M. Gordon, G. Morrisett and F. B.
      Schneider, editors), [3mVerified Trustworthy Software Systems[0m,
      Philosophical Transactions A, Royal Society Publishing, [31;1m374[0m,
      DOI 10.1098/rsta.2015.0399, September, 2017.
      [31;1mRelevance:[0m how ACL2 is used in industry, and why

  [Bib::hunt85]
      W. A. Hunt, Jr., [3mFM8501: A Verified Microprocessor[0m, University of
      Texas at Austin, Ph.D. dissertation, 1985 (also published as a
      book of the same title, Springer-Verlag LNAI 795, Heidelberg,
      1994.
      [31;1mRelevance:[0m first microprocessor verified at the gate level and the
      bottommost component of the CLI stack

  [Bib::kmm00a]
      M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning: An
      Approach |
      https://www.cs.utexas.edu/~moore/publications/acl2-books/car/index.html}[0m,
      Kluwer Academic Publishers, 2000.
      [31;1mRelevance:[0m introduction to ACL2

  [Bib::kmm00b]
      M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning:
      ACL2 Case Studies |
      https://www.cs.utexas.edu/~moore/publications/acl2-books/acs/index.html}[0m,
      Kluwer Academic Publishers, 2000.
      [31;1mRelevance:[0m tutorial examples of ACL2 applications

  [Bib::liu06]
      H. Liu, [3m{Formal Specification and Verification of a JVM and its
      Bytecode Verifier |
      https://www.cs.utexas.edu/~moore/publications/liu-dissertation.pdf}[0m,
      University of Texas at Austin, Ph.D. dissertation, 2006
      [31;1mRelevance:[0m most complete ACL2 model of the JVM

  [Bib::manolios00]
      P. Manolios, ``{Correctness of Pipelined Machines |
      https://dl.acm.org/doi/10.5555/646186.683220}'', in W. A. Hunt,
      Jr and S. D. Johnson, editors, [3mFormal Methods in Computer-Aided
      Design (FMCAD 2000)[0m, Springer-Verlag LNCS [31;1m1954[0m, Heidelberg, pp.
      161-178, 2000.
      [31;1mRelevance:[0m an alternative approach to verifying operational models of
      a pipelined machine

  [Bib::mccarthy62]
      J. McCarthy, ``{Towards a mathematical science of computation |
      http://jmc.stanford.edu/articles/towards/towards.pdf},''
      [3mProceedings of the Information Processing Cong. 62[0m,
      North-Holland, Munich, West Germany, pp. 21-28, August, 1962.
      [31;1mRelevance:[0m a seminal paper in the history of formal operational
      semantics

  [Bib::mmrv06]
      J. Matthews, J S. Moore, S. Ray and D. Vroon, ``{ Verification
      Condition Generation via Theorem Proving |
      http://ece.ufl.edu/wp-content/uploads/sites/119/publications/lpar06.pdf}'',
      in [3mProceedings of 13th International Conference on Logic for
      Programming, Artificial Intelligence, and Reasoning (LPAR
      2006)[0m, LNCS [31;1m4246[0m, pp. 362-376, 2006.
      [31;1mRelevance:[0m how to conduct inductive assertion-style proofs from an
      operational semantics without a verification condition
      generator

  [Bib::moore03a]
      J S. Moore, ``{Proving Theorems about Java and the JVM with ACL2 |
      https://www.cs.utexas.edu/~moore/publications/marktoberdorf-02/main_final.pdf}'',
      in M. Broy and M. Pizka, editors, [3mModels, Algebras and Logic of
      Engineering Software[0m, IOS Press, Amsterdam, pp. 227-290, 2003.
      [31;1mRelevance:[0m M5: a JVM model with method invocation, classes, and
      threads, with some example proofs including about
      mutual-exclusion

  [Bib::moore03b]
      J S. Moore, ``{ Inductive Assertions and Operational Semantics |
      https://www.cs.utexas.edu/~moore/publications/trecia/long.pdf}'',
      in D. Geist, editor, CHARME 2003,, Springer Verlag, LNCS [31;1m2860[0m,
      pp. 289-303, 2003.
      [31;1mRelevance:[0mThe URL above points to a longer version of the paper
      presented at CHARME.  Using a subset of M5 the paper shows how
      partial symbolic evaluation of a program can be used to
      generate and prove verification conditions produced from
      inductive assertions

  [Bib::moore14]
      J S. Moore, ``{ Proof Pearl: Proving a Simple Von Neumann Machine
      Turing Complete |
      https://www.cs.utexas.edu/~moore/publications/m1-is-turing-equiv.pdf}''
      in G. Klein and R. Gamboa, editors, [3mInteractive Theorem
      Proving, ITP 2014[0m, Springer LNCS [31;1m8558[0m,
      doi.org/10.1007/978-3-319-08970-6_26, 2014.
      [31;1mRelevance:[0mM1 can compute anything a Turing machine can.  (The paper
      ought to be re-titled ``Proving M1 Turing Equivalent.'')

  [Bib::moore15]
      J S. Moore, ``{ Stateman: Using Metafunctions to Manage Large Terms
      Representing Machine States |
      https://www.cs.utexas.edu/~moore/publications/stateman.pdf},''
      in M. Kaufmann and D. Rager, editors, [3mProceedings of the 13th
      International Workshop on the ACL2 Theorem Prover[0m, EPTCS, [31;1m192[0m,
      pp. 93-109, 2015.
      [31;1mRelevance:[0m some ACL2 tools for managing the terms representing states
      of operational models

  [Bib::moore17]
      J S. Moore, ``{ Computing Verified Machine Address Bounds during
      Symbolic Exploration of Code |
      https://www.cs.utexas.edu/~moore/publications/ainni.pdf},'' in
      J. Bowen, H. Langmaack and E.-R. Olderog, editors, [3mProvably
      Correct Systems[0m, Springer, pp. 151-172, 2017.
      [31;1mRelevance:[0m an ACL2 tool for determining whether two symbolic machine
      addresses may be equal

  [Bib::moore19]
      J S. Moore, ``{Milestones from The Pure Lisp Theorem Prover to ACL2
      | https://doi.org/10.1007/s00165-019-00490-3}'', [3mFormal Aspects
      of Computing[0m, Springer, DOI
      https://doi.org/10.1007/s00165-019-00490-3, 2019.
      [31;1mRelevance:[0m how the Edinburgh Pure Lisp Theorem Prover (PLTP) evolved
      into ACL2

  [Bib::moore73]
      J S. Moore, ``{Computational Logic: Structure Sharing and Proof of
      Program Properties |
      http://www.era.lib.ed.ac.uk/handle/1842/2245}, University of
      Edinburgh, Ph.D. dissertation, 1973.
      [31;1mRelevance:[0m details of the Edinburgh Pure Lisp Theorem Prover (PLTP)

  [Bib::moore96]
      J S. Moore, [3mPiton: A Mechanically Verified Assembly-Level Language[0m,
      J S. Moore, Automated Reasoning Series, Kluwer Academic
      Publishers, 1996.
      [31;1mRelevance:[0m verified assembler/linker/loader and a component of the
      CLI Verified Stack

  [Bib::moore99a]
      J S. Moore, ``{Proving Theorems about Java-like Byte Code |
      https://www.cs.utexas.edu/~moore/publications/tjvm/main.pdf},''
      in E.-R. Olderog and B. Steffen, editors, [3mCorrect System Design
      -- Recent Insights and Advances[0m, LNCS [31;1m1710[0m, pp. 139-162, 1999.
      [31;1mRelevance:[0m M2: a JVM model similar to M1 but with method invocation
      (i.e., subroutine call)

  [Bib::moore99b]
      J S. Moore, ``{A Mechanically Checked Proof of a Multiprocessor
      Result via a Uniprocessor View |
      https://www.cs.utexas.edu/~moore/publications/multi-v-uni.pdf}'',
      J S. Moore, [3mFormal Methods in System Design[0m, [31;1m14[0m(2), pp.
      213-228, March, 1999.
      [31;1mRelevance:[0m proving a relationship between two state machines

  [Bib::mp02]
      J S. Moore and G. Porter, ``{The Apprentice Challenge |
      https://www.cs.utexas.edu/~moore/publications/m5/apprentice.pdf}'',
      [3mACM TOPLAS[0m, [31;1m24[0m(3), pp. 1-24, May, 2002.
      [31;1mRelevance:[0m M5 and mutual-exclusion via monitors: an unbounded number
      of JVM threads competing for access to a shared resource

  [Bib::mp67]
      J. McCarthy and J. Painter, ``{Correctness of a Compiler for
      Arithmetic Expressions |
      http://jmc.stanford.edu/articles/mcpain/mcpain.pdf}'',
      [3mProceedings of Symposia in Applied Mathematics[0m, [31;1m19[0m, American
      Mathematical Society, 1967.
      [31;1mRelevance:[0m an early (perhaps the first) compiler proof

  [Bib::plotkin04a]
      G. D. Plotkin, ``{ A Structural Approach to Operational Semantics |
      https://homepages.inf.ed.ac.uk/gdp/publications/sos_jlap.pdf}'',
      Computer Science Department, Aarhus University, Denmark, DAIMI
      FN-19, 1981 (reprised in a 2004 submission to the [3mThe Journal
      of Logic and Algebraic Programming[0m).
      [31;1mRelevance:[0m Plotkin's introduction of the term ``structural
      operational semantics''

  [Bib::plotkin04b]
      G. D. Plotkin, ``{ The origins of structural operational semantics |
      https://www.sciencedirect.com/science/article/pii/S1567832604000268}'',
      [3mThe Journal of Logic and Algebraic Programming[0m, [31;1m60[0m and [31;1m61[0m, pp.
      3-15, July and December 2004.
      [31;1mRelevance:[0m an interesting historical account of the most popular
      (non-ACL2) approach to operational semantics

  [Bib::rhmm07]
      S. Ray, W. A. Hunt, Jr., J. Matthews, and J S. Moore, `{A Mechanical
      Analysis of Program Verification Strategies |
      https://link.springer.com/article/10.1007/s10817-008-9098-1},''
      [3mJournal of Automated Reasoning[0m, [31;1m40[0m(4), pp. 245-269, May, 2008.
      [31;1mRelevance:[0m stepwise invariants, clock functions, and inductive
      assertion proof styles are all equivalent

  [Bib::rm04]
      S. Ray and J S. Moore, ``{Proof Styles in Operational Semantics |
      https://www.ece.ufl.edu/wp-content/uploads/sites/119/publications/fmcad04.pdf},''
      in A. J. Hu and A. K. Martin, editors, [3mFormal Methods in
      Computer-Aided Design (FMCAD-2004)[0m, Springer, LNCS [31;1m3312[0m, pp.
      67-81, 2004.
      [31;1mRelevance:[0m ACL2 tools for transforming inductive assertion-style
      proofs to clock function style and vice versa

  [Bib::sawada00]
      J. Sawada, ``Verification of a Simple Pipelined Machine Model,'' in
      M. Kaufmann, P. Manolios, J S. Moore, editors, [3mComputer-Aided
      Reasoning: ACL2 Case Studies[0m, Kluwer Academic Publishers,
      Chapter 9, pp. 137-150, 2000. (See also {ACL2 books |
      https://www.cs.utexas.edu/~moore/publications/acl2-papers.html#Books}).
      [31;1mRelevance:[0m operational model of a pipelined machine and its
      verification

  [Bib::sh98]
      J. Sawada and W. A. Hunt, Jr, ``{Processor Verification with Precise
      Exceptions and Speculative Execution |
      https://link.springer.com/chapter/10.1007/BFb0028740}'', in A.
      J. Hu and M. Y. Vardi, editors, [3mComputer Aided Verification,
      (CAV '98)[0m, Springer-Verlag LNCS [31;1m1427[0m, Heidelberg, pp. 135-146,
      1998.
      [31;1mRelevance:[0m proof method for dealing with exceptions and speculative
      execution

  [Bib::wilding92]
      M. M. Wilding, [3mMachine-checked real-time system verification[0m
      [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/wilding.pdf)[0m,
      University of Texas at Austin, Ph.D. dissertation, 1996.
      [31;1mRelevance:[0m a non-trivial applications program on the CLI Verified
      Stack

  [Bib::wilding93]
      M. M. Wilding, ``{A Mechanically Verified Application for a
      Mechanically Verified Environment |
      https://link.springer.com/content/pdf/10.1007/3-540-56922-7_22},
      in C. Courcoubetis, editor, [3mProceedings of Computer-Aided
      Verification -- CAV '93[0m, Springer-Verlag, LNCS [31;1m697[0m, Heidelberg,
      pp. 268-279, DOI:10.1007/3-540-56922-7_22, 1993.
      [31;1mRelevance:[0m functional correctness and resource utilization of a
      Nim-playing program on the CLI Verified Stack

  [Bib::young88]
      W. D. Young, [3mA Verified Code Generator for a Subset of Gypsy[0m
      [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/young.pdf)[0m, University
      of Texas at Austin, Ph.D. dissertation, 1988.
      [31;1mRelevance:[0m a verified compiler (from a small Pascal-like subset to an
      assembly language) and a component of the CLI Verified Stack

  [Bib::yu92]
      Y. Yu, [3mAutomated proofs of object code for a widely used
      microprocessor[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/yu.pdf)[0m,
      University of Texas at Austin, Ph.D. dissertation, 1992.
      [31;1mRelevance:[0m details of the operational model of the Motorola 68020")
 (OPERATIONAL-SEMANTICS-4__HOW-TO-FIND-THINGS
  (OPERATIONAL-SEMANTICS)
  "Citation conventions for doc operational-semantics

  In the documentation topic [operational-semantics] and its supporting
  subtopics, references to published books and papers appear as
  ordinary documentation topics, except all the labels are in the
  \"BIB\" package, e.g., [bib::mccarthy62] or [bib::kmm00a].  When
  finding them with the [47m:[0m[47m[doc][0m keyword command or in the [ACL2-doc]
  Emacs-based browser, you must type the ``bib::'' prefix.  When
  finding them in the ``Jump to'' box of your browser you must not
  include the ``bib::'' prefix.

  In [operational-semantics] and its supporting subtopics we also make
  frequent reference to Nqthm and ACL2 directories and proof scripts,
  such as [47mexamples/hunt/fm8501.events[0m and [47mbooks/projects/x86isa/[0m.  In
  this topic we explain how to dereference those citations to find
  the directory or file we mean.

  By the way, the active development of Nqthm ended in 1992, three
  years after ACL2 development began.  For about 10 years Nqthm and
  ACL2 were both in use.  Since then Nqthm has been maintained by
  Boyer and most of its proof scripts are not only still available
  but can still be processed.

  Documentation for Nqthm may be found in [bib::bm97].

  The Nqthm source code and proof scripts are available in two places,

    ftp://ftp.cs.utexas.edu/pub/boyer/nqthm/nqthm-1992/

  and

    https://drive.google.com/drive/folders/18z-uwg8E_3NxIijLoxYE-_NS-klqYI7R

  While it is possible to download individual files from these sites,
  we recommend that you download the entire [47mnqthm-1992[0m distribution
  as follows.  In particular, download the gzipped tar file:

    ftp://ftp.cs.utexas.edu/pub/boyer/nqthm/nqthm-2nd-edition.tar.gz

  to a directory where you want the Nqthm source code and regression
  suite, connect to that directory, and extract the files as follows.

    tar xfz nqthm-2nd-edition.tar.gz

  That will create the directory [47mnqthm-1992/[0m.

  You do not have to build the Nqthm image or do a regression if all
  you want to do is inspect either the Nqthm source code (which
  consists of the files [47mnqthm-1992/*.lisp[0m) or the files in the
  regression suite ([47mnqthm-1992/examples/[0m).  You can just explore the
  relevant files locally.  If you want to build Nqthm and do a
  regression, see the Nqthm installation instructions in
  [47mnqthm-1992/README[0m.

  The ACL2 system, as it stood in 2000, is documented in two textbooks
  described {here |
  https://www.cs.utexas.edu/~moore/publications/acl2-papers.html#Books}.
  These books are a good place for a beginner to start, even though
  some of the material is out-of-date.  Up-to-date user-level
  [documentation] of ACL2 is available online as described in the
  User's Manuals link on the homepage (below), and a wealth of
  information is available there.  Some of it is organized for the
  experienced user trying to get information about a particular
  feature, but there is a documentation topic, [start-here], that
  provides many starting points for the beginning ACL2 user.

  Source code, input files, installation instructions, extensive online
  documentation and other material is available on the {ACL2 homepage
  | http://www.cs.utexas.edu/users/moore/acl2/}:

    https://www.cs.utexas.edu/~moore/acl2/

  That page provides instructions for obtaining the latest ACL2
  numbered release.  However, many ACL2 users obtain an up-to-date
  {snapshot of ACL2 from GitHub | https://github.com/acl2/acl2}:

    https://github.com/acl2/acl2

  As with Nqthm, to explore ACL2 source files or prover input files we
  recommend that you perform the first step of the installation
  instructions found under the {``Obtaining, Installing, and
  License'' |
  https://www.cs.utexas.edu/~moore/acl2/current/HTML/installation/installation.html}
  link of the ACL2 homepage above.  That first step downloads a
  gzipped tar file of the latest sources and input scripts (but not
  prover output) to a directory of your choosing.  The filenames
  suffixed with [47m.lisp[0m at the top-level of that directory constitute
  the ACL2 source code.  The ACL2 regression suite consists of
  thousands of files called ``[books]'' and are available under the
  [47mbooks/[0m subdirectory.  So, for example, you'll find a toy model of
  the JVM at [47mbooks/models/jvm/m1/m1.lisp[0m.  If you want to see proofs
  you must build ACL2 on your machine and run a full regression as
  described in the installation instructions.


Quick Index to Related Topics

    * [operational-semantics]

    * [operational-semantics-1__simple-example]

    * [operational-semantics-2__other-examples]

    * [operational-semantics-3__annotated-bibliography]

    * operational-semantics-4__how-to-find-things --- current topic

    * [operational-semantics-5__history-etc]")
 (OPERATIONAL-SEMANTICS-5__HISTORY-ETC
  (OPERATIONAL-SEMANTICS)
  "A quick history of our style of modeling state machines

  As informally explained in [operational-semantics] and illustrated in
  [operational-semantics-1__simple-example] and
  [operational-semantics-3__annotated-bibliography], the common ACL2
  style in which state machines are modeled involves representing the
  relevant part of the state as an ACL2 object, defining a
  single-step function for computing state transitions, and then
  defining a total recursive run function for iterating the step
  function until it ``halts'' or some specified number of steps has
  been taken.

  This approach to operational semantics is different from ``structural
  operational semantics'' described by Plotkin in his 1981 paper ``A
  Structural Approach to Operational Semantics'' (see
  [bib::plotkin04a]).  Plotkin formalized machines operationally but
  as inference rules (reminiscent of Hoare logic).  See also
  [bib::plotkin04b], where Plotkin elaborates on the origins of that
  approach.  Furthermore, the origins paper appears in a two volume
  special issue of [3mThe Journal of Logic and Algebraic Programming[0m
  which contains many other papers on structural operational
  semantics.

  To distinguish the approach taken commonly in the ACL2 community from
  structural operational semantics we might call it ``ACL2-style''
  operational semantics.  But its only connection to ACL2 is that
  ACL2 happens to be the logic in which our models are expressed.
  Other settings supporting recursion and induction could also be
  used.  Boyer and Moore used this approach in the 1970s, inspired in
  part by McCarthy's seminal papers (``Recursive Functions of
  Symbolic Expressions and Their Computation by Machine,'' 1960, ``A
  Basis for a Mathematical Theory of Computation,'' 1963, and
  ``Correctness of a Compiler for Arithmetic Expressions,'' with
  James Painter, 1967).  But we would be hard-pressed to attribute
  this style of operational semantics even to McCarthy.  In the first
  place, mathematicians have used formal state machines at least
  since since Goedel's 1931 incompleteness paper: he modeled proofs
  as objects (specifically, integers) and defined a non-terminating
  function that stepped through all possible proofs looking for a
  particular proof.  In the second place, machine designers and
  programmers have been writing software to emulate other machines
  for almost as long as computers have existed. ACL2 is just another
  programming language in which such software can be written ---
  albeit one that comes with a logical foundation and theorem prover
  allowing one to reason about programs running on the machine or
  even properties of the machine itself.

  In fact, such operational semantics models played an important role
  in the evolution of ACL2.

  ACL2 evolved from earlier theorem provers by Boyer and Moore.  Those
  earlier provers were the Edinburgh Pure Lisp Theorem prover, aka
  PLTP (see [bib::bm73] and [bib::moore73]), (1971--73), Thm
  (1974--79), and Nqthm (1980--95) (see [bib::bm97]).  The dates are
  approximate.  Boyer and Moore began working on ACL2 on August 14,
  1989 and the first ACL2 proof (associativity of [47mappend[0m) was done on
  November 3, 1989.  Matt Kaufmann officially joined the ACL2
  development team in August, 1993, although he had become an
  invaluable contributor years before that.  See ``[47m; Commemorative
  Plaque[0m'' in the ACL2 source file [47mprove.lisp[0m.  For a description of
  the evolution from PLTP, through Thm, and Nqthm, to ACL2, including
  proper bibliographic citations, see [bib::moore19].

  Boyer and Moore's first foray into operational semantics for a
  computing machine shows up in Chapter 17 of [bib::bm79] where they
  used Thm to prove a version of the McCarthy-Painter theorem
  verifying an expression compiler for a simple machine [bib::mp67].

  At the time, Boyer and Moore were employed at SRI and were working
  part-time on the Software Implemented Fault Tolerance (SIFT)
  project.  Their task was to verify that a certain small fragment of
  machine code for the Bendix 930 (BDX930) flight-control computer
  implemented a simple time-sharing system.  (Personal aside by J
  Moore: Having such an ambitious goal, in 1979, astounds me in 2024,
  but it was a side-effect of youthful energy combined with naivete
  and the excitement (and hype?) of that early period in the history
  of mechanized formal methods.)  To attack the problem they
  formalized the necessary subset of the BDX930 instruction set
  operationally.  But Thm was not able to process the ``large''
  system of definitions (30 pages).  The problem was, in part, due to
  the representation of logical constants in Thm's implementation.
  E.g., the logical constant [47m1[0m was represented as the ground term
  [47m(add1 (zero))[0m, and the logical constant pair containing [47m1[0m in its
  [47mcar[0m and [47m2[0m in its [47mcdr[0m was the ground term:

    (cons (add1 (zero)) (add1 (add1 (zero))))

  So Thm was rewritten to represent the constant [47m1[0m as [47m(quote 1)[0m and the
  constant pair above as

    (quote (1 . 2)).

  This required a major rewrite (affecting virtually every routine in
  the system that inspected terms) and was a significant step toward
  Nqthm.  (Note: another formalization problem pushed Boyer and Moore
  in the same direction: the desire to support verified
  ``metafunctions,'' which required the formalization in the logic of
  a weak interpreter, [47mV&C$[0m, for the logic.)

  The BDX930 model was admitted to the improved ``Thm'' (now more like
  Nqthm) but Boyer and Moore then realized that the machine code
  implemented a time-sharing system only if every SIFT process, when
  compiled from the native Pascal, respected a bevy of unstated
  invariants on the machine code.  They wrote a ``minority report''
  explaining this.  That report was contained in Sections 14 and 15
  of the SIFT final report for the period September 1978 to June
  1982.  Section 14 describes the problem and Section 15 lists the 30
  page BDX930 model.  See [bib::bm80], which has the provocative
  title ``WHY IT IS IMPOSSIBLE TO PROVE THAT THE BDX930 DISPATCHER
  IMPLEMENTS A TIME-SHARING SYSTEM.''

  Boyer and Moore left SRI for the University of Texas at Austin in
  1981 and Nqthm was fully formed shortly thereafter.  The
  combination of Nqthm and some brilliant students led to a
  remarkable string of projects, including the FM8501 (and later the
  FM9001), the Computational Logic, Inc., verified stack, and the
  Motorola 68020 model and its use in the emulation and verification
  of machine code produced from the Berkeley C String Library by [47mgcc
  -o[0m.  (See [operational-semantics-3__annotated-bibliography] for
  proper citations.)  These projects pushed Nqthm to its limits:
  models were large and running them as software prototypes of the
  compute engines they modeled was relatively slow.

  That spurred Boyer and Moore to abandon the home grown Lisp supported
  by Nqthm and build a theorem prover for a subset of Common Lisp:
  ACL2.  That way, operational models were just Common Lisp functions
  and could be run at Common Lisp speeds.

  Of course, pressure on Kaufmann and Moore to improve ACL2 to provide
  higher capacity and more efficiency to load and process models of
  commercial processors continues to this day.  See Sections 8 and 9
  of [bib::hkms17].  Among many other changes made in response to
  industrial requests, many of which relate to operational models,
  are such things the invention of guards as an extralogical device
  to ensure that compiled code complies with the axioms, support for
  inlining and other directives to the compiler, the [47m[mbt][0m directive,
  performance improvements in certification and the inclusion of
  certified files into a session, congruent single-threaded objects,
  nested single-threaded objects, patterned congruence rules, and an
  attachment mechanism for stobjs so that different memory models can
  be executed.  See [stobj]s.


Quick Index to Related Topics

    * [operational-semantics]

    * [operational-semantics-1__simple-example]

    * [operational-semantics-2__other-examples]

    * [operational-semantics-3__annotated-bibliography]

    * [operational-semantics-4__how-to-find-things]

    * operational-semantics-5__history-etc --- current topic")
 (OPTIMIZE (POINTERS) "See [declare].")
 (OR
  (BASICS ACL2-BUILT-INS)
  "Disjunction

  [47mOr[0m is the macro for disjunctions.  [47mOr[0m takes any number of arguments
  and returns the first that is non-[47mnil[0m, or [47mnil[0m if there is no
  non-[47mnil[0m element.

  (Note: If you are seeking documentation for the [47m:or[0m hint, see
  [hints].)

  In the ACL2 logic, the macroexpansion of [47m(or x y)[0m is an [47mIF[0m term that
  appears to cause [47mx[0m to be evaluated twice:

    ACL2 !>:trans (or x y)

    (IF X X Y)

    => *

    ACL2 !>

  If [47mx[0m were replaced by an expression whose evaluation takes a long
  time, then such an expansion would be inefficient.  However, don't
  be fooled: you can expect Common Lisp implementations to avoid this
  problem, say by generating a new variable, for example:

    ACL2 !>:q ; Exit the ACL2 loop and go into raw Common Lisp

    Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
    ACL2>(macroexpand '(or x y))

    (LET ((#:G5374 X)) (IF #:G5374 #:G5374 Y))
    T

    ACL2>

  [47mOr[0m is a Common Lisp macro.  See any Common Lisp documentation for
  more information.

  [31;1mMacro: [0m<or>

    (defmacro or (&rest args)
      (or-macro args))

  [31;1mFunction: [0m<or-macro>

    (defun or-macro (lst)
      (declare (xargs :guard t))
      (if (consp lst)
          (if (consp (cdr lst))
              (list 'if
                    (car lst)
                    (car lst)
                    (or-macro (cdr lst)))
            (car lst))
        nil))")
 (ORDINALS
  (MISCELLANEOUS)
  "Ordinals in ACL2

  Ordinals are used in ACL2 for proving termination in the admission of
  recursive function definitions.  For a proof that the ACL2 ordinals
  are well-founded, see [proof-of-well-foundedness].

  The representation of ordinals changed in ACL2 Version_2.8, and is
  due to Pete Manolios and Daron Vroon.  They have also defined
  algorithms for ordinal arithmetic, created a library of theorems to
  reason about ordinal arithmetic, and written the rest of this
  documentation in order to explain this change.  We thank them for
  their efforts.  Although they have provided the implementation and
  even modified the community books as needed, we have looked over
  their work and are maintaining it (and this documentation); if
  there are any bugs, they should be considered ours (Matt Kaufmann
  and J Moore).

  A book is included for compatibility with the representation before
  Version_2.8.  For books that contain events relying on the previous
  ordinal implementation, insert the following lines before the first
  such event:

    (include-book \"ordinals/e0-ordinal\" :dir :system)
    (set-well-founded-relation e0-ord-<)

  The new ordinal representation is based on a slightly different
  version of Cantor Normal Form than that used by the old ordinals.
  An advantage of the new representation is that it is exponentially
  more succinct than the old representation.

  While pre-Version_2.8 ACL2 versions provided built-in functions for
  checking if an object is an ordinal and for comparing two ordinals,
  they did not provide support for reasoning about and constructing
  ordinals.  The community books directory [47mbooks/ordinals[0m provides
  such support.  First, it provides efficient algorithms for ordinal
  arithmetic (including addition, subtraction, multiplication, and
  exponentiation).  The algorithms and their complexity are described
  in the following paper.

    Manolios, Panagiotis & Vroon, Daron.
    Algorithms for ordinal arithmetic.
    Baader, Franz (ed),
    19th International Conference on Automated Deduction--CADE-19.
    Pages 243-257 of LNAI, vol. 2741.  Springer-Verlag.

  Second, the algorithms are mechanically verified and libraries of
  theorems which can be used to automate reasoning involving the
  ordinals are provided.  For details, see the following paper.

    Manolios, Panagiotis & Vroon, Daron.
    Ordinal arithmetic in ACL2.
    Kaufmann, Matt, & Moore, J Strother (eds).
    Fourth International Workshop on the ACL2 Theorem
    Prover and Its Applications (ACL2-2003),
    July, 2003.
    See {http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/ | http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}.

  We now describe aspects of the above mentioned books in more detail.

  The new ordering function is [47m[o<][0m and the new ordinal recognizer is
  [47m[o-p][0m.  See also [47m[natp][0m, [47m[posp][0m, [47m[o<=][0m, [47m[o>][0m, [47m[o>=][0m,
  [47m[o-first-expt][0m, [47m[o-first-coeff][0m, [47m[o-rst][0m, [47m[make-ord][0m, [47m[o-finp][0m, and
  [47m[o-infp][0m.

  The old ordinals were based on the following formulation of Cantor
  Normal Form:

  For any ordinal, [47ma < epsilon-0[0m, there exist natural numbers [47mp[0m and [47mn[0m,
  and ordinals [47ma1 >= a2 >= ... >= an > 0[0m such that [47ma > a1[0m and [47ma =
  w^(a1) + w^(a2) + ... + w^(an) + p[0m.

  Thus, a predicate recognizing ACL2's old ordinals is given by the
  following definition.

    (defun e0-ordinalp (x)
      (if (consp x)
          (and (e0-ordinalp (car x))
               (not (equal (car x) 0))
               (e0-ordinalp (cdr x))
               (or (atom (cdr x))
                   (not (e0-ord-< (car x) (cadr x)))))
        (and (integerp x)
             (>= x 0))))

  The new representation is based on a corollary to the above theorem,
  which we get by the left distributive property of ordinal
  multiplication over ordinal addition. Thus, [47mw^a + w^a = (w^a)2[0m, [47mw^a
  + w^a + w^a = (w^a)3[0m and so forth. The corollary is as follows:

  For any ordinal, [47ma < epsilon-0[0m, there exist natural numbers [47mp[0m and [47mn[0m,
  positive integers [47mx1, x2, ..., xn[0m and ordinals [47ma1 > a2 > ... > an >
  0[0m such that [47ma > a1[0m and [47ma = w^(a1)x1 + w^(a2)x2 + ... + w^(an)xn +
  p[0m.

  Instead of representing an ordinal as a list of non-increasing
  ordinals, we represent it as a list of exponent-coefficient pairs,
  such that the exponents are strictly decreasing (see [o-p]).  Note
  that this representation is exponentially more efficient than the
  old representation.

  The ordinal arithmetic functions: [47mo+[0m, [47mo-[0m, [47mo*[0m, and [47mo^[0m are defined in
  the ordinals library (in the community books directory
  [47mbooks/ordinals[0m). To use them, include the book
  [47mordinals-without-arithmetic[0m or [47mordinals[0m, depending on whether you
  want the arithmetic books included or not ([47mordinals[0m includes
  community book [47mbooks/arithmetic/top-with-meta[0m). To use the old
  ordinals, include the book [47me0-ordinal[0m and run the command
  [47m(set-well-founded-relation e0-ord-<)[0m

  The community book [arithmetic/natp-posp] is a book for reasoning
  about [47mposp[0m and [47mnatp[0m.  We recommend using this book if you have to
  reason about [47mposp[0m and [47mnatp[0m.  It is included in community book
  [47mbooks/arithmetic/top[0m, which is included in community book
  [47mbooks/arithmetic/top-with-meta[0m, which is included in community book
  [47mbooks/ordinals/ordinals[0m.

  If you have a good reason to use the old definitions of the ordinals
  (e.g., because of legacy code and theorems), then we provide a
  convenient way to do this.  The book [47mordinal-isomorphism[0m proves
  that the new ordinals are order-isomorphic to the old ordinals and
  thus theorems proved in one context can be directly transferred to
  the other.  For an example of how to do this, look at the book
  [47mdefmul[0m in the community books directory
  [47mbooks/workshops/2000/ruiz/multiset[0m.

  The ordinals books have been used to prove non-trivial theorems.  For
  a good example, see the books in the community books directory
  [47mbooks/workshops/2003/sustik/support[0m, where Matyas Sustik proves
  Dickson's lemma.

  Finally, many termination proofs can be carried out with weaker
  orderings than the ordinals up to [47mepsilon-0[0m.  For example, many
  inductive theorem provers only know that the lexicographic ordering
  on natural numbers is well-founded.  The book
  [47mlexicographic-ordering[0m contains a definition of such an ordering [47ml<[0m
  whose arguments are either a list of natural numbers, or a natural
  number.  In the book we prove that [47ml<[0m is well-founded (that is, we
  prove a [47m:well-founded-relation[0m [47m[defthm][0m and provide a macro [47mllist[0m
  to simplify the generation of measure functions.  We also show how
  to use [47ml<[0m to prove that the famous Ackermann function terminates.
  Finally, since [47ml<[0m does something reasonable with natural numbers,
  it gets along with [47m[ACL2-count][0m, the default measure chosen by
  ACL2.


Subtopics

  [Make-ord]
      A constructor for ordinals.

  [O-finp]
      Recognizes if an ordinal is finite

  [O-first-coeff]
      Returns the first coefficient of an ordinal

  [O-first-expt]
      The first exponent of an ordinal

  [O-infp]
      Recognizes if an ordinal is infinite

  [O-p]
      A recognizer for the ordinals up to epsilon-0

  [O-rst]
      Returns the rest of an infinite ordinal

  [O<]
      The well-founded less-than relation on ordinals up to [47mepsilon-0[0m

  [O<=]
      The less-than-or-equal relation for the ordinals

  [O>]
      The greater-than relation for the ordinals

  [O>=]
      The greater-than-or-equal relation for the ordinals

  [Proof-of-well-foundedness]
      A proof that [47m[o<][0m is well-founded on [47m[o-p][0ms")
 (OTF-FLG
  (DEFTHM THM XARGS)
  "Allow more than one initial subgoal to be pushed for induction

  This keyword argument for certain [events] controls whether the
  theorem prover will abandon its initial work upon encountering the
  second subgoal to push for proof by induction: [47m:otf-flg[0m is [47mnil[0m for
  that behavior, but [47mt[0m if it should instead continue ``Onward Through
  the Fog'' and complete [waterfall] processing before starting any
  proof by induction.

  The default value for [47m:otf-flg[0m is [47mnil[0m except during processing of
  [47m[defun][0m events, where the default is [47mt[0m for both termination and
  [guard] proofs (see [defun]).  Note that the default for [47m:otf-flg[0m
  is thus [47mt[0m for processing [47m[verify-termination][0m events, since they
  abbreviate [47mdefun[0m events.  However, the default for [47m:otf-flg[0m is [47mnil[0m
  for processing [47m[verify-guards][0m events.


Further Explanation

  Suppose you submit a conjecture to the theorem prover and the system
  splits it up into many subgoals.  Any subgoal not proved by other
  methods is eventually set aside for an attempted induction proof.
  But upon setting aside the second such subgoal, the system chickens
  out and decides that rather than prove n>1 subgoals inductively, it
  will abandon its initial work and attempt induction on the
  originally submitted conjecture.  The [47m:otf-flg[0m (Onward Thru the
  Fog) allows you to override this chickening out. When [47m:otf-flg[0m is
  [47mt[0m, the system will push all the initial subgoals and proceed to try
  to prove each, independently, by induction.

  Even when you don't expect induction to be used or to succeed,
  setting the [47m:otf-flg[0m is a good way to force the system to generate
  and display all the initial subgoals.

  For [47m[defthm][0m and [47m[thm][0m, [47m:otf-flg[0m is a keyword argument that is a peer
  to [47m:[0m[47m[rule-classes][0m and [47m:[0m[47m[hints][0m.  It may be supplied as in the
  following examples; also see [defthm].

    (thm (my-predicate x y) :rule-classes nil :otf-flg t)

    (defthm append-assoc
      (equal (append (append x y) z)
             (append x (append y z)))
      :hints ((\"Goal\" :induct t))
      :otf-flg t)

  The [47m:otf-flg[0m may be supplied to [47m[defun][0m via the [47m[xargs][0m declare
  option.  When you supply an [47m:otf-flg[0m hint to [47mdefun[0m, the flag is
  effective for the termination proofs and the guard proofs, if any.")
 (OTHER_REQUIREMENTS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Other Requirements

  {IMAGE} (see [The_End_of_the_Flying_Tour])

  ACL2 is distributed on the Web without fee.

  There is a [31;1mlicense[0m agreement based on the 3-clause BSD license.  See
  the file LICENSE in the ACL2 distribution.

  ACL2 currently runs on [31;1mUnix[0m, [31;1mLinux[0m, [31;1mWindows[0m, and [31;1mMacintosh OS X[0m
  operating systems.

  It can generally be built in any of the following Common Lisps:

    * [31;1mAllegro Common Lisp[0m,
    * [31;1mCCL[0m (formerly OpenMCL)
    * [31;1mCMU Common Lisp[0m,
    * [31;1mGCL[0m (Gnu Common Lisp),
    * [31;1mLispWorks[0m, and
    * [31;1mSBCL[0m (Steel Bank Common Lisp)

  {IMAGE} (see [The_End_of_the_Flying_Tour])")
 (OUTPUT-CONTROLS
  (ACL2 IO)
  "Methods for controlling the output produced by the ACL2 prover

  This topic pertains primarily to processing of [events], often
  involving the prover.  For a general discussion about redirection
  of ACL2 output to a file, see [output-to-file].


Subtopics

  [Finalize-event-user]
      User-supplied code to complete [events], e.g., with extra [summary]
      output

  [Gag-mode]
      Verbosity of proof output

  [Get-event-data]
      Obtain data stored after at the conclusion of an event

  [Goal-spec]
      To indicate where a hint is to be used

  [Initialize-event-user]
      User-supplied code to initiate [events]

  [Pso]
      Show the most recently saved output

  [Pso!]
      Show the most recently saved output, including [proof-tree] output

  [Psof]
      Show the most recently saved output

  [Psog]
      Show the most recently saved output with [gag-mode]

  [Saving-event-data]
      Save data stored for subsidiary [events]

  [Set-duplicate-keys-action!]
      Non-[47m[local][0m version of [47m[set-duplicate-keys-action][0m

  [Set-gag-mode]
      Modify the nature of proof output

  [Set-inhibit-er]
      Control the error output

  [Set-inhibit-er!]
      Control error output non-[47m[local][0mly

  [Set-inhibit-output-lst]
      Control output

  [Set-inhibit-warnings]
      Control warnings

  [Set-inhibit-warnings!]
      Control warnings non-[47m[local][0mly

  [Set-inhibited-summary-types]
      Control which parts of the [summary] are printed

  [Set-let*-abstractionp]
      To shorten many prettyprinted [clause]s

  [Set-print-clause-ids]
      Cause subgoal numbers to be printed when [47m'prove[0m output is inhibited

  [Set-raw-proof-format]
      Proof output with [rune]s as lists and maybe clausal goals

  [Set-raw-warning-format]
      Print some warnings in a ``raw'', s-expression format

  [Set-warnings-as-errors]
      Changing [warnings] to hard [errors] (and vice-versa)

  [Summary]
      The summary printed at the conclusion of an event

  [Toggle-inhibit-er]
      Add or delete an error output string from the [47minhibit-er-table[0m

  [Toggle-inhibit-er!]
      Toggle an [47minhibit-er-table[0m entry non-[47m[local][0mly

  [Toggle-inhibit-warning]
      Add or delete a warning string from the [47minhibit-warnings-table[0m

  [Toggle-inhibit-warning!]
      Toggle an [47minhibit-warnings-table[0m entry non-[47m[local][0mly

  [Warnings]
      Warnings emitted by the ACL2 proof process

  [With-output]
      Suppressing or turning on specified output for an event

  [Wof]
      Direct standard output and proofs output to a file")
 (OUTPUT-TO-FILE
  (IO)
  "Redirecting output to a file

  For a general discussion of ACL2 input/output and of the ACL2
  read-eval-print loop, see [io] and see [ld] (respectively).  Here
  we use an example to illustrate how to use some of the options
  provided by [47mld[0m to redirect ACL2 output to a file, other than the
  printing of the prompt (which continues to go to the terminal).

  There are two [47mld[0m specials that control output from the [47mld[0m command:
  [47m[proofs-co][0m for proof output and [47m[standard-co][0m for other output.
  The following example shows how to use these to redirect output to
  a file [47m\"tmp.out\"[0m.  The following command opens a character output
  channel to the file [47m\"tmp.out\"[0m and redirects proof output to that
  channel, i.e., to file [47m\"tmp.out\"[0m.

    (mv-let (chan state)
            (open-output-channel \"tmp.out\" :character state)
            (set-proofs-co chan state))

  Next, we redirect standard output to that same channel.

    (set-standard-co (proofs-co state) state)

  Now we can load an input file, in this case file [47m\"tmp.lisp\"[0m, and
  output will be redirected to file [47m\"tmp.out\"[0m.  (The use of
  [47m:ld-pre-eval-print t[0m is optional; see [ld].)

    (ld \"tmp.lisp\" :ld-pre-eval-print t)

  Having completed our load operation, we restore both proof output and
  standard output to the terminal, as follows.

    (set-standard-co *standard-co* state)
    (close-output-channel (proofs-co state) state)
    (set-proofs-co *standard-co* state)

  The following variant of the above example shows how to redirect
  output as above except without changing the global settings of the
  two [47m[ld][0m specials, [47m[proofs-co][0m and [47m[standard-co][0m.  This approach
  uses a notion of ``global variables'' stored in the ACL2 [state];
  see [assign] and see [@].

    (mv-let (chan state)
            (open-output-channel \"tmp.out\" :character state)
            (assign tmp-channel chan))
    (ld \"tmp.lisp\" :ld-pre-eval-print t
                   :proofs-co (@ tmp-channel)
                   :standard-co (@ tmp-channel))
    (close-output-channel (@ tmp-channel) state)")
 (OVERRIDE-HINTS
  (HINTS)
  "A list of hints given priority in every proof attempt

  This is an advanced feature, originally implemented to help system
  designers to create ``modes'' that control the way hints are
  supplied to the theorem prover.  Please see [default-hints] for the
  much more usual way to install hints that may be applied by
  default.

    Examples:
    ACL2 !>(override-hints (w state))
    ((computed-hint-1 clause keyword-alist processor)
     (computed-hint-2 clause keyword-alist stable-under-simplificationp))

  [47mOverride-hints[0m returns a list of computed hints (see
  [computed-hints]) which, unlike other computed hints, may mention
  the variable [47mKEYWORD-ALIST[0m.

  Before reading further, please see [hints-and-the-waterfall] to
  review the basics of how [hints] are applied during a proof.  In
  particular, we assume familiarity with the notion of selecting a
  hint to be applied to the current goal.  If there are
  override-hints, that hint selection is tentative, because if it
  reduced to [47mnil[0m after the application of override-hints, then that
  hint will be skipped and the attempt will continue for selecting an
  applicable hint.  (Craft your override-hints so that [47m:no-op t[0m is
  returned in such cases instead of [47mnil[0m, if you don't want the hint
  to be skipped.)  But we must explain what is meant by ``the
  application of override-hints'', and we do that now.

  Suppose that there are override-hints when a hint is selected for the
  current goal.  That selected hint is a keyword-alist, which is an
  alternating list of hint keywords and their values, whose source is
  either an explicit hint [47m(goal-name :key1 val1 ... :keyn valn)[0m where
  the [47m:keyi[0m are allowed to be custom hint keywords (which are
  expanded away; see [custom-keyword-hints]), or else is the non-[47mnil[0m
  keyword-alist produced by evaluating a computed hint.  Then the
  override-hints are applied to that keyword-alist as follows, one at
  a time, in order of their occurrence in the list of override-hints
  (as determined by the use of [47m[set-override-hints][0m and
  [47m[add-override-hints][0m).  The first override-hint is evaluated, in
  the usual manner of evaluating computed hints but with the variable
  [47mKEYWORD-ALIST[0m bound to the above keyword-alist.  That evaluation
  produces a result that should also be a keyword-alist, or else an
  error occurs.  Any custom keyword hints are then eliminated from
  that keyword-alist.  The resulting keyword-alist must not contain
  the [47m:ERROR[0m hint keyword and must not start with the
  [47m:COMPUTED-HINT-REPLACEMENT[0m keyword; otherwise an error occurs.
  With [47mKEYWORD-ALIST[0m bound to this result, the second override-hint
  is similarly evaluated.  This process continues, and the
  keyword-alist returned by the final override-hint is the one used
  when processing the goal at hand.  Except: If that keyword-alist is
  [47mnil[0m, then the next hint among the pending hints is tentatively
  selected and the process repeats, applying each override hint to
  that new tentative selection.  Of course we might obtain [47mnil[0m again,
  in which case we tentatively select the next pending hint; and so
  on.

  If finally no hint is selected for the current goal, then
  [47mKEYWORD-ALIST[0m is bound to [47mnil[0m and the override-hints are applied as
  described above.  But note that this final step is skipped if hint
  selection is being performed because [47mstable-under-simplificationp[0m
  has just become true, rather than at the top of the waterfall.
  (Otherwise the override-hints could easily keep firing uselessly
  yet putting us back at the top of the waterfall, with no change to
  the given goal, resulting in an infinite loop.)

  As mentioned above, the [47m:COMPUTED-HINT-REPLACEMENT[0m keyword is illegal
  for the value of an override-hint.  But a selected hint may be a
  computed hint that evaluates to a keyword-alist beginning with
  prefix [47m:COMPUTED-HINT-REPLACEMENT val[0m.  What value does ACL2 return
  for such a computed hint in the presence of override-hints?  First,
  this prefix is stripped off before passing the resulting
  keyword-alist to the override-hints as described above.  If the
  result of applying override-hints to that keyword-alist is not [47mnil[0m,
  then the prefix is put back on the front of that resulting
  keyword-alist after doing internal processing of the hint,
  including expansion of any custom keyword hints.  Otherwise, the
  application of override-hints to the computed hint is [47mnil[0m, so this
  hint is not selected after all.

  [31;1mWARNING[0m: Unlike ordinary computed hints, a value of [47mnil[0m for an
  override-hint is not ignored.  That is: When an ordinary computed
  hint evaluates to [47mnil[0m, it is deemed not to apply, and the next
  available hint is consulted.  But when an override-hint is
  evaluated, the result is always supplied for the next binding of
  the variable [47mKEYWORD-ALIST[0m, even if that result is [47mnil[0m.  If you
  want an override-hint to be a no-op, return as the expression the
  variable [47mKEYWORD-ALIST[0m rather than an expression that evaluates to
  [47mnil[0m.

  This feature can be used in order to implement a form of additive
  hints.  Suppose for example that you want a hint that turns off
  generalization.  A simple but inadequate solution is:

    (add-default-hints '((quote (:do-not '(generalize)))))

  The problem is that if there is any explicit hint supplied for a
  given goal, then it will be the one selected, and the above will be
  ignored.  But suppose that the explicit hint supplied is of the
  form [47m(\"Subgoal x.y\" :do-not '(fertilize))[0m.  What we would really
  want in this case is to generate the hint for the indicated subgoal
  that binds [47m:do-not[0m to a list indicating that both fertilization
  _and_ generalization are disabled for that goal.  A solution is to
  merge, for example as follows.  (The use of [47m[prog2$][0m and [47m[cw][0m is of
  course optional, included here to provide debug printing.)

    (add-override-hints
     '((let* ((tmp (assoc-keyword :do-not KEYWORD-ALIST))
              (new-keyword-alist
               (cond (tmp (list* :do-not
                                 `(cons 'generalize ,(cadr tmp))
                                 (remove-keyword :do-not KEYWORD-ALIST)))
                     (t (list* :do-not ''(generalize) KEYWORD-ALIST)))))
         (prog2$ (cw \"New: ~x0~|\" new-keyword-alist)
                 new-keyword-alist))))

  REMARKS

  (1) The utilities [47m[add-override-hints][0m, [47m[add-override-hints!][0m,
  [47m[set-override-hints][0m, [47m[set-override-hints!][0m,
  [47m[remove-override-hints][0m, and [47m[remove-override-hints!][0m are also
  available, in complete analogy to their default-hints versions.

  (2) The community book [47mhints/basic-tests.lisp[0m illustrates the use of
  override-hints and illuminates a number of corner cases; search in
  that file for ``Test override-hints.''

  (3) The community book [47mhints/merge-hint.lisp[0m provides support for
  merging hints that might be useful for writers of override-hint
  expressions (see the examples at the end of that file).

  (4) Override-hints are used in the processing of [47m:BACKTRACK[0m hints
  (see [hints]).


Subtopics

  [Add-override-hints]
      Add to the [override-hints]

  [Add-override-hints!]
      Add non-[local]ly to the [override-hints]

  [Remove-override-hints]
      Delete from the list of [override-hints]

  [Remove-override-hints!]
      Delete non-[local]ly from the list of [override-hints]

  [Set-override-hints]
      Set the [override-hints]

  [Set-override-hints!]
      Set the [override-hints] non-[local]ly")
 (OVERVIEW_OF_THE_EXPANSION_OF_ENDP_IN_THE_BASE_CASE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Overview of the Expansion of ENDP in the Base Case

  [47mSubgoal *1/1[0m is the [31;1mBase Case[0m of our induction.  It simplifies to
  [47mSubgoal *1/1'[0m by expanding the [31;1mENDP[0m term in the hypothesis, just as
  we saw in the earlier proof of [47mSubgoal *1/2[0m.")
 (OVERVIEW_OF_THE_EXPANSION_OF_ENDP_IN_THE_INDUCTION_STEP
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Overview of the Expansion of ENDP in the Induction Step

  In this message the system is saying that [47mSubgoal *1/2[0m has been
  rewritten to the [47mSubgoal *1/2'[0m, by expanding the definition of
  [31;1mendp[0m.  This is an example of [31;1msimplification[0m, one of the main proof
  techniques used by the theorem prover.

  Click here (see
  [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_0}]) if you
  would like to step through the simplification of [47mSubgoal *1/2[0m.")
 (OVERVIEW_OF_THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Overview of the Final Simplification in the Base Case

  The [31;1mBut[0m is our signal that the goal is proved.

  Click here (see [The_Final_Simplification_in_the_Base_Case_{Step_0}])
  to step through the proof.  It is very simple.")
 (OVERVIEW_OF_THE_PROOF_OF_A_TRIVIAL_CONSEQUENCE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Overview of the Proof of a Trivial Consequence

  {IMAGE} (see [The_End_of_the_Walking_Tour])

  {IMAGE}

    ACL2 !>[31;1m(defthm trivial-consequence[0m
             [31;1m(equal (app (app (app (app x1 x2) (app x3 x4)) (app x5 x6)) x7)[0m
                    [31;1m(app x1 (app (app x2 x3) (app (app x4 x5) (app x6 x7))))))[0m

    ACL2 Warning (see [The_WARNING_about_the_Trivial_Consequence]) [Subsume] in ( DEFTHM TRIVIAL-CONSEQUENCE ...):  The previously
    added rule ASSOCIATIVITY-OF-APP subsumes the newly proposed :REWRITE
    rule TRIVIAL-CONSEQUENCE, in the sense that the old rule rewrites a
    more general target.  Because the new rule will be tried first, it
    may nonetheless find application.

    By the simple :rewrite rule ASSOCIATIVITY-OF-APP (see [The_First_Application_of_the_Associativity_Rule]) we reduce the conjecture
    to

    Goal'
    (EQUAL (APP X1
                (APP X2
                     (APP X3 (APP X4 (APP X5 (APP X6 X7))))))
           (APP X1
                (APP X2
                     (APP X3 (APP X4 (APP X5 (APP X6 X7))))))).

    But we reduce the conjecture to T, by primitive type reasoning.

    Q.E.D.

    Summary
    Form:  ( DEFTHM TRIVIAL-CONSEQUENCE ...)
    Rules: ((:REWRITE ASSOCIATIVITY-OF-APP)
            (:FAKE-RUNE-FOR-TYPE-SET NIL))
    Warnings:  Subsume (see [The_Summary_of_the_Proof_of_the_Trivial_Consequence])
    Time:  0.20 seconds (prove: 0.02, print: 0.00, other: 0.18)
     TRIVIAL-CONSEQUENCE

  {IMAGE}

  You might explore the links before moving on.

  {IMAGE} (see [The_End_of_the_Walking_Tour])")
 (OVERVIEW_OF_THE_SIMPLIFICATION_OF_THE_BASE_CASE_TO_T
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Overview of the Simplification of the Base Case to T

  {IMAGE} (see [The_End_of_the_Proof_of_the_Associativity_of_App])

    Subgoal *1/1 (see [Overview_of_the_Expansion_of_ENDP_in_the_Base_Case])
    (IMPLIES (ENDP A)
             (EQUAL (APP (APP A B) C)
                    (APP A (APP B C)))).

    By the simple :definition ENDP we reduce the conjecture to

    Subgoal *1/1'
    (IMPLIES (NOT (CONSP A))
             (EQUAL (APP (APP A B) C)
                    (APP A (APP B C)))).

    But (see [Overview_of_the_Final_Simplification_in_the_Base_Case]) simplification reduces this to T, using the :definition APP and
    primitive type reasoning.

  {IMAGE} (see [The_End_of_the_Proof_of_the_Associativity_of_App])")
 (OVERVIEW_OF_THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Overview of the Simplification of the Induction Conclusion

  In this message the system is saying that [47mSubgoal *1/2'[0m has been
  rewritten to T using the rules noted.  The word ``[31;1mBut[0m'' at the
  beginning of the sentence is a signal that the goal has been
  proved.

  Click here (see
  [The_Simplification_of_the_Induction_Conclusion_{Step_0}]) to step
  through the proof of [47mSubgoal *1/2'[0m.")
 (OVERVIEW_OF_THE_SIMPLIFICATION_OF_THE_INDUCTION_STEP_TO_T
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Overview of the Simplification of the Induction Step to T

  {IMAGE} (see [Overview_of_the_Simplification_of_the_Base_Case_to_T])

    Subgoal *1/2 (see [On_the_Naming_of_Subgoals])
    (IMPLIES (AND (NOT (ENDP A))
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP (APP A B) C)
                    (APP A (APP B C)))).

    By the simple :definition ENDP (see [Overview_of_the_Expansion_of_ENDP_in_the_Induction_Step]) we reduce the conjecture to

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP (APP A B) C)
                    (APP A (APP B C)))).

    But (see [Overview_of_the_Simplification_of_the_Induction_Conclusion]) simplification reduces this to T, using the :definition APP, the
    :rewrite rules CDR-CONS and CAR-CONS and primitive type reasoning.

  {IMAGE} (see [Overview_of_the_Simplification_of_the_Base_Case_to_T])")
 (P!
  (LD)
  "To pop up (at least) one level of ACL2's command loop

  Logically speaking, [47m(p!) = nil[0m.  If you are already at the top level
  of the ACL2 command loop, rather than being in a subsidiary call of
  [47m[ld][0m, then the keyword then a call of [47m(p!)[0m returns [47mnil[0m and has no
  other effect.

  Otherwise, [47m(p!)[0m is evaluated inside a call of [47m[ld][0m that was made
  inside ACL2's command loop.  In that case, the current computation
  is aborted and treating as causing an error, and control returns to
  the superior call of [47mld[0m.

  Here is a more detailed description of the effect of [47m(p!)[0m when not at
  the top level of the ACL2 command loop.  The current call of [47mLD[0m is
  treated as though [47mld-error-action[0m is [47m:RETURN![0m (the default; here we
  ignore the case [47m(:exit N)[0m) and hence immediately returns control to
  the superior call of [47m[ld][0m.  If all calls of [47m[ld][0m were made with the
  default [47mld-error-action[0m of [47m:RETURN![0m, then all superior calls of [47mld[0m
  will then complete until you are back at top level of the ACL2
  loop.  For more information, see [ld-error-action].

  If you are at an ACL2 prompt (as opposed to a raw Lisp break), then
  you may type [47m:p![0m in place of [47m(p!)[0m; see [keyword-commands].

  If you are actually in a break caused by [break-rewrite], [47m:p![0m and
  [47m(p!)[0m just print a message and otherwise are no-ops.  (A comment in
  the source code definition of [47mp![0m explains why break-rewrite cannot
  support ``popping up one level'' in the sense that you would
  probably expect.)")
 (PACKAGE (POINTERS) "See [packages].")
 (PACKAGE-REINCARNATION-IMPORT-RESTRICTIONS
  (PACKAGES)
  "Re-defining undone [47m[defpkg][0ms

  ACL2 imposes the following restriction on redefining packages.  Note
  that for the notion of a package definition being ``undone'', the
  undoing might have been by use of [47m:[0m[47m[ubt][0m, or it might have been
  because the [47mdefpkg[0m form was evaluated by a [local] event that
  disappeared during the second pass of an [47m[encapsulate][0m or
  [47m[include-book][0m event.

    Suppose [47m(defpkg \"pkg\" imports)[0m has been evaluated successfully and
    then has been undone.  Then any future attempt in the same
    session to define [47m\"pkg\"[0m as a package must specify an identical
    imports list.


Reasons for the restriction

  We will see below that the restriction above is necessary for
  avoiding unsoundness.  But first consider the following simple
  example, which shows that the package doesn't entirely disappear
  when undone.

    ACL2 !>(defpkg \"FOO\" nil)

    Summary
    Form:  ( DEFPKG \"FOO\" ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     \"FOO\"
    ACL2 !>(assign x 'foo::a)
     FOO::A
    ACL2 !>(u) ; undoes the defpkg event
               0:x(EXIT-BOOT-STRAP-MODE)
    ACL2 !>(@ x)
    FOO::A
    ACL2 !>(eq (@ x) 'acl2::a)
    NIL
    ACL2 !>

  Suppose that (without the restriction) the package [47m\"FOO\"[0m can now be
  introduced as [47m(defpkg \"FOO\" '(a))[0m.  Then will [47m(eq (@ x) 'acl2::a)[0m
  evaluate to [47mnil[0m as before, since we didn't make another assignment
  to [47mx[0m?  Or would that equality evaluate to [47mt[0m since the only symbol
  in package [47m\"FOO\"[0m whose [47m[symbol-name][0m is [47m\"A\"[0m is [47macl2::a[0m?  Each
  result is plausible so to avoid confusion, it might be best if [47m(@
  x)[0m is now undefined.  But that would require somehow removing all
  symbols in the [state] whose package is [47m\"FOO\"[0m when undoing the
  [47mdefpkg[0m event, which can be inefficient and --- more importantly ---
  may not make sense if there are [stobj]s that include such symbols.
  What a mess!

  A more important reason for the restriction is that it prevents
  unsoundness.  Consider the following two books.

    ;;; book1.lisp
    ;;; Portcullis command: (defpkg \"FOO\" '())
    (in-package \"ACL2\")
    (defthm thm1
      (equal (symbol-package-name (intern$ \"A\" \"FOO\"))
             \"FOO\"))

    ;;;;;;

    ;;; book2.lisp
    ;;; Portcullis command: (defpkg \"FOO\" '(a))
    (in-package \"ACL2\")
    (defthm thm2
      (equal (symbol-package-name (intern$ \"A\" \"FOO\"))
             \"ACL2\"))

  After each of these two books is certifiable in a (separate) fresh
  ACL2 session, consider the following two events.

    (encapsulate
      ()
      (local (include-book \"book1\"))
      (defthm thm1
        (equal (symbol-package-name (intern$ \"A\" \"FOO\"))
               \"FOO\")))

    (encapsulate
      ()
      (local (include-book \"book2\"))
      (defthm thm1
        (equal (symbol-package-name (intern$ \"A\" \"FOO\"))
               \"ACL2\")))

  Each is accepted in a separate, fresh ACL2 session.  But if we could
  admit the first and then the second in the same session, we could
  of course prove [47mnil[0m.  Fortunately, if we try that, then ACL2
  implements the restriction by complaining about the second as
  follows, when encountering the [47m(local (include-book \"book2\"))[0m form
  in the second [47mencapsulate[0m.

    ACL2 Error in ACL2-INTERFACE:
    We cannot reincarnate the package \"FOO\" because it was previously defined
    with a different list of imported symbols.

  A final reason for the restriction stems from the reinstallation of
  saved logical [world]s, as in error recovery and the [47m:[0m[47m[oops][0m
  [command].  Suppose that the new [47m[defpkg][0m attempts to import some
  symbol, [47ma::sym[0m, not imported by the previous definition of [47m\"pkg\"[0m.
  Because it was not imported in the original package, the symbol
  [47mpkg::sym[0m, different from [47ma::sym[0m, may well have been created and may
  well be used in some saved [world]s.  Those saved [world]s are
  Common Lisp objects being held for you ``behind the scenes.'' In
  order to import [47ma::sym[0m into [47m\"pkg\"[0m now we would have to unintern
  [47mpkg::sym[0m, rendering those saved [world]s ill-formed.  So because of
  saved [world]s, we do not clear out a package when it is undone.


A logical view of the restriction

  The restriction on redefining packages is based on the following part
  of the logical foundation of ACL2.

    [31;1mLogical Persistence of Packages.[0m
    When a package is introduced by [47m[defpkg][0m in an ACL2 session, its
    definition is considered to persist logically even if that
    [defpkg] [event] is undone.

  That principle certainly rules out the new definition of an undone
  package with different imports.  It also explains why package
  definitions from [local]ly included [books] are included in a
  book's [portcullis] commands; see [hidden-defpkg].  Note that this
  is a [3mlogical[0m principle; if you undo a [47m[defpkg][0m event, then ACL2
  will prevent you from referencing that package explicitly unless
  you first reintroduce it --- with the same imports, because of the
  restriction.")
 (PACKAGES
  (PROGRAMMING)
  "Collections of symbols that act as namespaces.

Packages are collections of symbols.  They can be used to avoid name
conflicts when working on large ACL2 projects.  See
[working-with-packages] for the best practices in setting up and
using packages.


Subtopics

  [*ACL2-exports*]
      Symbols that are often imported into new [packages] to provide easy
      access to ACL2 functionality.

  [*common-lisp-symbols-from-main-lisp-package*]
      Symbols that are often imported into new packages to provide easy
      access to Common Lisp functionality.

  [ACL2-user]
      A package the ACL2 user may prefer

  [Defpkg]
      Define a new symbol package

  [Hidden-death-package]
      Handling [47m[defpkg][0m [events] that are [47m[local][0m

  [Hidden-defpkg]
      Handling defpkg events that are local

  [In-package]
      Select current package

  [Intern]
      Create a new symbol in a given package

  [Intern$]
      Create a new symbol in a given package

  [Intern-in-package-of-symbol]
      Create a symbol with a given name

  [Managing-ACL2-packages]
      User-contributed documentation on packages

  [Package-reincarnation-import-restrictions]
      Re-defining undone [47m[defpkg][0ms

  [Packages-for-generated-symbols]
      Convention for packages of generated symbols

  [Pkg-imports]
      List of symbols imported into a given package

  [Pkg-witness]
      Return a specific symbol in the indicated package

  [Sharp-bang-reader]
      Package prefix that is not restricted to symbols

  [Symbol-package-name]
      The name of the package of a symbol (a string)")
 (PACKAGES-FOR-GENERATED-SYMBOLS
  (PACKAGES)
  "Convention for packages of generated symbols

  ACL2 utilities, whether defined in the ACL2 sources or in books, will
  ideally provide the following default behavior when feasible:
  generated symbols should be in the [47m[current-package][0m.  This is the
  ACL2 version of the general principle enforced by almost all
  programming languages: names introduced are, by default, in the
  current namespace.  We do not claim that ACL2 currently adheres to
  this principle in all cases, but our hope that this situation is
  improved over time.  Indeed, the utilities [47m[defequiv][0m,
  [47m[defrefinement][0m and [47m[defcong][0m have been improved to conform to this
  principle; see [note-8-3].  We hope that future utilities, not only
  in ACL2 but also in the [community-books], will respect this
  principle when feasible.  Conforming to this principle requires
  using [47m[make-event][0m in a top level form to determine the
  [47m[current-package][0m from [47m[state][0m and then passing this package to
  functions that generate symbols.  The section [47mSymbol generation
  utilities[0m of ACL2 source file [47mdefthm.lisp[0m contains utilities that
  are useful for generating symbols.  The code was adapted from
  similar code in [47m[ACL2s][0m; see the community book
  [47macl2s/utilities.lisp[0m which includes even more such utilities.  To
  see an example of a utility that generates symbols in the current
  package, see [47mbooks/acl2s/defunc.lisp[0m, which contains the
  [47m[ACL2s::defunc][0m utility.  Other examples include [47m[defequiv][0m,
  [47m[defrefinement][0m and [47m[defcong][0m in [47mdefthm.lisp[0m.")
 (PACKN
  (SYMBOLS ACL2-BUILT-INS)
  "Build a symbol from a list

  The call [47m(packn lst)[0m returns a symbol whose name is a concatenation
  of string representations of the atoms in the [47m[atom-listp][0m, [47mlst[0m.
  The symbol's package is the package of the first symbol in [47mlst[0m
  whose package is not [47m\"COMMON-LISP\"[0m if any, else [47m\"ACL2\"[0m.")
 (PACKN-POS
  (SYMBOLS ACL2-BUILT-INS)
  "Build a symbol in a specified package from a list

  The function [47mpackn-pos[0m behaves like [47m[packn][0m, except that for the call
  [47m(packn-pos lst witness)[0m, the returned symbol's package will instead
  be the package of the symbol, [47mwitness[0m.")
 (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS
  (ACL2-TUTORIAL)
  "Pages Written Especially for the Tours

  The ACL2 Home Page is generated from ACL2's online documentation
  strings.  (How else could we achieve the total integration of
  ACL2's online documentation with the home page?)  This page is just
  an artifact of the structure of our documentation strings: each
  string must belong to a ``major section'' of the documentation
  database.  This page is not structured to be used by a person
  browsing via the Web.  It contains, in an arbitrary order, the
  pages written specifically for the Web user.

  Furthermore, browsing the pages below as text, in particular using
  the ACL2 :DOC command, is often unsatisfying because because of the
  lack of support for displaying gif files or for going ``back'' to a
  node just visited.  If you wish to look at the pages below, we
  strongly recommend that you do so via a HTML-based Web browser.
  Indeed, you should simply visit ACL2's Home Page and take one of
  the Tours.

  Generally, the topics listed above will not be of use to the ACL2
  user.


Subtopics

  [A_Flying_Tour_of_ACL2]
      A Flying Tour of ACL2

  [A_Sketch_of_How_the_Rewriter_Works]
      A Sketch of How the Rewriter Works

  [A_Tiny_Warning_Sign]
      A Tiny Warning Sign

  [A_Trivial_Proof]
      A Trivial Proof

  [A_Typical_State]
      A Typical State

  [A_Walking_Tour_of_ACL2]
      A Walking Tour of ACL2

  [ACL2_Characters]
      ACL2 Characters

  [ACL2_Conses_or_Ordered_Pairs]
      ACL2 Conses or Ordered Pairs

  [ACL2_Strings]
      ACL2 Strings

  [ACL2_Symbols]
      ACL2 Symbols

  [ACL2_System_Architecture]
      ACL2 System Architecture

  [ACL2_as_an_Interactive_Theorem_Prover]
      ACL2 as an Interactive Theorem Prover

  [ACL2_as_an_Interactive_Theorem_Prover_{cont}]
      ACL2 as an Interactive Theorem Prover (cont)

  [ACL2_is_an_Untyped_Language]
      ACL2 is an Untyped Language

  [About_Models]
      About Models

  [About_Types]
      About Types

  [About_the_ACL2_Home_Page]
      About the ACL2 Home Page

  [About_the_Admission_of_Recursive_Definitions]
      About the Admission of Recursive Definitions

  [About_the_Prompt]
      About the Prompt

  [An_Example_Common_Lisp_Function_Definition]
      An Example Common Lisp Function Definition

  [An_Example_of_ACL2_in_Use]
      An Example of ACL2 in Use

  [Analyzing_Common_Lisp_Models]
      Analyzing Common Lisp Models

  [Common_Lisp]
      Common Lisp

  [Common_Lisp_as_a_Modeling_Language]
      Common Lisp as a Modeling Language

  [Conversion]
      Conversion to Uppercase

  [Corroborating_Models]
      Corroborating Models

  [Evaluating_App_on_Sample_Input]
      Evaluating App on Sample Input

  [Flawed_Induction_Candidates_in_App_Example]
      Flawed Induction Candidates in App Example

  [Free_Variables_in_Top-Level_Input]
      Free Variables in Top-Level Input

  [Functions_for_Manipulating_these_Objects]
      Functions for Manipulating these Objects

  [Guards_in_ACL2]
      Guards

  [Guessing_the_Type_of_a_Newly_Admitted_Function]
      Guessing the Type of a Newly Admitted Function

  [Guiding_the_ACL2_Theorem_Prover]
      Guiding the ACL2 Theorem Prover

  [Hey_Wait!__Is_ACL2_Typed_or_Untyped{Q}]
      Hey Wait!  Is ACL2 Typed or Untyped?

  [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}]
      How Long Does It Take to Become an Effective User?

  [How_To_Find_Out_about_ACL2_Functions]
      How To Find Out about ACL2 Functions

  [How_To_Find_Out_about_ACL2_Functions_{cont}]
      How To Find Out about ACL2 Functions (cont)

  [Modeling_in_ACL2]
      Modeling in ACL2

  [Models_in_Engineering]
      Models in Engineering

  [Models_of_Computer_Hardware_and_Software]
      Models of Computer Hardware and Software

  [Name_the_Formula_Above]
      Name the Formula Above

  [Nontautological_Subgoals]
      Prover output omits some details

  [Numbers_in_ACL2]
      Numbers in ACL2

  [On_the_Naming_of_Subgoals]
      On the Naming of Subgoals

  [Other_Requirements]
      Other Requirements

  [Overview_of_the_Expansion_of_ENDP_in_the_Base_Case]
      Overview of the Expansion of ENDP in the Base Case

  [Overview_of_the_Expansion_of_ENDP_in_the_Induction_Step]
      Overview of the Expansion of ENDP in the Induction Step

  [Overview_of_the_Final_Simplification_in_the_Base_Case]
      Overview of the Final Simplification in the Base Case

  [Overview_of_the_Proof_of_a_Trivial_Consequence]
      Overview of the Proof of a Trivial Consequence

  [Overview_of_the_Simplification_of_the_Base_Case_to_T]
      Overview of the Simplification of the Base Case to T

  [Overview_of_the_Simplification_of_the_Induction_Conclusion]
      Overview of the Simplification of the Induction Conclusion

  [Overview_of_the_Simplification_of_the_Induction_Step_to_T]
      Overview of the Simplification of the Induction Step to T

  [Perhaps]
      Perhaps

  [Popping_out_of_an_Inductive_Proof]
      Popping out of an Inductive Proof

  [Proving_Theorems_about_Models]
      Proving Theorems about Models

  [Revisiting_the_Admission_of_App]
      Revisiting the Admission of App

  [Rewrite_Rules_are_Generated_from_DEFTHM_Events]
      Rewrite Rules are Generated from DEFTHM Events

  [Running_Models]
      Running Models

  [Subsumption_of_Induction_Candidates_in_App_Example]
      Subsumption of Induction Candidates in App Example

  [Suggested_Inductions_in_the_Associativity_of_App_Example]
      Suggested Inductions in the Associativity of App Example

  [Symbolic_Execution_of_Models]
      Symbolic Execution of Models

  [The_Admission_of_App]
      The Admission of App

  [The_Associativity_of_App]
      The Associativity of App

  [The_Base_Case_in_the_App_Example]
      The Base Case in the App Example

  [The_End_of_the_Flying_Tour]
      The End of the Flying Tour

  [The_End_of_the_Proof_of_the_Associativity_of_App]
      The End of the Proof of the Associativity of App

  [The_End_of_the_Walking_Tour]
      The End of the Walking Tour

  [The_Event_Summary]
      The Event Summary

  [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_0}]
      The Expansion of ENDP in the Induction Step (Step 0)

  [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_1}]
      The Expansion of ENDP in the Induction Step (Step 1)

  [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_2}]
      The Expansion of ENDP in the Induction Step (Step 2)

  [The_Falling_Body_Model]
      The Falling Body Model

  [The_Final_Simplification_in_the_Base_Case_{Step_0}]
      The Final Simplification in the Base Case (Step 0)

  [The_Final_Simplification_in_the_Base_Case_{Step_1}]
      The Final Simplification in the Base Case (Step 1)

  [The_Final_Simplification_in_the_Base_Case_{Step_2}]
      The Final Simplification in the Base Case (Step 2)

  [The_Final_Simplification_in_the_Base_Case_{Step_3}]
      The Final Simplification in the Base Case (Step 3)

  [The_First_Application_of_the_Associativity_Rule]
      The First Application of the Associativity Rule

  [The_Induction_Scheme_Selected_for_the_App_Example]
      The Induction Scheme Selected for the App Example

  [The_Induction_Step_in_the_App_Example]
      The Induction Step in the App Example

  [The_Instantiation_of_the_Induction_Scheme]
      The Instantiation of the Induction Scheme

  [The_Justification_of_the_Induction_Scheme]
      The Justification of the Induction Scheme

  [The_Proof_of_the_Associativity_of_App]
      The Proof of the Associativity of App

  [The_Q.E.D._Message]
      The Q.E.D. Message

  [The_Rules_used_in_the_Associativity_of_App_Proof]
      The Rules used in the Associativity of App Proof

  [The_Simplification_of_the_Induction_Conclusion_{Step_0}]
      The Simplification of the Induction Conclusion (Step 0)

  [The_Simplification_of_the_Induction_Conclusion_{Step_1}]
      The Simplification of the Induction Conclusion (Step 1)

  [The_Simplification_of_the_Induction_Conclusion_{Step_10}]
      The Simplification of the Induction Conclusion (Step 10)

  [The_Simplification_of_the_Induction_Conclusion_{Step_11}]
      The Simplification of the Induction Conclusion (Step 11)

  [The_Simplification_of_the_Induction_Conclusion_{Step_12}]
      The Simplification of the Induction Conclusion (Step 12)

  [The_Simplification_of_the_Induction_Conclusion_{Step_2}]
      The Simplification of the Induction Conclusion (Step 2)

  [The_Simplification_of_the_Induction_Conclusion_{Step_3}]
      The Simplification of the Induction Conclusion (Step 3)

  [The_Simplification_of_the_Induction_Conclusion_{Step_4}]
      The Simplification of the Induction Conclusion (Step 4)

  [The_Simplification_of_the_Induction_Conclusion_{Step_5}]
      The Simplification of the Induction Conclusion (Step 5)

  [The_Simplification_of_the_Induction_Conclusion_{Step_6}]
      The Simplification of the Induction Conclusion (Step 6)

  [The_Simplification_of_the_Induction_Conclusion_{Step_7}]
      The Simplification of the Induction Conclusion (Step 7)

  [The_Simplification_of_the_Induction_Conclusion_{Step_8}]
      The Simplification of the Induction Conclusion (Step 8)

  [The_Simplification_of_the_Induction_Conclusion_{Step_9}]
      The Simplification of the Induction Conclusion (Step 9)

  [The_Summary_of_the_Proof_of_the_Trivial_Consequence]
      The Summary of the Proof of the Trivial Consequence

  [The_Theorem_that_App_is_Associative]
      The Theorem that App is Associative

  [The_Time_Taken_to_do_the_Associativity_of_App_Proof]
      The Time Taken to do the Associativity of App Proof

  [The_Tours]
      The Tours

  [The_WARNING_about_the_Trivial_Consequence]
      The WARNING about the Trivial Consequence

  [Undocumented_Topic]
      Undocumented Topic

  [Using_the_Associativity_of_App_to_Prove_a_Trivial_Consequence]
      Using the Associativity of App to Prove a Trivial Consequence

  [What_Is_ACL2{Q}]
      What Is ACL2?

  [What_is_Required_of_the_User{Q}]
      What is Required of the User?

  [What_is_a_Mathematical_Logic{Q}]
      What is a Mathematical Logic?

  [What_is_a_Mechanical_Theorem_Prover{Q}]
      What is a Mechanical Theorem Prover?

  [What_is_a_Mechanical_Theorem_Prover{Q}_{cont}]
      What is a Mechanical Theorem Prover? (cont)

  [You_Must_Think_about_the_Use_of_a_Formula_as_a_Rule]
      You Must Think about the Use of a Formula as a Rule")
 (PAIRLIS
  (LISTS ALISTS)
  "See [pairlis$]

  The Common Lisp language allows its [47mpairlis[0m function to construct an
  alist without specifying a single order!  So we have to define our
  own version: See [pairlis$].")
 (PAIRLIS$
  (LISTS ALISTS ACL2-BUILT-INS)
  "Zipper together two lists

  The Common Lisp language allows its [47m[pairlis][0m function to construct
  an alist in any order!  So we have to define our own version,
  [47mpairlis$[0m.  It returns the list of pairs obtained by [47m[cons][0ming
  together successive respective members of the given lists until the
  first list runs out.  (Hence in particular, if the second argument
  is [47mnil[0m then each element of the first argument is paired with [47mnil[0m.)

  The [guard] for [47mpairlis$[0m requires that its arguments are true lists.

  [31;1mFunction: [0m<pairlis$>

    (defun pairlis$ (x y)
      (declare (xargs :guard (and (true-listp x) (true-listp y))))
      (mbe :logic (cond ((endp x) nil)
                        (t (cons (cons (car x) (car y))
                                 (pairlis$ (cdr x) (cdr y)))))
           :exec (pairlis$-tailrec x y nil)))")
 (PAIRLIS-X1
  (LISTS ALISTS ACL2-BUILT-INS)
  "Cons a given element to each member of a list

  The call [47m(pairlis-x1 x1 lst)[0m conses [47mx1[0m onto each element of the
  true-list, [47mlst[0m.")
 (PAIRLIS-X2
  (LISTS ALISTS ACL2-BUILT-INS)
  "Cons each element of a list with a given element

  The call [47m(pairlis-x2 lst x2)[0m creates an alist consing each element of
  [47mlst[0m, a true-list, with [47mx2[0m.")
 (PAND
  (PARALLEL-PROGRAMMING ACL2-BUILT-INS)
  "Parallel, Boolean version of [47m[and][0m

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism],
  and see [parallel-programming], which has a disclaimer.

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

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

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

  where [47mN >= 0[0m and each [47margi[0m and [47mexpr[0m are arbitrary terms.

  [47mPand[0m evaluates its arguments in parallel.  It returns a Boolean
  result: [47mnil[0m if any argument evaluates to [47mnil[0m, else [47mt[0m.  Note that
  [47mpand[0m always returns a Boolean result, even though [47mand[0m can return a
  non-[47mnil[0m value other than [47mt[0m, namely the value of its last argument.
  (A moment's reflection will make it clear that in order for [47m[por][0m
  to parallelize efficiently, it needs to return a Boolean value; so
  [47mpand[0m returns a Boolean value for consistency with [47m[por][0m.)

  Another difference between [47mpand[0m and [47m[and][0m is that for a call of [47mpand[0m,
  even if an argument evaluates to [47mnil[0m, a subsequent argument may be
  evaluated.  Consider the following example (where [47mcw[0m prints a
  string; see [cw]).

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

  When [47m(bar)[0m is evaluated, the above arguments of [47mpand[0m can execute in
  parallel, causing ``[47mhello world[0m'' to be printed to the terminal.
  If we had used [47mand[0m rather than [47mpand[0m, then since [47m(equal (make-list
  100000) nil)[0m evaluates to [47mnil[0m, the above call of [47m[cw][0m would be
  avoided and no such printing would take place.  Even with [47mpand[0m,
  such printing [3mmight[0m not take place, depending on resources, timing
  of thread creation, and whether or not parallel execution is
  enabled (see [set-parallel-execution]).

  Note that unlike the case for [47m[and][0m, the definition of [47mpand[0m does not
  provide [47m(consp x)[0m as a [guard] to [47m(car x)[0m in the call of [47mpand[0m
  below:

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

  As a result, [guard] verification will fail for the above definition.
  If [47mpand[0m were replaced by [47mand[0m, then [guard] verification would
  succeed.

  See [parallelism-tutorial] for another example.  Also see
  [parallelism-at-the-top-level] for restrictions on evaluating
  parallelism primitives from within the ACL2 top-level loop.
  Finally see [early-termination] to read how [47mpand[0m can offer more
  efficiency than [47m[and][0m by avoiding evaluation of some of its
  arguments.")
 (PARALLEL (PARALLELISM)
           "Evaluating forms in parallel

  See [parallelism].")
 (PARALLEL-EXECUTION
  (PARALLEL-PROGRAMMING)
  "For ACL2(p): configure parallel execution

  See [set-parallel-execution] for how to configure parallel execution
  for calls of [47m[plet][0m, [47m[pargs][0m, [47m[pand][0m, [47m[por][0m (but not
  [47m[spec-mv-let][0m).")
 (PARALLEL-PROGRAMMING
  (PARALLELISM)
  "Parallel programming in ACL2(p)

  Here we document support for parallel programming in ACL2(p), an
  experimental extension of ACL2; also see [parallelism].

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

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

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

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

  In addition to providing parallel programming primitives, ACL2(p)
  also provides the ability to execute the main ACL2 proof process in
  parallel.  See [set-waterfall-parallelism] for further details.

  [3mDisclaimer[0m.  The parallelism primitives have been designed for
  executing purely functional code, but some ACL2 functions do
  interesting things ``under the hood'' in order to achieve their
  effects.  For example, [hons] primitives such as [47m[hons-wash][0m may
  not have the intended effect when executed under the parallelism
  primitives.


Subtopics

  [Deflock]
      Define a wrapper macro that provides mutual exclusion in ACL2(p)

  [Early-termination]
      Early termination for [47m[pand][0m and [47m[por][0m.

  [Error-triples-and-parallelism]
      How to avoid error triples in ACL2(p)

  [Granularity]
      Limit the amount of parallelism

  [Pand]
      Parallel, Boolean version of [47m[and][0m

  [Parallel-execution]
      For ACL2(p): configure parallel execution

  [Parallelism-at-the-top-level]
      Parallel execution in the ACL2 top-level loop

  [Parallelism-performance]
      Performance issues for parallel execution

  [Parallelism-tutorial]
      A tutorial on how to use the parallelism library.

  [Pargs]
      Parallel evaluation of arguments in a function call

  [Plet]
      Parallel version of [47m[let][0m

  [Por]
      Parallel, Boolean version of [47m[or][0m

  [Spec-mv-let]
      Modification of [47m[mv-let][0m supporting speculative and parallel
      execution

  [With-output-lock]
      Provides a mutual-exclusion mechanism for performing output in
      parallel")
 (PARALLEL-PROOF
  (PARALLELISM)
  "Parallel proof in ACL2(p)

  Here we document support for parallel proof in ACL2(p), an
  experimental extension of ACL2; also see [parallelism], and for
  parallel programming in particular, see [parallel-programming].


Subtopics

  [ACL2p-key-checkpoints]
      Key checkpoints in ACL2(p)

  [Default-total-parallelism-work-limit]
      For ACL2(p): returns the default value for global
      [47mtotal-parallelism-work-limit[0m

  [Parallel-pushing-of-subgoals-for-induction]
      Consequences of how parallelized proofs of subgoals are pushed for
      induction

  [Unsupported-waterfall-parallelism-features]
      Proof features not supported with waterfall-parallelism enabled

  [Waterfall-parallelism]
      For ACL2(p): configuring the parallel execution of the waterfall

  [Waterfall-printing]
      For ACL2(p): configuring the printing within the parallelized
      waterfall")
 (PARALLEL-PUSHING-OF-SUBGOALS-FOR-INDUCTION
  (PARALLEL-PROOF)
  "Consequences of how parallelized proofs of subgoals are pushed for
  induction

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

  The following discussion, concerning the naming of subgoals pushed
  for proof by induction and the timeliness of aborting when two or
  more goals are pushed for proof by induction, only applies when
  waterfall parallelism is enabled (see [set-waterfall-parallelism]).

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

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

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

  This documentation topic relates to an experimental extension of
  ACL2, ACL2(p), created initially by David L. Rager.  See
  [compiling-ACL2p] for how to build an executable image that
  supports parallel execution.  Also see community books directory
  [47mbooks/parallel/[0m for examples.  For a completely different sort of
  parallelism, at the system level, see [provisional-certification].

  IMPORTANT NOTE.  We hope and expect that every evaluation result is
  correctly computed by ACL2(p), and that every formula proved using
  ACL2(p) is a theorem of the ACL2 logic (and in fact is provable
  using ACL2).  However, we do not guarantee these properties.  Since
  ACL2(p) is intended to be an aid in efficient evaluation and proof
  development, we focus less on ironclad soundness and more on
  providing an efficient and working implementation.  Nevertheless,
  if you encounter a case where ACL2(p) computes an incorrect result,
  or produces a proof where ACL2 fails to do so (and this failure is
  not discussed in [unsupported-waterfall-parallelism-features]),
  please notify the implementors.

  The ACL2 source code provides experimental parallel execution and
  proof capabilities.  For example, one of ACL2's strengths lies in
  its ability to simulate industrial models efficiently, and it can
  also decrease the time required for proofs about such models both
  by making use of parallel evaluation and by dispatching proof
  subgoals in parallel.

  While we aim to support Clozure Common Lisp (CCL), Steel Bank Common
  Lisp (SBCL), and Lispworks, SBCL and Lispworks both currently
  sometimes experience problems when evaluating the ACL2 proof
  process (the ``waterfall'') in parallel.  Therefore, CCL is the
  recommend Lisp for anyone that wants to use parallelism and isn't
  working on fixing those problems.


Subtopics

  [Compiling-ACL2p]
      Compiling ACL2(p)

  [Cpu-core-count]
      The number of cpu cores

  [Parallel]
      Evaluating forms in parallel

  [Parallel-programming]
      Parallel programming in ACL2(p)

  [Parallel-proof]
      Parallel proof in ACL2(p)

  [Parallelism-build]
      Building an ACL2 executable with parallel execution enabled

  [Set-parallel-execution]
      For ACL2(p): enabling parallel execution for four parallelism
      primitives

  [Set-total-parallelism-work-limit]
      For ACL2(p): set thread limit for parallelism primitives

  [Set-total-parallelism-work-limit-error]
      For ACL2(p): control the action taken when the thread limit is
      exceeded

  [Set-waterfall-parallelism]
      For ACL2(p): configuring the parallel execution of the waterfall

  [Set-waterfall-parallelism-hacks-enabled]
      For ACL2(p): enable waterfall-parallelism hacks

  [Set-waterfall-parallelism-hacks-enabled!]
      For ACL2(p): enabling waterfall parallelism hacks

  [Set-waterfall-printing]
      For ACL2(p): configuring the printing that occurs within the
      parallelized waterfall

  [Unsupported-parallelism-features]
      ACL2 features not supported in ACL2(p)

  [Waterfall-parallelism-for-book-certification]
      For ACL2(p): using waterfall parallelism during book certification")
 (PARALLELISM-AT-THE-TOP-LEVEL
  (PARALLEL-PROGRAMMING)
  "Parallel execution in the ACL2 top-level loop

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

  Calls of parallelism primitives made explicitly in the ACL2 top-level
  loop, as opposed to inside function bodies, will never cause
  parallel execution.  Such calls will either execute with serial
  execution or will cause an error; see [set-parallel-execution].
  For a way around this restriction, see [top-level].

  Consider for example the following call of [47m[pargs][0m in the ACL2
  top-level loop.  Instead of executing [47mpargs[0m, ACL2 macroexpands away
  this call, leaving us with serial execution of the arguments to the
  [47m[cons][0m call, or else causes an error (see
  [set-parallel-execution]).  If there is no error, then

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

  expands into:

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

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

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

  Then in an executable image that supports parallel execution --- see
  [compiling-ACL2p] for instructions on how to build such an
  executable --- [47m(expensive-fn-1 4)[0m and [47m(expensive-fn-2 5)[0m can
  evaluate in parallel.

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

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

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

  Note that [guard]s need not be verified in order to obtain [parallel]
  execution.  The only restrictions on parallel execution are to use
  an ACL2 executable supporting it, to avoid calling parallelism
  primitives directly in the top-level loop, to have sufficient
  resources (especially, threads) available, and to avoid explicitly
  disabling parallel execution (see [set-parallel-execution]).")
 (PARALLELISM-BUILD
  (PARALLELISM)
  "Building an ACL2 executable with parallel execution enabled

  See [compiling-ACL2p].")
 (PARALLELISM-PERFORMANCE
  (PARALLEL-PROGRAMMING)
  "Performance issues for parallel execution

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

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

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

    (include-book \"finite-set-theory/osets/sets\" :dir :system)
    (defun 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))))))))
    (defconst *x* (reverse (fromto 1 400000)))
    (time$ (length (set::pmergesort-exec *x* 0)))
    (set-parallel-execution nil)
    (time$ (length (set::pmergesort-exec *x* 0)))")
 (PARALLELISM-TUTORIAL
  (PARALLEL-PROGRAMMING)
  "A tutorial on how to use the parallelism library.

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

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

  [31;1mSerial Fibonacci[0m

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

  [31;1mIntroducing[0m [47m[Pargs][0m

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

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

  [31;1mIntroducing the Granularity Problem[0m

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

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

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

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

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

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

  [31;1mExplicit Programming for the Granularity Problem[0m

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

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

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

    (declare (granularity <form>))

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

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

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

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

  [31;1mAnother Granularity Issue Related to Thread Limitations[0m

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

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

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

  [31;1mIntroducing[0m [47m[Plet][0m

  We can use a [47m[let][0m binding to compute the recursive calls of [47mfib[0m and
  then add the bound variables together, as follows.

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

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

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

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

  [31;1mIntroducing[0m [47m[Pand][0m (By Way of a Tree Validation Example)

  Consider ``genetic trees'' that contains leaves of DNA elements, in
  the sense that each tip is one of the symbols [47mA[0m, [47mG[0m, [47mC[0m, or [47mT[0m.  First
  we define the function [47mvalid-tip[0m which recognizes whether a tip
  contains one of these symbols.

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

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

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

  We also define a parallel version.

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

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

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

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

  We can time our functions with the forms:

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

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

  [31;1mDemonstrating Early Termination with an Invalid Tree[0m

  Now observe this magic:

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

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

  [31;1mGranularity with[0m [47m[Pand][0m

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

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

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

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

  [31;1mIntroducing[0m [47m[Por][0m

  [47m[Por][0m can be used in the same way as [47m[pand][0m, but with early
  termination occurring when an argument evaluates to a non-[47mnil[0m
  value, in which case the value returned is [47mt[0m.  Finally, [47m[por][0m also
  supports the use of a [granularity] form.")
 (PARGS
  (PARALLEL-PROGRAMMING ACL2-BUILT-INS)
  "Parallel evaluation of arguments in a function call

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism],
  and see [parallel-programming], which has a disclaimer.

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

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

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

  where [47mN >= 0[0m and each [47margi[0m and [47mexpr[0m are arbitrary terms.  Logically,
  [47mpargs[0m is just the identity macro, in the sense that the above forms
  can logically be replaced by [47m(f arg1 ... argN)[0m.  However, this
  [47mpargs[0m form may parallelize the evaluation of arguments [47marg1[0m through
  [47margN[0m before applying function [47mf[0m to those results.  If the above
  [47m[granularity][0m declaration is present, then its expression ([47mexpr[0m
  above) is first evaluated, and if the result is [47mnil[0m, then such
  parallelism is avoided.  Even if parallelism is not thus avoided,
  parallelism may be limited by available resources.

  Since macros can change expressions in unexpected ways, it is illegal
  to call [47mpargs[0m on a form that is a macro call.  To parallelize
  computation of arguments to a macro, see [plet].

  See [parallelism-at-the-top-level] for restrictions on evaluating
  parallelism primitives from within the ACL2 top-level loop.")
 (PARTIAL-ENCAPSULATE
  (EVENTS ENCAPSULATE)
  "Introduce functions with some constraints unspecified

  See [encapsulate] for relevant background.  [47mPartial-encapsulate[0m is a
  variant of [47mencapsulate[0m for which some of the constraints are
  implicit.  This is an advanced capability that is useful when one
  installs special-purpose code, possibly in raw Lisp, using a trust
  tag (see [defttag]).


Introduction

  The syntax for [47mpartial-encapsulate[0m is the same as the syntax of
  [47mencapsulate[0m, except for the addition of an argument, [47msupporters[0m,
  which is described below.

    General Form:
    (partial-encapsulate (signature ... signature)
      (f1 ... fk) ; supporters
      ev1
      ...
      evn)

  where, as for [47mencapsulate[0m: each [47msignature[0m is a well-formed
  [signature], each describing a different function symbol, and each
  [47mevi[0m is an embedded event form (see [embedded-event-form]).  The
  additional argument (shown above) is a true-list of function
  symbols, the [3msupporters[0m: it is an error if any such symbol, [47mfi[0m, is
  not a known function symbol at the time the [47mpartial-encapsulate[0m
  call is evaluated, the exception being that [47mfi[0m may be introduced in
  one of the signatures.  A [47mpartial-encapsulate[0m form must satisfy the
  following three requirements in addition to those of the
  corresponding [47mencapsulate[0m form: it must have at least one
  signature, it must not occur within any other [47mencapsulate[0m or
  [47mpartial-encapsulate[0m form that has at least one signature, and every
  function symbol that it introduces must be specified in one of the
  signatures.

  A call of [47mpartial-encapsulate[0m introduces its signature functions
  together with its exported theorems, exactly as though it had been
  the call of [47mencapsulate[0m with the same signatures and events,
  however with one difference: the [47mpartial-encapsulate[0m logically
  incorporates additional constraints that are not mentioned.  This
  is discussed further below, but for now let us note that because of
  this difference, a successful evaluation of a [47mpartial-encapsulate[0m
  form results in a special ``unknown-constraints'' designation for
  the functions introduced by the signatures.  Any attempt to access
  the constraints for those functions will thus fail.  Consider the
  following example, which introduces [47mf[0m as a constrained function
  symbol that is constrained not only by the property that [47mf[0m returns
  a boolean, but also by additional, unspecified (implicit)
  constraints.

    (partial-encapsulate
     ((f (x) t))
     nil
     (local (defun f (x) (declare (xargs :guard t)) (consp x)))
     (defthm booleanp-f
       (booleanp (f x))
       :rule-classes :type-prescription))

    (defthm symbolp-f
      (symbolp (f y)))

    (encapsulate
     ((g (x) t))
     (local (defun g (x) (consp x)))
     (defthm booleanp-g (booleanp (g x))))

  Then the following fails, even though it would succeed if we replace
  [47mpartial-encapsulate[0m by [47mencapsulate[0m above.  The reason is that the
  partial-encapsulate form allows for constraints beyond just the
  property that [47mf[0m is boolean.  Imagine that special code had been
  inserted (using a trust tag) for reasoning about [47mf[0m when proving a
  theorem like [47msymbolp-f[0m that we were now trying to functionally
  instantiate.

    ; Functional instantiation FAILS because of unknown-constraints on f
    (defthm symbolp-g
      (symbolp (g y))
      :hints ((\"Goal\" :by (:functional-instance symbolp-f (f g)))))


Supporters and corresponding encapsulate

  A [47mpartial-encapsulate[0m represents any [47mencapsulate[0m form that introduces
  the same function symbols, has the same signatures, and extends the
  constraints introduced such that every function symbol occurring in
  at least one of the additional constraints must either be mentioned
  in one of the [47mevi[0m or be among the list of supporters, [47m(f1 ... fk)[0m.
  We may refer to such an [47mencapsulate[0m form as a ``corresponding
  encapsulate''.  The user of [47mpartial-encapsulate[0m should keep in mind
  such a set of additional constraints.  The supporters should thus
  include all function symbols in the theorems exported from the
  intended corresponding encapsulate, except that signature functions
  are always included among the supporters whether specified or not,
  and hence their inclusion is optional.

  The list of supporters is used for generating proof obligations for a
  [47m:functional-instance[0m [lemma-instance].  Specifically, the
  supporters serve as the ``ancestors'' of the partial encapsulate's
  signature functions, in the constraint-generation algorithm
  described in the documentation for [constraint].  Thus, if
  supporters are missing that occur in the intended corresponding
  encapsulate, then functional instantiation may be unsound because
  some proof obligations fail to be generated.  Note that in the
  typical application described next, where the implicit constraints
  all specify evaluation results for calls of signature functions as
  discussed below, the specified list of supporters can simply be
  [47mnil[0m.


Applications

  A trust tag (see [defttag]) is not needed for evaluation of a
  partial-encapsulate form.  However, for a typical application of
  partial-encapsulate --- redefinition of a constrained function in
  raw Lisp --- a trust tag is of course necessary (see [defttag]).
  In such a case, the corresponding encapsulate may be viewed as
  extending the original partial-encapsulate with all theorems of the
  form [47m(equal (f a1 ... ak) val)[0m, ranging over all computations [47m(f a1
  ... ak)[0m ever to be evaluated (a finite but potentially huge set)
  where [47mval[0m is the value returned for [47m(f a1 ... ak)[0m.  It is the
  responsibility of the creator of such an application to ensure that
  all evaluations satisfy the original constraints of the
  partial-encapsulate.

  Note that in this sort of application --- that is, where the implicit
  constraints all arise from function evaluations --- the supporters
  argument may soundly be [47mnil[0m, since only the signature functions are
  involved in the implicit constraints (and those functions are
  automatically included among the supporters, even when not
  specified by the user).

  For examples of such an application, including explanatory comments,
  see [community-books] and [47mbooks/demos/partial-encapsulate.lisp[0m and
  [47mbooks/demos/include-raw-examples/mem-access-sound/mem.lisp[0m.

  Partial-encapsulates are, in essence, also used in the implementation
  of dependent clause-processors, where the list of supporters might
  well be non-[47mnil[0m.  See [define-trusted-clause-processor].


Implementation

  This section is provided as a reference for those interested, but can
  probably be safely skipped by most readers.

  Consider the following example.

    ACL2 !>:trans1 (partial-encapsulate
                    ((f0 (x) t))
                    (g0)
                    (local (defun f0 (x) x))
                    (defthm f0-prop
                      (implies (integerp x)
                               (integerp (f0 x)))))
     (ENCAPSULATE ((F0 (X) T))
                  (LOCAL (DEFUN F0 (X) X))
                  (DEFTHM F0-PROP
                          (IMPLIES (INTEGERP X)
                                   (INTEGERP (F0 X))))
                  (SET-UNKNOWN-CONSTRAINTS-SUPPORTERS G0))
    ACL2 !>

  This example illustrates that a [47mpartial-encapsulate[0m call expands to a
  call of [47mencapsulate[0m obtained by removing the supporters argument,
  but with the following extra event inserted after given list of
  events, where [47m(f1 ... fk)[0m is the specified list of supporters.

    (set-unknown-constraints-supporters f1 ... fk)

  The macro, [47mset-unknown-constraints-supporters[0m, extends a table,
  [47munknown-constraints-table[0m.  As evaluation of the
  partial-encapsulate concludes, the world is extended so that each
  signature function has a [47m'constraint-lst[0m property indicating that
  its constraints are unknown, but with supporters (``ancestors'', as
  discussed above) according to that table.  This macro call can thus
  be inserted non-[local]ly within an encapsulate, anywhere after the
  local function definitions, to make an encapsulate behave like a
  partial-encapsulate.")
 (PARTITION-REST-AND-KEYWORD-ARGS (POINTERS)
                                  "See [system-utilities].")
 (PATHNAME
  (BOOKS-REFERENCE)
  "Introduction to filename conventions in ACL2

  The notion of pathname objects from Common Lisp is not supported in
  ACL2, nor is the function [47mpathname[0m.  However, ACL2 supports file
  operations, using conventions for naming files based on those of
  the Unix (trademark of AT&T) operating system, so that the
  character [47m/[0m is used to terminate directory names.  Some file names
  are ``absolute'' (complete) descriptions of a file or directory;
  others are ``relative'' to the current working directory or to the
  connected book directory.  See [cbd] for how relative pathnames are
  elaborated to absolute pathnames.  We emphasize that even for users
  of Windows-based systems or Macintosh computers, ACL2 file names
  are in the Unix style.  We will call these [3mACL2 pathnames[0m, often
  omitting the ``ACL2.''

  Pathnames starting with the directory separator ([47m/[0m) or the tilde
  character ([47m~[0m) are absolute pathnames.  All other pathnames are
  relative pathnames.  An exception is in the Microsoft Windows
  operating system, where it is illegal for the pathname to start
  with a tilde character but the drive may be included, e.g.,
  [47m\"c:/home/smith/acl2/book-1.lisp\"[0m.  In fact, the drive [3mmust[0m be
  included in the portcullis of a book; see [portcullis].  Note also
  that some host Common Lisps will not support pathnames starting
  with [47m\"~\"[0m, for example [47m~smith[0m, though ACL2 will generally support
  those starting with [47m\"~/\"[0m regardless of the host Common Lisp.

  Consider the following examples.  The filename string

    \"/home/smith/acl2/book-1.lisp\"

  is an absolute pathname, with top-level directory [47m\"home\"[0m, under that
  the directory [47m\"smith\"[0m and then the directory [47m\"acl2\"[0m, and finally,
  within that directory the file [47m\"book-1.lisp\"[0m.  If the connected
  book directory is [47m\"/home/smith/\"[0m (see [cbd]), then the filename
  string above also corresponds to the relative filename string
  \"acl2/book1.lisp\".

  Finally, we note that (on non-Windows systems) the pathname [47m\"~\"[0m and
  pathnames starting with [47m\"~/\"[0m are illegal in books being certified.
  Otherwise, a subsidiary [47m[include-book][0m form would have a different
  meaning at certification time than at a later time when the
  certified book is included by a different user.")
 (PATTERNED-CONGRUENCE
  (RULE-CLASSES)
  "Removing restrictions on classic [congruence] rules

  This topic assumes familiarity with the basics of congruence rules;
  see [congruence].  Some aspects of congruence rules carry over to
  patterned congruence rules; in particular, they may be [disable]d,
  but they are not tracked for reporting in the [summary].

  We begin our discussion by showing some patterned congruence rules
  and using them to illustrate some terminology.

    Example forms:

    ; ``Shallow'' patterned congruence rule:
    (implies (e1 y1 y2)
             (e2 (f1 3 y1 (cons x x))
                 (f1 3 y2 (cons x x))))

    ; ``Deep'' patterned congruence rule:
    (implies (e1 y1 y2)
             (e2 (mv-nth 1 (foo x y1 z))
                 (mv-nth 1 (foo x y2 z))))

    ; ``Deep'' patterned congruence rule:
    (implies (e1 y1 y2)
             (e2 (mv-nth 1 (foo x (g y1) z))
                 (mv-nth 1 (foo x (g y2) z))))

  In the example forms above, [47me1[0m and [47me2[0m are known equivalence
  relations, which (as for classic congruence rules) we call the
  ``inner'' and ``outer'' equivalences.  The examples above are not
  classic, because the ``function symbol'' of the rule --- [47mf1[0m in the
  first example, [47mmv-nth[0m in the second and third examples --- is not
  being applied to distinct variables.  The first example is called
  ``shallow'' because the ``variable'' of the rule, [47my1[0m, is a
  top-level argument of the ``lhs'' of the rule, which is the first
  call of [47mf1[0m; the others do not have this property, as [47my1[0m is buried
  under further function calls.

  We invite you to browse the community book
  [47mdemos/patterned-congruences.lisp[0m, which provides several examples
  of patterned congruence rules and their use, as well as several
  examples of formulas that are illegal as patterned congruence rules
  for various reasons.

  We now define the class of patterned congruence rules.  The general
  form of a patterned congruence rule is

    (implies (equiv1 x y)
             (equiv2 lhs rhs)),

  where the rule is not classic (see [congruence]) and the following
  conditions hold.  [47mEquiv1[0m and [47mequiv2[0m are known equivalence
  relations, which (as in the classic case) we call the ``inner'' and
  ``outer'' equivalences, respectively.  The terms [47mlhs[0m and [47mrhs[0m are
  function calls, and we call these the [47mlhs[0m and [47mrhs[0m of the rule,
  respectively.  The variable [47mx[0m occurs in [47mlhs[0m and the variable [47my[0m
  occurs in [47mrhs[0m.  These must be the only occurrences of [47mx[0m and [47my[0m in
  either [47mlhs[0m or [47mrhs[0m, and [47mrhs[0m must be the result of substituting [47my[0m for
  [47mx[0m in [47mlhs[0m.  None of the following may occur as a function symbol of
  [47mlhs[0m (or, equivalently, [47mrhs[0m): [47mif[0m, [47mimplies[0m, [47mequal[0m, or a [47m[lambda][0m.

  Patterned congruence rules are used, much like classic congruence
  rules, by the ACL2 rewriter to determine which equivalence
  relations to maintain as it dives into a term.  Recall (see
  [congruence]) that if it suffices for the rewriter to maintain [47me2[0m
  when rewriting a term, then it suffices to maintain [47me1[0m when
  rewriting an argument of that term provided there is an applicable
  congruence rule with outer equivalence [47me2[0m and inner equivalence [47me1[0m.
  An analogous principle holds for patterned congruence rules, which
  by the way consider refinements of the outer equivalence just as is
  done by classic congruence rules.  But there is a new wrinkle
  because the lhs of a patterned congruence rule is a function call
  that can have non-variable arguments.  Consider the following
  events.

    (defun e1 (x y)
      (equal x y))

    (defequiv e1)

    (defun f10 (x)
      (list 3 x x))

    (defun f11 (x y)
      (declare (ignore y))
      x)

    (defthm e1-implies-iff-f11-cong-2
      (implies (e1 y1 y2)
               (iff (f11 (f10 x) y1)
                    (f11 (f10 x) y2)))
      :rule-classes (:congruence))

    (in-theory (disable f11 (:t f11) e1))

  The following proof fails, because the indicated call of [47mf10[0m expands
  before the rewriter is applied to [47mb2[0m --- otherwise [47mb2[0m would rewrite
  to [47mb1[0m because [47m(e1 b1 b2)[0m is known in that context and by the rule
  above, it suffices to maintain [47me1[0m when rewriting [47mb2[0m.

    (thm (implies (e1 b1 b2)
                  (iff (f11 (f10 a)
                            b1)
                       (f11 (f10 a) ; expands before b2 is rewritten
                            b2))))

  On the other hand, the following succeeds because the rewrite
  discussed above does indeed take place when the indicated call of
  [47mf10[0m does not expand.

    (thm
      (implies (e1 b1 b2)
               (iff (f11 (f10 a)
                         b1)
                    (f11 (f10 a) ; does not expand
                         b2)))
      :hints ((\"Goal\" :in-theory (disable f10))))

  This inherent sequentiality of matching is important for soundness,
  as is illustrated by examples using the function [47msome-consp[0m in the
  aforementioned community book, [47mdemos/patterned-congruences.lisp[0m.

  The example above illustrates the following point: as the rewriter
  dives into a term, then when matching is attempted using a
  patterned congruence rule, rewriting has already taken place to the
  left of the current subterm.  By contrast, note that this pass
  through the rewriter will not yet have completed rewriting of terms
  to the right of the current subterm when matching a patterned
  congruence rule.

  Patterned congruence rules are used primarily during the process of
  [3mrewriting[0m.  In particular, unlike classic congruence rules, they
  are [3mnot[0m used to do equality substitution at the goal level or in
  [proof-builder] commands such as [47m=[0m and [47mequiv[0m.  The simplest way to
  understand this point may be with the following trivial example.

    (defstub foo (x y z) t)

    (thm (implies (equal u (* a b))
                  (foo u u b)))

  The theorem fails, of course, but what is interesting is that ACL2
  simplifies it by replacing the variable [47mu[0m by the term [47m(* a b)[0m
  throughout the goal and then dropping the equality, to produce the
  following goal.

    (FOO (* A B) (* A B) B)

  This sort of substitution can also be made when [47mequal[0m is replaced by
  a known equivalence relation, if a classic congruence rule for [47mfoo[0m
  justifies the substitution.  But that is not the case for our
  implementation of patterned congruence rules.

  The discussion above is intended to suffice for effective use of
  patterned congruence rules.  If you are interested in their
  [3mimplementation[0m, we invite you to read the long comment entitled
  ``Essay on Patterned Congruences and Equivalences'' in ACL2 source
  file [47mrewrite.lisp[0m.")
 (PBT
  (HISTORY)
  "Print the [command]s back through a [command] descriptor

    Examples:
    :pbt :max      ; print back through the most recent command
    :pbt :x        ; print back through the most recent command
    :pbt fn        ; print back through the introduction of fn
    :pbt 5         ; print back through the fifth command executed
    :pbt (:x -4)   ; print back through the most recent five commands

  See [command-descriptor].

  [47mPbt[0m takes one argument, a [command] descriptor, and prints the
  [command]s from [47m:max[0m (aka [47m:x[0m) through the one described.  See
  [command-descriptor] for a description of what a [command]
  descriptor is.  See [pc] for a description of the format used to
  display [command]s.  [47mPbt[0m will print the [command]s that [47m[ubt][0m will
  undo.")
 (PC
  (HISTORY)
  "Print the [command] described by a [command] descriptor

    Examples:
    :pc 3    ; print the third command executed
    :pc :max ; print the most recent command
    :pc :x   ; print the most recent command
    :pc fn   ; print the command that introduced fn

  See [command-descriptor].

  [47mPc[0m takes one argument, a [command] descriptor, and prints the
  [command] identified by that descriptor, doing so in full unless
  the [ld-evisc-tuple] is non-nil, in which case it abbreviates using
  that evisc-tuple; see [evisc-tuple].  See [command-descriptor].
  For example:

    ACL2 !>:pc foo
     LVd     52 (DEFUN FOO (X) X)

  [47mPc[0m always prints a space first, followed by four (possibly blank)
  characters (``LVd'' above) explained below.  Then [47mpc[0m prints the
  [command] number, a number uniquely identifying the [command]'s
  position in the sequence of [command]s since the beginning of the
  user's session.  Finally, the [command] itself is printed.

  While [47mpc[0m always prints a space first, some [history] [command]s, for
  example [47m:[0m[47m[pcs][0m and [47m:[0m[47m[pe][0m, use the first column of output to delimit
  a region of [command]s or to point to a particular event (perhaps
  as modified using [47m[extend-pe-table][0m) within a [command].

  For example, [47m:pcs 52 54[0m will print something like

    /LVd     52 (DEFUN FOO (X) X)
     LV      53 (DEFUN BAR (X) (CONS X X))
    \\        54 (DEFTHM FOO-BAR (EQUAL (CAR (BAR X)) (FOO X)))
              : ...
            127 (DEFUN LATEST (X) X)

  Here, the two slash characters in the first column are intended to
  suggest a bracket delimiting [command]s 52 through 54.  The last
  [command] printed by [47m[pcs][0m is always the most recent [command],
  i.e., the [command] at [47m:here[0m, and is separated from the rest of the
  display by an ellipsis if some [command]s are omitted.

  Similarly, the [47m:[0m[47m[pe][0m [command] will print a particular event (perhaps
  as modified using [47m[extend-pe-table][0m) within a [command] block and
  will indicate that event by printing a ``[47m[>][0m'' in the first column.
  The symbol is intended to be an arrow pointing at the event in
  question.

  For example, [47m:[0m[47m[pe][0m [47mtrue-listp-app[0m might print:

             1 (INCLUDE-BOOK \"list-book\")
                \\
    >           (DEFTHM TRUE-LISTP-APP
                        (EQUAL (TRUE-LISTP (APP A B)) (TRUE-LISTP B)))

  using the arrow to indicate the event itself.  The slash printed to
  connect the [command], [47m[include-book][0m, with the event, [47m[defthm][0m, is
  intended to suggest a tree branch indicating that the event is
  inferior to (and part of) the [command].

  The mysterious characters sometimes preceding a [command] have the
  following interpretations.  The first two have to do with the
  function symbols introduced by the [command] and are blank if no
  symbols were introduced.

  At any time we can classify our function symbols into disjoint sets,
  which we will here name with characters.  The ``[47mP[0m'' functions are
  those in [47m:[0m[47m[program][0m mode.  The ``[47mL[0m'' functions are those in
  [47m:[0m[47m[logic][0m mode whose [guard]s have not been verified.  The ``[47mV[0m''
  functions are those in [47m:[0m[47m[logic][0m mode whose [guard]s have been
  verified.  You may also see the use of (lower-case) ``[47mv[0m'' to
  indicate functions introduced by [47m[encapsulate][0m.  Note that
  [47m[verify-termination][0m and [47m[verify-guards][0m cause function symbols to
  be reclassified.  If a [command] introduces function symbols then
  the first mysterious character indicates the class of the symbols
  at the time of introduction and the second character indicates the
  current class of the symbols (if the current class is different
  from the introductory class).

  Thus, the display

    PLd     52 (DEFUN FOO (X) X)

  tells us that [command] 52 introduced a [47m:[0m[47m[program][0m function but that
  some [command] after 52 changed its mode to [47m:[0m[47m[logic][0m and that the
  [guard]s of [47mfoo[0m have not been verified.  That is, [47mfoo[0m's termination
  has been verified even though it was not verified as part of the
  [command] that introduced [47mfoo[0m.  Had a subsequent [command] verified
  the [guard]s of [47mfoo[0m, the display would contain a [47mV[0m where the [47mL[0m is.

  The display

    P d     52 (DEFUN FOO (X) X)

  indicates that [47mfoo[0m was introduced in [47m:[0m[47m[program][0m mode and still is in
  that mode.

  The third character indicates the [enable]d/[disable]d status of the
  [rune]s introduced by the [command].  If the status character is
  blank then all the [rune]s (if any) introduced are [enable]d.  If
  the status character is ``[47mD[0m'' then some [rune]s were introduced and
  they are all [disable]d.  If the status character is ``[47md[0m'' then at
  least one, but not all, of the [rune]s introduced is [disable]d.
  Thus, in the display

    L d     52 (DEFUN FOO (X) X)

  we see that some [rune] introduced by [command] 52 is [disable]d.  As
  noted in the documentation for [rune], a [47m[defun][0m [command]
  introduces many [rune]s, e.g., the axiomatic definition rule,
  [47m(:definition fn)[0m, the executable-counterpart rule,
  [47m(:executable-counterpart fn)[0m, and [type-prescription]s,
  [47m(:type-prescription fn)[0m.  The display above does not say which of
  the [rune]s based on [47mfoo[0m is [disable]d, but it does tell us one of
  them is; see [disabledp] for how to obtain the disabled runes for a
  given function symbol.

  Remark for users of the [break-rewrite] utility.  Inside the [47m:[0m[47m[brr][0m
  loop, the status character shows whether rules are disabled at the
  current point of the proof that is currently underway, rather than
  whether rules are disabled globally.  For example, if you break
  while the prover is working on Subgoal 3, and the [hints] supplied
  for the proof specify [47m(\"Subgoal 3\" :in-theory (disable foo))[0m, then
  regardless of whether or not rules associated with [47mfoo[0m are enabled
  globally, the status character indicates whether they are enabled
  while processing Subgoal 3.

  Finally, a fourth character is printed, indicating whether functions
  are [memoize]d.  A symbol may be memoized if it is a function
  symbol that is not constrained (i.e., introduced by [47m[defchoose][0m or
  in the [signature] of an [47m[encapsulate][0m event).  If the command
  introduces no symbol that may be memoized, then a space is printed.
  Otherwise, if every memoizable symbol is memoized, an ``[47mM[0m'' is
  printed.  Otherwise, an ``[47mm[0m'' is printed.")
 (PCB
  (HISTORY)
  "Print the [command] block described by a [command] descriptor

    Examples:
    :pcb :max ; print the most recent command block
    :pcb :x   ; print the most recent command block
    :pcb fn   ; print the command block that introduced fn
    :pcb 5    ; print the fifth command block

  See [command-descriptor].

  [47mPcb[0m takes one argument, a [command-descriptor], and prints in an
  abbreviated format the [command] block of the command described.
  See [pc] for description of the format in which [command]s are
  displayed.  The command block of a command consists of the command
  itself and all of the [events] it created.  If the command created
  a single event and that event is in fact the command (i.e., if the
  command typed was just an event such as a [47m[defun][0m or [47m[defthm][0m
  rather than a macro that expanded to some event forms), then [47mpcb[0m
  just prints the command (unless the event is replaced using
  [47m[extend-pe-table][0m).  [47mPcb[0m sketches the command and all of the
  [events] it created, rather than printing them fully.  If you wish
  to see just the command, in its entirety, use [47m[pc][0m.  If you wish to
  see one of the [events] within the block, in its entirety, use
  [47m[pe][0m.  If you wish to see the command sketched and all of the
  events it created, in their entirety, use [47m[pcb!][0m.  For a sequence
  of commands, see [pcs] and [gcs].")
 (PCB!
  (HISTORY)
  "Print in full the [command] block described by a [command] descriptor

    Examples:
    :pcb! :max ; print the most recent command block
    :pcb! :x   ; print the most recent command block
    :pcb! fn   ; print the command block that introduced fn
    :pcb! 5    ; print the fifth command block

  See [command-descriptor].

  [47mPcb![0m takes one argument, a [command] descriptor, and prints the
  [command] block of the [command] described.  Unlike [47m[pcb][0m, [47mpcb![0m
  prints the event forms in full (see [pcb] for details) --- unless
  the [ld-evisc-tuple] is non-nil, in which case it abbreviates using
  that evisc-tuple; see [evisc-tuple].")
 (PCS
  (HISTORY)
  "Print the sequence of [command]s between two [command] descriptors

    Examples:
    :pcs 1 5              ; print commands 1 through 5
    :pcs 5 1              ; same as above
    :pcs :x (:x -3)       ; print the 3 most recently executed commands
    :pcs fn assoc-of-fn   ; print the commands between the one that introduced
                          ; fn and the one that introduced assoc-of-fn

  [47mPcs[0m takes two arguments, both of which are [command] descriptors, and
  prints the [command]s between them with [47m[pc][0m.  The order of the two
  descriptors is irrelevant.  See [command-descriptor] for a
  description of [command] descriptors.  See [pc] for a description
  of the format in which [command]s are displayed.

  For a related utility that simply returns a sequence of commands, see
  [get-command-sequence].")
 (PE
  (HISTORY)
  "Print the events named by a logical name

    Example:
    :pe fn   ; sketches the command that introduced fn and
             ; prints in full the event within it that created fn.

  See [logical-name].

  [47mPe[0m takes one argument, a logical name, and prints the event
  corresponding to the name, doing so in full unless the
  [ld-evisc-tuple] is non-nil, in which case it abbreviates using
  that evisc-tuple; see [evisc-tuple].  [47mPe[0m also sketches the
  [command] responsible for that event if the [command] is different
  from the event itself.  To remind you that the event is inferior to
  the [command], i.e., you can only undo the entire [command], not
  just the event, the event is indented slightly from the [command]
  and a slash (meant to suggest a tree branch) connects them.

  See [pc] for a description of the format used to display a [command].

  If the given logical name corresponds to more than one event, then
  [47m:pe[0m will print the above information for every such event.  Here is
  an example of such behavior.

    ACL2 !>:pe nth
          -4270  (ENCAPSULATE NIL ...)
                 \\
    >V            (VERIFY-TERMINATION NTH)

    Additional events for the logical name NTH:
     PV   -4949  (DEFUN NTH (N L)
                        \"Documentation available via :doc\"
                        (DECLARE (XARGS :GUARD (AND (INTEGERP N)
                                                    (>= N 0)
                                                    (TRUE-LISTP L))))
                        (IF (ENDP L)
                            NIL
                            (IF (ZP N)
                                (CAR L)
                                (NTH (- N 1) (CDR L)))))
    ACL2 !>

  If you prefer to see only the formula for the given name, for example
  if it is part of a large [47m[mutual-recursion][0m, see [pf].

  See [extend-pe-table] for a way to specify a form to be printed in
  place of the actual event.  To avoid such replacement, see [pe!].")
 (PE!
  (HISTORY)
  "Print events as with [47m[pe][0m but ignoring the [pe-table]

  This alternative to [47m[pe][0m temporarily clears the [pe-table] so that
  original [events] are displayed.")
 (PE-TABLE (POINTERS)
           "See [extend-pe-table].")
 (PEEK-CHAR$ (POINTERS) "See [io].")
 (PERHAPS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Perhaps

  The theorem prover's proof is printed in real time.  At the time it
  prints ``Perhaps'' it does not know the proof will succeed.")
 (PERSISTENT-WHS (POINTERS)
                 "See [wormhole-status].")
 (PF
  (HISTORY)
  "Print the formula corresponding to the given name

    Examples:
    :pf (:definition fn) ; prints the definition of fn as an equality
    :pf fn               ; same as above
    :pf (:rewrite foo)   ; prints the statement of the rewrite rule foo
    :pf foo              ; same as above
    :pf (:induction foo) ; prints the induction scheme associated with foo

  [47mpf[0m takes one argument, an event name or a [rune], and prints the
  formula associated with name.  If the argument is the name of a
  macro associated with a function name by [macro-aliases-table],
  then the function name is used as the argument.  If the argument
  names an [47m:[0m[47m[induction][0m rule, then the corresponding induction scheme
  is printed.")
 (PKG-IMPORTS
  (PACKAGES)
  "List of symbols imported into a given package

  Completion Axiom ([47mcompletion-of-pkg-imports[0m):

    (equal (pkg-imports x)
           (if (stringp x)
               (pkg-imports x)
             nil))

  [Guard] for [47m(pkg-imports x)[0m:

    (stringp x)

  [47m(Pkg-imports pkg)[0m returns a duplicate-free list of all symbols
  imported into [47mpkg[0m, which should be the name of a package known to
  ACL2.  For example, suppose [47m\"MY-PKG\"[0m was created by

    (defpkg \"MY-PKG\" '(ACL2::ABC LISP::CAR)).

  Then [47m(pkg-imports \"MY-PKG\")[0m equals the list [47m(ACL2::ABC LISP::CAR)[0m.

  If [47mpkg[0m is not a string, then [47m(pkg-imports pkg)[0m is [47mnil[0m.  If [47mpkg[0m is a
  string but not the name of a package known to ACL2, then the value
  of the form [47m(pkg-imports pkg)[0m is unspecified, and its evaluation
  will fail to yield a value.  By ``the symbols imported into [47mpkg[0m''
  we mean the symbols imported into [47mpkg[0m by the [47m[defpkg][0m event that
  introduced [47mpkg[0m.  There are no imports for built-in packages except
  for the [47m\"ACL2\"[0m package, which imports the symbols in the list value
  of the constant [47m*common-lisp-symbols-from-main-lisp-package*[0m.  In
  particular, this is the case for the [47m\"COMMON-LISP\"[0m package.  Users
  familiar with Common Lisp may find this surprising, since in actual
  Common Lisp implementations it is often the case that many symbols
  in that package are imported from other packages.  However, ACL2
  treats all symbols in the constant
  [47m*common-lisp-symbols-from-main-lisp-package*[0m as having a
  [47m[symbol-package-name][0m of [47m\"COMMON-LISP\"[0m, as though they were not
  imported.  ACL2 admits a symbol imported into in the [47m\"COMMON-LISP\"[0m
  package only if it belongs to that list: any attempt to read any
  other symbol imported into the [47m\"COMMON-LISP\"[0m package, or to produce
  such a symbol with [47m[intern$][0m or [47m[intern-in-package-of-symbol][0m, will
  cause an error.

  The following axioms formalize properties of [47mpkg-imports[0m discussed
  above (use [47m:[0m[47m[pe][0m to view them).

    symbol-package-name-intern-in-package-of-symbol
    intern-in-package-of-symbol-is-identity
    symbol-listp-pkg-imports
    no-duplicatesp-pkg-imports
    completion-of-pkg-imports")
 (PKG-WITNESS
  (PACKAGES ACL2-BUILT-INS)
  "Return a specific symbol in the indicated package

  For any string [47mpkg[0m that names a package currently known to ACL2,
  [47m(pkg-witness pkg)[0m is a symbol in that package whose [47m[symbol-name][0m
  is the value of constant [47m*pkg-witness-name*[0m.  Logically, this is
  the case even if the package is not currently known to ACL2.
  However, if [47mpkg-witness[0m is called on a string that is not the name
  of a package known to ACL2, a hard Lisp error will result.

  [47m(Pkg-witness pkg)[0m has a guard of [47m(and (stringp pkg) (not (equal pkg
  \"\")))[0m.  If [47mpkg[0m is not a string, then [47m(pkg-witness pkg)[0m is equal to
  [47m(pkg-witness \"ACL2\")[0m")
 (PL
  (HISTORY)
  "Print the rules for the given name or term

    Examples:
    :pl foo        ; prints rules that rewrite some call of foo
    :pl quote      ; prints rules that rewrite quoted constants
    :pl (+ x y)    ; prints rules that rewrite (+ x y)
    :pl '(4 1 2 3) ; prints rules that rewrite '(4 1 2 3)

  Also see [pl2], which restricts output to rules that you specify for
  a given term.

  [47mPl[0m takes one argument, which should be a symbol or a term.

  First suppose that the argument is a symbol.  Then it should be the
  symbol [47mquote[0m, a function symbol, or else a macro alias for a
  function symbol (see [macro-aliases-table]), which is treated as
  the corresponding function symbol.  When the argument to [47mpl[0m is
  [47mquote[0m, [47mpl[0m displays the rules that rewrite quoted constants, i.e.,
  the [47m:[0m[47m[rewrite-quoted-constant][0m rules.  Otherwise, [47m:pl[0m displays
  rules that apply to terms whose top function symbol is the one
  specified, specifically, rules of class [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m,
  [47m:[0m[47m[meta][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[forward-chaining][0m,
  [47m:[0m[47m[elim][0m, and [47m:[0m[47m[induction][0m.  For each class, rules are displayed in
  order from the most recently submitted rule to the oldest, with two
  exceptions: [47m:rewrite[0m, [47m:definition[0m, and [47m:meta[0m rules are considered
  as one ``class'' for this purpose; and only the current (most
  recent) [47m:elim[0m rule is displayed.

  Otherwise the argument should be a term.  Note that the term may have
  user-level syntax (that is, it may be an untranslated term; see
  [term]), for example one that is obtained from the theorem prover's
  output; in particular, macro calls are permitted.  When supplied a
  term, [47m:pl[0m displays rules that are (possibly) applicable to the
  given term, in order (as above, most recent rule first) for each of
  these four cases: first [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[rewrite][0m and
  [47m:[0m[47m[definition][0m rules, then [47m:meta[0m rules, then [47m:[0m[47m[linear][0m rules, and
  finally [47m:[0m[47m[type-prescription][0m rules.  Each rule is displayed with
  additional information, such as the hypotheses that remain after
  applying some simple techniques to discharge them that are likely
  to apply in any context.  (Those techniques include
  [type-reasoning], [forward-chaining], and some attempts to deal
  with [free-variables] including handling of binding hypotheses,
  [47m[syntaxp][0m and [47m[bind-free][0m.)

  It is important to remember that rules displayed as ``applicable'' by
  [47mpl[0m may in fact not be used because of logical requirements, like
  failure to relieve the hypotheses in the context in which the
  target occurs, or because of heuristics such as those controlled by
  the [47m:[0m[47m[loop-stopper][0m.

  A reminder of this can sometimes be seen in the output of [47mpl[0m.  For
  example, if the list of un-discharged hypotheses contains [47mnil[0m then
  the hypotheses of this instance the rule are known, by trivial
  means, to be unsatisfiable.

  Similarly, [47m:[0m[47m[rewrite-quoted-constant][0m rules of form [47m[2][0m are not
  actually applied unless a certain computation produces a quoted
  constant.  For example,

    ACL2 !>(include-book \"demos/rewrite-quoted-constant-examples\" :dir :system)

  includes a form [47m[2][0m rule, named [47mform-2-rule[0m, which will rewrite any
  quoted constant occurring a position admitting [47mset-equalp[0m as a
  congruence.  The rule will apply the function [47mdrop-dups-and-sort[0m to
  the constant and replace the constant by the result --- if the
  result is a quoted constant.  That function coerces the constant to
  a [47m[true-listp][0m, drops duplicate elements, and sorts the list.
  Thus, [47m'(3 1 1 2 . 77)[0m in a [47mset-equalp[0m occurrence would be rewritten
  to [47m'(1 2 3)[0m.  However, that replacement is only made if
  [47m(drop-dups-and-sort '(3 1 1 2 . 77))[0m is rewritten to a quoted
  constant.

    ACL2 !>:pl '(3 1 1 2 . 77)

  will include an entry for [47mform-2-rule[0m, but the entry reads:

    New term: (DROP-DUPS-AND-SORT '(3 1 1 2 . 77))
    Hypotheses: <none>
    Equiv: SET-EQUALP
    Substitution: ((LST '(3 1 1 2 . 77)))
    WARNING:  The new term above is only used if it rewrites to a quoted
    constant!

  How might the replacement not be made?  One way is if
  [47mdrop-dups-and-sort[0m and its [47m[executable-counterpart][0m are both
  disabled and there are no [47m:rewrite[0m rules about that function.

  Note that for [47m:[0m[47m[meta][0m rules, only those are displayed that meet two
  conditions: the application of the metafunction returns a term
  different from the input term, and if there is a hypothesis
  metafunction then it also returns a term.  (A subtlety: In the case
  of extended metafunctions (see [extended-metafunctions]), a trivial
  metafunction context is used for the application of the
  metafunction.)

  Note that some rule classes are not handled by [47m:pl[0m.  In particular,
  if you want to see all [47m:[0m[47m[clause-processor][0m rules, issue the command
  [47m:print-clause-processor-rules[0m, and for trusted clause-processors,
  [47m(table trusted-cl-proc-table)[0m; see [clause-processor] and see
  [define-trusted-clause-processor].")
 (PL2
  (HISTORY)
  "Print rule(s) for the given form

    Examples:
    :pl2 (+ x y) nil ; prints rules that apply to (+ x y)
    :pl2 (+ x y) foo ; prints rules named foo that apply to (+ x y)
    :pl2 (+ x y) (:rewrite foo) ; if the rule with rune (:rewrite foo) applies
                                ;   to (+ x y), then print it
    :pl2 (+ x y) (:type-prescription foo)
                                ; as above, but for the indicated
                                ;   type-prescription rule

  [47mPl2[0m takes two arguments.  The first is a term.  The second is either
  [47mnil[0m or a ``rule-id'' that is either a symbol or a [rune].  The
  result is to print rules of class [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, [47m:meta[0m,
  [47m:[0m[47m[linear][0m, and [47m:[0m[47m[type-prescription][0m that apply to the given term.
  Indeed, [47m:pl2[0m prints exactly what is printed by applying [47m:[0m[47m[pl][0m to
  the first argument --- see [pl] --- except that if the second
  argument is not [47mnil[0m then it is used to filter the rules printed, as
  follows.

      If the rule-id is a symbol, then only rules whose name is that symbol
      will be printed.

      If the rule-id is a [rune], then at most one rule will be printed:
      the rule named by that rune (if the rule would be printed by
      [47m:[0m[47m[pl][0m).")
 (PLET
  (PARALLEL-PROGRAMMING ACL2-BUILT-INS)
  "Parallel version of [47m[let][0m

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism],
  and see [parallel-programming], which has a disclaimer.

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

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

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

  The syntax of [47mplet[0m is identical to the syntax of [47m[let][0m, except that
  [47mplet[0m permits an optional granularity declaration in the first
  argument position; see [granularity].  In the logic a call of [47mplet[0m
  macroexpands to the corresponding call of [47m[let][0m, where the
  granularity declaration (if any) is dropped.

  [47mPlet[0m cause the evaluation of each [47mvali[0m above to be done in parallel
  before processing the body.  If the above [47m[granularity][0m declaration
  is present, then its expression ([47mexpr[0m above) is first evaluated,
  and if the result is [47mnil[0m, then such parallelism is avoided.  Even
  if parallelism is not thus avoided, parallelism may be limited by
  available resources.

  See [parallelism-at-the-top-level] for restrictions on evaluating
  parallelism primitives from within the ACL2 top-level loop.")
 (PLIST-WORLDP (POINTERS)
               "See [system-utilities].")
 (PLUSP
  (NUMBERS ACL2-BUILT-INS)
  "Test whether a number is positive

  [47m(Plusp x)[0m is true if and only if [47mx > 0[0m.

  The [guard] of [47mplusp[0m requires its argument to be a rational ([real],
  in ACL2(r)) number.

  [47mPlusp[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<plusp>

    (defun plusp (x)
      (declare (xargs :guard (real/rationalp x)))
      (> x 0))")
 (POINTERS
  (DOCUMENTATION)
  "Links pointing to relevant documentation topics


Subtopics

  [&allow-other-keys]
      See [macro-args].

  [&body]
      See [macro-args].

  [&key]
      See [macro-args].

  [&optional]
      See [macro-args].

  [&rest]
      See [macro-args].

  [&whole]
      See [macro-args].

  [*df-pi*]
      See [df].

  [Abstract-stobj]
      See [defabsstobj].

  [Accumulated-persistence-oops]
      See [accumulated-persistence].

  [ACL2-unwind-protect]
      See [system-utilities].

  [ACL2p]
      See [parallelism].

  [ACL2r]
      See [real].

  [ACL2s]
      See [ACL2-sedan].

  [Add-ld-keyword-alias]
      See [ld-keyword-aliases].

  [Add-ld-keyword-alias!]
      See [ld-keyword-aliases].

  [Add-suffix]
      See [system-utilities].

  [Add-suffix-to-fn]
      See [system-utilities].

  [Add-to-set-eq]
      See [add-to-set].

  [Add-to-set-eql]
      See [add-to-set].

  [Add-to-set-equal]
      See [add-to-set].

  [Adjust-ld-history]
      See [ld-history].

  [All-attachments]
      See [system-utilities].

  [All-calls]
      See [system-utilities].

  [All-fnnames]
      See [system-utilities].

  [All-fnnames-lst]
      See [system-utilities].

  [All-fnnames1]
      See [system-utilities].

  [All-vars]
      See [system-utilities].

  [Always$]
      See [loop$].

  [Always$+]
      See [loop$].

  [Append$]
      See [loop$].

  [Append$+]
      See [loop$].

  [Apropos]
      See [finding-documentation].

  [Arglistp]
      See [system-utilities].

  [Array]
      See [arrays].

  [Assertions]
      See [errors].

  [Assoc-eq]
      See [assoc].

  [Assoc-equal]
      See [assoc].

  [Auto-instance]
      See [defthm<w].

  [Backchain-limit-rw]
      See [hints] for information about the keyword [47m:backchain-limit-rw[0m.

  [Backtrack]
      See [hints] for information about the keyword [47m:backtrack[0m.

  [Binary-df*]
      See [df].

  [Binary-df+]
      See [df].

  [Binary-df-log]
      See [df].

  [Binary-df/]
      See [df].

  [Body]
      See [system-utilities].

  [Book-makefiles]
      See [books-certification].

  [By]
      See [hints] for information about the keyword [47m:by[0m.

  [Cases]
      See [hints] for information about the keyword [47m:cases[0m.

  [Ccl-updates]
      See [ccl-installation].

  [Certify-book-failure]
      See [certify-book-debug].

  [Certifying-books]
      See [books-certification].

  [Check-invariant-risk]
      See [set-check-invariant-risk].

  [Check-sum]
      See [checksum].

  [Close-input-channel]
      See [io].

  [Close-output-channel]
      See [io].

  [Coherence]
      See [wormhole-status].

  [Collect$]
      See [loop$].

  [Collect$+]
      See [loop$].

  [Comma]
      See [backquote].

  [Comma-atsign]
      See [backquote].

  [Community-book]
      See [community-books].

  [Computed-hint]
      See [computed-hints].

  [Conjoin]
      See [system-utilities].

  [Conjoin2]
      See [system-utilities].

  [Cons-term]
      See [system-utilities].

  [Cons-term*]
      See [system-utilities].

  [Context]
      See [ctx].

  [Cw-gstack-for-subterm]
      See [with-brr-data].

  [Cw-gstack-for-subterm*]
      See [with-brr-data].

  [Cw-gstack-for-term]
      See [with-brr-data].

  [Cw-gstack-for-term*]
      See [with-brr-data].

  [D<]
      See [l<].

  [Declaration]
      See [declare].

  [Default-state-vars]
      See [system-utilities].

  [Default-verify-guards-eagerness]
      See [set-verify-guards-eagerness].

  [Defined-constant]
      See [system-utilities].

  [Df*]
      See [df].

  [Df+]
      See [df].

  [Df-]
      See [df].

  [Df-abs]
      See [df].

  [Df-abs-fn]
      See [df].

  [Df-acos]
      See [df].

  [Df-acos-fn]
      See [df].

  [Df-acosh]
      See [df].

  [Df-acosh-fn]
      See [df].

  [Df-asin]
      See [df].

  [Df-asin-fn]
      See [df].

  [Df-asinh]
      See [df].

  [Df-asinh-fn]
      See [df].

  [Df-atan]
      See [df].

  [Df-atan-fn]
      See [df].

  [Df-atanh]
      See [df].

  [Df-atanh-fn]
      See [df].

  [Df-cos]
      See [df].

  [Df-cos-fn]
      See [df].

  [Df-cosh]
      See [df].

  [Df-cosh-fn]
      See [df].

  [Df-exp]
      See [df].

  [Df-exp-fn]
      See [df].

  [Df-expt]
      See [df].

  [Df-expt-fn]
      See [df].

  [Df-log]
      See [df].

  [Df-minus-1]
      See [df].

  [Df-pi]
      See [df].

  [Df-rationalize]
      See [df].

  [Df-round]
      See [df].

  [Df-sin]
      See [df].

  [Df-sin-fn]
      See [df].

  [Df-sinh]
      See [df].

  [Df-sinh-fn]
      See [df].

  [Df-sqrt]
      See [df].

  [Df-sqrt-fn]
      See [df].

  [Df-string]
      See [df].

  [Df-tan]
      See [df].

  [Df-tan-fn]
      See [df].

  [Df-tanh]
      See [df].

  [Df-tanh-fn]
      See [df].

  [Df/]
      See [df].

  [Df/=-fn]
      See [df].

  [Df0]
      See [df].

  [Df1]
      See [df].

  [Df<]
      See [df].

  [Df<-fn]
      See [df].

  [Df<=]
      See [df].

  [Df=]
      See [df].

  [Df=-fn]
      See [df].

  [Df>]
      See [df].

  [Df>=]
      See [df].

  [Dfp]
      See [df].

  [Disjoin]
      See [system-utilities].

  [Disjoin2]
      See [system-utilities].

  [Do-not-induct]
      See [hints] for information about the keyword [47m:do-not-induct[0m.

  [Double-float]
      See [df].

  [Doublet-listp]
      See [system-utilities].

  [Dumb-negate-lit]
      See [system-utilities].

  [Dumb-occur]
      See [system-utilities].

  [Dumb-occur-var]
      See [system-utilities].

  [Dynamically-monitor-rewrites]
      See [dmr].

  [Enabled-numep]
      See [system-utilities].

  [Enabled-runep]
      See [system-utilities].

  [Ephemeral-whs]
      See [wormhole-status].

  [Er-cmp]
      See [context-message-pair].

  [Er-let*]
      See [programming-with-state].

  [Er-let*-cmp]
      See [context-message-pair].

  [Er-progn-cmp]
      See [context-message-pair].

  [Error]
      See [hints] for information about the keyword [47m:error[0m.

  [Ev$-list]
      See [apply$].

  [Event]
      See [events].

  [Event-data]
      See [saving-event-data].

  [Execution]
      See [evaluation].

  [Expand]
      See [hints] for information about the keyword [47m:expand[0m.

  [Extended-syntaxp]
      See [syntaxp].

  [External-format]
      See [character-encoding].

  [Fake-rune]
      See [rune].

  [Fargn]
      See [system-utilities].

  [Fargs]
      See [system-utilities].

  [Fast-alist]
      See [fast-alists].

  [Fast-alist-discipline]
      See [slow-alist-warning].

  [Fcons-term]
      See [system-utilities].

  [Fcons-term*]
      See [system-utilities].

  [Fdefun-mode]
      See [system-utilities].

  [Ffn-symb]
      See [system-utilities].

  [Ffn-symb-p]
      See [system-utilities].

  [Ffnnamep]
      See [system-utilities].

  [Ffnnamep-lst]
      See [system-utilities].

  [First-keyword]
      See [system-utilities].

  [First-n-ac]
      See [take].

  [Fix-pkg]
      See [system-utilities].

  [Flambda-applicationp]
      See [system-utilities].

  [Flambdap]
      See [system-utilities].

  [Flatten-ands-in-lit]
      See [system-utilities].

  [Floating-point]
      See [df].

  [Fms!-to-string]
      See [printing-to-strings].

  [Fms-to-string]
      See [printing-to-strings].

  [Fmt!-to-string]
      See [printing-to-strings].

  [Fmt-hard-right-margin]
      See [set-fmt-hard-right-margin].

  [Fmt-soft-right-margin]
      See [set-fmt-hard-right-margin].

  [Fmt-to-string]
      See [printing-to-strings].

  [Fmt1!-to-string]
      See [printing-to-strings].

  [Fmt1-to-string]
      See [printing-to-strings].

  [Fmx!-cw]
      See [fmx-cw].

  [Fn-rune-nume]
      See [system-utilities].

  [Fn-symb]
      See [system-utilities].

  [Fncall-term]
      See [meta-extract].

  [Forced]
      See [force].

  [Formals]
      See [system-utilities].

  [Fquotep]
      See [system-utilities].

  [From-df]
      See [df].

  [Fsubcor-var]
      See [system-utilities].

  [Function-symbolp]
      See [system-utilities].

  [Gcs]
      See [get-command-sequence].

  [Genvar]
      See [system-utilities].

  [Get-brr-local]
      See [system-utilities].

  [Get-check-invariant-risk]
      See [set-check-invariant-risk].

  [Get-defun-event]
      See [system-utilities].

  [Get-event]
      See [system-utilities].

  [Get-in-theory-redundant-okp]
      See [set-in-theory-redundant-okp].

  [Get-output-stream-string$]
      See [io].

  [Get-register-invariant-risk]
      See [set-register-invariant-risk].

  [Get-serialize-character]
      See [with-serialize-character].

  [Get-skipped-proofs-p]
      See [system-utilities].

  [Getting-started]
      See [ACL2-tutorial].

  [Guard-checking]
      See [set-guard-checking].

  [Guard-hints]
      See [xargs] for information about the keyword [47m:guard-hints[0m.

  [Guard-holder]
      See [guard-holders].

  [Guard-msg-table]
      See [set-guard-msg].

  [Guards]
      See [guard].

  [Hands-off]
      See [hints] for information about the keyword [47m:hands-off[0m.

  [Hash-tables]
      See [defstobj].

  [If-intro]
      See [splitter].

  [Ignorable]
      See [declare].

  [Ignore]
      See [declare].

  [Ilks]
      See [ilk].

  [Immed-forced]
      See [splitter].

  [Implicate]
      See [system-utilities].

  [Induct]
      See [hints] for information about the keyword [47m:induct[0m.

  [Inline]
      See [defun-inline].

  [Interrupts]
      See [abort-soft].

  [Intersection-eq]
      See [intersection$].

  [Intersection-equal]
      See [intersection$].

  [Intersectp-eq]
      See [intersectp].

  [Intersectp-equal]
      See [intersectp].

  [Io?]
      See [system-utilities].

  [Iprint]
      See [set-iprint].

  [Iprinting]
      See [set-iprint].

  [Keyword]
      See [keywordp].

  [Known-package-alist]
      See [system-utilities].

  [Lambda-applicationp]
      See [system-utilities].

  [Lambda-body]
      See [system-utilities].

  [Lambda-formals]
      See [system-utilities].

  [Ld-history-entry-error-flg]
      See [ld-history].

  [Ld-history-entry-input]
      See [ld-history].

  [Ld-history-entry-stobjs-out]
      See [ld-history].

  [Ld-history-entry-stobjs-out/value]
      See [ld-history].

  [Ld-history-entry-user-data]
      See [ld-history].

  [Ld-history-entry-value]
      See [ld-history].

  [Ld-user-stobjs-modified-warning]
      See [user-stobjs-modified-warnings].

  [Legal-constantp]
      See [system-utilities].

  [Legal-variablep]
      See [system-utilities].

  [Let-mbe]
      See [equality-variants-details].

  [Lex-fix]
      See [l<].

  [Lexp]
      See [l<].

  [Lisp-programmer-introduction]
      See [introduction-to-programming-in-ACL2-for-those-who-know-lisp].

  [Logicp]
      See [system-utilities].

  [Loop$-do]
      See [do-loop$].

  [Loop$-for]
      See [for-loop$].

  [Make-lambda]
      See [system-utilities].

  [Make-lambda-application]
      See [system-utilities].

  [Make-lambda-term]
      See [system-utilities].

  [Make-list-ac]
      See [make-list].

  [Match-free]
      See [free-variables].

  [Maybe-convert-to-mv]
      See [system-utilities].

  [Measure-theorem]
      See [termination-theorem].

  [Member-eq]
      See [member].

  [Member-equal]
      See [member].

  [Memoization]
      See [memoize].

  [Meta-extract-contextual-fact]
      See [meta-extract].

  [Meta-extract-formula]
      See [meta-extract].

  [Meta-extract-global-fact]
      See [meta-extract].

  [Meta-extract-global-fact+]
      See [meta-extract].

  [Meta-extract-rw+-term]
      See [meta-extract].

  [Mfc]
      See [metafunction-context].

  [Mfc-ancestors]
      See [extended-metafunctions].

  [Mfc-ap]
      See [extended-metafunctions].

  [Mfc-clause]
      See [extended-metafunctions].

  [Mfc-rdepth]
      See [extended-metafunctions].

  [Mfc-relieve-hyp]
      See [extended-metafunctions].

  [Mfc-rw]
      See [extended-metafunctions].

  [Mfc-rw+]
      See [extended-metafunctions].

  [Mfc-ts]
      See [extended-metafunctions].

  [Mfc-type-alist]
      See [extended-metafunctions].

  [Mfc-unify-subst]
      See [extended-metafunctions].

  [Mfc-world]
      See [extended-metafunctions].

  [Mode]
      See [xargs] for information about the keyword [47m:mode[0m.

  [Multiple-value]
      See [mv-let].

  [Nfix-list]
      See [l<].

  [No-duplicatesp-eq]
      See [no-duplicatesp].

  [No-duplicatesp-equal]
      See [no-duplicatesp].

  [No-op]
      See [hints] for information about the keyword [47m:no-op[0m.

  [No-thanks]
      See [hints] for information about the keyword [47m:no-thanks[0m.

  [Non-executable]
      See [xargs] for information about the keyword [47m:non-executable[0m.

  [Nonlinearp]
      See [hints] for information about the keyword [47m:nonlinearp[0m.

  [Normalization]
      See [normalize].

  [Note1]
      See [note-1-1].

  [Note2]
      See [note-1-2].

  [Note3]
      See [note-1-3].

  [Note4]
      See [note-1-4].

  [Note5]
      See [note-1-5].

  [Note6]
      See [note-1-6].

  [Note7]
      See [note-1-7].

  [Note8]
      See [note-1-8].

  [Note8-update]
      See [note-1-8-update].

  [Note9]
      See [note-1-9].

  [Nvariablep]
      See [system-utilities].

  [Observation-cw]
      See [observation].

  [Old-and-new-event-data]
      See [saving-event-data].

  [Open-input-channel]
      See [io].

  [Open-input-channel-p]
      See [io].

  [Open-output-channel]
      See [io].

  [Open-output-channel-p]
      See [io].

  [Optimize]
      See [declare].

  [Package]
      See [packages].

  [Partition-rest-and-keyword-args]
      See [system-utilities].

  [Pe-table]
      See [extend-pe-table].

  [Peek-char$]
      See [io].

  [Persistent-whs]
      See [wormhole-status].

  [Plist-worldp]
      See [system-utilities].

  [Position-eq]
      See [position].

  [Position-equal]
      See [position].

  [Pound-bang-reader]
      See [sharp-bang-reader].

  [Pound-dot-reader]
      See [sharp-dot-reader].

  [Pound-u-reader]
      See [sharp-u-reader].

  [Prettyify-clause]
      See [system-utilities].

  [Print-object$-preserving-case]
      See [io].

  [Print-summary-user]
      See [finalize-event-user].

  [Programp]
      See [system-utilities].

  [Proof-supporters-alist]
      See [dead-events].

  [Put-assoc-eq]
      See [put-assoc].

  [Put-assoc-eql]
      See [put-assoc].

  [Put-assoc-equal]
      See [put-assoc].

  [Quotep]
      See [system-utilities].

  [Rassoc-eq]
      See [rassoc].

  [Rassoc-equal]
      See [rassoc].

  [Raw-mode]
      See [set-raw-mode].

  [Read-byte$]
      See [io].

  [Read-char$]
      See [io].

  [Read-object]
      See [io].

  [Read-object-suppress]
      See [io].

  [Read-object-with-case]
      See [io].

  [Recursivep]
      See [system-utilities].

  [Redefine]
      See [ld-redefinition-action].

  [Redefining]
      See [ld-redefinition-action].

  [Redundant]
      See [redundant-events].

  [Regression]
      See [books-certification].

  [Remove-assoc-eq]
      See [remove-assoc].

  [Remove-assoc-equal]
      See [remove-assoc].

  [Remove-duplicates-eq]
      See [remove-duplicates].

  [Remove-duplicates-equal]
      See [remove-duplicates].

  [Remove-eq]
      See [remove].

  [Remove-equal]
      See [remove].

  [Remove-guard-holders]
      See [guard-holders].

  [Remove1-assoc-eq]
      See [remove1-assoc].

  [Remove1-assoc-equal]
      See [remove1-assoc].

  [Remove1-eq]
      See [remove1].

  [Remove1-equal]
      See [remove1].

  [Reorder]
      See [hints] for information about the keyword [47m:reorder[0m.

  [Reset-print-control]
      See [print-control].

  [Restrict]
      See [hints] for information about the keyword [47m:restrict[0m.

  [Rewrite-cache]
      See [set-rw-cache-state].

  [Rize]
      See [df].

  [Ruler]
      See [rulers].

  [Ruler-extenders]
      See [rulers].

  [Runes-diff]
      See [saving-event-data].

  [Rw-cache]
      See [set-rw-cache-state].

  [Saving-and-restoring]
      See [save-exec].

  [Set-accumulated-persistence]
      See [accumulated-persistence].

  [Set-difference-eq]
      See [set-difference$].

  [Set-difference-equal]
      See [set-difference$].

  [Set-fast-cert]
      See [fast-cert].

  [Set-ld-always-skip-top-level-locals]
      See [ld-always-skip-top-level-locals].

  [Set-ld-error-action]
      See [ld-error-action].

  [Set-ld-error-triples]
      See [ld-error-triples].

  [Set-ld-evisc-tuple]
      See [ld-evisc-tuple].

  [Set-ld-keyword-aliases]
      See [ld-keyword-aliases].

  [Set-ld-keyword-aliases!]
      See [ld-keyword-aliases].

  [Set-ld-missing-input-ok]
      See [ld-missing-input-ok].

  [Set-ld-post-eval-print]
      See [ld-post-eval-print].

  [Set-ld-pre-eval-filter]
      See [ld-pre-eval-filter].

  [Set-ld-pre-eval-print]
      See [ld-pre-eval-print].

  [Set-ld-prompt]
      See [ld-prompt].

  [Set-ld-query-control-alist]
      See [ld-query-control-alist].

  [Set-ld-redefinition-action]
      See [ld-redefinition-action].

  [Set-ld-skip-proofs]
      See [ld-skip-proofsp].

  [Set-ld-skip-proofsp]
      See [ld-skip-proofsp].

  [Set-ld-user-stobjs-modified-warning]
      See [user-stobjs-modified-warnings].

  [Set-ld-verbose]
      See [ld-verbose].

  [Set-let*-abstraction]
      See [set-let*-abstractionp].

  [Set-non-linear]
      See [set-non-linearp].

  [Set-print-circle]
      See [print-control].

  [Set-print-escape]
      See [print-control].

  [Set-print-length]
      See [print-control].

  [Set-print-level]
      See [print-control].

  [Set-print-lines]
      See [print-control].

  [Set-print-readably]
      See [print-control].

  [Set-print-right-margin]
      See [print-control].

  [Set-proofs-co]
      See [proofs-co].

  [Set-ruler-extenders]
      See [rulers].

  [Set-serialize-character]
      See [with-serialize-character].

  [Set-slow-alist-action]
      See [slow-alist-warning].

  [Set-standard-co]
      See [standard-co].

  [Set-standard-oi]
      See [standard-oi].

  [Set-temp-touchable-fns]
      See [remove-untouchable].

  [Set-temp-touchable-vars]
      See [remove-untouchable].

  [Set-trace-co]
      See [trace-co].

  [Show-accumulated-persistence]
      See [accumulated-persistence].

  [Single-threaded-objects]
      See [stobj].

  [Split-types]
      See [xargs] for information about the keyword [47m:split-types[0m.

  [Stable-under-simplificationp]
      See [computed-hints].

  [Step-limit]
      See [with-prover-step-limit].

  [Stobj-let]
      See [nested-stobjs].

  [Stobjp]
      See [system-utilities].

  [Stobjs]
      See [xargs] for information about the keyword [47m:stobjs[0m.

  [Stobjs-in]
      See [system-utilities].

  [Stobjs-out]
      See [system-utilities].

  [Subcor-var]
      See [system-utilities].

  [Sublis-fn]
      See [system-utilities].

  [Sublis-fn-lst-simple]
      See [system-utilities].

  [Sublis-fn-simple]
      See [system-utilities].

  [Sublis-var]
      See [system-utilities].

  [Subsequencep]
      See [system-utilities].

  [Subsetp-eq]
      See [subsetp].

  [Subsetp-equal]
      See [subsetp].

  [Subst-expr]
      See [system-utilities].

  [Subst-var]
      See [system-utilities].

  [Suitably-tamep-listp]
      See [tame].

  [Sum$]
      See [loop$].

  [Sum$+]
      See [loop$].

  [Symbol-class]
      See [system-utilities].

  [Symbol-doublet-listp]
      See [system-utilities].

  [Table-alist]
      See [table].

  [Tag-tree]
      See [ttree].

  [Tamep]
      See [tame].

  [Tamep-functionp]
      See [tame].

  [Tamep-lambdap]
      See [tame].

  [Thereis$]
      See [loop$].

  [Thereis$+]
      See [loop$].

  [Time-limit]
      See [with-prover-time-limit].

  [To-df]
      See [df].

  [To-dfp]
      See [df].

  [Too-many-ifs]
      See [efficiency].

  [Top-level-loop]
      See [guarantees-of-the-top-level-loop].

  [Trans-eval-default-warning]
      See [user-stobjs-modified-warnings].

  [Trans-eval-no-warning]
      See [user-stobjs-modified-warnings].

  [Translate]
      See [system-utilities].

  [Translate-cmp]
      See [system-utilities].

  [Translate-hints]
      See [system-utilities].

  [Translate1]
      See [system-utilities].

  [Translate1-cmp]
      See [system-utilities].

  [Translate11]
      See [system-utilities].

  [Trust-tag]
      See [defttag].

  [Ttag]
      See [defttag].

  [Type]
      Disambiguation page for [3mtype[0m-related concepts.

  [Typespec-check]
      See [meta-extract].

  [Unary-df-]
      See [df].

  [Unary-df-log]
      See [df].

  [Unary-df/]
      See [df].

  [Undoing]
      See [undo].

  [Union-eq]
      See [union$].

  [Union-equal]
      See [union$].

  [Unknown-constraints]
      See [partial-encapsulate].

  [Until$]
      See [loop$].

  [Until$+]
      See [loop$].

  [Untouchable-marker]
      See [defmacro-untouchable].

  [Untranslate-preprocess]
      See [user-defined-functions-table].

  [Use]
      See [hints] for information about the keyword [47m:use[0m.

  [Value]
      See [system-utilities].

  [Value-cmp]
      See [context-message-pair].

  [Variablep]
      See [system-utilities].

  [Verify-guards-eagerness]
      See [set-verify-guards-eagerness].

  [Waterfall]
      See [hints-and-the-waterfall].

  [Weak-ld-history-entry-p]
      See [ld-history].

  [When$]
      See [loop$].

  [When$+]
      See [loop$].

  [With-output!]
      See [with-output].

  [With-prover-step-limit!]
      See [with-prover-step-limit].

  [Wormhole-coherence]
      See [wormhole-status].

  [Write-byte$]
      See [io].")
 (POPPING_OUT_OF_AN_INDUCTIVE_PROOF
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Popping out of an Inductive Proof

  Recall that our induction scheme (click here (see
  [The_Proof_of_the_Associativity_of_App]) to revisit it) had two
  cases, the induction step ([47mSubgoal *1/2[0m) and the base case ([47mSubgoal
  *1/1[0m).  Both have been proved!")
 (POR
  (PARALLEL-PROGRAMMING ACL2-BUILT-INS)
  "Parallel, Boolean version of [47m[or][0m

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism],
  and see [parallel-programming], which has a disclaimer.

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

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

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

  where [47mN >= 0[0m and each [47margi[0m and [47mexpr[0m are arbitrary terms.

  [47mPor[0m evaluates its arguments in parallel.  It returns a Boolean
  result: [47mt[0m if any argument evaluates to non-[47mnil[0m, else [47mnil[0m.  Note
  that while [47m[or][0m returns the first non-[47mnil[0m value from evaluating its
  arguments left-to-right (if any such value is not [47mnil[0m) [47m[por][0m always
  returns a Boolean result, in support of efficiency (see
  [early-termination]) in light of the nondeterministic order in
  which argument values are returned.

  Another difference between [47mpor[0m and [47m[or][0m is that for a call of [47mpor[0m,
  even if the an argument's value is not [47mnil[0m, a subsequent argument
  may be evaluated.  See [pand] for a discussion of the analogous
  property of [47mpand[0m.  In particular, [guard]s generated from calls of
  [47mpor[0m may not assume for an argument that the preceding arguments
  evaluated to [47mnil[0m.

  See [parallelism-tutorial] for another example.  Also see
  [parallelism-at-the-top-level] for restrictions on evaluating
  parallelism primitives from within the ACL2 top-level loop.
  Finally see [early-termination] to read how [47mpor[0m can offer more
  efficiency than [47m[or][0m by avoiding evaluation of some of its
  arguments.")
 (PORTCULLIS
  (BOOKS-TOUR)
  "The gate guarding the entrance to a certified book

  The certificate (see [certificate] for general information) of a
  certified book contains a portcullis and a [keep].  These names
  come from castle lore.  The portcullis of a castle is an iron grate
  that slides up through the ceiling of the tunnel-like entrance.
  The portcullis of a book ensures that [47m[include-book][0m does not start
  to read the book until the appropriate context has been created.

  Technically, the portcullis consists of the [version] number of the
  certifying ACL2, a list of [command]s used to create the
  ``certification [world]'' and an alist specifying [book-hash]
  values for all the [books] included in that [world].  The
  portcullis is constructed automatically by [47m[certify-book][0m from the
  [world] in which [47m[certify-book][0m is called, but that [world] must
  have certain properties described below.  After listing the
  properties we discuss the issues in a more leisurely manner.

  Each [command] in the portcullis must be either a [47m[defpkg][0m form or an
  embedded event form (see [embedded-event-form]).

  Consider a book to be certified.  The book is a file containing event
  forms.  Suppose the file contains references to such symbols as
  [47mmy-pkg::fn[0m and [47macl2-arith::cancel[0m, but that the book itself does
  not create the packages.  Then a hard Lisp error would be caused
  merely by the attempt to read the expressions in the book.  The
  corresponding [47m[defpkg][0ms cannot be written into the book itself
  because the book must be compilable and Common Lisp compilers
  differ on the rules concerning the inline definition of new
  packages.  The only safe course is to make all [47m[defpkg][0ms occur
  outside of compiled files.

  More generally, when a book is certified it is certified within some
  logical [world].  That ``certification [world]'' contains not only
  the necessary [47m[defpkg][0ms but also, perhaps, function and constant
  definitions and maybe even references to other [books].  When
  [47m[certify-book][0m creates the [certificate] for a file it recovers
  from the certification [world] the [command]s used to create that
  [world] from the initial ACL2 [world].  Those [command]s contribute
  to the portcullis for the certified book.  In addition,
  [47m[certify-book][0m records in the portcullis certain [3mbook-hash[0m values
  (see [book-hash]) for all the [books] included in the certification
  [world].

  [47m[Include-book][0m presumes that it is impossible even to read the
  contents of a certified book unless the portcullis can be
  ``raised.'' To raise the portcullis we must be able to execute
  (possibly redundantly, but certainly without error), all of the
  [command]s in the portcullis and then verify that the [books] thus
  included were identical to those used to build the certification
  [world] (up to book-hash).  This raising of the portcullis must be
  done delicately since [47m[defpkg][0ms are present: we cannot even read a
  [command] in the portcullis until we have successfully executed the
  previous ones, since packages are being defined.  Note that when
  [47minclude-book[0m evaluates portcullis commands, it skips proofs and
  ignores [local] events.

  Clearly, a book is most useful if its certification takes place with
  as few non-[local] events as possible that extend the initial
  logical [world].  If, for example, your certification [world]
  happens to contain a [47m[defpkg][0m for [47m\"MY-PKG\"[0m and a non-local
  definition of a function [47mfoo[0m, then those definitions become part of
  the portcullis for the book.  Every time the book is included,
  those names will be defined and will have to be either new or
  redundant (see [redundant-events]).  But if those names were not
  necessary to the certification of the book, their presence would
  unnecessarily restrict the utility of the book.

  See [keep] to continue the guided tour of [books].")
 (POS-LISTP
  (NUMBERS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of positive integers

  The predicate [47mpos-listp[0m tests whether its argument is a true list of
  positive integers.

  [31;1mFunction: [0m<pos-listp>

    (defun pos-listp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (eq l nil))
            (t (and (posp (car l))
                    (pos-listp (cdr l))))))")
 (POSITION
  (LISTS STRINGS ACL2-BUILT-INS)
  "Position of an item in a string or a list

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

  [47m(Position x seq)[0m is the least index (zero-based) of the element [47mx[0m in
  the string or list [47mseq[0m, if [47mx[0m is an element of [47mseq[0m.  Otherwise
  [47m(position x seq)[0m is [47mnil[0m.  The optional keyword, [47m:TEST[0m, has no
  effect logically, but provides the test (default [47m[eql][0m) used for
  comparing [47mx[0m with items of [47mseq[0m.

  The [guard] for a call of [47mposition[0m depends on the test.  In all
  cases, the second argument must satisfy [47m[stringp][0m or [47m[true-listp][0m.
  If the test is [47m[eql][0m, then either the first argument must be
  suitable for [47m[eql][0m (see [eqlablep]) or the second argument must
  satisfy [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then either the
  first argument must be a symbol or the second argument must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mposition[0m and its variants:

      [47m(position-eq x seq)[0m is equivalent to [47m(position x seq :test 'eq)[0m;

      [47m(position-equal x seq)[0m is equivalent to [47m(position x seq :test
      'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mposition-equal[0m.

  [47mPosition[0m is defined by Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mMacro: [0m<position>

    (defmacro position (x seq &key (test ''eql))
      (declare (xargs :guard (or (equal test ''eq)
                                 (equal test ''eql)
                                 (equal test ''equal))))
      (cond ((equal test ''eq)
             (cons 'let-mbe
                   (cons (cons (cons 'x (cons x 'nil))
                               (cons (cons 'seq (cons seq 'nil)) 'nil))
                         '(:logic (position-equal x seq)
                                  :exec (position-eq-exec x seq)))))
            ((equal test ''eql)
             (cons 'let-mbe
                   (cons (cons (cons 'x (cons x 'nil))
                               (cons (cons 'seq (cons seq 'nil)) 'nil))
                         '(:logic (position-equal x seq)
                                  :exec (position-eql-exec x seq)))))
            (t (cons 'position-equal
                     (cons x (cons seq 'nil))))))

  [31;1mFunction: [0m<position-equal>

    (defun position-equal (x seq)
      (declare (xargs :guard (or (stringp seq) (true-listp seq))))
      (if (stringp seq)
          (position-ac x (coerce seq 'list) 0)
        (position-equal-ac x seq 0)))

  [31;1mFunction: [0m<position-equal-ac>

    (defun position-equal-ac (item lst acc)
      (declare (xargs :guard (and (true-listp lst)
                                  (acl2-numberp acc))))
      (cond ((endp lst) nil)
            ((equal item (car lst))
             (mbe :exec acc :logic (fix acc)))
            (t (position-equal-ac item (cdr lst)
                                  (1+ acc)))))

  [31;1mMacro: [0m<position-ac>

    (defmacro position-ac (item lst acc &key (test ''eql))
     (declare (xargs :guard (or (equal test ''eq)
                                (equal test ''eql)
                                (equal test ''equal))))
     (cond
      ((equal test ''eq)
       (cons 'let-mbe
             (cons (cons (cons 'item (cons item 'nil))
                         (cons (cons 'lst (cons lst 'nil))
                               (cons (cons 'acc (cons acc 'nil))
                                     'nil)))
                   '(:logic (position-equal-ac item lst acc)
                            :exec (position-ac-eq-exec item lst acc)))))
      ((equal test ''eql)
       (cons
            'let-mbe
            (cons (cons (cons 'item (cons item 'nil))
                        (cons (cons 'lst (cons lst 'nil))
                              (cons (cons 'acc (cons acc 'nil))
                                    'nil)))
                  '(:logic (position-equal-ac item lst acc)
                           :exec (position-ac-eql-exec item lst acc)))))
      (t (cons 'position-equal-ac
               (cons item (cons lst (cons acc 'nil)))))))")
 (POSITION-EQ (POINTERS)
              "See [position].")
 (POSITION-EQUAL (POINTERS)
                 "See [position].")
 (POSP
  (NUMBERS ACL2-BUILT-INS)
  "A recognizer for the positive integers

  [47m(posp x)[0m is logically equivalent to [47m(not (zp x))[0m (see [zp]) and also
  to [47m(and (natp x) (not (equal x 0)))[0m.

  The community book [arithmetic/natp-posp] has some lightweight rules
  for reasoning about [47mposp[0m and [47mnatp[0m, and is included in the
  [arithmetic-1] library.  For a somewhat heavier and more
  comprehensive alternative, you may wish to instead see the
  [arith-equivs] book.

  [31;1mFunction: [0m<posp>

    (defun posp (x)
      (declare (xargs :guard t))
      (and (integerp x) (< 0 x)))")
 (POST-INDUCTION-KEY-CHECKPOINTS
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Reading post-induction key checkpoints

  Each post-induction key checkpoint is a theorem if and only if the
  original conjecture was a theorem.  The reason is that each subgoal
  produced by induction concludes with the original formula and
  simplification preserves equivalence.

  So if you see a post-induction key checkpoint that is not a theorem,
  stop looking at the checkpoints!  Your original conjecture is not a
  theorem!  Fix it.

  If you're convinced all the post-induction conjectures are theorems,
  ask whether each has the hypotheses you'd need to prove it.  If the
  case analysis feels inappropriate or induction hypotheses seem to
  be missing, then ACL2 might have done the wrong induction.  Find
  the induction scheme it did by reading the first induction message
  printed after the conjecture was submitted.  If it is wrong, then
  extend ACL2's induction analysis or tell ACL2 what induction to do,
  as explained shortly.

  But before you decide the induction hypothesis is missing, look
  closely for contradictions among the hypotheses of the checkpoint
  formula.  For example, perhaps one of the hypotheses is [47m(MEMBER e
  x)[0m and another is [47m(NOT (MEMBER e' x'))[0m where [47me[0m, [47mx[0m, [47me'[0m, and [47mx'[0m are
  possibly complicated expressions.

  Is it possible that [47me[0m and [47me'[0m are equal and [47mx[0m and [47mx'[0m are equal?  If
  so, then the two hypotheses are contradictory and the checkpoint
  would be proved if you could find rules that would simplify those
  expressions to their common forms.  So look for theorems about
  those subexpressions.

  Or maybe you can get [47me[0m and [47me'[0m to reduce to some common [47md[0m but but find
  that [47mx[0m and [47mx'[0m are really different.  Then ask whether

    (implies (member d x) (member d x'))

  If you could prove that, the key checkpoint would be proved.  Of
  course, you may need other hypotheses from the checkpoint to state
  your theorems.

  If you have been working your way through the tutorial introduction
  to the theorem prover, use your browser's [31;1mBack Button[0m now to
  [introduction-to-key-checkpoints].")
 (POUND-BANG-READER (POINTERS)
                    "See [sharp-bang-reader].")
 (POUND-DOT-READER (POINTERS)
                   "See [sharp-dot-reader].")
 (POUND-U-READER (POINTERS)
                 "See [sharp-u-reader].")
 (PPR-SPECIAL-SYMS
  (IO)
  "A [table] to control indentation for pretty-printing

  ACL2 output is generally pretty-printed: that is, spacing and
  indentation are controlled to enhance readability and aesthetics of
  the output.  Indentation may be controlled by using the table,
  [47mppr-special-syms[0m as described below.  We thank Stephen Westfold for
  enhancing the pretty-printer with support for [47mppr-special-syms[0m.

  The initial value of the [47mppr-special-syms[0m table is given by the
  constant [47m*ppr-special-syms*[0m as follows.  It associates each key, a
  symbol, with a corresponding [3mspecial-term-num[0m as discussed below.

  [31;1mDefinition: [0m<*ppr-special-syms*>

    (defconst *ppr-special-syms*
      '((case . 1)
        (case-match . 1)
        (defabsstobj . 1)
        (defaxiom . 1)
        (defchoose . 3)
        (defcong . 2)
        (defconst . 1)
        (defmacro . 2)
        (defstobj . 1)
        (defthm . 1)
        (defthmd . 1)
        (defun . 2)
        (defun-inline . 2)
        (defun-sk . 2)
        (defund . 2)
        (encapsulate . 1)
        (if . 2)
        (lambda . 1)
        (lambda$ . 1)
        (let . 1)
        (let* . 1)
        (mutual-recursion . 0)
        (mv-let . 2)
        (table . 1)))

  The [47mppr-special-syms[0m table is extended for some common macros in the
  files where they are defined, for example for [47m[define][0m and [47m[b*][0m.

  For calls of special forms and macros in the [47mppr-special-syms[0m table,
  their bodies are indented by 2 rather than in the usual default
  manner.  To support this we allow a [3mspecial-term-num[0m to be
  associated with a symbol.  Arguments of such symbols in the
  function position beyond the special-term-num position are indented
  by 2.  Earlier arguments are printed normally.  For example, the
  symbol, [47mlet[0m, has a special-term-num of 1, so the first argument is
  printed normally and subsequent arguments are indented by 2, as
  follows.

    (LET ((A B)
          (C D))
      (F A C))

  Since `if' has a special-term-num of 2, the first two arguments are
  printed normally and the other is indented by 2, for example as
  follows.

    (IF (P A B)
        (F A B)
      (G A B))

  Macros often have as their first argument a symbol, so these are
  treated specially by putting them on the first line and any
  remaining arguments before the body arguments begin on the same
  line if there is space.  For example, [47mdefun[0m has special-term-num 2,
  which is evident in the following output.

    (DEFUN FOO (X Y Z)
      (F X Y Z))

  Keyword pairs in macro calls can occur in other places than at the
  end of an argument list, so keyword pairing is done more
  aggressively, as in the following output.

    (DEFINE FOO ((X P1)
                 (Y P2))
      :GUARD (P3 X Y)
      (F X Y Z))")
 (PPROGN
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Evaluate a sequence of forms that return [state]

    Example Form:
    (pprogn
     (cond ((or (equal (car l) #\\) (equal (car l) slash-char))
            (princ$ #\\ channel state))
           (t state))
     (princ$ (car l) channel state)
     (mv (cdr l) state))

  The convention for [47mpprogn[0m usage is to give it a non-empty sequence of
  forms, each of which (except possibly for the last) returns state
  (see [state]) as its only value.  The [state] returned by each but
  the last is passed on to the next.  The value or values of the last
  form are returned as the value of the [47mpprogn[0m.

  If you are using single-threaded objects you may wish to define an
  analogue of this function for your own [stobj].

  General Form:

    (PPROGN form1
            form2
            ...
            formk
            result-form)

  This general form is equivalent, via macro expansion, to:

    (LET ((STATE form1))
         (LET ((STATE form2))
              ...
              (LET ((STATE formk))
                   result-form)))")
 (PR
  (HISTORY)
  "Print the rules stored by the event with the given name

    Examples:

    :pr fn ; prints the rules from the definition of fn (including any
           ; :type-prescription rule and :definition rule)

    :pr assoc-append ; if assoc-append is a rewrite rule, prints that rule

  Also see [pr!], which is similar but works at the command level
  instead of at the event level, and see [pl], which displays all
  rewrite rules for calls of [47mfn[0m, not just those introduced at
  definition time.

  [47mPr[0m takes one argument, a logical name, and prints the rules
  associated with it.  In each case it prints the rune, the current
  enabled/disabled status, and other appropriate fields from the
  rule.  It may be helpful to read the documentation for various
  kinds of rules in order to understand the information printed by
  this command.  For example, the information printed for a linear
  rule might be:

    Rune:     (:LINEAR ABC)
    Enabled:  T
    Hyps:     ((CONSP X))
    Concl:    (< (ACL2-COUNT (CAR X)) (ACL2-COUNT X))
    Max-term: (ACL2-COUNT (CAR X))
    Backchain-limit-lst:    (3)

  The [47mhyps[0m and [47mconcl[0m fields for this rule are fairly self-explanatory,
  but it is useful to see [linear] to learn about maximal terms
  (which, as one might guess, are stored under ``Max-term'').

  Currently, this function does not print congruence rules, equivalence
  rules, or refinement rules.

  The expert user might also wish to use [47m[find-rules-of-rune][0m.  See
  [find-rules-of-rune].")
 (PR!
  (HISTORY)
  "Print rules stored by the command with a given command descriptor

    Examples:

    :pr! fn ; prints the rules from the definition of fn (including any
            ; :type-prescription rule and :definition rule), as well as all other
            ; rules created by the command that created by fn (which could be
            ; many rules if, for example, fn was defined by an include-book
            ; command).

    :pr! :max ; prints all the rules stored by the most recent command

  Also see [pr], which is similar but works at the event level instead
  of at the command level.

  [47m[Pr][0m takes one argument, a command descriptor, and prints the rules
  created by the corresponding event.  In each case it prints the
  rune, the current enabled/disabled status, and other appropriate
  fields from the rule.  See [pr] for further details.")
 (PRACTICE-FORMULATING-STRONG-RULES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "A few simple checkpoints suggesting strong rules

  Consider these definitions:

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

    (defun nats-below (j)
      (if (zp j)
          '(0)
          (cons j (nats-below (- j 1)))))

  We assume you are familiar with such ACL2 built-ins as [47mappend[0m,
  [47mmember[0m, [47msubsetp[0m and [47mtrue-listp[0m.  When we use throw-away names like
  [47mFOO[0m, [47mBAR[0m, and [47mMUM[0m below we mean to suggest some arbitrary function
  you shouldn't think about!  We're just trying to train your eye to
  ignore irrelevant things.

  Below are some terms that should suggest rewrite rules to you.
  Imagine that each of these terms occurs in some Key Checkpoint.
  What rules come to mind?  Try to think of the strongest rules you
  can.

  Term 1:
  [47m(TRUE-LISTP (APPEND (FOO A) (BAR B)))[0m

  Answers: See [practice-formulating-strong-rules-1]

  Term 2:
  [47m(TRUE-LISTP (REV (FOO A)))[0m

  Answers: See [practice-formulating-strong-rules-2]

  Term 3:
  [47m(MEMBER (FOO A) (APPEND (BAR B) (MUM C)))[0m

  Answers: See [practice-formulating-strong-rules-3]

  Term 4:
  [47m(SUBSETP (APPEND (FOO A) (BAR B)) (MUM C))[0m

  Answers: See [practice-formulating-strong-rules-4]

  Term 5:
  [47m(SUBSETP (FOO A) (APPEND (BAR B) (MUM C)))[0m

  Answers: See [practice-formulating-strong-rules-5]

  Term 6:
  [47m(MEMBER (FOO A) (NATS-BELOW (BAR B)))[0m

  Answers: See [practice-formulating-strong-rules-6]

  We recommend doing all of these little exercises.  When you're
  finished, use your browser's [31;1mBack Button[0m to return to
  [strong-rewrite-rules].")
 (PRACTICE-FORMULATING-STRONG-RULES-1
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Rules suggested by [47m(TRUE-LISTP (APPEND (FOO A) (BAR B)))[0m

  What rules come to mind when looking at the following subterm of a
  Key Checkpoint?  Think of [3mstrong[0m rules (see
  [strong-rewrite-rules]).

    (TRUE-LISTP (APPEND (FOO A) (BAR B)))

  Obviously, you must think about the conditions under which [47m(APPEND x
  y)[0m returns a true-list.  Recall that [47mAPPEND[0m concatenates [47mx[0m and [47my[0m,
  with [47my[0m being the terminal sublist.  Its definition is equivalent to

    (defun append (x y)
      (if (endp x)
          y
          (cons (car x)
                (append (cdr x) y))))

  Technical Note: [47mAppend[0m is really a macro that permits you to write
  calls of [47mappend[0m with more than two arguments.

  In a sense, [47mappend[0m ``expects'' its arguments to be lists ending in
  [47mnil[0m, so-called [47mtrue-listp[0ms.  (Such expectations are formalized in
  ACL2 by the notion of the ``[guard]'' {ICON} (see
  [A_Tiny_Warning_Sign]) of the function, but we strongly recommend
  not investigating guards until you're good at using the system.)

  New users frequently start every new theorem by listing all their
  expectations on the arguments of functions in the problem.  For
  example, if the new user wants to make some statement about when
  [47m(append x y)[0m is a [47mtrue-listp[0m, it is not uncommon for him or her
  first to write:

    (implies (and (true-listp x)
                  (true-listp y))
             ...)

  to get ``comfortable.'' Then, thinking about when [47m(append x y)[0m is a
  [47mtrue-listp[0m is easy: it always returns a [47mtrue-listp[0m.  It's always a
  [47mtrue-listp[0m.'' This thinking produces the theorem:

    (defthm true-listp-append-really-weak
      (implies (and (true-listp x)
                    (true-listp y))
               (true-listp (append x y))))

  You'll note we gave it a name suggesting it is ``really weak.''

  One sense in which it is weak is that it has an unnecessary
  hypothesis.  If [47my[0m is a [47mtrue-listp[0m, then [47m(append x y)[0m is too,
  whether [47mx[0m is a [47mtrue-listp[0m or not.  In ACL2, all functions are
  total.  Logically speaking, it doesn't matter whether [47mendp[0m expects
  its argument to be a [47mtrue-listp[0m or not, it behaves.  [47m(Append x y)[0m
  either returns [47my[0m or a [47mcons[0m whose second argument is generated by
  [47mappend[0m.  Thus, if [47my[0m is a [47mtrue-listp[0m, the answer is too.  So here is
  an improved version of the rule:

    (defthm true-listp-append-weak
      (implies (true-listp y)
               (true-listp (append x y))))

  We still think of it as ``weak'' because it has a hypothesis that
  limits its applicability.

  The strong version of the rule is

    (defthm true-listp-append-strong
      (equal (true-listp (append x y))
             (true-listp y))).

  That is, [47mappend[0m returns a [47mtrue-listp[0m [3mprecisely[0m when its second
  argument is a [47mtrue-listp[0m.  We recommend that the strong version be
  made a [47m:[0m[47m[rewrite][0m {ICON} (see [A_Tiny_Warning_Sign]) rule.

  The weak version of the rule allows us to reduce [47m(TRUE-LISTP (APPEND
  x y))[0m to true if we can show that [47m(TRUE-LISTP y)[0m is true.  But
  suppose [47m(TRUE-LISTP y)[0m is actually false.  Then [47m(TRUE-LISTP (APPEND
  x y))[0m would not simplify under the weak version of the rule.  But
  under the strong version it would simplify to [47mNIL[0m.

  Technical Note: The weak version of the rule is a useful
  [47m:[0m[47m[type-prescription][0m {ICON} (see [A_Tiny_Warning_Sign]) rule.  The
  type mechanism cannot currently exploit the strong version of the
  rule.

  The strategy of ``getting comfortable'' by adding a bunch of
  hypotheses before you know you need them is not conducive to
  creating strong rules.  We tend to state the main relationship that
  we intuit about some function and then add the hypotheses we need
  to make it true.  In this case, there were no necessary hypotheses.
  But if there are, we first identify them and then we ask ``what can
  I say about the function if these hypotheses aren't true?'' and try
  to strengthen the statement still further.

  Use your browser's [31;1mBack Button[0m now to return to
  [practice-formulating-strong-rules].")
 (PRACTICE-FORMULATING-STRONG-RULES-2
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Rules suggested by [47m(TRUE-LISTP (REV (FOO A)))[0m

  What rules come to mind when looking at the following subterm of a
  Key Checkpoint?  Think of [3mstrong[0m rules (see
  [strong-rewrite-rules]).

    (TRUE-LISTP (REV (FOO A)))

  The definition of [47mrev[0m in this problem is

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

  Since the definition terminates with an [47mendp[0m test and otherwise [47mcdr[0ms
  the argument, the author of [47mrev[0m was clearly expecting [47mx[0m to be a
  [47mtrue-listp[0m.  (Indeed, the ``[guard]'' {ICON} (see
  [A_Tiny_Warning_Sign]) for [47mrev[0m must include [47m(true-listp x)[0m since
  that is [47mendp[0m's guard.)  So you're naturally justified in limiting
  your thoughts about [47m(rev x)[0m to [47mx[0m that are true-lists.  This gives
  rise to the theorem:

    (defthm true-listp-rev-weak
      (implies (true-listp x)
               (true-listp (rev x))))

  This is the kind of thinking illustrated in the earlier [47mappend[0m
  example (see [practice-formulating-strong-rules-1]), and, to
  paraphrase Z in [3mMen in Black[0m, it exemplifies ``everything we've
  come to expect from years of training with typed languages.''

  But logically speaking, the definition of [47mrev[0m does not require [47mx[0m to
  be a [47mtrue-listp[0m.  It can be any object at all: ACL2 functions are
  total.  [47mRev[0m either returns [47mnil[0m or the result of appending a
  singleton list onto the right end of its recursive result.  That
  call of [47mappend[0m always returns a [47mtrue-listp[0m since the singleton list
  is a true list.  (See [practice-formulating-strong-rules-1].)

  So this is a theorem and a very useful [47m:[0m[47m[rewrite][0m {ICON} (see
  [A_Tiny_Warning_Sign]) rule:

    (defthm true-listp-rev-strong
      (true-listp (rev x))).

  Use your browser's [31;1mBack Button[0m now to return to
  [practice-formulating-strong-rules].")
 (PRACTICE-FORMULATING-STRONG-RULES-3
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Rules suggested by [47m(MEMBER (FOO A) (APPEND (BAR B) (MUM C)))[0m

  What rules come to mind when looking at the following subterm of a
  Key Checkpoint?  Think of [3mstrong[0m rules (see
  [strong-rewrite-rules]).

    (MEMBER (FOO A) (APPEND (BAR B) (MUM C)))

  Since [47m(append x y)[0m contains all the members of [47mx[0m and all the members
  of [47my[0m, [47me[0m is a member of [47m(append x y)[0m precisely when [47me[0m is a member of
  [47mx[0m or of [47my[0m.  So a strong statement of this is:

    (defthm member-append-strong-false
      (equal (member e (append x y))
             (or (member e x)
                 (member e y))))

  However, this is not a theorem because [47mmember[0m is not Boolean.
  [47m(Member e x)[0m, for example, returns the first tail of [47mx[0m that starts
  with [47me[0m, or else [47mnil[0m.  To see an example of this formula that
  evaluates to [47mnil[0m, let

    e = 3
    x = '(1 2 3)
    y = '(4 5 6).

  Then the left-hand side, [47m(member e (append x y))[0m evaluates to [47m(3 4 5
  6)[0m while the right-hand side evaluates to [47m(3)[0m.

  However, the two sides are propositionally equivalent (both either
  [47mnil[0m or non-[47mnil[0m together).  So this is a useful [47m:[0m[47m[rewrite][0m {ICON}
  (see [A_Tiny_Warning_Sign]) rule:

    (defthm member-append-strong
      (iff (member e (append x y))
           (or (member e x)
               (member e y)))).

  It tells the system that whenever it encounters an instance of
  [47m(MEMBER e (APPEND x y))[0m in a propositional occurrence (where only
  its truth value is relevant), it should be replaced by this
  disjunction of [47m(MEMBER e x)[0m and [47m(MEMBER e y)[0m.

  The following two formulas are true but provide much weaker rules and
  we would not add them:

    (implies (member e x) (member e (append x y)))

    (implies (member e y) (member e (append x y)))

  because they each cause the system to backchain upon seeing [47m(MEMBER e
  (APPEND x y))[0m expressions and will not apply unless one of the two
  side-conditions can be established.

  There is a rewrite rule that is even stronger than
  [47mmember-append-strong[0m.  It is suggested by the counterexample,
  above, for the [47mEQUAL[0m version of the rule.

    (defthm member-append-really-strong
      (equal (member e (append x y))
             (if (member e x)
                 (append (member e x) y)
                 (member e y))))

  While [47mmember-append-strong[0m only rewrites [47mmember-append[0m expressions
  occurring propositionally, the [47m-really-strong[0m version rewrites
  [3mevery[0m occurrence.

  However, this rule will be more useful than [47mmember-append-strong[0m only
  if you have occurrences of [47mmember[0m in non-propositional places.  For
  example, suppose you encountered a term like:

    (CONS (MEMBER e (APPEND x y)) z).

  Then the [47m-strong[0m rule does not apply but the [47m-really-strong[0m rule
  does.

  Furthermore, the [47m-really-strong[0m rule, by itself, is not quite as good
  as the [47m-strong[0m rule in propositional settings!  For example, if you
  have proved the [47m-really-strong[0m rule, you'll notice that the system
  still has to use induction to prove

    (IMPLIES (MEMBER E A)
             (MEMBER E (APPEND B A))).

  The [47m-really-strong[0m rule would rewrite it to

    (IMPLIES (MEMBER E A)
             (IF (MEMBER E A)
                 (APPEND (MEMBER E A) B)
                 (MEMBER E B)))

  which would further simplify to

    (IMPLIES (MEMBER E A)
             (APPEND (MEMBER E A) B))

  What lemma does this suggest?  The answer is the rather odd:

    (implies x (append x y))

  which rewrites propositional occurrences of [47m(APPEND x y)[0m to [47mT[0m if [47mx[0m is
  non-[47mnil[0m.  This is an inductive fact about [47mappend[0m.

  A problem with the [47m-really-strong[0m rule is that it transforms even
  propositional occurrences of [47mmember[0m into mixed propositional and
  non-propositional occurrences.

    (defthm member-append-really-strong
      (equal (member e (append x y))      ; <-- even if this is a propositional occurrence
             (if (member e x)
                 (append (member e x) y)  ; <-- the member in here is not!
                 (member e y))))

  So if you are using the [47m-really-strong[0m lemma in a situation in which
  all your [47mmember[0m expressions are used propositionally, you'll
  suddenly find yourself confronted with non-propositional uses of
  [47mmember[0m.

  Our advice is not to use the [47m-really-strong[0m version unless your
  application is inherently using [47mmember[0m in a non-propositional way.

  Use your browser's [31;1mBack Button[0m now to return to
  [practice-formulating-strong-rules].")
 (PRACTICE-FORMULATING-STRONG-RULES-4
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Rules suggested by [47m(SUBSETP (APPEND (FOO A) (BAR B)) (MUM C))[0m

  What rules come to mind when looking at the following subterm of a
  Key Checkpoint?  Think of [3mstrong[0m rules (see
  [strong-rewrite-rules]).

    (SUBSETP (APPEND (FOO A) (BAR B)) (MUM C))

  When is [47m(append x y)[0m a subset of [47mz[0m?  When everything in [47mx[0m is in [47mz[0m and
  everything in [47my[0m is in [47mz[0m.  We would make it a rewrite rule:

    (defthm subsetp-append-1-strong
      (equal (subsetp (append x y) z)
             (and (subsetp x z)
                  (subsetp y z))))

  We put the ``[47m-1-[0m'' in the name because there is a comparable theorem
  for when the [47mappend[0m is in the second argument of the [47msubsetp[0m; see
  [practice-formulating-strong-rules-5].

  This strong rule is better than the conditional rule;

    (defthm subsetp-append-1-weak
      (implies (and (subsetp x z)
                    (subsetp y z))
               (subsetp (append x y) z)))

  for all the usual reasons.

  Use your browser's [31;1mBack Button[0m now to return to
  [practice-formulating-strong-rules].")
 (PRACTICE-FORMULATING-STRONG-RULES-5
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Rules suggested by [47m(SUBSETP (FOO A) (APPEND (BAR B) (MUM C)))[0m

  What rules come to mind when looking at the following subterm of a
  Key Checkpoint?  Think of [3mstrong[0m rules (see
  [strong-rewrite-rules]).

    (SUBSETP (FOO A) (APPEND (BAR B) (MUM C)))

  When is [47mx[0m a subset of [47m(append y z)[0m?  Clearly it is if [47mx[0m is a subset
  of [47my[0m or [47mx[0m is a subset of [47mz[0m.  We could write that:

    (defthm subsetp-append-2-weak
      (implies (or (subsetp x y)
                   (subsetp x z))
               (subsetp x (append y z))))

  The rule generated from this is: ``if you ever encounter (an instance
  of) [47m(SUBSETP x (APPEND y z))[0m, backchain to the [47mor[0m above and try to
  establish it.  If you can establish it, replace the target by [47mT[0m.''

  This does not fully characterize the situation though.  For example,
  [47m'(1 2 3 4)[0m is a subset of [47m(append '(1 3) '(2 4))[0m without being a
  subset of either argument of the [47mappend[0m.

  However, no obvious equivalence comes to mind --- indeed, to express
  any of the ideas floating around here requires defining and
  introducing more functions, which is not recommended unless those
  functions are already in the problem.

  For example, if you defined the concept of ``[47mset-minus[0m'' so that
  [47m(set-minus x y)[0m consists of those elements of [47mx[0m not in [47my[0m, then you
  could prove:

    (defthm subset-append-2-strong-but-messy
      (equal (subsetp x (append y z))
             (and (subsetp (set-minus x z) y)
                  (subsetp (set-minus x y) z))))

  But this rewrite rule would ``trade'' [47mappend[0m away and introduce
  [47mset-minus[0m.  That might be a good strategy if [47mset-minus[0m were already
  in the problem.  But if it were not, it might not be.  We wouldn't
  recommend this rule unless it were helpful in normalizing the
  expressions in the problem.

  We recommend sticking with the weak version of the rule,

    (defthm subsetp-append-2-weak
      (implies (or (subsetp x y)
                   (subsetp x z))
               (subsetp x (append y z)))).

  This illustrates the fact that sometimes there is no strong version
  of a rule!

  Use your browser's [31;1mBack Button[0m now to return to
  [practice-formulating-strong-rules].")
 (PRACTICE-FORMULATING-STRONG-RULES-6
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Rules suggested by [47m(MEMBER (FOO A) (NATS-BELOW (BAR B)))[0m

  What rules come to mind when looking at the following subterm of a
  Key Checkpoint?  Think of [3mstrong[0m rules (see
  [strong-rewrite-rules]).

    (MEMBER (FOO A) (NATS-BELOW (BAR B)))

  The definition of [47mNATS-BELOW[0m is

    (defun nats-below (j)
      (if (zp j)
          '(0)
          (cons j (nats-below (- j 1)))))

  Thus, [47m(nats-below 7)[0m is [47m(7 6 5 4 3 2 1 0)[0m.  So when is [47mk[0m a member of
  [47m(nats-below j)[0m?

  The weakest version is

    (defthm member-nats-below-weak
      (implies (and (natp k)
                    (natp j)
                    (<= k j))
               (member k (nats-below j))))

  But clearly we could improve this to:

    (defthm member-nats-below-weak-better
      (implies (and (natp k)
                    (natp j))
               (iff (member k (nats-below j))
                    (<= k j))))

  or even

    (defthm member-nats-below-weak-better
      (implies (natp j)
               (iff (member k (nats-below j))
                    (and (natp k)
                         (<= k j)))))

  Clearly though, we'd like to get rid of the [47m(natp j)[0m hypothesis and
  the neatest plausible version is:

    (defthm member-nats-below-weak-neatest
      (iff (member k (nats-below j))
           (and (natp j)
                (natp k)
                (<= k j))))

  But it is not a theorem!  For example, if [47mj[0m is [47m-1[0m and [47mk[0m is 0, then
  the left-hand side above returns [47mt[0m, because [47m(nats-below j)[0m is [47m(0)[0m,
  but the right-hand side is [47mnil[0m.

  But this suggests a strategy for dealing with necessary hypotheses,
  like [47m(natp j)[0m.  We can move them into an [47mIF[0m on the right-hand side!
  Something like this might be a useful rewrite rule:

    (iff (member k (nats-below j))
         (if (natp j)
             (and (natp k)
                  (<= k j))
             ...)).

  We know, from [47mmember-nats-below-weak-better[0m, that if [47m(natp j)[0m is
  true, the [47mmember[0m is equivalent to [47m(and (natp k) (<= k j))[0m.  So now
  consider what we know if [47m(natp j)[0m is false.  If we can think of
  some term it's equivalent to and that term is simpler than the
  [47mmember[0m expression, we have a strong rule.

  But by inspection of the definition of [47mnats-below[0m, we see that when
  [47m(natp j)[0m is false, [47m(nats-below j)[0m is the list [47m(0)[0m because [47m(zp j)[0m is
  t.  That is, [47mnats-below[0m treats all non-natural arguments like they
  were [47m0[0m.  Thus, when [47m(natp j)[0m is false, [47m(member k (nats-below j))[0m is
  [47m(member k '(0))[0m, which is [47m(equal k 0)[0m.

  So the strong version is

    (defthm member-nats-below-strong
       (iff (member k (nats-below j))
            (if (natp j)
                (and (natp k)
                     (<= k j))
                (equal k 0))))

  This is a great [47m:[0m[47m[rewrite][0m {ICON} (see [A_Tiny_Warning_Sign]) rule.
  It gets rid of the [47mmember[0m and [47mnats-below[0m and introduces arithmetic.

  This example illustrates the idea of putting an [47mif[0m on the
  right-hand-side of the equivalence.  Many users tend to limit
  themselves to propositional forms inside [47miff[0m or to simple
  expressions inside of [47mequal[0m.  But it is quite natural to use [47mif[0m to
  express what the answer is: if [47mj[0m is a natural, then [47mk[0m is in
  [47m(nats-below j)[0m precisely if [47mk[0m is a natural less than or equal to [47mj[0m;
  if [47mj[0m is not a natural, then [47mk[0m is in [47m(nats-below j)[0m precisely if [47mk[0m
  is [47m0[0m.

  The one weakness of the rule above is that it only rewrites [47m(member x
  (nats-below y))[0m when an instance of that target term occurs in a
  propositional setting, e.g., when the governing equivalence
  relation is [47miff[0m.  But, thanks to Andrei Koltsov, an even stronger
  version is available as an unconditional [47mequal[0mity rewrite:

    (defthm member-nats-below-stronger
      (equal (member x (nats-below y))
             (if (natp x)
                 (if (natp y)
                     (if (<= x y)
                         (nats-below x)
                         nil)
                     (if (= x 0) '(0) nil))
                 nil)))

  The key observation is that when [47mx[0m and [47my[0m are both naturals and [47m(<= x
  y)[0m, the result that [47mmember[0m computes can be expressed with
  [47mnats-below[0m.  You may wonder whether this stronger rule allows the
  immediate proof of the earlier [47mmember-nats-below-strong[0m and the
  answer is yes, because from the definition of [47mnats-below[0m ACL2 has
  observed that [47m(nats-below x)[0m is a [47mcons[0m whenever [47mx[0m is a natural.

  Use [47mif[0m to lay out the cases you must consider, if you can think of a
  simpler, equivalent expression for every possible case.

  Use your browser's [31;1mBack Button[0m now to return to
  [practice-formulating-strong-rules].")
 (PRE-BUILT-BINARY-DISTRIBUTIONS
  (ABOUT-ACL2)
  "Pre-built binary distributions of ACL2

  Visit the ``Recent changes to this page'' link on the {ACL2 home page
  | http://www.cs.utexas.edu/users/moore/acl2/} to see if there are
  other shortcuts available.

  [31;1mWARNING[0m: Some of these packages might be for old versions of ACL2.  We
  recommend that you use the latest version of ACL2 (Version 8.6).


Linux/Mac/Windows Binaries in ACL2s

  The ACL2 Sedan (see [ACL2-sedan]), also known as ACL2s, is an
  Eclipse-based IDE for ACL2 that is distributed with pre-certified
  books and pre-built binaries, though it is not always based on the
  latest ACL2 version.  The ACL2 Sedan is distributed via a Homebrew
  package for Linux and macOS users, and as a Windows Subsystem for
  Linux distro for Windows users.

  See [ACL2s::ACL2s-installation] for instructions for installing the
  ACL2 Sedan. Note that these instructions are typically intended for
  students at Northeastern, but hopefully are useful for anyone
  interested in installing ACL2s.


Windows

  In the past, a Windows Installer for ACL2 has included a Unix
  environment, pre-certified standard and workshop books, and a copy
  of Gnu Emacs.  This capability has largely been superseded in the
  installation instructions' {section on Building an Executable Image
  on Some Particular Systems |
  https://www.cs.utexas.edu/~moore/acl2/current/HTML/installation/obtaining-and-installing.html#Build-Particular}.
  See also [windows-installation].


macOS

  ACL2 versions are sometimes been made available {under MacPorts |
  https://ports.macports.org/port/acl2/}.

  Some folks maintain {a Homebrew package |
  https://formulae.brew.sh/formula/acl2} that tracks the latest
  stable version of ACL2.


Debian GNU Linux

  A Debian Gnu Linux package is available, which is likely to work on
  other Linux systems as well.  Thanks to Camm Maguire for
  maintaining this package, and for pointing out that as Debian
  packages are simply ar and tar archives, they can be unpacked on
  any linux system, and who has said: ``If someone is running Debian,
  all they want to do is 'apt-get install acl2', doing likewise for
  any optional add-on package they wish as well, e.g. emacs, infix,
  etc.'' Alternatively, Debian GNU Linux users may wish to {download
  the ACL2 Debian package for Linux |
  http://packages.qa.debian.org/a/acl2.html}.  An alternate location
  you might want to check is {[47mbackports.debian.org[0m |
  http://backports.debian.org}.


Docker images

  Some folks maintain Docker images for ACL2. Below is a nonexhaustive
  list of such images; feel free to add to this list. DH refers to
  Docker Hub and GHCR refers to the GitHub Container Registry.

    * DH: {atwalter/acl2 | https://hub.docker.com/r/atwalter/acl2/}, GHCR:
      {mister-walter/acl2 |
      https://github.com/mister-walter/acl2-docker/pkgs/container/acl2}

    * DH: {atwalter/acl2s | https://hub.docker.com/r/atwalter/acl2s/},
      GHCR: {mister-walter/acl2s |
      https://github.com/mister-walter/acl2s-docker/pkgs/container/acl2s}")
 (PRETTYIFY-CLAUSE (POINTERS)
                   "See [system-utilities].")
 (PRIMITIVE
  (PROGRAMMING ACL2-BUILT-INS)
  "Primitive functions built into ACL2 without definitions

  The ACL2 [ground-zero] [theory] includes axioms about some built-in
  functions that are not given explicit definitions, such as [47m[<][0m,
  [47m[car][0m, and [47m[symbolp][0m.  We sometimes call such functions [3mprimitives[0m.
  The built-in constant [47m*primitive-formals-and-guards*[0m is an alist
  that associates each primitive with its list of formals and its
  [guard]; that is, each element of that alist is of the form [47m(name
  formals guard)[0m.  The value of this constant is displayed below.

  [31;1mDefinition: [0m<*primitive-formals-and-guards*>

    (defconst *primitive-formals-and-guards*
      '((acl2-numberp (x) 't)
        (bad-atom<= (x y)
                    (if (bad-atom x) (bad-atom y) 'nil))
        (binary-* (x y)
                  (if (acl2-numberp x)
                      (acl2-numberp y)
                    'nil))
        (binary-+ (x y)
                  (if (acl2-numberp x)
                      (acl2-numberp y)
                    'nil))
        (unary-- (x) (acl2-numberp x))
        (unary-/ (x)
                 (if (acl2-numberp x)
                     (not (equal x '0))
                   'nil))
        (< (x y)
           (if (rationalp x) (rationalp y) 'nil))
        (car (x)
             (if (consp x) 't (equal x 'nil)))
        (cdr (x)
             (if (consp x) 't (equal x 'nil)))
        (char-code (x) (characterp x))
        (characterp (x) 't)
        (code-char (x)
                   (if (integerp x)
                       (if (< x '0) 'nil (< x '256))
                     'nil))
        (complex (x y)
                 (if (rationalp x) (rationalp y) 'nil))
        (complex-rationalp (x) 't)
        (coerce (x y)
                (if (equal y 'list)
                    (stringp x)
                  (if (equal y 'string)
                      (character-listp x)
                    'nil)))
        (cons (x y) 't)
        (consp (x) 't)
        (denominator (x) (rationalp x))
        (equal (x y) 't)
        (if (x y z) 't)
        (imagpart (x) (acl2-numberp x))
        (integerp (x) 't)
        (intern-in-package-of-symbol
             (str sym)
             (if (stringp str) (symbolp sym) 'nil))
        (numerator (x) (rationalp x))
        (pkg-imports (pkg) (stringp pkg))
        (pkg-witness (pkg)
                     (if (stringp pkg)
                         (not (equal pkg '\"\"))
                       'nil))
        (rationalp (x) 't)
        (realpart (x) (acl2-numberp x))
        (stringp (x) 't)
        (symbol-name (x) (symbolp x))
        (symbol-package-name (x) (symbolp x))
        (symbolp (x) 't)))")
 (PRINC$
  (IO ACL2-BUILT-INS)
  "Print an atom

  Use [47mprinc$[0m to do basic printing of atoms (i.e., other than [47mcons[0m
  pairs).  In particular, [47mprinc$[0m prints a string without the
  surrounding double-quotes and without escaping double-quote
  characters within the string.  Note that [47mprinc$[0m is sensitive to the
  print-base, print-radix, and print-case; see [set-print-base-radix]
  and see [set-print-case].  [47mPrinc$[0m returns [47m[state][0m.

    Examples:
    ACL2 !>(princ$ \"Howdy ho\" (standard-co state) state)
    Howdy ho<state>
    ACL2 !>(pprogn (princ$ \"Howdy ho\" (standard-co state) state)
                   (newline (standard-co state) state))
    Howdy ho
    <state>
    ACL2 !>(princ$ \"ab\\\"cd\" *standard-co* state)
    ab\"cd<state>
    ACL2 !>
    ACL2 !>(princ$ 17 *standard-co* state)
    17<state>
    ACL2 !>(set-print-base 16 state) ; might be nicer to use set-print-base-radix
    <state>
    ACL2 !>(princ$ 17 *standard-co* state)
    11<state>
    ACL2 !>(set-print-radix t state)
    <state>
    ACL2 !>(princ$ 17 *standard-co* state)
    #x11<state>
    ACL2 !>(princ$ 'xyz *standard-co* state)
    XYZ<state>
    ACL2 !>(set-print-case :downcase state)
    <state>
    ACL2 !>(princ$ 'xyz *standard-co* state)
    xyz<state>
    ACL2 !>

  The [guard] for [47m(princ$ x channel state)[0m is essentially as follows;
  see [io] for an explanation of guards of certain built-in functions
  that take [state], such as [47mprinc$[0m.

    (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))

  See [fmt] for more sophisticated printing routines, and see [io] for
  general information about input and output.


Subtopics

  [Newline]
      Print a newline to a given output channel")
 (PRINT-BASE-P
  (IO ACL2-BUILT-INS)
  "Recognizer for print bases that are understood by functions such as
  [explode-nonnegative-integer] and [explode-atom].

  [31;1mFunction: [0m<print-base-p>

    (defun print-base-p (print-base)
      (declare (xargs :guard t))
      (and (member print-base '(2 8 10 16))
           t))")
 (PRINT-CL-CACHE
  (APPLY$)
  "Information about the cache supporting [47mapply$[0m

    General Form:
    (print-cl-cache)

  Logically this function always returns [47mNIL[0m but it prints to the
  comment window information about the cache that supports the
  application of quoted [47mLAMBDA[0m objects by [47m[apply$][0m.  The name stands
  for Print Compiled Lambda Cache.

  In general there is a non-empty cache line for each [47mLAMBDA[0m object
  used in a [47mdefun[0m or seen by [47mverify-guards[0m or by [47mapply$[0m in the
  evaluation theory.  But the cache has a maximal size.  If a new
  [47mLAMBDA[0m object is seen when the cache is full, the least recently
  used line is re-used for the new [47mLAMBDA[0m object.  By default the
  maximal cache size is 1000.  This can be changed -- with the
  side-effect of clearing the cache -- by exiting the ACL2 loop with
  [47m:q[0m and doing [47m(setq *cl-cache* k)[0m, where [47mk[0m is the new maximal size.

  When [47mprint-cl-cache[0m is called it prints a block about each non-empty
  cache line enumerated from 0, and listed in the order that the
  cache is searched when a [47mLAMBDA[0m object is [47mapply$[0md.  Each block
  contains:

    * [47m:lambda-object[0m - a fully translated [47mLAMBDA[0m object

    * [47m:status[0m - one of four keywords with the following meanings:

        * [47m:GOOD[0m - the [47mLAMBDA[0m object is well-formed and Common Lisp compliant
          (``guard verified'') in the current world

        * [47m:BAD[0m - the [47mLAMBDA[0m object is not well-formed or not Common Lisp
          compliant (``guard verified'') in the current world, but
          (with high probability) there is a world in which it is
          well-formed and compliant

        * [47m:UGLY[0m - the [47mLAMBDA[0m object is so ill-formed it can never be [47m:GOOD[0m in
          any world, e.g., [47m(LAMBDA (T) (CONS 3 . 4))[0m

        * [47m:UNKNOWN[0m - we do not know the status of this object in the current
          world and leave it to [47mapply$[0m to determine the proper status
          the next time this object is [47mapply$[0md.

    * [47m:abs-event-no[0m - the absolute event number (in the current world) at
      which the [47mLAMBDA[0m object was proved to have status [47m:GOOD[0m, or [47mNIL[0m
      if its status is not [47m:GOOD[0m

    * [47m:extracts[0m - some parts of the [47mLAMBDA[0m object sufficient to confirm
      well-formedness.  Well-formedness must be re-confirmed if the
      world is retracted to before the object became [47m:GOOD[0m

    * [47m:problem[0m - One of the following values.

        * [47mNIL[0m - no problem; status is [47m:GOOD[0m

        * [47mNOT-WELL-FORMED[0m - the [47mLAMBDA[0m is syntactically plausible but not
          well-formed but could, perhaps, become well-formed in a
          suitable extension of the current world, e.g., the body
          calls an undefined function (but perhaps it can be
          defined), the body contains a [47m:program[0m mode function (but
          perhaps that could be upgraded to [47m:logic[0m mode), the body
          contains an unbadged or unwarranted function symbol (but
          perhaps [47mdefbadge[0m or [47mdefwarrant[0m could resolve the issue),
          etc.

        * [47m(GUARD-USES-NON-COMPLIANT-FNS . fns)[0m - [47mfns[0m is a list of function
          symbols used in the guard of the [47mLAMBDA[0m object that have
          not yet had their guards verified.

        * [47m(BODY-USES-NON-COMPLIANT-FNS . fns)[0m - [47mfns[0m is a list of function
          symbols used in the body of the [47mLAMBDA[0m object that have not
          yet had their guards verified.

        * [47m(UNPROVED-GUARD-CLAUSES . cl-set)[0m - [47mcl-set[0m is the list of guard
          conjectures -- written as clauses -- that tau was unable to
          prove.

        * [47mRE-VALIDATION-INTERRUPTED[0m - an interrupt aborted the updating of this
          cache line

    * [47m:hits[0m - The number of times [47mapply$[0m has seen this [47mLAMBDA[0m object

    * [47m:guard-code[0m - [47mNIL[0m or the string ``<code>'' indicating that the guard
      has been compiled

    * [47m:lambda-code[0m - [47mNIL[0m or the string ``<code>'' indicating that the
      [47mLAMBDA[0m object has been compiled


Using This Information to Speed Up LAMBDA Application

  [3mRemember:[0m A lot of programmers spend enormous amounts of time and
  effort optimizing code that runs adequately fast!  Do not make the
  mistake of investing your time here unless you really have a
  critical ACL2 top-level read-eval-print form that you [3mknow[0m runs too
  slowly!

  If you see a [47mLAMBDA[0m object in the cache with [47m:status[0m [47m:BAD[0m then it is
  being interpreted.  If you believe it can be converted to [47m:GOOD[0m and
  thus compiled, [3mand you believe you will [47mapply$[0m[3m it often enough in
  the future to warrant trying to speed it up,[0m then here are some
  tips.

  To be converted from [47m:BAD[0m to [47m:GOOD[0m a [47mLAMBDA[0m has to be both
  well-formed and [guard] verified.  The cache doesn't try to verify
  objects that are not well-formed.  So first make sure your object
  is well-formed and then once it is make sure it is guard verified.

  If the [47m:problem[0m is [47mNOT-WELL-FORMED[0m the [47m:lambda-object[0m does not pass
  the [47m[well-formed-lambda-objectp][0m test.  That predicate gives no
  hint as to why, but if you call [47m:[0m[47m[translam][0m on the [47m:lambda-object[0m
  it might give you more information.  E.g.,

    ACL2 !>:translam (lambda (x) (bar x))

    ACL2 Error in TRANSLAM: The body of a LAMBDA object or lambda$ term
    should be fully badged but BAR is used in (BAR X) and has no badge.

  Other typical problems are that a function which was formerly in
  [47m:logic[0m mode is now in [47m:program[0m mode because of an undo, or the
  [47mLAMBDA[0m object is not [tame], as in

    ACL2 !>:translam (lambda (x) (apply$ (cons x 'nil) 'sq))

    ACL2 Error in TRANSLAM:  The body of a LAMBDA object or lambda$ term
    must be tame and (APPLY$ (CONS X 'NIL) 'SQ) is not.

  Here the [47mLAMBDA[0m is unfixable because the arguments to [47mapply$[0m are in
  the wrong order.  Typing the object correctly may fix the problem.

  In any case, you may need to extend the world to convert functions to
  [47m:logic[0m mode, obtain [warrant]s (or at least [badge]s for functions
  that return multiple results), or even use a different [47mLAMBDA[0m
  object.

  When you think you've got a well-formed [47mLAMBDA[0m object, you can get
  the cache to update itself by applying the (new?) object in the
  (new?)  world,

    ACL2 !>(apply$ '(lambda (x) (apply$ 'sq (cons x 'nil))) '(5))
    25
    ACL2 !>(print-cl-cache)

  and see if the status is [47m:GOOD[0m and, if not, what the [47m:problem[0m is.

  If the problem is one of [47mGUARD-USES-NON-COMPLIANT-FNS[0m,
  [47mBODY-USES-NON-COMPLIANT-FNS[0m, or [47mUNPROVED-GUARD-CLAUSES[0m, the [47mLAMBDA[0m
  object is well-formed but not guard verified.  Again, you may need
  to further extend the world by calling [47m[verify-guards][0m on the
  listed function symbols in first two problems or call [47mverify-guard[0m
  on the lambda object itself for an opportunity to supply [47m:hints[0m to
  prove the guard [clause]s listed in the third problem.

  For example, suppose we define [47msqu[0m with a guard of [47mnatp[0m,

    (defun$ squ (x)
       (declare (type (satisfies natp) x))
       (* x x))

  And suppose we define [47mnfixer[0m to always return a natural number but in
  such a way as its type-prescription is weak.

    (defun$ nfixer (x)
      (if (equal x (car (cons x x)))
          (nfix x)
          nil))

  Furthermore, let's disable [47mnfixer[0m so the prover has no way of
  discovering the proper type.

    (in-theory (disable nfixer))

  If we then

    ACL2 !>(apply$ '(lambda (x) (squ (nfixer x))) '(5))
    25

  and use [47mprint-cl-cache[0m, we see that the [47m:problem[0m is that [47mNFIXER[0m is
  not guard verified.  So we

    ACL2 !>(verify-guards nfixer)

  and try the [47mapply$[0m and the [47mprint-cl-cache[0m again.  This time the
  [47m:problem[0m is [47m(UNPROVED-GUARD-CLAUSES ((NATP (NFIXER X))))[0m.  So tau
  couldn't prove that [47mNFIXER[0m returns a [47mNATP[0m.  We can thus

    ACL2 !>(verify-guards (lambda (x) (squ (nfixer x)))
               :hints ((\"Goal\" :in-theory (enable nfixer))))

  The [47mverify-guards[0m should succeed.  Successful calls of [47mverify-guards[0m
  on [47mLAMBDA[0m objects updates the cache, so we don't have to ``trick''
  the cache into updating itself by [47mapply$[0ming the [47mlambda[0m again.  We
  can now just do [47m(print-cl-cache)[0m and see the [47m:status[0m is [47m:GOOD[0m.

  Whether all this work is worth is depends on how often you're going
  to execute this [47mLAMBDA[0m object!


A Single Performance Comparison

  Suppose we have defined [47msqu[0m and [47mnfixer[0m, disabled [47mnfixer[0m, and verified
  the guards of [47mnfixer[0m as above.  Additionally, define the [scion]
  that maps a predicate over a list and checks that the predicate
  holds for every element.

    (defun$ always$ (pred lst)
           (if (endp lst)
               t
               (and (apply$ pred (list (car lst)))
                    (always$ pred (cdr lst)))))

  and define the function that builds a list of the first [47mn+1[0m naturals
  and use it to define the misleadingly named constant [47m*million*[0m
  which contains the first million and one naturals.

    (defun nats-ac (n ac)
      (if (zp n)
          (cons 0 ac)
          (nats-ac (- n 1) (cons n ac))))

    (defconst *million* (nats-ac 1000000 nil))

  Now observe that [47m(lambda (x) (natp (squ (nfixer x))))[0m suffers the
  same problem we witnessed above: tau cannot prove the guard clause
  because [47mnfixer[0m is disabled.  So we can do an experiment!  How long
  does it take to run this [47m:BAD[0m lambda object over the list
  [47m*million*[0m?  And then, how long does it take to do it again after
  verifying its guards and turning its status to [47m:GOOD[0m?

    ACL2 !>(time$ (always$ '(lambda (x) (natp (squ (nfixer x)))) *million*))
    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 4.35 seconds realtime, 4.35 seconds runtime
    ; (128,000,160 bytes allocated).
    T

    ACL2 !>(verify-guards (lambda (x) (natp (squ (nfixer x))))
             :hints ((\"Goal\" :in-theory (enable nfixer))))

    ...[successful but output elided]...

    ACL2 !>(time$ (always$ '(lambda (x) (natp (squ (nfixer x)))) *million*))
    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 0.19 seconds realtime, 0.19 seconds runtime
    ; (32,000,064 bytes allocated).
    T

  So we dramatically sped up the computation.  But we almost certainly
  spent longer than the original 4.35 seconds debugging the problems
  and converting the object's status to [47m:GOOD[0m.  So unless we're going
  to be doing this repeatedly in the future, it probably wasn't worth
  it!")
 (PRINT-CONTROL
  (IO)
  "Advanced controls of ACL2 printing

  See [io] for a summary of printing in ACL2.  Here we document some
  advanced ways to control what is printed by ACL2's primary printing
  routines.

  See [47m[set-print-base-radix][0m, [47m[set-print-base][0m, [47m[set-print-radix][0m, and
  [47m[set-print-case][0m for discussions of the most common ways to control
  what is printed.  Indeed, these are the only ways to control the
  behavior of [47m[princ$][0m and [47mprin1$[0m.

  See [47m[set-fmt-hard-right-margin][0m for how to set the right margin for
  prover output and, more generally, output from formatted printing
  functions (see [47m[fmt][0m).  Note that [47mset-print-right-margin[0m, mentioned
  below, does not affect such printing.

  The rest of this topic is for advanced users of ACL2.  We refer to
  Common Lisp behavior, as described in any good Common Lisp
  documentation.

  [31;1mPrint-control variables[0m.  [47m[Set-print-base][0m, [47m[set-print-radix][0m, and
  [47m[set-print-case][0m assign to corresponding so-called ``[state] global
  variables'' [47m'print-base[0m, [47m'print-radix[0m, and [47m'print-case[0m, which can
  be accessed using the expressions [47m(@ print-base)[0m, [47m(@ print-radix)[0m,
  and [47m(@ print-case)[0m, respectively; see [assign].  Here is a table
  showing all print-control variables, their setters, and their
  defaults.  Also see [47m[set-print-base-radix][0m.

    print-base          set-print-base          10
    print-case          set-print-case          :upcase
    print-circle        set-print-circle        nil
      [but see remark on print-circle-files, below]
    print-escape        set-print-escape        t
    print-length        set-print-length        nil
    print-level         set-print-level         nil
    print-lines         set-print-lines         nil
    print-pretty        set-print-pretty        nil
    print-radix         set-print-radix         nil
    print-readably      set-print-readably      nil
    print-right-margin  set-print-right-margin  nil

  Each ACL2 print-control variable [47mprint-xxx[0m can correspond in function
  to Common Lisp variable [47m*PRINT-XXX*[0m.  Specifically, the evaluation
  of forms [47m(set-print-base t)[0m, [47m(set-print-radix t)[0m, and
  [47m(set-print-case t)[0m affects ACL2 printing functions in much the same
  way that setting to [47mt[0m Common Lisp variables [47m*PRINT-BASE*[0m,
  [47m*PRINT-RADIX*[0m, and [47m*PRINT-CASE*[0m, respectively, affects Common Lisp
  printing.  The same is true for [47mprint-escape[0m, except that this does
  not affect [47m[princ$][0m or [47mprin1$[0m, which correspond to Common Lisp
  functions [47mprinc[0m and [47mprin1[0m: [47mprinc[0m treats [47m*PRINT-ESCAPE*[0m as [47mnil[0m while
  [47mprin1[0m treats [47m*PRINT-ESCAPE*[0m as [47mt[0m.  Moreover, all print-control
  variables not mentioned in this paragraph are set to their defaults
  in [47m[princ$][0m and [47mprin1$[0m, as indicated by ACL2 constant
  [47m*print-control-defaults*[0m, except that [47mprint-readably[0m is set to [47mnil[0m
  in [47mprinc$[0m.

  [47m[Fmt][0m and its related functions are sensitive to state globals
  [47m'print-base[0m, [47m'print-radix[0m, [47m'print-case[0m, [47m'print-escape[0m, and
  [47m'print-readably[0m, in analogy with Common Lisp functions that don't
  fix [47m*PRINT-ESCAPE*[0m or [47m*PRINT-READABLY*[0m.  But the [47m[fmt][0m functions do
  not respect settings of other print-control variables; for example,
  they act as though [47m'print-circle[0m is [47mnil[0m.  Since ACL2 output is
  produced using the same underlying print routines as the [47m[fmt][0m
  functions, it also is insensitive to all print-control variables
  except for the five above.  To control the print-level and
  print-length used for producing ACL2 output, see [set-evisc-tuple].

  [Print-object$] and [print-object$-preserving-case] are sensitive to
  the values of all of the print-control variables except for
  [47m'print-escape[0m.

  Evaluate [47m(reset-print-control)[0m to restore all print-control variables
  to their original settings, as stored in constant
  [47m*print-control-defaults*[0m.

  (Remark on [47mprint-circle-files[0m: ACL2 typically binds [47m'print-circle[0m to
  [47mt[0m before writing [certificate] files, or auxiliary files that are
  compiled when [47m[make-event][0m forms are present in a book, or files in
  support of [47m:[0m[47m[comp][0m commands.  This binding allows for structure
  sharing that can keep these files from growing large.  End of
  Remark.)

  (Remark for those using ACL2 built on CLtL1 (non-ANSI) Gnu Common
  Lisp (GCL): Note that Common Lisp variables [47m*PRINT-LINES*[0m,
  [47m*PRINT-MISER-WIDTH*[0m, [47m*PRINT-READABLY*[0m, [47m*PRINT-PPRINT-DISPATCH*[0m, and
  [47m*PRINT-RIGHT-MARGIN*[0m do not have any effect for such GCL versions.)")
 (PRINT-GV
  (GUARD DEBUGGING)
  "Print a form whose evaluation caused a guard violation

  By default, ACL2 checks input constraints on functions, known as
  [guard]s.  When guards are violated, an informative message is
  printed; but sometimes it is useful to investigate why the guard
  check fails.  The utility [47mprint-gv[0m is provided for that purpose.
  (Alternatively, you may prefer to avoid guards entirely with
  [47m(set-guard-checking :none)[0m; see [set-guard-checking].)

    Example Forms:
    (print-gv)
    :print-gv ; same as above
    (print-gv ; same as above, showing all system defaults
     :conjunct nil
     :evisc-tuple (print-gv-evisc-tuple)
     :substitute nil)
    (print-gv :substitute 20)
    (print-gv :evisc-tuple (evisc-tuple 4 4 nil nil))
    (print-gv :evisc-tuple (evisc-tuple 4 4 nil nil))
    (print-gv :evisc-tuple (evisc-tuple 4 ; print-level
                                        5 ; print-length
                                        (world-evisceration-alist state nil)
                                        nil ; hiding-cars
                                        ))

    General Form:
    (print-gv :conjunct c
              :substitute s
              :evisc-tuple e)

  where the keyword arguments are optional.  These arguments have the
  following effects and system defaults, but note that the defaults
  can be changed by the user; see [set-print-gv-defaults].

    * The [47m:conjunct[0m argument is [47mnil[0m by default, indicating that a form is
      to be displayed whose evaluation represents the [guard]
      evaluation that produced [47mnil[0m.  A value of [47mt[0m indicates that ACL2
      should parse the guard into conjuncts, and display the conjunct
      that actually evaluated to [47mnil[0m.  It does this by evaluating
      each conjunct in turn until one produces a result of [47mnil[0m.

    * The [47m:evisc-tuple[0m argument should be an [evisc-tuple].  Its default is
      the value of the expression [47m(print-gv-evisc-tuple)[0m, which
      specifies hiding only the ACL2 logical [world], so that the
      symbol [47m<world>[0m is printed instead of the actual world.  See
      [evisc-tuple] for a discussion of evisc-tuples.

    * The [47m:substitute[0m argument is [47mnil[0m by default, indicating that the
      displayed form uses [47m[flet][0m, which avoids duplicate occurrences
      of actual parameters.  A value of [47mt[0m indicates that ACL2 should
      instead substitute those actuals into the guard.  Otherwise the
      value should be a natural number [47mn[0m, which behaves the same as
      [47mnil[0m except when large duplicated terms are to be avoided in the
      precise sense below, in which case the behavior is the same as
      [47mt[0m, that is, [47mflet[0m is used.  The latter case (using [47mflet[0m) applies
      when some variable in the guard or (if [47m:conjunct t[0m is
      specified) conjunct has at least two occurrences, and
      corresponds to an actual parameter with at least [47mn[0m conses.
      Note that the number of conses is counted in the ``translated''
      term (guard or conjunct); see [term].

  Again, the user can change these defaults; see
  [set-print-gv-defaults].  For example, one might wish to evaluate
  [47m(set-print-gv-defaults :substitute 20)[0m so that [47m[flet][0m is used only
  when that avoids certain duplicated large terms, as discussed just
  above.

  [31;1mRemarks[0m

    * (1) [47mPrint-gv[0m starts by temporarily replacing the current installed
      ACL2 [world] with the world that was installed at the time the
      guard violation took place.  The current world is re-installed
      when [47mprint-gv[0m returns.  We illustrate this point with an
      example at the end of this topic.

    * (2) The output from [47mprint-gv[0m always goes to the terminal.
      (Specifically, the output goes to the value of the constant
      [47m[*standard-co*][0m.)

    * (3) While [47mprint-gv[0m is a utility for debugging [guard] violations, see
      [guard-debug] for a different sort of utility, which assists in
      debugging failed proofs arising from guard verification.

  To see how one might use [47mprint-gv[0m, consider the following definition.

    (defun foo (x)
      (declare (xargs :guard (and (integerp x)
                                  (posp (+ -2 x))
                                  (posp (+ 3 x))
                                  (posp (+ -4 x)))))
      x)

  Now suppose we evaluate a call of foo and obtain a guard violation.

    ACL2 !>(foo 1)


    ACL2 Error in TOP-LEVEL:  The guard for the function call (FOO X),
    which is (AND (INTEGERP X) (POSP (+ -2 X)) (POSP (+ 3 X)) (POSP (+ -4 X))),
    is violated by the arguments in the call (FOO 1).
    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.

  Let us investigate this guard failure.  First we use [47mprint-gv[0m to
  obtain a form that represents our guard violation.  Just for fun,
  we'll check that it indeed evaluates to [47mnil[0m.

    ACL2 !>:print-gv

    (FLET ((FOO{GUARD} (X)
                       (DECLARE (IGNORABLE X))
                       (AND (INTEGERP X)
                            (POSP (+ -2 X))
                            (POSP (+ 3 X))
                            (POSP (+ -4 X)))))
          (FOO{GUARD} 1))

    ACL2 !>(FLET ((FOO{GUARD} (X)
                      (DECLARE (IGNORABLE X))
                      (AND (INTEGERP X)
                           (POSP (+ -2 X))
                           (POSP (+ 3 X))
                           (POSP (+ -4 X)))))
                 (FOO{GUARD} 1))
    NIL

  This form doesn't tell us which of the four conjuncts actually
  evaluated to [47mnil[0m.  We can fix that by using the [47m:conjunct[0m keyword
  argument.

    ACL2 !>(print-gv :conjunct t)

    Showing guard conjunct (#2 of 4) that evaluates to nil:

    (FLET ((FOO{GUARD} (X) (POSP (+ -2 X)))) (FOO{GUARD} 1)).

    ACL2 !>

  But here's another way to analyze the guard failure.  Let's change
  [47m[and][0m to [47m[list][0m in the result of [47m:print-gv[0m, to see which conjuncts
  are false.  Of course, the user can massage the guard form in any
  way that might be helpful.

    ACL2 !>(FLET ((FOO{GUARD} (X)
                      (DECLARE (IGNORABLE X))
                      (list (INTEGERP X)
                            (POSP (+ -2 X))
                            (POSP (+ 3 X))
                            (POSP (+ -4 X)))))
                 (FOO{GUARD} 1))
    (T NIL T NIL)
    ACL2 !>

  The [47mNIL[0m results show that the second and fourth conjuncts of the
  guard were false in our particular case.

  If you use local [stobj]s (see [with-local-stobj]) or stobj fields of
  stobjs, you may need to edit the output of [47mprint-gv[0m in order to
  evaluate it.  Consider the following example.

    (defstobj st fld)

    (defun g (x st)
      (declare (xargs :guard (consp x) :stobjs st)
               (ignore x))
      (fld st))

    (defun test ()
      (with-local-stobj
       st
       (mv-let (result st)
               (mv (g 3 st) st)
               result)))

    (test)

  Then [47m:print-gv[0m yields the result shown below.

    (FLET ((G{GUARD} (X ST)
                     (DECLARE (IGNORABLE X ST))
                     (AND (STP ST) (CONSP X))))
          (G{GUARD} 3 |<some-stobj>|))

  In this example you could replace ``[47m|<some-stobj>|[0m'' by ``[47mst[0m'' to
  obtain a result of [47mnil[0m.  But similar cases may require the use of a
  local stobj that is no longer available, in which case you may need
  to be creative in order to take advantage of [47m:print-gv[0m.  Here is
  such an example.

    (defstobj st2 fld2)

    (defun g2 (st2)
      (declare (xargs :guard (null (fld2 st2)) :stobjs st2))
      (mv 0 st2))

    (defun test2 ()
      (with-local-stobj
       st2
       (mv-let (result st2)
               (let ((st2 (update-fld2 17 st2)))
                 (g2 st2))
               result)))

    (test2)

  In this case, [47m:print-gv[0m yields the following.

    (FLET ((G2{GUARD} (ST2)
                      (DECLARE (IGNORABLE ST2))
                      (AND (ST2P ST2) (NULL (FLD2 ST2)))))
          (G2{GUARD} |<some-stobj>|))

  But if you replace ``[47m|<some-stobj>|[0m'' by ``[47mst[0m'', the guard holds; it
  is only the local stobj, which is no longer available, that
  produced a guard violation (because its field had been updated to a
  cons).

    ACL2 !>(FLET ((G2{GUARD} (ST2)
                             (DECLARE (IGNORABLE ST2))
                             (AND (ST2P ST2) (NULL (FLD2 ST2)))))
                 (G2{GUARD} st2))
    T
    ACL2 !>

  We conclude with an example that illustrates point (1) above,
  regarding the installation of the [world] that was in place at the
  time the guard violation took place.  In the following, the [47m[progn][0m
  call fails when the form [47m(foo 3)[0m causes a guard violation.

    (progn (defn g (x) (consp x))
           (defun foo (x) (declare (xargs :guard (g x))) (car x))
           (value-triple (foo 3)))

  We can then issue [47mprint-gv[0m:

    ACL2 !>:print-gv

    (FLET ((FOO{GUARD} (X) (DECLARE (IGNORABLE X)) (G X))) (FOO{GUARD} 3))

    ACL2 !>

  However, if you try to evaluate this form, you will get an error
  because the function [47mg[0m is not currently defined.  This problem can
  be solved by preceding [47m:print-gv[0m with [47m:redo-flat[0m, to re-run the
  events up to the one that failed; see [redo-flat].


Subtopics

  [Set-print-gv-defaults]
      Set default keyword values for [47m[print-gv][0m")
 (PRINT-OBJECT$
  (IO ACL2-BUILT-INS)
  "Print an object to an open object output channel

    General Form:
    (print-object$ x channel state)

  where [47mx[0m is any ACL2 object and [47mchannel[0m is an open object output
  channel.  See [io].


Remarks

  A newline is printed just above [47mx[0m.  To eliminate that newline or
  print a given comment instead, see [print-object$+].

  [47mPrint-object$[0m pays attention to the values of [print-control]
  variables.  To provide them as keyword arguments rather than
  assigning them globally, see [print-object$+].

  By default, the output of [47mprint-object$[0m is human-readable.  To use
  [serialize] printing instead, first set the serialize character
  using [47m[set-serialize-character][0m.

  For a related utility, see [47m[write-list][0m.")
 (PRINT-OBJECT$+
  (IO ACL2-BUILT-INS)
  "Print an object to an open output channel in a specified manner

    General Form:
    (print-object$+ x       ; an ACL2 object
                    channel ; an open object output channel
                    &key
                    header  ; nil or a comment string (see below)
                    serialize-character       ; as in with-serialize-character
                    print-base print-case ... ; print-control variables
                    )

  This macro is a more flexible variant of [47m[print-object$][0m.  Any of the
  print-control variables may be provided as a keyword; see
  [print-control].  All arguments are evaluated.

  The [47m:header[0m is printed so that it immediately precedes [47mx[0m.  By
  default, a single newline is what is printed for the header.  If
  [47m:header[0m is specified as [47mnil[0m then no such header is printed.
  Otherwise, the value [47m:header[0m should be a string for which the first
  non-whitespace character (if any) on each line is a semicolon ([47m;[0m).
  If the last character of the string is not a newline, then a
  newline will be printed to separate the string from [47mx[0m.

  The [47m:serialize-character[0m keyword argument has a default of [47mnil[0m.  If
  it is supplied a value other than [47mnil[0m or [47m'nil[0m (even if it is
  supplied an expression other than those two constants), then it is
  an error to supply other keyword arguments.  Otherwise printing is
  done without serialization (see [serialize]).")
 (PRINT-OBJECT$-PRESERVING-CASE (POINTERS)
                                "See [io].")
 (PRINT-SUMMARY-USER (POINTERS)
                     "See [finalize-event-user].")
 (PRINTING-TO-STRINGS
  (IO)
  "Printing to strings instead of files or standard output

  Each of ACL2's formatted printing functions, [47mFM*[0m, has an analogous
  macro [47mFM*-TO-STRING[0m indicated below.  These functions do not
  include a channel or [47m[state][0m as an argument, and [47mFM*-TO-STRING[0m
  returns the string that [47mFM*[0m would print to the state, in place of
  [47mstate[0m; see [fmt].  The legal keyword arguments are described below.

    General Forms:                                 result
    (fms-to-string string alist &key ...)          ; string
    (fmt-to-string string alist &key ...)          ; (mv col string)
    (fmt1-to-string string alist column &key ...)  ; (mv col string)
    (fms!-to-string string alist &key ...)         ; string
    (fmt!-to-string string alist &key ...)         ; (mv col string)
    (fmt1!-to-string string alist column &key ...) ; (mv col string)

  The legal keyword arguments are as follows.  They are all optional
  with a default of [47mnil[0m.

      [47m:Evisc-tuple[0m is evaluated, and corresponds exactly to the [47mevisc-tuple[0m
      argument of the corresponding [47mFM*[0m function; see [fmt].

      [47m:Fmt-control-alist[0m should typically evaluate to an alist that maps
      print-control variables to values; see [print-control].  Any
      alist mapping variables to values is legal, however.  By
      default the print controls are set according to the value of
      constant [47m*fmt-control-defaults*[0m; [47m:fmt-control-alist[0m overrides
      these defaults.  For example, [47m*fmt-control-defaults*[0m sets the
      right margin just as it is set in the initial ACL2 [state], by
      binding [47mfmt-soft-right-margin[0m and [47mfmt-hard-right-margin[0m to
      their respective defaults of [47m*fmt-soft-right-margin-default*[0m
      and [47m*fmt-hard-right-margin-default*[0m.  The following example
      shows how you can override those defaults, in this case
      arranging to print flat by setting the right margin to a large
      number.

        (fmt-to-string \"~x0\"
                       (list (cons #\\0 (make-list 30)))
                       :fmt-control-alist
                       `((fmt-soft-right-margin . 10000)
                         (fmt-hard-right-margin . 10000)))

  Also see [io] for a discussion of the utility
  [47mget-output-stream-string$[0m, which allows for accumulating the
  results of more than one printing call into a single string but
  requires the use of [47m[state][0m.

  [31;1mRemarks on deviation from the [47m[fmt][0m[31;1m functions.[0m

   1. The [47m[evisc-table][0m is ignored by these functions that print to
      strings.  Use the [47m:evisc-tuple[0m keyword instead.

   2. [Iprinting] is turned off during evaluation of calls of these
      functions, even if it is enabled globally.  The reason is that
      for each iprint index, [47mi[0m, that is bound during creation of the
      result string, that binding would disappear after the string is
      returned; so it would be misleading or an error to read [47m#@i#[0m
      after that return.

   3. The following remark is subtle; see [fmt!] for relevant background.
      By default, there is identical behavior for each pair of
      functions of the form [47mfm<..>-to-string[0m and [47mfm<..>!-to-string[0m:
      both functions act like the [47mfm<..>![0m function, which is to say,
      they both avoid printing a backslash ([47m\\[0m) when the right margin
      is exceeded, so that the results can be read by ACL2.  If you
      include the pair [47m(:WRITE-FOR-READ NIL)[0m in [47m:fmt-control-alist[0m,
      then the [47mfm<..>-to-string[0m functions will be free to insert such
      backslashes; but that pair will have no effect on the
      [47mfm<..>!-to-string[0m functions.")
 (PROBE-FILE
  (IO PROGRAMMING-WITH-STATE)
  "Determine whether a file exists

  ACL2 does not directly support the Common Lisp function, [47mprobe-file[0m,
  which indicates whether or not a given file exists.  But see
  [canonical-pathname] and see [file-write-date$] for ways to check
  in ACL2 whether a file exists.")
 (PROFILE
  (EVENTS)
  "Turn on profiling for one function

  NOTE: An alternative to this utility, which has significantly less
  functionality but doesn't use [hons-enabled] features of ACL2, may
  be found in community book [47mbooks/misc/profiling.lisp[0m.  See
  [hons-and-memoization] for a general discussion of [memoization],
  on which this [47mprofile[0m utility is built, and the related features of
  hash consing and applicative hash tables.

  [47mProfile[0m can be useful in Common Lisp debugging and performance
  analysis, including examining the behavior of ACL2 functions.

    Example:
    (profile 'fn)       ; keep count of the calls of fn
    (profile 'fn        ; as above, with some memoize options
             :trace t
             :forget t)
    (memsum) ; report statistics on calls of memoized functions (e.g., fn)
    (clear-memoize-statistics) ; clear memoization (and profiling) statistics

  Evaluation of [47m(profile 'fn)[0m redefines [47mfn[0m so that a count will be kept
  of the calls of FN.  The information recorded may be displayed, for
  example, by invoking [47m([0m[47m[memoize-summary][0m[47m)[0m or (equivalently)
  [47m(memsum)[0m.  If you wish to gather fresh statistics for the
  evaluation of a top-level form, see [clear-memoize-statistics].

  [47mProfile[0m is just a macro that calls [47m[memoize][0m to do its work.  [47mProfile[0m
  gives the two keyword parameters [47m:condition[0m and [47m:recursive[0m of
  [47m[memoize][0m the value [47mnil[0m.  Other keyword parameters for [47mmemoize[0m,
  which must not include [47m:condition[0m, [47m:condition-fn[0m, or [47m:recursive[0m,
  are passed through.  To eliminate profiling, use [47m[unmemoize][0m; for
  example, to eliminate profiling for function [47mfn[0m, evaluate
  [47m(unmemoize 'fn)[0m.

  Functions [47m[profile-all][0m and [47m[profile-ACL2][0m are available for
  profiling all functions or all ACL2 functions, respectively.")
 (PROG2$
  (PROGN$ ACL2-BUILT-INS)
  "Execute two forms and return the value of the second one

  See [hard-error], see [illegal], and see [cw] for examples of
  functions to call in the first argument of [47mprog2$[0m.  Also see
  [progn$] for an extension of [47mprog2$[0m that handles than two
  arguments.

  Semantically, [47m(Prog2$ x y)[0m equals [47my[0m; the value of [47mx[0m is ignored.
  However, [47mx[0m is first evaluated for side effect.  Since the ACL2
  [programming] language is applicative, there can be no logical
  impact of evaluating [47mx[0m.  However, [47mx[0m may involve a call of a
  function such as [47m[hard-error][0m or [47m[illegal][0m, which can cause
  so-called ``hard errors'', or a call of [47m[cw][0m to perform output.

  Here is a simple, contrived example using [47m[hard-error][0m.  The
  intention is to check at run-time that the input is appropriate
  before calling function [47mbar[0m.

    (defun foo-a (x)
      (declare (xargs :guard (consp x)))
      (prog2$
       (or (good-car-p (car x))
           (hard-error 'foo-a
                       \"Bad value for x: ~x0\"
                       (list (cons #\\0 x))))
       (bar x)))

  The following similar function uses [47m[illegal][0m instead of [47mhard-error[0m.
  Since [47millegal[0m has a guard of [47mnil[0m, [guard] verification would
  guarantee that the call of [47millegal[0m below will never be made (at
  least when guard checking is on; see [set-guard-checking]).

    (defun foo-b (x)
      (declare (xargs :guard (and (consp x) (good-car-p (car x)))))
      (prog2$
       (or (good-car-p (car x))
           (illegal 'foo-b
                    \"Bad value for x: ~x0\"
                    (list (cons #\\0 x))))
       (bar x)))

  We conclude with a simple example using [47m[cw][0m from the ACL2 sources.

    (defun print-terms (terms iff-flg wrld evisc-tuple)

    ; Print untranslations of the given terms with respect to iff-flg, following
    ; each with a newline.

    ; We use cw instead of the fmt functions because we want to be able to use this
    ; function in print-type-alist-segments (used in brkpt1), which does not return
    ; state.

      (if (endp terms)
          terms
        (prog2$
         (cw \"~Y01\"
             (untranslate (car terms) iff-flg wrld)
             evisc-tuple)
         (print-terms (cdr terms) iff-flg wrld evisc-tuple))))")
 (PROGN
  (EVENTS)
  "Evaluate some [events]

    Example Form:
    (progn (defun foo (x) x)
           (defmacro my-defun (&rest args)
             (cons 'defun args))
           (my-defun bar (x) (foo x)))

    General form:
    (progn event1 event2 ... eventk)

  where [47mk[0m >= 0 and each [47meventi[0m is a legal embedded event form (see
  [embedded-event-form]).  Each event is evaluated, in sequence.  If
  any event fails, the entire [47mprogn[0m call is deemed to have failed,
  and the logical [world] is rolled back to what it was immediately
  before the [47mprogn[0m call was evaluated.  A utility is provided to
  assist in debugging failures of such execution; see [redo-flat].

  See [set-inhibit-output-lst] for how to control the printing done for
  each event.  By default, each event is printed before it is
  evaluated and a suitable value is printed after successful
  completion.  (Technical note: successful completion produces a
  multiple-value return that is an [error-triple] [47m(mv nil val state)[0m;
  then the value [47mval[0m is printed.)  Printing of both the event and its
  value can both be inhibited by including the symbol, [47mEVENT[0m, in your
  call of [47mset-inhibit-output-lst[0m.

  NOTE: If the [47meventi[0m above are not all legal embedded event forms (see
  [embedded-event-form]), consider using [47m[er-progn][0m or (with great
  care!) [47m[progn!][0m instead.  If your goal is simply to execute a
  sequence of top-level forms that are not necessarily all legal
  embedded event forms, consider using [47mld[0m instead; see [ld].

  For a related event form that does allow introduction of
  [constraint]s and [47m[local][0m [events], see [encapsulate].

  ACL2 does not allow the use of [47mprogn[0m in definitions.  Instead, the
  macro [47m[er-progn][0m can be used for sequencing [state]-oriented
  operations; see [er-progn] and see [state].  If you are using
  single-threaded objects (see [stobj]) you may wish to define a
  version of [47m[er-progn][0m that cascades the object through successive
  changes.  ACL2's [47m[pprogn][0m is the [47mstate[0m analogue of such a macro.

  Remark on return value.  As with all [events], a call of [47mprogn[0m
  returns an [error-triple], [47m(mv erp val state)[0m, where [47merp[0m is nil
  when the event is successfully admitted.  In that case, this is the
  error-triple returned by the final event in the [47mprogn[0m call, or [47m(mv
  nil nil state)[0m if the form is just [47m(progn)[0m.")
 (PROGN!
  (EVENTS)
  "Evaluate some forms, not necessarily [events]

  [31;1mWARNING![0m This event is intended for advanced users who, in essence,
  want to build extensions of ACL2.  See see [defttag], in
  particular, the ``WARNING'' there, and see the warning about
  [stobj]s at the end of this documentation topic.

  [47mProgn![0m can be used like [47m[progn][0m, even in [books].  But unlike
  [47m[progn][0m, [47mprogn![0m does not require its constituent forms to be
  [events] (see [embedded-event-form]), except that the first form
  cannot be a symbol unless it is [47m:state-global-bindings[0m (advanced
  feature, described below).  However, see [make-event] for a
  ``Restriction to the Top Level'' that still applies under a call of
  [47mprogn![0m.

  Because [47mprogn![0m allows non-events, it differs from [47mprogn[0m in another
  important respect: [47mprogn![0m is illegal unless there is an active
  ttag; see [defttag].

  See community book [hacker] for two macros, [with-raw-mode] and
  [with-redef-allowed], each defined in terms of [47mprogn![0m, that allow
  arbitrary forms in contexts that would normally require legal
  embedded event forms.

  Given a form [47m(progn! form1 form2 ... formk)[0m, ACL2 will evaluate each
  [47mformi[0m in turn (for i from 1 to k).  If a form returns more than one
  value (see [mv]) where the first value returned is not [47mnil[0m, then no
  later form will be evaluated and the result returned by the [47mprogn![0m
  call will be [47m(mv erp val state)[0m for some non-[47mnil[0m value [47merp[0m,
  signifying an error (see [ld-error-triples]).  Otherwise the
  evaluation is considered to have succeeded, and will continue with
  later forms.  The value returned by a call of [47mprogn![0m with no such
  error is of the form [47m(mv nil v state)[0m, where [47mv[0m depends on the last
  form as follows.  If the last form evaluates to a single value,
  then [47mv[0m is that value, except if the value is a [stobj], say [47mST[0m,
  then [47mv[0m is the symbol [47mREPLACED-ST[0m.  Otherwise the last form
  evaluates to some [47m(mv nil x ...)[0m, and [47mv[0m is [47mx[0m unless after the final
  form's evaluation we are in raw-mode (see [set-raw-mode]), in which
  case the [47mprogn![0m call returns [47mnil[0m (so that ACL2 can at least print
  the result --- imagine Lisp returning a pathname object from a [47mload[0m
  call, for example).

  The normal undoing mechanism does not generally apply to forms within
  a [47mprogn![0m that are not legal ACL2 [events] (see
  [embedded-event-form]).  In particular, note that a non-[47m[local][0m
  call of [47mprogn![0m in an [47m[encapsulate][0m event will generally be
  evaluated twice: once on each pass.  This fact is worth keeping in
  mind if you are using [47mprogn![0m to change the state of the system; ask
  yourself if it is acceptable to apply that state-changing operation
  more than once.

  Please note that [47mprogn![0m may differ from [47m[progn][0m in the following
  sense: definitions within a call of [47mprogn![0m might not be compiled.
  For example, consider the following book.

    (in-package \"ACL2\")
    (defttag :test)
    (progn  (defun f1 (x) x))
    (progn! (defun f2 (x) x))

  If the underlying Lisp is GCL 2.6.7, then after including this
  certified book (where the default certification took place,
  creating a compiled file), then [47mf1[0m is a compiled function but [47mf2[0m is
  not.  For other Lisps supported by ACL2, both [47mf1[0m and [47mf2[0m are
  compiled, though we are not sure that every function under every
  call of [47mprogn![0m would similarly be compiled.

  We now describe, for system hackers only, a sophisticated extension
  of [47mprogn![0m not mentioned above: support for keyword argument
  [47m:state-global-bindings[0m.  If the first argument of [47mprogn![0m is this
  keyword, then the second argument is treated as a list of bindings
  as expected by ACL2 system function [47m[state-global-let*][0m.  Thus, in
  the ACL2 loop,

    (progn! :state-global-bindings bindings form1 form2 ... formk)

  is treated as follows:

    (progn! (state-global-let* bindings (progn! form1 form2 ... formk)))

  However, in raw Lisp the former is just:

    (progn form1 form2 ... formk)

  Thus, one should use the [47m:state-global-bindings[0m argument with care,
  since the behavior in the ACL2 loop can differ from that in Common
  Lisp.  The intention is that one bind only [state] global variables
  that are relevant to evaluation of the forms within the ACL2 loop
  and are harmlessly ignored for evaluation of those forms in raw
  Lisp.  Here is a typical sort of example, as [state] global
  [47mld-redefinition-action[0m is not relevant to the evaluation of [47m[defun][0m
  in raw Lisp.

    (progn! (remove-untouchable 'ld-redefinition-action nil)
            (progn! :state-global-bindings
                    ((ld-redefinition-action '(:doit . :overwrite)))
                    (defun foo (x)
                      (cons x x)))
            (push-untouchable 'ld-redefinition-action nil))

  Finally, we point out a pitfall of [47mprogn![0m related to [stobj]s.  The
  following book can cause a hard Lisp error, depending on the host
  Common Lisp and whether certifying or including it, when certified
  with a non-[47mnil[0m value for [47mcompile-flg[0m (see [certify-book]).

    (in-package \"ACL2\")
    (defstobj st fld)
    (defttag :my-ttag)
    (progn! (update-fld 3 st))

  The problem is that the [stobj] variable [47mst[0m is not known to raw Lisp.
  The compilation problem disappears if the last form above is
  replaced with the following two forms.

    (include-book \"hacking/hacker\" :dir :system)
    (with-raw-mode
     (let ((live-st (cdr (assoc-eq 'st *user-stobj-alist*))))
       (update-fld 3 live-st)))")
 (PROGN$
  (BASICS ACL2-BUILT-INS)
  "Execute a sequence of forms and return the value of the last one

  This macro expands to a corresponding nest of calls of [47mprog2$[0m; see
  [prog2$].  The examples below show how this works: the first case
  below is typical, but we conclude with two special cases.

    ACL2 !>:trans1 (progn$ (f1 x) (f2 x) (f3 x))
     (PROG2$ (F1 X) (PROG2$ (F2 X) (F3 X)))
    ACL2 !>:trans1 (progn$ (f1 x) (f2 x))
     (PROG2$ (F1 X) (F2 X))
    ACL2 !>:trans1 (progn$ (f1 x))
     (F1 X)
    ACL2 !>:trans1 (progn$)
     NIL
    ACL2 !>


Subtopics

  [Prog2$]
      Execute two forms and return the value of the second one")
 (PROGRAM
  (DEFUN-MODE)
  "To set the default [defun-mode] to [47m:[0m[47m[program][0m

    Example:
    ACL2 !>:program
    ACL2 p!>

  Typing the keyword [47m:program[0m sets the default [defun-mode] to
  [47m:program[0m.

  Functions defined in [47m:program[0m mode are logically undefined but can be
  executed on constants outside of deductive contexts.  See
  [defun-mode].

  Calls of the following macros are ignored (skipped) when in [47m:program[0m
  mode.

    local
    verify-guards
    verify-termination
    defaxiom
    defthm
    deftheory
    in-theory
    in-arithmetic-theory
    regenerate-tau-database
    theory-invariant
    defchoose

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

  See [defun-mode] for a discussion of the [defun-mode]s available and
  what their effects on the logic are.  See [default-defun-mode] for
  a discussion of how the default [defun-mode] is used.  This event
  is equivalent to [47m(table acl2-defaults-table :defun-mode :program)[0m,
  and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs. See [ACL2-defaults-table].

  Recall that the top-level form [47m:program[0m is equivalent to [47m(program)[0m;
  see [keyword-commands].  Thus, to change the default [defun-mode]
  to [47m:program[0m in a book, use [47m(program)[0m, which is an embedded event
  form, rather than [47m:program[0m, which is not a legal form for [books].
  See [embedded-event-form].

  See [program-wrapper] for how to use program-mode functions to avoid
  expensive [guard] checks.


Subtopics

  [Program-wrapper]
      Avoiding expensive [guard] checks using [program]-mode functions")
 (PROGRAM-ONLY
  (GUARD)
  "Functions that cannot be in [logic] mode

  Functions are considered to be ``program-only'' when they are in
  [program] mode and they belong to the list [47m(@
  program-fns-with-raw-code)[0m.  For such a function, its
  executable-counterpart (see [evaluation]) always checks the guard.
  If the guard fails, then even if guard-checking is off, an error is
  signaled because a program-only function is assumed to have an
  executable-counterpart that should only execute the raw Lisp
  definition.  Moreover, an error is always signaled when in
  [safe-mode] (e.g., during macroexpansion), because there is no
  guarantee that evaluation of the raw Lisp code will be ``safe''.

  The constant [47m*initial-program-fns-with-raw-code*[0m provides the initial
  value of [47m(@ program-fns-with-raw-code)[0m.  The value of that constant
  is the list of ACL2 source functions that have special raw-Lisp
  code.  It is important that these [program]-mode functions not be
  converted to [logic] mode.  Otherwise, one could arrange to prove a
  contradiction.  To see how, consider the following example, which
  takes advantage of an unsound use of [47m:[0m[47m[q][0m to prove that a call of a
  program-only function, [47mp-o[0m, returns two different values on the
  same input (an obvious contradiction).

    (defun p-o (x)
      (declare (xargs :guard t))
      (er hard? 'p-o
          \"Attempted logical evaluation of ~x0.\"
          (list 'p-0 x)))

    :q ; exit the ACL2 read-eval-print loop

    (defun p-o (x)
      (declare (xargs :guard t))
      (atom x))

    (lp) ; re-enter the ACL2 read-eval-print loop

    (defthm p-0-nil-is-nil
      (equal (p-o nil) nil)
      :hints ((\"Goal\" :in-theory (disable (:e p-o)))))

    (defthm p-o-nil-is-t
      (equal (p-o nil) t))

  In the ACL2 source one often finds a definition marked with readtime
  conditionals, such as the following.

    (defun p-o (x)
      (declare (xargs :guard t))
      #-acl2-loop-only
      (atom x)
      #+acl2-loop-only
      (er hard? 'p-o
          \"Attempted logical evaluation of ~x0.\"
          (list 'p-0 x)))

  The [47macl2-loop-only[0m annotations arrange that when ACL2 is built, one
  gets the effect described above, where the [47m#+acl2-loop-only[0m code is
  used in the definition known to ACL2 and the [47m#-acl2-loop-only[0m code
  is used in the definition known to raw Lisp.  All function symbols
  with such definitions are in the list mentioned above, that is, the
  value of the constant [47m*initial-program-fns-with-raw-code*[0m.

  In summary: The contradiction proved above explains the restriction
  that [47m[logic][0m-mode functions may not call [program]-mode functions.

  See [safe-mode-cheat-sheet] for possible workarounds, which however
  may compromise soundness.")
 (PROGRAM-WRAPPER
  (PROGRAM PROGRAMMING ADVANCED-FEATURES)
  "Avoiding expensive [guard] checks using [program]-mode functions

  Application programs can benefit from avoiding expensive [guard]
  checks.  Imagine that [47mexpensive-guard-fn[0m is a function whose calls
  may be slow to evaluate, and that [47mexpensive-fn[0m is a function whose
  guard calls [47mexpensive-guard-fn[0m.  So, when you call [47mexpensive-fn[0m at
  the top level, whether directly in the ACL2 read-eval-print loop or
  during [47m[make-event][0m expansion, the guard check may be slow.  If you
  are confident that the guard check will pass, you may thus prefer
  to avoid it.

  The following contrived example shows how to avoid that guard check
  by using a [3mprogram-mode wrapper[0m: a function in [program] mode that
  calls the intended function directly.  The example below
  illustrates that idea by defining [47mexpensive-fn-wrapper[0m as a
  program-mode wrapper for [47mexpensive-fn[0m.  That wrapper has a
  computationally inexpensive guard, typically [47mt[0m, which avoids any
  expensive guard check: after the inexpensive guard check, the
  remaining computation takes place using raw Lisp computation, which
  doesn't do any guard checking.  (See [evaluation] for relevant
  background.)

    (defun fib (n) ; Fibonacci function, just for an example of slow computation
      (declare (xargs :guard (natp n)))
      (if (zp n)
          0
        (if (eql n 1)
            1
          (+ (fib (- n 1))
             (fib (- n 2))))))

    (defun expensive-guard-fn (n)
      (declare (xargs :guard t))
      (and (natp n)
           (natp (fib n))))

    (defun expensive-fn (n)
      (declare (xargs :guard (expensive-guard-fn n)))
      (* 2 n))

    ; The following may take about a second, virtually all in the guard check.
    (time$ (expensive-fn 40))

    (defun expensive-fn-wrapper (n)
      (declare (xargs :mode :program))
      (expensive-fn n))

    ; The following is virtually instantaneous.
    (time$ (expensive-fn-wrapper 40))

  This trick isn't necessary if your function call is made on behalf of
  a superior call of a function that is guard-verified (or in program
  mode, since that essentially brings us back to the wrapper
  situation).  Consider the following definition, building on the
  example above.

    (defun f (n)
      (declare (xargs :guard (natp n)))
      (expensive-fn n))

    ; The following is virtually instantaneous.
    (time$ (f 40))

  Then evaluation of [47m(f 40)[0m is virtually instantaneous, for the same
  reason that evaluation of [47m(expensive-fn-wrapper 40)[0m is virtually
  instantaneous: after the top-level guard check passes, the rest of
  the computation takes place without guard checks.  Note however
  that if we change the definition by removing guard verification,
  then the trick is once again helpful, as shown by continuing the
  examples above.

    ; Define a logic-mode function that is not guard-verified:
    (defun g (n)
      (expensive-fn n))

    ; The following may take about a second, virtually all in the guard check.
    (time$ (g 40))

  Remark.  This trick may be less effective if you see an
  [47m\"Invariant-risk\"[0m warning, which prevents computation from taking
  place within raw Lisp, thus avoiding guard checks; see
  [invariant-risk].")
 (PROGRAMMING
  (ACL2)
  "Programming in ACL2

  This [documentation] topic is a parent topic under which we include
  documentation topics for built-in functions, macros, and special
  forms, as well as topics for notions important to programming with
  ACL2.  If you don't find what you're looking for, see the Index or
  see individual topics that may be more directly appropriate; for
  example, see [events] for top-level event constructors like
  [47m[defun][0m.  A subtopic, [ACL2-built-ins], contains as subtopics
  (displayed in a flat list) most of the topics in the
  [documentation] hierarchy that appear under this `programming'
  topic.

  If you are unfamiliar with Lisp, we suggest you start by reading
  [gentle-introduction-to-ACL2-programming].

  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,
  [introduction-to-programming-in-ACL2-for-those-who-know-lisp].

  Also see [debugging] for utilities that can aid in programming.


Subtopics

  [ACL2-built-ins]
      ''Catch-all'' topic for built-in ACL2 functions

  [Advanced-features]
      Some advanced features of ACL2

  [Alists]
      Operations on association lists, which bind keys to values.

  [Apply$]
      Apply a badged function or tame lambda to arguments

  [Arrays]
      ACL2 arrays and operations on them

  [Basics]
      Basic control structures for [programming] like [if] and [cond],
      binding operators like [let] and [flet], multiple-value
      constructs like [mv], and so forth.

  [Characters]
      Characters in ACL2 and operations on them

  [Compilation]
      Compiling ACL2 functions

  [Conses]
      A [31;1mcons[0m is an ordered pair.  In ACL2, data structures like [lists],
      [alists], etc., are made up of conses.

  [Declare]
      Extra declarations that can occur in function definitions, [let]
      bindings, and so forth.

  [Defabbrev]
      A convenient form of macro definition for simple expansions

  [Defconst]
      Define a constant

  [Defmacro]
      Define a macro

  [Defmacro-untouchable]
      Define an ``untouchable'' macro

  [Defpkg]
      Define a new symbol package

  [Defun]
      Define a function symbol

  [Efficiency]
      Efficiency considerations

  [Equality-variants]
      Versions of a function using different equality tests

  [Errors]
      Support for causing runtime errors, breaks, assertions, etc.

  [Evaluation]
      Evaluating ACL2 expressions

  [Fast-alists]
      Alists with hidden hash tables for faster execution

  [Get-internal-time]
      Runtime vs. realtime in ACL2 timings

  [Guard]
      Restricting the domain of a function

  [Hons]
      [47m(hons x y)[0m returns a [normed] object equal to [47m(cons x y)[0m.

  [Introduction-to-programming-in-ACL2-for-those-who-know-lisp]
      Introduction to programming in ACL2 for Lisp users

  [Invariant-risk]
      Potential slowdown for [program]-mode updates to [stobj]s or
      [arrays]

  [Io]
      Input/output facilities in ACL2

  [Irrelevant-formals]
      Formals that are used but only insignificantly

  [Lists]
      Lists of objects, the classic Lisp data structure.

  [Loop$]
      Iteration with an analogue of the Common Lisp [47mloop[0m macro

  [Loop$-primer]
      Primer for using [47m[loop$][0m

  [Mbe]
      Attach code for execution

  [Memoize]
      Turn on memoization for a specified function

  [Mutual-recursion]
      Define some mutually recursive functions

  [Numbers]
      Numbers in ACL2 and operations on them

  [Packages]
      Collections of symbols that act as namespaces.

  [Primitive]
      Primitive functions built into ACL2 without definitions

  [Program-wrapper]
      Avoiding expensive [guard] checks using [program]-mode functions

  [Programming-with-state]
      Programming using the von Neumannesque ACL2 [state] object

  [Redefining-programs]
      An explanation of why we restrict redefinitions

  [Revert-world]
      Evaluate without (ultimately) changing the [world]

  [Set-check-invariant-risk]
      Affect certain [program]-mode updates to [stobj]s or [arrays]

  [Set-duplicate-keys-action]
      Control action for macro calls with duplicate keyword arguments

  [Set-register-invariant-risk]
      Avoid [invariant-risk] checking for specified functions

  [Sleep]
      Sleep for some number of seconds

  [State]
      The von Neumannesque ACL2 state object

  [Stobj]
      Single-threaded objects or ``von Neumann bottlenecks''

  [Strings]
      Strings are atomic objects that contain character sequences, like
      [47m\"Hello World\"[0m.

  [Symbols]
      Symbols in ACL2 and operations on them

  [System-attachments]
      System-level algorithms that users can modify with attachments

  [System-utilities]
      Some built-in programming utilities pertaining to the ACL2 system

  [Time$]
      Time the evaluation of a given form

  [Unmemoize]
      Turn off memoization for the specified function")
 (PROGRAMMING-KNOWLEDGE-TAKEN-FOR-GRANTED
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Background knowledge in ACL2 programming for theorem prover tutorial

  This brief review of the programming language is presented as a
  sequence of questions and answers meant to test your knowledge of
  the ACL2 programming language.  If you want a gentle introduction
  to the programming language, see
  [gentle-introduction-to-ACL2-programming].

  Before we get started with the programming drill, let us remind you
  that all we're interested in here is the language, not the
  ``program development environment.'' It's impossible to program in
  ACL2 or any other language without a decent environment, one that
  at the very least includes a way to prepare and edit files of
  programs.  The two most popular program development environments
  among ACL2 users are [Emacs] {ICON} (see [A_Tiny_Warning_Sign]) and
  the Eclipse-based [ACL2-Sedan] {ICON} (see [A_Tiny_Warning_Sign]).
  The Sedan provides the most support for the new user, including
  real-time syntax checking and a facility for testing among many
  other features.  But in this drill we're not interested in the
  program development environment, we're interested in your
  understanding of the ACL2 language.

  [31;1mQ[0m: What do you think this command does?

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

  [31;1mA[0m: It defines a function named [47mrev[0m that takes one argument, treats it
  like a list, and reverses the order of the elements in that list.
  To figure this out from the definition, you have to know that
  [47mappend[0m concatenates two lists.  Logically speaking, the [47mdefun[0m of
  [47mrev[0m adds the axiom:

    (rev x)
    =
    (if (endp x)
        nil
        (append (rev (cdr x)) (list (car x)))),

  implicitly quantified for all [47mx[0m.

  [31;1mQ[0m: Given the [47mdefun[0m of [47mrev[0m above, what are the [3mformal parameters[0m?
  What is the [3mbody[0m of the definition?  Write down a [3mcall[0m of [3mappend[0m
  that occurs in the body of [47mrev[0m.  What are the [3mactuals[0m of that call?
  [31;1mA[0m: The [3mformals[0m of [47mrev[0m is the list of variables after the first [47mrev[0m
  in the [47mdefun[0m, namely [47m(x)[0m.  We say [47mx[0m is the first (and only) [3mformal[0m
  here.  The [3mbody[0m of [47mrev[0m is the entire [47mif[0m-expression.  The only [3mcall[0m
  of [47mappend[0m in the body is

    (append (rev (cdr x)) (list (car x)))

  and the [3mactuals[0m of that call are, respectively, [47m(rev (cdr x))[0m and
  [47m(list (car x))[0m.

  [31;1mQ[0m: What do you get if you evaluate [47m(rev '(a b c d))[0m?  [31;1mA[0m: [47m(D C B A)[0m.

  [31;1mQ[0m: How did [47mrev[0m change the case of the elements, e.g., lowercase [47ma[0m was
  in the input list but uppercase [47mA[0m was in the output?  [31;1mA[0m: This is a
  trick question.  [47mRev[0m doesn't change the case of the elements.  ACL2
  is case-insensitive when dealing with symbols.  The symbol [47ma[0m is
  read in as the symbol [47mA[0m.  Thus, when writing function names, for
  example, we can write [47mrev[0m, [47mRev[0m, [47mREV[0m, or even [47mReV[0m and always be
  referring to the function [47mREV[0m.  By default, ACL2 prints symbols in
  uppercase.

  [31;1mQ[0m: What does [47m(rev '((a b c) \"Abc\" \"a\" b #\\c))[0m return?  [31;1mA[0m: [47m(#\\c B \"a\"
  \"Abc\" (A B C))[0m.  If you thought the answer was either of these,
  then you need to think or read more carefully:

    (#\\C B \"A\" \"ABC\" (A B C))

    (#\\c B \"a\" \"Abc\" (C B A))

  The first wrong answer above is wrong because Lisp is ``case
  insensitive'' only for symbols, not for character objects like [47m#\\c[0m
  (the lowercase character c) or for strings.  Furthermore, [47m\"A\"[0m is a
  string, not a symbol; it is different from [47mA[0m.  The second wrong
  answer above is wrong because [47mrev[0m does not go into the individual
  elements of the list, it just reverses the order of the elements.
  So it doesn't change the element [47m(A B C)[0m to [47m(C B A)[0m.

  [31;1mQ[0m: In the question about what [47m(rev '(a b c d))[0m returns, we put a
  quote mark before the [47m(a b c d)[0m but not before the answer, [47m(D C B
  A)[0m.  Why?  [31;1mA[0m: The phrase ``[3mx[0m evaluates to [3my[0m'' treats [3mx[0m as a [3mterm[0m to
  be evaluated and [3my[0m as an [3mobject[0m.  [47m(Rev '(a b c d))[0m is a term to be
  evaluated and denotes a call of the function [47mrev[0m on the value of
  the argument term [47m'(a b c d)[0m.  The value of that argument term is
  the object [47m(a b c d)[0m.  The value of the call of [47mrev[0m is the object
  [47m(d c b a)[0m.  If you have an object, [3mobj[0m, and you wish to create a
  term whose value is [3mobj[0m, then you put a quote mark in front of it,
  [3m'obj[0m.

  [31;1mQ[0m: Can [47mrev[0m be applied to something other than a list?  [31;1mA[0m: Yes, every
  ACL2 function can be applied to any object.  ACL2 is an untyped
  programming language: every variable ranges over the entire
  universe of objects.  In normal usage, [47mrev[0m is applied to lists but
  there is nothing about the syntax of the language that prevents it
  being applied to non-lists.

  [31;1mQ[0m: So what does [47m(rev 23)[0m evaluate to?  [31;1mA[0m: [47mNil[0m.

  [31;1mQ[0m: Why?  [31;1mA[0m: Because [47m(endp 23)[0m is [47mt[0m, because [47mendp[0m is defined:

    (defun endp (x) (not (consp x)))

  Thus, if [47mrev[0m is applied to anything that is not a cons, it returns
  [47mnil[0m.

  [31;1mQ[0m: So what does [47m(rev '(a b c . d))[0m evaluate to?  [31;1mA[0m: [47m(c b a)[0m.  To
  explain why requires demonstrating that you know what [47m(a b c . d)[0m
  means.  It is the object computed by evaluating:

    (cons 'a
          (cons 'b
                (cons 'c
                      'd))).

  That is, it is a list whose ``terminal marker'' is the atom [47mD[0m.  [47mRev[0m
  treats that list exactly as it treats the [47mnil[0m-terminated list of
  the same elements, [47m(a b c)[0m, because [47m(endp 'D)[0m = [47m(endp nil)[0m = [47mt[0m.

  [31;1mQ[0m: What does [47m(rev 1 2 3)[0m evaluate to?  [31;1mA[0m: That's a trick question.
  [47mRev[0m takes one argument, not three.  So [47m(rev 1 2 3)[0m is an ill-formed
  term.

  [31;1mQ[0m: What does [47m(rev '(a b c . d . nil))[0m evaluate to?  [31;1mA[0m: That is a
  trick question.  There is no such object.  In Lisp's ``dot
  notation'' every dot must be followed by a well-formed object and
  then a close parenthesis.  Usually that ``well-formed object'' is
  an atom.  If it is not an atom, i.e., if it is a cons, then the
  entire expression could have been written without that dot.  For
  example, [47m(a b c . (d e))[0m is an object, but it could be written [47m(a b
  c d e)[0m.

  [31;1mQ[0m: Do [47m(rev (rev x))[0m and [47mx[0m always evaluate to the same object?  [31;1mA[0m: No.
  [47m(Rev (rev 23))[0m evaluates to [47mnil[0m, not [47m23[0m.

  [31;1mQ[0m: Do [47m(rev (rev x))[0m and [47mx[0m always evaluate to the same object when [47mx[0m
  is a cons?  [31;1mA[0m: No.  [47m(rev (rev '(a b c . d)))[0m evaluates to [47m(a b c)[0m,
  not [47m(a b c . d)[0m.

  [31;1mQ[0m: When are [47m(rev (rev x))[0m and [47mx[0m equal?  [31;1mA[0m: When the terminal marker
  of [47mx[0m is [47mnil[0m.

  [31;1mQ[0m: Can you define a Lisp function that recognizes [47mnil[0m-terminated
  lists?  [31;1mA[0m: Yes, but it is not necessary for the user to define that
  concept because Common Lisp provides such a function which is
  logically defined as follows:

    (defun true-listp (x)
      (if (consp x)
          (true-listp (cdr x))
          (equal x nil))).

  This can be paraphrased: [47m(true-listp x)[0m means that if [47mx[0m is a [47mcons[0m,
  its [47mcdr[0m is a [47mtrue-listp[0m and if [47mx[0m is not a [47mcons[0m, it must be [47mnil[0m.
  Thus, [47m(true-listp '(a b c))[0m is [47mt[0m and [47m(true-listp '(a b c . d))[0m is
  [47mnil[0m.

  [31;1mQ[0m: Can you write a Lisp formula that says ``If [47mz[0m is a [47mnil[0m-terminated
  list then reversing the result of reversing [47mz[0m is [47mz[0m''?

  [31;1mA[0m: Yes:

    (implies (true-listp z)
             (equal (rev (rev z)) z)).

  [31;1mQ[0m: Is this all there is to ACL2 programming?  [31;1mA[0m: No!  ACL2 provides
  many other features.  For a full list of all the primitive
  functions in ACL2 see [programming] {ICON} (see
  [A_Tiny_Warning_Sign]).  Some highlights for the beginner are
  mentioned below, but all of the links below ought to be tagged with
  the {ICON} (see [A_Tiny_Warning_Sign]) sign.

  * [47m[list][0m: build a [47mnil[0m-terminated list from the values of [3mn[0m terms,
  e.g., [47m(list x (+ 1 x) (+ 2 x))[0m returns [47m(3 4 5)[0m if [47mx[0m is [47m3[0m.

  * [list*]: build a non-[47mnil[0m terminated list of [3mn[0m objects from the
  values of [3mn+1[0m terms, e.g., [47m(list* x (+ 1 x) (+ 2 x) (* -1 x))[0m
  returns the list [47m(3 4 5 . -3)[0m if [47mx[0m is [47m3[0m.

  * [47m[and][0m, [47m[or][0m, [47m[not][0m, [47m[implies][0m, [47m[iff][0m: The propositional
  connectives.  [47mAnd[0m and [47mor[0m are allowed to take a varying number of
  arguments, e.g., [47m(and p q r)[0m is just an abbreviation for [47m(and p
  (and q r))[0m.  In Lisp, [47mand[0m returns [47mnil[0m if any of its arguments
  evaluates to [47mnil[0m; otherwise it returns the value of the last
  argument!  Thus, [47m(and t t 3)[0m returns [47m3[0m!  If you object to the idea
  that [47mand[0m is not Boolean, don't give it non-Boolean arguments!
  Similarly, [47mor[0m returns the value of the first argument that
  evaluates to non-[47mnil[0m, or [47mnil[0m if they all evaluate to [47mnil[0m.  Both [47mand[0m
  and [47mor[0m can be thought of as ``lazy'' in that they don't always have
  to evaluate all their arguments.  This is really accomplished by
  treating [47mand[0m and [47mor[0m as abbreviations for [47mif[0m nests.

  * [47m[+][0m, [47m[*][0m, [47m[-][0m, [47m[/][0m, [47m[floor][0m, [47m[mod][0m, [47m[<][0m, [47m[<=][0m, [47m[>=][0m, [47m[>][0m: the Lisp
  elementary arithmetic operators.  Both [47m+[0m and [47m*[0m allow varying
  numbers of arguments.  All the arithmetic operators default
  non-numeric arguments to [47m0[0m.  If you don't like the idea that [47m(+ 1 2
  t)[0m is [47m3[0m, don't ask [47m+[0m to add [47mt[0m to something!

  * [47m[natp][0m, [47m[integerp][0m, [47m[rationalp][0m, [47m[characterp][0m, [47m[stringp][0m,
  [47m[symbolp][0m, [47m[consp][0m: the recognizers for the primitive data types.
  The first three recognize subsets of the ACL2 numeric universe.
  The naturals are a subset of the integers, the integers are a
  subset of the rationals, and the rationals are a subset of the
  objects recognized by [47m[ACL2-numberp][0m, which also includes the
  [47m[complex-rationalp][0ms.  The other recognizers listed above recognize
  characters, strings, symbols, and conses.

  * [47m[cond][0m: a convenient way to write a cascading nest of [47mif[0ms, e.g.,

    (cond ((not (natp x)) 'non-natural)
          ((equal x 0) 'zero)
          ((evenp x) 'positive-even)
          (t 'positive-odd))

  abbreviates

    (if (not (natp x))
        'non-natural
        (if (equal x 0)
            'zero
            (if (evenp x)
                'positive-even
                'positive-odd))).

  * [47m[case][0m: a convenient way to case split on the identity of an
  object.

    (case key
      (non-natural -1)
      (zero 0)
      ((positive-even positive-odd) 'positive-natural)
      (otherwise 'unknown))

  abbreviates

    (cond ((eql key 'non-natural) -1)
          ((eql key 'zero) 0)
          ((member key '(positive-even positive-odd))
           'positive-natural)
          (t 'unknown)).

  * user defined macros: using [47m[defmacro][0m {ICON} (see
  [A_Tiny_Warning_Sign]) you can introduce your own abbreviations.
  We recommend you not do this until you're good at list processing
  since macros are functions that build objects representing terms.

  * [47m[mutual-recursion][0m: allows you to define mutually-recursive
  functions.

  * [47m[mv][0m and [47m[mv-let][0m: allow functions to return ``multiple-values''.
  In Lisp, such functions return vectors of values, the vectors are
  represented as lists of values, but the implementations are
  generally more efficient.  For example, [47m(mv x y z)[0m returns a
  ``vector'' consisting of the values of [47mx[0m, [47my[0m, and [47mz[0m.

    (mv-let (a b c)
            (foo x)
            (bar a b c x))

  evaluates [47m(foo x)[0m, treats the result as a vector of three values,
  binds the variables [47ma[0m, [47mb[0m, and [47mc[0m to those three values, and
  evaluates and returns [47m(bar a b c x)[0m.

  ACL2 also provides many other features, such as single-threaded
  objects which may be ``destructively modified'' (see [stobj] {ICON}
  (see [A_Tiny_Warning_Sign]), including a very special
  single-threaded object that records the [47m[state][0m {ICON} (see
  [A_Tiny_Warning_Sign]) of the ACL2 system), file input and output
  (see [io] {ICON} (see [A_Tiny_Warning_Sign])), applicative arrays
  (see [arrays] {ICON} (see [A_Tiny_Warning_Sign])) and property
  lists (see [getprop] {ICON} (see [A_Tiny_Warning_Sign])) and other
  facilities necessary for it to be a practical programming language.
  However, we [31;1mstrongly[0m recommend that as a new user you stay away
  from these features until you are good at proving theorems about
  elementary list processing!

  If this little drill made sense to you, you know enough of the
  programming language to get started. Use your browser's [31;1mBack Button[0m
  now to return to [introduction-to-the-theorem-prover].

  If you are uncomfortable with ACL2 programming, we recommend that you
  study [gentle-introduction-to-ACL2-programming] and
  {http://www.cs.utexas.edu/users/moore/publications/acl2-programming-exercises1.html
  |
  http://www.cs.utexas.edu/users/moore/publications/acl2-programming-exercises1.html}.

  However, we strongly recommend that you first invest in learning
  either the [Emacs] or Eclipse-based [ACL2-Sedan] program
  development environments, since it is foolish to try to learn how
  to program in a stand-alone read-eval-print loop!

  While getting started, many users find the Hyper-Card a handy index
  into the documentation for the ACL2 language:

  {http://www.cs.utexas.edu/users/moore/publications/hyper-card.html |
  http://www.cs.utexas.edu/users/moore/publications/hyper-card.html}

  Once you are comfortable with the ACL2 programming language, use your
  browser's [31;1mBack Button[0m to return to
  [introduction-to-the-theorem-prover].")
 (PROGRAMMING-WITH-STATE
  (STATE PROGRAMMING)
  "Programming using the von Neumannesque ACL2 [state] object

  This [documentation] section introduces some common techniques for
  programming using the ACL2 state object.  A prerequisite is thus a
  basic understanding of that object; see [state].  We hope this
  section is useful, and we invite suggestions for improvements and
  additions.

  A supplement to this section is the ACL2 source code, which uses most
  (and probably all) of the techniques discussed here.  That code is
  thus a source of many examples, which can serve as ``templates'' to
  guide one's own programming with state.

  Recall that ``ACL2'' stands for ``A Computational Logic for
  Applicative Common Lisp''.  In particular, the language is
  applicative: there are no global variables or side effects.  For
  many purposes this does not feel restrictive; for example, an ACL2
  user who is programming in raw Lisp may well be more comfortable
  coding a factorial function applicatively, using recursion, rather
  than using iteration with repeated assignment to the same variable.

  However, there are situations that call for reading or modifying the
  system state, such as performing input and output, signaling
  errors, saving information from one computation for use in a later
  one, or reading and updating system-level or environmental data.
  This section provides an introductory guide for writing functions
  that traffic in state.  We emphasize that this guide is intended as
  an introduction; more complete documentation may often be found by
  following links to documentation of individual utilities, and
  again, more examples may be found by searching the ACL2 source code
  for uses of the functions and macros mentioned below.  The rest of
  this section is organized as follows.

    ENABLING PROGRAMMING WITH STATE
    STATE GLOBALS AND THE ACL2 LOGICAL WORLD
    A REMARK ON GUARDS
    ERRORS AND ERROR TRIPLES
    SEQUENTIAL PROGRAMMING
    BINDING VARIABLES USING ERROR TRIPLES
    BINDING STATE GLOBAL VARIABLES
    INPUT AND OUTPUT
    TIMINGS
    ENVIRONMENT AND SYSTEM
    REMARKS ON EVENTS AND LD
    ADVANCED TOPICS

  ENABLING PROGRAMMING WITH STATE

  In order to submit a definition that takes [47m[state][0m as a formal
  parameter, you must either declare [47mstate[0m as a [47m:[0m[47m[stobj][0m (see
  [xargs]) or first evaluate the following form at the top level:
  [47m(set-state-ok t)[0m.

  Consider for example the following trivial definition.

    (defun foo (state)
      (mv 3 state))

  If you submit the above definition in a fresh ACL2 session, you will
  get this error message.

    ACL2 Error in ( DEFUN FOO ...):  The variable symbol STATE should not
    be used as a formal parameter of a defined function unless you are
    aware of its unusual status and the restrictions enforced on its use.
    See :DOC set-state-ok.

  If first you evaluate [47m(set-state-ok t)[0m, you can admit the above
  definition.  Alternatively, you can declare [47mstate[0m as a [47m:[0m[47m[stobj][0m, as
  follows.

    (defun foo (state)
      (declare (xargs :stobjs state))
      (mv 3 state))

  A difference in the two approaches is that for the latter, a [guard]
  proof obligation is generated by default.  See the section below
  entitled ``A remark on guards''.

  STATE GLOBALS AND THE ACL2 LOGICAL WORLD

  Recall (see [state]) that one of the fields of the ACL2 state object
  is the global-table, which logically is an alist associating
  symbols, known as ``state globals'' or ``state global variables'',
  with values.  But no such alist actually exists in the
  implementation.  Instead, ACL2 provides utilities for reading state
  globals --- see [@] and see [f-get-global] --- and utilities for
  writing them --- see [assign] and see [f-put-global].  The
  following log shows how they work; further explanation follows
  below.

    ACL2 !>(assign my-var (+ 3 4))
     7
    ACL2 !>(@ my-var)
    7
    ACL2 !>(f-put-global 'my-var (+ 1 5) state)
    <state>
    ACL2 !>(f-get-global 'my-var state)
    6
    ACL2 !>

  Note that the first result is indented by one space.  This is ACL2's
  way to indicate that the [47m[assign][0m expression returned an ``error
  triple'' and that no error was signaled.  We discuss error triples
  in more detail below; also see [error-triple].

  As illustrated above, the output signatures of the utilities for
  assigning to state globals differ from each other as follows:
  [47m[f-put-global][0m returns [47mstate[0m, but [47m[assign][0m returns an error triple
  [47m(mv nil val state)[0m where [47mval[0m is the value assigned to the state
  global.  The output signatures of the utilities for reading, [47m@[0m and
  [47mf-get-global[0m, are identical.  In fact, the form [47m(f-get-global
  'my-var state)[0m is the single-step macroexpansion of the form [47m(@
  my-var)[0m, as can be confirmed using [47m[trans1][0m.

    ACL2 !>:trans1 (@ my-var)
     (F-GET-GLOBAL 'MY-VAR STATE)
    ACL2 !>

  State globals are useful for conveying persistent state information.
  Consider for example the utility [47m[set-inhibit-output-lst][0m.  The
  form [47m(set-inhibit-output-lst '(prove proof-tree))[0m is approximately
  equivalent to (assign inhibit-output-lst '(prove proof-tree)).  We
  say ``approximately'' because [47mset-inhibit-output-lst[0m additionally
  does some error checking to ensure that all the tokens in the new
  list are legal.  When deciding whether to print output, the ACL2
  system reads the value of state global variable [47minhibit-output-lst[0m.

  A particularly useful state global is [47mcurrent-acl2-world[0m, whose value
  is the ACL2 logical [world].  Because the ACL2 world is commonly
  accessed in applications that use the ACL2 state, ACL2 provides a
  function that returns the world: [47m(w state) = (f-get-global
  'current-acl2-world state)[0m.  While it is common to read the world,
  only functions [47mset-w[0m and [47mset-w![0m are available to write the world,
  but these are untouchable and should generally be avoided except by
  system implementors (see [remove-untouchable]).

  You may wish to modify state globals within a book, but this can be
  slightly problematic because only legal event forms (see
  [embedded-event-form]) may go into [books].  Fortunately there is a
  workaround using [47mmake-event[0m; see [make-event], in particular the
  section ``Examples Illustrating How to Access State''.

  A REMARK ON GUARDS

  For a function definition (see [defun]), if [47mstate[0m is specified as a
  [stobj] as with the form [47m(declare (xargs :stobjs state))[0m, then the
  [guard] for that function is considered to include the condition
  [47m(state-p state)[0m.  By default, [guard] verification will then be
  performed.  (Note for advanced system hackers: There is also a
  stronger predicate, [47m(state-p+ state)[0m, which for example implies the
  guards for [47mfmt[0m and related functions.

  We can illustrate this point by modifying the example above as
  follows, to read the value of state global [47mgag-mode[0m.

    (defun foo (state)
      (declare (xargs :stobjs state))
      (f-get-global 'gag-mode state))

  If you try this in a fresh ACL2 session, the proof will fail with the
  following key checkpoint, which says that the state global [47mgag-mode[0m
  is bound in the global-table of the state.

    (IMPLIES (STATE-P1 STATE)
             (ASSOC-EQUAL 'GAG-MODE (NTH 2 STATE)))

  How can we deal with this proof failure?  One way is simply to ignore
  the issue by defining the function in [47m:[0m[47m[program][0m mode, as follows.

    (defun foo (state)
      (declare (xargs :stobjs state
                      :mode :program))
      (f-get-global 'gag-mode state))

  Perhaps a better way is to strengthen the guard to assert that the
  indicated state global is bound, as follows.

    (defun foo (state)
      (declare (xargs :guard (boundp-global 'gag-mode state)
                      :stobjs state))
      (f-get-global 'gag-mode state))

  Also see [guard-miscellany] for discussion of guard generation from
  [47m[xargs][0m fields of [declare] forms, specifically, for keywords
  [47m:guard[0m, [47m:stobjs[0m, and [47m:dfs[0m.

  ERRORS AND ERROR TRIPLES

  When evaluation returns three values, where the first two are
  ordinary objects and the third is the ACL2 state, the result may be
  called an ``error triple''.  (Whether it is treated as an error
  triple depends on the programmer.)  Error triples are often denoted
  [47m(mv erp val state)[0m, and common ACL2 programming idioms treat [47merp[0m as
  a flag indicating whether an error is being signaled and [47mval[0m as the
  ``value'' computed.  Also see [error-triple].

  Even ACL2 users who are not programmers encounter error triples,
  because these are the values returned by evaluation of ACL2
  [events].  Consider the following log, where the only user input is
  the [47mdefun[0m form following the [prompt].

    ACL2 !>(defun foo (x) x)

    Since FOO is non-recursive, its admission is trivial.  We observe that
    the type of FOO is described by the theorem (EQUAL (FOO X) X).

    Summary
    Form:  ( DEFUN FOO ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     FOO
    ACL2 !>

  All output above results from explicit calls of output functions,
  except for the next-to-last line, which contains [47mFOO[0m.  Notice the
  single-space indentation preceding [47mFOO[0m.  That space indicates that
  in fact, the value returned by evaluation of the [47mdefun[0m form is the
  error triple whose error flag is [47mnil[0m and whose computed value is
  [47mFOO[0m.  By default, ACL2 prints any error triple [47m(mv nil val state)[0m
  by inserting a space before printing [47mval[0m.  You can change the
  default by setting state global [47m[ld-post-eval-print][0m to [47mt[0m; notice
  how the same result is printed below.

    ACL2 !>:u
              0:x(EXIT-BOOT-STRAP-MODE)
    ACL2 !>(set-ld-post-eval-print t state)
    (NIL T <state>)
    ACL2 !>(defun foo (x) x)

    Since FOO is non-recursive, its admission is trivial.  We observe that
    the type of FOO is described by the theorem (EQUAL (FOO X) X).

    Summary
    Form:  ( DEFUN FOO ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
    (NIL FOO <state>)
    ACL2 !>

  The way error triples are printed by [47mld[0m is controlled not only by
  state global [47mld-post-eval-print[0m, but also by state global
  [47mld-error-triples[0m.  These are examples of ``ld specials''; see [ld],
  see [ld-post-eval-print], and see [ld-error-triples].

  It is so common to produce an error triple whose first (error flag)
  component is [47mnil[0m that ACL2 provides a handy macro, [47mvalue[0m, for this
  purpose.  Thus, [47m(value <expression>)[0m is equivalent to [47m(mv nil
  <expression> state)[0m.  Also see [value-triple] for a similar
  construct that is a legal event form.

  We turn now to the topic of errors.  The macro [47m[er][0m ``causes'' an
  error, but there are really two quite different kinds of errors:
  ``soft'' and ``hard'' errors.  We use the term ``soft error'' to
  refer to a form that returns an error triple [47m(mv erp val state)[0m for
  which [47merp[0m is non-[47mnil[0m.  Soft errors do not interrupt the normal flow
  of evaluation: the error triple is returned to the caller which
  interprets the [47merp[0m flag and [47mval[0m as directed by the programmer.
  Macros discussed below make it convenient to think about soft
  errors as short-circuiting the computation.  Hard errors, on the
  other hand, do actually rip control away from the current
  evaluation and return it to the top-level loop.  Logically
  speaking, expressions that cause hard errors return [47mnil[0m in the
  error case, but the [47mnil[0m is never seen in actual evaluation because
  control does not return to the caller.

  Note that the function [47m[abort!][0m, which you can invoke by typing
  [47m:[0m[47m[a!][0m, always returns to the top level.  Note that ACL2 can prove
  that [47m(abort!)[0m returns [47mnil[0m but that this cannot be confirmed by
  computation.

    ACL2 !>(thm (equal (abort!) nil))

    Q.E.D.

    Summary
    Form:  ( THM ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL)
            (:TYPE-PRESCRIPTION ABORT!))
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

    Proof succeeded.
    ACL2 !>(equal (abort!) nil)
    Abort to ACL2 top-level
    ...
    ACL2 !>

  (What actually happens with a hard error, including non-default
  cases, is a bit subtle; most readers will probably want to skip
  this paragraph.  The read-eval-print loop implemented by [47m[ld][0m is
  implemented by a call of the ACL2 evaluator function, [47mtrans-eval[0m,
  on each input form.  If a hard error occurs during evaluation of an
  input form, its [47mtrans-eval[0m call will return with a soft error.
  [47m[Ld][0m, in turn handles that soft error appropriately; see
  [ld-error-action].)

  The most common way to signal errors is the macro [47m[er][0m, which prints
  a formatted error message and returns a soft or hard error as
  specified by the call.  Note however that soft errors are signaled
  using [47m:[0m[47m[program][0m mode functions.

  Since the output signatures of soft and hard errors are different ---
  hard errors ``return'' a single value while soft errors return a
  triple --- mixing them in an expression requires embedding the hard
  error form in (an irrelevant) triple, as illustrated below.  All
  branches of the expression must produce an error triple if any
  branch does.

    ACL2 !>(defun chk-find-or-abort (e x state)
             (declare (xargs :mode :program))
             (if (endp x)
                 (value                          ; Note use of VALUE!
                   (er hard 'chk-find-or-abort
                       \"Did not find ~x0!\"
                        e))
                 (if (not (integerp (car x)))
                     (er soft 'chk-find-or-abort
                         \"Non-integer, ~x0, in list!\"
                         (car x))
                     (if (eql (car x) e)
                         (value x)
                         (chk-find-or-abort e (cdr x) state)))))

    Summary
    Form:  ( DEFUN CHK-FIND-OR-ABORT ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     CHK-FIND-OR-ABORT
    ACL2 !>(chk-find-or-abort 3 '(1 2 3 4 5) state)
     (3 4 5)
    ACL2 !>(chk-find-or-abort 3 '(1 A 3 4 5) state)

    ACL2 Error in CHK-FIND-OR-ABORT:  Non-integer, A, in list!

    ACL2 !>(chk-find-or-abort 3 '(1 2 4 5) state)

    HARD ACL2 ERROR in CHK-FIND-OR-ABORT:  Did not find 3!
    ...
    ACL2 !>

  See [er] for further discussion of errors.  For some other individual
  topics related to errors see [assert$], see [break-on-error], see
  [error1], see [hard-error], see [illegal], and see
  [ld-error-triples].

  In the next section we discuss soft errors further, in the context of
  programming.

  SEQUENTIAL PROGRAMMING

  This section describes handy ways to modify state in steps, using
  macros that implement a sequence of [47m[let][0m or [47m[mv-let][0m bindings.
  For example, suppose you want to assign the values 1 and 2 to two
  state globals [47mone-var[0m and [47mtwo-var[0m, respectively.  Because of ACL2's
  syntactic restrictions on [47m[state][0m, it is not legal simply to write
  [47m(f-put-global 'two-var 2 (f-put-global 'one-var 1 state))[0m.
  However, [47m[let][0m comes to the rescue as follows.

    (let ((state (f-put-global 'one-var 1 state)))
      (let ((state (f-put-global 'two-var 2 state)))
        state))

  It is so common to bind state successively in such a manner that ACL2
  provides a macro, [47m[pprogn][0m, for this purpose.  Thus, an equivalent
  solution to the problem above is

    (pprogn (f-put-global 'one-var 1 state)
            (f-put-global 'two-var 2 state)
            state)

  or, more simply, as follows.

    (pprogn (f-put-global 'one-var 1 state)
            (f-put-global 'two-var 2 state))

  See [pprogn].  Note that the last form is allowed to return multiple
  values; the only requirement on the last form is that its value
  include [47mstate[0m.

  It is also common to update the state using a sequence of forms such
  that each returns an error triple, where the intention is for
  evaluation to short-circuit immediately if a soft error is
  encountered.  Suppose [47m<expr1>[0m and [47m<expr2>[0m are expressions that
  return error triples, where the [47mstate[0m components of the error
  triples might be updated, and one wishes to evaluate [47m<expr1>[0m and
  then [47m<expr2>[0m, returning the (multiple) values returned by [47m<expr2>[0m
  unless the error triple returned by [47m<expr1>[0m is a soft error, in
  which case that error triple is returned.  One can of course do so
  as follows.

    (mv-let (erp val state)
            <expr1>
            (cond (erp (mv erp val state))
                  (t <expr2>)))

  But ACL2 provides a handy macro, [47m[er-progn][0m, for this purpose.  The
  following code is equivalent to the code just above.

    (er-progn <expr1> <expr2>)

  See [er-progn] for more details.  Note that unlike [47m[pprogn][0m, the
  return [signature] for the last expression must be the same as that
  of the others: an error triple.

  Let's consider how to use [47mpprogn[0m and [47mer-progn[0m together.  In the
  following example [47mf1[0m and [47mf2[0m both return [47mstate[0m, while each of [47mg1[0m and
  [47mg2[0m returns an error triple.  The following code modifies state by
  executing these in the order [47mf1[0m, [47mg1[0m, [47mf2[0m, and finally [47mg2[0m, returning
  [47m(mv nil val state)[0m where [47mval[0m is the value component of the error
  triple returned by [47mg2[0m --- except we return a soft error if [47mg1[0m or [47mg2[0m
  returns a soft error.

    (pprogn (f1 x state)
            (er-progn (g1 x state)
                      (pprogn (f2 x state)
                              (g2 x state))))

  Finally, consider the [events] [47m[progn][0m and [47m[progn!][0m.  These have
  similar behavior to that of [47m[er-progn][0m.  However, [47m[progn][0m and
  [47m[progn!][0m may only be used in event contexts, for example at the top
  level or immediately underneath a call of [47m[encapsulate][0m or [47m[progn][0m,
  while [47m[er-progn][0m has no such restriction.  So when writing code,
  use [47mer-progn[0m rather than [47m[progn][0m or [47m[progn!][0m.  In particular, the
  body of a [47m[defun][0m must not have any calls of [47mprogn[0m (or of [47mprogn![0m
  either), and the same restriction holds for any code to be
  executed, such as the body of a [47m[make-event][0m form.

  BINDING VARIABLES USING ERROR TRIPLES

  In this section we discuss the macro [47mer-let*[0m, which is a variant of
  the special form, [47m[let*][0m, that is useful when programming with
  state.  A related utility that avoids the use of state is
  [47mer-let*-cmp[0m; see [context-message-pair].

  The macro [47mer-let*[0m is useful when binding variables to the value
  components of error triples.  It is actually quite similar to
  [47mer-progn[0m, described above, except that [47mer-let*[0m binds variables.
  First consider the following example.

    (er-let* ((x1 (f1 state))
              (x2 (f2 x1 state)))
      (value (cons x1 x2)))

  The code just above is essentially equivalent to writing the
  following.

    (mv-let (erp x1 state)
            (f1 state)
            (cond (erp (mv erp x1 state))
                  (t (mv-let (erp x2 state)
                             (f2 x1 state)
                             (cond (erp (mv erp x2 state))
                                   (t (value (cons x1 x2))))))))

  As suggested by the example above, [47mer-let*[0m has the same syntax as
  [47mlet*[0m, except that declarations are not supported.  (But note that
  [47mignore[0m declarations are not needed; all variables that are bound
  are also used, at least in the error case.  Consider replacing
  [47m(cons x1 x2)[0m by [47mnil[0m in the example displayed immediately above, and
  note that [47mx1[0m and [47mx2[0m are still used.)  However, unlike [47mlet*[0m, [47mer-let*[0m
  requires that for each binding [47m(var expr)[0m, the expression [47mexpr[0m must
  evaluate to an error triple and, moreover, it requires that the
  second argument (the ``body'') of [47mer-let*[0m must evaluate to an error
  triple.  If one of the variable expressions (e.g., the [47mf1[0m and [47mf2[0m
  calls above) signals an error, its error triple is returned as the
  value of the [47mer-let*[0m.

  Of course, soft errors can be ``caught'' by using [47m[mv-let][0m instead of
  [47mer-let*[0m and simply ignoring the error flag or, more generally, by
  returning a non-erroneous error triple even if the error flag was
  on.

  BINDING STATE GLOBAL VARIABLES

  In this section we introduce a utility, [47m[state-global-let*][0m, that is
  an analogue of [47mlet*[0m for state global variables.  Consider the
  following example.

    (state-global-let*
     ((inhibit-output-lst (add-to-set-eq 'summary (@ inhibit-output-lst))))
     (thm (equal x x)))

  This form binds state global variable [47minhibit-output-lst[0m to the
  result of adding the symbol, [47msummary[0m, to the current value of that
  state global.  Thus (see [set-inhibit-output-lst]), the usual
  [summary] is not printed when evaluating this call of [47m[thm][0m.

  See [state-global-let*] for more complete [documentation].

  INPUT AND OUTPUT

  In ACL2, most input and output involves the ACL2 state.  See [io].

  TIMINGS

  For how to obtain the time elapsed since the start of the ACL2
  session, see [read-run-time].

  For a utility for saving times into the ACL2 state and for printing
  those saved times, see the community book [47mmisc/save-time.lisp[0m.

  To time an evaluation (though this really isn't about state), see
  [time$].

  ENVIRONMENT AND SYSTEM

  Next, we mention briefly some ways in which ACL2 interacts with its
  environment using the ACL2 state.

  For how to read and write environment variables, see [getenv$] and
  see [setenv$].

  For how to run a command in the host operating system, see
  [sys-call], [sys-call+], and [sys-call*].

  REMARKS ON EVENTS AND LD

  In general, undefined or surprising behavior may occur when using
  ACL2 [events] or calling [ld] in your programs.  In some cases ACL2
  enforces restrictions against these uses.  We strongly discourage
  using [47m[ld][0m in programs, as it has been designed to be called only
  at the top level of a read-eval-print loop.  However, you may wish
  to read or write [47m[ld][0m specials in your programs; see [ld].

  There is also a restriction on contexts in which [47m[make-event][0m may be
  called: it may only be called in a context where an event is
  expected, such as the top level, in a book, or as an argument of
  [47m[encapsulate][0m or [47m[progn][0m.  The reason is that ACL2 does very subtle
  and careful tracking of [47m[make-event][0m expansions; and it is only
  able to do this in event contexts, where it is able to carry out
  such tracking accurately.

  ADVANCED TOPICS

  ACL2 provides the function [47mtrans-eval[0m to evaluate an arbitrary form
  (after translating it to a [term], i.e., into internal form).  For
  more information, we refer to reader to comments in the definition
  of [47mtrans-eval[0m in the ACL2 source code.  There are also many
  examples of its use in the ACL2 sources.

  For a function that provides the true absolute filename, with soft
  links resolved, see [canonical-pathname].

  For a function that returns a checksum on the characters in a
  channel, see [checksum].

  To obtain a random number, see [random$].

  If you are programming in raw-mode (see [set-raw-mode]) or in raw
  Lisp, use the variable [47m*the-live-state*[0m in place of the variable
  [47mstate[0m.

  We invite suggestions for additional advanced topics.


Subtopics

  [@]
      Get the value of a global variable in [47m[state][0m

  [Assign]
      Assign to a global variable in [47m[state][0m

  [Canonical-pathname]
      The true absolute filename, with soft links resolved

  [Cbd]
      Connected book directory string

  [Er-progn]
      Perform a sequence of state-changing ``error triples''

  [Error-triple]
      A common ACL2 programming idiom

  [F-boundp-global]
      Check whether a global variable in [47m[state][0m has a value

  [F-get-global]
      Get the value of a global variable in [47m[state][0m

  [F-put-global]
      Assign to a global variable in [47m[state][0m

  [Get-cpu-time]
      Read elapsed cpu time

  [Get-real-time]
      Read elapsed real time

  [Getenv$]
      Read an environment variable

  [Last-prover-steps]
      The number of prover steps most recently taken

  [Makunbound-global]
      Remove the value assigned to a global variable in [47m[state][0m

  [Pprogn]
      Evaluate a sequence of forms that return [state]

  [Probe-file]
      Determine whether a file exists

  [Read-ACL2-oracle]
      Pop the oracle field of the state

  [Read-run-time]
      Read elapsed runtime

  [Setenv$]
      Set an environment variable

  [State-global-let*]
      Bind [state] global variables

  [With-live-state]
      Allow a reference to [47mstate[0m in raw Lisp")
 (PROGRAMP (POINTERS)
           "See [system-utilities].")
 (PROHIBITION-OF-LOOP$-AND-LAMBDA$
  (DEFCONST DEFMACRO DEFPKG)
  "Certain events do not allow [47m[loop$][0ms or [47m[lambda$][0ms

  Certain events, including [47m[defconst][0m, [47m[defmacro][0m, and [47m[defpkg][0m,
  prohibit the use of [47m[loop$][0m and [47m[lambda$][0m.  The prohibition of
  [47mloop$[0ms is due to their use of [47mlambda$[0ms, so we focus on why [47mlambda$[0ms
  are prohibited here.

  [47mLambda$[0m is prohibited in these events because of the way [books] are
  loaded.  To speed up the execution of [47minclude-book[0m the compiled
  file for a book is loaded before the events in the book are
  processed.  But the evaluation of [47mlambda$[0m expressions in raw Lisp
  depends on the [47mlambda$[0ms having been translated and recorded in the
  logical world and in the lambda cache (see [47m[print-cl-cache][0m).  So
  the execution of these events can't depend on [47mlambda$[0m.

  If you have submitted an event that provoked an error citing this
  topic you must restate the event to avoid those prohibited
  constructions.  [3mUnfortunately, you must also consider ancestral
  occurrences of the prohibited constructions![0m We first give two
  examples of the problem to drive home the message and then we
  discuss various ways the problem can be dealt with.


Examples of Prohibited Forms

    ACL2 !>(defconst *2^10* (apply$ (lambda$ (x) (expt 2 x)) '(10)))

    ACL2 Error in ( DEFCONST *2^10* ...):  We prohibit certain events,
    including DEFCONST, DEFPKG, and DEFMACRO, from being ancestrally dependent
    on loop$ and lambda$ expressions.  But at least one of these prohibited
    expressions occurs in this event.  See :DOC prohibition-of-loop$-and-
    lambda$.

  We will discuss how to avoid such errors in the next section.

  Here is an example of an ancestral use of [47mlambda$[0m in a macro.
  Suppose we wish to define the macro [47mrat[0m so that [47m(rat \"123.4567\")[0m
  expands to the rational [47m1234567/10000[0m.  Our idea is to use [47mloop$[0m in
  the definition of the function [47mstring-to-rat[0m and then to call
  [47mstring-to-rat[0m in our macro.  (We don't recommend this particular
  use of [47mloop$[0ms to parse a string into a rational but we use it here
  to make a point later.)

    (defun string-to-rat (str)
      (let* ((lst (coerce str 'list))
             (right-of-pt (length (cdr (loop$ for d in lst
                                              as tail on lst
                                              thereis
                                              (if (eql #. d) tail nil))))))
        (loop$ for tail on lst
               when (not (eql (car tail) #.))
               sum
               (* (- (char-code (car tail)) 48)
                  (expt 10
                        (- (loop$ for d in tail sum (if (eql d #.) 0 1))
                           (+ 1 right-of-pt)))))))

    (defmacro rat (str) (string-to-rat str))

  The attempt to define the macro will provoke the error shown above
  for [47m(defconst *2^10* ...)[0m.


Avoiding These Errors

  The only way to avoid these errors is to not use [47mlambda$[0m or [47mloop$[0m in
  these events!  We can fix the particular [47mdefconst[0m example above
  simply with

    (defconst *2^10* (apply$ 'expt '(2 10)))

  or, better yet, by

    (defconst *2^10* (expt 2 10))

  since there is reason [47mapply$[0m is involved at all.

  When it is hard to avoid the prohibited constructs you might be able
  to use [47mmake-event[0m to do the necessary computation during the
  creation of the event, though this technique seems mainly
  applicable to [47mdefconst[0m and much less useful to the [47mdefmacro[0m case.

    (make-event
      `(defconst *2^10*
        ',(apply$ (lambda$ (x) (expt 2 x)) '(10))))

  However, in general, removing all uses of [47mloop$[0m and [47mlambda$[0m can
  require a lot of re-coding.  For example, fixing the [47mrat[0m macro
  requires several old-fashioned recursive definitions to carry out
  the iterations done with [47mloop$[0m.

    (defun old-fashioned-string-to-rat1 (lst power)
      (cond
       ((endp lst) 0)
       ((eql (car lst) #.)
        (old-fashioned-string-to-rat1 (cdr lst) power))
       (t (+ (* (- (char-code (car lst)) 48)
                (expt 10 power))
             (old-fashioned-string-to-rat1 (cdr lst) (- power 1))))))

    (defun left-of-pt (lst)
      (cond ((endp lst) 0)
            ((eql (car lst) #.) 0)
            (t (+ 1 (left-of-pt (cdr lst))))))

    (defun old-fashioned-string-to-rat (str)
      (let ((lst (coerce str 'list)))
        (old-fashioned-string-to-rat1 lst (- (left-of-pt lst) 1))))

    (defmacro rat (str) (old-fashioned-string-to-rat str))

  Another way to eliminate [47mloop$[0m and [47mlambda$[0m is to replace the
  offending expressions with their translations.  There is no
  prohibition of fully-translated quoted [47m[lambda][0m objects, just of
  [47mlambda$[0m expressions.

    (defun string-to-rat (str)
      ((LAMBDA
        (LST)
        ((LAMBDA
          (RIGHT-OF-PT LST)
          (SUM$+
           '(LAMBDA
             (LOOP$-GVARS LOOP$-IVARS)
             (DECLARE (IGNORABLE LOOP$-GVARS LOOP$-IVARS))
             ((LAMBDA
               (RIGHT-OF-PT TAIL)
               (BINARY-*
                (BINARY-+ '-48 (CHAR-CODE (CAR TAIL)))
                (EXPT
                 '10
                 (BINARY-+
                  (SUM$
                   '(LAMBDA (LOOP$-IVAR)
                            (DECLARE (IGNORABLE LOOP$-IVAR))
                            ((LAMBDA (D) (IF (EQL D '#.) '0 '1))
                             LOOP$-IVAR))
                   TAIL)
                  (UNARY-- (BINARY-+ '1 RIGHT-OF-PT))))))
              (CAR LOOP$-GVARS)
              (CAR LOOP$-IVARS)))
           (CONS RIGHT-OF-PT 'NIL)
           (WHEN$+
            '(LAMBDA
              (LOOP$-GVARS LOOP$-IVARS)
              (DECLARE (IGNORABLE LOOP$-GVARS LOOP$-IVARS))
              ((LAMBDA (TAIL)
                       (NOT (EQL (CAR TAIL) '#.)))
               (CAR LOOP$-IVARS)))
            'NIL
            (LOOP$-AS (CONS (TAILS LST) 'NIL)))))
         (LENGTH
          (CDR
           (THEREIS$+
            '(LAMBDA
              (LOOP$-GVARS LOOP$-IVARS)
              (DECLARE (IGNORABLE LOOP$-GVARS LOOP$-IVARS))
              ((LAMBDA (D TAIL)
                       (IF (EQL '#. D) TAIL 'NIL))
               (CAR LOOP$-IVARS)
               (CAR (CDR LOOP$-IVARS))))
            'NIL
            (LOOP$-AS (CONS LST (CONS (TAILS LST) 'NIL))))))
         LST))
       (COERCE STR 'LIST)))

  If we define [47mstring-to-rat[0m as above then we can define the [47mrat[0m macro
  as originally desired and the [47mdefmacro[0m is accepted.

  But there are several arguments against this approach in general:

    * [47mDefconst[0m, [47mdefmacro[0m and [47mdefpkg[0m not only prohibit [47mloop$[0m and [47mlambda$[0m but
      also prohibit all uses of [47mapply$[0m and scions if user-defined
      functions are involved in the function objects.  This is
      because to compute logically with them one must have [warrant]
      hypotheses and there is no provision for supplying warrants
      with these events.  See [ignored-attachment].  It turns out
      that the hideous example above does not mention any
      user-defined functions in the function objects, so this
      restriction doesn't stop us here.

    * Eliminating [47mloop$[0m in favor of scions sacrifices execution speed if
      the [47mloop$[0ms are guard verified.  A guard-verified [47mloop$[0m executes
      in raw Lisp as a Common Lisp [47mloop[0m, whereas its translation into
      nested calls of [47mloop$[0m scions, even if guard verified, involves
      far more function calls.

    * It is much harder to ``maintain'' code derived this way!

  There may be cases where no user-defined functions are involved,
  efficiency doesn't matter, and the [47mloop$[0m scion translation of a
  [47mloop$[0m is as perspicuous as the [47mloop$[0m itself.  So don't dismiss this
  approach out of hand.")
 (PROJECT-DIR-ALIST
  (BOOKS EVENTS)
  "Support for moving project directories (also [47m:dir[0m arguments)

  This topic describes the [47mproject-dir-alist[0m, which supports the
  relocation of book directories so that their [books] are still
  treated as certified.  Each such directory is treated as a [3mproject[0m,
  which is represented by a [keyword].  In particular, the keyword,
  [47m:SYSTEM[0m, represents the [community-books] as such a project.  The
  [47mproject-dir-alist[0m also provides one way to interpret the [47m:dir[0m
  keyword argument of [47m[include-book][0m and [47m[ld][0m.

  It is theoretically possible to undermine soundness by using this
  capability inappropriately (see below for some discussion of
  appropriate usage).  For the utmost security, perform a fresh
  certification of your entire collection of books without using this
  capability.  See [certificate], specifically the discussion there
  about placing a ``burden'' on the user.

  To see the [47mproject-dir-alist[0m in your session, evaluate the form
  [47m(project-dir-alist (w state))[0m.

  We start below by introducing the [47mproject-dir-alist[0m and explaining
  how to set it up.  Next we describe its effects.  We conclude by
  discussing some details, limitations, and restrictions.


What is the [47mproject-dir-alist[0m and how is it established?

  The [47mproject-dir-alist[0m is an association list that maps keywords to
  directory names.  If we map keyword [47m:K[0m to directory [47m\"<dir>\"[0m, we say
  that the project name [47mK[0m is associated with project directory
  [47m\"<dir>\"[0m.

  The way to establish the [47mproject-dir-alist[0m is to set environment
  variable [47mACL2_PROJECTS[0m to the name of a file, which we will call
  the ``projects file''.  The projects file may have lines of the
  following form, where we write [47m:K[0m to denote an arbitrary keyword
  and [47m\"<dir>\"[0m to denote a directory name inside double-quotes.

    :K \"<dir>\"

  Such a line associates the project name [47mK[0m with the project directory
  [47m\"dir\"[0m.  Each remaining line in a projects file should either be
  blank (i.e., contain only whitespace) or else be a comment line,
  that is, a line for which the first non-whitespace character is a
  semicolon ([47m;[0m).

  The projects file is read when ACL2 starts up.  ACL2 creates the
  [47mproject-dir-alist[0m by using each line as above to associate the
  keyword [47m:K[0m with the directory represented by [47m\"<dir>\"[0m, which may be
  a relative or absolute pathname.  Relative pathnames are
  interpreted with respect to the directory of the projects file.

  If the keyword [47m:SYSTEM[0m is not specified in the projects file, then
  the [47mproject-dir-alist[0m will additionally include a pair that
  associates [47m:SYSTEM[0m with the [community-books] directory, which is
  generally the [47mbooks/[0m subdirectory of your ACL2 distribution.  That
  value for [47m:SYSTEM[0m can be overridden either by specifying it
  explicitly with [47m:SYSTEM[0m in the projects file or by setting
  environment variable [47mACL2_SYSTEM_BOOKS[0m to that value --- where if
  both overrides are used, they must not conflict.

  The values of the environment variables mentioned above,
  [47mACL2_PROJECTS[0m and [47mACL2_SYSTEM_BOOKS[0m, are pathnames that can be
  either relative or absolute.  A relative pathname is interpreted
  with respect to the directory in which ACL2 is invoked.  The final
  character need not be ``[47m/[0m''; if it's not, then that character will
  be added at the end before adding to the [47mproject-dir-alist[0m.

  The [47mproject-dir-alist[0m must have no duplicate keys and no duplicate
  directory names.


Effects of the [47mproject-dir-alist[0m

  There are the following two effects of the association of a keyword
  [47m:K[0m with a directory [47m\"<dir>\"[0m in the [47mproject-dir-alist[0m.

  [31;1m(1) [47m:K[0m[31;1m specifies a project directory that may be moved.[0m

      Consider first the default case, where there is a single association
      in the [47mproject-dir-alist[0m: [47m:SYSTEM[0m is associated with the
      [community-books] directory.  Suppose that the community books
      and their certificates are moved to a new directory, [47m\"<dir>\"[0m.
      Then if you run ACL2 in an environment where the
      [47mproject-dir-alist[0m associates [47m:SYSTEM[0m with [47m\"<dir>\"[0m, the
      relocated community books will still be treated as certified.

      The case of [47m:SYSTEM[0m described above generalizes naturally, as
      follows.  Let [47mS[0m be a set of books certified with a given
      [47mproject-dir-alist[0m, each of which includes only other books in
      [47mS[0m.  (For example, [47mS[0m contains just the community books directory
      in the special case above.)  Also assume that the absolute
      pathname of every book in [47mS[0m has a prefix among the directories
      in that [47mproject-dir-alist[0m.  Then all books in [47mS[0m, along with
      their [certificate] files, can be moved and those books will
      still be considered to be certified in any ACL2 session with a
      suitable [47mproject-dir-alist[0m, as follows.  For every keyword [47m:K[0m
      mapped to directory [47m\"<dir>\"[0m in the original [47mproject-dir-alist[0m
      (the one at certification time), the new [47mproject-dir-alist[0m
      should map [47m:K[0m to the directory [47m\"<dir2>\"[0m to which [47m\"<dir>\"[0m was
      moved.

  [31;1m(2) [47m:K[0m[31;1m can be used as a [47m:dir[0m[31;1m keyword, to reference [47m\"<dir>\"[0m[31;1m.[0m

      The optional [47m:dir[0m keyword argument of [47m[include-book][0m and [47m[ld][0m can
      have value [47m:K[0m, in which case the pathname argument is
      interpreted with respect to [47m\"<dir>\"[0m.  This behavior is the same
      as when [47m:K[0m is bound to [47m\"<dir>\"[0m using [47m[add-include-book-dir][0m or
      [47m[add-include-book-dir!][0m.


Additional details

      [31;1mPrefixes.[0m Suppose [47m:K1[0m and [47m:K2[0m are keywords bound in the
      [47mproject-dir-alist[0m to [47m\"<dir1>\"[0m and [47m\"<dir2>\"[0m, respectively, where
      [47m\"<dir1>\"[0m is a prefix of [47m\"<dir2>\"[0m (hence is strictly shorter,
      since duplicates are disallowed, as noted above).  Then it may
      be simplest to maintain that property --- that the value of [47m:K1[0m
      is a prefix of the value of [47m:K2[0m --- when creating a new
      [47mACL2_PROJECTS[0m directory to reflect relocation of these
      directories of books.  The actual requirement is that
      directories under the old value of [47m:K2[0m need to be moved to the
      same relative locations under the new value of [47m:K2[0m, and all
      other directories under the old value of [47m:K1[0m need to be moved
      to the same relative locations under the new value of [47m:K1[0m.

      [31;1m[47m[Save-exec][0m[31;1m.[0m By default, an executable created with [47m[save-exec][0m will
      have an unchanged [47mproject-dir-alist[0m.  However, a new
      [47mproject-dir-alist[0m will be created as described above if
      environment variable [47mACL2_PROJECTS[0m is set; also, if environment
      variable [47mACL2_SYSTEM_BOOKS[0m is set, then the existing
      [47mproject-dir-alist[0m will be modified to map [47m:SYSTEM[0m to the value
      of [47mACL2_SYSTEM_BOOKS[0m.


Additional Limitations and Restrictions

      (Already noted above) [31;1mNo duplicates.[0m There must be no duplicate keys
      or duplicate directory names in the [47mproject-dir-alist[0m.

      [31;1mNo overlap.[0m No keyword may be bound with [47m[add-include-book-dir][0m or
      [47m[add-include-book-dir!][0m that is also bound in the
      [47mproject-dir-alist[0m.

      [31;1mAvoid using absolute pathnames in books.[0m Consider a form that
      contains an absolute pathname, such as [47m(defconst *c*
      \"/u/home/jones/bk\")[0m.  If that form is in a book [47mB[0m that is
      moved, then of course it remain in [47mB[0m after the move.  That is
      certainly fine, unless one expects this pathname to change as [47mB[0m
      is moved.  That said, an absolute pathname that extends a
      project directory is OK in an [47m[include-book][0m form among the
      [portcullis] commands for a book, in the following sense: it is
      replaced in that book's [certificate] by referencing the
      project's keyword name to avoid using an absolute pathname.


Subtopics

  [Sysfile]
      File representation using ACL2 project directories")
 (PROMPT
  (LD)
  "The prompt printed by [47m[ld][0m

  The prompt printed by ACL2 conveys information about various
  ``modes.'' See [default-print-prompt] and see [ld-prompt] for
  details.

  The prompt in raw Lisp, including [breaks] from the ACL2 loop, can be
  adjusted by ACL2 to include the string [47m\"[RAW LISP[0m\"], at least for
  most Common Lisp implementations.  That change can help to remind
  users not to submit ACL2 forms there.  That adjustment is made by
  executing the following form in raw Lisp (for example, after typing
  [47m:[0m[47m[q][0m).

    (install-new-raw-prompt)

  To return to printing the original Lisp prompt in raw lisp, evaluate
  the following in raw Lisp.

    (install-old-raw-prompt)")
 (PROOF-BUILDER
  (ACL2 DEBUGGING)
  "An interactive tool for controlling ACL2's proof processes.

  Call this up with [47m(verify ...)[0m.

  The [3minteractive proof-builder[0m provides a way to explore the
  development of ACL2 proofs below the level of the ACL2 prover (as
  typically used by [47m[thm][0m and [events] such as [47m[defthm][0m).  To use
  this tool, invoke the [47m[verify][0m command, for example as follows.

    ACL2 !>(verify (equal (append (append x y) z)
                          (append x (append y z))))
    ->:

  Then at the [47m\"->:\"[0m prompt, one submits commands that operate on a
  stack of goals, starting with the single goal that was supplied to
  [47mVERIFY[0m as shown above.  The final command (or ``instruction'') can
  be an [47mexit[0m command, which can print out a [47m[defthm][0m event if the
  goal stack is empty; see [proof-builder-commands], in particular
  the [47mexit[0m command.  That resulting [47mdefthm[0m event includes an
  [47m:[0m[47m[instructions][0m parameter, which directs replay of the interactive
  proof-builder commands (for example during certification of a book
  containing that event; see [books]).

  If you exit the interactive proof-builder's loop, you may re-enter
  that session at the same point using the command [47m(verify)[0m, i.e.,
  with no arguments.  The commands [47msave[0m and [47mretrieve[0m may be invoked
  to manage more than one session.

  The interactive proof-builder can be invoked on a specific subgoal,
  and the resulting [47m:instructions[0m can be given as a hint to the
  theorem prover for that subgoal.  See [instructions].

  A tutorial is available {here |
  http://www.cs.utexas.edu/users/kaufmann/tutorial/rev3.html}.  That
  tutorial illustrates more than just the interactive proof-builder.
  The portion relevant to the proof-builder may be accessed directly
  {here |
  http://www.cs.utexas.edu/users/kaufmann/tutorial/rev3.html#slide29}.

  See [set-evisc-tuple] for how to arrange that output is printed in
  abbreviated form.  In general, the interactive proof-builder uses
  the [47m:TERM[0m [evisc-tuple] described in that documentation.

  Individual proof-builder commands are documented in subsection
  [proof-builder-commands].  Note that the package name (see
  [symbol-package-name] is irrelevant for these commands (though not
  their arguments); for example [47m(dive 3)[0m, [47m(acl2::dive 3)[0m,
  [47m(acl2-pc::dive 3)[0m, and [47m(:dive 3)[0m are all equivalent.  For a list of
  perhaps the most commonly used commands, see
  [proof-builder-commands-short-list].

  The proof-builder supports user-defined macros, which are tactics
  that generate proof-builder instructions.  See [define-pc-macro].

  [3mRemark.[0m The ``pc-'' prefix, for example in ``define-pc-macro'' above,
  stems from an earlier name for the proof-builder, which was
  ``proof-checker''.  That also accounts for the string [47m\"PC\"[0m in the
  package name, [47m\"ACL2-PC\"[0m.


Subtopics

  [Define-pc-help]
      Define a macro command whose purpose is to print something

  [Define-pc-macro]
      Define a proof-builder macro command

  [Define-pc-meta]
      Define a proof-builder meta command

  [Dive-into-macros-table]
      Right-associated function information for the [proof-builder]

  [Instructions]
      Instructions to the interactive proof-builder

  [Macro-command]
      Compound command for the interactive proof-builder

  [Proof-builder-commands]
      List of commands for the interactive proof-builder

  [Proof-builder-commands-short-list]
      Perhaps the most commonly used [proof-builder] commands

  [Proof-checker]
      Old name for [proof-builder]

  [Retrieve]
      Re-enter a (specified) [proof-builder] state

  [Toggle-pc-macro]
      Change an ordinary macro command to an atomic macro, or vice-versa

  [Unsave]
      Remove a [proof-builder] state

  [Verify]
      Enter the interactive proof-builder")
 (PROOF-BUILDER-COMMANDS
  (PROOF-BUILDER)
  "List of commands for the interactive proof-builder

  This documentation section contains documentation for individual
  commands that can be given inside the interactive [proof-builder]
  loop that is entered using [47m[verify][0m.  For a summary of (arguably)
  the most useful commands, see [proof-builder-commands-short-list].


Subtopics

  [ACL2-pc::=]
      (atomic macro) attempt an equality (or equivalence) substitution

  [ACL2-pc::ACL2-wrap]
      (macro) same as [47m(lisp x)[0m

  [ACL2-pc::add-abbreviation]
      (primitive) add an abbreviation

  [ACL2-pc::al]
      (macro) same as apply-linear

  [ACL2-pc::apply-linear]
      (primitive) apply a linear rule

  [ACL2-pc::bash]
      (atomic macro) call the ACL2 theorem prover's simplifier

  [ACL2-pc::bdd]
      (atomic macro) prove the current goal using bdds

  [ACL2-pc::bk]
      (atomic macro) move backward one argument in the enclosing term

  [ACL2-pc::bookmark]
      (macro) insert matching ``bookends'' comments

  [ACL2-pc::casesplit]
      (primitive) split into two cases

  [ACL2-pc::cg]
      (macro) change to another goal.

  [ACL2-pc::change-goal]
      (primitive) change to another goal.

  [ACL2-pc::cl-proc]
      (macro) same as [47mclause-processor[0m

  [ACL2-pc::claim]
      (atomic macro) add a new hypothesis

  [ACL2-pc::clause-processor]
      (atomic macro) use a clause-processor

  [ACL2-pc::comm]
      (macro) display instructions from the current interactive session

  [ACL2-pc::commands]
      (macro) display instructions from the current interactive session

  [ACL2-pc::comment]
      (primitive) insert a comment

  [ACL2-pc::contradict]
      (macro) same as [47mcontrapose[0m

  [ACL2-pc::contrapose]
      (primitive) switch a hypothesis with the conclusion, negating both

  [ACL2-pc::demote]
      (primitive) move top-level hypotheses to the conclusion

  [ACL2-pc::dive]
      (primitive) move to the indicated subterm

  [ACL2-pc::do-all]
      (macro) run the given instructions

  [ACL2-pc::do-all-no-prompt]
      (macro) run the given instructions, halting once there is a
      ``failure''

  [ACL2-pc::do-strict]
      (macro) run the given instructions, halting once there is a
      ``failure''

  [ACL2-pc::doc]
      (macro) access documentation inside the interactive proof-builder

  [ACL2-pc::drop]
      (primitive) drop top-level hypotheses

  [ACL2-pc::dv]
      (atomic macro) move to the indicated subterm

  [ACL2-pc::elim]
      (atomic macro) call the ACL2 theorem prover's elimination process

  [ACL2-pc::equiv]
      (primitive) attempt an equality (or congruence-based) substitution

  [ACL2-pc::ex]
      (macro) exit after possibly saving the state

  [ACL2-pc::exit]
      (meta) exit the interactive proof-builder

  [ACL2-pc::expand]
      (primitive) expand the current function call without simplification

  [ACL2-pc::fail]
      (macro) cause a failure

  [ACL2-pc::finish]
      (macro) require completion of instructions; save error if inside
      [47m:[0m[47m[hints][0m

  [ACL2-pc::forwardchain]
      (atomic macro) forward chain from an implication in the hyps

  [ACL2-pc::free]
      (atomic macro) create a ``free variable''

  [ACL2-pc::geneqv]
      (macro) show the generated equivalence relation maintained at the
      current subterm

  [ACL2-pc::generalize]
      (primitive) perform a generalization

  [ACL2-pc::goals]
      (macro) list the names of goals on the stack

  [ACL2-pc::help]
      (macro) proof-builder help facility

  [ACL2-pc::hyps]
      (macro) print the hypotheses

  [ACL2-pc::illegal]
      (macro) illegal instruction

  [ACL2-pc::in-theory]
      (primitive) set the current proof-builder theory

  [ACL2-pc::induct]
      (atomic macro) generate subgoals using induction

  [ACL2-pc::lemmas-used]
      (macro) print the runes (definitions, lemmas, ...) used

  [ACL2-pc::lisp]
      (meta) evaluate the given form in Lisp

  [ACL2-pc::negate]
      (macro) run the given instructions, and ``succeed'' if and only if
      they ``fail''

  [ACL2-pc::nil]
      (macro) used for interpreting [47mcontrol-d[0m

  [ACL2-pc::noise]
      (meta) run instructions with prover output

  [ACL2-pc::noise!]
      (meta) run instructions with prover and proof-tree output

  [ACL2-pc::nx]
      (atomic macro) move forward one argument in the enclosing term

  [ACL2-pc::orelse]
      (macro) run the first instruction; if (and only if) it ``fails'',
      run the second

  [ACL2-pc::p]
      (macro) prettyprint the current term in the usual user-level
      (untranslated) syntax

  [ACL2-pc::p-top]
      (macro) prettyprint the conclusion, highlighting the current term

  [ACL2-pc::pl]
      (macro) print the rules for a given name

  [ACL2-pc::pot-lst]
      (macro) display the linear arithmetic database based on the current
      context

  [ACL2-pc::pp]
      (macro) prettyprint the current term in internal (translated) form

  [ACL2-pc::pr]
      (macro) print the rules for a given name

  [ACL2-pc::print]
      (macro) print the result of evaluating the given form

  [ACL2-pc::print-all-concs]
      (macro) print all the conclusions of (as yet unproved) goals

  [ACL2-pc::print-all-goals]
      (macro) print all the (as yet unproved) goals

  [ACL2-pc::print-main]
      (macro) print the original goal

  [ACL2-pc::pro]
      (atomic macro) repeatedly apply promote

  [ACL2-pc::promote]
      (primitive) move antecedents of conclusion's [47mimplies[0m term to
      top-level hypotheses

  [Proof-builder-commands-short-list]
      Perhaps the most commonly used [proof-builder] commands

  [ACL2-pc::protect]
      (macro) run the given instructions, reverting to existing state upon
      failure

  [ACL2-pc::prove]
      (primitive) call the ACL2 theorem prover to prove the current goal

  [ACL2-pc::pso]
      (macro) print the most recent proof attempt from inside the
      proof-builder

  [ACL2-pc::pso!]
      (macro) print the most recent proof attempt from inside the
      proof-builder

  [ACL2-pc::psog]
      (macro) print the most recent proof attempt from inside the
      proof-builder

  [ACL2-pc::put]
      (macro) substitute for a ``free variable''

  [ACL2-pc::quiet]
      (meta) run instructions without prover output

  [ACL2-pc::quiet!]
      (meta) run instructions without prover output

  [ACL2-pc::r]
      (macro) same as rewrite

  [ACL2-pc::reduce]
      (atomic macro) call the ACL2 theorem prover's simplifier

  [ACL2-pc::reduce-by-induction]
      (macro) call the ACL2 prover without induction, after going into
      induction

  [ACL2-pc::remove-abbreviations]
      (primitive) remove one or more abbreviations

  [ACL2-pc::repeat]
      (macro) repeat the given instruction until it ``fails''

  [ACL2-pc::repeat-rec]
      (macro) auxiliary to [47mrepeat[0m

  [ACL2-pc::replay]
      (macro) replay one or more instructions

  [ACL2-pc::restore]
      (meta) remove the effect of an UNDO command

  [ACL2-pc::retain]
      (atomic macro) drop all [31;1mbut[0m the indicated top-level hypotheses

  [ACL2-pc::retrieve]
      (macro) re-enter the proof-builder

  [ACL2-pc::rewrite]
      (primitive) apply a rewrite rule

  [ACL2-pc::run-instr-on-goal]
      (macro) auxiliary to THEN

  [ACL2-pc::run-instr-on-new-goals]
      (macro) auxiliary to [47mthen[0m

  [ACL2-pc::runes]
      (macro) print the runes (definitions, lemmas, ...) used

  [ACL2-pc::s]
      (primitive) simplify the current subterm

  [ACL2-pc::s-prop]
      (atomic macro) simplify propositionally

  [ACL2-pc::save]
      (macro) save the proof-builder state (state-stack)

  [ACL2-pc::sequence]
      (meta) run the given list of instructions according to a multitude
      of options

  [ACL2-pc::show-abbreviations]
      (macro) display the current abbreviations

  [ACL2-pc::show-linears]
      (macro) display the applicable [linear] rules

  [ACL2-pc::show-rewrites]
      (macro) display the applicable [rewrite] rules

  [ACL2-pc::show-type-prescriptions]
      (macro) display the applicable [type-prescription] rules

  [ACL2-pc::skip]
      (macro) ``succeed'' without doing anything

  [ACL2-pc::sl]
      (atomic macro) simplify with lemmas

  [ACL2-pc::sls]
      (macro) same as SHOW-LINEARS

  [ACL2-pc::split]
      (atomic macro) split the current goal into cases

  [ACL2-pc::sr]
      (macro) same as SHOW-REWRITES

  [ACL2-pc::st]
      (macro) same as SHOW-TYPE-PRESCRIPTIONS

  [ACL2-pc::succeed]
      (macro) run the given instructions, and ``succeed''

  [ACL2-pc::th]
      (macro) print the top-level hypotheses and the current subterm

  [ACL2-pc::then]
      (macro) apply one instruction to current goal and another to new
      subgoals

  [ACL2-pc::top]
      (atomic macro) move to the top of the goal

  [ACL2-pc::type-alist]
      (macro) display the [type-alist] from the current context

  [ACL2-pc::undo]
      (meta) undo some instructions

  [ACL2-pc::unsave]
      (macro) remove a proof-builder state

  [ACL2-pc::up]
      (primitive) move to the parent (or some ancestor) of the current
      subterm

  [ACL2-pc::use]
      (atomic macro) use a lemma instance

  [ACL2-pc::wrap]
      (atomic macro) execute the indicated instructions and combine all
      the new goals

  [ACL2-pc::wrap-induct]
      (atomic macro) same as induct, but create a single goal

  [ACL2-pc::wrap1]
      (primitive) combine goals into a single goal

  [ACL2-pc::x]
      (atomic macro) expand and (maybe) simplify function call at the
      current subterm

  [ACL2-pc::x-dumb]
      (atomic macro) expand function call at the current subterm, without
      simplifying")
 (PROOF-BUILDER-COMMANDS-SHORT-LIST
  (PROOF-BUILDER PROOF-BUILDER-COMMANDS)
  "Perhaps the most commonly used [proof-builder] commands

  The list of subtopics below includes what are arguably the most
  useful, and most commonly used, [proof-builder] commands.


Subtopics

  [ACL2-pc::=]
      (atomic macro) attempt an equality (or equivalence) substitution

  [ACL2-pc::bash]
      (atomic macro) call the ACL2 theorem prover's simplifier

  [ACL2-pc::bk]
      (atomic macro) move backward one argument in the enclosing term

  [ACL2-pc::cg]
      (macro) change to another goal.

  [ACL2-pc::claim]
      (atomic macro) add a new hypothesis

  [ACL2-pc::comm]
      (macro) display instructions from the current interactive session

  [ACL2-pc::contrapose]
      (primitive) switch a hypothesis with the conclusion, negating both

  [ACL2-pc::demote]
      (primitive) move top-level hypotheses to the conclusion

  [ACL2-pc::drop]
      (primitive) drop top-level hypotheses

  [ACL2-pc::dv]
      (atomic macro) move to the indicated subterm

  [ACL2-pc::exit]
      (meta) exit the interactive proof-builder

  [ACL2-pc::expand]
      (primitive) expand the current function call without simplification

  [ACL2-pc::goals]
      (macro) list the names of goals on the stack

  [ACL2-pc::in-theory]
      (primitive) set the current proof-builder theory

  [ACL2-pc::induct]
      (atomic macro) generate subgoals using induction

  [ACL2-pc::nx]
      (atomic macro) move forward one argument in the enclosing term

  [ACL2-pc::p]
      (macro) prettyprint the current term in the usual user-level
      (untranslated) syntax

  [ACL2-pc::p-top]
      (macro) prettyprint the conclusion, highlighting the current term

  [ACL2-pc::prove]
      (primitive) call the ACL2 theorem prover to prove the current goal

  [ACL2-pc::r]
      (macro) same as rewrite

  [ACL2-pc::replay]
      (macro) replay one or more instructions

  [ACL2-pc::restore]
      (meta) remove the effect of an UNDO command

  [ACL2-pc::retrieve]
      (macro) re-enter the proof-builder

  [ACL2-pc::runes]
      (macro) print the runes (definitions, lemmas, ...) used

  [ACL2-pc::s]
      (primitive) simplify the current subterm

  [ACL2-pc::s-prop]
      (atomic macro) simplify propositionally

  [ACL2-pc::save]
      (macro) save the proof-builder state (state-stack)

  [ACL2-pc::show-rewrites]
      (macro) display the applicable [rewrite] rules

  [ACL2-pc::split]
      (atomic macro) split the current goal into cases

  [ACL2-pc::sr]
      (macro) same as SHOW-REWRITES

  [ACL2-pc::th]
      (macro) print the top-level hypotheses and the current subterm

  [ACL2-pc::top]
      (atomic macro) move to the top of the goal

  [ACL2-pc::undo]
      (meta) undo some instructions

  [ACL2-pc::up]
      (primitive) move to the parent (or some ancestor) of the current
      subterm

  [ACL2-pc::use]
      (atomic macro) use a lemma instance

  [ACL2-pc::x]
      (atomic macro) expand and (maybe) simplify function call at the
      current subterm

  [ACL2-pc::x-dumb]
      (atomic macro) expand function call at the current subterm, without
      simplifying")
 (PROOF-CHECKER
  (PROOF-BUILDER)
  "Old name for [proof-builder]

  See [proof-builder].  Historically, this tool was misnamed the
  ``proof-checker'', but since the tool is used for building and
  exploring (what could be called) proofs rather than for checking
  them, its name was changed to ``proof-builder'' in 2016.")
 (PROOF-OF-WELL-FOUNDEDNESS
  (ORDINALS)
  "A proof that [47m[o<][0m is well-founded on [47m[o-p][0ms

  The soundness of ACL2 rests in part on the well-foundedness of [47m[o<][0m
  on [47m[o-p][0ms.  This can be taken as obvious if one is willing to grant
  that those concepts are simply encodings of the standard
  mathematical notions of the ordinals below [47mepsilon-0[0m and its
  natural ordering relation.  But it is possible to prove that [47m[o<][0m
  is well-founded on [47m[o-p][0ms without having to assert any connection
  to the ordinals and that is what we do here.  The community book
  [47mbooks/ordinals/proof-of-well-foundedness[0m carries out the proof
  outlined below in ACL2, using only that the natural numbers are
  well-founded.

  Before outlining the above mentioned proof, we note that in the
  analogous documentation page of ACL2 Version_2.7, there is a proof
  of the well-foundedness of [47me0-ord-<[0m on [47me0-ordinalp[0ms, the less-than
  relation and recognizer for the old ordinals (that is, for the
  ordinals appearing in ACL2 up through that version).  Manolios and
  Vroon have given a proof in ACL2 Version_2.7 that the current
  ordinals (based on [47m[o<][0m and [47m[o-p][0m) are order-isomorphic to the old
  ordinals (based on [47me0-ord-<[0m and [47me0-ordinalp[0m).  Their proof
  establishes that switching from the old ordinals to the current
  ordinals preserves the soundness of ACL2.  For details see their
  paper:

    Manolios, Panagiotis & Vroon, Daron.
    Ordinal arithmetic in ACL2.
    Kaufmann, Matt, & Moore, J Strother (eds).
    Fourth International Workshop on the ACL2 Theorem
    Prover and Its Applications (ACL2-2003),
    July, 2003.
    See {http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/ | http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}.

  We now give an outline of the above mentioned proof of
  well-foundedness.  We first observe three facts about [47m[o<][0m on
  ordinals that have been proved by ACL2 using only structural
  induction on lists.  These theorems can be proved by hand.

    (defthm transitivity-of-o<
      (implies (and (o< x y)
                    (o< y z))
               (o< x z))
      :rule-classes nil)

    (defthm non-circularity-of-o<
      (implies (o< x y)
               (not (o< y x)))
      :rule-classes nil)

    (defthm trichotomy-of-o<
      (implies (and (o-p x)
                    (o-p y))
               (or (equal x y)
                   (o< x y)
                   (o< y x)))
      :rule-classes nil)

  These three properties establish that [47m[o<][0m orders the [47m[o-p][0ms.  To put
  such a statement in the most standard mathematical nomenclature, we
  can define the macro:

    (defmacro o<= (x y)
      `(not (o< ,y ,x)))

  and then establish that [47mo<=[0m is a relation that is a simple, complete
  (i.e., total) order on ordinals by the following three lemmas,
  which have been proved:

    (defthm antisymmetry-of-o<=
      (implies (and (o-p x)
                    (o-p y)
                    (o<= x y)
                    (o<= y x))
               (equal x y))
      :rule-classes nil
      :hints ((\"Goal\" :use non-circularity-of-o<)))

    (defthm transitivity-of-o<=
      (implies (and (o-p x)
                    (o-p y)
                    (o<= x y)
                    (o<= y z))
               (o<= x z))
      :rule-classes nil
      :hints ((\"Goal\" :use transitivity-of-o<)))

    (defthm trichotomy-of-o<=
      (implies (and (o-p x)
                    (o-p y))
               (or (o<= x y)
                   (o<= y x)))
      :rule-classes nil
      :hints ((\"Goal\" :use trichotomy-of-o<)))

  Crucially important to the proof of the well-foundedness of [47m[o<][0m on
  [47m[o-p][0ms is the concept of ordinal-depth, abbreviated [47mod[0m:

    (defun od (l)
      (if (o-finp l)
          0
        (1+ (od (o-first-expt l)))))

  If the [47mod[0m of an [47m[o-p][0m [47mx[0m is smaller than that of an [47m[o-p][0m [47my[0m, then [47mx[0m is
  [47m[o<][0m [47my[0m:

    (defun od-1 (x y)
      (if (o-finp x)
          (list x y)
        (od-1 (o-first-expt x) (o-first-expt y))))

    (defthm od-implies-ordlessp
      (implies (and (o-p x)
                    (< (od x) (od y)))
               (o< x y))
      :hints ((\"Goal\"
               :induct (od-1 x y))))

  Remark.  A consequence of this lemma is the fact that if [47ms = s(1)[0m,
  [47ms(2)[0m, ... is an infinite, [47m[o<][0m descending sequence of [47m[o-p][0ms, then
  [47mod(s(1))[0m, [47mod(s(2))[0m, ... is a ``weakly'' descending sequence of
  non-negative integers: [47mod(s(i))[0m is greater than or equal to
  [47mod(s(i+1))[0m.

  [3mLemma Main.[0m For each non-negative integer [47mn[0m, [47m[o<][0m well-orders the set
  of [47m[o-p][0ms with [47mod[0m less than or equal to [47mn[0m .

    Base Case.  n = 0.  The o-ps with 0 od are the non-negative
    integers.  On the non-negative integers, o< is the same as <.

    Induction Step.  n > 0.  We assume that o< well-orders the
    o-ps with od less than n.

      If o< does not well-order the o-ps with od less than or equal to n,
      consider, D, the set of infinite, o< descending sequences of o-ps of od
      less than or equal to n.  The first element of a sequence in D has od n.
      Therefore, the o-first-expt of the first element of a sequence in D has od
      n-1.  Since o<, by IH, well-orders the o-ps with od less than n, the set
      of o-first-expts of first elements of the sequences in D has a minimal
      element, which we denote by B and which has od of n-1.

      Let k be the minimum integer such that for some infinite, o< descending
      sequence s of o-ps with od less than or equal to n, the first element of s
      has an o-first-expt of B and an o-first-coeff of k.  Notice that k is
      positive.

      Having fixed B and k, let s = s(1), s(2), ... be an infinite, o<
      descending sequence of o-ps with od less than or equal to n such that s(1)
      has a o-first-expt of B and an o-first-coeff of k.

      We show that each s(i) has a o-first-expt of B and an o-first-coeff of
      k. For suppose that s(j) is the first member of s either with o-first-expt
      B and o-first-coeff m (m neq k) or with o-first-expt B' and o-first-coeff
      B' (B' neq B). If (o-first-expt s(j)) = B', then B' has od n-1 (otherwise,
      by IH, s would not be infinite) and B' is o< B, contradicting the
      minimality of B. If 0 < m < k, then the fact that the sequence beginning
      at s(j) is infinitely descending contradicts the minimality of k. If m >
      k, then s(j) is greater than its predecessor; but this contradicts the
      fact that s is descending.

      Thus, by the definition of o<, for s to be a decreasing sequence of o-ps,
      (o-rst s(1)), (o-rst s(2)), ... must be a decreasing sequence. We end by
      showing this cannot be the case. Let t = t(1), t(2), ... be an infinite
      sequence of o-ps such that t(i) = (o-rst s(i)). Then t is infinitely
      descending. Furthermore, t(1) begins with an o-p B' that is o< B. Since t
      is in D, t(1) has od n, therefore, B' has od n-1. But this contradicts the
      minimality of B. Q.E.D.

  Theorem.  [47m[o<][0m well-orders the [47m[o-p][0ms.  Proof.  Every infinite,[47m o<[0m
  descending sequence of [47m[o-p][0ms has the property that each member has
  [47mod[0m less than or equal to the [47mod[0m, [47mn[0m, of the first member of the
  sequence.  This contradicts Lemma Main.  Q.E.D.")
 (PROOF-SUPPORTERS-ALIST (POINTERS)
                         "See [dead-events].")
 (PROOF-TREE
  (DEBUGGING)
  "Proof tree displays

  A view of ACL2 proofs may be obtained by way of ``proof tree
  displays,'' which appear in proof output (see [proofs-co]) when
  proof-tree output is enabled (see below) When ACL2 starts a proof
  and proof-tree output is enabled, the proof output begins with the
  following string.

    << Starting proof tree logging >>

  Then for each goal encountered during the proof, a corresponding
  proof tree display (as described below) is printed into the proof
  output: first the characters in the constant string
  [47m*proof-tree-start-delimiter*[0m are printed, then the proof tree
  display, and finally the characters in the constant string
  [47m*proof-tree-end-delimiter*[0m.

  External tools may present proof tree displays in a separate window.
  In particular, a tool distributed with the ACL2 community books
  customizes the emacs environment to provide window-based proof tree
  displays together with commands for traversing the proof
  transcript; see the discussion of ``ACL2 proof-tree support'' in
  file [47memacs-acl2.el[0m distributed with ACL2 (in either of two
  directories; see [emacs]).

  The command [47m:start-proof-tree[0m enables proof-tree output, while
  [47m:stop-proof-tree[0m disables proof-tree output; see [start-proof-tree]
  and see [stop-proof-tree].

  Here is an example of a proof tree display, with comments.  Lines
  marked with ``c'' are considered ``checkpoints,'' i.e., goals whose
  scrutiny may be of particular value.

    ( DEFTHM PLUS-TREE-DEL ...)    ;currently proving PLUS-TREE-DEL
       1 Goal preprocess   ;\"Goal\" creates 1 subgoal by preprocessing
       2 |  Goal' simp     ;\"Goal'\" creates 2 subgoals by simplification
    c  0 |  |  Subgoal 2 PUSH *1   ;\"Subgoal 2\" pushes \"*1\" for INDUCT
    ++++++++++++++++++++++++++++++ ;first pass thru waterfall completed
    c  6 *1 INDUCT                 ;Proof by induction of \"*1\" has
         |  <5 more subgoals>      ; created 6 top-level subgoals.  At
                                   ; this point, one of those 6 has been
                                   ; proved, and 5 remain to be proved.
                                   ; We are currently working on the
                                   ; first of those 5 remaining goals.

  See [proof-tree-examples] for many examples that contain proof tree
  displays.  But first, we summarize the kinds of lines that may
  appear in a proof tree display.  The simplest form of a proof tree
  display is a header showing the current event, followed by list of
  lines, each having one of the following forms.

    n <goal> <process> ...

  Says that the indicated goal created [47mn[0m subgoals using the indicated
  process.  Here ``...'' refers to possible additional information.

    c   n <goal> <process> ...

  As above, but calls attention to the fact that this goal is a
  ``checkpoint'' in the sense that it may be of particular interest.
  Some displays may overwrite ``c'' with ``>'' to indicate the
  current checkpoint being shown in the proof transcript.

    |  <goal> ...
    |  |  <k subgoals>

  Indicates that the goal just above this line, which is pointed to by
  the rightmost vertical bar (``|''), has [47mk[0m subgoals, none of which
  have yet been processed.

    |  <goal> ...
    |  |  <k more subgoals>

  As above, except that some subgoals have already been processed.

    ++++++++++++++++++++++++++++++

  Separates successive passes through the ``waterfall''.  Thus, this
  ``fencepost'' mark indicates the start of a new proof by induction
  or of a new forcing round.

  See [proof-tree-examples] for detailed examples.  See
  [checkpoint-forced-goals] to learn how to mark goals as checkpoints
  that [force] the creation of goals in forcing rounds.  Finally, see
  [proof-tree-details] for some points not covered elsewhere.


Subtopics

  [Checkpoint-forced-goals]
      Cause forcing goals to be checkpointed in proof trees

  [Proof-tree-details]
      Proof tree details not covered elsewhere

  [Proof-tree-examples]
      Proof tree example

  [Start-proof-tree]
      Start displaying proof trees during proofs

  [Stop-proof-tree]
      Stop displaying proof trees during proofs")
 (PROOF-TREE-DETAILS
  (PROOF-TREE)
  "Proof tree details not covered elsewhere

  See [proof-tree] for an introduction to proof trees, and for a list
  of related topics.  Here we present some details not covered
  elsewhere.

  1.  When proof tree display is enabled (because the command
  [47m:[0m[47m[stop-proof-tree][0m has not been executed, or has been superseded by
  a later [47m:[0m[47m[start-proof-tree][0m command), then time summaries will
  include the time for proof tree display.  This time includes the
  time spent computing with proof trees, such as the pruning process
  described briefly above.  Even when proof trees are not displayed,
  such as when their display is turned off in the middle of a proof,
  this time will be printed if it is not 0.

  2.  When a goal is given a [47m:bye[0m in a proof (see [hints]), it is
  treated for the purpose of proof tree display just as though it had
  been proved.

  3.  Several [state] global variables affect proof tree display.  [47m(@
  proof-tree-indent)[0m is initially the string [47m\"| \"[0m: it is the string
  that is laid down the appropriate number of times to effect
  indentation.  [47m(@ proof-tree-buffer-width)[0m is initially the value of
  [47m(fmt-soft-right-margin state)[0m, and is used to prevent printing of
  the annotation ``([force]d ...)'' in any greater column than this
  value.  However, [47m(assign proof-tree-buffer-width nil)[0m to avoid any
  such suppression.  Finally, [47m(@ checkpoint-processors)[0m is a list of
  processors from the constant list [47m*preprocess-clause-ledge*[0m,
  together with [47m:induct[0m.  You may remove elements of [47m(@
  checkpoint-processors)[0m to limit which processes are considered
  checkpoints, but note that this can affect what is printed by
  gag-mode (see [set-gag-mode]).

  4.  When [47m:[0m[47m[otf-flg][0m is not set to [47mt[0m in a proof, and the prover then
  decides to revert to the original goal and prove it by induction,
  the proof tree display will reflect this fact as shown here:

    c  0 |  |  Subgoal 2 PUSH (reverting)

  5. The usual [failure] message is printed as part of the prooftree
  display when a proof has failed.")
 (PROOF-TREE-EXAMPLES
  (PROOF-TREE)
  "Proof tree example

  See [proof-tree] for an introduction to proof trees, and for a list
  of related topics.  Here we present a detailed example followed by
  a shorter example that illustrates proof by induction.

  Consider the [guard] proof for the definition of a function
  [47mcancel_equal_plus[0m; the body of this definition is of no importance
  here.  The first proof tree display is:

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
         |  <18 subgoals>

  This is to be read as follows.

      At this stage of the proof we have encountered the top-level goal,
      named \"Goal\", which generated 18 subgoals using the
      ``preprocess'' process.  We have not yet begun to work on those
      subgoals.

  The corresponding message from the ordinary prover output is:

      By case analysis we reduce the conjecture to the following 18
      conjectures.

  Note that the field just before the name of the goal ([47m\"Goal\"[0m), which
  here contains the number 18, indicates the number of cases
  (children) created by the goal using the indicated process.  This
  number will remain unchanged as long as this goal is displayed.

  The next proof tree display is:

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
       1 |  Subgoal 18 simp
         |  |  <1 subgoal>
         |  <17 more subgoals>

  which indicates that at this point, the prover has used the
  simplification (``simp'') process on Subgoal 18 to create one
  subgoal (``<1 subgoal>'').  The vertical bar (``|'') below
  ``Subgoal 18'', accompanied by the line below it, signifies that
  there are 17 siblings of Subgoal 18 that remain to be processed.

  The next proof tree displayed is:

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
       1 |  Subgoal 18 simp
    c  2 |  |  Subgoal 18' ELIM
         |  |  |  <2 subgoals>
         |  <17 more subgoals>

  Let us focus on the fourth line of this display:

    c  2 |  |  Subgoal 18' ELIM

  The ``c'' field marks this goal as a ``checkpoint'', i.e., a goal
  worthy of careful scrutiny.  In fact, any goal that creates
  children by a process other than ``preprocess'' or ``simp'' is
  marked as a checkpoint.  In this case, the destructor-elimination
  (``[elim]'') process has been used to create subgoals of this goal.
  The indentation shows that this goal, Subgoal 18', is a child of
  Subgoal 18.  The number ``2'' indicates that 2 subgoals have been
  created (by [elim]).  Note that this information is consistent with
  the line just below it, which says ``<2 subgoals>''.

  Finally, the last line of this proof tree display,

    |  <17 more subgoals>

  is connected by vertical bars (``|'') up to the string [47m\"Subgoal 18\"[0m,
  which suggests that there are 17 immediate subgoals of Goal
  remaining to process after Subgoal 18.  Note that this line is
  indented one level from the second line, which is the line for the
  goal named [47m\"Goal\"[0m.  The display is intended to suggest that the
  subgoals of Goal that remain to be proved consist of Subgoal 18
  together with 17 more subgoals.

  The next proof tree display differs from the previous one only in
  that now, Subgoal 18' has only one more subgoal to be processed.

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
       1 |  Subgoal 18 simp
    c  2 |  |  Subgoal 18' ELIM
         |  |  |  <1 more subgoal>
         |  <17 more subgoals>

  Note that the word ``more'' in ``<1 more subgoal>'' tells us that
  there was originally more than one subgoal of Subgoal 18.  In fact
  that information already follows from the line above, which (as
  previously explained) says that Subgoal 18' originally created 2
  subgoals.

  The next proof tree display occurs when the prover completes the
  proof of that ``1 more subgoal'' referred to above.

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
         |  <17 more subgoals>

  Then, Subgoal 17 is processed and creates one subgoal, by
  simplification:

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
       1 |  Subgoal 17 simp
         |  |  <1 subgoal>
         |  <16 more subgoals>

  ... and so on.

  Later in the proof one might find the following successive proof tree
  displays.

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
         |  <9 more subgoals>

    ( DEFUN CANCEL_EQUAL_PLUS ...)

      18 Goal preprocess
       0 |  Subgoal 9 simp (FORCED)
         |  <8 more subgoals>

  These displays tell us that Subgoal 9 simplified to [47mt[0m (note that the
  ``0'' shows clearly that no subgoals were created), but that some
  rule's hypotheses were [force]d.  Although this goal is not
  checkpointed (i.e., no ``c'' appears on the left margin), one can
  cause such goals to be checkpointed; see [checkpoint-forced-goals].

  In fact, the proof tree displayed at the end of the ``main
  proof''(the 0-th forcing round) is as follows.

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
       0 |  Subgoal 9 simp (FORCED)
       0 |  Subgoal 8 simp (FORCED)
       0 |  Subgoal 7 simp (FORCED)
       0 |  Subgoal 6 simp (FORCED)
       0 |  Subgoal 4 simp (FORCED)
       0 |  Subgoal 3 simp (FORCED)

  This is followed by the following proof tree display at the start of
  the forcing round.

      18 Goal preprocess
       0 |  Subgoal 9 simp (FORCED [1]Subgoal 4)
       0 |  Subgoal 8 simp (FORCED [1]Subgoal 6)
       0 |  Subgoal 7 simp (FORCED [1]Subgoal 1)
       0 |  Subgoal 6 simp (FORCED [1]Subgoal 3)
       0 |  Subgoal 4 simp (FORCED [1]Subgoal 5)
       0 |  Subgoal 3 simp (FORCED [1]Subgoal 2)
    ++++++++++++++++++++++++++++++
       6 [1]Goal FORCING-ROUND
       2 |  [1]Subgoal 6 preprocess
         |  |  <2 subgoals>
         |  <5 more subgoals>

  This display shows which goals to ``blame'' for the existence of each
  goal in the forcing round.  For example, Subgoal 9 is to blame for
  the creation of [1]Subgoal 4.

  Actually, there is no real goal named [47m\"[1]Goal\"[0m.  However, the line

    6 [1]Goal FORCING-ROUND

  appears in the proof tree display to suggest a ``parent'' of the six
  top-level goals in that forcing round.  As usual, the numeric field
  before the goal name contains the original number of children of
  that (virtual, in this case) goal --- in this case, 6.

  In our example proof, Subgoal 6 eventually gets proved, without doing
  any further forcing.  At that point, the proof tree display looks
  as follows.

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
       0 |  Subgoal 9 simp (FORCED [1]Subgoal 4)
       0 |  Subgoal 7 simp (FORCED [1]Subgoal 1)
       0 |  Subgoal 6 simp (FORCED [1]Subgoal 3)
       0 |  Subgoal 4 simp (FORCED [1]Subgoal 5)
       0 |  Subgoal 3 simp (FORCED [1]Subgoal 2)
    ++++++++++++++++++++++++++++++
       6 [1]Goal FORCING-ROUND
         |  <5 more subgoals>

  Notice that the line for Subgoal 8,

    0 |  Subgoal 8 simp (FORCED [1]Subgoal 6)

  no longer appears.  That is because the goal [1]Subgoal 6 has been
  proved, along with all its children; and hence, the proof of
  Subgoal 8 no longer depends on any further reasoning.

  The final two proof tree displays in our example are as follows.

    ( DEFUN CANCEL_EQUAL_PLUS ...)
      18 Goal preprocess
       0 |  Subgoal 7 simp (FORCED [1]Subgoal 1)
    ++++++++++++++++++++++++++++++
       6 [1]Goal FORCING-ROUND
       2 |  [1]Subgoal 1 preprocess
       1 |  |  [1]Subgoal 1.1 preprocess
       1 |  |  |  [1]Subgoal 1.1' simp
    c  3 |  |  |  |  [1]Subgoal 1.1'' ELIM
         |  |  |  |  |  <1 more subgoal>

    ( DEFUN CANCEL_EQUAL_PLUS ...)
    <<PROOF TREE IS EMPTY>>

  The explanation for the empty proof tree is simple: once [1]Subgoal
  1.1.1 was proved, nothing further remained to be proved.  In fact,
  the much sought-after ``Q.E.D.'' appeared shortly after the final
  proof tree was displayed.

  Let us conclude with a final, brief example that illustrates proof by
  induction.  Partway through the proof one might come across the
  following proof tree display.

    ( DEFTHM PLUS-TREE-DEL ...)
       1 Goal preprocess
       2 |  Goal' simp
    c  0 |  |  Subgoal 2 PUSH *1
         |  |  <1 more subgoal>

  This display says that in the attempt to prove a theorem called
  [47mplus-tree-del[0m, preprocessing created the only child Goal' from
  Goal, and Goal' simplified to two subgoals.  Subgoal 2 is
  immediately pushed for proof by induction, under the name ``*1''.
  In fact if Subgoal 1 simplifies to [47mt[0m, then we see the following
  successive proof tree displays after the one shown above.

    ( DEFTHM PLUS-TREE-DEL ...)
       1 Goal preprocess
       2 |  Goal' simp
    c  0 |  |  Subgoal 2 PUSH *1

    ( DEFTHM PLUS-TREE-DEL ...)
       1 Goal preprocess
       2 |  Goal' simp
    c  0 |  |  Subgoal 2 PUSH *1
    ++++++++++++++++++++++++++++++
    c  6 *1 INDUCT
         |  <5 more subgoals>

  The separator ``+++++...'' says that we are beginning another trip
  through the waterfall.  In fact this trip is for a proof by
  induction (as opposed to a forcing round), as indicated by the word
  ``INDUCT''.  Apparently *1.6 was proved immediately, because it was
  not even displayed; a goal is only displayed when there is some
  work left to do either on it or on some goal that it brought
  (perhaps indirectly) into existence.

  Once a proof by induction is completed, the ``PUSH'' line that refers
  to that proof is eliminated (``pruned'').  So for example, when the
  present proof by induction is completed, the line

    c  0 |  |  Subgoal 2 PUSH *1

  is eliminated, which in fact causes the lines above it to be
  eliminated (since they no longer refer to unproved children).
  Hence, at that point one might expect to see:

    ( DEFTHM PLUS-TREE-DEL ...)
    <<PROOF TREE IS EMPTY>>

  However, if the proof by induction of *1 necessitates further proofs
  by induction or a forcing round, then this ``pruning'' will not yet
  be done.")
 (PROOFS-CO
  (IO ACL2-BUILT-INS)
  "The proofs character output channel

  [47mProofs-co[0m is an [47m[ld][0m special (see [ld]).  The accessor is [47m(proofs-co
  state)[0m and the updater is [47m(set-proofs-co val state)[0m.  [47mProofs-co[0m
  must be an open character output channel.  It is to this channel
  that [47m[defun][0m, [47m[defthm][0m, and the other event [command]s print their
  commentary.

  ``Proofs-co'' stands for ``proofs character output.'' The initial
  value of [47mproofs-co[0m is the same as the value of [47m[*standard-co*][0m.")
 (PROPER-CONSP
  (LISTS ACL2-BUILT-INS)
  "Recognizer for proper ([47mnil[0m-terminated) non-empty lists

  [47mProper-consp[0m is the function that checks whether its argument is a
  non-empty list that ends in [47mnil[0m.  Also see [true-listp].

  [31;1mFunction: [0m<proper-consp>

    (defun proper-consp (x)
      (declare (xargs :guard t))
      (and (consp x) (true-listp x)))")
 (PROPS
  (WORLD)
  "Print the ACL2 properties on a symbol

    Example:
    :props assoc-eq

  [47mProps[0m takes one argument, a symbol, and prints all of the properties
  that are on that symbol in the ACL2 [world].")
 (PROTECT-MEMOIZE-STATISTICS
  (MEMOIZE)
  "Ensure the integrity of memoization statistics even upon aborts

  Example Forms:

    (f-put-global 'protect-memoize-statistics t state)
    (assign protect-memoize-statistics t) ; same effect as above

  By default, if calls of [47m[memoize][0md functions are aborted, then
  statistics reported by [memsum] for those calls will often be
  incorrect.  Since aborts are relatively rare, this seems a
  reasonable default, since avoiding such inaccuracy incurs some
  additional computation time.  However, evaluation of either of the
  forms above will arrange that for functions memoized [3mafter[0m such
  evaluation, the accuracy of the statistics will not be adversely
  affected by aborts (again, at the expense of some additional
  computation time).

  Once again: evaluation of a form displayed above only affects
  behavior for future calls of [47m[memoize][0m, not for functions already
  memoized at the time of that form's evaluation (unless the function
  is subsequently [unmemoize]d and then once again [memoize]d).

  To revert to the default state in which performance is preferred to
  accuracy of memoization statistics after aborts, evaluate either of
  the following forms.

    (f-put-global 'protect-memoize-statistics nil state)
    (assign protect-memoize-statistics nil) ; same effect as above

  The following demo illustrates the effect of assigning to
  protect-memoize-statistics.

    (defun foo (n)
      (declare (xargs :guard (natp n)))
      (progn$
       (sleep n)
       n))

    ; OPTIONALLY:
    (assign protect-memoize-statistics t)

    (memoize 'foo)

    (clear-memoize-statistics) ; for good measure
    (memsum) ; should have nothing to report
    (foo 1)
    (memsum) ; reports 1 call, 1 second

    ; Now: submit this and then abort with an interrupt it after about 3 seconds.
    (foo 15)

    ; See explanation below.
    (memsum)

  If the ``OPTIONAL'' form above is omitted, we get the default
  behavior: the statistics from [47m[memsum][0m will show 2 calls of [47mfoo[0m
  taking only took 1 second total, for an average of only 0.5
  seconds, because no time was recorded for the aborted call.
  However, if the ``OPTIONAL'' form above is included, then you will
  see statistics that look accurate.")
 (PROVING_THEOREMS_ABOUT_MODELS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Proving Theorems about Models

  {IMAGE} (see [What_is_Required_of_the_User{Q}])

  But ACL2 is a [31;1mlogic[0m.  We can [31;1mprove theorems about the model[0m.

  {IMAGE}

    [31;1mTheorem.  MC 'mult is a multiplier[0m
    (implies (and (natp x)
                  (natp y))
             (equal (lookup 'z (mc (s 'mult x y) (mclk x)))
                    (* x y))).

  This theorem says that a certain program running on the [31;1mmc[0m machine
  will correctly multiply [31;1many two natural numbers[0m.

  It is a statement about an [31;1minfinite[0m number of test cases!

  We know it is true about the model because we [31;1mproved[0m it.

  Of course, models of actual machines usually only accept a finite
  number of different inputs.  For example, engineers at Advanced
  Micro Devices (AMD), Centaur, and IBM have produced ACL2 models of
  floating point units that operate on double precision IEEE floating
  point numbers.  These are finite models.  But the size of their
  inputs is sufficiently large that they are verified by the same
  mathematical methods used to prove theorems about infinite state
  systems like our little [47mmc[0m.

  {IMAGE} (see [What_is_Required_of_the_User{Q}])")
 (PROVISIONAL-CERTIFICATION
  (BOOKS-CERTIFICATION)
  "Certify a book in stages for improved book-level parallelism

  Provisional certification is a process that can increase parallelism
  when certifying books in parallel, typically using `make', when
  certifying a collection of [books].  We got this idea from Jared
  Davis, who developed rudimentary provisional certification schemes
  first at Rockwell Collins and later for his `Milawa' project.  Our
  design has also benefited from conversations with Sol Swords.

  Warning: as of November 2014, enabling provision certification via
  the [47mACL2_PCERT[0m flag can not be reliably enabled at the Makefile
  level (as is shown below).  See {Github Issue 255 |
  https://github.com/acl2/acl2/issues/255} for more information.

  To invoke provisional certification, see [books-certification].  For
  example, you could issue the following command.

    cert.pl --pcert-all -j 4 `find . -name '*.lisp'`

  Alternatively, see [books-certification-classic] for a discussion of
  classic ACL2 `make'-based certification (which may disappear in a
  future ACL2 release); here we extend those instructions to show how
  to use provisional certification.  (Also, you may wish to look at
  community books file [47mbooks/system/pcert/Makefile[0m for an example.)
  We begin by describing a few ways to do that.  A simple way is to
  add the line `[47mACL2_PCERT=t[0m' to a `make' command that you use for
  book certification, for example as follows.

    make -j 4 ACL2_PCERT=t

  The following works too, in a bash shell.

    (export ACL2_PCERT=t ; time make -j 4)

  Alternatively, add the line

    ACL2_PCERT ?= t

  to the [47mMakefile[0m residing in the directory, placed above the line that
  specifies the `[47minclude[0m' of file [47mMakefile-generic[0m.  A successful
  `make' will result in creating the desired [certificate] ([47m.cert[0m)
  files.

  Warning: If you put the line ``[47mACL2_PCERT ?= t[0m'' below the include of
  [47mMakefile-generic[0m, it might have no effect.  For example, try
  editing community books file [47mbooks/system/pcert/Makefile[0m by moving
  the line ``[47mACL2_PCERT ?= t[0m'' to the bottom of the file, and watch
  ``[47mmake top.cert[0m'' fail to invoke provisional certification.

  The description above may be sufficient for you to use provisional
  certification.  We provide additional documentation below for the
  reader who wants to understand more about this process, for example
  when not using `make'.  Below we assume prior familiarity with
  [books], in particular [47m[certify-book][0m and [47m[include-book][0m.  The
  remainder of this [documentation] topic is divided into sections:
  Summary, Correctness Claim and Issues, Combining Pcertify and
  Convert into Pcertify+, and Further Information.

  [31;1mSummary[0m

  Recall that certification of a book, [47mbk[0m, produces a [certificate]
  file [47mbk.cert[0m.  The provisional certification process produces this
  file as well, but as the last of the following three steps.  All of
  these steps are carried out by calls of [47m[certify-book][0m using its
  [47m:pcert[0m keyword argument.  We typically call these steps
  ``procedures'', to distinguish them from the steps of an individual
  call of [47m[certify-book][0m.

    * The ``Pcertify'' procedure (sometimes called the ``Create''
      procedure) is invoked by calling [47m[certify-book][0m with keyword
      argument [47m:pcert :create[0m.  It produces a file [47mbk.pcert0[0m,
      sometimes called the ``[47m.pcert0[0m'' file (pronounced ``dot pee
      cert zero'').  Proofs are skipped during this procedure, which
      can be viewed as an elaborate syntax check, augmented by
      compilation if specified (as it is by default).

    * The ``Convert'' procedure is invoked by calling [47m[certify-book][0m with
      keyword argument [47m:pcert :convert[0m.  It creates file [47mbk.pcert1[0m
      from [47mbk.pcert0[0m, by doing proofs for all events in [47mbk.lisp[0m.
      Note that the third argument (the `[47mcompile-flg[0m' argument) is
      ignored by such a call of [47mcertify-book[0m unless its value is [47m:all[0m
      (either explicitly or by way of environment variable
      [47mACL2_COMPILE_FLG[0m).  A subtlety is that if there is a compiled
      file at least as recent as the corresponding [47m.pcert0[0m file, then
      that compiled file's write date will be updated to the current
      time at the end of this procedure.  The usual
      [local-incompatibility] check at the end of [47m[certify-book][0m is
      omitted for the Convert procedure, since it was performed
      towards the end of the Create procedure.

    * The ``Complete'' procedure is invoked by calling [47m[certify-book][0m with
      keyword argument [47m:pcert :complete[0m.  It checks that every
      included book (including every one that is [47m[local][0mly included)
      has a [47m.cert[0m file that is at least as recent as the
      corresponding book.  The effect is to move [47mbk.pcert1[0m to
      [47mbk.cert[0m.  Note that all arguments of [47mcertify-book[0m other than
      the [47m:pcert[0m argument are ignored for this procedure, other than
      for some trivial argument checking.

  You can combine the Pcertify and Convert procedures into a single
  procedure, Pcertify+, which may be useful for books that contain
  expensive [47m[include-book][0m [events] but do few proofs.  We defer
  discussion of that feature to the section below, ``Combining
  Pcertify and Convert into Pcertify+''.

  The main idea of provisional certification is to break sequential
  dependencies caused by [47m[include-book][0m, that is, so that a book's
  proofs are carried out even when it includes books (sometimes
  called ``sub-books'') that have not themselves been fully
  certified.  For example, suppose that a proof development consists
  of books [47mA.lisp[0m, [47mB.lisp[0m, and [47mC.lisp[0m, where file [47mA.lisp[0m contains the
  form [47m(include-book \"B\")[0m and file [47mB.lisp[0m contains the form
  [47m(include-book \"C\")[0m.  Normally one would first certify [47mC[0m, then [47mB[0m,
  and finally, [47mA[0m.  However, the provisional certification process can
  speed up the process on a multi-core machine, as follows: the
  Pcertify (pronounced ``pee certify'') procedure respects this order
  but (one hopes) is fast since proofs are skipped; the Convert
  procedure essentially completes the certification in parallel by
  doing proofs and creating [47m.pcert1[0m files based on [47m.pcert0[0m files; and
  the Complete procedure respects book order when quickly renaming
  [47m.pcert1[0m files to [47m.cert[0m files.  In our example, the steps would be
  as follows, but note that we need not finish all Pcertify steps
  before starting some Convert steps, nor need we finish all Convert
  steps before starting some Complete steps, as explained further
  below.

    * Pcertify books \"C\", \"B\",and then \"A\", sequentially, skipping proofs
      but doing compilation.

    * Do proofs in parallel for the books using the Convert procedure,
      where each book relies on the existence of its own [47m.pcert0[0m file
      as well as a [47m.cert[0m, [47m.pcert0[0m, or [47m.pcert1[0m file for each of its
      included sub-books.  Write out a [47m.pcert1[0m file for the book when
      the proof succeeds.

    * Rename the [47m.pcert1[0m file to a corresponding [47m.cert[0m file when a [47m.cert[0m
      file exists and is up-to-date for each included book.

  The Convert step can begin for [47mbk.lisp[0m any time after [47mbk.pcert0[0m is
  built.  The Complete step can begin for this book any time after
  [47mbk.pcert1[0m and every [47msub-bk.cert[0m are built, for [47msub-bk[0m a sub-book of
  [47mbk[0m.

  The new procedures --- Pcertify, Convert, and Complete --- are
  invoked by supplying a value for the keyword argument [47m:pcert[0m of
  [47m[certify-book][0m, namely [47m:create[0m, [47m:convert[0m, or [47m:complete[0m,
  respectively.  Typically, and by default, the [47mcompile-flg[0m argument
  of [47m[certify-book][0m is [47mt[0m for the Pcertify procedure, so that
  [compilation] can take full advantage of parallelism.  This
  argument is treated as [47mnil[0m for the other procedures except when its
  value is [47m:all[0m in the Convert procedure, as mentioned above.

  For those who use [47m[make-event][0m, we note that expansion is done in the
  Pcertify procedure; the later steps use the expansion resulting
  from that procedure.  The reason is that although a call of
  [47m[make-event][0m is similar to a macro call, a difference is that the
  expansion of a [47mmake-event[0m form can depend on the [state].
  Therefore, we insist on doing such an expansion only once, so that
  all books involved agree on the expansion.  We say more about
  [47mmake-event[0m below.

  [31;1mCorrectness Claim and Issues[0m

  The Basic Claim for certification is the same whether or not the
  provisional certification process is employed: all books should be
  certified from scratch, with no files written to the directories of
  the books except by ACL2.  Moreover, no trust tags should be used
  (see [defttag]), or else it is the responsibility of the user to
  investigate every occurrence of ``[47mTTAG NOTE[0m'' that is printed to
  standard output.

  But common practice is to certify a set of books in stages: certify a
  few books, fix some books, re-certify changed books, certify some
  more books, and so on.  In practice, we expect this process to be
  sound even though it does not meet the preconditions for the Basic
  Claim above.  In particular, we expect that the use of [book-hash]
  values in [certificate]s will make it exceedingly unlikely that a
  book is still treated as certified after any events in the book or
  any sub-book, or any [portcullis] [command]s of the book or any
  sub-book, have been modified.

  Provisional certification makes it a bit easier for a determined user
  to subvert correctness.  For example, the Complete procedure only
  checks write dates to ensure that each sub-book's [47m.cert[0m file is no
  older than the corresponding [47m.lisp[0m file, but it does not look
  inside [47m.cert[0m files of sub-books; in particular it does not look at
  their [book-hash] information.  Of course, the automatic dependency
  analysis provided by classic ACL2 `make'-based certification avoids
  accidental problems of this sort.  And, book-hash information will
  indeed be applied at [47m[include-book][0m time, at least for sub-books
  included non-[local]ly.

  In short: while we believe that the provisional certification process
  can be trusted, we suggest that for maximum trust, it is best for
  all books in a project to be certified from scratch without the
  provisional certification process.

  [31;1mCombining Pcertify and Convert into Pcertify+[0m

  You can combine the Pcertify and Convert procedure into a single
  procedure, Pcertify+, which may be useful for books that contain
  expensive [47m[include-book][0m [events] but do few proofs.  If you are
  using `make' to do provisional certification as described above,
  just set `make' variable [47mACL2_BOOKS_PCERT_ARG_T[0m to the list of
  books for which you want the Pcertify+ procedure performed instead
  of separate Pcertify and Convert procedures.  Either of two common
  methods may be used to set this variable, as illustrated below for
  the case that books [47msub.lisp[0m and [47mmid.lisp[0m are the ones on which you
  want Pcertify+ performed.  One method is to add the following to
  your directory's Makefile, above the [47minclude[0m of [47mMakefile-generic[0m.

    ACL2_BOOKS_PCERT_ARG_T = sub mid

  Alternatively, you can specify the desired books on the command line,
  for example as follows.

    make -j 4 ACL2_BOOKS_PCERT_ARG_T='sub mid'

  Note that the books are given without their [47m.lisp[0m extensions.

  At the ACL2 level, the Pcertify+ procedure is performed when the
  value [47mt[0m is supplied to the [47m:pcert[0m keyword argument of
  [47m[certify-book][0m.  Thus, [47m:pcert t[0m can be thought of as a combination
  of [47m:pcert :create[0m and [47m:pcert :convert[0m.  However, what ACL2 actually
  does is to perform the Pcertify step without skipping proofs, and
  at the end of the [47mcertify-book[0m run, it writes out both the [47m.pcert0[0m
  and [47m.pcert1[0m file, with essentially the same contents.  (We say
  ``essentially'' because the implementation writes [47m:PCERT-INFO
  :PROVED[0m to the end of the [47m.pcert0[0m file, but not to the [47m.pcert1[0m
  file.)

  [31;1mFurther Information[0m

  Some errors during provisional certification cannot be readily
  solved.  For example, if there are circular directory dependencies
  (for example, some book in directory D1 includes some book in
  directory D2 and vice-versa), then classic ACL2 `make'-based
  certification will quite possibly fail.  For another example,
  perhaps your directory's Makefile is awkward to convert to one with
  suitable dependencies.  When no fix is at hand, it might be best
  simply to avoid provisional certification.  If you are using
  classic ACL2 `make'-based certification, you can simply add the
  following line to your directory's [47mMakefile[0m, or use ``[47mACL2_PCERT=
  [0m'' on the `make' command line, to avoid provisional certification.

    override ACL2_PCERT =

  We invite anyone who has troubleshooting tips to contact the ACL2
  developers with suggestions for adding such tips to this section.

  Our next remark is relevant only to users of [47m[make-event][0m, and
  concerns the interaction of that utility with state global
  [47m[ld-skip-proofsp][0m.  Normally, the global value of [47m[ld-skip-proofsp][0m
  is unchanged during [47mmake-event[0m expansion, except that it is bound
  to [47mnil[0m when the [47mmake-event[0m form has a non-[47mnil[0m [47m:check-expansion[0m
  argument.  But during the Pcertify procedure (not the Pcertify+
  procedure), [47m[ld-skip-proofsp][0m is always bound to [47mnil[0m at the start
  of [47mmake-event[0m expansion.  To see why, consider for example the
  community book [47mbooks/make-event/proof-by-arith.lisp[0m.  This book
  introduces a macro, [47mproof-by-arith[0m, that expands to a call of
  [47m[make-event][0m.  This [47mmake-event[0m form expands by trying to prove a
  given theorem using a succession of included arithmetic books,
  until the proof succeeds.  Now proofs are skipped during the
  Pcertify procedure, and if proofs were also skipped during
  [47mmake-event[0m expansion within that procedure, the first arithmetic
  book's [47m[include-book][0m form would always be saved because the
  theorem's proof ``succeeded'' (as it was skipped!).  Of course, the
  theorem's proof could then easily fail during the Convert step.  If
  you really want to inhibit proofs during [47mmake-event[0m expansion in
  the Pcertify step, consider using a form such as the following:
  [47m(state-global-let* ((ld-skip-proofsp nil)) ...)[0m.

  Finally, we describe what it means for there to be a valid
  [certificate] file for including a certified book.  Normally, this
  is a file with extension [47m.cert[0m.  However, if that [47m.cert[0m file does
  not exist, then ACL2 looks for a [47m.pcert0[0m file instead; and if that
  also does not exist, it looks for a [47m.pcert1[0m file.  (To see why does
  the [47m.pcert0[0m file take priority over the [47m.pcert1[0m file, note that the
  Convert procedure copies a [47m.pcert0[0m file to a [47m.pcert1[0m file, so both
  might exist --- but the [47m.pcert1[0m file might be incomplete if copying
  is in progress.)  Once the candidate certificate file is thus
  selected, it must be valid in order for the book to be considered
  certified (see [certificate]).  For the certificate file as chosen
  above, then in order for a compiled file to be loaded, it must be
  at least as recent as that certificate file.

  Again, as discussed above, a [47m.pcert0[0m or [47m.pcert1[0m file may serve as a
  valid certificate file when the [47m.cert[0m file is missing.  But when
  that happens, a warning may be printed that a ``provisionally
  certified'' book has been included.  No such warning occurs if
  environment variable [47mACL2_PCERT[0m has a non-empty value, or if that
  warning is explicitly inhibited (see [set-inhibit-warnings] and see
  [set-inhibit-output-lst]).")
 (PSEUDO-TERM-LISTP
  (TERM ACL2-BUILT-INS)
  "A predicate for recognizing lists of term-like s-expressions

  See [pseudo-termp] for a predicate that recognizes a term-like
  s-expression.  The predicate [47mpseudo-term-listp[0m tests whether its
  argument is a list of those.

  [31;1mFunction: [0m<pseudo-term-listp>

    (defun pseudo-term-listp (lst)
      (declare (xargs :guard t))
      (cond ((atom lst) (equal lst nil))
            (t (and (pseudo-termp (car lst))
                    (pseudo-term-listp (cdr lst))))))")
 (PSEUDO-TERMP
  (TERM ACL2-BUILT-INS)
  "A predicate for recognizing term-like s-expressions

    Example Forms:
    (pseudo-termp '(car (cons x 'nil)))      ; has value t
    (pseudo-termp '(car x y z))              ; also has value t!
    (pseudo-termp '(delta (h x)))            ; has value t
    (pseudo-termp '(delta (h x) . 7))        ; has value nil (not a true-listp)
    (pseudo-termp '((lambda (x) (car x)) b)) ; has value t
    (pseudo-termp '(if x y 123))             ; has value nil (123 is not quoted)
    (pseudo-termp '(if x y '123))            ; has value t

  If [47mx[0m is the quotation of a term, then [47m(pseudo-termp x)[0m is [47mt[0m.
  However, if [47mx[0m is not the quotation of a term it is not necessarily
  the case that [47m(pseudo-termp x)[0m is [47mnil[0m.

  See [term] for a discussion of the various meanings of the word
  ``term'' in ACL2.  In its most strict sense, a term is either a
  legal variable symbol, a quoted constant, or the application of an
  [47mn[0m-ary function symbol or closed [47mlambda[0m-expression to [47mn[0m terms.  By
  ``legal variable symbol'' we exclude constant symbols, such as [47mt[0m,
  [47mnil[0m, and [47m*ts-rational*[0m.  By ``quoted constants'' we include [47m't[0m (aka
  [47m(quote t)[0m), [47m'nil[0m, [47m'31[0m, etc., and exclude constant names such as [47mt[0m,
  [47mnil[0m and [47m*ts-rational*[0m, unquoted constants such as [47m31[0m or [47m1/2[0m, and
  ill-formed [47mquote[0m expressions such as [47m(quote 3 4)[0m.  By ``closed
  lambda expression'' we exclude expressions, such as [47m(lambda (x)
  (cons x y))[0m, containing free variables in their bodies.  Terms
  typed by the user are translated into strict terms for internal use
  in ACL2.

  The predicate [47mtermp[0m checks this strict sense of ``term'' with respect
  to a given ACL2 logical world; See [world].  Many ACL2 functions,
  such as the rewriter, require certain of their arguments to satisfy
  [47mtermp[0m.  However, if regarded simply from the perspective of an
  effective [guard] for a term-processing function, [47mtermp[0m checks many
  irrelevant things.  (Does it really matter that the variable
  symbols encountered never start and end with an asterisk?)  We have
  therefore introduced the notion of a ``pseudo-term'' and embodied
  it in the predicate [47mpseudo-termp[0m, which is easier to check, does
  not require the logical [world] as input, and is often perfectly
  suitable as a [guard] on term-processing functions.

  A [47mpseudo-termp[0m is either a symbol, a true list of length 2 beginning
  with the word [47mquote[0m, the application of an [47mn[0m-ary pseudo-[47mlambda[0m
  expression to a true list of [47mn[0m pseudo-terms, or the application of
  a symbol to a true list of [47mn[0m [47mpseudo-termp[0ms.  By an ``[47mn[0m-ary
  pseudo-[47mlambda[0m expression'' we mean an expression of the form
  [47m(lambda (v1 ... vn) pterm)[0m, where the [47mvi[0m are symbols (but not
  necessarily distinct legal variable symbols) and [47mpterm[0m is a
  [47mpseudo-termp[0m.

  Metafunctions may use [47mpseudo-termp[0m as a [guard].")
 (PSO
  (OUTPUT-CONTROLS)
  "Show the most recently saved output

  Evaluate [47m:pso[0m in order to print output that was generated in an
  environment where output was being saved, as in [gag-mode], which
  is active when ACL2 is invoked.  Also see [gag-mode].

    Example Forms:

    :pso                        ; Print saved output.

    (pso)                       ; equivalent to the above
    (pso :all)                  ; equivalent to the above
    (pso :all nil)              ; equivalent to the above

    (pso \"Subgoal *1/2''\")      ; Print saved output only for \"Subgoal *1/2''\".

    (pso '\"Subgoal *1/2'5'\"
          \"Subgoal *1/2'14'\")   ; Print saved output starting with the output
                                ; for '\"Subgoal *1/2'5'\" and ending just
                                ; before the output for \"Subgoal *1/2'14'\".

    (pso '(\"Subgoal *1/2'5'\"  \"Subgoal *1/2''\")
         '(\"Subgoal *1/2'14'\" \"Subgoal *1/2'12'\")
                                ; Print saved output
                                ; starting with the output for either
                                ; \"Subgoal *1/2'5'\" or \"Subgoal *1/2''\"
                                ; (whichever comes first)
                                ; and stopping just before the output for either
                                ; \"Subgoal *1/2'14'\" or \"Subgoal *1/2'12'\"
                                ; (whichever comes first).

    General Form:

    (pso start-goals-spec ; optional: default is :ALL
         stop-goals-spec  ; optional: default is NIL
         )

  where both arguments are optional and have the defaults shown above.
  Thus, the keyword command [47m:pso[0m is equivalent to each of [47m(pso)[0m, [47m(pso
  :all)[0m, and [47m(pso :all nil)[0m; see [keyword-commands].  The optional
  arguments restrict the output to specified goals, as follows; but
  the examples above probably provide an easier way to understand
  those arguments than the following explanation.

    * [47mStart-goals-spec[0m represents [3mthe set of start goal names[0m.  Its effects
      are described below.  The value [47m:all[0m represents the set of all
      goal names, a string represents the set consisting of just that
      one goal name, and a list represents the set of all goal names
      in that list.

    * [47mStop-goals-spec[0m represents [3mthe set of stop goal names[0m.  Its effects
      are described below, following the same conventions as above
      except that [47m:all[0m is not allowed.

    * Printing begins immediately if [47mstart-goals-spec[0m is [47m:all[0m, else begins
      with the first goal whose name is in the set of start goal
      names.

    * If the set of stop goal names is empty (as is the case when the
      second optional argument is omitted), then printing takes place
      only for the first goal whose name is in the set of start goal
      names.  Otherwise, printing continues starting with that goal,
      stopping only when a goal in the list of stop goal names is
      encountered, without any printing for that goal.

  Note that saved prover output is cleared at every top-level prover
  call, including such calls made by: [events] (e.g., [47m[defthm][0m and
  [47m[defun][0m), [47m[thm][0m, and [proof-builder] commands that invoke the
  prover.  A single event can make more than one top-level prover
  call, for example: in the case of [47m[defun][0m, one call made for
  termination and another for guard verification; and in the case of
  [47m[defthm][0m, one call made for the proposed theorem and one for each
  [corollary]. If you want to see more than one proof log for a
  single top-level form, then instead of using [47m:pso[0m, first evaluate
  [47m(set-gag-mode nil)[0m.

  The ``Time'' printed in the summary shows the original times for the
  proof attempt, not the times for processing the [47m:pso[0m command.

  Also see [pso!], [psog], [psof], [set-gag-mode],
  [set-inhibit-output-lst], and [set-print-clause-ids].")
 (PSO!
  (OUTPUT-CONTROLS)
  "Show the most recently saved output, including [proof-tree] output

  [47m:Pso![0m provides output just like [47m:pso[0m, except that [proof-tree] is
  included; see [47m[pso][0m.

  [47mPso![0m takes the same optional arguments as [47mpso[0m; see [pso], and also
  see [psog] and [psof].")
 (PSOF
  (OUTPUT-CONTROLS)
  "Show the most recently saved output

  For a similar utility, see [pso].  But unlike [47m:pso[0m, [47m:psof[0m takes a
  filename argument and writes output to that file, instead of
  printing to the terminal.  For large proofs, [47m:[0m[47m[psof][0m may complete
  much more quickly than [47m:[0m[47m[pso][0m.

  The first line of output from [47m:psof[0m directs the Emacs editor to use
  auto-revert mode.  You can change the frequency of auto-reverting
  the buffer connected to a file by evaluating a suitable command in
  Emacs.  For example, the command [47m(setq auto-revert-interval .1)[0m
  arranges for auto-revert mode to update as needed every 1/10 of a
  second.

  [47mPsof[0m takes the same optional arguments as [47mpso[0m; see [pso], and also
  see [pso!] and [psog].")
 (PSOG
  (OUTPUT-CONTROLS)
  "Show the most recently saved output with [gag-mode]

  [47m:Psog[0m is like [47m:pso[0m --- see [pso] --- but unlike [47m:pso[0m, [47m:psog[0m displays
  the output in [gag-mode]; more precisely, with gag-mode equal to [47mt[0m.

  [47mPsog[0m takes the same optional arguments as [47mpso[0m; see [pso], and also
  see [pso!] and [psof].")
 (PSTACK
  (DEBUGGING)
  "Seeing what the prover is up to

    General Forms:
    (pstack)      ; inspect break
    (pstack t)    ; inspect break, printing all calls in abbreviated form
    (pstack :all) ; as above, but only abbreviating the ACL2 world

  When the form [47m(pstack)[0m is executed during a break from a proof, or at
  the end of a proof that the user has aborted, a ``process stack''
  (or ``prover stack'') will be printed that gives some idea of what
  the theorem prover has been doing.  Moreover, by evaluating
  [47m(verbose-pstack t)[0m before starting a proof (see [verbose-pstack])
  one can get trace-like information about prover functions,
  including time summaries, printed to the screen during a proof.
  This feature is currently quite raw and may be refined considerably
  as time goes on, based on user suggestions.  For example, the usual
  control of printing given by [set-inhibit-output-lst] is irrelevant
  for printing the pstack.

  The use of [47m(pstack t)[0m or [47m(pstack :all)[0m should only be used by those
  who are comfortable looking at functions in the ACL2 source code.
  Otherwise, simply use [47m(pstack)[0m.

  Entries in the pstack include the following (listed here
  alphabetically, except for the first).

  [47mpreprocess-clause[0m, [47msimplify-clause[0m, etc. (in general,[47mxxx-clause[0m):
  top-level processes in the prover ``waterfall''

  [47mclausify[0m: splitting a goal into subgoals

  [47mev-fncall[0m: evaluating a function on explicit arguments

  [47mev-fncall+[0m: evaluating a function on explicit arguments while
  assuming that [warrant] hypotheses are true

  [47mev-fncall-meta[0m: evaluating a metafunction

  [47mforward-chain[0m: building a context for the current goal using
  [47m[forward-chaining][0m rules

  [47minduct[0m: finding an induction scheme

  [47mpop-clause[0m: getting the next goal to prove by induction

  [47mprocess-assumptions[0m: creating forcing rounds

  [47mremove-built-in-clauses[0m: removing built-in [clause]s (see
  [built-in-clause])

  [47mprocess-equational-polys[0m: deducing interesting equations

  [47mremove-trivial-equivalences[0m: removing trivial equalities (and
  equivalences) from the current goal

  [47mrewrite-atm[0m: rewriting a top-level term in the current goal

  [47msetup-simplify-clause-pot-lst[0m: building the linear arithmetic
  database for the current goal

  [47mstrip-branches[0m, [47msubsumption-replacement-loop[0m: subroutines of [47mclausify[0m

  [47mwaterfall[0m: top-level proof control


Subtopics

  [Verbose-pstack]
      Seeing what the prover is up to (for system hackers)")
 (PUFF
  (HISTORY)
  "Replace a compound [command] by its immediate subevents

    Example Forms:
    ACL2 !>:puff :max
    ACL2 !>:puff :x
    ACL2 !>:puff 15
    ACL2 !>:puff \"book\"

    General Form:
    :puff cd

  where [47mcd[0m is a [command] descriptor (see [command-descriptor]) for a
  ``puffable'' [command] (see below).  [47mPuff[0m replaces the [command] at
  [47mcd[0m by the immediate subevents of the [command], executed as
  [command]s.  [47mPuff[0m then prints, using [47m[pcs][0m, the [47mpuff[0med region.

  We consider [47mpuff[0m to be a sort of hack; it is generally robust and
  sound, but that is not guaranteed.  If any existing ACL2 event
  resulted from [47mpuff[0m, ACL2 considers proofs to have been skipped, and
  thus [47m[certify-book][0m is disallowed until such events have been
  undone (see [ubt]).

  Other than the few exceptions noted later below, a ``puffable''
  [command] is an [47m[encapsulate][0m, [47m[include-book][0m, or [47m[certify-book][0m
  [command], or any command other than those consisting of a single
  primitive event.  For example, since [47m[defun][0m is a primitive event,
  a [47m[defun][0m command is not puffable.  But a macro form that expands
  into one or more [events] is puffable.  The only primitive events
  that are puffable are calls of [47m[encapsulate][0m or [47m[include-book][0m.  In
  this sense, [47m[make-event][0m is not considered primitive --- that is,
  it can be puffed --- and moreover, an immediate subevent that is a
  call of [47mmake-event[0m is generally replaced by its expansion (see
  [make-event]).  A puffable [command] contains (interesting)
  subevents, namely, the events in the body of the [47m[encapsulate][0m, in
  the file of the book included, or in the [command] block.

  The puff [command] ``lifts'' the immediate subevents of the indicated
  [command] so that they become [command]s themselves.  The [command]
  [47m[puff*][0m recursively puffs the newly introduced [command]s.  See
  [puff*], which also gives an example illustrating both [47mpuff[0m and
  [47m[puff*][0m.  [47mPuff[0m undoes the [command] at [47mcd[0m and replaces it by its
  immediate subevents.  Thus, in general the length of the [history]
  grows when a puff [command] is executed.  If [47mpuff[0m causes an error
  (see below), the logical [world] remains unchanged from its initial
  configuration.

  The intended use of [47mpuff[0m is to allow the user access to the [events]
  ``hidden'' inside compound [command]s.  For example, while trying
  to prove some theorem, [47mp[0m, about a constrained function, [47mfn[0m, one
  might find that the [47m[encapsulate][0m, [47mcd[0m, that introduced [47mfn[0m failed to
  include an important [constraint], [47mq[0m.  Without [47mpuff[0m, the only way
  to proceed is to undo back through [47mcd[0m, create a suitable
  [47m[encapsulate][0m that proves and exports [47mq[0m as well as the old
  [constraint]s, re-execute the new [47m[encapsulate][0m, re-execute the
  [events] since [47mcd[0m, and then try [47mp[0m again.  Unfortunately, it may be
  hard to prove [47mq[0m and additional [events] may have to be inserted
  into the [47m[encapsulate][0m to prove it.  It may also be hard to
  formulate the ``right'' [47mq[0m, i.e., one that is provable in the
  [47m[encapsulate][0m and provides the appropriate facts for use in the
  proof of [47mp[0m.

  Using [47mpuff[0m, the user can erase the [47m[encapsulate][0m at [47mcd[0m, replacing it
  by the [events] in its body.  Now the formerly constrained
  function, [47mfn[0m, is defined as its witness.  The user can experiment
  with formulations and proofs of [47mq[0m suitable for [47mp[0m.  Of course, to
  get into the ultimately desired [state] --- where [47mfn[0m is constrained
  rather than defined and [47mq[0m is exported by an [47m[encapsulate][0m at [47mcd[0m ---
  the user must ultimately undo back to [47mcd[0m and carry out the more
  tedious program described above.  But by using [47mpuff[0m it is easier to
  experiment.

  Similar applications of [47mpuff[0m allow the user of a book to expose the
  top-level [events] in the book as though they had all been typed as
  [command]s.  The user might then ``partially undo'' the book,
  keeping only some of the events in it.

  [47mPuff[0m operates as follows.  First, it determines the list of immediate
  subevents of the [command] indicated by [47mcd[0m.  It causes an error if
  there is only one subevent and that subevent is identical to the
  [command] --- i.e., if the [command] at [47mcd[0m is a primitive.  Next,
  [47mpuff[0m undoes back through the indicated [command].  This not only
  erases the [command] at [47mcd[0m but all the [command]s executed after
  it.  Finally, [47mpuff[0m re-executes the subevents of (the now erased) [47mcd[0m
  followed by all the [command]s that were executed afterwards.

  Observe that the [command]s executed after [47mcd[0m will generally have
  higher [command] numbers than they did before the puff.  For
  example, suppose 100 [command]s have been executed and that [47m:puff
  80[0m is then executed.  Suppose [command] 80 contains 5 immediate
  subevents (i.e., is an encapsulation of five [events]).  Then,
  after puffing, [command] 80 is the first event of the puffed
  [command], [command] 81 is the second, and so on; 104 [command]s
  appear to have been executed.

  When puffing an [47m[encapsulate][0m or [47m[include-book][0m, the [47m[local][0m
  [command]s are executed.  Note that this will replace constrained
  functions by their witnesses.

  Here are some details and a few exceptions.

    * An [47m[encapsulate][0m command that generates [unknown-constraints], such
      as one generated by the macro
      [47m[define-trusted-clause-processor][0m, is not puffable.

    * When an [47m[encapsulate][0m has a non-empty [signature], it is not puffable
      if the `puff' command issued is [47m:[0m[47m[puff*][0m, rather than [47m:[0m[47mpuff[0m.
      That is because puffing may fail in this case, as discussed
      immediately below, and it may be annoying to deal with the
      failure, for example if [47m:puff*[0m takes a long time to run.

    * An attempt to puff may fail for an [47m[encapsulate][0m with a non-empty
      [signature] that contains at least one use of [47m[make-event][0m and
      also comes from a certified book.  The reason is that local
      definitions may be elided.  Here is an example of such a book.

          (in-package \"ACL2\")

          (encapsulate
            ((f (x) t))
            (make-event '(local (defun f (x) (cons x x))))
            (defthm f-prop (consp (f x))))

      If we first certify this book, then we include it in a new ACL2
      session, and next we issue the command [47m:puff 1[0m, then we can see
      that the local definition in our [47mencapsulate[0m event has been
      elided:

          ACL2 !>:pcb! 1
                     1  (ENCAPSULATE
                             ((F (X) T))
                             (RECORD-EXPANSION
                                  (MAKE-EVENT '(LOCAL (DEFUN F (X) (CONS X X))))
                                  (LOCAL (VALUE-TRIPLE :ELIDED)))
                             (DEFTHM F-PROP (CONSP (F X))))
                         (DEFTHM F-PROP (CONSP (F X)))
          ACL2 !>

      Now an attempt to execute the command, [47m:puff 1[0m, causes an error
      because [47mf[0m lacks a definition.

          ACL2 !>:puff 1


          ACL2 Error in ( DEFTHM F-PROP ...):  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 X).

          ACL2 !>

    * Similarly, a [47m[local][0m event that involves [47m[make-event][0m expansion may
      be elided when the event is from a book whose [47m[include-book][0m
      form has been puffed.  This will result in an error if the
      elided event is necessary to support later events in the [47mpuff[0m
      of the command.  Here is an example, where the attempt to puff
      an [47minclude-book[0m for this book will fail, giving an error for [47m(
      DEFUN G ...)[0m stating that the symbol [47mF[0m has not been defined.

          (in-package \"ACL2\")
          (make-event '(local (defun f (x) x)))
          (local (defun g (x) (f x)))

    * An attempt to [47mpuff[0m an [47m[include-book][0m command may fail for a book that
      has been modified, as described later in this documentation
      topic.

    * The [47mpuff[0m of an [47m[include-book][0m command for an uncertified book will
      simply expose the contents of the book.  However, if the book
      is certified then the [47mpuff[0m will replace each event by its
      [47m[make-event][0m expansion.  Also, ACL2 considers that (certified)
      book to have been included; future attempts to include that
      book will be considered to be [redundant].

  Finally, we note that it is an error to [47mpuff[0m in the presence of
  [47m[include-book][0m [events] for certified books that have been altered
  since they were included.  (Note that this restriction only applies
  to [47m[include-book][0m, not to [47m[certify-book][0m.)  To be specific, suppose
  [47m\"arith\"[0m is a certified book that has been included in a session.
  Suppose that after [47m\"arith\"[0m was included, the source file is
  modified.  (This might happen if the user of [47m\"arith\"[0m is not its
  author and the author happens to be working on a new version of
  [47m\"arith\"[0m during the same time period.)  Now suppose the user tries
  to [47mpuff[0m the [command] that included [47m\"arith\"[0m.  The attempt to obtain
  the subevents in [47m\"arith\"[0m will discover that the [book-hash] of
  [47m\"arith\"[0m has changed and an error will be caused.  No change is made
  in the logical [world].  A similar error is caused if, in this same
  situation, the user tries to puff any command that occurred before
  the inclusion of [47m\"arith\"[0m!  That is, [47mpuff[0m may cause an error and
  leave the [world] unchanged even if the [command] puffed is not one
  involving the modified book.  This happens because in order to
  reconstruct the [world] after the puffed [command], [47mpuff[0m must
  obtain the [events] in the book and if the book's source file has
  changed there is no assurance that the reconstructed [world] is the
  one the user intends.

  Warning: We do not detect changes to uncertified [books] that have
  been included and are then puffed or re-included!  The act of
  including an uncertified book leaves no trace of the [book-hash]
  value for the book.  Furthermore, the act prints a warning message
  disclaiming soundness.  In light of this, [47m:puff[0m quietly
  ``re-''executes the current contents of the book.")
 (PUFF*
  (HISTORY)
  "Replace a compound [command] by its subevents

    Example Forms:
    ACL2 !>:puff* :max
    ACL2 !>:puff* :x
    ACL2 !>:puff* 15
    ACL2 !>(puff* 15) ; same as just above
    ACL2 !>(puff* 15 t) ; same as just above, but keep partial results
    ACL2 !>:puff* \"book\"

    General Forms:
    :puff* cd
    (puff* 'cd) ; argument can be any expression evaluating to cd
    (puff* 'cd b) ; where b is t or nil

  where [47mcd[0m is a [command] descriptor (see [command-descriptor]).  See
  [puff] for the definition of ``puffable'' and for a description of
  the basic act of ``puffing'' a [command].  [47mPuff*[0m is just the
  recursive application of [puff]: it puffs not only the indicated
  command, but all of the commands thus generated, and recursively
  until none of the resulting commands can be puffed.  As noted in
  the documentation for [puff], [47m:puff[0m should be viewed as a sort of
  hack; hence so should [47mpuff*[0m.  [47mPuff*[0m prints the region [puff]ed,
  using [47m[pcs][0m.

  Thus, to [puff] a [command] is to replace it by its immediate
  subevents, each of which is executed as a [command].  To [47mpuff*[0m a
  [command] is to replace the [command] by each of its immediate
  subevents and then to [47mpuff*[0m each of the puffable [command]s among
  the newly introduced ones.  NOTE: because one call of [47m:puff*[0m may
  give rise to many calls of [47m:puff[0m, it can take considerable time for
  a call of [47m:puff*[0m to complete when many books are involved.

  For example, suppose [47m\"ab\"[0m is a book containing the following

    (in-package \"ACL2\")
    (include-book \"a\")
    (include-book \"b\")

  Suppose that book [47m\"a\"[0m only contained [47m[defun][0ms for the functions [47ma1[0m
  and [47ma2[0m and that [47m\"b\"[0m only contained [47m[defun][0ms for [47mb1[0m and [47mb2[0m.

  Now consider an ACL2 [state] in which only two [command]s have been
  executed, the first being [47m(include-book \"ab\")[0m and the second being
  [47m(include-book \"c\")[0m.  Thus, the relevant part of the display
  produced by [47m:[0m[47m[pbt][0m 1 would be:

    1 (INCLUDE-BOOK \"ab\")
    2 (INCLUDE-BOOK \"c\")

  Call this [state] the ``starting [state]'' in this example, because
  we will refer to it several times.

  Suppose [47m:puff 1[0m is executed in the starting [state].  Then the first
  [command] is replaced by its immediate subevents and [47m:pbt 1[0m would
  show:

    1 (INCLUDE-BOOK \"a\")
    2 (INCLUDE-BOOK \"b\")
    3 (INCLUDE-BOOK \"c\")

  Contrast this with the execution of [47m:puff* 1[0m in the starting [state].
  [47mPuff*[0m would first [puff] [47m(include-book \"ab\")[0m to get the [state]
  shown above.  But then it would recursively [47mpuff*[0m the puffable
  [command]s introduced by the first [puff].  This continues
  recursively as long as any [puff] introduced a puffable [command].
  The end result of [47m:puff* 1[0m in the starting [state] is

    1 (DEFUN A1 ...)
    2 (DEFUN A2 ...)
    3 (DEFUN B1 ...)
    4 (DEFUN B2 ...)
    5 (INCLUDE-BOOK \"c\")

  Observe that when [47mpuff*[0m is done, the originally indicated [command],
  [47m(include-book \"ab\")[0m, has been replaced by the corresponding
  sequence of primitive [events].  Observe also that puffable
  [command]s elsewhere in the [history], for example, [command] 2 in
  the starting [state], are not affected (except that their [command]
  numbers grow as a result of the splicing in of earlier [command]s).

  [47m:Puff*[0m may cause an error, for example because of a name conflict
  caused by two different local lemmas with the same name, or because
  a [47m[local][0m event in a book has been elided (see [puff]).  By
  default, the logical [world] is reverted to its value before that
  execution of [47mpuff*[0m.  However, if the optional Boolean second
  argument is [47mt[0m, then the world is preserved from the successful
  [47m:puff[0m commands executed before the failed one.  That behavior can
  help with debugging, since both the warning message and the return
  value tell you which command could not be puffed successfully.")
 (PUSH-UNTOUCHABLE
  (DEFTTAG)
  "Add name or list of names to the list of untouchable symbols

  Untouchables are functions that cannot be called, as well as [state]
  global variables (see [programming-with-state]) that cannot be
  modified or unbound.  Macros can also be untouchable in some sense;
  see [defmacro-untouchable].

    Examples:
    (push-untouchable my-var nil)
    (push-untouchable set-mem t)

    General Form:
    (push-untouchable name{s} fn-p)

  where [47mname{s}[0m is a non-[47mnil[0m symbol or a non-[47mnil[0m true list of symbols,
  and [47mfn-p[0m is any value (but generally [47mnil[0m or [47mt[0m).  If [47mname{s}[0m is a
  symbol it is treated as the singleton list containing that symbol.
  The effect of this event is to union the given symbols into the
  list of ``untouchable variables'' in the current world if [47mfn-p[0m is
  [47mnil[0m, else to union the symbols into the list of ``untouchable
  functions''.  This event is redundant if every symbol listed is
  already a member of the appropriate untouchables list (variables or
  functions).

  There is a further restriction on which function names may be made
  untouchable: If a function symbol, [47mg[0m, may be introduced into a
  proof by a metatheorem (via the metafunction or the hypothesis
  metafunction) or by a clause processor and the metatheorem or
  clause processor has a [47m:[0m[47m[well-formedness-guarantee][0m then [47mg[0m may not
  be made untouchable.

  As noted above, macros may not be made directly untouchable; the
  macro [47m[defmacro-untouchable][0m is provided for that purpose.  Thus,
  it is an error to evaluate [47m(push-untouchable F t)[0m if [47mF[0m is already a
  macro name, and it is also an error to define [47mF[0m as a macro when [47mF[0m
  has been made an untouchable function using [47m(push-untouchable F t)[0m.

  When a symbol is on the untouchables list it is syntactically illegal
  for any event to call a function of that name, if [47mfn-p[0m is non-[47mnil[0m,
  or to change the value of a state global variable of that name, if
  [47mfn-p[0m is [47mnil[0m.  Thus, the effect of pushing a function symbol, [47mname[0m,
  onto untouchables is to prevent any future event from using that
  symbol as a function, or as a state global variable (according to
  [47mfn-p[0m).  This is generally done to ``fence off'' some primitive
  function symbol from ``users'' after the developer has used the
  symbol freely in the development of some higher level mechanism.

  Also see [remove-untouchable].")
 (PUT-ASSOC
  (ALISTS ACL2-BUILT-INS)
  "Modify an association list by associating a value with a key

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

  [47m(Put-assoc name val alist)[0m returns an alist that is the same as the
  list [47malist[0m, except that the first pair in [47malist[0m with a [47m[car][0m of
  [47mname[0m is replaced by [47m(cons name val)[0m, if there is one.  If there is
  no such pair, then [47m(cons name val)[0m is added at the end.  Note that
  the order of the keys occurring in [47malist[0m is unchanged (though a new
  key may be added).

  The [guard] for a call of [47mput-assoc[0m depends on the test.  In all
  cases, the last argument must satisfy [47m[alistp][0m.  If the test is
  [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m
  (see [eqlablep]) or the last argument must satisfy
  [47m[eqlable-alistp][0m.  If the test is [47m[eq][0m, then either the first
  argument must be a symbol or the last argument must satisfy
  [47m[symbol-alistp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mput-assoc[0m and its variants:

      [47m(put-assoc-eq name val alist)[0m is equivalent to [47m(put-assoc name val
      alist :test 'eq)[0m;

      [47m(put-assoc-equal name val alist)[0m is equivalent to [47m(put-assoc name val
      alist :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mput-assoc-equal[0m.

  [31;1mFunction: [0m<put-assoc-equal>

    (defun put-assoc-equal (name val alist)
      (declare (xargs :guard (alistp alist)))
      (cond ((endp alist) (list (cons name val)))
            ((equal name (caar alist))
             (cons (cons name val) (cdr alist)))
            (t (cons (car alist)
                     (put-assoc-equal name val (cdr alist))))))")
 (PUT-ASSOC-EQ (POINTERS)
               "See [put-assoc].")
 (PUT-ASSOC-EQL (POINTERS)
                "See [put-assoc].")
 (PUT-ASSOC-EQUAL (POINTERS)
                  "See [put-assoc].")
 (PUTPROP
  (WORLD ACL2-BUILT-INS)
  "Update fast property lists

    General form:
    (putprop symbol key value world-alist)

  See [world] for discussion of both utilities [47m[getprop][0m and [47mputprop[0m.
  Also see community book [47mbooks/misc/getprop.lisp[0m for an example that
  illustrates the use of ACL2 utilities [47mgetprop[0m and [47mputprop[0m to take
  advantage of under-the-hood Lisp (hashed) property lists.

  [31;1mFunction: [0m<putprop>

    (defun putprop (symb key value world-alist)
      (declare (xargs :guard (and (symbolp symb)
                                  (symbolp key)
                                  (plist-worldp world-alist))))
      (cons (cons symb (cons key value))
            world-alist))")
 (Q
  (LP)
  "Quit ACL2 (type [47m:q[0m) --- reenter with [47m(lp)[0m

    Example:
    ACL2 !>:Q

  The keyword command [47m:q[0m typed at the top-level of the ACL2 loop will
  terminate the loop and return control to the Common Lisp top-level
  (or, more precisely, to whatever program invoked [47m[lp][0m).  To reenter
  the ACL2 loop, execute [47m(acl2::lp)[0m in Common Lisp.  You will be in
  the same state as you were when you exited with [47m:q[0m, unless during
  your stay in Common Lisp you messed with the data structures
  representing the ACL2 [state] (including files, property lists, and
  single-threaded objects).

  You may also issue the command [47m(value :q)[0m to exit the ACL2 loop.
  More generally, if the result of evaluating a form in the ACL2 loop
  is the [error-triple] [47m(nil :q state)[0m, the ACL2 loop will be exited.

  WARNING: The issuance of commands to raw Lisp may render your ACL2
  session unsound.  Furthermore, evaluation of forms after exiting
  the ACL2 loop with [47m:q[0m (or [47m(value :q)[0m, etc.) is not guaranteed to
  agree with their evaluation in the ACL2 loop.  Specifically, Common
  Lisp may read an expression with the backquote character ([47m`[0m)
  differently from how ACL2 reads the expression.  (The technical
  reason, in Common Lisp parlance, is that ACL2 installs its own
  readtable in the ACL2 loop, which includes a custom backquote
  reader.)  Results of evaluation may have surprising differences
  depending on whether evaluation takes place in the ACL2 loop or in
  raw Lisp, as illustrated by the following log produced using an
  ACL2 executable built on SBCL.

    ACL2 !>(car (quote `(a b c)))
    QUOTE
    ACL2 !>:q

    Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
    * (car (quote `(a b c)))
    SB-INT:QUASIQUOTE
    *

  To minimize discrepancies (including that one) between ACL2 and raw
  Lisp, use [raw-mode] instead of exiting the ACL2 loop.

  Unlike all other keyword commands, typing [47m:q[0m is not equivalent to
  invoking the function [47mq[0m.  There is no function [47mq[0m.")
 (QUANTIFIER-TUTORIAL
  (DEFUN-SK)
  "A Beginner's Guide to Reasoning about Quantification in ACL2

  The initial version of this tutorial was written by Sandip Ray.
  Additions and revisions are welcome.  Sandip has said:

      ``This is a collection of notes that I wrote to remind myself of how
      to reason about quantifiers when I just started.  Most users
      after they have gotten the hang of quantifiers probably will
      not need this and will be able to use their intuitions to guide
      them in the process.  But since many ACL2 users are not used to
      quantification, I am hoping that this set of notes might help
      them to think clearly while reasoning about quantifiers in
      ACL2.''

  Many ACL2 papers start with the sentence ``ACL2 is a quantifier-free
  first-order logic of recursive functions.'' It is true that the
  [3msyntax[0m of ACL2 is quantifier-free; every formula is assumed to be
  universally quantified over all free variables in the formula.  But
  the [3mlogic[0m in fact does afford arbitrary first-order quantification.
  This is obtained in ACL2 using a construct called [47mdefun-sk[0m.  See
  [defun-sk].

  Many ACL2 users do not think in terms of [quantifiers].  The focus is
  almost always on defining recursive functions and reasoning about
  them using induction.  That is entirely justified, in fact, since
  proving theorems about recursive functions by induction plays to
  the strengths of the theorem prover.  Nevertheless there are
  situations where it is reasonable and often useful to think in
  terms of quantifiers.  However, reasoning about quantifiers
  requires that you get into the mindset of thinking about theorems
  in terms of quantification.  This note is about how to do this
  effectively given ACL2's implementation of quantification.  This
  does not discuss [47m[defun-sk][0m in detail, but merely shows some
  examples.  A detailed explanation of the implementation is in the
  ACL2 [documentation] (see [defun-sk]); also see
  [conservativity-of-defchoose].

  [Note: Quantifiers can be used for some pretty cool things in ACL2.
  Perhaps the most interesting example is the way of using
  quantifiers to introduce arbitrary tail-recursive equations; see
  the paper ``Partial Functions in ACL2'' by Panagiotis Manolios and
  J Strother Moore.  This note does not address applications of
  quantifiers, but merely how you would reason about them once you
  think you want to use them.]

  Assume that you have some function [47mP[0m.  I have just left [47mP[0m as a unary
  function stub below, since I do not care about what [47mP[0m is.

    (defstub P (*) => *)

  Now suppose you want to specify the concept that ``there exists some
  [47mx[0m such that [47m(P x)[0m holds''.  ACL2 allows you to write that directly
  using quantifiers.

    (defun-sk exists-P () (exists x (P x)))

  If you submit the above form in ACL2 you will see that the theorem
  prover specifies two functions [47mexists-p[0m and [47mexists-p-witness[0m, and
  exports the following constraints:

    1.  (defun exists-P () (P (exists-P-witness)))
    2.  (defthm exists-P-suff (implies (p x) (exists-p)))

  Here [47mexists-P-witness[0m is a new function symbol in the current ACL2
  theory.  What do the constraints above say?  Notice the constraint
  [47mexists-p-suff[0m.  It says that if you can provide any [47mx[0m such that [47m(P
  x)[0m holds, then you know that [47mexists-p[0m holds.  Think of the other
  constraint (definition of [47mexists-p[0m) as going the other way.  That
  is, it says that if [47mexists-p[0m holds, then there is some [47mx[0m, call it
  [47m(exists-p-witness)[0m, for which [47mP[0m holds.  Notice that nothing else is
  known about [47mexists-p-witness[0m than the two constraints above.

  [Note: [47mexists-p-witness[0m above is actually defined in ACL2 using a
  special form called [47mdefchoose[0m.  See [defchoose].  This note does
  not talk about [47mdefchoose[0m.  So far as this note is concerned, think
  of [47mexists-p-witness[0m as a new function symbol that has been
  generated somehow in ACL2, about which nothing other than the two
  facts above is known.]

  Similarly, you can talk about the concept that ``for all [47mx[0m [47m(P x)[0m
  holds.'' This can be specified in ACL2 by the form:

    (defun-sk forall-P () (forall x (P x)))

  This produces the following two constraints:

    1.  (defun forall-P () (P (forall-p-witness)))
    2.  (defthm forall-p-necc (implies (not (P x)) (not (forall-p))))

  To understand these, think of [47mforall-p-witness[0m as producing some [47mx[0m
  which does not satisfy [47mP[0m, if such a thing exists.  The constraint
  [47mforall-p-necc[0m merely says that if [47mforall-p[0m holds then [47mP[0m is
  satisfied for every [47mx[0m.  (To see this more clearly, just think of
  the contrapositive of the formula shown.) The other constraint
  (definition of [47mforall-p[0m) implies that if [47mforall-p[0m does not hold
  then there is some [47mx[0m, call it [47m(forall-p-witness)[0m, which does not
  satisfy [47mP[0m.  To see this, just consider the following formula which
  is immediately derivable from the definition.

    (implies (not (forall-p)) (not (P (forall-witness))))

  The description above suggests that to reason about quantifiers, the
  following Rules of Thumb, familiar to most any student of logic,
  are useful.

      RT1: To prove [47m(exists-p)[0m, construct some object [47mA[0m such that [47mP[0m holds
      for [47mA[0m and then use [47mexists-P-suff[0m.

      RT2: If you assume [47mexists-P[0m in your hypothesis, use the definition of
      [47mexists-p[0m to know that [47mP[0m holds for [47mexists-p-witness[0m.  To use
      this to prove a theorem, you must be able to derive the theorem
      based on the hypothesis that [47mP[0m holds for something, whatever
      the something is.

      RT3: To prove [47mforall-P[0m, prove the theorem [47m(P x)[0m (that is, that [47mP[0m
      holds for an arbitrary [47mx[0m), and then simply instantiate the
      definition of [47mforall-p[0m, that is, show that [47mP[0m holds for the
      witness.

      RT4: If you assume [47mforall-p[0m in the hypothesis of the theorem, see how
      you can prove your conclusion if indeed you were given [47m(P x)[0m as
      a theorem.  Possibly for the conclusion to hold, you needed
      that [47mP[0m holds for some specific set of [47mx[0m values.  Then use the
      theorem [47mforall-p-necc[0m by instantiating it for the specific [47mx[0m
      values you care about.

  Perhaps the above is too terse.  In the remainder of the note, we
  will consider several examples of how this is done to prove
  theorems in ACL2 that involve quantified notions.

  Let us consider two trivial theorems.  Assume that for some unary
  function [47mr[0m, you have proved [47m(r x)[0m as a theorem.  Let us see how you
  can prove that (1) there exists some x such that [47m(r x)[0m holds, and
  (2) for all [47mx[0m [47m(r x)[0m holds.

  We first model these things using [47m[defun-sk][0m.  Below, [47mr[0m is simply
  some function for which [47m(r x)[0m is a theorem.

    (encapsulate
     (((r *) => *))
     (local (defun r (x) (declare (ignore x)) t))
     (defthm r-holds (r x)))

    (defun-sk exists-r () (exists x (r x)))
    (defun-sk forall-r () (forall x (r x)))

  ACL2 does not have too much reasoning support for quantifiers.  So in
  most cases, one would need [47m:use[0m hints to reason about quantifiers.
  In order to apply [47m:use[0m [hints], it is preferable to keep the
  function definitions and theorems disabled.

    (in-theory (disable exists-r exists-r-suff forall-r forall-r-necc))

  Let us now prove that there is some [47mx[0m such that [47m(r x)[0m holds.  Since
  we want to prove [47mexists-r[0m, we must use [47mexists-r-suff[0m by RT1.  We do
  not need to construct any instance here since [47mr[0m holds for all [47mx[0m by
  the theorem above.

    (defthm exists-r-holds
      (exists-r)
      :hints ((\"Goal\" :use ((:instance exists-r-suff)))))

  Let us now prove the theorem that for all [47mx[0m, [47m(r x)[0m holds.  By RT3, we
  must be able to prove it by definition of [47mforall-r[0m.

    (defthm forall-r-holds
      (forall-r)
      :hints ((\"Goal\" :use ((:instance (:definition forall-r))))))

  [Note: Probably no ACL2 user in his or her right mind would prove the
  theorems [47mexists-r-holds[0m and [47mforall-r-holds[0m above.  The theorems
  shown are only for demonstration purposes.]

  For the remainder of this note we will assume that we have two
  stubbed out unary functions [47mM[0m and [47mN[0m, and we will look at proving
  some quantified properties of these functions.

    (defstub M (*) => *)
    (defstub N (*) => *)

  Let us now define the predicates [47mall-M[0m, [47mall-N[0m, [47msome-M[0m, and [47msome-N[0m
  specifying the various quantifications.

    (defun-sk all-M () (forall x (M x)))
    (defun-sk all-N () (forall x (N x)))
    (defun-sk some-M () (exists x (M x)))
    (defun-sk some-N () (exists x (N x)))

    (in-theory (disable all-M all-N all-M-necc all-N-necc))
    (in-theory (disable some-M some-N some-M-suff some-N-suff))

  Let us prove the classic distributive properties of quantification:
  the distributivity of universal quantification over conjunction,
  and the distributivity of existential quantification over
  disjunction.  We can state these properties informally in ``pseudo
  ACL2'' notation as follows:

    1.  (exists x: (M x)) or (exists x: (N x)) <=> (exists x: (M x) or (N x))
    2.  (forall x: (M x)) and (forall: x (N x)) <=> (forall x: (M x) and (N x))

  To make these notions formal we of course need to define the formulas
  at the right-hand sides of 1 and 2.  So we define [47msome-MN[0m and
  [47mall-MN[0m to capture these concepts.

    (defun-sk some-MN () (exists x (or (M x) (N x))))
    (defun-sk all-MN () (forall x (and (M x) (N x))))

    (in-theory (disable all-MN all-MN-necc some-MN some-MN-suff))

  First consider proving property 1.  The formal statement of this
  theorem would be: [47m(iff (some-MN) (or (some-M) (some-N)))[0m.

  How do we prove this theorem?  Looking at RT1-RT4 above, note that
  they suggest how one should reason about quantification when one
  has an ``implication''.  But here we have an ``equivalence''.  This
  suggests another rule of thumb.

      RT5: Whenever possible, prove an equivalence involving quantifiers by
      proving two implications.

  Let us apply RT5 to prove the theorems above.  So we will first
  prove: [47m(implies (some-MN) (or (some-M) (some-N)))[0m

  How can we prove this?  This involves assuming a quantified predicate
  [47m(some-MN)[0m, so we must use RT2 and apply the definition of [47msome-MN[0m.
  Since the conclusion involves a disjunction of two quantified
  predicates, by RT1 we must be able to construct two objects [47mA[0m and [47mB[0m
  such that either [47mM[0m holds for [47mA[0m or [47mN[0m holds for [47mB[0m, so that we can
  then invoke [47msome-M-suff[0m and [47msome-N-suff[0m to prove the conclusion.
  But now notice that if [47msome-MN[0m is true, then there is already an
  object, in fact [47msome-MN-witness[0m, such that either [47mM[0m holds for it,
  or [47mN[0m holds for it.  And we know this is the case from the
  definition of [47msome-MN[0m! So we will simply prove the theorem
  instantiating [47msome-M-suff[0m and [47msome-N-suff[0m with this witness.  The
  conclusion is that the following event will go through with ACL2.

    (defthm le1
      (implies (some-MN)
               (or (some-M) (some-N)))
      :rule-classes nil
      :hints ((\"Goal\"
                :use ((:instance (:definition some-MN))
                      (:instance some-M-suff
                                 (x (some-MN-witness)))
                      (:instance some-N-suff
                                 (x (some-MN-witness)))))))

  This also suggests the following rule of thumb:

      RT6: If a conjecture involves assuming an existentially quantified
      predicate in the hypothesis from which you are trying to prove
      an existentially quantified predicate, use the witness of the
      existential quantification in the hypothesis to construct the
      witness for the existential quantification in the conclusion.

  Let us now try to prove the converse of le1, that is: [47m(implies (or
  (some-M) (some-N)) (some-MN))[0m

  Since the hypothesis is a disjunction, we will just prove each case
  individually instead of proving the theorem by a [47m:[0m[47mcases[0m hint.  So
  we prove the following two lemmas.

    (defthm le2
      (implies (some-M) (some-MN))
      :rule-classes nil
      :hints ((\"Goal\"
                :use ((:instance (:definition some-M))
                      (:instance some-MN-suff
                                 (x (some-M-witness)))))))

    (defthm le3
      (implies (some-N) (some-MN))
      :rule-classes nil
      :hints ((\"Goal\"
                :use ((:instance (:definition some-N))
                      (:instance some-MN-suff
                                 (x (some-N-witness)))))))

  Note that the hints above are simply applications of RT6 as in [47mle1[0m.
  With these lemmas, of course the main theorem is trivial.

    (defthmd |some disjunction|
      (iff (some-MN) (or (some-M) (some-N)))
      :hints ((\"Goal\"
                :use ((:instance le1)
                      (:instance le2)
                      (:instance le3)))))

  Let us now prove the distributivity of universal quantification over
  conjunction, that is, the formula: [47m(iff (all-MN) (and (all-M)
  (all-N)))[0m

  Applying RT5, we will again decompose this into two implications.  So
  consider first the one-way implication: [47m(implies (and (all-M)
  (all-N)) (all-MN))[0m.

  Here we get to assume [47mall-M[0m and [47mall-N[0m.  Thus by RT4 we can use
  [47mall-M-necc[0m and [47mall-N-necc[0m to think as if we are given the formulas
  [47m(M x)[0m and [47m(N x)[0m as theorems.  The conclusion here is also a
  universal quantification, namely we have to prove [47mall-MN[0m.  Then RT3
  tells us to proceed as follows.  Take any object [47my[0m.  Try to find an
  instantiation [47mz[0m of the hypothesis that implies [47m(and (M y) (N y))[0m.
  Then instantiate [47my[0m with [47mall-MN-witness[0m.  Note that the hypothesis
  lets us assume [47m(M x)[0m and [47m(N x)[0m to be theorems.  Thus to justify we
  need to instantiate [47mx[0m with [47my[0m, and in this case, therefore, with
  [47mall-MN-witness[0m.  To make the long story short, the following event
  goes through with ACL2:

    (defthm lf1
       (implies (and (all-M) (all-N))
                (all-MN))
        :rule-classes nil
        :hints ((\"Goal\"
                  :use ((:instance (:definition all-MN))
                        (:instance all-M-necc (x (all-MN-witness)))
                        (:instance all-N-necc (x (all-MN-witness)))))))

  This suggests the following rule of thumb which is a dual of RT6:

      RT7: If a conjecture assumes some universally quantified predicate in
      the hypothesis and its conclusion asserts a universally
      quantified predicate, then instantiate the ``necessary
      condition'' ([47mforall-mn-necc[0m) of the hypothesis with the witness
      of the conclusion to prove the conjecture.

  Applying RT7 now we can easily prove the other theorems that we need
  to show that universal quantification distributes over conjunction.
  Let us just go through this motion in ACL2.

    (defthm lf2
      (implies (all-MN)
               (all-M))
      :rule-classes nil
      :hints ((\"Goal\"
                :use ((:instance (:definition all-M))
                      (:instance all-MN-necc
                                 (x (all-M-witness)))))))

    (defthm lf3
      (implies (all-MN)
               (all-N))
      :rule-classes nil
      :hints ((\"Goal\"
                :use ((:instance (:definition all-N))
                      (:instance all-MN-necc
                                 (x (all-N-witness)))))))

    (defthmd |all conjunction|
      (iff (all-MN)
           (and (all-M) (all-N)))
     :hints ((\"Goal\" :use ((:instance lf1)
                           (:instance lf2)
                           (:instance lf3)))))

  The rules of thumb for universal and existential quantification
  should make you realize the duality of their use.  Every reasoning
  method about universal quantification can be cast as a way of
  reasoning about existential quantification, and vice versa.
  Whether you reason using universal and existential quantifiers
  depends on what is natural in a particular context.  But just for
  the sake of completeness let us prove the duality of universal and
  existential quantifiers.  So what we want to prove is the
  following:

    3.  (forall x (not (M x))) = (not (exists x (M x)))

  We first formalize the notion of [47m(forall x (not (M x)))[0m as a
  quantification.

    (defun-sk none-M () (forall x (not (M x))))
    (in-theory (disable none-M none-M-necc))

  So we now want to prove: [47m(equal (none-M) (not (some-M)))[0m.

  As before, we should prove this as a pair of implications.  So let us
  prove first: [47m(implies (none-M) (not (some-M)))[0m.

  This may seem to assert an existential quantification in the
  conclusion, but rather, it asserts the [3mnegation[0m of an existential
  quantification.  We are now trying to prove that something does not
  exist.  How do we do that?  We can show that nothing satisfies [47mM[0m by
  just showing that [47m(some-M-witness)[0m does not satisfy [47mM[0m.  This
  suggests the following rule of thumb:

      RT8: When you encounter the negation of an existential quantification
      think in terms of a universal quantification, and vice-versa.

  Ok, so now applying RT8 and RT3 you should be trying to apply the
  definition of [47msome-M[0m.  The hypothesis is just a pure (non-negated)
  universal quantification so you should apply RT4.  A blind
  application lets us prove the theorem as below.

    (defthm nl1
      (implies (none-M) (not (some-M)))
      :rule-classes nil
      :hints ((\"Goal\"
                :use ((:instance (:definition some-M))
                      (:instance none-M-necc (x (some-M-witness)))))))

  How about the converse implication?  I have deliberately written it
  as [47m(implies (not (none-M)) (some-M))[0m instead of switching the
  left-hand and right-hand sides of [47mnl1[0m, which would have been
  equivalent.  Again, RH8 tells us how to reason about it, in this
  case using RH2, and we succeed.

    (defthm nl2
      (implies (not (none-M)) (some-M))
      :rule-classes nil
      :hints ((\"Goal\"
                :use ((:instance (:definition none-M))
                      (:instance some-M-suff (x (none-M-witness)))))))

  So finally we just go through the motions of proving the equality.

    (defthmd |forall not = not exists|
      (equal (none-M) (not (some-M)))
      :hints ((\"Goal\"
                :use ((:instance nl1)
                      (:instance nl2)))))

  Let us now see if we can prove a slightly more advanced theorem which
  can be stated informally as: If there is a natural number [47mx[0m which
  satisfies [47mM[0m, then there is a least natural number [47my[0m that satisfies
  [47mM[0m.

  [Note: Any time I have had to reason about existential quantification
  I have had to do this particular style of reasoning and state that
  if there is an object satisfying a predicate, then there is also a
  ``minimal'' object satisfying the predicate.]

  Let us formalize this concept.  We first define the concept of
  existence of a natural number satisfying [47mx[0m.

    (defun-sk some-nat-M () (exists x (and (natp x) (M x))))
    (in-theory (disable some-nat-M some-nat-M-suff))

  We now talk about what it means to say that [47mx[0m is the least number
  satisfying [47mM[0m.

    (defun-sk none-below (y)
      (forall r (implies (and (natp r) (< r y)) (not (M r))))))
    (in-theory (disable none-below none-below-necc))

    (defun-sk min-M () (exists y (and (M y) (natp y) (none-below y))))
    (in-theory (disable min-M min-M-suff))

  The predicate [47mnone-below[0m says that no natural number less than [47my[0m
  satisfies [47mM[0m.  The predicate [47mmin-M[0m says that there is some natural
  number [47my[0m satisfying [47mM[0m such that [47mnone-below[0m holds for [47my[0m.

  So the formula we want to prove is: [47m(implies (some-nat-M) (min-M))[0m.

  Since the formula requires that we prove an existential
  quantification, RT1 tells us to construct some object satisfying
  the predicate over which we are quantifying.  We should then be
  able to instantiate [47mmin-M-suff[0m with this object.  That predicate
  says that the object must be the least natural number that
  satisfies [47mM[0m.  Since such an object is uniquely computable if we
  know that there exists some natural number satisfying [47mM[0m, let us
  just write a recursive function to compute it.  This function is
  [47mleast-M[0m below.

    (defun least-M-aux (i bound)
      (declare (xargs :measure (nfix (- (1+ bound) i))))
      (cond ((or (not (natp i))
                 (not (natp bound))
                 (> i bound))
             0)
           ((M i) i)
           (t (least-M-aux (+ i 1) bound))))

    (defun least-M (bound) (least-M-aux 0 bound))

  Let us now reason about this function as one does typically.  So we
  prove that this object is indeed the least natural number that
  satisfies [47mM[0m, assuming that [47mbound[0m is a natural number that satisfies
  [47mM[0m.

    (defthm least-aux-produces-an-M
      (implies (and (natp i)
                    (natp bound)
                    (<= i bound)
                    (M bound))
               (M (least-M-aux i bound))))

    (defthm least-<=bound
      (implies (<= 0 bound)
               (<= (least-M-aux i bound) bound)))

    (defthm least-aux-produces-least
      (implies (and (natp i)
                    (natp j)
                    (natp bound)
                    (<= i j)
                    (<= j bound)
                    (M j))
                (<= (least-M-aux i bound) j)))

    (defthm least-aux-produces-natp
      (natp (least-M-aux i bound)))

    (defthmd least-is-minimal-satisfying-m
      (implies (and (natp bound)
                    (natp i)
                     (< i (least-M bound)))
               (not (M i)))
      :hints ((\"Goal\"
                :in-theory (disable least-aux-produces-least least-<=bound)
                :use ((:instance least-<=bound
                                 (i 0))
                      (:instance least-aux-produces-least
                                 (i 0)
                                 (j i))))))

    (defthm least-has-m
      (implies (and (natp bound)
                    (m bound))
               (M (least-M bound))))

    (defthm least-is-natp
      (natp (least-M bound)))

  So we have done that, and hopefully this is all that we need about
  [47mleast-M[0m.  So we disable everything.

    (in-theory (disable least-M natp))

  Now of course we note that the statement of the conjecture we are
  interested in has two quantifiers, an inner [47mforall[0m (from
  [47mnone-below[0m) and an outer [47mexists[0m (from [47mmin-M[0m).  Since ACL2 is not
  very good with quantification, we hold its hands to reason with the
  quantifier part.  So we will first prove something about the [47mforall[0m
  and then use it to prove what we need about the [47mexists[0m.

      RT9: When you face nested quantifiers, reason about each nesting
      separately.

  So what do we want to prove about the inner quantifier?  Looking
  carefully at the definition of [47mnone-below[0m we see that it is saying
  that for all natural numbers [47mr[0m < [47my[0m, [47m(M r)[0m does not hold.  Well, how
  would we want to use this fact when we want to prove our final
  theorem?  We expect that we will instantiate [47mmin-M-suff[0m with the
  object [47m(least-M bound)[0m where we know (via the outermost existential
  quantifier) that [47mM[0m holds for [47mbound[0m, and we will then want to show
  that [47mnone-below[0m holds for [47m(least-M bound)[0m.  So let us prove that
  for any natural number (call it [47mbound[0m), [47mnone-below[0m holds for
  [47m(least-M bound)[0m.  For the final theorem we only need it for natural
  numbers satisfying [47mM[0m, but note that from the lemma
  [47mleast-is-minimal-satisfying-m[0m we really do not need that [47mbound[0m
  satisfies [47mM[0m.

  So we are now proving: [47m(implies (natp bound) (none-below (least-M
  bound)))[0m.

  Well since this is a standard case of proving a universally
  quantified predicate, we just apply RT3.  We have proved that for
  all naturals [47mi[0m < [47m(least-M bound)[0m, [47mi[0m does not satisfy [47mM[0m (lemma
  [47mleast-is-minimal-satisfying-M[0m), so we merely need the instantiation
  of that lemma with [47mnone-below-witness[0m of the thing we are trying to
  prove, that is, [47m(least-M bound)[0m.  The theorem below thus goes
  through.

    (defthm least-is-minimal
      (implies (natp bound)
               (none-below (least-M bound)))
      :hints ((\"Goal\"
                :use ((:instance (:definition none-below)
                                 (y (least-M bound)))
                      (:instance least-is-minimal-satisfying-m
                                 (i (none-below-witness (least-M bound))))))))

  Finally we are in the outermost existential quantifier, and are in
  the process of applying [47mmin-M-suff[0m.  What object should we
  instantiate it with?  We must instantiate it with [47m(least-M bound)[0m
  where [47mbound[0m is an object which must satisfy [47mM[0m and is a natural.  We
  have such an object, namely [47m(some-nat-M-witness)[0m which we know have
  all these qualities given the hypothesis.  So the proof now is just
  RT1 and RT2.

    (defthm |minimal exists|
      (implies (some-nat-M) (min-M))
      :hints ((\"Goal\"
                :use ((:instance min-M-suff
                                 (y (least-M (some-nat-M-witness))))
                      (:instance (:definition some-nat-M))))))

  If you are comfortable with the reasoning above, then you are
  comfortable with quantifiers and probably will not need these notes
  any more.  In my opinion, the best way of dealing with ACL2 is to
  ask yourself why you think something is a theorem, and the rules of
  thumb above are simply guides to the questions that you need to ask
  when you are dealing with quantification.

  Here are a couple of simple exercises for you to test if you
  understand the reasoning process.

  [31;1mExercise 1[0m.  Formalize and prove the following theorem.  Suppose
  there exists [47mx[0m such that [47m(R x)[0m and suppose that all [47mx[0m satisfy [47m(P
  x)[0m.  Then prove that there exists [47mx[0m such that [47m(P x) & (R x)[0m.  (See
  {http://www.cs.utexas.edu/users/moore/acl2/contrib/quantifier-exercise-1-solution.html
  |
  http://www.cs.utexas.edu/users/moore/acl2/contrib/quantifier-exercise-1-solution.html}
  for a solution.)

  [31;1mExercise 2[0m.  Recall the example just before the preceding exercise,
  where we showed that if there exists a natural number [47mx[0m satisfying
  [47mM[0m then there is another natural number [47my[0m such that [47my[0m satisfies [47mM[0m
  and for every natural number [47mz[0m < [47my[0m, [47mz[0m does not.  What would happen
  if we remove the restriction of [47mx[0m, [47my[0m, and [47mz[0m being naturals?  Of
  course, we will not talk about [47m<[0m any more, but suppose you use a
  total order on all ACL2 objects such as [<<].  More concretely,
  consider the definition of [47msome-M[0m above.  Let us now define two
  other functions:

    (include-book \"misc/total-order\" :dir :system)

    (defun-sk none-below-2 (y)
      (forall r (implies (<< r y) (not (M r)))))

    (defun-sk min-M2 () (exists y (and (M y) (none-below-2 y))))

  The question is whether [47m(implies (some-M) (min-M2))[0m is a theorem.
  Can you prove it?  Can you disprove it? See
  [47m[solution-to-ACL2-quantifier-exercise-2][0m for a solution.


Subtopics

  [Solution-to-ACL2-quantifier-exercise-2]
      A solution to [47m[quantifier-tutorial][0m Exercise 2")
 (QUANTIFIERS
  (DEFUN-SK)
  "Issues about quantification in ACL2

  ACL2 supports first-order quantifiers [47m[exists][0m and [47m[forall][0m by way of
  the [47m[defun-sk][0m event.  However, proof support for quantification is
  quite limited.  Therefore, you may prefer using recursion in place
  of [47mdefun-sk[0m when possible (following common ACL2 practice).

  For example, the notion ``every member of [47mx[0m has property [47mp[0m'' can be
  defined either with recursion or explicit quantification, but
  proofs may be simpler when recursion is used.  We illustrate this
  point with two proofs of the same informal claim, one of which uses
  recursion which the other uses explicit quantification.  Notice
  that with recursion, the proof goes through fully automatically;
  but this is far from true with explicit quantification (especially
  notable is the ugly hint).

  The informal claim for our examples is: If every member [47ma[0m of each of
  two lists satisfies the predicate [47m(p a)[0m, then this holds of their
  [47m[append][0m; and, conversely.

  See [quantifiers-using-recursion] for a solution to this example
  using recursion.

  See [quantifiers-using-defun-sk] for a solution to this example using
  [47m[defun-sk][0m.  Also See [quantifiers-using-defun-sk-extended] for an
  elaboration on that solution.

  But perhaps first, see [defun-sk] for an ACL2 utility to introduce
  first-order quantification in a direct way.  Examples of the use of
  [47mdefun-sk[0m are also available: see [defun-sk-example] and see
  [Tutorial4-Defun-Sk-Example] for basic examples, and see
  [quantifier-tutorial] for a more complete, careful beginner's
  introduction that takes you through typical kinds of
  quantifier-based reasoning in ACL2.


Subtopics

  [Quantifiers-using-defun-sk]
      Quantification example

  [Quantifiers-using-defun-sk-extended]
      Quantification example with details

  [Quantifiers-using-recursion]
      Recursion for implementing quantification")
 (QUANTIFIERS-USING-DEFUN-SK
  (QUANTIFIERS)
  "Quantification example

  See [quantifiers] for the context of this example.  It should be
  compared to a corresponding example in which a simpler proof is
  attained by using recursion in place of explicit quantification;
  see [quantifiers-using-recursion].

    (in-package \"ACL2\")

    ; We prove that if every member A of each of two lists satisfies the
    ; predicate (P A), then this holds of their append; and, conversely.

    ; Here is a solution using explicit quantification.

    (defstub p (x) t)

    (defun-sk forall-p (x)
      (forall a (implies (member a x)
                         (p a))))

    (defthm member-append
      (iff (member a (append x1 x2))
           (or (member a x1) (member a x2))))

    (defthm forall-p-append
      (equal (forall-p (append x1 x2))
             (and (forall-p x1) (forall-p x2)))
      :hints ((\"Goal\" ; ``should'' disable forall-p-necc, but no need
               :use
               ((:instance forall-p-necc
                           (x (append x1 x2))
                           (a (forall-p-witness x1)))
                (:instance forall-p-necc
                           (x (append x1 x2))
                           (a (forall-p-witness x2)))
                (:instance forall-p-necc
                           (x x1)
                           (a (forall-p-witness (append x1 x2))))
                (:instance forall-p-necc
                           (x x2)
                           (a (forall-p-witness (append x1 x2))))))))

  Also see [quantifiers-using-defun-sk-extended] for an elaboration on
  this example.")
 (QUANTIFIERS-USING-DEFUN-SK-EXTENDED
  (QUANTIFIERS)
  "Quantification example with details

  See [quantifiers-using-defun-sk] for the context of this example.

    (in-package \"ACL2\")

    ; We prove that if every member A of each of two lists satisfies the
    ; predicate (P A), then this holds of their append; and, conversely.

    ; Here is a solution using explicit quantification.

    (defstub p (x) t)

    (defun-sk forall-p (x)
      (forall a (implies (member a x)
                         (p a))))

    ; The defun-sk above introduces the following axioms.  The idea is that
    ; (FORALL-P-WITNESS X) picks a counterexample to (forall-p x) if there is one.

    ;   (DEFUN FORALL-P (X)
    ;     (LET ((A (FORALL-P-WITNESS X)))
    ;          (IMPLIES (MEMBER A X) (P A))))
    ;
    ;   (DEFTHM FORALL-P-NECC
    ;     (IMPLIES (NOT (IMPLIES (MEMBER A X) (P A)))
    ;              (NOT (FORALL-P X)))
    ;     :HINTS ((\"Goal\" :USE FORALL-P-WITNESS)))

    ; The following lemma seems critical.

    (defthm member-append
      (iff (member a (append x1 x2))
           (or (member a x1) (member a x2))))

    ; The proof of forall-p-append seems to go out to lunch, so we break into
    ; directions as shown below.

    (defthm forall-p-append-forward
      (implies (forall-p (append x1 x2))
               (and (forall-p x1) (forall-p x2)))
      :hints ((\"Goal\" ; ``should'' disable forall-p-necc, but no need
               :use
               ((:instance forall-p-necc
                           (x (append x1 x2))
                           (a (forall-p-witness x1)))
                (:instance forall-p-necc
                           (x (append x1 x2))
                           (a (forall-p-witness x2)))))))

    (defthm forall-p-append-reverse
      (implies (and (forall-p x1) (forall-p x2))
               (forall-p (append x1 x2)))
      :hints ((\"Goal\"
               :use
               ((:instance forall-p-necc
                           (x x1)
                           (a (forall-p-witness (append x1 x2))))
                (:instance forall-p-necc
                           (x x2)
                           (a (forall-p-witness (append x1 x2))))))))

    (defthm forall-p-append
      (equal (forall-p (append x1 x2))
             (and (forall-p x1) (forall-p x2)))
      :hints ((\"Goal\" :use (forall-p-append-forward
                            forall-p-append-reverse))))")
 (QUANTIFIERS-USING-RECURSION
  (QUANTIFIERS)
  "Recursion for implementing quantification

  The following example illustrates the use of recursion as a means of
  avoiding proof difficulties that can arise from the use of explicit
  quantification (via [47m[defun-sk][0m).  See [quantifiers] for more about
  the context of this example.

    (in-package \"ACL2\")

    ; We prove that if every member A of each of two lists satisfies the
    ; predicate (P A), then this holds of their append; and, conversely.

    ; Here is a solution using recursively-defined functions.

    (defstub p (x) t)

    (defun all-p (x)
      (if (atom x)
          t
        (and (p (car x))
             (all-p (cdr x)))))

    (defthm all-p-append
      (equal (all-p (append x1 x2))
             (and (all-p x1) (all-p x2))))")
 (QUICK-AND-DIRTY-SUBSUMPTION-REPLACEMENT-STEP
  (DEBUGGING)
  "(advanced topic) controlling a heuristic in the prover's clausifier

  This topic is probably only of interest to those who are undertaking
  particularly complex proof developments.

  The ACL2 prover's handling of propositional logic uses a heuristic
  that we believe might cause the prover to slow down significantly
  or even to trigger a stack overflow.  However, we believe these
  negative effects are only felt on very large formulas --- formulas
  that are likely to cause similar degradation of many other parts of
  ACL2.

  The following two events turn off that heuristic (by eliminating
  calls to source function
  [47mquick-and-dirty-subsumption-replacement-step[0m, after which this
  [documentation] topic is named).

    (defun quick-and-dirty-srs-off (cl1 ac)
      (declare (ignore cl1 ac)
               (xargs :mode :logic :guard t))
      nil)

    (defattach-system quick-and-dirty-srs quick-and-dirty-srs-off)

  However, if you feel the need to try this out, please remember that
  the proof is likely to fail anyway since other parts of ACL2 will
  probably be stressed.  A more basic problem with your proof
  strategy may exist: the formulas are getting extraordinarily large.
  A common approach for avoiding such problem include disabling
  functions (see [in-theory]).  Other less common approaches might
  help if you are sufficiently desperate, such as defining your own
  [47mIF[0m function to use in place of the built-in [47mIF[0m.

  For an example of where this capability has proven useful, see
  [without-subsumption].  That tool uses [47m[set-case-split-limitations][0m
  as well, since that is another way to control the prover's handling
  of propositional logic.

  To turn the heuristic back on:

    (defattach-system quick-and-dirty-srs quick-and-dirty-srs-builtin)")
 (QUIT (GOOD-BYE)
       "Quit entirely out of Lisp

  Same as [47m[good-bye][0m.")
 (QUOTE
  (BASICS ACL2-BUILT-INS)
  "Create a constant

  The form [47m(quote x)[0m evaluates to [47mx[0m.  See any Common Lisp
  documentation.  Also see [unquote].


Subtopics

  [Unquote]
      Obtain the object being quoted")
 (QUOTEP (POINTERS)
         "See [system-utilities].")
 (R-AND-I-ABBREVIATIONS-FOR-TERMS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Abbreviations for Terms

  If [3mx[0m  is [47mt[0m, [47mnil[0m, an integer, a character object, or a string, and [3mx[0m
  is used where a term is expected, then [3mx[0m  abbreviates the quoted
  constant [47m'[0m[3mx[0m.  Recall that a single quote mark followed by a symbol,
  e.g., [47m'load[0m, is a quoted constant.

  In the following, an [3mexpression[0m  is an integer, a character object,
  a string, a symbol, an optionally dotted parenthesized sequence of
  expressions, or a single quote mark followed by an expression.  By
  [3moptionally dotted parenthesized sequence of expressions[0m we mean a
  parenthesized non-empty sequence of expressions, optionally
  containing a dot (.) between the last two expressions in the
  sequence.  For example ``[47m(A 123 . B)[0m'' and ``[47m(A (123 B) 'C)[0m'' are
  both optionally dotted parenthesized sequences of expressions.

  A single quote mark followed by an optionally dotted parenthesized
  sequence of expressions, when used as a term, denotes a [47mcons[0m term
  as follows, using these four rules:

  [3mNULL Rule:[0m  If '() is used as a term, it abbreviates [47m'nil[0m.

  [3mSingleton Rule:[0m  If [47m'([3mx[0m[47m)[0m is used as a term it abbreviates [47m(cons '[3mx[0m[47m
  'nil)[0m.

  [3mDotted Pair Rule:[0m  If [47m'([3mx[0m[47m  . [3my[0m[47m)[0m is used as a term it abbreviates
  [47m(cons '[3mx[0m[47m  '[3my[0m[47m)[0m.

  [3mList Rule:[0m  If [47m'([3mx[0m[47m  [3m\\alpha[0m[47m)[0m is used as a term and [3m\\alpha[0m  is any
  non-empty sequence of expressions it abbreviates [47m(cons '[3mx[0m[47m
  '([3m\\alpha[0m[47m))[0m.  Note the new pair of parentheses around [47m[3m\\alpha[0m[47m[0m.

  Thus, for example, the rules above mean that if [47m'(A B C)[0m is used as
  a term then it denotes [47m(cons 'A '(B C))[0m, which denotes [47m(cons 'A
  (cons 'B '(C)))[0m, which denotes [47m(cons 'A (cons 'B (cons 'C 'nil)))[0m.

  If [47m'(A B . C)[0m is used as a term it denotes [47m(cons 'A (cons 'B 'C))[0m.

  It remains to deal with cases like [47m'[0m[47m'A[0m and [47m'[0m[47m'(A 'B)[0m involving
  multiple single quote marks.  We do not expect to use such
  expressions in this course but we specify their meaning just for
  completeness.

  Let [3m\\alpha[0m  be an expression that does not start with a single quote
  mark.  Consider a sequence of two or more single quote marks
  followed by [3m\\alpha[0m and suppose it is used as a term.  It denotes a
  [47mcons[0m derived as follows.  Replace [3m\\alpha[0m  and the single quote mark
  immediately before it with [47m(quote [3m\\alpha[0m[47m)[0m.  Repeat that replacement
  until all but the first single quote mark remains.  Then apply the
  four rules above.

  Thus, [47m'[0m[47m'(A 'B)[0m, when used as a term, denotes the term derived by the
  following sequence of steps

  [47m'[0m[47m'(A 'B)[0m
  [47m'(quote (A 'B))[0m
  [47m(cons 'quote '((A 'B)))[0m
  [47m(cons 'quote (cons '(A 'B) 'nil))[0m
  [47m(cons 'quote (cons (cons 'A '('B)) 'nil))[0m
  [47m(cons 'quote (cons (cons 'A (cons '[0m[47m'B 'nil)) 'nil))[0m
  [47m(cons 'quote (cons (cons 'A (cons '(quote B) 'nil)) 'nil))[0m
  [47m(cons 'quote (cons (cons 'A (cons (cons 'quote '(B)) 'nil)) 'nil))[0m
  [47m(cons 'quote (cons (cons 'A (cons (cons 'quote (cons 'B 'nil)) 'nil))
  'nil))[0m

  Note that every occurrence of single quote now marks a quoted
  constant.

  When [47m(list [3mx_1[0m[47m   ... )[0m is used as a term, it abbreviates [47m(cons [3mx_1[0m[47m
  (list  ... ))[0m.  When [47m(list)[0m is used as a term, it abbreviates [47mnil[0m.
  Thus [47m(list a b c)[0m abbreviates [47m(cons a (cons b (cons c nil)))[0m.

  [47mAnd[0m and [47mor[0m will be defined as function symbols of two arguments.
  But if [47mand[0m is used as though it were a function symbol of more than
  two arguments, then it abbreviates the corresponding
  right-associated nest of [47mand[0ms.  Thus, [47m(and p q r s)[0m, when used
  where a term is expected, abbreviates [47m(and p (and q (and r s)))[0m.

  If [47mor[0m is used as though it were a function symbol of more than two
  arguments, then it abbreviates the corresponding right-associated
  nest of [47mor[0ms.

  (Maybe explore term abbreviation in ACL2?  But abbreviation is
  complicated in ACL2 by the presence of a powerful macro facility.
  To learn about ACL2 term abbreviation, explore <<[term]>>, paying
  special attention to ``untranslated'' terms.  Maybe also explore
  <<[macros]>>.)

  [31;1mProblem 7.
  [0m Show the term abbreviated by each of the following:

   1. [47m(cons 1 '(2 3))[0m

   2. [47m(equal \"Hello\" hello)[0m

   3. [47m(and (or a1 a2 a3) (or b1 b2 b3) (or c1 c2 c3))[0m

   4. [47m(equal x '(or a1 a2 a3))[0m

   5. [47m(cons cons '(cons cons 'cons))[0m

  The art of displaying a Lisp term in a way that it can be easily
  read by a person is called [3mpretty printing[0m.  We recommend the
  following heuristics.  First, write clearly and count your
  parentheses.  Second, try never to write a single line with more
  than about 30 non-blank characters on it.  Third, if a function
  call will not fit on a line, break it into multiple lines,
  indenting each argument the same amount.

  Below we show one term pretty printed with successively narrower
  margins.  (Note that the display is a term only if [47mapp[0m is a
  function symbol of arity two.)  We find the second and third lines
  of the first display below excessively long.  Each display shows
  exactly the same term.  Note how we break terms to indent arguments
  the same amount and how we sometimes slide the arguments under the
  function symbol to save horizontal space.  Personally, we find the
  second display below (the one labeled ``[47mwidth 46[0m'') the easiest to
  read.  We show the others merely to illustrate how more space can
  be saved when one finds oneself close to the right margin.

      |<---------------------------- width 70 ---------------------------->|

      (IMPLIES (AND (CONSP A)
                    (EQUAL (APP (APP (CDR A) B) C) (APP (CDR A) (APP B C))))
               (EQUAL (APP (APP A B) C) (APP A (APP B C))))

      |<---------------- width 46 ---------------->|

      (IMPLIES (AND (CONSP A)
                    (EQUAL (APP (APP (CDR A) B) C)
                           (APP (CDR A) (APP B C))))
               (EQUAL (APP (APP A B) C)
                      (APP A (APP B C))))

      |<------------ width 38 ------------>|

      (IMPLIES
       (AND (CONSP A)
            (EQUAL (APP (APP (CDR A) B) C)
                   (APP (CDR A) (APP B C))))
       (EQUAL (APP (APP A B) C)
              (APP A (APP B C))))

      |<---------- width 34 ---------->|

      (IMPLIES
       (AND
        (CONSP A)
        (EQUAL (APP (APP (CDR A) B) C)
               (APP (CDR A) (APP B C))))
       (EQUAL (APP (APP A B) C)
              (APP A (APP B C))))

      |<------- width 28 ------->|

      (IMPLIES
       (AND
        (CONSP A)
        (EQUAL
         (APP (APP (CDR A) B) C)
         (APP (CDR A) (APP B C))))
       (EQUAL
        (APP (APP A B) C)
        (APP A (APP B C))))

      |<---- width 23 ----->|

      (IMPLIES
       (AND
        (CONSP A)
        (EQUAL
         (APP (APP (CDR A) B)
              C)
         (APP (CDR A)
              (APP B C))))
       (EQUAL
        (APP (APP A B) C)
        (APP A (APP B C))))

  Next: Function Definitions (see [R-AND-I-FUNCTION-DEFINITIONS]) (or
  Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-ACL2-ARITHMETIC
  (R-AND-I-ARITHMETIC)
  "Recursion and Induction: ACL2 Arithmetic

  The techniques we have studied so far suffice to prove the most
  elementary facts of natural number arithmetic.  In fact, we could
  conduct our entire study of recursion and induction in the domain
  of number theory.  But it is more fun to deal with less familiar
  ``data structures'' where basic properties can be discovered.  So
  we will skip past formal arithmetic with a few brief remarks.

  ACL2 provides the numbers as a data type distinct from conses,
  symbols, strings, and characters.  They are not lists of [47mnil[0ms!  The
  naturals are among the integers, the integers are among the
  rationals, and the rationals are among the ACL2 numbers.  The
  complex rationals are also among the ACL2 numbers; in fact they are
  complex numbers whose real and imaginary parts are rational and
  whose imaginary parts are non-[47m0[0m.

  Here are a few commonly used functions in ACL2.

      [47m(natp x)[0m - recognizes natural numbers

      [47m(integerp x)[0m - recognizes integers

      [47m(rationalp x)[0m - recognizes rationals

      [47m(zp x)[0m - [47mt[0m if x is [47m0[0m or not a natural; [47mnil[0m otherwise

      [47m(nfix x)[0m - [47mx[0m if [47mx[0m is a natural; [47m0[0m otherwise

      [47m(+ x y)[0m - sum of the numbers [47mx[0m and [47my[0m

      [47m(- x y)[0m - difference of the numbers [47mx[0m and [47my[0m

      [47m(* x y)[0m - product of the numbers [47mx[0m and [47my[0m

      [47m(/ x y)[0m - rational quotient of the numbers [47mx[0m and [47my[0m

      [47m(< x y)[0m - predicate recognizing that the number [47mx[0m is less than the
      number [47my[0m

      [47m(<= x y)[0m - predicate recognizing that the number [47mx[0m is less than or
      equal to the number [47my[0m

  The functions [47m+[0m, [47m-[0m, [47m*[0m, [47m/[0m, [47m<[0m, and [47m<=[0m default their arguments to [47m0[0m in
  the sense that if some argument is not an ACL2 number then [47m0[0m is
  used instead.

  The predicate [47mzp[0m is commonly used in recursive definitions that
  treat an argument as though it were a natural number and count it
  down to zero.

  Here is a ``definition'' that accesses the [47mn[0mth element of a list,
  treating [47mn[0m as a natural.  (This definition is unacceptable under
  our current Principle of Structural Recursion because [47m(consp x)[0m
  does not rule the recursive call.  We will return to this point
  momentarily.)

      (defun nth (n x)
        (if (zp n)
            (car x)
            (nth (- n 1) (cdr x))))

  Thus, [47m(nth 2 '(A B C D))[0m is [47mC[0m.  [47m(Nth 0 '(A B C D))[0m is [47mA[0m.
  Interestingly, [47m(nth -1 '(A B C D))[0m is also [47mA[0m, because [47m-1[0m satisfies
  [47mzp[0m.  Thus, we can use [47mnth[0m with any first argument.  (In ACL2, [47mnth[0m
  is defined differently, but equivalently.)

  The numbers are axiomatized with the standard axioms for rational
  fields.  See [reference 3] (see [R-AND-I-ANNOTATED-BIBLIOGRAPHY]).

  [31;1mHenceforth, you may use arithmetic freely in your proofs and assume
  any theorem of ACL2 arithmetic.  That is, you may assume any ACL2
  theorem that can be written with the function symbols described
  above and use it in routine arithmetic simplification.  But be
  careful about what you assume![0m

  For example, the following familiar arithmetic facts are not (quite)
  theorems:

      (equal (+ x 0) x)                ; Additive Identity

      (iff (equal (+ x y) (+ x z))     ; Additive Cancellation
           (equal y z))

    Why aren't the formulas above theorems?

  In addition, the following strange fact is a theorem:

      (not (equal (* x x) 2))

  That is, we can prove that the square root of 2 is not rational and
  hence not in ACL2.

  (Maybe explore ACL2 arithmetic?  You won't need ACL2 arithmetic
  libraries to do the problems here.  But that is good because there
  is probably not an area of mathematics that the typical computer
  science student knows better than arithmetic.  Furthermore, you
  likely know much more about arithmetic than ACL2 does when it is
  first fired up.  Its performance can be improved by including
  ``certified books'' of definitions and theorems about arithmetic.
  The ACL2 Community Books Repository [4] contains thousands of books
  created by the community.  To load a book into an ACL2 session the
  command <<[47m[include-book][0m>> is used.  But there are many kinds of
  arithmetic books to choose from depending on what sort of
  operations are involved in your conjectures.  You might explore
  books on elementary <<[arithmetic]>> including some number theory
  books, or books on the arithmetic of <<[bit-vectors]>> (which deal
  with concepts like shifting or bitwise logical operations on
  number), or floating point books (see <<[rtl]>>; these are useful
  for verifying implementations of floating point operations) or a
  book on the <<[gl]>> utility (which provides a bit-blaster for
  finite arithmetic), or <<[algebra]>> books (e.g., properties of
  rings and fields), to name a few.)

  Next: Inadequacies of Structural Recursion (see
  [R-AND-I-INADEQUACIES-OF-STRUCTURAL-RECURSION]) (or Table of
  Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-ANNOTATED-BIBLIOGRAPHY
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Annotated Bibliography


Annotated Bibliography

  The following resources are useful for understanding the ACL2 logic
  and theorem prover, as well as its relation to both the earlier
  Nqthm logic and the Common Lisp programming language.  These
  resources are not necessary for you to do the exercises in these
  notes.  But if you are considering learning how to use the ACL2 or
  just wondering why anyone would bother, you might browse this
  annotated bibliography.

    * [0] R. S. Boyer and J S. Moore.
      [3mA Computational Logic Handbook[0m.
      Academic Press, London, 1997 (Second Edition).
      See [3m{https://www.cs.utexas.edu/users/boyer/ftp/nqthm/ |
      https://www.cs.utexas.edu/users/boyer/ftp/nqthm/}[0m
      for source code and regression suite
      This book is the user's manual for the Boyer-Moore theorem prover,
      Nqthm, of the 1980s.  The ACL2 project started in 1989, when
      Boyer and Moore set themselves the goal of re-implementing
      Nqthm so that it supported an efficient, functional
      (applicative) subset of Common Lisp and was coded in that same
      subset.  (They almost succeeded but had to use imperative code
      to implement functional versions of some utilities.)  So this
      reference, [0], describes the precursor of ACL2.  This book is
      the second edition of the Nqthm manual which was first
      published in 1988.  The url above contains the Nqthm source
      code and input and output files for the prover.  Most of these
      files were developed by the Nqthm user community.  The files
      include many proofs of classic list-processing and elementary
      number theory theorems but also proofs of Goedel's
      incompleteness theorem, Gauss's law of quadratic reciprocity,
      the Paris-Harrington Ramsey theorem, and the ``verified stack''
      of Computational Logic, Inc.  The verified stack, first
      reported in 1989 and then ported to a verified fabricated
      microprocessor in 1992, consisted of a gate-level
      implementation of a microprocessor, an assembler, linker, and
      loader, a compiler, an operating system, and some applications,
      all of which were verified with Nqthm to ``stack'' so that a
      theorem proved about an application written in one of two high
      level languages and proved correct with respect to that
      high-level semantics runs correctly on the microprocessor.
      These results are only briefly mentioned in [0] but that book
      does contain citations that describe them in detail.  Further
      development of Nqthm was halted because Nqthm users were
      building formal models that were so big they strained the
      capacity of the prover and were too slow to run as simulators
      for the modeled systems.  For example, when the ACL2 project
      was getting started, a student of Boyer was formalizing the
      Motorola 68020 microprocessor with the goal of verifying the
      Berkeley C String Library.  (That Nqthm project was completed
      successfully in 1993 and the files are available at the url
      above.)

    * [1] M. Kaufmann, P. Manolios, and J S. Moore, editors.
      [3mComputer-Aided Reasoning: ACL2 Case Studies[0m.
      Kluwer Academic Press, Boston, MA., 2000.
      See
      [3m{https://www.cs.utexas.edu/users/moore/publications/acl2-books/acs/index.html
      |
      https://www.cs.utexas.edu/users/moore/publications/acl2-books/acs/index.html}[0m.
      This book is a collection of papers by ACL2 users, assembled in
      2000, describing, in a textbook-like style. applications of
      ACL2.  It contains examples from graph theory, calculus, model
      checking, language simulators, microprocessor design including
      hardware description languages, floating-point implementations,
      compiler verification, and other topics.  While the Kluwer
      hardback edition of the book is out of print, the url above
      includes instructions for obtaining a paperback copy (for which
      the authors of [1] and [2] hold the copyright).

    * [2] M. Kaufmann, P. Manolios, and J S. Moore.
      [3mComputer-Aided Reasoning: An Approach[0m.
      Kluwer Academic Press, Boston, MA., 2000.
      
      [3m{https://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html
      |
      https://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html}[0m.
      This book is essentially a textbook for students wishing to learn
      how to use the ACL2 system.  It starts with a description of
      the ACL2 programming language, then formalizes the logic with
      axioms and rules of inference, and then discusses how to prove
      theorems with the system.  The book includes exercises.  While
      the Kluwer hardback edition of the book is out of print, the
      url above includes instructions for obtaining a paperback copy
      (for which the authors of [1] and [2] hold the copyright).

    * [3] M. Kaufmann and J S. Moore.
      A precise description of the ACL2 logic.
      In [3m
      {https://www.cs.utexas.edu/users/moore/publications/km97a.pdf |
      https://www.cs.utexas.edu/users/moore/publications/km97a.pdf}[0m
      Dept. of Computer Science, University of Texas at Austin,
      1997.
      The title says it all.  The ACL2 logic is a first-order logic of
      total recursive functions providing mathematical induction and
      several extension principles including symbol package
      definition and recursive function definition.  The logic is a
      formalization of an extension of a functional subset of Common
      Lisp.  This paper describes the logic in detail, more in the
      style of a logic book than the style used in these notes.  The
      paper also explains the connection between theorems in the
      logic and evaluation in Common Lisp, which very roughly
      speaking is that, given enough time and computing resources,
      any instance of a guard-verified (aka a ``gold'' theorem in the
      terminology of this 1997 paper) will compute to non-[47mnil[0m in
      Common Lisp.  (Maybe explore <<[47m[verify-guards][0m>>?)

    * [4] M. Kaufmann and J S. Moore.
      The ACL2 home page.
      [3m{http://www.cs.utexas.edu/users/moore/acl2/ |
      http://www.cs.utexas.edu/users/moore/acl2/}[0m
      Dept. of Computer Science, University of Texas at Austin,
      2022.
      This web page contains the latest release of the ACL2 system in
      Common Lisp source code form.  The system is largely
      implemented in the subset of Common Lisp the prover supports.
      ACL2 is distributed without fee under a 3-clause BSD license.
      A new release is currently made about once per year and the web
      page also contains links to all past releases going back to
      1996.  The home page includes instructions for installing any
      of several Common Lisp implementations and instructions for
      downloading and building ACL2.  The web page contains the
      online user's manual and instructions for how to download the
      regression suite from {the ACL2 GitHub repository |
      https://github.com/acl2/acl2}.  The regression suite, called
      the ACL2 <<[Community-Books]>>, contains thousands of verified
      files created by the ACL2 user community containing definitions
      and theorems.  If you scan down to the [31;1mSubtopics[0m section of the
      <<top>> node of the manual you will find a list of many topics
      for which certified <<[books]>> are available.  To take just
      one example from that top-level list of Subtopics, scroll down
      to Hardware Verification.  In that Subtopic you find
      directories dealing with symbolic simulation, register transfer
      logic (including tools for reasoning about floating point
      implementations), a Verilog translator, an x86 ISA model, and
      many other topics.  There are many other nodes besides Hardware
      Verification.  In fact, the tree of books listed among the
      Subtopics is simply too big and too rapidly changing to try to
      summarize here.  We encourage you to explore, or ask
      <<[ACL2-help]>> about resources (if any) for a particular
      topic.

    * [5] P. Manolios and D. Vroon.
      Ordinal arithmetic in acl2.
      In [3mACL2 Workshop 2003[0m, Boulder, Colorado, July 2003.
      {http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/ |
      http://www.cs.utexas.edu/users/moore/acl2/workshop-2003/}.
      The termination of recursive functions in ACL2 and the induction
      principle are both based on the ordinals and the
      well-foundedness of ordinal ``less than''.  The description of
      ACL2 in [2] above includes a formalization of the ordinals up
      to \\epsilon_0 (``epsilon naught'') represented in ACL2 with
      conses and natural numbers based on a version of Cantor Normal
      Form.  That representation was superseded in 2004 by the
      representation described in this paper, which implements a
      slightly different version of the normal form that is
      exponentially more efficient.  The paper also describes
      algorithms for manipulating ordinals in this representation.

    * [6] K. Pitman (editor).
      [3mCommon Lisp Hyper Spec[0m.
      LispWorks, Ltd, 1996.
      {http://www.lispworks.com/documentation/HyperSpec/Front/ |
      http://www.lispworks.com/documentation/HyperSpec/Front/}.
      This is an online hypertext presentation of the Common Lisp
      specification as described in [7].

    * [7] G. L. Steele, Jr.
      [3mCommon Lisp The Language, Second Edition[0m.
      Digital Press, 30 North Avenue, Burlington, MA.  01803, 1990.
      This is the definitive specification of Common Lisp.  ACL2 only
      formalizes a small subset of the language described by Steele.
      But ACL2's documentation of some primitives refers to Steele's
      descriptions.  By the way, we do not recommend the ACL2
      documentation as a way to learn to how to program in full
      Common Lisp.  Indeed, we don't recommend [6] or [7] for that
      purpose either.  Many good introductions to Common Lisp are
      available via the web.  There are many implementations of
      Common Lisp available and the installation instructions on the
      {ACL2 home page | http://www.cs.utexas.edu/users/moore/acl2/}
      list several.

    * [8] W. A. Hunt, Jr., M. Kaufmann, J S. Moore and A. Slobodova.
      Industrial Hardware and Software Verification with ACL2.
      In [3mVerified Trustworthy Software Systems[0m, P. Gardner, P.
      O'Hearn, M. Gordon,
      G. Morrisett and F. B. Schneider, Phil. Trans. R. Soc. A,
      [31;1m375[0m, The Royal Society,
      ISSN 1364-503X, DOI 10.1098/rsta.2015.0399 (Article Number
      20150399), 2017.
      The ACL2 system has seen sustained industrial use since the
      mid-1990s. Companies that have used ACL2 regularly include AMD,
      Centaur Technology, IBM, Intel, Kestrel Institute,
      Motorola/Freescale, Oracle and Collins (formerly Rockwell
      Collins).  This paper describes how ACL2 came to be used in
      industry, what it is used for, and how it is used.  The paper
      highlights ACL2's use in the microprocessor industry,
      specifically by Centaur Technology on modules in their x86
      microprocessors.  The paper was written in 2017.  Since then
      the formal verification team at Centaur Technology has moved to
      Intel, where ACL2 is used in the same way today (2022).

Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS])")
 (R-AND-I-ARITHMETIC
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Arithmetic

  We will next discuss arithmetic, in two steps.  First, we'll
  challenge you to use what we have already got to define ``natural
  numbers'' (non-negative integers) and the elementary operations on
  them.  This is called ``Peano'' arithmetic after the 19th century
  Italian mathematician Giuseppe Peano who first wrote down formal
  axioms describing the natural numbers.

  After you've explored the foundations of arithmetic, we'll talk about
  briefly about the more familiar arithmetic of integers and
  rationals.

  Next: Peano Arithmetic (see [R-AND-I-PEANO-ARITHMETIC]) (or Table of
  Contents (see [R-AND-I-TABLE-OF-CONTENTS]))


Subtopics

  [R-and-i-peano-arithmetic]
      Recursion and Induction: Peano Arithmetic

  [R-and-i-ACL2-arithmetic]
      Recursion and Induction: ACL2 Arithmetic")
 (R-AND-I-AXIOMS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Axioms

  A formal mathematical theory is given by a formal syntax for
  [3mformulas[0m, a set of formulas designated as [3maxioms[0m, and some formula
  manipulation [3mrules of inference[0m that allow one to derive [3mnew[0m
  formulas from [3mold[0m ones.  A [3mproof[0m  of a formula [3mp[0m  is a derivation
  of [3mp[0m  from the given axioms using the given rules of inference.  If
  a formula can be proved, it is said to be a [3mtheorem[0m.  Formulas are
  given [3msemantics[0m similar to those described for terms.  Given an
  [3massignment[0m of values to variable symbols and an interpretation of
  the function symbols, every formula is given a truthvalue by the
  semantics.  Given an interpretation, a formula is [3mvalid[0m if it is
  given the value true under every possible assignment to the
  variable symbols.  A [3mmodel[0m of a theory is an interpretation that
  makes all the axioms valid.  Provided the rules of inference are
  validity preserving, every theorem is valid, i.e., [3malways true[0m.

  We assume you know all that, and won't go into it further.  The
  whole point of a practical formal theory is to use proof to
  determine truth: one way to determine if a formula is true is to
  prove it.

  If [3m\\alpha[0m  and [3m\\beta[0m  are terms, then [3m\\alpha[0m  = [3m\\beta[0m  is a [3mformula[0m.
  If [3mp[0m  and [3mq[0m  are formulas, then each of the following is a formula:

    * [3mp[0m --> [3mq[0m

    * [3mp[0m & [3mq[0m

    * [3mp[0m \\/ [3mq[0m

    * ~[3mp[0m

    * [3mp[0m <-> [3mq[0m.

  If [3m\\alpha[0m  and [3m\\beta[0m  are terms, then [3m\\alpha[0m != [3m\\beta[0m  is just an
  abbreviation for the formula ~([3m\\alpha[0m  = [3m\\beta[0m).

  We extend the notation [3mterm[0m/[3m\\sigma[0m  in the obvious way so that we
  can apply substitution [3m\\sigma[0m  to formulas, replacing all the
  variables bound by [3m\\sigma[0m  in all the terms of the formula.

  The axioms we will use for the initial part of our study are given
  below.  Note that Axioms 1 and 8 are actually axiom schemas, i.e.,
  they describe an infinite number of axioms.

      [31;1mAxiom[0m	|  [31;1m1.[0m	|  [47m'[0m[3m\\alpha[0m  != [47m'[0m[3m\\beta[0m,	|
      	|  	|  where [3m\\alpha[0m  and [3m\\beta[0m  are distinct integers, characters, strings,
      or symbols	|
      [31;1mAxiom[0m	|  [31;1m2.[0m	|  [47mx[0m != [47mnil[0m --> [47m(if x y z)[0m = [47my[0m	|
      [31;1mAxiom[0m	|  [31;1m3.[0m	|  [47mx[0m = [47mnil[0m --> [47m(if x y z)[0m = [47mz[0m	|
      [31;1mAxiom[0m	|  [31;1m4.[0m	|  [47m(equal x y)[0m = [47mnil[0m \\/ [47m(equal x y)[0m = [47mt[0m	|
      [31;1mAxiom[0m	|  [31;1m5.[0m	|  [47mx[0m = [47my[0m <-> [47m(equal x y)[0m = [47mt[0m	|
      [31;1mAxiom[0m	|  [31;1m6.[0m	|  [47m(consp x)[0m = [47mnil[0m \\/ [47m(consp x)[0m = [47mt[0m	|
      [31;1mAxiom[0m	|  [31;1m7.[0m	|  [47m(consp (cons x y))[0m = [47mt[0m	|
      [31;1mAxiom[0m	|  [31;1m8.[0m	|  [47m(consp '[0m[3m\\alpha[0m[47m)[0m = [47mnil[0m,	|
      	|  	|  where [3m\\alpha[0m  is an integer, character, string, or symbol	|
      [31;1mAxiom[0m	|  [31;1m9.[0m	|  [47m(car (cons x y))[0m = [47mx[0m	|
      [31;1mAxiom[0m	|  [31;1m10.[0m	|  [47m(cdr (cons x y))[0m = [47my[0m	|
      [31;1mAxiom[0m	|  [31;1m11.[0m	|  [47m(consp x)[0m = [47mt[0m --> [47m(cons (car x) (cdr x))[0m = [47mx[0m	|
      [31;1mAxiom[0m	|  [31;1m12.[0m	|  [47m(consp x)[0m = [47mnil[0m --> [47m(car x)[0m = [47mnil[0m	|
      [31;1mAxiom[0m	|  [31;1m13.[0m	|  [47m(consp x)[0m = [47mnil[0m --> [47m(cdr x)[0m = [47mnil[0m	|

  One axiom described by Axiom (schema) 1 is [47m't[0m != [47m'nil[0m.  Others are
  [47m'nil[0m != [47m'3[0m and [47m'\"Hello\"[0m != [47m'Hello[0m.  We refer to all of these as
  Axiom 1.

  One axiom described by Axiom (schema) 8 is [47m(consp 'nil)[0m = [47mnil[0m.
  Others are [47m(consp '3)[0m = [47mnil[0m and [47m(consp 'Hello)[0m = [47mnil[0m.  We refer to
  all of these as Axiom 8.

  Note that if [3m\\phi[0m  is an axiom or theorem and [3m\\sigma[0m  is a
  substitution, then [3m\\phi[0m/[3m\\sigma[0m  is a theorem, by the Rule of
  Instantiation.

  We assume you are familiar with the rules of inference for
  propositional calculus and for equality.  For example, we take for
  granted that you can recognize simple propositional tautologies,
  reason by cases, and substitute equals for equals.

  For example, we show a theorem below that you should be able to
  prove, using nothing but your knowledge of propositional calculus
  and equality (and Axiom 1).

  The proof shown below uses the Deduction Law of propositional
  calculus: we can prove [3mp[0m --> [3mq[0m  by assuming [3mp[0m  as a ``Given'' and
  deriving [3mq[0m.

      [31;1mTheorem.[0m
      (consp x) = t & x = (car z) --> (consp (car z)) != nil

      [31;1mProof.[0m

      1.	|  	|  [47m(consp x) = t[0m	|  	|  [3m{Given}[0m	|
      2.	|  	|  [47mx = (car z)[0m	|  	|  [3m{Given}[0m	|
      3.	|  	|  [47mt != nil[0m	|  	|  [3m{Axiom 1}[0m	|
      4.	|  	|  [47m(consp x) != nil[0m	|  	|  [3m{Equality Substitution, line 1 into line 3}[0m	|
      5.	|  	|  [47m(consp (car z)) != nil[0m	|  	|  [3m{Equality Substitution, line 2 into line 4}[0m	|
      	|  	|  Q.E.D.	|  	|  	|

  We will not write proofs in this style.  We will simply say that the
  formula is a theorem ``by propositional calculus, equality, and
  Axiom 1.''

  Recall that each function definition adds an axiom.  The definition

      (defun tree-copy (x)
        (if (consp x)
            (cons (tree-copy (car x))
                  (tree-copy (cdr x)))
            x))

  adds the axiom

      [31;1mAxiom[0m tree-copy
      (tree-copy x)
      =
      (if (consp x)
          (cons (tree-copy (car x))
                (tree-copy (cdr x)))
          x)

  Thus, by the Rule of Instantiation

      [31;1mTheorem.[0m
      (tree-copy (cons a b))
      =
      (if (consp (cons a b))
          (cons (tree-copy (car (cons a b)))
                (tree-copy (cdr (cons a b))))
          (cons a b))

  Next: Terms as Formulas (see [R-AND-I-TERMS-AS-FORMULAS]) (or Table
  of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-CHARACTERS
  (R-AND-I-DATA-TYPES)
  "Recursion and Induction: Characters

  We will not use character objects in this document.  In case you
  come across such an object in your exploration of ACL2, some
  characters are [47m#\\a[0m, [47m#\\A[0m, [47m#\\Newline[0m and [47m#\\Space[0m.  It is actually
  possible in ACL2 to ``construct'' and ``deconstruct'' characters in
  terms of naturals.  For example, one can construct [47m#\\A[0m from [47m65[0m, the
  ASCII code for uppercase `A'.

  (Maybe explore <<[characters]>>?)

  Next: Strings (see [R-AND-I-STRINGS]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-DATA-TYPES
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Data Types

  ACL2 provides five data types: numbers, characters, strings, symbols,
  and ordered pairs.

  Next: Numbers (see [R-AND-I-NUMBERS]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))


Subtopics

  [R-and-i-numbers]
      Recursion and Induction: Numbers

  [R-and-i-characters]
      Recursion and Induction: Characters

  [R-and-i-strings]
      Recursion and Induction: Strings

  [R-and-i-symbols]
      Recursion and Induction: Symbols

  [R-and-i-pairs]
      Recursion and Induction: Pairs

  [R-and-i-identity]
      Recursion and Induction: Identity

  [R-and-i-data-types-exercises]
      Recursion and Induction: Data Types Exercises")
 (R-AND-I-DATA-TYPES-EXERCISES
  (R-AND-I-DATA-TYPES)
  "Recursion and Induction: Data Types Exercises

  [31;1mProblem 1.
  [0m Each of the utterances below is supposed to be a single object.  Say
  whether it is a number, string, symbol, pair, or ill-formed (i.e.,
  does not represent a single object in our language).

   1. [47mMonday[0m

   2. [47m[3m\\pi[0m[47m[0m

   3. [47mHelloWorld![0m

   4. [47m--1[0m

   5. [47m-1[0m

   6. [47m*PI*[0m

   7. [47m31415x10**-4[0m

   8. [47m(A . B . C)[0m

   9. [47mHello World![0m

  10. [47mif[0m

  11. [47minvokevirtual[0m

  12. [47m((1) . (2))[0m

  13. [47m<=[0m

  14. [47m((A . 1) (B . 2) (C . 3))[0m

  15. [47mHello_World![0m

  16. [47m+[0m

  17. [47mlo-part[0m

  18. [47m31415926535897932384626433832795028841971693993751058209749445923[0m

  19. [47m(1 . (2 . 3))[0m

  20. [47m(1 . 2 3)[0m

  21. [47m\"Hello World!\" [0m

  22. [47m((1) (2) . 3)[0m

  23. [47m()[0m

  [31;1mProblem 2.
  [0m Group the constants below into equivalence classes.  That is, some
  items below are equal to others even though they are displayed
  differently; group equal constants together.

   1. [47m(1 . (2 3))[0m

   2. [47m(nil . (nil nil))[0m

   3. [47m((nil nil) . nil)[0m

   4. [47m(1 (2 . 3) 4)[0m

   5. [47m(nil nil)[0m

   6. [47m(1 (2 . 3) . (4 . ()))[0m

   7. [47m(HelloWorld !)[0m

   8. [47m(1 (2 3 . ()) 4)[0m

   9. [47m((A . t) (B . nil)(C . nil))[0m

  10. [47m(()())[0m

  11. [47m(1 2 3)[0m

  12. [47m(() () . nil)[0m

  13. [47m(A B C)[0m

  14. [47m(a . (b . (c)))[0m

  15. [47m(HELLO WORLD !)[0m

  16. [47m((a . t) (b) . ((c)))[0m

  Next: Terms (see [R-AND-I-TERMS]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-DEFINITIONAL-PRINCIPLE
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: The Definitional Principle

  Below we give a new definitional principle that subsumes the
  previously given Principle of Structural Recursion.

  The definition

  [47m(defun[0m [3mf[0m  [47m([0m[3mv_1[0m ... [3mv_n[0m[47m)[0m [3m\\beta[0m[47m)[0m

  is [3madmissible[0m  if and only if

   1. [3mf[0m  is a new function symbol,

   2. the [3mv_i[0m  are distinct variable symbols,

   3. [3m\\beta[0m  is a term that mentions no variable other than the [3mv_i[0m  and
      calls no new function symbol other than (possibly) [3mf[0m, and

   4. there is a term [3mm[0m  (called the [3mmeasure[0m) such that the following are
      theorems:

        * [3mOrdinal Conjecture[0m

          [47m(o-p[0m [3mm[0m[47m)[0m

        * [3mMeasure Conjecture(s)[0m  For each recursive call of [47m([0m[3mf a_1[0m ... [3ma_n[0m[47m)[0m in
          [3m\\beta[0m  and the conjunction [3mq[0m  of tests ruling it,

          [47m(implies[0m [3mq[0m  [47m(o<[0m [3mm[0m/[3m\\sigma[0m  [3mm[0m[47m))[0m

          where [3m\\sigma[0m  is [47m{[0m[3mv_1[0m<--[3ma_1[0m,  ... , [3mv_n[0m<--[3ma_n[0m[47m}[0m.

  If that definition is admissible, then it adds the axiom:

  [47m([0m[3mf[0m  [3mv_1[0m ... [3mv_n[0m[47m) = [0m[3m\\beta[0m.

  In each of the problems below, admit the proposed definition, i.e.,
  identify the measure and prove the required theorems.

  (Maybe explore <<[47m[defun][0m>>?  Note in particular how the user can
  explicitly specify the measure and well-founded relation alleged to
  decrease.  When specified, the system will attempt to prove it
  decreases as per the Definitional Principle.  If no measure is
  specified by the user, the system attempts to find an argument
  whose [47m[ACL2-count][0m decreases according to [47m[o<][0m.)

  [31;1mProblem 95.
  [0m

      (defun tree-copy (x)
        (if (atom x)
            x
            (cons (tree-copy (first x))
                  (tree-copy (rest x)))))

  [31;1mProblem 96.
  [0m

      (defun ack (x y)
        (if (zp x)
            1
            (if (zp y)
                (if (equal x 1) 2 (+ x 2))
                (ack (ack (- x 1) y) (- y 1)))))

  [31;1mProblem 97.
  [0m Recursion like that in [47mack[0m allows us to define functions that cannot
  be defined if we are limited to ``primitive recursion'' where a
  given argument is decremented in every recursive call.  That is,
  the new definitional principle is strictly more powerful than the
  old one.  This can be formalized and proved within our system
  (after we extend the principle of induction below).  If you are
  inclined towards metamathematics, feel free to pursue the
  formalization and ACL2 proof of this.  The existence of
  non-primitive recursive functions, dating from 1928, by Wilhelm
  Ackermann, a student of David Hilbert, was one of the important
  milestones in our understanding of the power and limitations of
  formal mathematics culminating in Goedel's results of the early
  1930s.

  [31;1mProblem 98.
  [0m

      (defun f1 (i j)
        (if (and (natp i)
                 (natp j)
                 (< i j))
            (f1 (+ 1 i) j)
            1))

  [31;1mProblem 99.
  [0m

      (defun f2 (x)
        (if (equal x nil)
            2
            (and (f2 (car x))
                 (f2 (cdr x)))))

  [31;1mProblem 100.
  [0m

      (defun f3 (x y)
        (if (and (endp x)
                 (endp y))
            3
            (f3 (cdr x) (cdr y))))

  [31;1mProblem 101.
  [0m Suppose [47mp[0m, [47mm[0m, [47mup[0m, and [47mdn[0m (``down'') are undefined functions.
  Suppose however that you know this about [47mp[0m, [47mm[0m, and [47mdn[0m:

      [31;1mTheorem[0m dn-spec
      (and (o-p (m x))
           (implies (p x)
                    (o< (m (dn x)) (m x))))

  Then admit

      (defun f4 (x y q)
        (if (p x)
            (if q
                (f4 y (dn x) (not q))
                (f4 y (up x) (not q)))
            4))

  Note that [47mf4[0m is swapping its arguments.  Thus, if [47mq[0m starts at [47mt[0m,
  say, then in successive calls the first argument is [47mx[0m, [47my[0m, [47m(dn x)[0m,
  [47m(up y)[0m, [47m(dn (dn x))[0m, [47m(up (up y))[0m, etc.  I thank Anand Padmanaban
  for helping me think of and solve this problem.

  Next: The Induction Principle (see [R-AND-I-INDUCTION-PRINCIPLE]) (or
  Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-DEFINITIONS-REVISITED
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Definitions Revisited

  [31;1mProblem 27.
  [0m Suppose we define

      (defun f (x) 1)

  and then prove some theorems and then ``redefine'' [47mf[0m with

      (defun f (x) 2)

  Now prove that [47m(equal 'June' 'July)[0m, using the theorems that [47m(equal
  (f x) 1)[0m, proved before redefining [47mf[0m, and [47m(equal (f x) 2)[0m, proved
  after.

  Flesh out your argument using axioms presented earlier (see
  [r-and-i-axioms] and see [r-and-i-definitions-revisited]).

  A consequence is that since anything provable is valid, then the
  formula [47m(equal 'June 'July) != nil[0m is true, hence [47m'June[0m = [47m'July[0m, a
  contradiction!  In the following Problems we explore further such
  consequences of permitting ``bad'' definitions.

  [31;1mProblem 28.
  [0m Suppose we define

      (defun f (x) (cons x y))

  Prove [47m(equal 1 2)[0m.  (Remark.  The definition [47mf[0m in this problem has
  nothing to do with the definition of [47mf[0m in the previous problem!  We
  tend to ``re-use'' function names like [47mf[0m, [47mg[0m and [47mh[0m from time to time
  simply to avoid inventing new names.)

  [31;1mProblem 29.
  [0m Suppose we define

      (defun f (x) (not (f x)))

  Prove [47m(equal t nil)[0m.

  These problems should disturb you!  We often think of
  ``definitions'' as being logically innocuous, allowing us to
  abbreviate complicated expressions.  And we think of proof as a way
  to determine truth.  So it is disturbing if after making a
  ``definition'' we are suddenly able to prove things we know aren't
  true, like that [47mJune[0m is [47mJuly[0m or that [47mt[0m is [47mnil[0m!  Something has gone
  terribly wrong.

  To prevent this kind of logical inconsistency, we impose some
  restrictions on our ability to introduce definitions.  The
  restrictions we'll impose will prevent us from defining many useful
  functions but guarantee that we don't ruin the logic with
  ``definitions'' like those shown above.  ACL2 is much more generous
  in its restrictions but they are spiritually similar: both here and
  in ACL2 the restrictions on definitions will guarantee that every
  defined function terminates.  We do not explain in this document
  why termination is enough to avoid inconsistencies.

  One way to make sure a function terminates is to insist that there
  is an argument that is being [47mcar[0m'd and/or [47mcdr[0m'd at least once every
  time the function recurs and that before it recurs the definition
  tests that the argument is a [47mcons[0m-pair.  For example, [47m(defun f (x)
  (not (f x)))[0m is disallowed by this restriction, and so is [47m(defun f
  (x) (not (f (cdr x))))[0m.  But

      (defun f (x)
        (if (consp x)
            (and (not (f (car x)))
                 (not (f (cdr (cdr x)))))
            t))

  is allowed because [47mx[0m is [47mcar[0m'd and/or [47mcdr[0m'd in every recursion and
  the function tests [47m(consp x)[0m before recurring.  We say [47m(consp x)[0m
  ``rules'' the two recursive calls above.

  So we have to define the notions of a ``[47mcar[0m/[47mcdr[0m'' nest and what
  terms ``rule'' the recursive calls.

  A [3mcar/cdr nest around[0m  [3mv[0m  is [47m(car[0m [3mv[0m[47m)[0m, [47m(cdr[0m [3mv[0m[47m)[0m, or a [47mcar[0m/[47mcdr[0m nest
  around [47m(car[0m [3mv[0m[47m)[0m or [47m(cdr[0m [3mv[0m[47m)[0m.  Thus, [47m(car (cdr (car x)))[0m is a [47mcar[0m/[47mcdr[0m
  nest around [47mx[0m.

  The idea in this next definition is to take a term [3m\\beta[0m  and a
  particular occurrence [3mr[0m  of some subterm in [3m\\beta[0m  and define the
  set of tests that rule [3mr[0m.  Then, if you have a function definition
  like [47m(defun[0m [3mf[0m  [47m([0m[3mv_1[0m ... [3mv_k[0m[47m)[0m [3m\\beta[0m[47m)[0m you can let [3mr[0m  be a particular
  recursive call of [3mf[0m  in [3m\\beta[0m  and then determine which tests rule
  that call.

  The [3mrulers[0m  of an occurrence of a term [3mr[0m  in another term [3m\\beta[0m  is
  the set defined as follows:

   1. if [3m\\beta[0m  is [47m(if[0m [3mp[0m [3mx[0m [3my[0m[47m)[0m and [3mr[0m  is in [3mx[0m, then the rulers of [3mr[0m  in
      [3m\\beta[0m  is the set obtained by adding [3mp[0m  to the set of rulers of
      [3mr[0m  in [3mx[0m;

   2. if [3m\\beta[0m  is [47m(if[0m [3mp[0m [3mx[0m [3my[0m[47m)[0m and [3mr[0m  is in [3my[0m, then the rulers of [3mr[0m  in
      [3m\\beta[0m  is the set obtained by adding [47m(NOT[0m [3mp[0m[47m)[0m to the set of
      rulers of [3mr[0m  in [3my[0m;

   3. otherwise, the rulers of [3mr[0m  in [3m\\beta[0m  is the empty set.

  Thus, in the term [47m(if a (if b (h c) (h d)) (g c))[0m, both [47ma[0m and [47mb[0m rule
  the first occurrence of [47mc[0m and the occurrence of [47m(h c)[0m.  In
  addition, [47ma[0m and [47m(not b)[0m rule the occurrences of [47md[0m and [47m(h d)[0m.
  Finally, [47m(not a)[0m rules the second occurrence of [47mc[0m and [47m(g c)[0m.

  Note that our definition of ``rulers'' does not include every test
  that has to be true in order to reach the occurrence in question.
  For example, [47mp[0m does not rule the occurrence of [47ma[0m in [47m(car (if p a
  b))[0m even though the only way evaluation can reach [47ma[0m is if [47mp[0m is
  true.  The rulers of the occurrence of [47ma[0m in that term is the empty
  set, because that term is not a call of [47mif[0m.  However, [47mp[0m does rule
  the occurrence of [47ma[0m in the equivalent term [47m(if p (car a) (car b))[0m.
  The reason we've defined rulers this way has to do with heuristics
  in the ACL2 theorem prover.

  [31;1mPrinciple of Structural Recursion:[0m A definition, [47m(defun[0m [3mf[0m  [47m([0m[3mv_1[0m ...
  [3mv_n[0m[47m)[0m [3m\\beta[0m[47m)[0m will be allowed (for now) only if it satisfies these
  four restrictions:

   1. The symbol being defined, [3mf[0m, must be ``new,'' i.e., not already in
      use as a function symbol in any axiom.

   2. The formal variables, [3mv_1[0m, ... , [3mv_n[0m, must be distinct variable
      symbols.

   3. The body, [3m\\beta[0m, must be a term, it must use no new function symbol
      other than (possibly) [3mf[0m, and the only variable symbols in it
      are among the formals.

   4. There is an [3mi[0m  such that [47m(consp[0m [3mv_i[0m[47m)[0m rules every recursive call of [3mf[0m
      in [3m\\beta[0m  and for every recursive call ([3mf[0m  [3ma_1[0m ... [3ma_n[0m) in
      [3m\\beta[0m, [3ma_i[0m  is a [47mcar[0m/[47mcdr[0m nest around [3mv_i[0m.  We call [3mv_i[0m a
      [3mmeasured formal[0m.

  An acceptable definition adds the axiom [47m([0m[3mf[0m  [3mv_1[0m   ...  [3mv_n[0m[47m) = [0m[3m\\beta[0m.

  (Maybe explore <<[47m[defun][0m>>?  Be advised, however, that ACL2's
  Definitional Principle does not insist on the last condition above,
  about there being a [47mcar[0m/[47mcdr[0m nest in a certain argument of every
  recursive call.  Instead it insists that ``some measure of the
  arguments decreases'' in every recursive call.  We'll make that
  clearer later.  But ACL2's Definitional Principle allows all the
  definitions described above.)

  [31;1mProblem 30.
  [0m Explain why these restrictions rule out the spurious definitions of
  [47mf[0m in the problems above.

  [31;1mProblem 31.
  [0m Is the following definition allowed under the above restrictions?

      (defun f (x)
        (if (consp x)
            (if (consp (cdr x))
                (f (cdr (cdr x)))
                nil)
            t))

  [31;1mProblem 32.
  [0m Is the following definition allowed?

      (defun f (x y)
        (if (consp x)
            (f (cons nil x) (cdr y))
            y))

  [31;1mProblem 33.
  [0m Is the following definition allowed?

      (defun f (x y)
        (if (consp x)
            (f (cons nil y) (cdr x))
            y))

  [31;1mProblem 34.
  [0m Is the following definition allowed?

      (defun f (x)
        (if (not (consp x))
            x
            (f (cdr (cdr x)))))

  [31;1mProblem 35.
  [0m Is the following sequence of definitions allowed?

      (defun endp (x) (not (consp x)))

      (defun f (x)
        (if (endp x)
            nil
            (cons nil (f (cdr x)))))

  [31;1mProblem 36.
  [0m Is the following definition allowed?

      (defun f (x y)
        (if (consp x)
            (f (cdr x) (cons nil y))
            y))

  [31;1mProblem 37.
  [0m Is the following definition allowed?

      (defun f (x y)
        (if (consp x)
            (f (cdr x)
               (f (cdr x) y))
            y))

  [31;1mProblem 38.
  [0m Is the following sequence of definitions allowed?

      (defun f (x)
        (if (consp x)
            (g (cdr x))
            x))

      (defun g (x)
        (if (consp x)
            (f (cdr x))
            x))

  Next: Structural Induction (see [R-AND-I-STRUCTURAL-INDUCTION]) (or
  Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-FUNCTION-DEFINITIONS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Function Definitions

  To define a function, we use the form [47m(defun[0m [3mf[0m  ([3mv_1[0m  ...  [3mv_n[0m)
  [3m\\beta[0m[47m)[0m where [3mf[0m  is the function symbol being defined, the [3mv_i[0m  are
  the formal variables or simply [3mformals[0m, and [3m\\beta[0m  is the body of
  the function.

  Operationally, a definition means that to compute [47m([0m[3mf[0m  [3ma_1[0m   ...
  [3ma_n[0m[47m)[0m one can evaluate the actuals, [3ma_i[0m, bind the formals, [3mv_i[0m , to
  those values, and compute [3m\\beta[0m  instead.  Logically speaking, a
  definition adds the axiom that [47m([0m[3mf[0m  [3mv_1[0m   ...  [3mv_n[0m[47m)[0m is equal to
  [3m\\beta[0m.

  Here are the Lisp definitions of the standard propositional logic
  connectives:

      (defun not (p) (if p nil t))

      (defun and (p q) (if p q nil))

      (defun or (p q) (if p p q))

      (defun implies (p q) (if p (if q t nil) t))

      (defun iff (p q) (and (implies p q) (implies q p)))

  Note that in Lisp, [47mand[0m and [47mor[0m are not Boolean valued.  E.g., [47m(and t
  3)[0m and [47m(or nil 3)[0m both return [47m3[0m.  This is unimportant if they are
  only used propositionally, e.g., [47m(and t 3)[0m <-> [47m(and 3 t)[0m <-> [47mt[0m, if
  ``<->'' means [47miff[0m.  In Lisp, any non-nil value is propositionally
  equivalent to [47mt[0m.

  Here is a recursive definition that copies a [47mcons[0m-structure.

      (defun tree-copy (x)
        (if (consp x)
            (cons (tree-copy (car x))
                  (tree-copy (cdr x)))
            x))

  For example, the term [47m(tree-copy '((1 . 2) . 3))[0m has the value [47m((1 .
  2) . 3)[0m.

  (Maybe explore <<[47m[defun][0m>>?  Be advised, however, that ACL2's
  Definitional Principle imposes restrictions that may not make sense
  just yet.)

  In the exercises below you may wish to define auxiliary (``helper'')
  functions as part of your solutions.

  [31;1mProblem 8.
  [0m Define [47mapp[0m to concatenate two lists.  For example [47m(app '(1 2 3) '(4
  5 6))[0m evaluates to [47m(1 2 3 4 5 6)[0m.

  [31;1mProblem 9.
  [0m Define [47mrev[0m to reverse a list.  For example, [47m(rev '(1 2 3))[0m evaluates
  to [47m(3 2 1)[0m.

  [31;1mProblem 10.
  [0m Define [47mmapnil[0m to ``copy'' a list, replacing each element by [47mnil[0m.
  Thus, [47m(mapnil '(1 2 3))[0m evaluates to [47m(nil nil nil)[0m.

  [31;1mProblem 11.
  [0m The result of ``swapping'' the pair [47m([3mx[0m[47m  . [3my[0m[47m)[0m is the pair [47m([3my[0m[47m  . [3mx[0m[47m)[0m.
  Define [47mswap-tree[0m to swap every cons in a binary tree.  Thus,
  [47m(swap-tree '((1 . 2) . (3 . 4)))[0m evaluates to [47m((4 . 3) . (2 . 1))[0m.

  [31;1mProblem 12.
  [0m Define [47mmem[0m to take two arguments and determine if the first one
  occurs as an element of the second.  Thus, [47m(mem '2 '(1 2 3))[0m
  evaluates to [47mt[0m and [47m(mem '4 '(1 2 3))[0m evaluates to [47mnil[0m.

  [31;1mProblem 13.
  [0m Define the list analogue of subset, i.e., [47m(sub x y)[0m returns [47mt[0m or [47mnil[0m
  according to whether every element of [47mx[0m is an element of [47my[0m.

  [31;1mProblem 14.
  [0m Define [47mint[0m to take two lists and to return the list of elements that
  appear in both.  Thus [47m(int '(1 2 3 4) '(2 4 6))[0m evaluates to [47m(2 4)[0m.

  [31;1mProblem 15.
  [0m Define [47m(tip e x)[0m to determine whether [47me[0m occurs as a tip of the
  binary tree [47mx[0m.

  [31;1mProblem 16.
  [0m Define [47m(flatten x)[0m to make a list containing the tips of the binary
  tree [47mx[0m.  Thus, [47m(flatten '((1 . 2) . (3 . 4)))[0m evaluates to [47m(1 2 3
  4)[0m.

  [31;1mProblem 17.
  [0m Define [47mevenlen[0m to recognize lists of even length.  Thus, [47m(evenlen
  '(1 2 3))[0m evaluates to [47mnil[0m and [47m(evenlen '(1 2 3 4))[0m evaluates to [47mt[0m.

  Next: Axioms (see [R-AND-I-AXIOMS]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-IDENTITY
  (R-AND-I-DATA-TYPES)
  "Recursion and Induction: Identity

  Since a pair can typically be written down in several different
  ways, you might ask how can you tell whether one display is equal
  to another?  For example, how can you determine that [47m(1 . (2 . (3 .
  nil)))[0m is the same pair as [47m(1 2 3)[0m, which is also the same pair as
  [47m(1 . (2 3))[0m?

  One way is to write each constant in a canonical form.  If their
  canonical forms are different, the two constants are different.
  For integers, the standard canonical form is to use base 10 and to
  drop leading [47m0[0ms and ``+'' signs.  For symbols, it is to write
  everything in upper case.  For conses, the canonical form is to
  eschew the use of the three conventions noted in the previous
  section and to use dot notation exclusively.

  Next: Data Types Exercises (see [R-AND-I-DATA-TYPES-EXERCISES]) (or
  Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-INADEQUACIES-OF-STRUCTURAL-RECURSION
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Inadequacies of Structural Recursion

  Recall that to avoid logical contradictions introduced by ``bad''
  definitions, we imposed four restrictions.  The fourth restriction
  is very constraining: we can only recur on a [47mcar[0m/[47mcdr[0m component of
  some argument and must ensure that that argument satisfies [47mconsp[0m
  before the recursion.

  The intent of this restriction was to guarantee that the newly
  defined function terminates.  It is beyond the scope of these notes
  to explain why termination is linked to consistency, but the
  intuitive explanation is that if the recursion cannot go on forever
  then, for every combination of constants to which we apply the
  function, we could compute a value satisfying the definitional
  equation (given enough computational resources).  From this
  observation we can conclude there exists a mathematical function
  satisfying the definitional equation -- namely, the one that maps
  inputs to the computed outputs.  Thus, given a model of the theory
  before we added the definition, we could extend it to a model of
  the theory with the new definition added.  This establishes the
  consistency of the extended theory.  (Remark.  In fact, our
  definitions produce [3mconservative extensions[0m, which we will briefly
  discuss below.)  The problem with the current version of our fourth
  restriction is that it is too syntactic -- it insists, literally,
  on the use of [47mconsp[0m, [47mcar[0m, and [47mcdr[0m.  In the ACL2 definitional
  principle, the fourth restriction is less syntactic: it requires
  that we be able to [3mprove[0m  that the recursion terminates.  That is,
  when we propose a new definition, a conjecture is generated and if
  this conjecture can be proved as a theorem, then we know the
  function terminates.

  The basic idea of this conjecture is to establish that some measure
  of the function's arguments decreases in size as the function
  recurs, and this decreasing cannot go on forever.  If the size
  were, say, a natural number, then we would know the decreasing
  could not go on forever, because the arithmetic less-than relation,
  [47m<[0m, is [3mwell-founded[0m  on the natural numbers.  We discuss
  well-foundedness more in the next section.

  [31;1mProblem 82.
  [0m Define [47m(cc x)[0m to return the number of conses in [47mx[0m.  The name stands
  for ``cons count.''

  [31;1mProblem 83.
  [0m Prove that [47mcc[0m always returns a non-negative [47minteger[0m.

  [31;1mProblem 84.
  [0m If we define

      (defun atom (x) (not (consp x)))
      (defun first (x) (car x))
      (defun rest (x) (cdr x))

  then the following ``definition'' of [47mtree-copy[0m is logically
  equivalent to the acceptable version, but it is considered
  unacceptable by our syntactic fourth restriction:

      (defun tree-copy (x)
        (if (atom x)
            x
            (cons (tree-copy (first x))
                  (tree-copy (rest x)))))

  Write down a conjecture that captures the idea that the argument to
  [47mtree-copy[0m is getting smaller (as measured by [47mcc[0m) as the function
  recurs.

  [31;1mProblem 85.
  [0m Prove the conjecture above.  Note that since [47mcc[0m is a natural number,
  this proof establishes that [47mtree-copy[0m terminates on all objects.

  [31;1mProblem 86.
  [0m Define [47m(rm e x)[0m to return the result of removing the first
  occurrence (if any) of [47me[0m from [47mx[0m.  Thus, [47m(rm 3 '(1 2 3 4 3 2 1))[0m is
  [47m(1 2 4 3 2 1)[0m.

  [31;1mProblem 87.
  [0m Show that the following function terminates.

      (defun f23 (e x)
        (if (mem e x)
            (f23 e (rm e x))
            23))

  Note that no [47mcar[0m/[47mcdr[0m nest around [47mx[0m is equal to the result of [47m(rm 3
  '(1 2 3))[0m.  Thus, [47mf23[0m exhibits a kind of recursion we have not seen
  previously -- but we know it terminates.

  [31;1mProblem 88.
  [0m It is obvious that [47m(f23 e x)[0m always return [47m23[0m.  Can you prove that
  with our current logical machinery?

  The key to these termination proofs is that the less-than relation
  is well-founded on the natural numbers.  But consider this famous
  function, known as Ackermann's function,

      (defun ack (x y)
        (if (zp x)
            1
            (if (zp y)
                (if (equal x 1) 2 (+ x 2))
                (ack (ack (- x 1) y) (- y 1)))))

  Observe that [47mack[0m can generate some very large numbers.  For example,
  [47m(ack 4 3)[0m is [47m65536[0m.

  [31;1mProblem 89.
  [0m [47mAck[0m always terminates.  Why?  Don't feel compelled to give a formal
  proof, just an informal explanation.

  In the next three sections of this document we will discuss a
  well-founded relation far more powerful than less-than on the
  natural numbers.  We will then connect that well-foundedness
  machinery to a new version of the Definitional Principle, so that
  we can admit many interesting recursive functions, including [47mack[0m.
  We will also connect the well-foundedness machinery to a new
  version of the Induction Principle, so that we can prove that [47m(f23
  e x)[0m is [47m23[0m -- and far more interesting theorems.

  Next: The Ordinals (see [R-AND-I-ORDINALS]) (or Table of Contents
  (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-INDUCTION-PRINCIPLE
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: The Induction Principle

  The Induction Principle allows one to derive an arbitrary formula,
  [3m\\psi[0m, from

    * [3mBase Case[0m : [47m(implies (and (not[0m [3mq_1[0m[47m) ... (not[0m [3mq_k[0m[47m))[0m [3m\\psi[0m[47m)[0m, and

    * [3mInduction Step(s)[0m : For each 1<=[3mi[0m<=[3mk[0m,
      [47m(implies (and [0m[3mq_i[0m[47m [0m[3m\\psi[0m/[3m\\sigma_{i,1}[0m ... [3m\\psi[0m/[3m\\sigma_{i,h_i}[0m[47m)[0m
      [47m         [0m[3m\\psi[0m[47m)[0m,

  provided that for terms [3mm[0m, [3mq_1[0m,...[3mq_k[0m, and substitutions
  [3m\\sigma_{i,j}[0m  (1<=[3mi[0m<=[3mk[0m, 1<=[3mj[0m<=[3mh_i[0m), the following are theorems:

    * [3mOrdinal Conjecture[0m : [47m(o-p[0m [3mm[0m[47m)[0m, and

    * [3mMeasure Conjecture(s)[0m : For each 1<=[3mi[0m<=[3mk[0m and 1<=[3mj[0m<=[3mh_i[0m,
      [47m(implies [0m[3mq_i[0m[47m (o< [0m[3mm[0m/[3m\\sigma_{i,j}[0m  [3mm[0m[47m))[0m.

  Next: Relations Between Recursion and Induction (see
  [R-AND-I-RELATIONS-BETWEEN-RECURSION-AND-INDUCTION]) (or Table of
  Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-INTRODUCTION
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Introduction

  The language we will use is a subset of Lisp called ACL2.  ACL2,
  which stands for [3mA Computational Logic for Applicative Common Lisp[0m,
  is both a functional programming language based on Common Lisp and
  a first-order mathematical theory with induction.  There is a
  mechanical theorem prover for ACL2, but we do not discuss it here.
  A good way to learn to use that theorem prover is first to master
  the art of recursive definition and inductive proof.

  This course on Recursion and Induction uses a tiny fragment of full
  ACL2.  We describe just enough formal machinery to study recursion
  and induction in an interesting context.  This document is
  self-contained.  You'll need nothing besides this document, a
  pencil and paper (or a computer), and time and space to think.  In
  the interest of scholarly completeness, we provide an annotated
  bibliography; see [r-and-i-annotated-bibliography].  But none of
  the documents listed there is necessary for the problems here.

  These notes are meant to be read linearly, like a text book.  Each
  section ends with a link to the next section.  For example, the
  link to the section after this one looks like this, Data Types (see
  [R-AND-I-DATA-TYPES]); but don't go there yet!

  Throughout these notes you will see see links to resources on the web
  and some of those links take you out of the [3mRecursion and Induction[0m
  notes and into ACL2's online manual.  Those ``external'' links
  appear like this, ``(Maybe explore <<...>>?)''.  These links lead
  to related discussions of issues and features of the ACL2 system.
  You'll need to be connected to the web to access some of these
  pages, unless you have installed ACL2 on your system and built the
  full manual and books documentation.  See the installation
  instructions on the ACL2 home page [4].  We provide this material
  for students who want to explore further.  But these links are
  technically irrelevant to the student who is focused on working the
  exercises here, even if your ultimate goal is to learn how to use
  ACL2.  First, learn how to do the exercises here.  In a second
  pass, where you're trying to get ACL2 to do your proofs, you might
  want to explore.  And remember, it is easy for explorers to get
  lost!

  [31;1mIf you are working your way through [3mRecursion and Induction[0m[31;1m and
  decide to follow one of these explorer links be sure to use the
  ``Back'' feature of your browser to return to these notes.[0m

  Next: Data Types (see [R-AND-I-DATA-TYPES]) (or Table of Contents
  (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-MORE-INADEQUACIES-OF-THE-DEFINITIONAL-PRINCIPLE
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: More Inadequacies of the Definitional
  Principle

  Next: Mutual Recursion Inadequacies (see
  [R-AND-I-MUTUAL-RECURSION-INADEQUACIES]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))


Subtopics

  [R-and-i-mutual-recursion-inadequacies]
      Recursion and Induction: Mutual Recursion Inadequacies

  [R-and-i-problematic-nested-recursion]
      Recursion and Induction: Problematic Nested Recursion")
 (R-AND-I-MORE-PROBLEMS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: More Problems

  [31;1mProblem 106.
  [0m Here is a way to flatten a binary tree without using an auxiliary
  function.  Admit this definition.

      (defun flatten! (x)
        (if (atom x)
            (cons x nil)
            (if (atom (car x))
                (cons (car x) (flatten! (cdr x)))
                (flatten! (cons (caar x) (cons (cdar x) (cdr x)))))))

  [31;1mProblem 107.
  [0m Prove [47m(equal (flatten! x) (flatten x))[0m.

  [31;1mProblem 108.
  [0m Here is a clever way to determine if two binary trees have the same
  fringe.  Admit this function (and its subroutine).

      (defun samefringe (x y)
       (if (or (atom x)
               (atom y))
           (equal x y)
           (and (equal (car (gopher x))
                       (car (gopher y)))
                (samefringe (cdr (gopher x))
                            (cdr (gopher y))))))

  where

      (defun gopher (x)
        (if (or (atom x)
                (atom (car x)))
            x
            (gopher (cons (caar x) (cons (cdar x) (cdr x))))))

  [31;1mProblem 109.
  [0m Prove

      (equal (samefringe x y)
             (equal (flatten x)
                    (flatten y)))

  [31;1mProblem 110.
  [0m The curious recursions in [47mgopher[0m and [47msamefringe[0m are due to John
  McCarthy, who viewed [47mgopher[0m as a model of a co-routine.  Explain
  what he was thinking.

  [31;1mProblem 111.
  [0m Below is a model of the functional behavior of QuickSort.  Note that
  [47mrel[0m is defined as a ``higher order'' function that can apply any of
  four relations.

      (defun rel (fn x y)
        (if (equal fn '<<=)
            (<<= x y)
            (if (equal fn '>>=)
                (<<= y x)
                (if (equal fn '<<)
                    (and (<<= x y) (not (equal x y)))
                    (and (<<= y x) (not (equal x y)))))))

      (defun filter (fn x e)
        (if (endp x)
            nil
            (if (rel fn (car x) e)
                (cons (car x) (filter fn (cdr x) e))
                (filter fn (cdr x) e))))

      (defun qsort (x)
        (if (endp x)
            nil
            (if (endp (cdr x))
                x
                (app (qsort (filter '<< (cdr x) (car x)))
                     (cons (car x)
                           (qsort (filter '>>= (cdr x) (car x))))))))

  Prove that [47mqsort[0m produces an ordered permutation of its input.

  [31;1mProblem 112.
  [0m Prove that the length of a list of distinct natural numbers is no
  greater than its maximum element plus one.  This is sometimes
  called the Pigeon Hole Principle.

  [31;1mProblem 113.
  [0m Imagine a simple list being treated as a ``memory.'' If [3ma[0m  is a
  natural number less than the length of the memory, then [3ma[0m  is an
  ``address'' and we can use [47mnth[0m to fetch the contents.  This is
  ``dereferencing'' [3ma[0m.  If [3ma[0m  is not an address, we will say it is
  ``data.'' Now consider the idea of taking an object and a memory
  and dereferencing until we get to data.  The following function
  counts the steps; it returns the symbol [47minfinite[0m if a loop is
  detected.

      (defun deref-cnt (ptr mem seen)
        (if (addressp ptr mem)
            (if (mem ptr seen)
                'infinite
                (inc (deref-cnt (nth ptr mem) mem (cons ptr seen))))
            0))

  where

      (defun len (x)
        (if (consp x)
            (+ 1 (len (cdr x)))
            0))

      (defun inc (x)
        (if (integerp x) (+ 1 x) 'infinite))

      (defun addressp (ptr m)
        (and (natp ptr)
             (< ptr (len m))))

  Admit [47mderef-cnt[0m.

  [31;1mProblem 114.
  [0m This is a fact every undergraduate knows.  The number of times you
  can dereference (without being in a loop) is bounded by the size of
  the memory (plus one for the initial probe).  Prove it.

      (<= (deref-cnt ptr mem nil)
          (+ 1 (len mem)))

  Since [47mderef-cnt[0m returns the non-number [47minfinite[0m if it is a loop, and
  since ACL2 arithmetic treats non-numbers as [47m0[0m, this theorem is
  trivial when the process loops.  You may therefore explicitly add
  the hypothesis [47m(integerp (deref-cnt ptr mem nil))[0m if you are
  uncomfortable dealing with the non-numeric defaults.

  [31;1mProblem 115.
  [0m Here is the familiar definition of the Fibonacci function and a more
  efficient one (``fast Fibonacci'').

      (defun fib (i)
        (if (zp i)
            0
            (if (equal i 1)
                1
                (+ (fib (- i 1))
                   (fib (- i 2))))))

      (defun ffib (i j k)
        (if (zp i)
            j
            (if (equal i 1)
                k
                (ffib (- i 1) k (+ j k)))))

  Prove they are equal in the following sense

      (equal (ffib n 0 1) (fib n))

  [31;1mProblem 116.
  [0m Prove

      (equal (rotn (len x) x) x)

  where

      (defun rot (x)
        (if (endp x)
            nil
            (app (cdr x) (cons (car x) nil))))

      (defun rotn (n x)
        (if (zp n)
            x
            (rotn (- n 1) (rot x))))

  [31;1mProblem 117.
  [0m In this problem we explore binary arithmetic.  Let a [3mbit vector[0m  be
  a list of Booleans; it is convenient to suppose that the least
  significant bit is the car.  A bit vector represents a natural
  number in the usual binary encoding.  Define [47m(vadd x y)[0m to return a
  bit vector representing the sum of the numbers represented by the
  bit vectors [47mx[0m and [47my[0m.  Formally specify and prove that [47mvadd[0m is
  correct.  Obviously, this problem can be expanded to include other
  binary arithmetic operations and implementations.

  Next: More Inadequacies of the Definitional Principle (see
  [R-AND-I-MORE-INADEQUACIES-OF-THE-DEFINITIONAL-PRINCIPLE]) (or
  Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-MUTUAL-RECURSION-INADEQUACIES
  (R-AND-I-MORE-INADEQUACIES-OF-THE-DEFINITIONAL-PRINCIPLE)
  "Recursion and Induction: Mutual Recursion Inadequacies

  [31;1mProblem 118.
  [0m Mutual recursion is (still) not allowed by our statement of the
  Definitional Principle.  However, suppose that somehow the axioms
  produced by the following pair of definitions were available.

      (defun fx (x)
        (if (consp x)
            (cons (fx (car x))
                  (gx (cdr x)))
            x))

      (defun gx (x)
        (if (consp x)
            (cons (gx (car x))
                  (fx (cdr x)))
            x))

  Prove

      (equal (fx x) x)

  [31;1mProblem 119.
  [0m Develop a methodology for dealing with mutual recursion.  That is,
  explain how you can use our Definitional Principle to introduce two
  functions [47mfx[0m and [47mgx[0m that can be shown to satisfy the ``defining
  equations'' for [47mfx[0m and [47mgx[0m above.  Your methodology should work for
  any clique of mutually recursive functions that can be shown to
  terminate under the [47mo<[0m relation.

  [31;1mProblem 120.
  [0m We say [47mx[0m is an [3mexpression[0m  if (a) [47mx[0m is a symbol or (b) [47mx[0m is a list
  of the form [47m([0m[3mf[0m  [3me_1[0m   ...  [3me_n[0m[47m)[0m, where [3mf[0m  is a symbol and the [3me_i[0m
  are expressions.  Define [47m(expr x)[0m to recognize expressions.

  [31;1mProblem 121.
  [0m An [3mexpression substitution[0m  is a list of 2-tuples of the form [47m([0m[3mv[0m
  [3mexpr[0m[47m)[0m, where [3mv[0m  is a symbol and [3mexpr[0m  is an expression.  Define
  [47msubstitution[0m to recognize expression substitutions.

  [31;1mProblem 122.
  [0m Define [47m(slash x s)[0m so that it substitutes the expression
  substitution [47ms[0m into the expression [47mx[0m, e.g., it returns [47mx[0m/[47ms[0m.

  [31;1mProblem 123.
  [0m Prove that if [47ms[0m is an expression substitution and [47mx[0m is an
  expression, then [47m(slash x s)[0m is an expression.

  (Maybe explore <<[mutual-recursion]>>?)

  Next: Problematic Nested Recursion (see
  [R-AND-I-PROBLEMATIC-NESTED-RECURSION]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-NUMBERS
  (R-AND-I-DATA-TYPES)
  "Recursion and Induction: Numbers

  The only numbers we will use are the integers, written in the usual
  way, e.g., [47m-3[0m, [47m0[0m, and [47m123[0m.  ACL2 allows integers to be written in
  other ways, e.g., [47m00123[0m, [47m+123[0m, [47m246/2[0m, [47m#b1111011[0m, [47m#o173[0m and [47m#x7B[0m are
  all ways to write [47m123[0m.  However, we will always write them in
  conventional decimal notation.

  ACL2 also supports rationals, e.g., [47m1/3[0m and [47m22/7[0m, and complex
  rationals, e.g., [47m#c(5 2)[0m, which is more commonly written 5 + 2[3mi[0m.
  Lisp, but not ACL2, supports floating point numbers, e.g., [47m3.1415[0m
  and [47m31415E-4[0m.

  (Maybe explore <<[numbers]>>?)

  Next: Characters (see [R-AND-I-CHARACTERS]) (or Table of Contents
  (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-ORDINALS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: The Ordinals

  The ordinals are an extension of the naturals that captures an
  essential notion of ordering.  They were invented by Georg Cantor
  in the late nineteen century.  While controversial during Cantor's
  lifetime, ordinals are among the richest and deepest mines of
  mathematics.  We only scratch the surface here.

  Think of each natural number as denoted by a sequence of strokes,
  i.e.,

      0             0
      1             |
      2             | |
      3             | | |
      4             | | | |
       ...               ...
      \\omega             | | | | |  ...

  The limit of that progression is the ordinal [3m\\omega[0m, an infinite
  sequence of strokes.

  Ordinal addition is just concatenation.  Observe that adding one to
  the front of [3m\\omega[0m  produces [3m\\omega[0m  again, which gives rise to a
  standard definition of [3m\\omega[0m: the least ordinal such that adding
  another stroke at the beginning does not change the ordinal.

  We denote by [3m\\omega[0m  + [3m\\omega[0m  or [3m\\omega[0m\\times2 the ``doubly
  infinite'' sequence that we might write as follows.

      \\omega \\times 2         | | | | |  ...  | | | | |  ...

  One way to think of [3m\\omega[0m\\times2 is that it is obtained by
  replacing each stroke in 2 (| |) by [3m\\omega[0m.  Thus, one can imagine
  [3m\\omega[0m\\times3, [3m\\omega[0m\\times4, etc., which leads ultimately to the
  idea of [3m\\omega[0m\\times[3m\\omega[0m, the ordinal obtained by replacing each
  stroke in [3m\\omega[0m  by [3m\\omega[0m.  This is also written as [3m\\omega[0m^2.

      \\omega^2           | | | | |  ...  | | | | |  ...  | | | | |  ...  | | | | |  ...  | | | | |  ...   ...

  We can analogously construct [3m\\omega[0m^3 by replacing each stroke in
  [3m\\omega[0m  by [3m\\omega[0m^2 (which, it turns out, is the same as replacing
  each stroke in [3m\\omega[0m^2 by [3m\\omega[0m).  That is, we can construct
  [3m\\omega[0m^3 as [3m\\omega[0m  copies of [3m\\omega[0m^2, and so on.  This ultimately
  suggests [3m\\omega[0m^[3m\\omega[0m.  We can then stack [3m\\omega[0ms, i.e.,
  [3m\\omega[0m^([3m\\omega[0m^[3m\\omega[0m), etc.  Consider the limit of all of those
  stacks,

  [47m [3m\\omega[0m[47m^([3m\\omega[0m[47m^([3m\\omega[0m[47m^([3m\\omega[0m[47m^([3m\\omega[0m[47m^([3m\\omega[0m[47m^([3m\\omega[0m[47m^ ... )))))).
  [0m

  That limit is [3m\\epsilon_0[0m.  (As the subscript suggests, there are
  lots more ordinals!  But ACL2 stops with [3m\\epsilon_0[0m.)

  Despite the plethora of ordinals, we can represent all the ones
  below [3m\\epsilon_0[0m  in ACL2, using lists.  Below we begin listing
  some ordinals up to [3m\\epsilon_0[0m; the reader can fill in the gaps at
  his or her leisure.  We show in the left column the conventional
  notation and in the right column the ACL2 object representing the
  corresponding ordinal.

    ordinal	|  	|  ACL2 representation	|
    	|  	|  	|
    0	|  	|  0	|
    1	|  	|  1	|
    2	|  	|  2	|
    3	|  	|  3	|
    ...	|  	|  ...	|
    [3m\\omega[0m	|  	|  ((1 . 1) . 0)	|
    [3m\\omega[0m  + 1	|  	|  ((1 . 1) . 1)	|
    [3m\\omega[0m  + 2	|  	|  ((1 . 1) . 2)	|
    ...	|  	|  ...	|
    [3m\\omega[0m\\times2	|  	|  ((1 . 2) . 0)	|
    ([3m\\omega[0m\\times2) + 1	|  	|  ((1 . 2) . 1)	|
    ...	|  	|  ...	|
    [3m\\omega[0m\\times3	|  	|  ((1 . 3) . 0)	|
    ([3m\\omega[0m\\times3) + 1	|  	|  ((1 . 3) . 1)	|
    ...	|  	|  ...	|
    [3m\\omega[0m^2	|  	|  ((2 . 1) . 0)	|
    ...	|  	|  ...	|
    [3m\\omega[0m^2 + [3m\\omega[0m\\times4 + 3	|  	|  ((2 . 1) (1 . 4) . 3)	|
    ...	|  	|  ...	|
    [3m\\omega[0m^3	|  	|  ((3 . 1) . 0)	|
    ...	|  	|  ...	|
    [3m\\omega[0m^[3m\\omega[0m	|  	|  ((((1 . 1) . 0) . 1) . 0)	|
    ...	|  	|  ...	|
    [3m\\omega[0m^[3m\\omega[0m  + [3m\\omega[0m^99 + [3m\\omega[0m\\times4 + 3	|  	|  ((((1 . 1) . 0) . 1) (99 . 1) (1 . 4) . 3)	|
    ...	|  	|  ...	|
    [3m\\omega[0m^([3m\\omega[0m^2)	|  	|  ((((2 . 1) . 0) . 1) . 0)	|
    ...	|  	|  ...	|
    [3m\\omega[0m^([3m\\omega[0m^[3m\\omega[0m)	|  	|  ((((((1 . 1) . 0) . 1) . 0) . 1) . 0)	|
    ...	|  	|  ...	|

  We say an ordinal is ``finite'' if it is not a cons and we define
  [47m(o-finp x)[0m to recognize finite ordinals.  Of course, if [47mx[0m is an
  ordinal and finite, it is a natural number.  But by defining [47mo-finp[0m
  this way we ensure that if an ordinal is not finite we can recur
  into it with [47mcdr[0m.

  To manipulate ordinals we define functions that access the first
  exponent, the first coefficient, and the rest of the ordinal:

      (defun o-first-expt (x)
        (if (o-finp x) 0 (car (car x))))

      (defun o-first-coeff (x)
        (if (o-finp x) x (cdr (car x))))

      (defun o-rst (x) (cdr x))

  For example, if [47mx[0m is the representation of [3m\\omega[0m^e\\times[3mc[0m  + [3mr[0m
  then [47m(o-first-expt x)[0m is [3me[0m, [47m(o-first-coeff x)[0m is [3mc[0m  and [47m(o-rst x)[0m
  is [3mr[0m.

  Here is the definition of [47mo-p[0m, the function that recognizes
  ordinals.

      (defun o-p (x)
        (if (o-finp x)
            (natp x)
            (and (consp (car x))
                 (o-p (o-first-expt x))
                 (not (equal 0 (o-first-expt x)))
                 (natp (o-first-coeff x))
                 (< 0 (o-first-coeff x))
                 (o-p (o-rst x))
                 (o< (o-first-expt (o-rst x))
                     (o-first-expt x)))))

  (The ACL2 definition is syntactically different but equivalent.)

  The function [47mo<[0m is the ``less than'' relation on ordinals.  We show
  its definition below.  But study the definition of [47mo-p[0m first.  It
  says that an ordinal is a list of pairs, terminated by a natural
  number.  Each pair [47m(e . c)[0m consists of an exponent [47me[0m and a
  coefficient [47mc[0m and represents ([3m\\omega[0m^e)\\times[3mc[0m.  The exponents are
  themselves ordinals and the coefficients are non-0 naturals.
  Importantly, the exponents are listed in strictly descending order.
  The list represents the ordinal sum of its elements plus the final
  natural number.  Thus, ordinals can be viewed as polynomials.

  By insisting on the ordering of exponents we can readily compare two
  ordinals, using [47mo<[0m below, in much the same way we can compare
  polynomials.

      (defun o< (x y)
        (if (o-finp x)
            (or (not (o-finp y))
                (< x y))
            (if (o-finp y)
                nil
                (if (equal (o-first-expt x)
                           (o-first-expt y))
                    (if (equal (o-first-coeff x)
                               (o-first-coeff y))
                        (o< (o-rst x)
                            (o-rst y))
                        (< (o-first-coeff x)
                           (o-first-coeff y)))
                    (o< (o-first-expt x)
                        (o-first-expt y))))))

  (The ACL2 definition is syntactically different but equivalent.)

  [31;1mProblem 90.
  [0m Which is smaller, ordinal a or ordinal b?

   1. a = [47m23[0m, b = [47m100[0m

   2. a = [47m1000000[0m, b = [47m((1 . 1) . 0)[0m

   3. a = [47m((2 . 1) . 0)[0m, b = [47m((1 . 2) . 0)[0m

   4. a = [47m((3 . 5) (1 . 25) . 7)[0m, b = [47m((3 . 5) (2 . 1) . 3)[0m

   5. a = [47m((((2 . 1) . 0) . 5) . 3)[0m, b = [47m((((1 . 1) . 0) . 5) (1 . 25) . 7)[0m

  [31;1mProblem 91.
  [0m The [47mo<[0m operation can be reduced to lexicographic comparison.  Define
  [47mm2[0m so that it constructs ``lexicographic ordinals'' from two
  arbitrary natural numbers.  Specifically, show that the following
  is a theorem:

      (implies (and (natp i1)
                    (natp j1)
                    (natp i2)
                    (natp j2))
               (and (o-p (m2 i1 j1))
                    (iff (o< (m2 i1 j1)
                             (m2 i2 j2))
                         (if (equal i1 i2)
                             (< j1 j2)
                             (< i1 i2)))))

  The crucial property of [47mo<[0m is that it is [3mwell-founded on the
  ordinals[0m.  That is, there is no infinite sequence of ordinals, [3mx_i[0m
  such that  ...  [3mx_3[0m  [47mo<[0m [3mx_2[0m  [47mo<[0m [3mx_1[0m  [47mo<[0m [3mx_0[0m.

  [31;1mProblem 92.
  [0m What is the longest decreasing chain of ordinals starting from the
  ordinal [47m10[0m?  What is the longest decreasing chain of ordinals
  starting from the ordinal [47m((1 . 1) . 0)[0m?

  [31;1mProblem 93.
  [0m Construct an infinitely descending [47mo<[0m chain of objects.  Note that
  by the well-foundedness of [47mo<[0m on the ordinals, your chain will not
  consist entirely of ordinals!

  [31;1mProblem 94.
  [0m Prove that [47mo<[0m is well-founded on our ordinals, i.e., those
  recognized by [47mo-p[0m.

  Caution: Using the logical machinery we have developed here, it is
  not possible to state that [47mo<[0m is well-founded on the ordinals: that
  requires an existential quantifier and infinite sequences.
  However, it can be done in a traditional set theoretic setting.
  That is, the theorem that [47mo<[0m is well-founded is a ``meta-theorem'',
  it can be proved about our system but it cannot be proved within
  our system.

  Our definitional and induction principles are built on the
  assumption that [47mo<[0m is well-founded on the ordinals recognized by
  [47mo-p[0m.  Thus, if some ordinal measure of the arguments of a recursive
  function decreases according to [47mo<[0m in every recursive call, the
  recursion cannot go on forever.

  The representation of ordinals described here is a version of
  Cantor's Normal Form.  See [reference 5] (see
  [R-AND-I-ANNOTATED-BIBLIOGRAPHY]) or the online documentation
  topics <<[ordinals]>> and <<[o-p]>>, from which some of the
  examples above have been chosen.

  Next: The Definitional Principle (see
  [R-AND-I-DEFINITIONAL-PRINCIPLE]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-PAIRS
  (R-AND-I-DATA-TYPES)
  "Recursion and Induction: Pairs

  Pairs are written in Lisp's [3mdot notation[0m.  Instead of conventional
  Cartesian notation, e.g., < [47m1[0m, [47m2[0m >, Lisp replaces the angle
  brackets with parentheses and the comma with a dot, [47m(1 . 2)[0m.  Thus,
  [47m((1 . 2) . (3 . 4))[0m is the pair containing the pair [47m(1 . 2)[0m in its
  left component and the pair [47m(3 . 4)[0m in its right.  In high school,
  you might have written this object as <<1, 2>,<3, 4>>.  Note that
  exactly one object must follow the dot; for example, the notation
  [47m((1 . 2) . 3 4)[0m is illegal.  However, one or more objects may
  precede the dot, as discussed below.

  In Lisp, pairs are called [3mconses[0m.  Non-conses are called [3matoms[0m.  The
  left component is called the [3mcar[0m  and the right component is called
  the [3mcdr[0m  (pronounced ``cudder'').  (Remark.  The names come from
  the original implementation of Lisp on the IBM 704.  That machine
  had a 36-bit word that was logically divided into two parts, the
  ``address'' and the ``decrement.'' Lisp used such words to
  represent a [47mcons[0m cell.  The address part pointed to the left
  component and the decrement part pointed to the right component.
  Thus, the operations were [47mcar[0m (``contents of address of register'')
  and [47mcdr[0m (``contents of decrement of register'').)  Lisp provides
  three conventions for writing parenthesized constants.

    * [47mNil[0m can be written [47m()[0m.

    * A pair of the form [47m([3mx[0m[47m  . nil)[0m may be written [47m([3mx[0m[47m)[0m.

    * A pair of the form [47m([3mx[0m[47m  . ([3my[0m[47m  ...))[0m may be written [47m([3mx[0m[47m [3my[0m[47m  ...)[0m.

  Thus, the cons [47m(1 . (2 . (3 . nil)))[0m may be written [47m(1 2 3)[0m.  This
  suggests the most common use of conses: to represent linked lists
  or sequences.  The special role of [47mnil[0m in these conventions is the
  only sense in which [47mnil[0m is ``the empty list.''

  Any object can be treated as a list!  If a cons is being treated as
  a list, then its car is the first element and its cdr is treated as
  a list of the remaining elements.  If an atom is treated as a list,
  it is treated as the empty list.  [47mNil[0m is just the most common atom
  used in this way.

  Thus, the elements of [47m(1 . (2 . (3 . nil)))[0m are [47m1[0m, [47m2[0m, and [47m3[0m,
  respectively.  The length of this list is three.  If [47m((1 . 2) . (3
  . 4))[0m is treated as a list, its elements are [47m(1 . 2)[0m and [47m3[0m; its
  length is two.  The [47m4[0m is just the terminal atom.  [47m((1 . 2) . (3 .
  nil))[0m and [47m((1 . 2) . (3 . 4))[0m are different objects, but when
  treated as lists they have the same two elements.

  Here is a list of the symbols naming the summer months: [47m(June July
  August)[0m.  It could also be written [47m(JUNE . (JULY . (AUGUST . NIL)))[0m
  and many other ways.

  (Maybe explore <<[conses]>>?)

  Next: identity (see [R-AND-I-IDENTITY]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-PEANO-ARITHMETIC
  (R-AND-I-ARITHMETIC)
  "Recursion and Induction: Peano Arithmetic

  Recall that the integers are being treated as atomic objects in this
  document.  But we can explore elementary arithmetic by thinking of
  a list of [3mn[0m  [47mnil[0ms as a representation for the natural number [3mn[0m.  We
  will call such a list a ``nat.'' Thus, [47m(nil nil nil)[0m is a nat, but
  [47m3[0m is a natural number.

  [31;1mProblem 65.
  [0m Define [47m(nat x)[0m to recognize nats.

  [31;1mProblem 66.
  [0m Define [47m(plus x y)[0m to take two arbitrary lists (even ones that are
  not nats) and to return the nat representing the sum of their
  lengths.  By defining [47mplus[0m this way we ensure that it always
  returns a nat and that it is commutative.

  [31;1mProblem 67.
  [0m Define [47m(times x y)[0m to take two arbitrary lists and to return the nat
  representing the product of their lengths.

  [31;1mProblem 68.
  [0m Define [47m(power x y)[0m to take two arbitrary lists and to return the nat
  representing the exponentiation of their lengths, i.e., if [47mx[0m and [47my[0m
  are of lengths [3mi[0m  and [3mj[0m, then [47m(power x y)[0m should return the nat
  representing [3mi^j[0m.

  [31;1mProblem 69.
  [0m Define [47m(lesseqp x y)[0m to return [47mt[0m or [47mnil[0m according to whether the
  length of [47mx[0m is less than or equal to that of [47my[0m.

  [31;1mProblem 70.
  [0m Define [47m(evennat x)[0m to return [47mt[0m or [47mnil[0m according to whether the
  length of [47mx[0m is even.

  [31;1mProblem 71.
  [0m Prove

      (implies (nat i)
               (equal (plus i nil) i))

  [31;1mProblem 72.
  [0m Prove

      (equal (plus (plus i j) k)
             (plus i (plus j k)))

  [31;1mProblem 73.
  [0m Prove

      (equal (plus i j) (plus j i))

  [31;1mProblem 74.
  [0m Prove

      (equal (times (times i j) k)
             (times i (times j k)))

  [31;1mProblem 75.
  [0m Prove

      (equal (times i j) (times j i))

  [31;1mProblem 76.
  [0m Prove

      (equal (power b (plus i j))
             (times (power b i) (power b j)))

  [31;1mProblem 77.
  [0m Prove

      (equal (power (power b i) j)
             (power b (times i j)))

  [31;1mProblem 78.
  [0m Prove

      (lesseqp i i)

  [31;1mProblem 79.
  [0m Prove

      (implies (and (lesseqp i j)
                    (lesseqp j k))
               (lesseqp i k))

  [31;1mProblem 80.
  [0m Prove

      (equal (lesseqp (plus i j) (plus i k))
             (lesseqp j k))

  [31;1mProblem 81.
  [0m Prove

      (implies (and (evennat i)
                    (evennat j))
               (evennat (plus i j)))

  Next: ACL2 Arithmetic (see [R-AND-I-ACL2-ARITHMETIC]) (or Table of
  Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-PROBLEMATIC-NESTED-RECURSION
  (R-AND-I-MORE-INADEQUACIES-OF-THE-DEFINITIONAL-PRINCIPLE)
  "Recursion and Induction: Problematic Nested Recursion

  [31;1mProblem 124.
  [0m The following function cannot be admitted.  Explain why.

      (defun f5 (x)
        (if (zp x)
            0
            (+ 1 (f5 (f5 (- x 1))))))

  When the function being defined, [3mf[0m, is called recursively on the
  value of a nested recursive call, e.g., [47m([0m[3mf[0m   ...  ([3mf[0m   ... [47m))[0m, we
  say the definition exhibits [3mnested recursion[0m.  We have already seen
  some examples of nested recursion:

      (defun mcflatten (x a)
        (if (consp x)
            (mcflatten (car x)
                       (mcflatten (cdr x) a))
            (cons x a)))

      (defun ack (x y)
        (if (zp x)
            1
            (if (zp y)
                (if (equal x 1) 2 (+ x 2))
                (ack (ack (- x 1) y) (- y 1)))))

  [31;1mProblem 125.
  [0m What makes the recursion in [47mf5[0m, which cannot be admitted, different
  from that in [47mmcflatten[0m and [47mack[0m, which can be admitted?

  It is often possible to deal with problematic nested recursion, by
  admitting a different but related definition and then proving that
  it is equivalent to the one you wanted.  The next few problems
  illustrate this.

  [31;1mProblem 126.
  [0m Admit the following

      (defun f5 (x)
        (if (zp x)
            0
            (if (< (nfix (f5 (- x 1))) (nfix x))
                (+ 1 (f5 (f5 (- x 1))))
                'undef)))

  [31;1mProblem 127.
  [0m Prove

      (implies (natp x) (<= (f5 x) x))

  [31;1mProblem 128.
  [0m Prove

      (equal (f5 x)
             (if (zp x)
                 0
                 (+ 1 (f5 (f5 (- x 1))))))

  You may think that problematic nested recursion never arises in
  actual formal models.  Think again!  Consider a graph reachability
  algorithm, as might be implemented in the mark phase of a garbage
  collector.  Suppose a memory location can hold a pair of addresses,
  a single address, or data.  Given an initial address, mark all the
  reachable addresses, avoiding any possible cycles in the data.
  When the mark algorithm arrives at an address, [3mptr[0m, containing a
  pair, it marks that address, explores and marks one of the
  addresses, and then explores and marks the other.  The algorithm
  terminates because marking increases the number of marked addresses
  in memory and the number of addresses is bounded.  But note that
  when the algorithm explores and marks the second address it does so
  on the memory produced by exploring and marking the first address
  and the parent.  This is problematic nested recursion: if the inner
  recursion [3munmarked[0m  some of the marked addresses, the outer sweep
  might get caught in a cycle.  But we cannot prove that the
  algorithm does not unmark things until we have admitted the model!

  [31;1mProblem 129.
  [0m Let [47mm[0m be a list representing a RAM, with 0-based addressing modeled
  by [47mnth[0m.  An address is legal if it is a natural less than the
  length of the memory.  If an address contains a pair, we explore
  both the [47mcar[0m and the [47mcdr[0m.  If an address contains an address, we
  explore that address.  Cycles may be present.  The function below
  collects the list of all addresses reachable from a given one.
  This definition exhibits problematic nested recursion.

      (defun reachables (ptr m seen)
        (if (addressp ptr m)
            (if (mem ptr seen)
                seen
                (if (consp (nth ptr m))
                    (reachables (car (nth ptr m))
                                m
                                (reachables (cdr (nth ptr m))
                                            m
                                            (cons ptr seen)))
                    (reachables (nth ptr m) m (cons ptr seen))))
            seen))

  Use the method suggested by the [47mf5[0m problems to define a function
  satisfying the equation above.

  [31;1mProblem 130.
  [0m Consider the problem of reversing a list.  Our standard definition,
  [47mrev[0m, uses an auxiliary function, [47mapp[0m.  The tail-recursive version,
  [47mrev1[0m, uses an additional formal parameter.  Below is a definition
  of reverse that has only one parameter and no auxiliary functions.
  This definition was proposed by Rod M. Burstall in the early 1970s
  as an entertaining puzzle.  It exhibits problematic nested
  recursion.

      (defun rmb (x)
        (if (consp x)
            (if (consp (cdr x))
                (cons (car (rmb (cdr x)))
                      (rmb (cons (car x)
                                 (rmb (cdr (rmb (cdr x)))))))
                (cons (car x) nil))
            nil))

  Show how this definition can be derived from an admissible one.

  [31;1mProblem 131.
  [0m Suppose [47mrmb[0m is known to satisfy the ``defining equation'' that would
  be added by the [47mdefun[0m above had it been admissible.  That is,
  suppose that is the only equation known for [47mrmb[0m.  Prove

      (equal (rmb x) (rev x))

  Next: Still More Problems (see [R-AND-I-STILL-MORE-PROBLEMS]) (or
  Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-RELATIONS-BETWEEN-RECURSION-AND-INDUCTION
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Relations Between Recursion and Induction

  Informally speaking, a recursive definition is ``ok'' if there is an
  ordinal measure that decreases in every recursive call.  Thus, the
  recursion cannot go on forever.  In a simple recursion on naturals
  down to 0 by -1, the value of the function on 5 is determined
  recursively by its value on 4, which is determined recursively by
  its value on 3, which is determined recursively by its value on 2,
  which is determined recursively by its value on 1, which is
  determined recursively by its value on 0, which is specified
  explicitly in the definition.

  An inductive proof is ``ok'' if there is an ordinal measure that
  decreases in every induction hypothesis.  Thus, any concrete
  instance of the conjecture could be proved by ``pumping'' forward a
  finite number of times from the base cases.  Given a simple
  inductive proof over the naturals, the conjecture is true on 0
  because it was proved explicitly in the base case, so it is true on
  1 by the induction step, so it is true on 2 by the induction step,
  so it is true on 3 by the induction step, so it is true on 4 by the
  induction step, so it is true on 5 by the induction step.

  Clearly these two concepts are duals.  The formal statements of the
  two principles look more different than they are.  They both
  require us to prove that a measure returns an ordinal and that some
  substitutions make the measure decrease under some tests.  But
  there seems to be a lot less indexing going on in the Definitional
  Principle than in the Induction Principle.  That is due to language
  and the two different uses of the principles.  The Definitional
  Principle is designed to tell us whether a definitional equation is
  ok.  The Induction Principle is designed to tell us whether a set
  of formulas is an ok inductive argument.  So the Definitional
  Principle talks about the tests in [47mIF[0ms and the substitution built
  from each recursive call, whereas the Induction Principle talks
  about the tests in the [3mi[0mth formula and the substitution that
  created the [3mj[0mth induction hypothesis of the [3mi[0mth formula.

  But the key insight is: [3mEvery ok definition suggests an ok
  induction[0m!  We call this the induction [3msuggested by[0m  the
  definition.  It is easiest to see this by considering a particular,
  generic definition and thinking about what had to be proved to
  admit it, what induction it suggests, what has to be proved for
  that induction to be legal, and when the suggested induction might
  be useful.

  Suppose the following definition has been admitted, justified by
  measure term [47m(m x a)[0m.  Note that the body is an [47mIF[0m-tree, and there
  are three tips in the [47mIF[0m-tree; the first tip contains two recursive
  calls, the second tip contains one recursive call, and the third
  tip contains no recursive calls.

      (defun f (x a)
        (if (test1 x a)
            (if (test2 x a)
                (h                         ; tip 1
                 (f (d1 x a) (a1 x a))     ;   rec call 1,1
                 (f (d2 x a) (a2 x a)))    ;   rec call 1,2
                (g                         ; tip 2
                 (f (d3 x a) (a3 x a))))   ;   rec call 2,1
            (b x a)))                      ; tip 3

  To admit this definition we had to prove:

      [3mOrdinal Conjecture[0m
      (o-p (m x a))

      [3mMeasure Conjecture 1,1[0m
      (implies (and (test1 x a) (test2 x a))
               (o< (m (d1 x a) (a1 x a))
                   (m x a)))

      [3mMeasure Conjecture 1,2[0m
      (implies (and (test1 x a) (test2 x a))
               (o< (m (d2 x a) (a2 x a))
                   (m x a)))

      [3mMeasure Conjecture 2,1[0m
      (implies (and (test1 x a) (not (test2 x a)))
               (o< (m (d3 x a) (a3 x a))
                   (m x a)))

  Suppose we want to prove [47m(p x a)[0m, by induction according to the
  scheme ``suggested'' by [47m(f x a)[0m.  Here is the scheme:

      [3mBase Case[0m                               ; for tip 3
      (implies (not (test1 x a))
               (p x a))

      [3mInduction Step 1[0m                        ; for tip 1
      (implies (and (test1 x a)
                    (test2 x a)
                    (p (d1 x a) (a1 x a))    ;   for rec call 1,1
                    (p (d2 x a) (a2 x a)))   ;   for rec call 1,2
               (p x a))

      [3mInduction Step 2[0m                        ; for tip 2
      (implies (and (test1 x a)
                    (not (test2 x a))
                    (p (d3 x a) (a3 x a)))   ;   for rec call 2,1
               (p x a))

  This induction is produced by the following parameter choices in the
  Induction Principle:

      [3m\\psi[0m	|  [47m(p x a)[0m	|
      [3mm[0m	|  [47m(m x a)[0m	|
      [3mq_1[0m	|  [47m(and (test1 x a) (test2 x a))[0m	|
      [3mq_2[0m	|  [47m(and (test1 x a) (not (test2 x a)))[0m	|
      [3m\\sigma_{1,1}[0m	|  [47m{x <-- (d1 x a), a <-- (a1 x a)}[0m	|
      [3m\\sigma_{1,2}[0m	|  [47m{x <-- (d2 x a), a <-- (a2 x a)}[0m	|
      [3m\\sigma_{2,1}[0m	|  [47m{x <-- (d3 x a), a <-- (a3 x a)}[0m	|

  It should be obvious to you how these choices are determined from
  the definition of [47mf[0m with measure [47m(m x a)[0m.  For example, [3mq_1[0m  is the
  conjunction of the tests leading to the first tip containing
  recursive calls of [47mf[0m, and the substitutions [3m\\sigma_{1,j}[0m  are the
  substitutions derived from the recursive calls in that tip.

  The measure conjectures required by the Induction Principle for this
  choice of parameters are exactly the same as the measure
  conjectures verified when the Definitional Principle was used to
  admit [47mf[0m!  That is, to use an induction suggested by an
  already-admitted recursive function, no additional measure
  conjectures have to be proved.

  (Remark on ``exactly the same'' above.  We have propositionally
  simplified the defining condition for the Base Case.  The Induction
  Principle says it is [47m(and (not [3mq_1[0m[47m) (not [3mq_2[0m[47m))[0m and the literal
  instantiation of that here would be [47m(and (not (and (test1 x a)
  (test2 x a))) (not (and (test1 x a) (not (test2 x a)))))[0m, but that
  is propositionally equivalent to [47m(not (test1 x a))[0m.)

  But why might this induction be interesting or useful for proving [47m(p
  x a)[0m?  The answer depends on [47m(p x a)[0m, of course.  But the most
  common situation is that we choose the induction scheme suggested
  by some recursive function used in the conjecture to be proved.  So
  suppose [47m(f x a)[0m occurs in [47m(p x a)[0m.  Why is the suggested induction
  likely to be helpful?  Consider the Base Case and the two Induction
  Steps.

  In the Base Case, the [47m(f x a)[0m occurring in [47m(p x a)[0m can be replaced
  by tip 3 of the definition of [47mf[0m, [47m(b x a)[0m because the test in the
  Base Case of the induction is the test leading to the non-recursive
  exit from the definition.  So [47mf[0m has been eliminated from the proof
  of the Base Case.

  Now consider Induction Step 1.  The [47m(f x a)[0m occurring in [47m(p x a)[0m can
  be replaced by tip 1 of the definition of [47mf[0m, namely

      (h                         ; tip 1
       (f (d1 x a) (a1 x a))     ;   rec call 1,1
       (f (d2 x a) (a2 x a)))    ;   rec call 1,2

  because the tests in Induction Step 1 are the tests leading to tip 1
  of the definition.  But notice that the induction hypothesis
  labeled ``for rec call 1,1'' in Induction Step 1 gives us a
  hypothesis about recursive call 1,1 --- because the occurrence of
  [47m(f x a)[0m in [47m(p x a)[0m becomes an occurrence of [47m(f (d1 x a) (a1 x a))[0m
  when we apply the substitution [3m\\sigma_{1,1}[0m to it.  Similarly, the
  induction hypothesis labeled ``for rec call 1,2'' gives us a
  hypothesis about call 1,2.  Thus, the proof of Induction Step 1
  boils down to proving, ``if the two recursive calls in this tip
  have the property we're proving, then [47mh[0m of those two calls has the
  property.'' While not exactly eliminating [47mf[0m from the proof, it
  provides us with all the information that we have a right to
  suppose about [47mf[0m in this case.  Usually the proof of this step
  requires a lemma about [47mp[0m and [47mh[0m, e.g., ``if [47ma[0m and [47mb[0m have property [47mp[0m,
  then so does [47m(h a b)[0m.'' Such a lemma would eliminate [47mf[0m, and if we
  had that lemma the proof of Induction Step 1 would be done.  The
  proof of Induction Step 2 is analogous.

  Thus, we see that there may well be some heuristic value in using
  the induction suggested by [47m(f x a)[0m whenever you are trying to prove
  a property of [47m(f x a)[0m.  Occasionally it is necessary to use an
  induction suggested by a function not appearing in the conjecture,
  but when that occurs it is usually some easily recognized ``mash
  up'' of other functions appearing in the conjecture.

  [31;1mProblem 102.
  [0m Recall the previously admitted

      (defun f1 (i j)
        (if (and (natp i)
                 (natp j)
                 (< i j))
            (f1 (+ 1 i) j)
            1))

  Prove [47m(equal (f1 i j) 1)[0m.

  [31;1mProblem 103.
  [0m Recall the previously admitted

      (defun f2 (x)
        (if (equal x nil)
            2
            (and (f2 (car x))
                 (f2 (cdr x)))))

  Prove [47m(equal (f2 x) 2)[0m.

  [31;1mProblem 104.
  [0m Recall the previously admitted

      (defun f3 (x y)
        (if (and (endp x)
                 (endp y))
            3
            (f3 (cdr x) (cdr y))))

  Prove [47m(equal (f3 x y) 3)[0m.

  [31;1mProblem 105.
  [0m Recall the previously admitted

      (defun f4 (x y q)
        (if (p x)
            (if q
                (f4 y (dn x) (not q))
                (f4 y (up x) (not q)))
            4))

  Prove [47m(equal (f4 x y q) 4)[0m.

  These simple inductive exercises drive home the point that once a
  function has been admitted (proved to terminate) then we can do
  inductions to ``unwind'' it.  Students so frequently see induction
  limited to ``[3mp(n)[0m  implies [3mp(n+1)[0m '' that it is easy to forget that
  every total recursive function gives rise to an induction that is
  appropriate for it.

  Next: More Problems (see [R-AND-I-MORE-PROBLEMS]) (or Table of
  Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-STILL-MORE-PROBLEMS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Still More Problems

  The next several problems will lead you to define a tautology
  checker in ACL2 and to prove that it is sound and complete.  This
  is an excellent exercise if you are interested in theorem proving.

  [31;1mProblem 132.
  [0m An [3m[47mIF[0m[3m-expression[0m  is a cons whose car is [47mIF[0m.  A [3mquote[0m  is a cons
  whose car is [47mQUOTE[0m.  A [3mvariable[0m  is anything besides an
  [47mIF[0m-expression or a quote.  An [3mexpression[0m  is a variable, a quote,
  or an [47mIF[0m-expression.

  Note: By these definitions, any object is an expression.  But we
  typically think of [47mIF[0m-expressions as being of the form [47m(IF[0m [3ma_1[0m [3ma_2[0m
  [3ma_3[0m[47m)[0m and quotes being of the form [47m(QUOTE[0m [3ma[0m[47m)[0m.  But rather than check
  that they are of this form we will just use [47mcar[0m and [47mcdr[0m to chew
  into [47mIF[0ms and quotes to access the desired substructure, which we
  will call ``arguments'' one, two, and three.

  An [3massignment[0m  is a list of pairs, [47m([0m[3mvar[0m[47m . [0m[3mval[0m[47m)[0m, where [3mvar[0m  is a
  variable and [3mval[0m  is an arbitrary object (but is typically a
  Boolean).

  We define the [3mvalue[0m  of an expression under an assignment as
  follows.  The [3mvalue[0m  of a variable is the [3mval[0m  associated with that
  variable, or [47mnil[0m if the variable is not bound.  The [3mvalue[0m  of a
  quote is the first argument of the quote.  The value of an
  [47mIF[0m-expression depends on the value, [3mv[0m, of the first argument.  If [3mv[0m
  is [47mnil[0m, the value of the [47mIF[0m-expression is the value of its third
  argument; otherwise, it is the value of its second argument.

  Define these concepts.

  [31;1mProblem 133.
  [0m An expression is said to be in [3m[47mIF[0m[3m-normal form[0m  if no [47mIF[0m-expression
  in the expression has an [47mIF[0m-expression in its first argument.
  Thus, [47m(IF A (IF B C D) D)[0m is in [47mIF[0m-normal form, but [47m(IF (IF A B
  'NIL) C D)[0m is not.  It is possible to put an expression into
  [47mIF[0m-normal form while preserving its value, by repeatedly
  transforming it with the rule:

      (IF (IF a b c) x y) = (IF a (IF b x y) (IF c x y))

  Define the notion of [47mIF[0m-normal form and admit the function [47mnorm[0m that
  normalizes an expression while preserving its value.

  [31;1mProblem 134.
  [0m Given an expression in [47mIF[0m-normal form, define the function [47mtautp[0m
  that explores all feasible branches through the expression and
  determines that every output is non-[47mnil[0m.  We say a branch is
  [3minfeasible[0m if, in order to traverse it during evaluation under an
  assignment, the assignment would have to assign some variable both
  [47mnil[0m and non-[47mnil[0m.

  [31;1mProblem 135.
  [0m Define [47mtautology-checker[0m to recognize whether an expression has a
  non-[47mnil[0m value under all possible assignments.

  [31;1mProblem 136.
  [0m Prove that your [47mtautology-checker[0m is [3msound[0m: if it says an expression
  is a tautology, then the value of the expression is non-[47mnil[0m, under
  any assignment.

  [31;1mProblem 137.
  [0m Prove that your [47mtautology-checker[0m is [3mcomplete[0m: if it fails to
  recognize an expression, then some assignment falsifies the
  expression.

  This concludes [3mRecursion and Induction[0m.  Are you interested in
  learning how to use the ACL2 theorem prover?  (Maybe explore
  <<[introduction-to-the-theorem-prover]>>?)

  Next: Annotated Bibliography (see [R-AND-I-ANNOTATED-BIBLIOGRAPHY])
  (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-STRINGS
  (R-AND-I-DATA-TYPES)
  "Recursion and Induction: Strings

  Strings in our subset of ACL2 are written as sequences of ASCII
  characters between successive [3mstring quotes[0m.  For example, here is
  a string: [47m\"Hello, World!\"[0m.  For the purposes of this document, we
  will treat strings as atomic objects, though it is actually
  possible to construct and deconstruct them in terms of lists of
  character objects.

  (Maybe explore <<[strings]>>?)

  Next: Symbols (see [R-AND-I-SYMBOLS]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-STRUCTURAL-INDUCTION
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Structural Induction

  [31;1mProblem 39.
  [0m Given the definition

      (defun f (x)
        (if (consp x)
            (f (cdr x))
            t))

  can you prove the theorem [47m(equal (f x) t)[0m using the logical
  machinery we have described so far?

  ACL2 supports inductive proofs.  Its Induction Principle is quite
  general and involves the notion of the ordinals and
  well-foundedness.  We use a much simpler principle for now.

  A substitution [3m\\sigma[0m  is a [3m[47mcar[0m[3m/[47mcdr[0m[3m substitution[0m  on [3mv[0m  if the
  binding (image) of [3mv[0m  under [3m\\sigma[0m  is a [47mcar[0m/[47mcdr[0m nest around [3mv[0m.
  The other bindings of [3m\\sigma[0m  are unrestricted.  For example,
  [3m\\sigma[0m  = {[47mx <-- (car x), y <-- (cons (cdr x) y)[0m} is a [47mcar[0m/[47mcdr[0m
  substitution on [47mx[0m.

  [31;1mPrinciple of Structural Induction:[0m Let [47m[3m\\psi[0m[47m[0m be the term representing
  a conjecture.  [47m[3m\\psi[0m[47m[0m may be proved by selecting an ``induction''
  variable [47mx[0m, selecting a set of [47mcar[0m/[47mcdr[0m substitutions on [47mx[0m [3m\\sigma_1[0m,
  ... , [3m\\sigma_n[0m, and by proving the following subgoals:

      [3mBase Case:[0m
      (implies (not (consp x))
               [3m\\psi[0m)

  and

      [3mInduction Step:[0m
      (implies (and (consp x)   ; [3mtest[0m
                    [3m\\psi[0m/[3m\\sigma_1[0m   ; [3minduction hypothesis 1[0m
                    .
                    .
                    .
                    [3m\\psi[0m/[3m\\sigma_n[0m)  ; [3minduction hypothesis n[0m
               [3m\\psi[0m)  ; [3minduction conclusion[0m

  Here is an example Induction Step.

      (implies (and (consp x)
                    [3m\\psi[0m/{x <-- (car x), y <-- (app x y)}
                    [3m\\psi[0m/{x <-- (cdr (cdr x)), y <-- (cons x y)}
                    [3m\\psi[0m/{x <-- (cdr (cdr x)), y <-- y})
               [3m\\psi[0m)

  Let us use structural induction to prove a theorem about [47mtree-copy[0m.
  Recall the definition.

      (defun tree-copy (x)
        (if (consp x)
            (cons (tree-copy (car x))
                  (tree-copy (cdr x)))
            x))

  [31;1mTheorem[0m [47m(equal (tree-copy x) x)[0m.

  [31;1mProof[0m.

  Name the formula above *1.

  We prove *1 by induction.  One induction scheme is suggested by this
  conjecture -- namely the one that unwinds the recursion in
  [47mtree-copy[0m.

  If we let [3m\\psi[0m  denote *1 above then the induction scheme we'll use
  is

      (and (implies (not (consp x))
                    [3m\\psi[0m)
           (implies (and (consp x)
                         [3m\\psi[0m/{x <-- (car x)}
                         [3m\\psi[0m/{x <-- (cdr x)})
                    [3m\\psi[0m)).

  When applied to the goal at hand the above induction scheme produces
  the following two nontautological subgoals.

      Subgoal *1/2
      (implies (not (consp x))
               (equal (tree-copy x) x)).

  But simplification reduces this to [47mt[0m, using the definition of
  [47mtree-copy[0m and the primitive axioms.

      Subgoal *1/1
      (implies (and (consp x)                             ; [3mhyp 1[0m
                    (equal (tree-copy (car x)) (car x))   ; [3mhyp 2[0m
                    (equal (tree-copy (cdr x)) (cdr x)))  ; [3mhyp 3[0m
               (equal (tree-copy x) x)).

  But simplification reduces this to [47mt[0m, using the definition of
  [47mtree-copy[0m and the primitive axioms.

  That completes the proof of *1.

  [31;1mQ.E.D.[0m

  Let us look more closely at the reduction of Subgoal *1/1.  Consider
  the left-hand side of the concluding equality.  Here is how it
  reduces to the right-hand side under the hypotheses.

      (tree-copy x)
      =                      [3m{def [0m[47mtree-copy[0m[3m}[0m
      (if (consp x)
          (cons (tree-copy (car x))
                (tree-copy (cdr x)))
          x)
      =                      [3m{hyp 1 and Axiom 6}[0m
      (if t
          (cons (tree-copy (car x))
                (tree-copy (cdr x)))
          x)
      =                      [3m{Axioms 2 and 1}[0m
      (cons (tree-copy (car x))
            (tree-copy (cdr x)))
      =                      [3m{hyp 2}[0m
      (cons (car x)
            (tree-copy (cdr x)))
      =                      [3m{hyp 3}[0m
      (cons (car x)
            (cdr x))
      =                      [3m{Axioms 11 and 6 and hyp 1}[0m
      x

  This proof is of a very routine nature: induct so as to unwind some
  particular function appearing in the conjecture and then use the
  axioms and definitions to simplify each case to [47mt[0m.

  The problems below refer to function symbols defined in previous
  exercises.  Try to prove them for the definitions you wrote.  But
  if you cannot, then use the definitions we use in our solutions.
  For each conjecture below that is not a theorem, show a
  counterexample and then try to write the theorem ``suggested'' by
  the conjecture.  For example, add a hypothesis that restricts some
  variable so that the conjecture holds; you may even need to
  introduce new concepts.

  [31;1mWarning:[0m Proving implications by induction is a little tricky.
  Suppose you're trying to prove [47m(implies (p x) (q x))[0m by induction
  and you choose the substitution that replaces [47mx[0m by [47m(cdr x)[0m.  So the
  Induction Step will be

    Induction Step.
    (implies (and (consp x)
                  (implies (p (cdr x)) (q (cdr x))))
             (implies (p x) (q x))).

  By propositional calculus, this is the same as

    (implies (and (consp x)
                  (implies (p (cdr x)) (q (cdr x)))
                  (p x))
             (q x)).

  Many students act like the induction hypothesis is that [47m(q (cdr x))[0m
  is true and use that to show [47m(q x)[0m is true.  But the induction
  hypothesis is actually [47m(implies (p (cdr x)) (q (cdr x)))[0m.  It tells
  us that [47m(q (cdr x))[0m is true [3mif[0m [47m(p (cdr x))[0m is true!  So it often
  happens that you will use the [47m(p x)[0m hypothesis to prove [47m(p (cdr x))[0m
  is true.  Only then can you use [47m(q (cdr x))[0m to work on [47m(q x)[0m.

  [31;1mProblem 40.
  [0m Prove

      (equal (app (app a b) c) (app a (app b c))).

  [31;1mProblem 41.
  [0m Prove

      (equal (app a nil) a)

  [31;1mProblem 42.
  [0m Prove

      (equal (mapnil (app a b)) (app (mapnil a) (mapnil b)))

  [31;1mProblem 43.
  [0m Prove

      (equal (rev (mapnil x)) (mapnil (rev x)))

  [31;1mProblem 44.
  [0m Prove

      (equal (rev (rev x)) x)

  [31;1mProblem 45.
  [0m Prove

      (equal (swap-tree (swap-tree x)) x)

  [31;1mProblem 46.
  [0m Prove

      (equal (mem e (app a b)) (or (mem e a) (mem e b)))

  [31;1mProblem 47.
  [0m Prove

      (equal (mem e (int a b)) (and (mem e a) (mem e b)))

  [31;1mProblem 48.
  [0m Prove

      (sub a a)

  [31;1mProblem 49.
  [0m Prove

      (implies (and (sub a b)
                    (sub b c))
               (sub a c))

  [31;1mProblem 50.
  [0m Prove

      (sub (app a a) a)

  [31;1mProblem 51.
  [0m Define

      (defun mapnil1 (x a)
         (if (consp x)
             (mapnil1 (cdr x) (cons nil a))
             a))

  Formalize and then prove the remark ``On lists of [47mnil[0ms, [47mmapnil1[0m is
  commutative.''

  [31;1mProblem 52.
  [0m Define [47m(perm x y)[0m so that it returns [47mt[0m if lists [47mx[0m and [47my[0m are
  permutations of each other; otherwise it returns [47mnil[0m.

  [31;1mProblem 53.
  [0m Prove

      (perm x x)

  [31;1mProblem 54.
  [0m Prove

      (implies (perm x y) (perm y x)).

  [31;1mProblem 55.
  [0m Prove

      (implies (and (perm x y)
                    (perm y z))
               (perm x z))

  For several of the problems below it is necessary to have a total
  ordering relation.  Let [47m<<=[0m be a non-strict total order, i.e., a
  Boolean function that enjoys the following properties:

      (and (<<= x x)                 ; Reflexive
           (implies (and (<<= x y)   ; Anti-symmetric
                         (<<= y x))
                    (equal x y))
           (implies (and (<<= x y)   ; Transitive
                         (<<= y z))
                    (<<= x z))
           (or (<<= x y)             ; Total
               (<<= y x)))

  Actually, there is such a function in ACL2 and it is called
  [47mlexorder[0m.  But we use the more suggestive name ``[47m<<=[0m'' here.  On
  the integers, [47m<<=[0m is just [47m<=[0m, but it orders all ACL2 objects.

  [31;1mProblem 56.
  [0m Define [47m(ordered x)[0m so that it returns [47mt[0m or [47mnil[0m according to whether
  each pair of adjacent elements of [47mx[0m are in the relation [47m<<=[0m.  For
  example, [47m(ordered '(1 3 3 7 12))[0m would evaluate to [47mt[0m and [47m(ordered
  '(1 3 7 3 12))[0m would evaluate to [47mnil[0m.

  [31;1mProblem 57.
  [0m Define [47m(isort x)[0m to take an arbitrary list and return an [47mordered[0m
  permutation of it.

  [31;1mProblem 58.
  [0m Prove

      (ordered (isort x)).

  [31;1mProblem 59.
  [0m Prove

      (perm (isort x) x).

  [31;1mProblem 60.
  [0m Prove

      (equal (isort (rev (isort x)))
             (isort x)).

  We thank Pete Manolios for suggesting this problem.

  [31;1mProblem 61.
  [0m Define

      (defun rev1 (x a)
        (if (consp x)
            (rev1 (cdr x) (cons (car x) a))
            a))

  Prove

      (equal (rev1 x nil) (rev x))

  [31;1mProblem 62.
  [0m Prove

      (equal (mapnil1 x nil) (mapnil x))

  [31;1mProblem 63.
  [0m Prove

      (not (equal x (cons x y)))

  [31;1mProblem 64.
  [0m Define

      (defun mcflatten (x a)
        (if (consp x)
            (mcflatten (car x)
                       (mcflatten (cdr x) a))
            (cons x a)))

  Prove

      (equal (mcflatten x nil) (flatten x))

  Next: Arithmetic (see [R-AND-I-ARITHMETIC]) (or Table of Contents
  (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-SUBSTITUTIONS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Substitutions

  A [3msubstitution[0m  is a set {[3mv_0[0m  <-- [3mt_0[0m, [3mv_1[0m  <-- [3mt_1[0m,  ...} where
  each [3mv_i[0m  is a distinct variable symbol and each [3mt_i[0m  is a term.
  If, for a given substitution [3m\\sigma[0m  and variable [3mv[0m, there is an [3mi[0m
  such that [3mv[0m  is [3mv_i[0m, we say [3mv[0m  [3mis bound[0m  by [3m\\sigma[0m.  If [3mv[0m  is bound
  by [3m\\sigma[0m, then the [3mbinding[0m  of [3mv[0m  in [3m\\sigma[0m  is [3mt_i[0m, for the [3mi[0m
  such that [3mv_i[0m  is [3mv[0m.  (In set theory, a substitution is just a
  finite function that maps the [3mv_i[0m  to their respective [3mt_i[0m.)

  The result of [3mapplying[0m  a substitution [3m\\sigma[0m  to a term [3mterm[0m  is
  denoted [3mterm[0m/[3m\\sigma[0m  and is defined as follows.  If [3mterm[0m is a
  variable, then [3mterm[0m/[3m\\sigma[0m  is either the binding of [3mterm[0m  in
  [3m\\sigma[0m  or is [3mterm[0m  itself, depending on whether [3mterm[0m  is bound in
  [3m\\sigma[0m.  If [3mterm[0m  is a quoted constant, [3mterm[0m/[3m\\sigma[0m  is [3mterm[0m.
  Otherwise, [3mterm[0m  is [47m([0m[3mf[0m  [3ma_1[0m   ...  [3ma_n[0m[47m)[0m and [3mterm[0m/[3m\\sigma[0m  is [47m([0m[3mf[0m
  [3ma_1[0m/[3m\\sigma[0m   ...  [3ma_n[0m/[3m\\sigma[0m[47m)[0m.

  [31;1mProblem 6.
  [0m Suppose [3m\\sigma[0m  is

      {x <-- (car a),
       y <-- (cdr x)}

  What term is [47m(car (cons x (cons y (cons '\"Hello\" z))))[0m/[3m\\sigma[0m?

  Next: Abbreviations for Terms (see [R-AND-I-ABBREVIATIONS-FOR-TERMS])
  (or Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-SYMBOLS
  (R-AND-I-DATA-TYPES)
  "Recursion and Induction: Symbols

  Unlike many languages, Lisp provides symbols as primitive data
  objects.  Some example symbols are [47mt[0m, [47mnil[0m, [47mLOAD[0m, [47mSTORE[0m, [47mICONST_0[0m,
  [47mprime-factors[0m, [47m++[0m, and [47mfile77[0m.  For the purposes of this document,
  we will treat symbols as atomic objects, though it is actually
  possible to construct and deconstruct them in terms of strings.

  For the purposes of this document, a symbol is a sequence of
  alphabetic characters, digits, and/or certain signs (specifically,
  [47m+[0m, [47m-[0m, [47m*[0m, [47m/[0m, [47m=[0m, [47m<[0m, [47m>[0m, [47m?[0m, [47m![0m, [47m$[0m, [47m&[0m, and [47m_[0m (underscore)) that cannot be
  read as a number.  Case is unimportant.  Symbols are parsed to have
  the greatest length possible under the rules above.  Thus, [47mxy[0m is
  one symbol, not two symbols ([47mx[0m and [47my[0m) written without intervening
  whitespace!

  Note that [47mt[0m and [47mT[0m are different ways to write the same symbol, as
  are [47mnil[0m, [47mNil[0m, and [47mNIL[0m.  [47mT[0m and [47mnil[0m are called the [3mBoolean symbols[0m.
  [47mT[0m is frequently used to denote [3mtrue[0m and [47mnil[0m is used to denote
  [3mfalse[0m.  For reasons that will become apparent, [47mnil[0m is also used as
  the [3mempty list[0m.

  (Maybe explore <<[symbols]>>?)

  Next: Pairs (see [R-AND-I-PAIRS]) (or Table of Contents (see
  [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-TABLE-OF-CONTENTS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction Table of Contents)


Recursion and Induction Table of Contents

    * Preface and Acknowledgments (see [RECURSION-AND-INDUCTION])

    * Introduction (see [R-AND-I-INTRODUCTION])

    * Data Types (see [R-AND-I-DATA-TYPES])

    * Terms (see [R-AND-I-TERMS])

    * Substitutions (see [R-AND-I-SUBSTITUTIONS])

    * Abbreviations for Terms (see [R-AND-I-ABBREVIATIONS-FOR-TERMS])

    * Function Definitions (see [R-AND-I-FUNCTION-DEFINITIONS])

    * Axioms (see [R-AND-I-AXIOMS])

    * Terms as Formulas (see [R-AND-I-TERMS-AS-FORMULAS])

    * Definitions Revisited (see [R-AND-I-DEFINITIONS-REVISITED])

    * Structural Induction (see [R-AND-I-STRUCTURAL-INDUCTION])

    * Arithmetic (see [R-AND-I-ARITHMETIC])

    * Inadequacies of Structural Recursion (see
      [R-AND-I-INADEQUACIES-OF-STRUCTURAL-RECURSION])

    * The Ordinals (see [R-AND-I-ORDINALS])

    * The Definitional Principle (see [R-AND-I-DEFINITIONAL-PRINCIPLE])

    * The Induction Principle (see [R-AND-I-INDUCTION-PRINCIPLE])

    * Relations Between Recursion and Induction (see
      [R-AND-I-RELATIONS-BETWEEN-RECURSION-AND-INDUCTION])

    * More Problems (see [R-AND-I-MORE-PROBLEMS])

    * More Inadequacies of the Definitional Principle (see
      [R-AND-I-MORE-INADEQUACIES-OF-THE-DEFINITIONAL-PRINCIPLE])

    * Still More Problems (see [R-AND-I-STILL-MORE-PROBLEMS])

    * Annotated Bibliography (see [R-AND-I-ANNOTATED-BIBLIOGRAPHY])")
 (R-AND-I-TERMS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Terms

  For the purposes of this document, a [3mterm[0m  is a variable symbol, a
  quoted constant, or a function application written as a sequence,
  enclosed in parenthesis, consisting of a function symbol of arity [3mn[0m
  followed by [3mn[0m  terms.

  Since [47mcar[0m is a function symbol of arity one and [47mcons[0m is a function
  symbol of arity two, then [47m(cons (car x) y)[0m is a term.  In more
  conventional notation this term would be written [3mcons[0m ([3mcar[0m ([3mx[0m ), [3my[0m
  ).  We call [47m(car x)[0m and [47my[0m the [3mactual expressions[0m  or [3mactuals[0m  of
  the [3mfunction call[0m  [47m(cons (car x) y)[0m.

  Semantically, terms are interpreted with respect to (i) an
  assignment binding variable symbols to constants and (ii) an
  interpretation of function symbols as mathematical functions.  For
  example, suppose the variables [47mx[0m and [47my[0m are bound, respectively, to
  the constants [47m1[0m and [47m(2 3 4)[0m, and suppose the function symbol [47mcons[0m
  is interpreted as the function that constructs ordered pairs (as it
  always is).  Then the meaning or [3mvalue[0m  of the term [47m(cons x y)[0m is
  [47m(1 . (2 3 4))[0m or, equivalently, [47m(1 2 3 4)[0m.  That is, the value of a
  variable is determined by the variable assignment; the value of a
  quoted constant is that constant; and the value of a function
  application, [47m([0m[3mf[0m  [3ma_1[0m  ...  [3ma_n[0m[47m)[0m, is the result of applying the
  mathematical function assigned to [3mf[0m  to the values of the actuals,
  [3ma_i[0m.

  ACL2 provides an infinite number of [3mvariable symbols[0m, whose syntax
  is that of symbols.  Some example variable symbols are [47mx[0m, [47ma1[0m, and
  [47mtemp[0m.  The symbols [47mt[0m and [47mnil[0m are not legal variable symbols.

  A [3mquoted constant[0m  is written by prefixing an integer, a character
  object, a string, or a symbol by a single quote mark.  For example,
  [47m't[0m, [47m'nil[0m, [47m'-3[0m, [47m'[0m[47m#\\A[0m, [47m'\"Hello World!\"[0m and [47m'LOAD[0m are quoted
  constants.  Note that we do not consider [47m'(1 2 3)[0m a quoted
  constant.  This is a mere technicality.  We will shortly introduce
  some abbreviations that allow us to write [47m'(1 2 3)[0m as an
  abbreviation for [47m(cons '1 (cons '2 (cons '3 'nil)))[0m.

  ACL2 also has an infinite number of [3mfunction symbols[0m  each of which
  has an associated [3marity[0m  or number of arguments.  For the moment we
  will concern ourselves with six primitive function symbols: [47mcons[0m,
  [47mcar[0m, [47mcdr[0m, [47mconsp[0m, [47mif[0m, and [47mequal[0m, described below.  Note that we
  implicitly specify the arity of each primitive function symbol.

      [47m(cons [3mx[0m[47m [3my[0m[47m)[0m - construct and return the ordered pair [47m([3mx[0m[47m . [3my[0m[47m)[0m.

      [47m(car [3mx[0m[47m)[0m - return the left component of [3mx[0m, if [3mx[0m  is a pair; otherwise,
      return [47mnil[0m.

      [47m(cdr [3mx[0m[47m)[0m - return the right component of [3mx[0m, if [3mx[0m  is a pair;
      otherwise, return [47mnil[0m.

      [47m(consp [3mx[0m[47m)[0m - return [47mt[0m if [3mx[0m  is a pair; otherwise return [47mnil[0m.

      [47m(if [3mx[0m[47m [3my[0m[47m [3mz[0m[47m)[0m - return [3mz[0m  if [3mx[0m  is [47mnil[0m; otherwise return [3my[0m.

      [47m(equal [3mx[0m[47m [3my[0m[47m)[0m - return [47mt[0m if [3mx[0m  and [3my[0m  are identical; otherwise return
      [47mnil[0m.

  With these primitives we cannot do anything interesting with
  numbers, characters, strings, and symbols.  They are just tokens to
  put into or take out of pairs.  But we can explore most of the
  interesting issues in recursion and induction in this setting!

  (Maybe explore <<[term]>>?)

  Note that if the terms [3m\\alpha[0m and [3m\\beta[0m both evaluate to the same
  value, [3mv[0m, then the term [47m(equal[0m [3m\\alpha[0m [3m\\beta[0m[47m)[0m evaluates to [47mt[0m.  For
  example, the terms [47m(car (cons '3 '4))[0m and [47m'3[0m both evaluate to the
  value [47m3[0m, so the term [47m(equal (car (cons '3 '4)) '3)[0m evaluates to [47mt[0m.

  [31;1mProblem 3.
  [0m Which of the utterances below are terms?

   1. [47m(car (cdr x))[0m

   2. [47m(cons (car x y) z)[0m

   3. [47m(cons 1 2)[0m

   4. [47m(cons '1 '2)[0m

   5. [47m(cons one two)[0m

   6. [47m(cons 'one 'two)[0m

   7. [47m(equal '1 (car (cons '2 '3)))[0m

   8. [47m(if t 1 2)[0m

   9. [47m(if 't '1 '2)[0m

  10. [47m(car (cons (cdr hi-part) (car lo-part)))[0m

  11. [47mcar(cons x y)[0m

  12. [47mcar(cons(x,y))[0m

  13. [47m(cons 1 (2 3 4))[0m

  [31;1mProblem 4.
  [0m For each constant below, write a term whose value is the constant.

   1. [47m((1 . 2) . (3 . 4))[0m

   2. [47m(1 2 3)[0m

   3. [47m((1 . t) (2 . nil) (3 . t))[0m

   4. [47m((A . 1) (B . 2))[0m

  [31;1mProblem 5.
  [0m For each term below, write the constant to which it evaluates.

   1. [47m(cons (cons '1 '2) (cons (cons '3 '4) 'nil))[0m

   2. [47m(cons '1 (cons '2 '3))[0m

   3. [47m(cons 'nil (cons (cons 'nil 'nil) 'nil))[0m

   4. [47m(if 'nil '1 '2)[0m

   5. [47m(if '1 '2 '3)[0m

   6. [47m(equal 'nil (cons 'nil 'nil))[0m

   7. [47m(equal 'Hello 'HELLO)[0m

   8. [47m(equal (cons '1 '2) (cons '1 'two))[0m

  Next: Substitutions (see [R-AND-I-SUBSTITUTIONS]) (or Table of
  Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-AND-I-TERMS-AS-FORMULAS
  (RECURSION-AND-INDUCTION)
  "Recursion and Induction: Terms as Formulas

  Logicians typically make a careful distinction between terms (whose
  values range over objects in the domain, like the integers, etc.)
  and formulas (whose values range over the truthvalues).  We have
  set up two systems of propositional calculus.  At the level of
  formulas we have the traditional equality relation, =, and the
  logical operators &, \\/, ~, -->, and <->.  At the level of terms,
  we have the primitive function [47mequal[0m and the defined propositional
  functions [47mand[0m, [47mor[0m, [47mnot[0m, [47mimplies[0m, and [47miff[0m.  In our term-level
  propositional calculus, [47mt[0m and [47mnil[0m play the role of truthvalues.
  Because terms can be written entirely with ASCII symbols (and
  easily entered on a keyboard!) we tend to write terms and use them
  as formulas.

  For example, we might say that

      (implies (and (consp x)
                    (not (consp y)))
               (not (equal x y)))

  is a theorem, or even say

      ((consp x) & ~(consp y))
    -->
      x != y

  is a theorem.

  But of course, the former cannot be a theorem because it is a term
  and only formulas are theorems, and the latter cannot be a theorem
  because it is not even a well-formed formula (it uses some terms as
  though they were formulas).

  If we use an ACL2 term [47mp[0m as though it were a formula then the term
  should be understood as an abbreviation for the formula [47mp[0m != [47mnil[0m.
  Thus, if we say term [47mp[0m is a theorem we mean it is a theorem that [47mp[0m
  is not [47mnil[0m.

  Since we assume the reader here is familiar with programming, we
  assume this isomorphism between one syntactic category and another
  is very familiar.  If this makes sense to you, we suggest you just
  skip the rest of this section, including the problems below, and go
  to Definitions Revisited (see [R-AND-I-DEFINITIONS-REVISITED]).
  But if not, read on.

  This abuse of terminology is justified by the following theorems.

  [31;1mTheorem.[0m [47mNOT[0m is Logical Negation:
  [47m(not p)[0m != [47mnil[0m <-> ~ ([47mp[0m != [47mnil[0m).

  [31;1mProof.[0m We handle the two directions of the <->.

  Case 1.
  [47m(not p)[0m != [47mnil[0m --> ~ ([47mp[0m != [47mnil[0m).

  This is equivalent to its contrapositive:

  [47mp[0m != [47mnil[0m --> [47m(not p)[0m = [47mnil[0m.

  By the definition of [47mnot[0m and Axiom 2 and the hypothesis [47mp[0m!= [47mnil[0m,
  [47m(not p)[0m = [47m(if p nil t)[0m = [47mnil[0m.

  Case 2.
  ~ ([47mp[0m != [47mnil[0m) --> [47m(not p)[0m != [47mnil[0m.

  The hypothesis is propositionally equivalent to [47mp[0m = [47mnil[0m.  By
  substitution of equals for equals, the conclusion is [47m(not nil)[0m !=
  [47mnil[0m.  By the definition of [47mnot[0m and Axioms 3 and 1, [47m(not nil)[0m = [47m(if
  nil nil t)[0m = [47mt[0m != [47mnil[0m.

  Q.E.D.

  [31;1mProblem 18.
  [0m Prove
  [47m(and p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) & ([47mq[0m != [47mnil[0m).

  [31;1mProblem 19.
  [0m Prove
  [47m(or p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) \\/ ([47mq[0m != [47mnil[0m).

  [31;1mProblem 20.
  [0m Prove
  [47m(implies p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) --> ([47mq[0m != [47mnil[0m).

  [31;1mProblem 21.
  [0m Prove
  [47m(iff p q)[0m != [47mnil[0m <-> ([47mp[0m != [47mnil[0m) <-> ([47mq[0m != [47mnil[0m).

  [31;1mProblem 22.
  [0m Prove
  [47m(equal x y)[0m != [47mnil[0m <-> ([47mx[0m = [47my[0m)

  Note that these theorems allow us to change the propositional
  functions to their logical counterparts as we move the ``!= [47mnil[0m''
  into the term.  Furthermore, we can always drop a ``!= [47mnil[0m''
  anywhere it occurs in a formula since the term with which it
  appears would then be used as a formula and would mean the same
  thing.

  [31;1mProblem 23.
  [0m Using the theorems above, prove that

      (implies (and p (implies q r))
               s)

  is equivalent to

  [47m (p & (q --> r)) --> s [0m

  which is equivalent to

       ((p & ~ q) --> s)
      &
       ((p & q & r) --> s)

  When writing proofs on paper or the board, we tend to use formulas
  and the short symbols =, &, \\/, ~, -->, <-> instead of the longer
  term notation.

  [31;1mProblem 24.
  [0m Prove

      (equal (car (if a b c)) (if a (car b) (car c)))

  that is, prove [47m (car (if a b c)) = (if a (car b) (car c)) [0m

  [31;1mProblem 25.
  [0m Prove

      (equal (if (if a b c) x y)
             (if a (if b x y) (if c x y)))

  [31;1mProblem 26.
  [0m Prove

      (equal (tree-copy (cons a b))
             (cons (tree-copy a) (tree-copy b)))

  Next: Definitions Revisited (see [R-AND-I-DEFINITIONS-REVISITED]) (or
  Table of Contents (see [R-AND-I-TABLE-OF-CONTENTS]))")
 (R-EQLABLE-ALISTP
  (ALISTS ACL2-BUILT-INS)
  "Recognizer for a true list of pairs whose [47m[cdr][0ms are suitable for
  [47m[eql][0m

  The predicate [47mr-eqlable-alistp[0m tests whether its argument is a
  [47m[true-listp][0m of [47m[consp][0m objects whose [47m[cdr][0ms all satisfy
  [47m[eqlablep][0m.

  [31;1mFunction: [0m<r-eqlable-alistp>

    (defun r-eqlable-alistp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (equal x nil))
            (t (and (consp (car x))
                    (eqlablep (cdr (car x)))
                    (r-eqlable-alistp (cdr x))))))")
 (R-SYMBOL-ALISTP
  (ALISTS ACL2-BUILT-INS)
  "Recognizer for association lists with symbols as values

  [47m(R-symbol-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of
  the form [47m(cons key val)[0m where [47mval[0m is a [47m[symbolp][0m.

  [31;1mFunction: [0m<r-symbol-alistp>

    (defun r-symbol-alistp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (equal x nil))
            (t (and (consp (car x))
                    (symbolp (cdr (car x)))
                    (r-symbol-alistp (cdr x))))))")
 (RANDOM$
  (STATE NUMBERS ACL2-BUILT-INS)
  "Obtain a random value

    Example:
    (random$ 10 state) ==> (mv 7 <state>)

  [47m(Random$ limit state)[0m, where [47mlimit[0m is a positive integer, returns a
  random non-negative integer together with a new [47m[state][0m.
  Logically, it simply returns the first element of a list that is a
  field of the ACL2 [47m[state][0m, called the [47macl2-oracle[0m (see
  [47m[read-ACL2-oracle][0m), together with the new state resulting from
  removing that element from that list.  (Except, if that element is
  not in range as specified above, then 0 is returned.)  However,
  [47mrandom$[0m actually invokes a Common Lisp function to choose the
  integer returned.  Quoting from the Common Lisp HyperSpec(TM),
  {http://www.lispworks.com/documentation/HyperSpec/Front |
  http://www.lispworks.com/documentation/HyperSpec/Front}: ``An
  approximately uniform choice distribution is used...  each of the
  possible results occurs with (approximate) probability 1/limit.''

  Consider enabling rules [47mnatp-random$[0m and [47mrandom$-linear[0m if you want
  to reason about [47mrandom$[0m.

  [31;1mFunction: [0m<random$>

    (defun random$ (limit state)
      (declare (type (integer 1 *) limit)
               (xargs :stobjs state))
      (mv-let (erp val state)
              (read-acl2-oracle state)
        (mv (cond ((and (null erp)
                        (natp val)
                        (< val limit))
                   val)
                  (t 0))
            state)))")
 (RANDOM-REMARKS-ON-REWRITING
  (REWRITE REWRITE-QUOTED-CONSTANT)
  "Some basic facts about the ACL2 rewriter

  The ACL2 rewriter is technically part of the simplifier, but in this
  documentation we often conflate the two and say things like ``the
  conclusion simplifies to [47mT[0m'' when in fact we should say ``the
  conclusion rewrites to [47mT[0m during simplification'' In addition, both
  the simplifier and the rewriter are enormously complicated and
  contain so many heuristics that users are not often helped by
  studying the details.  For example, the rewriter takes 18 arguments
  (some of which are bundles of more rarely used arguments) and is
  part of a mutually recursive clique containing 50 functions as of
  Version 8.3, including the linear (and non-linear) arithmetic
  semi-decision procedures.  The rewriter and its clique consume
  about 6500 lines of code.

  But to understand how [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[rewrite-quoted-constant][0m,
  [47m:[0m[47m[linear][0m, [47m:[0m[47m[congruence][0m, [47m:[0m[47mforward-chaining[0m and other rules behave,
  the user has to have a fairly weak model of the simplifier and
  rewriter, so we sketch that here.

  In ACL2, the goals you see printed in proof output are represented
  internally as clauses.  See [clause].

  The job of the simplifier is to simplify a clause, returning a set of
  clauses whose conjunction is propositionally equivalent to the
  input clause.  The most desirable output set is the empty set,
  because the conjunction over the empty set is [47mT[0m, which means the
  goal clause was proved.  For related discussions, see
  [hints-and-the-waterfall], where we discuss how repeated
  simplifications are performed.

  Note that if you are trying to simplify the clause [47m(lit1 lit2 ...
  litk)[0m and you manage to rewrite, say, the [47mliti[0m to [47mT[0m, then the
  clause is true.  Furthermore, when rewriting a literal of a clause
  you may assume all the other literals false because if one were
  true the clause would be true.  Finally, when you rewrite a literal
  you are justified in replacing it with one that is propositional
  equivalent, since the literals are disjoined.

  The simplifier works by first generating several data structures,
  here called the ``context,'' which codify governing assumptions
  available for the rewriting of each literal.  These data structures
  include the [type-alist] and [linear-arithmetic] data base.  They
  are built using various rules derived from previously proved
  lemmas, including [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[forward-chaining][0m, and
  [47m:[0m[47m[linear][0m rules.  It then calls the rewriter successively on each
  literal passing it the appropriate context and stipulating that the
  result of the rewriting must be propositionally equivalent to the
  input.  The rewriter returns a suitable term.  If the result is the
  unchanged, the simplifier just moves on to the next literal.  If
  the result contains no [47mIF[0m-expressions, the simplifier just replaces
  the old literal with the new one.  But if the new term contains
  [47mIF[0m-expressions, the simplifier splits them out into a set of clause
  segments, i.e., if the literal simplifies to [47m(IF a b c)[0m, then the
  simplifier gets two new clause segments, [47m((NOT a) b)[0m and [47m(a c)[0m, and
  then it splices each segment into the goal clause where the literal
  was, producing a set of new clauses, and then resumes rewriting
  literals in each new clause.  Heuristics try to prevent excessive
  case splitting, e.g., see [case-split-limitations].

  The job of the rewriter is to take a term, some context, and an
  equivalence relation, and return a ``simpler'' term that is
  equivalent to the input term under the assumptions in the context.

  The rewriter works by exploring the term, possibly changing the
  context and the equivalence relation as appropriate for the
  subterms it rewrites.

    * If the term is a variable, the rewriter just returns it (unless the
      context tells it something interesting about that variable,
      such as that the variable is equal to [47mnil[0m).  Sometimes you
      might wish that the value of a bound variable be rewritten,
      usually because the value found on the alist was rewritten
      under a different equivalence relation than the variable is now
      being used.  See [47mdouble-rewrite[0m.

    * If the term is a quoted constant, the rewriter tries to apply
      [47m:[0m[47m[rewrite-quoted-constant][0m rules to that constant.

    * If the term is [47m(IF a b c)[0m, it rewrites the test, [47ma[0m, under the
      equivalence relation [47mIFF[0m to get some (possibly) new term, [47ma'[0m.
      If [47ma'[0m is [47mnil[0m or is obviously different from [47mnil[0m (like [47mT[0m), the
      rewriter replaces the [47mIF[0m-term by [47mb[0m or [47mc[0m, appropriately, and
      rewrites that.  If on the other hand, the rewriter can't decide
      whether [47ma'[0m is [47mnil[0m or not, it rewrites [47mb[0m to [47mb'[0m in an extended
      context in which [47ma'[0m is assumed non-[47mnil[0m and rewrites [47mc[0m to [47mc'[0m in
      an extended context in which [47ma'[0m is [47mnil[0m.  In rewriting both
      branches it preserves the outer equivalence relation -- the one
      to be maintained while rewriting the [47mIF[0m-term.  Then the
      rewriter returns [47m(IF a' b' c[0m').

    * If the term is a call of an arithmetic inequality, like [47m(< a b)[0m, the
      rewriter rewrites [47ma[0m and [47mb[0m and then considers whether the
      context allows it deduce the truth or falsity of the inequality
      using a [linear-arithmetic] decision procedure.  The decision
      procedure, which is complete for linear inequalities over the
      rationals, uses heuristics to decide many integer cases, to
      select the order in which inequalities are combined to
      eliminate variables, and to handle some [non-linear-arithmetic]
      problems.

    * If the term is a call of a function symbol, [47mfn[0m, on some argument
      terms, [47ma1[0m, ..., [47man[0m, the rewriter rewrites each argument, [47mai[0m to
      [47mai'[0m.  For each argument the rewriter uses known [47m:[0m[47m[congruence][0m
      rules to determine which equivalence relations can be used to
      rewrite terms in that argument position so as to maintain the
      outer equivalence.  Then, having transformed [47m(fn a1 ... an)[0m to
      [47m(fn a1' ... an[0m') the rewriter tries to apply [47m:[0m[47m[rewrite][0m rules
      to that transformed term, called the ``target.''.

    * Among the rewrite rules generally available for [47m(fn a1' ... an[0m') is
      the definition of [47mfn[0m itself.  The rewriter considers
      ``expanding'' the call, i.e., replacing it by the body of [47mfn[0m
      after substituting the [47mai'[0m for the formal variables, if the
      definition is [enable]d, and then rewriting that.  But
      heuristics are used to prevent the indefinite expansion of
      recursive definitions.

  For an elementary tutorial on the application of a [47m:[0m[47mrewrite[0m rule to a
  target term, see [introduction-to-rewrite-rules-part-1] and
  [introduction-to-rewrite-rules-part-2].  Those topics also lead to
  documentation on how to design effective rules.  But just to
  summarize very briefly, we offer the following.

  [47m:Rewrite[0m rules take the general form

    (implies (and hyp1 ... hypk) (equiv lhs rhs))

  where [47mequiv[0m is a known [equivalence] relation.  Recall that the
  rewriter has a target term to rewrite in some context and is
  required to return a term that is equivalent modulo a given
  equivalence relation, here called the ``outer'' equivalence.
  Furthermore, if the target term is a function application, e.g.,
  [47m(fn a1' ... an[0m'), the argument subterms have already been
  rewritten.

  If the rule in question is enabled and its [47mequiv[0m refines the outer
  equivalence, the rewriter tries to match [47mlhs[0m with the target.  By
  ``match'' we mean it tries to find a substitution for the variables
  in [47mlhs[0m that make the instantiated [47mlhs[0m identical to the target.  We
  discuss matching further below.  Second, having found a suitable
  substitution, tries to ``relieve'' the hypotheses, as discussed
  below.  If successful, that means each [47mhypi[0m, when instantiated with
  the substitution, is non-[47mnil[0m.  Third, if all the hypotheses are
  relieved, the target is ``replaced'' by the result of rewriting [47mrhs[0m
  under the substitution.  We discuss that step more below too.

  [31;1mMatching[0m: Technically, ACL2 uses a restriction of ordinary
  first-order unification -- the restriction being that only
  variables in the pattern (here the [47mlhs[0m of the rule) may be
  instantiated.  Thus, the pattern [47m(G x (H x))[0m matches [47m(G (M A B) (H
  (M A B)))[0m by binding [47mx[0m to [47m(M A B)[0m.  It does not match [47m(G (M A B) (H
  (M A A)))[0m even though those two terms ``unify'' by binding [47mx[0m to [47m(M
  A A)[0m and [47mB[0m to [47mA[0m.  Our pattern matcher is the function [47mone-way-unify[0m
  in our source code.

  However, our pattern matcher knows some things about the structure of
  quoted constants.  For example, the pattern [47m(CONS x y)[0m matches the
  quoted constant [47m'(A B C)[0m, by binding [47mx[0m to [47m'A[0m and [47my[0m to [47m'(B C)[0m.  This
  can be seen by running [47mone-way-unify[0m on those two terms:

    ACL2 !>(one-way-unify '(cons x y) ''(A B C))
    (T ((Y QUOTE (B C)) (X QUOTE A)))

  Note the quote marks in our input.  Since [47mone-way-unify[0m expects both
  of its arguments to be fully translated formal terms, we have to
  quote every constant we write here.  And since the arguments to
  [47mone-way-unify[0m are evaluated before the function is called, we have
  to quote the two terms.  We see that [47mone-way-unify[0m returns two
  results.  The first is [47mT[0m, meaning that a suitable substitution was
  found.  The second is the substitution.  Lisp's abbreviation
  convention for printed ``dotted pairs,'' its ``quote convention,''
  its convention of reading symbols in uppercase, and our convention
  here of writing terms (and variables) in lower case but constants
  in upper case, all conspire to make the substitution a little hard
  to read for novices.  Another way to display the exact same
  substitution is:

    ((y . '(B C)) (x . 'A))

  i.e., [47mx[0m is bound to [47m'A[0m and [47my[0m is bound to [47m(B C)[0m.

  Below are some other examples, but we've re-displayed the
  substitutions.

    ACL2 !>(one-way-unify '(coerce x 'string) ''\"Hello!\")
    (T ((x . (#H #e #l #l #o #!))))
    ACL2 !>(one-way-unify '(intern-in-package-of-symbol x y) ''ACL2::TEMP)
    (T ((y . 'TEMP) (x . '\"TEMP\")))
    ACL2 !>(one-way-unify '(binary-+ '3 x) ''7)
    (T ((X . '4)))
    ACL2 !>(one-way-unify '(unary-- x) ''-7)
    (T ((X QUOTE 7)))
    ACL2 !>(one-way-unify '(unary-- x) ''7)
    (NIL NIL)
    ACL2 !>(one-way-unify '(binary-* '2 y) ''8)
    (T ((Y QUOTE 4)))
    ACL2 !>(one-way-unify '(binary-* x y) ''8)
    (NIL NIL)

  Note that the pattern matching algorithm is incomplete on quoted
  constants!  For example, it fails to match [47m(unary-- x)[0m with [47m'7[0m even
  though [47m(unary-- '-7)[0m is [47m'7[0m.  It similarly fails to match [47m(binary-*
  x y)[0m with [47m'8[0m even though [47m(binary-* '33 '8/33)[0m is [47m8[0m; indeed, there
  are in infinite number of suitable substitutions for this case, but
  [47mone-way-unify[0m is designed to return at most one so as to limit the
  applicability of rewrite rules to ``reasonable'' cases.

  [31;1mRelieving the Hypotheses[0m: The hypotheses of a rewrite rule are
  relieved one at a time starting with the left-most one.  The basic
  strategy is just to rewrite each hypothesis, assuming the current
  context and if [47mIFF[0m equivalence relation.  If the result comes back
  non-[47mNIL[0m the hypothesis is equivalent to [47mT[0m in the current context.
  But there are various special considerations.

    * Free variables: It is possible that a hypothesis contains variables
      that are not bound by the substitution generated by the match.
      We call these ``free variables'' and the system tries to bind
      them to make the instantiated hypothesis appear among the
      contextual assumptions.  New bindings are accumulated as
      hypotheses are relieved.  It is possible to find multiple
      successful substitutions, some possibly filtered out by
      subsequent hypotheses.  See [47mfree-variables[0m and the
      documentation topics it cites.

    * Pragmas: It is possible to mark a hypothesis so that it is
      temporarily assumed true so that the rewrite rule can be
      applied.  This essentially spawns another subgoal to prove the
      hypothesis and thus brings the full power of the prover (not
      just the rewriter) to bear on the hypothesis.  See [47m[force][0m and
      [47m[case-split][0m.  It is also possible to include hypotheses that
      are logically always true but which cause the attempt to apply
      the rule to fail if a certain user-specified computation so
      indicates.  This can be used to restrict the application of a
      rule to certain syntactic situations.  See [47msyntaxp[0m.

  [31;1mReplacement[0m: Before the target is replaced by the rewritten [47mrhs[0m, a
  heuristic check is made to prevent certain trivial forms of rewrite
  loops.  See [47m[loop-stopper][0m.  Otherwise, if the hypotheses are
  relieved (or assumed), the rewriter rewrites [47mrhs[0m under the
  substitution generated by the match and the hypotheses.  It then
  makes certain heuristic checks to decide if replacing the target by
  this new term is a ``good idea'' in the opinion of the ACL2
  implementors.  The two main checks are designed to avoid runaway
  expansion of recursive functions (see [definition]), and
  introducing ``too many [47m[if][0ms'' (see [too-many-ifs].  The latter
  check is used to prevent unmanageable case explosions.  (In
  general, the number of cases rises exponentially with the number of
  [47mIF[0ms.)")
 (RASSOC
  (ALISTS ACL2-BUILT-INS)
  "Look up value in association list

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

  [47m(Rassoc x alist)[0m is the first member of [47malist[0m whose [47m[cdr][0m is [47mx[0m, or
  [47mnil[0m if no such member exists.  [47m(rassoc x alist)[0m is thus similar to
  [47m(assoc x alist)[0m, the difference being that it looks for the first
  pair in the given alist whose [47m[cdr][0m, rather than [47m[car][0m, is [47m[eql][0m to
  [47mx[0m.  See [assoc].  The optional keyword, [47m:TEST[0m, has no effect
  logically, but provides the test (default [47m[eql][0m) used for comparing
  [47mx[0m with the [47m[cdr][0ms of successive elements of [47mlst[0m.

  The [guard] for a call of [47mrassoc[0m depends on the test.  In all cases,
  the second argument must satisfy [47m[alistp][0m.  If the test is [47m[eql][0m,
  then either the first argument must be suitable for [47m[eql][0m (see
  [eqlablep]) or the second argument must satisfy [47m[r-eqlable-alistp][0m.
  If the test is [47m[eq][0m, then either the first argument must be a
  symbol or the second argument must satisfy [47m[r-symbol-alistp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mrassoc[0m and its variants:

      [47m(rassoc-eq x lst)[0m is equivalent to [47m(rassoc x lst :test 'eq)[0m;

      [47m(rassoc-equal x lst)[0m is equivalent to [47m(rassoc x lst :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mrassoc-equal[0m.

  [31;1mFunction: [0m<rassoc-equal>

    (defun rassoc-equal (x alist)
      (declare (xargs :guard (alistp alist)))
      (cond ((endp alist) nil)
            ((equal x (cdr (car alist)))
             (car alist))
            (t (rassoc-equal x (cdr alist)))))

  [47mRassoc[0m is defined by Common Lisp.  See any Common Lisp documentation
  for more information.")
 (RASSOC-EQ (POINTERS) "See [rassoc].")
 (RASSOC-EQUAL (POINTERS)
               "See [rassoc].")
 (RATIONAL-LISTP
  (NUMBERS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of rational numbers

  The predicate [47mrational-listp[0m tests whether its argument is a true
  list of rational numbers.

  [31;1mFunction: [0m<rational-listp>

    (defun rational-listp (l)
      (declare (xargs :guard t))
      (cond ((atom l) (eq l nil))
            (t (and (rationalp (car l))
                    (rational-listp (cdr l))))))")
 (RATIONALP
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for rational numbers (ratios and integers)

  [47m(rationalp x)[0m is true if and only if [47mx[0m is an rational number.")
 (RAW-LISP-ERROR
  (COMMON-LISP)
  "Raw lisp errors

  You may see a message about ``ABORTING from raw Lisp'' as in the
  following example.

    ACL2 !>(defun foo (x) (declare (xargs :mode :program)) (car x))

    Summary
    Form:  ( DEFUN FOO ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     FOO
    ACL2 !>(foo 3)

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Fault during read of memory address #x1D
    ***********************************************

    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)
    ACL2 !>

  The ``Error:'' message, ``Fault during read of memory address #x1D'',
  is printed by the host Common Lisp implementation.  In the example
  above, the function [47mfoo[0m has an implicit [guard] of [47mt[0m, which causes
  evaluation to invoke the Common Lisp function [47mcar[0m on argument [47m3[0m,
  resulting in the error.  This sort of error may occur when calling
  a [47m:[0m[47m[program][0m mode function, because the guard hasn't been verified.
  See [defun-mode-caveat] for a discussion of the possibility that
  ACL2 is rendered unsound by a raw Lisp error.  For further relevant
  background, see [evaluation].

  Calls of [47m:program[0m mode functions are not the only sources of raw Lisp
  errors.  Here is a non-exhaustive list of some such sources.

    * Calls of [47m:program[0m mode functions

    * Calls of [47m:logic[0m mode functions whose [guard]s were verified using
      [47m[skip-proofs][0m

    * Resource errors, e.g., when attempting to evaluate [47m(expt 2 (expt 2
      1000000))[0m.  (We have seen raw Lisp errors when evaluating that
      expression in ACL2 built on host Lisps CCL, SBCL, and Allegro
      CL.)

    * Illegal calls of certain functions and macros with special ``under
      the hood'' raw Lisp code, such as [47m[read-file-into-string][0m and
      [47m[return-last][0m

    * [47m[Defattach][0m using argument [47m:skip-checks t[0m

    * Reader errors (for examples see [reader] and see [set-iprint])")
 (RAW-MODE (POINTERS)
           "See [set-raw-mode].")
 (READ-ACL2-ORACLE
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Pop the oracle field of the state

  ACL2 has a mutable `state' that contains a number of fields; see
  [state].  One of these fields is a list, called the [47macl2-oracle[0m
  field.  There are no constraints on the elements of this list;
  thus, you will not be able to prove anything about those elements.
  However, as a convenience, ACL2 permits you to evaluate the form
  [47m(read-acl2-oracle state)[0m, which returns the multiple value [47m(mv nil
  nil state)[0m.

  The ACL2 implementation uses [47mread-acl2-oracle[0m, but you will likely
  find this function to be useless unless you do advanced, scurrilous
  things using trust tags (see [47m[defttag][0m).

  The following definition is the logical definition of
  [47mread-acl2-oracle[0m, but as explained above does not really
  characterize its behavior under the hood.

  [31;1mFunction: [0m<read-acl2-oracle>

    (defun read-acl2-oracle (state-state)
      (declare (xargs :guard (state-p1 state-state)))
      (mv (null (acl2-oracle state-state))
          (car (acl2-oracle state-state))
          (update-acl2-oracle (cdr (acl2-oracle state-state))
                              state-state)))")
 (READ-BYTE$ (POINTERS) "See [io].")
 (READ-CHAR$ (POINTERS) "See [io].")
 (READ-FILE-INTO-STRING
  (IO)
  "The contents of a file (or part of it) as a string

  When this macro is passed a valid filename and the ACL2 [state], it
  generally returns the contents of the file (or a specified part of
  the file) as a string.  Otherwise, it returns [47mnil[0m or causes an
  error.  Unlike other ACL2 functions for reading a file, this one
  does not return the ACL2 [47mstate[0m, and it is generally much faster.

    Example Forms:

    (read-file-into-string \"foo.lisp\")
    (read-file-into-string \"foo.lisp\" :start 0 :bytes nil) ; same as above
    (read-file-into-string \"foo.lisp\" :start 20000 :bytes 10000)
    (read-file-into-string \"foo.lisp\" :start 20000 :bytes 10000 :close t)

    General Form:

    (read-file-into-string filename ; a filename relative to the current directory
                           :start s ; default 0
                           :bytes b ; default nil
                           :close c ; default :default
                           )

  where [47mfilename[0m is a string, which is typically the name of a file,
  and the keyword argument are optional and evaluated, as follows: [47ms[0m
  has default [47m0[0m and its value is a natural number (except, an error
  occurs if that number exceeds the length of the given file), [47mb[0m has
  default [47mnil[0m and its value is either a natural number or [47mnil[0m, and [47mc[0m
  has default [47m:default[0m and its value is otherwise considered to be
  false (when [47mnil[0m) or true (when not [47mnil[0m).

  For examples, see [community-books] file
  [47mbooks/system/tests/read-file-into-string.lisp[0m.

  The result, when not [47mnil[0m or an error, is a string representing the
  specified file contents.  For the default of [47m:start 0[0m and [47m:bytes
  nil[0m, or equivalently, when no keyword arguments are specified, the
  entire file contents are returned as a string.  In general, [47m:start
  s[0m specifies the part of the file starting at byte position [47ms[0m of the
  file, and [47m:bytes b[0m specifies that only the first [47mb[0m bytes are to be
  read starting at that position --- however, stopping at the end of
  the file if [47mb+s[0m exceeds the length [47mL[0m of the file.  Below we call
  this case that [47mb+s>L[0m the ``truncation case''.

  Note that ACL2 characters always fit into a single byte, which is why
  we can talk about ``bytes'' here.

  The [47m:close[0m argument affects handling of the Lisp stream that is
  created for the specified file.  When the value of [47m:close[0m is the
  default, [47m:default[0m, this stream is closed immediately after the read
  exactly when either [47m:bytes[0m has value [47mnil[0m (the default) or we are in
  the truncation case [47mb+s>L[0m described above.  But otherwise the
  stream remains open, which could cause a problem since operating
  systems can complain when too many streams are open at the same
  time.  If the value of [47m:bytes[0m is non-[47mnil[0m (hence, a natural number),
  then you may want to specify [47m:close t[0m to prevent that problem,
  unless you plan to read more bytes from the same file.  If you
  decide to close the file later, this can be accomplished
  efficiently by evaluating the following form for your file,
  [47m\"<file>\"[0m.

    (time$ (read-file-into-string \"<file>\" :start 0 :bytes 0 :close t))

  Compared with the usual [io] routines provided by ACL2,
  [47mread-file-into-string[0m is generally much more efficient, and also it
  does not return [47m[state][0m.  Note that the expansion of a call of this
  macro takes [47mstate[0m as an argument; so if you call it in the body of
  a function definition, then --- as usual for functions that take
  [47mstate[0m --- either [47m(set-state-ok t)[0m must have been evaluated or else
  a suitable [47m:stobjs[0m declaration, typically [47m:stobjs state[0m, must be
  provided (see [xargs]).

  The constant [47m*read-file-into-string-bound*[0m (see the definition below)
  establishes a strict upper bound on the size of the string
  returned.  If the file (or specified portion thereof) contains more
  bytes than this, then [47mnil[0m is returned.

  There are two checks to guarantee that [47mread-file-into-string[0m is truly
  a function --- that is, it returns the same value for two calls
  with the same inputs.  The primary check ensures that the write
  date of the file has not changed in the interval between two such
  calls unless the [47mfile-clock[0m component of the ACL2 state has been
  updated within that interval.  That update takes place when an
  input or output channel is opened or closed in the usual way (that
  is, using [47mopen-input-channel[0m, [47mopen-output-channel[0m,
  [47mclose-input-channel[0m, or [47mclose-output-channel[0m; see [io]).  However,
  it suffices to evaluate the following form, which returns the
  [47m[state][0m obtained by incrementing its [47mfile-clock[0m.

    (increment-file-clock state)

  If however you make illegal successive reads as described above, a
  Lisp error will occur with a message of the following form.

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Illegal consecutive reads from file
    \"<some_filename>\",
    which appears to have been written between the two reads.
    Execute (INCREMENT-FILE-CLOCK STATE) to avoid this error.
    See :DOC read-file-into-string.
    While executing: READ-FILE-INTO-STRING2
    ***********************************************

  A similar error may occur when a call of [47mread-file-into-string[0m is
  followed by a call of [47m[open-input-channel][0m on the same filename
  when that file is modified between the two calls.  For low-level
  details about logical issues being addressed by such errors, see
  the comment in the definition of [47m*read-file-into-string-alist*[0m in
  the ACL2 sources.

  The other check ensures that the write date of the file has not
  changed while a call is in progress.  When that check fails the
  corresponding Lisp error is of the following form.

    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Illegal attempt to call READ-FILE-INTO-STRING concurrently
    with some write to that file!  See :DOC read-file-into-string.
    ***********************************************

  We close by showing the relevant ACL2 definitions in the logic, that
  is, not including the special raw Lisp (under the hood) code in the
  definition of [47mread-file-into-string2[0m.

  [31;1mFunction: [0m<read-file-into-string1>

    (defun read-file-into-string1 (channel state ans bound)
     (declare (xargs :stobjs state
                     :guard (and (symbolp channel)
                                 (open-input-channel-p channel
                                                       :character state)
                                 (character-listp ans)
                                 (natp bound))))
     (cond
      ((zp bound) (mv nil state))
      (t (mv-let (val state)
                 (read-char$ channel state)
           (cond ((not (characterp val))
                  (mv (coerce (reverse ans) 'string)
                      state))
                 (t (read-file-into-string1 channel state (cons val ans)
                                            (1- bound))))))))

  [31;1mDefinition: [0m<*read-file-into-string-bound*>

    (defconst *read-file-into-string-bound*
      (1- (ash 1 60)))

  [31;1mFunction: [0m<read-file-into-string2-logical>

    (defun read-file-into-string2-logical (filename start bytes state)
     (declare (xargs :stobjs state
                     :guard (and (stringp filename)
                                 (natp start)
                                 (or (null bytes) (natp bytes)))))
     (non-exec
       (mv-let
        (erp val state)
        (mv-let (chan state)
                (open-input-channel filename
                                    :character state)
          (cond ((or (null chan) (not (state-p state)))
                 (mv nil nil state))
                (t (mv-let (val state)
                           (read-file-into-string1
                                chan
                                state nil *read-file-into-string-bound*)
                     (pprogn (ec-call (close-input-channel chan state))
                             (mv nil val state))))))
        (declare (ignore erp state))
        (and (stringp val)
             (<= start (length val))
             (subseq val start
                     (if bytes (min (+ start bytes) (length val))
                       (length val)))))))

  [31;1mFunction: [0m<read-file-into-string2>

    (defun read-file-into-string2 (filename start bytes close state)
      (declare (xargs :stobjs state
                      :guard (and (stringp filename)
                                  (natp start)
                                  (or (null bytes) (natp bytes))))
               (ignore close))
      (read-file-into-string2-logical filename start bytes state))

  [31;1mMacro: [0m<read-file-into-string>

    (defmacro read-file-into-string (filename &key (start '0)
                                              bytes (close ':default))
      (cons 'read-file-into-string2
            (cons filename
                  (cons start
                        (cons bytes (cons close '(state)))))))")
 (READ-OBJECT (POINTERS) "See [io].")
 (READ-OBJECT-SUPPRESS (POINTERS)
                       "See [io].")
 (READ-OBJECT-WITH-CASE (POINTERS)
                        "See [io].")
 (READ-RUN-TIME
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Read elapsed runtime

  By default, [47m(read-run-time state)[0m returns [47m(mv cpu-time state)[0m, where
  [47mcpu-time[0m is the elapsed cpu time in seconds since the start of the
  current ACL2 session and [47mstate[0m is the resulting ACL2 [state].
  Thus, [47m(read-run-time state)[0m is, by default, equivalent to
  [47m(get-cpu-time state)[0m.  But [47mread-run-time[0m can be made to return
  elapsed real time (wall clock time) instead, thus making it
  equivalent to [47m(get-real-time state)[0m.  Note that time is returned in
  seconds in all of these cases.

  To specify that [47mread-run-time[0m shall use cpu time or real time:

    (assign get-internal-time-as-realtime t)   ; use real time
    (assign get-internal-time-as-realtime nil) ; use cpu time

  See [get-internal-time] for more discussion of cpu time vs. real
  time.  In both cases, the precision depends on the host Common
  Lisp; for example, in CCL as of this writing, the result is
  accurate to the microsecond.

  The logical definition probably won't concern many users, but for
  completeness, we say a word about it here.  That definition uses
  the function [47m[read-ACL2-oracle][0m, which modifies [state] by popping
  the value to return from its acl2-oracle field.

  [31;1mFunction: [0m<read-run-time>

    (defun read-run-time (state-state)
      (declare (xargs :guard (state-p1 state-state)))
      (mv (cond ((or (null (acl2-oracle state-state))
                     (not (rationalp (car (acl2-oracle state-state)))))
                 0)
                (t (car (acl2-oracle state-state))))
          (update-acl2-oracle (cdr (acl2-oracle state-state))
                              state-state)))

  Note that logically [47m(read-run-time state)[0m, [47m(get-real-time state)[0m, and
  [47m(get-cpu-time state)[0m are all equal (defined using the acl2-oracle),
  so for example ACL2 succeeds in the proof of [47m(thm (equal
  (get-real-time state) (get-cpu-time state)))[0m, even though the first
  returns elapsed real time and the second returns elapsed cpu time.
  However, there is no contradiction: either way, we are logically
  just reading the oracle of [47mstate[0m.  In the ACL2 loop, successive
  calls of [47m(get-real-time state)[0m and [47m(get-cpu-time state)[0m would be
  operating on different values of [47mstate[0m (because their oracles
  differ).


Subtopics

  [Get-cpu-time]
      Read elapsed cpu time

  [Get-real-time]
      Read elapsed real time")
 (READER
  (MISCELLANEOUS)
  "Reading expressions in the ACL2 read-eval-print loop

  The ACL2 read-eval-print loop reads expressions much like they are
  read in any Common Lisp read-eval-print loop.  For example, you may
  use the single tick symbol ([47m'[0m) for [47mquote[0m and also the backquote
  symbol ([47m`[0m) with its escapes, comma ([47m,[0m) and comma-atsign ([47m,@[0m).  See
  any Common Lisp reference or tutorial.

  ACL2-specific reader macros include its reading of expressions in a
  specified package (using [47m#![0m --- see [sharp-bang-reader]), its
  restriction of read-time evaluation to constants introduced by
  [47m[defconst][0m (using [47m#.[0m --- see [sharp-dot-reader]), and the ability
  to put underscores in numeric constants (using [47m#u[0m --- see
  [sharp-u-reader]).

  See [set-iprint] for how to make ACL2 print expressions like [47m#@2#[0m
  that can be read back in.

  Strictly speaking, there is nothing special about how the reader
  handles [keyword]s in the input.  But see [keyword-commands] for
  how ACL2 may interpret a top-level keyword command.

  We conclude this topic with a log that illustrates features discussed
  above.  Comments of the form [47m{{..}}[0m have been inserted manually.

    ACL2 !>(defconst *c* (+ 3 4))

    Summary
    Form:  ( DEFCONST *C* ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     *C*
    ACL2 !>'(a #.*c* 17)
    ;{{See :doc sharp-dot-reader.
    ;  Notice that #.*c* is read as the value of *c*, thus,
    ;  as 7 rather than as (+ 3 4).}}
    (A 7 17)
    ACL2 !>'(a #.(+ 5 6) 17)
    ;{{But this is not legal in ACL2, as #. must be followed by
    ;  a known constant symbol.}}

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  ACL2 supports #. syntax only for #.*a*, where *a* has been
    defined by DEFCONST.  Thus the form #.(+ 5 6) is illegal.
    ***********************************************

    ;{{Additional output here has been omitted in this log.}}
    ACL2 !>(defpkg \"FOO\" nil)

    Summary
    Form:  ( DEFPKG \"FOO\" ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     \"FOO\"
    ACL2 !>#!foo'(a b c)
    ;{{See :doc sharp-bang-reader.  The prefix \"#!foo\" causes
    ;  the s-expression after it to be read into the \"FOO\" package.}}
    (FOO::A FOO::B FOO::C)
    ACL2 !>#x100a
    ;{{As in Common Lisp, \"#x\" causes the digits after it to be read in hex.}}
    4106
    ACL2 !>#ux10_0a
    ;{{The \"#u\" prefix allows underscores in the numeral after it.  Those
    ;  underscores are ignored, but can improve readability.}}
    4106
    ACL2 !>(set-iprint t)
    ;{{See :DOC set-print.  This causes \"#@1#\" below to be printed.}}

    ACL2 Observation in SET-IPRINT:  Iprinting has been enabled.
    ACL2 !>(set-evisc-tuple (evisc-tuple 3   ; print-level
                                         4   ; print-length
                                         nil ; alist
                                         nil ; hiding-cars
                                         )
                            :sites :ld)
    ;{{Abbreviate the printing of top-level evaluation results.
    ;  See :doc set-evisc-tuple.}}
     (:LD)
    ACL2 !>(make-list 10)
    (NIL NIL NIL NIL . #@1#)
    ACL2 !>'#@1#
    ;{{Note that the reader replaces #@1# with the value that was stored there.}}
    (NIL NIL NIL NIL . #@2#)
    ACL2 !>(without-evisc '(NIL NIL NIL NIL . #@1#))
    ;{{See :doc without-evisc.}}
    (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)
    ACL2 !>(set-evisc-tuple nil :sites :ld)
     (:LD)
    ACL2 !>(let ((x '(3 4)))
             `(a b ,x c))
    ;{{As in Common Lisp, backquote can be escaped by comma.}}
    (A B (3 4) C)
    ACL2 !>(let ((x '(3 4)))
             `(a b ,@x c))
    ;{{As in Common Lisp, backquote can be escaped by comma-atsign, which
    ;  splices its value into the list.}}
    (A B 3 4 C)
    ACL2 !>


Subtopics

  [Backquote]
      Variant of quotation introducing templates for data structures

  [Fancy-string-reader]
      A friendly syntax for strings literals that have backslashes and
      quotes.

  [Sharp-bang-reader]
      Package prefix that is not restricted to symbols

  [Sharp-d-reader]
      Read a rational number as a representable rational (see [df])

  [Sharp-dot-reader]
      Read-time evaluation of constants

  [Sharp-f-reader]
      Read a rational number in floating-point syntax

  [Sharp-u-reader]
      Allow underscore characters in numbers")
 (REAL
  (ACL2)
  "ACL2(r) support for real numbers

  ACL2 supports rational numbers but not real numbers.  However,
  starting with Version 2.5, a variant of ACL2 called ``ACL2(r)''
  supports the real numbers by way of non-standard analysis.  ACL2(r)
  was conceived and first implemented by Ruben Gamboa in his Ph.D.
  dissertation work, supervised by Bob Boyer with active
  participation by Matt Kaufmann.

  ACL2(r) has the same source files as ACL2.  After you download ACL2,
  you can build ACL2(r) by executing the following command on the
  command line in your acl2-sources directory, replacing [47m<your_lisp>[0m
  with a path to your Lisp executable:

    make large-acl2r LISP=<your_lisp>

  This will create an executable in your acl2-sources directory named
  [47msaved_acl2r[0m.

  Note that if you have fetched the [community-books], then you will
  already have the books to be certified with ACL2(r).  They can be
  certified from your acl2-sources directory, shown here as [47m<DIR>[0m:

    make regression ACL2=<DIR>/saved_acl2r

  To check that you are running ACL2(r), see if the prompt includes the
  string ``[47m(r)[0m'', e.g.:

    ACL2(r) !>

  Or, look at [47m(@ acl2-version)[0m and see if ``[47m(r)[0m'' is a substring.

  In ACL2 (as opposed to ACL2(r)), when we say ``real'' we mean
  ``rational.''

  Caution: ACL2(r) should be considered experimental: although we
  (Kaufmann and Moore) have carefully completed Gamboa's integration
  of the reals into the ACL2 source code, our primary concern has
  been to ensure unchanged behavior when ACL2 is compiled in the
  default manner, i.e., without the non-standard extensions.  As for
  every release of ACL2, at the time of a release we are unaware of
  soundness bugs in ACL2 or ACL2(r).

  There is only limited documentation on the non-standard features of
  ACL2(r).  We hope to provide more documentation for such features
  in future releases.  Please feel free to query the authors if you
  are interested in learning more about ACL2(r).  Gamboa's
  dissertation may also be helpful.

  ACL2(r) does not currently support the [useless-runes] feature.


Subtopics

  [I-close]
      ACL2(r) test for whether two numbers are infinitesimally close

  [I-large]
      ACL2(r) recognizer for infinitely large numbers

  [I-limited]
      ACL2(r) recognizer for limited numbers

  [I-small]
      ACL2(r) recognizer for infinitesimal numbers

  [Real-listp]
      ACL2(r) recognizer for a true list of real numbers

  [Standard-part]
      ACL2(r) function mapping limited numbers to standard numbers

  [Standardp]
      ACL2(r) recognizer for standard objects")
 (REAL-LISTP
  (REAL LISTS ACL2-BUILT-INS)
  "ACL2(r) recognizer for a true list of real numbers

  The predicate [47mreal-listp[0m tests whether its argument is a true list of
  real numbers.  This predicate is only defined in ACL2(r) (see
  [real]).")
 (REAL/RATIONALP
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for rational numbers (including real number in ACL2(r))

  For most ACL2 users, this is a macro abbreviating [47m[rationalp][0m.  In
  ACL2(r) (see [real]), this macro abbreviates the predicate [47mrealp[0m,
  which holds for real numbers as well (including rationals).  Most
  ACL2 users can ignore this macro and use [47m[rationalp][0m instead, but
  many community books use [47mreal/rationalp[0m so that these books will be
  suitable for ACL2(r) as well.")
 (REALFIX
  (NUMBERS ACL2-BUILT-INS)
  "Coerce to a real number

  [47mRealfix[0m simply returns any real number argument unchanged, returning
  [47m0[0m on a non-real argument.  Also see [nfix], see [ifix], see [rfix],
  and see [fix] for analogous functions that coerce to a natural
  number, an integer, a rational, and a number, respectively.

  [47mRealfix[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<realfix>

    (defun realfix (x)
      (declare (xargs :guard t))
      (if (real/rationalp x) x 0))")
 (REALPART
  (NUMBERS ACL2-BUILT-INS)
  "Real part of a complex number

  Completion Axiom ([47mcompletion-of-realpart[0m):

    (equal (realpart x)
           (if (acl2-numberp x)
               (realpart x)
             0))

  [Guard] for [47m(realpart x)[0m:

    (acl2-numberp x)")
 (REBUILD
  (LD)
  "A convenient way to reconstruct your old [state]

    Examples:
    ACL2 !>(rebuild \"project.lisp\")
    ACL2 !>(rebuild \"project.lisp\" t)
    ACL2 !>(rebuild \"project.lisp\" t :dir :system)
    ACL2 !>(rebuild \"project.lisp\" :all)
    ACL2 !>(rebuild \"project.lisp\" :query)
    ACL2 !>(rebuild \"project.lisp\" 'lemma-22)

  [47mRebuild[0m allows you to assume all the [command]s in a given file or
  list, supplied in the first argument.  Because [47mrebuild[0m processes an
  arbitrary sequence of [command]s with [47m[ld-skip-proofsp][0m [47mt[0m, it is
  unsound!  However, if each of these [command]s is in fact
  admissible, then processing them with [47mrebuild[0m will construct the
  same logical [state] that you would be in if you typed each
  [command] and waited through the proofs again.  Thus, [47mrebuild[0m is a
  way to reconstruct a [state] previously obtained by proving your
  way through the [command]s.

  The second, optional argument to [47mrebuild[0m is a ``filter'' (see
  [ld-pre-eval-filter]) that lets you specify which [command]s to
  process.  You may specify [47mt[0m, [47m:all[0m, [47m:query[0m, or a new logical name.
  [47mt[0m and [47m:all[0m both mean that you expect the entire file or list to be
  processed.  [47m:query[0m means that you will be asked about each
  [command] in turn.  A new name means that all [command]s will be
  processed as long as the name is new, i.e., [47mrebuild[0m will stop
  processing [command]s immediately after executing a [command] that
  introduces name.  [47mRebuild[0m will also stop if any [command] causes an
  error.  You may therefore wish to plant an erroneous form in the
  file, e.g., [47m(mv t nil state)[0m, (see [ld-error-triples]), to cause
  [47mrebuild[0m to stop there.  The form [47m(i-am-here)[0m is such a pre-defined
  form.  If you do not specify a filter, [47mrebuild[0m will query you for
  one.

  Inspection of the definition of [47mrebuild[0m, e.g., via [47m:[0m[47m[pc][0m [47mrebuild-fn[0m,
  will reveal that it is just a glorified call to the function [47m[ld][0m.
  See [ld] if you find yourself wishing that [47mrebuild[0m had additional
  functionality.

  If you supply the above ``filter'' argument, then you may also supply
  the keyword argument [47m:dir[0m, which is then passed to [47mld[0m; see [ld].")
 (RECURSION-AND-INDUCTION
  (DOCUMENTATION ACL2 ABOUT-ACL2)
  "Recursion and Induction


Recursion and Induction


Preface and Acknowledgments

  These notes are for teaching yourself how to prove theorems about
  recursively defined functions using mathematical induction.  Think
  of this as a college-level practical math course that just happens
  to focus on issues of concern in computing.  We assume you're
  passingly familiar with notions from formal mathematical logic,
  like ``axioms'' and ``rules of inference'' (like instantiation and
  substitution of equals for equals) to derive ``new'' truths from
  ``old'' ones.  We describe a very simple logical system and present
  many exercises for you to do.

  Our presentation is less formal than formal logicians would expect,
  and the ``proofs'' we expect of you would be considered just
  ``proof sketches'' by formal logicians.  But we believe we're
  precise enough that if you follow our rules your ``proofs'' could
  be turned into formal proofs in conventional first-order
  mathematical logic.

  Unlike a traditional course in logic, we do not focus on metatheory
  but on lots of proofs about elementary algorithms expressed
  recursively.  It helps if you're familiar with computer programming
  because our logic is a subset of the programming language Lisp and
  the exercises involve conjectures about simple list processing
  algorithms like member, union, reverse, etc.  We do not assume
  prior familiarity with Lisp.

  In fact, the logic is a subset of the mechanized logic of the ACL2
  system. ACL2 stands for ``A Computational Logic for Applicative
  Common Lisp'' and the ACL2 system includes a programming language
  and an ``automatic'' theorem prover.  But this is not a course in
  mechanical theorem proving or how to use ACL2.  In fact, we
  recommend that you not use the ACL2 system while doing these
  exercises.  A good way to learn to use ACL2 --- or any of today's
  mechanical proof systems --- is to learn to do proofs by hand.  It
  will teach you how to define functions that are convenient to
  analyze, how to state inductively provable theorems, how to
  decompose theorems into simpler ``lemmas'', and how to simplify
  terms using previously proved results.

  If your goal is to learn to prove theorems about recursively defined
  functions, work your way through these notes and do the exercises.
  It can help if you partner with someone else so you have someone to
  double-check your proofs.  If your goal is learn to use the ACL2
  system to prove theorems, we recommend that you start exactly the
  same way: work through these exercises by hand (ideally, all of
  them).  Only then should you fire up the prover and try to use it
  to prove the same theorems you've proved by hand.  It will be
  educational.  The ACL2 system is a [3mvery[0m attentive partner.

  Our answers to all the exercises are available in the Answer Key,
  which may be found in the [community-books], file
  [47mdemos/r-and-i-answer-key-log.txt[0m.  We urge you not to refer to the
  Answer Key except as a last resort (and, of course, to check your
  answers).  That file is generated by ACL2 and has a certain amount
  of unavoidable boilerplate in it.  You should read the Lisp comment
  at the top of the file for instructions on how to explore and
  interpret the file.

  This document started as course notes for [3mCS389R Recursion and
  Induction[0m, in the Department of Computer Science of the University
  of Texas at Austin.  The course was created in 1981 by Robert S.
  Boyer and J Strother Moore.  It has been offered almost every year
  since 1981, taught by Boyer, Moore, or Warren A. Hunt, Jr.
  Initially, the course used a subset of the logic of the Nqthm
  theorem prover [0], but around 2000 it was changed to a subset of
  the logic of the ACL2 prover [1,2,4].  (See
  [r-and-i-annotated-bibliography] for an annotated bibliography that
  elaborates references in square brackets, such as ``[0]''.)
  Mechanical theorem proving tools were not taught or used in the
  course.

  In the early 1980s, when Boyer and Moore co-taught the course, the
  logic was presented in a bare-bones style in a few pages.  Several
  more pages listed problems for the students to work on.  Students
  were expected to formalize concepts and come to the blackboard and
  present definitions and proofs.  Their classmates were expected to
  question and critique what was being said.  Often these classroom
  discussions just raised new problems that the students addressed in
  subsequent class meetings.

  Over time, the course notes were expanded to include explanations,
  examples, and more problems.  Moore wrote the first version of this
  ACL2-based document in the early 2000s, building on joint work with
  Matt Kaufmann.  That document was edited still further by Kaufmann,
  Moore, and Hunt after Hunt began teaching the course in 2004.  In
  2022, Kaufmann converted it from LaTeX pdf to the hypertext format
  of ACL2's online documentation and tied it into ACL2's
  documentation.

  Finally, we thank the many sponsors and supporters of the Nqthm and
  ACL2 projects over the last 40 years, as well as the many students
  who have so carefully studied and corrected these notes and the
  many users of Nqthm and ACL2.  See the ACL2 [Acknowledgments] page.

  Next: Introduction (see [R-AND-I-INTRODUCTION]) (or Table of Contents
  (see [R-AND-I-TABLE-OF-CONTENTS]))


Subtopics

  [R-and-i-introduction]
      Recursion and Induction: Introduction

  [R-and-i-data-types]
      Recursion and Induction: Data Types

  [R-and-i-terms]
      Recursion and Induction: Terms

  [R-and-i-substitutions]
      Recursion and Induction: Substitutions

  [R-and-i-abbreviations-for-terms]
      Recursion and Induction: Abbreviations for Terms

  [R-and-i-function-definitions]
      Recursion and Induction: Function Definitions

  [R-and-i-axioms]
      Recursion and Induction: Axioms

  [R-and-i-terms-as-formulas]
      Recursion and Induction: Terms as Formulas

  [R-and-i-definitions-revisited]
      Recursion and Induction: Definitions Revisited

  [R-and-i-structural-induction]
      Recursion and Induction: Structural Induction

  [R-and-i-arithmetic]
      Recursion and Induction: Arithmetic

  [R-and-i-inadequacies-of-structural-recursion]
      Recursion and Induction: Inadequacies of Structural Recursion

  [R-and-i-ordinals]
      Recursion and Induction: The Ordinals

  [R-and-i-definitional-principle]
      Recursion and Induction: The Definitional Principle

  [R-and-i-induction-principle]
      Recursion and Induction: The Induction Principle

  [R-and-i-relations-between-recursion-and-induction]
      Recursion and Induction: Relations Between Recursion and Induction

  [R-and-i-more-problems]
      Recursion and Induction: More Problems

  [R-and-i-more-inadequacies-of-the-definitional-principle]
      Recursion and Induction: More Inadequacies of the Definitional
      Principle

  [R-and-i-still-more-problems]
      Recursion and Induction: Still More Problems

  [R-and-i-annotated-bibliography]
      Recursion and Induction: Annotated Bibliography

  [R-and-i-table-of-contents]
      Recursion and Induction Table of Contents)")
 (RECURSIVEP (POINTERS)
             "See [system-utilities].")
 (REDEF
  (LD)
  "A common way to set [ld-redefinition-action]

    Example and General Form:
    ACL2 !>:redef

  This command sets [47m[ld-redefinition-action][0m to [47m'(:query . :overwrite)[0m.

  This command allows redefinition of functions and other [events]
  without undoing, but with a query that requires the user to
  acknowledge that the redefinition is intentional.  To avoid that
  query, see [redef!].  For more options and an important warning
  about the danger of using redefinition, including possible
  unsoundness, see [ld-redefinition-action].")
 (REDEF!
  (LD)
  "A common way to set [ld-redefinition-action]

    Example and General Form:
    ACL2 !>:redef!

  This command sets [47m[ld-redefinition-action][0m to [47m'(:warn!  .
  :overwrite)[0m.

  This command allows redefinition of functions and other [events]
  without undoing, but with a warning.  The command [47m:[0m[47m[redef][0m is
  similar, but queries the user first before doing the redefinition.
  For more options and an important warning about the danger of using
  redefinition, including possible unsoundness, see
  [ld-redefinition-action].")
 (REDEF+
  (LD)
  "System hacker's redefinition [command]

    Example and General Form:
    ACL2 !>:redef+
    ACL2 p!>

  This [command] is intended only for system hackers, not typical
  users.  It sets [47m[ld-redefinition-action][0m to [47m'(:warn! . :overwrite)[0m,
  sets the default [defun-mode] to [47m:[0m[47m[program][0m, and invokes
  [47m[set-state-ok][0m with value [47mt[0m.  It also introduces [47m(defttag :redef+)[0m,
  so that redefinition of system functions will be permitted; see
  [defttag].  It also removes as untouchable (see [push-untouchable])
  all variables and functions.

  WARNING: This command is potentially unsafe and even unsound!  For a
  relevant warning about redefinition, see [ld-redefinition-action].
  Moreover, if the form [47m(redef+)[0m is used in a book, then including
  the book can leave you in a state in which dangerous actions are
  allowed, specifically: redefinition, and access to functions and
  variables normally prohibited because they are untouchable.  To
  avoid this problem, insert the form [47m([0m[47m[redef-][0m[47m)[0m into your book after
  [47m(redef+)[0m.

  Note that undoing a [47m:redef+[0m command, say with [47m:[0m[47m[u][0m, only undoes the
  effects of [47m:redef+[0m on the ACL2 [world]; it does [3mnot[0m undo the other
  effects on the ACL2 [state].  The best way to undo the effects of
  [47m:redef+[0m is generally to execute [47m:[0m[47m[redef-][0m.  To understand this
  point we look at the code for [47mredef+[0m.  The output below has been
  edited to put world-changing parts in lower case.

    ACL2 !>:trans1 (redef+)
     (WITH-OUTPUT
          :OFF (SUMMARY EVENT)
          (PROGN (defttag :redef+)
                 (PROGN! (SET-LD-REDEFINITION-ACTION '(:WARN! . :OVERWRITE)
                                                     STATE)
                         (program)
                         (SET-TEMP-TOUCHABLE-VARS T STATE)
                         (SET-TEMP-TOUCHABLE-FNS T STATE)
                         (F-PUT-GLOBAL 'REDUNDANT-WITH-RAW-CODE-OKP
                                       T STATE)
                         (set-state-ok t))))
    ACL2 !>

  In particular, we see that redefinition remains active after undoing.
  In general, it is therefore best to execute [47m:redef-[0m before undoing
  [47m:redef+[0m.

  This [command] was introduced to support modification of ACL2 source
  code definitions.  Thus, note that even system functions can be
  redefined with a mere warning.  Be careful!")
 (REDEF-
  (LD)
  "Turn off system hacker's redefinition [command]

    Example and General Form:
    ACL2 !>:redef-
    ACL2 p!>

  This macro, for system hackers only, is a convenient way to reverse
  the effects of [47m:redef+[0m.  See [redef+].  We do not guarantee that
  [47m:redef-[0m will restore everything one might expect to its state
  before the earlier [47m:redef+[0m.  To see exactly what [47m:redef-[0m does, look
  at its code, for example by evaluating [47m:trans1 (redef-)[0m")
 (REDEFINE (POINTERS)
           "See [ld-redefinition-action].")
 (REDEFINED-NAMES
  (WORLD)
  "To collect the names that have been redefined

    Example and General Forms:
    (redefined-names state)

  This function collects names that have been redefined in the current
  ACL2 [state].  [47m:[0m[47m[Program][0m mode functions that were reclassified to
  [47m:[0m[47m[logic][0m functions are not collected, since such reclassification
  cannot imperil soundness because it is allowed only when the new
  and old definitions are identical.

  Thus, if [47m(redefined-names state)[0m returns [47mnil[0m then no unsafe
  definitions have been made, regardless of [47m[ld-redefinition-action][0m.
  See [ld-redefinition-action].

  WARNING: This function does not report names that are not explicitly
  redefined in the current logical [world].  Consider for example:

    (encapsulate
     ()
     (defun foo () t)
     (local (defun foo () nil))
     (defthm foo-prop
       (equal (foo) nil)
       :rule-classes nil))

  If you attempt to call [47m[certify-book][0m in the resulting world, ACL2
  will appropriately refuse to do the certification:

    ACL2 Error in (CERTIFY-BOOK \"foo\" ...):  At least one command in the
    current ACL2 world was executed while the value of state global variable
    'LD-REDEFINITION-ACTION was not nil:

      (DEFUN FOO NIL T)

    Certification is therefore not allowed in this world.  You can use
    :ubt to undo back through this command; see :DOC ubt.

  However, since the local redefinition of [47mfoo[0m is gone in the
  certification world, [47m(redefined-names state)[0m will return [47mnil[0m.
  (Technical aside, to be ignored except for those interested in
  implementation details: ACL2 inhibits [47mcertify-book[0m in this example
  because the definition of [47mfoo[0m is the value of [47m(global-val
  'redef-seen (w state))[0m.)")
 (REDEFINING (POINTERS)
             "See [ld-redefinition-action].")
 (REDEFINING-PROGRAMS
  (PROGRAMMING)
  "An explanation of why we restrict redefinitions

  ACL2 does not in general allow the redefinition of functions because
  logical inconsistency can result: previously stored theorems can be
  rendered invalid if the axioms defining the functions involved are
  changed.  However, to permit prototyping of both [47m:[0m[47m[program][0m and
  [47m:[0m[47m[logic][0m mode systems, ACL2 permits redefinition if the user has
  accepted logical responsibility for the consequences by setting
  [47m[ld-redefinition-action][0m to an appropriate non-[47mnil[0m value.  The
  refusal of ACL2 to support the unrestricted redefinition of
  [47m:[0m[47m[program][0m mode functions may appear somewhat capricious.  After
  all, what are the logical consequences of changing a definition if
  no axioms are involved?

  Three important points should be made before we discuss redefinition
  further.

  The first is that ACL2 does support redefinition (of both [47m:[0m[47m[program][0m
  and [47m:[0m[47m[logic][0m functions) when [47m[ld-redefinition-action][0m is non-[47mnil[0m.

  The second is that a ``redefinition'' that does not change the mode,
  formals, guards, type declarations, stobjs, or body of a function
  is considered redundant and is permitted even when
  [47m[ld-redefinition-action][0m is [47mnil[0m.  We recognize and permit redundant
  definitions because it is not uncommon for two distinct [books] to
  share identical function definitions.  When determining whether the
  body of a function is changed by a proposed redefinition, we
  actually compare the untranslated versions of the two bodies.  See
  [term].  For example, redundancy is not recognized if the old body
  is [47m(list a b)[0m and the new body is [47m(cons a (cons b nil))[0m.  We use
  the untranslated bodies because of the difficulty of translating
  the new body in the presence of the old syntactic information,
  given the possibility that the redefinition might attempt to change
  the [signature] of the function, i.e., the number of formals, the
  number of results, or the position of single-threaded objects in
  either.

  The third important point is that a ``redefinition'' that preserves
  the formals, guard, types, stobjs, and body but changes the mode
  from [47m:[0m[47m[program][0m to [47m:[0m[47m[logic][0m is permitted even when
  [47m[ld-redefinition-action][0m is [47mnil[0m.  That is what [47m[verify-termination][0m
  does.

  This note addresses the temptation to allow redefinition of
  [47m:[0m[47m[program][0m functions in situations other than the three described
  above.  Therefore, suppose [47m[ld-redefinition-action][0m is [47mnil[0m and
  consider the cases.

  Case 1.  Suppose the new definition attempts to change the formals or
  more generally the [signature] of the function.  Accepting such a
  redefinition would render ill-formed other [47m:[0m[47m[program][0m functions
  which call the redefined function.  Subsequent attempts to evaluate
  those callers could arbitrarily damage the Common Lisp image.
  Thus, redefinition of [47m:[0m[47m[program][0m functions under these
  circumstances requires the user's active approval, as would be
  sought with [47m[ld-redefinition-action][0m [47m'(:query . :overwrite)[0m.

  Case 2.  Suppose the new definition attempts to change the body (even
  though it preserves the [signature]).  At one time we believed this
  was acceptable and ACL2 supported the quiet redefinition of
  [47m:[0m[47m[program][0m mode functions in this circumstance.  However, because
  such functions can be used in macros and redundancy checking is
  based on untranslated bodies, this turns out to be unsound!
  (Aside: Perhaps this is not an issue if the function takes [47m[state][0m
  or a user-defined [stobj] argument; but we do not further consider
  this distinction.)  Such redefinition is therefore now prohibited.
  We illustrate such an unsoundness below.  Let [47mfoo-thm1.lisp[0m be a
  book with the following contents.

    (in-package \"ACL2\")
    (defun p1 (x) (declare (xargs :mode :program)) (list 'if x 't 'nil))
    (defmacro p (x) (p1 x))
    (defun foo (x) (p x))
    (defthm foo-thm1 (iff (foo x) x) :rule-classes nil)

  Note that the macro form [47m(p x)[0m translates to [47m(if x t nil)[0m.  The
  [47m:[0m[47m[program][0m function [47mp1[0m is used to generate this translation.  The
  function [47mfoo[0m is defined so that [47m(foo x)[0m is [47m(p x)[0m and a theorem
  about [47mfoo[0m is proved, namely, that [47m(foo x)[0m is true iff [47mx[0m is true.

  Now let [47mfoo-thm2.lisp[0m be a book with the following contents.

    (in-package \"ACL2\")
    (defun p1 (x) (declare (xargs :mode :program)) (list 'if x 'nil 't))
    (defmacro p (x) (p1 x))
    (defun foo (x) (p x))
    (defthm foo-thm2 (iff (foo x) (not x)) :rule-classes nil)

  In this book, the [47m:[0m[47m[program][0m function [47mp1[0m is defined so that [47m(p x)[0m
  means just the negation of what it meant in the first book, namely,
  [47m(if x nil t)[0m.  The function [47mfoo[0m is defined identically --- more
  precisely, the [3muntranslated[0m body of [47mfoo[0m is identical in the two
  [books], but because of the difference between the two versions of
  the [47m:[0m[47m[program][0m function [47mp1[0m the axioms defining the two [47mfoo[0ms are
  different.  In the second book we prove the theorem that [47m(foo x)[0m is
  true iff [47mx[0m is nil.

  Now consider what would happen if the [signature]-preserving
  redefinition of [47m:[0m[47m[program][0m functions were permitted and these two
  [books] were included.  When the second book is included the
  redefinition of [47mp1[0m would be permitted since the [signature] is
  preserved and [47mp1[0m is just a [47m:[0m[47m[program][0m.  But then when the
  redefinition of [47mfoo[0m is processed it would be considered redundant
  and thus be permitted.  The result would be a logic in which it was
  possible to prove that [47m(foo x)[0m is equivalent to both [47mx[0m and [47m(not x)[0m.
  In particular, the following sequence leads to a proof of nil:

    (include-book \"foo-thm1\")
    (include-book \"foo-thm2\")
    (thm nil :hints ((\"Goal\" :use (foo-thm1 foo-thm2))))

  It might be possible to loosen the restrictions on the redefinition
  of [47m:[0m[47m[program][0m functions by allowing [signature]-preserving
  redefinition of [47m:[0m[47m[program][0m functions not involved in macro
  definitions.  Alternatively, we could implement definition
  redundancy checking based on the translated bodies of functions
  (though that is quite problematic).  Barring those two changes, we
  believe it is necessary simply to impose the same restrictions on
  the redefinition of [47m:[0m[47m[program][0m mode functions as we do on [47m:[0m[47m[logic][0m
  mode functions.")
 (REDO-FLAT
  (DEBUGGING)
  "Redo on failure of a [47m[progn][0m, [47m[encapsulate][0m, or [47m[certify-book][0m

  When one submits an [47m[encapsulate][0m, [47m[progn][0m, or [47m[certify-book][0m command
  and there is a failure, ACL2 restores its logical [world] as though
  the command had not been run.  But sometimes one would like to
  debug the failure by re-executing all sub-events that succeeded up
  to the point of failure, and then re-executing the failed
  sub-event.  Said differently, imagine that the [events] under an
  [47mencapsulate[0m, [47mprogn[0m, or [47mcertify-book[0m form were flattened into a list
  of events that were then submitted to ACL2 up to the point of
  failure.  This would put us in the state in which the original
  failed event had failed, so we could now replay that failed event
  and try modifying it, or first proving additional events, in order
  to get it admitted.

  [47mRedo-flat[0m is provided for this purpose.  Consider the following
  (rather nonsensical) example, in which the [47m[defun][0m of [47mf3[0m fails (the
  body is [47my[0m but the formal parameter list is [47m(x)[0m).

    (encapsulate
     ()
     (defun f1 (x) x)
     (encapsulate ()
                  (local (defthm hack (equal (car (cons x y)) x))))
     (encapsulate ()
                  (local (defthm hack (equal (+ x y) (+ y x)))))
     (encapsulate ()
                  (make-event '(defun f2 (x) x))
                  (progn (defthm foo (equal x x) :rule-classes nil)
                         (defun f3 (x) y)))
     (defun f4 (x) x)
     (defun f5 (x) y))

  After this attempt fails, you can evaluate the following form.

    (redo-flat)

  This will first lay down a [47m[deflabel][0m event, [47m(deflabel r)[0m, so that
  you can eventually remove your debugging work with [47m(:ubt! r)[0m.  Then
  the successful sub-events that preceded the failure will be
  executed with proofs skipped (so that this execution is fast).
  Then, the failed event will be executed.  Finally, a [47m:[0m[47m[pbt][0m command
  is executed so that you can see a summary of the events that
  executed successfully.

  You can eliminate some of the steps above by supplying keyword
  values, as follows, where those arguments are not evaluated.

    (redo-flat
     :succ  succ ; Skip the successful sub-events if val is nil.
     :fail  fail ; Skip the failed sub-event if val is nil.
     :label lab  ; Skip deflabel if lab or succ is nil, else use (deflabel lab).
     :pbt   val  ; Skip the final :pbt if val, lab, or succ is nil.
     )

  Also, you can avoid skipping proofs for the successful sub-events by
  supplying keyword [47m:succ-ld-skip-proofsp[0m with a valid value for
  [47mld-skip-proofsp[0m; see [ld-skip-proofsp].  For example, you might
  want to execute [47m(redo-flat :succ-ld-skip-proofsp nil)[0m if you use
  the [47mmust-fail[0m utility from community book [47mmake-event/eval.lisp[0m,
  since for example [47m(must-fail (thm (equal x y)))[0m normally succeeds
  but would cause an error if proofs are skipped.  For another
  example: you may wish to do proofs when re-running certain
  [47m[make-event][0m forms, for example, when the expansion is [47m(:OR expr1
  expr2)[0m and the proof initially succeeds for [47mexpr2[0m rather than [47mexpr1[0m
  (see [make-event]).

  If you prefer only to see the successful and failed sub-events,
  without any events being re-executed, you may evaluate the
  following form instead.

    (redo-flat :show t)

  For the example above, this command produces the following output.

    List of events preceding the failure:

    ((DEFUN F1 (X) X)
     (ENCAPSULATE NIL
                  (LOCAL (DEFTHM HACK (EQUAL (CAR (CONS X Y)) X))))
     (ENCAPSULATE NIL
                  (LOCAL (DEFTHM HACK (EQUAL (+ X Y) (+ Y X)))))
     (MAKE-EVENT '(DEFUN F2 (X) X))
     (DEFTHM FOO (EQUAL X X)
             :RULE-CLASSES NIL))

    Failed event:

    (DEFUN F3 (X) Y)
    ACL2 !>

  [47mRedo-flat[0m uses a scheme that should not cause spurious name conflicts
  for [47m[local][0m events.  Above, it is mentioned that events are
  ``flattened''; now we clarify this notion.  Each sub-event that
  succeeds and is an [47m[encapsulate][0m or [47m[progn][0m is left intact.  Only
  such events that fail are replaced by their component events.
  Thus, in the example above, there is no conflict between the two
  [47m[local][0m sub-events named ``[47mhack[0m,'' because these are contained in
  successful [47mencapsulate[0m sub-events, which are therefore not
  flattened.  The [47m[progn][0m and two [47m[encapsulate][0m events surrounding
  the definition of [47mf3[0m are, however, flattened, because that
  definition failed to be admitted.

  Normally, [47mredo-flat[0m will have the desired effect even if you
  interrupted a proof (with control-c).  However, [47mredo-flat[0m will not
  produce the desired result after an interrupt if you have enabled
  the debugger using [47m(set-debugger-enable t)[0m or if you have disabled
  the default ``soft'' interrupt behavior (see [abort-soft]).")
 (REDUNDANT (POINTERS)
            "See [redundant-events].")
 (REDUNDANT-ENCAPSULATE
  (ENCAPSULATE)
  "Redundancy of [47m[encapsulate][0m [events]

  For this [documentation] topic we assume familiarity with [47mencapsulate[0m
  events and the notion of redundancy for [events]; see [encapsulate]
  and see [redundant-events].  Until the final remark, we also assume
  that redefinition is off (see [ld-redefinition-action]).

  The typical way for an [47mencapsulate[0m event to be redundant is when a
  syntactically identical [47mencapsulate[0m has already been executed under
  the same [47m[default-defun-mode][0m, [47m[default-ruler-extenders][0m, and
  [47m[default-verify-guards-eagerness][0m.  But more generally, the
  [47mencapsulate[0m events need not be syntactically identical; for
  example, it suffices that they agree when the contents of [47m[local][0m
  sub-events are ignored.  Detailed criteria for redundancy are given
  below, but let us first look at a consequence of the point just
  made about ignoring the contents of [47m[local][0m sub-events.  Consider
  the following sequence of two events.

    (encapsulate
     ()
     (defun f (x) x)
     (local (defthm f-identity
              (equal (f x) x))))

    (encapsulate
     ()
     (defun f (x) x)
     (local (defthm false-claim
              (equal (f x) (not x)))))

  You might be surprised to learn that the second is actually
  redundant, even though [47mfalse-claim[0m is clearly not a theorem;
  indeed, its negation is a theorem!  The following two points may
  soften the blow.  First, this behavior is as specified above (and
  is specified more precisely below): the contents of [local] events
  are ignored when checking redundancy of [47m[encapsulate][0m events.
  Second, this behavior is sound, because the logical meaning of an
  [47m[encapsulate][0m event is taken from the events that it exports, which
  do not include events that are [local] to the [47mencapsulate[0m event.

  Some users, however, want to use [47m[encapsulate][0m events for testing in
  a way that is thwarted by this ignoring of [local] sub-events.
  Consider the following sort of example.

    (encapsulate ()
                 (local (defthm test1 ...)))

    (encapsulate ()
                 (local (defthm test2 ...)))

  Fortunately, in this case both [47mtest1[0m and [47mtest2[0m will be evaluated.  To
  see why, first note that when a completed [encapsulate] event with
  empty [signature] has introduced no sub-[events], then it has no
  effect at all on the logical [world].  Thus, the first [47mencapsulate[0m
  event is not stored in the world; so, the second [47mencapsulate[0m event
  is not redundant, since it is executed in a world that contains no
  trace of the first [47mencapsulate[0m event.

  Also see community books [47mstd/testing/eval.lisp[0m,
  [47mmake-event/eval-check.lisp[0m, and [47mmake-event/eval-tests.lisp[0m for more
  ways to test in books.

  Here are detailed criteria for redundancy of [47m[encapsulate][0m [events].
  First, based on a heuristic (but rather thorough) check, the
  proposed (new) [47mencapsulate[0m event must be seen as [3mpossibly[0m
  introducing a new name, for example because one of its sub-events,
  perhaps after some macroexpansion, is an invocation of [47m[defun][0m, of
  [47m[defthm][0m, or of certain other events that [3mmight[0m introduce a name,
  including [47m[make-event][0m.  Second, the two [world]s in which each
  [47mencapsulate[0m event is evaluated must have the same
  [default-defun-mode]s, the same [default-ruler-extenders], and the
  same [default-verify-guards-eagerness].  Third, the existing and
  proposed [47mencapsulate[0m [events] must contain the same [signature]s
  and the same number of top-level sub-events; let [47mk[0m be that number.
  Finally: for each [47mi < k[0m, the [47mi[0mth top-level events [47mE1[0m and [47mE2[0m from
  the earlier and proposed [47mencapsulate[0ms must be related in one of the
  following ways.

    * [47mE1[0m and [47mE2[0m are equal; or

    * [47mE1[0m is of the form [47m(record-expansion E2 ...)[0m, with the exception noted
      below; or else

    * [47mE1[0m and [47mE2[0m are equal after replacing each sub-event of [47mE1[0m with its
      [47m[make-event][0m expansion and replacing each [47m[local][0m sub-event of
      [47mE1[0m or [47mE2[0m by [47m(local (value-triple :elided))[0m.  Here, a sub-event
      of an event [47mE[0m is defined to be either [47mE[0m itself, or a sub-event
      of a constituent event of [47mE[0m in the case that [47mE[0m is a call of
      [47m[skip-proofs][0m, [47m[with-output][0m, [47m[with-prover-time-limit][0m,
      [47m[with-prover-step-limit][0m, [47mrecord-expansion[0m, [47m[time$][0m, [47m[progn][0m,
      [47m[progn!][0m, or [47m[encapsulate][0m itself.

  The second condition has the following exception: it does not apply
  when the new [47mencapsulate[0m event takes place within an [47m[include-book][0m
  event.  (Allowing that would be unsound, as explained in a comment
  in ACL2 source function [47mcorresponding-encaps[0m.)

  [31;1mRemark[0m.  We conclude with some discussion of redundancy of
  [47mencapsulate[0m events in the presence of redefinition (see
  [ld-redefinition-action]).  Consider the following sequence of
  events.

    (encapsulate () (defun foo (x) x))

    (redef!) ; Turn on redefinition.

    ; not redundant
    (encapsulate () (defun foo (x) (cons x x)))

    ; not redundant
    (encapsulate () (defun foo (x) x))

  Note that the last [47mencapsulate[0m call is identical to an earlier event,
  namely the first one.  However, ACL2 never sees that first event
  when determining whether the last event is redundant.  The reason
  is that when ACL2 searches the world for a corresponding
  [47mencapsulate[0m event, it does not look back past the most recent
  definition of [47mfoo[0m.

  By contrast, consider what happens when, in a fresh ACL2 session, we
  evaluate the following sequence instead, obtained by wrapping a
  [47m[make-event][0m call around each [47m[defun][0m event.

    (encapsulate () (make-event '(defun foo (x) x)))

    (redef!) ; Turn on redefinition.

    ; not redundant
    (encapsulate () (make-event '(defun foo (x) (cons x x))))

    ; redundant!
    (encapsulate () (make-event '(defun foo (x) x)))

  It may be surprising that the last [47mencapsulate[0m call is redundant.
  The reason is that it is identical to an earlier [47mencapsulate[0m event.
  Because of the use of [47mmake-event[0m in the final event, ACL2 does not
  determine that the last event is attempting to define [47mfoo[0m, so ACL2
  does not limit its search backward through the world as it did in
  the previous example (where there were no uses of [47mmake-event[0m).  The
  moral of the story: when redefinition is involved, it may be best
  not to rely on one's intuition about redundancy for [47mencapsulate[0m
  events.")
 (REDUNDANT-EVENTS
  (EVENTS)
  "Allowing a name to be introduced ``twice''

  Sometimes an event will announce that it is ``redundant'', meaning
  that the form is not evaluated because ACL2 determines that its
  effect is already incorporated into the logical [world].  Thus,
  when this happens, no change to the logical [world] takes place.
  This feature permits two independent [books], each of which defines
  some name, to be included sequentially provided they use exactly
  the same definition.

  Note that by the definition above, a form can have no effect on the
  logical [world] yet not be considered to be redundant.  Here is an
  example of such a form.

    (value-triple (cw \"Hello world.~%\"))

  When are two [logical-name] definitions considered ``the same''?  It
  depends upon the kind of event that introduces that name.  We
  consider these below in alphabetical order, followed by ``Note
  About'' comments.  Macros in the [community-books] may also support
  redundancy; see their documentation for details, since below we
  only discuss ACL2 [events] that are built into ACL2.

  A [47m[defstobj][0m or [47m[defabsstobj][0m is redundant if there is already an
  identical such event in the logical [world].

  A [47m[defattach][0m event is never redundant.  (Reasons are provided in a
  comment in the ACL2 sources definition of defattach in the ACL2
  logic.)  Note that [47mdefattach[0m events do not define any names.

  A [47m[defaxiom][0m or [47m[defthm][0m event is redundant if there is already an
  axiom or theorem of the given name and the two [events] are
  syntactically identical.  But there is the following more generous
  criterion, which applies unless the older event is a [47mdefthm[0m event
  and the newer event is a [47mdefaxiom[0m event: both the formula (after
  macroexpansion) and the [rule-classes] (after translation and
  certain ``truncation'') are syntactically identical.  This
  ``truncation'' involves removing the [47m:HINTS[0m and [47m:INSTRUCTIONS[0m
  fields from a rule-class, and also removing the [47m:COROLLARY[0m field
  when it specifies the same term as the event.  Note that a [47m[defthm][0m
  can be redundant with a [47m[defaxiom][0m but not vice-versa.  (Remark for
  system hackers: [47mdefthm[0m/[47mdefaxiom[0m redundancy is implemented in ACL2
  source function, [47mredundant-theoremp[0m.)

  A [47m[defconst][0m is redundant if the name is already defined either with
  a syntactically identical [47mdefconst[0m event or one that defines it to
  have the same value.

  A [47m[deflabel][0m event is never redundant.  This means that if you have a
  [47m[deflabel][0m in a book and that book has been included (without
  error), then references to that label denote the point in [history]
  at which the book introduced the label.  See the note about
  shifting logical names, below.

  A [47m[defmacro][0m event is redundant if there is already a macro defined
  with the same name and syntactically identical arguments, [guard],
  and body.

  A [47m[defpkg][0m event is redundant if a package of the same name with
  exactly the same imports has been defined.

  A [47m[defthm][0m event is redundant according to the criteria given above
  in the discussion of [47mdefaxiom[0m.

  A [47m[deftheory][0m event is redundant if keyword argument [47m:redundant-okp[0m
  is not [47mnil[0m and the theory is unchanged from the one already
  associated with the name.  More precisely, the runic theory
  computed from the theory expression must be equal to the runic
  theory already associated with the name.  (See [theories] for a
  discussion of runic theories.  Also see [defthy] for a variant of
  [47mdeftheory[0m that supports redundancy by default.)  Equality of runic
  theories is a rather severe restriction, since most theory
  expressions are sensitive to the context in which they occur.
  Consider the following example.

    (deftheory foo (disable append revappend) :redundant-okp t)
    (defthm my-car-cons (equal (car (cons x y)) x))
    (deftheory foo (disable revappend append) :redundant-okp t)

  The second [47mdeftheory[0m event above is not redundant, because its
  computed runic theory includes the [rune] [47m(:rewrite my-car-cons)[0m,
  which is not in the runic theory previously associated with [47mfoo[0m.
  If we change the example either to eliminate the [47m[defthm][0m above or
  to change it to call [47m[defthmd][0m instead, then the second [47mdeftheory[0m
  event is redundant, because the runic theories are ordered, and
  hence the order of runic designators (here, [47mrevappend[0m and [47mappend[0m)
  is irrelevant.

  A [47m[defun][0m, [47m[defuns][0m, or [47m[mutual-recursion][0m event is redundant if for
  each function to be introduced, there has already been introduced a
  function with the same name, formals, and body (before
  macroexpansion), and with the same values [declare]d for the
  [47m:[0m[47m[guard][0m, [47m:[0m[47m[measure][0m, types, [47m:[0m[47m[ruler-extenders][0m, [47m:non-executable[0m,
  [47m:type-prescription[0m, [47m:[0m[47m[stobj][0m[47ms[0m, and [47m:[0m[47m[split-types][0m, provided that
  the [defun-mode]s are appropriate (see the ``Note About Appropriate
  Modes'' below).  Moreover, the order of the combined [47m:[0m[47m[guard][0m and
  type declarations must be the same in both cases.  Exceptions and
  clarifications:

   1. If the new and existing function events have no explicit
      [ruler-extenders] (which are therefore syntactically equal),
      the [default-ruler-extenders] for the new and existing function
      events must be the same.

   2. It is permissible for one definition to have a [47m:[0m[guard] of [47mt[0m and the
      other to have no explicit guard (hence, the guard is implicitly
      [47mt[0m).

   3. The [47m:measure[0m check is avoided if the old definition is non-recursive
      (and not defined within a [47m[mutual-recursion][0m) or we are
      skipping proofs (for example, during [47m[include-book][0m).
      Otherwise, the new definition may have a [47m:measure[0m of [47m(:? v1 ...
      vk)[0m, where [47m(v1 ... vk)[0m enumerates the variables occurring in
      the measure stored for the old definition.

   4. If either the old or new event is a [47m[mutual-recursion][0m event, then
      redundancy requires that both are [47m[mutual-recursion][0m events
      that define the same set of function symbols.

   5. The [stobj]s declared by the two definitions are allowed to disagree
      on [47mstate[0m: one can declare [47mstate[0m among its declared [47m:stobjs[0m
      values while the other does not, regardless of whether or not
      [47m[set-state-ok][0m has been evaluated.  That is, they only need to
      agree on the stobjs that are [3muser-defined[0m.

   6. Redundancy may fail with an error about a name being ``already
      defined using special raw Lisp code'' or ``predefined in the
      \"COMMON-LISP\" package''.  This applies to certain functions
      that are built into ACL2; it may also apply when definitions
      are overridden in raw Lisp using trust tags (see [defttag]),
      typically in books.  The reason for causing an error is that if
      the proposed redundant definition is in a book, then when later
      including that book after it is certified, the compiled code
      for that definition will replace the original code, which is
      generally undesirable when the original code has special raw
      Lisp optimizations.  If the earlier definition is in a book,
      then the error message will suggest including that book rather
      than trying to define the function redundantly.

  An [47m[encapsulate][0m event is most commonly redundant when a
  syntactically identical [47m[encapsulate][0m has already been executed
  under the same [47m[default-defun-mode][0m, [47m[default-ruler-extenders][0m, and
  [47m[default-verify-guards-eagerness][0m.  The full criterion for
  redundancy of [47mencapsulate[0m events is more complex, for example
  ignoring contents of [47m[local][0m [events]; see [redundant-encapsulate].

  An [47m[in-theory][0m event is never redundant by default, though that can
  be changed; see [set-in-theory-redundant-okp].  Note that it
  doesn't define any name.

  An [47m[include-book][0m event is redundant if the book has already been
  included.

  A call of [47m[make-event][0m is never redundant, as its argument is always
  evaluated to obtain the make-event expansion.  However, that
  expansion may of course be redundant.

  A [47m[mutual-recursion][0m event is redundant according to the criteria in
  the discussion above for the case of a [47mdefun[0m event.

  A [47m[progn][0m event is never redundant: its subsidiary [events] are
  always considered.  Of course, its sub-events may themselves be
  redundant.  If all of its sub-events are redundant --- or more
  generally, if none of the sub-events changes the logical [world]
  --- then the [47mprogn[0m event also won't change the world.

  A [47m[push-untouchable][0m event is redundant if every name supplied is
  already a member of the corresponding list of untouchable symbols.

  A [47m[regenerate-tau-database][0m event is never redundant.  Note that it
  doesn't define any name.

  A [47m[remove-untouchable][0m event is redundant if no name supplied is a
  member of the corresponding list of untouchable symbols.

  A [47m[reset-prehistory][0m event is redundant if it does not cause any
  change.

  A [47m[set-body][0m event is redundant if the indicated body is already the
  current body.

  A [47m[table][0m event not define any name.  It is redundant when it sets
  the value already associated with a key of the table, or when it
  sets an entire table (using keyword [47m:clear[0m) to its existing value;
  see [table].  Setting a non-existent key to [47mnil[0m is not redundant,
  with the exception discussed next.

  [Memoization] is carried out using a [table], [47mmemoize-table[0m, that may
  associate a function symbol with [47mnil[0m when it is not memoized.  It
  is redundant to [47m[unmemoize][0m a currently-unmemoized function symbol,
  thus associating it with [47mnil[0m in the [47mmemoize-table[0m --- even if that
  function symbol is not already a key of that table (this is the
  exception noted in the preceding paragraph).  It is redundant to
  [47m[memoize][0m a function when the function is already identically
  memoized, that is, when the corresponding [47m[table][0m event is
  redundant.

  A [47m[verify-guards][0m event is redundant if the function has already had
  its [guard]s verified.

  [3mNote About Built-in (Predefined) Functions and Macros:[0m

  Redundancy is restricted for built-in macros and functions that have
  special raw Lisp code.  Such redundancy is only legal in the
  context of [47m[local][0m.  This restriction is needed for soundness, for
  technical reasons omitted here (details may be found in a long
  comment about redundant-events in source function
  [47mchk-acceptable-defuns-redundancy[0m).

  [3mNote About Appropriate Modes:[0m

  Suppose a function is being redefined and that the formals, guards,
  types, user-defined stobjs, and bodies are identical.  When are the
  modes ([47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m) ``appropriate?'' Identical modes are
  appropriate.  But what if the old mode was [47m:program[0m and the new
  mode is [47m:logic[0m?  This is appropriate, provided the definition meets
  the requirements of the logical definitional principle.  That is,
  you may redefine ``redundantly'' a [47m:program[0m mode function as a
  [47m:logic[0m mode function provide the measure conjectures can be proved.
  This is what [47m[verify-termination][0m does.  Now consider the reverse
  style of redefinition.  Suppose the function was defined in [47m:logic[0m
  mode and is being identically redefined in [47m:program[0m mode.  ACL2
  will treat the redefinition as redundant, provided the appropriate
  criteria are met (as though it were in :logic mode).

  [3mNote About Shifting Logical Names:[0m

  Suppose a book defines a function [47mfn[0m and later uses [47mfn[0m as a logical
  name in a theory expression.  Consider the value of that theory
  expression in two different sessions.  In session A, the book is
  included in a [world] in which [47mfn[0m is not already defined, i.e., in
  a [world] in which the book's definition of [47mfn[0m is not redundant.
  In session B, the book is included in a [world] in which [47mfn[0m is
  already identically defined.  In session B, the book's definition
  of [47mfn[0m is redundant.  When [47mfn[0m is used as a logical name in a theory
  expression, it denotes the point in [history] at which [47mfn[0m was
  introduced.  Observe that those points are different in the two
  sessions.  Hence, it is likely that theory expressions involving [47mfn[0m
  will have different values in session A than in session B.

  This may adversely affect the user of your book.  For example,
  suppose your book creates a theory via [47m[deftheory][0m that is
  advertised just to contain the names generated by the book.  But
  suppose you compute the theory as the very last event in the book
  using:

    (set-difference-theories (universal-theory :here)
                             (universal-theory fn))

  where [47mfn[0m is the very first event in the book and happens to be a
  [47m[defun][0m event.  This expression returns the advertised set if [47mfn[0m is
  not already defined when the book is included.  But if [47mfn[0m were
  previously (identically) defined, the theory is larger than
  advertised.

  The moral of this is simple: when building [books] that other people
  will use, it is best to describe your [theories] in terms of
  logical names that will not shift around when the [books] are
  included.  The best such names are those created by [47m[deflabel][0m.

  [3mNote About Unfortunate Redundancies.[0m

  Notice that our syntactic criterion for redundancy of [47m[defun][0m
  [events] may not allow redefinition to take effect unless there is
  a syntactic change in the definition.  The following example shows
  how an attempt to redefine a function can fail to make any change.

    (set-ld-redefinition-action '(:warn . :overwrite) state)
    (defmacro mac (x) x)
    (defun foo (x) (mac x))
    (defmacro mac (x) (list 'car x))
    (set-ld-redefinition-action nil state)
    (defun foo (x) (mac x)) ; redundant, unfortunately; foo does not change
    (thm (equal (foo 3) 3)) ; succeeds, showing that redef of foo didn't happen

  The call of macro [47mmac[0m was expanded away before storing the first
  definition of [47mfoo[0m for the theorem prover.  Therefore, the new
  definition of [47mmac[0m does not affect the expansion of [47mfoo[0m by the
  theorem prover, because the new definition of [47mfoo[0m is ignored.

  One workaround is first to supply a different definition of [47mfoo[0m, just
  before the last definition of [47mfoo[0m above.  Then that final
  definition will no longer be redundant.  However, as a courtesy to
  users, we strengthen the redundancy check for function definitions
  when redefinition is active.  If in the example above we remove the
  form [47m(set-ld-redefinition-action nil state)[0m, then the problem goes
  away:

    (set-ld-redefinition-action '(:warn . :overwrite) state)
    (defmacro mac (x) x)
    (defun foo (x) (mac x))
    (defmacro mac (x) (list 'car x))
    (defun foo (x) (mac x)) ; no longer redundant
    (thm (equal (foo 3) 3)) ; fails, as we would like

  To summarize: If a [47m[defun][0m form is submitted that meets the usual
  redundancy criteria, then it may be considered redundant even if a
  macro called in the definition has since been redefined.  The
  analogous problem applies to constants, i.e., symbols defined by
  [47m[defconst][0m that occur in the definition body.  However, if
  redefinition is currently active the problem goes away: that is,
  the redundancy check is strengthened to check the ``translated''
  body, in which macro calls and constants defined by [47m[defconst][0m are
  expanded away.

  The above discussion for [47m[defun][0m forms applies to [47m[defconst][0m forms as
  well.  However, for [47m[defmacro][0m forms ACL2 always checks translated
  bodies, so such bogus redundancy does not occur.

  Here is more complex example illustrating the limits of redefinition,
  based on one supplied by Grant Passmore.

    (defun n3 () 0)
    (defun n4 () 1)
    (defun n5 () (> (n3) (n4))) ; body is see normalized to nil
    (thm (equal (n5) nil)) ; succeeds, trivially
    (set-ld-redefinition-action '(:warn . :overwrite) state)
    (defun n3 () 2)
    (thm (equal (n5) nil)) ; still succeeds, sadly

  We may expect the final [47m[thm][0m call to fail because of the following
  reasoning: [47m(n5)[0m = [47m(> (n3) (n4))[0m = [47m(> 2 1)[0m = [47mt[0m.  Unfortunately, the
  body of [47mn5[0m was simplified to [47mnil[0m when [47mn5[0m was admitted (see
  [normalize]), so the redefinition of [47mn3[0m is ignored during the final
  [47mthm[0m call.  (Such normalization can be avoided; see [xargs] for
  discussion of the [47m:normalize[0m keyword.)  So, given this unfortunate
  situation, one might expect at this point simply to redefine [47mn5[0m
  using the same definition as before, in order to pick up the new
  definition of [47mn3[0m.  Such ``redefinition'' would, however, be
  redundant, for the same reason as in the previous example: no
  syntactic change was made to the definition.  Even with
  redefinition active, there is no change in the body of [47mn5[0m, even
  with macros and constants (defined by [47m[defconst][0m) expanded; there
  are none such!  The same workaround applies as before: redefine [47mn5[0m
  to be something different, and then redefine [47mn5[0m again to be as
  desired.

  A related phenomenon can occur for [47m[encapsulate][0m.  As explained
  above, an [47mencapsulate[0m event is redundant if it is identical to one
  already in the database.  (But a weaker condition applies in
  general; see [redundant-encapsulate].)  Consider then the following
  contrived example.

    (defmacro mac (x) x)
    (encapsulate () (defun foo (x) (mac x)))
    (set-ld-redefinition-action '(:warn . :overwrite) state)
    (defmacro mac (x) (list 'car x))
    (encapsulate () (defun foo (x) (mac x)))

  The last [47mencapsulate[0m event is redundant because it meets the
  criterion for redundancy: it is identical to the earlier
  [47mencapsulate[0m event.  Even though redefinition is active, and hence
  ACL2 ``should'' be able to see that the new [47m[defun][0m of [47mfoo[0m is not
  truly redundant, nevertheless the criterion for redundancy of
  [47m[encapsulate][0m allows the new [47mencapsulate[0m form to be redundant.

  A workaround can be to add something trivial to the [47mencapsulate[0m, for
  example:

    (encapsulate ()
      (deflabel try2) ; ``Increment'' to try3 next time, and so on.
      (defun foo (x) x))


Subtopics

  [Get-enforce-redundancy]
      Query the [world] on whether redundancy is being enforced

  [Get-guard-checking]
      Get the status most recently installed by [47m[set-guard-checking][0m

  [Set-enforce-redundancy]
      Require most events to be redundant

  [Set-in-theory-redundant-okp]
      Allow [47m[in-theory][0m events to be redundant")
 (REFINEMENT
  (RULE-CLASSES)
  "Record that one equivalence relation refines another

  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.

    Example:
    (defthm bag-equal-refines-set-equal
      (implies (bag-equal x y)
               (set-equal y x))
      :rule-classes :refinement)

  Also see [defrefinement].

    General Form:
    (implies (equiv1 x y) (equiv2 x y))

  [47mEquiv1[0m and [47mequiv2[0m must be known equivalence relations.  The effect of
  such a rule is to record that [47mequiv1[0m is a refinement of [47mequiv2[0m.
  This means that [47mequiv1[0m [47m:[0m[47m[rewrite][0m rules may be used while trying to
  maintain [47mequiv2[0m.  See [equivalence] for a general discussion of the
  issues.

  The macro form [47m(defrefinement equiv1 equiv2)[0m is an abbreviation for a
  [47m[defthm][0m of rule-class [47m:refinement[0m that establishes that [47mequiv1[0m is
  a refinement of [47mequiv2[0m.  See [defrefinement].

  Suppose we have the [47m:[0m[47m[rewrite][0m rule

    (bag-equal (append a b) (append b a))

  which states that [47m[append][0m is commutative modulo bag-equality.
  Suppose further we have established that bag-equality refines
  set-equality.  Then when we are simplifying [47m[append][0m expressions
  while maintaining set-equality we use [47m[append][0m's commutativity
  property, even though it was proved for bag-equality.

  Equality is known to be a refinement of all equivalence relations.
  The transitive closure of the refinement relation is maintained, so
  if [47mset-equality[0m, say, is shown to be a refinement of some third
  sense of equivalence, then [47mbag-equality[0m will automatically be known
  as a refinement of that third equivalence.

  A rewrite rule may fail to fire because its equivalence relation is
  not known to be a refinement of any of those known to be permitted.
  See [47m[geneqv][0m for a discussion of how ACL2 uses [47m[congruence][0m rules
  to derive the permitted equivalences and how those equivalences are
  represented.  See [refinement-failure] for advice on how to use
  [break-rewrite] to determine that a rule failed the refinement
  check and for advice about how to ``fix'' such a problem.

  [47m:refinement[0m lemmas cannot be disabled.  That is, once one equivalence
  relation has been shown to be a refinement of another, there is no
  way to prevent the system from using that information.
  Furthermore, [47m:refinement[0m lemmas are not tracked and are thus not
  reported in the [summary].  Of course, individual [47m:[0m[47m[rewrite][0m rules
  can be disabled.

  More will be written about this as we develop the techniques.")
 (REFINEMENT-FAILURE
  (INTRODUCTION-TO-THE-THEOREM-PROVER BREAK-REWRITE)
  "what to do when a rewrite rule fails the refinement check

  One reason a [47m:[0m[47m[rewrite][0m rule may fail to fire is that its equivalence
  relation fails to be a known refinement of the generated
  equivalence relation (or ``[geneqv]'') governing the current target
  of the rewriter.  In the following discussion we assume you are
  familiar with the notion of the generated equivalence relation.  If
  not, please see [47m[geneqv][0m for the necessary background and details.


Is a Rule Not Firing Because of a Refinement Failure?

  To determine whether refinement failure is the cause of a rule's
  failure to fire, enable [break-rewrite] with [47m(brr t)[0m and install a
  [47m[monitor][0m with [47m:rf[0m set to [47mt[0m on the rule, e.g., [47m(monitor rune '(:rf
  t))[0m, where [47mrune[0m evaluates to the [47m[rune][0m of the rule in question.
  You might also specify a [47m:condition[0m so that a break occurs only if
  the target is the translated term, [47mtterm[0m, you expected the rule to
  hit,

    (monitor rune '(:condition (equal (brr@ :target) 'tterm) :rf t)).

  Then try the proof again.  (Note: if the rule being monitored is a
  [simple] abbreviation rule, be sure to supply the hint [47m:DO-NOT
  '(PREPROCESS)[0m as discussed in [47m[monitor][0m.)  If a monitored rule
  fails to fire (under the monitored condition) because its
  equivalence relation is not known to refine the geneqv derived for
  that occurrence of the target, an interactive break will occur.
  The break header will name the rule, print the target, show the
  rule's equivalence relation, and show the geneqv.  The header tells
  you the equivalence relation is not a refinement of the geneqv.
  You might wish to use the break-rewrite command [47m:path[0m or [47m:path+[0m to
  print the path down to the target from the top-level goal.  That
  will show the geneqv derived for each active call of the rewriter
  and will help you understand why the current geneqv is what it is.
  While looking at the path make sure that the current occurrence of
  the target is the one you expected the rule to hit.  If it is not,
  proceed to the next break with [47m:ok[0m.

  When you find the target you're looking for, focus your attention on
  the equivalence relation and geneqv.  To fix the problem you need
  the former to be a refinement of the latter.  When you understand
  how to make that happen, abort the failing proof attempt with [47m:a![0m
  and try to fix the problem.


How to Fix a Refinement Failure

  There are two basic ways to ``fix'' a refinement failure:

    * (a) prove a [47m[refinement][0m rule that establishes that the equivalence
      relation used in the rule indeed refines one of the equivalence
      relations displayed in the geneqv, or

    * (b) prove a [47m[congruence][0m rule that will extend the geneqv derived for
      the current occurrence of the target.

  We illustrate these approaches below.  But first you must keep in
  mind that the equivalence relation in the rule may not refine any
  possible geneqv derivable along the path.  You may have to find a
  different proof or, at least, you may have to define some
  additional equivalence relations, refinement rules, and congruence
  rules, and prove a version of your lemma that uses a new relation.
  After all, this is a theorem proving problem and not all fixes are
  trivial!


How Geneqvs Are Displayed

  As illustrated in the discussion of [geneqv], a generated equivalence
  is essentially a set of equivalence relations.  ACL2 prints geneqvs
  in three different ways depending on the utility doing the
  printing.

  When reporting that an equivalence relation is not a refinement of a
  geneqv, the geneqv is printed simply as a list of equivalence
  relation names, e.g., [47m(EQV1 EQV2)[0m.  Order is unimportant as this
  list represents a set.

  When reporting the path the rewriter took to the current target and
  the geneqvs for each active call of the rewriter along that path,
  each geneqv is printed as a list of doublets, where the first
  component of the doublet is the name of an equivalence relation and
  the second component is the name of the [congruence] rule
  responsible for adding that relation to the geneqv, e.g.,

    ((EQV1 EQV1-IFF-CONGRUENCE-FOR-F)
     (EQV2 EQV2-IFF-CONGRUENCE-FOR-F))

  This is just another presentation of [47m(eqv1 eqv2)[0m but we believe the
  congruence rule names may help you recall how equivalence relations
  get into the set.

  Finally, in [47m[trace$][0m, or the value returned by (brr@ :geneqv) or any
  other system utility that displays the actual internal
  representation of a geneqv you will see something like this:

    ((5603 EQV1 . (:congruence EQV1-IFF-CONGRUENCE-FOR-F))
     (4957 EQV2 . (:congruence EQV2-IFF-CONGRUENCE-FOR-F)))

  where the equivalence relation names are paired with the runes (not
  just the names) of the responsible congruence rules and the numbers
  are unique session-dependent indices for those runes allowing quick
  determination of the enabled status of the rules.

  You will see the first two print conventions in the examples below.


Some Generic Examples

  In the following discussion we introduce some functions that will
  allow us to explore refinement failures.  The experiments reported
  below are carried out in the community book
  [47mbooks/demos/refinement-failure-test-book.lisp[0m whose input/output
  log may be found in [47mbooks/demos/refinement-failure-test-log.txt[0m.

  We're going to attempt to prove [47m(P (F (G A (BETA B))))[0m by rewriting
  the occurrence of [47m(BETA B)[0m to [47m(GAMMA B)[0m and appealing to a rule
  that establishes [47m(P (F (G A (GAMMA B))))[0m.  But at every subterm
  level in the conjecture different equivalence relations are
  involved.  Thus, many equivalence and congruence relations are
  involved and that makes this example hard to follow.  Assume that
  [47mPEQ[0m, [47mFEQ[0m, [47mG2EQ1[0m, [47mG2EQ2[0m, and [47mG2EQ1![0m are known equivalence relations.

  Possibly Distracting Aside: In this section of this documentation we
  use names that follow a certain convention.  These conventions help
  the authors keep the names straight!  Perhaps they'll help you too.
  Names containing ``[47mEQ[0m'' are equivalence relations; they will serve
  as ``inside'' equivalences for the function symbol indicated by the
  first character in the name, ``[47mP[0m'', ``[47mF[0m'' or ``[47mG[0m''; if that first
  character is followed by ``2'' it means they apply to the second
  argument of the function, otherwise they apply to the first (and
  only) argument; and if there is more than one such inside
  equivalence relation for that function the name is suffixed with
  ``[47m1[0m'' or ``[47m2[0m''.  The exclamation mark at the end of ``G2EQ1!'' is
  to remind us that the function is a refinement of [47mG2EQ1[0m.  Thus [47mPEQ[0m
  is the inside equivalence for the first (only) argument of [47mP[0m-terms
  and [47mG2EQ1[0m is the inside equivalence for the second argument of
  [47mG[0m-terms and is one of two such relations.

  Imagine that we've proved two rewrite rules:

    * [47m(DEFTHM RULE (G2EQ1! (BETA X) (GAMMA X)))[0m

    * [47m(DEFTHM DONE (P (F (G X (GAMMA Y)))))[0m
        which is actually stored as

      [47m(DEFTHM DONE (IFF (P (F (G X (GAMMA Y)))) T))[0m.

  Clearly, our strategy to prove [47m(P (F (G A (BETA B))))[0m is to use [47mRULE[0m
  to replace the [47m(BETA B)[0m by [47m(GAMMA B)[0m, and then use [47mDONE[0m to reduce
  the conjecture to [47mT[0m.

  However, the problem is that [47mRULE[0m uses the equivalence relation
  [47mG2EQ1![0m.  So the rewriter, which starts by maintaining [47mIFF[0m on the
  top-level [47mP[0m term, will have to evolve a geneqv so that by the time
  it reaches the occurrence of [47m(BETA B)[0m the geneqv at that target
  admits [47mG2EQ1![0m as a refinement.  To do so we'll provide the
  following [47m[congruence][0m rules.  As you read them, remember that the
  term we'll be working on is [47m(P (F (G A (BETA B))))[0m, i.e., our
  conjecture is a call of [47mP[0m, in which the 1st (and only) argument is
  a call of [47mF[0m, in which the 1st (and only) argument is a call of [47mG[0m,
  in which the 2nd argument is call of [47mBETA[0m.

    * [47mIFF[0m is maintained on a call of [47mP[0m provided [47mPEQ[0m is maintained on the
      1st argument of [47mP[0m:

        * [3mevent[0m: [47m(DEFCONG PEQ IFF (P X) 1)[0m

        * [3mname[0m: [47mPEQ-IMPLIES-IFF-P-1[0m

    * [47mPEQ[0m is maintained on a call of [47mF[0m provided [47mFEQ[0m is maintained on the
      1st argument of [47mF[0m:

        * [3mevent[0m: [47m(DEFCONG FEQ PEQ (F X) 1)[0m

        * [3mname[0m: [47mFEQ-IMPLIES-PEQ-F-1[0m

    * [47mFEQ[0m is maintained on a call of [47mG[0m provided [47mG2EQ1[0m is maintained on the
      2nd argument of [47mG[0m:

        * [3mevent[0m: [47m(DEFCONG G2EQ1 FEQ (G X Y) 2)[0m

        * [3mname[0m: [47mG2EQ1-IMPLIES-FEQ-G-2[0m

    * [47mFEQ[0m is [3malso[0m maintained on a call of [47mG[0m provided [47mG2EQ2[0m is maintained on
      the 2nd argument of [47mG[0m:

        * [3mevent[0m: [47m(DEFCONG G2EQ2 FEQ (G X Y) 2)[0m

        * [3mname[0m: [47mG2EQ2-IMPLIES-FEQ-G-2[0m

  Note that there are two ways to maintain [47mFEQ[0m on a call of [47mG[0m: maintain
  either [47mG2EQ1[0m or [47mG2EQ2[0m on the second argument of [47mG[0m.  But neither of
  those equivalence relations is used in our rewrite [47mRULE[0m.  Our [47mRULE[0m
  uses [47mG2EQ1![0m, so assume we've proved:

    * [47mG2EQ1![0m refines [47mG2EQ1[0m:

        * [3mevent[0m: [47m(DEFREFINEMENT G2EQ1! G2EQ1)[0m

        * [3mname[0m: [47mG2EQ1!-REFINES-G2EQ1[0m

  Having arranged all of the above, imagine issuing the commands

    (brr T)
    (monitor '(:REWRITE RULE)
             '(:condition (and (equal (brr@ :target) '(BETA B))
                               '(:path+ :go))
               :rf t))
    (thm (P (F (G A (BETA B))))
         :hints ((\"Goal\" :do-not '(preprocess))))

  Note: The [47m:condition[0m value above will cause a break only if the
  [47m:target[0m is [47m(BETA B)[0m, but when the break occurs it will issue the
  command [47m:PATH+[0m to print the path and then issue the command [47m:GO[0m to
  proceed from the break.  Because we've just monitored a [simple]
  abbreviation rule, we include in the [47m[thm][0m command the hint to
  avoid preprocessing, as advised in the documentation for [47m[monitor][0m.

  Because we've done the equivalence, congruence, and refinement setup
  perfectly, our [47mRULE[0m will fire and we will get a break like this:

    (1 Breaking (:REWRITE RULE) on (BETA B):
    1 ACL2 >

  The subsequent [47m:PATH+[0m command will show how the rewriter descended to
  here from the top-level goal and will display the geneqvs derived
  for each rewrite.

    1 ACL2 >:path+
    1. Simplifying the clause
         ((P (F (G A (BETA B)))))
    2. Rewriting (to simplify) the atom of the first literal,
         (P (F (G A (BETA B)))),
       Geneqv: (IFF)
    3. Rewriting (to simplify) the first argument,
         (F (G A (BETA B))),
       Geneqv: ((PEQ PEQ-IMPLIES-IFF-P-1))
    4. Rewriting (to simplify) the first argument,
         (G A (BETA B)),
       Geneqv: ((FEQ FEQ-IMPLIES-PEQ-F-1))
    5. Rewriting (to simplify) the second argument,
         (BETA B),
       Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2)
                (G2EQ1 G2EQ1-IMPLIES-FEQ-G-2))
    6. Attempting to apply (:REWRITE RULE) to
         (BETA B)
       Preserving: G2EQ1!
       Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2)
                (G2EQ1 G2EQ1-IMPLIES-FEQ-G-2))
    1 ACL2 >

  Recall, from the discussion above, that sometimes geneqvs are printed
  merely as a list of equivalence relations, e.g., [47m(G2EQ2 G2EQ1)[0m, and
  other times, as above, are printed so as to include the name of the
  congruence relation responsible for each equivalence.

  Notice that in frame 4, where the rewriter is working on [47m(G A (BETA
  B))[0m it is to maintain the [47mFEQ[0m equivalence relation (which was
  justified from frame 3 by the rule [47mFEQ-IMPLIES-PEQ-F-1[0m where the
  rewriter was to maintain [47mPEQ[0m).  But when the rewriter stepped from
  frame 4 to the second argument of [47m(G A (BETA B))[0m in frame 5, it
  used both [47mG2EQ1-IMPLIES-FEQ-G-2[0m and [47mG2EQ2-IMPLIES-FEQ-G-2[0m to derive
  the geneqv [47m(G2EQ2 G2EQ1)[0m.  Then, when it attempted to apply [47mRULE[0m,
  whose equivalence relation is [47mG2EQ1![0m, it passed the refinement test
  because [47mG2EQ1![0m refines [47mG2EQ1[0m, which is one of the equivalences
  listed in the geneqv.

  When we proceed from the break, the proof completes successfully.

  But now imagine that we had failed to prove [47m(DEFREFINEMENT G2EQ1!
  G2EQ1)[0m.  The [47mthm[0m command above would have caused this break:

    (1 Breaking (:REWRITE RULE) on (BETA B):

    The equivalence relation, G2EQ1!, of this rule is not a refinement
    of the current geneqv, (G2EQ2 G2EQ1).  Use :path or :path+ to see how
    the geneqv evolved.  See :DOC refinement-failure for advice about how
    to deal with this kind of problem.

    1 ACL2 >

  The break header explains the problem: the rewriter does not know
  that [47mG2EQ1![0m refines [47mG2EQ1[0m or [47mG2EQ2[0m.  Of course, [3mwe[0m do know that and
  the fix is simply to prove the ``forgotten'' [47m[defrefinement][0m.

  On the other hand, suppose we had proved the [47mdefrefinement[0m but had
  forgotten to prove that [47mFEQ[0m is maintained on a call of [47mG[0m when [47mG2EQ1[0m
  is maintained on the 2nd argument of [47mG[0m, i.e., [47m(DEFCONG G2EQ1 FEQ (G
  X Y) 2)[0m, aka [47mG2EQ1-IMPLIES-FEQ-G-2[0m.  Then the [47mthm[0m command would
  produce the following break.

    (1 Breaking (:REWRITE RULE) on (BETA B):

    The equivalence relation, G2EQ1!, of this rule is not a refinement
    of the current geneqv, (G2EQ2).  Use :path or :path+ to see how the
    geneqv evolved.  See :DOC refinement-failure for advice about how to
    deal with this kind of problem.

  Note that the geneqv is printed in its simplest form, as a list of
  equivalence relation names; in this case only one name is included:
  [47mG2EQ2[0m.  Of course, if we believed [47mG2EQ1![0m does refine [47mG2EQ2[0m, it
  would suffice to prove the corresponding refinement rule.  But
  let's suppose we know [47mG2EQ1![0m doesn't refine [47mG2EQ2[0m.  Instead, we
  know [47mG2EQ1![0m refines [47mG2EQ1[0m, which is not in the geneqv.  Our problem
  then is to arrange for [47mG2EQ1[0m to be in the geneqv.  Look at the path
  that got us here.

    1 ACL2 >:path+
    1. Simplifying the clause
         ((P (F (G A (BETA B)))))
    2. Rewriting (to simplify) the atom of the first literal,
         (P (F (G A (BETA B)))),
       Geneqv: (IFF)
    3. Rewriting (to simplify) the first argument,
         (F (G A (BETA B))),
       Geneqv: ((PEQ PEQ-IMPLIES-IFF-P-1))
    4. Rewriting (to simplify) the first argument,
         (G A (BETA B)),
       Geneqv: ((FEQ FEQ-IMPLIES-PEQ-F-1))
    5. Rewriting (to simplify) the second argument,
         (BETA B),
       Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2))
    6. Attempting to apply (:REWRITE RULE) to
         (BETA B)
       Preserving: G2EQ1!
       Geneqv: ((G2EQ2 G2EQ2-IMPLIES-FEQ-G-2))
    1 ACL2 >

  In frame 4 we are to maintain [47mFEQ[0m on a call of [47mG[0m.  In frame 5 we are
  rewriting the second argument of [47mG[0m and used [47mG2EQ2-IMPLIES-FEQ-G-2[0m
  to derive the new geneqv containing [47mG2EQ2[0m.  We could get [47mG2EQ1[0m into
  that new geneqv is only we had a congruence rule that says [47mFEQ[0m is
  maintained on [47mG[0m when rewriting the second argument of [47mG[0m maintaining
  [47mG2EQ1[0m.  That's just the ``forgotten'' [47m(DEFCONG G2EQ1 FEQ (G X Y)
  2)[0m.  Of course we could alternatively have chosen to prove [47m(DEFCONG
  G2EQ1! FEQ (G X Y) 2)[0m, but it is generally better to prove the
  strongest congruence rules we know.

  Finally, as documented in [refinement] and [congruence], refinement
  and congruence rules are not (always) tracked and usually do not
  show up in the [summary] printed at the end of proof attempts.  The
  decision not to track every use of these rules was made to improve
  prover efficiency.")
 (REGENERATE-TAU-DATABASE
  (EVENTS INTRODUCTION-TO-THE-TAU-SYSTEM)
  "Regenerate the tau database relative to the current enabled theory

    General Form:
    (regenerate-tau-database)

  The tau database is regenerated by scanning the current logical world
  and re-processing every rule-generating event in it relative to the
  current enabled theory and current tau auto mode settings.  See
  [introduction-to-the-tau-system] for background details.

  This command was intended to allow the user to remove a fact from the
  tau database, by regenerating the database without the fact.  But
  as the following discussion highlights, [47mregenerate-tau-database[0m
  does not really solve the problem.  We regard it as a placeholder
  for a more sophisticated mechanism.  However, we have trouble
  understanding why a user might wish to remove a fact from the
  database and are awaiting further user experiences before designing
  the more sophisticated mechanism.

  Suppose, for example, that you wanted to remove a signature rule
  provided by some rule with name [3mrune[0m.  You could disable [3mrune[0m and
  regenerate the database.  We discuss why you might --- or might not
  --- want to do this later.  But suppose you did it.  Unfortunately,
  the database you get will not be just like the one you started with
  minus the signature rule.  The reason is that the database you
  started with was generated incrementally and the current theory
  might have evolved.  To take a simple example, your starting
  database might have included a rule that has been disabled since it
  was first added.  Thus, the part of your starting database built
  before the disabling was constructed with the rule enabled and the
  part built afterwards has the rule disabled.  You are unlikely to
  get the same database whether you enable or disable that rule now.

  You might hope that the avoidance of [47min-theory[0m events would eliminate
  the problem but it does not because even the [47m[ground-zero][0m theory
  is constructed incrementally from the ``pre-history'' commands used
  to boot up ACL2.  Those pre-history commands include some global
  [47min-theory[0m commands.  Since every session starts from the
  [47mground-zero[0m state, the starting database is already ``infected''
  with global [47min-theory[0m commands.

  The reason we hope that it will not be necessary to remove tau facts
  is that the tau system is designed merely to be fast and benign
  (see [3mDesign Philosophy[0m in [introduction-to-the-tau-system]).  The
  tau system's coverage should grows monotonically with the addition
  of rules.  According to this understanding of tau, adding a
  signature rule, for example, may allow tau to prove some additional
  goals but will not prevent it from proving goals it could prove
  previously.  If this is understanding of tau is accurate, we see no
  fundamental reason to support the removal of a fact.  This, of
  course, ignores the possibility that the user wishes to explore
  alternative proof strategies or measure performance.

  We welcome user observations and experience on this issue.")
 (REGRESSION (POINTERS)
             "See [books-certification].")
 (RELEASE-NOTES
  (ABOUT-ACL2)
  "Pointers to what has changed

  This section of the online [documentation] contains notes on the
  changes that distinguish successive released versions of ACL2.

  Each topic [47mnote-x-y[0m is a note describing what in ACL2 version X.Y was
  new in comparison to the preceding version of ACL2.

  The current version of ACL2 is the value of the constant [47m(@
  acl2-version)[0m.


Subtopics

  [Note-1-1]
      Acl2 Version 1.1 Notes

  [Note-1-2]
      Acl2 Version 1.2 Notes

  [Note-1-3]
      Acl2 Version 1.3 Notes

  [Note-1-4]
      Acl2 Version 1.4 Notes

  [Note-1-5]
      Acl2 Version 1.5 Notes

  [Note-1-6]
      Acl2 Version 1.6 Notes

  [Note-1-7]
      ACL2 Version 1.7 (released October 1994) Notes

  [Note-1-8]
      ACL2 Version 1.8 (May, 1995) Notes

  [Note-1-8-update]
      ACL2 Version 1.8 (Summer, 1995) Notes

  [Note-1-9]
      ACL2 Version 1.9 (Fall, 1996) Notes

  [Note-2-0]
      ACL2 Version 2.0 (July, 1997) Notes

  [Note-2-1]
      ACL2 Version 2.1 (December, 1997) Notes

  [Note-2-2]
      ACL2 Version 2.2 (August, 1998) Notes

  [Note-2-3]
      ACL2 Version 2.3 (October, 1998) Notes

  [Note-2-4]
      ACL2 Version 2.4 (August, 1999) Notes

  [Note-2-5]
      ACL2 Version 2.5 (June, 2000) Notes

  [Note-2-5{r}]
      ACL2 Version 2.5(r) (June, 2000) Notes

  [Note-2-6]
      ACL2 Version 2.6 (November, 2001) Notes

  [Note-2-6{r}]
      ACL2 Version 2.6(r) (November, 2001) Notes

  [Note-2-7]
      ACL2 Version 2.7 (November, 2002) Notes

  [Note-2-7{r}]
      ACL2 Version 2.7(r) (November, 2002) Notes

  [Note-2-8]
      ACL2 Version 2.8 (March, 2004) Notes

  [Note-2-8{r}]
      ACL2 Version 2.8(r) (March, 2003) Notes

  [Note-2-9]
      ACL2 Version 2.9 (October, 2004) Notes

  [Note-2-9{r}]
      ACL2 Version 2.9(r) (October, 2004) Notes

  [Note-2-9-1]
      ACL2 Version 2.9.1 (December, 2004) Notes

  [Note-2-9-2]
      ACL2 Version 2.9.2 (April, 2005) Notes

  [Note-2-9-3]
      ACL2 Version 2.9.3 (August, 2005) Notes

  [Note-2-9-4]
      ACL2 Version 2.9.4 (February, 2006) Notes

  [Note-2-9-5]
      Changes in Version 3.0 since Version 2.9.4

  [Note-3-0]
      ACL2 Version 3.0 (June, 2006) Notes

  [Note-3-0{r}]
      ACL2 Version 3.0(r) (June, 2006) Notes

  [Note-3-0-1]
      ACL2 Version 3.0.1 (August, 2006) Notes

  [Note-3-0-1{r}]
      ACL2 Version 3.0.1(r) (August, 2006) Notes

  [Note-3-0-2]
      ACL2 Version 3.0.2 (December, 2006) Notes

  [Note-3-1]
      ACL2 Version 3.1 (December, 2006) Notes

  [Note-3-1{r}]
      ACL2 Version 3.1(r) (December, 2006) Notes

  [Note-3-2]
      ACL2 Version 3.2 (April, 2007) Notes

  [Note-3-2{r}]
      ACL2 Version 3.2(r) (April, 2007) Notes

  [Note-3-2-1]
      ACL2 Version 3.2.1 (June, 2007) Notes

  [Note-3-2-1{r}]
      ACL2 Version 3.2.1(r) (June, 2007) Notes

  [Note-3-3]
      ACL2 Version 3.3 (November, 2007) Notes

  [Note-3-3{r}]
      ACL2 Version 3.3(r) (November, 2007) Notes

  [Note-3-4]
      ACL2 Version 3.4 (August, 2008) Notes

  [Note-3-4{r}]
      ACL2 Version 3.4(r) (August, 2008) Notes

  [Note-3-5]
      ACL2 Version 3.5 (May, 2009) Notes

  [Note-3-5{r}]
      ACL2 Version 3.5(r) (May, 2009) Notes

  [Note-3-6]
      ACL2 Version 3.6 (August, 2009) Notes

  [Note-3-6{r}]
      ACL2 Version 3.6(r) (August, 2009) Notes

  [Note-3-6-1]
      ACL2 Version 3.6.1 (September, 2009) Notes

  [Note-4-0]
      ACL2 Version 4.0 (July, 2010) Notes

  [Note-4-0{r}]
      ACL2 Version 4.0(r) (July, 2010) Notes

  [Note-4-1]
      ACL2 Version 4.1 (September, 2010) Notes

  [Note-4-1{r}]
      ACL2 Version 4.1(r) (September, 2010) Notes

  [Note-4-2]
      ACL2 Version 4.2 (January, 2011) Notes

  [Note-4-2{r}]
      ACL2 Version 4.2(r) (January, 2011) Notes

  [Note-4-3]
      ACL2 Version 4.3 (July, 2011) Notes

  [Note-4-3{r}]
      ACL2 Version 4.3(r) (July, 2011) Notes

  [Note-5-0]
      ACL2 Version 5.0 (August, 2012) Notes

  [Note-6-0]
      ACL2 Version 6.0 (December, 2012) Notes

  [Note-6-1]
      ACL2 Version 6.1 (February, 2013) Notes

  [Note-6-2]
      ACL2 Version 6.2 (June, 2013) Notes

  [Note-6-3]
      ACL2 Version 6.3 (October, 2013) Notes

  [Note-6-4]
      ACL2 Version 6.4 (January, 2014) Notes

  [Note-6-5]
      ACL2 Version 6.5 (August, 2014) Notes

  [Note-7-0]
      ACL2 Version 7.0 (January, 2015) Notes

  [Note-7-1]
      ACL2 Version 7.1 (May, 2015) Notes

  [Note-7-2]
      ACL2 Version 7.2 (January, 2016) Notes

  [Note-7-3]
      ACL2 Version 7.3 (December, 2016) Notes

  [Note-7-4]
      ACL2 Version 7.4 (March, 2017) Notes

  [Note-8-0]
      ACL2 Version 8.0 (December, 2017) Notes

  [Note-8-1]
      ACL2 Version 8.1 (September, 2018) Notes

  [Note-8-2]
      ACL2 Version 8.2 (May, 2019) Notes

  [Note-8-3]
      ACL2 Version 8.3 (April, 2020) Notes

  [Note-8-4]
      ACL2 Version 8.4 (August, 2021) Notes

  [Note-8-5]
      ACL2 Version 8.5 (July, 2022) Notes

  [Note-8-6]
      ACL2 Version 8.6 (October, 2024) Notes

  [Note-8-7]
      ACL2 Version 8.7 (xxx, 20xx) Notes")
 (REM
  (NUMBERS ACL2-BUILT-INS)
  "Remainder using [47m[truncate][0m

    ACL2 !>(rem 14 3)
    2
    ACL2 !>(rem -14 3)
    -2
    ACL2 !>(rem 14 -3)
    2
    ACL2 !>(rem -14 -3)
    -2
    ACL2 !>(rem -15 -3)
    0
    ACL2 !>

  [47m(Rem i j)[0m is that number [47mk[0m for which [47m(* j (truncate i j))[0m added to [47mk[0m
  equals [47mi[0m.

  The [guard] for [47m(rem i j)[0m requires that [47mi[0m and [47mj[0m are rational ([real],
  in ACL2(r)) numbers and [47mj[0m is non-zero.

  [47mRem[0m is a Common Lisp function.  See any Common Lisp documentation for
  more information.

  [31;1mFunction: [0m<rem>

    (defun rem (x y)
      (declare (xargs :guard (and (real/rationalp x)
                                  (real/rationalp y)
                                  (not (eql y 0)))))
      (- x (* (truncate x y) y)))")
 (REMOVE
  (LISTS ACL2-BUILT-INS)
  "Remove all occurrences

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

  [47m(Remove x lst)[0m is equal to [47mlst[0m if [47mx[0m is not a member of [47mlst[0m, else is
  the result of removing all occurrences of [47mx[0m from [47mlst[0m.  The optional
  keyword, [47m:TEST[0m, has no effect logically, but provides the test
  (default [47m[eql][0m) used for comparing [47mx[0m with successive elements of
  [47mlst[0m.

  Also see [remove1].

  The [guard] for a call of [47mremove[0m depends on the test.  In all cases,
  the second argument must satisfy [47m[true-listp][0m.  If the test is
  [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m
  (see [eqlablep]) or the second argument must satisfy
  [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then either the first
  argument must be a symbol or the second argument must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mremove[0m and its variants:

      [47m(remove-eq x lst)[0m is equivalent to [47m(remove x lst :test 'eq)[0m;

      [47m(remove-equal x lst)[0m is equivalent to [47m(remove x lst :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mremove-equal[0m.

  [31;1mFunction: [0m<remove-equal>

    (defun remove-equal (x l)
      (declare (xargs :guard (true-listp l)))
      (cond ((endp l) nil)
            ((equal x (car l))
             (remove-equal x (cdr l)))
            (t (cons (car l)
                     (remove-equal x (cdr l))))))

  [47mRemove[0m is defined by Common Lisp.  See any Common Lisp documentation
  for more information.")
 (REMOVE-ASSOC
  (ALISTS ACL2-BUILT-INS)
  "Remove all pairs with a given key from an association list

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

  [47m(Remove-assoc key alist)[0m returns an alist that is the same as the
  list [47malist[0m, except that all pairs in [47malist[0m with a [47m[car][0m of [47mkey[0m are
  deleted (if any; otherwise [47malist[0m is returned).  Note that the order
  of the elements of [47malist[0m is unchanged (though some may be deleted).

  Also see [remove1-assoc] for a similar utility that deletes only the
  first pair in an alist with a given key, rather than all such
  pairs.

  The [guard] for a call of [47mremove-assoc[0m depends on the test.  In all
  cases, the second argument must satisfy [47m[alistp][0m.  If the test is
  [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m
  (see [eqlablep]) or the second argument must satisfy
  [47m[eqlable-alistp][0m.  If the test is [47m[eq][0m, then either the first
  argument must be a symbol or the second argument must satisfy
  [47m[symbol-alistp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mremove-assoc[0m and its variants:

      [47m(remove-assoc-eq key alist)[0m is equivalent to [47m(remove-assoc key alist
      :test 'eq)[0m;

      [47m(remove-assoc-equal key alist)[0m is equivalent to [47m(remove-assoc key
      alist :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mremove-assoc-equal[0m.

  [31;1mFunction: [0m<remove-assoc-equal>

    (defun remove-assoc-equal (x alist)
      (declare (xargs :guard (alistp alist)))
      (cond ((endp alist) nil)
            ((equal x (car (car alist)))
             (remove-assoc-equal x (cdr alist)))
            (t (cons (car alist)
                     (remove-assoc-equal x (cdr alist))))))")
 (REMOVE-ASSOC-EQ (POINTERS)
                  "See [remove-assoc].")
 (REMOVE-ASSOC-EQUAL (POINTERS)
                     "See [remove-assoc].")
 (REMOVE-BINOP
  (MACROS)
  "Remove the association of a function name with a macro name

  The form [47m(remove-binop macro-fn)[0m is an abbreviation for the form
  [47m(remove-macro-fn macro-fn)[0m.  See [remove-macro-fn].")
 (REMOVE-CUSTOM-KEYWORD-HINT
  (EVENTS)
  "Remove a custom keyword hint

    Example Forms:
    (remove-custom-keyword-hint :my-hint)

    General Form:
    (remove-custom-keyword-hint keyword)

  where [47mkeyword[0m is a [47m[keywordp][0m.

  For an explanation of how custom keyword hints are processed, see
  [custom-keyword-hints]; also see [add-custom-keyword-hint].

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.")
 (REMOVE-DEFAULT-HINTS
  (DEFAULT-HINTS)
  "Remove from the default hints

    Examples:
    (remove-default-hints '((computed-hint-1 clause)
                            (computed-hint-2 clause
                                             stable-under-simplificationp)))

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs (see [remove-default-hints!] for a corresponding
  non-[47m[local][0m event).

    General Form:
    (remove-default-hints lst)

  where [47mlst[0m is a list.  Generally speaking, the elements of [47mlst[0m should
  be suitable for use as [47m[computed-hints][0m.  Also see
  [add-default-hints].

  If some elements of the given list do not belong to the existing
  default hints, they will simply be ignored by this event.

  Also See [set-default-hints], see [add-default-hints], and see
  [default-hints].

  Finally, note that the effects of [47mset-default-hints[0m,
  [47m[add-default-hints][0m, and [47m[remove-default-hints][0m are [47m[local][0m 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 [47m[set-default-hints!][0m, [47m[add-default-hints!][0m, or
  [47m[remove-default-hints!][0m.")
 (REMOVE-DEFAULT-HINTS!
  (DEFAULT-HINTS)
  "Remove from the default hints non-[47m[local][0mly

  Please see [remove-default-hints], which is the same as
  [47mremove-default-hints![0m except that the latter is not [47m[local][0m to the
  [47m[encapsulate][0m or the book in which it occurs.  Probably
  [remove-default-hints] is to be preferred unless you have a good
  reason for wanting to export the effect of this event outside the
  enclosing [47m[encapsulate][0m or book.")
 (REMOVE-DIVE-INTO-MACRO
  (DIVE-INTO-MACROS-TABLE)
  "Removes association of [proof-builder] diving function with macro
  name

    Example:
    (remove-dive-into-macro logand)

  This feature undoes the effect of [47m[add-dive-into-macro][0m, which is
  used so that the interactive [proof-builder]'s [47mDV[0m command and
  numeric diving commands (e.g., [47m3[0m) will dive properly into subterms.
  Please see [add-dive-into-macro] and especially see
  [dive-into-macros-table].")
 (REMOVE-DUPLICATES
  (LISTS STRINGS ACL2-BUILT-INS)
  "Remove duplicates from a string or a list

    General Forms:
    (remove-duplicates x)
    (remove-duplicates x :test 'eql)   ; same as above (eql as equality test)
    (remove-duplicates x :test 'eq)    ; same, but eq is equality test
    (remove-duplicates x :test 'equal) ; same, but equal is equality test

  [47m(Remove-duplicates x)[0m returns the result of deleting duplicate
  elements from the beginning of the list or string [47mx[0m.  For example,
  [47m(remove-duplicates '(1 2 3 2 4))[0m is equal to [47m'(1 3 2 4)[0m.  The
  optional keyword, [47m:TEST[0m, has no effect logically, but provides the
  test (default [47m[eql][0m) used for comparing [47mx[0m with successive elements
  of [47mlst[0m.

  The [guard] for a call of [47mremove-duplicates[0m depends on the test.  In
  all cases, the argument must satisfy [47m[stringp][0m or [47m[true-listp][0m.  If
  the test is [47m[eql][0m, then the argument must satisfy either [47m[stringp][0m
  or [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then the argument must
  satisfy [47m[symbol-listp][0m.

  The relation between [47mremove-duplicates[0m and its variants is related to
  the usual pattern for equality variants; see [equality-variants].
  However, the possibility of a string argument changes the usual
  pattern a bit.  As one might expect:

      [47m(remove-duplicates-eq lst)[0m is equivalent to [47m(remove-duplicates lst
      :test 'eq)[0m.

  However, [47mremove-duplicates-equal[0m is defined without consideration of
  strings, for backward compatibility with versions of ACL2 through
  Version_4.2.  The macro [47mremove-duplicates-logic[0m has been introduced
  to model the behavior of [47mremove-duplicates[0m even on strings; use
  [47m:[0m[47m[pe][0m if you wish to see its definition.  So we can say the
  following.

      [47m(remove-duplicates-logic lst)[0m is equivalent to [47m(remove-duplicates lst
      :test 'equal)[0m; and

      [47m(remove-duplicates-logic lst)[0m is equal to [47m(remove-duplicates-equal
      lst)[0m when [47mlst[0m is not a string.

  In particular, when the argument is not a string, reasoning about any
  of these primitives reduces to reasoning about the function
  [47mremove-duplicates-equal[0m.

  [31;1mFunction: [0m<remove-duplicates-equal>

    (defun remove-duplicates-equal (l)
      (declare (xargs :guard (true-listp l)))
      (cond ((endp l) nil)
            ((member-equal (car l) (cdr l))
             (remove-duplicates-equal (cdr l)))
            (t (cons-with-hint (car l)
                               (remove-duplicates-equal (cdr l))
                               l))))

  [47mRemove-duplicates[0m is defined by Common Lisp.  See any Common Lisp
  documentation for more information.")
 (REMOVE-DUPLICATES-EQ (POINTERS)
                       "See [remove-duplicates].")
 (REMOVE-DUPLICATES-EQUAL (POINTERS)
                          "See [remove-duplicates].")
 (REMOVE-EQ (POINTERS) "See [remove].")
 (REMOVE-EQUAL (POINTERS)
               "See [remove].")
 (REMOVE-GLOBAL-STOBJ
  (EVENTS STOBJ)
  "Remove a global [stobj] with a given name

  See [47m[add-global-stobj][0m for relevant background and terminology
  together with an explanation of [47mremove-global-stobj[0m.  Here we give
  only a brief summary.

    General Form:
    (remove-global-stobj x state)

  where [47mx[0m evaluates to the name of a stobj that has a global value.

    Example Form:
    (remove-global-stobj 'st state)")
 (REMOVE-GUARD-HOLDERS (POINTERS)
                       "See [guard-holders].")
 (REMOVE-INVISIBLE-FNS
  (LOOP-STOPPER)
  "Make some unary functions no longer invisible

    Examples:
    (remove-invisible-fns binary-+ unary-- foo)
    (remove-invisible-fns + unary-- foo)

  The setting above has makes unary functions [47m[unary--][0m and [47mfoo[0m no
  longer ``invisible'' for the purposes of applying permutative
  [47m:[0m[47m[rewrite][0m rules to [47m[binary-+][0m trees.

    General Form:
    (remove-invisible-fns top-fn unary-fn1 ... unary-fnk)

  where [47mtop-fn[0m is a function symbol and the [47munary-fni[0m are unary
  function symbols, or more generally, these are all macro aliases
  for such function symbols (see [macro-aliases-table]).

  See [add-invisible-fns] and also see [invisible-fns-table] and see
  [set-invisible-fns-table].")
 (REMOVE-MACRO-ALIAS
  (MACROS)
  "Remove the association of a function name with a macro name

    Example:
    (remove-macro-alias append)

    General Form:
    (remove-macro-alias macro-name)

  See [macro-aliases-table] for a discussion of macro aliases; also see
  [add-macro-alias].  This form sets [47m[macro-aliases-table][0m to the
  result of deleting the key [47mmacro-name[0m from that [table].  If the
  name does not occur in the [table], then this form still generates
  an event, but the event has no real effect.")
 (REMOVE-MACRO-FN
  (MACROS)
  "Remove the association of a function name with a macro name

    Example:
    (remove-macro-fn binary-append)

    General Form:
    (remove-macro-fn macro-fn)

  See [add-macro-fn] for a discussion of how to associate a macro name
  with a function name.  This form sets [47m[untrans-table][0m to the result
  of deleting the association of a macro name with the given binary
  function name.  If the function name has no such association, then
  this form still generates an event, but the event has no real
  effect.")
 (REMOVE-NTH-ALIAS
  (NTH-ALIASES-TABLE)
  "Remove a symbol alias for printing of [47m[nth][0m/[47m[update-nth][0m terms

    Example:
    (remove-nth-alias append)

    General Form:
    (remove-nth-alias alias-name)

  See [nth-aliases-table] for further discussion; also see
  [add-nth-alias].  This form sets [47m[nth-aliases-table][0m to the result
  of deleting the key [47malias-name[0m from that [table].  If the name does
  not occur in the [table], then this form still generates an event,
  but the event has no real effect.")
 (REMOVE-OVERRIDE-HINTS
  (OVERRIDE-HINTS)
  "Delete from the list of [override-hints]

  See [override-hints] for a discussion of override-hints.  Here we
  describe how to delete from the list of override-hints.  Note that
  the effects of [47mremove-override-hints[0m [events] are [local] to the
  [books] or [47mencapsulate[0m [events] in which they reside; see
  [remove-override-hints!] to avoid that restriction.  Also see
  [add-override-hints] and see [set-override-hints].

    General Form:
    (remove-override-hints form)

  where [47mform[0m should evaluate to a list of computed hint forms.  The
  effect of this event is to set the list of [override-hints] to the
  result of deleting each element of the evaluation result from the
  [override-hints], if that element indeed belongs to the
  override-hints; no check is made that these elements are actually
  elements of the existing override-hints.")
 (REMOVE-OVERRIDE-HINTS!
  (OVERRIDE-HINTS)
  "Delete non-[local]ly from the list of [override-hints]

  [47mRemove-override-hints![0m is the same as [47m[remove-override-hints][0m, except
  that the former is not [local] to [books] or [47m[encapsulate][0m [events]
  in which it occurs.  See [remove-override-hints]; also see
  [add-override-hints] and see [set-override-hints].")
 (REMOVE-TRIVIAL-EQUIVALENCES-ENABLED-P
  (REWRITE SYSTEM-ATTACHMENTS)
  "Avoid removal of trivial equivalences during rewriting

  This topic concerns an advanced control for the ACL2 prover.

  This zero-ary attachable system function controls the
  ``remove-trivial-equivalences'' heuristic, which uses an equality
  hypothesis (and, when appropriate, an [equivalence] hypothesis) to
  replace a variable by a term in the rest of the goal.  (However,
  perhaps similar heuristics will still be used, for example as part
  of the [tau-system].)  Attach the function
  [47mconstant-nil-function-arity-0[0m to avoid this heuristic, and attach
  the function [47mconstant-t-function-arity-0[0m to restore it.")
 (REMOVE-UNTOUCHABLE
  (DEFTTAG)
  "Remove names from lists of untouchable symbols

  Untouchables are functions that cannot be called or as [state] global
  variables (see [programming-with-state]) that cannot be modified or
  unbound.

    Example Forms:
    (remove-untouchable my-var nil) ; then state global my-var is not untouchable
    (remove-untouchable set-mem t)  ; then function set-mem is not untouchable

  Also see [push-untouchable].

  This documentation topic is directed at those who build systems on
  top of ACL2.  We first describe a means for modifying [state] to
  remove some untouchables.  Then we describe the [47mremove-untouchable[0m
  event.  Both require an active trust tag (see [defttag]).

  We begin by discussing untouchable state global variables
  [47mtemp-touchable-vars[0m and [47mtemp-touchable-fns[0m, which initially have
  value [47mnil[0m.  These can often be used in place of [47mremove-untouchable[0m.
  When the value is [47mt[0m, no variable (respectively, no function or
  macro) is treated as untouchable, regardless of the set of initial
  untouchables or the [47mremove-untouchable[0m or [47m[push-untouchable][0m
  [events] that have been admitted.  Otherwise the value of each of
  these two variables is a [47m[symbol-listp][0m, and no member of this list
  is treated as an untouchable variable (in the case of
  [47mtemp-touchable-vars[0m) or as an untouchable function or macro (in the
  case of [47mtemp-touchable-fns[0m).  These two state global variables can
  be set by [47mset-temp-touchable-vars[0m and [47mset-temp-touchable-fns[0m,
  respectively, provided there is an active trust tag (see
  [defttag]).  Here is an illustrative example.  This macro executes
  the indicated forms in a context where there are no untouchable
  variables, but requires an active trust tag when invoked.

    (defmacro with-all-touchable (&rest forms)
      `(progn!
        :state-global-bindings
        ((temp-touchable-vars t set-temp-touchable-vars))
        (progn! ,@forms)))

  An equivalent version, which however is not recommended since
  [47m[state-global-let*][0m may have surprising behavior in raw Lisp, is as
  follows.

    (defmacro with-all-touchable (&rest forms)
      `(progn!
        (state-global-let*
         ((temp-touchable-vars t set-temp-touchable-vars))
         (progn! ,@forms))))

  Finally, the value [47mt[0m for [47mtemp-touchable-vars[0m removes the requirement
  that built-in state globals cannot be made unbound (with
  [47mmakunbound-global[0m).

  We now turn to the [47mremove-untouchable[0m event, in case the approach
  above is for some reason not adequate.  This event is illegal by
  default, since it can be used to provide access to ACL2 internal
  functions and data structures that are intentionally made
  untouchable for the user.  If you want to call it, you must first
  create an active trust tag; see [defttag].

    General Form:
    (remove-untouchable name{s} fn-p)

  where [47mname{s}[0m is a non-[47mnil[0m symbol or a non-[47mnil[0m true list of symbols,
  and [47mfn-p[0m is any value (but generally [47mnil[0m or [47mt[0m).  If [47mname{s}[0m is a
  symbol it is treated as the singleton list containing that symbol.
  The effect of this event is to remove the given symbols from the
  list of ``untouchable variables'' in the current world if [47mfn-p[0m is
  [47mnil[0m, else to remove the symbols into the list of ``untouchable
  functions''.  This event is redundant if no symbol listed is a
  member of the appropriate untouchables list (variables or
  functions).")
 (REMOVE1
  (LISTS ACL2-BUILT-INS)
  "Remove first occurrences, testing using [47m[eql][0m

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

  [47m(Remove1 x lst)[0m is equal to [47mlst[0m if [47mx[0m is not a member of [47mlst[0m, else is
  the result of removing the first occurrences of [47mx[0m from [47mlst[0m.  The
  optional keyword, [47m:TEST[0m, has no effect logically, but provides the
  test (default [47m[eql][0m) used for comparing [47mx[0m with successive elements
  of [47mlst[0m.

  Also see [remove].

  The [guard] for a call of [47mremove1[0m depends on the test.  In all cases,
  the second argument must satisfy [47m[true-listp][0m.  If the test is
  [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m
  (see [eqlablep]) or the second argument must satisfy
  [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then either the first
  argument must be a symbol or the second argument must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mremove1[0m and its variants:

      [47m(remove1-eq x lst)[0m is equivalent to [47m(remove1 x lst :test 'eq)[0m;

      [47m(remove1-equal x lst)[0m is equivalent to [47m(remove1 x lst :test 'equal)[0m.

  [31;1mFunction: [0m<remove1-equal>

    (defun remove1-equal (x l)
      (declare (xargs :guard (true-listp l)))
      (cond ((endp l) nil)
            ((equal x (car l)) (cdr l))
            (t (cons-with-hint (car l)
                               (remove1-equal x (cdr l))
                               l))))

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mremove1-equal[0m.")
 (REMOVE1-ASSOC
  (ALISTS ACL2-BUILT-INS)
  "Remove the first pair with a given key from an association list

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

  [47m(Remove1-assoc key alist)[0m returns an alist that is the same as the
  list [47malist[0m, except that the first pair in [47malist[0m with a [47m[car][0m of [47mkey[0m
  is deleted, if there is one; otherwise [47malist[0m is returned.  Note
  that the order of the elements of [47malist[0m is unchanged (though one
  may be deleted).

  Also see [remove-assoc] for a similar utility that deletes all pairs
  in an alist with a given key, rather than only the first such pair.

  The [guard] for a call of [47mremove1-assoc[0m depends on the test.  In all
  cases, the second argument must satisfy [47m[alistp][0m.  If the test is
  [47m[eql][0m, then either the first argument must be suitable for [47m[eql][0m
  (see [eqlablep]) or the second argument must satisfy
  [47m[eqlable-alistp][0m.  If the test is [47m[eq][0m, then either the first
  argument must be a symbol or the second argument must satisfy
  [47m[symbol-alistp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mremove1-assoc[0m and its variants:

      [47m(remove1-assoc-eq key alist)[0m is equivalent to [47m(remove1-assoc key
      alist :test 'eq)[0m;

      [47m(remove1-assoc-equal key alist)[0m is equivalent to [47m(remove1-assoc key
      alist :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mremove1-assoc-equal[0m.

  [31;1mFunction: [0m<remove1-assoc-equal>

    (defun remove1-assoc-equal (key alist)
      (declare (xargs :guard (alistp alist)))
      (cond ((endp alist) nil)
            ((equal key (caar alist)) (cdr alist))
            (t (cons (car alist)
                     (remove1-assoc-equal key (cdr alist))))))")
 (REMOVE1-ASSOC-EQ (POINTERS)
                   "See [remove1-assoc].")
 (REMOVE1-ASSOC-EQUAL (POINTERS)
                      "See [remove1-assoc].")
 (REMOVE1-EQ (POINTERS) "See [remove1].")
 (REMOVE1-EQUAL (POINTERS)
                "See [remove1].")
 (REORDER (POINTERS)
          "See [hints] for information about the keyword [47m:reorder[0m.")
 (RESET-FC-REPORTING
  (FORWARD-CHAINING-REPORTS)
  "Reset the forward-chaining tracking state to its initial
  configuration

    Example:  (reset-fc-reporting)

  This function erases all forward chaining tracking criteria and sets
  the on-the-fly reporting flag to [47mnil.[0m The next time you set the
  criteria (see [set-fc-criteria]) the short form of reports, in
  which only the caller and the fc-report number is printed, will
  appear in your proof logs.

  See [forward-chaining-reports] for details.")
 (RESET-KILL-RING
  (HISTORY)
  "Save memory by resetting and perhaps resizing the kill ring used by
  [47m[oops][0m

  By default, ACL2 holds on to old logical [world]s when you undo
  [command]s (see [ubt]), as documented elsewhere; see [oops].  You
  can free up memory by deleting those old worlds using
  [47mreset-kill-ring[0m.

    Examples:
    (reset-kill-ring t state)   ; replace each element of the kill ring by nil
    (reset-kill-ring 2 state)   ; create a new kill ring of '(nil nil)
    (reset-kill-ring 0 state)   ; create a new kill ring that is empty
    (reset-kill-ring nil state) ; just return the length of the kill ring

    General form:
    (reset-kill-ring n state)

  where [47mn[0m evaluates either to [47mt[0m, to [47mnil[0m, or to a nonnegative integer (a
  [47m[natp][0m).  If [47mn[0m evaluates to [47mt[0m, it is treated as the length of the
  current kill ring.  If [47mn[0m is [47mnil[0m, then the length [47mk[0m of the current
  kill ring is returned as a value triple [47m(mv nil k state)[0m.  If [47mn[0m is
  a [47m[natp][0m, then the kill ring is replaced with a list of [47mn[0m [47mnil[0ms.

  In particular, use [47m(reset-kill-ring 0 state)[0m to avoid saving any old
  logical [world]s, at the cost of disabling the effect of the [47m[oops][0m
  [command].")
 (RESET-LD-SPECIALS
  (LD)
  "Restores initial settings of the [47m[ld][0m specials

    Examples:
    (reset-ld-specials t)
    (reset-ld-specials nil)

  Roughly speaking, the [47m[ld][0m specials are certain [state] global
  variables, such as [47m[ld-prompt][0m and [47m[ld-pre-eval-filter][0m, which are
  managed by [47m[ld][0m as though they were local variables.  These
  variables determine the channels on which [47m[ld][0m reads and prints and
  control many options of [47m[ld][0m.  See [ld] for the details on what the
  [47m[ld][0m specials are.

  This function, [47mreset-ld-specials[0m, takes one Boolean argument, [47mflg[0m.
  The function resets all of the [47m[ld][0m specials to their initial,
  top-level values, except for the three channel variables,
  [47m[standard-oi][0m, [47m[standard-co][0m, and [47m[proofs-co][0m, which are reset to
  their initial values only if [47mflg[0m is non-[47mnil[0m.  Of course, if you are
  in a recursive call of [47m[ld][0m, then when you exit that call, the [47m[ld][0m
  specials will be restored to the values they had at the time [47m[ld][0m
  was called recursively.  To see what the initial values are,
  inspect the value of the constant [47m*initial-ld-special-bindings*[0m.")
 (RESET-PREHISTORY
  (HISTORY)
  "Reset the prehistory

    Examples:
    (reset-prehistory)     ; restart command numbering at 0
    (reset-prehistory nil) ; same as above
    (reset-prehistory t)   ; as above except also disable ubt-prehistory

    General Forms:
    (reset-prehistory)
    (reset-prehistory permanent-p)

  where [47mpermanent-p[0m is [47mt[0m or [47mnil[0m.  After execution of this command, ACL2
  will change the numbering provided by its [history] utilities so
  that this [47mreset-prehistory[0m command (or the top-level compound
  [command] containing it, which for example might be an
  [47m[include-book][0m) is assigned the number 0.  The only way to undo
  this command is with command [47m[ubt-prehistory][0m.  However, even that
  is disallowed if [47mpermanent-p[0m is [47mt[0m.

  Note that the second argument of [47m[certify-book][0m, which specifies the
  number of commands in the certification world (i.e., since
  ground-zero), is not sensitive to [47mreset-prehistory[0m; rather, it
  expects the number of commands since ground-zero.  To see such
  commands, [47m:[0m[47m[pbt][0m[47m :start[0m.

  A [47mreset-prehistory[0m event for which parameter [47mpermanent-p[0m has the
  default value of [47mnil[0m is always skipped when any of the following
  conditions holds: during [47m[certify-book][0m; during [47m[include-book][0m or
  the second pass of [47m[encapsulate][0m (indeed, whenever [ld] special
  [47m'[0m[47m[ld-skip-proofsp][0m has value [47m'include-book[0m); or when [47mstate[0m global
  [47m'skip-reset-prehistory[0m has a non-[47mnil[0m value.  Thus, we avoid
  resetting the history numbering to 0 when including or certifying a
  book, since that would probably not be what was intended.

  See [ubt-prehistory] for how to undo a [47mreset-prehistory[0m command that
  does not have a [47mpermanent-p[0m of [47mt[0m.  See [disable-ubt] for a variant
  of [47m(reset-prehistory t)[0m that does not change command numbering and
  is used by the [break-rewrite] utility.  Like [47mdisable-ubt[0m,
  [47mreset-prehistory[0m is never [redundant].")
 (RESET-PRINT-CONTROL (POINTERS)
                      "See [print-control].")
 (RESIZE-LIST
  (STOBJ ACL2-BUILT-INS)
  "List resizer in support of [stobj]s

  [47m(Resize-list lst n default-value)[0m takes a list, [47mlst[0m, and a desired
  length, [47mn[0m, for the result list, as well as a [47mdefault-value[0m to use
  for the extra elements if [47mn[0m is greater than the length of [47mlst[0m.

  [47mResize-list[0m has a guard of [47mt[0m.  This function is called in the body of
  function, [47mresize-<a>[0m where [47m<a>[0m is an array field of a [stobj].  See
  [defstobj].

  [31;1mFunction: [0m<resize-list-exec>

    (defun resize-list-exec (lst n default-value acc)
     (declare (xargs :guard (true-listp acc)))
     (if (and (integerp n) (> n 0))
         (resize-list-exec (if (atom lst) lst (cdr lst))
                           (1- n)
                           default-value
                           (cons (if (atom lst) default-value (car lst))
                                 acc))
       (reverse acc)))

  [31;1mFunction: [0m<resize-list>

    (defun resize-list (lst n default-value)
      (declare (xargs :guard t))
      (mbe :logic
           (if (and (integerp n) (> n 0))
               (cons (if (atom lst) default-value (car lst))
                     (resize-list (if (atom lst) lst (cdr lst))
                                  (1- n)
                                  default-value))
             nil)
           :exec (resize-list-exec lst n default-value nil)))")
 (REST
  (NTH ACL2-BUILT-INS)
  "Rest ([47m[cdr][0m) of the list

  In the logic, [47mrest[0m is just a macro for [47m[cdr][0m.

  [47mRest[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mMacro: [0m<rest>

    (defmacro rest (x) (list 'cdr x))")
 (RESTORE-MEMOIZATION-SETTINGS
  (MEMOIZE)
  "Restore the saved memoization settings

  For background on memoization, see [memoize].

    General Form:
    (restore-memoization-settings)

  Calls of this macro restore the memoization settings saved by
  [47m[save-and-clear-memoization-settings][0m.")
 (RESTRICT
      (POINTERS)
      "See [hints] for information about the keyword [47m:restrict[0m.")
 (RETRACT-WORLD
  (WORLD)
  "Install an initial segment (retraction) of a given ACL2 [world]

  See [world] for relevant background on ACL2 property list worlds.
  Here we discuss how to install an initial segment (retraction) of a
  user-defined world, that is, a world other than the one named
  [47m'current-acl2-world[0m, which is maintained by the ACL2 system.  Also
  see [extend-world] for a similar utility that instead extends a
  named world.

    General Form:

    (retract-world name wrld)

  where [47mname[0m is a symbol intended to name the given ACL2 property list
  world, [47mworld[0m.  Consider the following example.

    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)))
             (pprogn (f-put-global 'my-w1 wrld1 state)
                     (f-put-global 'my-w3 (extend-world 'my-world wrld3) state)))
    <state>
    ACL2 !>(retract-world 'my-world (@ my-w1))
    ((MY-SYM1 MY-KEY1 . MY-VAL1-OLD))
    ACL2 !>(getprop 'my-sym1 'my-key1 nil 'my-world (@ my-w1))
    MY-VAL1-OLD
    ACL2 !>

  The first top-level form sets the values of [47m[state][0m globals [47mmy-w1[0m and
  [47mmy-w3[0m to to the worlds obtained by extending the empty world one or
  three times, respectively, as shown.  The second top-level form
  [3minstalls[0m the value of [47mmy-w1[0m as the world that is current for the
  name [47m'my-world[0m.  The third top-level form returns the [47m'my-key1[0m
  property for the symbol [47m'my-sym1[0m in the installed world [47m(@ my-w1)[0m,
  and it does so efficiently because that world is installed.  See
  [world].")
 (RETRIEVE
  (PROOF-BUILDER)
  "Re-enter a (specified) [proof-builder] state

    Examples:
    (retrieve associativity-of-permutationp)
    retrieve

    General Form:
    (retrieve &optional name)

  See [ACL2-pc::retrieve], or use [47m(help retrieve)[0m inside the
  interactive [proof-builder] loop.  Also see [unsave].")
 (RETURN-LAST
  (BASICS ACL2-BUILT-INS)
  "Return the last argument, perhaps with side effects

  [47mReturn-last[0m is an ACL2 function that returns its last argument.  It
  is used to implement common utilities such as [47m[prog2$][0m and [47m[time$][0m.
  For most users, this may already be more than one needs to know
  about [47mreturn-last[0m; for example, ACL2 tends to avoid printing calls
  of [47mreturn-last[0m in its output, printing calls of [47m[prog2$][0m or [47m[time$][0m
  (or other such utilities) instead.

  If you encounter a call of [47mreturn-last[0m during a proof, then you may
  find it most useful to consider [47mreturn-last[0m simply as a function
  defined by the following equation.

    (equal (return-last x y z) z)

  It may also be useful to know that unlike other ACL2 functions,
  [47mreturn-last[0m can take a multiple value as its last argument, in
  which case this multiple value is returned.  The following
  contrived definition illustrates this point.

    ACL2 !>(defun foo (fn x y z)
             (return-last fn x (mv y z)))

    Since FOO is non-recursive, its admission is trivial.  We observe that
    the type of FOO is described by the theorem
    (AND (CONSP (FOO FN X Y Z)) (TRUE-LISTP (FOO FN X Y Z))).  We used
    primitive type reasoning.

    (FOO * * * *) => (MV * *).

    Summary
    Form:  ( DEFUN FOO ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
     FOO
    ACL2 !>(foo 'bar 3 4 5)
    (4 5)
    ACL2 !>(mv-let (a b)
                   (foo 'bar 3 4 5)
                   (cons b a))
    (5 . 4)
    ACL2 !>

  Most readers would be well served to avoid reading the rest of this
  documentation of [47mreturn-last[0m.  For reference, however, below we
  document it in some detail.  We include some discussion of its
  evaluation, in particular its behavior in raw Lisp, because we
  expect that most who read further are working with raw Lisp code
  (and trust tags).

  [47mReturn-last[0m is an ACL2 function that can arise from macroexpansion of
  certain utilities that return their last argument, which may be a
  multiple value.  Consider for example the simplest of these,
  [47m[prog2$][0m:

    ACL2 !>:trans1 (prog2$ (cw \"Some CW printing...~%\") (+ 3 4))
     (RETURN-LAST 'PROGN
                  (CW \"Some CW printing...~%\")
                  (+ 3 4))
    ACL2 !>

  Notice that a call of [47mprog2$[0m macroexpands to a call of [47mreturn-last[0m in
  which the first argument is [47m(quote progn)[0m.  Although [47mreturn-last[0m is
  a function in the ACL2 world, it is implemented ``under the hood''
  as a macro in raw Lisp, as the following log (continuing the
  example above) illustrates.

    ACL2 !>:q

    Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
    ? (macroexpand-1 '(RETURN-LAST 'PROGN
                                    (CW \"Some CW printing...~%\")
                                    (+ 3 4)))
    (PROGN (LET ((*AOKP* T)) (CW \"Some CW printing...~%\")) (+ 3 4))
    T
    ?

  Thus, the original [47mprog2$[0m call generates a corresponding call of
  [47mprogn[0m in raw Lisp, which in turn causes evaluation of each argument
  and returns whatever is returned by evaluation of the last (second)
  argument.

  Remark for those who use [47m[defattach][0m.  The binding of [47m*aokp*[0m to [47mt[0m is
  included for the second argument as shown in most cases.  That
  binding is avoided only when the first argument is of the form
  [47m(QUOTE S)[0m for [47mS[0m a macro name and the second argument is a symbol or
  of the form [47m(QUOTE X)[0m for any [47mX[0m.  By binding [47m*aokp*[0m to [47mt[0m, ACL2 is
  permitted to use attachments when evaluating the second argument of
  [47mreturn-last[0m (hence, in the first argument of [47m[prog2$][0m), even in
  contexts such as proofs in which attachments are normally not
  allowed.

  In general, a form [47m(return-last (quote F) X Y)[0m macroexpands to [47m(F X
  Y)[0m, where [47mF[0m is a symbol defined in raw Lisp to return its last
  argument.  The case that [47mF[0m is [47mprogn[0m is a bit misleading, because it
  is so simple.  More commonly, macroexpansion produces a call of a
  macro defined in raw Lisp that may produce side effects.  Consider
  for example the ACL2 utility [47m[with-guard-checking][0m, which is
  intended to change the [guard]-checking mode to the indicated value
  (see [with-guard-checking]).

    ACL2 !>(with-guard-checking :none (car 3)) ; no guard violation
    NIL
    ACL2 !>:trans1 (with-guard-checking :none (car 3))
     (WITH-GUARD-CHECKING1 (CHK-WITH-GUARD-CHECKING-ARG :NONE)
                           (CAR 3))
    ACL2 !>:trans1 (WITH-GUARD-CHECKING1 (CHK-WITH-GUARD-CHECKING-ARG :NONE)
                                         (CAR 3))
     (RETURN-LAST 'WITH-GUARD-CHECKING1-RAW
                  (CHK-WITH-GUARD-CHECKING-ARG :NONE)
                  (CAR 3))
    ACL2 !>:q

    Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
    ? (macroexpand-1
       '(RETURN-LAST 'WITH-GUARD-CHECKING1-RAW
                     (CHK-WITH-GUARD-CHECKING-ARG :NONE)
                     (CAR 3)))
    (WITH-GUARD-CHECKING1-RAW (CHK-WITH-GUARD-CHECKING-ARG :NONE) (CAR 3))
    T
    ? (pprint
       (macroexpand-1
        '(WITH-GUARD-CHECKING1-RAW
          (CHK-WITH-GUARD-CHECKING-ARG :NONE)
          (CAR 3))))

    (LET ((ACL2_GLOBAL_ACL2::GUARD-CHECKING-ON
           (CHK-WITH-GUARD-CHECKING-ARG :NONE)))
      (DECLARE (SPECIAL ACL2_GLOBAL_ACL2::GUARD-CHECKING-ON))
      (CAR 3))
    ?

  The above raw Lisp code binds the state global variable
  [47mguard-checking-on[0m to [47m:none[0m, as [47mchk-with-guard-checking-arg[0m is just
  the identity function except for causing a hard error for an
  illegal input.

  The intended use of [47mreturn-last[0m is that the second argument is
  evaluated first in a normal manner, and then the third argument is
  evaluated in an environment that may depend on the value of the
  second argument.  (For example, the macro [47m[with-prover-time-limit][0m
  macroexpands to a call of [47mreturn-last[0m with a first argument of
  [47m'WITH-PROVER-TIME-LIMIT1-RAW[0m, a second argument that evaluates to a
  numeric time limit, and a third argument that is evaluated in an
  environment where the theorem prover is restricted to avoid running
  longer than that time limit.)  Although this intended usage model
  is not strictly enforced, it is useful to keep in mind in the
  following description of how calls of [47mreturn-last[0m are handled by
  the ACL2 evaluator.

  When a form is submitted in the top-level loop, it is handled by
  ACL2's custom evaluator.  That evaluator is specified to respect
  the semantics of the expression supplied to it: briefly put, if an
  expression [47mE[0m evaluates to a value [47mV[0m, then the equality [47m(equal E
  (quote V))[0m should be a theorem.  Notice that this specification
  does not discuss the side-effects that may occur when evaluating a
  call of [47mreturn-last[0m, so we discuss that now.  Suppose that the ACL2
  evaluator encounters the call [47m(return-last 'fn expr1 expr2)[0m.  First
  it evaluates [47mexpr1[0m.  If this evaluation succeeds without error,
  then it constructs an expression of the form [47m(fn *x* ev-form)[0m,
  where *x* is a Lisp variable bound to the result of evaluating
  [47mexpr1[0m and [47mev-form[0m is a call of the evaluator for [47mexpr2[0m.  (Those who
  want implementation details are invited to look at function
  [47mev-rec-return-last[0m in ACL2 source file [47mtranslate.lisp[0m.)  There are
  exceptions if [47mfn[0m is [47mprogn[0m, [47mec-call1-raw[0m, [47mwith-guard-checking1-raw[0m,
  or [47mmbe1-raw[0m, but the main idea is the same: do a reasonable job
  emulating the behavior of a raw-Lisp call of [47mreturn-last[0m.

  The following log shows how a [47m[time$][0m call can generate a call of the
  evaluator for the last argument of [47mreturn-last[0m (argument [47mexpr2[0m,
  above).  We use [47m:[0m[47m[trans1][0m to show single-step macroexpansions,
  which indicate how a call of [47m[time$][0m expands to a call of
  [47mreturn-last[0m.  The implementation actually binds the Lisp variable
  [47m*RETURN-LAST-ARG3*[0m to [47mexpr2[0m before calling the ACL2 evaluator,
  [47mev-rec[0m.

    ACL2 !>:trans1 (time$ (+ 3 4))
     (TIME$1 (LIST 0 NIL NIL NIL NIL)
             (+ 3 4))
    ACL2 !>:trans1 (TIME$1 (LIST 0 NIL NIL NIL NIL)
                           (+ 3 4))
     (RETURN-LAST 'TIME$1-RAW
                  (LIST 0 NIL NIL NIL NIL)
                  (+ 3 4))
    ACL2 !>(time$ (+ 3 4))
    ; (EV-REC *RETURN-LAST-ARG3* ...) took
    ; 0.00 seconds realtime, 0.00 seconds runtime
    ; (1,120 bytes allocated).
    7
    ACL2 !>

  We now show how things can go wrong in other than the ``intended
  use'' case described above.  In the example below, the macro
  [47mmac-raw[0m is operating directly on the syntactic representation of
  its first argument, which it obtains of course as the second
  argument of a [47mreturn-last[0m call.  Again this ``intended use'' of
  [47mreturn-last[0m requires that argument to be evaluated and then only
  its result is relevant; its syntax is not supposed to matter.  We
  emphasize that only top-level evaluation depends on this ``intended
  use''; once evaluation is passed to Lisp, the issue disappears.  We
  illustrate below how to use the [47m[top-level][0m utility to avoid this
  issue; see [top-level].  The example uses the utility [47mdefmacro-last[0m
  to ``install'' special handling of the raw-Lisp macro [47mmac-raw[0m by
  [47mreturn-last[0m; later below we discuss [47mdefmacro-last[0m.

     ACL2 !>(defttag t)

     TTAG NOTE: Adding ttag :T from the top level loop.
      T
     ACL2 !>(progn!
              (set-raw-mode t)
              (defmacro mac-raw (x y)
                `(progn (print (quote ,(cadr x)))
                        (terpri) ; newline
                        ,y)))

     Summary
     Form:  ( PROGN! (SET-RAW-MODE T) ...)
     Rules: NIL
     Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
      NIL
     ACL2 !>(defmacro-last mac)
     [[ ... output omitted ... ]]
      RETURN-LAST-TABLE
     ACL2 !>(return-last 'mac-raw '3 nil)

     ***********************************************
     ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
     Error:  Fault during read of memory address #x120000300006
     ***********************************************

     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 !>(top-level (return-last 'mac-raw '3 nil))

     3
     NIL
     ACL2 !>

  We next describe how to extend the behavior of [47mreturn-last[0m.  This
  requires an active trust tag (see [defttag]), and is accomplished
  by extending a [table] provided by ACL2, see [return-last-table].
  Rather than using [47m[table][0m [events] directly for this purpose, it is
  probably more convenient to use a macro, [47mdefmacro-last[0m.  We
  describe the community book [47mbooks/misc/profiling.lisp[0m in order to
  illustrate how this works.  The events in that book include the
  following, which are described below.

    (defttag :profiling)

    (progn!
     (set-raw-mode t)
     (load (concatenate 'string (cbd) \"profiling-raw.lsp\")))

    (defmacro-last with-profiling)

  The first event introduces a trust tag.  The second loads a file into
  raw Lisp that defines a macro, [47mwith-profiling-raw[0m, which can do
  profiling for the form to be evaluated.  The third introduces an
  ACL2 macro [47mwith-profiling[0m, whose calls expand into calls of the
  form [47m(return-last (quote with-profiling-raw) & &)[0m.  The third event
  also extends [47m[return-last-table][0m so that these calls will expand in
  raw Lisp to calls of [47mwith-profiling-raw[0m.

  The example above illustrates the following methodology for
  introducing a macro that returns its last argument but produces
  useful side-effects with raw Lisp code.

      (1) Introduce a trust tag (see [defttag]).

      (2) Using [47m[progn!][0m, load into raw Lisp a file defining a macro,
      [47mRAW-NAME[0m, that takes two arguments, returning its last (second)
      argument but using the first argument to produce desired side
      effects during evaluation of that last argument.

      (3) Evaluate the form [47m(defmacro-last NAME :raw RAW-NAME)[0m.  This will
      introduce [47mNAME[0m as an ACL2 macro that expands to a corresponding
      call of [47mRAW-NAME[0m (see (2) above) in raw Lisp.  The
      specification of keyword value of [47m:raw[0m as [47mRAW-NAME[0m may be
      omitted if [47mRAW-NAME[0m is the result of modifying the symbol [47mNAME[0m
      by suffixing the string [47m\"-RAW\"[0m to the [47m[symbol-name][0m of [47mNAME[0m.

  WARNING: Not every use of [47mreturn-last[0m can be soundly evaluated
  outside a function body.  The reason is that ACL2's evaluator,
  [47mev-rec[0m, recurs through terms that are presented in the top-level
  loop, and handles [47mreturn-last[0m calls in a special manner: basically,
  the call of [47mev-rec[0m on the form [47m(return-last 'mac-raw x y)[0m leads to
  evaluation of a macro call of the form [47m(mac-raw *return-last-arg2*
  (ev-rec ...))[0m, where *return-last-arg2* is a global variable bound
  to the result of evaluating [47mx[0m with [47mev-rec[0m.  Consider the following
  example.

    (defttag t)
    (set-raw-mode-on state)
    (defmacro mac-raw (str y) ; print message is an atom
     `(let ((result (consp ,y))
            (str ,str))
        (or result
            (prog2$ (fmx ,str ',y)
                    nil))))
    (set-raw-mode-off state)
    (defmacro-last mac)
    ; Horrible error:
    (mac \"Not a cons: ~x0~%\" 17)
    ; Works, but probably many would consider it awkward to use top-level:
    (top-level (mac \"Not a cons: ~x0~%\" 17))

  In such cases we suggest supplying keyword [47m:top-level-ok nil[0m to the
  call of [47mdefmacro-last[0m, for example:

    (defmacro-last mac :top-level-ok nil)

  Then any attempt to call [47mmac[0m at the top level, as opposed to inside a
  function body, will cause a clean error before evaluation begins.

  It is useful to explore what is done by [47mdefmacro-last[0m.

    ACL2 !>:trans1 (defmacro-last with-profiling)
     (PROGN (DEFMACRO WITH-PROFILING (X Y)
                      (LIST 'RETURN-LAST
                            (LIST 'QUOTE 'WITH-PROFILING-RAW)
                            X Y))
            (TABLE RETURN-LAST-TABLE 'WITH-PROFILING-RAW
                   'WITH-PROFILING))
    ACL2 !>:trans1 (with-profiling '(assoc-eq fgetprop rewrite) (mini-proveall))
     (RETURN-LAST 'WITH-PROFILING-RAW
                  '(ASSOC-EQ FGETPROP REWRITE)
                  (MINI-PROVEALL))
    ACL2 !>:q

    Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
    ? (macroexpand-1
       '(RETURN-LAST 'WITH-PROFILING-RAW
                     '(ASSOC-EQ FGETPROP REWRITE)
                     (MINI-PROVEALL)))
    (WITH-PROFILING-RAW '(ASSOC-EQ FGETPROP REWRITE) (MINI-PROVEALL))
    T
    ?

  To understand the macro [47mwith-profiling-raw[0m you could look at the
  community book loaded above: [47mbooks/misc/profiling-raw.lsp[0m.

  We mentioned above that ACL2 tends to print calls of [47m[prog2$][0m or
  [47m[time$][0m (or other such utilities) instead of calls of [47mreturn-last[0m.
  Here we elaborate that point.  ACL2's `[47muntranslate[0m' utility treats
  [47m(return-last (quote F) X Y)[0m as [47m(G X Y)[0m if [47mF[0m corresponds to the
  symbol [47mG[0m in [47mreturn-last-table[0m.  However, it is generally rare to
  encounter such a term during a proof, since calls of [47mreturn-last[0m
  are generally expanded away early during a proof.

  Calls of [47mreturn-last[0m that occur in code --- forms submitted in the
  top-level ACL2 loop, and definition bodies other than those marked
  as [47m[non-executable][0m (see [defun-nx]) --- have the following
  restriction: if the first argument is of the form [47m(quote F)[0m where [47mF[0m
  is a non-[47mnil[0m symbol, then [47mF[0m must be an entry in [47mreturn-last-table[0m.
  There are however four exceptions: the following symbols are
  considered to be keys of [47mreturn-last-table[0m even if they are no
  longer associated with non-[47mnil[0m values, say because of a [47m[table][0m
  event with keyword [47m:clear[0m.

      * [47mprogn[0m, associated with [47m[prog2$][0m
      * [47mmbe1-raw[0m, associated with [47mmbe1[0m, a version of [47mmbe[0m
      * [47mec-call1-raw[0m, associated with [47mec-call1[0m (a variant of [47m[ec-call][0m)
      * [47mwith-guard-checking1-raw[0m, associated with [47mwith-guard-checking1[0m (a
      variant of [47m[with-guard-checking][0m)

  Note that because of its special status, it is illegal to trace
  [47mreturn-last[0m.

  For any object [47mx[0m that is not of the form [47m(quote S)[0m where [47mS[0m is a
  symbol, the call [47m(return-last x y z)[0m is legal, even in code, if [47my[0m
  and [47mz[0m are legal.  Such terms are evaluated as though [47mx[0m is [47m(QUOTE
  PROGN)[0m, that is, as though they arose from a call of [47m[prog2$][0m.  In
  particular, you are welcome to write terms of the form [47m(return-last
  '(<some-annotation>) y z)[0m.

  We conclude by warning that as a user, you take responsibility for
  not compromising the soundness or error handling of ACL2 when you
  define a macro in raw Lisp and especially when you install it as a
  key of [47m[return-last-table][0m, either directly or (more likely) using
  [47mdefmacro-last[0m.  In particular, be sure that you are defining a
  macro of two arguments that always returns the value of its last
  argument, returning the complete multiple value if that last
  argument evaluates to a multiple value.

  The following is correct, and illustrates care taken to return
  multiple values.

    (defttag t)
    (set-raw-mode t)
    (defmacro my-time1-raw (val form)
      (declare (ignore val))
      `(let  ((start-time (get-internal-run-time))
              (result (multiple-value-list ,form))
              (end-time (get-internal-run-time)))
         (format t \"Total time: ~s~%\"
                 (float (/ (- end-time start-time)
                           internal-time-units-per-second)))
         (values-list result)))
    (set-raw-mode nil)
    (defmacro-last my-time1)
    (defmacro my-time (form)
      `(my-time1 nil ,form))

  Then for example:

    ACL2 !>(my-time (equal (make-list 1000000) (make-list 1000000)))
    Total time: 0.12
    T
    ACL2 !>

  But if instead we provide the following more naive implementation, of
  the above raw Lisp macro, the above evaluation can produce an
  error, for example if the host Lisp is CCL.

    (defmacro my-time1-raw (val form)
        (declare (ignore val))
        `(let  ((start-time (get-internal-run-time))
                (result ,form)
                (end-time (get-internal-run-time)))
           (format t \"Total time: ~s~%\"
                   (float (/ (- end-time start-time)
                             internal-time-units-per-second)))
           result)) ; WRONG -- need multiple values returned!

  Here is a second, similar example.  This time we'll start with the
  error; can you spot it?

    (defttag t)
    (progn!
     (set-raw-mode t)
     (defmacro foo-raw (x y)
       `(prog1
            ,y
          (cw \"Message showing argument 1: ~x0~%\" ,x))))
    (defmacro-last foo)

  We then can wind up with a hard Lisp error:

    ACL2 !>(foo 3 (mv 4 5))
    Message showing argument 1: 3

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  value NIL is not of the expected type REAL.
    ***********************************************

    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 !>

  Here is a corrected version of the above macro.  The point here is
  that [47mprog1[0m returns a single value, while [47mour-multiple-value-prog1[0m
  returns all the values that are returned by its first argument.

    (progn!
     (set-raw-mode t)
     (defmacro foo-raw (x y)
       `(our-multiple-value-prog1 ;; better
         ,y
         (cw \"Message showing argument 1: ~x0~%\" ,x))))

  [31;1mFunction: [0m<return-last>

    (defun return-last (fn eager-arg last-arg)
      (declare (ignore fn eager-arg)
               (xargs :guard
                      (if (equal fn 'mbe1-raw)
                          (equal last-arg eager-arg)
                        t)))
      last-arg)


Subtopics

  [Return-last-table]
      Install special raw Lisp behavior")
 (RETURN-LAST-TABLE
  (RETURN-LAST)
  "Install special raw Lisp behavior

  Please first see [return-last] for relevant background.

  This [table] is for advanced users only, and requires an active trust
  tag (see [defttag]).  We recommend that you do not modify this
  table directly, but instead use the macro [47mdefmacro-last[0m.  Here we
  augment that discussion with some highly technical observations
  that can probably be ignored if you use [47mdefmacro-last[0m.

  This [table] has a [47m:guard[0m requiring that each key be a symbol defined
  in raw Lisp, generally as a macro, and requiring that each non-[47mnil[0m
  value be associated either with a symbol that names a macro defined
  in ACL2, or else with a list of one element containing such a
  symbol.  The table can only be modified when there is an active
  trust tag; see [defttag].  If a key is associated with the value
  [47mnil[0m, then that key is treated as though it were not in the table.

  Note that keys of this table are not eligible to be bound by [47m[flet][0m
  or [47m[macrolet][0m.  The current value of this table may be obtained by
  evaluating the form [47m(table-alist 'return-last-table (w state))[0m.
  The built-in constant [47m*initial-return-last-table*[0m holds the initial
  value of this table.")
 (REVAPPEND
  (LISTS ACL2-BUILT-INS)
  "Concatenate the [reverse] of one list to another

  [47m(Revappend x y)[0m [concatenate]s the [reverse] of the list [47mx[0m to [47my[0m,
  which is also typically a list.

  The following theorem characterizes this English description.

    (equal (revappend x y)
           (append (reverse x) y))

  Hint: This lemma follows immediately from the definition of [47m[reverse][0m
  and the following lemma.

    (defthm revappend-append
      (equal (append (revappend x y) z)
             (revappend x (append y z))))

  The [guard] for [47m(revappend x y)[0m requires that [47mx[0m is a true list.

  [47mRevappend[0m is defined in Common Lisp.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<revappend>

    (defun revappend (x y)
      (declare (xargs :guard (true-listp x)))
      (if (endp x)
          y
        (revappend (cdr x) (cons (car x) y))))")
 (REVERSE
  (LISTS STRINGS ACL2-BUILT-INS)
  "Reverse a list or string

  [47m(Reverse x)[0m is the result of reversing the order of the elements of
  the list or string [47mx[0m.

  The [guard] for [47mreverse[0m requires that its argument is a true list or
  a string.

  [47mReverse[0m is defined in Common Lisp.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<reverse>

    (defun reverse (x)
      (declare (xargs :guard (or (true-listp x) (stringp x))))
      (cond ((stringp x)
             (coerce (revappend (coerce x 'list) nil)
                     'string))
            (t (revappend x nil))))")
 (REVERT-WORLD
  (PROGRAMMING)
  "Evaluate without (ultimately) changing the [world]

    General Form:
    (revert-world form)

  where [47mform[0m evaluates to an [error-triple].

  Evaluation of [47m(revert-world form)[0m returns the same result, [47m(mv erp
  val state)[0m, as the given [47mform[0m, except that the [world] of the
  returned [47m[state][0m is the same as the world of the input state even
  if the evaluation of [47mform[0m modifies the world of the input state.

  To see [47mrevert-world[0m in action, consider the following definition.

    (defun test-revert-world (state)
     (declare (xargs :mode :program :stobjs state))
     (er-progn
      (value (cw \"Length of (w state) before defun: ~x0~%\"
                 (length (w state))))
      (revert-world (er-progn
                     (trans-eval '(with-output :off :all ; avoid output ;
                                    (defun foo (x) x))
                                 'my-ctx state nil)
                     (value (cw \"Length of (w state) after defun: ~x0~%\"
                                (length (w state))))))
      (value (cw \"Length of (w state) after revert-world: ~x0~%\"
                 (length (w state))))))

  Here is a log produced after admitting the definition above in a
  fresh session (for an ACL2 build circa November 2017).  It shows
  that the definition lengthens the world, but that the world's
  length is back to its initial value after we return from
  [47mrevert-world[0m.

    ACL2 !>(test-revert-world state)
    Length of (w state) before defun: 107133
    Length of (w state) after defun: 107153
    Length of (w state) after revert-world: 107133
     NIL
    ACL2 !>:pbt 0
               0  (EXIT-BOOT-STRAP-MODE)
     P         1:x(DEFUN TEST-REVERT-WORLD (STATE) ...)
    ACL2 !>

  The macroexpansion of [47m(revert-world form)[0m contains a call of a
  [program]-mode function.  It is thus illegal to call [47mrevert-world[0m
  in the body of a [logic]-mode function.  Contact the ACL2
  implementors if you want them to consider working to lift this
  restriction.")
 (REVISITING_THE_ADMISSION_OF_APP
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Revisiting the Admission of App

  {IMAGE} (see [Evaluating_App_on_Sample_Input])

  Here is the definition of [47mapp[0m again with certain parts highlighted.
  If you are taking the Walking Tour, please read the text carefully
  and click on each of the links below, [31;1mexcept those marked[0m {ICON}
  (see [A_Tiny_Warning_Sign]).  Then come [31;1mback[0m here.

  {IMAGE}

    ACL2 !> (see [About_the_Prompt])[31;1m(defun app (x y)[0m
      [31;1m(cond ((endp x) y)[0m
            [31;1m(t (cons (car x) [0m
                     [31;1m(app (cdr x) y)))))[0m

    The admission (see [About_the_Admission_of_Recursive_Definitions]) of APP is trivial, using the
    relation [o<] {ICON} (see [A_Tiny_Warning_Sign]) (which is known to be well-founded on
    the domain recognized by [o-p] {ICON} (see [A_Tiny_Warning_Sign])) and the measure
    ([ACL2-count] {ICON} (see [A_Tiny_Warning_Sign]) X).  We observe (see [Guessing_the_Type_of_a_Newly_Admitted_Function]) that the
    type (see [About_Types]) of APP is described by the theorem (OR
    (CONSP (APP X Y)) (EQUAL (APP X Y) Y)).  We used primitive type
    reasoning.

    Summary (see [The_Event_Summary])
    Form:  ( DEFUN APP ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Warnings:  None
    Time:  0.03 seconds (prove: 0.00, print: 0.00, other: 0.03)
     APP

  {IMAGE}

  {IMAGE} (see [Evaluating_App_on_Sample_Input])")
 (REWRITE
  (RULE-CLASSES)
  "Make some [47m:rewrite[0m rules (possibly conditional ones)

  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.

  This doc topic discusses the rule-class [47m:rewrite[0m.  If you want a
  general discussion of how rewriting works in ACL2 and some guidance
  on how to construct effective rewrite rules, see
  [introduction-to-rewrite-rules-part-1] and then see
  [introduction-to-rewrite-rules-part-2].  If you want a flexible,
  convenient interface to the ACL2 rewriter that can be called
  programmatically, see [rewrite$].

    Examples:

    (defthm plus-commutes                 ; Replace (+ a b) by (+ b a) provided
      (equal (+ x y) (+ y x)))            ; certain heuristics approve the
                                          ; permutation.

    (defthm plus-commutes                 ; equivalent to the above
      (equal (+ x y) (+ y x))
      :rule-classes ((:rewrite :corollary (equal (+ x y) (+ y x))
                               :loop-stopper ((x y binary-+))
                               :match-free :all)))

    (defthm append-nil                    ; Replace (append a nil) by a, if
      (implies (true-listp x)             ; (true-listp a) rewrites to t.
               (equal (append x nil) x)))

    (defthm append-nil                    ; as above, but with defaults and
      (implies (true-listp x)             ; a backchain limit
               (equal (append x nil) x))
      :rule-classes ((:rewrite :corollary (implies (true-listp x)
                                                   (equal (append x nil) x))
                               :backchain-limit-lst (3) ; or equivalently, 3
                               :match-free :all)))

    (defthm member-append                 ; Replace (member e (append b c)) by
      (implies                            ; (or (member e b) (member e c) in
       (and                               ; contexts in which propositional
        (true-listp x)                    ; equivalence is sufficient, provided
        (true-listp y))                   ; b and c are true-lists.
       (iff (member e (append x y))
            (or (member e x) (member e y)))))

    General Form:
    (and ...
         (implies (and ...hi...)
                  (implies (and ...hk...)
                           (and ...
                                (equiv lhs rhs)
                                ...)))
         ...)

  Note: One [47m:rewrite[0m rule class object might create many rewrite rules
  from the [47m:[0m[47m[corollary][0m formula.  To create the rules, we first
  translate the formula, expanding all macros (see [trans]) and also
  removing [guard-holders].  Next, we then flatten the [47m[and][0m and
  [47m[implies][0m structure of the formula; for example, if the hypothesis
  or conclusion is of the form [47m(and (and term1 term2) term3)[0m, then we
  replace that by the ``flat'' term [47m(and term1 term2 term3)[0m.  (The
  latter is actually an abbreviation for the right-associated term
  [47m(and term1 (and term2 term3))[0m.)  During this flattening process, we
  eliminate [47m[lambda][0ms as necessary in order to continue flattening;
  one may think of this step as simply substituting to eliminate
  [47m[let][0m, [47m[let*][0m, and [47m[mv-let][0m in order to expose more calls of
  [47mimplies[0m and [47mand[0m.  The result is a conjunction of formulas, each of
  the form

    (implies (and h1 ... hn) concl)

  where no hypothesis is a conjunction and [47mconcl[0m is neither a
  conjunction nor an implication.  If necessary, the hypothesis of
  such a conjunct may be vacuous.  We then further coerce each [47mconcl[0m
  into the form [47m(equiv lhs rhs)[0m, where we continue to eliminate
  [47mlambdas[0m until we reach this form, and then we eliminate [47mlambdas[0m
  from the first argument of [47mequiv[0m but not the second argument.  Here
  [47mequiv[0m is a known [equivalence] relation.  If we do not reach an
  equivalence relation, even after eliminating [47mlambdas[0m, then we
  replace the resulting term, [47mterm[0m by [47m(iff term t)[0m, except that we
  replace [47m(not term)[0m by [47m(iff term nil)[0m.  By these steps we reduce the
  given [47m:[0m[47m[corollary][0m to a sequence of conjuncts, each of which is of
  the form

    (implies (and h1 ... hn)
             (equiv lhs rhs))

  where [47mequiv[0m is a known [equivalence] relation and [47mlhs[0m has no [47mlambda[0ms.
  See [equivalence] for a general discussion of the introduction of
  new [equivalence] relations.  At this point, we check whether [47mlhs[0m
  and [47mrhs[0m are the same term; if so, we cause an error, since this
  rule will loop.  (But this is just a basic check; the rule could
  loop in other cases, for example if [47mrhs[0m is an instance of [47mlhs[0m; see
  [loop-stopper].)

  You can experiment by creating some rewrite rules using [47m[defthm][0m and
  then using [47m:[0m[47m[pr][0m to see how the rule was stored.

  We create a [47m:rewrite[0m rule for each such conjunct, if possible, and
  otherwise cause an error.  It is possible to create a rewrite rule
  from such a conjunct provided [47mlhs[0m is not a variable, a quoted
  constant, a [47m[let][0m-expression, or a [47mlambda[0m application.  Although it
  is legal to create a rewrite rule from an [47m[if][0m-expression [47m(if tst
  tbr fbr)[0m, note that the rewriter uses the truth or falsity of the
  test, [47mtst[0m, when rewriting the true and false branches [47mtbr[0m and [47mfbr[0m,
  respectively; so rewrite rules are most often unnecessary for
  [47mif[0m-expressions.

  A [47m:rewrite[0m rule is used when any instance of the [47mlhs[0m occurs in a
  context in which the [equivalence] relation is an admissible
  [congruence] relation.  First, we find a substitution that makes
  [47mlhs[0m equal to the target term.  Then we attempt to relieve the
  instantiated hypotheses of the rule.  Hypotheses that are fully
  instantiated are relieved by recursive rewriting.  Hypotheses that
  contain ``free variables'' (variables not assigned by the unifying
  substitution) are relieved by attempting to guess a suitable
  instance so as to make the hypothesis equal to some known
  assumption in the context of the target.  If the hypotheses are
  relieved, and certain restrictions that prevent some forms of
  infinite regress are met (see [loop-stopper]), the target is
  replaced by the instantiated [47mrhs[0m, which is then recursively
  rewritten.

  ACL2's rewriting process has some optimizations, including the
  following.

    * The suggestion, above, that the rewriter looks through the goal
      [clause] for ``any instance of the [47mlhs[0m'' is not quite true.
      [47m:Rewrite[0m rules are never applied to quoted constants or any
      term inside a call of [47m[hide][0m.  If you want to rewrite a quoted
      constant use a [47m:[0m[47m[rewrite-quoted-constant][0m rule.

    * The notion of ``a substitution that makes [47mlhs[0m equal to the target
      term'' is a bit more generous than the most straightforward
      such notion.  Suppose for example that [47mlhs[0m is [47m(f (+ 3 x))[0m and
      the target term is [47m(f (+ 3 (g y))[0m.  (Aside: ACL2 deals in
      so-called translated terms, so since [47m+[0m is a macro, [47mlhs[0m and term
      would actually be [47m(f (binary-+ '3 x))[0m and [47m(f (binary-+ '3 (g
      y)))[0m; we will ignore this distinction, but if you want more
      information, see [term].)  Then of course, that substitution
      binds [47mx[0m to [47m(g y)[0m.  But now suppose that instead the target term
      is [47m(f 10)[0m.  You may be surprised to learn that the substitution
      binding [47mx[0m to [47m7[0m makes [47m(f (+ 3 x))[0m equal to [47m(f 10)[0m; for example,
      the rewrite rule [47m(equal (f (+ x 3)) (h x)))[0m would rewrite [47m(f
      10)[0m to [47m(h 7)[0m.  This would also be the case if [47mlhs[0m were instead
      [47m(f (+ x 3))[0m.  This sort of optimization occurs when the new
      constant has [47m[ACL2-count][0m no greater than the old constant.
      There are similar optimizations for [47m*[0m, [47m/[0m, [47m-[0m, strings, symbols,
      and conses (for details see ACL2 source function
      [47mone-way-unify1-quotep-subproblems[0m).

    * When a term [47mt1[0m is rewritten to a new term [47mt2[0m, the rewriter is then
      immediately applied to [47mt2[0m.  On rare occasions you may find that
      you do not want this behavior, in which case you may wish to
      use a trick involving [47m[hide][0m; see [meta], near the end of that
      documentation.

    * When the hypotheses and right-hand side are rewritten, ACL2 does not
      really first apply the substitution and then rewrite; instead,
      as it rewrites those terms it looks up the [3malready rewritten[0m
      values of the bound variables.  Sometimes you may want those
      bindings rewritten again, e.g., because the variables occur in
      slots that admit additional equivalence relations.  See
      [double-rewrite].

  See [introduction-to-rewrite-rules-part-1] and see
  [introduction-to-rewrite-rules-part-2] for an extended discussion
  of how to create effective rewrite rules.


Subtopics

  [Assume-true-false-aggressive-p]
      Control rewriter's use of the [type-alist] with [47mIF[0m calls

  [Backchain-limit]
      Limiting the effort expended on relieving hypotheses

  [Bind-free]
      To bind free variables of a rewrite, definition, or linear rule

  [Case-split]
      Like force but immediately splits the top-level goal on the
      hypothesis

  [Double-rewrite]
      Cause a term to be rewritten twice

  [Force]
      Identity function used to force a hypothesis

  [Free-variables]
      Free variables in rules

  [Hands-off-lambda-objects-theory]
      how to specify no modification of lambda objects

  [Hide]
      Hide a term from the rewriter

  [Loop-stopper]
      Limit application of permutative rewrite rules

  [Random-remarks-on-rewriting]
      Some basic facts about the ACL2 rewriter

  [Remove-trivial-equivalences-enabled-p]
      Avoid removal of trivial equivalences during rewriting

  [Rewrite-equiv]
      Force ACL2 to perform substitution using a stylized [equivalence]
      hypothesis

  [Rewrite-if-avoid-swap]
      Control rewriter's swapping of branches of [47mIF[0m calls

  [Rewrite-lambda-modep]
      switch controlling rewriting of lambda objects

  [Rewrite-lambda-object]
      rewriting lambda objects in :FN slots

  [Rewrite-lambda-object-actions]
      actions available when rewriting lambda objects

  [Rewrite-lambda-objects-theory]
      how to specify rewriting of lambda objects

  [Rewrite-stack-limit]
      Limiting the stack depth of the ACL2 rewriter

  [Rewriting-versus-cleaning-up-lambda-objects]
      why change the default action on rewriting [47mlambda[0m objects

  [Rw-cache-state]
      The current rw-cache-state

  [Set-rw-cache-state]
      Set the default rw-cache-state

  [Set-rw-cache-state!]
      Set the default rw-cache-state non-[47m[local][0mly

  [Simple]
      [47m:[0m[47m[definition][0m and [47m:[0m[47m[rewrite][0m rules used in preprocessing

  [Syntactically-clean-lambda-objects-theory]
      how to specify syntactic cleaning of lambda objects

  [Syntaxp]
      Attach a heuristic filter on a rule")
 (REWRITE-CACHE (POINTERS)
                "See [set-rw-cache-state].")
 (REWRITE-EQUIV
  (REWRITE)
  "Force ACL2 to perform substitution using a stylized [equivalence]
  hypothesis

  [47mRewrite-equiv[0m is actually the [identity] function: [47m(rewrite-equiv x)
  = x[0m for all [47mx[0m.  However, a term of the form [47m(hide (rewrite-equiv
  (equiv x y)))[0m appearing in the hypothesis induces ACL2 to
  aggressively substitute [47my[0m for [47mx[0m when [47mequiv[0m is an [equivalence]
  relation (including [47mequal[0m) and [47mx[0m appears in a context in which
  [47mequiv[0m is being maintained.

  Equivalence relations appearing in the hypothesis are not generally
  used by ACL2 to perform substitutions except under special
  circumstances, such as when one argument is a symbol or a constant
  or during the fertilization stage of the [waterfall] process. A
  stylized [47mrewrite-equiv[0m expression of the form [47m(hide (rewrite-equiv
  (equiv x y)))[0m can be used to override this default behavior.  Care
  should be taken in using [47mrewrite-equiv[0m, however, because it can
  easily result in rewrite loops.

  For an example of a [clause-processor] that leverages [47mRewrite-equiv[0m
  to induce substitution using equivalence relations appearing in the
  hypothesis, see [rewrite-equiv-hint].")
 (REWRITE-IF-AVOID-SWAP
  (REWRITE SYSTEM-ATTACHMENTS)
  "Control rewriter's swapping of branches of [47mIF[0m calls

  This topic concerns an advanced control for the ACL2 prover.

  By default, the ACL2 rewriter may swap true and false branches of a
  call of [47mIF[0m, in particular when the test is a call of [47mNOT[0m.  Attach
  the function [47mconstant-t-function-arity-0[0m to defeat this behavior.
  Attach the function [47mconstant-nil-function-arity-0[0m to restore the
  default behavior.")
 (REWRITE-LAMBDA-MODEP
  (REWRITE)
  "switch controlling rewriting of lambda objects

  [47mRewrite-lambda-modep[0m is an identity function with no purpose other
  than to serve as a switch controlling whether and how the ACL2
  prover rewrites quoted [47mlambda[0m objects in argument positions of
  [ilk] [47m:FN[0m.  Behavior is determined by the enabled status of two
  runes associated with [47mrewrite-lambda-modep[0m, the
  executable-counterpart rune and the definition rune.  See
  [rewrite-lambda-object].")
 (REWRITE-LAMBDA-OBJECT
  (REWRITE)
  "rewriting lambda objects in :FN slots

  [47m[Lambda][0m objects are quoted constants passed to [scion]s and applied
  as functions by [47m[apply$][0m.  The ACL2 rewriter can be made to replace
  the bodies of quoted [47mlambda[0m objects with (supposedly) simpler
  bodies that are [47m[ev$][0m equivalent, when the lambda objects occur in
  slots of [ilk] [47m:FN[0m.  However, there are restrictions on which
  lambda objects can be so simplified, restrictions on the techniques
  available to the rewriter during the simplification of [47mlambda[0m
  bodies, and restrictions controlling whether the simplified body
  replaces the original or is ignored.  We explain below.


When an Occurrence of a [47mlambda[0m Objects Is Eligible

  An occurrence of a quoted [47mlambda[0m object is eligible to be simplified
  provided

    * (a) it occurs in a [47m:FN[0m position of a call of a [scion],

    * (b) the [47mlambda[0m object is well-formed (see
      [47m[well-formed-lambda-objectp][0m),

    * (c) every function symbol mentioned in the body has been warranted

  However, eligible quoted [47mlambda[0m objects are not modified at all if
  the [rune] [47m(:executable-counterpart rewrite-lambda-modep)[0m is
  [disable]d.  That rune is enabled by default.

  Condition (b) implies the body of the [47mlambda[0m is in fact a well-formed
  ACL2 term (so the rewriter can explore it), every function symbol
  in it is [badge]d (so that function objects mentioned are used
  properly), that every variable symbol occurring freely in the body
  is among the formals of the [47mlambda[0m object, and together with (c)
  implies that the term ``behaves'' as expected if the appropriate
  warrant hypotheses govern this occurrence of the object.  This last
  implication means that [47m[ev$][0m of the body is equal to unquoted body
  (under a suitable assignment), which means we can replace the
  unquoted body.

  If (a) holds but either (b) or (c) fails, then a
  [47m\"rewrite-lambda-object\"[0m warning message is printed during the
  proof.  However, this message is only printed once per [47mlambda[0m
  object per proof attempt because otherwise the presence of
  ill-formed [47mlambda[0m-like objects in a conjecture will litter the
  output with repeated warnings.  You may turn these warnings off
  with [47m([0m[47m[toggle-inhibit-warning][0m [47m\"Rewrite-lambda-object\")[0m.


Restrictions During Rewriting of a [47mLambda[0m Body

  The rewriter is restricted in three ways when rewriting the bodies of
  eligible occurrences of [47mlambda[0m objects.

  First, the user can specify one of two actions the rewriter can take
  on an eligible [47mlambda[0m object occurrence (in addition to taking no
  action as controlled by the [47mrewrite-lambda-modep[0m rune mentioned
  above).  The available actions are to recursively call the rewriter
  and normalize the result, or to do syntactic cleaning only.  The
  default is recursive rewriting, with the restrictions explained in
  below.  Syntactic cleaning just eliminates declarations, guards,
  and various tags irrelevant to the logical value of the body.  We
  describe how the user specifies the action to be used in
  [rewrite-lambda-object-actions].  We give more details about these
  two kinds of [47mlambda[0m body simplification in
  [rewriting-versus-cleaning-up-lambda-objects].

  Second, warrant hypotheses in the goal [clause] are the only
  contextual information ``imported'' from the goal clause and made
  available while rewriting a [47mlambda[0m body.  That means type
  information about variables and other terms is forgotten, as are
  any linear arithmetic relationships.  The reason is simple: the
  variables in the body are in a different scope than the variables
  outside the [47mlambda[0m object.  Put another way, we do not know, in
  general, to what the [47mlambda[0m object will eventually be applied and
  so, in ACL2's untyped logic, we know nothing about its formal
  variables.  (Actually, we not only ``import'' the warrants from the
  goal clause, we import every ground hypothesis governing the [47mlambda[0m
  object's occurrence.  But practically speaking that means we only
  import warrant hypotheses.  A more sophisticated handling of
  contextual information can be imagined.  For example, if the [47mlambda[0m
  object occurs as the first argument of a [47m[loop$][0m scion, like
  [47mcollect$[0m or [47msum$[0m, then the rewriter could perhaps extract type
  information from the target and import that information.  For
  example, perhaps every element of the target is a number.  In that
  case, since we know the [47mlambda[0m object in a [47mloop$[0m scion call is only
  applied to elements of that list, we would then be allowed to
  assume the corresponding formal of the [47mlambda[0m object is a number.
  But that more sophisticated handling of contextual information has
  not been implemented.)

  Third, recursive functions are never opened when rewriting [47mlambda[0m
  bodies.  For example, if [47m(len (cons e x))[0m occurs in a [47mlambda[0m body,
  you might expect it to be simplified to [47m(+ 1 (len x))[0m, because that
  is what generally happens to that term when occurrences outside
  [47mlambda[0m objects are rewritten.  ACL2 normally controls the expansion
  of recursive functions by reference to terms that already occur
  within the current goal.  But the [47mlambda[0m object effectively shares
  no variables with the surrounding goal and those heuristics are
  inapplicable.  Preliminary experiments with allowing expansions of
  recursive functions inside [47mlambda[0m objects have produced
  unsatisfactory results such as runaway expansions.  So at the
  moment we allow no recursive expansions.

  The ACL2 implementors hope to address both of the above problems in
  eventual future releases.

  Syntactic cleaning, in contrast to the restricted rewriting just
  described, eliminates declarations, guards, and other
  compiler-related tags introduced by translation of [47mlambda$[0m and
  [47mloop$[0m.  It does beta reduction, which eliminates local variable
  names (other than the formals of the [47mlambda[0m object).  And it
  replaces the last argument of calls of [47m[do$][0m by [47mnil[0m if that
  argument is a quoted constant other than [47mnil[0m.  (This argument is
  irrelevant to the value of the [47mdo$[0m term and only used in error
  reporting.)


What Happens After Rewriting a [47mLambda[0m Body

  After the specified action on the body, [3mb[0m, of [47m(lambda([0m[3mv1...vn[0m[47m)[0m[3mb[0m[47m)[0m to
  produce [3mb'[0m the decision must be made as to whether to return the
  [47mlambda[0m with the rewritten body, [47m(lambda([0m[3mv1...vn[0m[47m)[0m[3mb'[0m[47m)[0m, or to ignore
  the rewrite and return the original (unrewritten) object.  ACL2
  ignores the rewrite and returns the original [47mlambda[0m object if any
  of the following three cases obtains:

    * (a) [3mb'[0m contains variables other than the [47mlambda[0m formals [3mv1,...,vn[0m,

    * (b) [3mb'[0m is not tame, or

    * (c) some function symbol appearing in [3mb'[0m has no warrant hypothesis in
      the goal clause but forcing is disabled (see [47m[force][0m).

  In all cases, the rewriter prints a [47m\"rewrite-lambda-object\"[0m warning
  when the rewritten body is different from the original one but the
  rewrite is rejected.  The warning message displays the before and
  after [47mlambda[0m objects, lists the rewrite rules used, and explains
  which of the three conditions above was violated.  However, this
  message is only printed once per [47mlambda[0m object per proof attempt
  because otherwise the presence of a [47mlambda[0m object that rewrites
  inappropriately will litter the output with repeated warnings.

  Condition (a) can arise if a rewrite rule introduces a free variable;
  disabling that rewrite rule is recommended.  Condition (b) can
  arise if some rewrite rule introduces a function symbol that has
  not been warranted; disabling that rule can often solve that
  problem but perhaps a better response is to use [47m[defwarrant][0m to
  issue a warrant for the offending function symbol and then supply
  that warrant as a hypothesis to the goal; the latter response is
  perhaps better because it means all the ``usual'' rewriting is
  done, normalizing terms as expected.  Condition (c) can be
  addressed by using [47mdefwarrant[0m to issue a warrant for the offending
  function symbol and enabling forcing (see [47m[force][0m).

  The warning message noted above can become annoying.  You may turn
  these warnings off with [47m([0m[47m[toggle-inhibit-warning][0m
  [47m\"Rewrite-lambda-object\")[0m.

  Be advised that if the [47m\"rewrite-lambda-object\"[0m warning has been
  inhibited (by you or some book included in your session) and then,
  when looking at, say, the checkpoints in a failed proof, you see a
  [47mlambda[0m object that you expected to be simplified but was not, you
  may think rewriting was not attempted for it, for some reason, when
  in fact it was attempted but rejected.  You can
  [47m(toggle-inhibit-warning \"Rewrite-lambda-object\")[0m and replay the
  proof attempt to see (all) the rejected [47mlambda[0m object rewrites.


A Possible Confusion

  A metafunction that is included in the book [47mprojects/apply/top[0m can
  also cause quoted [47mlambda[0m objects to be rewritten.  This
  metafunction, called [47mrelink-fancy-scion[0m, is called on certain calls
  of the fancy [47mloop$[0m scions, e.g., calls of [47m[always$+][0m, [47m[collect$+][0m,
  [47m[sum$+][0m, etc.  The goal of that metafunction is to keep the list of
  ``global variables'' in some normal form.

  For example,consider the term

    (collect$+ (quote
                (lambda (loop$-gvars loop$-ivars)
                  (cons (car loop$-gvars)
                        (cons (car (cdr loop$-gvars))
                              (cons (car loop$-ivars) 'nil)))))
               (list a b)
               target)

  which is (essentially) the translation of [47m(loop$ for e in target
  collect (list a b e))[0m.  Suppose that in some case of a proof about
  this term the hypothesis [47m(equal a b)[0m governs this term.  The term
  would thus become

    (collect$+ (quote
                (lambda (loop$-gvars loop$-ivars)
                  (cons (car loop$-gvars)
                        (cons (car (cdr loop$-gvars))
                              (cons (car loop$-ivars) 'nil)))))
               (list a a)
               target)

  [47mRelink-fancy-scion[0m will rewrite that term to

    (collect$+ (quote
                (lambda (loop$-gvars loop$-ivars)
                  (cons (car loop$-gvars)
                        (cons (car loop$-gvars)
                              (cons (car loop$-ivars) 'nil)))))
               (list a)
               target)

  which eliminates the duplicate entry in the list of globals and, as a
  necessary side effect, also replaces the body of the lambda object
  to eliminate the term [47m(car (cdr loop$-gvars))[0m.

  The application of the metafunction [47mrelink-fancy-scion[0m can easily but
  mistakenly be attributed to the rewriting of [47mlambda[0m objects but it
  is not!  The metafunction is applied to the whole [47mcollect$+[0m term
  (and calls of every other fancy scion), not just the [47mlambda[0m object.

  If you want to avoid this normalization of the globals, disable the
  [rune] [47m(:meta relink-fancy-scion-correct)[0m.")
 (REWRITE-LAMBDA-OBJECT-ACTIONS
  (REWRITE)
  "actions available when rewriting lambda objects

  As explained in [rewrite-lambda-object] the rewriter can be applied
  to eligible occurrences of quoted [47mlambda[0m objects.  That
  documentation also describes eligibility, what happens during, and
  what happens after the specified action, with a focus on
  recursively rewriting the [47mlambda[0m body.  This topic discusses how to
  specify the desired action.

  The user can specify one of three actions by manipulating the enabled
  status of the [rune] [47m(:executable-counterpart rewrite-lambda-modep)[0m
  and the enabled status of [47m(:definition rewrite-lambda-modep)[0m.
  Recall that such runes can be abbreviated [47m(:e rewrite-lambda-modep)[0m
  and [47m(:d rewrite-lambda-modep)[0m.  But in this discussion, we'll
  abbreviate them still further by [3me[0m and [3md[0m, respectively.

  The actions available on the body of an eligible [47mlambda[0m object
  occurrence are

    * rewrite: [3me[0m and [3md[0m enabled

    * syntactically clean: [3me[0m enabled and [3md[0m disabled

    * hands-off (no action): [3me[0m disabled

  Since the action is determined by the enabled status of runes, it can
  be specified by the user by appropriate global [47m[in-theory][0m events
  or by goal-specific, local [47m:in-theory[0m [47m:[0m[47m[hints][0m.  There are three
  0-ary macros that expand into appropriate theories [3mprovided[0m the
  only runes you wish to affect are our so-called [3me[0m and [3md[0m.

  The three macros are [47m[rewrite-lambda-objects-theory][0m,
  [47m[syntactically-clean-lambda-objects-theory][0m, and
  [47m[hands-off-lambda-objects-theory][0m, with the obvious meanings.  For
  example, [47m(syntactically-clean-lambda-objects-theory)[0m macroexpands
  to

    (e/d ((:executable-counterpart rewrite-lambda-modep))   ; enable ``e''
         ((:definition rewrite-lambda-modep)))              ; disable ``d''

  Since [3me[0m and [3md[0m are both initially enabled in ACL2, eligible [47mlambda[0m
  objects are rewritten by default unless you change the status of [3me[0m
  and/or [3md[0m.

  For example, to make the prover just syntactically clean eligible
  [47mlambda[0m objects in [47mSubgoal 3[0m of some proof attempt you could provide
  the [47m:hint[0m

      (\"Subgoal 3\"
        :in-theory (syntactically-clean-lambda-objects-theory))

  Note however that if you also need to adjust the status of some other
  rune in that same hint you must create a theory expression that
  includes the appropriate use of [3me[0m and [3md[0m.  For example, to also
  enable [47mLEMMA1[0m but disable [47mLEMMA2[0m while specifying use of syntactic
  cleaning you could write:

    (\"Subgoal 3\"
     :in-theory (e/d ((:executable-counterpart rewrite-lambda-modep)
                      LEMMA1)
                     ((:definition rewrite-lambda-modep)
                      LEMMA2)))

  For details on what syntactic cleaning is and why it is sometimes
  useful, see [rewriting-versus-cleaning-up-lambda-objects].")
 (REWRITE-LAMBDA-OBJECTS-THEORY
  (THEORIES THEORY-FUNCTIONS REWRITE)
  "how to specify rewriting of lambda objects

  The enabled status of two [47mrewrite-lambda-modep[0m runes are used as
  flags to determine the action taken when eligible [47mlambda[0m objects
  are encountered by the ACL2 rewriter.  See [rewrite-lambda-object]
  and [47m[rewrite-lambda-object-actions][0m.  To make the rewriter dive
  into the body of an eligible [47mlambda[0m object, both
  [47m(:executable-counterpart rewrite-lambda-modep)[0m and [47m(:definition
  rewrite-lambda-modep)[0m must be enabled in the then-current theory.
  The 0-ary function [47mrewrite-lambda-objects-theory[0m returns such a
  theory.

  In fact, diving into eligible quoted [47mlambda[0m object constants to
  rewrite the body is the default action when ACL2 starts up.  See
  [rewriting-versus-cleaning-up-lambda-objects] for why you might
  want to change the default action when eligible [47mlambda[0m objects are
  encountered by the rewriter.

  The expression [47m(rewrite-lambda-objects-theory)[0m macroexpands to the
  theory expression

    (e/d ((:executable-counterpart rewrite-lambda-modep)
          (:definition rewrite-lambda-modep))
         nil)

  which is a theory equal to the current theory except that the
  executable-counterpart rune and the definition rune of
  [47mrewrite-lambda-modep[0m are enabled.  This expansion is suitable for
  use in an [47m[in-theory][0m event or [47m:in-theory[0m hint (see [47m:[0m[47m[hints][0m).

  Both these two runes are initially enabled, so eligible [47mlambda[0m object
  bodies are rewritten by default until and unless some event (e.g.,
  an [47m[in-theory][0m or [47m[include-book][0m) or a superior local subgoal hint
  changes the status of those runes.

  For example, if [47mlambda[0m object rewriting has been disabled globally
  and you wish to enable it for [47mSubgoal 3[0m of some proof, you could
  use the [47m:[0m[47m[hints][0m

    (\"Subgoal 3\"
     :in-theory (rewrite-lambda-objects-theory))

  Note that if you also wish to enable or disable other runes in the
  same subgoal you must construct an appropriate theory.

  For example, if in [47mSubgoal 3[0m of some proof you wanted to enable
  [47mLEMMA1[0m and disable [47mLEMMA2[0m in a theory that will also allow
  rewriting of [47mlambda[0m objects, you might write

    (\"Subgoal 3\"
     :in-theory (set-difference-theories
                   (union-theories (rewrite-lambda-objects-theory)
                                   '(LEMMA1))
                   '(LEMMA2)))

  Some users might prefer

    (\"Subgoal 3\"
     :in-theory (e/d ((:executable-counterpart rewrite-lambda-modep)
                      (:definition rewrite-lambda-modep)
                      LEMMA1)
                     (LEMMA2)))

  See [theories] for general information about theories and how to
  create and use them.")
 (REWRITE-QUOTED-CONSTANT
  (RULE-CLASSES)
  "Make a rule to rewrite a quoted constant

  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.

  Note: It is helpful to know some basic facts about the ACL2 rewriter;
  see [random-remarks-on-rewriting].

    Example Forms:
    (defthm lambda-id
      (fn-equal '(lambda (x) x) 'identity)
      :rule-classes :rewrite-quoted-constant)

    (defthm set-normalizer
      (set-equalp (drop-duplicates-and-sort x) x)
      :rule-classes :rewrite-quoted-constant)

    (defthm lambda-id-generalized
      (implies (symbolp v)
               (fn-equal (list 'lambda (list v) v)
                         'identity))
      :rule-classes :rewrite-quoted-constant)

  To be accepted with rule-class [47m:rewrite-quoted-constant[0m a conjecture
  must have one of the following three

    General Forms:

    (IMPLIES hyps (equiv 'const1 'const2))        ; [1]

    (IMPLIES hyps (equiv (fn var) var))           ; [2]

    (IMPLIES hyps (equiv (constructor ...) rhs))  ; [3]

  where

    * [47mhyps[0m is a term (typically a conjunction) and may include [47m[force][0m and
      [47m[syntaxp][0m hypotheses with the usual semantics,

    * [47mequiv[0m is a known [equivalence] relation and, in the case of [47m[1][0m and
      [47m[2][0m, [47mequiv[0m is not [47mEQUAL[0m,

    * [47mvar[0m, in form [47m[2][0m, is a variable symbol, and

    * [47mconstructor[0m, in form [47m[3][0m, is an explicit value ``constructor''
      function symbol listed in [47m*one-way-unify1-implicit-fns*[0m.  The
      list just mentioned includes [47mcons[0m, which can be used to match
      non-empty list constants, [47mcoerce[0m, which can match string
      constants, [47mintern-in-package-of-symbol[0m, which can match symbol
      constants, and [47mbinary-+[0m and certain other arithmetic primitives
      which can match numeric constants.  See
      [random-remarks-on-rewriting] for some examples.

  If a rule meets the criteria for both a form [47m[2][0m rule and a form [47m[3][0m
  rule, then it is considered to be a form [47m[2][0m rule.

  The function, [47mfn[0m, in a form [47m[2][0m rule is called the ``normalizer.'' We
  explain this terminology as we discuss how such rules are used.

  The [47m:rewrite-quoted-constant[0m rule-class is permitted to specify a
  [47m:corollary[0m and/or a [47m:loop-stopper[0m, with the usual syntax and
  meaning.  See [47m:[0m[47m[rule-classes][0m.  Note that for forms [47m[1][0m and [47m[2][0m
  above a [47m:[0m[47mloop-stopper[0m is probably irrelevant as the forms do not
  usually contain multiple variable symbols.

  Once a [47m:rewrite-quoted-constant[0m rule is proved and stored, the
  rewriter behaves as follows.  When a quoted constant is encountered
  as the target term to be rewritten, the rewriter considers each
  enabled [47m:rewrite-quoted-constant[0m rule (most-recent first), looking
  for those whose [47mequiv[0m refines (see [47m:[0m[47m[refinement][0m) the equivalence
  relation being maintained by the rewriter for the given occurrence
  of the target.  The rewriter tries to apply each such rule in turn
  (as described below) and replaces the target by the rewritten
  result of the first applicable rule.

  A rule applies if the ``pattern'' (see below) in the conclusion
  ``matches'' the quoted constant and the [47mhyps[0m can be relieved in the
  usual sense, including the treatment of free variables, pragmatic
  directives like [47m[force][0m and [47m[syntaxp][0m, and heuristics such as those
  controlled by any [47m:[0m[47m[loop-stopper][0m options in the rule-class or
  [47m:[0m[47mrestrict[0m [hints].  If these conditions are met, the quoted
  constant is replaced by the ``result.'' But the exact meanings of
  ``pattern,'' ``match'' and ``result'', here, are a little different
  from their meanings for ordinary [47m:rewrite[0m rules and depend on which
  of the three forms is being applied.

    * A form [47m[1][0m rule, whose conclusion is [47m(equiv 'const1 'const2)[0m, has
      [47m'const1[0m as its pattern and that pattern matches the target
      constant [47m'const[0m only when [47mconst1[0m is exactly [47mconst[0m.  The result
      is [47m'const2[0m.  Note that it is impossible to prove a form [47m[1][0m
      rule whose equivalence is [47mequal[0m unless the two constants are
      identical, so we disallow that case.

    * A form [47m[2][0m rule, whose conclusion is [47m(equiv (fn var) var)[0m, is most
      easily understood by swapping the roles of left- and right-hand
      sides of its conclusion.  Its pattern is the right-hand side,
      [47mvar[0m, and its result is derived from the left-hand side, [47m(fn
      var)[0m.  The reason we use the form shown here is so that the
      same conjecture might also be used as an ordinary [47m:rewrite[0m rule
      without forcing the user to type a [47m:corollary[0m with the sides
      swapped.  Since form [47m[2][0m rules have a variable as the pattern
      they will match any quoted constant, [47m'const[0m, by binding [47mvar[0m to
      [47m'const[0m.  The result is the quoted constant, if any, obtained by
      rewriting [47m(fn var)[0m under that binding of [47mvar[0m.  If that rewrite
      does not result in a constant, no replacement is made, i.e., it
      is as though the rule did not match.  Note that it is pointless
      to prove a form [47m[2][0m rule whose equivalence is [47mequal[0m because it
      would replace a quoted constant by itself, so we disallow that
      equivalence.
      Intuitively, [47mfn[0m is a function that normalizes every member of the
      [47mequiv[0m equivalence class: given a constant that is a member of
      the class it returns its ``normal'' form.  That is why we call
      [47mfn[0m the ``normalizer'' for [47mequiv[0m.  However, you do not have to
      prove anything like normality or canonicality; you just have to
      prove that [47mfn[0m returns a member of the class.  Having several
      different normalizers is possible but it is best if only one is
      enabled at a time.
      When [47mvar[0m is bound to a constant, the rewriter will first try to
      reduce [47m(fn var)[0m to a constant by simple evaluation.  If that
      fails, it tries using lemmas.  If the normalizer or one of its
      subfunctions is disabled or is non-executable or has a disabled
      executable counterpart the attempt to simply evaluate [47m(fn var)[0m
      (under the assignment of [47m'const[0m to [47mvar[0m) may fail.  That is why
      full-blown rewriting of [47m(fn var)[0m is tried instead.  It might
      happen that evaluation fails but lemmas produce a constant.
      [31;1mThe fact that form [47m[2][0m[31;1m rules are used ``backwards,'' with the roles
      of the left- and right-hand sides swapped, has some
      ramifications worth noting.[0m First, you can also classify the
      same formula as a [47m:rewrite[0m rule (but of course as such it won't
      rewrite quoted constants); as a [47m:rewrite[0m rule it rewrites
      instances of [47m(fn var)[0m to the corresponding instance of [47mvar[0m.
      Second, when a [47m:rewrite-quoted-constant[0m rule is added, the new
      rule is compared to old rules for subsumption and warning
      messages are generated; however form [47m[2][0m rules are omitted from
      this subsumption check because their patterns match every
      constant (in the equivalence class).  Third, if you inspect a
      form [47m[2][0m rule with [47m[pr][0m, it reports the actual syntax typed,
      e.g., the ``[47mLhs[0m'' is [47m(fn var)[0m and the ``[47mRhs[0m'' is [47mvar[0m.  But, if
      you [47m:[0m[47m[monitor][0m a form [47m[2][0m rule and then interact with the
      resulting [break-rewrite] you will see that the [47m[brr-commands][0m
      [47m:lhs[0m and [47m:rhs[0m report the swapped results.  That is, in the
      break, [47m:lhs[0m will be [47mvar[0m and [47m:rhs[0m will be [47m(fn var)[0m.  This is
      different from the display by [47mpr[0m because [47mpr[0m reports the actual
      syntax but interactive breaks report how the rule is being
      used.  We think the interactive user, out of long habit, will
      type [47m:lhs[0m to see the pattern being matched and we did not think
      it wise to add a special command just to see the pattern in a
      form [47m[2][0m rule.  Fourth, if a form [47m[2][0m rule is mentioned in the
      report by [47m[pl][0m the ``New term'' is reported to be [47m(fn 'const)[0m,
      however replacement of [47m'const[0m occurs only if [47m(fn 'const)[0m
      reduces to a quoted constant by rewriting.

    * A form [47m[3][0m rule, whose conclusion is [47m(equiv (constructor ...)  rhs)[0m,
      matches the constant [47m'const[0m provided [47m'const[0m is an instance of
      [47m(constructor ...)[0m under some variable substitution [47ms[0m.  We
      illustrate cases where quoted constants are instances of
      ``constructor'' terms below and in
      [random-remarks-on-rewriting].  Note that form [47m[3][0m rules allow
      the equivalence relation to be [47mequal[0m.  Use of [47mequal[0m here could
      cause looping rewrites if the [47mrhs[0m reduces to a constant.  But
      we allow it because, as noted below, such a rule will also
      permit you to rewrite a quoted constant into an equivalent term
      that is not a quoted constant.

  It is important to realize that form [47m[1][0m and form [47m[3][0m rules only
  apply to the top-level of a quoted constant.  We discuss this at
  length because it can cause some confusion.  The examples below are
  drawn from the community book
  [47mbooks/demos/rewrite-quoted-constant-examples[0m.  That book introduces
  [47mset-equalp[0m as an equivalence relation and proves various
  [47m:rewrite-quoted-constant[0m rules to rearrange the quoted constants
  occurring in [47mset-equalp[0m contexts.  Assume all the quoted constants
  mentioned below occur in [47mset-equalp[0m contexts.

  The form [47m[1][0m rule [47m(set-equalp 77 nil)[0m will not cause [47m'(1 2 3 . 77)[0m to
  rewrite to [47m'(1 2 3)[0m.  Because ACL2 applications frequently involve
  huge quoted list constants, we believe that making the rewriter
  explore them down to the tips would be prohibitively expensive.

  However, form [47m[2][0m rules, of the general form [47m(implies hyps (equiv (fn
  var) var))[0m, allow the normalizer to be applied to every quoted
  constant occurring in a suitable [47mequiv[0m context.  The normalizer can
  then do a root-and-branch exploration of the constant to compute
  its replacement.

  For example, the [47mrewrite-quoted-constants-examples[0m book cited above
  defines the normalizer [47m(drop-dups-and-sort var)[0m to coerce its
  argument to a [47m[true-listp][0m, eliminate duplicate elements, and sort
  the remaining elements.  It then proves the form [47m[2][0m rule
  [47m(set-equalp (drop-dups-and-sort var) var)[0m.  Now consider how this
  rule is used when the rewriter encounters [47m'(3 1 1 2 . 77)[0m in a
  [47mset-equalp[0m context.  First, [47mvar[0m is bound to [47m'const[0m.  Then, the
  rewriter tries to relieve the instantiated hypotheses of the rule,
  if any.  The example rule here has no hypotheses.  But you can
  provide some and perhaps use them to prevent calling the normalizer
  on this particular constant.  Since [47mvar[0m is bound to the constant
  [47m'const[0m such hypotheses can usually just be computed.  Supposing the
  hypotheses are relieved, the rewriter then rewrites
  [47m(drop-dups-and-sort 'const)[0m.  Under the most common circumstance,
  this just causes your normalizer function, here [47mdrop-dups-and-sort[0m,
  to execute on the given constant.  (If you have verified the guard
  of the normalizer and [47m'const[0m satisfies the guard, then the
  execution is in the underlying raw Common Lisp.)  In the most
  common circumstance, the function will return an explicit constant.
  If that returned value is indeed a constant (and different from
  [47m'const[0m), the rewriter replaces this occurrence of [47m'const[0m by the
  returned value.  Otherwise the rule does not apply.

  As noted earlier, form [47m[3][0m rules are only applied at the top-level of
  a quoted constant.  For example, the rule [47m(set-equalp (cons x y)
  (my-cons x y))[0m will not cause [47m'(1 2 3)[0m to rewrite to [47m(my-cons 1
  (my-cons 2 (my-cons 3 nil)))[0m in [47mset-equalp[0m contexts.  Instead, it
  would produce [47m(my-cons 1 '(2 3))[0m.

  But since the rewriter will eventually be called on that term, and
  since that term contains another top-level quoted constant, namely
  [47m'(2 3)[0m, you might expect the rule to eventually be used to replace
  [47m'(2 3)[0m by [47m(my-cons 2 '(3))[0m.  Indeed, that is what happens -- if you
  have proved that [47mset-equalp[0m is a [congruence] for the second
  argument of [47mmy-cons[0m, maintaining [47mset-equalp[0m.  However, for
  technical reasons explained in comments in the book
  [47mrewrite-quoted-constant-examples[0m, each rewrite occurs in a separate
  simplification step.  So turning [47m'(1 2 3)[0m into [47m(my-cons 1 (my-cons
  2 (my-cons 3 nil)))[0m requires three simplification steps.  If the
  rule in question were [47m(set-equalp (cons x y) (cons x
  (double-rewrite y)))[0m it would happen in one simplification step.
  See [47mdouble-rewrite[0m and the examples in the book
  [47mrewrite-quoted-constant-examples[0m.


Subtopics

  [Random-remarks-on-rewriting]
      Some basic facts about the ACL2 rewriter")
 (REWRITE-STACK-LIMIT
  (REWRITE)
  "Limiting the stack depth of the ACL2 rewriter

  ACL2 users can create rules of class [47m:[0m[47m[rewrite][0m (see [rule-classes])
  that have the potential of causing an infinite loop in the ACL2
  rewriter.  This could lead to Lisp stack overflows and even
  segmentation faults.  For this reason, the depth of certain calls
  of functions in the ACL2 rewriter is limited by default using the
  value of the form [47m(rewrite-stack-limit (w state))[0m.  To see the
  limit in action, execute the following forms.

    (defthm app-assoc-1
      (equal (append (append x y) z)
             (append x y z)))
    (defthm app-assoc-2
      (equal (append x y z)
             (append (append x y) z)))
    (thm (equal (append a b c) xxx)
         ; try without these hints to see a slightly different error message
         :hints ((\"Goal\" :do-not '(preprocess))))

  The ensuing error message shows a stack of one greater than the value
  of [47m(rewrite-stack-limit (w state))[0m, which by default is the value
  of the constant [47m*default-rewrite-stack-limit*[0m.  The error message
  also explains how to use [47m:[0m[47m[brr][0m[47m t[0m and [47m([0m[47m[cw-gstack][0m[47m)[0m to find looping
  rewrite rules.

  This limit can be changed; see [set-rewrite-stack-limit].

  For a related limit, see [backchain-limit].


Subtopics

  [Set-rewrite-stack-limit]
      Sets the rewrite stack depth used by the rewriter")
 (REWRITE_RULES_ARE_GENERATED_FROM_DEFTHM_EVENTS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Rewrite Rules are Generated from DEFTHM Events

  {IMAGE} (see [You_Must_Think_about_the_Use_of_a_Formula_as_a_Rule])

  By reading the documentation of [47m[defthm][0m {ICON} (see
  [A_Tiny_Warning_Sign]) (and especially of its [47m:[0m[rule-classes]
  {ICON} (see [A_Tiny_Warning_Sign]) argument) you would learn that
  when we submitted the command

    [31;1m(defthm associativity-of-app[0m
      [31;1m(equal (app (app a b) c)[0m
             [31;1m(app a (app b c))))[0m

  we not only command the system to prove that [47mapp[0m is an associative
  function but

    * [31;1mwe commanded it to use that fact as a rewrite rule[0m.

  That means that every time the system encounters a term of the form

    (app (app [31;1mx[0m [31;1my[0m) [31;1mz[0m)

  it will replace it with

    (app [31;1mx[0m (app [31;1my[0m [31;1mz[0m))!

  {IMAGE} (see [You_Must_Think_about_the_Use_of_a_Formula_as_a_Rule])")
 (REWRITING-CALLS-OF-APPLY$-EV$-AND-LOOP$-SCIONS
  (APPLY$)
  "How the rewriter handles [47mapply$[0m, [47mev$[0m, and [47mloop$[0m terms

  This section focuses on how ACL2 rewrites calls of [47mapply$[0m, [47mev$[0m, and
  [47mloop$[0m scions.  Our purpose is to explain the various ways the user
  can control that rewriting.  We do so by taking you through a
  particularly simple example, starting with a [47mloop$[0m expression.

  We assume that the standard [47mapply$[0m book has been included,

    (include-book \"projects/apply/top\" :dir :system).

  and we suppose the function [47msq[0m, of one argument, has been defined and
  warranted (see [47m[defwarrant][0m.

  Recall that each [47m[loop$][0m statement is translated into a call of some
  [47mloop$[0m [scion] involving [47mlambda[0m objects formed from the iterated
  expressions in the [47mloop$[0m statement.  Thus, for example,

    (loop$ for x in (cons a (cdr (cons x b))) collect (* (sq x) 3))

  is essentially translated into

    (COLLECT$ '(LAMBDA (LOOP$-IVAR)
                       (BINARY-* (SQ LOOP$-IVAR) '3))
               (CONS A (CDR (CONS X B)))).

  Recall that you can view the cleaned up translation with [47m:[0m[47m[tc][0m, and
  the discussion at [47m[tc][0m explains what we mean by ``cleaned up''
  here.

  So [47mloop$[0m statements just introduce [47mlambda[0m objects and scions into any
  conjecture using [47mloop$[0m.  These are rewritten like any other term in
  ACL2: the arguments are rewritten recursively and then enabled
  [47m:[0m[47m[rewrite][0m rules (including the definition of the scion) are tried.
  Recall that ACL2 can rewrite [47mlambda[0m constants. (See
  [rewrite-lambda-object] for when that can occur and how to control
  it.)

  So now consider what happens when the rewriter encounters the
  translation of the [47mloop$[0m above.

    (collect$ '(lambda (x) (binary-* (sq x) '3))  ; note where 3 occurs
              (cons a (cdr (cons x b)))

  it will rewrite the [47mlambda[0m object and the [47mcons[0m term, effectively
  turning the [47mcollect$[0m term into

    (collect$ '(lambda (x) (binary-* '3 (sq x)))  ; note where 3 occurs now
              (cons a b))

  Then, if other rewrite rules about [47mcollect$[0m don't rewrite that, the
  the definition of [47mcollect$[0m will be tentatively tried.  By that we
  mean the body of the definition of [47mcollect$[0m is rewritten (in an
  environment binding locals to actuals) and then the rewriter
  decides heuristically whether to use the original call (with its
  rewritten arguments) or the rewritten body.  We do not discuss
  those heuristics here because they're the same for [47mloop$[0m scions as
  for all other recursive functions in ACL2.

  The logical definition of [47mcollect$[0m is

    (defun collect$ (fn lst)
      (if (endp lst)
          nil
          (cons (apply$ fn (list (car lst)))
                (collect$ fn (cdr lst))))).

  And in this case, the body will be tentatively rewritten in the
  environment where the locals [47mfn[0m and [47mlst[0m are bound as follows.

    fn:  '(lambda (x) (binary-* '3 (sq x)))
    lst: (cons a b).

  As the rewriter descends through the body of [47mcollect$[0m it eventually
  encounters the [47mapply$[0m term.  After rewriting its arguments, the
  [47mapply$[0m term effectively becomes

    (apply$ '(lambda (x) (binary-* 3 '(sq x)))
            (cons a 'nil))

  and then rules about [47mapply$[0m are tried.

  Unless you disable it, the rule [47mbeta-reduction[0m, from the standard
  [47mapply$[0m book above, will fire, transforming the above [47mapply$[0m term to

    (ev$ '(binary-* '3 (sq x))
         (cons (cons 'x a) 'nil)).

  ([47mBeta-reduction[0m is enabled by default.  If you disable it, the [47mapply$[0m
  term will not change unless you enable [47m(:definition apply$)[0m, which
  is disabled by default.)

  But we recommend leaving [47mbeta-reduction[0m enabled and thus converting
  every [47mapply$[0m of a [47mlambda[0m object into an [47mev$[0m term.  There is a
  special feature of the rewriter for simplifying certain [47mev$[0m terms.
  It is based on the fact that that (roughly speaking) the [47mev$[0m of a
  quoted tame term under an alist is the unquoted term with the alist
  applied as a substitution.  That is, the [47mev$[0m term above is equal to
  [47m(binary-* '3 (sq a))[0m.

  More precisely, if a [3mx[0m is a [tame] term and every non-primitive
  function symbol in [3mx[0m has been warranted (see [47m[defwarrant][0m) and [3ma[0m is
  a [47mcons[0m nest term representing a substitution [3msigma[0m pairing the
  variable symbols occurring freely in [3mx[0m with terms, then [47m(ev$ '[0m[3mx  a[0m[47m)[0m
  is equal to [3mx[0m/[3msigma[0m, provided the warrants of all the non-primitive
  function symbols in [3mx[0m are assumed.

  This is implemented in the rewriter so that when an [47m(ev$ 'x a)[0m is
  encountered and the following conditions hold

    * the standard [47mapply$[0m book has been included,

    * the rune [47m(:rewrite ev$-opener)[0m is enabled

    * [47mx[0m is a tame term

    * all non-primitive function symbols in [47mx[0m have been warranted (whether
      the warrants are assumed or not), and

    * [47ma[0m is a [47mcons[0m term representing an alist on variables,

  then the following three actions are taken,

    * The [47mcons[0m term [47ma[0m is converted to a substitution, [47msigma[0m, and that
      substitution is extended to a substitution, [47msigma'[0m, by pairing
      with [47mnil[0m each variable of [47mx[0m that is unbound in [47msigma[0m.  It
      should be observed that an unbound variable is assigned the
      value [47mnil[0m by the definitions of [47mev$[0m (actually, of [47massoc[0m).

    * The warrant for each non-primitive function in [47mx[0m is [force]d if
      possible unless the warrant is already assumed in the current
      context.

    * The [47m(ev$ x a)[0m term is rewritten to the result of recursively
      rewriting [47mx[0m under the substitution [47msigma'[0m.

  Note that this eliminates [47mev$[0m.

  If you see an [47mev$[0m of a quoted term in a checkpoint produced by the
  prover, you will know that one of the conditions above is not
  satisfied or that a necessary warrant could not be forced because
  forcing was disallowed or the warrant was assumed false in the
  context.

  If you would rather [47mev$[0m did not just disappear like this, disable
  [47m(:rewrite ev$-opener)[0m.  This might be desirable if the expansion
  produces a lot of cases and you can prove the theorem without
  exposing them.

  Sometimes you may wish for [47mev$[0m to expand, but to do so step-by-step,
  gradually working its way down through [47mx[0m. Such behavior can be
  achieved by disabling [47mev$-opener[0m but enabling [47m(:definition ev$)[0m,
  which is disabled by default.  However, the tentative application
  of the mutually recursive definitions of [47mev$[0m and [47mapply$[0m can be
  quite slow when dealing with moderately large [47mlambda[0m objects.
  Step-by-step expansion of [47mev$[0m can be accomplished by the
  alternative but generally faster method of disabling [47m(:rewrite
  ev$-opener)[0m, leaving [47m(:definition ev$)[0m disabled, but proving your
  own version of [47mev$-opener[0m under a different name.

    (defthm my-version-of-ev$-opener
      (and (implies (symbolp x)
                    (equal (ev$ x a) (cdr (assoc x a))))
           (equal (ev$ (list 'quote obj) a) obj)
           (implies (suitably-tamep-listp 3 nil args)
                    (equal (ev$ (cons 'if args) a)
                           (if (ev$ (car args) a)
                               (ev$ (cadr args) a)
                               (ev$ (caddr args) a))))
           (implies (and (not (eq fn 'quote))
                         (not (eq fn 'if))
                         (tamep (cons fn args)))
                    (equal (ev$ (cons fn args) a)
                           (apply$ fn (ev$-list args a)))))
      :hints ((\"Goal\" :use ev$-opener))).

  By having the [47mapply$[0m book's [47mev$-opener[0m disabled you shut off the
  special feature described above, and by having your own version of
  [47mev$-opener[0m enabled you push the [47mev$[0m through the quoted term with
  rewrite rules.  This can sometimes help narrow down which of the
  conditions above is unsatisfied, especially if you modify your
  version of the rule so that the [47mtamep[0m and [47msuitably-tamep-listp[0m
  hypotheses are [47m[force][0md.")
 (REWRITING-VERSUS-CLEANING-UP-LAMBDA-OBJECTS
  (REWRITE)
  "why change the default action on rewriting [47mlambda[0m objects

  See [rewrite-lambda-object] and [47m[rewrite-lambda-object-actions][0m for
  background information on how the ACL2 rewriter behaves on certain
  quoted [47mlambda[0m objects.  In this topic we discuss why you might want
  to change that behavior.

  There are three basic actions the rewriter might take when it
  encounters a suitable [47mlambda[0m object.

    * recursively rewrite the body to get a new body,
      by rewriting in the theory described in
      [47m[rewrite-lambda-objects-theory][0m

    * just clean it up syntactically,
      by rewriting in the theory described by
      [47m[syntactically-clean-lambda-objects-theory][0m, or

    * do nothing --- leave [47mlambda[0m object constants untouched.
      by rewriting in the theory described by
      [47m[hands-off-lambda-objects-theory][0m.

  The reason we have several options has to do with the representation
  of [47mlambda[0m objects as quoted constants in ACL2's first order logic.
  Distinct [47mlambda[0m objects are unequal and yet sometimes by rewriting
  their bodies to functionally equivalent terms under [47m[ev$][0m they can
  become identical.

  For example, [47m'(lambda (x) (+ 1 x))[0m and [47m'(lambda (x) (+ x 1))[0m are
  unequal list constants.  But they are functionally equal and by
  rewriting their bodies we can make them identical.

  The problem is greatly magnified by the way [47mlambda$[0m and [47mloop$[0m
  expressions macroexpand into formal terms.  Their expansions are
  complicated with guards and tags that play key roles in their
  Common Lisp compilation and execution efficiency within the ACL2
  top-level read-eval-print loop.  But those guards and tags are
  irrelevant to their logical meanings.  By eliminating the guards
  and tags from quoted [47mlambda[0m objects in slots of [47m[ilk][0m [47m:FN[0m we
  increase the chances that different objects become identical.

  Consider the translation of a [47mthereis[0m [47mloop$[0m statement.  The [47mthereis[0m
  [47mloop$[0m operand looks for an element of the range that satisfies a
  given predicate and returns the first non-[47mnil[0m value of that
  predicate.  The predicate is formally a [47mlambda[0m object.  Below we
  translate a [47mthereis[0m [47mloop$[0m and show the result.

    ACL2 !>:trans (loop$ for x on a
                         thereis
                         (if (equal (car x) b) x nil))

    (RETURN-LAST
     'PROGN
     '(LOOP$ FOR X ON A
             THEREIS
             (IF (EQUAL (CAR X) B) X NIL))
     (THEREIS$+
      '(LAMBDA
        (LOOP$-GVARS LOOP$-IVARS)
        (DECLARE (XARGS :GUARD (IF (TRUE-LISTP LOOP$-GVARS)
                                   (IF (EQUAL (LEN LOOP$-GVARS) '1)
                                       (IF (TRUE-LISTP LOOP$-IVARS)
                                           (EQUAL (LEN LOOP$-IVARS) '1)
                                           'NIL)
                                       'NIL)
                                   'NIL)
                        :SPLIT-TYPES T)
                 (IGNORABLE LOOP$-GVARS LOOP$-IVARS))
        (RETURN-LAST
             'PROGN
             '(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))))
                       (LET ((B (CAR LOOP$-GVARS))
                             (X (CAR LOOP$-IVARS)))
                            (DECLARE (IGNORABLE E X))
                            (IF (EQUAL (CAR X) B) X NIL)))
             ((LAMBDA (B X)
                      (IF (EQUAL (CAR X) B) X 'NIL))
              (CAR LOOP$-GVARS)
              (CAR LOOP$-IVARS))))
      (CONS B 'NIL)
      (LOOP$-AS (CONS (TAILS A) 'NIL))))

    => *

  The predicate being mapped is the quoted [47mlambda[0m object in the first
  argument of the [47mthereis$+[0m.  When shorn of the logically irrelevant
  [47mDECLARE[0m and [47mRETURN-LAST[0m forms this particular quoted [47mlambda[0m object
  becomes

    '(LAMBDA
      (LOOP$-GVARS LOOP$-IVARS)
      ((LAMBDA (B X)
               (IF (EQUAL (CAR X) B) X 'NIL))
       (CAR LOOP$-GVARS)
       (CAR LOOP$-IVARS)))

  But now consider the closely related [47mthereis[0m [47mloop$[0m which is like the
  one translated above but uses different names for the variables.

    (loop$ for y on aaa
           thereis
           (if (equal (car y) bbb) y nil))

  The [47mlambda[0m object representing the predicate in this [47mloop$[0m, when
  shorn of logically irrelevant material, is

    '(LAMBDA
      (LOOP$-GVARS LOOP$-IVARS)
      ((LAMBDA (BBB Y)
               (IF (EQUAL (CAR Y) BBB) Y 'NIL))
       (CAR LOOP$-GVARS)
       (CAR LOOP$-IVARS)))

  But note that this [47mlambda[0m object contains the ``variables'' [47mBBB[0m and [47mY[0m
  where the earlier one contained [47mB[0m and [47mX[0m.  However, they are not
  really variables!  They are symbol constants because they occur in
  quoted list constants.  Thus, the [47mlambda[0m object generated for the
  first [47mthereis[0m [47mloop$[0m is different from the [47mlambda[0m object generated
  from the ``closely related'' one.  They are just two different list
  constants.

  Thus, the translations of those two [47mthereis[0m [47mloop$[0ms are not instances
  of one another.  So if you proved a rewrite rule about the [47m(loop$
  for x on ...B...)[0m and then the rewriter encountered [47m(loop$ for y on
  ...BBB...)[0m the rule would not match.  (By the way, this problem has
  nothing special to do with [47mthereis[0m [47mloop$[0ms.  It happens on every
  kind of [47mloop$[0m because the problem has everything to do with
  representing [47mlambda[0m expressions as list constants.)

  Fortunately, it is sound to replace the body of a [47mlambda[0m object with
  one that is equivalent under [47m[ev$][0m.  That can be done either by
  rewriting the body or by syntactically cleaning the body.  It turns
  out that both rewriting and syntactic cleaning produce the same
  result in this case and reduce these two distinct [47mlambda[0m objects to
  this one.

    '(LAMBDA
      (LOOP$-GVARS LOOP$-IVARS)
      (IF (EQUAL (CAR (CAR LOOP$-IVARS))
                 (CAR LOOP$-GVARS))
          (CAR LOOP$-IVARS)
          'NIL))

  Actually, all that is needed in this case is the beta reduction of
  the two bodies.

  Syntactic cleaning eliminates declarations, guards, and other
  compiler-related tags introduced by translation of [47mlambda$[0m and
  [47mloop$[0m.  It does beta reduction, which eliminates local variable
  names (other than the formals of the [47mlambda[0m object).  And it
  replaces the last argument of calls of [47m[do$][0m by [47mnil[0m if that
  argument is a quoted constant other than [47mnil[0m.  (That argument is
  irrelevant to the value of the [47mdo$[0m term and only used in error
  reporting.)  The logical semantics of [47mloop$[0m is best understood not
  by looking at its translation as we did above but by looking at the
  result of syntactically cleaning its translation.  That is done by
  the command [47m:[0m[47m[tc][0m.  [47mTc[0m translates its argument, in this case the
  [47mloop$[0m statement we've been studying, obtaining the large form shown
  above, and then syntactically cleans it, returning the internal
  representation of the logical semantics.

    ACL2 !>:tc (loop$ for x on a
                      thereis
                      (if (equal (car x) b) x nil))
    (THEREIS$+ '(LAMBDA
                 (LOOP$-GVARS LOOP$-IVARS)
                 (IF (EQUAL (CAR (CAR LOOP$-IVARS))
                            (CAR LOOP$-GVARS))
                     (CAR LOOP$-IVARS)
                     'NIL))
               (CONS B 'NIL)
               (LOOP$-AS (CONS (TAILS A) 'NIL)))

  Note that the free variables of the term are [47mA[0m and [47mB[0m.  The iteration
  variable, [47mx[0m of the [47mloop$[0m does not appear.  Instances of this term
  are formed by choosing instantiations of [47mA[0m and [47mB[0m.

  (Note: The related command [47m:[0m[47m[tcp][0m translates, cleans, and then
  converts the internal form of the term into the ``pretty''
  user-level syntax.  E.g., it converts the quoted [47mLAMBDA[0m constant
  above to a [47mlambda$[0m expression, converts the [47mIF[0m expression to an
  [47mAND[0m, and converts the [47mCONS[0m terms into [47mLIST[0m terms.  But for this
  discussion it is really better to see the internal form.  That
  [47mLAMBDA[0m object above is really a list constant!)

  [31;1mBefore a newly proved [47m:[0m[31;1m[47m[rewrite][0m[31;1m or [47m:[0m[31;1m[47m[linear][0m[31;1m rule is stored, the
  conclusion is syntactically cleaned.[0m

  Like syntactic cleaning, rewriting eliminates declarations, guards,
  and other compiler-related tags and does beta reduction --- but
  these transformations are generally carried out by rules whose
  enabled status can be altered.  Furthermore, rewriting applies
  [47m:rewrite[0m and other rules which might commute terms, open function
  definitions, etc.  We don't rewrite the conclusions of newly proved
  rules simply because the enabled rules may change from one event
  (or subgoal) to another.

  As noted earlier, there are three basic actions the rewriter might
  take when it encounters a suitable [47mlambda[0m object.

    * recursively rewrite the body to get a new body,

    * just clean it up syntactically, or

    * do nothing --- leave [47mlambda[0m object constants untouched.

  Since rules are cleaned before storage, it is almost always the case
  that you will want the prover either to rewrite [47mlambda[0m objects or
  syntactically clean them.  In simple cases, like a rule about the
  first [47mthereis[0m [47mloop$[0m above and a conjecture about the [47msecond[0m, either
  action by the prover reduces ``closely related'' [47mlambda[0m objects to
  identical objects, making it more likely that rules will fire.

  So which of the three actions do you want the rewriter to take when
  it encounters an eligible [47mlambda[0m object?

    * rewrite the body --- best if there are multiple [47mlambda[0m objects in the
      conjecture that need to be written to be identified, and in
      simple cases rewriting is equivalent to syntactic cleaning

    * syntactic cleaning --- best if you want the [47mlambda[0m objects in the
      conjecture to match [47m:rewrite[0m or [47m:linear[0m rules containing
      closely related [47mlambda[0m objects, but you find that otherwise
      necessary [47m:rewrite[0m rules cause the rewriter to ``overshoot''
      the syntactically cleaned term as illustrated further below

    * hands off --- fairly unuseful since rules are cleaned up before
      storage.  However, one use of this is if you prove a lemma
      containing a [47mlambda[0m object but store it with [47m:rule-classes nil[0m
      and then [47m:use[0m an instance of it in the [47m:hints[0m for some
      conjecture that involves the very same [47mlambda[0m objects.

  We now illustrate some typical problems that arise when proving
  theorems about [47mloop$[0ms.  These examples are documented in the book
  [47mbooks/projects/apply/rewriting-versus-cleaning-examples[0m.

  [31;1mWhy you might want to use syntactic cleaning:[0m Suppose you prove the
  [47m:rewrite[0m rule below.  It says that a certain [47mthereis[0m [47mloop$[0m computes
  the same answer as the function [47m[last][0m.

    (defthm loop$-can-be-last
      (implies (listp a)
               (equal (loop$ for x on a
                             thereis
                             (if (atom (cdr x)) x nil))
                      (last a))))

  What term does this rule target?  We can answer that by using the
  [47m:[0m[47m[tc][0m command.

    ACL2 !>:tc (loop$ for x on a
                      thereis
                      (if (atom (cdr x)) x nil))
     (THEREIS$ '(LAMBDA (LOOP$-IVAR)
                        (IF (ATOM (CDR LOOP$-IVAR))
                            LOOP$-IVAR 'NIL))
               (TAILS A))

  By the way, a more common way to see the rules created by an event is
  to use the [47m:[0m[47m[pr][0m command.  But that command displays the terms of
  the rule in user-level syntax and we want to see the internal form
  here.  The ``[47mlambda[0m expression'' is really a quoted constant.

  Now imagine you are proving a conjecture that involves that identical
  (!)  [47mloop$[0m.  Of course, translation will replace the [47mloop$[0m by a
  rather large tagged term containing compiler directives, etc.
  Shorn of that material the term would become the [47mthereis$[0m term
  above, but the translation is what is in the initial [47mGoal[0m.  Imagine
  further that you're doing this proof in a theory that allows the
  rewriter to recursively rewrite the bodies of quoted [47mlambda[0m
  objects, i.e., you are in a theory as described by
  [47m[rewrite-lambda-objects-theory][0m.  ACL2 starts up in such a theory
  and unless you've changed the enabled status of the
  [47mrewrite-lambda-modep[0m runes rewriting [47mlambda[0m objects is the default
  behavior.

  You might expect the [47mloop$-can-be-last[0m rule to fire and replace the
  [47mthereis$[0m term in the [47mGoal[0m by [47m(last a)[0m.  But that will not happen!
  The rule won't fire!

  The reason is that before the rewriter rewrites the [47mthereis$[0m term it
  rewrites its arguments.  The quoted [47mlambda[0m object in the Goal is
  rewritten first.  That is necessary because the translated [47mloop$[0m
  contains tags, etc.  But the rewriter does more than just clean up
  the body.  It ``overshoots'' and opens the nonrecursive function
  [47matom[0m and swaps the branches of the [47mif[0m to eliminate the [47mnot[0m thus
  introduced.  The quoted [47mlambda[0m object becomes

    '(LAMBDA (LOOP$-IVAR)
             (IF (CONSP (CDR LOOP$-IVAR))
                 'NIL
                 LOOP$-IVAR))

  So when the rewriter then tries to rewrite the [47mthereis$[0m terms the
  quoted [47mlambda[0m object in the rule does not match the one in the
  rewritten [47mGoal[0m.

  If the rewritten goal is printed, as it is likely to be a checkpoint,
  you will see the rewritten body with the [47mconsp[0m instead of [47matom[0m in
  it.  As usual, pay attention to the checkpoints.

  One way to respond to this problem would be to ``hobble'' the
  rewriter by shifting over to syntactic cleaning of quoted [47mlambda[0m
  objects.  This could be done by providing a local subgoal hint in
  which you specify

    :in-theory (syntactically-clean-lambda-objects-theory)

  which would prevent the rewriter from diving into the bodies of
  [47mlambda[0m objects and just clean them instead.

  [31;1mWhy you should probably use rewriting:[0m There is a deeper lesson here
  than just that you might want to hobble the rewriter to prevent it
  from diving into quoted [47mlambda[0m bodies.  In our view the actual
  problem is with the [47mloop$-can-be-last[0m rule itself.  ACL2 users are
  taught to express rules in maximally rewritten terms.  No
  experienced user would pose a rule with a non-recursive function
  like [47matom[0m in its lefthand side.  The best response to this
  situation, which may or may not be practical depending on how
  [47mloop$-can-be-last[0m came to be a rule in the session, is to change
  that rule to

    (defthm loop$-can-be-last
      (implies (listp a)
               (equal (loop$ for x on a
                             thereis
                             (if (consp (cdr x)) nil x))
                      (last a))))

  This version of the rule would not only rewrite the [47mthereis[0m [47mloop$[0m
  above but rewrites

    (loop$ for x on a
           thereis
           (if (atom (cdr x)) x nil))

  because, as illustrated above, the rewriter by default dives into the
  translated [47mloop$[0m and ``normalizes'' the resulting [47mthereis$[0m.

  Furthermore, because [47mand[0m macroexpands to an [47mif[0m-term and beta
  reduction eliminates local variable names it would rewrite

    (loop$ for rest on (aaa aa)
           thereis
           (let ((z (cdr rest)))
             (and (atom z) rest))

  [31;1mBut not all such problems can be solved by switching between
  rewriting quoted [47mlambda[0m[31;1m objects and just cleaning them up![0m

  Consider this rewrite rule.  The [47mthereis[0m [47mloop$[0m in the lefthand side
  of the rule below is exactly the [47mloop$[0m whose translation we showed
  at the beginning of this topic.  The cleaned up internal form of
  the lefthand side is the [47mthereis$+[0m term shown by the first [47m:tc[0m
  display in this topic.  The rule below says that the [47mthereis[0m [47mloop$[0m
  in question computes [47mmember[0m.

    (defthm loop$-can-be-member
       (equal (loop$ for x on a
                     thereis
                     (if (equal (car x) b) x nil))
              (member b a)))

  You might expect that when the rewriter encounters (an instance of)
  such a [47mloop$[0m it will replace it by a [47mmember[0m term.  That is actually
  true!

  For example, if we then tried to prove a conjecture mentioning

    (loop$ for x on aaa
           thereis
           (if (equal (car x) bbb) x nil))

  the [47mloop$-can-be-member[0m rule would fire and replace that [47mloop$[0m by
  [47m(member bbb aaa)[0m.

  But it is easy to misjudge whether a given [47mloop$[0m is an instance of
  another.

  Suppose our goal conjecture contained

    (loop$ for x on (aaa aa)
           thereis (if (equal (car x) (bbb bb)) x nil))

  This [47mloop$[0m looks like the [47mloop$[0m in [47mloop$-can-be-member[0m except we've
  used [47m(aaa aa)[0m instead of [47ma[0m, and [47m(bbb bb)[0m instead of [47mb[0m.

  Will that [47mloop$[0m be rewritten to [47m(member (bbb v) (aaa u))[0m?  No!

  To understand why not, we first have to compare the internal forms of
  the two [47mloop$[0ms.  Recall that the lefthand side of rewrite rules are
  cleaned up before storage, so the internal form of the lefthand
  side of [47mloop$-can-be-member[0m is in fact the [47mthereis$+[0m term produced
  by [47m:tc[0m above.  If we are either rewriting [47mlambda[0m objects or just
  syntactically cleaning [47mlambda[0m objects in the proof we're looking
  at, the the internal forms of the [47mloop$[0m in the conjecture will be
  just the [47m:tc[0m of that [47mloop$[0m (because there's nothing interesting to
  rewrite here).  So here is the lefthand side of the rule
  side-by-side with the rewritten target in the conjecture.  We have
  highlighted the differences in uppercase and numbered the lines
  that contain differences.

    lhs of rule                   target
    (thereis$+                    (thereis$+
     '(lambda                      '(lambda
        (loop$-gvars loop$-ivars)     (loop$-gvars loop$-ivars)
        (if (equal                    (if (equal
             (car (car loop$-ivars))       (car (car loop$-ivars))
             (CAR LOOP$-GVARS))            (BBB (CAR LOOP$-GVARS))) ; [1]
            (car loop$-ivars)             (car loop$-ivars)
            'nil))                        'nil))
     (cons B 'nil)                 (cons BB 'nil)                   ; [2]
     (loop$-as                     (loop$-as
      (cons (tails A) 'nil)))       (cons (tails (AAA AA)) 'nil)))  ; [3]

  Note that the target is not an instance of the lefthand side of the
  rule --- but only because of the difference on line [1].  Lines [2]
  and [3] of the lefthand side can be instantiated to become those
  lines in the target.  But because of [1] our [47mloop$-can-be-member[0m
  rule will not rewrite the target shown here.

  This kind of problem cannot be fixed by fiddling with how the prover
  treats [47mlambda[0m objects.  Instead, we need to transform the target
  [47mlambda[0m object into the functionally different [47mlambda[0m object in the
  rule while simultaneously changing how [47mthereis$+[0m applies it.  In
  particular we need to transform [47mtarget[0m to [47mtarget'[0m below by moving
  the [47mBBB[0m out of [1] and into [2] as shown below.

    target                         target'
    (thereis$+                     (thereis$+
     '(lambda                       '(lambda
        (loop$-gvars loop$-ivars)      (loop$-gvars loop$-ivars)
        (if (equal                     (if (equal
             (car (car loop$-ivars))        (car (car loop$-ivars))
             (BBB (CAR LOOP$-GVARS)))       (CAR LOOP$-GVARS))      ; [1]
            (car loop$-ivars)              (car loop$-ivars)
            'nil))                         'nil))
     (cons BB 'nil)                 (cons (BBB BB) 'nil)            ; [2]
     (loop$-as                      (loop$-as
      (cons (tails (aaa aa)) 'nil))) (cons (tails (aaa aa)) 'nil)))

  Note that [47mtarget'[0m is in fact an instance of the lefthand side of the
  rule.  But we've changed the semantics of the [47mlambda[0m object and
  changed the way [47mthereis$+[0m uses it by moving the [47mBBB[0m from the inside
  to the outside of the [47mlambda[0m.  No [47mlambda[0m rewriting can do this.
  Instead, we need a rule that rewrites [47mthereis$+[0m.  (In fact, a great
  project would be to implement a metafunction that does this kind of
  optimization for all [47mloop$[0m scions.  We just haven't done that yet.
  Let us know if you do!)

  Here is a suitable rewrite rule for this particular instance of this
  phenomenon.  We write it as a [47mthereis[0m [47mloop$[0m rule rather than a
  [47mthereis$+[0m, but they're the same.

    (defthm example-of-constant-subterm-abstraction
    (implies (warrant bbb)
             (equal (loop$ for xxx on a
                           thereis
                           (if (equal (car xxx) (bbb bb)) xxx nil))
                    (let ((zzz (bbb bb)))
                      (loop$ for xxx on a
                             thereis
                             (if (equal (car xxx) zzz) xxx nil))))))

  This illustrates another lesson.  Remember that we're imagining a
  proof of some conjecture that involves a [47mthereis[0m [47mloop$[0m mentioning
  [47mBBB[0m and wondering whether our rewrite rule [47mloop$-can-be-member[0m will
  hit it.  Had the [47mthereis[0m [47mloop$[0m in the conjecture been written in
  the style of the [47mlet[0m expression above, where a variable is bound to
  [47m(bbb bb)[0m and then that variable used in the [47mloop$[0m body, we wouldn't
  need to move the [47m(bbb bb)[0m out.  Instead, the [47mlambda[0m generated by
  translating the [47mloop$[0m would contain a variable instead of [47m(bbb bb)[0m.
  The name of the [47mlet[0m-bound variable outside the [47mlambda[0m is irrelevant
  since it won't appear in the cleaned up [47mlambda[0m object where it is
  replaced by a component of the global variables [47mLOOP$-GVARS[0m.  In
  the containing [47mthereis$+[0m the value of that global variable will be
  [47m(bbb bb)[0m, which means the free variable [47mb[0m in our
  [47mloop$-can-be-member[0m rule can be instantiated with [47m(bbb bb)[0m to allow
  the rule to match.

  Put another way, by writing the [47mloop$[0m in the inefficient way
  (requiring [47m(bbb bb)[0m to be recomputed on every iteration) we
  implicitly produce [47mlambda[0m object that is less general than one with
  the [47m(bbb bb)[0m on the outside.

  [31;1mKeep unchanging subterms of [47mloop$[0m[31;1m bodies as variables and compute
  their values outside of the [47mlambda[0m[31;1m.[0m Basically, try to write the
  most general [47mlambda[0m objects you can.

  Finally, these difficulties are exacerbated by the ease with which
  [47mloop$[0m statements can be written and the difference between their
  appearance and the formal terms they denote.  You might be more
  successful at learning to use [47mloop$[0ms in lemmas and theorems if you
  simply [31;1mdon't use [47mloop$[0m[31;1m![0m Instead, learn to write the corresponding
  terms, e.g., try writing a [47mthereis$[0m or a [47mthereis$+[0m term instead of
  a [47mthereis[0m [47mloop$[0m statement in your lemmas and theorems.  Since the
  prover's output contains such terms (rather than [47mloop$[0m statements),
  it will be easier to see where lemmas differ from the targets they
  were intended to hit.  After enough practice you can write [47mloop$[0m
  statements with a better appreciation of what they actually denote.")
 (RFIX
  (NUMBERS ACL2-BUILT-INS)
  "Coerce to a rational number

  [47mRfix[0m simply returns any rational number argument unchanged, returning
  [47m0[0m on a non-rational argument.  Also see [nfix], see [ifix], see
  [realfix], and see [fix] for analogous functions that coerce to a
  natural number, an integer, a real, and a number, respectively.

  [47mRfix[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<rfix>

    (defun rfix (x)
      (declare (xargs :guard t))
      (if (rationalp x) x 0))")
 (RIZE (POINTERS) "See [df].")
 (ROUND
  (NUMBERS ACL2-BUILT-INS)
  "Division returning an integer by rounding off

    Example Forms:
    ACL2 !>(round 14 3)
    5
    ACL2 !>(round -14 3)
    -5
    ACL2 !>(round 14 -3)
    -5
    ACL2 !>(round -14 -3)
    5
    ACL2 !>(round 13 3)
    4
    ACL2 !>(round -13 3)
    -4
    ACL2 !>(round 13 -3)
    -4
    ACL2 !>(round -13 -3)
    4
    ACL2 !>(round -15 -3)
    5
    ACL2 !>(round 15 -2)
    -8

  [47m(Round i j)[0m is the result of taking the quotient of [47mi[0m and [47mj[0m and
  rounding off to the nearest integer.  When the quotient is exactly
  halfway between consecutive integers, it rounds to the even one.

  The [guard] for [47m(round i j)[0m requires that [47mi[0m and [47mj[0m are rational
  ([real], in ACL2(r)) numbers and [47mj[0m is non-zero.

  [47mRound[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.  However, note that unlike Common Lisp, the
  ACL2 [47mround[0m function returns only a single value,

  [31;1mFunction: [0m<round>

    (defun round (i j)
      (declare (xargs :guard (and (real/rationalp i)
                                  (real/rationalp j)
                                  (not (eql j 0)))))
      (let ((q (* i (/ j))))
        (cond ((integerp q) q)
              ((>= q 0)
               (let* ((fl (floor q 1)) (remainder (- q fl)))
                 (cond ((> remainder 1/2) (+ fl 1))
                       ((< remainder 1/2) fl)
                       (t (cond ((integerp (* fl (/ 2))) fl)
                                (t (+ fl 1)))))))
              (t (let* ((cl (ceiling q 1))
                        (remainder (- q cl)))
                   (cond ((< (- 1/2) remainder) cl)
                         ((> (- 1/2) remainder) (+ cl -1))
                         (t (cond ((integerp (* cl (/ 2))) cl)
                                  (t (+ cl -1))))))))))")
 (RULE-CLASSES
  (ACL2)
  "Adding rules to the database

  For an introduction to rule-classes, see [rule-classes-introduction].

    Example Form (from community book finite-set-theory/total-ordering.lisp):
    (defthm <<-trichotomy
      (implies (and (ordinaryp x)
                    (ordinaryp y))
               (or (<< x y)
                   (equal x y)
                   (<< y x)))
      :rule-classes
      ((:rewrite :corollary
                 (implies (and (ordinaryp x)
                               (ordinaryp y)
                               (not (<< x y))
                               (not (equal x y)))
                          (<< y x)))))

    General Form:
    a true list of rule class objects as defined below

    Special Cases:
    a symbol abbreviating a single rule class object

  When [47m[defthm][0m is used to prove a named theorem, rules may be derived
  from the proved formula and stored in the database.  The user
  specifies which kinds of rules are to be built, by providing a list
  of rule class [3mnames[0m or, more generally, rule class [3mobjects[0m, which
  name the kind of rule to build and optionally specify various
  attributes of the desired rule.  The rule class names are
  [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[built-in-clause][0m,
  [47m:[0m[47m[clause-processor][0m, [47m:[0m[47m[compound-recognizer][0m, [47m:[0m[47m[congruence][0m,
  [47m:[0m[47m[definition][0m, [47m:[0m[47m[elim][0m, [47m:[0m[47m[equivalence][0m, [47m:[0m[47m[forward-chaining][0m,
  [47m:[0m[47m[generalize][0m, [47m:[0m[47m[induction][0m, [47m:[0m[47m[linear][0m, [47m:[0m[47m[meta][0m, [47m:[0m[47m[refinement][0m,
  [47m:[0m[47m[tau-system][0m, [47m:[0m[47m[type-prescription][0m, [47m:[0m[47m[type-set-inverter][0m, and
  [47m:well-founded-relation[0m (see [well-founded-relation-rule]).  Some
  classes [3mrequire[0m the user-specification of certain class-specific
  attributes.  Each class of rule affects the theorem prover's
  behavior in a different way, as discussed in the corresponding
  documentation topic.  In this topic we discuss the various
  attributes that may be attached to rule classes.

  Note that not all [events] generate rules.  For example, a [47m[defthm][0m
  event that specifies [47m:rule-classes nil[0m does not generate a rule.
  Similarly, a [47m[defchoose][0m event generates an axiom that can be
  referenced by name in [47m:use[0m [hints], but it does not generate a
  rule.

  A rule class object is either one of the [47m:class[0m keywords or else is a
  list of the form shown below.  Those fields marked with ``(!)'' are
  required when the [47m:class[0m is as indicated.

    (:class
      :COROLLARY term
      :TRIGGER-FNS (fn1 ... fnk)   ; provided :class = :META (!)
      :WELL-FORMEDNESS-GUARANTEE x ; provided :class = :META
                                           or :class = :CLAUSE-PROCESSOR
      :TRIGGER-TERMS (t1 ... tk)   ; provided :class = :FORWARD-CHAINING
                                   ;       or :class = :LINEAR
      :TYPE-SET n                  ; provided :class = :TYPE-SET-INVERTER
      :TYPED-TERM term             ; provided :class = :TYPE-PRESCRIPTION
      :CLIQUE (fn1 ... fnk)        ; provided :class = :DEFINITION
      :CONTROLLER-ALIST alist      ; provided :class = :DEFINITION
      :INSTALL-BODY directive      ; provided :class = :DEFINITION
      :LOOP-STOPPER alist          ; provided :class = :REWRITE
                                           or :class = :REWRITE-QUOTED-CONSTANT
      :PATTERN term                ; provided :class = :INDUCTION (!)
      :CONDITION term              ; provided :class = :INDUCTION
      :SCHEME term                 ; provided :class = :INDUCTION (!)
      :MATCH-FREE all-or-once      ; provided :class = :REWRITE
                                   ;       or :class = :LINEAR
                                   ;       or :class = :FORWARD-CHAINING
      :BACKCHAIN-LIMIT-LST limit   ; provided :class = :REWRITE
                                   ;       or :class = :META
                                   ;       or :class = :LINEAR
                                   ;       or :class = :TYPE-PRESCRIPTION
      :HINTS hints                 ; provided instrs = nil
      :INSTRUCTIONS instrs         ; provided  hints = nil
      :OTF-FLG flg)

  When rule class objects are provided by the user, most of the fields
  are optional and their values are computed in a context sensitive
  way.  When a [47m:class[0m keyword is used as a rule class object, all
  relevant fields are determined contextually.  Each rule class
  object in [47m:rule-classes[0m causes one or more rules to be added to the
  database.  The [47m:class[0m keywords are documented individually under
  the following names.  Note that when one of these names is used as
  a [47m:class[0m, it is expected to be in the keyword package (i.e., the
  names below should be preceded by a colon but the ACL2
  [documentation] facilities do not permit us to use keywords below).

  See also [47m[force][0m, [case-split], [47m[syntaxp][0m, and [47m[bind-free][0m for
  ``pragmas'' one can wrap around individual hypotheses of certain
  classes of rules to affect how the hypothesis is relieved.

  Before we get into the discussion of rule classes, let us return to
  an important point.  In spite of the large variety of rule classes
  available, at present we recommend that new ACL2 users rely almost
  exclusively on (conditional) rewrite rules.  A reasonable but
  slightly bolder approach is to use [47m:[0m[47m[type-prescription][0m and
  [47m:[0m[47m[forward-chaining][0m rules for ``type-theoretic'' rules, especially
  ones whose top-level function symbol is a common one like
  [47m[true-listp][0m or [47m[consp][0m; see [type-prescription] and see
  [forward-chaining].  However, the rest of the rule classes are
  really not intended for widespread use, but rather are mainly for
  experts.

  When in doubt, create a [47m:[0m[47m[rewrite][0m rule, which is the default.  See
  [rule-classes-introduction].

  [47m:Rule-classes[0m is an optional keyword argument of the [47m[defthm][0m (and
  [47m[defaxiom][0m) event.  In the following, let [47mname[0m be the name of the
  event and let [47mthm[0m be the formula to be proved or added as an axiom.

  If [47m:rule-classes[0m is not specified in a [47m[defthm][0m (or [47m[defaxiom][0m)
  event, it is as though what was specified was to make one or more
  [47m:[0m[47m[rewrite][0m rules, i.e., as though [47m:rule-classes[0m [47m((:rewrite))[0m had
  been used.  Use [47m:rule-classes[0m [47mnil[0m to specify that no rules are to
  be generated.

  If [47m:rule-classes[0m class is specified, where class is a non-[47mnil[0m symbol,
  it is as though [47m:rule-classes[0m [47m((class))[0m had been used.  Thus,
  [47m:rule-classes[0m [47m:[0m[47m[forward-chaining][0m is equivalent to [47m:rule-classes[0m
  [47m((:forward-chaining))[0m.

  We therefore now consider [47m:rule-classes[0m as a true list.  If any
  element of that list is a keyword, replace it by the singleton list
  containing that keyword.  Thus, [47m:rule-classes[0m [47m(:rewrite :elim)[0m is
  the same as [47m:rule-classes[0m [47m((:rewrite) (:elim))[0m.

  Each element of the expanded value of [47m:rule-classes[0m must be a true
  list whose [47m[car][0m is one of the rule class keyword tokens listed
  above, e.g., [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[elim][0m, etc., and whose [47m[cdr][0m is a
  ``keyword alist'' alternately listing keywords and values.  The
  keywords in this alist must be taken from those shown below.  They
  may be listed in any order and most may be omitted, as specified
  below.

      [47m:[0m[47m[Corollary][0m --- its value, [47mterm[0m, must be a term.  If omitted, this
      field defaults to [47mthm[0m.  The [47m:[0m[47m[corollary][0m of a rule class object
      is the formula actually used to justify the rule created and
      thus determines the form of the rule.  Nqthm provided no
      similar capability: each rule was determined by [47mthm[0m, the
      theorem or axiom added.  ACL2 permits [47mthm[0m to be stated
      ``elegantly'' and then allows the [47m:[0m[47m[corollary][0m of a rule class
      object to specify how that elegant statement is to be
      interpreted as a rule.  For the rule class object to be
      well-formed, its (defaulted) [47m:[0m[47m[corollary][0m, [47mterm[0m, must follow
      from [47mthm[0m.  Unless [47mterm[0m follows trivially from [47mthm[0m using little
      more than propositional logic, the formula [47m(implies thm term)[0m
      is submitted to the theorem prover and the proof attempt must
      be successful.  During that proof attempt the values of
      [47m:[0m[47m[hints][0m, [47m:[0m[47m[instructions][0m, and [47m:[0m[47m[otf-flg][0m, as provided in the
      rule class object, are provided as arguments to the prover.
      Such auxiliary proofs give the sort of output that one expects
      from the prover.  However, as noted above, corollaries that
      follow trivially are not submitted to the prover; thus, such
      corollaries cause no prover output.  Note that no rule is
      stored for the theorem until all corollaries have been proved.

      Note that before [47mterm[0m is stored, all calls of macros in it are
      expanded away.  See [trans].

      [47m:[0m[47m[Hints][0m, [47m:[0m[47m[instructions][0m, [47m:[0m[47m[otf-flg][0m --- the values of these fields
      must satisfy the same restrictions placed on the fields of the
      same names in [47m[defthm][0m.  These values are passed to the
      recursive call of the prover used to establish that the
      [47m:[0m[47m[corollary][0m of the rule class object follows from the theorem
      or axiom [47mthm[0m.

      [47m:[0m[47m[Type-set][0m --- this field may be supplied only if the [47m:class[0m is
      [47m:[0m[47m[type-set-inverter][0m.  When provided, the value must be a
      type-set, an integer in a certain range.  If not provided, an
      attempt is made to compute it from the corollary.  See
      [type-set-inverter].

      [47m:Typed-term[0m --- this field may be supplied only if the [47m:class[0m is
      [47m:[0m[47m[type-prescription][0m.  When provided, the value is the term for
      which the [47m:[0m[47m[corollary][0m is a type-prescription lemma.  If no
      [47m:typed-term[0m is provided in a [47m:[0m[47m[type-prescription][0m rule class
      object, we try to compute heuristically an acceptable term.
      See [type-prescription].

      [47m:Trigger-terms[0m --- this field may be supplied only if the [47m:class[0m is
      [47m:[0m[47m[forward-chaining][0m or [47m:[0m[47m[linear][0m.  When provided, the value is
      a list of terms, each of which is to trigger the attempted
      application of the rule.  If no [47m:trigger-terms[0m is provided, we
      attempt to compute heuristically an appropriate set of
      triggers.  See [forward-chaining] or see [linear].

      [47m:Trigger-fns[0m --- this field must (and may only) be supplied if the
      [47m:class[0m is [47m:[0m[47m[meta][0m.  Its value must be a list of function
      symbols (except that a macro alias can stand in for a function
      symbol; see [add-macro-alias]).  Terms with these symbols
      trigger the application of the rule.  See [meta].

      [47m:Well-formedness-guarantee[0m --- this field may be supplied only if the
      [47m:class[0m is [47m:[0m[47m[meta][0m or [47m:[0m[47m[clause-processor][0m.  Its value must be of
      one of the following forms:

        [1]  thm-name1                ; :META or :CLAUSE-PROCESSOR rules
        [2]  (thm-name1)              ; :META rules
        [3]  (thm-name1 thm-name2)    ; :META rules

      where [47mthm-name1[0m and [47mthm-name2[0m are the names of previously proved
      theorems establishing that the results of applying the
      metafunction(s) or clause-processor will be syntactically
      well-formed.  See [47m:[0m[meta] and [47m:[0m[clause-processor] for details
      of the required forms of these well-formedness theorems.  Forms
      [1] and [2] may be used for [47m:meta[0m rules where no hypothesis
      metafunction is involved.  Form [3] must be used for [47m:meta[0m
      rules with hypothesis metafunctions; that is, if you provide a
      well-formedness guarantee for a metatheorem with a hypothesis
      metafunction you must guarantee the well-formedness of both the
      metafunction (with [47mthm-name1[0m) and the hypothesis metafunction
      (with [47mthm-name2[0m).  Form [1] must be used for [47m:clause-processor[0m
      rules.  In the absence of a proper [47m:well-formedness-guarantee[0m
      the well-formedness of the output of a both kinds of rules is
      checked every time the rule is fired.  These checks are skipped
      when a proper [47m:well-formedness-guarantee[0m is provided or when
      overridden as described in [47m[set-skip-meta-termp-checks][0m.

      [47m:Clique[0m and [47m:controller-alist[0m --- these two fields may only be
      supplied if the [47m:class[0m is [47m:[0m[47m[definition][0m.  If they are omitted,
      then ACL2 will attempt to guess them.  Suppose the [47m:[0m[47m[corollary][0m
      of the rule is [47m(implies hyp (equiv (fn a1 ... an) body))[0m.  The
      value of the [47m:clique[0m field should be a true list of function
      symbols, and if non-[47mnil[0m must include [47mfn[0m.  These symbols are all
      the members of the mutually recursive clique containing this
      definition of [47mfn[0m.  That is, a call of any function in [47m:clique[0m
      is considered a ``recursive call'' for purposes of the
      expansion heuristics.  The value of the [47m:controller-alist[0m field
      should be an alist that maps each function symbol in the
      [47m:clique[0m to a list of [47mt[0m's and [47mnil[0m's of length equal to the arity
      of the function.  For example, if [47m:clique[0m consists of just two
      symbols, [47mfn1[0m and [47mfn2[0m, of arities [47m2[0m and [47m3[0m respectively, then
      [47m((fn1 t nil) (fn2 nil t t))[0m is a legal value of
      [47m:controller-alist[0m.  The value associated with a function symbol
      in this alist is a ``mask'' specifying which argument slots of
      the function ``control'' the recursion for heuristic purposes.
      Sloppy choice of [47m:clique[0m or [47m:controller-alist[0m can result in
      infinite expansion and stack overflow.

      [47m:Install-body[0m --- this field may only be supplied if the [47m:class[0m is
      [47m:[0m[47m[definition][0m.  Its value must be [47mt[0m, [47mnil[0m, or the default,
      [47m:normalize[0m.  A value of [47mt[0m or [47m:normalize[0m will cause ACL2 to
      install this rule as the new body of the function being
      ``defined'' ([47mfn[0m in the paragraph just above); hence this
      definition will be installed for future [47m:expand[0m [hints].
      Furthermore, if this field is omitted or the value is
      [47m:normalize[0m, then this definition will be simplified with the
      [normalization] procedure that is used by default when
      processing definitions made with [47m[defun][0m.  You must explicitly
      specify [47m:install-body nil[0m in the following cases: the arguments
      are not a list of distinct variables, [47mequiv[0m (as above) is not
      [47m[equal][0m, or there are free variables in the hypotheses or
      right-hand side (see [free-variables]).  However, supplying
      [47m:install-body nil[0m will not affect the rewriter's application of
      the [47m:definition[0m rule, other than to avoid using the rule to
      apply [47m:expand[0m hints.  If a definition rule equates [47m(f a1 ...
      ak)[0m with [47mbody[0m but there are hypotheses, [47mhyps[0m, then [47m:expand[0m
      [hints] will replace terms [47m(f term1 ... termk)[0m by corresponding
      terms [47m(if hyps body (hide (f term1 ... termk)))[0m.

      [47m:[0m[47m[Loop-stopper][0m --- this field may only be supplied if the class is
      [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[rewrite-quoted-constant][0m.  Its value must be a
      list of entries each consisting of two variables followed by a
      (possibly empty) list of function symbols, for example [47m((x y
      binary-+) (u v foo bar))[0m.  It will be used to restrict
      application of rewrite rules by requiring that the list of
      instances of the second variables must be ``smaller'' than the
      list of instances of the first variables in a sense related to
      the corresponding functions listed; see [loop-stopper].  The
      list as a whole is allowed to be [47mnil[0m, indicating that no such
      restriction shall be made.  Note that any such entry that
      contains a variable not being instantiated, i.e., not occurring
      on the left side of the rewrite rule, will be ignored.
      However, for simplicity we merely require that every variable
      mentioned should appear somewhere in the corresponding
      [47m:[0m[47m[corollary][0m formula.

      [47m:Pattern[0m, [47m:Condition[0m, [47m:Scheme[0m --- the first and last of these fields
      must (and may only) be supplied if the class is [47m:[0m[47m[induction][0m.
      [47m:Condition[0m is optional but may only be supplied if the class is
      [47m:[0m[47m[induction][0m.  The values must all be terms and indicate,
      respectively, the pattern to which a new induction scheme is to
      be attached, the condition under which the suggestion is to be
      made, and a term which suggests the new scheme.  See
      [induction].

      [47m:Match-free[0m --- this field must be [47m:all[0m or [47m:once[0m and may be supplied
      only if the [47m:class[0m is either [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, or
      [47m:[0m[47m[forward-chaining][0m.  (This field is not implemented for other
      rule classes, including the [47m:[0m[47m[type-prescription][0m rule class.)
      See [free-variables] for a description of this field.  Note:
      Although this field is intended to be used for controlling
      retries of matching free variables in hypotheses, it is legal
      to supply it even if there are no such free variables.  This
      can simplify the automated generation of rules, but note that
      when [47m:match-free[0m is supplied, the warning otherwise provided
      for the presence of free variables in hypotheses will be
      suppressed.

      [47m:Backchain-limit-lst[0m --- this field may be supplied only if the
      [47m:class[0m is either [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[meta][0m, [47m:[0m[47m[linear][0m, or
      [47m:[0m[47m[type-prescription][0m.  It is further required that either only
      one rule is generated from the formula or, at least, every such
      rule has the same list of hypotheses.  The value for
      [47m:backchain-limit-lst[0m must be [47mnil[0m; a non-negative integer; or,
      except in the case of [47m:[0m[47m[meta][0m rules, a true list each element
      of which is either [47mnil[0m or a non-negative integer.  If it is a
      list, its length must be equal to the number of hypotheses of
      the rule and each item in the list is the ``backchain limit''
      associated with the corresponding hypothesis.  If
      [47mbackchain-limit-lst[0m is a non-negative integer, it is defaulted
      to a list of the appropriate number of repetitions of that
      integer.  The backchain limit of a hypothesis is used to limit
      the effort that ACL2 will expend when relieving the hypothesis.
      If it is [47mNIL[0m, no new limits are imposed; if it is an integer,
      the hypothesis will be limited to backchaining at most that
      many times.  Note that backchaining may be further limited by a
      global [47mbackchain-limit[0m; see [backchain-limit] for details.  For
      different ways to reign in the rewriter, see
      [rewrite-stack-limit] and see [set-prover-step-limit].  Jared
      Davis has pointed out that you can set the [47m:backchain-limit-lst[0m
      to 0 to avoid any attempt to relieve [47m[force][0md hypotheses, which
      can lead to a significant speed-up in some cases.

  Once [47mthm[0m has been proved (in the case of [47m[defthm][0m) and each rule
  class object has been checked for well-formedness (which might
  require additional proofs), we consider each rule class object in
  turn to generate and add rules.  Let [47m:class[0m be the class keyword
  token of the [47mi[0mth class object (counting from left to right).
  Generate the [rune] [47m(:class name . x)[0m, where [47mx[0m is [47mnil[0m if there is
  only one class and otherwise [47mx[0m is [47mi[0m.  Then, from the [47m:[0m[47m[corollary][0m
  of that object, generate one or more rules, each of which has the
  name [47m(:class name . x)[0m.  See the [47m:[0m[47m[doc][0m entry for each rule class
  to see how formulas determine rules.  Note that it is in principle
  possible for several rules to share the same name; it happens
  whenever a [47m:[0m[47m[corollary][0m determines more than one rule.  This in
  fact only occurs for [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[linear][0m, and [47m:[0m[47m[forward-chaining][0m
  class rules and only then if the [47m:[0m[47m[corollary][0m is essentially a
  conjunction.  (See the documentation for [rewrite], [linear], or
  [forward-chaining] for details.)


Subtopics

  [Backchaining]
      Attempting to relieve the hypotheses of a rule

  [Built-in-clause]
      To build a [clause] into the simplifier

  [Clause-processor]
      Make or apply a [47m:clause-processor[0m rule (goal-level simplifier)

  [Compound-recognizer]
      Make a rule used by the typing mechanism

  [Congruence]
      The relations to maintain while simplifying arguments

  [Corollary]
      The corollary formula of a [rune]

  [Default-backchain-limit]
      Specifying the backchain limit for a rule

  [Definition]
      Make a rule that acts like a function definition

  [Elim]
      Make a destructor elimination rule

  [Equivalence]
      Mark a relation as an equivalence relation

  [Executable-counterpart]
      A rule for computing the value of a function

  [Forward-chaining]
      Make a rule to forward chain when a certain trigger arises

  [Free-variables]
      Free variables in rules

  [Generalize]
      Make a rule to restrict generalizations

  [Guard-holders]
      Remove trivial calls from a [term]

  [Induction]
      Make a rule that suggests a certain induction

  [Induction-heuristics]
      How ACL2 selects induction schemes

  [Linear]
      Make some arithmetic inequality rules

  [Meta]
      Make a [47m:meta[0m rule (a hand-written simplifier)

  [Patterned-congruence]
      Removing restrictions on classic [congruence] rules

  [Refinement]
      Record that one equivalence relation refines another

  [Rewrite]
      Make some [47m:rewrite[0m rules (possibly conditional ones)

  [Rewrite-quoted-constant]
      Make a rule to rewrite a quoted constant

  [Rule-classes-introduction]
      Selecting which kind of rule to create

  [Tau-system]
      Make a rule for the ACL2 ``type checker''

  [Type-prescription]
      Make a rule that specifies the type of a term

  [Type-reasoning]
      ACL2 reasoning with ``types''

  [Type-set-inverter]
      Exhibit a new decoding for an ACL2 type-set

  [Well-formedness-guarantee]
      Guarantee that a metafunction or clause-processor returns a
      well-formed answer

  [Well-founded-relation]
      Show that a relation is well-founded on a set

  [Well-founded-relation-rule]
      Show that a relation is well-founded on a set")
 (RULE-CLASSES-INTRODUCTION
  (RULE-CLASSES)
  "Selecting which kind of rule to create

  Successful ACL2 users generally direct many of their proved theorems
  to be stored as rules, which can be applied automatically in
  subsequent proof attempts.  See [rule-classes] for a detailed
  discussion of the kinds of rules that can be created.  Here, we
  give a brief introduction to rule-classes that may suffice for most
  ACL2 users.

  The workhorse for ACL2 proof attempts is generally the application of
  [rewrite] rules.  When you prove a theorem stated with [47m[defthm][0m,
  ACL2 stores it as a rewrite rule unless either the [47m:rule-classes[0m
  keyword is supplied explicitly or an error occurs because the
  theorem is not in a form that ACL2 knows how to store as a rewrite
  rule.  See [rewrite] for an introduction to rewrite rules in ACL2.
  That topic also has links to useful introductory material as well
  as a notion of [congruence], which allows the rewriting of one term
  to another when the two are merely equivalent in some suitable
  sense, but not necessarily equal.

  Most successful ACL2 users make only sparing use of other kinds of
  rules besides rewrite rules.  When in doubt, the default is
  probably best: the absence of any [47m:rule-classes[0m keyword in a
  [47m[defthm][0m event, which is equivalent to [47m:rule-classes :rewrite[0m.
  Below are some suggestions for when other kinds of rules might be
  appropriate.  Of course, you are welcome to scan the
  [community-books] for examples.  One can for example find many
  examples (apparently more than 15,000) of [47m:type-prescription[0m rules
  by standing in the [47mbooks/[0m directory and issuing the following shell
  command (Linux or MacOS):

    time egrep -e ':rule-classes .*type-prescription' --include='*.l*sp' -ri .

  Below, we sometimes speak of the ``conclusion'' of a formula.  For
  many rule classes, this is simply the formula itself unless the
  formula is of the form [47m(implies hyp concl)[0m, in which case it is
  recursively the conclusion of [47mconcl[0m.  See the subtopics of
  [rule-classes] for detailed documentation.

    * If the conclusion is a call of a primitive recognizer or a compound
      recognizer, or the negation of such --- for example,
      [47m(true-listp (f x y))[0m --- consider making a [type-prescription]
      rule.  (For relevant background on recognizers, see
      [compound-recognizer], which also describes how to make a rule
      that designates a function as a compound-recognizer.)  But note
      that hypotheses of such a rule are proved (``relieved'') by
      ACL2 only using type reasoning (see [TYPE-REASONING]).  If you
      want rewriting to be used for relieving the hypotheses, you can
      wrap them in [47m[force][0m or [47m[case-split][0m.

    * If the conclusion is an inequality or negated inequality, consider
      making a [linear] rule, but generally only if you can identify
      a reasonable maximal term, which very roughly is a
      syntactically largest term that binds all the variables.  For
      example, the formula [47m(< (f x y) (g y z))[0m might not make a good
      linear rule.  For a more careful discussion of maximal terms,
      see [linear].

    * If the formula is a term in normal form (not simplifiable by your
      rewrite rules) that tends to be an explicit hypothesis in some
      of your theorems, consider making it a [forward-chaining] rule.
      For example, if you are reasoning about a finite state machine
      (such as an interpreter) and your theorems tend to have the
      hypothesis [47m(good-state-p st)[0m, and your formula is [47m(good-state-p
      (foo st))[0m, then that formula is a good candidate for a
      [forward-chaining] rule.

    * If the rule looks like a recursive definition [47m(equal (f x1 x2 ..)
      (... (f ...) ...))[0m, consider making a [definition] rule.

    * When you want to control the simplifier rather than just turning
      rules (especially rewrite rules) loose on your terms, consider
      using [meta] rules or [clause-processor] rules.

  There are other rule classes that can be useful.  See [rule-classes]
  for a complete list.")
 (RULE-NAMES
  (THEORIES)
  "How rules are named.

    Examples:
    (:rewrite assoc-of-app)
    (:linear delta-aref . 2)
    (:definition length)
    (:executable-counterpart length)

  See [rune].")
 (RULER (POINTERS) "See [rulers].")
 (RULER-EXTENDERS (POINTERS)
                  "See [rulers].")
 (RULERS
  (DEFUN)
  "Control for ACL2's termination and induction analyses

  [31;1mIntroduction[0m

  Consider the following recursive definition, which returns a list of
  threes of length one more than the length of [47mx[0m.

    (defun f (x)
      (cons 3
            (if (consp x)
                (f (cdr x))
              nil)))

  One might expect ACL2's termination analysis to admit this function,
  since we know that [47m(cdr x)[0m is ``smaller'' than [47mx[0m if [47m(consp x)[0m is
  true.  (ACL2's notion of ``smaller'' here is essentially ordinary
  natural-number [47m<[0m, and the argument [47mx[0m is measured by applying
  function [47m[ACL2-count][0m to [47mx[0m; see [defun].)  However, by default that
  termination analysis does not consider [47m[if][0m tests, like [47m(consp x)[0m
  above, when they occur under calls of functions other than [47mIF[0m, such
  as [47mCONS[0m in the case above; it considers only rulers, as we now
  discuss.

  In the example above, we say that the term [47m(consp x)[0m [3mgoverns[0m the
  recursive call [47m(f (cdr x))[0m shown above, but does not [3mrule[0m that
  call.  Roughly speaking, the set of [3mgovernors[0m of a subterm
  occurrence in a given term consists of all superior [47mIF[0m tests and
  their negations that must be true in order for evaluation to reach
  that subterm; however, the set of [3mrulers[0m of the occurrence only
  includes, at least by default, those tests and their negations from
  the top-level [47mIF[0m structure of the term --- that is, tests and their
  negations that are collected by walking through the true and false
  branches of [47mIF[0m calls, starting at the top.  Consider for example
  the following term, where [47mfoo[0m is assumed to be a function symbol.

    (if a
        (if (if b c d) e f)
      (if g
          (foo (if h i j))
        k))

  For the occurrence of [47mc[0m in that term, the only ruler is [47ma[0m; but both [47ma[0m
  and [47mb[0m are governors.  For the occurrence of [47mi[0m, [47m(not a)[0m and [47mg[0m are
  the only rulers; but its governors are [47m(not a)[0m, [47mg[0m, and [47mh[0m.

  We have seen that for a subterm occurrence in a term, every ruler is
  a governor but not necessarily vice-versa.  It is the rulers of a
  recursive call that affect its role in the termination and
  induction analysis for a function.

  One way to overcome the discrepancy between rulers and governors is
  to ``lift'' the [47mIF[0m test to the top level.  We can apply that
  technique to the [47mdefun[0m of [47mf[0m above, so that now [47m(consp x)[0m is a ruler
  of the recursive call, and not merely a governor (though it remains
  a governor as well, of course).

    (defun f (x)
      (if (consp x)
          (cons 3 (f (cdr x)))
        (cons 3 nil)))

  But another way to overcome the problem is to tell ACL2 to extend its
  termination (and induction) analysis through calls of [47mcons[0m, as
  follows, by designating that calls of [47mcons[0m should not block the
  accumulation of rulers.

    (defun f (x)
      (declare (xargs :ruler-extenders (cons)))
      (cons 3
            (if (consp x)
                (f (cdr x))
              nil)))

  Let's look at one more (contrived) example:

    (defun g (x)
      (if (atom x)
          x
        (len (if (symbolp (car x))
                 (g (cddr x))
               (g (cdr x))))))

  There are two recursive calls, and the set of rulers is [47m{(not (atom
  x))}[0m for each of those.  The set of governors for the first
  recursive call is [47m{(not (atom x)), (symbolp (car x))}[0m, and for the
  second, [47m{(not (atom x)), (not (symbolp (car x)))}[0m.  The rulers is
  extended to be the governors in each case if we specify: [47m(declare
  (xargs :ruler-extenders (len)))[0m.

  You may even wish to provide value [47m:all[0m instead of an explicit list
  of ruler-extenders, so that no function call blocks the termination
  analysis:

    (defun f (x)
      (declare (xargs :ruler-extenders :all))
      (cons 3
            (if (consp x)
                (f (cdr x))
              nil)))

  Alternatively, you can omit the [47mXARGS[0m [47m:RULER-EXTENDERS[0m form, instead
  modifying the global default set of ruler-extenders:

    (set-ruler-extenders :all)

    ; or, for example:
    (set-ruler-extenders '(cons return-last))

  You can call the function [47m[default-ruler-extenders][0m as follows to see
  the current global default set of ruler-extenders:

    (default-ruler-extenders (w state))

  We conclude this introduction by considering the handling of [47mLET[0m
  expressions by termination analysis.  Consider the following
  example.

    (defun fact (n)
      (the (integer 1 *)
           (if (posp n)
               (* n (fact (1- n)))
             1)))

  ACL2 treats the call of [47m[the][0m in the body of this definition as
  follows.

    (let ((var (if (posp n)
                   (* n (fact (1- n)))
                 1)))
      (if (and (integerp var) (<= 1 var))
          var
        <some_error>))

  A [47m[let][0m expression, in turn, is treated as a [47m[lambda][0m application:

    ((lambda (var)
       (if (if (integerp var)
               (not (< var 1))
             nil)
           var
         <some_error>))
     (if (posp n)
         (* n (fact (1- n)))
       1))

  Notice that the [47m[posp][0m test, which governs the recursive call of
  [47mfact[0m, is inside an argument of a function application, namely the
  application of the [47mLAMBDA[0m expression.  So by default, ACL2 will not
  consider this [47m[posp][0m test in its termination analysis.  The keyword
  [47m:LAMBDAS[0m in the list of ruler-extenders denotes all calls of lambda
  expressions, much as the inclusion of [47mCONS[0m in the ruler-extenders
  denotes all calls of [47mCONS[0m.  The following definition is thus
  accepted by ACL2.

    (defun fact (n)
      (declare (xargs :ruler-extenders (:lambdas)))
      (the (integer 1 *)
           (if (posp n)
               (* n (fact (1- n)))
             1)))

  As a convenience, ACL2 allows the symbol [47m:lambdas[0m in place of
  [47m(:lambdas)[0m, and in fact the former will also include the three
  basic ruler-extenders: [47m[return-last][0m, which comes from
  macroexpansion of calls of [47m[prog2$][0m, [47m[ec-call][0m, and others;
  [47m[mv-list][0m; and [47m[if][0m, which affects termination analysis through the
  first argument of calls of [47mIF[0m (it continues through the true and
  false branches of these calls even without [47mIF[0m being among the
  ruler-extenders).

  IMPORTANT REMARKS.

   1. Notice that the argument to [47mset-ruler-extenders[0m is evaluated, but the
      argument to [47m:RULER-EXTENDERS[0m in [47mXARGS[0m is not evaluated.

   2. Do not put macro names in your list of ruler-extenders.  For example,
      if you intend that [47m+[0m should not block the termination analysis,
      in analogy to [47mcons[0m in the example above, then the list of
      ruler-extenders should include [47mbinary-+[0m, not [47m+[0m.  Of course, if
      you use [47m:all[0m then this is not an issue, but see the next
      remark.

   3. Also please note that by taking advantage of the ruler-extenders, you
      may change the induction scheme computed for the function.
      This is especially worth remembering for functions containing
      [47m[let][0m or [47m[let*][0m expressions (which translate to [47m[lambda][0m
      applications; see [term]).  If the induction scheme suggested
      by such a function seems to provide more induction hypotheses
      than appear necessary, it might help to admit the function with
      [47m:lambdas[0m included among the ruler extenders even if that is not
      necessary for the termination proof.  This can cause the
      induction scheme to have a richer case analysis with fewer
      induction hypotheses on any given induction step.  While this
      can make it more difficult for the system to merge induction
      schemes to get an appropriate induction, it can also make the
      proof of each induction step easier.  Unfortunately, we have no
      more precise advice as to exactly when adding [47m:lambdas[0m will
      help.  See [induction-coarse-v-fine-grained].

  To see the ruler-extenders of an existing function symbol, [47mfn[0m, in a
  logical [world], [47mwrld[0m, evaluate [47m(ruler-extenders 'fn wrld)[0m after
  [47m(include-book \"kestrel/utilities/system/world-queries\" :dir
  :system)[0m.  For example, evaluation of [47m(ruler-extenders 'fn (w
  state))[0m provides the ruler-extenders of [47mfn[0m in the current logical
  world.

  Below we describe the notion of ruler-extenders in detail, as well as
  how to set its default using [47mset-ruler-extenders[0m.

  [31;1mDetails[0m

  We begin by discussing how to set the ruler-extenders by using the
  macro [47mset-ruler-extenders[0m; below we will discuss the use of keyword
  [47m:ruler-extenders[0m in [47m[xargs][0m [47m[declare][0m forms.  NOTE: The legal
  values discussed below for [47mset-ruler-extenders[0m are the same as the
  legal values for the [47m:ruler-extenders[0m [47m[xargs][0m keyword.

    Examples:
    (set-ruler-extenders :basic) ; return to default
    (set-ruler-extenders *basic-ruler-extenders*) ; same as immediately above
    (set-ruler-extenders :all) ; every governing IF test rules a recursive call
    (set-ruler-extenders :lambdas) ; LET does not block termination analysis
    (set-ruler-extenders (cons :lambdas *basic-ruler-extenders*))
                                   ; same as immediately above
    (set-ruler-extenders '(f g)) ; termination analysis goes past calls of f, g

    General Form:
    (set-ruler-extenders val)

  where [47mval[0m evaluates to one of [47m:basic[0m, [47m:all[0m, [47m:lambdas[0m, or a true list
  of symbols containing no keyword other than, optionally, [47m:lambdas[0m.

  When a recursive definition is submitted to ACL2 (in [47m:[0m[47m[logic][0m mode),
  the recursion must be proved to terminate; see [defun].  More
  precisely, ACL2 explores the [47m[if][0m structure of the body of the
  definition to accumulate the tests that ``rule'' any given
  recursive call.  The following example reviews how this works.
  Suppose that [47mf[0m has already been defined.

    (defun g (x y)
      (declare (xargs :measure (+ (acl2-count x) (acl2-count y))))
      (if (consp x)
          (g (cdr x) y)
        (if (consp y)
            (f (g x (cdr y)))
          (f (list x y)))))

  ACL2 makes the following response to this proposed definition.
  Notice that the [47m:measure[0m proposed above must be proved to be an
  ACL2 ordinal --- that is, to satisfy [47mO-P[0m --- and that the arguments
  to each recursive call must be smaller (in the sense of that
  measure and [47mO<[0m, which here reduces to the ordinary [47m<[0m relation) than
  the formals under the assumption of the ruling [47mIF[0m tests.  The first
  [47mIMPLIES[0m term below thus corresponds to the recursive call [47m(g (cdr
  x) y)[0m, while the second corresponds to the recursive call [47m(g x (cdr
  y))[0m.

    For the admission of G 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) (ACL2-COUNT Y)).  The non-trivial part of the measure
    conjecture is

    Goal
    (AND (O-P (+ (ACL2-COUNT X) (ACL2-COUNT Y)))
         (IMPLIES (CONSP X)
                  (O< (+ (ACL2-COUNT (CDR X)) (ACL2-COUNT Y))
                      (+ (ACL2-COUNT X) (ACL2-COUNT Y))))
         (IMPLIES (AND (NOT (CONSP X)) (CONSP Y))
                  (O< (+ (ACL2-COUNT X) (ACL2-COUNT (CDR Y)))
                      (+ (ACL2-COUNT X) (ACL2-COUNT Y))))).

  Now consider the following alternate version of the above definition.

    (defun g (x y)
      (declare (xargs :measure (+ (acl2-count x) (acl2-count y))))
      (if (consp x)
          (g (cdr x) y)
        (f (if (consp y)
               (g x (cdr y))
             (list x y)))))

  The first test, [47m(consp x)[0m, still rules the first recursive call, [47m(g
  (cdr x) y)[0m.  And the negation of that test, namely [47m(not (consp x))[0m,
  still rules the second recursive call [47m(g x (cdr y))[0m.  But the call
  of [47mf[0m blocks the top-down exploration of the [47mIF[0m structure of the
  body of [47mg[0m, so [47m(consp y)[0m does not rule that second recursive call,
  which (again) is [47m(g x (cdr y))[0m.  As a result, ACL2 fails to admit
  the above definition.

  [47mSet-ruler-extenders[0m is provided to overcome the sort of blocking
  described above.  Suppose for example that the following event is
  submitted:

    (set-ruler-extenders '(f))

  Then the alternate definition of [47mg[0m above is admissible, because the
  call of [47mf[0m no longer blocks the top-down exploration of the [47mIF[0m
  structure of the body of [47mg[0m: that is, [47m(consp y)[0m becomes a ruler of
  the recursive call [47m(g x (cdr y))[0m.  In this case, we say that [47mf[0m is a
  ``ruler-extender''.  The same result obtains if we first submit

    (set-ruler-extenders :all)

  as this removes all function calls as blockers of the top-down
  analysis.  In other words, with [47m:all[0m it is the case that for every
  recursive call, every test argument of a superior call of [47mIF[0m
  contributes a ruler of that recursive call.

  ACL2 handles [47m[let][0m (and [47m[let*][0m) expressions by translating them to
  [47mLAMBDA[0m expressions (see [term]).  The next examples illustrates
  termination analysis involving such expressions.  First consider
  the following (admittedly inefficient) definition.

    (defun fact (n)
      (let ((k (if (natp n) n 0)))
        (if (equal k 0)
            1
          (* k (fact (+ -1 k))))))

  ACL2 translates the body of this definition to a [47mLAMBDA[0m application,
  essentially:

    ((lambda (k)
       (if (equal k 0)
           1
         (* k (fact (+ -1 k)))))
     (if (natp n) n 0))

  As with the application of any function other than [47mIF[0m, the top-down
  termination analysis does not dive into arguments: the [47mLAMBDA[0m
  blocks the continuation of the analysis into its argument.  But
  here, the argument of the [47mLAMBDA[0m is [47m(if (natp n) n 0)[0m, which has no
  recursive calls to consider anyhow.  What is more interesting: ACL2
  does continue its termination analysis into the body of the [47mLAMBDA[0m,
  in an environment binding the [47mLAMBDA[0m formals to its actuals.  In
  this case, the termination analysis thus continues into the term

    (if (equal k 0)
        1
      (* k (fact (+ -1 k))))

  in the environment that binds [47mk[0m to the term [47m(if (natp n) n 0)[0m.  Thus,
  the proof obligation is successfully discharged, as reported by
  ACL2:

    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 N).  The non-trivial part of the measure conjecture is

    Goal
    (IMPLIES (NOT (EQUAL (IF (NATP N) N 0) 0))
             (O< (ACL2-COUNT (+ -1 (IF (NATP N) N 0)))
                 (ACL2-COUNT N))).
    .....
    Q.E.D.

    That completes the proof of the measure theorem for FACT.

  But now consider the following definition, in which the recursion
  takes place inside the argument of the [47mLAMBDA[0m rather than inside
  the [47mLAMBDA[0m body.

    (defun app (x y)
      (let ((result (if (endp x)
                        y
                      (cons (car x)
                            (app (cdr x) y)))))
        (if (our-test result)
            result
          0)))

  Writing the body in [47mLAMBDA[0m notation:

    ((lambda (result)
       (if (our-test result)
           result
         0))
     (if (endp x)
         y
       (cons (car x)
             (app (cdr x) y))))

  By default, the [47mLAMBDA[0m call blocks the top-down termination analysis
  from proceeding into the term [47m(if (endp x) ...)[0m.  To solve this,
  one can submit the event:

    (set-ruler-extenders :lambdas)

  The above definition of [47mapp[0m is then admitted by ACL2, because the
  termination analysis is no longer blocked by the [47mLAMBDA[0m call.

  The example just above illustrates that the heuristically-chosen
  measure is suitably sensitive to the ruler-extenders.
  Specifically: that measure is the application of [47macl2-count[0m to the
  first formal parameter of the function that is tested along every
  branch of the relevant [47mIF[0m structure (as determined by the rulers)
  and occurs as a proper subterm at the same argument position in
  every recursive call.  The heuristics for choosing the
  controller-alist for a [47m[definition][0m rule are similarly sensitive to
  the ruler-extenders (see [definition]).

  The remarks above for [47m[defun][0m [events] are equally applicable when a
  definition sits inside a [47m[mutual-recursion][0m event, except of course
  that in this case, a ``recursive call'' is a call of any function
  being defined by that [47m[mutual-recursion][0m event.

  Rules of class [47m:[0m[47m[definition][0m are sensitive to [47mset-ruler-extenders[0m in
  analogy to the case of [47mdefun[0m [events].

  This macro generates a call [47m(table acl2-defaults-table
  :ruler-extenders val)[0m and hence is [47m[local][0m to any [books] and
  [47m[encapsulate][0m [events] in which it occurs. See
  [ACL2-defaults-table].  The current list of ruler-extenders may be
  obtained as

    (cdr (assoc-eq :ruler-extenders
         (table-alist 'acl2-defaults-table (w state))))

  or more conveniently, as:

    (default-ruler-extenders (w state))

  Note that evaluation of [47m(set-ruler-extenders lst)[0m, where [47mlst[0m
  evaluates to a list, does not necessarily include the default
  ruler-extenders --- i.e., those included for the argument, [47m:basic[0m
  --- which are the elements of the list constant
  [47m*basic-ruler-extenders*[0m, namely [47m[return-last][0m [47m[mv-list][0m, and [47m[if][0m.
  You may, of course, include these explicitly in your list argument.

  We conclude our discussion by noting that the set of ruler-extenders
  can affect the induction scheme that is stored with a recursive
  definition.  The community book
  [47mbooks/misc/misc2/ruler-extenders-tests.lisp[0m explains how induction
  schemes are derived in this case.  Consider the following example.

    (defun tree-of-nils-p (x)
      (if (consp x)
          (and (tree-of-nils-p (car x))
               (tree-of-nils-p (cdr x)))
        (null x)))

  The above definition generates the following induction scheme.  Note
  that [47m(and u v)[0m expands to [47m(if u v nil)[0m, which explains why the term
  [47m(tree-of-nils-p (car x))[0m rules the recursive call [47m(tree-of-nils-p
  (cdr x))[0m, resulting in the hypothesis [47m(tree-of-nils-p (car x))[0m in
  the final conjunct below.

    (AND (IMPLIES (NOT (CONSP X)) (:P X))
         (IMPLIES (AND (CONSP X)
                       (NOT (TREE-OF-NILS-P (CAR X)))
                       (:P (CAR X)))
                  (:P X))
         (IMPLIES (AND (CONSP X)
                       (TREE-OF-NILS-P (CAR X))
                       (:P (CAR X))
                       (:P (CDR X)))
                  (:P X)))

  Now consider the following variant of the above definition, in which
  a call of the function [47midentity[0m blocks the termination analysis.

    (defun tree-of-nils-p (x)
      (if (consp x)
          (identity (and (tree-of-nils-p (car x))
                         (tree-of-nils-p (cdr x))))
        (null x)))

  This time the induction scheme is as follows, since only the
  top-level [47mIF[0m test contributes rulers to the termination analysis.

    (AND (IMPLIES (NOT (CONSP X)) (:P X))
         (IMPLIES (AND (CONSP X)
                       (:P (CAR X))
                       (:P (CDR X)))
                  (:P X)))

  But now suppose we first designate [47midentity[0m as a ruler-extender.

    (set-ruler-extenders '(identity))

  Then the induction scheme generated for the both of the above
  variants of [47mtree-of-nils-p[0m is the one shown for the first variant,
  which is reasonable because both definitions now produce
  essentially the same termination analysis.


Subtopics

  [Default-ruler-extenders]
      The default [ruler-extenders] for [47m[defun][0m'd functions

  [Induction-coarse-v-fine-grained]
      advice on case explosion in complex inductions")
 (RUNE
  (THEORIES)
  "A rule name

    Examples:
    (:rewrite assoc-of-app)
    (:linear delta-aref . 2)
    (:definition length)
    (:executable-counterpart length)

  Note: This topic discusses a basic notion of ``rule name'', or
  ``rune'' for short.  Users often use abbreviations for runes; for
  example, a [theory] expression [47m(DISABLE APPEND)[0m abbreviates the
  following set of runes: [47m{(:DEFINITION BINARY-APPEND), (:INDUCTION
  BINARY-APPEND)}[0m.  See [theories] for a discussion of so-called
  ``runic designators'', which include expressions like [47mAPPEND[0m (as
  above) as well as [47m(APPEND)[0m (for the [executable-counterpart] of
  [47mBINARY-APPEND[0m).  Runic designators can also be ``runic
  abbreviations'' such as [47m(:d APPEND)[0m, [47m(:e APPEND)[0m, [47m(:i APPEND)[0m, and
  [47m(:t APPEND)[0m, which designate the definition,
  executable-counterpart, induction, and type-prescription rules for
  [47mBINARY-APPEND[0m.  For a complete description of runic designators,
  see [theories]; we return now to the more basic notion of a rune.

  Background: The theorem prover is driven from a database of rules.
  The most common rules are [47m:[0m[47m[rewrite][0m rules, which cause the
  simplifier to replace one term with another.  [Events] introduce
  rules into the database.  For example, a [47m[defun][0m event may
  introduce runes for symbolically replacing a function call by its
  instantiated body, for evaluating the function on constants, for
  determining the type of a call of the function, and for the
  induction scheme introduced upon defining the function.  [47m[Defthm][0m
  may introduce several rules, one for each of the [47m:[0m[47m[rule-classes][0m
  specified (where one rule class is specified if [47m:[0m[47m[rule-classes][0m is
  omitted, namely, [47m:rewrite[0m).

  Every rule in the system has a name.  Each name is a structured
  object called a ``rune,'' which is short for ``rule name''.  Runes
  are always of the form [47m(:token symbol . x)[0m, where [47m:token[0m is some
  keyword symbol indicating what kind of rule is named, [47msymbol[0m is the
  event name that created the rule (and is called the ``base symbol''
  of the rune), and [47mx[0m is either [47mnil[0m or a natural number that makes
  the rule name distinct from that of rules generated by other
  [events] or by other [47m:[0m[47m[rule-classes][0m within the same event.

  For example, an event of the form

    (defthm name thm
      :rule-classes ((:REWRITE :COROLLARY term1)
                     (:REWRITE :COROLLARY term2)
                     (:ELIM    :COROLLARY term3)))

  typically creates three rules, each with a unique rune.  The runes
  are

    (:REWRITE name . 1), (:REWRITE name . 2), and (:ELIM name).

  However, a given formula may create more than one rule, and all rules
  generated by the same [47m:corollary[0m formula will share the same rune.
  Consider the following example.

    (defthm my-thm
      (and (equal (foo (bar x)) x)
           (equal (bar (foo x)) x)))

  This is treated identically to the following.

    (defthm my-thm
      (and (equal (foo (bar x)) x)
           (equal (bar (foo x)) x))
      :rule-classes ((:rewrite
                      :corollary
                      (and (equal (foo (bar x)) x)
                           (equal (bar (foo x)) x)))))

  In either case, two rules are created: one rewriting [47m(foo (bar x))[0m to
  [47mx[0m, and one rewriting [47m(bar (foo x))[0m to [47mx[0m.  However, only a single
  rune is created, [47m(:REWRITE MY-THM)[0m, because there is only one rule
  class.  But now consider the following example.

    (defthm my-thm2
      (and (equal (foo (bar x)) x)
           (equal (bar (foo x)) x))
      :rule-classes ((:rewrite
                      :corollary
                      (and (equal (foo (bar x)) x)
                           (equal (bar (foo x)) x)))
                     (:rewrite
                      :corollary
                      (and (equal (foo (bar (foo x))) (foo x))
                           (equal (bar (foo (bar x))) (bar x))))))

  This time there are four rules created.  The first two rules are as
  before, and are assigned the rune [47m(:REWRITE MY-THM . 1)[0m.  The other
  two rules are similarly generated for the second [47m:corollary[0m, and
  are assigned the rune [47m(:REWRITE MY-THM . 2)[0m.

  The function [47m[corollary][0m will return the [corollary] term associated
  with a given rune in a given [world].  Example:

    (corollary '(:TYPE-PRESCRIPTION DIGIT-TO-CHAR) (w state))

  However, the preferred way to see the corollary term associated with
  a rune or a name is to use [47m:pf[0m; see [pf].

  The [47m[defun][0m event creates as many as four rules.  [47m(:definition fn)[0m is
  the rune given to the equality axiom defining the function, [47mfn[0m.
  [47m(:executable-counterpart fn)[0m is the rune given to the rule for
  computing [47mfn[0m on known arguments.  A type prescription rule may be
  created under the name [47m(:type-prescription fn)[0m, and an [induction]
  rule may be created under the name [47m(:induction fn)[0m.

  Runes may be individually [enable]d and [disable]d, according to
  whether they are included in the current theory.  See [theories].
  Thus, it is permitted to [disable] [47m(:elim name)[0m, say, while
  enabling the other rules derived from name.  Similarly,
  [47m(:definition fn)[0m may be [disable]d while [47m(:executable-counterpart
  fn)[0m and the type prescriptions for [47mfn[0m are [enable]d.

  Associated with most runes is the formula justifying the rule named.
  This is called the ``[corollary] formula'' of the rune and may be
  obtained via the function [47m[corollary][0m, which takes as its argument
  a rune and a property list [world].  Also see [pf].  The
  [corollary] formula for [47m(:rewrite name . 1)[0m after the [47m[defthm][0m
  event above is [47mterm1[0m.  The corollary formulas for [47m(:definition fn)[0m
  and [47m(:executable-counterpart fn)[0m are always identical: the defining
  axiom.  Some runes, e.g., [47m(:definition car)[0m, do not have corollary
  formulas.  [47m[Corollary][0m returns [47mnil[0m on such runes.  In any case, the
  corollary formula of a rune, when it is non-[47mnil[0m, is a theorem and
  may be used in the [47m:use[0m and [47m:by[0m [hints].

  Note: The system has built-in rules that, for regularity, ought to
  have names but don't because they can never be [disable]d.  One
  such rule is that implemented by the [linear] arithmetic package.
  Because many of our subroutines are required by their calling
  conventions to return the justifying rune, we have invented the
  notion of ``fake runes.'' Fake runes always have the base symbol
  [47mnil[0m, use a keyword token that includes the phrase ``fake-rune'',
  and are always [enable]d.  Here is the list of fake runes.

      ((:fake-rune-for-linear nil)
       (:fake-rune-for-linear-equalities nil)
       (:fake-rune-for-type-set nil)
       (:fake-rune-for-cert-data nil))

  Occasionally the system will print a fake rune where a rune is
  expected.  For example, when [47m(:FAKE-RUNE-FOR-LINEAR NIL)[0m is
  reported among the rules used in a proof, it is an indication that
  the linear arithmetic package was used.  However, fake runes are
  not allowed in [theories], they cannot be [enable]d or [disable]d,
  and they do not have associated [corollary] formulas.  In short,
  despite the fact that the user may sometimes see fake runes
  printed, they should never be typed.


Subtopics

  [Find-rules-of-rune]
      Find the rules named rune")
 (RUNES-DIFF (POINTERS)
             "See [saving-event-data].")
 (RUNNING_MODELS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Running Models

  {IMAGE} (see [Symbolic_Execution_of_Models])

  Suppose the machine being modeled is some kind of arithmetic unit.
  Suppose the model can be initialized so as to [31;1mmultiply[0m [31;1mx[0m times [31;1my[0m
  and leave the answer in [31;1mz[0m.  Then if we initialize [31;1ms[0m to [31;1mmultiply[0m
  with [31;1mx=5[0m and [31;1my=7[0m and run the machine long enough, we can read the
  answer [31;1m35[0m in the final state.  {IMAGE}

  Because ACL2 is a programming language, our model can be [31;1mrun[0m or
  [31;1mexecuted[0m.

  If you defined the model in ACL2 and then typed

    (lookup 'z (mc (s 'mult 5 7) 29))

  then ACL2 would compute 35.  (Here we assume that the function [47ms[0m
  creates a state ready to run a given application on given inputs [47mx[0m
  and [47my[0m.)  You can [31;1memulate[0m or [31;1mtest[0m the model of your machine.

  This is [31;1mobvious[0m because ACL2 is Common Lisp; and Common Lisp is a
  [31;1mprogramming language[0m.

  {IMAGE} (see [Symbolic_Execution_of_Models])")
 (RW-CACHE (POINTERS)
           "See [set-rw-cache-state].")
 (RW-CACHE-STATE
  (REWRITE)
  "The current rw-cache-state

  See [47m[set-rw-cache-state][0m for background on the [3mrw-cache[0m, which saves
  failed attempts to apply conditional [rewrite] rules.  To get the
  current rw-cache-state, evaluate the following form.

    (rw-cache-state (w state))")
 (SAFE-MODE
  (GUARD MACROS)
  "A mode that avoids [guard] violations on [primitive]s

  ACL2 has a special mode, called ``safe mode'', that guarantees that
  built-in ACL2 [primitive]s check their [guard]s even even when
  [47m[set-guard-checking][0m has turned off guard-checking.  This mode is
  used for macroexpansion as well as in processing a few other kinds
  of forms, notably [47m[defconst][0m, [47m[defpkg][0m, and [47m[value-triple][0m events.

  Use of this mode avoids the possibility of certain errors when
  loading a compiled file for a book.  Consider the following
  definitions.

    (defun foo (x) (declare (xargs :guard (consp x))) (car x))
    (defmacro bar () (foo 3))

  Then we can see [47msafe-mode[0m in action as follows.

    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 >(bar)


    ACL2 Error in TOP-LEVEL:  In the attempt to macroexpand the form (BAR),
    evaluation of the macro body caused the following error:

    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).  The guard is being checked because this function is a primitive
    and a \"safe\" mode is being used for defconst, defpkg, macroexpansion,
    or another operation where safe mode is required.  To debug see :DOC
    print-gv, see :DOC trace, and see :DOC wet.

    ACL2 >

  Notice that because of the [47mset-guard-checking[0m call above, no guard
  violation was reported for [47mfoo[0m.  However, [47msafe-mode[0m caused the call
  of the [primitive], [47m[car][0m, to be guard-checked, and a violation was
  reported.

  To understand how safe-mode works we refer to the notion of
  ``executable-counterpart''; see [evaluation] for relevant
  background.  ACL2 arranges for that for the executable-counterpart
  of any program mode function, [47mF[0m, then for every called subroutine [47mG[0m
  of [47mF[0m that is in program mode, the executable-counterpart of [47mG[0m is
  called rather than the raw Lisp function for [47mG[0m.  This may result in
  an attempt to evaluate a so-called ``[program-only]'' function in
  safe-mode, which is illegal.  See [safe-mode-cheat-sheet] for
  possible workarounds.


Subtopics

  [Safe-mode-cheat-sheet]
      Working around ``[program-only]'' issues")
 (SAFE-MODE-CHEAT-SHEET
  (SAFE-MODE)
  "Working around ``[program-only]'' issues

  This cheat sheet gives workarounds for errors caused by attempts to
  evaluate executable-counterparts (see [evaluation]) of so-called
  [program-only] functions.  This most often occurs when [safe-mode]
  is active.  Recall that safe-mode can be set by [47m(assign safe-mode
  t)[0m, and also is used during macroexpansion and other logical acts
  that might involve [47m:[0m[47m[program][0m mode functions.

  The problems manifest with a hard error like this:

    HARD ACL2 ERROR in PROGRAM-ONLY:  The call
    <term>
    is an illegal call of a function that has been marked as ``program-
    only,'' presumably because it has special raw Lisp code and safe-mode
    is active.  See :DOC program-only for further explanation and a link
    to possible workarounds.
    (See :DOC set-iprint to be able to see elided values in this message.)

  When the term is a call of [47mev-w[0m, an unsafe hack allowing such calls
  is as follows.  Warning: This may result in unsoundness!  (On a
  related note: For discussion about unsoundness when converting such
  [program]-mode functions to [logic] mode, see [program-only].)

    (value :q)
    (setf (symbol-function (*1*-symbol 'ev-w))
          (symbol-function 'ev-w))
    (lp)

  Typically that just leads to other similar errors and so you discover
  the call tree, each of whose functions can be handled similarly
  (also in raw Lisp):

    (setf (symbol-function (*1*-symbol 'ev-rec))
          (symbol-function 'ev-rec))
    (setf (symbol-function (*1*-symbol 'ev-fncall-rec))
          (symbol-function 'ev-fncall-rec))
    (setf (symbol-function (*1*-symbol 'push-warning))
          (symbol-function 'push-warning))

  Other times you may avoid the problem by defining your own utilities.
  For example, in safe-mode you can't use the utility [47m[without-evisc][0m
  (which is useful when [iprint]ing is active).  But the following
  works, provided [47mform[0m evaluates to an [error-triple].

    (defmacro without-evisc-error-triple (form)
      `(state-global-let*
        ((abbrev-evisc-tuple nil set-abbrev-evisc-tuple-state)
         (gag-mode-evisc-tuple nil set-gag-mode-evisc-tuple-state)
         (term-evisc-tuple nil set-term-evisc-tuple-state)
         (ld-evisc-tuple nil set-ld-evisc-tuple-state))
        ,form))

  The following log illustrates how to use this utility to avoid an
  error caused by [47mwithout-evisc[0m in safe-mode.

    ACL2 !>(set-iprint t)

    ACL2 Observation in SET-IPRINT:  Iprinting has been enabled.
    ACL2 !>(assign safe-mode t)
     T
    ACL2 !>(cw \"Something printed with evisceration: ~X01~|\"
               '((((DEEP))))
               (evisc-tuple 3 4 nil nil))
    Something printed with evisceration: (((#@1#)))
    NIL
    ACL2 !>(without-evisc-error-triple (value '(((#@1#)))))
     ((((DEEP))))
    ACL2 !>")
 (SAVE-AND-CLEAR-MEMOIZATION-SETTINGS
  (MEMOIZE)
  "Save and remove the current memoization settings

  For background on memoization, see [memoize].

    General Form:
    (save-and-clear-memoization-settings)

  Calls of this macro achieve two changes.  The first copies the
  current memoization settings into an ACL2 [table], and the second
  unmemoizes all functions that were memoized by calls of [47m[memoize][0m.
  But note that this skips memoization settings that are either
  derived from calls of [47m[memoize-partial][0m or have a non-[47mnil[0m value of
  [47m[memoize][0m argument [47m:invoke[0m

  Also see [restore-memoization-settings].")
 (SAVE-EXEC
  (INTERFACING-TOOLS COMMAND-LINE)
  "Save an executable image and a wrapper script

  [47mSave-exec[0m saves your ACL2 state so that you can immediately re-start
  later in that same state.  This utility can be useful for a project
  with [books] to be included every time ACL2 is started (see
  [build::using-extended-ACL2-images]), to avoid time taken to run
  [47m[include-book][0m.  Another use of [47msave-exec[0m is to save an executable
  that takes command-line arguments beyond those normally passed to
  the host Lisp executable.  All arguments of a call of [47msave-exec[0m are
  evaluated.

  At the end of this topic we discuss how to use the `[47mmake[0m' utility to
  invoke [47msave-exec[0m.

    Examples:

    ; Save an executable script named my-saved_acl2, with the indicated message
    ; added below the words \"MODIFICATION NOTICE\" under the start-up banner:
    (save-exec \"my-saved_acl2\"
               \"This saved image includes Version 7 of Project Foo.\")

    ; Same as above, but instead with a generic comment under the modification
    ; notice:
    (save-exec \"my-saved_acl2\" nil)

    ; Arrange that the generated script passes the indicated arguments to be
    ; processed by the Lisp (ACL2) executable (where this example is specific to
    ; the case that CCL is the host Lisp):
    (save-exec \"my-saved_acl2\" nil
               :host-lisp-args \"--no-init -Z 256M\")

    ; Arrange that the generated script passes along the indicated arguments
    ; to Lisp (ACL2), but that they are not processed by Lisp other than to
    ; record the additional arguments (see (6) below).
    (save-exec \"my-saved_acl2\" nil
               :inert-args \"abc xyz -i foo\")

    ; Combining the preceding two examples:
    (save-exec \"my-saved_acl2\" nil
               :host-lisp-args \"--no-init -Z 256M\"
               :inert-args \"abc xyz -i foo\")

    ; Arrange that ACL2 evaluates (with LD) the three forms shown.
    ; In this example, the THM form fails, but that does not stop the definition
    ; of BAR from being evaluated: LD continues on, just as the top-level loop
    ; lets you continue after a failure.
    (save-exec \"my-acl2\" \"test\"
               :init-forms
               '((defun foo (x) (reverse x))
                 (thm (equal (foo x) x))
                 (defun bar (x) x)))

    ; Essentially as just above, except that the call of LD returns after the THM
    ; failure, so BAR does not get defined.
    (save-exec \"my-acl2\" \"test\"
               :init-forms
               '((ld '((defun foo (x) (reverse x))
                       (thm (equal (foo x) x))
                       (defun bar (x) x))
                     :ld-pre-eval-print t :ld-verbose nil)))

    ; Immediately exit the ACL2 read-eval-print loop after starting up.
    (save-exec \"my-acl2\" nil
               :return-from-lp t)

    ; Immediately exit the ACL2 read-eval-print loop after starting up and
    ; defining function FOO in the logic.
    (save-exec \"my-acl2\" \"Start with foo defined.\"
               :return-from-lp '(with-output
                                 :off :all
                                 (defun foo (x) x)))

    ; Immediately exit the ACL2 read-eval-print loop after starting up and
    ; defining variable xxx in raw Lisp.
    (save-exec \"my-acl2\" \"Start with xxx defined.\"
               :return-from-lp '(with-output
                                 :off :all
                                 (ld '((set-raw-mode-on!)
                                       (defvar xxx (make-list 10))
                                       (set-raw-mode nil)
                                       (u)))))

  Each example above generates a file named \"my-saved_acl2\".  That file
  is quite similar in form to the script generated when building ACL2
  directly from source code; details are below.  For example, here
  are the contents of that generated file if the host Lisp is CCL
  (but where dates and pathnames are specific to one's environment).
  Here, we break lines using `\\', but the [47mexec[0m command is actually on
  a single line.

    #!/bin/sh

    # Saved August 16, 2013  23:06:49
    #  then August 17, 2013  11:01:56

    export CCL_DEFAULT_DIRECTORY=\"/projects/acl2/lisps/ccl/15542/ccl\"
    exec \"/projects/ccl/lx86cl64\" -I \"/u/smith/my-saved_acl2.lx86cl64\" \\
         -Z 64M -K ISO-8859-1 -e \"(acl2::acl2-default-restart)\" \\
         --no-init -Z 256M \\
         -- \\
         abc xyz -i foo \\
         \"$@\"

    General Form:
    (save-exec exec-filename extra-startup-string
               :host-lisp-args host-lisp-args
               :inert-args inert-args
               :return-from-lp return-from-lp
               :init-forms init-forms)

  where the keyword arguments are optional, and arguments are as
  follows.

      [47mExec-filename[0m is the filename of the proposed executable.

      [47mExtra-startup-string[0m is a non-empty string to be printed after the
      normal ACL2 startup message when you start up the saved image.
      However, [47mextra-startup-string[0m is allowed to be [47mnil[0m, in which
      case a generic string will be printed instead.

      [47mHost-lisp-args[0m can be [47mnil[0m (the default), but if it is a non-[47mnil[0m
      value, then it is a string to be inserted into the command line
      in the saved script, specifying additional arguments that are
      to be processed by the host Lisp executable.  (Note for SBCL
      only: these are runtime options; for toplevel options, see (8)
      below.)

      [47mInert-args[0m can be [47mnil[0m (the default), but if it is a non-[47mnil[0m value,
      then it is a string to be inserted into the command line in the
      saved script, specifying additional arguments that are not to
      be processed by the host Lisp executable.

  [47mReturn-from-lp[0m and [47minit-forms[0m are [47mnil[0m by default.  Regardless of
  their value, ACL2 starts up and enters its read-eval-print loop in
  the usual way; see [lp].  Normally you'll stay inside that loop,
  but if [47mreturn-from-lp[0m or [47minit-forms[0m is not [47mnil[0m, then the indicated
  forms are evaluated in the ACL2 read-eval-print loop: a single form
  in the case of [47mreturn-from-lp[0m, and a list of forms in the case of
  [47minit-forms[0m.  (Essentially, the [47m[ld][0m special [47m[standard-oi][0m is
  provided to a call of [47m[ld][0m as a list with the indicated forms on
  the front.)  Moreover, if the case of [47mreturn-from-lp[0m, the loop is
  exited after evaluation of the form, leaving you in raw Lisp.
  Evaluation of [47mreturn-from-lp[0m is done with [47m[ld][0m options that
  minimize output (also see [with-output] to minimize output).
  Suggestion: let [47mreturn-from-lp[0m be [47mt[0m if you simply want to exit the
  read-eval-print loop at startup, without evaluating any
  (nontrivial) form.

  NOTE: It is illegal to supply non-[47mnil[0m values for both [47m:return-from-lp[0m
  and [47m:init-forms[0m.  But if you add [47m(value :q)[0m to the end of your list
  of [47m:init-forms[0m, and your other forms do not result in an error,
  then you will be left in raw Lisp (as was presumably intended if
  you were planning to use [47m:return-from-lp[0m).

  The remainder of this documentation focuses on the options other than
  [47mreturn-from-lp[0m and [47minit-forms[0m.

  [31;1mDetails[0m:

  (1) You must first exit the ACL2 read-eval-print loop, typically by
  executing [47m:[0m[47m[q][0m, before evaluating a [47msave-exec[0m call; otherwise an
  error occurs.

  (2) The image will be saved so that in the new image, the raw Lisp
  package and the package in the ACL2 read-eval-print loop (see [lp])
  will be the same as their respective values at the time [47msave-exec[0m
  is called.

  (3) [47mSave-exec[0m generates a small script file (e.g., [47m\"my-saved_acl2\"[0m in
  the examples above), similar in form (see (4) below) to the script
  generated when building ACL2 directly from source code, but with a
  comment line indicating the time at which the new script is
  written.  [47mSave-exec[0m also saves an associated binary file.  The
  binary file's name is obtained by putting a suffix on the script
  filename; for example, if the host Lisp is GCL running on a Linux
  or Darwin (MacOS) system, then that binary file has the name
  [47mmy-saved_acl2.gcl[0m in the examples above.

  (4) If [47minert-args[0m is [47mnil[0m (for example if keyword [47m:inert-args[0m is
  omitted), then when the generated ACL2 script is invoked with
  command line arguments, those arguments will be passed to the host
  Lisp.  If [47minert-args[0m is supplied a string, then although those
  arguments will be appended to the supplied arguments (see (5)
  below), they will be ignored by the host Lisp (except for being
  recorded; see (6) below).  [47mInert-args[0m is [47mnil[0m by default (that is,
  when omitted).  The other legal value of [47minert-args[0m, [47mt[0m, is
  discussed in (5) below.  Thus for the example above, suppose we
  invoke the generated script as follows.

    my-saved_acl2 -a bcd -e fgh

  If [47mmy-saved_acl2[0m was generated using a [47msave-exec[0m command with a
  non-[47mnil[0m value specified for keyword [47m:inert-args[0m, then the arguments
  ``[47m-a bcd -e fgh[0m'' will not be passed to the host Lisp; otherwise,
  they will be.  Note that for ACL2 executable scripts generated by
  an ordinary ACL2 build from sources, the latter case (i.e., without
  [47minert-args[0m) takes place.

  (5) The generated script, which specifies execution with [47m/bin/sh[0m,
  will generally contain a line of one of the following forms.  (But
  for SBCL, see (8) below.)  In the examples that follow,
  [47mACL2_options[0m is a suitable list of command-line arguments given to
  the ACL2 executable.  The quoted string [47m\"$@\"[0m is intended to allow
  the user to pass additional command-line arguments to that
  executable.

      If [47mhost-lisp-args[0m and [47minert-args[0m are omitted (or [47mnil[0m):

        exec <lisp_executable> <ACL2_options> \"$@\"

      More generally, [47mhost-lisp-args[0m is inserted immediately after
      [47m<ACL2_options>[0m, but only if it is non-[47mnil[0m (hence a string).  If
      [47minert-args[0m is [47mnil[0m, we thus get:

        exec <lisp_executable> <ACL2_options> host-lisp-args \"$@\"

      If [47mhost-lisp-args[0m redefines a value from [47m<ACL2_options>[0m, then it is
      up to the host lisp which value to use.  For example,
      experiments show that in CCL, if [47m-Z[0m appears twice, each with a
      legal value, then the second value is the one that is used
      (i.e. it does indeed override the original value written out by
      ACL2 in [47m<ACL2_options>[0m.  But experiments also show that in
      LispWorks, where ``[47m-init -[0m'' is included in [47m<ACL2_options>[0m,
      then inclusion of ``[47m-init foo.lisp[0m'' in [47mhost-lisp-args[0m is
      ignored.

      The remaining cases below are for a non-[47mnil[0m value of [47minert-args[0m.  In
      each case, if [47mhost-lisp-args[0m is [47mnil[0m then it should be omitted
      from the displayed command.

      If [47minert-args[0m is [47mt[0m then an additional argument, `[47m--[0m', indicates that
      when ACL2 is given command line arguments, these should not be
      processed by the host Lisp (other than recording them; see (6)
      below):

        exec <lisp_executable> <ACL2_options> host-lisp-args -- \"$@\"

      If [47minert-args[0m is a string then the result is similar to the above,
      except that [47minert-args[0m is added immediately after `[47m--[0m':

        exec <lisp_executable> <ACL2_options> host-lisp-args -- inert-args \"$@\"

  (6) See [oslib::argv] for a utility that returns a list of all
  [47minert-args[0m from an invocation of ACL2.  See also [getopt] for a
  convenient way to parse these arguments.

  (7) Suppose that you invoke an ACL2 script, say [47m\"my-saved_acl2\"[0m, that
  was generated by [47msave-exec[0m, and then optionally evaluate some
  forms.  Then you may save a new ACL2 script with [47msave-exec[0m.  The
  new script will contain comment lines that extend comment lines in
  [47m\"my-saved_acl2\"[0m with a new write date, but otherwise will be
  identical to the script that would have been generated by executing
  the new [47msave-exec[0m call after invoking the original ACL2 executable
  (built directly from ACL2 sources) instead of [47m\"my-saved_acl2\"[0m.  In
  other words, the options added by the earlier [47msave-exec[0m call that
  created [47m\"my-saved_acl2\"[0m are discarded by the new [47msave-exec[0m call.
  However, the [47m.core[0m file will built on top of the [47m.core[0m file that
  was consulted when [47m\"my-saved_acl2\"[0m was invoked.

  (8) The following note pertains only to the case that the host Lisp
  is SBCL.  For SBCL, the scripts written are analogous to, but
  slightly different from, those shown above.  Please note that for
  SBCL, the [47mhost-lisp-args[0m are what the SBCL manual calls ``runtime
  options''.  For SBCL only, an extra keyword argument,
  [47m:toplevel-args[0m, may be used for specifying what the SBCL manual
  calls ``toplevel options.  As with [47m:host-lisp-args[0m, this value,
  [47mtoplevel-args[0m, should be [47mnil[0m (the default) or a string.  Here is an
  example.

    (save-exec \"my-saved_acl2\" nil
               :host-lisp-args \"--dynamic-space-size 50000\"
               :toplevel-args \"--eval '(print \\\"HELLO\\\")'\"
               :inert-args \"--my-option my-value\")

  The script generated by this example call of [47msave-exec[0m contains a
  line such as the following (with the same convention for `\\' as
  before).  Notice that [47m:host-lisp-args[0m can be modified at startup
  (without [47msave-exec[0m) by setting environment variable [47mSBCL_USER_ARGS[0m.

    exec \"/projects/sbcl-1.1.7-x86-64-linux/src/runtime/sbcl\" \\
         --dynamic-space-size 24000 --control-stack-size 64 \\
         --core \"/u/smith/my-saved_acl2.core\" --dynamic-space-size 50000 \\
         ${SBCL_USER_ARGS} \\
         --end-runtime-options \\
         --no-userinit --eval '(acl2::sbcl-restart)' \\
         --eval '(print \"HELLO\")' \\
         --end-toplevel-options \\
         --my-option my-value \\
         \"$@\"

  In general, the generated script is of one of the following forms
  (with the same convention for `\\' as before).

      For the case that [47minert-args[0m is [47mnil[0m:

        exec <lisp_executable> \\
             <ACL2_runtime_options> host-lisp-args --end-runtime-options \\
             <ACL2_toplevel_options> host-lisp-args \\
             \"$@\"

      For the case that [47minert-args[0m is non-[47mnil[0m:

        exec <lisp_executable> \\
             <ACL2_runtime_options> host-lisp-args --end-runtime-options \\
             <ACL2_toplevel_options> host-lisp-args --end-toplevel-options \\
             inert-args \"$@\"

  Notice that as before, when the generated script is invoked (for
  example, at the shell), additional command-line arguments provided
  at that time are passed to Lisp if and only if [47minert-args[0m is [47mnil[0m.
  For SBCL, when they are passed to Lisp they are passed as toplevel
  options, not as runtime options.

  Finally, note that [47msave-exec[0m can be invoked using the `[47mmake[0m' utility
  in the main ACL2 directory by using the [47msave-exec[0m target.  That
  target will first build an ACL2 executable in the normal way if it
  is out of date.  Then it will start that executable, using the
  value of [47mACL2_CUSTOMIZATION[0m (as a `[47mmake[0m' or environment variable)
  --- which must be specified --- as the [ACL2-customization] file,
  before making a [47msave-exec[0m call.  By default, that call is
  [47m(save-exec \"custom-saved_acl2\" \"Saved with additions from <file>\")[0m,
  where [47m<file>[0m is the value of [47mACL2_CUSTOMIZATION[0m.  (Except, in
  ACL2(p) and ACL2(r), [47m\"custom-saved_acl2\"[0m is replaced by
  [47m\"custom-saved_acl2p\"[0m and [47m\"custom-saved_acl2r\"[0m, respectively.)
  However, you can specify the first argument as the value of
  [47mACL2_SAVED[0m (as a `[47mmake[0m' or environment variable), and you can
  specify the remaining arguments as the value of [47mACL2_SAVED_ARGS[0m
  (also as a `[47mmake[0m' or environment variable).  Here is an example one
  could run at the shell prompt; notice the careful quoting.

    make save-exec \\
      ACL2_CUSTOMIZATION=~/temp/foo.lsp \\
      ACL2_SAVED=my-acl2 \\
      ACL2_SAVED_ARGS='\"My custom image\" \\
                       :init-forms (quote ((defun foo (x) (reverse x))))'

  WARNING: It is a good idea to look at the log file noted in the
  `[47mmake[0m' output, to check that your customization file loaded as
  intended (presumably, without errors).")
 (SAVING-AND-RESTORING (POINTERS)
                       "See [save-exec].")
 (SAVING-EVENT-DATA
  (SYSTEM-UTILITIES OUTPUT-CONTROLS)
  "Save data stored for subsidiary [events]

  Warning: This is a low-level system utility that may change somewhat
  over time.  For more details, see the ACL2 source code.

    General Forms:
    (saving-event-data form)

    ; See Further information below for keyword options for these two:
    (runes-diff book-name)
    (old-and-new-event-data book-name)

  where [47mform[0m is any form that evaluates to an [error-triple] and
  [47mbook-name[0m is a file ending with [47m\".lisp\"[0m.  See below for typical
  usage.

  A common problem is that a book whose certification formerly
  succeeded now has a certification failure.  In that case, the
  failure is often caused by a proof failure; then one may wish for
  information on what has changed from the previous, successful proof
  attempt and the new, failing proof attempt.  Here is a procedure
  for obtaining such information.  After that we discuss some
  variations on that procedure.


Finding [rune]s that were used only previously, or only now

  Here we discuss a procedure for discovering, given a book [47mBOOK.lisp[0m,
  which [rune]s were used in a previous successful proof but not in
  the new failed proof attempt, or vice-versa.

  The procedure described here requires certain ``event-data''
  information to have been written by a previous certification of
  [47mBOOK.lisp[0m.  Such writing of event-data can be accomplished by
  providing [47m[certify-book][0m the keyword argument [47m:write-event-data t[0m.
  Writing of event-data by [47mcertify-book[0m can also be accomplished by
  setting environment variable [47mACL2_WRITE_EVENT_DATA[0m to a non-empty
  value, though that is overridden if [47m[certify-book][0m keyword argument
  [47m:write-event-data[0m is explicitly supplied the value, [47mnil[0m.  See
  [build::custom-certify-book-commands] for discussion about how a
  [47mcert-flags[0m comment can set [47mcertify-book[0m keyword values when using
  the [47mcert.pl[0m utility.

  When [47mcertify-book[0m writes event-data under either condition above
  (keyword argument or environment variable), it writes it to
  [47mBOOK@event-data.lsp[0m.  That file includes entries of the form [47m(name
  . alist)[0m, where [47malist[0m is an [3mevent-data alist[0m --- see
  [47m[get-event-data][0m --- where each entry corresponds to one of the
  following event types, possibly generated by a macro or
  [47m[make-event][0m call.

    * defthm

    * defun

    * verify-guards

    * thm

  One [47m(name . alist)[0m entry is written for each such event, in the order
  in which the events were encountered during the proof pass of
  certification.  Normally [47mname[0m is the name of the event, but it is
  [47mnil[0m in the case of a [47m[thm][0m event.

  Suppose that you have file [47mBOOK@event-data.lsp[0m as discussed above,
  that is, from having previously certified [47mBOOK.lisp[0m when writing
  event-data.  Also suppose that you now have a copy of [47mBOOK.lisp[0m
  (maybe the same one, maybe not) for which certification has failed,
  possibly using a different ACL2 version than the first, and let [47mEV[0m
  be the event that caused the failure; assume that's because of a
  proof failure.  Below are steps that allow you to see which rules
  (actually, [rune]s) were used in the proof attempt for the first
  event but not the second, or vice-versa.  That information might
  help you to repair the proof, for example by enabling or disabling
  a rule whose [enable]d status has changed after the successful
  certification, or by proving a rule that was in an included book
  during the successful certification but has since been deleted.

  [31;1mStep 1[0m.  Load the [portcullis] commands:

    (ld \"BOOK.port\")

  [31;1mStep 2[0m.  Execute the following command, which will presumably end
  with a failed proof for the event, [47mEV[0m.

    (saving-event-data (ld \"BOOK.lisp\"))

  [31;1mStep 3[0m.  See which runes were used in the old proof and not the new,
  and vice-versa, respectively:

    (runes-diff \"BOOK.lisp\")

  An example is in [community-books] file
  [47mbooks/demos/event-data/test1.lisp[0m, which has comments that lead
  through a variant of the steps above.  File [47mtest1-input.lsp[0m in that
  directory actually carries out that process, resulting in output
  displayed in log file [47mtest1-log.txt[0m in that directory.  Here is the
  output of a [47mrunes-diff[0m call shown both in that log file and in a
  comment in file [47mtest1-input.lsp[0m.  It shows that a
  [type-prescription] rule, named [47mtrue-listp-append[0m, was used in the
  original proof but not the failed proof (which made the [47m[ld][0m call
  of Step 2 above without first performing Step 1, which would have
  introduced that type-prescription rule).  This output also shows
  that the new (failed) proof attempt used many runes not used in the
  previous proof --- not surprisingly, since without the rule
  [47mtrue-listp-reverse[0m the prover made a desperate attempt involving
  destructor elimination and induction.

    ((:OLD ((:TYPE-PRESCRIPTION TRUE-LISTP-REVERSE)))
     (:NEW ((:DEFINITION ALISTP)
            (:DEFINITION ATOM)
            (:DEFINITION NOT)
            (:DEFINITION TRUE-LISTP)
            (:ELIM CAR-CDR-ELIM)
            (:EXECUTABLE-COUNTERPART CONSP)
            (:EXECUTABLE-COUNTERPART NOT)
            (:EXECUTABLE-COUNTERPART REVERSE)
            (:FAKE-RUNE-FOR-TYPE-SET NIL)
            (:INDUCTION ALISTP))))

  A second, analogous set of three files is in that same directory;
  just replace [47m\"test1\"[0m by [47m\"test2\"[0m in the filenames.


Further information

  The [47mrunes-diff[0m utility is intended to serve as an example of a class
  of such query utilities.  It is a macro that expands to a
  corresponding function call.

    ACL2 !>:trans1 (runes-diff \"BOOK.lisp\")
     (RUNES-DIFF-FN \"BOOK.lisp\" NIL NIL NIL 'RUNES-DIFF
                    STATE)
    ACL2 !>

  [47mRunes-diff-fn[0m is actually quite simple.

  [31;1mFunction: [0m<runes-diff-fn>

    (defun runes-diff-fn (book-string name namep dir ctx state)
      (er-let*
           ((old/new (old-and-new-event-data-fn
                          book-string name namep dir ctx state)))
           (let* ((old (car old/new))
                  (new (cdr old/new))
                  (old-runes (get-event-data-1 'rules old))
                  (new-runes (get-event-data-1 'rules new))
                  (old-diff (set-difference-equal old-runes new-runes))
                  (new-diff (set-difference-equal new-runes old-runes)))
             (value (list (list :old old-diff)
                          (list :new new-diff))))))

  It is simple because the real work is carried out using a more
  complex function, [47mold-and-new-event-data-fn[0m.  That function returns
  a pair [47m(old . new)[0m, where [47mold[0m and [47mnew[0m are event-data alists for the
  failed event (called [47mEV[0m above).  Then [47mrunes-diff-fn[0m only needs to
  pick out the [47mRULES[0m fields and form the set-differences.

  The macro [47mold-and-new-event-data[0m provides a convenient interface to
  [47mold-and-new-event-data-fn[0m.

    ACL2 !>:trans1 (old-and-new-event-data \"BOOK.lisp\")
     (OLD-AND-NEW-EVENT-DATA-FN \"BOOK.lisp\"
                                NIL NIL NIL 'OLD-AND-NEW-EVENT-DATA
                                STATE)
    ACL2 !>

  Both [47mrunes-diff[0m and [47mold-and-new-event-data[0m have keyword arguments
  that allow one to choose a specific name for a failed event --- the
  most recent event with that name, rather than [47mEV[0m --- and a
  directory for the given filename, which may be a string or a
  keyword representing a project directory (see [project-dir-alist]).
  The [47m\"test2\"[0m files mentioned above have an example in which the name
  [47mnil[0m is supplied to specify the [47m[thm][0m event most recently preceding
  the failed event (actually it's the only one preceding the failed
  event).

    General Forms:
    (runes-diff book-string &key name dir)
    (old-and-new-event-data book-string &key name dir)

  If you want to use these programmatically, call the corresponding
  [47m\"-FN\"[0m versions, where [47mnamep[0m is [47mt[0m to represent the case that a name
  is provided, else [47mnil[0m.

    General Forms:
    (runes-diff-fn book-string name namep dir ctx state)
    (old-and-new-event-data book-string name namep dir ctx state)")
 (SBCL-INSTALLATION
  (BUILDING-ACL2)
  "Installing Steel Bank Common Lisp (SBCL)

  SBCL is available from [47m{https://www.sbcl.org | https://www.sbcl.org}[0m.
  You can of course go to that website to find download and
  installation instructions for SBCL, but below is a concise summary
  that includes build options appropriate for ACL2.

  [31;1mNOTE:[0m If you already have a previous version of SBCL installed and
  you have experience with Lisp, you might want to see
  [sbcl-installation-brief] for abbreviated instructions to use
  instead of those below.

   1. Download an SBCL binary from
      [47m{https://www.sbcl.org/platform-table.html |
      https://www.sbcl.org}[0m.  That page contains a table with
      combinations of operating systems and hardware architectures,
      from which you have to pick the one that applies to you.  Note
      that you need an SBCL binary in order to compile from source
      (see below).  The file downloaded from the table will have a
      name like [47msbcl-2.1.2-arm64-darwin-binary.tar.bz2[0m, where the
      [47marm64-darwin[0m part depends on the chosen combination of
      operating system and hardware architecture.

   2. Untar the file in a directory of your choice, which will create a
      subdirectory with a name like [47msbcl-2.1.2-arm64-darwin[0m,
      consistently with the name of the downloaded file.

   3. Change to that subdirectory and run

          sh run-sbcl.sh

      to make sure that the binary works.  On macOS, you may get a pop-up
      saying that Apple cannot check it for malware and that it needs
      to be updated.  In that case, open the macOS settings, go under
      `Privacy and Security' (or `Security and Privacy', depending on
      macOS version), and you should see something about the (SBCL)
      executable whose execution was stopped: click the button to
      allow it, and retry running it.  Eventually it should work.

   4. In the same directory where you just ran SBCL, run the SBCL
      installer.  This is done via

          INSTALL_ROOT=... sh install.sh

      where [47m...[0m is optional: if omitted, it defaults to [47m/usr/local[0m.  If
      you pick something different from this default, note that the
      installer will create three directories there, namely [47mbin[0m, [47mlib[0m,
      and [47mshare[0m.  Thus, for examples, if you want to install SBCL in
      your home, you may want to create a directory in your home
      (e.g. [47msbcl[0m, or [47mapps[0m), and pass that as [47mINSTALL_ROOT[0m, instead of
      passing your home directory.

   5. Add that [47mbin[0m directory to your path, so that SBCL can be found.  Try
      running

          sbcl

      to make sure that the installed binary works.  This time macOS
      should not block its execution.

   6. Download the SBCL source from
      [47m{https://www.sbcl.org/platform-table.html |
      https://www.sbcl.org}[0m, the same page with the table of
      binaries.  There should be one link to the sources, above the
      table of binaries.  The downloaded file will have a name like
      [47msbcl-2.3.9-source.tar.bz2[0m.

   7. Untar the file in a directory of your choice, which will create a
      subdirectory with a name like [47msbcl-2.3.9[0m.

   8. Change to that subdirectory, and compile SBCL via:

          sh make.sh --without-immobile-space --without-immobile-code --without-compact-instance-header

      These options prevents certain possible errors.  The compilation
      process prints a lot of stuff on the screen, and should
      succeed.

   9. The final part of the screen output will suggest to run the tests,
      via:

          cd ./tests && sh ./run-tests.sh

      They will take a while, but should eventually succeed.

  10. The final part of the screen output will also suggest to build the
      documentation, via

          cd ./doc/manual && make

      --- this may fail, but that does not seem to matter.

  11. Finally, install the just compiled SBCL in the same way as the
      downloaded binary above, via:

          INSTALL_ROOT=... sh install.sh

      If you use the same [47m...[0m as above (or use the default if you did
      before), the new installation will replace the old one, and
      invoking SBCL (which will still be on the path) will run the
      newly compiled version.

  12. If a new version of the SBCL sources becomes available, you can
      repeat the procedure above to compile and install it, using the
      previously installed binary.

  13. As an alternative to installing the binary compiled from the sources,
      you could create a script, in your executable path, containing

          #!/bin/sh
          <dir>/run-sbcl.sh --dynamic-space-size 2000 \"$@\"

      where [47m<dir>[0m is the untarred directory described above, and where the
      dynamic space size option is just an example of how one can
      pass options to the running SBCL, but it is not necessarily
      needed.  If you need to pass options like this, you can also do
      that if you follow the installation instructions: in that case,
      the script should contain just [47msbcl[0m instead of
      [47m<dir>/run-sbcl.sh[0m.")
 (SBCL-INSTALLATION-BRIEF
  (BUILDING-ACL2)
  "Installing Steel Bank Common Lisp (SBCL)

  The topic [sbcl-installation] contains full installation instructions
  for SBCL.  The present topic contains abbreviated instructions that
  have been used successfully over time; these may be suitable for
  those who already have a previous version of SBCL installed and
  have experience with Lisp.  If the instructions below are not
  sufficient for you, please see [sbcl-installation] instead.

  SBCL is available from [47m{https://www.sbcl.org | https://www.sbcl.org}[0m.
  You can of course go to that website to find download and
  installation instructions for SBCL, but here is a concise summary
  that includes build options appropriate for ACL2.

   1. Download SBCL from [47m{https://www.sbcl.org | https://www.sbcl.org}[0m.  A
      shortcut may be to follow the ``[31;1mSource[0m'' link near the top of
      the page, [47m{https://www.sbcl.org/platform-table.html |
      https://www.sbcl.org/platform-table.html}[0m.

   2. The downloaded file will have a name like
      ``[47msbcl-2.2.10-source.tar.bz2[0m'', where ``[47m2.2.10[0m'' is replaced by
      the current SBCL version.  Change to a directory just above
      where you want SBCL to reside and move the downloaded file
      there.

   3. Extract the downloaded file (where it now resides), for example as
      follows (again, where ``[47m2.2.10[0m'' is replaced by the current
      SBCL version number).

          tar xfj sbcl-2.2.10-source.tar.bz2

   4. Change to the new directory and build SBCL with options appropriate
      for ACL2, as follows (again, replacing ``[47m2.2.10[0m'' as
      appropriate).

          cd sbcl-2.2.10
          sh make.sh --without-immobile-space --without-immobile-code --without-compact-instance-header

   5. Create a script file in a directory that is on your path (or, if you
      are updating your sbcl, just replace your current sbcl script;
      you can find its location by executing the command, ``[47mwhich
      sbcl[0m'').  If you are in directory [47m<DIR>[0m from the preceding step
      (e.g., a path ending in ``[47msbcl-2.2.10[0m''), then that script file
      should contain the following lines.

          #!/bin/sh
          <DIR>/run-sbcl.sh --dynamic-space-size 2000 \"$@\"")
 (SCION
  (APPLY$)
  "A function ancestrally dependent on [47mapply$[0m

  The function [47mfn[0m is a [3mscion of[0m [47mapply$[0m or simply a [3mscion[0m if the
  function is ancestrally dependent on [47mapply$[0m.  That is, [47mfn[0m is
  [47mapply$[0m, or [47mfn[0m calls [47mapply$[0m, or calls a function that calls [47mapply$[0m,
  or calls a function that calls a function that calls [47mapply$[0m, etc.

  Meriam-Webster defines [3mscion[0m as ``a descendant of a wealthy,
  aristocratic, or influential family.''

  Examples of scions include [47mapply$[0m, [47mcollect$[0m and [47mfoldr[0m, where the last
  two are defined as shown below.

    (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)))))

  Note: [47mCollect$[0m, which is part of the support for the [47m[loop$][0m
  statement, is pre-defined in ACL2 but [47mfoldr[0m is not.

  Most often, scions treat one or more of their arguments as
  ``functions,'' i.e., have at least one formal of ilk [47m:FN[0m.  But that
  is not necessarily the case.  [47mCollect$-squares[0m, as defined below,

    (defun$ collect$-squares (lst)
      (collect$ (lambda$ (x) (* x x)) lst))

  is a scion even though it does not have a formal of ilk [47m:FN[0m.
  However, it calls the scion [47mcollect$[0m.

  The function defined by

    (defun$ collect$-expr (x lst alist)
      (if (endp lst)
          nil
          (cons (ev$ x (cons (cons 'v (car lst)) alist))
                (collect$-expr x (cdr lst) alist))))

  is a scion because it calls [47mev$[0m which calls [47mapply$[0m in the mutually
  recursive clique that defines them both.  Note that the ilks of the
  formals of [47mcollect$-expr[0m are [47m:EXPR[0m, [47mNIL[0m and [47mNIL[0m, respectively.  The
  function collects the successive values of the expression [47mx[0m under
  extensions of [47malist[0m binding the variable symbol [47mv[0m to successive
  elements of [47mlst[0m.

  In the early days of [47mapply$[0m we used the term ``mapping function'' to
  refer to scions.  But that nomenclature was misleading because in
  the Lisp culture ``mapping'' tends to be understood as a kind of
  linear iteration.

  Fans of higher order logic have suggested we use the term
  ``functional'' for our scions, or at least for those scions having
  at least one formal of ilk [47m:FN[0m.  However, we have resisted that
  suggestion because a functional takes a function as an argument and
  is thus a higher-order entity, but ACL2 is first-order, functions
  are never objects in ACL2, and the values of our [47m:FN[0m formals are
  ordinary objects like symbols and lists that are interpreted as
  functions.")
 (SEARCH
  (LISTS STRINGS ACL2-BUILT-INS)
  "Search for a string or list in another string or list

    Example Forms:
    (search \"cd\" \"Cdabcdefcde\")                   ; = 4, index of first match
    (search \"cd\" \"Cdabcdefcde\" :test 'equal)      ; same as above
    (search \"cd\" \"Cdabcdefcde\" :from-end t)       ; = 8, index of last match
    (search \"cd\" \"Cdabcdefcde\" :start1 1)         ; = 1
    (search \"cd\" \"Cdabcdefcde\" :start2 5)         ; = 8
    (search \"cd\" \"Cdabcdefcde\" :test 'char-equal) ; = 0 (case-insensitive)
    (search \"ac\" \"Cdabcdefcde\")                   ; = nil
    (search '(a b) '(9 8 a b 7 6))                    ; = 2

    General Form:
    (search seq1 seq2 &key from-end test start1 start2 end1 end2)

  [47mSearch[0m indicates whether one string or list occurs as a (contiguous)
  subsequence of another string or list, respectively.  It returns
  [47mnil[0m if no such match is found; otherwise it returns the
  (zero-based) index of the first match by default, but a non-[47mnil[0m
  value of keyword argument [47m:from-end[0m causes it to return the last
  match.  The [47m:test[0m is [47mequal[0m by default.  The other legal value for
  [47m:test[0m is [47mchar-equal[0m, which can be given only for two strings, in
  which case the match is case-insensitive.  Finally, values of
  [47m:start1[0m and [47m:end1[0m for the first sequence, and of [47m:start2[0m and [47m:end2[0m
  for the second sequence, bound the portion of the respective
  sequence used for deciding on a match, though the index returned is
  always an index into the second sequence as a whole.

  The [guard] for calls of [47msearch[0m is given by a function,
  [47msearch-fn-guard[0m, which has the following requirements.

    * The two arguments much both satisfy [47m[true-listp][0m or else must both be
      strings.

    * The [47m:test[0m must evaluate to one of the symbols [47m[equal][0m or
      [47m[char-equal][0m, where the latter is only allowed if the (first)
      two arguments are strings.

    * The values of [47m:start1[0m, [47m:start2[0m, [47m:end1[0m, and [47m:end2[0m must all be natural
      numbers, where if omitted they default to 0, 0, the length [47mlen1[0m
      of the first argument, and the length [47mlen2[0m of the second
      argument, respectively.

    * If [47mstart1[0m is the value of [47m:start1[0m, defaulting as described just
      above, and similarly for the other start and end keywords and
      for lengths [47mlen1[0m and [47mlen2[0m as described just above, then: [47mstart1
      <= end1 <= len1[0m and [47mstart2 <= end2 <= len2[0m.

  [47mSearch[0m is a Common Lisp function (actually, a macro in ACL2).  See
  any Common Lisp documentation for more information.


Definition

  [31;1mMacro: [0m<search>

    (defmacro search (seq1 seq2 &key from-end (test ''equal)
                           (start1 '0)
                           (start2 '0)
                           (end1 'nil end1p)
                           (end2 'nil end2p))
     (cons
      'search-fn
      (cons
       seq1
       (cons
        seq2
        (cons
         from-end
         (cons
          test
          (cons
              start1
              (cons start2
                    (cons end1
                          (cons end2
                                (cons end1p (cons end2p 'nil))))))))))))

  [31;1mFunction: [0m<search-fn>

    (defun search-fn (seq1 seq2 from-end test
                           start1 start2 end1 end2 end1p end2p)
     (declare
      (xargs
          :guard (search-fn-guard seq1 seq2 from-end test
                                  start1 start2 end1 end2 end1p end2p)))
     (let* ((end1 (if end1p end1 (length seq1)))
            (end2 (if end2p end2 (length seq2)))
            (seq1 (subseq seq1 start1 end1)))
      (mv-let (seq1 seq2)
              (cond ((eq test 'char-equal)
                     (mv (string-downcase seq1)
                         (string-downcase seq2)))
                    (t (mv seq1 seq2)))
       (and (<= (- end1 start1) (- end2 start2))
            (cond (from-end (search-from-end seq1 seq2 start2 end2 nil))
                  (t (search-from-start seq1 seq2 start2 end2)))))))

  [31;1mFunction: [0m<search-from-end>

    (defun search-from-end (seq1 seq2 start2 end2 acc)
      (declare (xargs :guard (and (or (true-listp seq1) (stringp seq1))
                                  (or (true-listp seq2) (stringp seq2))
                                  (integerp start2)
                                  (<= 0 start2)
                                  (integerp end2)
                                  (<= end2 (length seq2))
                                  (<= (+ start2 (length seq1)) end2))))
      (cond ((or (not (integerp end2))
                 (not (integerp start2)))
             nil)
            (t (let* ((bound2 (+ start2 (length seq1)))
                      (matchp (equal seq1 (subseq seq2 start2 bound2)))
                      (new-acc (if matchp start2 acc)))
                 (cond ((>= bound2 end2) new-acc)
                       (t (search-from-end seq1 seq2 (1+ start2)
                                           end2 new-acc)))))))

  [31;1mFunction: [0m<search-from-start>

    (defun search-from-start (seq1 seq2 start2 end2)
      (declare (xargs :guard (and (or (true-listp seq1) (stringp seq1))
                                  (or (true-listp seq2) (stringp seq2))
                                  (integerp start2)
                                  (<= 0 start2)
                                  (integerp end2)
                                  (<= end2 (length seq2))
                                  (<= (+ start2 (length seq1)) end2))))
      (let ((bound2 (+ start2 (length seq1))))
        (cond ((or (not (integerp end2))
                   (not (integerp start2)))
               nil)
              ((equal seq1 (subseq seq2 start2 bound2))
               start2)
              ((>= bound2 end2) nil)
              (t (search-from-start seq1 seq2 (1+ start2)
                                    end2)))))")
 (SECOND
  (NTH ACL2-BUILT-INS)
  "Second member of the list

  See any Common Lisp documentation for details.")
 (SERIALIZE
  (IO)
  "Routines for saving ACL2 objects to files, and later restoring them

  We thank Jared Davis for contributing the ``serialization'' routines
  for saving ACL2 objects in files for later loading.

  We implement some routines for writing arbitrary ACL2 objects to
  files, and for loading those files later.  We usually call these
  \".sao\" files, which stands for (S)erialized (A)CL2 (O)bject.

  Our serialization scheme uses a compact, binary format that preserves
  structure sharing in the original object.  We optimize for read
  performance.


Subtopics

  [Serialize-alternatives]
      Historic alternatives to the [serialize] routines.

  [Serialize-in-books]
      Using serialization efficiently in books

  [Serialize-read]
      Read a serialized ACL2 object from a file

  [Serialize-write]
      Write an ACL2 object into a file

  [Set-serialize-character-system]
      Avoid some special [serialize] writing, including for [47m.cert[0m files

  [With-serialize-character]
      Control output mode for [47mprint-object$[0m")
 (SERIALIZE-ALTERNATIVES
  (SERIALIZE)
  "Historic alternatives to the [serialize] routines.

  Routines [47mcompact-print-file[0m and [47mcompact-read-file[0m were previously
  built into ACL2.  Another option was to use the [47mhons-archive[0m
  library.  These tools were deprecated and ultimately removed from
  ACL2.  If for some reason you need to use them, see
  [community-books] SVN revisions prior to 1314.")
 (SERIALIZE-IN-BOOKS
  (SERIALIZE)
  "Using serialization efficiently in books

  Our serialize scheme was developed in order to allow very large ACL2
  objects to be loaded into books.  Ordinarily this is carried out
  using [47m[serialize-read][0m within a [47m[make-event][0m, e.g.,

    (make-event (mv-let (obj state)
                        (serialize-read \"my-file\")
                        (value `(defconst *my-file* ',obj))))

  But this scheme is not particularly efficient.

  During [47m[certify-book][0m, the actual call of [47mserialize-read[0m is carried
  out, and this is typically pretty fast.  But then a number of
  possibly inefficient things occur.

    * The ACL2 function [47mbad-lisp-object[0m is run on the resulting object.
      This is memoized for efficiency, but may still take
      considerable time when the file is very large.

    * The [checksum] of the resulting object is computed (though this is
      not the default; see [book-hash].  This is also memoized, but
      as before may still take some time.

    * The object that was just read is then written into book.cert,
      essentially with [47m[serialize-write][0m.  This can take some time,
      and results in large certificate files.

  Then, during [include-book], the [47mmake-event[0m expansion is loaded.
  This is now basically just a [47mserialize-read[0m.

  The moral of the story is that using serialize will only help your
  [47mcertify-book[0m time, and it only impacts a portion of the overall
  time.

  To avoid this overhead, we have developed an UNSOUND alternative to
  [47mserialize-read[0m, which is available only by loading an additional
  book.  So, if the above scheme is not performing well for you, you
  may wish to see [unsound-read].")
 (SERIALIZE-READ
  (SERIALIZE ACL2-BUILT-INS)
  "Read a serialized ACL2 object from a file

  General form:

    (serialize-read filename
                    [:hons-mode {:always, :never, :smart}]   ; :smart by default
                    [:verbosep  {t, nil}])                   ; nil by default
     -->
    (mv obj state)

  In the logic this is an oracle read.

  Under the hood, we try to read and return a serialized object from a
  file that was presumably created by [47m[serialize-write][0m.  On success
  we return the contents of the file.  Any failures (e.g., file not
  found, bad file contents, etc.) will result in a hard Lisp error.

  The [47mfilename[0m should be a string that gives the path to the file.

  The [47mhons-mode[0m controls how whether to use [47m[hons][0m or [47m[cons][0m to restore
  the object.  The default mode is [47m:smart[0m, which means that conses
  that were [normed] at the time of the file's creation should be
  restored with [47mhons[0m.  But you can override this and insist that [47mhons[0m
  is to [47m:always[0m or [47m:never[0m be used, instead.

  Why would you use [47m:never[0m?  If your object previously had a lot of
  honses, but you no longer have any need for them to be normed, then
  using [47m:never[0m may sometimes be a lot faster since it can avoid [47mhons[0m
  calls.  On the other hand, if you are going to [47m[hons-copy][0m some
  part of the file's contents, then it is likely faster to use [47m:smart[0m
  or [47m:always[0m instead of first creating normal conses and then copying
  them to build honses.

  The [47m:verbosep[0m flag just controls whether to print some low-level
  details related to timing and memory usage as the file is being
  read.")
 (SERIALIZE-WRITE
  (SERIALIZE ACL2-BUILT-INS)
  "Write an ACL2 object into a file

  General form:

    (serialize-write filename obj
                     [:verbosep  {t, nil}])    ; nil by default
     -->
    state

  In the logic this carries out an oracle read.

  Under the hood, we try to save [47mobj[0m into the file indicated by
  [47mfilename[0m, which must be a string.  The object can later be
  recovered with [47m[serialize-read][0m.  We just return [47mstate[0m, and any
  failures (e.g., file not openable) will result in a hard Lisp
  error.

  Writing objects to disk is generally slower than reading them back in
  since some analysis is required to convert an object into our
  [serialize]d object format.

  The [47mverbosep[0m flag just says whether to print some low-level details
  related to timing and memory usage as the file is being written.")
 (SET-ABSSTOBJ-DEBUG
  (DEFABSSTOBJ)
  "Get more information when atomic update fails for an abstract stobj

  This [documentation] topic assumes familiarity with abstract stobjs.
  See [defabsstobj].

  Below we explain what is meant by the following error message, and
  how to add information to the end of it.

    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.

  Advanced users who are willing to risk unsound invariance violations
  to get a bit more speed may submit the following when there is an
  active trust tag (see [defttag]).

    (set-absstobj-debug :ignore)

  The rest of the session will then avoid the error message above
  because it avoids the abstract stobj invariance checking discussed
  below.  BUT WITHOUT THIS CHECKING, YOUR SESSION COULD BE CORRUPTED!
  The discussion below assumes that you are not using the special
  argument [47m:ignore[0m for [47mset-absstobj-debug[0m.

  The use of [47m(set-absstobj-debug t)[0m will make the error message above
  more informative, for example as follows, at the cost of slower
  execution --- but in practice, the slowdown may be negligible (more
  on that below).  Below, only the last two lines are new.

    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.
    Evaluation was aborted under a call of abstract stobj export
    UPDATE-FLD-NIL-BAD.

  You may be best off starting a new ACL2 session if you see one of the
  errors above.  But you can continue at your own risk.  With a trust
  tag (see [defttag]), you can even fool ACL2 into thinking nothing
  is wrong, and perhaps you can fix up the abstract stobj so that
  indeed, nothing really is wrong.  See the [community-books] file
  [47mbooks/demos/defabsstobj-example-4-input.lsp[0m for how to do that.
  (The corresponding output file
  [47mbooks/demos/defabsstobj-example-4-log.txt[0m may also be informative.)

    Examples:
    (set-absstobj-debug t)                 ; obtain extra debug info, as above
    (set-absstobj-debug nil)               ; avoid extra debug info (default)
    (set-absstobj-debug :ignore)           ; possibly unsound! -- see above

    General Form:
    (set-absstobj-debug val)

  where [47mval[0m is evaluated.

  Recall (see [defabsstobj]) that for any exported function whose [47m:EXEC[0m
  function might (according to ACL2's heuristics) modify the
  foundational stobj non-atomically, one must specify [47m:PROTECT t[0m.
  This results in extra code generated for the exported function,
  which provides a check that atomicity was not actually violated by
  a call of the exported function.  The extra code might slow down
  execution, but perhaps only negligibly in typical cases.  If you
  can tolerate a bit extra slow-down, then evaluate the form
  [47m(set-absstobj-debug t)[0m.  Subsequent such errors will provide
  additional information, as in the example displayed earlier in this
  documentation topic.

  Calls of [47mset-absstobj-debug[0m are legal event forms (e.g., for
  [books]).")
 (SET-ACCUMULATED-PERSISTENCE (POINTERS)
                              "See [accumulated-persistence].")
 (SET-BACKCHAIN-LIMIT
  (BACKCHAIN-LIMIT)
  "Sets the backchain-limit used by the type-set and rewriting
  mechanisms

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

  This event sets the global [47m[backchain-limit][0m used by the ACL2
  type-set and rewriting mechanisms.  Its value may be a cons whose
  car and cdr are each either [47mnil[0m or a non-negative integer.  Its
  value [47mx[0m may also be [47mnil[0m or a non-negative integer, which is treated
  as a cons whose car and cdr are both [47mx[0m.

  The car is used to limit backchaining used by the ACL2 type-set
  mechanism, while the cdr is used to limit backchaining used by the
  rewriting mechanism.  See [backchain-limit] for details about how
  backchain-limits are used.  Rewrite backchain limits may also be
  installed at the level of hints; see [hints] for a discussion of
  [47m:backchain-limit-rw[0m.

    :set-backchain-limit nil  ; do not impose any additional limits
    :set-backchain-limit 0    ; allow only type reasoning for rewriting
                              ; hypotheses
    :set-backchain-limit 500  ; allow backchaining to a depth of no more
                              ; than 500 for rewriting hypotheses
    (set-backchain-limit 500) ; same as above
    :set-backchain-limit (500 500)
                              ; same as above
    (set-backchain-limit '(500 500))
                              ; same as above
    (set-backchain-limit '(3 500))
                              ; allow type-set backchaining to a depth of no more
                              ; than 3 and rewriter backchaining to a depth of no
                              ; more than 500

  The default limit is [47m(nil nil)[0m.")
 (SET-BAD-LISP-CONSP-MEMOIZE
  (MEMOIZE)
  "Turn off or on memoization of raw Lisp function [47mbad-lisp-consp[0m

  WARNING: This is an advanced utility, recommended only for users who
  understand ACL2 at a deep level.  Calling this function can
  permanently alter the performance of low-level raw Lisp function
  [47mbad-lisp-consp[0m.

  Invoke [47m(set-bad-lisp-consp-memoize t)[0m to memoize raw Lisp function
  [47mbad-lisp-consp[0m, which is memoized by default in ACL2 but not
  ACL2(p).  This call has no effect if [47mbad-lisp-consp[0m is already
  memoized.  Similarly, invoke [47m(set-bad-lisp-consp-memoize nil)[0m to
  unmemoize [47mbad-lisp-consp[0m; this call has no effect if [47mbad-lisp-consp[0m
  is already unmemoized.")
 (SET-BODY
  (DEFINITION EVENTS)
  "Set the definition body

    Examples:
    (set-body foo (:definition foo)) ; restore original definition of foo
    (set-body foo foo) ; same as just above
    (set-body foo my-foo-def) ; use my-foo-def for the body of foo
    (set-body foo (:definition my-foo-def)) ; same as just above

  Rules of class [47m:[0m[47m[definition][0m can install a new definition body, used
  for example by [47m:expand[0m [hints].  See [definition] and also see
  [hints] for a detailed discussion of the [47m:install-body[0m fields of
  [47m:[0m[47m[definition][0m rules and their role in [47m:expand[0m hints.

  There may be several such definitions, but by default, the latest one
  is used by [47m:expand[0m hints.  Although the [47m:with[0m keyword may be used
  in [47m:expand[0m hints to override this behavior locally (see [hints]),
  it may be convenient to install a definition for expansion other
  than the latest one --- for example, the original definition.
  [47mSet-body[0m may be used for this purpose.

    General Form:
    (set-body function-symbol rule-name)

  where [47mrule-name[0m is either a [47m:definition[0m [rune] or is a function
  symbol, [47msym[0m, which represents the rune [47m(:definition sym)[0m.

  You can view all definitions available for expansion; see
  [show-bodies].")
 (SET-BOGUS-DEFUN-HINTS-OK
  (DEFUN)
  "Allow unnecessary [47m(xargs :hints ...)[0m and [measure]s.

    General Forms:
    (set-bogus-defun-hints-ok t)
    (set-bogus-defun-hints-ok nil)
    (set-bogus-defun-hints-ok :warn)

  By default, ACL2 causes an error when either of the keywords [47m:[0m[47m[hints][0m
  or [47m:measure[0m is supplied in an [47m[xargs][0m [declare] form for a [47m:[0m[47m[logic][0m
  mode non-recursive definition.  That restriction also applies to
  [47m:[0m[47m[program][0m mode definitions in the case of [47m:measure[0m.  This behavior
  can be defeated with [47m(set-bogus-defun-hints-ok t)[0m, or if you still
  want to see a warning in such cases, [47m(set-bogus-defun-hints-ok
  :warn)[0m.  This utility should perhaps be called
  [47mset-bogus-defun-hints-and-measures-ok[0m, but we retain its original
  name (from when it did not deal with bogus measures).")
 (SET-BOGUS-MEASURE-OK
  (DEFUN)
  "Allow unnecessary [measure]s and [47m(xargs :hints ...)[0m.

  A call [47m(set-bogus-measure-ok X)[0m is just an abbreviation for
  [47m(set-bogus-defun-hints-ok X)[0m.  See [set-bogus-defun-hints-ok].")
 (SET-BOGUS-MUTUAL-RECURSION-OK
  (MUTUAL-RECURSION)
  "Allow unnecessary ``mutual recursion''

    Examples:
    (set-bogus-mutual-recursion-ok t)
    (set-bogus-mutual-recursion-ok nil)
    (set-bogus-mutual-recursion-ok :warn)

  By default, ACL2 checks that when a ``clique'' of more than one
  function is defined simultaneously (using [47m[mutual-recursion][0m or
  [47m[defuns][0m), then every body calls at least one of the functions in
  the ``clique.'' Below, we refer to definitional events that fail
  this check as ``bogus'' mutual recursions.  The check is important
  because ACL2 does not store induction schemes for functions defined
  with other functions in a [47m[mutual-recursion][0m or [47m[defuns][0m event.
  Thus, ACL2 may have difficulty proving theorems by induction that
  involve such functions.  Moreover, the check can call attention to
  bugs, since users generally intend that their mutual recursions are
  not bogus.

  Nevertheless, there are times when it is advantageous to allow bogus
  mutual recursions, for example when they are generated
  mechanically, even at the expense of losing stored induction
  schemes.  The first example above allows bogus mutual recursion.
  The second example disallows bogus mutual recursion; this is the
  default.  The third example allows bogus mutual recursion, but
  prints an appropriate warning.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

    General Form:
    (set-bogus-mutual-recursion-ok flg)

  where [47mflg[0m is either [47mt[0m, [47mnil[0m, or [47m:warn[0m.")
 (SET-BRR-EVISC-TUPLE
  (BRR BRR-EVISC-TUPLE SET-EVISC-TUPLE)
  "Set the [47m[brr-evisc-tuple][0m

    General Form:
    (set-brr-evisc-tuple ev state)

  where [47mev[0m is either the keyword [47m:default[0m or a legal [47m[evisc-tuple][0m.
  This function sets the evisceration tuple used by [brr-commands].
  The current value can be retrieved with [47m[brr-evisc-tuple][0m.  The
  initial value is [47m:default[0m which means the [47m:term[0m evisceration tuple
  is used.  To see how the [47mbrr-evisc-tuple[0m is used see
  [47m[brr-evisc-tuple][0m.

  Think of [47mbrr-evisc-tuple[0m as a true global variable, not a locally
  bound variable of break-rewrite.  In particular, if you set the
  [47mbrr-evisc-tuple[0m inside a break-rewrite interactive break and
  eventually exit that break --- either to enter a deeper break or
  return to a shallower break or to the ACL2 top-level --- the
  [47mbrr-evisc-tuple[0m will retain its chronologically most recent
  setting.

  The general command for setting any of the system evisc-tuples is
  [47m[set-evisc-tuple][0m.")
 (SET-CASE-SPLIT-LIMITATIONS
  (MISCELLANEOUS)
  "Set the [case-split-limitations]

  Also see [case-split-limitations] for an example of how this utility
  inhibits case splitting.

    Examples:
    (set-case-split-limitations '(500 100))
    (set-case-split-limitations 'nil)
    (set-case-split-limitations '(500 nil))

  The first of these prevents [47mclausify[0m from trying the
  subsumption/replacement (see below) loop if more than 500 [clause]s
  are involved.  It also discourages the clause simplifier from
  splitting into more than 100 cases at once.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

  See [hints] for discussion of a related hint,
  [47m:case-split-limitations[0m.  Also see [splitter] for information about
  reports on rules that may be responsible for case splits.

    General Form:
    (set-case-split-limitations lst)

  where [47mlst[0m is either [47mnil[0m (denoting a list of two [47mnil[0ms), or a list of
  length two, each element of which is either [47mnil[0m or a natural
  number.  When [47mnil[0m is used as an element, it is treated as positive
  infinity.  The default setting is [47m(500 100)[0m.

  The first number specifies the maximum number of clauses that may
  participate in the ``subsumption/replacement'' loop.  Because of
  the expensive nature of that loop (which compares every clause to
  every other in a way that is quadratic in the number of literals in
  the clauses), when the number of clauses exceeds about 1000, the
  system tends to ``go into a black hole,'' printing nothing and not
  even doing many garbage collections (because the
  subsumption/replacement loop does not create new clauses so much as
  it just tries to delete old ones).  The initial setting is lower
  than the threshold at which we see noticeably bad performance, so
  you probably will not see this behavior unless you have raised or
  disabled the limit.

  Why raise the subsumption/replacement limit?  The
  subsumption/replacement loop cleans up the set of subgoals produced
  by the simplifier.  For example, if one subgoal is

    (implies (and p q r) s)            [1]

  and another is

    (implies (and p (not q) r) s)      [2]

  then the subsumption/replacement loop would produce the single
  subgoal

    (implies (and p r) s)              [3]

  instead.  This cleanup process is simply skipped when the number of
  subgoals exceeds the subsumption/replacement limit.  But each
  subgoal must nonetheless be proved.  The proofs of [1] and [2] are
  likely to duplicate much work, which is only done once in proving
  [3].  So with a low limit, you may find the system quickly produces
  a set of subgoals but then takes a long time to prove that set.
  With a higher limit, you may find the set of subgoals to be
  ``cleaner'' and faster to prove.

  Why lower the subsumption/replacement limit?  If you see the system
  go into a ``black hole'' of the sort described above (no output,
  and few garbage collections), it could due to the
  subsumption/replacement loop working on a large set of large
  subgoals.  You might temporarily lower the limit so that it begins
  to print the uncleaned set of subgoals.  Perhaps by looking at the
  output you will realize that some function can be disabled so as to
  prevent the case explosion.  Then raise or disable the limit again!

  The second number in the case-split-limitations specifies how many
  case splits the simplifier will allow before it begins to shut down
  case splitting.  In normal operation, when a literal rewrites to a
  nest of [47mIF[0ms, the system simplifies all subsequent literals in all
  the contexts generated by walking through the nest in all possible
  ways.  This can also cause the system to ``go into a black hole''
  printing nothing except garbage collection messages.  This ``black
  hole'' behavior is different from than mentioned above because
  space is typically being consumed at a prodigious rate, since the
  system is rewriting the literals over and over in many different
  contexts.

  As the simplifier sweeps across the clause, it keeps track of the
  number of cases that have been generated.  When that number exceeds
  the second number in case-split-limitations, the simplifier stops
  rewriting literals.  The remaining, unrewritten, literals are
  copied over into the output clauses.  [47mIF[0ms in those literals are
  split out, but the literals themselves are not rewritten.  Each
  output clause is then attacked again, by subsequent simplification,
  and eventually the unrewritten literals in the tail of the clause
  will be rewritten because the earlier literals will stabilize and
  stop producing case splits.

  The default setting of 100 is fairly low.  We have seen successful
  proofs in which thousands of subgoals were created by a
  simplification.  By setting the second number to small values, you
  can force the system to case split slowly.  For example, a setting
  of 5 will cause it to generate ``about 5'' subgoals per
  simplification.

  You can read about how the simplifier works in the book
  Computer-Aided Reasoning: An Approach (Kaufmann, Manolios, Moore);
  also see [introduction-to-the-theorem-prover] for a detailed
  tutorial on using the ACL2 prover.  If you think about it, you will
  see that with a low case limit, the initial literals of a goal are
  repeatedly simplified, because each time a subgoal is simplified we
  start at the left-most subterm.  So when case splitting prevents
  the later subterms from being fully split out, we revisit the
  earlier terms before getting to the later ones.  This can be good.
  Perhaps it takes several rounds of rewriting before the earlier
  terms are in normal form and then the later terms rewrite quickly.
  But it could happen that the earlier terms are expensive to rewrite
  and do not change, making the strategy of delayed case splits less
  efficient.  It is up to you.

  Sometimes the simplifier produces more clauses than you might expect,
  even with case-split-limitations in effect.  As noted above, once
  the limit has been exceeded, the simplifier does not rewrite
  subsequent literals.  But [47mIF[0ms in those literals are split out
  nonetheless.  Furthermore, the enforcement of the limit is --- as
  described above --- all or nothing: if the limit allows us to
  rewrite a literal then we rewrite the literal fully, without regard
  for limitations, and get as many cases as ``naturally'' are
  produced.  It quite often happens that a single literal, when
  expanded, may grossly exceed the specified limits.

  If the second ``number'' is [47mnil[0m and the simplifier is going to
  produce more than 1000 clauses, a ``helpful little message'' to
  this effect is printed out.  This output is printed to the system's
  ``comment window'' not the standard proofs output.")
 (SET-CBD
  (BOOKS-REFERENCE)
  "To set the connected book directory

    Example Forms:
    ACL2 !>:set-cbd \"/usr/home/smith/\"
    ACL2 !>:set-cbd \"my-acl2/books\"

  See [cbd] for a description of the connected book directory.

    General Form:
    (set-cbd str)

  where [47mstr[0m evaluates to a nonempty string that represents the desired
  directory (see [pathname]).  This command sets the connected book
  directory according to that string; see [cbd].  Thus, this command
  may determine which files are processed by [47m[include-book][0m,
  [47m[certify-book][0m, and [47m[ld][0m [command]s, as well as by file operations
  such as [47m[open-input-channel][0m.

  IMPORTANT: Pathnames in ACL2 are in the Unix (trademark of AT&T)
  style.  That is, the character ``[47m/[0m'' separates directory components
  of a pathname, and pathnames are absolute when they start with this
  character, and relative otherwise.  See [pathname].")
 (SET-CHECK-INVARIANT-RISK
  (PROGRAMMING ADVANCED-FEATURES
               GUARD DEBUGGING INVARIANT-RISK)
  "Affect certain [program]-mode updates to [stobj]s or [arrays]

  See [invariant-risk] for an introduction to the notion of
  invariant-risk.  Also see [set-register-invariant-risk] for a way
  to avoid marking a specific set of functions as having
  invariant-risk, which can be much safer than avoiding
  invariant-risk checking for all functions at runtime as described
  below.

  Briefly put, if a syntactic analysis suggests that the call of a
  [47m:[0m[47m[program][0m-mode function can lead to an ill-guarded call of a
  [stobj] updater or of [47m[aset1][0m or [47m[aset2][0m, then ACL2 considers such
  a call to be an ``invariant-risk call''.  There are four different
  ways that ACL2 can handle such a call, corresponding to four
  different values of the ``invariant-risk mode'', which is the value
  obtained by evaluating [47m(get-check-invariant-risk state)[0m.  The
  default invariant-risk mode is [47m:WARNING[0m: in that mode, ACL2 prints
  a warning when encountering a topmost invariant-risk call and uses
  a slower mode of execution in order to avoid ill-guarded calls as
  discussed above.  Mode [47mT[0m has the same behavior, but without the
  warning.  Mode [47m:ERROR[0m causes a break when encountering a topmost
  invariant-risk call; the Lisp should give you the option of
  continuing (as though the mode were [47mT[0m) or aborting, as you choose.
  Finally, mode [47mNIL[0m --- which is unsafe and hence involves a trust
  tag (see [defttag]), as discussed below --- avoids any special
  treatment for invariant-risk calls.

  The utility, [47mset-check-invariant-risk[0m, is provided for changing
  invariant-risk mode.  The simplest case is when that utility is
  only called with one argument, in which case, that argument becomes
  the new invariant-risk mode, as follows.

    (set-check-invariant-risk :ERROR)   ; new mode is :ERROR
    (set-check-invariant-risk :WARNING) ; new mode is :WARNING (the default)
    (set-check-invariant-risk T)        ; new mode is T
    (set-check-invariant-risk NIL)      ; new mode is NIL

  The argument is evaluated (to itself when given one of the four
  constants shown above).  There must be an active trust tag in order
  to set the invariant-risk mode to [47mNIL[0m.  However, ACL2 arranges
  automatically to create a temporary trust tag when invoking
  [47mset-check-invariant-risk[0m on an expression that is other than one of
  the symbols [47m:ERROR[0m, [47m:WARNING[0m, or [47mT[0m.

  An environment variable, [47mACL2_CHECK_INVARIANT_RISK[0m, provides a
  convenient way to evaluate one of these forms automatically when
  ACL2 is invoked.  When that environment variable has a value other
  than the empty string, the value is converted to a symbol after
  converting to upper-case with the function [47m[string-upcase][0m, and
  then corresponding call is make automatically (after loading the
  [ACL2-customization] file, if any).

    \"error\", \":error\" ==> (set-check-invariant-risk :ERROR)
    \"warning\", \":warning\" ==> (set-check-invariant-risk :WARNING)
    \"t\" ==> (set-check-invariant-risk T)
    \"nil\" ==> (set-check-invariant-risk NIL)

  Whether by direct user evaluation or environment variable, these
  calls simply set a certain global parameter, [47m'check-invariant-risk[0m
  (technically, a [state] global variable).  However, they are not
  embedded event forms (see [embedded-event-form]: they cannot appear
  at the top level of books, [47m[encapsulate][0m [events], or [47m[progn][0m
  events.  A non-nil second (optional) argument causes an
  [47m[ACL2-defaults-table][0m entry to be made, associating the key
  [47m:check-invariant-risk[0m with the invariant-risk mode.  Thus, the
  following forms are embedded event forms.  Notice the new ``mode'',
  [47m:CLEAR[0m, which behaves as though removing the key
  [47m:check-invariant-risk[0m from the [47m[ACL2-defaults-table][0m.

    (set-check-invariant-risk :ERROR   t)
    (set-check-invariant-risk :WARNING t)
    (set-check-invariant-risk t        t)
    (set-check-invariant-risk NIL      t)
    (set-check-invariant-risk :CLEAR t) ; avoid using table to determine mode

  As before, the value [47mNIL[0m requires an active trust tag; but unlike
  before, ACL2 does not create a temporary trust tag, but instead
  expect the user to have created one already.  Note also that
  changes to the [47macl2-defaults-table[0m are automatically local to a
  book or [47m[encapsulate][0m event in which they occur;
  [47m[ACL2-defaults-table][0m.  Therefore, do not surround the forms just
  above with [47m[local][0m.

  When the [47m[ACL2-defaults-table][0m associates the key
  [47m:check-invariant-risk[0m with any value (as in the calls above) other
  than [47m:CLEAR[0m, then the invariant-risk mode is actually the
  ``minimum'' of that value and the value of the global parameter,
  [47m'check-invariant-risk[0m, where the modes are ordered from greatest to
  least as shown in the displays above.  An [observation] is printed
  when the new mode does not change: for example, if you start your
  ACL2 session by evaluating [47m(set-check-invariant-risk :ERROR t)[0m,
  then the invariant-risk mode will be the minimum of the existing
  (default) value of [47m:WARNING[0m and the proposed value (newly stored in
  the [47macl2-defaults-table[0m of [47m:ERROR[0m; that minimum is [47m:WARNING[0m, so the
  mode will remain [47m:WARNING[0m and an [observation] will be printed to
  that effect.  You can see all the relevant mode values as follows.

    ; current invariant-risk mode (:WARNING by default):
    (get-check-invariant-risk state)

    ; invariant-risk mode stored in global parameter 'check-invariant-risk:
    (@ check-invariant-risk)

    ; invariant-risk mode stored in the acl2-defaults-table:
    (table acl2-defaults-table :check-invariant-risk)

  The following log illustrates the interaction of the two ways of
  setting the invariant-risk mode (state global and table).

    ACL2 !>(set-check-invariant-risk :error t)

    ACL2 Observation in SET-CHECK-INVARIANT-RISK:  No change is being made
    in the value computed by (GET-CHECK-INVARIANT-RISK STATE).  This happens
    when the value of state global 'check-invariant-risk is less than the
    new table value; see :DOC set-check-invariant-risk.
     :ERROR
    ACL2 !>(get-check-invariant-risk state)
    :WARNING
    ACL2 !>(@ check-invariant-risk)
    :WARNING
    ACL2 !>(set-check-invariant-risk :error)
     :ERROR
    ACL2 !>(@ check-invariant-risk)
    :ERROR
    ACL2 !>(get-check-invariant-risk state)
    :ERROR
    ACL2 !>(set-check-invariant-risk t t)
     T
    ACL2 !>(get-check-invariant-risk state)
    T
    ACL2 !>(set-check-invariant-risk :warning)

    ACL2 Observation in SET-CHECK-INVARIANT-RISK:  No change is being made
    in the value computed by (GET-CHECK-INVARIANT-RISK STATE), because
    the new value of state global 'check-invariant-risk is greater than
    the table value; see :DOC set-check-invariant-risk.
     :WARNING
    ACL2 !>(get-check-invariant-risk state)
    T
    ACL2 !>(set-check-invariant-risk :clear t)
     :CLEAR
    ACL2 !>(get-check-invariant-risk state)
    :WARNING
    ACL2 !>

  Note that the handling of an invariant-risk call of a function, [47mf[0m,
  depends on the current invariant-risk mode, not on the mode in
  place when [47mf[0m was defined.

  It might not be obvious how a given function call could lead to an
  ill-guarded call of a [stobj] updater or of a primitive with
  invariant-risk such as [aref1].  It should be reasonably
  straightforward to write a utility that provides this information;
  contact the ACL2 implementors if you want assistance in writing
  such a utility.")
 (SET-CHECKPOINT-SUMMARY-LIMIT
  (SET-GAG-MODE)
  "Control printing of key checkpoints upon a proof's failure

  See [set-gag-mode] for a discussion of key checkpoints.

    Examples:

    ; (Default) When a proof fails, print all key checkpoints before
    ; induction but at most 3 key checkpoints after induction:
    (set-checkpoint-summary-limit (nil . 3))

    ; When a proof fails, print at most 3 key checkpoints before
    ; induction but all 3 key checkpoints after induction:
    (set-checkpoint-summary-limit (3 . nil))

    ; When a proof fails, print at most 3 key checkpoints before
    ; induction and at most 5 key checkpoints after induction:
    (set-checkpoint-summary-limit (3 . 5))

    ; When a proof fails, print at most 3 key checkpoints before
    ; induction and at most 3 key checkpoints after induction:
    (set-checkpoint-summary-limit (3 . 3))
    ; or equivalently,
    (set-checkpoint-summary-limit 3)

    ; When a proof fails, print all key checkpoints:
    (set-checkpoint-summary-limit (nil . nil))
    ; or equivalently,
    (set-checkpoint-summary-limit nil)

    ; When a proof fails, print no information at all about key checkpoints:
    (set-checkpoint-summary-limit t)

    General Forms:
    (set-checkpoint-summary-limit (n1 . n2))
    (set-checkpoint-summary-limit n)
    (set-checkpoint-summary-limit t)

  where each of [47mn1[0m and [47mn2[0m is a natural number or [47mnil[0m.  For the second
  form, [47mn[0m can be a natural number or [47mnil[0m and is treated as [47m(n . n)[0m.
  The value [47mt[0m inhibits all printing of checkpoint [summary]
  information.  The values [47mn1[0m and [47mn2[0m determine printing of key
  checkpoints generated before the first induction and generated
  after the first induction, respectively, where at most [47mn1[0m or [47mn2[0m
  (respectively) such key checkpoints are printed unless the value is
  [47mnil[0m, in which case there is no limitation.

  The argument [47mx[0m for [47mset-checkpoint-summary-limit[0m, as described above,
  may be quoted, i.e. supplied as [47m'x[0m or [47m(quote x)[0m.  Thus, you may use
  the keyword form (see [keyword-commands]) if you prefer, for
  example:

    :set-checkpoint-summary-limit (nil . 3)

  To see the current limit, invoke [47m(checkpoint-summary-limit)[0m.

  Note that if some subgoal in a set of key checkpoints is [47mNIL[0m, then
  such a subgoal will be printed first in the corresponding list,
  provided of course that the list isn't entirely ignored because of
  a limit of 0.  See [nil-goal].")
 (SET-COMPILE-FNS
  (COMPILATION)
  "Have each function compiled as you go along.

    Example Forms:
    (set-compile-fns t)    ; new functions compiled after DEFUN
    (set-compile-fns nil)  ; new functions not compiled after DEFUN

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

  Also see [comp], because it may be more efficient in some Common
  Lisps to compile many functions at once rather than to compile each
  one as you go along.

    General Form:
    (set-compile-fns term)

  where [47mterm[0m is a variable-free term that evaluates to [47mt[0m or [47mnil[0m.  This
  macro is equivalent to

    (table acl2-defaults-table :compile-fns term)

  and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs; see [ACL2-defaults-table].  However, unlike the
  above simple call of the [47m[table][0m event function (see [table]), no
  output results from a [47mset-compile-fns[0m event.

  [47mSet-compile-fns[0m may be thought of as an event that merely sets a flag
  to [47mt[0m or [47mnil[0m.  The flag's effect is felt when functions are defined,
  as with [47m[defun][0m.  If the flag is [47mt[0m, functions are automatically
  compiled after they are defined, as are their
  executable-counterparts (see [evaluation]).  Otherwise, functions
  are not automatically compiled.  Exception: The flag has no effect
  when explicit compilation is suppressed; see [compilation].

  Because [47mset-compile-fns[0m is an event, the old value of the flag is
  restored when a [47mset-compile-fns[0m event is undone.

  Even when [47m:set-compile-fns t[0m has been executed, functions are not
  individually compiled when processing an [47m[include-book][0m event.  If
  you wish to include a book of compiled functions, we suggest that
  you first certify it with the [compilation] flag set (see
  [certify-book]) or else compile the book by supplying the
  appropriate [47mload-compiled-file[0m argument to [47m[include-book][0m.  More
  generally, [compilation] via [47mset-compile-fns[0m is suppressed when the
  [state] global variable [47m[ld-skip-proofsp][0m has value
  [47m'[0m[47m[include-book][0m.")
 (SET-COMPILER-ENABLED
  (COMPILATION)
  "Disable [compilation].

  For a thorough discussion of this utility, see [compilation].
  Probably its most common use is the following, in order to prohibit
  [47m[include-book][0m from attempting to include compiled files:

    (set-compiler-enabled nil state)")
 (SET-DEBUGGER-ENABLE
  (DEBUGGING)
  "Control whether Lisp errors and breaks invoke the Lisp debugger

    Forms (see below for explanations and GCL exceptions):

    (set-debugger-enable t)         ; enable breaks into the raw Lisp debugger
    (set-debugger-enable :break)    ; same as above
    :set-debugger-enable t          ; same as above
    (set-debugger-enable :break-bt) ; as above, but print a backtrace first
    (set-debugger-enable :bt-break) ; as above, but print a backtrace first
    (set-debugger-enable :bt)       ; print a backtrace but do not enter debugger
    (set-debugger-enable :never)    ; disable all breaks into the debugger
    (set-debugger-enable nil)       ; disable debugger except when calling break$

  [3mIntroduction.[0m Suppose we define [47mfoo[0m in [47m:[0m[47m[program][0m mode to take the
  [47m[car][0m of its argument.  This can cause a raw Lisp error.  ACL2 will
  then return control to its top-level loop unless you enable the
  Lisp debugger, as shown below (except: the error message can take
  quite a different form in non-ANSI GCL).

    ACL2 !>(defun foo (x) (declare (xargs :mode :program)) (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)
    ***********************************************
    ************ 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 !>(SET-DEBUGGER-ENABLE T)
    <state>
    ACL2 !>(foo 3)
    Error: Attempt to take the car of 3 which is not listp.
      [condition type: TYPE-ERROR]

    Restart actions (select using :continue):
     0: Abort entirely from this (lisp) process.
    [Current process: Initial Lisp Listener]
    [1] ACL2(1): [RAW LISP]

  [3mDetails.[0m ACL2 usage is intended to take place inside the ACL2
  read-eval-print loop (see [lp]).  Indeed, in most Lisp
  implementations ACL2 comes up inside that loop, as evidenced by the
  prompt:

    ACL2 !>

  However, one can occasionally hit a raw Lisp error.  Here is the
  above example again, this time for a GCL implementation, which
  unfortunately gives a slightly less aesthetic report.

    ACL2 !>(foo 3)

    Error: 3 is not of type LIST.
    Fast links are on: do (si::use-fast-links nil) for debugging
    Error signalled by CAR.
    Backtrace: funcall > system:top-level > lisp:lambda-closure > lp > acl2_*1*_acl2::foo > foo > car > system:universal-error-handler > system::break-level-for-acl2 > let* > UNLESS
    ACL2 !>

  Here, the user has defined [47mfoo[0m in [47m:[0m[47m[program][0m mode, with an implicit
  [guard] of [47mt[0m.  The ACL2 evaluator therefore called the Lisp
  evaluator, which expected [47mnil[0m or a [47m[consp][0m argument to [47m[car][0m.

  By default, ACL2 will return to its top-level loop (at the same level
  of [47m[ld][0m) when there is a raw Lisp error, as though a call of [47m[er][0m
  with flag [47mHARD[0m has been evaluated.  If instead you want to enter
  the raw Lisp debugger in such cases, evaluate the following form.

    (set-debugger-enable t)

  You can subsequently return to the default behavior with:

    (set-debugger-enable nil)

  Either way, you can enter the Lisp debugger from within the ACL2 loop
  by evaluating [47m([0m[47m[break$][0m[47m)[0m.  If you want [47mbreak$[0m disabled, then
  evaluate the following, which disables entry to the Lisp debugger
  not only for Lisp errors but also when executing [47m(break$)[0m.

    (set-debugger-enable :never)

  The discussion above also applies to interrupts (from [47mControl-C[0m) in
  some, but not all, host Common Lisps --- perhaps all except for
  non-ANSI GCL, where interrupts will likely always put you into the
  debugger.

  It remains to discuss options [47m:break[0m, [47m:bt[0m, [47m:break-bt[0m, and [47m:bt-break[0m.
  Option [47m:break[0m is synonymous with option [47mt[0m, while option [47m:bt[0m prints
  a backtrace.  Options [47m:break-bt[0m and [47m:bt-break[0m are equivalent, and
  each has the combined effect of [47m:bt[0m and [47m:break[0m: a backtrace is
  printed and then the debugger is entered.

  Note that [47mset-debugger-enable[0m applies not only to raw Lisp errors,
  but also to ACL2 errors: those affected by [47m[break-on-error][0m.
  However, for ACL2 errors, entering the debugger is controlled only
  by [47mbreak-on-error[0m, not by [47mset-debugger-enable[0m.  For ACL2 errors
  encountered after evaluating [47m(break-on-error t)[0m, the
  [47mset-debugger-enable[0m values of [47m:bt[0m, [47m:break-bt[0m, and [47m:bt-break[0m will
  result in the same effect: in many host Lisps, this effect will be
  to cause a backtrace to be printed.

  Remark for Common Lisp hackers (except for the case that the host
  Lisp is non-ANSI GCL).  You can customize the form of the backtrace
  printed by entering raw Lisp (with [47m:q[0m) and then redefining function
  [47mprint-call-history[0m, whose definition immediately precedes that of
  [47mbreak-on-error[0m in ACL2 source file [47mld.lisp[0m.  Of course, all bets
  are off when defining any function in raw Lisp, but as a practical
  matter you are probably fine as long as your books are ultimately
  certified with an unmodified copy of ACL2.  If you come up with
  improvements to [47mprint-call-history[0m, please pass them along to the
  ACL2 implementors.")
 (SET-DEFAULT-BACKCHAIN-LIMIT
  (BACKCHAIN-LIMIT)
  "Sets the default backchain-limit used when admitting a rule

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

  This event sets the default [47m[backchain-limit][0m used when a new
  [47m[rewrite][0m, [47m[linear][0m, [47m[meta][0m, or [47m[type-prescription][0m rule is
  admitted.  Its value may be a two-element list whose elements are
  each either [47mnil[0m or a non-negative integer.  Its value [47mx[0m may also be
  [47mnil[0m or a non-negative integer, which is treated as the two element
  list [47m(x x)[0m.

  The first element of the list is used to limit backchaining for a
  rule of class [47m[type-prescription][0m while the second element is used
  to limit backchaining for the other three classes of rules
  mentioned above.  See [backchain-limit] for details about how
  backchain-limits are used.  The examples below assume that a new
  rule doesn't itself specify a value for [47m:backchain-limit-lst[0m.

    :set-default-backchain-limit nil  ; do not impose backchain limits for the
                                      ; rule
    :set-default-backchain-limit 0    ; allow only type reasoning for
                                      ; relieving a new rule's hypotheses
    :set-default-backchain-limit 500  ; allow backchaining through a new rewrite,
                                      ; linear, or meta rule's hypotheses to a
                                      ; depth of no more than 500
    (set-default-backchain-limit 500) ; same as above
    :set-default-backchain-limit (nil 500)
                                      ; same as above
    (set-default-backchain-limit '(nil 500))
                                      ; same as above
    (set-default-backchain-limit '(3 500))
                                      ; for a new :type-prescription rule, allow
                                      ; type-set backchaining to a depth
                                      ; of no more than 3; for a new
                                      ; rule of class :rewrite, :linear,
                                      ; or :meta, allow backchaining to
                                      ; a depth of no more than 50
    (set-default-backchain-limit '(nil 500))
                                      ; do not limit backchaining for a
                                      ; new :type-prescription rule; for
                                      ; a new rule of class :rewrite,
                                      ; :linear, or :meta, allow
                                      ; backchaining to a depth of no
                                      ; more than 50

  The initial default backchain-limit is [47mnil[0m.")
 (SET-DEFAULT-HINTS
  (DEFAULT-HINTS)
  "Set the default hints

    Examples:
    (set-default-hints '((computed-hint-1 clause)
                         (computed-hint-2 clause
                                          stable-under-simplificationp)))
    (set-default-hints nil)

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [set-default-hints!] for a corresponding non-[47m[local][0m
  event.

    General Form:
    (set-default-hints lst)

  where [47mlst[0m is a list.  Generally speaking, the elements of [47mlst[0m should
  be suitable for use as [47m[computed-hints][0m.

  Whenever a [47m[defthm][0m or [47m[thm][0m command is executed, the default hints
  are appended to the right of any explicitly provided [47m:[0m[47m[hints][0m in
  the command.  The same applies to [47m[defun][0ms as well ([47m:hints[0m,
  [47m:guard-hints[0m, and (for ACL2(r)) [47m:std-hints[0m).  The hints are then
  translated and processed just as though they had been explicitly
  included.

  Technically, we do not put restrictions on [47mlst[0m, beyond that it is a
  true list.  It would be legal to execute

    (set-default-hints '((\"Goal\" :use lemma23)))

  with the effect that the given hint is added to subsequent hints
  supplied explicitly.  An explicit \"Goal\" hint would, however, take
  priority, as suggested by the mention above of ``appended to the
  right.''

  Note that [47mset-default-hints[0m sets the default hints as specified.  To
  add to or remove from the current default, see [add-default-hints]
  and see [remove-default-hints].  To see the current default hints,
  see [default-hints].

  Finally, note that the effects of [47mset-default-hints[0m,
  [47m[add-default-hints][0m, and [47m[remove-default-hints][0m are [47m[local][0m 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 [47m[set-default-hints!][0m, [47m[add-default-hints!][0m, or
  [47m[remove-default-hints!][0m.

  For a related feature, which however is only for advanced system
  builders, see [override-hints].")
 (SET-DEFAULT-HINTS!
  (DEFAULT-HINTS)
  "Set the default hints non-[47m[local][0mly

  Please see [set-default-hints], which is the same as
  [47mset-default-hints![0m except that the latter is not [47m[local][0m to the
  [47m[encapsulate][0m or the book in which it occurs.  Probably
  [set-default-hints] is to be preferred unless you have a good
  reason for wanting to export the effect of this event outside the
  enclosing [47m[encapsulate][0m or book.")
 (SET-DEFERRED-TTAG-NOTES
  (DEFTTAG)
  "Modify the verbosity of [47mTTAG NOTE[0m printing

    General Form:
    (set-deferred-ttag-notes val state)

  where [47mval[0m is [47mt[0m or [47mnil[0m.

  See [defttag] for a discussion of trust tags (ttags).  By default, a
  ``[47mTTAG NOTE[0m'' is printed in order to indicate reliance on a ttag.
  When many such notes are printed, it may be desirable to avoid
  seeing them all.  Upon evaluation of the form

    (set-deferred-ttag-notes t state)

  ACL2 will enter a deferred mode for the printing of ttag notes.  In
  this mode, only the first ttag note is printed for each top-level
  command, and the remainder are summarized before the next top-level
  prompt (if any) is printed, hence before the next command is
  evaluated.  That summary is merely a list of ttags, but the summary
  explains that the full ttag notes may be printed with the command
  [47m(show-ttag-notes)[0m.

  Note that [47m(show-ttag-notes)[0m spares you duplicate ttag notes.  If you
  want to see every ttag note as it would normally appear, for
  maximum security, do not evaluate the command
  [47m(set-deferred-ttag-notes t state)[0m.  You can undo the effect of this
  command, returning to an immediate mode for printing ttag notes, by
  evaluating:

    (set-deferred-ttag-notes nil state)")
 (SET-DIFFERENCE$
  (LISTS ACL2-BUILT-INS)
  "Elements of one list that are not elements of another

    General Forms:
    (set-difference$ l1 l2)
    (set-difference$ l1 l2 :test 'eql)   ; same as above (eql as equality test)
    (set-difference$ l1 l2 :test 'eq)    ; same, but eq is equality test
    (set-difference$ l1 l2 :test 'equal) ; same, but equal is equality test

  [47m(Set-difference$ l1 l2)[0m equals a list that contains the [47m[member][0ms of
  [47ml1[0m that are not [47m[member][0ms of [47ml2[0m.  More precisely, the resulting
  list is the same as one gets by deleting the members of [47ml2[0m from [47ml1[0m,
  leaving the remaining elements in the same order as in [47ml1[0m.  The
  optional keyword, [47m:TEST[0m, has no effect logically, but provides the
  test (default [47m[eql][0m) used for comparing members of the two lists.

  The [guard] for a call of [47mset-difference$[0m depends on the test.  In
  all cases, both arguments must satisfy [47m[true-listp][0m.  If the test
  is [47m[eql][0m, then one of the arguments must satisfy [47m[eqlable-listp][0m.
  If the test is [47m[eq][0m, then one of the arguments must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47mset-difference$[0m and its variants:

      [47m(set-difference-eq l1 l2)[0m is equivalent to [47m(set-difference$ l1 l2
      :test 'eq)[0m;

      [47m(set-difference-equal l1 l2)[0m is equivalent to [47m(set-difference$ l1 l2
      :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47mset-difference-equal[0m.

  [31;1mFunction: [0m<set-difference-equal>

    (defun set-difference-equal (l1 l2)
      (declare (xargs :guard (and (true-listp l1) (true-listp l2))))
      (cond ((endp l1) nil)
            ((member-equal (car l1) l2)
             (set-difference-equal (cdr l1) l2))
            (t (cons (car l1)
                     (set-difference-equal (cdr l1) l2)))))

  [47mSet-difference$[0m is similar to the Common Lisp primitive
  [47mset-difference[0m.  However, Common Lisp does not specify the order of
  elements in the result of a call of [47mset-difference[0m.")
 (SET-DIFFERENCE-EQ (POINTERS)
                    "See [set-difference$].")
 (SET-DIFFERENCE-EQUAL (POINTERS)
                       "See [set-difference$].")
 (SET-DIFFERENCE-THEORIES
  (THEORIES THEORY-FUNCTIONS)
  "Difference of two [theories]

    Example:
    (set-difference-theories (current-theory :here)
                             '(fact (fact)))

    General Form:
    (set-difference-theories th1 th2)

  where [47mth1[0m and [47mth2[0m are [theories] (see [theories]).  To each of the
  arguments there corresponds a runic theory.  This function returns
  the set-difference of those two runic [theories], represented as a
  list and ordered chronologically.  That is, a [rune] is in the
  result iff it is in the first runic theory but not in the second.

  The standard way to ``disable'' a theory, [47mlst[0m, is: [47m(in-theory
  (set-difference-theories (current-theory :here) lst))[0m.

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].")
 (SET-DUPLICATE-KEYS-ACTION
  (MACRO-ARGS MACROS PROGRAMMING ADVANCED-FEATURES)
  "Control action for macro calls with duplicate keyword arguments

    Example Forms:
    (set-duplicate-keys-action thm :warning)
    (set-duplicate-keys-action my-macro-1 nil)

    General Forms:
    (set-duplicate-keys-action name :error)
    (set-duplicate-keys-action name :warning)
    (set-duplicate-keys-action name nil)

  where [47mname[0m is a symbol, one that is generally expected to be the name
  of a macro.

  By default, an error occurs when ACL2 encounters a macro call with
  duplicate keys, for example [47m(foo 3 :y 4 :y 5)[0m where [47m:y[0m is a keyword
  argument of the macro, [47mfoo[0m.  However, the event
  [47m(set-duplicate-keys-action name val)[0m can be used to determine
  whether such duplicate keys cause an error, a warning, or neither,
  according to whether [47mval[0m is the keyword [47m:error[0m, [47m:warning[0m, or [47mnil[0m,
  respectively.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [set-duplicate-keys-action!] for a corresponding
  non-[47m[local][0m event.  Indeed, [47m(set-duplicate-keys-action ...)[0m is
  equivalent to [47m(local (set-duplicate-keys-action! ...))[0m.")
 (SET-DUPLICATE-KEYS-ACTION!
  (OUTPUT-CONTROLS)
  "Non-[47m[local][0m version of [47m[set-duplicate-keys-action][0m

  Please see [set-duplicate-keys-action], which is the same as
  [47mset-duplicate-keys-action![0m except that the latter is not [47m[local][0m to
  the [47m[encapsulate][0m or the book in which it occurs.  Perhaps
  [set-duplicate-keys-action] is to be preferred unless you have a
  good reason for wanting to export the effect of this event outside
  the enclosing [47m[encapsulate][0m or book.")
 (SET-DWP
  (TYPE-REASONING)
  "Affect the effort made in [type-reasoning]

  This is a relatively advanced event that affects the [type-reasoning]
  heuristics.  (The name ``dwp'' stands for ``double-whammy
  property'' because the effect pertains to making a second attempt.)
  The default behavior is obtained with [47m(set-dwp nil)[0m, but type
  reasoning makes an extra effort after evaluation of [47m(set-dwp t)[0m.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [set-dwp!] for a corresponding non-[47m[local][0m event.

    General Form:
    (set-dwp val)

  where [47mval[0m is arbitrary but is typically [47mt[0m or [47mnil[0m, since every non-[47mnil[0m
  value is treated the same as [47mt[0m.

  The following example, from Eric Smith, proves after evaluating
  [47m(set-dwp t)[0m but otherwise fails.

    (thm
     (implies (and (<= 0 (* 2 k)) ; extra hyp ;
                   (unsigned-byte-p 4 k)
                   (integerp x)
                   (< x (+ 4 (* 2 k))))
              (<= x (+ 3 (* 2 k))))
     :hints ((\"Goal\" :in-theory (disable unsigned-byte-p))))

  So why not always evaluate [47m(set-dwp t)[0m at the beginning of an ACL2
  session?  Such a change added 3.9% to the certification of the ACL2
  community books, and at least one book took almost twice as long to
  certify.  That isn't a huge penalty, but on the other hand it seems
  likely that [47m(set-dwp t)[0m is helpful only in rare instances.

  To get the current value of [47mdwp[0m, evaluate [47m(get-dwp nil (w state))[0m.")
 (SET-DWP!
  (TYPE-REASONING)
  "Affect the effort made in [type-reasoning], non-[47m[local][0mly

  Please see [set-dwp], which is the same as [47mset-dwp![0m except that the
  latter is not [47m[local][0m to the [47m[encapsulate][0m or the book in which it
  occurs.  Probably [set-dwp] is to be preferred unless you have a
  good reason for wanting to export the effect of this event outside
  the enclosing [47m[encapsulate][0m or book.")
 (SET-ENFORCE-REDUNDANCY
  (REDUNDANT-EVENTS)
  "Require most events to be redundant

    General Forms:
    (set-enforce-redundancy nil)   ; do not require redundancy (default)
    (set-enforce-redundancy t)     ; most events (see below) must be redundant
    (set-enforce-redundancy :warn) ; warn for most non-redundant events

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

    General Form:
    (set-enforce-redundancy flag)

  where [47mflag[0m is [47mnil[0m, [47mt[0m, or [47m:warn[0m, as indicated above.  This macro is
  essentially equivalent to

    (table acl2-defaults-table :enforce-redundancy flag)

  and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs; see [ACL2-defaults-table].  However, unlike the
  above simple call of the [47m[table][0m event function (see [table]), no
  output results from a [47mset-enforce-redundancy[0m event.

  [47mSet-enforce-redundancy[0m may be thought of as an event that merely sets
  a flag as indicated above, which determines whether most [events],
  including [47m[defun][0m and [47m[defthm][0m events, are allowed to be redundant;
  see [redundant-events].  The exceptions are [47m[deflabel][0m, [47m[defpkg][0m,
  [47m[encapsulate][0m, [47m[include-book][0m, [47m[push-untouchable][0m,
  [47m[remove-untouchable][0m, [47m[set-body][0m, and [47m[table][0m [events].  Any other
  type of non-redundant event will cause an error if [47mflag[0m is [47mt[0m and a
  warning if [47mflag[0m is [47mnil[0m, [3mexcept[0m in the course of carrying out an
  [47m[include-book][0m form or the second pass of an [47m[encapsulate][0m form.

  Note that because [47m[table][0m [events] that set the [47m[ACL2-defaults-table][0m
  are implicitly [47m[local][0m, [47mset-enforce-redundancy[0m events are ignored
  when including books.  However, the presence of the event
  [47m(set-enforce-redundancy t)[0m in a book guarantees that its subsequent
  definitions and theorems are redundant.  This can be a useful
  property to maintain in library development, as we now describe.

  An example of the use of this form can be found in the community
  [books] under directory [47mbooks/rtl/rel4/[0m.  The intention in that
  directory has been to put all the gory details in subdirectories
  [47msupport/[0m and [47marithmetic/[0m, so that the books in subdirectory [47mlib/[0m
  contain only the ``exported'' definitions and theorems.  This
  approach is useful for human readability.  Moreover, suppose we
  want to prove new theorems in [47mlib/[0m.  Typically we wish to prove the
  new theorems using the existing books in [47mlib/[0m; however, our
  methodology demands that the proofs go into books in [47msupport/[0m.  If
  every theorem in [47mlib/[0m is redundant, then we can [3mdevelop[0m the proofs
  in [47mlib/[0m but then when we are done, [3mmove[0m each book with such proofs
  into [47msupport/[0m as follows.  In any such book, we first replace
  [47m[include-book][0m forms referring to books in [47mlib/[0m by [47m[include-book][0m
  forms referring to corresponding books in [47msupport/[0m and/or
  [47marithmetic/[0m.  Then, we add suitable [47m[in-theory][0m events to get us
  back into the original [47mlib/[0m proof environment.

  The default behavior of the system is as though the
  [47m:enforce-redundancy[0m value is [47mnil[0m.  The current behavior can be
  ascertained by evaluating the following form.

    (cdr (assoc-eq :enforce-redundancy (table-alist 'acl2-defaults-table wrld)))")
 (SET-EVISC-TUPLE
  (IO)
  "Control suppression of details when printing

  ACL2 output is generally printed in full.  However, ACL2 can be
  directed to abbreviate, or ``eviscerate'', objects before printing
  them, through the use of a so-called ``evisc-tuple''.  See
  [evisc-tuple] for a discussion of evisc-tuples.  The utility
  [47mset-evisc-tuple[0m modifies certain global evisc-tuples, as explained
  below, to affect the extent to which ACL2 eviscerates objects
  during printing, for example during proof output or when printing
  top-level evaluation results.

    General Form:
    (set-evisc-tuple evisc-tuple  ; a legal evisc-tuple, or :DEFAULT
                    :iprint val   ; one of *iprint-actions*
                    :sites sites) ; either :ALL, or an element or a subset of
                                  ;   the list of legal sites (see below)

  where the value of [47m:iprint[0m is passed to [47m[set-iprint][0m, [47m:sites :all[0m
  abbreviates [47m:sites[0m '[47m(:term :ld :trace :abbrev :gag-mode :brr)[0m, and
  other documentation is provided below.  Note that all arguments are
  evaluated.

  See [without-evisc] for how to avoid evisceration for ACL2 output.

  The following example illustrates an invocation of [47mset-evisc-tuple[0m
  that limits the print-level to 3 --- only three descents into list
  structures are permitted before eviscerating a subterm --- and
  limits the print-length to 4 --- only the first four elements of
  any list structure will be printed.

    ACL2 !>(set-evisc-tuple (evisc-tuple 3   ; print-level
                                         4   ; print-length
                                         nil ; alist
                                         nil ; hiding-cars
                                         )
                            :iprint :same ; better yet, T
                            :sites :all)
     (:TERM :LD :TRACE :ABBREV ...)
    ACL2 !>'((a b ((c d)) e f g) u v w x y)
    ((A B (#) E ...) U V W ...)
    ACL2 !>

  We recommend however using [47m:iprint t[0m so that eviscerated terms may be
  read back in (see [set-iprint]), as shown here:

    ACL2 !>(set-evisc-tuple (evisc-tuple 3   ; print-level
                                         4   ; print-length
                                         nil ; alist
                                         nil ; hiding-cars
                                         )
                            :iprint t
                            :sites :all)

    ACL2 Observation in SET-EVISC-TUPLE:  Iprinting has been enabled.
     (:TERM :LD :TRACE :ABBREV . #@1#)
    ACL2 !>(without-evisc '(:TERM :LD :TRACE :ABBREV . #@1#))
    (:TERM :LD
           :TRACE :ABBREV
           :GAG-MODE :BRR)
    ACL2 !>

  Indeed, the [47m:iprint[0m argument is required as a reminder to the user to
  consider that issue, unless iprinting has been enabled at least
  once.  If [47m:sites[0m or a required [47m:iprint[0m argument is omitted,
  however, ACL2 will query the user for the missing arguments rather
  than causing an error.

  ACL2 eviscerates by default only in a few cases, primarily in
  informational messages for errors, warnings, and queries (i.e., in
  the [47m:EVISC[0m case below), and in response to [break-rewrite]
  commands.  Users can modify the default behavior by supplying a
  suitable argument to [47mset-evisc-tuple[0m.  The argument may be
  [47m:default[0m, which denotes the evisceration provided when ACL2 starts
  up.  Otherwise that argument is an evisc-tuple, which is either [47mnil[0m
  (no evisceration) or as described above.  Moreover, there are six
  evisc-tuple ``evisceration contexts'', each with its own
  evisceration control.  The value returned by [47mset-evisc-tuple[0m
  indicates the evisceration contexts whose evisc-tuple has been set.
  The evisceration contexts are as follows, all of which use a
  default value of [47mnil[0m for the hiding-cars.  Accessors are also shown
  for retrieving the corresponding evisc-tuple.

    * [47m:TERM[0m --- used for printing terms.  The accessor is [47m(term-evisc-tuple
      flg state)[0m, where [47mflg[0m is ignored if [47mset-evisc-tuple[0m has been
      called for [47m:term[0m with value other than [47m:default[0m, and otherwise
      (hence initially): a [47mflg[0m of [47mnil[0m indicates an evisc-tuple of
      [47mnil[0m, and otherwise the term-evisc-tuple has a print-level of 3
      and print-length of 4.

    * [47m:ABBREV[0m --- used for printing informational messages for errors,
      warnings, and queries.  Initially, the alist abbreviates the
      ACL2 [47mworld[0m, print-level is 5, and print-level is 7.  The
      accessor is [47m(abbrev-evisc-tuple state)[0m.

    * [47m:BRR[0m --- used for output from [brr-commands] issued in the
      [break-rewrite] loop.  When the value is [47m:DEFAULT[0m then the
      [3meffective value[0m of this evisc-tuple is the [47m:TERM[0m evisc-tuple
      with [47mflg = t[0m (see above).  Also see [brr-evisc-tuple].

    * [47m:GAG-MODE[0m --- used for printing induction schemes (and perhaps, in
      the future, for other printing) when [gag-mode] is on.  If
      gag-mode is off, the value used for this [evisc-tuple] is
      [47m(term-evisc-tuple nil state)[0m.  But if gag-mode is on (i.e.,
      [47m(gag-mode)[0m evaluates to a non-[47mnil[0m value), then with one
      exception, the value is an evisc-tuple or [47mnil[0m, to be used in
      gag-mode for printing of induction schemes and, during proofs,
      the ``The non-trivial part of the guard conjecture''.  The
      exceptional value is [47mt[0m, which indicates that in gag-mode, no
      printing of induction schemes should be and the guard
      conjecture should be printed using [47m(term-evisc-tuple t state)[0m.
      The accessor is [47m(gag-mode-evisc-tuple state)[0m.

    * [47m:LD[0m --- used by the ACL2 read-eval-print loop.  The accessor is
      [47m([0m[47m[ld-evisc-tuple][0m[47m state)[0m.

    * [47m:TRACE[0m --- used for printing [trace] output.  No accessor is
      available (though in raw Lisp, [47m(trace-evisc-tuple)[0m returns the
      trace-evisc-tuple).

  Each context [47mectx[0m also has an updater, [47m(set-ectx-evisc-tuple val
  state)[0m, where [47mval[0m is a legal value for [47mset-evisc-tuple[0m as described
  above: [47m:default[0m or an [evisc-tuple] (possibly [47mnil[0m).


Subtopics

  [Set-brr-evisc-tuple]
      Set the [47m[brr-evisc-tuple][0m")
 (SET-FAST-CERT (POINTERS)
                "See [fast-cert].")
 (SET-FC-CRITERIA
  (FORWARD-CHAINING-REPORTS)
  "To set the tracking criteria for forward chaining reports

    Examples:
    (set-fc-criteria)                 ; shut off all tracking
    (set-fc-criteria nil)

    (set-fc-criteria t)               ; to track all forward chaining
    (set-fc-criteria (t t t))

    (set-fc-criteria
     ((:FORWARD-CHAINING LEMMA1)      ; track all uses of LEMMA1,
       t
       t)
      ((:FORWARD-CHAINING LEMMA2)     ; uses of LEMMA2 triggered
       (ALISTP (BASIC-MAPPER A B))    ; by this specific ALISTP term
       t)
      (t t (TRUE-LISTP (DLT D))))     ; and every rule deriving
                                      ; this TRUE-LISTP term.

    General Forms:
    (set-fc-criteria nil)
    (set-fc-criteria t)
    (set-fc-criteria triple1 triple2 ...)

  where each triple is of the form [47m(rune inst-trigger inst-concl)[0m.  If
  rune is non-[47mt[0m is must be a forward chaining [rune].  The other two
  components, [47minst-trigger[0m and [47minst-concl[0m, if non-[47mt[0m, must be terms.
  The list of all the triples supplied is called the ``criteria.'' In
  the form [47m(set-fc-criteria nil)[0m, the criteria used is the empty list
  of triples.  (Technically, supplying [47mnil[0m as a triple ``ought'' to
  be an error, but it is a more ``natural'' way to say the list of
  criteria is empty than to use the correct form [47m(set-fc-criteria)[0m.)
  In the form [47m(set-fc-criteria t)[0m the criteria used is the list
  containing the single triple [47m(t t t)[0m.

  This function sets the tracking criteria for forward chaining
  reporting.  See [forward-chaining-reports] for a general discussion
  of tracking and reporting forward chaining activity.

  Think of the forward chaining criteria as a list of triples,
  representing a disjunction of conjunctions.  The activation of a
  [47m:[0m[47m[forward-chaining][0m rune by some triggering term in the current
  context [3msatisfies[0m the criteria if it satisfies one of the triples.
  To satisfy the triple [47m(rune inst-trigger inst-concl)[0m, the
  activation must satisfy each component of the triple.  Any [47mt[0m
  component is always satisfied.  If [47mrune[0m is non-[47mt[0m it is satisfied if
  the activation is for the given rune.  If [47minst-trigger[0m is non-[47mt[0m, it
  is satisfied if the activation is triggered by the given term.
  (``[47mInst-trigger''[0m stands for ``instantiated trigger.'' It is not
  the trigger term of the rule but is supposed to be an instance of
  that term that you believe will arise in some proof attempt you are
  debugging --- an instance you want to ``watch'' as it fires the
  rule.)  If [47minst-concl[0m is non-[47mt[0m, it is satisfied if the activation
  could possibly derive the conclusion given.  (Again, ``[47minst-concl''[0m
  stands for ``instantiated conclusion'' and shows the term in your
  problem that you expect to be derived by forward chaining.)

  Note that if the criteria is empty, it is never satisfied, so
  tracking is turned off.  If the criteria is the singleton list
  containing just the triple [47m(t t t)[0m, then every activation satisfies
  it and so all [47m:forward chaining[0m rules are tracked.

  See [forward-chaining-reports] for details.")
 (SET-FC-REPORT-ON-THE-FLY
  (FORWARD-CHAINING-REPORTS)
  "To determine when forward-chaining reports are printed

    Examples:  (set-fc-report-on-the-fly t)
               (set-fc-report-on-the-fly nil)

  If the flag is set to [47mt[0m, forward chaining tracking reports are
  printed when forward chaining occurs.  If the flag is set to [47mnil[0m,
  very short reports (giving just the caller and the report number)
  are printed during forward chaining but you can use [47m[fc-report][0m to
  see the full report afterwards.

  Since nothing is tracked when the criteria is [47mnil[0m, this function also
  prints out the current criteria to remind you of what it is.

  The flag manipulated by this function does not shut off tracking.  It
  only determines whether reports are printed on-the-fly or not.  To
  shut off tracking [47m[set-fc-criteria][0m.

  See [forward-chaining-reports] for details.")
 (SET-FMT-HARD-RIGHT-MARGIN
  (IO ACL2-BUILT-INS)
  "Set the right margin for formatted output

  In this documentation topic we discuss setting of both a ``soft'' and
  a ``hard'' right margin.

    Example Forms:
    (set-fmt-soft-right-margin 55 state) ; set soft right margin to 55
    (set-fmt-hard-right-margin 68 state) ; set hard right margin to 68

  [47m[Fmt][0m and related functions can insert linebreaks when lines get too
  long.  A linebreak is inserted at an aesthetically appropriate
  point once the column exceeds the value of [47m(@
  fmt-soft-right-margin)[0m.  ACL2 may also insert a linebreak
  (sometimes in an unaesthetic place) to prevent printing in a column
  that equals or exceeds the value of [47m(@ fmt-hard-right-margin)[0m.
  Such a ``hard'' linebreak follows the insertion of a backslash ([47m\\[0m)
  character unless [47m[fmt!][0m, [47m[fms!][0m, or [47m[fmt1!][0m is used, or state
  global [47mwrite-for-read[0m is true.

  Note that a right margin of 40 is used for pretty printing with [47m[fmt][0m
  directives [47m~y[0m, [47m~Y[0m, [47m~q[0m, and [47m~Q[0m and can be changed to a positive
  integer [47mN[0m with [47m(set-ppr-flat-right-margin N state)[0m.")
 (SET-FMT-SOFT-RIGHT-MARGIN
  (IO ACL2-BUILT-INS)
  "Set the soft right margin for formatted output

  See [set-fmt-hard-right-margin] for a discussion of the soft and hard
  right margin for formatted output.")
 (SET-GAG-MODE
  (OUTPUT-CONTROLS)
  "Modify the nature of proof output

    Examples:

    :set-gag-mode t      ; enable gag-mode, suppressing most proof commentary
    (set-gag-mode t)     ; same as above
    :set-gag-mode :goals ; same as above, but print names of goals when produced
    :set-gag-mode nil    ; disable gag-mode

    General Forms:
    (set-gag-mode val)
    :set-gag-mode val

  where [47mval[0m is one of [47mt[0m, [47mnil[0m, or [47m:goals[0m.

  By default, gag-mode is enabled, set to [47m:goals[0m.  To see the current
  value of gag-mode, evaluate the form, [47m(gag-mode)[0m.

    (gag-mode) ; evaluates to t, nil, or :goals

  The basic idea of gag-mode is to avoid much of the verbose output
  from the theorem prover, leaving only output that is expected to be
  helpful.  The first two forms below set gag-mode on, while the
  other turns it off; these may be placed in your ACL2 customization
  file; see [ACL2-customization].

    (set-gag-mode :goals) ; (default) avoid most prover output; show goal names
    (set-gag-mode t)      ; avoid most prover output; also, hide goal names
    (set-gag-mode nil)    ; allow prover output

  Gag-mode focuses attention on so-called ``key checkpoints''.  By
  default, a checkpoint is a goal that cannot be simplified.  (Below
  we discuss how to change this default.)  A key checkpoint is a
  checkpoint that is not descended from another checkpoint.
  (Technical point: ``descended'' signifies that both goals are at
  the top level in the same forcing round, or are in the same proof
  by induction.)  Successful ACL2 users generally focus their
  attention on key checkpoints, or less often, induction schemes.
  (To suppress or abbreviate induction schemes in gag-mode, see
  [set-evisc-tuple], specifically, the discussion of [47m:GAG-MODE[0m.)  For
  a discussion of how to use ACL2 prover output in an effective
  manner, see [the-method], and see
  [introduction-to-the-theorem-prover] for a more detailed tutorial.
  In gag-mode, a key checkpoint is only displayed when ACL2 is unable
  to make any further progress on that goal or some descendant of it,
  other than with a proof by induction.

  Evaluation of [47m(set-gag-mode t)[0m enters gag-mode, so that only key
  checkpoints are printed.  Evaluation of [47m(set-gag-mode :goals)[0m also
  enters gag-mode, but will additionally cause the name of a goal to
  be printed as soon as it is generated (by invoking
  [set-print-clause-ids]).  The [47m:goals[0m setting is the default, and is
  useful for cases in which the prover spends very little of its time
  generating goals to be proved by induction, yet you want to see
  that it is making progress.  For finer-grained feedback about the
  simplifier's activity, see [dmr].

  An alternative to gag-mode is to use proof-trees; see [proof-tree].
  With proof-trees it is not so important to avoid excessive prover
  output, since the proof-tree display provides structure that makes
  it easy to monitor proof attempts and navigate output for a proof
  that has failed or seems to be failing.  Still, output can take
  time to print, so you may get better performance with gag-mode.

  The intention of gag-mode is to show you only the parts of a proof
  attempt that are relevant for debugging a failure; additional
  output is generally more likely to be distracting than truly
  helpful.  But on occasion you may want to see the full proof output
  after an attempt made with gag-mode.  This can be done provided
  proof output is not inhibited (see [set-inhibit-output-lst]) during
  the proof attempt; see [pso] and see [pso!].

  You may notice that gag-mode tends to print relatively little
  information about goals pushed for proof by sub-induction --- i.e.,
  a proof of *i.j, *i.j.k, etc.  That feature emphasizes that
  unsuccessful sub-inductions should generally be avoided, not
  analyzed for ways to make them succeed.  Instead, the key
  checkpoint that generated the goal pushed for this induction is
  more appropriate to analyze.  In general, the ``higher level'' the
  checkpoint, the more worthy it is of attention.  Thus, it might be
  helpful to look at the top-level checkpoints before looking at
  those labeled ``Key checkpoints under a top-level induction''.

  We conclude with remarks for advanced users.

  The notion of ``checkpoint'' can be modified by the user.  The
  default, as discussed above, is for a checkpoint to be a goal that
  cannot be simplified.  Put differently, a checkpoint is acted on by
  one of the processes in the value of the form [47m(@
  checkpoint-processors)[0m; see [@].  Any or all of the symbols
  [47meliminate-destructors-clause[0m, [47mfertilize-clause[0m, [47mgeneralize-clause[0m,
  or [47meliminate-irrelevance-clause[0m can be removed from this value in
  order that invocation of the corresponding proof process does not
  cause its input goal to be labeled a checkpoint.  For example, if
  you do not want destructor elimination to be treated differently
  from simplification for purposes of labeling checkpoints, you can
  evaluate the following form (see [assign]):

    (assign checkpoint-processors
            (remove 'eliminate-destructors-clause
                    (@ checkpoint-processors)))

  Note that the value of [47m(@ checkpoint-processors)[0m also affects the
  proof tree display; see [proof-tree-details].  End of Remark.)

  See [set-evisc-tuple], in particular the discussion there of
  [47m:GAG-MODE[0m, for how to influence slightly just what is printed in
  gag-mode.


Subtopics

  [Checkpoint-summary-limit]
      Control printing of key checkpoints upon a proof's failure

  [Set-checkpoint-summary-limit]
      Control printing of key checkpoints upon a proof's failure")
 (SET-GC-STRATEGY
  (MISCELLANEOUS ACL2-BUILT-INS)
  "Set the garbage collection strategy (CCL only)

  [3mNote[0m: This macro has no effect unless the host Lisp is CCL.

    General Forms:

    (set-gc-strategy :egc)     ; the default: EGC is on, full GC is not delayed
    (set-gc-strategy :delay)   ; EGC is off, full GC is delayed
    (set-gc-strategy :current) ; same as replacing :current by the latest
                               ; strategy set (:egc or :delay)

    (set-gc-strategy strategy threshold)
                               ; Same as (set-gc-strategy strategy), but sets
                               ; threshold to the indicated number of bytes
                               ; (see below)

  Logically, [47m(set-gc-strategy op)[0m returns [47mop[0m.  But in some host Lisps
  (currently CCL only), it changes how garbage collection is invoked.
  Exactly how that is done is best understood by reading the ACL2
  source code, starting with [47mset-gc-strategy[0m.  Here we document what
  most users might want to know about this utility, assuming they are
  using CCL.  We defer discussion of the optional second argument,
  [47mthreshold[0m, to the end.

  Normally the default garbage collection strategy will probably be
  fine.  That default has the ephemeral garbage collector (EGC)
  enabled.  But in jobs that stress [47m[hons][0m, or perhaps memoization
  (see [memoize]) or [fast-alists], it might be useful to switch to a
  strategy that disables EGC but also significantly delays garbage
  collection.  To switch to that delaying strategy:

    (set-gc-strategy :delay)

  Then, you can return to the default strategy, re-enabling EGC and no
  longer causing delays in garbage collection, as follows.

    (set-gc-strategy :egc)

  It is also legal to invoke [47m(set-gc-strategy :current)[0m, which is
  equivalent to replacing [47m:current[0m by the current strategy; see
  [gc-strategy].

  If you want to change the gc-strategy during certification of a book,
  but not when including that book, you can place your call of
  [47mset-gc-strategy[0m inside [47m[value-triple][0m, for example as follows.

    (value-triple (set-gc-strategy :delay))

  The following variant causes the [gc-strategy] to be modified when
  including the book as well.

    (value-triple (set-gc-strategy :delay) :on-skip-proofs t)

  This capability might be extended to other host Lisps in the future,
  especially if ACL2 users provide suggestions for how to do so.

  Note that the default behavior can be changed to [47m:delay[0m at ACL2 build
  time, by setting [47mMake[0m variable [47mACL2_EGC_ON=nil[0m when building an
  ACL2 executable.


The [47mthreshold[0m argument

  When a second argument is supplied in a call of [47mset-gc-strategy[0m, it
  must be either [47mnil[0m, which is equivalent to supplying no second
  argument, or else a positive integer.  This positive integer will
  be the ``GC threshold'' number of bytes CCL will try to ensure are
  available before the next full garbage collection.  The default
  (i.e., the value used when the second argument is [47mnil[0m or is
  omitted) is the minimum of the following two values: 1/2 GB, and
  1/32 of physical memory (or 1/32 of 4 GB, if the physical memory
  cannot be determined).  (Technical note: The GC threshold is stored
  in raw Lisp variable [47m*gc-min-threshold*[0m.)")
 (SET-GUARD-CHECKING
  (GUARD)
  "Control checking [guard]s during execution of top-level forms

  Detailed comments about the arguments of this function may be found
  elsewhere: see [guard-evaluation-table].  Here we provide an
  introduction to the use of [47mset-guard-checking[0m.

  New users are encouraged to execute one of the following forms in
  order to avoid evaluation errors due to [guard]s:

    (set-guard-checking :none)
    (set-guard-checking nil)

  The former avoids all guard-checking on user-defined functions and
  should generally work fine for new users, the only drawback being
  efficiency loss on compute-intensive problems.  All settings other
  than [47m:none[0m check guards, but a value of [47mnil[0m allows evaluation to
  continue in the logic when guards fail (avoiding the raw Lisp
  definition in that case).

  You may put one of the above forms in the [47m\"acl2-customization.lsp\"[0m
  file in your current directory (see [cbd]) or your home directory;
  see [ACL2-customization].

  Note that [guard]s are not part of the ACL2 logic, and hence new
  users can completely ignore the notion of [guard] (and the rest of
  this documentation section after this paragraph!).  For example,
  [47m(car 3)[0m and [47mnil[0m can be proved equal in the ACL2 logic, as follows,
  even though the [guard] on [47m[car][0m requires its first argument to be
  a [47m[cons][0m pair or [47mnil[0m.

    (thm (equal (car 3) nil))

  Moreover, unless your functions or top-level forms call built-in ACL2
  functions that are defined in [47m:[0m[47m[program][0m mode, the following
  property will hold.

      Evaluation of [47m(set-guard-checking :none)[0m will allow evaluation of
      forms such as [47m(car 3)[0m to take place without error in the top
      level loop, not only when proving theorems.

  If you feel bold, then you may wish to read the rest of this
  documentation topic; also see [guard].

  See [guard-evaluation-table] for a succinct table, with associated
  discussion, that covers in detail the material presented in the
  rest of the present topic.

  The top-level ACL2 loop has a variable which controls which sense of
  execution is provided.  To turn ``[guard] checking on,'' by which
  we mean that [guard]s are checked at runtime, execute the top-level
  form [47m:set-guard-checking t[0m.  To allow guard violations, do
  [47m:set-guard-checking nil[0m, or do [47m:set-guard-checking :none[0m to turn
  off all guard-checking, so that raw Lisp definitions of
  user-defined functions are avoided unless their [guard] is [47mt[0m. The
  status of guard-checking is reflected in the [prompt].

    ACL2 !>

  means [guard] checking is on and

    ACL2 >

  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

    ACL2 !>(car 'abc)

  will signal an error, while

    ACL2 >(car 'abc)

  will return [47mnil[0m.

  We will return at the end of this documentation topic to discuss two
  other values, [47m:all[0m and [47m:nowarn[0m, for [47m:set-guard-checking[0m.  We also
  note that evaluation of built-in [47m:program[0m mode functions always
  takes place in raw Lisp.

  Whether [guard]s are checked during evaluation is independent of the
  [47m[default-defun-mode][0m.  We note this simply because it is easy to
  confuse ``[47m:[0m[47m[program][0m mode'' with ``evaluation in Common Lisp'' and
  thus with ``[guard] checking on;'' and it is easy to confuse
  ``[47m:[0m[47m[logic][0m mode'' with ``evaluation in the logic'' and with
  ``[guard] checking off.'' But the [47m[default-defun-mode][0m determines
  whether newly submitted definitions introduce programs or add
  logical axioms.  That mode is independent of whether evaluation
  checks [guard]s or not.  You can operate in [47m:[0m[47m[logic][0m mode with
  runtime [guard] checking on or off.  Analogously, you can operate
  in [47m:[0m[47m[program][0m mode with runtime [guard] checking on or off.

  For further discussion on evaluation and guards see
  [guards-and-evaluation], in particular the exception for safe-mode
  in the ``Aside'' there.  See [guard] for a general discussion of
  [guard]s.

  Now we fulfill our promise above to discuss two other values for
  [47m:set-guard-checking[0m:

    :set-guard-checking :nowarn
    :set-guard-checking :all

  The meaning of these values is perhaps best described by the
  following example provided by David Rager.

    ACL2 !>(defun my-test (expr)
             (declare (xargs :guard (true-listp expr)
                             :verify-guards nil))
             (if (atom expr)
                 expr
               (cons (my-test (car expr))
                     (my-test (cdr expr)))))

    The admission of MY-TEST 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 EXPR).  We could deduce no constraints on the type of MY-
    TEST.  However, in normalizing the definition we used primitive type
    reasoning.

    Summary
    Form:  ( DEFUN MY-TEST ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Warnings:  None
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
     MY-TEST
    ACL2 !>(my-test '(a b c))

    ACL2 Warning [Guards] in TOP-LEVEL:  Guard-checking will be inhibited
    on recursive calls of the executable-counterpart (i.e., in the ACL2
    logic) of MY-TEST.  To check guards on all recursive calls:
      (set-guard-checking :all)
    To leave behavior unchanged except for inhibiting this message:
      (set-guard-checking :nowarn)

    (A B C)
    ACL2 !>

  If you think about evaluation of [47m(my-test '(a b c))[0m, you will see
  that it leads to the recursive call [47m(my-test 'a)[0m, which one might
  expect to cause a guard violation since the symbol [47ma[0m is not a
  [47m[true-listp][0m.  However, as the warning above explains, we do not by
  default check guards on recursive calls.  The reason is efficiency
  --- imagine a simple definition with a guard that is slow to
  evaluate.  The values [47m:nowarn[0m and [47m:all[0m for [47m:set-guard-checking[0m have
  been introduced as ways of dealing with the above warning.  The
  value [47m:nowarn[0m simply turns off the warning above.  The value [47m:all[0m
  causes all guards to be checked, even on recursive calls and even
  on all calls of non-built-in [47m:[0m[47m[program][0m mode functions --- unless,
  of course, a call is made of a function whose guard has been
  verified (see [verify-guards]), where the arguments satisfy the
  guard, in which case the corresponding call is made in raw Lisp
  without subsidiary guard-checking.  We still say that
  ``guard-checking is on'' after [47m:set-guard-checking[0m is invoked with
  values [47mt[0m, [47m:nowarn[0m, and [47m:all[0m, otherwise (after value [47mnil[0m) we say
  ``guard-checking is off.

  For technical reasons, [47m:all[0m does not have its advertised effect in
  the case of built-in [47m:[0m[47m[program][0m-mode functions.  If you are
  interested in this technical detail, see the comment ``In the
  boot-strap world...'' in source function [47moneify-cltl-code[0m.

  We conclude with a remark about the use of [47m:set-guard-checking[0m for
  experimenting with ACL2 as a logic or as a programming language.
  If one views ACL2 as a logic, one may wish to use
  [47m:set-guard-checking :none[0m, while if instead one views ACL2 as a
  functional programming language, one may wish to use
  [47m:set-guard-checking :all[0m.  The following transcript illustrates
  this distinction by way of example.  Specifically, [47m(car 3)[0m is equal
  to [47mnil[0m in the ACL2 logic, but may be viewed as a programming error.
  The default of [47m:set-guard-checking t[0m is problematic for learning
  ACL2 using [47m:[0m[47m[program][0m mode functions, since one can get raw Lisp
  errors.  In the example below, the raw Lisp error occurs because
  [47mfoo[0m implicitly has a [guard] of [47mt[0m, hence [47m(foo 3)[0m is evaluated in
  raw Lisp, which leads to a raw Lisp call of c[(car 3)].

    ACL2 !>(defun foo (x)
             (declare (xargs :mode :program))
             (car x))

    Summary
    Form:  ( DEFUN FOO ...)
    Rules: NIL
    Warnings:  None
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
     FOO
    ACL2 !>(foo 3)
    Error: Attempt to take the car of 3 which is not listp.
      [condition type: TYPE-ERROR]

    Restart actions (select using :continue):
     0: Abort entirely from this (lisp) process.
    [Current process: Initial Lisp Listener]
    [1] ACL2(1): [RAW LISP] :pop
    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 >(foo 3)
    NIL
    ACL2 >:set-guard-checking :all

    Turning guard checking on, value :ALL.

    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 !>")
 (SET-GUARD-MSG
  (GUARD DEBUGGING)
  "Specify what is printed when a [guard] is violated

  This is an advanced feature that may require considerable
  understanding of ACL2 programming.  ACL2 provides default error
  messages for guard violations.  However, ACL2 also provides a
  [table], [47mguard-msg-table[0m, that allows custom error messages for
  guard-checking failures.  The macro [47mset-guard-msg[0m provides a
  convenient way to update this table.  The keys of the table are
  symbols, which can be expected to be function symbols or names of
  macros.  Each value is a (translated) [term] whose only free
  variables are [47mworld[0m, [47margs[0m, and [47mcoda[0m.  When guard-checking fails,
  the term is evaluated to create a [3mmessage[0m suitable for \"[47m~@[0m\"
  formatted printing directives; see [fmt].  That evaluation is done
  with [47mworld[0m bound to the current ACL2 logical [world], with [47margs[0m
  bound to the actual parameters of the call, and with [47mcoda[0m bound to
  the message that would typically be printed by default at the end
  of a guard violation.  (See ACL2 source function
  [47mguard-er-message-coda[0m for details, or simply experiment.)


Example

  Consider the following example.

    (defun foo (x)
     (declare (xargs :mode :program :guard (consp x)))
     (car x))

    (set-guard-msg foo (msg \"An error for call ~x0.\"
                            (cons 'foo args)))

  Corresponding output for a guard violation is as follows.

    ACL2 !>(foo 3)


    ACL2 Error in TOP-LEVEL:  An error for call (FOO 3).

    ACL2 !>

  Continuing in the same session, suppose we provide this fancier error
  message specification.

    (set-guard-msg foo
                   (msg \"An error for call ~x0 in a world of length ~x1.~@2\"
                        (cons 'foo args)
                        (length world) ; length of the current ACL2 world
                        coda))

  The corresponding error is shown below.  Notice that the coda starts
  on a new line, with the same \"See :DOC ...\" message that one would
  see if the default error message were supplied for the same guard
  violation.

    ACL2 !>(foo 3)


    ACL2 Error in TOP-LEVEL:  An error for call (FOO 3) in a world of length
    98582.
    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 !>

  The capability shown above for function symbols is also available for
  macro names.  However, the variable, [47mcoda[0m, should not be used for
  macro names.")
 (SET-IGNORE-OK
  (DECLARE DEFUN)
  "Allow unused formals and locals without an [47mignore[0m or [47mignorable[0m
  declaration

    Examples:
    (set-ignore-ok t)
    (set-ignore-ok nil)
    (set-ignore-ok :warn)

  The first example above allows unused formals and locals, i.e.,
  variables that would normally have to be [declare]d [47mignore[0md or
  [47mignorable[0m.  The second example disallows unused formals and locals;
  this is the default.  The third example allows them, but prints an
  appropriate warning.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

    General Form:
    (set-ignore-ok flg)

  where [47mflg[0m is either [47mt[0m, [47mnil[0m, or [47m:warn[0m.

  One might find this event useful when one is generating function
  definitions by an automated procedure, when that procedure does not
  take care to make sure that all formals are actually used in the
  definitions that it generates.

  Note: Defun will continue to report irrelevant formals even if
  [47m:set-ignore-ok[0m has been set to [47mt[0m, unless you also use
  [47m[set-irrelevant-formals-ok][0m to instruct it otherwise.")
 (SET-IN-THEORY-REDUNDANT-OKP
  (REDUNDANT-EVENTS)
  "Allow [47m[in-theory][0m events to be redundant

  See [redundant-events] for discussion of the notion of redundant
  events.

    General Forms:
    (set-in-theory-redundant-okp nil) ; default
    (set-in-theory-redundant-okp t)   ; allow in-theory events to be redundant

  By default, [47m[in-theory][0m events are never redundant.  This behavior
  avoids a redundancy check that could be a bit expensive, as it
  would require computing the current theory and checking its
  equality to the new theory.  Evaluation of the event
  [47m(set-in-theory-redundant-okp t)[0m enables that redundancy check, so
  that when an [47min-theory[0m event computes a theory that is equal to the
  current theory, then that event is redundant.

  To see the current setting (i.e., the default of [47mnil[0m or else [47mt[0m after
  evaluation of [47m(set-in-theory-redundant-okp t)[0m), evaluate
  [47m(get-in-theory-redundant-okp state)[0m.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].")
 (SET-INDUCTION-DEPTH-LIMIT
  (INDUCTION-DEPTH-LIMIT)
  "Set the [induction-depth-limit]

    Examples:
    (set-induction-depth-limit 3)   ;; Set the induction depth limit to 3.
    (set-induction-depth-limit nil) ;; Remove the induction depth limit.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [set-induction-depth-limit!] for a corresponding
  non-[47m[local][0m event.

    General Form:
    (set-induction-depth-limit x)

  where [47mx[0m evaluates to a value that is a natural number or [47mnil[0m.  The
  induction-depth-limit is set to that value; see
  [induction-depth-limit].")
 (SET-INDUCTION-DEPTH-LIMIT!
  (INDUCTION)
  "Set the induction-depth-limit non-[47m[local][0mly

  Please see [set-induction-depth-limit], which is the same as
  [47mset-induction-depth-limit![0m except that the latter is not [47m[local][0m to
  the [47m[encapsulate][0m or the book in which it occurs.  Probably
  [47m[set-induction-depth-limit][0m is to be preferred unless you have a
  good reason for wanting to export the effect of this event outside
  the enclosing [47m[encapsulate][0m or book.")
 (SET-INHIBIT-ER
  (OUTPUT-CONTROLS ERRORS)
  "Control the error output

    Examples:
    (set-inhibit-er \"translate\" \"failure\")

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [set-inhibit-er!] for a corresponding non-[47m[local][0m
  event.  Indeed, [47m(set-inhibit-er ...)[0m is equivalent to [47m(local
  (set-inhibit-er! ...))[0m.

    General Form:
    (set-inhibit-er string1 string2 ...)

  where each string is considered without regard to case.  This macro
  is is essentially [47m(local (table inhibit-er-table nil 'alist
  :clear))[0m, where [47malist[0m pairs each supplied string with [47mnil[0m: that is,
  [47malist[0m is [47m(pairlis$ lst nil)[0m where [47mlst[0m is the list of strings
  supplied.  This macro is an event (see [table]), but no output
  results from a [47mset-inhibit-er[0m event.

  ACL2 prints errors that are generally important to see.  This utility
  is appropriate for situations where one prefers not to see all
  error messages.  Individual ``labeled'' error output can be
  silenced.  Consider for example

    ACL2 Error [Failure] in ( DEFUN FOO ...):  See :DOC failure.

  Here, the label is \"Failure\".  The argument list for [47mset-inhibit-er[0m
  is a list of such labels, each of which is a string.  Any error
  message is suppressed if its label is a member of this list, where
  case is ignored.  Thus, for example, the error output above will be
  avoided after a call of [47mset-inhibit-er[0m that contains the string,
  [47m\"Failure\"[0m (or any string that is [47m[string-equal][0m to [47m\"Failure\"[0m, such
  as [47m\"failure\"[0m or [47m\"FAILURE\"[0m).  In summary: the effect of this event
  is to suppress any error output whose label is a member of the
  given argument list, where case is ignored.

  At this time, many error messages are printed without a label, for
  example (as of this writing) the following.

    ACL2 !>(+ x 3)


    ACL2 Error in TOP-LEVEL:  Global variables, such as X, are not allowed.
    See :DOC ASSIGN and :DOC @.

    ACL2 !>

  These can only be suppressed by turning off all error output; see
  [set-inhibit-output-lst].  Feel free to ask the ACL2 implementors
  to add labels; for example, you might ask for a label in the
  example above (which could be [47m\"Globals\"[0m or [47m\"Global-variables\"[0m).

  Note that [47mset-inhibit-er[0m has no effect on the value(s) returned by an
  expression (excepting the ACL2 [state] since it formally includes
  output).

  The list of currently inhibited error types is the list of keys in
  the [table] named [47minhibit-er-table[0m.  (The values in the table are
  irrelevant.)  One way to get that value is to get the result from
  evaluating the following form: [47m(table-alist 'inhibit-er-table (w
  state))[0m.  Of course, if error output is inhibited overall --- see
  [set-inhibit-output-lst] --- then this value is entirely
  irrelevant.

  See [47m[toggle-inhibit-er][0m for a way to add or remove a single string.")
 (SET-INHIBIT-ER!
  (OUTPUT-CONTROLS ERRORS)
  "Control error output non-[47m[local][0mly

  Please see [set-inhibit-er], which is the same as [47mset-inhibit-er![0m
  except that the latter is not [47m[local][0m to the [47m[encapsulate][0m or the
  book in which it occurs.  Probably [set-inhibit-er] is to be
  preferred unless you have a good reason for wanting to export the
  effect of this event outside the enclosing [47m[encapsulate][0m or book.")
 (SET-INHIBIT-OUTPUT-LST
  (OUTPUT-CONTROLS)
  "Control output

    Examples:
    (set-inhibit-output-lst '(warning))
    (set-inhibit-output-lst '(proof-tree prove proof-builder))
    (set-inhibit-output-lst *valid-output-names*) ; inhibit all prover output
    :set-inhibit-output-lst (proof-tree prove)

    General Form:
    (set-inhibit-output-lst x)

  where [47mx[0m is a form (which may mention [47m[state][0m) that evaluates to a
  list of names, each of which is the name of one of the following
  ``kinds'' of output produced by ACL2.

    error          error messages (but for hard errors, see below)
    warning        warnings other than those related to soundness
    warning!       warnings (of all degrees of importance)
    observation    observations
    prove          commentary produced by the theorem prover
    proof-builder  commentary produced by the interactive proof-builder
    event          non-proof commentary produced by events such as defun
                   and encapsulate
    history        output from history commands such as :ubt and :pbt
    summary        the summary at the successful conclusion of an event
    proof-tree     proof-tree output
    comment        output from cw, cw!, and utilities like time$ that use them

  It is possible to inhibit each kind of output by putting the
  corresponding name into [47mx[0m.  For example, if [47m'warning[0m is included in
  (the value of) [47mx[0m, then no warnings are printed except those related
  to soundness, e.g., the inclusion of an uncertified book.  Note
  that [proof-tree] output is affected by [47mset-inhibit-output-lst[0m; see
  [proof-tree].

  Note that proof output can be controlled without inhibiting it using
  this utility, and indeed is already quite limited by default.  See
  [47m[set-gag-mode][0m.

  See [with-output] for a variant of this utility that can be used in
  [books].  Also see [set-inhibit-warnings] and [set-inhibit-er] for
  how to inhibit individual warning and error output types,
  respectively, and see [set-inhibited-summary-types] for how to
  inhibit individual parts of the [summary].

  Printing of events on behalf of [47m[certify-book][0m and [47m[encapsulate][0m is
  inhibited when both [47m'event[0m and [47m'prove[0m belong to the value of the
  input.  Otherwise, printing of events is controlled by the [47m[ld][0m
  special [47m[ld-pre-eval-print][0m.

  Normally, hard error messages (see [er]) are not inhibited.  To
  inhibit those as well when [47mERROR[0m output is inhibited: [47m(assign
  inhibit-er-hard t)[0m.  To restore the original behavior: [47m(assign
  inhibit-er-hard nil)[0m.

  To get the current of names representing kinds of inhibit output,
  evaluate [47m(@ inhibit-output-lst)[0m.

  [3mNote for advanced users.[0m By including [47mwarning![0m in the value of the
  input, you are automatically including [47mwarning[0m as well: all
  warnings will be inhibited.  This is not the case if you modify
  value of state global variable [47m'inhibit-output-lst[0m directly (with
  [47m[assign][0m or [47mf-put-global[0m); then, if you include [47mwarning![0m but not
  [47mwarning[0m, then warnings not related to soundness will still be
  printed (which is probably not what was intended).")
 (SET-INHIBIT-WARNINGS
  (OUTPUT-CONTROLS)
  "Control warnings

    Examples:
    (set-inhibit-warnings \"theory\" \"use\")

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [set-inhibit-warnings!] for a corresponding
  non-[47m[local][0m event.  Indeed, [47m(set-inhibit-warnings ...)[0m is
  equivalent to [47m(local (set-inhibit-warnings! ...))[0m.

    General Form:
    (set-inhibit-warnings string1 string2 ...)

  where each string is considered without regard to case.  This macro
  is is essentially [47m(local (table inhibit-warnings-table nil 'alist
  :clear))[0m, where [47malist[0m pairs each supplied string with [47mnil[0m: that is,
  [47malist[0m is [47m(pairlis$ lst nil)[0m where [47mlst[0m is the list of strings
  supplied.  This macro is an event (see [table]), but no output
  results from a [47mset-inhibit-warnings[0m event.

  ACL2 prints warnings that may, from time to time, seem excessive to
  experienced users.  Each warning is ``labeled'' with a string
  identifying the type of warning.  Consider for example

    ACL2 Warning [Use] in ( THM ...):  It is unusual to :USE ....

  Here, the label is \"Use\".  The argument list for [47mset-inhibit-warnings[0m
  is a list of such labels, each of which is a string.  Any warning
  is suppressed if its label is a member of this list, where case is
  ignored.  Thus, for example, the warning above will not be printed
  after a call of [47mset-inhibit-warnings[0m that contains the string,
  [47m\"Use\"[0m (or any string that is [47m[string-equal][0m to [47m\"Use\"[0m, such as [47m\"use\"[0m
  or [47m\"USE\"[0m).  In summary: the effect of this event is to suppress any
  warning whose label is a member of the given argument list, where
  case is ignored.

  The list of currently inhibited warnings is the list of keys in the
  [table] named [47minhibit-warnings-table[0m.  (The values in the table are
  irrelevant.)  One way to get that value is to get the result from
  evaluating the following form: [47m(table-alist 'inhibit-warnings-table
  (w state))[0m.  Of course, if warnings are inhibited overall --- see
  [set-inhibit-output-lst] --- then this value is entirely
  irrelevant.

  See [47m[toggle-inhibit-warning][0m for a way to add or remove a single
  warning string.")
 (SET-INHIBIT-WARNINGS!
  (OUTPUT-CONTROLS)
  "Control warnings non-[47m[local][0mly

  Please see [set-inhibit-warnings], which is the same as
  [47mset-inhibit-warnings![0m except that the latter is not [47m[local][0m to the
  [47m[encapsulate][0m or the book in which it occurs.  Probably
  [set-inhibit-warnings] is to be preferred unless you have a good
  reason for wanting to export the effect of this event outside the
  enclosing [47m[encapsulate][0m or book.")
 (SET-INHIBITED-SUMMARY-TYPES
  (OUTPUT-CONTROLS)
  "Control which parts of the [summary] are printed

    Example:
    (set-inhibited-summary-types '(rules time))

  Note: This is not an event.  Rather, it changes the [state], in
  analogy to [47m[set-inhibit-output-lst][0m.

    General Form:
    (set-inhibited-summary-types form)

  where form evaluates to a true-list of symbols, each of which is
  among the values of the constant [47m*summary-types*[0m, which is [47m(errors
  form header hint-events redundant rules splitter-rules steps
  system-attachments time value warnings)[0m.  Each specified type
  inhibits printing of the corresponding portion of the summaries
  printed at the conclusions of [events], where [47mheader[0m refers to an
  initial newline followed by the line containing just the word
  [47mSummary[0m.

  Note the distinction between [47mrules[0m and [47mhint-events[0m.  [47mRules[0m provides a
  record of automatic rule usage by the prover, while [47mhint-events[0m
  shows the names of events given to [47m:USE[0m or [47m:BY[0m [hints], as well as
  [clause-processor] functions given to [47m:CLAUSE-PROCESSOR[0m hints that
  have an effect on the proof.

  Also see [set-inhibit-output-lst].  Note that
  [47mset-inhibited-summary-types[0m has no effect when [47msummary[0m is one of
  the types inhibited by [set-inhibit-output-lst], because in that
  case none of the [summary] will be printed.

  To control summary types for a single event, see [with-output].")
 (SET-INVISIBLE-FNS-TABLE
  (LOOP-STOPPER)
  "Set the invisible functions table

    Examples:
    (set-invisible-fns-table ((binary-+ unary--)
                              (binary-* unary-/)
                              (unary-- unary--)
                              (unary-/ unary-/)))
    (set-invisible-fns-table t) ; restore original invisible-fns-table

  Among other things, the setting above has the effect of making
  [47m[unary--][0m ``invisible'' for the purposes of applying permutative
  [47m:[0m[47m[rewrite][0m rules to [47m[binary-+][0m trees.  Thus, [47marg[0m and [47m(unary-- arg)[0m
  will be given the same weight and will be permuted so as to be
  adjacent.  The form [47m(invisible-fns-table (w state))[0m returns the
  current value of the invisible functions table.

  Also see [add-invisible-fns] and see [remove-invisible-fns] for
  events that add to and remove from the invisible functions table,
  while accounting for macro aliases (see [macro-aliases-table]).

    General Form:
    (set-invisible-fns-table alist)

  where [47malist[0m is either [47mt[0m or a true list of pairs, each element of
  which is of the form [47m(fn ufn1 ... ufnk)[0m, where [47mfn[0m is a function
  symbol and each [47mufni[0m is a unary function symbol.  When alist is [47mt[0m,
  the initial value of this table is used in its place.  Modulo the
  replacement of [47malist[0m by the default setting when [47malist[0m is [47mt[0m, this
  macro is equivalent to

    (table invisible-fns-table nil 'alist :clear)

  which is also an event (see [table]).

  Note that [47mset-invisible-fns-table[0m does not evaluate its argument.
  However, you can call [47m[table][0m directly for that purpose.  For
  example,

    (set-invisible-fns-table ((binary-+ unary--)
                              (binary-* unary-/)
                              (unary-- unary--)
                              (unary-/ unary-/)))

  ie equivalent to the following; see [table].

    (table invisible-fns-table nil
           (quote ((binary-+ unary--)
                   (binary-* unary-/)
                   (unary-- unary--)
                   (unary-/ unary-/)))
           :clear)

  See [invisible-fns-table] for a description of the invisible
  functions table.")
 (SET-IPRINT
  (IO)
  "Control whether abbreviated output can be read back in

  The following log may be sufficient for you to see how to use
  [47mset-iprint[0m; more explanation is below.  The example is taken from a
  session that used the [break-rewrite] utility, but familiarity with
  that utility is not necessary in order to understand this example.
  What it shows is that the form [47m(set-iprint t)[0m allows you to
  recover, using [without-evisc], output that had been hidden.  (See
  [break-rewrite] for more about the interaction of [47mbreak-rewrite[0m
  with iprinting.)

    ACL2 !>(thm (p y))

    (1 Breaking (:REWRITE AX) on (P Y):
    1 ACL2 >:eval

    1x (:REWRITE AX) failed because :HYP 1 rewrote to
    (EQUAL Y '(NIL NIL NIL NIL ...)).

    1 ACL2 >:a!
    Abort to ACL2 top-level
    Here is the current pstack [see :DOC pstack]:
    (REWRITE-ATM SIMPLIFY-CLAUSE WATERFALL)

    *** Note: No checkpoints to print. ***

    ACL2 Version 6.4.  Level 1.  Cbd \"u/smith/\".
    System books directory \"/u/smith/acl2/v6-4/books/\".
    Type :help for help.
    Type (good-bye) to quit completely out of ACL2.

    ACL2 !>(set-iprint t)

    ACL2 Observation in SET-IPRINT:  Iprinting has been enabled.
    ACL2 !>(thm (p y))

    (1 Breaking (:REWRITE AX) on (P Y):
    1 ACL2 >:eval

    1x (:REWRITE AX) failed because :HYP 1 rewrote to
    (EQUAL Y '(NIL NIL NIL NIL . #@2#)).

    1 ACL2 >(without-evisc '(EQUAL Y '(NIL NIL NIL NIL . #@2#)))
    (EQUAL Y
           '(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
                 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
                 NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL
                 NIL NIL NIL NIL NIL NIL NIL NIL NIL))
    1 ACL2 >

  This concludes the introductory example.

  When ACL2 pretty-prints large expressions using formatted printing
  (see [fmt]), it may save time and space by printing tokens `[47m#[0m' or
  `[47m...[0m' in place of certain subexpressions.  By default this only
  happens for a few settings such as error and warning messages; see
  [set-evisc-tuple] for controlling such elision in general.  The
  full expression is unavailable to the user when `[47m#[0m' or `[47m...[0m' is
  printed, but that is easily solved by evaluating the form

    (set-iprint t)

  to enable a mode called ``iprinting''.  Then, instead of printing `[47m#[0m'
  or `[47m...[0m', ACL2 prints `[47m#@i#[0m' for [47mi[0m = 1,2,3,... --- all in base 10.
  ACL2 can read back in such `[47m#@i#[0m' because under the hood, [47mi[0m is
  associated with its corresponding elided form.  Thus the term
  ``iprint'' can be viewed as suggesting ``interactive print'' or
  ``index print''.  We also think of ``iprint'' as suggesting ``[47mi[0m
  printing'', to suggest the printing of token `[47m#@i#[0m'.  We call [47mi[0m the
  ``iprint index'' of that token.

  The following example should suffice to illustrate how to recover
  elided subexpressions.  (Below this example we provide details that
  may be of interest only to advanced users.)  Here we cause an error
  by defining a macro of one argument and then calling it with two
  arguments.  By default, error messages abbreviate subexpressions
  deeper than level 5 with `[47m#[0m' and past the 7th element of a list
  with `[47m...[0m'.  We see this behavior below.

    ACL2 !>(defmacro foo (x) x)

    Summary
    Form:  ( DEFMACRO FOO ...)
    Rules: NIL
    Warnings:  None
    Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
     FOO
    ACL2 !>(foo arg1 (a (b (c (d (e (f (g)))))) h i j k l m n))

    ACL2 Error in macro expansion:  Wrong number of args in macro expansion
    of (FOO ARG1 (A (B (C (D #))) H I J K L ...)).  (See :DOC set-iprint
    to be able to see elided values in this message.)

    ACL2 !>(set-iprint t)

    ACL2 Observation in SET-IPRINT:  Iprinting has been enabled.
    ACL2 !>(foo arg1 (a (b (c (d (e (f (g)))))) h i j k l m n))

    ACL2 Error in macro expansion:  Wrong number of args in macro expansion
    of (FOO ARG1 (A (B (C (D #@1#))) H I J K L . #@2#)).

    ACL2 !>(acl2-count '(FOO ARG1 (A (B (C (D #@1#))) H I J K L . #@2#)))
    23
    ACL2 !>

  Sometimes you may want to supply the abbreviated form not to compute
  with it, as in the [47m[ACL2-count][0m example just above, but so that you
  can see it.  The macro [47m[without-evisc][0m eliminates elision during
  printing.  Below we show two ways to use this utility: first, we
  use it to print the elided form, and then, we use it instead on the
  original input form to print the entire error message.

    ACL2 !>(without-evisc '(FOO ARG1 (A (B (C (D #@1#))) H I J K L . #@2#)))
    (FOO ARG1
         (A (B (C (D (E (F (G))))))
            H I J K L M N))
    ACL2 !>(without-evisc (foo arg1 (a (b (c (d (e (f (g)))))) h i j k l m n)))

    ACL2 Error in macro expansion:  Wrong number of args in macro expansion
    of (FOO ARG1 (A (B (C (D (E (F (G)))))) H I J K L M N)).

    ACL2 !>

  If you wish to know which elided expressions are equal, you may call
  [47mset-iprint[0m with non-[47mnil[0m value for keyword argument [47m:share[0m.  That
  will turn on [3miprint sharing[0m, which causes behavior as shown below:
  the value printed shows the iprint index 2 being used twice for the
  list [47m(C D E F)[0m.

    ACL2 !>'((a b c d e f) (a b c d e f) (a b c d e f))
    ((A B . #@2#) (A B . #@2#) . #@3#)
    ACL2 !>

  We use the log displayed below to explain iprint sharing a bit more.
  The Warning below is pointing out that previous iprint indices are
  no longer valid; we are starting over.  The first Observation
  points out that iprint sharing is on, and gives the name
  [47m:IPRINT-FAL[0m to look for in [47m(fast-alist-summary)[0m in case you want
  information on the [fast-alist] that associates values with
  corresponding iprint indices.  To see the relevance of a
  fast-alist, note that the two elided occurrences of the list [47m(C D E
  F)[0m were originally not the identical list in memory; to make them
  identical, [47m[hons-copy][0m is applied to each to get the same list in
  memory, which is the one associated with iprint index 2 in a
  fast-alist named [47m:IPRINT-FAL[0m.

    ACL2 !>(set-iprint t :share t)

    ACL2 Warning [Iprint] in SET-IPRINT:  Converting SET-IPRINT action
    from T to :RESET-ENABLE, as required by use of keyword :SHARE or :HARD-
    BOUND.  See :DOC set-iprint.


    ACL2 Observation in SET-IPRINT:  Iprinting is enabled with sharing,
    with a fast-alist whose name is :IPRINT-FAL.

    ACL2 Observation in SET-IPRINT:  Iprinting has been reset and enabled.
    ACL2 !>(set-evisc-tuple (evisc-tuple 2 2 nil nil) :sites :all)
     (:TERM :LD . #@1#)
    ACL2 !>'((a b c d e f) (a b c d e f) (a b c d e f))
    ((A B . #@2#) (A B . #@2#) . #@3#)
    ACL2 !>'(b c d e f)
    (B C . #@4#)
    ACL2 !>

  One might have expected the last form printed above to take advantage
  of the fact that the tail [47m(C D E F)[0m of the input's value is already
  associated with iprint index 2.  If you want that sort of behavior
  --- that is, where we use an existing iprint index even when we
  have not yet reached the print-level or print-depth specified by
  our most recent call of [47m[set-evisc-tuple][0m --- then we can use the
  special value [47m:eager[0m for keyword [47m:share[0m, which gives us [3meager
  iprinting[0m:

    (set-iprint t :share :eager)

  If we use that call of [47mset-iprint[0m instead of our earlier one above
  (that is, with [47m:share t[0m), then the first of the two last results
  from the log above is unchanged, but in the second result, the tail
  [47m(C D E F)[0m is indeed abbreviated using iprint index 2.

    ACL2 !>'((a b c d e f) (a b c d e f) (a b c d e f))
    ((A B . #@2#) (A B . #@2#) . #@3#)
    ACL2 !>'(b c d e f)
    (B . #@2#)
    ACL2 !>

  The documentation above probably suffices for most users.  For those
  who want more details, below we detail all the ways to use the
  [47mset-iprint[0m utility.

    Example Forms:
    (set-iprint t)   ; enable iprinting (elision with #@i@)
    (set-iprint nil) ; disable iprinting

    General Form:
    (set-iprint action          ; t, nil, :reset, :reset-enable, or :same
                :share      sym ; initially nil
                :soft-bound s   ; initially  1000
                :hard-bound h   ; initially 10000)

  where all arguments are optional, but ACL2 queries for [47maction[0m if it
  is omitted.  All arguments are evaluated.  When a keyword argument
  is omitted, there is no change in the behavior that it controls.
  For now we defer further explanations of the keyword arguments.
  The values for [47maction[0m are as follows.

      [47mt[0m --- Enable iprinting.  If either keyword [47m:share[0m or [47m:hard-bound[0m is
      supplied, then [47mt[0m is converted to [47m:reset-enable[0m.

      [47mnil[0m --- Disable iprinting.  If either keyword [47m:share[0m or [47m:hard-bound[0m
      is supplied, then [47mnil[0m is converted to [47m:reset[0m.  Otherwise, if
      the next call of [47mset-iprint[0m is with a first argument of [47mt[0m, then
      iprint indices will start at the next available value rather
      than going back to 1.

      [47m:reset[0m --- Reset iprinting to its initial disabled state, so that
      when enabled, the first index [47mi[0m for which `[47m#@i#[0m is printed will
      be 1.  Note that all stored information for existing iprint
      indices will be erased.

      [47m:reset-enable[0m --- Reset iprinting as with [47m:reset[0m, and then enable
      iprinting.

      [47m:same[0m --- If either keyword [47m:share[0m or [47m:hard-bound[0m is supplied, then
      [47m:same[0m is converted to [47m:reset[0m or [47m:reset-enable[0m according to
      whether iprinting is currently disabled or enabled,
      respectively.  Otherwise, make no change to the iprinting state
      other than setting the [47msoft-bound[0m if specified, as explained
      below.

  The value of [47m:share[0m must be a symbol, with default [47mnil[0m.  If the value
  is [47mnil[0m, then an elided value will be printed using the next
  available iprint index.  The value [47m:same[0m is treated as though
  [47m:share[0m had not been supplied.  Otherwise, iprint sharing is on,
  which provides the following behavior.  Suppose that a value [47mV[0m is
  to be elided that would be assigned the next available iprint
  index, [47mN[0m.  If an iprint index [47mI < N[0m is already associated with a
  value equal to [47mV[0m, then ACL2 will print [47m#@I[0m for [47mV[0m instead of [47m#@N[0m.
  Thus, [47mN[0m will remain the next available iprint index.  This behavior
  is implemented using a [fast-alist] that associates values with
  indices; in our example, the [47m[hons-copy][0m of [47mV[0m is associated with [47mI[0m.
  If the value of [47m:share[0m is [47mt[0m then the name of this fast-alist ---
  that is, its initial value --- is [47m:iprint-fal[0m; otherwise, the value
  of [47m:share[0m (other than [47mnil[0m or [47m:same[0m) is its name.  This name is
  useful when viewing the output of [47m[fast-alist-summary][0m.  Finally, a
  special case, called ``eager sharing'', is installed if the value
  of [47m:share[0m is [47m:eager[0m.  In that case, the behavior described above
  --- where [47m#@I[0m is printed for [47mV[0m --- will occur even if the value [47mV[0m
  would otherwise not be elided, provided the most recent call of
  [47m[set-evisc-tuple][0m specified a non-[47mnil[0m print-level or print-length.

  Immediately after a top-level form is read, hence before it is
  evaluated, a check is made for whether the latest iprint index
  exceeds a certain bound, [47m(iprint-soft-bound state)[0m --- 1000, by
  default.  If so, then the [47m(iprint-last-index state)[0m is set back to
  0 so that the next iprint index that is generated will be 1.  This
  soft bound can be changed to any positive integer [47mk[0m by calling
  [47mset-iprint[0m with [47m:soft-bound k[0m, for example: [47m(set-iprint :same
  :soft-bound k[0m)].

  The above ``soft bound'' is applied once for each top-level form, but
  you may want finer control by applying a bound after the
  pretty-printing of each individual form (since many forms may be
  pretty-printed between successive evaluations of top-level forms).
  That bound is [47m(iprint-hard-bound state)[0m, and can be set with the
  [47m:hard-bound[0m argument in analogy to how [47m:soft-bound[0m is set, as
  described above, but with the effect of resetting iprinting, with
  [47m(iprint-last-index state)[0m set back to 0.

  A ``rollover'' is the detection that the soft or hard bound has been
  exceeded, along with a state update setting [47m(iprint-last-index
  state)[0m to 0 so that the next iprint index will be 1.  Immediately
  before a rollover, any index beyond the last iprint index used
  (which must be from before an earlier rollover) is no longer
  available for reading.  At the top level of the ACL2
  read-eval-print loop, this works as follows: ACL2 reads the next
  top-level form according to the current iprint state, then handles
  a rollover if the latest iprint index exceeded the current soft
  bound.  The following log illustrates a rollover, which follows the
  description above.

    ACL2 !>(set-iprint t :soft-bound 3)

    ACL2 Observation in SET-IPRINT:  The soft-bound for iprinting has been
    set to 3.

    ACL2 Observation in SET-IPRINT:  Iprinting has been enabled.
    ACL2 !>(set-evisc-tuple (evisc-tuple 2 3 nil nil) :sites :ld)
     (:LD)
    ACL2 !>'((a b c d e f g) (a b c d e f g) (a b c d e f g))
    ((A B C . #@1#) (A B C . #@2#) (A B C . #@3#))
    ACL2 !>'((a b c d e f g) (a b c d e f g) (a b c d e f g))
    ((A B C . #@4#) (A B C . #@5#) (A B C . #@6#))
    ACL2 !>(without-evisc '((A B C . #@4#) (A B C . #@5#) (A B C . #@6#)))
    ((A B C D E F G)
     (A B C D E F G)
     (A B C D E F G))
    ACL2 !>'(1 2 3 4 5)
    (1 2 3 . #@1#)
    ACL2 !>'((a b c d e f g) (a b c d e f g) (a b c d e f g))
    ((A B C . #@2#) (A B C . #@3#) (A B C . #@4#))
    ACL2 !>(without-evisc '((A B C . #@4#) (A B C . #@5#) (A B C . #@6#)))
    ((A B C D E F G)
     (A B C D E F G)
     (A B C D E F G))
    ACL2 !>(without-evisc '((A B C . #@4#) (A B C . #@5#) (A B C . #@6#)))

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Out-of-bounds index in #@5#.  See :DOC set-iprint.
    ***********************************************

    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)
    ACL2 !>

  Rollover has the following additional effect when iprint sharing is
  on: it is illegal to read a form that has both an index from before
  the rollover and an index from after the rollover.  The following
  log illustrates this requirement.  Note that if the last input form
  below were read without error, the result would likely be highly
  confusing, since iprint index 1 no longer refers to the value it
  was originally given at the time the other iprint indices in the
  input (2, 3, and 4) were given their values.

    ACL2 !>(set-iprint t :soft-bound 3 :share t)

    ACL2 Warning [Iprint] in SET-IPRINT:  Converting SET-IPRINT action
    from T to :RESET-ENABLE, as required by use of keyword :SHARE or :HARD-
    BOUND.  See :DOC set-iprint.


    ACL2 Observation in SET-IPRINT:  The soft-bound for iprinting has been
    set to 3.

    ACL2 Observation in SET-IPRINT:  Iprinting is enabled with sharing,
    with a fast-alist whose name is :IPRINT-FAL.

    ACL2 Observation in SET-IPRINT:  Iprinting has been reset and enabled.
    ACL2 !>(set-evisc-tuple (evisc-tuple 2 3 nil nil) :sites :ld)
     (:LD)
    ACL2 !>'((a b c d) (x y z w))
    ((A B C . #@1#) (X Y Z . #@2#))
    ACL2 !>'((e f g h) (k l m n))
    ((E F G . #@3#) (K L M . #@4#))
    ACL2 !>'(#@1# #@2# #@3# #@4#) ; OK, since rollover occurs after the read
    ((D) (W) (H) . #@1#)
    ACL2 !>'(#@1# #@2# #@3# #@4#)

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Attempt to read a form containing both an index
    created before the most recent rollover (#@2#) and
    an index created after that rollover (#@1#).  See :DOC set-iprint.
    ***********************************************

    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)
    ACL2 !>

  We conclude by mentioning two cases where iprinting and evisc-tuples
  are ignored.  (1) This is typically the case when printing results
  in raw Lisp outside the ACL2 loop.  To use iprinting and
  evisc-tuples in raw Lisp, use raw-mode; see [set-raw-mode].  In
  raw-mode, results that are ACL2 objects will be printed in the same
  way that ACL2 would print those results if not in raw-mode.  (2)
  Iprinting and evisc-tuples are ignored by [47m[print-object$][0m, which
  however is sensitive to many settings that do not affect formatted
  ([47m[fmt][0m etc.) printing; see [print-control].

  The reader interested in design and implementation issues considered
  during the addition of iprinting to ACL2 is invited to read the
  paper ``Abbreviated Output for Input in ACL2: An Implementation
  Case Study''; see the {proceedings of ACL2 Workshop 2009 |
  http://www.cs.utexas.edu/users/moore/acl2/workshop-2009/}.")
 (SET-IRRELEVANT-FORMALS-OK
  (DECLARE DEFUN)
  "Allow irrelevant formals in definitions

    Examples:
    (set-irrelevant-formals-ok t)
    (set-irrelevant-formals-ok nil)
    (set-irrelevant-formals-ok :warn)

  The first example above allows irrelevant formals in definitions; see
  [irrelevant-formals].  The second example disallows irrelevant
  formals; this is the default.  The third example allows irrelevant
  formals, but prints an appropriate warning.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

    General Form:
    (set-irrelevant-formals-ok flg)

  where [47mflg[0m is either [47mt[0m, [47mnil[0m, or [47m:warn[0m.

  For a way to permit irrelevant formals in a specific definition, see
  [declare].")
 (SET-LD-ALWAYS-SKIP-TOP-LEVEL-LOCALS
      (POINTERS)
      "See [ld-always-skip-top-level-locals].")
 (SET-LD-ERROR-ACTION (POINTERS)
                      "See [ld-error-action].")
 (SET-LD-ERROR-TRIPLES (POINTERS)
                       "See [ld-error-triples].")
 (SET-LD-EVISC-TUPLE (POINTERS)
                     "See [ld-evisc-tuple].")
 (SET-LD-KEYWORD-ALIASES (POINTERS)
                         "See [ld-keyword-aliases].")
 (SET-LD-KEYWORD-ALIASES! (POINTERS)
                          "See [ld-keyword-aliases].")
 (SET-LD-MISSING-INPUT-OK (POINTERS)
                          "See [ld-missing-input-ok].")
 (SET-LD-POST-EVAL-PRINT (POINTERS)
                         "See [ld-post-eval-print].")
 (SET-LD-PRE-EVAL-FILTER (POINTERS)
                         "See [ld-pre-eval-filter].")
 (SET-LD-PRE-EVAL-PRINT (POINTERS)
                        "See [ld-pre-eval-print].")
 (SET-LD-PROMPT (POINTERS)
                "See [ld-prompt].")
 (SET-LD-QUERY-CONTROL-ALIST (POINTERS)
                             "See [ld-query-control-alist].")
 (SET-LD-REDEFINITION-ACTION (POINTERS)
                             "See [ld-redefinition-action].")
 (SET-LD-SKIP-PROOFS (POINTERS)
                     "See [ld-skip-proofsp].")
 (SET-LD-SKIP-PROOFSP (POINTERS)
                      "See [ld-skip-proofsp].")
 (SET-LD-USER-STOBJS-MODIFIED-WARNING (POINTERS)
                                      "See [user-stobjs-modified-warnings].")
 (SET-LD-VERBOSE (POINTERS)
                 "See [ld-verbose].")
 (SET-LET*-ABSTRACTION (POINTERS)
                       "See [set-let*-abstractionp].")
 (SET-LET*-ABSTRACTIONP
  (OUTPUT-CONTROLS)
  "To shorten many prettyprinted [clause]s

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

  When this flag is set to [47mt[0m, subterms that occur more than once in a
  [clause] are abstracted away with [47m[let*][0m, generally shortening the
  displayed size of the clauses.  This flag only affects how clauses
  are printed.  It does not change what terms the theorem prover
  manipulates.

    :set-let*-abstractionp t ;;; or, (set-let*-abstractionp t)

  will cause the prettyprinter to do ``let* abstraction'' on clauses
  before they are printed.  The algorithm finds the maximal
  multiply-occurring subterm and extracts it, binding it to some new
  variable and replacing its occurrences by that variable.  This
  produces a [47mlet*[0m form.  This process is iterated until no subterm
  occurs more than once.  This process generally takes a little time,
  but less time than to print large clauses.  The process can greatly
  reduce the amount of text produced by the prover.

  THIS ONLY AFFECTS HOW THE CLAUSES ARE PRINTED!  The unabstracted
  clauses are manipulated by the theorem prover.

    :set-let*-abstractionp nil

  restores normal clause printing.

  The mode is stored in the defaults table, See [ACL2-defaults-table].
  Thus, the mode may be set locally in books.")
 (SET-MATCH-FREE-DEFAULT
  (FREE-VARIABLES)
  "Provide default for [47m:match-free[0m in future rules

    General Forms:
    (set-match-free-default :once)
    (set-match-free-default :all)
    (set-match-free-default nil)

  Note: This utility does not apply to [type-prescription] rules; for a
  related topic pertinent to such rules, see
  [free-variables-type-prescription].

  As described elsewhere (see [free-variables]), a [rewrite], [linear],
  or [forward-chaining] rule may have free variables in its
  hypotheses, and ACL2 can be directed either to try all bindings
  (``[47m:all[0m'') or just the first (``[47m:once[0m'') when relieving that
  hypothesis, as a basis for relieving subsequent hypotheses.  This
  directing of [47m:all[0m or [47m:once[0m is generally provided by specifying
  either [47m:match-free :once[0m or [47m:match-free :all[0m in the [47m:[0m[47m[rule-classes][0m
  of the rule.  If neither of these is specified, then the most
  recent [47mset-match-free-default[0m is used by ACL2 to fill in this
  missing [47m:match-free[0m field.  See [rule-classes].  Except: If the
  last [47mset-match-free-default[0m specifies [47mnil[0m, then ACL2 reverts to the
  behavior it had at start-up, as described in Remarks (2) and (3)
  below.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It uses the [47m[ACL2-defaults-table][0m, and hence its effect
  is [47m[local][0m to the book or [47m[encapsulate][0m form in which it occurs.

  Remarks.

  (1) The use of [47mset-match-free-default[0m has no effect on existing
  rules.  In order to change the behavior of existing rules with
  respect to free-variable matching, see [add-match-free-override].

  (2) If you submit a [rewrite], [linear], or [forward-chaining] rule
  with a free variable in a hypothesis, and no default setting was
  previously specified with [47mset-match-free-default[0m or the default
  setting is [47mnil[0m, and the rule is not within a book being processed
  with [47m[include-book][0m, [47m[certify-book][0m, or [47m[rebuild][0m, then a warning
  or error is caused.  In order to make this an error instead of a
  warning, see [set-match-free-error].

  (3) If you submit a [rewrite], [linear], or [forward-chaining] rule
  with a free variable in a hypothesis, and no default setting has
  been previously specified with [47mset-match-free-default[0m or the
  default setting is [47mnil[0m, and no error is caused (see (2) above),
  then the default [47m:all[0m is used.")
 (SET-MATCH-FREE-ERROR
  (FREE-VARIABLES)
  "Control error vs. warning when [47m:match-free[0m is missing

    Legal Forms:
    (set-match-free-error nil)
    :set-match-free-error nil
    (set-match-free-error t)
    :set-match-free-error t

  As described elsewhere (see [free-variables]), when a [rewrite],
  [linear], or [forward-chaining] rule has free variables in its
  hypotheses, the user can specify whether to try all bindings
  (``[47m:all[0m'') or just the first (``[47m:once[0m'') when relieving its
  hypotheses, as a basis for relieving subsequent hypotheses.  This
  direction of [47m:all[0m or [47m:once[0m is generally provided by specifying
  either [3m:match-free :once[0m or [3m:match-free :all[0m in the [47m:[0m[47m[rule-classes][0m
  of the rule.

  But suppose that neither of these is specified for such a rule.
  (Note: [47mset-match-free-error[0m is not relevant for [type-prescription]
  rules.)  Also suppose that [47mset-match-free-default[0m has not specified
  a default of [47m:once[0m or [47m:all[0m (see [set-match-free-default]).  In this
  case a warning will occur except when in the context of
  [47m[include-book][0m.  If you prefer to see an error in such cases,
  except in the context of [47m[certify-book][0m, execute
  [47m(set-match-free-error t)[0m.  If there is no error, then a default of
  [47m:all[0m is used.

  Note: This is NOT an event!  Instead, [47mset-match-free-error[0m sets the
  state global [47m'match-free-error[0m (see [state] and see [assign]).
  Thus, this form cannot be put into a book.  If you are tempted to
  put it into a book, consider the fact that it really isn't needed
  there, since the absence of [47m:match-free[0m does not cause an error in
  the context of [47m[certify-book][0m or [47m[include-book][0m.  If you still feel
  the need for such a form, consider using [47mset-match-free-default[0m to
  provide a default, at least within the scope of the current book
  (if any); see [set-match-free-default].")
 (SET-MEASURE-FUNCTION
  (DEFUN)
  "Set the default measure function symbol

    Examples:
    (set-measure-function nqthm::count)

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

    General Form:
    (set-measure-function name)

  where [47mname[0m is a function symbol of one argument.  This macro is
  equivalent to [47m(table acl2-defaults-table :measure-function 'name)[0m,
  and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs; see [ACL2-defaults-table].  Although this is thus
  an event (see [table]), nevertheless no output results from a
  [47mset-measure-function[0m event.

  This event sets the default measure function to [47mname[0m.  Subsequently,
  if a recursively defined function is submitted to [47m[defun][0m with no
  explicitly given [47m:measure[0m argument, [47m[defun][0m ``guesses'' the measure
  [47m(name var)[0m, where [47mname[0m is the then current default measure function
  and [47mvar[0m is the first formal found to be tested along every branch
  and changed in every recursive call.

  Note that if [47m(table acl2-defaults-table :measure-function 'name)[0m has
  its default value of [47mnil[0m, then the default measure function is
  [47m[ACL2-count][0m.")
 (SET-NON-LINEAR (POINTERS)
                 "See [set-non-linearp].")
 (SET-NON-LINEARP
  (NON-LINEAR-ARITHMETIC)
  "To turn on or off non-linear arithmetic reasoning

    Examples:
    (set-non-linearp t)
    (set-non-linearp nil)

  See [non-linear-arithmetic].  This event is equivalent to [47m(table
  acl2-defaults-table :non-linearp <t-or-nil>)[0m, and hence is [47m[local][0m
  to any [books] and [47m[encapsulate][0m [events] in which it occurs; see
  [ACL2-defaults-table].

  The initial value is [47mnil[0m.")
 (SET-OVERRIDE-HINTS
  (OVERRIDE-HINTS)
  "Set the [override-hints]

  See [override-hints] for a discussion of override-hints.  Here we
  describe how to set them.  Note that the effects of
  [47mset-override-hints[0m [events] are [local] to the [books] or
  [47mencapsulate[0m [events] in which they reside; see
  [set-override-hints!] to avoid that restriction.  Also see
  [add-override-hints] to add to the list of override-hints, rather
  than setting a new list and ignoring the present list.

    General Form:
    (set-override-hints form)

  where [47mform[0m evaluates to a list of computed hint forms.  The effect of
  this event is to set the list of [override-hints] to the result of
  that evaluation.")
 (SET-OVERRIDE-HINTS!
  (OVERRIDE-HINTS)
  "Set the [override-hints] non-[local]ly

  [47mSet-override-hints![0m is the same as [47m[set-override-hints][0m, except that
  the former is not [local] to [books] or [47m[encapsulate][0m [events] in
  which it occurs.  See [set-override-hints]; also see
  [add-override-hints].")
 (SET-PARALLEL-EXECUTION
  (PARALLELISM)
  "For ACL2(p): enabling parallel execution for four parallelism
  primitives

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].
  See [parallelism-tutorial] for an introduction to parallel
  execution in ACL2.

    General Forms:
    (set-parallel-execution nil) ; default for images not built for parallelism
    (set-parallel-execution t)   ; default for images built for parallelism
    (set-parallel-execution :bogus-parallelism-ok)

  [47mSet-parallel-execution[0m takes an argument that specifies the enabling
  or disabling of [parallel] execution for the primitives [47m[pand][0m,
  [47m[por][0m, [47m[plet][0m, and [47m[pargs][0m (but not [47m[spec-mv-let][0m, whose parallel
  execution remains enabled).  However, without using [47m[top-level][0m,
  calls of parallelism primitives made explicitly in the ACL2
  top-level loop, as opposed to inside function bodies, will never
  cause parallel execution; see [parallelism-at-the-top-level].
  Parallel execution is determined by the value of the argument to
  [47mset-parallel-execution[0m, as follows.

  Value [47mt[0m:
  All parallelism primitives used in bodies of function definitions
  are given the opportunity to execute in parallel.  However, the use
  of parallelism primitives directly in the ACL2 top-level loop
  causes an error.

  Value [47m:bogus-parallelism-ok[0m:
  Parallel execution is enabled, as for value [47mt[0m.  However, the use of
  parallelism primitives directly in the ACL2 top-level loop does not
  cause an error, but rather, simply results in serial execution for
  these primitives.

  Value [47mnil[0m:
  All parallelism primitives degrade to their serial equivalents,
  including their calls made directly in the ACL2 top-level loop.
  Thus, uses of parallelism primitives do not in themselves cause
  errors.")
 (SET-PERSISTENT-WHS-AND-EPHEMERAL-WHS
  (WORMHOLE)
  "maintaining wormhole coherence

    General Form:
    (set-persistent-whs-and-ephemeral-whs name new-status state)

  where [47mname[0m is the name of a [47m[wormhole][0m other than one of the built-in
  ACL2 system wormholes, and [47mnew-status[0m is the desired status of the
  wormhole.  ACL2 insists that [47mname[0m be supplied as a [quote]d
  constant.  The constant [47m*protected-system-wormhole-names*[0m lists the
  names of the built-in wormholes and includes [47mbrr[0m (the
  [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and
  [47mfc-wormhole[0m (the name of the wormhole managing
  [forward-chaining-reports]), among others.

  [47mSet-persistent-whs-and-ephemeral-whs[0m moves [47mnew-status[0m into the
  wormhole's persistent-whs (the status stored outside of the ACL2
  state) and then executes [47m[sync-ephemeral-whs-with-persistent-whs][0m
  to re-establish coherence.  It returns a modified [47mstate[0m.

  See [wormhole-programming-tips] for some tips for using this
  function.")
 (SET-PRINT-BASE
  (IO ACL2-BUILT-INS)
  "Control radix in which numbers are printed

  Also see [47m[set-print-base-radix][0m for a nice combined use of
  [47mset-print-base[0m and [47m[set-print-radix][0m.

  By default, integers and ratios are printed in base 10.  ACL2 also
  supports printing in radix 2, 8, or 16 by calling set-print-base
  with the desired radix (base).

    (set-print-base 10 state) ; Default printing
    (set-print-base 16 state) ; Print integers and ratios in hex

  Here is a sample log.

    ACL2 !>(list 25 25/3)
    (25 25/3)
    ACL2 !>(set-print-base 16 state)
    <state>
    ACL2 !>(list 25 25/3)
    (19 19/3)
    ACL2 !>

  See [set-print-radix] for how to print the radix, for example,
  printing the decimal number 25 in print-base 16 as ``[47m#x25[0m'' rather
  than ``[47m25[0m''.  Also see [print-control] for other user-settable
  print controls.

  Note: ACL2 [events] and some other top-level commands (for example,
  [47m[thm][0m, [47m[verify][0m, and history commands such as [47m:[0m[47mpe[0m and [47m:[0m[47mpbt[0m) set the
  print base to 10 during their evaluation.  So [47m[set-print-base][0m has
  no effect while these forms are being processed.")
 (SET-PRINT-BASE-RADIX
  (IO ACL2-BUILT-INS)
  "Control radix in which numbers are printed and printing of the radix

  See [47m[set-print-base][0m and [47m[set-print-radix][0m for detailed discussions
  of those functions.  [47mSet-print-base-radix[0m combines their
  functionality by setting the base (as is done by [47m[set-print-base][0m),
  and then causing the radix to be printed (as is done by
  [47m[set-print-radix][0m) exactly when the specified radix is not 10.

  Here is a sample log.

    ACL2 !>(list 25 25/3)
    (25 25/3)
    ACL2 !>(set-print-base-radix 16 state)
    <state>
    ACL2 !>(list 25 25/3)
    (#x19 #x19/3)
    ACL2 !>(set-print-base-radix 10 state)
    <state>
    ACL2 !>(list 25 25/3)
    (25 25/3)
    ACL2 !>")
 (SET-PRINT-CASE
  (IO ACL2-BUILT-INS)
  "Control whether symbols are printed in upper case or in lower case

  By default, symbols are printed in upper case when vertical bars are
  not required, as specified by Common Lisp.  As with Common Lisp,
  ACL2 supports printing in a \"downcase\" mode, where symbols are
  printed in lower case.  Many printing functions (some details
  below) print characters in lower case for a symbol when the ACL2
  [state] global variable [47mprint-case[0m has value [47m:downcase[0m and vertical
  bars are not necessary for printing that symbol.  (Thus, this state
  global functions in complete analogy to the Common Lisp global
  [47m*print-case*[0m.)  The value [47mprint-case[0m is returned by [47m(print-case)[0m,
  and may be set using the function [47mset-print-case[0m as follows.

    (set-print-case :upcase   state) ; Default printing
    (set-print-case :downcase state) ; Print symbols in lower case when
                                     ; vertical bars are not required

  The ACL2 user can expect that the [47m:downcase[0m setting will have an
  effect for formatted output (see [fmt] and see [fms]) when the
  directives are [47m~x[0m, [47m~X[0m, [47m~y[0m, or [47m~Y[0m, for built-in functions [47mprinc$[0m and
  [47mprin1$[0m, and the [47mppr[0m family of functions, and [3mnot[0m for built-in
  function [47mprint-object$[0m.  For other printing functions, the effect
  of [47m:downcase[0m is unspecified.

  Also see [print-control] for other user-settable print controls.")
 (SET-PRINT-CIRCLE (POINTERS)
                   "See [print-control].")
 (SET-PRINT-CLAUSE-IDS
  (OUTPUT-CONTROLS)
  "Cause subgoal numbers to be printed when [47m'prove[0m output is inhibited

    General Forms:
    (set-print-clause-ids t)
    :set-print-clause-ids t
    (set-print-clause-ids nil)
    :set-print-clause-ids nil

  This command affects output from the theorem prover only when [47m'prove[0m
  output is inhibited (see [set-inhibit-output-lst]) or gag-mode is
  on (but in that case the [47m:goals[0m setting issues this command
  automatically; see [set-gag-mode]).  Calling this macro with value
  [47mt[0m as shown above will cause subsequent proof attempts with [47m'prove[0m
  output inhibited to print the subgoal number, so that you can see
  the progress of the proof; value [47mnil[0m reverts to the default
  behavior, where this is not the case.  On a related note, we point
  out that you can cause output to be saved for later display; see
  [pso] and see [pso!].

  If [47m'prove[0m output is inhibited or gag-mode is on, and if you issue
  [47m(set-print-clause-ids t)[0m (either explicitly or with [47m(set-gag-mode
  :goals)[0m), then you can restrict when subgoal numbers are printed.
  In the following example we restrict to subgoals that are no more
  than four inductions deep, no more than four casesplits deep, and
  no more than four single-subgoals deep.  For additional relevant
  explanation, see [clause-identifier] and see [defattach].

    (defun print-clause-id-okp-level-4 (cl-id)
      (declare (xargs :mode :logic :guard (clause-id-p cl-id)))
      (and (<= (length (access clause-id cl-id :pool-lst))
               4)
           (<= (length (access clause-id cl-id :case-lst))
               4)
           (<= (access clause-id cl-id :primes)
               4)))

    (defattach-system print-clause-id-okp print-clause-id-okp-level-4)")
 (SET-PRINT-ESCAPE (POINTERS)
                   "See [print-control].")
 (SET-PRINT-GV-DEFAULTS
  (PRINT-GV GUARD DEBUGGING)
  "Set default keyword values for [47m[print-gv][0m

    Example Forms:
    (set-print-gv-defaults :conjunct t)
    (set-print-gv-defaults :conjunct t :substitute t)
    (set-print-gv-defaults :conjunct t :substitute 20)
    (set-print-gv-defaults :evisc-tuple
                           (evisc-tuple 4   ; print-level
                                        5   ; print-length
                                        (world-evisceration-alist state nil)
                                        nil ; hiding-cars
                                        ))
    (set-print-gv-defaults :conjunct :restore
                           :substitute :restore
                           :evisc-tuple :restore)
    (set-print-gv-defaults)

    General Form:
    (set-print-gv-defaults :conjunct c
                           :substitute s
                           :evisc-tuple e)

  where any or all of [47mc[0m, [47ms[0m, and [47me[0m may be the keyword, [47m:restore[0m, and
  otherwise these are as for [47m[print-gv][0m.  These forms set the
  defaults for the corresponding keyword arguments of the [47mprint-gv[0m
  utility, where the value [47m:restore[0m restores the system defaults; see
  [print-gv].  Evaluation returns an [error-triple] whose value is an
  alist associating keywords with their current defaults.  In
  particular, the call [47m(set-print-gv-defaults)[0m simply returns an
  error-triple with that alist as the value, without changing any
  defaults.

  Thus, for example, if you submit the form

    (set-print-gv-defaults :substitute t
                           :conjunct t
                           :evisc-tuple (evisc-tuple 3 4 nil nil))

  then subsequently, if you submit the form [47m:print-gv[0m or [47m(print-gv[0m) it
  would be interpreted as follows.

    (print-gv :substitute t
              :conjunct t
              :evisc-tuple (evisc-tuple 3 4 nil nil))

  Of course, you can override your defaults, so that for example if you
  subsequently submit the form [47m(print-gv :substitute nil)[0m or the form
  [47m(print-gv :substitute nil :evisc-tuple (print-gv-evisc-tuple))[0m,
  these would be equivalent to submitting the following forms,
  respectively.

    (print-gv :substitute nil
              :conjunct t
              :evisc-tuple (evisc-tuple 3 4 nil nil))
    (print-gv :substitute nil
              :conjunct t
              :evisc-tuple (print-gv-evisc-tuple))")
 (SET-PRINT-LENGTH (POINTERS)
                   "See [print-control].")
 (SET-PRINT-LEVEL (POINTERS)
                  "See [print-control].")
 (SET-PRINT-LINES (POINTERS)
                  "See [print-control].")
 (SET-PRINT-RADIX
  (IO ACL2-BUILT-INS)
  "Control printing of the radix for numbers

  Also see [47m[set-print-base-radix][0m for a nice combined use of
  [47m[set-print-base][0m and [47mset-print-radix[0m.

  See [set-print-base] for background on how the print base affects the
  printing of numbers.  [47mset-print-radix[0m affects whether a radix
  indicated when a number is printed.  The radix is not indicated by
  default, or after evaluating [47m(set-print-radix nil state)[0m.  But if
  [47mset-print-radix[0m is called with a first argument that evaluates to a
  non[47mnil[0m value --- for example, [47m(set-print-radix t state)[0m --- then
  the radix is shown when printing.  (This behavior is consistent
  with the handling of Common Lisp global [47m*print-radix*[0m.)  The
  following log illustrates how this works.

    ACL2 !>(list 25 25/3)
    (25 25/3)
    ACL2 !>(set-print-base 16 state)
    <state>
    ACL2 !>(list 25 25/3)
    (19 19/3)
    ACL2 !>(set-print-radix t state)
    <state>
    ACL2 !>(list 25 25/3)
    (#x19 #x19/3)
    ACL2 !>(set-print-base 10 state)
    <state>
    ACL2 !>(list 25 25/3)
    (25. #10r25/3)
    ACL2 !>(set-print-radix nil state)
    <state>
    ACL2 !>(list 25 25/3)
    (25 25/3)
    ACL2 !>")
 (SET-PRINT-READABLY (POINTERS)
                     "See [print-control].")
 (SET-PRINT-RIGHT-MARGIN (POINTERS)
                         "See [print-control].")
 (SET-PROOFS-CO (POINTERS)
                "See [proofs-co].")
 (SET-PROVER-STEP-LIMIT
  (MISCELLANEOUS)
  "Sets the step-limit used by the ACL2 prover

  This event provides a way to limit the number of so-called ``prover
  steps'' permitted for an event.  See [with-prover-step-limit] for a
  way to specify the limit on prover steps for a single event, rather
  than globally.  For a related utility based on time instead of
  prover steps, see [with-prover-time-limit].  For examples of how
  step limits work, see the community book
  [47mbooks/misc/misc2/step-limits.lisp[0m.  For a utility that returns an
  indicator of the number of prover steps most recently taken, see
  [last-prover-steps].

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].

    Example Forms:
    (set-prover-step-limit *default-step-limit*) ; no limit on prover steps
    (set-prover-step-limit nil)   ; abbreviation for the form just above
    (set-prover-step-limit 10000) ; allow at most 10,000 prover steps per event

    General Form:
    (set-prover-step-limit expr)

  where [47mexpr[0m evaluates either to [47mnil[0m or else to a natural number not
  exceeding the value of [47m*default-step-limit*[0m.  If that value is [47mnil[0m
  or the value of [47m*default-step-limit*[0m, then no default limit is
  placed on the number of prover ``steps'' (see below) during
  processing of an event.  Otherwise, that value is the maximum
  number of prover steps permitted before an error occurs.

  This event specifies the limit on the number of ``steps'' counted by
  the ACL2 prover during processing of an event.  Currently, a step
  is counted for each call of the system functions [47mrewrite[0m and
  [47mexpand-abbreviations[0m.  However, the steps counted may change in
  future releases of ACL2, so users would probably be well served by
  avoiding the assumption that only the above two calls are counted
  as prover steps.

  Depending on the computer you are using, you may have less than a
  half-hour of time before the number of prover steps exceeds the
  maximum step-limit, which is one less than the value of
  [47m*default-step-limit*[0m.  Note however the exception stated above: if
  the ``limit'' is [47mnil[0m or is the value of [47m*default-step-limit*[0m, then
  no limit is imposed.

  There is at best a loose connection between the counting of steps and
  [47m[with-prover-time-limit][0m.  In particular, for a call of [47mmfc-rw[0m or
  any [47mmfc-[0m function (see [extended-metafunctions]), the steps taken
  during that call are forgotten when returning from that call.

  The limit is relevant for every event, as well as for calls of [47m[thm][0m
  and [47m[certify-book][0m --- and more generally, to any form that creates
  a ``summary context'' to print the usual event [summary].  The
  limit is also put in force when entering the interactive
  [proof-builder].  A call of [47mset-prover-step-limit[0m applies to each
  subsequent form unless the call of [47mset-prover-step-limit[0m is within
  a summary context, in which case its effect disappears when exiting
  that summary context.

  The limit applies to each event, not just ``atomic'' events.
  Consider the following example.

    (set-prover-step-limit 500)

    (encapsulate
      ()
      (defthm lemma-1 ; takes 380 steps
        (equal (append (append x y) z) (append x y z))
        :rule-classes nil)
      (defthm lemma-2 ; would take 319 steps
        (equal (len (append x y)) (+ (len x) (len y)))
        :rule-classes nil))

  The first [47m[defthm][0m event, [47mlemma-1[0m takes 380 steps (as of this
  writing), as shown in the [summary]:

    Prover steps counted:  380
    LEMMA-1

  The second [47m[defthm][0m event, [47mlemma-2[0m, takes 319 steps (as of this
  writing) when evaluated at the top level.  However, in the context
  above, 380 steps of the available 500 steps (from the
  [47mset-prover-step-limit[0m event above) have already been taken under
  the above [47m[encapsulate][0m event.  Thus, when the number of steps
  would exceed 120, the proof of [47mlemma-2[0m is aborted:

    ACL2 Error in STEP-LIMIT:  The prover step-limit, which is 120 in the
    current context, has been exceeded.  See :DOC set-prover-step-limit.

  The summary for [47mlemma-2[0m reflects that situation:

    Prover steps counted:  More than 120

  The summary for the [47m[encapsulate][0m event then indicates that the
  available steps for that event have also been exceeded:

    Prover steps counted:  More than 500

  The discussion above applies to any event that contains other events,
  hence applies similarly to [47m[progn][0m events.

  For those who use [47m[make-event][0m, we note that prover steps in the
  expansion phase similarly contribute to the total number of steps
  counted.  For example, suppose that the limit is 500 prover steps
  as above, and you submit [47m(make-event EXPR)[0m, where 300 prover steps
  take place during evaluation of [47mEXPR[0m, producing event [47mEV[0m.  Then
  evaluation of [47mEV[0m will cause an error if it takes more than 200
  prover steps.  This observation actually can be used to count
  prover steps for sequences of forms that are not all legal [47m[events][0m
  (see [embedded-event-form]), such as calls of [47m[thm][0m.  For example,
  a small built-in ACL2 test suite that includes [47m[thm][0m forms can be
  run by evaluating the form [47m(mini-proveall)[0m, and the steps can be
  counted as shown below.  (Here we assume a fresh ACL2 session; an
  error would occur if first, we evaluate the event
  [47m(set-prover-step-limit 500)[0m displayed above.)

    ACL2 !>(make-event (er-progn (mini-proveall) (value '(value-triple nil))))
    [[... output omitted here ...]]
    Summary
    Form:  ( MAKE-EVENT (ER-PROGN ...))
    Rules: NIL
    Warnings:  Double-rewrite, Equiv, Subsume and Non-rec
    Time:  0.38 seconds (prove: 0.04, print: 0.29, other: 0.05)
    Prover steps counted:  41090
     NIL
    ACL2 !>


Subtopics

  [Last-prover-steps]
      The number of prover steps most recently taken")
 (SET-RAW-MODE
  (DEFTTAG)
  "Enter or exit ``raw mode,'' a raw Lisp environment

  Below we discuss raw-mode.  In brief: The simplest way to turn
  raw-mode on is [47m:SET-RAW-MODE-ON![0m, and to turn it off, [47m:SET-RAW-MODE
  NIL[0m.  Also see [set-raw-mode-on!].

  ACL2 users often find its careful syntax checking to be helpful
  during code development.  Sometimes it is even useful to do code
  development in [47m:[0m[47m[logic][0m mode, where ACL2 can be used to check
  termination of (mutually) recursive functions, verify guards, or
  even prove properties of the functions.

  However, loading code using [47m[include-book][0m is much slower than using
  Common Lisp [47mload[0m in raw Lisp, and in this sense ACL2 can get in the
  way of efficient execution.  Unfortunately, it is error-prone to
  use ACL2 sources (or their compilations) in raw Lisp, primarily
  because a number of ACL2 primitives will not let you do so.
  Perhaps you have seen this error message when trying to do so:

    HARD ACL2 ERROR in ACL2-UNWIND-PROTECT:  Apparently you have tried
    to execute a form in raw Lisp that is only intended to be executed
    inside the ACL2 loop.

  Even without this problem it is important to enter the ACL2 loop (see
  [lp]), for example in order to set the [47m[cbd][0m and (to get more
  technical) the readtable.  See [q].

  ACL2 provides a ``raw mode'' for execution of raw Lisp forms.  In
  this mode, [47m[include-book][0m reduces essentially to a Common Lisp
  [47mload[0m.  More generally, the ACL2 logical [47m[world][0m is not routinely
  extended in raw mode (some sneaky tricks are probably required to
  make that happen).  To turn raw mode off or on:

    :set-raw-mode t   ; turn raw mode on
    :set-raw-mode-on! ; same as above, but no trust tag required
    :set-raw-mode nil ; turn raw mode off

  The way you can tell that you are in raw mode is by looking at the
  prompt (see [default-print-prompt]), which uses a capital ``[47mP[0m''
  (suggesting something like [program] mode, but even further from
  [logic] mode).

    ACL2 P>

  Typical benefits of raw mode are fast loading of source and compiled
  files and the capability to hack arbitrary Common Lisp code in an
  environment with the ACL2 sources loaded (and hence with ACL2
  primitives available).  However, it probably is generally best to
  avoid raw mode unless these advantages seem important.  We expect
  the main benefit of raw mode to be in deployment of applications,
  where raw Lisp code may be useful, and where load time is much
  faster than the time required for a full-blown [47m[include-book][0m ---
  but not that the fast loading of books and treatment of hard errors
  discussed above may be useful during development.

  Raw mode is also useful for those who want to build extensions of
  ACL2.  For example, the following form can be put into a
  certifiable book to load an arbitrary Common Lisp source or
  compiled file.

    (progn (defttag my-application)
           (progn! (set-raw-mode t)
                   (load \"some-file\")))

  Also see [include-raw] [with-raw-mode], [defttag], and [progn!].

  Below are several disadvantages to using raw mode.  These should
  discourage users from using it for general code development, as
  [47m:[0m[47m[program][0m mode is generally preferable.

    * Forms are in essence executed in raw Lisp.  Hence:

        * Syntax checking is turned off; and

        * Guard checking is completely disabled.

    * Table events, including [47m[logic][0m, are ignored, as are many other
      [47m[events][0m, including [47m[defthm][0m and [47m[comp][0m.

    * Soundness claims are weakened for any ACL2 session in which raw mode
      was ever entered; see [defttag].

    * The normal undoing mechanism (see [ubt]) is not supported.

    * Unexpected behavior may occur when you return from raw-mode.  For
      example, if you redefine a :logic mode function whose guards
      have not been verified, you will not see the change inside the
      ACL2 loop because there, the raw Common Lisp definition is only
      executed after guards have been verified; see
      [guards-and-evaluation] and see [guard-evaluation-table].

  We conclude with some details.

  [3mPrinting results[0m.  The rules for printing results are mostly
  unchanged for raw mode, even to the point of attempting appropriate
  printing for state and stobjs (though this is merely heuristic when
  the top-level function is defined in raw mode), for example as
  follows.

    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 !>(set-raw-mode-on!)

    TTAG NOTE: Adding ttag :RAW-MODE-HACK from the top level loop.
    ACL2 P>(defun f (st) st)
    F
    ACL2 P>(f st)
    <st>
    ACL2 P>(defun g (st state) (mv 3 st state))
    G
    ACL2 P>(g st state)
    (3 <st> <state>)
    ACL2 P>(defun h (state) (mv nil 17 state))
    H
    ACL2 P>(h state) ; notice the leading space; see below
     17
    ACL2 P>

  There is however one major exception.  If the value to be printed
  contains any Lisp object that is not a legal ACL2 object, then the
  [47mprint[0m routine is used from the host Lisp, rather than the usual
  ACL2 printing routine.  The following example illustrates the
  printing used when an illegal ACL2 object needs to be printed.
  Notice how that ``command conventions'' are observed, as indicated
  in the ``leading space'' comment above; see [ld-post-eval-print].
  In particular, the ``[47m[Note[0m'' occurs one space over in the second
  example, and no result is printed in the third example.

    ACL2 P>(find-package \"ACL2\")
    [Note:  Printing non-ACL2 result.]
    #<The ACL2 package>
    ACL2 P>(mv nil (find-package \"ACL2\") state)
     [Note:  Printing non-ACL2 result.]
    #<The ACL2 package>
    ACL2 P>(mv t (find-package \"ACL2\") state)
    ACL2 P>(mv 3 (find-package \"ACL2\"))
    [Note:  Printing non-ACL2 result.]
    (3 #<The ACL2 package>)
    ACL2 P>

  If you have trouble with large structures being printed out, you
  might want to execute appropriate Common Lisp forms in raw mode,
  for example, [47m(setq *print-length* 5)[0m and [47m(setq *print-level* 5)[0m.

  Evaluation in raw mode attempts to maintain global [stobjs], but may
  not accommodate arbitrary raw Lisp hacks that hide the stobj
  returned by ACL2.  This can happen in two cases: when array
  resizing is used on the unique (array) field of a stobj, and when
  [47m[swap-stobjs][0m is used.  Consider for example the following log.
  Evaluation behaves nicely for all forms except the last, where
  resizing seems not to have taken effect as explained after the log,
  below.

    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 !>(defstobj st2 (ar :type (array t (8)) :resizable t))

    Summary
    Form:  ( DEFSTOBJ ST2 ...)
    Rules: NIL
    Time:  0.02 seconds (prove: 0.00, print: 0.00, other: 0.02)
     ST2
    ACL2 !>(set-raw-mode-on!)

    TTAG NOTE: Adding ttag :RAW-MODE-HACK from the top level loop.
    ACL2 P>(progn (update-fld 3 st) 17)
    17
    ACL2 P>(resize-ar 20 st2)
    <st2>
    ACL2 P>(ar-length st2)
    20
    ACL2 P>(progn (resize-ar 30 st2) 17)
    17
    ACL2 P>(ar-length st2) ; Should be 30, but it's not!
    20
    ACL2 P>

  The reason for the last form's ``wrong'' result (and the other
  ``correct'' results) is technical.  A stobj with a single array
  field is exactly that array in raw Lisp (except in some cases where
  that may be an array of characters), in which case resizing
  completely replaces the stobj in the global structure that stores
  the global stobj values.  The use of raw-Lisp [47mprogn[0m hides the
  evidence of stobj modification, which is based on the stobjs
  returned by the form (but this [47mprogn[0m form returns 17).  Such
  evidence is available in the earlier call of [47mresize-ar[0m above, since
  ACL2 knows that [47mresize-ar[0m returns a [47mst2[0m stobj.  The [47mupdate-fld[0m call
  does not provide such evidence for [47mst1[0m, again because of the [47mprogn[0m
  around the call; but [47mupdate-fld[0m actually modifies the stobj in
  place, rather than replacing it in the aforementioned global
  structure.

  [3mInclude-book[0m.  The [events] [47m[add-include-book-dir][0m,
  [47m[add-include-book-dir!][0m, [47m[delete-include-book-dir][0m, and
  [47m[delete-include-book-dir!][0m have been designed to work with raw
  mode.  However, if you enter raw mode and then evaluate such forms,
  then the effects of these forms will disappear when you exit raw
  mode, in which case you can expect to see a suitable warning.
  Regarding [3minclude-book[0m itself: it should work in raw mode as you
  might expect, at least if a compiled file or expansion file was
  created when the book was certified; see [certify-book].")
 (SET-RAW-MODE-ON
  (DEFTTAG)
  "Enter ``raw mode,'' a raw Lisp environment (requires trust tag)

  [47m(Set-raw-mode-on state)[0m is equivalent to [47m([0m[47m[set-raw-mode][0m[47m t)[0m; see
  [set-raw-mode].  Both require an active trust tag; see [defttag].
  Also see [set-raw-mode-on!], which first introduces a trust tag.")
 (SET-RAW-MODE-ON!
  (DEFTTAG)
  "Enter ``raw mode,'' a raw Lisp environment (adds trust tag)

  This is equivalent to [47m([0m[47m[set-raw-mode][0m[47m t)[0m except that it first
  introduces the required trust tag; see [defttag].  See
  [set-raw-mode] for a discussion of raw-mode.")
 (SET-RAW-PROOF-FORMAT
  (OUTPUT-CONTROLS)
  "Proof output with [rune]s as lists and maybe clausal goals

    General Forms:
    (set-raw-proof-format t)
    :set-raw-proof-format t
    (set-raw-proof-format nil)
    :set-raw-proof-format nil
    (set-raw-proof-format :clause)
    :set-raw-proof-format :clause

  This command affects output from the theorem prover only when [47m'prove[0m
  output is not inhibited (see [set-inhibit-output-lst]) and gag-mode
  is off (see [set-gag-mode]).  The default behavior is obtained with
  argument [47mnil[0m.

  Calling this macro with argument [47mt[0m will cause simplification steps
  from proof output, including steps from preprocess (see [simple]),
  to print the list of runes used in a list format, rather than in
  the English proof commentary.  This ``raw'' format can be handy
  when you want to use that list as a basis for [47m[hints][0m that you
  construct for a subsequent proof attempt.

  Calling this macro with argument [47m:clause[0m provides not only the
  behavior described above for argument [47mt[0m, but also causes goals to
  be printed using their internal clausal format: each goal is a
  list, implicitly disjoined, of translated [term]s.  See [clause].

  To obtain the current raw proof format value of [47mt[0m, [47m:clause[0m or [47mnil[0m,
  corresponding to the descriptions above, evaluate [47m(@
  raw-proof-format)[0m.")
 (SET-RAW-WARNING-FORMAT
  (OUTPUT-CONTROLS)
  "Print some warnings in a ``raw'', s-expression format

    General Forms:
    (set-raw-warning-format t)
    :set-raw-warning-format t
    (set-raw-warning-format nil)
    :set-raw-warning-format nil

  This command affects [47m'warning[0m (and [47m'warning![0m) output from the theorem
  prover when not inhibited (see [set-inhibit-output-lst]).  Calling
  this macro with value [47mt[0m as shown above will cause warnings to be
  printed in a ``raw'', s-expression format, of the form [47m(:WARNING
  warning-type alist)[0m.  The following example shows a traditional
  warning message followed by its counterpart after evaluating
  [47m(set-raw-warning-format t)[0m.

    ; default format
    ACL2 Warning [Subsume] in ( DEFTHM APP-COMMUTES ...):  A newly proposed
    :REWRITE rule generated from APP-COMMUTES probably subsumes the previously
    added :REWRITE rule APP-CONS, in the sense that the new rule will now
    probably be applied whenever the old rule would have been.

    ; raw format
    (:WARNING \"Subsume\"
              ((:CTX (DEFTHM . APP-COMMUTES))
               (:NEW-RULE APP-COMMUTES)
               (:RULE-CLASS-NEW :REWRITE)
               (:RULE-CLASS-OLD :REWRITE)
               (:SUBSUMED-RULES (APP-CONS))))

  As illustrated above, it is typical that in the raw format, the [47m:CTX[0m
  entry is first in the alist while the others are ordered
  alphabetically by key (e.g., [47m:NEW-RULE[0m precedes [47m:RULE-CLASS-NEW[0m
  alphabetically).

  To obtain the current raw-warning-format ([47mt[0m if that format is active,
  [47mnil[0m if not), evaluate [47m(@ raw-warning-format)[0m.

  NOTE: Only a few commonly-occurring classes of warnings are shown
  differently in raw-warning-format.")
 (SET-REGISTER-INVARIANT-RISK
  (PROGRAMMING ADVANCED-FEATURES
               GUARD DEBUGGING INVARIANT-RISK)
  "Avoid [invariant-risk] checking for specified functions

  See [invariant-risk] for an introduction to the notion of
  invariant-risk.  Also see [set-check-invariant-risk] for a way to
  avoid invariant-risk checking at runtime.  The present topic
  discusses a way to avoid marking specified functions as potentially
  having invariant-risk.

    General Forms:
    (set-register-invariant-risk t)   ; default
    (set-register-invariant-risk nil) ; requires active trust tag

  See community book [47mbooks/demos/register-invariant-risk.lisp[0m for a
  demonstration of how to use this utility.

  Normally a function is marked by ACL2 as having ``invariant-risk'' if
  its execution may have the potential to corrupt the ACL2 state.
  This causes execution slowdown that is not necessary if there is
  actually no such potential.  In such cases it may be advisable to
  instruct ACL2 to avoid marking that function as having
  invariant-risk.  This can be done by including the form
  [47m(set-register-invariant-risk nil)[0m in the book (or its [portcullis]
  commands) or [47m[encapsulate][0m event that contains the definition of
  that function (or, it can be done in the top-level loop before
  defining that function).  This action requires an active trust tag
  (see [defttag]) because you are asserting, without proof, that
  invariant-risk is impossible for that function.  Its effect can be
  reversed (returning to the default behavior) by evaluating
  [47m(set-register-invariant-risk t)[0m, which does not require an active
  trust tag.

  To see the current setting (i.e., the default of [47mt[0m or else [47mnil[0m after
  evaluation of [47m(set-register-invariant-risk nil)[0m), evaluate
  [47m(get-register-invariant-risk state)[0m.

  Note this utility does not affect whether a [stobj] primitive is
  marked with invariant-risk (which seems too dangerous in general);
  it only applies to functions introduced by [47m[defun][0m.  If you want a
  version of a stobj updater that has no invariant-risk and you have
  invoked [47m(set-register-invariant-risk nil)[0m, then define a function
  that calls the stobj updater.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  Moreover, its effect is to set the
  [47m[ACL2-defaults-table][0m, and hence its effect is [47m[local][0m to the book
  or [47m[encapsulate][0m form containing it; see [ACL2-defaults-table].")
 (SET-REWRITE-STACK-LIMIT
  (REWRITE-STACK-LIMIT)
  "Sets the rewrite stack depth used by the rewriter

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

    Example Forms:
    (set-rewrite-stack-limit 30)                            ; set to small limit
    :set-rewrite-stack-limit 30                             ; same as above
    (set-rewrite-stack-limit *default-rewrite-stack-limit*) ; the default
    (set-rewrite-stack-limit (1- (expt 2 28)))              ; maximum legal limit
    :set-rewrite-stack-limit nil         ; same as above -- essentially, no limit

  This event sets the maximum stack depth for calls of certain
  functions that implement the ACL2 rewriter; see
  [rewrite-stack-limit].  It must be a non-negative integer less than
  2^28.  A call [47m(set-rewrite-stack-limit limit)[0m is equivalent to:

    (table acl2-defaults-table :rewrite-stack-limit limit).

  The use of [47m[ACL2-defaults-table][0m ensures that this event's effect is
  implicitly [47m[local][0m to the book or [47m[encapsulate][0m form in which it
  occurs.

  For a different but somewhat related concept, see [backchain-limit].")
 (SET-RULER-EXTENDERS (POINTERS)
                      "See [rulers].")
 (SET-RW-CACHE-STATE
  (REWRITE)
  "Set the default rw-cache-state

  The ACL2 rewriter uses a data structure, called the rw-cache
  (rewriter cache), to save failed attempts to apply conditional
  [rewrite] rules.  The regression suite has taken approximately 11%
  less time with this mechanism.  The rw-cache is active by default
  but this event allows its behavior to be modified or even disabled
  by changing the so-called [3mrw-cache-state[0m.  Note that this event is
  [local] to its context (from [47m[encapsulate][0m or [47m[include-book][0m).  For
  a non-local version, use [set-rw-cache-state!].

    Example forms:
    (set-rw-cache-state :atom)     ; default: rw-cache cleared for each literal
                                   ;   (i.e., hypothesis or conclusion of a goal)
    (set-rw-cache-state nil)       ; rw-cache is inactive
    (set-rw-cache-state t)         ; rw-cache persists beyond each literal
    (set-rw-cache-state :disabled) ; rw-cache is inactive, but the rw-cache-state
                                   ;   transitions to state t after
                                   ;   simplification takes place

    General Form:
    (set-rw-cache-state val)

  where [47mval[0m evaluates to one of the four values shown in ``Example
  forms'' above.  The default is [47m:atom[0m, which enables the rw-cache
  but clears it before rewriting a hypothesis or conclusion of any
  goal.  The value [47mt[0m is provides more aggressive use of the rw-cache,
  basically preserving the rw-cache when there is a single subgoal.
  The value [47m:disabled[0m is the same as [47mt[0m, except that the rw-cache is
  initially inactive and only becomes active when some simplification
  has taken place.  We have seen a few cases where value [47mt[0m will make
  a proof fail but [47m:disabled[0m does not.

  To obtain the current rw-cache-state, evaluate the form
  [47m(rw-cache-state (w state))[0m.

  The following example illustrates the rw-cache in action.  You will
  see a break during evaluation of the [47m[thm][0m form.  Type [47m:eval[0m and
  you will see a failed rewriting attempt.  Type [47m:go[0m to continue, and
  at the next break type [47m:eval[0m again.  This time you will see the
  same failed rewriting attempt, but this time labeled with a
  notation saying that the failure was cached earlier, which
  indicates that this time the rewriter did not even attempt to prove
  the hypothesis of the [rewrite] rule [47mf1->f2[0m.

    (defstub f1 (x) t)
    (defstub f2 (x) t)
    (defaxiom f1->f2
             (implies (f1 x) (equal (f2 x) t)))
    :brr t
    :monitor (:rewrite f1->f2) t
    (thm (equal (car (f2 a)) (cdr (f2 a))))

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs (see [set-rw-cache-state!] for a corresponding
  non-[47m[local][0m event).

  We also note that rw-cache-state changes may also be caused at the
  subgoal level; see [hints].

  We welcome you to experiment with different rw-cache states.  If the
  more aggressive values of [47mt[0m and [47m:disabled[0m cause proofs to fail,
  then you can revert to the default of [47m:atom[0m or even turn off the
  rw-cache using [47m(set-rw-cache-state nil)[0m.  We don't expect users to
  need a deep knowledge of the rw-cache in order to do such
  experiments, but readers interested in details of the rw-cache
  implementation are invited to read the ``Essay on Rw-cache'' in the
  ACL2 source code.")
 (SET-RW-CACHE-STATE!
  (REWRITE)
  "Set the default rw-cache-state non-[47m[local][0mly

  Please see [set-rw-cache-state], which is the same as
  [47mset-rw-cache-state![0m except that the latter is not [47m[local][0m to the
  [47m[encapsulate][0m or the book in which it occurs.")
 (SET-SERIALIZE-CHARACTER (POINTERS)
                          "See [with-serialize-character].")
 (SET-SERIALIZE-CHARACTER-SYSTEM
  (SERIALIZE)
  "Avoid some special [serialize] writing, including for [47m.cert[0m files

  This function can be used to turn off (or on) the [serialize-write]
  capability, which is on by default, for writing certain files
  during book certification, including [certificate] files.  To use
  this function during a session:

    ; Disable the use of serialize-write by book certification:
    (set-serialize-character-system nil state)

    ; Re-enable the use of serialize-write by book certification:
    (set-serialize-character-system #\\Z state)

  To use this capability when certifying community-books, you can use a
  suitable [ACL2-customization] file, for example:

    cd books ; \\
    make basic \\
    ACL2_CUSTOMIZATION=`pwd`/../acl2-customization-files/no-serialize.lisp

  Alternatively, you can put the following form directly into the book:

    (make-event
     (pprogn (set-serialize-character-system nil state)
             (value '(value-triple nil))))

  To control the use of [serialize] for writes controlled by the user
  rather than by the system, see [with-serialize-character].")
 (SET-SKIP-META-TERMP-CHECKS
  (META CLAUSE-PROCESSOR)
  "Skip output checks for [meta] functions and [clause-processor]s

  WARNING: Use of this macro may render ACL2 unsound, which is why it
  requires a trust tag.  If you obtained an error during application
  of a [meta]function, a hypothesis metafunction, or a
  [clause-processor], it might well be best to rewrite that function
  to avoid generating terms with the ``forbidden'' function calls
  described in that error message.  However, judicious use of this
  macro can be useful during development; the rest of this topic
  describes its usage.

  The result of applying a [meta]function (or a hypothesis
  metafunction) must be a term.  Similarly, the result of applying a
  [clause-processor] must be a list of clauses, where a clause is a
  list of terms (see [clause]).  If these conditions fail, then an
  error occurs; see [term-table] for how one obtains some assistance
  towards avoiding such errors.

  By default, ACL2 actually enforces a stronger requirement: the
  resulting term or clause-list cannot contain any calls of
  ``forbidden'' function symbols: ones that would be illegal when
  submitting a theorem.  These include function symbols that are
  [3muntouchable[0m (see [remove-untouchable]) as well as those that are
  keys of the alist [47m*ttag-fns*[0m.

  These two checks --- that the results are terms and that they contain
  no calls of forbidden function symbols --- can be expensive for
  large terms.  The macro [47mset-skip-meta-termp-checks[0m provides a way
  to avoid both checks.  Since these checks can be critical for
  soundness, a trust tag (see [defttag]) must be active in order to
  invoke this macro unless the argument is [47mnil[0m.  It might be best to
  avoid using this macro except to skip such checks that you have
  identified to be expensive, and to skip them only when using ACL2
  interactively (as opposed to doing batch certification jobs) ---
  though this macro might also be useful in determining when such
  checks are indeed expensive.

  There are two legal ways to call this macro, as follows.  Note that
  the arguments are not evaluated.

    ; Skip all such checks:
    (set-skip-meta-termp-checks t)

    ; Skip such checks for functions fn1, ..., fnk (each of which is presumably a
    ; metafunction, hypothesis metafunction, or clause-processor):
    (set-skip-meta-termp-checks (fn1 ... fnk))

  A special case of the second form above is to perform all such
  checks: [47m(set-skip-meta-termp-checks nil)[0m.  No trust tag is required
  in this case.

  This macro actually generates a [local] [table] event, for the table
  [47mskip-meta-termp-checks-table[0m and its unique key, [47mt[0m.  The macro
  [47m[set-skip-meta-termp-checks][0m generates a corresponding non-[local]
  [table] event.

    ACL2 !>:trans1 (set-skip-meta-termp-checks (f g))
     (LOCAL (SET-SKIP-META-TERMP-CHECKS! (F G)))
    ACL2 !>:trans1 (set-skip-meta-termp-checks! (f g))
     (TABLE SKIP-META-TERMP-CHECKS-TABLE T '(F G))
    ACL2 !>

  It is probably good practice to use [47mset-skip-meta-termp-checks[0m rather
  than [47mset-skip-meta-termp-checks![0m, except when there is a compelling
  reason to do otherwise.")
 (SET-SKIP-META-TERMP-CHECKS!
  (META CLAUSE-PROCESSOR)
  "Skip output checks non-[local]ly for [meta] functions and
  [clause-processor]s

  See [set-skip-meta-termp-checks].")
 (SET-SLOW-ALIST-ACTION (POINTERS)
                        "See [slow-alist-warning].")
 (SET-SPLITTER-OUTPUT
  (SPLITTER)
  "Turn on or off reporting of rules that may have caused case splits

    Examples:
    (set-splitter-output t)   ; enable  reports of ``splitter'' rules (default)
    (set-splitter-output nil) ; disable reports of ``splitter'' rules

  After evaluation of the form [47m(set-splitter-output t)[0m (the default),
  then whenever [47mprove[0m output is not inhibited (see
  [set-inhibit-output-lst]), ACL2 will report [rewrite] and
  [definition] rules that may have reduced a goal to more than one
  subgoal.  See [splitter] for how to interpret such reports.  We
  call such rules ``splitter rules'' for the goal that is being
  split.  This information can be useful in deciding how to eliminate
  large splits, for example of Goal into Subgoal 1000 through Subgoal
  1, by disabling some splitter rules.  If you want to avoid the
  printing of such information, you can put the form
  [47m(set-splitter-output t)[0m in your customization file; see
  [ACL2-customization].

  Note that this command does not change the ACL2 [world]; it only
  modifies the [state].  More precisely, it sets a state global to
  the indicated value.  (See [state] for discussion of the
  ``global-table'' of the state.)  When [47mprove[0m output is enabled (see
  [set-inhibit-output-lst]), the value of that state global is the
  value of the form [47m([0m[47m[splitter-output][0m[47m)[0m; otherwise the value of that
  form is [47mnil[0m.

  Again, see [splitter] for the effects of turning on the reporting of
  splitter rules.")
 (SET-STANDARD-CO (POINTERS)
                  "See [standard-co].")
 (SET-STANDARD-OI (POINTERS)
                  "See [standard-oi].")
 (SET-STATE-OK
  (STATE)
  "Allow the use of STATE as a formal parameter

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

  In brief: The variable symbol [47m[state][0m has an unusual status in ACL2.
  In order to use it, you either need to issue [47m:set-state-ok t[0m, as we
  explain below, or you need to declare it to be a [stobj], as
  explained elsewhere (see [declare-stobjs]).  Now we explain in more
  detail.

  Because the variable symbol [47m[state][0m denotes the ``current ACL2
  state,'' ACL2 treats the symbol very restrictively when it occurs
  as a formal parameter of a defined function.  The novice user, who
  is unlikely to be aware of the special status of that symbol, is
  likely to be confused when error messages about [47mSTATE[0m are printed
  in response to the innocent choice of that symbol as a formal
  variable.  Therefore the top-level ACL2 loop can operate in a mode
  in which [47m[state][0m is simply disallowed as a formal parameter.

  For a discussion of [47mSTATE[0m, See [state] and see [stobj].  Roughly
  speaking, at the top-level, the ``current ACL2 state'' is denoted
  by the variable symbol [47mSTATE[0m.  Only the current state may be passed
  into a function expecting a state as an argument.  Furthermore, the
  name of the formal parameter into which the current state is passed
  must be [47mSTATE[0m and nothing but the current state may be passed into
  a formal of that name.  Therefore, only certain access and change
  functions can use that formal --- namely those with a [47mSTATE[0m formal
  --- and if any such function produces a new state it becomes the
  ``current state'' and must be passed along in the [47mSTATE[0m position
  thereafter.  Thus, ACL2 requires that the state be single-threaded.
  This, in turn, allows us to represent only one state at a time and
  to produce new states from it destructively in a von Neumannesque
  fashion.  The syntactic restrictions on the variable [47mSTATE[0m are
  enforced by the translate mechanism (see [trans] and see [term])
  when terms are read.

  To prevent the novice user from seeing messages prohibiting certain
  uses of the variable symbol [47mSTATE[0m ACL2 has a mode in which it
  simply disallows the use of that symbol as a formal parameter.  Use
  of the symbol causes a simple error message.  The system is
  initially in that mode.

  To get out of that mode, execute:

    :set-state-ok t ;;; or, (set-state-ok t)

  It is not recommended that you do this until you have read the
  documentation of [47m[state][0m.

  To enter the mode in which use of [47mstate[0m is prohibited as a formal
  parameter, do:

    :set-state-ok nil

  The mode is stored in the defaults table, See [ACL2-defaults-table].
  Thus, the mode may be set [47m[local][0mly in books.")
 (SET-TABLE-GUARD
  (TABLE EVENTS)
  "Set the [47m:guard[0m for a [table]

  This macro is a convenient interface for setting a [47mtable[0m's guard to
  produce user-friendly error messages when the guard fails.  See
  [table] for background on table guards.  As noted there, the table
  guard may reference variables [47mKEY[0m, [47mVAL[0m, [47mWORLD[0m, [47mENS[0m, and [47mSTATE[0m; that
  is the case for the [47mguard[0m and [47mcoda[0m mentioned below.  Also
  particularly relevant here is the fact that the table guard can
  return a single value, but it can also return [47m(mv flg msg)[0m; in the
  latter case, if [47mflg[0m is [47mnil[0m then [47mmsg[0m is an error message.
  [47mSet-table-guard[0m is supplied a guard term that returns a single
  value, but sets the table guard to a corresponding term that
  returns values [47m(mv flg msg[0m), where [47mmsg[0m is constructed to be
  user-friendly when it is non-[47mnil[0m.

    General Form:
    (set-table-guard name guard
                     :topic topic
                     :show show
                     :coda coda)

  where [47mname[0m is the name of a table, [47mguard[0m is a term returning a single
  value that specifies the guard of that table, and the optional
  keyword arguments are as follows.

    * [47m:Topic[0m defaults to [47mname[0m.  Otherwise it is the name of a
      [documentation] topic to which the user is directed when the
      table guard fails.

    * [47m:Show[0m is [47mnil[0m by default, in which case the guard term is not included
      in the error message; otherwise it is included.

    * [47m:Coda[0m is [47mnil[0m by default.  Otherwise it should be a message (see
      [msgp]) to be printed, preceded by two spaces, after the
      message that would otherwise be printed.

  The error message when keywords are omitted is as shown in the
  example below, but (of course) where [47mFOO[0m, [47mMY-KEY[0m, and [47mMY-VAL[0m are
  replaced respectively by the table name, the key, and the value.
  We start our example by evaluating the following two events.

    (defun foo-check (key val world)
      (declare (ignore val))
      (function-symbolp key world))
    (set-table-guard foo (foo-check key val world))

  Then evaluation of [47m(table foo 'my-key 'my-val)[0m produces the following
  error message.

    ACL2 Error in ( TABLE FOO ...):  The TABLE :guard for FOO disallows
    the combination of key MY-KEY and value MY-VAL.  See :DOC FOO.

  Here we show what happens to the error message if instead we set the
  table guard as follows.  As before, it should be clear from this
  example what the message would look like in general.  This time we
  evaluate:

    (set-table-guard foo (foo-check key val world)
                     :topic set-foo
                     :show t
                     :coda (and (eq val 'my-val)
                                (msg \"~x0 is an odd name for a value!\"
                                     val)))

  This time, evaluation of [47m(table foo 'my-key 'my-val)[0m produces an
  error message that references [47m:DOC[0m topic [47mSET-FOO[0m instead of [47mFOO[0m
  (because of the [47m:topic[0m argument), shows the table guard (because of
  the [47m:show[0m argument), and prints a final coda (because of the [47m:coda[0m
  argument).

    ACL2 Error in ( TABLE FOO ...):  The TABLE :guard for FOO disallows
    the combination of key MY-KEY and value MY-VAL.  The :guard requires
    (FOO-CHECK KEY VAL WORLD).  See :DOC SET-FOO.  MY-VAL is an odd name
    for a value!

  It can be helpful for the table guard to be well-guarded.  For the
  examples above, the error message from [47m(table foo 3 'my-val)[0m is
  ugly because [47m3[0m fails to satisfy the guard of [47mfunction-symbolp[0m,
  which is called by [47mfoo-check[0m.  Here is a version of that function
  that produces the desired error message.

    (defun foo-check (key val world)
      (declare (xargs :guard t)
               (ignore val))
      (and (symbolp key)        ; for guard of function-symbolp
           (plist-worldp world) ; for guard of function-symbolp
           (function-symbolp key world)))

  Finally, here are two examples from the ACL2 source code.  They
  illustrate that [47m:show t[0m is reasonable when the table guard is
  concise, and that [47m:topic[0m is necessary when the table name is
  undocumented.

    (set-table-guard invisible-fns-table
                     (invisible-fns-entryp key val world)
                     :show t)

    (set-table-guard inhibit-warnings-table
                     (stringp key)
                     :topic set-inhibit-warnings)")
 (SET-TAU-AUTO-MODE
  (TAU-SYSTEM)
  "Turn on or off automatic (``greedy'') generation of [47m:tau-system[0m rules

    Examples:
    (set-tau-auto-mode t)      ; select automatic (``greedy'') mode
    (set-tau-auto-mode nil)    ; select manual mode

  This event is equivalent to [47m(table acl2-defaults-table
  :tau-auto-modep <t-or-nil>)[0m, and hence is [47m[local][0m to any [books]
  and [47m[encapsulate][0m [events] in which it occurs; see
  [ACL2-defaults-table].  See [introduction-to-the-tau-system] for
  background details.

  The tau system gathers rules for its database in one of two ways:
  greedily or only at the explicit command of the user.  ``Greedy''
  mode is officially called ``automatic mode'' and is the default.
  The other mode is called ``manual mode.''

  In automatic mode, all rules processed by ACL2 are also considered
  for inclusion in the tau database: if the [47m:corollary[0m of some proved
  theorem happens to fit into one of the forms described in
  [47m:[0m[47m[tau-system][0m, that rule is quietly added to the tau database
  [3mregardless of what[0m [47m:[0m[47m[rule-classes][0m the user named for the
  [47m:corollary[0m.  Of course, such rules are also stored in the ways
  named by the user.  See the [3mDesign Philosophy[0m section of
  [introduction-to-the-tau-system] for a discussion of why the tau
  system is greedy by default.  More details are given on automatic
  mode after we explain manual mode.

  To more tightly control the rules available to the tau system, the
  user may select manual mode by executing [47m(set-tau-auto-mode nil)[0m.
  In manual mode, the only events that create [47m:tau-system[0m rules are
  [47mdefthm[0m events explicitly specifying the [47m:[0m[47m[tau-system][0m rule class in
  the [47m:[0m[47m[rule-classes][0m argument.  Of course, for a [47m:tau-system[0m rule to
  be created from a proved formula (or its specified [47m:corollary[0m), the
  formula must be of the appropriate shape (syntactic form). See
  [tau-system].  In manual mode, if the [47m:tau-system[0m rule class is
  specified but the formula is not of an appropriate form an error is
  signaled.  (Note: even in manual mode, monadic functions that are
  recognized as Boolean are classified as tau predicates; but no
  rules are created for them.)

  Returning to our discussion of automatic mode, a [47m:[0m[47m[tau-system][0m rule
  may be created by any of the events below, provided the definition
  or formula proved is of an appropriate shape:

  (1) [47mdefun[0m events introducing ``big switch'' or ``[47mmv-nth[0m synonyms,''

  (2) [47mdefun[0m events creating type-prescription rules that may be also
  represented as ``signature rules'' of form 1, and

  (3) any [47mdefthm[0m event with a non-[47mnil[0m [47m:rule-classes[0m argument if no
  [47m:tau-system[0m rule is among the rule classes and the formula proved
  is in the shape of any [47mtau-system[0m rule.

  Of course, events such as [47m[defstobj][0m and [47m[defevaluator][0m may also add
  rules to the tau database when they execute the [47m[defun][0m and
  [47m[defthm][0m events implicit in their descriptions.  See [tau-system]
  for a description of the various shapes mentioned above.

  Note that any rule (of any rule class) created when the tau system is
  in manual mode is also created in automatic mode.  For example, if
  an event would create a [47m:DEFINITION[0m, [47m:TYPE-PRESCRIPTION[0m,
  [47mFORWARD-CHAINING[0m, or [47m:REWRITE[0m rule when the tau system is in manual
  mode, then the event will create that same rule when the tau system
  is in automatic mode.  Automatic mode just means that some
  additional [47m:tau-system[0m rules may be created.

  Of course, if a [47mdefthm[0m event explicitly specifies a [47m:tau-system[0m rule
  class, then even if the tau system is in automatic mode, that tau
  rule is created from the proved formula (or the specified
  [47m:corollary[0m) or else an error is caused.  But if the tau system is
  in automatic mode and a [47mdefthm[0m event doesn't explicitly specify a
  [47m:tau-system[0m rule class, then the system quietly checks each
  specified [47m:corollary[0m --- or, in the absence of any [47m:corollary[0m, it
  checks the proved formula --- for whether it can be stored as a tau
  rule.  If so, then the system stores a tau rule, in addition to
  storing the specified rule.  Of course, no error is signaled if a
  proved formula of some non-[47m:tau-system[0m rule class fails to be of an
  appropriate shape for the tau system.

  In automatic mode, if the [47m:rule-classes[0m specified for [47mdefthm[0m included
  several corollaries and any one of them is of class [47m:tau-system[0m
  then the only tau system rules created are those explicitly classed
  as [47m:tau-system[0m rules.  For example, suppose a [47mdefthm[0m has one
  [47m:corollary[0m stored as a [47m:rewrite[0m rule and another [47m:corollary[0m stored
  as a [47m:tau-system[0m rule.  But suppose the [47m:rewrite[0m rule happens to
  also to fit the form of a [47m:tau-system[0m rule.  Is it added to the tau
  database or not?  The answer is no.  If you have taken the trouble
  to specify [47m:tau-system[0m corollaries for an event, then those
  corollaries are the only ones stored as tau system rules from that
  event.  Note that had both corollaries been classed as [47m:rewrite[0m
  rules (and been of acceptable [47m:tau-system[0m form) both would have
  also been made [47m:tau-system[0m rules.  This also allows you be in
  automatic mode and state a [47m:rewrite[0m or other non-[47m:tau-system[0m rule
  and prevent it from being also made a tau system rule: just add a
  frivolous [47m:tau-system[0m [47m:corollary[0m like [47m(booleanp (integerp x))[0m.

  Recall that the use of tau rules is controlled by the rune
  [47m(:EXECUTABLE-COUNTERPART TAU-SYSTEM)[0m.  When that rune is disabled,
  no tau rules are [3mused[0m in proofs.  However, the tau system continues
  to collect tau rules if the system is in automatic mode.  Thus, if
  and when the tau system is re-enabled, rules automatically
  generated while the tau system was disabled will be used as usual
  by the tau system.

  Finally, note that [47mdefthm[0m events with [47m:rule-classes[0m [47mnil[0m do not create
  [47m:tau-system[0m rules even if the formula proved is of an appropriate
  shape, regardless of whether the tau system is in automatic or
  manual mode.

  The macro [47m[tau-status][0m provides a convenient way to enable/disable
  the [47m:[0m[47m[executable-counterpart][0m of [47mtau-system[0m and/or to switch
  between manual and automatic modes.  It may also be used to
  determine the current settings of those two flags.")
 (SET-TEMP-TOUCHABLE-FNS (POINTERS)
                         "See [remove-untouchable].")
 (SET-TEMP-TOUCHABLE-VARS (POINTERS)
                          "See [remove-untouchable].")
 (SET-TOTAL-PARALLELISM-WORK-LIMIT
  (PARALLELISM)
  "For ACL2(p): set thread limit for parallelism primitives

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].
  While the most common use of the limit described below is in
  parallel proof (see [parallel-proof]), it also applies to all
  parallelism primitives (see [parallel-programming]) except
  [47m[spec-mv-let][0m --- though we expect that rather few programming
  applications will encounter this limit.

    General Forms:
    (set-total-parallelism-work-limit :none)     ; disable the limit
    (set-total-parallelism-work-limit <integer>) ; set limit to <integer>

  See [parallelism-tutorial], Section ``Another Granularity Issue
  Related to Thread Limitations'', for an explanation of how the host
  Lisp can run out of threads.  Also see
  [set-total-parallelism-work-limit-error].

  If the underlying runtime system (the Operating System, the host
  Lisp, etc.)  is unable to provide enough threads to finish
  executing the parallelism work given to it, the runtime system can
  crash in a very unpleasant manner (ranging from a Lisp error to
  completely freezing the machine).  To avoid this unpleasantness,
  ACL2(p) will attempt to avoid creating so much parallelism that the
  runtime system crashes.

  ACL2 initially uses a conservative estimate to limit the number of
  threads.  To tell ACL2(p) to use a different limit, call
  [47mset-total-parallelism-work-limit[0m with the new limit.  For example,
  if the current default limit is 10,000, then to allow 13,000
  threads to exist, issue the following form at the top level.

    (set-total-parallelism-work-limit 13000)

  To disable this limit altogether, evaluate the following form:

    (set-total-parallelism-work-limit :none)

  The default value of total-parallelism-work-limit can be found by
  calling function [47mdefault-total-parallelism-work-limit[0m.  If the
  default value is too high for your system please notify the ACL2
  maintainers with a limit that does work for your system, as they
  might then lower the default limit.")
 (SET-TOTAL-PARALLELISM-WORK-LIMIT-ERROR
  (PARALLELISM)
  "For ACL2(p): control the action taken when the thread limit is
  exceeded

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

    General Forms:
    (set-total-parallelism-work-limit-error t)   ; cause error (default)
    (set-total-parallelism-work-limit-error nil) ; disable error and
                                                 ; continue serially

  See [parallelism-tutorial], Section ``Another Granularity Issue
  Related to Thread Limitations'', for an explanation of how the host
  Lisp can run out of threads.  See
  [set-total-parallelism-work-limit] for further details, including
  an explanation of how to manage the limit that triggers this error.

  The value of state global [47mtotal-parallelism-work-limit-error[0m dictates
  what occurs when the underlying runtime system runs reaches a limit
  on the number of threads for parallel computation.  By default,
  when this limit is reached, the ACL2(p) user will receive an error
  and computation will halt.  At this point, the ACL2(p) user has the
  following options.

  (1) Remove the limit by evaluating the following form.

    (set-total-parallelism-work-limit :none)

  (2) Disable the error so that execution continues serially once the
  available thread resources have been exhausted.

    (set-total-parallelism-work-limit-error nil)

  (3) Increase the limit on number of threads that ACL2(p) is willing
  to create, in spite of potential risk (see
  [set-total-parallelism-work-limit]).  In this case, the following
  query returns the current limit.

    (f-get-global 'total-parallelism-work-limit)

  Then to increase that limit, evaluate the following form:

    (set-total-parallelism-work-limit <new-integer-value>)

  For example, suppose that the value of [47mtotal-parallelism-work-limit[0m
  was originally 10,000.  Then evaluation of the following form
  increases that limit to 13,000.

    (set-total-parallelism-work-limit 13000)")
 (SET-TRACE-CO (POINTERS)
               "See [trace-co].")
 (SET-TRACE-EVISC-TUPLE
  (TRACE)
  "Set the trace evisc tuple

  A trace evisc-tuple, which is set by this utility, provides a means
  to restrict printing during tracing.  See [evisc-tuple] for an
  introduction to evisc-tuples; also see [set-evisc-tuple] and see
  [set-iprint].

  By default the ACL2 [trace] mechanism, [47m[trace$][0m, automatically deals
  with stobjs, the logical world, and certain other large structures.
  See [trace$], in particular the documentation of [47mtrace$[0m option
  [47m:hide[0m.  However, even with that default behavior you may want to
  restrict what is printed according to the print-level and
  print-length of an evisc-tuple; see [evisc-tuple].

    Examples:

    ; Set trace evisc tuple to a standard value, using current Lisp *print-level*
    ; and *print-length* variables:
    (set-trace-evisc-tuple t state)

    ; Set trace evisc tuple back to its default:
    (set-trace-evisc-tuple nil state)

    ; Set trace evisc tuple to restrict print-level to 3 and print-length to 4,
    ; while hiding the logical world and suitably printing stobjs even if trace$
    ; option ``:hide nil'' is used.  (Note: calling [47mtrace-evisceration-alist[0m
    ; directly requires removing this function as `untouchable', which requires a
    ; trust tag; see [remove-untouchable].)
    (set-trace-evisc-tuple
     (evisc-tuple 3 4 (trace-evisceration-alist state) nil)
     state)

    General Forms:

    (set-trace-evisc-tuple nil state) ; trace evisc-tuple set to standard value
    (set-trace-evisc-tuple   t state) ; trace evisc-tuple set to hide the logical
                                      ;   world and deal with stobjs even when
                                      ;   trace$ option ``:hide nil'' is supplied
    (set-trace-evisc-tuple evisc-tuple state)
                                      ; tracing set to use indicated evisc-tuple

  See [trace$] for a discussion of ACL2 tracing.  The [evisc-tuple]
  used by that trace utility is the one last installed by
  [47mset-trace-evisc-tuple[0m (or by [47m[set-evisc-tuple][0m for the
  trace-evisc-tuple) --- initially to the default of [47mnil[0m --- unless
  overridden by trace option [47m:evisc-tuple[0m.

  [31;1mRemark[0m.  If you use value [47mt[0m, then ACL2 will ensure that the logical
  world and stobjs are kept up-to-date in the trace evisc-tuple.")
 (SET-VERIFY-GUARDS-EAGERNESS
  (GUARD)
  "The eagerness with which [guard] verification is tried.

    Example Forms:                        try guard verification?
    (set-verify-guards-eagerness 0) ; no, unless :verify-guards t
    (set-verify-guards-eagerness 1) ; yes if :guard, type :stobjs, or :df present
    (set-verify-guards-eagerness 2) ; yes, unless :verify-guards nil
    (set-verify-guards-eagerness 3) ; yes

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.

    General Form:
    (set-verify-guards-eagerness n)

  where [47mn[0m is a variable-free term that evaluates to [47m0[0m, [47m1[0m, [47m2[0m, or [47m3[0m.
  This macro is essentially equivalent to

    (table acl2-defaults-table :verify-guards-eagerness n)

  and hence is [47m[local][0m to any [books] and [47m[encapsulate][0m [events] in
  which it occurs; see [ACL2-defaults-table].  However, unlike the
  above simple call of the [47m[table][0m event function (see [table]), no
  output results from a [47mset-verify-guards-eagerness[0m event.

  [47mSet-verify-guards-eagerness[0m may be thought of as an event that merely
  sets a flag to [47m0[0m, [47m1[0m, [47m2[0m, or [47m3[0m.  The flag is used by certain [47m[defun][0m
  [events] to determine whether [guard] verification is tried.  The
  flag is irrelevant to those [47m[defun][0m [events] in [47m:[0m[47m[program][0m mode.
  It is also irrelevant to those [47m[defun][0m [events] in which an
  explicit [47m:[0m[47m[verify-guards][0m setting is provided among the [47m[xargs][0m,
  except when the flag is [47m3[0m.  In the [47m:[0m[47m[program][0m mode case, [guard]
  verification is not done because it can only be done when logical
  functions are being defined.  Otherwise, unless the flag is [47m3[0m, the
  explicit [47m:[0m[47m[verify-guards][0m setting determines whether [guard]
  verification is tried.  So consider a [47m:[0m[47m[logic][0m mode [47m[defun][0m in
  which no [47m:[0m[47m[verify-guards][0m setting is provided.  Is [guard]
  verification tried?  The answer depends on the eagerness setting as
  follows.  If the eagerness is [47m0[0m, [guard] verification is not tried.
  If the eagerness is [47m1[0m, it is tried if and only if a guard is
  explicitly specified in the [47m[defun][0m, in the following sense: there
  is an [47mxargs[0m keyword [47m:guard[0m, [47m:stobjs[0m, or [47m:dfs[0m, or there is a [47m[type][0m
  declaration.  If the eagerness is [47m2[0m or [47m3[0m, [guard] verification is
  tried.

  The above remarks apply to [47m[verify-termination][0m [events], according
  to whether guards are explicitly specified in the existing,
  corresponding [47m:[0m[47m[program][0m mode definitions.

  The default behavior of the system is as though the
  [47m:verify-guards-eagerness[0m is [47m1[0m.  The current behavior can be
  ascertained by evaluating the form [47m(default-verify-guards-eagerness
  (w state))[0m.")
 (SET-WARNINGS-AS-ERRORS
  (WARNINGS ERRORS OUTPUT-CONTROLS)
  "Changing [warnings] to hard [errors] (and vice-versa)

  It is common for ACL2 users not to notice warnings.  That problem can
  be avoided by using the utility [47mset-warnings-as-errors[0m to convert
  warnings to errors.  We start below with a general specification,
  followed by example forms, a detailed specification, and finally an
  extended example.


General Form

  The general form is

    (set-warnings-as-errors flg types state)

  where [47mflg[0m is [47mt[0m, [47m:always[0m, or [47mnil[0m and [47mtypes[0m is either [47m:all[0m or a list of
  strings.  The effect is to turn certain [warnings] into hard
  [errors], aborting the computation in progress.  Note that
  [47mset-warnings-as-errors[0m is a function, so all arguments are
  evaluated.  Details are described in the section below entitled
  ``Detailed Specification''.


Example Forms

    ; When a [Subsume] or [Use] warning is to be printed, cause a hard error
    ; instead with a similar message.
    (set-warnings-as-errors t '(\"Subsume\" \"Use\") state)

    ; As above, but cause a hard error even if the warning is not to be printed,
    ; i.e., even if by default it would be suppressed as a warning because of
    ; prior use of set-inhibit-output-lst or set-inhibit-warnings.
    (set-warnings-as-errors :always '(\"Subsume\" \"Use\") state)

    ; Restore the treatment of [Use] warnings as warnings.
    (set-warnings-as-errors nil '(\"Use\") state)

    ; Treat a warning as a hard error, but only if the warning is to be printed
    ; (hence not suppressed by set-inhibit-output-lst or set-inhibit-warnings).
    (set-warnings-as-errors t :all state)

    ; Treat a warning as a hard error, whether the warning is printed or not.
    (set-warnings-as-errors :always :all state)

    ; Restore the default behavior, treating warnings as warnings, not errors.
    (set-warnings-as-errors nil :all state)


Detailed Specification

    * No warning whose type specified by constant
      [47m*uninhibited-warning-summaries*[0m is converted to an error.
      Those types are the ones that belong, with a case-insensitive
      check, to the list [47m(\"Uncertified\" \"Provisionally certified\"
      \"Skip-proofs\" \"Defaxioms\" \"Ttags\" \"Compiled file\"
      \"User-stobjs-modified\")[0m.  This exception overrides all
      discussion below.

    * The behavior of [warnings] is affected for every warning type
      specified by the [47mtypes[0m argument.  When its value is [47m:all[0m, then
      all warnings are affected.  Otherwise the value of [47mtypes[0m is a
      list of warning types (see [set-inhibit-warnings]): a true list
      of strings, each treated as case-insensitive.  Note that when
      the value is not [47m:all[0m, the existing behavior for warning types
      is only changed for those in the value of [47mtypes[0m.

    * When [47mflg[0m is [47m:always[0m, then every warning specified by [47mtypes[0m is
      converted to a hard error, which aborts the evaluation in
      progress.  This happens even if the warning is suppressed (by
      [47m[set-inhibit-output-lst][0m or [47m[set-inhibit-warnings][0m).

    * When [47mflg[0m is [47mt[0m, then when a warning specified by [47mtypes[0m is to be
      printed, it is converted to a hard error, which aborts the
      evaluation in progress.  There is no error, however, if the
      warning is suppressed.

    * When [47mflg[0m is [47mnil[0m, then every warning specified by [47mtypes[0m is treated as
      a warning even if it had previously been treated as an error.

    * When a warning of a given type (possibly [47mnil[0m type) is converted to a
      hard error as specified above, then whether that error is
      printed is controlled by the usual mechanism for suppressing
      error messages; see [set-inhibit-er].  Note that the error will
      still be signaled regardless of whether the error message is
      thus suppressed.

    * Previous evaluations of calls of [47mset-warnings-as-errors[0m are ignored
      during [47m[certify-book][0m and [47m[include-book][0m.  The handling of
      warnings as errors is restored at the end of these operations
      to what it was at the beginning.


Extended Example

  ACL2 often prints [warnings], often with a message that includes a
  warning type.  Here is a contrived example.

    (defthm foo t
     :hints ((\"Goal\" :use car-cons))
     :rule-classes nil)

    ACL2 Warning [Use] in ( DEFTHM FOO ...):  It is unusual to :USE the
    formula of an enabled :REWRITE or :DEFINITION rule, so you may want
    to consider disabling (:REWRITE CAR-CONS) in the hint provided for
    Goal.  See :DOC using-enabled-rules.

  In the example above, the warning type is the string, [47m\"Use'[0m which is
  treated as case-insensitive; see [set-inhibit-warnings].  But maybe
  we prefer that every such warning be converted to an error; after
  all, as the warning suggests, we might want to disable the used
  rule first.  It's easy to miss a warning but not an error, so we
  might do the following.

    (set-warnings-as-errors t '(\"use\") state)

  That modifies ACL2 behavior such that instead of the warning above,
  we get the following error (after using [47m:u[0m to undo the effects of
  the [47mdefthm[0m event above).

    HARD ACL2 ERROR [Use] in ( DEFTHM FOO ...):  It is unusual to :USE
    the formula of an enabled :REWRITE or :DEFINITION rule, so you may
    want to consider disabling (:REWRITE CAR-CONS) in the hint provided
    for Goal.  See :DOC using-enabled-rules.

  Note that this is a ``hard'' error: it aborts the computation in
  progress.

  Suppose however that we turn off the warning by evaluating either of
  the following two forms.

    (set-inhibit-output-lst '(warning proof-tree))
    ; OR
    (set-inhibit-warnings \"use\")

  After evaluating either (or both) of these forms, the [47mdefthm[0m form
  above completes with no warnings or errors.  That's because there
  was no warning to print, and the [47mflg[0m value of [47mt[0m only has an effect
  for warnings that are printed.  If we want errors to occur even for
  warnings whose printing is suppressed, we should use the [47mflg[0m value,
  [47m:always[0m.

    (set-warnings-as-errors :always '(\"use\") state)
    ; OR
    (set-warnings-as-errors :always :all state)")
 (SET-WATERFALL-PARALLELISM
  (PARALLELISM)
  "For ACL2(p): configuring the parallel execution of the waterfall

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

    General Forms:
    (set-waterfall-parallelism nil)        ; never parallelize (serial execution)
    (set-waterfall-parallelism :full)      ; always parallelize
    (set-waterfall-parallelism :top-level) ; parallelize top-level subgoals
    (set-waterfall-parallelism             ; parallelize if sufficient resources
      :resource-based)                     ;   (recommended setting)
    (set-waterfall-parallelism t)          ; alias for :resource-based
    (set-waterfall-parallelism             ; parallelize if sufficient resources
      :resource-and-timing-based           ;   and suggested by prior attempts
    (set-waterfall-parallelism             ; never parallelize but use parallel
      :pseudo-parallel)                    ;   code base (a debug mode)

  [47mSet-waterfall-parallelism[0m evaluates its argument, which specifies the
  enabling or disabling of the [parallel] execution of ACL2's main
  proof process, the waterfall.

  It also sets [state] global [47mwaterfall-printing[0m to an appropriate
  value.  See [set-waterfall-printing].

  Note that not all ACL2 features are supported when
  waterfall-parallelism is set to non-[47mnil[0m (see
  [unsupported-waterfall-parallelism-features]).

  A value of [47mt[0m is treated the same as a value of [47m:resource-based[0m and is
  provided for user convenience.

  [47m:Resource-based[0m waterfall parallelism typically achieves the best
  performance in ACL2(p), while maintaining system stability, so
  [47m:resource-based[0m (or equivalently, [47mt[0m) is the recommended value.

  A value of [47mnil[0m indicates that ACL2(p) should never prove subgoals in
  parallel.

  A value of [47m:full[0m indicates that ACL2(p) should always prove
  independent subgoals in parallel.

  A value of [47m:top-level[0m indicates that ACL2(p) should prove each of the
  top-level subgoals in parallel but otherwise prove subgoals in a
  serial manner.  This mode is useful when the user knows that there
  are enough top-level subgoals, many of which take a non-trivial
  amount of time to be proved, such that proving them in parallel
  will result in a useful reduction in overall proof time.

  A value of [47m:resource-based[0m (or equivalently, [47mt[0m) indicates that
  ACL2(p) should use its built-in heuristics to determine whether CPU
  core resources are available for parallel execution.  Note that
  ACL2(p) does not hook into the operating system to determine the
  workload on the machine.  ACL2(p) works off the assumption that it
  is the only process using significant CPU resources, and it
  optimizes the amount of parallelism based on the number of CPU
  cores in the system.  (Note that ACL2(p) knows how to obtain the
  number of CPU cores from the operating system in CCL, but that, in
  SBCL and in Lispworks, a constant is used instead).

  During the first proof attempt of a given conjecture, a value of
  [47m:resource-and-timing-based[0m results in the same behavior as with
  [47m:resource-based[0m.  However, on subsequent proof attempts, the time
  it took to prove each subgoal will be considered when deciding
  whether to parallelize execution.  If a particular theorem's proof
  is already achieving satisfactory speedup via [47m:resource-based[0m
  parallelism, there is no reason to try this setting.  However, if
  the user wishes to experiment, the [47m:resource-and-timing-based[0m
  setting may improve performance.  Note that since the initial run
  does not have the subgoal proof times available, this mode will
  never be better than the [47m:resource-based[0m setting for
  non-interactive theorem proving.

  A value of [47m:pseudo-parallel[0m results in using the parallel waterfall
  code, but with serial execution.  This setting is useful for
  debugging the code base that supports parallel execution of the
  waterfall.  For example, you may wish to use this mode if you are
  an ``ACL2 Hacker'' who would like to see comprehensible output from
  tracing (see [trace$]) the [47m@par[0m versions of the waterfall
  functions.

  Since [memoization] is not supported when waterfall parallelism is
  enabled (see [unsupported-waterfall-parallelism-features]), then
  when [47mset-waterfall-parallelism[0m is called with a non-[47mnil[0m value, all
  memoized functions are unmemoized.  When [47mset-waterfall-parallelism[0m
  is again called with a [47mnil[0m value, those memoization settings are
  restored.

  [47mSet-waterfall-parallelism[0m is an embedded event form.  However, a call
  of this macro will not affect waterfall-parallelism when including
  a certified book that contains that call.  For such an effect, you
  may use the following [47m[make-event][0m form; also see
  [non-parallel-book].

    (make-event (er-progn (set-waterfall-parallelism :full)
                          (value '(value-triple nil)))
                :check-expansion t)

  To enable waterfall parallelism for book certification using ACL2(p),
  see [waterfall-parallelism-for-book-certification].")
 (SET-WATERFALL-PARALLELISM-HACKS-ENABLED
  (PARALLELISM)
  "For ACL2(p): enable waterfall-parallelism hacks

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

    General Forms:
    (set-waterfall-parallelism-hacks-enabled t)
    (set-waterfall-parallelism-hacks-enabled nil)

  Some features (e.g., [override-hints] and [clause-processor]s) of
  serial ACL2 are by default not available in ACL2(p) with waterfall
  parallelism enabled, because they offer a mechanism to modify
  [state] that is unsound.  To allow or (once again) disallow the use
  the these features in ACL2(p), call
  [47mset-waterfall-parallelism-hacks-enabled[0m with argument [47mt[0m or [47mnil[0m,
  respectively.

  [47mSet-waterfall-parallelism-hacks-enabled[0m requires the use of a trust
  tag (see [defttag]).  One can call
  [47m[set-waterfall-parallelism-hacks-enabled!][0m instead, which will
  automatically install a trust tag named
  [47m:waterfall-parallelism-hacks[0m.

  See [error-triples-and-parallelism] for further related discussion.")
 (SET-WATERFALL-PARALLELISM-HACKS-ENABLED!
  (PARALLELISM)
  "For ACL2(p): enabling waterfall parallelism hacks

  See [set-waterfall-parallelism-hacks-enabled].")
 (SET-WATERFALL-PRINTING
  (PARALLELISM)
  "For ACL2(p): configuring the printing that occurs within the
  parallelized waterfall

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

    General Forms:
    (set-waterfall-printing :full)    ; print everything
    (set-waterfall-printing :limited) ; print a subset that's thought to be useful
    (set-waterfall-printing :very-limited) ; print an even smaller subset

  [47mSet-waterfall-printing[0m evaluates its argument, which indicates how
  much printing should occur when executing ACL2 with the
  parallelized version of the waterfall.  It only affects the
  printing that occurs when parallelism mode is enabled for the
  waterfall (see [set-waterfall-parallelism]).

  A value of [47m:full[0m is intended to print the same output as in serial
  mode.  This output will be interleaved unless the
  waterfall-parallelism mode is one of [47mnil[0m or [47m:pseudo-parallel[0m.

  A value of [47m:limited[0m omits most of the output that occurs in the
  serial version of the waterfall.  Instead, the proof attempt prints
  key checkpoints (see [ACL2p-key-checkpoints]).  The value of
  [47m:limited[0m also prints messages that indicate which subgoal is
  currently being proved, along with the wall-clock time elapsed
  since the theorem began its proof; and if state global
  [47m'waterfall-printing-when-finished[0m has a non-[47mnil[0m value, then such a
  message will also be printed at the completion of each subgoal.
  The function [47mprint-clause-id-okp[0m may receive an attachment to limit
  such printing; see [set-print-clause-ids].  Naturally, these
  subgoal numbers can appear out of order, because the subgoals can
  be proved in parallel.

  A value of [47m:very-limited[0m is treated the same as [47m:limited[0m, except that
  instead of printing subgoal numbers, the proof attempt prints a
  period (`[47m.[0m') each time it starts a new subgoal.

  Note that this form cannot be used at the top level of a book, or of
  a [47m[progn][0m or [47m[encapsulate][0m event.  Here is a workaround for use in
  such contexts; of course, you may replace [47m:very-limited[0m with any
  other legal argument for [47mset-waterfall-printing[0m.

    (make-event (er-progn (set-waterfall-printing :very-limited)
                          (value '(value-triple nil))))

  (For more about event contexts and the use of [47mmake-event[0m, see
  [make-event], in particular the section ``Restriction to Event
  Contexts.'')

  The following form has the effect described above, except that it
  will affect waterfall-printing even when including a certified book
  that contains it.

    (make-event (er-progn (set-waterfall-printing :very-limited)
                          (value '(value-triple nil)))
                :check-expansion t)

  Note that [47mset-waterfall-printing[0m is automatically called by
  [47m[set-waterfall-parallelism][0m.

  To enable the printing of information when a subgoal is finished,
  assign a non-[47mnil[0m value to global [47mwaterfall-printing-when-finished[0m.
  This can be accomplished by entering the following at the top
  level:

    (f-put-global 'waterfall-printing-when-finished t state)")
 (SET-WELL-FOUNDED-RELATION
  (DEFUN)
  "Set the default well-founded relation

    Examples:
    (set-well-founded-relation lex2)

  provided [47mlex2[0m has been proved to be a well-founded relation (see
  [well-founded-relation-rule]).  Note: This is an event!  It does
  not print the usual event [summary] but nevertheless changes the
  ACL2 logical [world] and is so recorded.

    General Form:
    (set-well-founded-relation rel)

  where [47mrel[0m has been proved to be a well-founded relation on objects
  satisfying some predicate, [47mmp[0m; see [well-founded-relation-rule].
  This macro is equivalent to [47m(table acl2-defaults-table
  :well-founded-relation 'rel)[0m, and hence is [47m[local][0m to any [books]
  and [47m[encapsulate][0m [events] in which it occurs; see
  [ACL2-defaults-table].

  This event sets the default well-founded relation to be that imposed
  on [47mmp[0m-measures by the relation [47mrel[0m.  Subsequently, if a recursively
  defined function is submitted to [47m[defun][0m with no explicitly given
  [47m:well-founded-relation[0m argument, [47m[defun][0m uses the default relation,
  [47mrel[0m, and the associated domain predicate [47mmp[0m used in its
  well-foundedness theorem.  That is, the termination conditions
  generated will require proving that the measure used by the [47m[defun][0m
  is an [47mmp[0m-measure and that in every recursive call the measure of
  the arguments decreases according to [47mrel[0m.")
 (SET-WORMHOLE-DATA
  (WORMHOLE)
  "Sets the wormhole data object in a wormhole status object

    General Form:  (set-wormhole-data whs data)

  See [wormhole].  [47mWhs[0m should be a well-formed wormhole status; [47mdata[0m is
  arbitrary.  This function returns a new status with the same entry
  code as [47mwhs[0m but with the new [47mdata[0m.  This function does not affect
  state or a wormhole's persistent-whs or ephemeral-whs.  It just
  returns a (possibly) new status object suitable as the value of the
  [47mlambda[0m expressions in [47m[wormhole-eval][0m and [47m[wormhole][0m.")
 (SET-WORMHOLE-ENTRY-CODE
  (WORMHOLE)
  "Sets the wormhole entry code in a wormhole status object

    General Form:  (set-wormhole-entry-code whs code)

  See [wormhole].  [47mWhs[0m should be a well-formed wormhole status and [47mcode[0m
  should be [47m:ENTER[0m or [47m:SKIP[0m.  This function returns a new status with
  the specified entry code but the same data as [47mwhs[0m.  This function
  does not affect state or a wormhole's persistent-whs or
  ephemeral-whs.  It just returns a (possibly) new status object
  suitable as the value of the [47mlambda[0m expressions in [47m[wormhole-eval][0m
  and [47m[wormhole][0m.")
 (SET-WRITE-ACL2X
  (BOOKS-REFERENCE)
  "Cause [47m[certify-book][0m to write out a [47m.acl2x[0m file

    Example Forms:
    (set-write-acl2x nil state)
    (set-write-acl2x t state)
    (set-write-acl2x '(nil) state) ; same as just above, but allow inclusion of
                                   ; uncertified books during certify-book
    (set-write-acl2x '(t) state)
    (set-write-acl2x '(include-book-with-locals) state)

    General Form:
    (set-write-acl2x val state)

  where [47mval[0m evaluates to [47mt[0m, [47mnil[0m, or a one-element list whose element is
  a legal value for the global [47m'ld-skip-proofsp[0m; see
  [ld-skip-proofsp].  The value returned is an error triple, which in
  the non-error case is [47m(mv nil v state)[0m, where [47mv[0m is the value of [47mval[0m
  and [47mstate[0m is the result of updating the input [state] by assigning
  state global [47m'write-acl2x[0m the value [47mv[0m.

  The command [47m(set-write-acl2x val state)[0m assigns the value of [47mval[0m to
  the [state] global variable [47m'write-acl2x[0m, affecting whether or not
  [47m[certify-book][0m writes out a file with extension [47macl2x[0m, called a
  ``[47m.acl2x[0m file'' and pronounced ``dot-acl2x file''.  Such a file is
  read or written by [47m[certify-book][0m when it is supplied with keyword
  argument [47m:acl2x t[0m.  By default, such a call of [47mcertify-book[0m reads a
  [47m.acl2x[0m file; but if the value of state global variable [47m'write-acl2x[0m
  is not [47mnil[0m, then [47mcertify-book[0m writes a [47m.acl2x[0m file (in which case
  it is illegal to specify a non-[47mnil[0m value for [47m[certify-book][0m keyword
  argument [47m:pcert[0m).  Consider for example [47m(certify-book \"foo\" 0 nil
  :acl2x t)[0m.  By default, this command reads file [47mfoo.acl2x[0m, which
  supplies replacements for some forms in [47mfoo.lisp[0m, as described
  later below.  But if the value of state global [47m'write-acl2x[0m is not
  [47mnil[0m, then instead, this [47mcertify-book[0m command writes such a file
  [47mfoo.acl2x[0m.

  Before we discuss the function of [47m.acl2x[0m files, we first explain more
  about how a non-[47mnil[0m value of [state] global [47m'write-acl2x[0m affects
  the behavior of a command [47m(certify-book ... :acl2x t ...)[0m.  A
  significant effect on the behavior is that after processing events
  in the given book, ACL2 writes out a [47m.acl2x[0m file and then returns,
  skipping the other subsequent actions typically performed by
  [47m[certify-book][0m: a [local-incompatibility] check, writing of a
  [certificate] file, and possibly [compilation].  Another effect is
  that proofs may be skipped when processing [events] assuming that
  the [47mcertify-book[0m command does not explicitly specify
  [47m:skip-proofs-okp nil[0m, as we now explain.  A non-[47mnil[0m value of
  [47m'write-acl2x[0m should either be [47mt[0m or a one-element list [47m(x)[0m, where [47mx[0m
  is a legal value for the [state] global [47m'ld-skip-proofsp[0m (see
  [ld-skip-proofsp]).  In both cases, [47mcertify-book[0m will process
  [events] to write out a [47m.acl2x[0m file as described above.  But in the
  latter (list) case, event processing will take place according to
  the value of [47mx[0m: in particular, proofs will be skipped when [47mx[0m is not
  [47mnil[0m, and if moreover [47mx[0m is the symbol [47minclude-book-with-locals[0m, then
  only one pass will be made through each [47m[encapsulate][0m form.  A
  third effect of a non-[47mnil[0m value of [47m'write-acl2x[0m, which is
  restricted to the list case, is that [include-book] events
  encountered during event processing are allowed to succeed on
  uncertified books, something that is prohibited during most calls
  of [47m[certify-book][0m.

  When [47m[certify-book][0m is used to write out a [47m.acl2x[0m file, there is
  typically a subsequent run of [47m[certify-book][0m that reads that file.
  Consider how this can work with a book [47mfoo.lisp[0m.  In the first call
  of [47mcertify-book[0m, a file [47mfoo.acl2x[0m is written that contains all
  [47m[make-event][0m expansions, but [47mfoo.cert[0m is not written.  In the
  second call of [47mcertify-book[0m, no [47m[make-event][0m expansion typically
  takes place, because [47mfoo.acl2x[0m supplies the expansions.  The
  command [47m(set-write-acl2x t state)[0m should be evaluated before the
  first certification (though another legal non-[47mnil[0m value may be used
  in place of [47mt[0m), setting the value of [47m[state][0m global [47m'write-acl2x[0m to
  [47mt[0m, to enable writing of [47mfoo.acl2x[0m; and the command [47m(set-write-acl2x
  nil state)[0m may be evaluated before the second run (though this is
  not necessary in a fresh ACL2 session) in order to complete the
  certification (writing out [47mfoo.cert[0m) using [47mfoo.acl2x[0m to supply the
  [47m[make-event][0m expansions.

  When [47m[Certify-book][0m is supplied with keyword argument [47m:acl2x t[0m it
  will read or write the book's [47m.acl2x[0m file; when supplied with
  [47m:acl2x nil[0m, it will not read or write that [47m.acl2x[0m file.  The value
  of [47m:acl2x[0m is [47mnil[0m by default.  The interaction of [47m[certify-book][0m
  with the corresponding [47m.acl2x[0m file is as follows.

    o If [47m:acl2x[0m is [47mt[0m, then:
      - If [47mset-write-acl2x[0m has been (most recently) called with a value of
        [47mt[0m for its first argument,then ACL2 writes the corresponding
        [47m.acl2x[0m file.
      - If [47mset-write-acl2x[0m has been (most recently) called with a value of
        [47mnil[0m for its first argument, or not called at all, then ACL2 insists
        on a corresponding [47m.acl2x[0m file that is at least as recent as the
        corresponding [47m.lisp[0m file, causing an error otherwise.
     o If [47m:acl2x[0m is [47mnil[0m,then:
      - If [47mset-write-acl2x[0m has been (most recently) called with a value
        [47mt[0m for its first argument, or if argument [47m:ttagsx[0m is supplied,
        then an error occurs.
      - If the [47m.acl2x[0m file exists, then regardless of whether or how
        [47mset-write-acl2x[0m has been called, ACL2 ignores the [47m.acl2x[0m file
        but issues a warning about it.

  Suppose you use the two-runs approach: first write a [47m.acl2x[0m file,
  then certify using (reading) that [47m.acl2x[0m file.  Then with scripts
  such as makefiles, then you may wish to provide a single
  [47m[certify-book][0m command to use for both runs.  For that purpose,
  [47m[certify-book][0m supports the keyword argument [47m:ttagsx[0m.  If this
  argument is supplied and [47mwrite-acl2x[0m is true, then this argument is
  treated as the [47m:ttags[0m argument, overriding a [47m:ttags[0m argument if
  present.  That is, for the two runs, [47m:ttagsx[0m may be used to specify
  the trust tags used in the first certification while [47m:ttags[0m
  specifies the trust tags, if any (else [47m:ttags[0m may be omitted), used
  in the second certification.  Note: If the argument [47m:ttagsx[0m is not
  supplied, then its value defaults to the (explicit or default)
  value of the [47m:ttags[0m argument.

  The built-in ACL2 Makefile support automatically generates suitable
  dependencies if you create a [47m.acl2[0m file with a [47m[certify-book][0m call
  matching the following regular expression, case-independent:

    (certify-book[^;]*:acl2x t

  For an example [47m.acl2[0m file with a [47mcertify-book[0m call matching the above
  pattern, see community books file
  [47mbooks/make-event/double-cert-test-1.acl2[0m.

  Note that [47m[include-book][0m is generally not affected by
  [47mset-write-acl2x[0m, other than through the indirect effect on
  [47m[certify-book][0m.  More precisely: All expansions are stored in the
  [certificate] file, so when [47m[include-book][0m is applied to a
  certified book, the [47m.acl2x[0m file is not consulted.

  An example of how to put this all together may be found in community
  book [47mbooks/make-event/double-cert-test-1.lisp[0m.  There, we see the
  following form.

    (make-event
     (progn (defttag :my-ttag)
            (progn! (let ((val (sys-call \"pwd\" nil)))
                      (value (list 'defun 'foo () val))))))

  Imagine that in place of the binding computed using [47m[sys-call][0m, which
  by the way requires a trust tag, is some computation of your choice
  (such as reading forms from a file) that is used to construct your
  own event, in place of the [47m[defun][0m event constructed above.  The
  [47mMakefile[0m in that directory contains the following added dependency,
  so that file [47mdouble-cert-test-1.acl2x[0m will be created:

    double-cert-test-1.cert: double-cert-test-1.acl2x

  There is also the file [47mdouble-cert-test-1.acl2[0m in that directory,
  which contains a single form as follows.

    (certify-book \"double-cert-test-1\" ? t :ttagsx :all :ttags nil)

  Thus, a call of `make' first creates file [47mdouble-cert-test-1.acl2x[0m,
  which uses the above [47m:ttagsx[0m argument in order to support the use
  of [47m[defttag][0m during [47m[make-event][0m expansion.  Then, `make' goes on
  to cause a second certification in which no trust tags are
  involved.  As a result, the parent book [47mdouble-cert-test.lisp[0m is
  ultimately certified without requiring any trust tags.

  The discussion above is probably sufficient for most users of the
  two-run approach it describes.  We conclude with further details
  for those who want more information.  Those who wish to see a yet
  lower-level explanation of how all this works are invited to read
  the comment in the ACL2 source code entitled ``Essay on .acl2x
  Files (Double Certification).

  Consider the [47m.acl2x[0m file produced by the first run as described
  above.  It contains a single expression, which is an association
  list whose keys are all positive integers, which occur in
  increasing order.  When the [47m.acl2x[0m file is present and at least as
  recent as the corresponding [47m.lisp[0m file, then for a subsequent
  [47m[certify-book][0m with argument [47m:acl2x t[0m and the (default) value of
  [47mnil[0m for [state] global [47m'write-acl2x[0m, that association list will be
  applied to the top-level events in the book, as follows.  Suppose
  the entry [47m(n . ev)[0m belongs to the association list in the [47m.acl2x[0m
  file.  Then [47mn[0m is a positive integer, and the [47mn[0mth top-level event in
  the book --- where the [47m0[0mth event is the initial [47m[in-package][0m form
  --- will be replaced by [47mev[0m.  In practice, [47mev[0m is the [47m[make-event][0m
  expansion created during certification for the [47mnth[0m top-level event
  in the book; and this will always be the case if the [47m.acl2x[0m file is
  created by [47m[certify-book][0m after execution of the form
  [47m(set-write-acl2x t state)[0m.  However, you are welcome to associate
  indices manually with any [events] you wish into the alist stored
  in the [47m.acl2x[0m file.

  Note: Also see the community book [47mmake-event/acl2x-help.lisp[0m for a
  useful utility that can be used to skip proofs during the writing
  of [47m.acl2x[0m files.")
 (SETENV$
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Set an environment variable

  [47m(Setenv$ str val)[0m, where [47mstr[0m and [47mval[0m are strings, sets the
  environment variable [47mstr[0m to have value [47mval[0m, for subsequent read by
  [47mgetenv$[0m (see [getenv$]), and returns [47mnil[0m.  Or, if this operation is
  not implemented for the host Common Lisp, an error will occur.

    Example:
    (setenv$ \"FOO\" \"BAR\")

  It may be surprising that [47msetenv$[0m returns [47mnil[0m; indeed, it neither
  takes nor returns the ACL2 [state].  The reason is that [47m[getenv$][0m
  takes responsibility for trafficking in [state]; it is defined in
  the logic using the function [47m[read-ACL2-oracle][0m, which (again, in
  the logic) does modify state, by popping an entry from its
  acl2-oracle field.  See [getenv$].

  As suggested above, a call of [47m[getenv$][0m takes into account the most
  recent call of [47msetenv$[0m on the same environment variable.  It may
  also be the case that [47msetenv$[0m modifies the environment of the
  underlying process; for example, we think this is probably the case
  for most invocations of ACL2 built on a host Lisp that is CCL,
  SBCL, or CMUCL, as well as others perhaps.  If you want to rely on
  such behavior, however, we advise you to look at source code.

  [31;1mFunction: [0m<setenv$>

    (defun setenv$ (str val)
      (declare (xargs :guard (and (stringp str) (stringp val))))
      (declare (ignore str val))
      nil)")
 (SEVENTH
  (NTH ACL2-BUILT-INS)
  "Seventh member of the list

  See any Common Lisp documentation for details.")
 (SHARP-BANG-READER
  (READER PACKAGES)
  "Package prefix that is not restricted to symbols

    Examples:

    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 !>'#!foo(a b)
    (FOO::A FOO::B)
    ACL2 !>'#!foo(a #!acl2 b)
    (FOO::A B)
    ACL2 !>'#!foo(#!acl2 a b)
    (A FOO::B)
    ACL2 !>'#!foo(#!\"ACL2\" a b)
    (A FOO::B)
    ACL2 !>

  The ACL2 reader supports the syntax [47m#!pkg-name expr[0m where [47mpkg-name[0m is
  a string or symbol that names a package known to ACL2.  As
  illustrated above, this syntax nests as one might expect.  In the
  special case that [47mexpr[0m is a symbol, [47m#!pkg-name expr[0m is equivalent
  to [47mpkg-name::expr[0m.")
 (SHARP-D-READER
  (READER NUMBERS)
  "Read a rational number as a representable rational (see [df])

  When the ACL2 reader encounters the two-character sequence [47m#d[0m, it
  invokes the Lisp reader to obtain the next token, which should
  designate a Lisp double-precision floating-point number.
  (Technically, the Lisp value of variable
  [47m*read-default-float-format*[0m is the symbol [47mDOUBLE-FLOAT[0m when the
  floating-point token is read.)  The reader then returns the
  rational number represented by that floating-point token.

  The discussion above is complete, but it may make more sense to those
  familiar with so-called [3mdf[0m values in ACL2.  See [df].

  See also [sharp-f-reader], which reads input starting with [47m#f[0m.  As
  with [47m#d[0m, one reads floating-point notation and returns the
  corresponding rational number.  However, while [47m#d[0m reads the next
  token as a Lisp floating-point number, [47m#f[0m is specific to ACL2 and
  follows precise documented rules that, unlike [47m#d[0m, allow use of
  underscores ([47m_[0m) and hexadecimal notation.")
 (SHARP-DOT-READER
  (READER DEFCONST)
  "Read-time evaluation of constants

    Example:

    ACL2 !>(defconst *a* '(a b c))

    Summary
    Form:  ( DEFCONST *A* ...)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     *A*
    ACL2 !>(quote (1 2 #.*a* 3 4))
    (1 2 (A B C) 3 4)
    ACL2 !>

  The ACL2 reader supports the syntax [47m#.*a*[0m where [47m*a*[0m was defined by
  [47m[defconst][0m.  In this case, the reader treats [47m#.*a*[0m as though it
  were reading the value of [47m*a*[0m.  This feature can be useful in
  conjunction with the use of [47m[evisc-table][0m to abbreviate large
  constants, so that the abbreviation can be read back in; see
  [evisc-table].

  Remarks.

  (1) The ACL2 reader only supports `[47m#.[0m' as described above, unlike
  Common Lisp.  Older versions (preceding 3.5) used `[47m#.[0m' to abort,
  but that functionality is now carried out by [47m(a!)[0m; see [a!].  For a
  related feature that only pops up one level, see [p!].

  (2) If you call [47m[certify-book][0m on a book that contains a form
  `[47m#.*foo*[0m', the [47m*foo*[0m must already be defined in the [world] in
  which you issue the [47mcertify-book[0m command.  The reason is that
  [47mcertify-book[0m reads the entire book before evaluating its forms.")
 (SHARP-F-READER
  (READER NUMBERS)
  "Read a rational number in floating-point syntax

  This topic is about reading expressions starting with [47m#f[0m.  See also
  [sharp-d-reader], which reads input starting with [47m#d[0m.  Both read a
  form of floating-point notation as a rational number.  However,
  while [47m#d[0m reads the next token as a Lisp floating-point number, [47m#f[0m
  is specific to ACL2 and follows rules documented explicitly below,
  including the use of underscores ([47m_[0m) and hexadecimal notation.

    Examples:

    ACL2 !>#f567
    567
    ACL2 !>#f_5_6__7_ ; underscores are allowed, and discarded
    567
    ACL2 !>
    ACL2 !>#f-567
    -567
    ACL2 !>#f+567
    567
    ACL2 !>#f5.67
    567/100
    ACL2 !>#f-5.67
    -567/100
    ACL2 !>#f5.67e3
    5670
    ACL2 !>#f-5.67e3
    -5670
    ACL2 !>#f-5.67e-3
    -567/100000
    ACL2 !>#f.67e2
    67
    ACL2 !>#f-.67e2
    -67
    ACL2 !>#f-.67e+4
    -6700
    ACL2 !>#f-0.67e+4
    -6700
    ACL2 !>#fx101
    257
    ACL2 !>#fx10.1
    257/16
    ACL2 !>#fx10.1p3
    257/2
    ACL2 !>#fx10.1p-4
    257/256
    ACL2 !>#fx-10.1p-4
    -257/256
    ACL2 !>#fx.1p4
    1
    ACL2 !>#fx.1p+8
    16
    ACL2 !>#fx.1p-2
    1/64
    ACL2 !>#fx-0_4p1_0
    -4096
    ACL2 !>

  As illustrated above, we support two forms of this reader: [47m#f[0m,
  indicating base 10 digits, and [47m#fx[0m, indicating base 16 digits.  Let
  {i} be notation representing a sequence of digits and (optionally)
  underscore ([47m_[0m) characters, optionally preceded by a sign ([47m-[0m or [47m+[0m),
  that the ACL2 reader reads as the integer i after discarding
  underscore characters; similarly for {j} and {n}, except that an
  initial sign is illegal for {j}, and for {n} the digits are always
  base 10 (even in the case of [47m#fx[0m).  Note that each such string is
  terminated at the first character from the input channel that is
  not a digit.  For the [47m#f[0m case we have the following semantics.

    #f{i}          => i
    #f{i}e{n}      => i * 10^n
    #f{i}.{j}      => i + (/ j 10^k) where k is the length of {j}
    #f{i}.{j}e{n}  => (i + (/ j 10^k)) * 10^n where k is the length of {j}

  We have the following similar semantics for the [47m#fx[0m case, except that
  {i} and {j} are now read in base 16.  Note that {n} is still read
  in base 10.

    #fx{i}         => i
    #fx{i}p{n}     => i * 2^n
    #fx{i}.{j}     => i + (/ j 16^k) where k is the length of {j}
    #fx{i}.{j}p{n} => (i + (/ j 16^k)) * 2^n where k is the length of {j}

  We thank Dmitry Nadezhin for pointing us to the following page, which
  explains an analogous ``floating point literal'' syntax for C++:

    http://en.cppreference.com/w/cpp/language/floating_literal

  Note, however, that in ACL2 we do not support the use of single quote
  ([47m'[0m) as a separator, using underscore ([47m_[0m) instead, which is
  consistent with another reader macro, [47m#u[0m (see [sharp-u-reader]).
  Moreover, unlike the syntax described on the page above, the ACL2
  [47m#f[0m reader allows an initial sign ([47m-[0m or [47m+[0m).  To see why, note that
  in Lisp, the string [47m\"-#\"[0m starts a symbol, for example:

    ? '-#f23
    |-#F23|
    ?

  Since the ACL2 reader is based on the Lisp reader, it would be
  awkward to provide support to read the string [47m\"-#f23\"[0m as a number,
  -23.  Instead, ACL2 accepts a sign immediately after the initial
  [47m\"#f\"[0m or [47m\"#fx\"[0m:

    ACL2 !>#f-23
    -23
    ACL2 !>")
 (SHARP-U-READER
  (READER NUMBERS)
  "Allow underscore characters in numbers

    Example:

    ACL2 !>#ub1000_1000_1000_
    2184
    ACL2 !>#b100010001000
    2184
    ACL2 !>#uo1_1
    9
    ACL2 !>#o11
    9
    ACL2 !>#u34_5
    345
    ACL2 !>#u345
    345
    ACL2 !>345
    345
    ACL2 !>#ux12_a
    298
    ACL2 !>#ux12a
    298
    ACL2 !>#u x12a
    298
    ACL2 !>#x12a
    298
    ACL2 !>#u123_456/7_919
    123456/7919
    ACL2 !>

  The ACL2 reader supports the use of [47m#ub[0m, [47m#uo[0m, and [47m#ux[0m where one would
  otherwise write [47m#b[0m, [47m#o[0m, and [47m#x[0m, respectively (for binary, octal,
  and hexadecimal numerals), but where underscore characters (`[47m_[0m')
  are allowed but ignored.  Also supported is the prefix [47m#u[0m in front
  of a an expression that is a decimal numeral except that underscore
  characters are allowed but ignored.

  The precise specification of [47m#u[0m is as follows.  The ACL2 reader reads
  one expression after the [47m#u[0m.  If the result is a number, then that
  number is returned by the reader.  Otherwise the result must be a
  symbol.  Let [47mN[0m be the [47m[symbol-name][0m of the symbol; thus [47mN[0m is a
  string.  If [47mN[0m begins with one of the characters `[47mB[0m', `[47mO[0m', or `[47mX[0m',
  then first obtain a string [47mS1[0m by prefixing [47mN[0m with the character,
  `[47m#[0m'; otherwise let [47mS1[0m be [47mN[0m.  Next, remove all underscore characters
  `[47m_[0m' from [47mS1[0m, obtaining [47mS2[0m.  The result is obtained by applying the
  ACL2 reader to [47mS2[0m; that result must be a number, or else an error
  occurs.")
 (SHOW-ACCUMULATED-PERSISTENCE (POINTERS)
                               "See [accumulated-persistence].")
 (SHOW-BDD
  (BDD)
  "Inspect failed BDD proof attempts

  Attempts to use BDDs (see [bdd]), using [47m:[0m[47m[bdd][0m [hints], can fail for
  various reasons.  Sometimes it is useful to explore such failures.
  To do so, one may simply execute the form

    (show-bdd)

  inside the ACL2 loop.  The system's response is generally
  self-explanatory.  Perhaps you have already seen [47mshow-bdd[0m used in
  some examples (see [bdd-introduction] and see [if*]).  Here we give
  some details about [47mshow-bdd[0m.

  [47m(Show-bdd)[0m prints the goal to which the BDD procedure was applied and
  reports the number of nodes created during the [bdd] computation,
  followed by additional information depending on whether or not the
  computation ran to completion or aborted (for reasons explained
  elsewhere; see [bdd-algorithm]).  If the computation did abort, a
  backtrace is printed that should be useful in understanding where
  the problem lies.  Otherwise, [47m(show-bdd)[0m prints out ``falsifying
  constraints.'' This list of pairs associates [term]s with values
  and suggests how to construct a binding list for the variables in
  the conjecture that will falsify the conjecture.  It also prints
  out the [term] that is the result of simplifying the input [term].
  In each of these cases, parts of the object may be hidden during
  printing, in order to avoid creating reams of uninteresting output.
  If so, the user will be queried about whether he wishes to see the
  entire object (alist or [term]), which may be quite large.  The
  following responses are legal:

      [47m w[0m --- Walk around the object with a structure editor

      [47m y[0m --- Print the object in full

      [47m n[0m --- Do not print any more of the object

  [47mShow-bdd[0m actually has four optional arguments, probably rarely used.
  The general form is

    (show-bdd goal-name goal-ans falsifying-ans term-ans)

  where [47mgoal-name[0m is the name of the goal on which the [47m:[0m[47m[bdd][0m hint was
  used (or, [47mnil[0m if the system should find such a goal), [47mgoal-ans[0m is
  [47mnil[0m if there is to be a query and otherwise is the answer to be
  used (without a query) for whether to print the input goal in full
  ([47mt[0m for '[47my[0m', [47mnil[0m for '[47mn[0m', and [47m:w[0m for '[47mw[0m'), [47mfalsifying-ans[0m is the
  answer to be used in place of the query for whether to print the
  falsifying constraints in full, and [47mterm-ans[0m is the answer to be
  used in place of the query for whether to print the resulting
  [term] in full.")
 (SHOW-BODIES
  (DEFINITION)
  "Show the potential definition bodies

    Examples:
    (show-bodies foo)
    :show-bodies foo

  A definition made using [47m[defun][0m installs a so-called ``body'' of a
  function symbol, as do certain [47m:[0m[47m[definition][0m rules.  Such bodies
  are used in a number of ways, including the application of [47m:expand[0m
  [hints]; see [definition], in particular the discussion of ``body''
  there, and see [hints] for a discussion of the [47m:expand[0m hint.  Also
  see [set-body] for how to change which of the available definitions
  (among the original definition and appropriate [47m:[0m[47m[definition][0m rules)
  is the one that provides the body.  The [47mshow-bodies[0m command
  displays the available such bodies in an appropriate format,
  starting with the one that is currently used as the body.

    General Forms:
    (show-bodies function-symbol)
    :show-bodies function-symbol")
 (SHOW-CUSTOM-KEYWORD-HINT-EXPANSION
  (CUSTOM-KEYWORD-HINTS)
  "Print out custom keyword hints when they are expanded

    Examples:
    (show-custom-keyword-hint-expansion t)
    (show-custom-keyword-hint-expansion nil)

    General Form:
    (show-custom-keyword-hint-expansion flg)

  If the value of [47mflg[0m is non-[47mnil[0m, then when custom keyword hints are
  expanded, the system prints the results of each expansion.  This is
  sometimes useful for debugging custom keyword hints and, from time
  to time, may be useful in understanding how a custom hint affects
  some proof attempt.

  The default setting is [47mnil[0m.

  For an explanation of how custom keyword hints are processed, see
  [custom-keyword-hints].")
 (SHOW-FC-CRITERIA
  (FORWARD-CHAINING-REPORTS)
  "Print the forward-chaining tracking criteria

    Example:  (show-fc-criteria)

  This function prints the list of triples being used to determine what
  is tracked during forward chaining.

  See [forward-chaining-reports] for details.")
 (SIGNATURE
  (ENCAPSULATE)
  "How to specify the arity of a constrained function

  We start with a gentle introduction to signatures, where we pretend
  that there are no single-threaded objects (more on that below ---
  for now, if you don't know anything about single-threaded objects,
  that's fine!).  Here are some simple examples of signatures.

    ((hd *) => *)
    ((pair * *) => *)
    ((foo * *) => (mv * * *))

  The first of these says that [47mhd[0m is a function of one argument, while
  the other two say that [47mpair[0m and [47mfoo[0m are functions that each take
  two arguments.  The first two say that [47mhd[0m and [47mpair[0m return a single
  value.  The third says that [47mfoo[0m returns three values, much as the
  following definition returns three values:

    (defun bar (x y)
      (mv y x (cons x y)))

  Corresponding ``old style'' signatures are as follows.  In each case,
  a function symbol is followed by a list of formal parameters and
  then either [47mt[0m, to denote a single value return, or [47m(mv t t t)[0m, to
  denote a multiple value return (in this case, returning three
  values).

    (hd (x) t)
    (pair (x y) t)
    (foo (x y) (mv t t t))

  That concludes our gentle introduction.  The documentation below is
  more general, for example covering single-threaded objects (see
  [stobj]), dfs (see [df]), and keyword values such as [47m:guard[0m.  When
  reading what follows below, all you need to know about
  single-threaded objects (or ``stobjs'') that each has a unique
  symbolic name and that [47m[state][0m is the name of the only built-in
  single-threaded object.  All other stobjs are introduced by the
  user via [47m[defstobj][0m or [47m[defabsstobj][0m.  We also mention ``dfs'',
  which are ACL2 expressions that denote Lisp floating-point values;
  see [df].  An expression that is neither a stobj name nor a df is
  said to be ``ordinary''.

    Examples:
    ((hd *) => *)
    ((hd *) => * :formals (x) :guard (consp x))
    ((printer * state) => (mv * * state))
    ((mach * mach-state * state) => (mv * mach-state))
    ((df-mult3 :df :df :df) => :df)

    General Form:
    ((fn ...) => *)
    ((fn ...) => s) ; where s is a stobj name
    ((fn ...) => :df)
    or
    ((fn ...) => (mv x1 x2 ... xn)) ; where each xi is *, a stobj, or :df
    or for part1 and part2 as above,
    (part1 => part2 :kwd1 val1 ... :kwdn valn)

  where [47mfn[0m is the constrained function symbol and the optional [47m:kwdi[0m
  and [47mvali[0m are as described below.  ACL2 also supports an older style
  of signature, described below after we describe the preferred
  style.

  Signatures specify three syntactic aspects of a function symbol: (1)
  the ``arity'' or how many arguments the function takes, (2) the
  ``multiplicity'' or how many results it returns via [47mMV[0m, and (3) the
  arguments and results that are stobjs or dfs.

  A signature typically has the form [47m((fn x1 ... xn) => val)[0m.  Such a
  signature has two parts, separated by the symbol ``=>''.  The first
  part, [47m(fn x1 ... xn)[0m, is suggestive of a call of the constrained
  function.  The number of ``arguments,'' [47mn[0m, indicates the arity of
  [47mfn[0m.  Each [47mxi[0m must be a symbol.  If a given [47mxi[0m is the symbol ``*''
  then the corresponding argument must be ordinary.  If a given [47mxi[0m is
  any other symbol, that symbol must be the name of a single-threaded
  object and the corresponding argument must be that object, or else
  that symbol must be [47m:df[0m and the corresponding argument must be a df
  (see [df]).  No stobj name may occur twice among the [47mxi[0m.

  The second part, [47mval[0m, of a signature is suggestive of a term and
  indicates the ``shape'' of the output of [47mfn[0m.  If [47mval[0m is a symbol
  then it must be either the symbol ``*'', the keyword [47m:df[0m, or the
  name of a single-threaded object.  In either case, the multiplicity
  of [47mfn[0m is 1 and [47mval[0m indicates whether the result is ordinary, a df,
  or a stobj.  Otherwise, [47mval[0m is of the form [47m(mv y1 ... yk)[0m, where [47mk[0m
  > 1.  Each [47myi[0m must be either the symbol ``*'', the keyword [47m:df[0m, or
  the name of a stobj.  Such a [47mval[0m indicates that [47mfn[0m has multiplicity
  [47mk[0m and the [47myi[0m indicate which results are ordinary, which are dfs,
  and which are stobjs.  No stobj name may occur twice among the [47myi[0m,
  and a stobj name may appear in [47mval[0m only if appears among the [47mxi[0m.

  A signature may have the form [47m((fn x1 ... xn) => val . k)[0m, where [47mk[0m is
  a [47m[keyword-value-listp][0m, i.e., an alternating list of keywords and
  values starting with a keyword.  In this case [47m((fn x1 ... xn) =>
  val)[0m must be a legal signature as described above.  The legal
  keywords in [47mk[0m are generally [47m:GUARD[0m and [47m:FORMALS[0m, but see remarks at
  the end of this topic regarding [47m:GLOBAL-STOBJS[0m and [47m:TRANSPARENT[0m
  and, for ACL2(r), [47m:CLASSICALP[0m.  The value following [47m:FORMALS[0m is to
  be the list of formal parameters of [47mfn[0m, which must be consistent
  with the parameters specified in [47m(fn x1 ... xn)[0m: they must both
  specify the same arity (number of formal parameters) and the same
  [stobj] inputs.  The value following [47m:GUARD[0m is a term that is to be
  the [guard] of [47mfn[0m.  Note that this guard is never actually
  evaluated, and is not subject to the guard verification performed
  on functions introduced by [47m[defun][0m (see [verify-guards]).  Said
  differently: this guard need not itself have a guard of [47mt[0m.  Indeed,
  the guard is only used for attachments; see [defattach].  Note that
  if [47m:GUARD[0m is supplied, then [47m:FORMALS[0m must also be supplied as a
  list of distinct variables that includes all variables occurring
  free in the specified guard.  One final observation about guards:
  if the [47m:GUARD[0m keyword is omitted, then the guard defaults to [47mT[0m.

  Before ACL2 supported user-declared single-threaded objects there was
  only one single-threaded object: ACL2's built-in notion of [47m[state][0m.
  The notion of signature supported then gave a special role to the
  symbol [47mstate[0m and all other symbols were considered to denote
  ordinary objects.  ACL2 still supports the old form of signature,
  but it is limited to functions that operate on ordinary objects or
  ordinary objects and [47mstate[0m.

    Old Style General Form:
    (fn formals result . k)

  where [47mfn[0m is the constrained function symbol, [47mformals[0m is a suitable
  list of formal parameters for it, [47mk[0m is an optional
  [47m[keyword-value-listp][0m (see below), and [47mresult[0m is either a symbol
  denoting that the function returns one result or else [47mresult[0m is an
  [47m[mv][0m expression, [47m(mv s1 ... sn)[0m, where [47mn>1[0m, each [47msi[0m is a symbol,
  indicating that the function returns [47mn[0m results.  At most one of the
  formals may be the symbol [47mSTATE[0m, indicating that the corresponding
  argument must be ACL2's built-in [47m[state][0m.  If [47mstate[0m appears in
  [47mformals[0m then [47mstate[0m may appear once in [47mresult[0m.  All ``variable
  symbols'' other than [47mstate[0m in old style signatures denote ordinary
  objects, regardless of whether the symbol has been defined to be a
  single-threaded object name!

  The optional [47mk[0m is as described above for newer-style signatures,
  except that the user is also allowed to declare which symbols
  (besides [47mstate[0m) are to be considered stobjs names or dfs.  Thus
  [47m:STOBJS[0m and @9':DFS') are also legal keywords.  The form

    (fn formals result ... :stobjs stobj-names :dfs df-names ...)

  specifies that [47mstobj-names[0m is either the name of a stobj or else is a
  list of such names; also, both [47mstobj-names[0m and [47mdf-names[0m are lists
  that must be contained in the [47mformals[0m list.  Every name in
  [47mstobj-names[0m must have been previously defined as a stobj via
  [47m[defstobj][0m or [47m[defabsstobj][0m.

  As promised above, we conclude with a remark about additional
  keywords.  The keyword [47m:GLOBAL-STOBJS[0m specifies the use of the
  macro, [47mwith-global-stobj[0m, in attachments (see [defattach]); see
  [47m[with-global-stobj][0m for explanation of this keyword.  The keyword
  [47m:TRANSPARENT[0m specifies transparent functions; see
  [transparent-functions].  Finally, the keyword [47m:CLASSICALP[0m is legal
  for ACL2(r) only (see [real]).  The value of this keyword must be [47mt[0m
  (the default) or [47mnil[0m, indicating respectively whether [47mfn[0m is
  classical or not.")
 (SIGNED-BYTE-P
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for signed integers that fit in a specified bit width

  [47m(Signed-byte-p bits x)[0m is [47mT[0m when [47mbits[0m is a positive integer and [47mx[0m is
  a signed integer whose 2's complement representation fits in a
  bit-width of [47mbits[0m, i.e., [47m-2^(bits-1) <= x < 2^(bits-1)[0m.

  Note that a [type-spec] of [47m(signed-byte i)[0m for a variable [47mx[0m in a
  function's [47m[declare][0m form translates to a [guard] condition of
  [47m(signed-byte-p i x)[0m.

  The [guard] for [47msigned-byte-p[0m is [47mT[0m.

  [31;1mFunction: [0m<signed-byte-p>

    (defun signed-byte-p (bits x)
      (declare (xargs :guard t))
      (and (integerp bits)
           (< 0 bits)
           (let ((y (expt 2 (1- bits))))
             (integer-range-p (- y) y x))))")
 (SIGNUM
  (NUMBERS ACL2-BUILT-INS)
  "Indicator for positive, negative, or zero

  [47m(Signum x)[0m is [47m0[0m if [47mx[0m is [47m0[0m, [47m-1[0m if [47mx[0m is negative, and is [47m1[0m otherwise.

  The [guard] for [47msignum[0m requires its argument to be rational ([real],
  in ACL2(r)) number.

  [47mSignum[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  From ``Common Lisp the Language'' page 206, we see a definition of
  [47msignum[0m in terms of [47m[abs][0m.  As explained elsewhere (see [abs]), the
  [guard] for [47m[abs][0m requires its argument to be a rational ([real],
  in ACL2(r)) number; hence, we make the same restriction for [47msignum[0m.

  [31;1mFunction: [0m<signum>

    (defun signum (x)
      (declare (xargs :guard (real/rationalp x)))
      (if (zerop x) 0 (if (minusp x) -1 1)))")
 (SIMPLE
  (REWRITE DEFINITION)
  "[47m:[0m[47m[definition][0m and [47m:[0m[47m[rewrite][0m rules used in preprocessing

    Example of simple rewrite rule:
    (equal (car (cons x y)) x)

    Examples of simple definition:
    (defun file-clock-p (x) (integerp x))
    (defun naturalp (x)
      (and (integerp x) (>= x 0)))

  The theorem prover output sometimes refers to ``simple'' definitions
  and rewrite rules.  These rules can be used by the preprocessor,
  which is one of the theorem prover's ``processes'' understood by
  the [47m:do-not[0m hint; see [hints].

  The preprocessor expands certain definitions and uses certain rewrite
  rules that it considers to be ``fast''.  There are two ways to
  qualify as fast.  One is to be an ``abbreviation'', where a rewrite
  rule with no hypotheses or loop stopper is an ``abbreviation'' if
  the right side contains no more variable occurrences than the left
  side, and the right side does not call the functions [47m[if][0m, [47m[not][0m or
  [47m[implies][0m.  Definitions and rewrite rules can both be
  abbreviations; the criterion for definitions is similar, except
  that the definition must not be recursive.  The other way to
  qualify applies only to a non-recursive definition, and applies
  when its body is a disjunction or conjunction, according to a
  perhaps subtle criterion that is intended to avoid case splits.")
 (SINGLE-THREADED-OBJECTS (POINTERS)
                          "See [stobj].")
 (SIXTH
  (NTH ACL2-BUILT-INS)
  "Sixth member of the list

  See any Common Lisp documentation for details.")
 (SKIP-PROOFS
  (EVENTS)
  "Skip proofs for a given form --- a quick way to introduce unsoundness

    Example Form:
    (skip-proofs
      (defun foo (x)
        (if (atom x) nil (cons (car x) (foo (reverse (cdr x)))))))

    General Form:
    (skip-proofs form)

  where [47mform[0m is processed as usual except that the proof obligations
  usually generated are merely assumed.

  Normally [47mform[0m is an event; see [events].  If you want to put
  [47mskip-proofs[0m around more than one event, consider the following (see
  [progn]): [47m(skip-proofs (progn event1 event2 ... eventk))[0m.

  [31;1mWARNING[0m: The use of [47mskip-proofs[0m carries an implicit promise by the
  user that the ensuing proof obligations are indeed theorems of the
  current theory.  When that is not the case, [47mskip-proofs[0m can even
  allow inconsistent [events] to be admitted to the logic.  Use it at
  your own risk!  If your intention is truly to extend the current
  logical theory, consider using [47m[defaxiom][0m instead.

  Sometimes in the development of a formal model or proof it is
  convenient to skip the proofs required by a given event.  By
  embedding the event in a [47mskip-proofs[0m form, you can avoid the proof
  burdens generated by the event, at the risk of introducing
  unsoundness.  Below we list four illustrative situations in which
  you might find [47mskip-proofs[0m useful.

  1. The termination argument for a proposed function definition is
  complicated.  You presume you could admit it, but are not sure that
  your definition has the desired properties.  By embedding the
  [47m[defun][0m event in a [47mskip-proofs[0m you can ``admit'' the function and
  experiment with theorems about it before undoing (see [ubt]) and
  then paying the price of its admission.  Note however that you
  might still have to supply a measure.  The set of formals used in
  some valid measure, known as the ``measured subset'' of the set of
  formals, is used by ACL2's induction heuristics and therefore needs
  to be suitably specified.  You may wish to specify the special
  measure of [47m(:? v1 ... vk)[0m, where [47m(v1 ... vk)[0m enumerates the
  measured subset.

  2. You intend eventually to verify the [guard]s for a definition but
  do not want to take the time now to pursue that.  By embedding the
  [47m[verify-guards][0m event in a [47mskip-proofs[0m you can get the system to
  behave as though the [guard]s were verified.

  3. You are repeatedly recertifying a book while making many
  experimental changes.  A certain [47m[defthm][0m in the book takes a very
  long time to prove and you believe the proof is not affected by the
  changes you are making.  By embedding the [47m[defthm][0m event in a
  [47mskip-proofs[0m you allow the theorem to be assumed without proof
  during the experimental recertifications.

  4. You are constructing a proof top-down and wish to defer the proof
  of a [47m[defthm][0m until you are convinced of its utility.  You can
  embed the [47mdefthm[0m in a [47mskip-proofs[0m.  Of course, you may find later
  (when you attempt prove the theorem) that the proposed [47mdefthm[0m is
  not a theorem.

  Unsoundness or Lisp errors may result if the presumptions underlying
  a use of [47mskip-proofs[0m are incorrect.  Therefore, [47mskip-proofs[0m must be
  considered a dangerous (though useful) tool in system development.

  Roughly speaking, a [47m[defthm][0m embedded in a [47mskip-proofs[0m is essentially
  a [47m[defaxiom][0m, except that it is not noted as an axiom for the
  purposes of functional instantiation (see [lemma-instance]).  But a
  skipped [47m[defun][0m is much more subtle since not only is the
  definitional equation being assumed but so are formulas relating to
  termination and type.  The situation is also difficult to
  characterize if the [47mskip-proofs[0m [events] are within the scope of an
  [47m[encapsulate][0m in which constrained functions are being introduced.
  In such contexts no clear logical story is maintained; in
  particular, constraints aren't properly tracked for definitions.  A
  proof script involving [47mskip-proofs[0m should be regarded as
  work-in-progress, not as a completed proof with some unproved
  assumptions.  A [47mskip-proofs[0m event represents a promise by the
  author to admit the given event without further axioms.  In other
  words, [47mskip-proofs[0m should only be used when the belief is that the
  proof obligations are indeed theorems in the existing ACL2 logical
  [world].

  ACL2 allows the certification of [books] containing [47mskip-proofs[0m
  [events] by providing the keyword argument [47m:skip-proofs-okp t[0m to
  the [47m[certify-book][0m command.  This is contrary to the spirit of
  certified [books], since one is supposedly assured by a valid
  [certificate] that a book has been ``blessed.'' But certification,
  too, takes the view of [47mskip-proofs[0m as ``work-in-progress'' and so
  allows the author of the book to promise to finish.  When such
  [books] are certified, a warning to the author is printed,
  reminding him or her of the incurred obligation.  When [books]
  containing [47mskip-proofs[0m are included into a session, a warning to
  the user is printed, reminding the user that the book is in fact
  incomplete and possibly inconsistent.  This warning is in fact an
  error if [47m:skip-proofs-okp[0m is [47mnil[0m in the [47m[include-book][0m form; see
  [include-book].

  We conclude with a technical note.  [47mSkip-proofs[0m works by binding the
  [47m[ld][0m special [47m[ld-skip-proofsp][0m to [47mt[0m unless it is already bound to a
  non-[47mnil[0m value; see [ld-skip-proofsp].")
 (SLEEP
  (PROGRAMMING)
  "Sleep for some number of seconds

  The call [47m(sleep n)[0m returns [47mnil[0m.  However, it takes approximately [47mn[0m
  seconds of real time for this call to return.

  The [guard] for [47msleep[0m requires its argument to be a non-negative
  rational number.

  [47mSleep[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<sleep>

    (defun sleep (n)
      (declare (xargs :guard (and (rationalp n) (<= 0 n))))
      (declare (ignore n))
      nil)")
 (SLOW-ALIST-WARNING
  (FAST-ALISTS)
  "Warnings/errors issued when [47m[fast-alists][0m are used inefficiently

  Obtaining hash-table performance from [47m[hons-get][0m requires one to
  follow a certain discipline.  If this discipline is violated, you
  may see the following message, which by default is followed by a
  Lisp break.  (The Lisp break may be ignored by continuing in the
  host Common Lisp, for example using [47m:go[0m if the host Lisp is CCL.
  Or, it may be aborted, often using [47m:q[0m, again depending on the host
  Lisp.)

    *****************************************************************
    Fast alist discipline violated in HONS-ACONS.
    See :DOC slow-alist-warning to suppress or break on this warning.
    *****************************************************************

  This warning means that the alist you are extending or accessing does
  not have a valid hash table associated with it, and hence any
  accesses must be carried out with [47m[hons-assoc-equal][0m instead of
  [47mgethash[0m.

  You can control whether or not you get a warning and, if so, whether
  or not a break (again: an error from which you can continue)
  ensues.  For instance:

    (set-slow-alist-action :break)    ; warn and also call break$ (default)
    (set-slow-alist-action :warning)  ; warn on slow access
    (set-slow-alist-action nil)       ; do not warn or break

  The above forms expand to [47m[table][0m [events], so they can be embedded
  in [47m[encapsulate][0ms and [books], wrapped in [47m[local][0m, and so on.

  We conclude by showing how slow alist warnings can occur naturally,
  together with a couple of possible solutions.  First consider the
  rather trivial example; the labels A1, A2, etc. are explained
  later.

    ; (A1) Create a hash table HT1 and associate it with the resulting alist.
    (assign a (hons-acons 'fn1 1 nil))

    ; (A2) Create a hash table HT2 and associate it with the resulting alist.
    ; (Minor observation: HT1 is no longer accessible.)
    (assign a (hons-acons 'fn1 1 nil))

    ; (B1) Update HT2 and associate it with the resulting alist.  Thus, H2 is
    ; no longer associated with (@ a).
    (assign b (hons-acons 'fn2 2 (@ a)))

    ; (B2) Fast alist warning (with a Lisp break, by default): discipline is
    ; violated because (@ a) no longer has a backing hash table.
    (assign b (hons-acons 'fn2 2 (@ a)))

    ; (C1) Fast alist warning/break: discipline is violated because (@ b) does not
    ; have a backing hash table.
    (assign c (hons-acons 'fn3 3 (@ b)))

    ; (C2) Fast alist warning/break: discipline is violated because (@ b) does not
    ; have a backing hash table.
    (assign c (hons-acons 'fn3 3 (@ b)))

  Now consider the following related example (in a fresh session),
  involving three [47m[encapsulate][0m events labeled A, B, and C.

    (encapsulate nil (defconst *a* (hons-acons 'fn1 1 nil))) ; (A)
    (encapsulate nil (defconst *b* (hons-acons 'fn2 2 *a*))) ; (B)
    (encapsulate nil (defconst *c* (hons-acons 'fn3 3 *b*))) ; (C)

  Each of these [47mencapsulate[0m events generates two calls of [47m[hons-acons][0m:
  one in the first pass of the [47mencapsulate[0m and one in the second
  pass.  With a little reflection you can see the connection between
  the two sequences of events above: [47mencapsulate[0m A makes assignments
  analogous to A1 (in its first pass) and A2 (in its second pass);
  similarly for B, B1, B2 and for C, C1, C2.  Thus, we get a slow
  alist warning/break on the second pass of B and on both passes of
  C.

  The simplest way to fix this problem is to call [47m[make-fast-alist][0m,
  which is essentially a no-op when its argument is already a fast
  alist.

    (encapsulate nil (defconst *a* (make-fast-alist (hons-acons 'fn1 1 nil))))
    (encapsulate nil (defconst *b* (make-fast-alist (hons-acons 'fn2 2 *a*))))
    (encapsulate nil (defconst *c* (make-fast-alist (hons-acons 'fn3 3 *b*))))

  We still see the warning/break in pass 2 of the second and third
  encapsulates, created by calls of [47m[hons-acons][0m exactly as before.
  However, the results of those two calls are converted to fast
  alists by [47mmake-fast-alist[0m; so after each [47mencapsulate[0m, the value of
  the defined constant is indeed a fast alist.  A problem still
  persists: the second and third [47m[defconst][0m event each steal the
  fast-alist value of the previous [47mdefconst[0m.  That's a problem that
  we won't try to solve here; we will just focus on how to ensure
  that the value of [47m*c*[0m is a fast alist.

  The following alternate solution has the advantage of avoiding the
  expense of reconstituting the fast alist during pass 2 of each of
  the [47mdefconst[0m events.  (We continue to use [47m[encapsulate][0m since
  otherwise the issue at hand dissolves.)

    (encapsulate nil (make-event `(defconst *a* ',(hons-acons 'fn1 1 nil))))
    (encapsulate nil (make-event `(defconst *b* ',(hons-acons 'fn2 2 *a*))))
    (encapsulate nil (make-event `(defconst *c* ',(hons-acons 'fn3 3 *b*))))

  These uses of [47m[make-event][0m cause each fast alist from pass 1 to be
  saved and then reused in pass 2.  There are no fast-alist warnings,
  and we avoid the expense of [47m[make-fast-alist][0m.")
 (SLOW-ARRAY-WARNING
  (ARRAYS)
  "A warning or error issued when [arrays] are used inefficiently

  If you use ACL2 [arrays] you may sometimes see a [31;1mslow array[0m warning.
  We explain below what that warning means and some likely
  ``mistakes'' it may signify.

  First, we note that you can control whether or not you get a warning
  and, if so, whether or not a break (error from which you can
  continue; see [break$]) ensues:

    (assign slow-array-action :warning) ; warn on slow array access (default)
    (assign slow-array-action :break)   ; warn as above, and then call break$
    (assign slow-array-action nil) ; do not warn or break on slow array access

  If you are using ACL2 arrays, then you probably care about
  performance, in which case it is probably best to avoid the [47mnil[0m
  setting.  Below we assume the default behavior: a warning, but no
  break.

  The discussion in the documentation for [arrays] defines what we mean
  by the semantic value of a name.  As noted there, behind the scenes
  ACL2 maintains the invariant that with some names there is
  associated a pair consisting of an ACL2 array [47malist[0m, called the
  semantic value of the name, and an equivalent raw lisp array.
  Access to ACL2 array elements, as in [47m(aref1 name alist i)[0m, is
  executed in constant time when the array alist is the semantic
  value of the name, because we can just use the corresponding raw
  lisp array to obtain the answer.  [47m[Aset1][0m and [47m[compress1][0m modify
  the raw lisp array appropriately to maintain the invariant.

  If [47m[aref1][0m is called on a name and alist, and the alist is not the
  then-current semantic value of the name, the correct result is
  computed but it requires linear time because the alist must be
  searched.  When this happens, [47m[aref1][0m prints a [31;1mslow array[0m warning
  message to the comment window.  [47m[Aset1][0m behaves similarly because
  the array it returns will cause the [31;1mslow array[0m warning every time
  it is used.

  From the purely logical perspective there is nothing ``wrong'' about
  such use of [arrays] and it may be spurious to print a warning
  message.  But because [arrays] are generally used to achieve
  efficiency, the [31;1mslow array[0m warning often means the user's
  intentions are not being realized.  Sometimes merely performance
  expectations are not met; but the message may mean that the
  functional behavior of the program is different than intended.

  Here are some ``mistakes'' that might cause this behavior.  In the
  following we suppose the message was printed by [47m[aset1][0m about an
  array named [47mname[0m.  Suppose the alist supplied [47m[aset1][0m is [47malist[0m.

  (1) [47m[Compress1][0m was never called on [47mname[0m and [47malist[0m.  That is, perhaps
  you created an alist that is an [47m[array1p][0m and then proceeded to
  access it with [47m[aref1][0m but never gave ACL2 the chance to create a
  raw lisp array for it.  After creating an alist that is intended
  for use as an array, you must do [47m(compress1 name alist)[0m and pass
  the resulting [47malist'[0m as the array.

  (2) [47mName[0m is misspelled.  Perhaps the array was compressed under the
  name [47m'delta-1[0m but accessed under [47m'delta1[0m?

  (3) An [47m[aset1][0m was done to modify [47malist[0m, producing a new array,
  [47malist'[0m, but you subsequently used [47malist[0m as an array.  Inspect all
  [47m(aset1 name ...)[0m occurrences and make sure that the alist modified
  is never used subsequently (either in that function or any other).
  It is good practice to adopt the following syntactic style.
  Suppose the alist you are manipulating is the value of the local
  variable [47malist[0m.  Suppose at some point in a function definition you
  wish to modify [47malist[0m with [47m[aset1][0m.  Then write

    (let ((alist (aset1 name alist i val))) ...)

  and make sure that the subsequent function body is entirely within
  the scope of the [47m[let][0m.  Any uses of [47malist[0m subsequently will refer
  to the new alist and it is impossible to refer to the old alist.
  Note that if you write

    (foo (let ((alist (aset1 name alist i val))) ...)  ; arg 1
         (bar alist))                                  ; arg 2

  you have broken the rules, because in [47marg 1[0m you have modified [47malist[0m
  but in [47marg 2[0m you refer to the old value.  An appropriate rewriting
  is to lift the [47m[let][0m out:

    (let ((alist (aset1 name alist alist i val)))
      (foo ...                                         ; arg 1
           (bar alist)))                               ; arg 2

  Of course, this may not mean the same thing.

  (4) A function which takes [47malist[0m as an argument and modifies it with
  [47m[aset1][0m fails to return the modified version.  This is really the
  same as (3) above, but focuses on function interfaces.  If a
  function takes an array [47malist[0m as an argument and the function uses
  [47m[aset1][0m (or a subfunction uses [47m[aset1][0m, etc.), then the function
  probably ``ought'' to return the result produced by [47m[aset1][0m.  The
  reasoning is as follows.  If the array is passed into the function,
  then the caller is holding the array.  After the function modifies
  it, the caller's version of the array is obsolete.  If the caller
  is going to make further use of the array, it must obtain the
  latest version, i.e., that produced by the function.")
 (SOLUTION-TO-ACL2-QUANTIFIER-EXERCISE-2
  (QUANTIFIER-TUTORIAL)
  "A solution to [47m[quantifier-tutorial][0m Exercise 2

  In [quantifier-tutorial] exercise 2, it asks if we can prove or
  disprove the conjecture below.

    [31;1mExercise 2[0m. If there is an ACL2 object [47mx[0m which satisfies [47mM[0m, then
    there exists a least ACL2 object [47my[0m that satisfies [47mM[0m.

  This hypothesis can be disproved. Here is one possible solution,
  provided by Yan Peng..

    (in-package \"ACL2\")
    (include-book \"misc/total-order\" :dir :system)

    ;; This hypothesis can be disproved.
    ;; The intuition: find a function M that can be satisfied and does not have a
    ;; minimal object that satisfies it.

    ;; For example, if M is evenp, then for any ACL2 object that satisfies M, one
    ;; can always construct a smaller object by subtracting 2 from it, which also
    ;; satisfies M.

    ;; Instead of using defstub, we provide an implementation for M which calls
    ;; evenp.
    (defun M (x) (evenp x))

    ;; We prove a helper lemma that says if x satisfies M, then (- x 2) also
    ;; satisfies M and it is a smaller object.
    (defthm -2-satisfies-M-and-<<
      (implies (M x)
               (and (M (- x 2)) (<< (- x 2) x)))
      :hints ((\"Goal\"
               :in-theory (enable << lexorder alphorder))))
    (in-theory (disable evenp M))

    (defun-sk some-M () (exists x (M x)))
    (in-theory (disable some-M some-M-suff))

    ;; We prove M can be satisfied by providing a witness 0.
    (defthm some-M-lemma
      (some-M)
      :hints ((\"Goal\" :use ((:instance some-M-suff (x 0))))))

    ;; We negate none-below-2
    (defun-sk exists-below (y)
      (exists r (and (<< r y) (M r))))
    (in-theory (disable exists-below exists-below-suff))

    ;; We negate min-M2
    (defun-sk not-min-M () (forall y (implies (M y) (exists-below y))))
    (in-theory (disable not-min-M not-min-M-necc))

    ;; We prove that forall y, if y satisfies M, then there exists another smaller
    ;; object that satisfies M.
    (defthm not-min-M-lemma
      (not-min-M)
      :hints ((\"Goal\"
               :use (;; The definition of not-min-M provides a witness
                     ;; (not-min-M-witness) that satisfies M but doesn't satisfy
                     ;; exists-below.
                     (:instance (:definition not-min-M))
                     ;; By instantiating exists-below-suff, we provide a smaller
                     ;; object r:(- (not-min-M-witness) 2) than
                     ;; y:(not-min-M-witness), and satisfies M. This makes
                     ;; (not-min-M-witness) vacuous, allowing us to prove the
                     ;; forall.
                     (:instance exists-below-suff
                                (r (- (not-min-M-witness) 2))
                                (y (not-min-M-witness)))))))

    ;; We prove both some-M and not-min-M
    (defthm |minimal does not exist|
      (and (some-M) (not-min-M)))")
 (SOLUTION-TO-SIMPLE-EXAMPLE
  (ANNOTATED-ACL2-SCRIPTS)
  "Solution to a simple example

  To see a statement of the problem solved below, see
  [annotated-ACL2-scripts] (in particular the end of that topic).

  Here is a sequence of ACL2 [events] that illustrates the use of ACL2
  to make definitions and prove theorems.  We will introduce the
  notion of the fringe of a tree, as well as the notion of a leaf of
  a tree, and then prove that the members of the fringe are exactly
  the leaves.

  We begin by defining the fringe of a tree, where we identify trees
  simply as [cons] structures, with [atom]s at the leaves.  The
  definition is recursive, breaking into two cases.  If [47mx[0m is a
  [cons], then the [47mfringe[0m of [47mx[0m is obtained by appending together the
  [47mfringe[0ms of the [47m[car][0m and [47m[cdr][0m (left and right child) of [47mx[0m.
  Otherwise, [47mx[0m is an [atom] and its [47mfringe[0m is the one-element list
  containing only [47mx[0m.

    (defun fringe (x)
      (if (consp x)
          (append (fringe (car x))
                  (fringe (cdr x)))
        (list x)))

  Now that [47mfringe[0m has been defined, let us proceed by defining the
  notion of an atom appearing as a ``leaf'', with the goal of proving
  that the leaves of a tree are exactly the members of its [47mfringe[0m.

    (defun leaf-p (atm x)
      (if (consp x)
          (or (leaf-p atm (car x))
              (leaf-p atm (cdr x)))
        (equal atm x)))

  The main theorem is now as follows.  Note that the rewrite rule below
  uses the equivalence relation [47m[iff][0m (see [equivalence]) rather than
  [47m[equal][0m, since [47m[member][0m returns the tail of the given list that
  begins with the indicated member, rather than returning a Boolean.
  (Use [47m:pe member[0m to see the definition of [47m[member][0m.)

    (defthm leaf-p-iff-member-fringe
      (iff (leaf-p atm x)
           (member-equal atm (fringe x))))")
 (SOUNDNESS
  (ABOUT-ACL2)
  "Correctness property claimed for ACL2

  What can we conclude when we use ACL2 to prove a formula or to
  compute the value of an expression?  This topic provides a
  high-level sketch of an answer.


Overview of the ACL2 logic

  Any notion of correctness of ACL2 necessarily depends on the logic
  that it is intended to implement.  At its core, the ACL2 logic is
  just classical first-order logic.  The first-order theory for a
  given ACL2 session, which we may call the ``prover's theory'', is
  the result of extending its set of built-in axioms according to
  [events] that have been executed in the session.

    * The built-in axioms describe properties of the ACL2 data types, such
      as the following.

          ACL2 !>:pe car-cons
                 -8139  (DEFAXIOM CAR-CONS
                          (EQUAL (CAR (CONS X Y)) X))
          ACL2 !>

    * A key extension principle is the Principle of Definition, which, for
      a definition [47m(defun <fn> <args> <body>)[0m, introduces an axiom
      equating [47m<body>[0m with application of [47m<fn>[0m to [47m<args>[0m.  This
      principle permits recursion, and even [mutual-recursion],
      provided a suitable [3mmeasure conjecture[0m is provable.

    * Other [events] come with extension principles too, including
      [47m[encapsulate][0m, [47m[defchoose][0m, [47m[defpkg][0m, and [47m[include-book][0m.  Note
      that from a logical perspective, [47m[defstobj][0m and [47m[defabsstobj][0m
      just provide definitional extensions.

    * Each ACL2 theory is [3mclosed under induction[0m: that is, every instance
      of induction (in the language of the theory) below the ordinal
      [47mepsilon-0[0m (see [ordinals]) is also in the theory.  In practical
      terms, this is what allows ACL2 to prove theorems by induction.

  For more about the ACL2 logic see the following publications by Matt
  Kaufmann and J Moore.

    * {``A Precise Description of the ACL2 Logic'' |
      http://www.cs.utexas.edu/users/moore/publications/km97a.pdf}
      (April, 1998).

    * {``Structured Theory Development for a Mechanized Logic'' |
      https://www.cs.utexas.edu/users/moore/publications/encap-story.pdf},
      [3mJournal of Automated Reasoning[0m 26, no. 2 (2001) 161-203.


The soundness property for ACL2 sessions

  The following soundness property is key for a given ACL2 session.

    The theorem prover proves only formulas that are theorems in the
    corresponding prover's theory in that session.

  Note that the theorem prover uses evaluation during proofs.  The
  soundness property thus encompasses the following: when such
  evaluation of a term [47mtm[0m produces a value [47mv[0m, then [47m(equal tm 'v)[0m is
  provable from the context of that evaluation.  Evaluation in the
  top-level loop has such a property as well, but because of
  attachments (see [defattach]) and [47m[apply$][0m, provability is with
  respect to a larger ``evaluation theory''; see
  [guarantees-of-the-top-level-loop].


Constraints on the soundness guarantee

  Here is a list of constraints on the soundness guarantee.

    * The prover's theory of a session is construed to include all axioms
      introduced by hidden [defpkg] events.  See
      [hidden-death-package].

    * There is no soundness guarantee for a session in which there is raw
      Lisp evaluation with side effects.  (ACL2 normally avoids
      putting the user into raw Lisp, but this can happen with an
      interrupt, the use of [47m[break$][0m, or explicitly leaving the
      top-level loop with [47m:[0m[47m[q][0m.)  ``Side effects'' should be
      interpreted as generously as possible: this certainly includes
      redefining a function or assigning to a variable, but not
      merely evaluating an arithmetic expression, for example.

    * There is no soundness guarantee for a session in which any trust tag
      has been installed (see [defttag]).  The absence of trust tags
      is guaranteed by the absence of ``[47mTTAG NOTE[0m'' being printed to
      standard output (that is, to [47m[*standard-co*][0m).

    * The soundness guarantee only applies when a set of books is certified
      from scratch, including [community-books], in a single
      environment --- in particular, with the same Lisp
      implementation and operating system.  (In practice this is
      often not an issue.)


Examples of divergence among Lisp implementations

  Next, we provide examples illustrating the last point above,
  restricting to the use of a single Lisp.

  [31;1mExample 1: Divergences involving character and string operations.[0m

  Consider the following log in raw Lisp using SBCL, which introduces
  versions of characters ``[47mA[0m'' and ``[47ma[0m'' that are augmented with an
  ``acute'' accent.

    * (code-char 193)
    #LATIN_CAPITAL_LETTER_A_WITH_ACUTE
    * (code-char 225)
    #LATIN_SMALL_LETTER_A_WITH_ACUTE
    *

  While most Lisps that host ACL2 consider these two characters to be
  alphabetic characters with case (upper and lower, respectively),
  GCL does not (at least, a version available as of this writing).

    (alpha-char-p (code-char 193)) ; T except NIL in GCL
    (alpha-char-p (code-char 225)) ; T except NIL in GCL
    (upper-case-p (code-char 193)) ; T except NIL in GCL
    (lower-case-p (code-char 225)) ; T except NIL in GCL
    (char-code (char-downcase (code-char 193))) ; 225 except 193 in GCL
    (char-code (char-upcase (code-char 225)))   ; 193 except 225 in GCL
    (let ((s (string-downcase (string (code-char 193)))))
      (char-code (char s 0)))      ; 225 except 193 in GCL
    (let ((s (string-upcase (string (code-char 225)))))
      (char-code (char s 0)))      ; 193 except 225 in GCL

  [31;1mExample 2: Another divergence for [47m[alpha-char-p][0m[31;1m.[0m

    ; True in SBCL 2.4.2, about the character it calls #MICRO_SIGN,
    ; but false in LispWorks 8.0.1:
    (alpha-char-p (code-char 181))

    ; False in SBCL 2.4.2, about the character it calls #CENT_SIGN,
    ; but true in Allegro CL 10.1:
    (alpha-char-p (code-char 162))

  [31;1mExample 3: A divergence involving a floating-point computation.[0m

  Here is another example illustrating the requirement on a single
  Lisp.  In ACL2 built on most host Lisp implementations, one can
  admit the following event.  (See [df] for background on
  floating-point computations with ACL2.)

    (defthm usual-sin-2pi
      (equal (df-sin (df* 2 *df-pi*))
             #d-2.4492935982947064E-16))

  But in ACL2 built on LispWorks, one can instead admit the following.

    (defthm lispworks-sin-2pi
      (equal (df-sin (df* 2 *df-pi*))
             #d-2.4492127076447545E-16))

  Clearly one could prove [47mnil[0m by including two books, one containing
  each of these theorems.  (Aside: This does not violate the IEEE-754
  spec, since it does not make specific requirements for
  trigonometric functions.)


Further reading for those interested in drilling down

  This topic has discussed the soundness guarantee from the user
  perspective.  Those interested in exploring deeper theoretical and
  implementation issues are welcome to read the extensive relevant
  comments in the ACL2 source code, including the comments labeled as
  follows (listed in order of appearance as of this writing, not to
  indicate the order in which to read them).

    * Essay on Admitting a Model for Apply$ and the Functions that Use It

    * Essay on Hidden Packages

    * Essay on Soundness Threats

    * Essay on a Total Order of the ACL2 Universe

    * Essay on Illegal-states

    * Essay on Evaluation in ACL2

    * Essay on the Logical Basis for Linear Arithmetic

    * Essay on the Correctness of Abstract Stobjs

    * Essay on Memoization with Partial Functions (Memoize-partial)

    * Essay on Correctness of Evaluation with Stobjs

    * Essay on Correctness of Meta Reasoning


Subtopics

  [Guarantees-of-the-top-level-loop]
      Guarantees provided by top-level evaluation")
 (SPEC-MV-LET
  (PARALLEL-PROGRAMMING ACL2-BUILT-INS)
  "Modification of [47m[mv-let][0m supporting speculative and parallel
  execution

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism],
  and see [parallel-programming], which has a disclaimer.

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

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

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

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

  The calls to [47mmv-let[0m and to [47mif[0m displayed above in the General Form are
  an essential part of the design of [47mspec-mv-let[0m, and are thus
  required.

  The following definition of [47mfib-with-step-count[0m completes the example
  above:

    (defun fib-with-step-count (x)
    (declare (xargs :mode :program))
    (cond ((<= x 0)
           (mv 0 1))
          ((= x 1) (mv 1 1))
          (t (mv-let (a cnt1)
                     (fib-with-step-count (- x 1))
                     (mv-let (b cnt2)
                             (fib-with-step-count (- x 2))
                             (mv (+ a b)
                                 (+ 1 cnt1 cnt2)))))))")
 (SPECIAL-CASES-FOR-REWRITE-RULES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Convenient short forms for rewrite rule formulas

  In principle, every rewrite rule is made from a formula of this
  shape:

    (IMPLIES (AND [3mhyp1[0m ... [3mhypk[0m)
             ([3meqv[0m [3mlhs[0m [3mrhs[0m))

  where [3meqv[0m is either [47mEQUAL[0m or [47mIFF[0m and the result of expanding any
  abbreviations in [3mlhs[0m is the application of some function symbol
  other than [47mIF[0m.

  * In the special case where there is only one [3mhyp[0m term, i.e., [3mk[0m=1,
  the [47m(AND[0m [3mhyp1[0m[47m)[0m can be written [3mhyp1[0m.

  * In the special case where there are no [3mhyp[0m terms, [3mk[0m=0, the [47m(AND)[0m
  term is logically just [47mT[0m and the whole [47mIMPLIES[0m can be dropped; such
  a formula may be written as an unconditional [47mEQUAL[0m or [47mIFF[0m term.

  * If you build a rewrite rule from a formula that concludes with [47m(NOT[0m
  [3mx[0m[47m)[0m, it is treated as though it were [47m(EQUAL[0m [3mx[0m [47mNIL)[0m, which is
  logically equivalent to what you typed.

  * If you build a rewrite rule from a formula that concludes with an
  [47mAND[0m, ACL2 will build a rewrite rule for each conjunct of the [47mAND[0m.
  This is because

    (IMPLIES hyp (AND concl1 concl2))

  is propositionally equivalent to

    (AND (IMPLIES hyp concl1)
         (IMPLIES hyp concl2)).

  However, if you use an [47mOR[0m-expression as a hypothesis, ACL2 does [3mnot[0m
  do the dual transformation.  Thus, [47m(IMPLIES (OR hyp1 hyp2) concl)[0m
  generates one rewrite rule.

  * Finally, if you build a rewrite rule from a formula that does not
  conclude with an [47mEQUAL[0m, an [47mIFF[0m, a [47mNOT[0m, or an [47mAND,[0m but with some
  other term, say, [3mlhs[0m, then ACL2 acts like you typed [47m(IFF[0m [3mlhs[0m [47mT)[0m,
  which is logically equivalent to what you typed.

  Thus, regardless of what you type, every rule has [3mk[0m hypotheses.  For
  unconditional rules, [3mk[0m is 0 and the hypotheses are vacuously true.
  Whether or not you write an [47mEQUAL[0m or an [47mIFF[0m in the conclusion,
  every rule is either an equality or a propositional equivalence,
  every rule has a left-hand side, and every rule has a right-hand
  side.

  Use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-rewrite-rules-part-1].")
 (SPECIFIC-KINDS-OF-FORMULAS-AS-REWRITE-RULES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Advice about how to handle commonly occurring formulas as rewrite
  rules

  Below we give you some guidelines for handling specific, commonly
  occurring situations.

  * [31;1mAssociativity[0m: If a function [47mf[0m is associative, prove

    (equal (f (f x y) z) (f x (f y z)))

  ACL2 will use this to flatten [47mf[0m-nests ``to the right.''

  * [31;1mCommutativity[0m: If a function [47mf[0m is commutative, prove both

    (equal (f x y) (f y x))

  and

    (equal (f x (f y z)) (f y (f x z)))

  ACL2's heuristics will use these rules to order the arguments
  alphabetically, so that [47m(f B (f D (f A C)))[0m becomes [47m(f A (f B (f C
  D)))[0m.

  * [31;1mDistributivity[0m: If you have a pair of functions [47mf[0m and [47mg[0m so that [47m(f
  x (g y z))[0m is [47m(g (f x y) (f x z))[0m or some other form of
  distributivity is provable, arrange your rules to move the lighter
  function symbol up and the heavier one toward the variable symbols.
  For example, our arithmetic libraries drive multiplication through
  addition, producing sums of products rather than products of sums.

  * [31;1mIdentity and Other Laws[0m: Prove the obvious identity and zero laws
  (or at least anticipate that you might need them down the road) so
  as to eliminate operators.

  * [31;1mGet Rid of Tail Recursive Functions[0m: A corollary to the above
  advice concerns tail recursive functions that use auxiliary
  variables.  New users often define concepts using tail recursions,
  accumulating partial results in auxiliary variables, because
  creating such functions is similar to programming with [47mwhile[0m loops.
  Expert users will use tail recursion when necessary for execution
  efficiency.  But tail recursive functions are messy to reason
  about: their auxiliary variables have to be properly initialized to
  make the functions compute the expected results, but to state
  inductively provable properties of tail recursive functions you
  must identify the invariants on those auxiliary variables.  This
  problem tends not to happen with [3mprimitive recursive functions[0m.  A
  primitive recursive function is one that recurs down one variable
  and holds all the other variables constant in recursion.  Most
  tail-recursive functions can be written elegantly as primitive
  recursive functions, though one might have to ignore the
  programmer's desire to make things efficient and define auxiliary
  functions to appropriately transform the value returned by the
  recursive call.  The classic example is reverse defined in terms of
  the auxiliary function [47mappend[0m versus reverse defined tail
  recursively with an accumulator.  By introducing [47mappend[0m you
  introduce a concept about which you can state lemmas and decompose
  the proofs of properties of reverse.  So if your problem involves
  tail recursive functions with auxiliary variables, define the
  primitive recursive version, prove that the tail recursive function
  is equivalent to the primitive recursive one, and arrange the
  rewrite rule to eliminate the tail recursive function.

  * [31;1mGet Rid of Mutually Recursive Functions[0m: Similarly, if you have
  used [47mmutual-recursion[0m to introduce a clique of mutually recursive
  functions, [47mf1[0m, [47mf2[0m, ..., you will find that to reason about any one
  function in the nest you have to reason about all of them.  Any
  mutually recursive function can be defined in a singly recursive
  way.  So do that and then prove a rewrite rule that gets rid of all
  the mutually recursive functions by proving

    (and (equal (f1 ...) (g1 ...))
         (equal (f2 ...) (g2 ...))
         ...)

  where the [47mgi[0m are singly recursive.  You may need to appeal to a trick
  to define the [47mgi[0m: define a singly recursive function that takes a
  flag argument and mimics whichever mutually recursive function the
  flag specifies.  See [mutual-recursion] {ICON} (see
  [A_Tiny_Warning_Sign]) and see [mutual-recursion-proof-example]
  {ICON} (see [A_Tiny_Warning_Sign]).

  If you got to this documentation page from the tutorial discussion of
  rewrite rules, use your browser's [31;1mBack Button[0m now to return to
  [introduction-to-rewrite-rules-part-2].")
 (SPECIOUS-SIMPLIFICATION
  (MISCELLANEOUS)
  "Nonproductive proof steps

  Occasionally the ACL2 theorem prover reports that the current goal
  simplifies to itself or to a set including itself.  Such
  simplifications are said to be ``specious'' and are ignored in the
  sense that the theorem prover acts as though no simplification were
  possible and tries the next available proof technique.  Specious
  simplifications are almost always caused by the use of [47m[force][0m or
  [47m[case-split][0m.

  The simplification of a formula proceeds primarily by the local
  application of [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[type-prescription][0m, and other rules to
  its various subterms.  If no rewrite rules apply, the formula
  cannot be simplified and is passed to the next ACL2 proof
  technique, which is generally the elimination of destructors.  The
  experienced ACL2 user pays special attention to such ``maximally
  simplified'' formulas; the presence of unexpected terms in them
  indicates the need for additional rules or the presence of some
  conflict that prevents existing rules from working harmoniously
  together.

  However, consider the following interesting possibility: local
  rewrite rules apply but, when applied, reproduce the goal as one of
  its own subgoals.  How can rewrite rules apply and reproduce the
  goal?  Of course, one way is for one rule application to undo the
  effect of another, as when commutativity is applied twice in
  succession to the same term.  Another kind of example is when two
  rules conflict and undermine each other.  For example, under
  suitable hypotheses, [47m(length x)[0m might be rewritten to [47m(+ 1 (length
  (cdr x)))[0m by the [47m:[0m[47m[definition][0m of [47m[length][0m and then a [47m:[0m[47m[rewrite][0m
  rule might be used to ``fold'' that back to [47m(length x)[0m.  Generally
  speaking the presence of such ``looping'' rewrite rules causes
  ACL2's simplifier either to stop gracefully because of heuristics
  such as that described in the documentation for [47m[loop-stopper][0m or
  to cause a stack overflow because of indefinite recursion.

  A more insidious kind of loop can be imagined: two rewrites in
  different parts of the formula undo each other's effects ``at a
  distance,'' that is, without ever being applied to one another's
  output.  For example, perhaps the first hypothesis of the formula
  is simplified to the second, but then the second is simplified to
  the first, so that the end result is a formula propositionally
  equivalent to the original one but with the two hypotheses
  commuted.  This is thought to be impossible unless forcing or
  case-splitting occurs, but if those features are exploited (see
  [force] and see [case-split]) it can be made to happen relatively
  easily.

  Here is a simple example.  Declare [47mfoo[0m to be a function of one
  argument returning one result:

    (defstub p1 (x) t)

  Prove the following silly rule:

    (defthm bad
      (implies (case-split (p1 x))
               (p1 x)))

  Now suppose we try the following.

    (thm (p1 x))

  The [rewrite] rule [47mbad[0m will rewrite [47m(p1 x)[0m to [47mt[0m, but it will be
  unable to prove the hypothesis [47m(case-split (p1 x))[0m.  As a result,
  the prover will spawn a new goal, to prove [47m(p1 x)[0m.  However, since
  this new goal is the same as the original goal, ACL2 will recognize
  the simplification as [3mspecious[0m and consider the attempted
  simplification to have failed.

  In other words, despite the rewriting, no progress was made!  In more
  common cases, the original goal may simplify to a set of subgoals,
  one of which includes the original goal.

  If ACL2 were to adopt the new set of subgoals, it would loop
  indefinitely.  Therefore, it checks whether the input goal is a
  member of the output subgoals.  If so, it announces that the
  simplification is ``specious'' and pretends that no simplification
  occurred.

  ``Maximally simplified'' formulas that produce specious
  simplifications are maximally simplified in a very technical sense:
  were ACL2 to apply every applicable rule to them, no progress would
  be made.  Since ACL2 can only apply every applicable rule, it
  cannot make further progress with the formula.  But the informed
  user can perhaps identify some rule that should not be applied and
  make it inapplicable by disabling it, allowing the simplifier to
  apply all the others and thus make progress.

  When specious simplifications are a problem it might be helpful to
  [disable] rules involved in forcing (including case-splits; see
  [force] and see [case-split]).  For the example above we see the
  following output; and in fact, a hint to disable [47mBAD[0m will avoid the
  specious simplification (although the proof will still fail).

      Splitter note (see :DOC splitter) for Goal (0 subgoals).
        case-split: ((:REWRITE BAD))

  A more drastic possibility is to disable all forcing (including
  [case-split]s) and resubmit the formula to observe whether forcing
  is involved in the loop or not.  The commands

    ACL2 !>:disable-forcing
    and
    ACL2 !>:enable-forcing

  [disable] and [enable] the pragmatic effects of both [47mforce[0m and
  [47mcase-split[0m.  If the loop is broken when forcing is [disable]d, then
  it is very likely some [force]d hypothesis of some rule is
  ``undoing'' a prior simplification.  The most common cause of this
  is when we [force] a hypothesis that is actually false but whose
  falsity is somehow temporarily hidden (more below).  To find the
  offending rule, compare the specious simplification with its
  non-specious counterpart and look for rules that were speciously
  applied that are not applied in the non-specious case.  Most likely
  you will find at least one such rule and it will have a [47m[force][0md
  hypothesis.  By disabling that rule, at least for the subgoal in
  question, you may allow the simplifier to make progress on the
  subgoal.")
 (SPLIT-TYPES
      (POINTERS)
      "See [xargs] for information about the keyword [47m:split-types[0m.")
 (SPLITTER
  (DEBUGGING)
  "Reporting of rules whose application may have caused case splits

  When the ACL2 rewriter applies a rule to a term, a goal might
  simplify to more than one subgoal.  A rule with such an application
  is called a ``splitter''.  Here, we explain the output produced for
  splitters when proof output is enabled (see
  [set-inhibit-output-lst]) and such reporting is turned on (as it is
  by default) --- that is, when the value of [47m([0m[47m[splitter-output][0m[47m)[0m is
  true.

  See [set-splitter-output] for how to turn off, or on, the reporting
  of splitters.  Also see [set-case-split-limitations] for
  information on how to control case splits.  Note that since
  splitters are rule applications, splitter output is not generated
  for case splits that are caused by other than rules, such as the
  mere presence of calls of the function symbol, [47m[if][0m, in the goal.

  We begin by describing three types of splitters.

      [47mif-intro[0m: The rule application may have introduced a call of [47mIF[0m, in
      the sense discussed at the end below.

      [47mcase-split[0m: For the application of a rule with hypothesis of the form
      [47m(case-split <hyp>)[0m, [47m<hyp>[0m did not simplify to true or false.

      [47mimmed-forced[0m: For the application of a rule with hypothesis of the
      form [47m(force <hyp>)[0m, [47m<hyp>[0m did not simplify to true or false,
      where immediate-force-modep is enabled (see
      [immediate-force-modep]).

  These three annotations --- [47mif-intro[0m, [47mcase-split[0m, and [47mimmed-forced[0m
  --- may be used in proof output and summaries for describing rule
  applications, as discussed below.  A fourth annotation, [47mforced[0m, may
  also be used in proof output to indicate the application of a rule
  with hypothesis of the form [47m(force <hyp>)[0m when [47m<hyp>[0m did not
  simplify to true or false, where immediate-force-modep is disabled
  (see [immediate-force-modep]).  We don't consider such uses of
  [47m[force][0m to be splitters, because they do not cause case splits
  (though they do produce goals to prove after lower-case ``q.e.d.''
  is printed); see [force].

  There are three kinds of output affected by splitters, illustrated in
  turn below using examples.

      (a) During the proof, [gag-mode] and raw proof format (see
      [set-raw-proof-format]) off
      (b) During the proof, [gag-mode] or raw proof format on
      (c) [Summary]

  Of course, (a) and (b) are skipped if proof output is inhibited, and
  (c) is skipped if [summary] output is inhibited; see
  [set-inhibit-output-lst].

  (a) During the proof, [gag-mode] and raw proof format (see
  [set-raw-proof-format]) off

  With [gag-mode] off (or when using [47m:[0m[47m[pso][0m, [47m:[0m[47m[psof][0m, or [47m:[0m[47m[psog][0m) one
  normally gets an English commentary.  The following output
  indicates that at least one application of each rule [47mF[0m and [47mG[0m is of
  type [47mif-intro[0m, at least one application of rules [47mG[0m and [47mR1[0m are of
  type [47mcase-split[0m, and at least one application of rule [47mR3[0m is of type
  [47mimmed-forced[0m.  If [immediate-force-modep] is off then
  ``[47mimmed-forced[0m'' would be replaced by ``[47mforced[0m''.

    This simplifies, using the :definitions F (if-intro), G (case-split and
    if-intro) and H and the :rewrite rules R1, R2 (case-split), and
    R3 (immed-forced), to the following two conjectures.

  Note that any such printing of ``[47mforced[0m'' is done even if
  [47m(splitter-output)[0m is false.

  (b) During the proof, [gag-mode] or raw proof format on

  With [gag-mode] or raw proof format (see [set-raw-proof-format]) on,
  the proof output is abbreviated.  However, in these cases
  ``Splitter Notes'' are printed so that one can still get important
  information to help control large case splits (by disabling
  splitter rules as appropriate).  These are printed at the point
  when a goal splits into subgoals.  Here, for example, is the
  Splitter Note that corresponds to the output shown in (a) above.
  It shows the goal whose simplification has produced a split into
  more than one subgoal, and it shows how many subgoals have been
  created.

    Splitter note (see :DOC splitter) for Subgoal *1/2.2.1' (2 subgoals).
      case-split: ((:DEFINITION G) (:REWRITE R2))
      immed-forced: ((:REWRITE R3))
      if-intro: ((:DEFINITION G) (:DEFINITION F))

  No such splitter notes are printed for the use of [47m[force][0m (when
  [immediate-force-modep] is off).

  (c) [Summary]

  Here is a possible summary corresponding to our running example.  In
  the summary, ``Splitter rules'' is omitted if there are no splitter
  rules, and a splitter type is only mentioned if there is at least
  one corresponding splitter rule.

    Summary
    Form:  ( THM ...)
    Rules: ((:DEFINITION F)
            (:DEFINITION G)
            (:DEFINITION H)
            (:REWRITE R1)
            (:REWRITE R2)
            (:REWRITE R3))
    Splitter rules (see :DOC splitter):
      case-split: ((:DEFINITION G) (:REWRITE R2))
      immed-forced: ((:REWRITE R3))
      if-intro: ((:DEFINITION G) (:DEFINITION F))
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.00)
    Prover steps counted:  145

  No indication for ``[47mforced[0m'' is given for ``Splitter rules''.  (As
  discussed earlier above, the [47m[force][0md hypotheses are not considered
  relevant for determining splitter rule applications unless
  [immediate-force-modep] is on.)

  We conclude by giving the criteria for a [rewrite] or [definition]
  rule application to be a splitter of type [47mif-intro[0m.

    * Reporting of splitter rules is on, i.e., the value of
      [47m([0m[47m[splitter-output][0m[47m)[0m is true.

    * At least two subgoals are created, even before considering subgoals
      generated by hypotheses that are calls of [47m[case-split][0m or
      [47m[force][0m.

    * The term to which the rule is applied is at the top level, rather
      than being encountered when trying to establish the hypothesis
      of a rule.

    * The rule is a [rewrite] rule, a [definition] rule, or a [meta] rule.

    * There is a call of the function symbol [47mIF[0m in the right-hand side of
      the [rewrite] rule; or, in the case of a [definition] rule, in
      the body of the definition; or, in the case of a [meta] rule,
      in the result of applying the metafunction.

    * There is a call of the function symbol [47mIF[0m in the result of rewriting:
      the right-hand side (for a [rewrite] rule), the definition body
      (for a [definition] rule), or the metafunction application (for
      a [meta] rule).

  Any rule application meeting the above criteria will be considered a
  splitter of type [47mif-intro[0m, even if the call does not actually cause
  a case split.  For example, if you are proving [47m(implies (hyp x)
  (conc x))[0m and rule R rewrites [47m(hyp x)[0m to [47m(if (h1 x) (h2 x) nil)[0m,
  which is really the term [47m(and (h1 x) (h2 x))[0m, then R may be labeled
  as a splitter rule.  If you want to find the causes of
  case-splitting, the list of [47mif-intro[0m splitters can help you narrow
  your search, but may include irrelevant rules as well.

  Finally, note that you may see splits not attributed to splitters.
  We believe that this will be uncommon during simplification, though
  it can occur for example when a call of [47mIF[0m is in the body of a
  [47m[let][0m expression, i.e., in a call of a [47m[lambda][0m expression.  But
  splits caused by other processes, notably destructor elimination
  (see [elim]), will typically not be attributed to splitters.


Subtopics

  [Set-splitter-output]
      Turn on or off reporting of rules that may have caused case splits

  [Splitter-output]
      Status for reporting of [splitter] rules")
 (SPLITTER-OUTPUT
  (SPLITTER)
  "Status for reporting of [splitter] rules

  See [splitter] for a discussion of splitter rules.  See
  [set-splitter-output] for how to turn off, or on, the reporting of
  splitter rules.  When splitter-output is off, because either [47mprove[0m
  output is inhibited (see [set-inhibit-output-lst]) or
  [47m([0m[47m[set-splitter-output][0m[47m nil)[0m has been invoked, then the value of
  [47m(splitter-output)[0m is [47mnil[0m.  Otherwise, such reporting is on and the
  value is non-[47mnil[0m.")
 (STABLE-UNDER-SIMPLIFICATIONP (POINTERS)
                               "See [computed-hints].")
 (STANDARD-CHAR-LISTP
  (CHARACTERS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of standard characters

  [47m(standard-char-listp x)[0m is true if and only if [47mx[0m is a [47mnil[0m-terminated
  list all of whose members are standard [characters].  See
  [standard-char-p].

  [47mStandard-char-listp[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<standard-char-listp>

    (defun standard-char-listp (l)
      (declare (xargs :guard t))
      (cond ((consp l)
             (and (characterp (car l))
                  (standard-char-p (car l))
                  (standard-char-listp (cdr l))))
            (t (equal l nil))))")
 (STANDARD-CHAR-P
  (CHARACTERS ACL2-BUILT-INS)
  "Recognizer for standard characters

  [47m(Standard-char-p x)[0m is true if and only if [47mx[0m is a ``standard''
  character, i.e., a member of the list [47m*standard-chars*[0m.  This list
  includes [47m#\\Newline[0m and [47m#\\Space[0m [characters], as well as the usual
  punctuation and alphanumeric [characters].

  [47mStandard-char-p[0m has a [guard] requiring its argument to be a
  character.

  [47mStandard-char-p[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<standard-char-p>

    (defun standard-char-p (x)
      (declare (xargs :guard (characterp x)))
      (if (member x *standard-chars*) t nil))


Subtopics

  [Standard-char-p+]
      Recognizer for standard characters whose guard is [47mt[0m")
 (STANDARD-CHAR-P+
  (STANDARD-CHAR-P CHARACTERS ACL2-BUILT-INS)
  "Recognizer for standard characters whose guard is [47mt[0m

  Logically [47mstandard-char-p+[0m is the same as [47m[standard-char-p][0m.
  However, [47mstandard-char-p+[0m has a guard of [47mt[0m, while [47mstandard-char-p[0m
  is guarded by [47m[characterp][0m.

  [31;1mFunction: [0m<standard-char-p+>

    (defun standard-char-p+ (x)
      (declare (xargs :guard t))
      (and (characterp x)
           (standard-char-p x)))")
 (STANDARD-CO
  (IO ACL2-BUILT-INS)
  "The character output channel to which [47m[ld][0m prints

  [47mStandard-co[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(standard-co state)[0m and the updater is [47m(set-standard-co val state)[0m.
  [47mStandard-co[0m must be an open character output channel.  It is to
  this channel that [47m[ld][0m prints the [prompt], the form to be
  evaluated, and the results.  The event [command]s such as [47m[defun][0m,
  [47m[defthm][0m, etc., which print extensive commentary do not print to
  [47mstandard-co[0m but rather to a different channel, [47m[proofs-co][0m, so that
  you may redirect this commentary while still interacting via
  [47mstandard-co[0m.  See [proofs-co].

  ``Standard-co'' stands for ``standard character output.'' The initial
  value of [47mstandard-co[0m is the same as the value of [47m[*standard-co*][0m.")
 (STANDARD-OI
  (IO ACL2-BUILT-INS)
  "The standard object input ``channel''

  [47mStandard-oi[0m is an [47m[ld][0m special (see [ld]).  The accessor is
  [47m(standard-oi state)[0m and the updater is [47m(set-standard-oi val state)[0m.
  [47mStandard-oi[0m must be an open object input channel, a true list of
  objects, or a list of objects whose last [47m[cdr][0m is an open object
  input channel.  It is from this source that [47m[ld][0m takes the input
  forms to process.  When [47m[ld][0m is called, if the value specified for
  [47mstandard-oi[0m is a string or a list of objects whose last [47m[cdr][0m is a
  string, then [47m[ld][0m treats the string as a file name and opens an
  object input channel from that file, where the connected book
  directory (see [cbd]) is used to resolve relative pathnames.  The
  channel opened by [47m[ld][0m is closed by [47m[ld][0m upon termination.

  ``Standard-oi'' stands for ``standard object input.'' The
  read-eval-print loop in [47m[ld][0m reads the objects in [47mstandard-oi[0m and
  treats them as forms to be evaluated.  The initial value of
  [47mstandard-oi[0m is the same as the value of [47m[*standard-oi*][0m.")
 (STANDARD-PART
  (REAL)
  "ACL2(r) function mapping limited numbers to standard numbers

  [47m(Standard-part x)[0m is, for a given [47m[i-limited][0m number [47mx[0m, the unique
  real number infinitesimally close (see [i-close]) to [47mx[0m.  This
  function is only defined in ACL2(r) (see [real]).")
 (STANDARDP
  (REAL)
  "ACL2(r) recognizer for standard objects

  [47m(Standardp x)[0m is true if and only if [47mx[0m is a ``standard'' object.
  This notion of ``standard'' comes from non-standard analysis and is
  discussed in Ruben Gamboa's dissertation.  In brief, all the
  familiar objects are standard: e.g., the familiar real numbers are
  standard, but non-zero infinitesimals are not standard, and the
  familiar integers are standard, but not those that exceed every
  integer that you can express in the usual way (1, 2, 3, and so on).
  Similarly, the familiar lists are standard, but not so a list that
  contains a large number of integers, where ``large'' means more
  than the standard integers.  The set of standard numbers is closed
  under the usual arithmetic operations, hence the sum of a standard
  number and a non-zero infinitesimal is not standard, though it is
  what is called ``limited'' (see [i-limited]).

  This predicate is only defined in ACL2(r) (see [real]).")
 (START-HERE
  (ACL2)
  "Introductory information about ACL2

  This [documentation] topic provides a starting point for those who
  are new to ACL2 or want to learn more about it.  It accommodates
  different goals (ranging from mild curiosity about ACL2 to the
  desire to become an expert user) and different learning styles.  A
  quick scan should help you find a place to start that suits you.

    * The [31;1mACL2 home page[0m, at [47m{ http://www.cs.utexas.edu/users/moore/acl2/ |
      http://www.cs.utexas.edu/users/moore/acl2/}[0m, provides links
      that can take you to good places to start learning about ACL2.

    * See [about-ACL2] for [31;1mbasic ``administrative'' information[0m such as how
      to obtain and build ACL2, copyright and license material,
      mailing lists, connection with GitHub, and so on.

    * [31;1mOverviews at a high level[0m may be found in {The Tours |
      https://www.cs.utexas.edu/users/moore/acl2/v8-6/combined-manual/index.html?topic=ACL2____The_02Tours}.
      The paper [3m{Industrial Proofs with ACL2 |
      https://www.cs.utexas.edu/users/moore/publications/how-to-prove-thms/intro-to-acl2.pdf}[0m
      was written in the 1990s but is still useful for providing a
      brief overview of what can be done with ACL2.

    * [31;1mTutorial Introductions[0m at various levels are available at the
      [ACL2-tutorial] documentation topic and especially its
      subtopics.  (There is some overlap with the present topic.)

    * [31;1mBooks[0m include the following.

          * [3m{Computer-Aided Reasoning: An Approach |
            http://www.cs.utexas.edu/users/moore/publications/acl2-books/car/index.html}[0m
            provides a detailed introduction to ACL2 and contains
            many exercises.

          * [3m{Computer-Aided Reasoning: ACL2 Case Studies |
            http://www.cs.utexas.edu/users/moore/publications/acl2-books/acs/index.html}[0m
            describes some relatively early applications of ACL2,
            including scripts as well as answers to the exercises.

    * There are many [31;1mprojects that use ACL2.[0m

        * See [interesting-applications] for an overview of some projects that
          have used ACL2.

        * A {publications page |
          https://www.cs.utexas.edu/users/moore/publications/acl2-papers.html}
          has links to many books and papers.  You can also follow
          links starting at the {ACL2 Workshops page |
          https://www.cs.utexas.edu/users/moore/acl2/workshops.html}
          to see programs, talks, and papers presented at ACL2
          Workshops (25 and counting as of 2022).

        * The {Community Books |
          https://github.com/acl2/acl2/tree/master/books} is a
          repository of many projects, processed virtually
          continuously by virtue of constituting the ACL2 regression
          suite.  Many of those projects are descried in the
          {ACL2+books online manual |
          http://www.cs.utexas.edu/users/moore/acl2/manuals/latest/index.html}.

    * [31;1mProgramming with ACL2[0m is introduced gently in the documentation
      topic, [gentle-introduction-to-ACL2-programming].

    * [31;1mLogical basics[0m are presented in the [recursion-and-induction]
      documentation topic, for teaching yourself how to prove
      theorems about recursively defined functions using mathematical
      induction.  There are lots of exercises.  Some may find this a
      good way to get into ACL2, by understanding its proof system
      before attempting to use the tool.

    * [31;1mThe theorem prover[0m is something perhaps best learned after studying
      the logical basics above, or at least giving them a quick
      glance.  Then you can just dive in or you can first study how
      to use it.

        * See [the-method] for concise guidance on the key technique for using
          the ACL2 prover effectively.

        * See [introduction-to-the-theorem-prover] for a detailed discussion of
          how to be an effective user of the ACL2 theorem prover,
          including a focus on its primary proof technique,
          rewriting.

        * The paper ``{How to Prove Theorems Formally |
          https://www.cs.utexas.edu/users/moore/publications/how-to-prove-thms/main.pdf}
          guides the reader towards effective use of ACL2, with
          exercises included.  Quoting the abstract: ``The real
          purpose of this paper is to answer the question how does
          one construct and manage large mechanically checked proofs
          (in ACL2)?''.

    * Here are some resources for trying out ACL2 without directly
      installing it yourself.

          * The ACL2 Sedan (see [ACL2-SEDAN]) is an [31;1mEclipse-based plug-in that
            provides a modern development environment[0m and other
            capabilities that may be helpful for new ACL2 users.

          * A basic [31;1mweb-based interface to ACL2[0m is {Proof Pad |
            http://new.proofpad.org}.

          * There is an {ACL2 Docker container |
            https://hub.docker.com/r/atwalter/acl2} (maintained at
            {this repo |
            https://github.com/mister-walter/acl2-docker}).


Subtopics

  [About-ACL2]
      General information About ACL2

  [ACL2-tutorial]
      Tutorial introduction to ACL2

  [Gentle-introduction-to-ACL2-programming]
      A Gentle Introduction to ACL2 Programming")
 (START-PROOF-TREE
  (PROOF-TREE)
  "Start displaying proof trees during proofs

  Also see [proof-tree] and see [stop-proof-tree].  Note that
  [47m:start-proof-tree[0m works by removing [47m'[0m[47m[proof-tree][0m from the
  [47minhibit-output-lst[0m; see [set-inhibit-output-lst].

  Explanations of proof tree displays may be found elsewhere: see
  [proof-tree].  In a nutshell: [47m:start-proof-tree[0m causes proof tree
  display to be turned on, once it has been turned off by
  [47m:[0m[47m[stop-proof-tree][0m.

  Do not attempt to invoke [47mstart-proof-tree[0m during an interrupt in the
  middle of a proof.")
 (STARTUP
  (ACL2-TUTORIAL)
  "How to start using ACL2; the ACL2 [command] loop

  When you start up ACL2, you'll probably find yourself inside the ACL2
  [command] loop, as indicated by the following [prompt].

    ACL2 !>

  If not, you should type [47m(LP)[0m.  See [lp], which has a lot more
  information about the ACL2 [command] loop.

  You should now be in ACL2.  The current ``[default-defun-mode]'' is
  [47m:[0m[47m[logic][0m; the other mode is [47m:[0m[47m[program][0m, which would cause the
  letter [47mp[0m to be printed in the [prompt].  [47m:[0m[47m[Logic][0m means that any
  function we define is not only executable but also is axiomatically
  defined in the ACL2 logic.  See [defun-mode] and see
  [default-defun-mode].  For example we can define a function [47mmy-cons[0m
  as follows.  (You may find it useful to start up ACL2 and submit
  this and other [command]s below to the ACL2 [command] loop, as we
  won't include output below.)

    ACL2 !>(defun my-cons (x y) (cons x y))

  An easy theorem may then be proved: the [47m[car][0m of [47m(my-cons a b)[0m is A.

    ACL2 !>(defthm car-my-cons (equal (car (my-cons a b)) a))

  You can place raw Lisp forms to evaluate at start-up into file
  [47macl2-init.lsp[0m in your home directory, except on Windows systems.
  For example, if you put the following into [47macl2-init.lsp[0m, then ACL2
  will print \"HI\" when it starts up.

    (print \"HI\")

  But be careful; all bets are off when you submit forms to raw Lisp,
  so this capability should only be used when you are hacking or when
  you are setting some Lisp parameters (e.g., [47m(setq si::*notify-gbc*
  nil)[0m to turn off garbage collection notices in GCL).

  Notice that unlike Nqthm, the theorem [command] is [47m[defthm][0m rather
  than [47mprove-lemma[0m.  See [defthm], which explains (among other
  things) that the default is to turn theorems into [rewrite] rules.

  Various keyword commands are available to query the ACL2 ``[world]'',
  or database.  For example, we may view the definition of [47mmy-cons[0m by
  invoking a command to print [events], as follows.

    ACL2 !>:pe my-cons

  Also see [pe].  We may also view all the lemmas that [rewrite]
  [term]s whose top function symbol is [47m[car][0m by using the following
  command, whose output will refer to the lemma [47mcar-my-cons[0m proved
  above.

    ACL2 !>:pl car

  Also see [pl].  Finally, we may print all the [command]s back through
  the initial [world] as follows.

    ACL2 !>:pbt 0

  See [history] for a list of commands, including these, for viewing
  the current ACL2 [world].

  Continue with the [documentation] for [annotated-ACL2-scripts] to see
  a simple but illustrative example in the use of ACL2 for reasoning
  about functions.")
 (STARTUP-BANNER
  (INTERFACING-TOOLS)
  "Modifying the ACL2 startup banner

  When you start up an ACL2 executable built from sources obtained from
  GitHub between ACL2 releases, you'll typically see a startup banner
  like this:

    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    + ACL2 Version 8.6+ (a development snapshot based on ACL2 Version 8.6) +
    +   built January 14, 2025  10:09:28.                                  +
    +   (Git commit hash: 89b2701f59f8e561b17121cf0a25cb8d1910377f)        +
    + Copyright (C) 2025, Regents of the University of Texas.              +
    + ACL2 comes with ABSOLUTELY NO WARRANTY.  This is free software and   +
    + you are welcome to redistribute it under certain conditions.  For    +
    + details, see the LICENSE file distributed with ACL2.                 +
    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

  The third line of that banner can be modified by setting environment
  variable [47mACL2_SNAPSHOT_INFO[0m to a non-empty string before saving the
  executable.  The value of that variable will be placed into the
  banner, for example as follows if that value is [47m\"This is my private
  executable.\"[0m.

    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    + ACL2 Version 8.6+ (a development snapshot based on ACL2 Version 8.6) +
    +   built January 14, 2025  09:56:49.                                  +
    +   (Note from the environment when this executable was saved:         +
    +    This is my private executable.)                                   +
    + Copyright (C) 2025, Regents of the University of Texas.              +
    + ACL2 comes with ABSOLUTELY NO WARRANTY.  This is free software and   +
    + you are welcome to redistribute it under certain conditions.  For    +
    + details, see the LICENSE file distributed with ACL2.                 +
    ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

  An exception is the special value, [47m\"none\"[0m, which is treated as
  case-insensitive (so it can similarly be [47m\"None\"[0m, [47m\"NONE\"[0m, etc.).  In
  that case, the third line of the original banner is omitted
  entirely.")
 (STATE
  (PROGRAMMING)
  "The von Neumannesque ACL2 state object

  Note: If you are interested in programming with state, see
  [programming-with-state] after reading the information below.

  The ACL2 state object is used extensively in programming the ACL2
  system, and has been used in other ACL2 programs as well.  However,
  most users, especially those interested in specification and
  verification (as opposed to programming [3mper se[0m), need not be aware
  of the role of the state object in ACL2, and will not write
  functions that use it explicitly.  We say more about this point at
  the end of this documentation topic.

  The ACL2 state object is an example of a single-threaded object or
  [stobj].  ACL2 allows the user to define new single-threaded
  objects.  Generally, ACL2 may need to access the ACL2 state but
  should not (cannot) change it except via a certain set of approved
  functions such as [47m[defun][0m and [47m[defthm][0m.  If you need a state-like
  object to which you have complete rights, you may want a [stobj].

  Key to the idea of our [47mstate[0m is the notion of single-threadedness.
  For an explanation, see [stobj].  The upshot of it is that [47mstate[0m is
  a variable symbol with severe restrictions on its use, so that it
  can be passed into only certain functions in certain slots, and
  must be returned by those functions that ``modify'' it.
  Henceforth, we do not discuss single-threaded objects in general
  (which the user can introduce with [47m[defstobj][0m and [47m[defabsstobj][0m)
  but one in particular, namely ACL2's [47mstate[0m object.

  The [3mglobal table[0m is perhaps the most visible portion of the state
  object.  Using the interface functions [47m@[0m and [47massign[0m, a user may
  bind global variables to the results of function evaluations (much
  as an Nqthm user exploits the Nqthm utility [47mr-loop[0m).  See [@], and
  see [assign].  A particularly interesting global is
  [47m'current-acl2-world[0m, whose value is the ACL2 logical [world].

  ACL2 supports several facilities of a truly von Neumannesque state
  machine character, including file [io] and global variables.
  Logically speaking, the state is a true list of the 14 components
  described below.  There is a ``current'' state object at the
  top-level of the ACL2 [command] loop.  This object is understood to
  be the value of what would otherwise be the free variable [47mstate[0m
  appearing in top-level input.  When any [command] returns a state
  object as one of its values, that object becomes the new current
  state.  But ACL2 provides von Neumann style speed for state
  operations by maintaining only one physical (as opposed to logical)
  state object.  Operations on the state are in fact destructive.
  This implementation does not violate the applicative semantics
  because we enforce certain draconian syntactic rules regarding the
  use of state objects.  For example, one cannot ``hold on'' to an
  old state, access the components of a state arbitrarily, or
  ``modify'' a state object without passing it on to subsequent
  state-sensitive functions.

  Every routine that uses the state facilities (e.g. does [io], or
  calls a routine that does [io]), must be passed a ``state object.''
  And a routine must return a state object if the routine modifies
  the state in any way.  Rigid syntactic rules governing the use of
  state objects are enforced by the function [47mtranslate[0m, through which
  all ACL2 user input first passes.  State objects can only be
  ``held'' in the formal parameter [47mstate[0m, never in any other formal
  parameter and never in any structure (except as a state value in a
  [multiple-value] return).  State objects can only be accessed with
  the primitives we specifically permit.  Thus, for example, one
  cannot ask, in code to be executed, for the length of [47mstate[0m or the
  [47m[car][0m of [47mstate[0m.  In the statement and proof of theorems, there are
  no syntactic rules prohibiting arbitrary treatment of state
  objects.

  Logically speaking, a state object is a true list whose members are
  as follows:

      [47mOpen-input-channels[0m, an alist with keys that are symbols in package
      [47m\"ACL2-INPUT-CHANNEL\"[0m.  The value ([47m[cdr][0m) of each pair has the
      form [47m((:header type file-name open-time) . elements)[0m, where
      [47mtype[0m is one of [47m:character[0m, [47m:byte[0m, or [47m:object[0m and [47melements[0m is a
      list of things of the corresponding [47mtype[0m, i.e. characters,
      integers of type [47m(mod 255)[0m, or lisp objects in our theory.
      [47mFile-name[0m is a string.  [47mOpen-time[0m is an integer.  See [io].

      [47mOpen-output-channels[0m, an alist with keys that are symbols in package
      [47m\"ACL2-OUTPUT-CHANNEL\"[0m.  The value of a pair has the form
      [47m((:header type file-name open-time) .  current-contents)[0m.  See
      [io].

      [47mGlobal-table[0m, an alist associating symbols (to be used as ``global
      variables'') with values.  See [@], and see [assign].

      [47mIdates[0m, a list of dates and times, used to implement the function
      [47mprint-current-idate[0m, which prints the date and time.

      [47mAcl2-oracle[0m, a list of objects, used for example to implement the
      functions that let ACL2 report how much time was used, but
      inaccessible to the user.  See [47m[read-ACL2-oracle][0m and also see
      [47m[with-prover-time-limit][0m.

      [47mFile-clock[0m, an integer that is increased on every file opening and
      closing, and is used to maintain the consistency of the [47m[io][0m
      primitives.

      [47mReadable-files[0m, an alist whose keys have the form [47m(string type time)[0m,
      where [47m[string][0m is a file name and [47mtime[0m is an integer.  The
      value associated with such a key is a list of characters,
      bytes, or objects, according to [47mtype[0m.  The [47mtime[0m field is used
      in the following way: when it comes time to open a file for
      input, we will only look for a file of the specified name and
      [47mtype[0m whose time field is that of [47mfile-clock[0m.  This permits us
      to have a ``probe-file'' aspect to [47mopen-file[0m: one can ask for a
      file, find it does not exist, but come back later and find that
      it does now exist.

      [47mWritten-files[0m, an alist whose keys have the form [47m(string type time1
      time2)[0m, where [47m[string][0m is a file name, [47mtype[0m is one of
      [47m:character[0m, [47m:byte[0m or [47m:object[0m, and [47mtime1[0m and [47mtime2[0m are integers.
      [47mTime1[0m and [47mtime2[0m correspond to the [47mfile-clock[0m time at which the
      channel for the file was opened and closed.  This field is
      write-only; the only operation that affects this field is
      [47mclose-output-channel[0m, which [47m[cons][0mes a new entry on the front.

      [47mRead-files[0m, a list of the form [47m(string type time1 time2)[0m, where
      [47m[string][0m is a file name and [47mtime1[0m and [47mtime2[0m were the times at
      which the file was opened for reading and closed.  This field
      is write only.

      [47mWriteable-files[0m, an alist whose keys have the form [47m(string type
      time)[0m.  To open a file for output, we require that the name,
      type, and time be on this list.

      [47mUser-stobj-alist[0m, an alist which associates user-defined
      single-threaded objects (see [stobj]) with their values.

  We recommend avoiding the use of the state object when writing ACL2
  code intended to be used as a formal model of some system, for
  several reasons.  First, the state object is complicated and
  contains many components that are oriented toward implementation
  and are likely to be irrelevant to the model in question.  Second,
  there is currently not much support for reasoning about ACL2
  functions that manipulate the state object, beyond their logical
  definitions.  Third, the documentation about state is not as
  complete as one might wish.

  User-defined single-threaded objects offer the speed of [47mstate[0m while
  giving the user complete access to all the fields.  See [stobj].

  Again, if you are interested in programming with state see
  [programming-with-state].


Subtopics

  [Io]
      Input/output facilities in ACL2

  [Programming-with-state]
      Programming using the von Neumannesque ACL2 [state] object

  [Random$]
      Obtain a random value

  [Set-state-ok]
      Allow the use of STATE as a formal parameter

  [W]
      The current ACL2 [world]

  [World]
      ACL2 property lists and the ACL2 logical database

  [Wormhole]
      [47m[ld][0m without [47m[state][0m --- a short-cut to a parallel universe")
 (STATE-GLOBAL-LET*
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Bind [state] global variables

  See [programming-with-state] for requisite background on programming
  with the ACL2 [state].

    Example Forms:
    (state-global-let*
     ((inhibit-output-lst *valid-output-names*))
     (thm (equal x x)))

    (state-global-let*
     ((fmt-hard-right-margin 1000 set-fmt-hard-right-margin)
      (fmt-soft-right-margin 1000 set-fmt-soft-right-margin))
     (mini-proveall))

    General Form:
    (state-global-let* ((var1 form1) ; or (var1 form1 set-var1)
                        ...
                        (vark formk) ; or (vark formk set-vark)
                       )
                       body)

  where: each [47mvari[0m is a variable; each [47mformi[0m is an expression whose
  value is a single ordinary object (i.e. not multiple values, and
  not [state] or any other [stobj]); [47mset-vari[0m, if supplied, is a
  function or macro such that [47m(set-vari _ state)[0m returns [47m[state][0m; and
  [47mbody[0m is an expression that evaluates to an [error-triple].  Each
  [47mformi[0m is evaluated in order, starting with [47mform1[0m, and with each
  such binding the state global variable [47mvari[0m is bound to the value
  of [47mformi[0m, sequentially in the style of [47m[let*][0m.  More precisely, the
  meaning of this form is to perform the following actions, in order.

   1. Set (in order) the global values of the indicated [state] global
      variables [47mvari[0m to the values of [47mformi[0m.  Exception: This is
      skipped when [47mvari[0m is a built-in state global and [47mformi[0m is
      [47m(f-get-global 'vari state)[0m.

   2. Execute [47mbody[0m.

   3. Restore the [47mvari[0m to their previous values.

   4. Return the [error-triple] produced by [47mbody[0m, where [47m[state][0m reflects
      the modifications of the preceding step.

  The restoration is guaranteed even in the face of aborts.  The
  ``bound'' variables may initially be unbound in state and
  restoration means to make them unbound again.

  Still referring to the General Form above, we next discuss how the
  values are set and restored.  Let [47mold-vali[0m be the value of state
  global variable [47mvari[0m at the time [47mvari[0m is about to be assigned the
  value of [47mformi[0m.  We say that a ``setter is supplied'' for [47mvari[0m if
  [47mset-vari[0m is supplied, either explicitly as in the General Form
  above, or implicitly by being associated with [47mvari[0m in the value of
  the constant, [47m*state-global-let*-untouchable-alist*[0m (whose
  definition appears at the end of this topic).  If no setter is
  supplied then [47mvari[0m is set or restored to a value [47m<val>[0m by
  evaluating [47m(f-put-global 'vari <val> state)[0m.  However, if a setter
  [47mset-vari[0m is supplied, then the form evaluated will instead be
  [47m(set-vari <val> state)[0m.  Having a setter supplied is particularly
  useful if [47mvari[0m is [untouchable], since the call above of
  [47m[f-put-global][0m is illegal.  However, the use of
  [47m*state-global-let*-untouchable-alist*[0m (mentioned above) avoids the
  need for supplying [47mset-vari[0m explicitly for certain built-in
  [untouchable] state global variables, [47mvari[0m.

  Note that the scope of the bindings of a [47mstate-global-let*[0m form is
  the body of that form.  This may seem obvious, but to drive the
  point home, let's consider the following example (see
  [set-print-base] and see [set-print-radix]).

    ACL2 !>(state-global-let* ((print-base 16 set-print-base)
                               (print-radix t set-print-radix))
                              (mv nil 10 state))
     10
    ACL2 !>

  Why wasn't the result printed as [47m#xA[0m?  The reason is that the result
  was printed after evaluation of the entire form had completed.  If
  you want to see [47m#xA[0m, do the printing in the scope of the bindings,
  for example as follows.

    ACL2 !>(state-global-let* ((print-base 16 set-print-base)
                               (print-radix t set-print-radix))
                              (pprogn (fms \"~x0~%\"
                                           (list (cons #\\0 10))
                                           *standard-co* state nil)
                                      (mv nil 10 state)))

    #xA
     10
    ACL2 !>

  Finally, as promised above, here is the definition of the constant
  that maps certain built-in untouchable variables to setters.

  [31;1mDefinition: [0m<*state-global-let*-untouchable-alist*>

    (defconst *state-global-let*-untouchable-alist*
      '((abbrev-evisc-tuple . set-abbrev-evisc-tuple-state)
        (compiler-enabled . set-compiler-enabled)
        (current-package . set-current-package-state)
        (fmt-hard-right-margin . set-fmt-hard-right-margin)
        (fmt-soft-right-margin . set-fmt-soft-right-margin)
        (gag-mode-evisc-tuple . set-gag-mode-evisc-tuple-state)
        (inhibit-output-lst . set-inhibit-output-lst-state)
        (inhibited-summary-types . set-inhibited-summary-types-state)
        (ld-evisc-tuple . set-ld-evisc-tuple-state)
        (ppr-flat-right-margin . set-ppr-flat-right-margin)
        (print-base . set-print-base)
        (print-case . set-print-case)
        (print-length . set-print-length)
        (print-level . set-print-level)
        (print-lines . set-print-lines)
        (print-right-margin . set-print-right-margin)
        (proofs-co . set-proofs-co-state)
        (serialize-character . set-serialize-character)
        (serialize-character-system . set-serialize-character-system)
        (standard-co . set-standard-co-state)
        (temp-touchable-fns . set-temp-touchable-fns)
        (temp-touchable-vars . set-temp-touchable-vars)
        (term-evisc-tuple . set-term-evisc-tuple-state)))")
 (STATING-AND-PROVING-LEMMAS-ABOUT-LOOP$S
  (LOOP$)
  "Stating and proving theorems about [47mloop$[0ms

  In this topic we give some advice about how to state and prove
  theorems involving [47mloop$[0ms, especially stating lemmas that are
  intended to rewrite [47mloop$[0m statements and proving theorems about
  [47mloop$[0m statements inductively.


Name [47mLoop$[0ms When Memorable Names Come to Mind

  Just because you can write iterative computations inline, don't get
  carried away!

  If you can think of a good name for the concept implemented by a
  [47mloop$[0m statement, use [47mdefun[0m to define that name.  This is especially
  the case if you intend to reason about that [47mloop$[0m statement or to
  write more than one instance of it.

  For example, rather than write instances of

    (loop$ for a in x as b in y sum (* a b))

  it is better to define [47m(dot-product x y)[0m with that [47mloop$[0m as its body
  and then write calls of [47mdot-product[0m and lemmas about [47mdot-product[0m
  rather than that [47mloop$[0m.

  Basically, names are good as long as you can remember them.  They
  give you a place to hang lemmas and the lemmas match without you
  having to think about how lambda objects rewrite, local variables,
  etc.  Not all [47mloop$[0ms compute concepts with obvious, memorable
  names, but just because you can write ``anonymous'' iterations
  doesn't mean you should!


Generalizing the Initial Values

  Let's start with the most common issue raised by any inductive proof:
  the conjecture to be proved must be general enough to permit the
  provision of an appropriate inductive hypothesis.

  Consider how you would prove the conjecture below after defining [47mrev[0m
  and [47mrev1[0m.

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

    (defun rev1 (x a)
      (if (endp x)
          a
          (rev1 (cdr x) (cons (car x) a))))

    (defthm rev1-is-rev
      (equal (rev1 x nil) (rev x)))

  The experienced ACL2 user would not attempt to prove [47mrev1-is-rev[0m by
  induction because the [47mnil[0m prevents the provision of an appropriate
  induction hypothesis.  Instead, the user would first prove a
  generalization obtained by replacing that [47mnil[0m by a variable and
  ``explaining'' the role of that variable on the right-hand side.

    (defthm rev1-is-rev-generalized
      (equal (rev1 x a)
             (append (rev x) a)))

  The proof of the generalized theorem succeeds (though the prover must
  ``discover'' and then prove that [47mappend[0m is associative).

  With that theorem available, the proof of [47mrev1-is-rev[0m is trivial,
  given that [47mnil[0m is the right-identity for [47mappend[0m on true-lists and
  that [47mrev[0m returns a true-list.

  Now consider defining reverse with a [47mdo[0m [47mloop$[0m.

    (defun rev-loop$ (x)
      (loop$ with tail = x
             with a = nil
             do
             (if (endp tail)
                 (return a)
                (progn (setq a (cons (car tail) a))
                        (setq tail (cdr tail))))))

  The experienced ACL2 user would not attept to prove that [47m(rev-loop$
  x)[0m is [47m(rev x)[0m by induction!  The problem is the same as before: the
  [47mnil[0m initialization of the iterative variable [47ma[0m in the [47mdo[0m [47mloop$[0m does
  not permit an appropriate inductive hypothesis.  Instead, the user
  needs to prove a more general theorem that cannot be stated in
  terms of [47mrev-loop$[0m because that [47mnil[0m is built into the definition.
  We need to lift the [47mloop$[0m out of the definition, generalize it, and
  prove a theorem about the generalized [47mloop$[0m.  Ideally we'd prove

    (defthm rev-loop$-is-rev-generalized
      (equal (loop$ with tail = x
                    with a = a
                    do
                    (if (endp tail)
                        (return a)
                        (progn (setq a (cons (car tail) a))
                               (setq tail (cdr tail)))))
             (append (rev x) a))).

  ACL2's prover can derive induction schemes suggested by some [47mloop$[0m
  statements, just as it can from some calls of recursive functions.
  Because both iterative variables, [47mtail[0m and [47ma[0m, are initialized to
  variables, the [47mDO[0m [47mloop$[0m above suggests an appropriate induction.
  But inductions for [47mloop$[0ms raise some new issues as well as some
  traditional ones.

  ACL2 will prove the lemma above, if the associativity of [47mappend[0m has
  first been proved explicitly as a rewrite rule.  (The presence of
  the [47mloop$[0m confuses the heuristics that enable the prover to
  ``discover'' the associativity of [47mappend[0m.)

  [31;1mLesson 1[0m: If a [47mloop$[0m has iterative variables initialized to
  non-variables, generalize them before expecting an induction to
  work!  If the [47mloop$[0m is buried in a definition you'll have to lift
  the [47mloop$[0m out of the definition to generalize it and prove a
  theorem about the the generalized [47mloop$[0m.


Normal Forms in [47mLoop$[0m Bodies

  The lemma above, [47mrev-loop$-is-rev-generalized[0m, is adequate to
  subsequently prove the main theorem,

    (defthm rev-loop$-is-rev
      (equal (rev-loop$ x)
             (rev x))).

  But as stated, [47mrev-loop$-is-rev-generalized[0m is fragile because it
  mentions the non-recursively defined function [47mendp[0m.  To explain
  this remark we need to walk through the proof of the main theorem.

  Recall that the prover always expands enabled functions that are not
  explicitly recursive.  And [47mrev-loop$[0m is not explicitly recursive.
  So the proof attempt of [47mrev-loop$-is-rev[0m will expand the call of
  [47mrev-loop$[0m and produce

    Goal'
    (equal (loop$ with tail = x
                  with a = nil
                  do
                  (if (endp tail)
                      (return a)
                      (progn (setq a (cons (car tail) a))
                             (setq tail (cdr tail)))))
           (rev x))

  If the [47mloop$[0m term above is immediately rewritten, our generalized
  lemma would fire and reduce the goal to

    Goal''
    (equal (append (rev x) nil)
           (rev x))

  and the proof would be completed as before with the right-identity
  rule.

  Indeed, this is what happens in this particular case, but the reason
  it works is completely unrelated to [47mloop$[0ms!  Our generalized lemma
  has no hypotheses --- it is an unconditional rewrite rule that is
  applied early in the ``preprocessing'' phase of simplification.

  Let's suppose the generalized lemma did have some hypotheses or
  otherwise failed to apply during preprocessing.  You can cause this
  to happen by restating the generalized lemma and the main theorem
  to have the (unnecessary but easily dealt with) hypothesis
  [47m(true-listp x)[0m.  The proof of the conditional generalized lemma
  still goes through, but the proof of the conditional main theorem
  fails because the generalized lemma never fires!

  The reason it never fires is that it is not tried during
  prepreprocessing (because preprocessing doesn't deal with
  conditional rules because preprocessing doesn't support
  backchaining) and [47mGoal'[0m above enters the rewriter, which [3mrewrites
  every subterm of the term before trying to apply rules to the term
  itself[0m.  In particular, before the rewriter tries to apply our
  generalized rule it rewrites the subterms of the [47mloop$[0m statement,
  including the body.  (Technically, it rewrites the [47mlambda[0m object in
  the translation of the [47mloop$[0m.  See [rewrite-lambda-object].)

  This transforms

    (loop$ with tail = x
           with a = nil
           do
           (if (endp tail)
               (return a)
               (progn (setq a (cons (car tail) a))
                      (setq tail (cdr tail)))))

  to

    (loop$ with tail = x
           with a = nil
           do
           (if (consp tail)
               (progn (setq a (cons (car tail) a))
                      (setq tail (cdr tail)))
               (return a)))

  because [47m(endp x)[0m expands to [47m(not (consp x))[0m and the branches of the
  [47mif[0m are swapped to eliminate the [47mnot[0m.

  After this rewrite, our generalized lemma no longer matches.

  [31;1mLesson 2[0m: Do not prove rewrite rules that target [47mloop$[0m statements
  containing terms in non-normal form!  That is, as with all other
  rewrite rules, make sure your target is normalized under your
  intended rewrite regime.

  So for example, in addition to watching out for non-recursive
  functions in the body, be alert for things like expressions that
  are rearranged by associativity and commutativity rules.  You
  wouldn't write a rewrite rule containing a subterm like [47m(append
  (append a b) c)[0m if you're right-associating [47mappend[0m nests, nor would
  you include a subterm like [47m(+ x 1)[0m if you're normalizing arithmetic
  expressions (in this case to [47m(+ 1 x)[0m).  So don't use such
  non-normal terms in lemmas about [47mloop$[0ms!

  The entire robust script for the [47mrev-loop$[0m proof is given below.

    (defun rev (x)
      (if (endp x)
          nil
          (append (rev (cdr x)) (list (car x)))))

    (defun rev-loop$ (x)
      (loop$ with tail = x
             with a = nil
             do
             (if (endp tail)
                 (return a)
                 (progn (setq a (cons (car tail) a))
                        (setq tail (cdr tail))))))

    (defthm assoc-of-append
      (equal (append (append a b) c)
             (append a (append b c))))

    (defthm rev-loop$-is-rev-generalized
      (equal (loop$ with tail = x
                    with a = a
                    do
                    (if (consp tail)
                        (progn (setq a (cons (car tail) a))
                               (setq tail (cdr tail)))
                        (return a)))
             (append (rev x) a)))

    (defthm rev-loop$-is-rev
      (equal (rev-loop$ x)
             (rev x)))

  The script is robust in the sense that even if you conditionalize the
  generalized lemma with a hypothesis that can be relieved in the
  main theorem the lemma will fire and rewrite the [47mloop$[0m exposed when
  [47mrev-loop$[0m is expanded.  Note that the [47mloop$[0m was written with [47m(endp
  tail)[0m in the [47mdefun[0m of [47mrev-loop$[0m but lemma deals with the normalized
  form of that body.


The Secret [47mSetq[0m Problem

  Another issue that comes up when posing lemmas about [47mloop$[0ms is called
  the [3msecret [47msetq[0m[3m problem[0m and is best illustrated by example.

  Define the following function.

    (defun secret-setq-problem (k x)
      (loop$ with x = x
             with j = 0
             do
             (cond ((endp x) (return 'bad))
                   ((equal j k) (return 'good))
                   (t (progn (setq x (cdr x))
                             (setq j (+ 1 j)))))))

  The function counts [47mj[0m up from [47m0[0m until it is equal to [47mk[0m, while [47mcdr[0ming
  [47mx[0m.  It returns [47mgood[0m if it [47mj[0m reaches [47mk[0m before the list is exhausted,
  and returns [47mbad[0m otherwise.  Thus, this is a theorem.

    (defthm secret-setq-problem-main
      (implies (and (natp k)
                    (< k (len x)))
               (equal (secret-setq-problem k x)
                      'good)))

  While [47msecret-setq-problem-main[0m is provable by ACL2, it should be
  clear from Lessons 1 and 2 above that we first need to prove a
  lemma about the generalized, normalized loop$.  Here is a candidate
  lemma, which is proved by ACL2.

    (defthm secret-setq-problem-lemma
      (implies (and (natp j)
                    (natp k)
                    (< k (+ j (len x)))
                    (<= j k))
               (equal (loop$ with x = x
                             with j = j
                             do
                             (if (consp x)
                                 (if (equal j k)
                                     (return 'good)
                                     (progn (setq x (cdr x))
                                            (setq j (+ 1 j))))
                                 (return 'bad)))
                      'good)))

  Following Lesson 1, we generalized the initial value of [47mj[0m, which was
  [47m0[0m, to [47mj[0m, and we added the hypotheses that [47mj[0m is a natural less than
  or equal to [47mk[0m.  We generalized the [47m(< k (len x))[0m which we see in
  the main theorem to [47m(< k (+ j (len x)))[0m.  This accommodates the
  arbitrary initial [47mj[0m and simplifies to [47m(len x)[0m when [47mj[0m is [47m0[0m.
  Furthermore, as [47mj[0m goes up and [47mx[0m gets shorter, their sum stays
  fixed, which is necessary if the generalized hypothesis is going to
  survive induction.

  Following Lesson 2, we normalized the body.  We replaced the [47m(endp x)[0m
  by [47m(not (consp x))[0m and normalized the resulting [47mIF[0m nest.

  The lemma is proved automatically by ACL2, using the induction
  suggested by the [47mloop$[0m.

  However, the attempt to prove the main theorem above will fail!  The
  lemma doesn't fire because the [47mloop$[0m target still doesn't match.
  (Note: we could forget about the lemma firing automatically.
  Instead, we could give a [47m:hint[0m that disables the lemma and [47m:use[0ms
  the instance of it with [47mj[0m replaced by [47m0[0m.  That succeeds.  But it is
  valuable for us to explore why it didn't work as a rewrite rule.)

  Sometimes to debug a failed proof it helps to compare the term that a
  lemma targets with its intended target in the checkpoint of the
  failed proof.  This is especially true for [47mloop$[0ms because their
  translations are so different from their outward appearance.  (See
  the sections titled ``Semantics'' in [for-loop$] and [do-loop$].)
  The following use of the [47m:[0m[47m[pr][0m command shows our lemma's true form.
  It is the left-hand side, [47mLhs[0m, we are interested in because it is
  the target pattern of the rewrite rule.

    ACL2 !>:pr secret-setq-problem-lemma

    Rune:    (:REWRITE SECRET-SETQ-PROBLEM-LEMMA)
    Enabled: T
    Hyps:    (AND (NATP J)
                  (NATP K)
                  (< K (+ J (LEN X)))
                  (<= J K))
    Equiv:   EQUAL
    Lhs:     (DO$
              (LAMBDA$ (ALIST)
                (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'X ALIST))))
              (LIST (CONS 'X X)
                    (CONS 'J J)
                    (CONS 'K K))
              (LAMBDA$ (ALIST)
               (IF (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                   (IF (EQUAL (CDR (ASSOC-EQ-SAFE 'J ALIST))
                              (CDR (ASSOC-EQ-SAFE 'K ALIST)))
                       (LIST :RETURN 'GOOD
                             (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                                   (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST)))
                                   (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST)))))
                       (LIST NIL NIL
                             (LIST (CONS 'X (CDDR (ASSOC-EQ-SAFE 'X ALIST)))
                                   (CONS 'J (+ 1 (CDR (ASSOC-EQ-SAFE 'J ALIST))))
                                   (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST))))))
                   (LIST :RETURN 'BAD
                         (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                               (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST)))
                               (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST)))))))
                (LAMBDA$ (ALIST)
                 (LIST NIL NIL
                      (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                            (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST)))
                            (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST))))))
                (NIL) NIL)
    Rhs:     'GOOD
    Backchain-limit-lst: NIL
    Subclass: BACKCHAIN
    Loop-stopper: NIL

  The actual [47mdo$[0m term term you'll see in the checkpoint of the failed
  proof attempt is:

    (DO$
     (LAMBDA$ (ALIST)
       (ACL2-COUNT (CDR (ASSOC-EQ-SAFE 'X ALIST))))
     (LIST (CONS 'X X)
           '(J . 0)
           (CONS 'K K))
     (LAMBDA$ (ALIST)
      (IF (CONSP (CDR (ASSOC-EQ-SAFE 'X ALIST)))
          (IF (EQUAL (CDR (ASSOC-EQ-SAFE 'J ALIST))
                     (CDR (ASSOC-EQ-SAFE 'K ALIST)))
              (LIST :RETURN 'GOOD
                    (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                          (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST)))
                          (CONS 'K (CDR (ASSOC-EQ-SAFE 'J ALIST)))))
              (LIST NIL NIL
                    (LIST (CONS 'X (CDDR (ASSOC-EQ-SAFE 'X ALIST)))
                          (CONS 'J (+ 1 (CDR (ASSOC-EQ-SAFE 'J ALIST))))
                          (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST))))))
          (LIST :RETURN 'BAD
                (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                      (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST)))
                      (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST)))))))
       (LAMBDA$ (ALIST)
        (LIST NIL NIL
             (LIST (CONS 'X (CDR (ASSOC-EQ-SAFE 'X ALIST)))
                   (CONS 'J (CDR (ASSOC-EQ-SAFE 'J ALIST)))
                   (CONS 'K (CDR (ASSOC-EQ-SAFE 'K ALIST))))))
       (NIL) NIL)

  Note that the [47mLhs[0m matches the actual term, when [47mJ[0m is instantiated
  with [47m0[0m, [3mexcept[0m in one place: the alist constructed in the [47m(LIST
  :RETURN 'GOOD ...)[0m triple binds [47m'K[0m to the value of [47m'K[0m in [47mLhs[0m but
  binds [47m'K[0m to the value of [47m'J[0m in the actual term.  This happens
  because the actual term was rewritten under the assumption that the
  [47mIF[0m test equating the value of [47m'J[0m to the value of [47m'K[0m, and the
  rewriter substituted the value of [47m'J[0m for that of [47m'K[0m because of term
  ordering.  The ACL2 pattern matching routine does not take account
  of tests.

  We could possibly fix this problem by changing how ACL2 stores lemmas
  or how the pattern matcher works.  But such changes could have far
  reaching consequences across the entire ACL2 regression suite, so
  we have made no such changes.

  Absent such changes, it's incumbent on the user to phrase the rewrite
  rule appropriately.  The question is, ``How can you make that
  particular [47m'K[0m in [47mLhs[0m be [47m'J[0m?''

  One way would be to rephrase the rewrite rule by using the [47mDO$[0m term
  from the checkpoint in place of the [47mloop$[0m statement we wrote in
  [47msecret-setq-problem-lemma[0m.

  Another way to accomplish the same effect is to rewrite the [47mloop$[0m
  statement as shown below.

    (defthm secret-setq-problem-lemma
      (implies (and (natp j)
                    (natp k)
                    (< k (+ j (len x)))
                    (<= j k))
               (equal (loop$ with x = x
                             with j = j
                             with k = k                     ; ``new'' var
                             do
                             (if (consp x)
                                 (if (equal j k)
                                     (progn (setq k j)      ; new setq!
                                            (return 'good))
                                     (progn (setq x (cdr x))
                                            (setq j (+ 1 j))))
                                 (return 'bad)))
                      'good)))

  You can use [47m:[0m[47m[tcp][0m to confirm that the translation of the above [47mloop$[0m
  matches the actual term in the checkpoint.

  Note that the inclusion of the new ``[47mwith k = k[0m'' does not add any
  new subterms to the translation, it merely allows assignment to a
  previously used but never assigned variable.  The order of the [47mwith[0m
  clauses determines the order of the alists being constructed, so
  this pay attention to where [47m'k[0m is bound in the alists.  Also note
  that the new [47msetq[0m does not add any new subterms to the translation,
  just affects the final value of [47m'k[0m on that branch of the [47mif[0m tree.
  Finally note that we phrase the [47mloop$[0m this way in the lemma [3mwithout
  changing how we write the [47mloop$[0m[3m in the [47mdefun[0m[3m.[0m Writing the [47mloop$[0m
  this way in the [47mdefun[0m would add an unnecessary [47msetq[0m in the Common
  Lisp execution.  But there is no need to change how we write the
  [47mloop$[0m in the defun.  This lemma matches what comes up when we prove
  things about the [47mloop$[0m in the [47mdefun[0m.

  Because this matching problem can repaired by adding an unnecessary
  [47msetq[0m in the lemma, we call this the ``secret [47msetq[0m problem.''

  [31;1mLesson 3:[0m If the left-hand side of a rewrite rule contains an [47mloop$[0m
  with an [47mif[0m in the body, remember the secret [47msetq[0m problem.  More
  practically, if a [47mloop$[0m lemma you've proved fails to rewrite its
  target, compare the output of [47m:[0m[47mpr[0m, specifically the [47mLhs[0m, to the
  intended target printed in the checkpoint, and remember the secret
  [47msetq[0m problem.


The Hidden Hypothesis Problem

  Another issue you may occasionally confront when dealing with
  inductions suggested by [47mdo[0m [47mloop$[0ms is indicated when the prover
  fails to prove the measure conjecture even though you ``know'' it
  is provable.  To explain, we have to explain a little about how
  induction suggested by [47mdo[0m [47mloop$[0ms are done.

  From every [47mdo[0m [47mloop$[0m we can derive a proposed recursive function
  definition.  When the prover sees a [47mdo[0m [47mloop$[0m in a conjecture that
  it has decided requires inductions, it generates that derived
  function, does an induction analysis for it, and adds any
  suggestions it gets to the set of candidate inductions to consider.
  However, the derived function may not terminate ``normally.''
  Recall that [47m[do$][0m checks that the measure goes down before each
  iteration and returns a default value if that check fails.  Thus,
  to justify the induction suggested by the generated function the
  proof obligations include those that establish that the measure
  decreases [3munder the tests leading to further iterations in the
  [47mloop$[0m[3m body[0m.

  Those tests are not always sufficient to guarantee termination!  If
  the [47mloop$[0m came from a guard verified function definition,
  termination was proved.  But it was proved as part of guard
  verification.  Remember the main purpose of guards in [47mloop$[0ms: to
  allow us to execute the [47mloop$[0m as a Common Lisp [47mloop[0m.  But that
  execution only happens when we know guards hold.  But [47mloop$[0ms seen
  by the prover may not come from guard verified statements and,
  besides, guards are stripped out of conjectures to be proved
  because they're irrelevant to the logical meaning.

  However, it is logically valid to condition the induction-time
  measure conjectures on hypotheses from the conjecture being proved
  --- and it is often ineffective to include all of those hypotheses.
  So ACL2's induction mechanism chooses some of the available
  hypotheses and may not choose enough.  This is the ``hidden
  hypothesis problem.'' An example is below.

  The following function can be admitted and guard verified, meaning
  the termination obligation is proved as part of guard verification.

    (defun hidden-hyp-problem (lo j)
      (declare (xargs :guard (and (natp lo) (natp j) (<= lo j))))
      (loop$ with j = j
             do
             :guard (and (natp lo) (natp j) (<= lo j))
             (if (equal lo j)
                 (return 'good)
                 (setq j (- j 1)))))

  Since since [47mlo[0m and [47mj[0m are both natural numbers and [47mj[0m is (weakly) above
  [47mlo[0m and is decremented on iteration, [47mj[0m will eventually reach [47mlo[0m and
  the [47mloop$[0m will stop.

  The derived recursive function corresponding to this [47mloop$[0m, which
  we'll call [47mderived-fn[0m here, is

    (defun derived-fn (lo j)
      (if (equal lo j)
          'good
          (derived-fn lo (- j 1)))).

  That derived function doesn't terminate.

  Now let's try to prove that the [47mloop$[0m always returns [47m'good[0m.  Note
  that it doesn't matter if we include guards in the conjecture or
  not.  They're logically irrelevant and will be eliminated.

  However, the following proof attempt fails.  The prover chooses to
  induct as suggested by the [47mdo[0m [47mloop$[0m.  The induction scheme selected
  is shown.

    ACL2 !>(defthm hidden-hyp-problem-main
             (implies (and (natp lo)
                           (natp j)
                           (<= lo j))
                      (equal (loop$ with j = j
                                    do
                                    :guard (and (natp lo) (natp j) (<= lo j))
                                    (if (equal lo j)
                                        (return 'good)
                                        (setq j (- j 1))))
                             'good)))

    ...

    This suggestion was produced using the :induction rule DO$.  If we
    let (:P J LO) denote *1 above then the induction scheme we'll use is
    (AND (IMPLIES (AND (NOT (EQUAL LO J))
                       (:P (+ -1 J) LO)
                       (INTEGERP J)
                       (<= 0 J))
                  (:P J LO))
         (IMPLIES (AND (NOT (EQUAL LO J))
                       (< (+ -1 J) 0)
                       (INTEGERP J)
                       (<= 0 J))
                  (:P J LO))
         (IMPLIES (AND (NOT (EQUAL LO J))
                       (NOT (INTEGERP (+ -1 J)))
                       (INTEGERP J)
                       (<= 0 J))
                  (:P J LO))
         (IMPLIES (AND (EQUAL LO J) (INTEGERP J) (<= 0 J))
                  (:P J LO))
         (IMPLIES (AND (INTEGERP J)
                       (<= 0 J)
                       (NOT (EQUAL LO J)))
                  (L< (LEX-FIX (ACL2-COUNT (+ -1 J)))
                      (LEX-FIX (ACL2-COUNT J))))).
    Note that one or more measure conjectures included in the scheme above
    justify this induction if they are provable.  When applied to the goal
    at hand the above induction scheme produces six nontautological subgoals.

    ...

  The first four proof obligations, which are all proved by the prover,
  implicitly include the hypotheses that [47mLO[0m is a natural below [47mJ[0m
  because they're hypotheses in the four conclusions, [47m(:P J LO)[0m.  But
  the last proof obligation has no hypotheses about [47mLO[0m other than the
  test in the body of the [47mloop$[0m, [47m(NOT (EQUAL LO J))[0m.  This proof
  obligation is not a theorem and the proof attempt will fail.

  If the prover had just generated the measure conjecture from the
  [47mderived-fn[0m the last proof obligation would be even more inadequate!

    (IMPLIES (NOT (EQUAL LO J))
             (L< (LEX-FIX (ACL2-COUNT (+ -1 J)))
                 (LEX-FIX (ACL2-COUNT J)))).

  But we see that the prover actually augmented the hypothesis from the
  body with two literals it assumed were relevant from the conjecture
  being proved, namely [47m(INTEGERP J)[0m and [47m(<= 0 J)[0m.  (The legality of
  such augmentation is illustrated by the book
  [47mprojects/apply/justification-of-do-induction.lisp[0m.)  However, it
  did not include any facts about [47mLO[0m other than the test in the [47mloop$[0m
  body.  This is a manifestation of the hidden hypothesis problem.
  In this case, we wish it had included [47m(NATP LO)[0m and [47m(<= LO J)[0m.
  (One can regard this as a heuristic inadequacy, but enlarging the
  set of hypotheses can cause proofs to fail and we've been
  conservative in our heuristics for augmenting [47mdo[0m [47mloop$[0m inductions.)

  You can fix this by providing an [47m:induct[0m hint.  The [47mloop$[0m statement
  in the hint below is exactly the [47mloop$[0m statement in the theorem
  except we've added the UPPERCASE text.  This proof succeeds.

    (defthm hidden-hyp-problem-main
      (implies (and (natp lo)
                    (natp j)
                    (<= lo j))
               (equal (loop$ with j = j
                             do
                             (if (equal lo j)
                                 (return 'good)
                                 (setq j (- j 1))))
                      'good))
      :hints ((\"Goal\"
               :induct
               (loop$ with j = j
                      do
                      (IF (AND (NATP LO) (<= LO J))
                          (if (equal lo j)
                              (return 'good)
                              (setq j (- j 1)))
                          (RETURN 'IRRELEVANT-BASE-CASE))))))

  [31;1mLesson 4[0m: You can use [47mloop$[0m to provide induction hints and those
  [47mloop$[0ms don't have to be identical to ones in your goal theorem.  In
  particular, your hint [47mloop$[0m might contain more case analysis than
  the [47mloop$[0ms in your conjecture.  You can use this fact to overcome
  the hidden hypothesis problem.

  Note that the derived function from the [47mloop$[0m in the hint doesn't
  terminate either (because no mention is made that [47mJ[0m is a natural).
  But the induction-time proof obligation is provable because it is
  still augmented by [47m(INTEGERP J)[0m and [47m(<= 0 J)[0m as before.


Avoiding Some Specially Defined Hint Functions

  Another lesson suggested by the example above is that you don't
  always have to define a recursive function to suggest certain
  inductions.  Here is an example.  Recall the function [47mrev1[0m from the
  beginning of this topic.  Now define the functions that ``mark''
  every element of a list and that check that every element is
  ``marked''.

    (defun mark-all (x)
      (if (consp x)
          (cons (list 'mark (car x))
                (mark-all (cdr x)))
          nil))

    (defun all-markedp (x)
      (if (consp x)
          (and (consp (car x))
               (eq (car (car x)) 'mark)
               (all-markedp (cdr x)))
          t)).

  Now prove

    (thm (implies (all-markedp a)
                  (all-markedp (rev1 (mark-all x) a))))

  No induction suggested by the functions in this theorem is
  appropriate.  The appropriate induction assumes the theorem for [47mx[0m
  replaced by [47m(cdr x)[0m and [47ma[0m replaced by [47m(cons (list 'mark (car x))
  a)[0m.  (This is an example of rippling as discussed by Bundy, Basin,
  Hutter and Ireland, in the book [3mRippling: Meta-Level Guidance for
  Mathematical Reasoning[0m, Cambridge University, UK, 2005.  But ACL2's
  induction heuristics don't implement rippling.)  We could, of
  course, define a recursive function that suggests the appropriate
  induction and provide it as a hint.  But in this case we needn't
  define a new function.  We can just use a [47mloop$[0m.

    (thm (implies (all-markedp a)
                  (all-markedp (rev1 (mark-all x) a)))
         :hints ((\"Goal\" :induct
                  (loop$ with x = x
                         with a = a
                         do
                         (if (consp x)
                             (progn (setq a (cons (list 'mark (car x)) a))
                                    (setq x (cdr x)))
                             (return 'base-case)))))).


Other Relevant :DOC Topics

  See [lp-section-11] of the [47mLoop$[0m Primer for a narrative of how we
  might solve a certain computational problem with a nest of two [47mFOR[0m
  [47mloop$[0m.  We also show how we verify the guards and then prove that
  the [47mloop$[0m solution is equivalent to a recursive solution.  In
  [lp-section-12] of the primer you'll find some exercises in proving
  theorems about [47mFOR[0m [47mLoop$[0ms (with answers in a Community Book).  In
  [lp-section-16] you'll find a narrative of how we might go about
  proving a theorem about a [47mDO[0m [47mLoop$[0m.  And in [lp-section-17] you'll
  find exercises in proving theorems about [47mDO[0m [47mLoop$[0ms (with answers in
  a Community Book).")
 (STEP-LIMIT (POINTERS)
             "See [with-prover-step-limit].")
 (STOBJ
  (PROGRAMMING)
  "Single-threaded objects or ``von Neumann bottlenecks''

  In ACL2, a ``single-threaded object'' is a data structure whose use
  is so syntactically restricted that only one instance of the object
  need ever exist and its fields can be updated by destructive
  assignments.

  Note: Novices are advised to avoid using single-threaded objects,
  perhaps instead using [std::defaggregate] or community book
  [47mbooks/data-structures/structures.lisp[0m.  At the least, consider
  using [47m([0m[47m[set-verify-guards-eagerness][0m[47m 0)[0m to avoid [guard]
  verification.

  This topic introduces the notion of a ``stobj'', or single-threaded
  object.  It concludes with a link to a tour that introduces the use
  of stobjs by way of examples.  We recommend that you follow that
  link the first time you read about stobjs.  Detailed reference
  documentation about stobjs may be found in the subtopics listed at
  the end below; in particular see [defstobj] and, for so-called
  abstract stobjs, see [defabsstobj].

  As noted, a ``single-threaded object'' is a data structure whose use
  is so syntactically restricted that only one instance of the object
  need ever exist.  Updates to the object must be sequentialized.
  This allows us to update its fields with destructive assignments
  without wrecking the axiomatic semantics of update-by-copy.  For
  this reason, single-threaded objects are sometimes called ``von
  Neumann bottlenecks.''

  From the logical perspective, a single-threaded object is an ordinary
  ACL2 object, e.g., composed of integers and conses.  Logically
  speaking, ordinary ACL2 functions are defined to allow the user to
  ``access'' and ``update'' its fields.  Logically speaking, when
  fields in the object, obj, are ``updated'' with new values, a new
  object, obj', is constructed.

  But suppose that by syntactic means we could ensure that there were
  no more references to the ``old'' object, obj.  Then we could
  create obj' by destructively modifying the memory locations
  involved in the representation of obj.  The syntactic means is
  pretty simple but draconian: the only reference to obj is in the
  variable named [47mOBJ[0m.

  The consequences of this simple rule are far-reaching and require
  some getting used to.  For example, if [47mOBJ[0m has been declared as a
  single-threaded object name, then the following consequences ensue
  (but see the discussion at the end of this topic for some
  relaxations).

    * [47mOBJ[0m is a top-level global variable that contains the current object,
      obj.

    * If a function uses the formal parameter [47mOBJ[0m that is declared as a
      stobj, the only ``actual expression'' that can be passed into
      that slot is the variable [47mOBJ[0m, not merely a term that
      ``evaluates to an obj''; thus, such functions can only operate
      on the current object.  So for example, instead of [47m(FOO
      (UPDATE-FIELD1 3 ST))[0m write [47m(LET ((ST (UPDATE-FIELD1 3 ST)))
      (FOO ST))[0m.  And instead of [47m(MV X (LET ((ST (UPDATE-FIELD1 3
      ST))) (FOO ST)))[0m write [47m(LET ((ST (UPDATE-FIELD1 3 ST))) (MV X
      ST))[0m.

    * The accessors and updaters have a formal parameter named [47mOBJ[0m, so by
      the rule just above, those functions can only be applied to the
      current object.  The recognizer is the one exception to the
      rule: it may be applied either the [47mOBJ[0m or to an ordinary
      (non-stobj) object.

    * The ACL2 primitives, such as [47mCONS[0m, [47mCAR[0m and [47mCDR[0m, may not be applied to
      the variable [47mOBJ[0m.  Thus, for example, obj may not be consed
      into a list (which would create another pointer to it) or
      accessed or copied via ``unapproved'' means.

    * The updaters return a ``new [47mOBJ[0m object'', i.e., obj'; thus, when an
      updater is called, the only variable which can hold its result
      is [47mOBJ[0m.

    * If a function calls an [47mOBJ[0m updater, it must return an [47mOBJ[0m object
      (either as the sole value returned, or in [47m(mv ... OBJ ...)[0m; see
      [mv]).

    * When a top-level expression involving [47mOBJ[0m returns an [47mOBJ[0m object, that
      object becomes the new current value of [47mOBJ[0m.

  There are other functional languages supporting single-threadedness,
  for example Haskell's ``monads'' and Clean's ``uniqueness type
  system''.  Of course, ACL2 provides a theorem prover that can prove
  theorems that involve such constructs.

  Note that the syntactic restrictions noted above are enforced only
  when single-threaded objects are encountered directly in the
  top-level loop or are used in function definitions; the accessor
  and update functions for single-threaded objects may be used
  without restriction in formulas to be proved.  Since function
  evaluation is sometimes necessary during proofs, ACL2 must be able
  to evaluate these functions on logical constants representing the
  object, even when the constant is not ``the current object.'' Thus,
  ACL2 supports both the efficient von Neumann semantics and the
  clean applicative semantics, and uses the first in contexts where
  execution speed is paramount and the second during proofs.

  [47m[Defstobj][0m and [47m[defabsstobj][0m [events] introduce stobjs.  See
  [defstobj] for more details about stobjs.  In particular, a
  relatively advanced notion of ``congruent stobjs'' is discussed
  there.  The idea is to allow a stobj, [47mst2[0m, of the same ``shape'' as
  a given stobj, [47mst1[0m, to be used in place of [47mst1[0m.  Other [47m[defstobj][0m
  keywords allow inlining and renaming of stobj accessors and
  updaters, and a [47m:non-executable[0m keyword can be used to defer or
  totally avoid creating a ``global'' stobj for the given stobj name.

  But we are getting ahead of ourselves.  To start the stobj tour
  recommended earlier in this topic, see [stobj-example-1].


Subtopics

  [Add-global-stobj]
      Add a global [stobj] with a given name

  [Count-keys]
      Count the number of keys in association list

  [Declare-stobjs]
      Declaring a formal parameter name to be a single-threaded object

  [Defabsstobj]
      Define a new abstract single-threaded object

  [Defstobj]
      Define a new single-threaded object

  [Nested-stobjs]
      Using [stobj]s that contain stobjs

  [Nth-aliases-table]
      A [table] used to associate names for nth/update-nth printing

  [Remove-global-stobj]
      Remove a global [stobj] with a given name

  [Resize-list]
      List resizer in support of [stobj]s

  [Stobj-example-1]
      An example of the use of single-threaded objects

  [Stobj-example-1-defuns]
      The defuns created by the [47mcounters[0m stobj

  [Stobj-example-1-implementation]
      The implementation of the [47mcounters[0m stobj

  [Stobj-example-1-proofs]
      Some proofs involving the [47mcounters[0m stobj

  [Stobj-example-2]
      An example of the use of arrays in single-threaded objects

  [Stobj-example-3]
      Another example of a single-threaded object

  [Stobj-table]
      A [stobj] field mapping stobj names to stobjs

  [Swap-stobjs]
      Swap two congruent [stobj]s

  [Trans-eval-and-locally-bound-stobjs]
      [47m[Trans-eval][0m deals in global [stobj]s.

  [Trans-eval-and-stobjs]
      How user-defined [stobj]s are handled by [47m[trans-eval][0m

  [Update-nth-array]
      Update a stobj array

  [User-stobjs-modified-warnings]
      Interactions of [47m[trans-eval][0m with [stobj]s that violate applicative
      semantics

  [With-global-stobj]
      Operate on a global single-threaded object

  [With-local-state]
      Locally bind state

  [With-local-stobj]
      Locally bind a single-threaded object")
 (STOBJ-EXAMPLE-1
  (STOBJ)
  "An example of the use of single-threaded objects

  Suppose we want to sweep a tree and (1) count the number of interior
  nodes, (2) count the number of tips and (3) keep a record of every
  tip we encounter that is an integer.  We could use a
  single-threaded object as our ``accumulator''.  Such an object
  would have three fields, one holding the number of nodes seen so
  far, one holding the number of tips, and one holding all the
  integer tips seen.

  The following event declares [47mcounters[0m to be a single-threaded object.

    (defstobj counters
      (NodeCnt     :type integer :initially 0)
      (TipCnt      :type integer :initially 0)
      (IntTipsSeen :type t       :initially nil))

  It has three fields, [47mNodeCnt[0m, [47mTipCnt[0m, and [47mIntTipsSeen[0m.  (As always in
  ACL2, capitalization is irrelevant in simple symbol names, so the
  first name could be written [47mnodecnt[0m or [47mNODECNT[0m, etc.) Those are the
  name of the accessor functions for the object.  The corresponding
  update functions are named [47mupdate-NodeCnt[0m, [47mupdate-TipCnt[0m and
  [47mupdate-IntTipsSeen[0m.

  If you do not like the default function names chosen above, there is
  a feature in the [47m[defstobj][0m event that allows you to specify other
  names.

  If you want to see the ACL2 definitions of all the functions defined
  by this event, look at [stobj-example-1-defuns].

  If, after this event, we evaluate the top-level ``global variable''
  [47mcounters[0m in the ACL2 read-eval-print loop we get:

    ACL2 !>counters
    <counters>

  Note that the value printed is ``[47m<counters>[0m''.  Actually, the value
  of [47mcounters[0m in the logic is [47m(0 0 NIL)[0m.  But ACL2 always prints
  single-threaded objects in this non-informative way because they
  are usually so big that to do otherwise would be unpleasant.

  Had you tried to evaluate the ``global variable'' [47mcounters[0m before
  declaring it a single-threaded object, ACL2 would have complained
  that it does not support global variables.  So a lesson here is
  that once you have declared a new single-threaded object your
  top-level forms can reference it.  In versions of ACL2 prior to
  Version 2.4 the only variable enjoying this status was [47mSTATE[0m.
  single-threaded objects are a straightforward generalization of the
  long-implemented von Neumann [47m[state][0m feature of ACL2.

  We can access the fields of [47mcounters[0m as with:

    ACL2 !>(NodeCnt counters)
    0
    ACL2 !>(IntTipsSeen counters)
    NIL

  and we can set the fields of [47mcounters[0m as with:

    ACL2 !>(update-NodeCnt 3 counters)
    <counters>
    ACL2 !>(NodeCnt counters)
    3

  Observe that when we evaluate an expression that returns a counter
  object, that object becomes the ``current value'' of [47mcounters[0m.

  Here is a function that ``converts'' the [47mcounters[0m object to its
  ``ordinary'' representation:

    (defun show-counters (counters)
      (declare (xargs :stobjs (counters)))
      (list (NodeCnt counters)
            (TipCnt counters)
            (IntTipsSeen counters)))

  Observe that we [3mmust[0m declare, at the top of the [47mdefun[0m, that we mean
  to use the formal parameter [47mcounters[0m as a single-threaded object!
  If we did not make this declaration, the body of [47mshow-counters[0m
  would be processed as though [47mcounters[0m were an ordinary object.  An
  error would be caused because the accessors used above cannot be
  applied to anything but the single-threaded object [47mcounters[0m.  If
  you want to know why we insist on this declaration, see
  [declare-stobjs].

  When [47mshow-counters[0m is admitted, the following message is printed:

    Since SHOW-COUNTERS is non-recursive, its admission is trivial.  We
    observe that the type of SHOW-COUNTERS is described by the theorem
    (AND (CONSP (SHOW-COUNTERS COUNTERS))
         (TRUE-LISTP (SHOW-COUNTERS COUNTERS))).
    We used primitive type reasoning.

    (SHOW-COUNTERS COUNTERS) => *.

    The guard conjecture for SHOW-COUNTERS is trivial to prove.
    SHOW-COUNTERS is compliant with Common Lisp.

  The line above containing the ``=>'' is called the ``signature'' of
  [47mshow-counters[0m; it conveys the information that the first argument
  is the single-threaded object [47mcounters[0m and the only result is an
  ordinary object.  Here is an example of another signature:

    (PROCESSOR * * COUNTERS) => (MV * COUNTERS)

  which indicates that the function [47mPROCESSOR[0m (which we haven't shown
  you) takes three arguments, the third of which is the [47mCOUNTERS[0m
  stobj, and returns two results, the second of which is the modified
  [47mCOUNTERS[0m.

  Returning to the admission of [47mshow-counters[0m above, the last sentence
  printed indicates that the [47m[guard][0m conjectures for the function
  were proved.  When some argument of a function is declared to be a
  single-threaded object via the [47mxargs[0m, [47m:stobjs[0m, we automatically add
  (conjoin) to the guard the condition that the argument satisfy the
  recognizer for that single-threaded object.  In the case of
  [47mshow-counters[0m the guard is [47m(countersp counters)[0m.

  Here is an example of [47mshow-counters[0m being called:

    ACL2 !>(show-counters counters)
    (3 0 NIL)

  This is what we would see had we set the [47mNodeCnt[0m field of the initial
  value of [47mcounters[0m to [47m3[0m, as we did earlier in this example.

  We next wish to define a function to reset the [47mcounters[0m object.  We
  could define it this way:

    (defun reset-counters (counters)
      (declare (xargs :stobjs (counters)))
      (let ((counters (update-NodeCnt 0 counters)))
        (let ((counters (update-TipCnt 0 counters)))
          (update-IntTipsSeen nil counters))))

  which ``successively'' sets the [47mNodeCnt[0m field to [47m0[0m, then the [47mTipCnt[0m
  field to [47m0[0m, and then the [47mIntTipsSeen[0m field to [47mnil[0m and returns the
  resulting object.

  However, the nest of [47mlet[0m expressions is tedious and we use this
  definition instead.  This definition exploits a macro, here named
  ``[47mseq[0m'' (for ``sequentially'') which evaluates each of the forms
  given, binding their results successively to the stobj name given.

    (defun reset-counters (counters)
      (declare (xargs :stobjs (counters)))
      (seq counters
           (update-NodeCnt 0 counters)
           (update-TipCnt 0 counters)
           (update-IntTipsSeen nil counters)))

  This definition is syntactically identical to the one above, after
  macro expansion.  Our definition of [47mseq[0m is shown below and is not
  part of native ACL2.

    (defmacro seq (stobj &rest rst)
      (cond ((endp rst) stobj)
            ((endp (cdr rst)) (car rst))
            (t `(let ((,stobj ,(car rst)))
                 (seq ,stobj ,@(cdr rst))))))

  The signature printed for [47mreset-counters[0m is

    (RESET-COUNTERS COUNTERS) => COUNTERS.

  Here is an example.

    ACL2 !>(show-counters counters)
    (3 0 NIL)
    ACL2 !>(reset-counters counters)
    <counters>
    ACL2 !>(show-counters counters)
    (0 0 NIL)

  Here finally is a function that uses [47mcounters[0m as a single-threaded
  accumulator to collect the desired information about the tree [47mx[0m.

    (defun sweep-tree (x counters)
      (declare (xargs :stobjs (counters)))
      (cond ((atom x)
             (seq counters
                  (update-TipCnt (+ 1 (TipCnt counters)) counters)
                  (if (integerp x)
                      (update-IntTipsSeen (cons x (IntTipsSeen counters))
                                      counters)
                    counters)))
            (t (seq counters
                    (update-NodeCnt (+ 1 (NodeCnt counters)) counters)
                    (sweep-tree (car x) counters)
                    (sweep-tree (cdr x) counters)))))

  We can paraphrase this definition as follows.  If [47mx[0m is an atom, then
  increment the [47mTipCnt[0m field of [47mcounters[0m and [3mthen[0m, if [47mx[0m is an
  integer, add [47mx[0m to the [47mIntTipsSeen[0m field, and return [47mcounters[0m.  On
  the other hand, if [47mx[0m is not an atom, then increment the [47mNodeCnt[0m
  field of [47mcounters[0m, and [3mthen[0m sweep the [47mcar[0m of [47mx[0m and [3mthen[0m sweep the
  [47mcdr[0m of [47mx[0m and return the result.

  Here is an example of its execution.  We have displayed the input
  tree in full dot notation so that the number of interior nodes is
  just the number of dots.

    ACL2 !>(sweep-tree '((((a . 1) . (2 . b)) . 3)
                         . (4 . (5 . d)))
                       counters)
    <counters>
    ACL2 !>(show-counters counters)
    (7 8 (5 4 3 2 1))
    ACL2 !>(reset-counters counters)
    <counters>
    ACL2 !>(show-counters counters)
    (0 0 NIL)

  The [47mcounters[0m object has two integer fields and a field whose type is
  unrestricted.  single-threaded objects support other types of
  fields, such as arrays.  We deal with that in the
  [stobj-example-2].  But we recommend that you first consider the
  implementation issues for the [47mcounters[0m example (in
  [stobj-example-1-implementation]) and then consider the proof
  issues (in [stobj-example-1-proofs]).

  To continue the stobj tour, see [stobj-example-2].")
 (STOBJ-EXAMPLE-1-DEFUNS
  (STOBJ)
  "The defuns created by the [47mcounters[0m stobj

  Consider the event shown in [stobj-example-1]:

    (defstobj counters
      (NodeCnt     :type integer :initially 0)
      (TipCnt      :type integer :initially 0)
      (IntTipsSeen :type t       :initially nil))

  Here is a complete list of the defuns added by the event.

  The careful reader will note that the [47mcounters[0m argument below is [3mnot[0m
  declared with the [47m:stobjs[0m [47mxarg[0m even though we insist that the
  argument be a stobj in calls of these functions.  This ``mystery''
  is explained below.

    (defun NodeCntp (x)                 ;;; Recognizer for 1st field
      (declare (xargs :guard t :verify-guards t))
      (integerp x))

    (defun TipCntp (x)                  ;;; Recognizer for 2nd field
      (declare (xargs :guard t :verify-guards t))
      (integerp x))

    (defun IntTipsSeenp (x)             ;;; Recognizer for 3rd field
      (declare (xargs :guard t :verify-guards t) (ignore x))
      t)

    (defun countersp (counters)         ;;; Recognizer for object
      (declare (xargs :guard t :verify-guards t))
      (and (true-listp counters)
           (= (length counters) 3)
           (NodeCntp (nth 0 counters))
           (TipCntp (nth 1 counters))
           (IntTipsSeenp (nth 2 counters))
           t))

    (defun create-counters ()           ;;; Creator for object
      (declare (xargs :guard t :verify-guards t))
      (list '0 '0 'nil))

    (defun NodeCnt (counters)           ;;; Accessor for 1st field
      (declare (xargs :guard (countersp counters) :verify-guards t))
      (nth 0 counters))

    (defun update-NodeCnt (v counters)  ;;; Updater for 1st field
      (declare (xargs :guard
                      (and (integerp v)
                           (countersp counters))
                      :verify-guards t))
      (update-nth 0 v counters))

    (defun TipCnt (counters)            ;;; Accessor for 2nd field
      (declare (xargs :guard (countersp counters) :verify-guards t))
      (nth 1 counters))

    (defun update-TipCnt (v counters)   ;;; Updater for 2nd field
      (declare (xargs :guard
                      (and (integerp v)
                           (countersp counters))
                      :verify-guards t))
      (update-nth 1 v counters))

    (defun IntTipsSeen (counters)       ;;; Accessor for 3rd field
      (declare (xargs :guard (countersp counters) :verify-guards t))
      (nth 2 counters))

    (defun update-IntTipsSeen (v counters) ;;; Updater for 3rd field
      (declare (xargs :guard (countersp counters) :verify-guards t))
      (update-nth 2 v counters))

  Observe that there is a recognizer for each of the three fields and
  then a recognizer for the [47mcounters[0m object itself.  Then, for each
  field, there is an accessor and an updater.

  Observe also that the functions are guarded so that they expect a
  [47mcountersp[0m for their [47mcounters[0m argument and an appropriate value for
  the new field values.

  You can see all of the [47mdefuns[0m added by a [47mdefstobj[0m event by executing
  the event and then using the [47m:pcb![0m command on the stobj name.
  E.g.,

    ACL2 !>:pcb! counters

  will print the defuns above.

  We now clear up the ``mystery'' mentioned above.  Note, for example
  in [47mTipCnt[0m, that the formal [47mcounters[0m is used.  From the discussion
  in [stobj-example-1] it has been made clear that [47mTipCnt[0m can only be
  called on the [47mcounters[0m object.  And yet, in that same discussion it
  was said that an argument is so treated only if it it declared
  among the [47m:stobjs[0m in the definition of the function.  So why
  doesn't [47mTipCnt[0m include something like [47m(declare (xargs :stobjs
  (counters)))[0m?

  The explanation of this mystery is as follows.  At the time [47mTipCnt[0m
  was defined, during the introduction of the [47mcounters[0m stobj, the
  name ``[47mcounters[0m'' was not yet a single-threaded object.  The
  introduction of a new single-threaded object occurs in three steps:
  (1) The new primitive recognizers, accessors, and updaters are
  introduced as ``ordinary functions,'' producing their logical
  axiomatizations.  (2) The executable-counterparts are defined in
  raw Lisp to support destructive updating.  (3) The new name is
  declared a single-threaded object to ensure that all future use of
  these primitives respects the single-threadedness of the object.
  The functions defined as part of the introduction of a new
  single-threaded object are the only functions in the system that
  have undeclared stobj formals other than [47mstate[0m.

  You may return to [stobj-example-1] here.")
 (STOBJ-EXAMPLE-1-IMPLEMENTATION
  (STOBJ)
  "The implementation of the [47mcounters[0m stobj

  The event

    (defstobj counters
      (NodeCnt     :type integer :initially 0)
      (TipCnt      :type integer :initially 0)
      (IntTipsSeen :type t       :initially nil))

  discussed in [stobj-example-1], creates a Common Lisp object to
  represent the current value of [47mcounters[0m.  That object is created by
  evaluating either of the following ``raw'' (non-ACL2) Common Lisp
  forms:

    (create-counters)

    (vector (make-array 1 :element-type 'integer
                          :initial-element '0)
            (make-array 1 :element-type 'integer
                          :initial-element '0)
            'nil)

  and the value is stored in the Common Lisp global variable named
  [47m*the-live-counters*[0m.

  Thus, the [47mcounters[0m object is an array of length three.  The first two
  elements are arrays of size 1 and are used to hold the [47mNodeCnt[0m and
  [47mTipCnt[0m fields.  The third element is the [47mIntTipsSeen[0m field.  The
  first two fields are represented by arrays so that we can implement
  the [47minteger[0m type specification efficiently.  Generally, integers
  are ``boxed'' in some Common Lisp implementations, for example,
  GCL.  Creating a new integer requires creating a new box to put it
  in.  But in some lisps, including GCL, the integers inside arrays
  of integers are not boxed.

  The function [47mNodeCnt[0m is defined in raw Lisp as:

    (defun NodeCnt (counters)
      (the integer
           (aref (the (simple-array integer (1))
                      (svref counters 0))
                 0)))

  Observe that the form [47m(svref counters 0)[0m is evaluated to get an array
  of size 1, which is followed by a call of [47maref[0m to access the 0th
  element of that array.

  The function [47mupdate-NodeCnt[0m is defined in raw Lisp as:

    (defun update-NodeCnt (v counters)
      (declare (type integer v))
      (progn
       (setf (aref (the (simple-array integer (1))
                        (svref counters 0))
                   0)
             (the integer v))
       counters))

  Note that when this function is called, it does not create a new
  vector of length three, but ``smashes'' the existing one.

  One way to see all the raw Lisp functions defined by a given [47mdefstobj[0m
  is to evaluate the [47mdefstobj[0m event and then evaluate, in the ACL2
  loop, the expression [47m(nth 4 (global-val 'cltl-command (w state)))[0m.
  Those functions that contain [47m(DECLARE (STOBJ-INLINE-FN T))[0m will
  generate [47m[defabbrev][0m forms because the [47m:inline[0m keyword of
  [47m[defstobj][0m was supplied the value [47mt[0m.  The rest will generate
  [47m[defun][0ms.

  We now recommend that you look at [stobj-example-1-proofs].")
 (STOBJ-EXAMPLE-1-PROOFS
  (STOBJ)
  "Some proofs involving the [47mcounters[0m stobj

  Consider again the event

    (defstobj counters
      (NodeCnt     :type integer :initially 0)
      (TipCnt      :type integer :initially 0)
      (IntTipsSeen :type t       :initially nil))

  discussed in [stobj-example-1], followed by the definition

    (defun reset-counters (counters)
      (declare (xargs :stobjs (counters)))
      (seq counters
           (update-NodeCnt 0 counters)
           (update-TipCnt 0 counters)
           (update-IntTipsSeen nil counters)))

  which, because of the [47mseq[0m macro in [stobj-example-1], is just
  syntactic sugar for

    (defun reset-counters (counters)
      (declare (xargs :stobjs (counters)))
      (let ((counters (update-NodeCnt 0 counters)))
        (let ((counters (update-TipCnt 0 counters)))
          (update-IntTipsSeen nil counters)))).

  Here is a simple theorem about [47mreset-counters[0m.

    (defthm reset-counters-is-constant
      (implies (countersp x)
               (equal (reset-counters x)
                      '(0 0 nil))))

  Before we talk about how to prove this theorem, note that the theorem
  is unusual in two respects.

  First, it calls [47mreset-counters[0m on an argument other than the variable
  [47mcounters[0m!  That is allowed in theorems; logically speaking, the
  stobj functions are indistinguishable from ordinary functions.
  Their use is syntactically restricted only in [47mdefun[0ms, which might
  be compiled and run in raw Lisp.  Those restrictions allow us to
  implement stobj modification destructively.  But logically
  speaking, [47mreset-counters[0m and other stobj ``modifying'' functions
  just create new objects, constructively.

  Second, the theorem above explicitly provides the hypothesis that
  [47mreset-counters[0m is being applied to an object satisfying [47mcountersp[0m.
  Such a hypothesis is not always required: [47mreset-counters[0m is total
  and will do something no matter what [47mx[0m is.  But in this particular
  case, the result is not [47m'(0 0 nil)[0m unless [47mx[0m is, at least, a
  true-list of length three.

  To make a long story short, to prove theorems about stobj functions
  you behave in exactly the way you would to prove the same theorems
  about the same functions defined without the stobj features.

  How can we prove the above theorem?  Unfolding the definition of
  [47mreset-counters[0m shows that [47m(reset-counters x)[0m is equal to

    (update-IntTipsSeen nil
      (update-TipCnt 0
        (update-NodeCnt 0 x)))

  which in turn is

    (update-nth 2 nil
     (update-nth 1 0
      (update-nth 0 0 x))).

  Opening up the definition of [47mupdate-nth[0m reduces this to

    (list* 0 0 nil (cdddr x)).

  This is clearly equal to [47m'(0 0 nil)[0m, provided we know that [47m(cdddr x)[0m
  is [47mnil[0m.

  Unfortunately, that last fact requires a lemma.  The most specific
  lemma we could provide is

    (defthm special-lemma-for-counters
      (implies (countersp x)
               (equal (cdddr x) nil)))

  but if you try to prove that lemma you will find that it requires
  some reasoning about [47mlen[0m and [47mtrue-listp[0m.  Furthermore, the special
  lemma above is of interest only for [47mcounters[0m.

  The following lemma about [47mlen[0m is the one we prefer.

    (defthm equal-len-n
      (implies (syntaxp (quotep n))
               (equal (equal (len x) n)
                      (if (integerp n)
                          (if (< n 0)
                              nil
                            (if (equal n 0)
                                (atom x)
                              (and (consp x)
                                   (equal (len (cdr x)) (- n 1)))))
                        nil))))

  This lemma will simplify any equality in which a [47mlen[0m expression is
  equated to any explicitly given constant [3mn[0m, e.g., [47m3[0m, reducing the
  equation to a conjunction of [47mconsp[0m terms about the first [3mn[0m [47mcdr[0ms.

  If the above lemma is available then ACL2 immediately proves

    (defthm reset-counters-is-constant
      (implies (countersp x)
               (equal (reset-counters x)
                      '(0 0 nil))))

  The point is presumably well made: proving theorems about
  single-threaded object accessors and updaters is no different than
  proving theorems about other recursively defined functions on
  lists.

  As we have seen, operations on [stobj]s turn into definitions
  involving [47m[nth][0m and [47m[update-nth][0m in the logic.  Here are two
  lemmas, both due to Matt Wilding, that are useful for simplifying
  terms involving [47mnth[0m and [47mupdate-nth[0m, which are therefore useful in
  reasoning about single-threaded objects.

    (defthm update-nth-update-nth-same
      (implies (equal (nfix i1) (nfix i2))
               (equal (update-nth i1 v1 (update-nth i2 v2 l))
                      (update-nth i1 v1 l))))

    (defthm update-nth-update-nth-diff
      (implies (not (equal (nfix i1) (nfix i2)))
               (equal (update-nth i1 v1 (update-nth i2 v2 l))
                      (update-nth i2 v2 (update-nth i1 v1 l))))
      :rule-classes ((:rewrite :loop-stopper ((i1 i2)))))

  We now recommend that you see [stobj-example-2].")
 (STOBJ-EXAMPLE-2
  (STOBJ)
  "An example of the use of arrays in single-threaded objects

  The following event

    (defstobj ms
      (pcn  :type integer                  :initially 0)
      (mem  :type (array integer (100000)) :initially -1)
      (code :type t                        :initially nil))

  introduces a single-threaded object named [47mms[0m (which stands for
  ``machine state'').  The object has three fields, a [47mpcn[0m or program
  counter, a [47mmem[0m or memory, and a [47mcode[0m field.

  The [47mmem[0m field is occupied by an object initially of type [47m(array
  integer (100000))[0m.  Logically speaking, this is a list of length
  [47m100000[0m, each element of which is an integer.  But in the underlying
  implementation of the [47mms[0m object, this field is occupied by a raw
  Lisp array, initially of size 100000.

  You might expect the above [47mdefstobj[0m to define the accessor function
  [47mmem[0m and the updater [47mupdate-mem[0m.  [3mThat does not happen![0m.

  The above event defines the accessor function [47mmemi[0m and the updater
  [47mupdate-memi[0m.  These functions do not access/update the [47mmem[0m field of
  the [47mms[0m object; they access/update the individual elements of the
  array in that field.

  In particular, the logical definitions of the two functions are:

    (defun memi (i ms)
      (declare (xargs :guard
                      (and (msp ms)
                           (integerp i)
                           (<= 0 i)
                           (< i (mem-length ms)))))
      (nth i (nth 1 ms)))

    (defun update-memi (i v ms)
      (declare (xargs :guard
                      (and (msp ms)
                           (integerp i)
                           (<= 0 i)
                           (< i (mem-length ms))
                           (integerp v))))
      (update-nth-array 1 i v ms))

  For example, to access the 511th (0-based) memory location of the
  current [47mms[0m you could evaluate:

    ACL2 !>(memi 511 ms)
    -1

  The answer is [47m-1[0m initially, because that is the above-specified
  initial value of the elements of the [47mmem[0m array.

  To set that element you could do

    ACL2 !>(update-memi 511 777 ms)
    <ms>
    ACL2 !>(memi 511 ms)
    777

  The raw Lisp implementing these two functions is shown below.

    (defun memi (i ms)
      (declare (type (and fixnum (integer 0 *)) i))
      (the integer
           (aref (the (simple-array integer (*))
                      (svref ms 1))
                 (the (and fixnum (integer 0 *)) i))))

    (defun update-memi (i v ms)
      (declare (type (and fixnum (integer 0 *)) i)
               (type integer v))
      (progn
       (setf (aref (the (simple-array integer (*))
                        (svref ms 1))
                   (the (and fixnum (integer 0 *)) i))
             (the integer v))
       ms))

  If you want to see the raw Lisp supporting a [47mdefstobj[0m, execute the
  [47mdefstobj[0m and then evaluate the ACL2 form [47m(nth 4 (global-val
  'cltl-command (w state)))[0m.

  To continue the stobj tour, see [stobj-example-3].")
 (STOBJ-EXAMPLE-3
  (STOBJ)
  "Another example of a single-threaded object

  The event

    (defstobj $s
      (x :type integer :initially 0)
      (a :type (array (integer 0 9) (3)) :initially 9 :resizable t))

  introduces a stobj named [47m$S[0m.  The stobj has two fields, [47mX[0m and [47mA[0m.  The
  [47mA[0m field is an array.  The [47mX[0m field contains an integer and is
  initially 0.  The [47mA[0m field contains a list of integers, each between
  0 and 9, inclusively.  (Under the hood, this ``list'' is actually
  implemented as an array.)  Initially, the [47mA[0m field has three
  elements, each of which is 9.

  This event introduces the following sequence of function definitions:

    (DEFUN XP (X) ...)               ; recognizer for X field
    (DEFUN AP (X) ...)               ; recognizer of A field
    (DEFUN $SP ($S) ...)             ; top-level recognizer for stobj $S
    (DEFUN CREATE-$S NIL ...)        ; 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 (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

  Here is the definition of [47m$SP[0m:

    (DEFUN $SP ($S)
      (DECLARE (XARGS :GUARD T :VERIFY-GUARDS T))
      (AND (TRUE-LISTP $S)
           (= (LENGTH $S) 2)
           (XP (NTH 0 $S))
           (AP (NTH 1 $S))
           T))

  This reveals that in order to satisfy [47m$SP[0m an object must be a true
  list of length 2 whose first element satisfies [47mXP[0m and whose second
  satisfies [47mAP[0m.  By printing the definition of [47mAP[0m one learns that it
  requires its argument to be a true list, each element of which is
  an integer between 0 and 9.

  The initial value of stobj [47m$S[0m is given by zero-ary ``creator''
  function [47mCREATE-$S[0m.  Creator functions may only be used in limited
  contexts.  See [with-local-stobj].

  Here is the definition of [47mUPDATE-AI[0m, the updater for the [47mA[0m field at
  index [47mI[0m:

    (DEFUN UPDATE-AI (I V $S)
      (DECLARE (XARGS :GUARD
                      (AND ($SP $S)
                           (INTEGERP I)
                           (<= 0 I)
                           (< I (A-LENGTH $S))
                           (AND (INTEGERP V) (<= 0 V) (<= V 9)))
                      :VERIFY-GUARDS T))
      (UPDATE-NTH-ARRAY 1 I V $S))

  By definition [47m(UPDATE-NTH-ARRAY 1 I V $S)[0m is [47m(UPDATE-NTH 1
  (UPDATE-NTH I V (NTH 1 $S)) $S)[0m.  This may be a little surprising
  but should be perfectly clear.

  First, ignore the guard, since it is irrelevant in the logic.
  Reading from the inside out, [47m(UPDATE-AI I V $S)[0m extracts [47m(NTH 1
  $S)[0m, which is array [47ma[0m of [47m$S[0m.  (Recall that [47m[nth][0m is 0-based.)  The
  next higher expression in the definition above, [47m(UPDATE-NTH I V a)[0m,
  ``modifies'' [47ma[0m by setting its [47mI[0mth element to [47mV[0m.  Call this [47ma'[0m.  The
  next higher expression, [47m(UPDATE-NTH 1 a' $S)[0m, ``modifies'' [47m$S[0m by
  setting its 1st component to [47ma'[0m.  Call this result [47m$s'[0m.  Then [47m$s'[0m
  is the result returned by [47mUPDATE-AI[0m.

  So the first useful observation is that from the perspective of the
  logic, the type ``restrictions'' on stobjs are irrelevant.  They
  are ``enforced'' by ACL2's guard mechanism, not by the definitions
  of the updater functions.

  As one might also imagine, the accessor functions do not really
  ``care,'' logically, whether they are applied to well-formed stobjs
  or not.  For example, [47m(AI I $S)[0m is defined to be [47m(NTH I (NTH 1
  $S))[0m.

  Thus, you will not be able to prove that (AI 2 $S) is an integer.
  That is,

    (integerp (AI 2 $S))

  is not a theorem, because [47m$S[0m may not be well-formed.

  Now [47m(integerp (AI 2 $S))[0m will always evaluate to [47mT[0m in the top-level
  ACL2 command loop, because we insist that the current value of the
  stobj [47m$S[0m always satisfies [47m$SP[0m by enforcing the guards on the
  updaters, independent of whether guard checking is on or off; see
  [set-guard-checking].  But in a theorem [47m$S[0m is just another
  variable, implicitly universally quantified.

  So [47m(integerp (AI 2 $S))[0m is not a theorem because it is not true when
  the variable [47m$S[0m is instantiated with, say,

    '(1 (0 1 TWO))

  because, logically speaking, [47m(AI 2 '(1 (0 1 TWO)))[0m evaluates to the
  symbol [47mTWO[0m.  That is,

    (equal (AI 2 '(1 (0 1 TWO))) 'TWO)

  is true.

  However,

    (implies (and ($SP $S) (< 2 (A-LENGTH $S))) (integerp (AI 2 $S)))

  is a theorem.  To prove it, you will have to prove a lemma about [47mAP[0m.
  The following will do:

    (defthm ap-nth
      (implies (and (AP x)
                    (integerp i)
                    (<= 0 i)
                    (< i (len x)))
               (integerp (nth i x)))).

  Similarly,

    (implies (and (integerp i)
                  (<= 0 i)
                  (< i (A-LENGTH $S))
                  (integerp v)
                  (<= 0 v)
                  (<= v 9))
             ($SP (UPDATE-AI i v $S)))

  is not a theorem until you add the additional hypothesis [47m($SP $S)[0m.
  To prove the resulting theorem, you will need a lemma such as the
  following.

    (defthm ap-update-nth
      (implies (and (AP a)
                    (integerp v)
                    (<= 0 v)
                    (<= v 9)
                    (integerp i)
                    (<= 0 i)
                    (< i (len a)))
               (AP (update-nth i v a))))

  The moral here is that from the logical perspective, you must provide
  the hypotheses that, as a programmer, you think are implicit on the
  structure of your stobjs, and you must prove their invariance.
  This is a good area for further support, perhaps in the form of a
  library of macros.

  [3mResizing Array Fields[0m

  Recall the specification of the array field, [47mA[0m for the stobj [47m$S[0m
  introduced above:

    (a :type (array (integer 0 9) (3)) :initially 9 :resizable t)

  Logically, this field is a list, initially of length 3.  Under the
  hood, this field is implemented using a Common Lisp array with 3
  elements.  In some applications, one may wish to lengthen an array
  field, or even (to reclaim space) to shrink an array field.  The
  [47m[defstobj][0m event provides functions to access the current length of
  an array field and to change the array field, with default names
  obtained by suffixing the field name with ``[47mLENGTH-[0m'' or prefixing
  it with ``[47mRESIZE-[0m,'' respectively.  The following log shows the
  uses of these fields in the above example.

    ACL2 !>(A-LENGTH $S)
    3
    ACL2 !>(RESIZE-A 10 $S) ; change length of A to 10
    <$s>
    ACL2 !>(A-LENGTH $S)
    10
    ACL2 !>(AI 7 $S)        ; new elements get value from :initially
    9
    ACL2 !>(RESIZE-A 2 $S)  ; truncate A down to first 2 elements
    <$s>
    ACL2 !>(A-LENGTH $S)
    2
    ACL2 !>(AI 7 $S)        ; error:  access past array bound

    ACL2 Error in TOP-LEVEL:  The guard for the function symbol AI, which
    is (AND ($SP $S) (INTEGERP I) (<= 0 I) (< I (A-LENGTH $S))), is violated
    by the arguments in the call (AI 7 $S).

    ACL2 !>

  Here are the definitions of the relevant functions for the above
  example; also see [resize-list].

    (DEFUN A-LENGTH ($S)
      (DECLARE (XARGS :GUARD ($SP $S) :VERIFY-GUARDS T))
      (LEN (NTH 1 $S)))

    (DEFUN RESIZE-A (K $S)
      (DECLARE (XARGS :GUARD ($SP $S) :VERIFY-GUARDS T))
      (UPDATE-NTH 1
                  (RESIZE-LIST (NTH 1 $S) K 9)
                  $S))

  It is important to note that the implementation of array resizing in
  ACL2 involves copying the entire array into a newly allocated space
  and thus can be quite costly if performed often.  This approach was
  chosen in order to make array access and update as efficient as
  possible, with the suspicion that for most applications, array
  access and update are considerably more frequent than resizing
  (especially if the programmer is aware of the relative costs
  beforehand).

  It should also be noted that computations of lengths of stobj array
  fields should be fast (constant-time) in all or most Common Lisp
  implementations.

  Finally, if [47m:resizable t[0m is not supplied as shown above, then an
  attempt to resize the array will result in an error.  If you do not
  intend to resize the array, it is better to omit the [47m:resizable[0m
  option (or to supply [47m:resizable nil[0m), since then the length
  function will be defined to return a constant, namely the initial
  length, which can simplify guard proofs (compare with the
  definition of [47mA-LENGTH[0m above).

  This completes the tour through the documentation of [stobj]s.
  However, you may now wish to read the documentation for the event
  that introduces a new single-threaded object; see [defstobj].")
 (STOBJ-LET (POINTERS)
            "See [nested-stobjs].")
 (STOBJ-TABLE
  (STOBJ NESTED-STOBJS)
  "A [stobj] field mapping stobj names to stobjs

  See [stobj] for basic background on stobjs, and see [defstobj] for
  detailed documentation on the syntax and semantics of stobjs,
  including fields specified with [47m:type (stobj-table)[0m or [47m:type
  (stobj-table SIZE)[0m.  In the latter case, [47mSIZE[0m must either be a
  natural number or a defined constant whose value is a natural
  number.  We call such fields --- that is, stobj fields specified
  with [47m:type (stobj-table)[0m or [47m:type (stobj-table SIZE)[0m ---
  ``stobj-table fields''; this documentation topic explains them, and
  it assumes familiarity with stobj fields of stobjs as documented in
  [nested-stobjs] --- especially, the use of [47m[stobj-let][0m to read and
  write such fields.  Note that the documentation for [defstobj]
  shows the default names for accessors and updaters; for a
  stobj-table field, [47mTBL[0m, these are [47mTBL-GET[0m and [47mTBL-PUT[0m,
  respectively.

  For examples of [47mstobj-let[0m usage for stobj-tables, see
  [community-book] [47mbooks/system/tests/stobj-table-tests-input.lsp[0m.

  A stobj-table field may be viewed as an association list mapping
  stobj names to corresponding stobjs, so that each stobj name maps
  to a stobj that satisfies the recognizer for that stobj name.  This
  requirement is not enforced in the logic (i.e., in recognizer
  functions).  But it is essentially maintained in raw Lisp as an
  invariant, except that for efficiency, a stobj-table field is
  implemented as a hash table (again, mapping stobj names to
  corresponding stobjs).  Below we give more details and explain how
  [47mstobj-let[0m may be used to access and update stobjs that are in such
  a table.

  The general forms for stobj-table fields of stobjs are as shown
  below.

    (defstobj NAME
      (TBL1 :type (stobj-table))      ; stobj field of default size
      ...
      (TBL2 :type (stobj-table SIZE)) ; stobj field of desired size SIZE
      ...)

  That is, a stobj-table field is a field whose type is of the form
  [47m(stobj-table)[0m or [47m(stobj-table SIZE)[0m.  The syntax is thus much like
  the syntax for hash-table fields of stobjs, except that there is no
  test specified for a stobj-table (it is actually [47m[eq][0m in raw Lisp).

  As noted above, a stobj-table is conceptually an alist that
  associates stobj names with corresponding stobjs.  We say
  ``conceptually'' because in fact, the recognizer for any
  stobj-table field is [47mt[0m: there is no requirement that it is actually
  an alist.  It is accessed logically with [47m[hons-assoc-equal][0m, which
  is a variant of [47m[assoc][0m that treats an arbitrary object as an
  alist: only pairs are considered when looking up a key, and the
  final cdr is ignored.  A default value is returned when there is no
  pair with the given key.  A stobj-table field is thus very much
  like a hash-table field.  The key difference (pun somewhat
  intended) is that each key of a stobj-table is the name of a stobj
  (other than [47mstate[0m, i.e., it is a user-defined stobj name), and the
  corresponding value is a stobj satisfying the recognizer for that
  name.

  A common case is that a stobj-table field is the unique field of its
  parent stobj.  In that case we may think of the entire stobj as a
  stobj-table, and that is actually consistent with the
  implementation: in raw Lisp, if a stobj-table field is the sole
  field of its parent stobj, then that stobj-table field is actually
  the entire stobj; there is not the usual indirection in raw Lisp,
  where a stobj is a vector of fields and the field is accessed as an
  entry in that vector.  (Logically, however, a stobj is always a
  list of its fields, even if there is only one field.)

  Reads and writes of a stobj-table field are much like reads and
  writes when the field is an array of stobjs.  In both cases, one
  uses [47m[stobj-let][0m to access and possibly update the desired
  individual stobj or stobjs.  The syntax thus looks as follows,
  where [47mST[0m is a stobj name and [47mPARENT[0m is the name of a stobj that has
  a stobj-table accessor with name [47mTBL-GET[0m.  Note that the first
  argument of the accessor must be the quotation of the name of the
  bound stobj (thus below, [47m'ST[0m is the quotation of [47mST[0m) and the third
  argument must be a call of that stobj's creator function.

    (stobj-let (...                                 ; bindings
                (ST (TBL-GET 'ST PARENT (CREATE-ST)))
                ...
                )
               (...)                                ; producer variables
               (...)                                ; producer
               ...                                  ; consumer
               )

  The [47mTBL-GET[0m call above always returns an object that satisfies the
  recognizer for the stobj, [47mST[0m.  However, that is a fact about
  evaluation; it is not provable in the logic.  Fortunately, [guard]
  verification typically adds hypotheses to this effect when
  necessary.

  [31;1mRemark[0m.  This remark on the implementation may be skipped, but it may
  provide some intuition.  When a stobj name is not bound in the
  underlying hash table, then the default value (in the example
  above, [47m(CREATE-ST)[0m) provides a suitable stobj nonetheless.  And if
  that stobj name is among the producer variables of a [47mstobj-let[0m
  form, it will be bound in the underlying hash table when the
  [47mstobj-let[0m form completes.  End of remark.

  The remainder of this topic explains the use of stobj-tables by
  following the example in [community-book]
  [47mstd/stobjs/stobj-table.lisp[0m.  The first form in that book (after
  the initial [47m[in-package][0m form) is as follows.

    (defstobj stobj-table (tbl :type (stobj-table)))

  This specifies a stobj named [47mstobj-table[0m with a unique field, [47mtbl[0m.
  As noted above, this stobj is the same as its field in raw Lisp, so
  even though it is the field that is truly a stobj-table, it is not
  conceptually problematic to call the entire stobj ``stobj-table''.
  This may be the most common case for a stobj-table (i.e., being a
  unique field of a stobj).

  The remaining forms in the book are [local] to the book, intended to
  illustrate with simple examples how stobj-tables may be used.  The
  first one just introduces a rather trivial stobj.

    (defstobj st1 fld1)

  The next form puts this stobj into the stobj-table after updating its
  field with a specified value.

    (defun update-st1-in-tbl (val stobj-table)
      (declare (xargs :stobjs stobj-table))
      (stobj-let ((st1 (tbl-get 'st1 stobj-table (create-st1)))) ; bindings
                 (st1)                                        ; producer variable
                 (update-fld1 val st1)                        ; producer
                 stobj-table                                  ; consumer
                 ))

  The form after that accesses the value of [47m'st1[0m in the stobj-table and
  returns its field's value.

    (defun read-st1-in-tbl1 (stobj-table)
      (declare (xargs :stobjs stobj-table))
      (stobj-let ((st1 (tbl-get 'st1 stobj-table (create-st1)))) ; bindings
                 (val)                                        ; producer variable
                 (fld1 st1)                                   ; producer
                 val                                          ; consumer
                 ))

  Next is a check that when a specific value is written for the key
  [47m'st1[0m with the update function defined above, the value subsequently
  read for key [47m'st1[0m is that written value.  The reason for the [47mmv[0m
  call is that the updater returns an updated stobj-table, which
  therefore must be returned.  However, [47m[assert-event][0m is
  sufficiently clever to check that the first (i.e., ordinary) value
  returned is non-[47mnil[0m.

    (assert-event
     (let ((stobj-table (update-st1-in-tbl 3 stobj-table)))
       (mv (equal (read-st1-in-tbl1 stobj-table)
                  3)
           stobj-table))
     :stobjs-out '(nil stobj-table))

  The computation above is a special case of a standard
  ``read-over-write'' property, that after a write, we read the value
  that was just written.  This is proved automatically.

    (defthm read-over-write-st1-in-tbl
      (implies (stobj-tablep stobj-table)
               (let ((stobj-table (update-st1-in-tbl val stobj-table)))
                 (equal (read-st1-in-tbl1 stobj-table)
                        val))))

  The other standard ``read-over-write'' property is that the write for
  a given key doesn't affect the value read for a different key.  The
  following events, admitted automatically, illustrate that property:
  here, writing a value for the key [47m'st1[0m doesn't affect the value
  read for the key [47m'st2[0m.

    (defstobj st2 fld2)

    (defun read-st2-in-tbl (stobj-table)
      (declare (xargs :stobjs stobj-table))
      (stobj-let ((st2 (tbl-get 'st2 stobj-table (create-st2)))) ; bindings
                 (val)                                        ; producer variable
                 (fld2 st2)                                   ; producer
                 val                                          ; consumer
                 ))

    (defthm read-over-write-st2-in-tbl
      (implies (stobj-tablep stobj-table)
               (let ((stobj-table-2 (update-st1-in-tbl val stobj-table)))
                 (equal (read-st2-in-tbl stobj-table-2)
                        (read-st2-in-tbl stobj-table)))))

  Note that all keys in a stobj-table are names of stobjs.  Consider
  what happens when we evaluate the events in the book above,
  including the local events, and then undo the [47m[defstobj][0m event
  admitting [47mst1[0m.  It is clear that undoing has removed the symbol [47mst1[0m
  as a key in the stobj-table.

    ACL2 !>(ld \"std/stobjs/stobj-table.lisp\" :dir :system)
    [[.. output omitted ..]]
    ACL2 !>(tbl-count stobj-table)
    1
    ACL2 !>:ubt st1
       d       1:x(DEFSTOBJ STOBJ-TABLE (TBL :TYPE #))
    ACL2 !>(tbl-count stobj-table)
    0
    ACL2 !>

  Finally, we remark that there is nothing special about stobj-table
  fields with respect to stobj fields of abstract stobjs.")
 (STOBJP (POINTERS)
         "See [system-utilities].")
 (STOBJS (POINTERS)
         "See [xargs] for information about the keyword [47m:stobjs[0m.")
 (STOBJS-IN (POINTERS)
            "See [system-utilities].")
 (STOBJS-OUT (POINTERS)
             "See [system-utilities].")
 (STOP-PROOF-TREE
  (PROOF-TREE)
  "Stop displaying proof trees during proofs

  Also see [proof-tree] and see [start-proof-tree].  Note that
  [47m:stop-proof-tree[0m works by adding [47m'[0m[47m[proof-tree][0m to the
  [47minhibit-output-lst[0m; see [set-inhibit-output-lst].

  Proof tree displays are explained in the documentation for
  [proof-tree].  [47m:Stop-proof-tree[0m causes proof tree display to be
  turned off.

  It is permissible to submit the form [47m(stop-proof-tree)[0m during a
  break.  Thus, you can actually turn off proof tree display in the
  middle of a proof by interrupting ACL2 and submitting the form
  [47m(stop-proof-tree)[0m in raw Lisp.")
 (STRING
  (STRINGS ACL2-BUILT-INS)
  "[coerce] to a string

  [47m(String x)[0m [coerce]s [47mx[0m to a string.

  The [guard] for [47mstring[0m requires its argument to be a string, a
  symbol, or a character.

    * If [47mx[0m is already a string, then it is returned unchanged.

    * If [47mx[0m is a symbol, then its [47m[symbol-name][0m is returned.

    * If [47mx[0m is a character, the corresponding one-character string is
      returned.

  Note: this is a rather low-level operation that doesn't support
  coercing numbers or conses into strings.  If you want to turn
  numbers into strings, see functions such as
  [str::nat-to-dec-string], or more generally the [str::numbers]
  functions.  For conses, see the [str::pretty-printing] routines
  such as [str::pretty].

  [47mString[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<string>

    (defun string (x)
      (declare (xargs :guard (or (stringp x)
                                 (symbolp x)
                                 (characterp x))))
      (cond ((stringp x) x)
            ((symbolp x) (symbol-name x))
            (t (coerce (list x) 'string))))")
 (STRING-ALISTP
  (ALISTS ACL2-BUILT-INS)
  "Recognizer for association lists with strings as keys

  [47m(String-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of the
  form [47m(cons key val)[0m where [47mkey[0m is a string.

  [47mString-alistp[0m has a [guard] of [47mt[0m.

  [31;1mFunction: [0m<string-alistp>

    (defun string-alistp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (eq x nil))
            (t (and (consp (car x))
                    (stringp (car (car x)))
                    (string-alistp (cdr x))))))")
 (STRING-APPEND
  (STRINGS ACL2-BUILT-INS)
  "[concatenate] two strings

  [47mString-append[0m takes two arguments, which are both strings (if the
  [guard] is to be met), and returns a string obtained by
  concatenating together the [characters] in the first string
  followed by those in the second.  For a related macro that can take
  an arbitrary number of string arguments, see [concatenate], noting
  that the macro call

    (concatenate 'string str1 str2).

  expands to the call

    (string-append str1 str2).

  [31;1mFunction: [0m<string-append>

    (defun string-append (str1 str2)
      (declare (xargs :guard (and (stringp str1) (stringp str2))))
      (mbe :logic (coerce (append (coerce str1 'list)
                                  (coerce str2 'list))
                          'string)
           :exec (concatenate 'string str1 str2)))")
 (STRING-DOWNCASE
  (STRINGS ACL2-BUILT-INS)
  "In a given string, turn upper-case [characters] into lower-case

  For a string [47mx[0m, [47m(string-downcase x)[0m is the result of applying
  [47m[char-downcase][0m to each character in [47mx[0m.

  The [guard] for [47mstring-downcase[0m states that its argument is a string.

  [47mString-downcase[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<string-downcase>

    (defun string-downcase (x)
      (declare (xargs :guard (stringp x)))
      (coerce (string-downcase1 (coerce x 'list))
              'string))")
 (STRING-EQUAL
  (STRINGS ACL2-BUILT-INS)
  "String equality without regard to case

  For strings [47mstr1[0m and [47mstr2[0m, [47m(string-equal str1 str2)[0m is true if and
  only [47mstr1[0m and [47mstr2[0m are the same except perhaps for the cases of
  their [characters].

  The [guard] on [47mstring-equal[0m requires that its arguments are strings.

  [47mString-equal[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<string-equal>

    (defun string-equal (str1 str2)
      (declare (xargs :guard (and (stringp str1) (stringp str2))))
      (let ((len1 (length str1)))
        (and (= len1 (length str2))
             (string-equal1 str1 str2 0 len1))))")
 (STRING-LISTP
  (STRINGS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of strings

  The predicate [47mstring-listp[0m tests whether its argument is a
  [47m[true-listp][0m of strings.

  [31;1mFunction: [0m<string-listp>

    (defun string-listp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (eq x nil))
            (t (and (stringp (car x))
                    (string-listp (cdr x))))))")
 (STRING-UPCASE
  (STRINGS ACL2-BUILT-INS)
  "In a given string, turn lower-case [characters] into upper-case

  For a string [47mx[0m, [47m(string-upcase x)[0m is the result of applying
  [47m[char-upcase][0m to each character in [47mx[0m.

  The [guard] for [47mstring-upcase[0m states that its argument is a string.

  [47mString-upcase[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<string-upcase>

    (defun string-upcase (x)
      (declare (xargs :guard (stringp x)))
      (coerce (string-upcase1 (coerce x 'list))
              'string))")
 (STRING<
  (STRINGS ACL2-BUILT-INS)
  "Less-than test for strings

  [47m(String< str1 str2)[0m is non-[47mnil[0m if and only if the string [47mstr1[0m
  precedes the string [47mstr2[0m lexicographically, where character
  inequalities are tested using [47m[char<][0m.  When non-[47mnil[0m, [47m(string< str1
  str2)[0m is the first position (zero-based) at which the strings
  differ.  Here are some examples.

    ACL2 !>(string< \"abcd\" \"abu\")
    2
    ACL2 !>(string< \"abcd\" \"Abu\")
    NIL
    ACL2 !>(string< \"abc\" \"abcde\")
    3
    ACL2 !>(string< \"abcde\" \"abc\")
    NIL

  The [guard] for [47mstring<[0m specifies that its arguments are strings.

  [47mString<[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<string<>

    (defun string< (str1 str2)
      (declare (xargs :guard (and (stringp str1) (stringp str2))))
      (string<-l (coerce str1 'list)
                 (coerce str2 'list)
                 0))")
 (STRING<=
  (STRINGS ACL2-BUILT-INS)
  "Less-than-or-equal test for strings

  [47m(String<= str1 str2)[0m is non-[47mnil[0m if and only if the string [47mstr1[0m
  precedes the string [47mstr2[0m lexicographically or the strings are
  equal.  When non-[47mnil[0m, [47m(string<= str1 str2)[0m is the first position
  (zero-based) at which the strings differ, if they differ, and
  otherwise is their common length.  See [string<].

  The [guard] for [47mstring<=[0m specifies that its arguments are strings.

  [47mString<=[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<string<=>

    (defun string<= (str1 str2)
      (declare (xargs :guard (and (stringp str1) (stringp str2))))
      (if (equal str1 str2)
          (length str1)
        (string< str1 str2)))")
 (STRING>
  (STRINGS ACL2-BUILT-INS)
  "Greater-than test for strings

  [47m(String> str1 str2)[0m is non-[47mnil[0m if and only if [47mstr2[0m precedes [47mstr1[0m
  lexicographically.  When non-[47mnil[0m, [47m(string> str1 str2)[0m is the first
  position (zero-based) at which the strings differ.  See [string<].

  [47mString>[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<string>>

    (defun string> (str1 str2)
      (declare (xargs :guard (and (stringp str1) (stringp str2))))
      (string< str2 str1))")
 (STRING>=
  (STRINGS ACL2-BUILT-INS)
  "Less-than-or-equal test for strings

  [47m(String>= str1 str2)[0m is non-[47mnil[0m if and only if the string [47mstr2[0m
  precedes the string [47mstr1[0m lexicographically or the strings are
  equal.  When non-[47mnil[0m, [47m(string>= str1 str2)[0m is the first position
  (zero-based) at which the strings differ, if they differ, and
  otherwise is their common length.  See [string>].

  The [guard] for [47mstring>=[0m specifies that its arguments are strings.

  [47mString>=[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.

  [31;1mFunction: [0m<string>=>

    (defun string>= (str1 str2)
      (declare (xargs :guard (and (stringp str1) (stringp str2))))
      (if (equal str1 str2)
          (length str1)
        (string> str1 str2)))")
 (STRINGP
  (STRINGS ACL2-BUILT-INS)
  "Recognizer for strings

  [47m(stringp x)[0m is true if and only if [47mx[0m is a string.")
 (STRINGS
  (PROGRAMMING)
  "Strings are atomic objects that contain character sequences, like
  [47m\"Hello World\"[0m.

  See the [std/strings] library for many additional string functions
  and lemmas about the built-in string functions.


Subtopics

  [Char]
      The [nth] element (zero-based) of a string

  [Coerce]
      Coerce a character list to a string and a string to a list

  [Concatenate]
      Concatenate lists or strings together

  [Count]
      Count the number of occurrences of an item in a string or true-list

  [Length]
      Length of a string or proper list

  [Position]
      Position of an item in a string or a list

  [Remove-duplicates]
      Remove duplicates from a string or a list

  [Reverse]
      Reverse a list or string

  [Search]
      Search for a string or list in another string or list

  [String]
      [coerce] to a string

  [String-append]
      [concatenate] two strings

  [String-downcase]
      In a given string, turn upper-case [characters] into lower-case

  [String-equal]
      String equality without regard to case

  [String-listp]
      Recognizer for a true list of strings

  [String-upcase]
      In a given string, turn lower-case [characters] into upper-case

  [String<]
      Less-than test for strings

  [String<=]
      Less-than-or-equal test for strings

  [String>]
      Greater-than test for strings

  [String>=]
      Less-than-or-equal test for strings

  [Stringp]
      Recognizer for strings

  [Subseq]
      Subsequence of a string or list

  [Substitute]
      Substitute into a string or a list, using [47m[eql][0m as test")
 (STRIP-CARS
  (ALISTS ACL2-BUILT-INS)
  "Collect up all first components of pairs in a list

  [47m(strip-cars x)[0m is the list obtained by walking through the list [47mx[0m and
  collecting up all first components ([47m[car][0ms).  This function is
  implemented in a tail-recursive way, despite its logical
  definition.

  [47m(strip-cars x)[0m has a [guard] of [47m(alistp x)[0m.

  [31;1mFunction: [0m<strip-cars>

    (defun strip-cars (x)
      (declare (xargs :guard (alistp x)))
      (cond ((endp x) nil)
            (t (cons (car (car x))
                     (strip-cars (cdr x))))))")
 (STRIP-CDRS
  (ALISTS ACL2-BUILT-INS)
  "Collect up all second components of pairs in a list

  [47m(strip-cdrs x)[0m has a [guard] of [47m(alistp x)[0m, and returns the list
  obtained by walking through the list [47mx[0m and collecting up all second
  components ([47m[cdr][0ms).  This function is implemented in a
  tail-recursive way, despite its logical definition.

  [31;1mFunction: [0m<strip-cdrs>

    (defun strip-cdrs (x)
      (declare (xargs :guard (alistp x)))
      (cond ((endp x) nil)
            (t (cons (cdr (car x))
                     (strip-cdrs (cdr x))))))")
 (STRONG-REWRITE-RULES
  (INTRODUCTION-TO-THE-THEOREM-PROVER)
  "Formulating good rewrite rules

  Suppose you notice the following term in a Key Checkpoint:

    (MEMBER (CAR A) (REV B)).

  You might think of two theorems for handling this term, which we'll
  call the ``weak'' and ``strong'' version of [47mmember-rev[0m.

    (defthm member-rev-weak
      (implies (member e b)
               (member e (rev b)))).

    (defthm member-rev-strong
      (iff (member e (rev b))
           (member e b))).

  The ``strong'' version logically implies the ``weak'' version and so
  deserves the adjective.  (Recall that ``[3mp[0m <---> [3mq[0m'' is just ``[3mp[0m
  ---> [3mq[0m'' and ``[3mq[0m ---> [3mp[0m.'' So the strong version quite literally
  says everything the weak version does and then some.)

  But the ``strong'' version also produces a [3mbetter[0m rewrite rule.  Here
  are the rules generated from these two formulas, phrased as
  directives to ACL2's simplifier:

  [47mmember-rev-weak[0m: If you ever see an instance of [47m(MEMBER e (REV b))[0m,
  backchain to [47m(MEMBER e b)[0m (i.e., turn your attention to that term)
  and if you can show that it is true, replace [47m(MEMBER e (REV b))[0m by
  [47mT[0m.

  [47mmember-rev-strong[0m: If you ever see an instance of [47m(MEMBER e (REV b))[0m,
  replace it by [47m(MEMBER e b)[0m.

  Technical Note: Actually, both rules concern [3mpropositional[0m
  occurrences of the ``target'' expression, [47m(MEMBER e (REV b))[0m, i.e.,
  occurrences of the target in which its truth value is the only
  thing of relevance.  (Recall that [47m(MEMBER x y)[0m returns the tail of
  [47my[0m starting with [47mx[0m!  Evaluate some simple [47mMEMBER[0m expressions, like
  [47m(MEMBER 3 '(1 2 3 4 5))[0m to see what we mean.)  Both theorems tell
  us about circumstances in which the target is non-[47mNIL[0m (i.e.,
  ``true'') without telling us its identity.  But ACL2 keeps track of
  when the target is in a propositional occurrence and can use such
  rules to rewrite the target to propositionally equivalent terms.

  So the strong version is better because it will always eliminate
  [47m(MEMBER e (REV b))[0m in favor of [47m(MEMBER e b)[0m.  That simpler
  expression may be further reduced if the context allows it.  But in
  any case, the strong version eliminates [47mREV[0m from the problem.  The
  weak version only eliminates [47mREV[0m when a side-condition can be
  proved.

  While either version may permit us to prove the Key Checkpoint that
  ``suggested'' the rule, the strong version is a better rule to have
  in the database going forward.

  For example, suppose [47mNATS-BELOW[0m returns the list of natural numbers
  below its argument.  Imagine two alternative scenarios in which a
  key checkpoint is about to arise involving this term:

    (MEMBER K (REV (NATS-BELOW J)))

  [31;1mScenario 1[0m is when you've got the strong version in your database: it
  will rewrite the key checkpoint term to

    (MEMBER K (NATS-BELOW J))

  and that's what you'll see in the printed checkpoint unless other
  rules reduce it further.

  [31;1mScenario 2[0m is when you have only the weak version in your database:
  the weak rule will attempt to reduce the term above to [47mT[0m and will,
  if there are sufficient rules and hypotheses about [47mK[0m's membership
  in [47m(NATS-BELOW J)[0m.  But if no such rules or hypotheses are
  available, you'll be confronted with a key checkpoint involving

    (MEMBER K (REV (NATS-BELOW J)))

  and [3mit will not be obvious[0m that the problem would go away if you
  could establish that [47mK[0m is in [47m(NATS-BELOW J)[0m.  Clearly, Scenario 1
  is better.

  We recommend that you now practice formulating strong versions of
  rules suggested by terms you might see.  See
  [practice-formulating-strong-rules].

  When you are finished with that, use your browser's [31;1mBack Button[0m to
  return to [introduction-to-key-checkpoints].")
 (SUBCOR-VAR (POINTERS)
             "See [system-utilities].")
 (SUBLIS
  (ALISTS ACL2-BUILT-INS)
  "Substitute an alist into a tree

  [47m(Sublis alist tree)[0m is obtained by replacing every leaf of [47mtree[0m with
  the result of looking that leaf up in the association list [47malist[0m.
  However, a leaf is left unchanged if it is not found as a key in
  [47malist[0m.

  Leaves are looked up using the function [47m[assoc][0m.  The [guard] for
  [47m(sublis alist tree)[0m requires [47m(eqlable-alistp alist)[0m.  This [guard]
  ensures that the [guard] for [47m[assoc][0m will be met for each lookup
  generated by [47msublis[0m.

  [47mSublis[0m is defined in Common Lisp.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<sublis>

    (defun sublis (alist tree)
      (declare (xargs :guard (eqlable-alistp alist)))
      (cond ((atom tree)
             (let ((pair (assoc tree alist)))
               (cond (pair (cdr pair)) (t tree))))
            (t (cons (sublis alist (car tree))
                     (sublis alist (cdr tree))))))")
 (SUBLIS-FN (POINTERS)
            "See [system-utilities].")
 (SUBLIS-FN-LST-SIMPLE (POINTERS)
                       "See [system-utilities].")
 (SUBLIS-FN-SIMPLE (POINTERS)
                   "See [system-utilities].")
 (SUBLIS-VAR (POINTERS)
             "See [system-utilities].")
 (SUBSEQ
  (LISTS STRINGS ACL2-BUILT-INS)
  "Subsequence of a string or list

  For any natural numbers [47mstart[0m and [47mend[0m, where [47mstart[0m [47m<=[0m [47mend[0m [47m<=[0m [47m(length
  seq)[0m, [47m(subseq seq start end)[0m is the subsequence of [47mseq[0m from index
  [47mstart[0m up to, but not including, index [47mend[0m.  [47mEnd[0m may be [47mnil[0m, in
  which case it is treated as though it is [47m(length seq)[0m, i.e., we
  obtain the subsequence of [47mseq[0m from index [47mstart[0m all the way to the
  end.

  The [guard] for [47m(subseq seq start end)[0m is that [47mseq[0m is a true list or
  a string, [47mstart[0m and [47mend[0m are integers (except, [47mend[0m may be [47mnil[0m, in
  which case it is treated as [47m(length seq)[0m for the rest of this
  discussion), and [47m0[0m [47m<=[0m [47mstart[0m [47m<=[0m [47mend[0m [47m<=[0m [47m(length seq)[0m.

  [47mSubseq[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.  Note: In Common Lisp the third argument of
  [47msubseq[0m is optional, but in ACL2 it is required, though it may be
  [47mnil[0m as explained above.

  [31;1mFunction: [0m<subseq>

    (defun subseq (seq start end)
      (declare (xargs :guard (and (or (true-listp seq) (stringp seq))
                                  (integerp start)
                                  (<= 0 start)
                                  (or (null end)
                                      (and (integerp end)
                                           (<= end (length seq))))
                                  (<= start (or end (length seq))))))
      (if (stringp seq)
          (coerce (subseq-list (coerce seq 'list)
                               start (or end (length seq)))
                  'string)
        (subseq-list seq start (or end (length seq)))))")
 (SUBSEQUENCEP (POINTERS)
               "See [system-utilities].")
 (SUBSETP
  (LISTS ACL2-BUILT-INS)
  "Test if every [47m[member][0m of one list is a [47m[member][0m of the other

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

  [47m(Subsetp x y)[0m is true if and only if every [47m[member][0m of the list [47mx[0m is
  a [47mmember[0m of the list [47my[0m.  The optional keyword, [47m:TEST[0m, has no effect
  logically, but provides the test (default [47m[eql][0m) used for comparing
  members of the two lists.

  The [guard] for a call of [47msubsetp[0m depends on the test.  In all cases,
  both arguments must satisfy [47m[true-listp][0m.  If the test is [47m[eql][0m,
  then one of the arguments must satisfy [47m[eqlable-listp][0m.  If the
  test is [47m[eq][0m, then one of the arguments must satisfy
  [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47msubsetp[0m and its variants:

      [47m(subsetp-eq x lst)[0m is equivalent to [47m(subsetp x lst :test 'eq)[0m;

      [47m(subsetp-equal x lst)[0m is equivalent to [47m(subsetp x lst :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47msubsetp-equal[0m.

  [31;1mFunction: [0m<subsetp-equal>

    (defun subsetp-equal (x y)
      (declare (xargs :guard (and (true-listp y) (true-listp x))))
      (cond ((endp x) t)
            ((member-equal (car x) y)
             (subsetp-equal (cdr x) y))
            (t nil)))

  [47mSubsetp[0m is defined by Common Lisp.  See any Common Lisp documentation
  for more information.")
 (SUBSETP-EQ (POINTERS) "See [subsetp].")
 (SUBSETP-EQUAL (POINTERS)
                "See [subsetp].")
 (SUBST
  (CONSES ACL2-BUILT-INS)
  "A single substitution into a tree

  [47m(Subst new old tree)[0m is obtained by substituting [47mnew[0m for every
  occurrence of [47mold[0m in the given tree.

  Equality to [47mold[0m is determined using the function [47m[eql][0m.  The [guard]
  for [47m(subst new old tree)[0m requires [47m(eqlablep old)[0m, which ensures
  that the [guard] for [47m[eql][0m will be met for each comparison
  generated by [47msubst[0m.

  [47mSubst[0m is defined in Common Lisp.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<subst>

    (defun subst (new old tree)
      (declare (xargs :guard (eqlablep old)))
      (cond ((eql old tree) new)
            ((atom tree) tree)
            (t (cons (subst new old (car tree))
                     (subst new old (cdr tree))))))")
 (SUBST-EXPR (POINTERS)
             "See [system-utilities].")
 (SUBST-VAR (POINTERS)
            "See [system-utilities].")
 (SUBSTITUTE
  (LISTS STRINGS ACL2-BUILT-INS)
  "Substitute into a string or a list, using [47m[eql][0m as test

  [47m(Substitute new old seq)[0m is the result of replacing each occurrence
  of [47mold[0m in [47mseq[0m, which is a list or a string, with [47mnew[0m.

  The guard for [47msubstitute[0m requires that either [47mseq[0m is a string and [47mnew[0m
  is a character, or else: [47mseq[0m is a [47m[true-listp][0m such that either all
  of its members are [47m[eqlablep][0m or [47mold[0m is [47meqlablep[0m.

  [47mSubstitute[0m is a Common Lisp function.  See any Common Lisp
  documentation for more information.  Since ACL2 functions cannot
  take keyword arguments (though macros can), the test used in
  [47msubstitute[0m is [47meql[0m.

  [31;1mFunction: [0m<substitute>

    (defun substitute (new old seq)
      (declare (xargs :guard (or (and (stringp seq) (characterp new))
                                 (and (true-listp seq)
                                      (or (eqlablep old)
                                          (eqlable-listp seq))))))
      (if (stringp seq)
          (coerce (substitute-ac new old (coerce seq 'list)
                                 nil)
                  'string)
        (substitute-ac new old seq nil)))")
 (SUBSUMPTION_OF_INDUCTION_CANDIDATES_IN_APP_EXAMPLE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Subsumption of Induction Candidates in App Example

  After collecting induction suggestions from these three terms

    (app [31;1ma[0m b)

    (app [31;1mb[0m c)

    (app [31;1ma[0m (app b c))

  the system notices that the first and last suggest the same
  decomposition of [47ma[0m: case split on whether [47ma[0m is empty (i.e., [47m(endp
  a)[0m), and in the case where it is not empty, recursively process
  [47m(cdr a)[0m.  So we are left with two ideas about how to induct:

  Decompose [31;1ma[0m as we would to unwind (app [31;1ma[0m b).

  Decompose [31;1mb[0m as we would to unwind (app [31;1mb[0m c).")
 (SUBVERSIVE-INDUCTIONS
  (MISCELLANEOUS)
  "Why we restrict [encapsulate]d recursive functions

  See [subversive-recursions].")
 (SUBVERSIVE-RECURSIONS
  (MISCELLANEOUS)
  "Why we restrict [encapsulate]d recursive functions

  Subtleties arise when one of the ``constrained'' functions, [47mf[0m,
  introduced in the [signature] of an [47m[encapsulate][0m event, is
  involved in the termination argument for a non-local recursively
  defined function, [47mg[0m, in that [47mencapsulate[0m.  During the processing of
  the encapsulated events, [47mf[0m is locally defined to be some witness
  function, [47mf'[0m.  Properties of [47mf'[0m are explicitly proved and exported
  from the encapsulate as the constraints on the undefined function
  [47mf[0m.  But if [47mf[0m is used in a recursive [47mg[0m defined within the
  encapsulate, then the termination proof for [47mg[0m may use properties of
  [47mf'[0m --- the witness --- that are not explicitly set forth in the
  constraints stated for [47mf[0m.

  Such recursive [47mg[0m are said be ``subversive'' because if naively
  treated they give rise to unsound induction schemes or (via
  functional instantiation) recurrence equations that are impossible
  to satisfy.  We illustrate what could go wrong below.

  Subversive recursions are not banned outright.  Instead, they are
  treated as part of the constraint.  That is, in the case above, the
  definitional equation for [47mg[0m becomes one of the constraints on [47mf[0m.
  This is generally a severe restriction on future functional
  instantiations of [47mf[0m.  In addition, ACL2 removes from its knowledge
  of [47mg[0m any suggestions about legal inductions to ``unwind'' its
  recursion.

  What should you do?  Often, the simplest response is to move the
  offending recursive definition, e.g., [47mg[0m, out of the encapsulate.
  That is, introduce [47mf[0m by constraint and then define [47mg[0m as an
  ``independent'' event.  You may need to constrain ``additional''
  properties of [47mf[0m in order to admit [47mg[0m, e.g., constrain it to reduce
  some ordinal measure.  However, by separating the introduction of [47mf[0m
  from the admission of [47mg[0m you will clearly identify the necessary
  constraints on [47mf[0m, functional instantiations of [47mf[0m will be simpler,
  and [47mg[0m will be a useful function which suggests inductions to the
  theorem prover.

  Note that the functions introduced in the [signature] should not even
  occur ancestrally in the termination proofs for non-local recursive
  functions in the encapsulate.  That is, the constrained functions
  of an encapsulate should not be reachable in the dependency graph
  of the functions used in the termination arguments of recursive
  functions in encapsulate.  If they are reachable, their definitions
  become part of the constraints.

  The following event illustrates the problem posed by subversive
  recursions.

    (encapsulate
      (((f *) => *))
      (local (defun f (x) (cdr x)))
      (defun g (x)
        (if (consp x) (not (g (f x))) t)))

  Suppose, contrary to how ACL2 works, that the encapsulate above were
  to introduce no constraints on [47mf[0m on the bogus grounds that the only
  use of [47mf[0m in the encapsulate is in an admissible function.  We
  discuss the plausibility of this bogus argument in a moment.

  Then it would be possible to prove the theorem:

    (defthm f-not-identity
      (not (equal (f '(a . b)) '(a . b)))
      :rule-classes nil
      :hints ((\"Goal\" :use (:instance g (x '(a . b))))))

  simply by observing that if [47m(f '(a . b))[0m were [47m'(a . b)[0m, then [47m(g '(a .
  b))[0m would be [47m(not (g '(a . b)))[0m, which is impossible.

  But then we could functionally instantiate [47mf-not-identity[0m, replacing
  [47mf[0m by the identity function, to prove [47mnil[0m!  This is bad.

    (defthm bad
      nil
      :rule-classes nil
      :hints
      ((\"Goal\" :use (:functional-instance f-not-identity (f identity)))))

  This sequence of events was legal in versions of ACL2 prior to
  Version 1.5.  When we realized the problem we took steps to make it
  illegal.  However, our steps were insufficient and it was possible
  to sneak in a subversive function (via mutual recursion) as late as
  Version 2.3.

  We now turn to the plausibility of the bogus argument above.  Why
  might one even be tempted to think that the definition of [47mg[0m above
  poses no constraint on [47mf[0m?  Here is a very similar encapsulate.

    (encapsulate (((f *) => *))
      (local (defun f (x) (cdr x)))
      (defun map (x)
        (if (consp x)
            (cons (f x) (map (cdr x)))
          nil)))

  Here [47mmap[0m plays the role of [47mg[0m above.  Like [47mg[0m, [47mmap[0m calls the
  constrained function [47mf[0m.  But [47mmap[0m truly does not constrain [47mf[0m.  In
  particular, the definition of [47mmap[0m could be moved ``out'' of the
  encapsulate so that [47mmap[0m is introduced afterwards.  The difference
  between [47mmap[0m and [47mg[0m is that the constrained function plays no role in
  the termination argument for the one but does for the other.

  As a ``user-friendly'' gesture, ACL2 implicitly moves [47mmap[0m-like
  functions out of encapsulations; logically speaking, they are
  introduced after the encapsulation.  This simplifies the
  constraint.  When the constraint cannot be thus simplified the user
  is advised, via the ``infected'' warning, to phrase the
  encapsulation in the simplest way possible.  See
  [infected-constraints].

  The lingering bug between Versions 1.5 and 2.3 mentioned above was
  due to our failure to detect the [47mg[0m-like nature of some functions
  when they were defined in mutually recursively cliques with other
  functions.  The singly recursive case was recognized.  The bug
  arose because our detection ``algorithm'' was based on the
  ``suggested inductions'' left behind by successful definitions.  We
  failed to recall that mutually-recursive definitions do not, as of
  this writing, make any suggestions about inductions and so did not
  leave any traces of their subversive natures.

  We conclude by elaborating on the criterion ``involved in the
  termination argument'' mentioned at the outset.  Suppose that
  function [47mf[0m is recursively defined in an [47m[encapsulate][0m, where the
  body of [47mf[0m has no ``ancestor'' among the functions introduced in the
  signature of that [47m[encapsulate][0m, i.e.: the body contains no call of
  a signature function, no call of a function whose body calls a
  signature function, and so on.  Then ACL2 treats [47mf[0m as though it is
  defined in front of that [47mencapsulate[0m form; so [47mf[0m is not [47mconstrained[0m
  by the encapsulate, and its definition is hence certainly not
  subversive in the sense discussed above.  But suppose to the
  contrary that some function introduced in the signature is an
  ancestor of the body of [47mf[0m.  Then the definition of [47mf[0m is subversive
  if moreover, its termination proof obligation has an ancestor among
  the signature functions.  Now, that proof obligation involves terms
  from the first argument of selected calls of [47mIF[0m, as well as
  recursive calls; for a detailed discussion, see [rulers].  The
  important point here is that for the recursive calls, only the
  arguments in ``measured'' positions are relevant to the termination
  proof obligation.  Consider the following example.

    (encapsulate
     (((h *) => *))
     (local (defun h (n) n))
     (defun f (i n)
       (if (zp i)
           n
         (f (1- i) (h n)))))

  ACL2 heuristically picks the measure [47m(acl2-count i)[0m for the
  definition of [47mf[0m; thus, [47mi[0m is the only ``measured formal'' of [47mf[0m.
  Since [47mi[0m is the first formal of [47mf[0m, then for the recursive call of [47mf[0m,
  only the first argument contributes to the termination proof
  obligation: in this case, [47m(1- i)[0m but not [47m(h n)[0m.  Thus, even though
  [47mh[0m is a signature function, the definition of [47mf[0m is not considered to
  be subversive; an induction scheme is thus stored for [47mf[0m.  (This
  restriction to measured formal positions of recursive calls, for
  determining subversive definitions, is new in Version_3.5 of ACL2.)")
 (SUGGESTED_INDUCTIONS_IN_THE_ASSOCIATIVITY_OF_APP_EXAMPLE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Suggested Inductions in the Associativity of App Example

  To find a plausible induction argument, the system studies the
  recursions exhibited by the terms in the conjecture.

  Roughly speaking, a call of a recursive function ``suggests'' an
  induction if the argument position decomposed in recursion is
  occupied by a variable.

  In this conjecture, three terms suggest inductions:

    (app [31;1ma[0m b)

    (app [31;1mb[0m c)

    (app [31;1ma[0m (app b c))

  The variable recursively decomposed is indicated in [31;1mbold[0m.")
 (SUITABLY-TAMEP-LISTP (POINTERS)
                       "See [tame].")
 (SUM$ (POINTERS) "See [loop$].")
 (SUM$+ (POINTERS) "See [loop$].")
 (SUMMARY
  (OUTPUT-CONTROLS)
  "The summary printed at the conclusion of an event

  At the conclusion of an [event] form, ACL2 prints (by default)
  information summarizing the event.  The entire summary may be
  avoided --- see [set-inhibit-output-lst] --- or if you prefer, you
  may inhibit just specified components of the summary --- see
  [set-inhibited-summary-types].  The components are listed in the
  constant [47m*summary-types*[0m and most are available programmatically:
  see [get-event-data].  Some are omitted, however, if they would
  otherwise be empty.  Here is a brief summary of the components,
  listed alphabetically.  Most are printed with an initial field
  indicator, e.g., ``[47mRules: [0m''; a few, as indicated below, are not.

    * [47mErrors[0m (no field indicator): The final error message

    * [47mForm[0m (no field indicator): The ``context'' for the event ([ctx])

    * [47mHeader[0m (no field indicator): The initial word ``Summary''

    * [47mHint-events[0m: Certain hints (e.g., [47m:use[0m hints) supplied

    * [47mRedundant[0m: There is field indicator, but a message is printed that
      notes a redundant event (see [redundant-events]) above the rest
      of the summary.  That message is printed even when [47mSUMMARY[0m
      output or the [47mREDUNDANT[0m summary-type is inhibited, if [47mEVENT[0m
      output is not inhibited.

    * [47mRules[0m: [Rune]s contributing to the proof or storage of the event

    * [47mSplitter-rules[0m: Potential causes of case splits (see [splitter])

    * [47mSteps[0m (field indicator is [47m\"Prover steps counted\"[0m): Prover steps (see
      [set-prover-step-limit])

    * [47mSystem-attachments[0m: List of doublets [47m(f g)[0m for which [47mf[0m is a system
      function with attachment [47mg[0m (see [defattach]), when [47mg[0m differs
      from the initial attachment to [47mf[0m

    * [47mTime[0m: Runtime (or real time; see [get-internal-time])

    * [47mValue[0m: When an event form under [47m[progn][0m or [47m[encapsulate][0m evaluates to
      [47m(mv nil val state)[0m, [47mval[0m is printed immediately under the
      summary fields.  (No field indicator)

    * [47mWarnings[0m: All warning string summaries printed during processing of
      the event


Subtopics

  [Checkpoint-summary-limit]
      Control printing of key checkpoints upon a proof's failure")
 (SWAP-STOBJS
  (STOBJ ACL2-BUILT-INS)
  "Swap two congruent [stobj]s

  See [stobj] for relevant background on single-threaded objects.

  The macro call [47m(swap-stobjs st1 st2)[0m is allowed exactly when [47mst1[0m and
  [47mst2[0m are congruent [stobj]s.  The logical meaning is simply to
  return the two stobjs in reverse order, [47m(list st2 st1)[0m:

  [31;1mMacro: [0m<swap-stobjs>

    (defmacro swap-stobjs (x y)
      (cons 'mv (cons y (cons x 'nil))))

  However, for purposes of tracking single-threadedness, the result [47m(mv
  st2 st1)[0m of [47m(swap-stobjs st1 st2)[0m is treated as a list of new
  values for the stobjs [47mst1[0m and [47mst2[0m, respectively.  That is, after
  this call of [47mswap-stobjs[0m, the new value of stobj [47mst1[0m is considered
  to be the old value of [47mst2[0m, and the new value of stobj [47mst2[0m is
  considered to be the old value of [47mst1[0m.  This is illustrated by the
  following example.

    (defstobj st1 fld1)
    (defstobj st2 fld2 :congruent-to st1)
    (defstobj st3 fld3 :congruent-to st1)
    (defun foo (st1 st2)
      (declare (xargs :stobjs (st1 st2)))
      (swap-stobjs st1 st2))
    ; Initialize:
    (update-fld1 3 st1)
    (update-fld2 4 st2)
    ; Swap:
    (foo st1 st2)
    ; Check that the swap took place:
    (assert-event (equal (fld2 st2) 3))
    (assert-event (equal (fld1 st1) 4))

  The example above is essentially the first of several that may be
  found in the [community-book], [47mbooks/system/tests/swap-stobjs.lisp[0m.
  Those examples illustrate that [47mswap-stobjs[0m has the expected effect
  even when stobjs are involved that are bound by [47m[with-local-stobj][0m
  or [47m[stobj-let][0m.  It also explains subtle interaction with
  [47m[trans-eval][0m.  For another example, see
  [47mbooks/demos/swap-stobj-fields.lisp[0m")
 (SYMBOL-ALISTP
  (ALISTS ACL2-BUILT-INS)
  "Recognizer for association lists with symbols as keys

  [47m(Symbol-alistp x)[0m is true if and only if [47mx[0m is a list of pairs of the
  form [47m(cons key val)[0m where [47mkey[0m is a [47m[symbolp][0m.

  [31;1mFunction: [0m<symbol-alistp>

    (defun symbol-alistp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (eq x nil))
            (t (and (consp (car x))
                    (symbolp (car (car x)))
                    (symbol-alistp (cdr x))))))")
 (SYMBOL-CLASS (POINTERS)
               "See [system-utilities].")
 (SYMBOL-DOUBLET-LISTP (POINTERS)
                       "See [system-utilities].")
 (SYMBOL-LISTP
  (SYMBOLS LISTS ACL2-BUILT-INS)
  "Recognizer for a true list of symbols

  The predicate [47msymbol-listp[0m tests whether its argument is a true list
  of symbols.

  [31;1mFunction: [0m<symbol-listp>

    (defun symbol-listp (lst)
      (declare (xargs :guard t))
      (cond ((atom lst) (eq lst nil))
            (t (and (symbolp (car lst))
                    (symbol-listp (cdr lst))))))")
 (SYMBOL-NAME
  (SYMBOLS ACL2-BUILT-INS)
  "The name of a symbol (a string)

  Completion Axiom ([47mcompletion-of-symbol-name[0m):

    (equal (symbol-name x)
           (if (symbolp x)
               (symbol-name x)
             \"\"))

  [Guard] for [47m(symbol-name x)[0m:

    (symbolp x)")
 (SYMBOL-NAME-LST
  (SYMBOLS ACL2-BUILT-INS)
  "Lift [47m[symbol-name][0m to lists

  This function returns the list of [47m[symbol-name][0ms of a given list of
  symbols.

  [31;1mFunction: [0m<symbol-name-lst>

    (defun symbol-name-lst (lst)
      (declare (xargs :guard (symbol-listp lst)))
      (cond ((endp lst) nil)
            (t (cons (symbol-name (car lst))
                     (symbol-name-lst (cdr lst))))))")
 (SYMBOL-PACKAGE-NAME
  (SYMBOLS PACKAGES ACL2-BUILT-INS)
  "The name of the package of a symbol (a string)

  WARNING: While [47msymbol-package-name[0m behaves properly on all ACL2
  objects, it may give surprising results when called in raw Lisp.
  For more details see [pkg-imports], in particular the discussion
  there of the [47m\"COMMON-LISP\"[0m package.

  Completion Axiom ([47mcompletion-of-symbol-package-name[0m):

    (equal (symbol-package-name x)
           (if (symbolp x)
               (symbol-package-name x)
             \"\"))

  [Guard] for [47m(symbol-package-name x)[0m:

    (symbolp x)

  Note: [47mSymbol-package-name[0m may diverge from the name of the symbol's
  package in raw Lisp, in the case that this package is the main Lisp
  package.  For example, in GCL [47m(symbol-package-name 'car)[0m evaluates
  to \"COMMON-LISP\" even though the actual package name for the
  symbol, [47mcar[0m, is \"LISP\".")
 (SYMBOL<
  (SYMBOLS ACL2-BUILT-INS)
  "Less-than test for symbols

  [47m(symbol< x y)[0m is non-[47mnil[0m if and only if either the [47m[symbol-name][0m of
  the symbol [47mx[0m lexicographically precedes the [47m[symbol-name][0m of the
  symbol [47my[0m (in the sense of [47m[string<][0m) or else the [47m[symbol-name][0ms are
  equal and the [47m[symbol-package-name][0m of [47mx[0m lexicographically precedes
  that of [47my[0m (in the same sense).  So for example, [47m(symbol< 'abcd
  'abce)[0m and [47m(symbol< 'acl2::abcd 'foo::abce)[0m are true.

  The [guard] for [47msymbol[0m specifies that its arguments are symbols.

  [31;1mFunction: [0m<symbol<>

    (defun symbol< (x y)
      (declare (xargs :guard (and (symbolp x) (symbolp y))))
      (let ((x1 (symbol-name x))
            (y1 (symbol-name y)))
        (or (string< x1 y1)
            (and (equal x1 y1)
                 (string< (symbol-package-name x)
                          (symbol-package-name y))))))")
 (SYMBOLIC_EXECUTION_OF_MODELS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Symbolic Execution of Models

  {IMAGE} (see [Proving_Theorems_about_Models])

  But ACL2 is more than a programming language.

  Initialize [31;1mx[0m to 5 and let [31;1my[0m be [31;1many legal value[0m.

  {IMAGE}

  Because ACL2 is a mathematical language, we can simplify the
  expression

    (lookup 'z (mc (s 'mult 5 y) 29))

  and get (+ y y y y y).  This is [31;1msymbolic execution[0m because not all of
  the parameters are known.

  {IMAGE} (see [Proving_Theorems_about_Models])")
 (SYMBOLP
  (SYMBOLS ACL2-BUILT-INS)
  "Recognizer for symbols

  [47m(symbolp x)[0m is true if and only if [47mx[0m is a symbol.


Subtopics

  [Intern]
      Create a new symbol in a given package

  [Intern$]
      Create a new symbol in a given package

  [Intern-in-package-of-symbol]
      Create a symbol with a given name")
 (SYMBOLS
  (PROGRAMMING)
  "Symbols in ACL2 and operations on them

  Symbols are a basic datatype in ACL2 and Common Lisp.  Every symbol
  has two components: its name (see [symbol-name]) and its package
  name (see [symbol-package-name]).


Subtopics

  [Add-to-set]
      Add a symbol to a list

  [Keywordp]
      Recognizer for keywords

  [Packn]
      Build a symbol from a list

  [Packn-pos]
      Build a symbol in a specified package from a list

  [Symbol-listp]
      Recognizer for a true list of symbols

  [Symbol-name]
      The name of a symbol (a string)

  [Symbol-name-lst]
      Lift [47m[symbol-name][0m to lists

  [Symbol-package-name]
      The name of the package of a symbol (a string)

  [Symbol<]
      Less-than test for symbols

  [Symbolp]
      Recognizer for symbols")
 (SYNC-EPHEMERAL-WHS-WITH-PERSISTENT-WHS
  (WORMHOLE)
  "establishing wormhole coherence

    General Form:
    (sync-ephemeral-whs-with-persistent-whs name state)

  where [47mname[0m is the quoted name of a [47m[wormhole][0m other than one of the
  built-in ACL2 system wormholes.  It is forbidden to invoke
  [47msync-ephemeral-whs-with-persistent-whs[0m on the names listed in the
  constant [47m*protected-system-wormhole-names*[0m which includes [47mbrr[0m (the
  [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and
  [47mfc-wormhole[0m (the name of the wormhole managing
  [forward-chaining-reports]), among others.

  If executed on the live state and while in the named wormhole, this
  function moves the wormhole's status from the persistent-whs
  (located in that part of the memory outside of ACL2's state) to the
  ephemeral-whs (the value of the state global variable
  [47mwormhole-status[0m).  Subsequently, [47mname[0m's persistent-whs is equal to
  its ephemeral-whs: the [47mname[0m wormhole is coherent.  If executed on a
  state other than the live one or while outside of the named
  wormhole, this function is a no-op.  Of course, the next time the
  [47mname[0m wormhole is entered it will be in a coherent state since entry
  to a wormhole initializes the [47mwormhole-status[0m to the
  persistent-whs.  [47msync-ephemeral-whs-with-persistent-whs[0m returns the
  new state.

  Logically speaking, this function uses [47m[read-ACL2-oracle][0m to obtain
  the wormhole's hidden status.  So the output state is almost
  certainly different than the input state.

  See [wormhole-programming-tips] for some tips for using this
  function.")
 (SYNTACTICALLY-CLEAN-LAMBDA-OBJECTS-THEORY
  (THEORIES THEORY-FUNCTIONS REWRITE)
  "how to specify syntactic cleaning of lambda objects

  The enabled status of two [47mrewrite-lambda-modep[0m runes are used as
  flags to determine the action taken when eligible [47mlambda[0m objects
  are encountered by the ACL2 rewriter.  See [rewrite-lambda-object]
  and [47m[rewrite-lambda-object-actions][0m.  To prevent the rewriter from
  diving recursively into the body of an eligible [47mlambda[0m object but
  use a simpler syntactic cleaning process instead, the rune
  [47m(:executable-counterpart rewrite-lambda-modep)[0m must be enabled and
  the rune [47m(:definition rewrite-lambda-modep)[0m must be disabled in the
  then-current theory.  The 0-ary function
  [47msyntactically-clean-lambda-objects-theory[0m returns such a theory.

  In fact, diving into eligible quoted [47mlambda[0m object constants to
  rewrite the body is the default action when ACL2 starts up.  See
  [rewriting-versus-cleaning-up-lambda-objects] for why you might
  want to change the default action when eligible [47mlambda[0m objects are
  encountered by the rewriter.

  The expression [47m(syntactically-clean-lambda-objects-theory)[0m
  macroexpands to the theory expression

    (e/d ((:executable-counterpart rewrite-lambda-modep))
         ((:definition rewrite-lambda-modep)))

  which is a theory equal to then current theory except that the
  executable-counterpart rune of [47mrewrite-lambda-modep[0m but the
  definition rune is disabled.  This expansion is suitable for use in
  an [47m[in-theory][0m event or [47m:in-theory[0m hint (see [47m:[0m[47m[hints][0m).

  Both these two runes are initially enabled, so eligible [47mlambda[0m object
  bodies are rewritten by default until and unless some event (e.g.,
  an [47m[in-theory][0m or [47m[include-book][0m) or a superior local subgoal hint
  changes the status of those runes.

  For example, if [47mlambda[0m object rewriting is active you wish to just
  syntactically clean the [47mlambda[0m objects in [47mSubgoal 3[0m of some proof,
  you could use the [47m:[0m[47m[hints][0m

    (\"Subgoal 3\"
     :in-theory (syntactically-clean-lambda-objects-theory))

  Note that if you also wish to enable or disable other runes in the
  same subgoal you must construct an appropriate theory.

  For example, if in [47mSubgoal 3[0m of some proof you wanted to enable
  [47mLEMMA1[0m and disable [47mLEMMA2[0m in a theory that will also specify
  syntactic cleaning of [47mlambda[0m objects, you might write

    (\"Subgoal 3\"
     :in-theory (set-difference-theories
                   (union-theories (syntactically-clean-lambda-objects-theory)
                                   '(LEMMA1))
                   '(LEMMA2)))

  Some users might prefer

    (\"Subgoal 3\"
     :in-theory (e/d ((:executable-counterpart rewrite-lambda-modep)
                      LEMMA1)
                     ((:definition rewrite-lambda-modep)
                      LEMMA2)))

  See [theories] for general information about theories and how to
  create and use them.")
 (SYNTAX
  (MISCELLANEOUS)
  "The syntax of ACL2 is that of Common Lisp

  For the details of ACL2 syntax, see CLTL.  For examples of ACL2
  syntax, use [47m:[0m[47m[pe][0m to print some of the ACL2 system code.  For
  example:

    :pe assoc-equal
    :pe dumb-occur
    :pe var-fn-count
    :pe add-linear-variable-to-alist

  There is no comprehensive description of the ACL2 syntax yet, except
  that found in CLTL.  Also see [term].")
 (SYNTAXP
  (REWRITE DEFINITION LINEAR META)
  "Attach a heuristic filter on a rule

  A call of [47msyntaxp[0m in the hypothesis of a [47m:[0m[47m[rewrite][0m,
  [47m:[0m[47m[rewrite-quoted-constant][0m, [47m:[0m[47m[definition][0m, or [47m:[0m[47m[linear][0m rule is
  treated specially, as described below.  Similar treatment is given
  to the evaluation of a [47m:[0m[47m[meta][0m rule's hypothesis function call.

  For example, consider the [47m:[0m[47m[rewrite][0m rule created from the following
  formula.

    Example:
    (IMPLIES (SYNTAXP (NOT (AND (CONSP X)
                                (EQ (CAR X) 'NORM))))
             (EQUAL (LXD X)
                    (LXD (NORM X)))).

  The [47msyntaxp[0m hypothesis in this rule will allow the rule to be applied
  to [47m(lxd (trn a b))[0m but will not allow it to be applied to [47m(lxd
  (norm a))[0m.

    General Form:
    (SYNTAXP test)

  [47mSyntaxp[0m always returns [47mt[0m and so may be added as a vacuous hypothesis.
  However, when relieving the hypothesis, the test ``inside'' the
  [47msyntaxp[0m form is actually treated as a meta-level proposition about
  the proposed instantiation of the rule's variables and that
  proposition must evaluate to true (non-[47mnil[0m) to ``establish'' the
  [47msyntaxp[0m hypothesis.

  Note that the test of a [47msyntaxp[0m hypothesis does not, in general, deal
  with the meaning or semantics or values of the terms, but rather
  with their syntactic forms.  In the example above, the [47msyntaxp[0m
  hypothesis allows the rule to be applied to every target of the
  form [47m(lxd u)[0m, provided [47mu[0m is not of the form [47m(norm v)[0m.  Observe that
  without this syntactic restriction the rule above could loop,
  producing a sequence of increasingly complex targets [47m(lxd a)[0m, [47m(lxd
  (norm a))[0m, [47m(lxd (norm (norm a)))[0m, etc.  An intuitive reading of the
  rule might be ``[47mnorm[0m the argument of [47mlxd[0m unless it has already been
  [47mnorm[0med.''

  Note also that a [47msyntaxp[0m hypothesis deals with the syntactic form
  used internally by ACL2, rather than that seen by the user.  In
  some cases these are the same, but there can be subtle differences
  with which the writer of a [47msyntaxp[0m hypothesis must be aware.  You
  can use [47m:[0m[47m[trans][0m to display this internal representation.

  There are two types of [47msyntaxp[0m hypotheses.  The simpler type may be a
  hypothesis of a [47m:[0m[47m[rewrite][0m, [47m:[0m[47m[definition][0m, or [47m:[0m[47m[linear][0m rule
  provided [47mtest[0m contains at least one variable but no free variables
  (see [free-variables]).  In particular, [47mtest[0m may not use [stobj]s;
  any stobj name will be treated as an ordinary variable.  The case
  of [47m:[0m[47m[meta][0m rules is similar to the above, except that it applies to
  the result of applying the hypothesis metafunction.  (Later below
  we will describe the second type, an [3mextended[0m [47msyntaxp[0m hypothesis,
  which may use [47m[state][0m.)

  We illustrate the use of simple [47msyntaxp[0m hypotheses by slightly
  elaborating the example given above.  Consider a [47m:[0m[47m[rewrite][0m rule:

    (IMPLIES (AND (RATIONALP X)
                  (SYNTAXP (NOT (AND (CONSP X)
                                     (EQ (CAR X) 'NORM)))))
             (EQUAL (LXD X)
                    (LXD (NORM X))))

  How is this rule applied to [47m(lxd (trn a b))[0m?  First, we form a
  substitution that instantiates the left-hand side of the conclusion
  of the rule so that it is identical to the target term.  In the
  present case, the substitution replaces [47mx[0m with [47m(trn a b)[0m.

    (LXD X) ==> (LXD (trn a b)).

  Then we backchain to establish the hypotheses, in order.  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 above, we
  rewrite

    (RATIONALP (trn a b)).

  If this rewrites to true, we continue.

  Of course, many users are aware of some exceptions to this general
  description of the way we relieve hypotheses.  For example, if a
  hypothesis contains a ``free-variable'' --- one not bound by the
  current substitution --- we attempt to extend the substitution by
  searching for an instance of the hypothesis among known truths.
  See [free-variables].  [47m[Force][0md hypotheses are another exception to
  the general rule of how hypotheses are relieved.

  Hypotheses marked with [47msyntaxp[0m, as in [47m(syntaxp test)[0m, are also
  exceptions.  We instantiate such a hypothesis; but instead of
  rewriting the instantiated instance, we evaluate the instantiated
  [47mtest[0m.  More precisely, we evaluate [47mtest[0m in an environment in which
  its variable symbols are bound to the quotations of the terms to
  which those variables are bound in the instantiating substitution.
  So in the case in point, we (in essence) evaluate

    (NOT (AND (CONSP '(trn a b)) (EQ (CAR '(trn a b)) 'NORM))).

  This clearly evaluates to [47mt[0m.  When a [47msyntaxp[0m test evaluates to true,
  we consider the [47msyntaxp[0m hypothesis to have been established; this
  is sound because logically [47m(syntaxp test)[0m is [47mt[0m regardless of [47mtest[0m.
  If the test evaluates to [47mnil[0m (or fails to evaluate because of
  [guard] violations) we act as though we cannot establish the
  hypothesis and abandon the attempt to apply the rule; it is always
  sound to give up.

  The acute reader will have noticed something odd about the form

    (NOT (AND (CONSP '(trn a b)) (EQ (CAR '(trn a b)) 'NORM))).

  When relieving the first hypothesis, [47m(RATIONALP X)[0m, we substituted
  [47m(trn a b)[0m for [47mX[0m; but when relieving the second hypothesis, [47m(SYNTAXP
  (NOT (AND (CONSP X) (EQ (CAR X) 'NORM))))[0m, we substituted the
  quotation of [47m(trn a b)[0m for [47mX[0m.  Why the difference?  Remember that
  in the first hypothesis we are talking about the value of [47m(trn a b)[0m
  --- is it rational --- while in the second one we are talking about
  its syntactic form.  Remember also that Lisp, and hence ACL2,
  evaluates the arguments to a function before applying the function
  to the resulting values. Thus, we are asking ``Is the list [47m(trn a
  b)[0m a [47m[consp][0m and if so, is its [47m[car][0m the symbol [47mNORM[0m?'' The [47mquote[0ms
  on both [47m(trn a b)[0m and [47mNORM[0m are therefore necessary.  One can verify
  this by defining [47mtrn[0m to be, say [47m[cons][0m, and then evaluating forms
  such as

    (AND (CONSP '(trn a b)) (EQ (CAR '(trn a b)) 'NORM))
    (AND (CONSP (trn a b)) (EQ (CAR (trn a b)) NORM))
    (AND (CONSP (trn 'a 'b)) (EQ (CAR (trn 'a 'b)) NORM))
    (AND (CONSP '(trn a b)) (EQ '(CAR (trn a b)) ''NORM))

  at the top-level ACL2 prompt.

  See [syntaxp-examples] for more examples of the use of [47msyntaxp[0m.

  An extended [47msyntaxp[0m hypothesis is similar to the simple type
  described above, but it uses two additional variables, [47mmfc[0m and
  [47mstate[0m, 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 [47mform[0m; first [47mmfc[0m, then [47mstate[0m.  These two variables give
  access to the functions [47mmfc-[0mxxx; see [extended-metafunctions].  As
  described there, [47mmfc[0m is bound to the so-called metafunction-context
  and [47mstate[0m to ACL2's [47m[state][0m.  See [syntaxp-examples] for an example
  of the use of these extended [47msyntaxp[0m hypotheses.

  We conclude with an example illustrating an error that may occur if
  you forget that a [47msyntaxp[0m hypothesis will be evaluated in an
  environment where variables are bound to syntactic terms, not to
  values.  Consider the following [stobj] introduction (see
  [defstobj]).

    (defstobj st
      (fld1 :type (signed-byte 3) :initially 0)
      fld2)

  The following [47msyntaxp[0m hypothesis is ill-formed for evaluation.
  Indeed, ACL2 causes an error because it anticipates that when
  trying to relieve the [47msyntaxp[0m hypothesis of this rule, ACL2 would
  be evaluating [47m(fld1 st)[0m where [47mst[0m is bound to a term, not to an
  actual [47mstobj[0m as required by the function [47mfld1[0m.  The error message
  is intended to explain this problem.

    ACL2 !>(defthm bad
             (implies (syntaxp (quotep (fld1 st)))
                      (equal (stp st)
                             (and (true-listp st)
                                  (equal (len st) 2)
                                  (fld1p (car st))))))

    ACL2 Error in ( DEFTHM BAD ...):  The form (QUOTEP (FLD1 ST)), from
    a SYNTAXP hypothesis, is not suitable for evaluation in an environment
    where its variables are bound to terms.  See :DOC SYNTAXP.  Here is
    further explanation:
         The form ST is being used, as an argument to a call of FLD1, where
    the single-threaded object of that name is required.  But in the current
    context, the only declared stobj name is STATE.  Note:  this error
    occurred in the context (FLD1 ST).

    Summary
    Form:  ( DEFTHM BAD ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

    ACL2 Error in ( DEFTHM BAD ...):  See :DOC failure.

    ******** FAILED ********
    ACL2 !>

  Presumably the intention was to rewrite the term [47m(stp st)[0m when the
  [47mfld1[0m component of [47mst[0m is seen to be an explicit constant.  As
  explained elsewhere (see [free-variables]), we can obtain the
  result of rewriting [47m(fld1 st)[0m by binding a fresh variable to that
  term using [47mEQUAL[0m, as follows.

    (defthm good
      (implies (and (equal f (fld1 st))
                    (syntaxp (quotep f)))
               (equal (stp st)
                      (and (true-listp st)
                           (equal (len st) 2)
                           (fld1p (car st))))))

  The event above is admitted by ACL2.  We can see it in action by
  disabling the definition of [47mstp[0m so that only the rule above, [47mgood[0m,
  is available for reasoning about [47mstp[0m.

    (in-theory (disable stp))

  Then the proof fails for the following, because the [47msyntaxp[0m
  hypothesis of the rule, [47mgood[0m, fails: [47m(quotep f)[0m evaluates to [47mnil[0m
  when [47mf[0m is bound to the term [47m(fld1 st)[0m.

    (thm (stp st))

  However, the proof succeeds for the next form, as we explain below.

    (thm (stp (list 3 rest)))

  Consider what happens in that case when rule [47mgood[0m is applied to the
  term [47m(stp (list 3 rest))[0m.  (See [free-variables] for relevant
  background.)  The first hypothesis of [47mgood[0m binds the variable [47mf[0m to
  the result of rewriting [47m(fld1 st)[0m, where [47mst[0m is bound to the
  (internal form of) the term [47m(list 3 rest)[0m --- and that result is
  clearly the term, [47m'3[0m.  Then the [47msyntaxp[0m hypothesis is successfully
  relieved, because the evaluation of [47m(quotep f)[0m returns [47mt[0m in the
  environment that binds [47mf[0m to [47m'3[0m.


Subtopics

  [Syntaxp-examples]
      Examples pertaining to syntaxp hypotheses")
 (SYNTAXP-EXAMPLES
  (SYNTAXP)
  "Examples pertaining to syntaxp hypotheses

  See [syntaxp] for a basic discussion of the use of [47msyntaxp[0m to control
  rewriting.

  A common syntactic restriction is

    (SYNTAXP (AND (CONSP X) (EQ (CAR X) 'QUOTE)))

  or, equivalently,

    (SYNTAXP (QUOTEP X)).

  A rule with such a hypothesis can be applied only if [47mx[0m is bound to a
  specific constant.  Thus, if [47mx[0m is [47m23[0m (which is actually represented
  internally as [47m(quote 23)[0m), the test evaluates to [47mt[0m; but if [47mx[0m prints
  as [47m(+ 11 12)[0m then the test evaluates to [47mnil[0m (because [47m(car x)[0m is the
  symbol [47m[binary-+][0m).  We see the use of this restriction in the rule

    (implies (and (syntaxp (quotep c))
                  (syntaxp (quotep d)))
             (equal (+ c d x)
                    (+ (+ c d) x))).

  If [47mc[0m and [47md[0m are constants, then the [47m[executable-counterpart][0m of
  [47m[binary-+][0m will evaluate the sum of [47mc[0m and [47md[0m.  For instance, under
  the influence of this rule

    (+ 11 12 foo)

  rewrites to

    (+ (+ 11 12) foo)

  which in turn rewrites to [47m(+ 23 foo)[0m.  Without the syntactic
  restriction, this rule would loop with the built-in rules
  [47mASSOCIATIVITY-OF-+[0m or [47mCOMMUTATIVITY-OF-+[0m.

  We here recommend that the reader try the affects of entering
  expressions such as the following at the top level ACL2 prompt.

    (+ 11 23)
    (+ '11 23)
    (+ '11 '23)
    (+ ''11 ''23)
    :trans (+ 11 23)
    :trans (+ '11 23)
    :trans (+ ''11 23)
    :trans (+ c d x)
    :trans (+ (+ c d) x)

  We also recommend that the reader verify our claim above about
  looping by trying the affect of each of the following rules
  individually.

    (defthm good
       (implies (and (syntaxp (quotep c))
                     (syntaxp (quotep d)))
                (equal (+ c d x)
                       (+ (+ c d) x))))

    (defthm bad
       (implies (and (acl2-numberp c)
                     (acl2-numberp d))
                (equal (+ c d x)
                       (+ (+ c d) x))))

  on (the false) theorems:

    (thm
      (equal (+ 11 12 x) y))

    (thm
      (implies (and (acl2-numberp c)
                    (acl2-numberp d)
                    (acl2-numberp x))
               (equal (+ c d x) y))).

  One can use [47m:[0m[47m[brr][0m, perhaps in conjunction with [47m[cw-gstack][0m, to
  investigate any looping.

  Here is a simple example showing the value of rule [47mgood[0m above.
  Without [47mgood[0m, the [47mthm[0m form below fails.

    (defstub foo (x) t)

    (thm (equal (foo (+ 3 4 x)) (foo (+ 7 x))))

  The next three examples further explore the use of [47mquote[0m in [47m[syntaxp][0m
  hypotheses.

  We continue the examples of [47m[syntaxp][0m hypotheses with a rule from
  community book [47mbooks/finite-set-theory/set-theory.lisp[0m.  We will
  not discuss here the meaning of this rule, but it is necessary to
  point out that [47m(ur-elementp nil)[0m is true in this book.

    (defthm scons-nil
      (implies (and (syntaxp (not (equal a ''nil)))
                    (ur-elementp a))
               (= (scons e a)
                  (scons e nil)))).

  Here also, [47m[syntaxp][0m is used to prevent looping.  Without the
  restriction, [47m(scons e nil)[0m would be rewritten to itself since
  [47m(ur-elementp nil)[0m is true.
  Question: Why the use of two quotes in [47m''nil[0m?
  Hints: [47mNil[0m is a constant just as 23 is.  Try [47m:trans (cons a nil)[0m,
  [47m:trans (cons 'a 'nil)[0m, and [47m:trans (cons ''a ''nil)[0m.  Also, don't
  forget that the arguments to a function are evaluated before the
  function is applied.

  The next two rules move negative constants to the other side of an
  inequality.

    (defthm |(< (+ (- c) x) y)|
      (implies (and (syntaxp (quotep c))
                    (syntaxp (< (cadr c) 0))
                    (acl2-numberp y))
               (equal (< (+ c x) y)
                      (< (fix x) (+ (- c) y)))))

    (defthm |(< y (+ (- c) x))|
      (implies (and (syntaxp (quotep c))
                    (syntaxp (< (cadr c) 0))
                    (acl2-numberp y))
               (equal (< y (+ c x))
                      (< (+ (- c) y) (fix x)))))

  Questions: What would happen if [47m(< (cadr c) '0)[0m were used?  What
  about [47m(< (cadr c) ''0)[0m?

  One can also use [47msyntaxp[0m to restrict the application of a rule to a
  particular set of variable bindings as in the following taken from
  the [ihs] library.

    (encapsulate ()

      (local
       (defthm floor-+-crock
         (implies
          (and (real/rationalp x)
               (real/rationalp y)
               (real/rationalp z)
               (syntaxp (and (eq x 'x) (eq y 'y) (eq z 'z))))
          (equal (floor (+ x y) z)
                 (floor (+ (+ (mod x z) (mod y z))
                           (* (+ (floor x z) (floor y z)) z)) z)))))

      (defthm floor-+
        (implies
         (and (force (real/rationalp x))
              (force (real/rationalp y))
              (force (real/rationalp z))
              (force (not (equal z 0))))
         (equal (floor (+ x y) z)
                (+ (floor (+ (mod x z) (mod y z)) z)
                   (+ (floor x z) (floor y z))))))

      )

  We recommend the use of [47m:[0m[47mbrr[0m to investigate the use of [47mfloor-+-crock[0m.

  Another useful restriction is defined by

    (defun rewriting-goal-literal (x mfc state)

      ;; Are we rewriting a top-level goal literal, rather than rewriting
      ;; to establish a hypothesis from a rewrite (or other) rule?

      (declare (ignore x state))
      (null (access metafunction-context mfc :ancestors))).

  We use this restriction in the rule

    (defthm |(< (* x y) 0)|
        (implies (and (syntaxp (rewriting-goal-literal x mfc state))
                      (rationalp x)
                      (rationalp y))
                 (equal (< (* x y) 0)
                        (cond ((equal x 0)
                               nil)
                              ((equal y 0)
                               nil)
                              ((< x 0)
                               (< 0 y))
                              ((< 0 x)
                               (< y 0))))))

  which has been found to be useful, but which also leads to excessive
  thrashing in the linear arithmetic package if used
  indiscriminately.

  See [extended-metafunctions] for information on the use of [47mmfc[0m and
  [47mmetafunction-context[0m.")
 (SYS-CALL
  (INTERFACING-TOOLS ACL2-BUILT-INS)
  "Make a system call to the host operating system

    Example Forms:
    (sys-call \"cp\" '(\"foo.lisp\" \"foo-copied.lisp\"))
    (prog2$ (sys-call \"cp\" '(\"foo.lisp\" \"foo-copied.lisp\"))
            (sys-call-status state))

  The first argument of [47msys-call[0m is a command for the host operating
  system, and the second argument is a list of strings that are the
  arguments for that command.

  The use of [47m[prog2$][0m in the second example form above is optional, but
  illustrates how to get the return status.  See [sys-call-status].
  [47mSys-call[0m itself always returns [47mnil[0m.

  [31;1mWARNING[0m: The details of how [47msys-call[0m works can vary among different
  host Lisp implementations!  Consider for example wildcard
  expansion, such as when executing the form [47m(sys-call \"ls\"
  '(\"*.lisp\"))[0m.  For ACL2 built on Allegro CL, CCL, CMUCL, GCL, or
  SBCL, we have seen this result in an error message such as [47m\"No such
  file or directory\"[0m, even though files with names of the form [47m*.lisp[0m
  are present in the current directory; but for ACL2 built on
  LispWorks, a list of such filenames is printed.

  More generally, we note that [47msys-call[0m does not provide some features
  that one may expect of a shell.  We mentioned wildcard expansion
  above; other sorts of shell expansion may also not be supported,
  such as [47m~/[0m.  [47mSys-call[0m also does not directly support output
  redirection.  If you want to run a program, [47mP[0m, and redirect its
  output, one option is to create a wrapper script, [47mW[0m to call
  instead.  Thus [47mW[0m might be a shell script containing the line:

    P $* >& foo.out

  Another approach is suggested by {a passage in the CCL manual |
  https://ccl.clozure.com/manual/chapter9.2.html}: call the shell
  program.  For example, here is how one might list the [47m.lisp[0m files
  in a directory.

    (sys-call \"sh\" '(\"-c\" \"ls *.lisp\"))

  For related utilities, see [sys-call*] and [sys-call+].  Both of
  those utilities return a suitable status (rather than requiring a
  separate call of a separate function, [47m[sys-call-status][0m, as
  described later below).  Also, [47msys-call+[0m returns the command's
  output, but (like [47msys-call[0m) [47msys-call*[0m does not.  An important
  distinction is that both [47msys-call+[0m and [47msys-call*[0m can make their
  calls to the operating system during proofs, unlike [47msys-call[0m as we
  now explain.

  [47mSys-call[0m does not invoke the operating system when it is invoked
  inside the theorem prover or [proof-builder].  The following
  example, from Eric Smith, illustrates this point: presumably we
  only want to reason about the return value, not write a file during
  a proof!

    (defttag foo)
    (thm (equal (sys-call \"touch\" (list \"/tmp/XXX\"))
                nil)
         :hints ((\"Goal\" :in-theory (disable (:type-prescription sys-call)))))

  Through Version 7.4, running this example did indeed create file
  [47m/tmp/XXX[0m if that file did not already exist.  Now, the
  [executable-counterpart] of [47msys-call[0m is disabled, which avoids that
  specific behavior.  Moreover: even with that executable-counterpart
  enabled, no file is created; [47msys-call[0m returns [47mnil[0m without invoking
  the operating system.  If such an evaluation attempt occurs during
  invocation of a [clause-processor] or [meta]function, then an error
  will be signaled.

    General Form:
    (sys-call cmd args)

  This function logically returns [47mnil[0m.  However, it makes the indicated
  call to the host operating system, as described above (not during a
  proof), using a function supplied ``under the hood'' by the
  underlying Lisp system.  This is an advanced feature that requires
  a trust tag (see below).  As noted above, host lisps differ on
  their handling of [47msys-call[0m; see the raw Lisp definition of ACL2
  source function [47msystem-call[0m for details, including exactly the
  underlying Lisp code that is invoked.  You can then look at that
  host lisp's manual for details about that underlying function.

  On occasions where one wishes to obtain the numeric status returned
  by the host operating system (or more precisely, by the Lisp
  function under the hood that passes the system call to the host
  operating system), one may do so; see [sys-call-status].  The
  status value is the value returned by that Lisp function, which may
  well be the same numeric value returned by the host operating
  system for the underlying system call.

  Note that [47msys-call[0m does not touch the ACL2 [47m[state][0m; however,
  [47m[sys-call-status][0m updates the [47macl2-oracle[0m field of the [47mstate[0m.

  Be careful if you use [47msys-call[0m!  It can be used for example to
  overwrite files, or worse!  We view a use of [47msys-call[0m as a call to
  the operating system that is made outside ACL2.  The following
  example from Bob Boyer shows how to use [47msys-call[0m to execute, in
  effect, arbitrary Lisp forms.  ACL2 provides a ``trust tag''
  mechanism that requires execution of a [47m[defttag][0m form before you
  can use [47msys-call[0m; see [defttag].  (Note: The setting of the raw
  Lisp variable [47m*features*[0m below is just to illustrate that any such
  mischief is possible.  Normally [47m*features*[0m is a list with more than
  a few elements.  Also, note that this log is from many years ago;
  the feature shown, [47m:AKCL-SET-MV[0m, is no longer present.)

    % cat foo
    print *0x85d2064=0x838E920
    detach
    q
    % acl2
    ... boilerplate deleted
    ACL2 !>(sys-call \"gdb -p $PPID -w < foo >& /dev/null \" nil)
    NIL
    ACL2 !>:q

    Exiting the ACL2 read-eval-print loop.  To re-enter, execute (LP).
    ACL2>*features*

    (:AKCL-SET-MV)

    ACL2>


Subtopics

  [Sys-call*]
      Make a system call to the host OS, returning a status

  [Sys-call+]
      Make a system call to the host OS, returning status and output

  [Sys-call-status]
      Exit status from the preceding system call")
 (SYS-CALL*
  (SYS-CALL ACL2-BUILT-INS)
  "Make a system call to the host OS, returning a status

  See [sys-call+] for a closely related utility.  There are only the
  following two differences between [47msys-call*[0m and [47msys-call+[0m.

    * Both return an [error-triple] [47m(mv erp val state)[0m, but for [47msys-call*[0m,
      [47mval[0m is always [47mnil[0m after printing as a side effect like
      [47m[sys-call][0m.  (For [47msys-call+[0m, [47mval[0m is the string produced as
      output by the command.)

    * Logically, [47msys-call*[0m pops the oracle once, not twice.")
 (SYS-CALL+
  (SYS-CALL ACL2-BUILT-INS)
  "Make a system call to the host OS, returning status and output

    Example Form:
    ; The following returns (mv nil s state), where s is the standard output
    ; from the command: ls -l ./
    (sys-call+ \"ls\" '(\"-l\" \"./\") state)

    General Form:
    (sys-call+ cmd args state)

  where [47mcmd[0m is a command to the host operating system and [47margs[0m is a
  list of strings.  Also see related utilities [sys-call] and
  [sys-call*].  There are three major differences between [47m[sys-call][0m
  and both [47msys-call+[0m and [47msys-call*[0m.  First, the latter two take an
  extra argument, [47mstate[0m.  Second, while [47msys-call[0m returns [47mnil[0m,
  [47msys-call+[0m and [47msys-call*[0m both return an [error-triple], [47m(mv erp val
  state)[0m.  Finally, [47msys-call+[0m and [47msys-call*[0m provide a command to the
  host operating system even during a proof, which could be useful in
  computed hints and clause processors.  While execution returns
  values as listed below, further below we explain the logical return
  values.  In the following, please keep in mind that the exact
  behavior depends on the platform; the description is only a guide.
  For example, on some platforms [47merp[0m might always be [47mnil[0m, even if in
  the error case, and [47mval[0m might or might not include error output.
  (For details, look at the ACL2 source code for function
  [47msystem-call+[0m, whose output is converted by replacing an [47merp[0m of [47mnil[0m
  by 0.)

      [47mErp[0m can be [47mnil[0m, indicating that after the command executes the
      process status returned is 0, indicating a normal exit.
      Otherwise [47merp[0m is a non-zero integer, which is the status
      returned by the process when it completes.

      [47mVal[0m is a string, typically the output generated by the call of [47mcmd[0m.

      [47mState[0m is an ACL2 [state].

  While the description above pertains to the values returned by
  executing [47msys-call+[0m, the logical values are as follows.  For a
  discussion of the [47macl2-oracle[0m field of an ACL2 state, see
  [47m[read-ACL2-oracle][0m and [state].

      [47mErp[0m is the first element of the [47macl2-oracle[0m of the input state if
      that element is a nonzero integer, and otherwise is [47mnil[0m.

      [47mVal[0m is the second element of the [47macl2-oracle[0m of the input state if it
      is a string, else the empty string, [47m\"\"[0m.

      [47mState[0m is the result of popping the [47macl2-oracle[0m field twice from the
      input state.

  Note that unlike [47m[sys-call][0m, a call of [47m[sys-call+][0m has no effect on
  subsequent calls of [47m[sys-call-status][0m.

  As is the case for [47msys-call[0m, a trust tag is required to call
  [47msys-call+[0m.  For discussion of this and more, see [sys-call].")
 (SYS-CALL-STATUS
  (SYS-CALL ACL2-BUILT-INS)
  "Exit status from the preceding system call

  This function returns two values, [47m(mv status state)[0m.  The first is
  the status resulting from the most recent call to the operating
  system by invoking function [47m[sys-call][0m.  The second is the ACL2
  [47m[state][0m object, which is also the input to this function.

  The function [47m[sys-call][0m provides a command to be executed by the host
  operating system (except when invoked during a proof; see
  [sys-call]) using a function supplied ``under the hood'' by the
  underlying Lisp system.  The status value is an integer, which is
  the status returned by the process when it completes.")
 (SYSFILE
  (BOOKS PROJECT-DIR-ALIST)
  "File representation using ACL2 project directories

  ACL2 supports relocation of book directories so that those books are
  still treated as certified.  See [project-dir-alist].

  A key data structure to support this feature is the [3msysfile[0m, which is
  a pair of the form [47m(:kwd . \"relpath\")[0m.  Here, [47m:kwd[0m is a key of the
  [47mproject-dir-alist[0m, bound to some absolute pathname [47m\"D/\"[0m of a
  directory, and [47m\"relpath\"[0m is a string that denotes a pathname
  relative to directory [47m\"D/\"[0m.  Thus, the sysfile [47m(:kwd . \"relpath\")[0m
  represents the same pathname as [47m\"D/relpath\"[0m.

  (Remark.  The name ``sysfile'' was originally coined to suggest
  ``system file'', suggesting the use of keyword [47m:SYSTEM[0m to indicate
  a file residing in the [community-books].  It now extends to [47m(:kwd
  . \"relpath\")[0m even for [47m:kwd[0m values other than [47m:SYSTEM[0m.  But
  ``sysfile'' is a convenient name, and it still seems reasonable
  since ``system file'' can suggest a file of the filesystem.)

  ACL2 rarely generates output that includes sysfiles; they are mostly
  used in the implementation, for example to denote included books in
  [certificate] files.  But they are occasionally relevant at the
  user level; for example see [add-include-book-dir].

  Finally we discuss the use of sysfiles in [certificate] files.  When
  the [community-books] directory is a prefix of a [full-book-name]
  string, ACL2 may choose to represent that full-book-name as
  [47m(:system . \"relpath\")[0m, where [47m\"relpath\"[0m is the result of removing
  the community-books directory from the front of the full-book-name.
  Here is an example.

    ; full-book-name:
    \"/Users/smith/acl2/acl2/books/std/portcullis.lisp\"

    ; sysfile representation
    ; (where \"/Users/smith/acl2/acl2/books/\" is the community-books directory):
    (:SYSTEM . \"std/portcullis.lisp\")

  This behavior applies to more than the community-books: it applies to
  the entire [47m[project-dir-alist][0m.  If that alist associates keyword
  [47m:K[0m with absolute directory name [47m\"<dir>\"[0m, then a full-book-name with
  prefix [47m\"<dir>\"[0m, say, [47m\"<dir>/relpath\"[0m, is written to a [certificate]
  file as [47m(:K . \"relpath\")[0m.  This capability supports relocating book
  directories; see [project-dir-alist] for a more complete
  discussion.")
 (SYSTEM-ATTACHMENTS
  (PROGRAMMING DEFATTACH)
  "System-level algorithms that users can modify with attachments

  This topic concerns advanced methods for modifying the behavior of
  ACL2.  See [defattach] for some relevant background.

  If you evaluate the form [47m(global-val 'attachments-at-ground-zero (w
  state))[0m, you will see a list of pairs of the form [47m(f . g)[0m, where [47mf[0m
  is a built-in constrained utility and [47mg[0m is its attachment.  At the
  end of this topic is a list that associates each such [47mf[0m with brief
  documentation (often, just a link).  Users are permitted to modify
  these attachments using [47m[defattach-system][0m, even without a trust
  tag (see [defttag]), because they do not affect soundness.

  Here are two functions that are useful for attaching to many
  attachable 0-ary system functions.

  [31;1mFunction: [0m<constant-t-function-arity-0>

    (defun constant-t-function-arity-0 nil
      (declare (xargs :guard t))
      t)

  [31;1mFunction: [0m<constant-nil-function-arity-0>

    (defun constant-nil-function-arity-0 nil
      (declare (xargs :guard t))
      nil)

  To see how to use one of these functions, consider the following
  example of a pair [47m(f . g)[0m as described above, i.e., a system
  function [47mf[0m that comes with attachment [47mg[0m.

    (ASSUME-TRUE-FALSE-AGGRESSIVE-P . CONSTANT-NIL-FUNCTION-ARITY-0)

  Here is how we can make the so-called ``assume-true-false'' algorithm
  more aggressive; see [assume-true-false-aggressive-p].

    (defattach-system assume-true-false-aggressive-p constant-t-function-arity-0)

  The following brief explanations are intentionally brief.  We expect
  that those who want to use such system attachments are comfortable
  as ``system programmers'', so that the brief documentation below is
  sufficient for getting started.  Perusal of the ACL2 source code
  and its comments can fill in details as needed.

  Also see [efficiency] for further discussion on making system
  attachments that modify ACL2's default behavior.


Summary of attachable system functions

  [47mACL2X-EXPANSION-ALIST[0m
  Built-in attachment: [47mIDENTITY-WITH-STATE[0m
  [Undocumented: low-level system utility]

  [47mALWAYS-DO-PROOFS-DURING-MAKE-EVENT-EXPANSION[0m
  Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m
  Documentation: See [make-event].

  [47mANCESTORS-CHECK[0m
  Built-in attachment: [47mANCESTORS-CHECK-BUILTIN[0m
  Documentation: Backchaining control; see
  [use-trivial-ancestors-check].  Source function
  [47mstrip-ancestor-literals[0m might also be useful.

  [47mAPPLY$-USERFN[0m
  Built-in attachment: [47mDOPPELGANGER-APPLY$-USERFN[0m
  [Undocumented: low-level system utility]

  [47mASSUME-TRUE-FALSE-AGGRESSIVE-P[0m
  Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m
  Documentation: See [assume-true-false-aggressive-p].

  [47mBADGE-USERFN[0m
  Built-in attachment: [47mDOPPELGANGER-BADGE-USERFN[0m
  [Undocumented: low-level system utility]

  [47mBEING-OPENEDP-LIMITED-FOR-NONREC[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: Attach to [47mconstant-nil-function-arity-0[0m to extend to
  non-recursively defined functions the stack-based limitation on
  opening recursively-defined functions.

  [47mBRKPT1-BRR-DATA-ENTRY[0m
  Built-in attachment: [47mBRKPT1-BRR-DATA-ENTRY-BUILTIN[0m
  Documentation: See [with-brr-data].

  [47mBRKPT2-BRR-DATA-ENTRY[0m
  Built-in attachment: [47mBRKPT2-BRR-DATA-ENTRY-BUILTIN[0m
  Documentation: See [with-brr-data].

  [47mCONJOIN-CLAUSE-SETS-BOUND[0m
  Built-in attachment: [47mCONJOIN-CLAUSE-SETS-BOUND-BUILTIN[0m
  Documentation: Attach to a constant function that returns a natural
  number (default [47m50[0m) bounding how large a clause-set can be to do
  smart merging into another clause-set; see comments in the
  definition of conjoin-clause-sets in the ACL2 sources for more
  explanation.

  [47mHEAVY-LINEAR-P[0m
  Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m
  Documentation: See [heavy-linear-p].

  [47mHIDE-WITH-COMMENT-P[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: See [hide].

  [47mONCEP-TP[0m
  Built-in attachment: [47mONCEP-TP-BUILTIN[0m
  Documentation: See [free-variables-type-prescription].

  [47mPRINT-CLAUSE-ID-OKP[0m
  Built-in attachment: [47mPRINT-CLAUSE-ID-OKP-BUILTIN[0m
  Documentation: See [set-print-clause-ids].

  [47mQUICK-AND-DIRTY-SRS[0m
  Built-in attachment: [47mQUICK-AND-DIRTY-SRS-BUILTIN[0m
  Documentation: See [quick-and-dirty-subsumption-replacement-step].

  [47mRELIEVE-HYP-FAILURE-ENTRY-SKIP-P[0m
  Built-in attachment: [47mRELIEVE-HYP-FAILURE-ENTRY-SKIP-P-BUILTIN[0m
  [Undocumented: low-level system utility]

  [47mREMOVE-GUARD-HOLDERS-BLOCKED-BY-HIDE-P[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: See [guard-holders].

  [47mREMOVE-GUARD-HOLDERS-LAMP[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: See [guard-holders].

  [47mREMOVE-TRIVIAL-EQUIVALENCES-ENABLED-P[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: See [remove-trivial-equivalences-enabled-p].

  [47mREWRITE-IF-AVOID-SWAP[0m
  Built-in attachment: [47mCONSTANT-NIL-FUNCTION-ARITY-0[0m
  Documentation: See [rewrite-if-avoid-swap].

  [47mRW-CACHE-DEBUG[0m
  Built-in attachment: [47mRW-CACHE-DEBUG-BUILTIN[0m
  [Undocumented: low-level system utility]

  [47mRW-CACHE-DEBUG-ACTION[0m
  Built-in attachment: [47mRW-CACHE-DEBUG-ACTION-BUILTIN[0m
  [Undocumented: low-level system utility]

  [47mRW-CACHEABLE-FAILURE-REASON[0m
  Built-in attachment: [47mRW-CACHEABLE-FAILURE-REASON-BUILTIN[0m
  [Undocumented: low-level system utility]

  [47mSET-LD-HISTORY-ENTRY-USER-DATA[0m
  Built-in attachment: [47mSET-LD-HISTORY-ENTRY-USER-DATA-DEFAULT[0m
  Documentation: See [ld-history].

  [47mSIMPLIFIABLE-MV-NTH-P[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: See [theories-and-primitives].

  [47mTOO-MANY-IFS-POST-REWRITE[0m
  Built-in attachment: [47mTOO-MANY-IFS-POST-REWRITE-BUILTIN[0m
  Documentation: Heuristic for discarding rewriter result with ``too
  many IFs''.  Defeat by attaching [47mconstant-nil-function-arity-2[0m.

  [47mTOO-MANY-IFS-PRE-REWRITE[0m
  Built-in attachment: [47mTOO-MANY-IFS-PRE-REWRITE-BUILTIN[0m
  Documentation: Heuristic for skipping rewrite when unrewritten result
  has ``too many IFs''.  Defeat by attaching
  [47mconstant-nil-function-arity-2[0m.

  [47mUNTRANSLATE-LAMBDA-OBJECT-P[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: See [lambda$].

  [47mUPDATE-BRR-DATA-1[0m
  Built-in attachment: [47mUPDATE-BRR-DATA-1-BUILTIN[0m
  Documentation: See [with-brr-data].

  [47mUPDATE-BRR-DATA-2[0m
  Built-in attachment: [47mUPDATE-BRR-DATA-2-BUILTIN[0m
  Documentation: See [with-brr-data].

  [47mUSE-ENHANCED-RECOGNIZER[0m
  Built-in attachment: [47mCONSTANT-T-FUNCTION-ARITY-0[0m
  Documentation: Heuristic for treating [47m(equal TERM nil)[0m and [47m(equal nil
  TERM)[0m as providing a type for [47mTERM[0m during forward-chaining and
  other operations that assume such a term to be true.

  [47mWORSE-THAN[0m
  Built-in attachment: [47mWORSE-THAN-BUILTIN[0m
  [Undocumented: low-level system utility]

  [47mWORSE-THAN-OR-EQUAL[0m
  Built-in attachment: [47mWORSE-THAN-OR-EQUAL-BUILTIN[0m
  [Undocumented: low-level system utility]


Subtopics

  [Assume-true-false-aggressive-p]
      Control rewriter's use of the [type-alist] with [47mIF[0m calls

  [Heavy-linear-p]
      Extend the use of [linear-arithmetic] during rewriting

  [Remove-trivial-equivalences-enabled-p]
      Avoid removal of trivial equivalences during rewriting

  [Rewrite-if-avoid-swap]
      Control rewriter's swapping of branches of [47mIF[0m calls")
 (SYSTEM-UTILITIES
  (PROGRAMMING)
  "Some built-in programming utilities pertaining to the ACL2 system

  Since the ACL2 system is written in itself, the source code defines
  many utilities that support the ACL2 implementation.  Some of these
  have been found to be useful not only to the ACL2 developers, but
  to those who use ACL2 to perform tasks other than the traditional
  ones: writing and submitting definitions, and proving theorems
  about the functions defined.

  This topic provides a summary of some of those utilities that are
  built into the ACL2 system.  It is intended to be a growing
  document, with contributions from those in the community who find
  such utilities that benefit them.  It has already grown
  substantially from an initial version created by the ACL2
  implementors, and others will likely continue to add to it over
  time.

  [31;1mWARNING 1[0m.  Some system utilities are in [47m:[0m[47m[program][0m mode, and for
  many of those, [guard]s are incomplete or missing entirely.
  Incorrect use of such utilities can thus lead to scary (though
  often harmless) raw Lisp errors!  Although this situation may
  improve over time, for now users of these utilities must cope with
  that danger just as the ACL2 implementors cope with it, which is by
  understanding the requirements on each utility that is invoked.
  For example, if you incorrectly invoke [47m(untranslate (cons 3 4) nil
  (w state))[0m, where perhaps [47m(untranslate '(cons '3 '4) nil (w state))[0m
  was intended, then the resulting raw Lisp error is your
  responsibility for invoking [47muntranslate[0m on the object [47m(3 . 4)[0m
  instead of the term [47m(cons '3 '4)[0m.

  [31;1mWARNING 2[0m.  These utilities are subject to change.  They were
  developed to support the ACL2 system, and as ACL2 evolves, its
  developers claim the right to modify these functions --- even their
  input-output [signature]s.  That said, changes to these functions
  are likely to be quite rare.

  The ACL2 system comes with substantial comments.  As of Version_7.1
  (May, 2015), out of slightly under 10 MB of source code (not
  including 4.8 MB of [documentation] topics), nearly 400 KB (just
  over 40%) were comment lines.  This topic is not intended to
  supplant or duplicate those comments, but rather, only to note
  system utilities of interest to the community.  If you find the
  source comments inadequate, please feel free to ask the system
  implementors to make corresponding additions to the source code
  comments.  Note that if you execute the command

    egrep -e '^; Essay on' *.lisp

  in your ACL2 sources directory, you will see the names of more than
  90 long source comments, or ``Essays'', that can provide additional
  background.

  Also see [programming] and its subtopics, in particular
  [programming-with-state], which describes [3mmany[0m built-in system
  utilities.  For example, a subsection of [programming-with-state],
  entitled ``SEQUENTIAL PROGRAMMING'', introduces handy utilities
  [47m[pprogn][0m and [47m[er-progn][0m along with links to their documentation.
  You may also wish to see [system-attachments] for how to make a few
  changes to the behavior of ACL2.

  Here is another option for finding a built-in system utility: As ACL2
  developers sometimes do, use [47mmeta-.[0m or [47mmeta-x tags-apropos[0m in Emacs
  to find utilities with given substrings in their names.  For
  example, if in Emacs you submit the command [47mmeta-x tags-apropos[0m and
  reply [47mpwd[0m at the prompt, you'll find a raw Lisp function [47mour-pwd[0m
  that ACL2 defines as an analogue to the Linux [47mpwd[0m command; and,
  with [47mmeta-x tags-search[0m applied to [47m(our-pwd[0m, you can see how ACL2
  source code uses this utility.


List of a few built-in system utilities

  Every function mentioned below belongs in the constant
  [47m[*ACL2-system-exports*][0m.  Also see [ACL2-built-ins] for built-in
  utilities that are less relevant to the ACL2 system, and see
  [programming] for utilities in general.

    * [47m(acl2-unwind-protect expl body cleanup1 cleanup2)[0m: This particularly
      sophisticated utility (warning: for advanced system hackers) is
      logically just the following (where the formals shown above are
      capitalized).

          (mv-let (erp val state)
                  BODY
                  (cond (erp (pprogn CLEANUP1 (mv erp val state)))
                        (t   (pprogn CLEANUP2 (mv erp val state)))))

      However, aborts are typically handled by causing the ``cleanup''
      forms to be executed, in the spirit of Common Lisp's
      [47munwind-protect[0m.  In typical use the cleanup forms restore the
      values of [state] global variables that were ``temporarily''
      set by [47mbody[0m.  Note that [47mexpl[0m is essentially ignored.  For more
      information see the Essay on Unwind-Protect in the ACL2 source
      code.

    * [47m(add-suffix sym str)[0m: Extend a symbol [47msym[0m with a suffix expressed as
      a string [47mstr[0m.  The resulting symbol is in the same package as
      the original symbol.  For instance, [47m(add-suffix 'abc \"DEF\")[0m
      results in the symbol [47m'abcdef[0m, in the same package as [47m'abc[0m.
      See [47m[add-suffix-to-fn][0m for a variant that may be more
      appropriate for generating new function names.

    * [47m(add-suffix-to-fn sym suffix)[0m: Variant of [47m[add-suffix][0m that puts the
      new symbol in the [47m\"ACL2\"[0m package when [47msym[0m is in the
      [47m\"COMMON-LISP\"[0m package.  New function symbols cannot be in the
      [47m\"COMMON-LISP\"[0m package; thus, this utility may be appropriate
      when generating new function names from old ones.

    * [47m(all-attachments wrld)[0m: Return a list of all attachment pairs [47m(f . g)[0m
      where [47mg[0m is attached to [47mf[0m (see [defattach]) in the [world],
      [47mwrld[0m, except for two cases that are ignored for this purpose:
      [warrant]s, and attachments introduced with a non-[47mnil[0m value of
      [47m:skip-checks[0m.  To obtain the attachment to a function symbol [47mf[0m,
      without the restrictions above and with value [47mnil[0m if there is
      no attachment to [47mf[0m, evaluate [47m(cdr (attachment-pair 'f wrld))[0m.
      To obtain the list of all built-in attachments, evaluate
      [47m(global-val 'attachments-at-ground-zero (w state))[0m.

    * [47m(all-calls names term alist ans)[0m: Accumulate into [47mans[0m (which
      typically is [47mnil[0m at the top level) all pseudo-terms [47mu/alist[0m
      such that for some [47mf[0m in the list, [47mnames[0m, [47mu[0m is a subterm of the
      pseudo-term, [47mterm[0m, that is a call of the symbol, [47mf[0m.  Note that
      [47m(all-calls-lst names lst alist ans)[0m is similar, except for a
      list, [47mlst[0m, of terms in place of a single term, [47mterm[0m.

    * [47m(all-ffn-symbs term ans)[0m: Accumulate into [47mans[0m (which typically is [47mnil[0m
      at the top level) all function symbols called in the given
      term.  This may become deprecated, and is just a macro
      expanding to a corresponding call of [47mall-fnnames1[0m; see
      [47mall-fnnames[0m, [47mall-fnnames-lst[0m, and [47mall-fnnames1[0m, below.

    * [47m(all-ffn-symbs-lst lst ans)[0m: Accumulate into [47mans[0m (which typically is
      [47mnil[0m at the top level) all function symbols called in the given
      list of terms.  This may become deprecated, and is just a macro
      expanding to a corresponding call of [47mall-fnnames1[0m; see
      [47mall-fnnames[0m, [47mall-fnnames-lst[0m, and [47mall-fnnames1[0m, below.

    * [47m(all-fnnames term)[0m: Return a list of all function symbols called in
      the given term.  This is a macro call expanding to
      [47m(all-fnnames1 nil term nil)[0m.

    * [47m(all-fnnames-lst lst)[0m: Return a list of all function symbols called
      in the given list of terms.  This is a macro call expanding to
      [47m(all-fnnames1 t lst nil)[0m.

    * [47m(all-fnnames1 flg x acc)[0m: Accumulate into [47macc[0m the function symbols
      called in the given term or list of terms, [47mx[0m, according to
      whether [47mflg[0m is [47mnil[0m (for a term) or not [47mnil[0m (for a list of
      terms), respectively.

    * [47m(all-vars x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return a duplicate-free list of
      all variables in [47mx[0m, in reverse print order of first occurrence.
      For example, [47mall-vars[0m of [47m'(f (g a b) c)[0m is [47m'(c b a)[0m.

    * [47m(arglistp lst)[0m: Return true iff [47mlst[0m is a [47mnil[0m-terminated list of
      distinct, legal variable names, usable as the formal argument
      list (hence the name of this utility) of a function.

    * [47m(arity fn w)[0m: For a function symbol or [47mlambda[0m expression [47mfn[0m of
      [world] [47mw[0m, return the number of its formal parameters.

    * [47m(body fn normalp w)[0m: [47mFn[0m should either be a [47m:[0m[47m[logic][0m-mode function
      symbol of [world] [47mw[0m or a [47mlambda[0m expression.  If [47mfn[0m is a symbol
      and [47mnormalp[0m is [47mnil[0m, then return the body (translated but
      unnormalized) of its original definition.  If [47mfn[0m is a [47mlambda[0m
      expression, return its body.  We now discuss the remaining
      case, where [47mfn[0m is a [47m:[0m[47m[logic][0m-mode function symbol and [47mnormalp[0m
      is true.  In the usual case that no [definition] rule has been
      introduced for [47mfn[0m with a non-[47mnil[0m value of [47m:install-body[0m (which
      is the default), return the [normalize]d body from the [47mdefun[0m
      form that introduced [47mfn[0m, or [47mnil[0m if [47mfn[0m was not introduced with
      [47mdefun[0m (as with [47m[encapsulate][0m, [47m[defstub][0m, or [47m[defchoose][0m) ---
      except that in the case that [47m:normalize nil[0m was specified in
      that [47mdefun[0m form (see [xargs]), return the unnormalized body.
      The remaining case is that at least one [definition] rule for
      [47mfn[0m has been installed.  In that case, the latest such rule
      provides the body (see source function [47mlatest-body[0m for how
      hypotheses are handled), with one exception: if the equivalence
      relation for that rule is other than [47mequal[0m, then the
      unnormalized body is returned.

    * [47m(conjoin lst)[0m: The conjunction of the given list of terms.

    * [47m(conjoin2 term1 term2)[0m: The conjunction of the given two terms.

    * [47m(cons-term fn args)[0m: Returns a [term] with function symbol (or
      [lambda] expression) [47mfn[0m and arguments [47margs[0m.  Evaluation may be
      performed for calls of primitives --- that is, built-in
      functions without definitions --- on arguments that are quoted
      constants, for example as follows.

          ACL2 !>(cons-term 'coerce (list ''\"abc\" ''list))
          '(#\\a #\\b #\\c)
          ACL2 !>

      To avoid such evaluation, use [47mfcons-term[0m (``fast cons-term''),
      described below.  Also see [47mcons-term*[0m and [47mfcons-term*[0m below.

    * [47m(cons-term* fn arg1 arg2 ...)[0m: This variant of [47mcons-term[0m (described
      above) returns a term with the indicated function and
      arguments, where the arguments are ``spread'' into individual
      actual parameters rather than provided as a list.  Some
      simplification may be done; to avoid that, use [47mfcons-term*[0m.
      Also see [47mcons-term[0m above and [47mfcons-term[0m below.

    * [47m(default-state-vars state-p &key ...)[0m: Returns a record suitable as
      an argument for some utilities that take the [world] as an
      argument but not the [state], such as [47mtranslate-cmp[0m.  That
      record provides values for certain state global variables
      (which are not stored in the world), such as [47mguard-checking-on[0m
      (which holds the [guard]-checking mode).  As described below,
      [47mdefault-state-vars[0m provides suitable defaults, which however
      can be modified by supplying keyword arguments corresponding to
      certain state globals, such as [47m:guard-checking-on[0m.  When the
      required argument is [47mt[0m, those defaults are the values of those
      state globals; thus, [47mt[0m is probably the right value to use for
      that argument when the state is available in the calling
      context.  Otherwise, those defaults are the values commonly
      found in those state globals.

    * [47m(defined-constant name w)[0m: If [47mname[0m is [47mt[0m, [47mnil[0m, or defined using
      [47m[defconst][0m, return [47m(quote val)[0m where [47mval[0m is the value of [47mname[0m;
      otherwise return [47mnil[0m.

    * [47m(defun-mode fn w)[0m: If [47mfn[0m is a function symbol, return the
      [defun-mode] of [47mfn[0m: [47m:program[0m if [47mfn[0m is in [47m:[0m[47m[program][0m mode,
      [47m:logic[0m if [47mfn[0m is in [47m:[0m[47m[logic][0m mode.  If [47mfn[0m is not a function
      symbol, return [47mnil[0m.

    * [47m(disabledp name)[0m: The list of [rune]s introduced with [47mname[0m that are
      currently [disable]d.  See [disabledp].  Also see
      [47menabled-runep[0m, below, for a more direct test of whether a given
      rune is [enable]d.

    * [47m(disjoin lst)[0m: The disjunction of the given list of terms.

    * [47m(disjoin2 term1 term2)[0m: The disjunction of the given two terms.

    * [47m(doublet-listp x)[0m: Returns [47mt[0m if [47mlst[0m is a list of two-element lists
      [47m(x1 x2)[0m, else [47mnil[0m.

    * [47m(dumb-negate-lit t1)[0m: For the given [term] [47mt1[0m, return a term that is
      propositionally equivalent to [47m(not t1)[0m.

    * [47m(dumb-occur x y)[0m: Return [47mt[0m if the term [47mx[0m occurs free in the term [47my[0m,
      but without looking for [47mx[0m inside of quoted constants; else,
      returns [47mnil[0m.

    * [47m(dumb-occur-var x y)[0m: Return [47mt[0m if the variable [47mx[0m occurs free in the
      term [47my[0m, else [47mnil[0m.  This is the same as [47mdumb-occur[0m, but
      optimized for the case that [47mx[0m is a variable.

    * [47m(enabled-numep nume ens wrld)[0m: Return true iff the given nume
      (numeric representation of a [rune]) in the [world], [47mwrld[0m, is
      [enable]d with respect to the given enabled structure, [47mens[0m.
      (For example, [47m(ens state)[0m returns the global enabled structure;
      during a proof, the enabled structure comes from the so-called
      rewrite-constant.)  [47mNil[0m is also a valid first argument, in
      which case the return value is [47mt[0m.  See also [47menabled-runep[0m.

    * [47m(enabled-runep rune ens wrld)[0m: Return true iff the given [rune] in
      the [world], [47mwrld[0m, is [enable]d with respect to the given
      enabled structure (as discussed for [47menabled-numep[0m, just above).
      See also [47menabled-numep[0m, which may be more efficient since
      [47menabled-runep[0m is defined in terms of [47menabled-numep[0m.

    * [47m(fargn x n)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is a function call and for a
      positive integer [47mn[0m, return the [47mn[0m-th argument of [47mx[0m, where the
      numbering of arguments starts at 1.

    * [47m(fargs x)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is a function call, return its
      arguments.

    * [47m(fcons-term fn args)[0m: This variant of [47mcons-term[0m (described above)
      returns a term with the indicated function and arguments,
      without any simplification.  Also see [47mcons-term[0m and [47mcons-term*[0m
      above, and [47mfcons-term*[0m below.

    * [47m(fcons-term* fn arg1 arg2 ...)[0m: This variant of [47mfcons-term[0m (described
      above) returns a term with the indicated function and
      arguments, without any simplification, and where the arguments
      are ``spread'' into individual actual parameters rather than
      provided as a list.  Also see [47mcons-term[0m, [47mcons-term*[0m, and
      [47mfcons-term[0m above.

    * [47m(fdefun-mode fn)[0m: For a function symbol [47mfn[0m, return the [defun-mode]
      of [47mfn[0m: [47m:program[0m if [47mfn[0m is in [47m:[0m[47m[program][0m mode, [47m:logic[0m if [47mfn[0m is in
      [47m:[0m[47m[logic][0m mode.

    * [47m(ffn-symb x)[0m: This version of [47mfn-symb[0m (described below) assumes that
      [47mx[0m is a [47m[pseudo-termp][0m that is a function call, without checking
      that [47mx[0m is a function call (the leading ``f'' is for ``fast''),
      and returns its called function or [47mlambda[0m expression.

    * [47m(ffn-symb-p x sym)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return [47mt[0m if it is a
      function call whose function symbol is [47msym[0m, else return [47mnil[0m.

    * [47m(ffnnamep fn term)[0m: Returns [47mt[0m when the function [47mfn[0m (possibly a
      [lambda] expression) is used as a function in [47mterm[0m, which is
      assumed to be a [47m[pseudo-termp][0m; else returns [47mnil[0m.

    * [47m(ffnnamep-lst fn lst)[0m: Returns [47mt[0m when the function [47mfn[0m (possibly a
      [lambda] expression) is used as a function in a member of the
      list [47mlst[0m of [47m[pseudo-termp][0ms; else returns [47mnil[0m.

    * [47m(fix-pkg pkg)[0m: Returns [47mpkg[0m, which should be [47mnil[0m or a non-empty
      string, with one exception: if [47mpkg[0m is [47m\"COMMON-LISP\"[0m then [47m\"ACL2\"[0m
      is returned.

    * [47m(flambda-applicationp x)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is not a
      variable, return [47mt[0m if it is a function call whose function
      symbol is a [47mlambda[0m expression, else return [47mnil[0m.

    * [47m(flambdap fn)[0m: For a [47m[pseudo-termp][0m [47m(fn arg1 ... argk)[0m, true when [47mfn[0m
      is a [47m[lambda][0m expression

    * [47m(flatten-ands-in-lit term)[0m: Returns a list of terms whose conjunction
      is equivalent to the given term (which satisfies
      [47m[pseudo-termp][0m), obtained by flattening its conjunctive
      structure.  For example, [47m(flatten-ands-in-lit '(if (if x y
      'nil) z 'nil))[0m is the list [47m(x y z)[0m.

    * [47m(fn-rune-nume fn nflg xflg wrld)[0m: For a function symbol [47mfn[0m, return
      either the [rune] (case [47mnflg[0m = [47mnil[0m) or nume (numeric
      representation of a rune) (case [47mnflg[0m = [47mt[0m) associated with
      either [47m(:DEFINITION fn)[0m (case [47mxflg[0m = [47mnil[0m) or
      [47m(:EXECUTABLE-COUNTERPART fn)[0m (case [47mxflg[0m = [47mt[0m).  If [47mfn[0m is a
      constrained function, return [47mnil[0m for all combinations of the
      flags.

    * [47m(fn-symb x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return its called function or
      [47mlambda[0m expression if [47mx[0m is a function call, otherwise return
      [47mnil[0m.  Also see [47mffn-symb[0m, above.

    * [47m(formals fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return its
      list of formal parameters.

    * [47m(formula name normalp w)[0m: For an event name or [rune], [47mname[0m, of
      [world] [47mw[0m, return the corresponding formula if any
      ([normalize]d iff [47mnormalp[0m is true), else [47mnil[0m.  See [formula].

    * [47m(fquotep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m that is not a variable, return
      true iff [47mx[0m is a quoted constant.

    * [47m(fsubcor-var vars terms form)[0m: This variant of [47msubcor-var[0m (described
      below) also substitutes, in the [47m[pseudo-termp][0m [47mform[0m, the
      variables in the list of [47m[symbolp][0ms [47mvars[0m with the corresponding
      elements in the list of [47m[pseudo-termp][0ms [47mterms[0m, but without
      performing any simplification.

    * [47m(function-symbolp sym w)[0m: True when the symbol [47msym[0m is a function
      symbol in the [world] [47mw[0m.

    * [47m(genvar pkg-witness prefix n avoid-lst)[0m: Generate a new variable
      name.

    * [47m(get-brr-local var state)[0m: The value of brr-local variable [47mvar[0m; this
      is the utility used by [brr@].

    * [47m(get-defun-event name w)[0m: For the given name of a defined function in
      the current ACL2 [world] [47mw[0m, return its [47m[defun][0m form.  Note that
      this applies to both [47m:[0m[47m[logic][0m-mode and [47m:[0m[47m[program][0m-mode
      functions, in spite of the name, ``logical'' (which is actually
      intended to distinguish from ``raw Lisp'').

    * [47m(get-event name w)[0m: For the given name of an event in the current
      ACL2 [world] [47mw[0m, return that event.  Typically there is only one
      such event, but for built-in functions the most recent event
      might be a variant of a [47m[verify-termination][0m event, so consider
      using [47mget-defun-event[0m for names of functions (see above).

    * [47m(get-skipped-proofs-p name w)[0m: For the given name of an event in the
      current ACL2 [world] [47mw[0m, return [47mt[0m if proofs were skipped when
      introducing that event, as with [47m[skip-proofs][0m or using
      [47m[set-ld-skip-proofsp][0m --- that is, with proofs skipped other
      than by the system (as with [47m[include-book][0m); else return [47mnil[0m.
      Exception: if [47mname[0m is a function symbol that is either built in
      or in [47m:[0m[47m[program][0m mode, return [47mnil[0m.

    * [47m(guard fn stobj-optp w)[0m: For a function symbol or [47mlambda[0m expression
      [47mfn[0m of [world] [47mw[0m, return its [guard]. Optimize the [stobj]
      recognizers away iff [47mstobj-optp[0m is true.

    * [47m(implicate t1 t2)[0m: For terms [47mt1[0m and [47mt2[0m, return a term that is
      propositionally equivalent to [47m(implies t1 t2)[0m.

    * [47m(io? token commentp shape vars body &key ...)[0m: This is a complex
      macro that may be most fully understood by reading the source
      code, including comments in its definition and examples of its
      use.  But the following example from the definition of source
      function [47mprint-failure1[0m may get the idea across.

          (io? summary nil state (channel)
               (fms *proof-failure-string* nil channel state nil))

      This is essentially just the [47mbody[0m argument, which here is the
      indicated [47m[fms][0m call, but where, going through the other
      arguments:

        * [47msummary[0m --- evaluation only takes place when [47msummary[0m output is
          enabled (see [set-inhibit-output-lst]);

        * [47mnil[0m --- don't enter a wormhole;

        * [47mstate[0m --- the body (which here is the [47mfms[0m call) returns a single
          [47mstate[0m value; and finally

        * [47mchannel[0m --- this is the list of free variables in the body (which
          here is the [47mfms[0m call).

    * [47m(known-package-alist state)[0m: Returns a list of package entries, as
      explained in the definition of [47mmake-package-entry[0m in ACL2
      sources, which is followed by simple accessor definitions (all
      in file [47maxioms.lisp[0m as of this writing).  This list includes
      entries for hidden packages (see [hidden-death-package]).  As a
      package is introduced, its package entry is pushed on the front
      of the existing known-package-alist.  Note that this list can
      be accessed directly from a [world], [47mw[0m, with: [47m(global-val
      'known-package-alist w)[0m.

    * [47m(lambda-applicationp x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return [47mt[0m if it is a
      function call whose function symbol is a [47mlambda[0m expression,
      else return [47mnil[0m.

    * [47m(lambda-body x)[0m: For a [47mlambda[0m expression [47mx[0m, return its body.

    * [47m(lambda-formals x)[0m: For a [47mlambda[0m expression [47mx[0m, return its formal
      parameters.

    * [47m(legal-constantp name)[0m: Returns [47mt[0m if [47mname[0m is a legal constant name,
      else [47mnil[0m.

    * [47m(legal-variablep name)[0m: Returns [47mt[0m if [47mname[0m is a legal variable name,
      else [47mnil[0m.  For example, [47mx[0m is a legal variable name but the
      following are not: [47m:abc[0m, [47mt[0m, [47mnil[0m, [47m&a[0m (a lambda keyword), [47m*c*[0m
      (syntax of a constant), and [47mpi[0m (a Common Lisp constant).

    * [47m(logicp fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return [47mt[0m when
      the [47msymbol-class[0m of [47mfn[0m in [47mw[0m is not [47m:program[0m, else [47mnil[0m.  (See
      [47msymbol-class[0m, below.)

    * [47m(make-lambda args body)[0m: Return the [47mlambda[0m expression with formal
      parameters [47margs[0m and body [47mbody[0m.

    * [47m(make-lambda-application formals body actuals)[0m: Return the [47mlambda[0m
      application that is essentially [47m((lambda formals body) .
      actuals)[0m.  However, extra formals and corresponding actuals are
      added when [47mbody[0m has free variables that do not belong to
      [47mformals[0m, because lambdas must be closed in ACL2.  A similar
      function is [47mmake-lambda-term[0m, but that one does not drop unused
      formals, while [47mmake-lambda-application[0m does drop them.

    * [47m(make-lambda-term formals actuals body)[0m: Return the [47mlambda[0m
      application that is essentially [47m((lambda formals body) .
      actuals)[0m.  However, extra formals and corresponding actuals are
      added when [47mbody[0m has free variables that do not belong to
      [47mformals[0m, because lambdas must be closed in ACL2.  A similar
      function is [47mmake-lambda-application[0m, but that one drops unused
      formals, while [47mmake-lambda-term[0m does not.

    * [47m(maybe-convert-to-mv uterm)[0m: Given the untranslated [term] [47muterm[0m,
      replace each of its top-level calls of [47m[list][0m by a call of [47m[mv][0m
      on the same arguments.

    * [47m(nvariablep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return true iff [47mx[0m is not a
      variable (i.e. it is a quoted constant or a function call).

    * [47m(partition-rest-and-keyword-args x keys)[0m: [47mx[0m should be a list of the
      form [47m(a1 ... an :key1 v1 ... :keyk vk)[0m, where no [47mai[0m is a
      keyword.  The result is [47m(mv erp rest alist)[0m, where [47merp[0m is
      non-[47mnil[0m if and only if the keyword section of [47mx[0m (that is,
      starting with [47m:key1[0m) is ill-formed, that is: some [47m:keyi[0m is not
      a keyword, [47m:keyi[0m and [47m:keyj[0m are the same for some distinct i and
      j, or some [47m:keyi[0m is not a member of [47mkeys[0m.  When [47merp[0m is [47mnil[0m,
      then [47mrest[0m is [47m(a1 ... an)[0m and alist is equivalent (as a mapping)
      to [47m((:key1 . v1) ... (:keyk . vk))[0m.

    * [47m(plist-worldp alist)[0m: Recognizer for when [47malist[0m is syntactically
      well-formed as an ACL2 logical [world], sometimes suitable for
      use in [guard]s.  Note: for a somewhat deeper check, see
      community book [47mbooks/system/pseudo-good-worldp.lisp[0m.

    * [47m(prettyify-clause cl let*-abstractionp wrld)[0m: Returns an untranslated
      (user-level) term that is equivalent to the [clause], [47mcl[0m.

    * [47m(programp fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return [47mt[0m when
      the [47msymbol-class[0m of [47mfn[0m in [47mw[0m is [47m:program[0m, else [47mnil[0m.  (See
      [47msymbol-class[0m, below.)

    * [47m(quotep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return true iff [47mx[0m is a quoted
      constant.

    * [47m(recursivep fn flg w)[0m: [47mFn[0m should be a [47m:[0m[47m[logic][0m-mode function symbol
      [47mfn[0m of the [world], [47mw[0m.  The result is the list of mutually
      recursive functions of which [47mfn[0m is a member.  The list is empty
      iff [47mfn[0m is not recursive.  The list contains just [47mfn[0m iff [47mfn[0m is
      singly recursive.  NOTE: [47mflg[0m should be [47mt[0m or [47mnil[0m.  If [47mflg[0m is
      [47mnil[0m, the result is based solely on the [47m[defun][0m form that
      introduced [47mfn[0m and is equal to [47m(getpropc fn 'recursivep nil w)[0m.
      If [47mflg[0m is [47mt[0m, then the most recent [definition] rule for [47mfn[0m with
      a non-[47mnil[0m value of [47m:install-body[0m --- which could be the
      original definition --- will cause [47mrecursivep[0m to return the
      [47m:clique[0m specified by that rule; see [rule-classes].

    * [47m(stobjp x known-stobjs w)[0m: Returns a non-[47mnil[0m value when [47mx[0m is to be
      treated as a [stobj] name, else [47mnil[0m.  Argument [47mknown-stobjs[0m is
      a list of all such names, or else [47mt[0m, standing for all stobj
      names in the [world], [47mw[0m.  If you want to know whether [47mx[0m has
      been defined as a stobj in [47mw[0m, use [47mknown-stobjs[0m = [47mt[0m.
      Technicality: if [47mknown-stobjs[0m is a list then it is allowed to
      contain any number of [47mnil[0m elements (as may be the case for the
      [47mstobjs-in[0m or [47mstobjs-out[0m of a symbol), which are ignored.

    * [47m(stobjs-in fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return the
      stobjs-in of [47mfn[0m, which is the result of modifying the list of
      formal parameters of [47mfn[0m by replacing with [47mnil[0m or [47m:df[0m each
      symbol that is not a [stobj] input --- generally [47mnil[0m, but [47m:df[0m
      if the formal parameter is declared to be a df (see [df]).
      Note that [47mfn[0m must be a symbol, not a [lambda] expression.

    * [47m(stobjs-out fn w)[0m: For a function symbol [47mfn[0m of [world] [47mw[0m, return the
      stobjs-out of [47mfn[0m, which is the list described below whose
      length [47mL[0m is the number of return values of [47mfn[0m --- that is, [47mL[0m is
      1 unless [47mfn[0m returns multiple values.  First suppose that [47mL[0m is
      1; say the stobjs-out list is [47m(s)[0m.  If [47mfn[0m returns a stobj then
      [47ms[0m is that stobj; if [47mfn[0m returns a [df] then [47ms[0m is [47m:df[0m; and
      otherwise [47ms[0m is [47mnil[0m.  Otherwise, [47mL[0m is greater than 1.  Then for
      each [47mi[0m less than [47mL[0m, if the [47mi[0mth return value is a stobj, then
      that is the [47mi[0mth element of the stobjs-out; otherwise the [47mi[0mth
      element of the stobjs-out is [47m:df[0m if calls of [47mfn[0m are df{i}
      expressions (see [df], else [47mnil[0m.  Note that [47mfn[0m must be a
      symbol, not a [lambda] expression.  Moreover [47mfn[0m must not be a
      member of the list value of the constant [47m*stobjs-out-invalid*[0m,
      i.e., the list [47m(if return-last do$ read-user-stobj-alist)[0m,
      since for these functions arbitrary multiple values may be
      returned.

    * [47m(subcor-var vars terms form)[0m: For a list [47mvars[0m of symbols, a list
      [47mterms[0m of [47m[pseudo-termp][0ms, and a [47m[pseudo-termp][0m [47mform[0m,
      substitute, in [47mform[0m, the [3mi[0m-th variable from [47mvars[0m with the [3mi[0m-th
      term from [47mterms[0m.  Note that [47mvars[0m and [47mterms[0m should have the same
      length.  (\"[47msubcor[0m\" stands for \"substitute corresponding
      elements\".)  Some simplification may be done; to avoid that,
      use [47mfsubcor-var[0m (``fast substitute corresponding elements''),
      described above.

    * [47m(sublis-fn-simple alist term)[0m, [47m(sublis-fn alist term bound-vars)[0m:
      Both of these apply the functional substitution, [47malist[0m, to the
      given term.  Thus in both cases, all keys of [47malist[0m are function
      symbols.  In the case of [47msublis-fn-simple[0m, each key of [47malist[0m is
      mapped to a function symbol; but for [47msublis-fn[0m, a key may
      instead be mapped to a legal [lambda] expression.  The other
      difference between the two functions is that for [47msublis-fn[0m, the
      formal [47mbound-vars[0m is a list of variables, generally [47mnil[0m at the
      top level.  For details see the Lisp comments in the ACL2
      sources for function [47msublis-fn-rec[0m (which is more general than
      either [47msublis-fn-simple[0m and [47msublis-fn[0m, and is called by both of
      them to do the real work).

    * [47m(sublis-fn-lst-simple alist termlist)[0m: Apply the given functional
      substitution, [47malist[0m, to each term in [47mtermlist[0m, essentially by
      applying [47msublis-fn-simple[0m to alist and each such term.  See the
      description of [47msublis-fn-simple[0m, above.

    * [47m(sublis-var alist form)[0m: Substitute [47malist[0m into the [term], [47mform[0m.
      [47mAlist[0m should be an alist that associates symbols with
      [47m[pseudo-termp][0ms, and [47mterm[0m should also satisfy [47mpseudo-termp[0m.
      Note that the substitution process evaluates calls of
      primitives on quoted constants, essentially using [47m[cons-term][0m.

    * [47m(subsequencep lst1 lst2)[0m: Determine whether the list lst1 is a
      subsequence of the list lst2, although not necessarily a proper
      subsequence.

    * [47m(subst-expr new old term)[0m: Substitute [47mnew[0m for [47mold[0m in [47mterm[0m; all are
      assumed to be [term]s.  This function provides a slightly
      optimized version of equivalent function [47m(subst-expr1 new old
      term)[0m.  Also, the former causes an explicit error if [47mold[0m is a
      quoted constant, and neither will search strictly inside a
      quoted subterm of [47mold[0m.  A more complex function (perhaps a bit
      less likely to stay forever unchanged), [47msubst-equiv-expr[0m, may
      be found in the source code; it can substitute one expression
      for another when the two are equivalent, but not necessarily
      equal.

    * [47m(subst-var new old term)[0m: Substitute [47mnew[0m for [47mold[0m in [47mterm[0m; all are
      assumed to be [term]s, but moreover, [47mold[0m is assumed to be a
      variable.

    * [47m(symbol-class name w)[0m: For a function symbol, [47mname[0m, of the ACL2
      [world] [47mw[0m, return [47m:program[0m if [47mname[0m is in [47m:[0m[47m[program][0m mode,
      [47m:common-lisp-compliant[0m if [47mname[0m is [guard]-verified, and
      otherwise, [47m:ideal[0m.  If [47mname[0m is the name of a theorem (more
      specifically, has a [47m'theorem[0m property; see [getprop]), return
      [47m:ideal[0m unless the theorem is guard-verified, in which case
      return [47m:common-lisp-compliant[0m.  Otherwise return [47m:program[0m.

    * [47m(symbol-doublet-listp lst)[0m: Returns [47mt[0m if [47mlst[0m is a list of two-element
      lists [47m(x1 x2)[0m where [47mx1[0m is a symbol, else [47mnil[0m.

    * [47m(termp x w)[0m: Is [47mx[0m a [term] in logical [world] [47mw[0m?

    * [47m(trans-eval form ctx state aok)[0m: Translate and then evaluate [47mform[0m.
      See [trans-eval] for discussion and related utilities.

    * [47mtranslate[0m, [47mtranslate1[0m, [47mtranslate11[0m, [47mtranslate-cmp[0m, [47mtranslate1-cmp[0m,
      and [47mtranslate1-cmp+[0m: Functions that translate user-level input
      to translated [term]s, as recognized by [47mtermp[0m.  Note that these
      functions perform macroexpansion, which checks [guard]s on
      [primitive]s; see [safe-mode].

    * [47m(translate-hints name-tree lst ctx wrld state)[0m: Translate a given
      list of user-level hints, [47mlst[0m, to internal form.  NOTE: this
      function returns an [error-triple], and it checks the syntax of
      [47mlst[0m.  Its documentation essentially resides in a comment in
      source function [47mtranslate-hints1[0m.

    * [47m(untranslate term iff-flg w)[0m: see [untranslate].

    * [47m(value x)[0m: This macro call expands to [47m(mv nil x state)[0m.  For related
      discussion, see [error-triple].

    * [47m(variablep x)[0m: For a [47m[pseudo-termp][0m [47mx[0m, return true iff [47mx[0m is a
      variable, i.e., a symbol.


Subtopics

  [Constraint-info]
      Obtaining the [constraint] on a function symbol

  [Get-event-data]
      Obtain data stored after at the conclusion of an event

  [Saving-event-data]
      Save data stored for subsidiary [events]

  [Trans-eval]
      Evaluate a form

  [Untranslate]
      Show a user-level representation of a term")
 (TABLE (EVENTS)
  "User-managed tables

    Examples:
    (table tests 1 '(...))                ; set contents of tests[1] to '(...)
    (table tests 25)                      ; get contents of tests[25]
    (table tests)                         ; return table tests as an alist
    (table tests nil nil :clear)          ; clear table tests
    (table tests nil '((foo . 7)) :clear) ; set table tests to ((foo . 7))
    (table tests nil nil :guard)          ; fetch the table guard
    (table tests nil nil :guard term)     ; set the table guard

    General Form:
    (table table-name key-term value-term op term)

  where [47mtable-name[0m is a symbol that is the name of a (possibly new)
  table; [47mkey-term[0m and [47mvalue-term[0m, if present, are arbitrary terms
  involving (at most) the variables [47mWORLD[0m and [47mENS[0m; [47mop[0m, if present, is
  one of the table operations below; and [47mterm[0m, if present, is a term.
  [47mTable[0m returns an ACL2 [error-triple].  The effect of [47mtable[0m on
  [47m[state][0m depends on [47mop[0m and how many arguments are presented.  Some
  invocations actually have no effect on the ACL2 [world] and hence
  an invocation of [47mtable[0m is not always an ``event''.  We explain
  below, after giving some background information.

  [31;1mImportant Note:[0m The [47mtable[0m forms above are calls of a macro that
  expands to involve the special variable [47m[state][0m.  This will prevent
  you from accessing a table from within a hint or theory where you
  do not have the [47m[state][0m variable.  However, the form

    (table-alist 'tests world)

  returns the alist representation of the table named [47mtests[0m in the
  given [47m[world][0m.  Often you can provide a suitable expression for
  [47mworld[0m, for example, [47m(w state)[0m.

  The ACL2 system provides ``tables'' by which the user can associate
  one object with another.  Tables are in essence just conventional
  association lists --- lists of pairs --- but the ACL2 environment
  provides a means of storing these lists in the ``ACL2 world'' of
  the current [47m[state][0m.  The ACL2 user could accomplish the same ends
  by using ACL2 ``global variables''; however, limitations on global
  variable names are imposed to ensure ACL2's soundness.  Some
  features of the system use tables, and the user is invited to make
  free use of tables.  By convention, no user-defined table is
  important to ACL2's soundness.  Because tables are stored in the
  ACL2 [world] they are restored by [47m[include-book][0m and undone by
  [47m:[0m[47m[ubt][0m.  Many users of Nqthm requested a facility by which user
  data could be saved in Nqthm ``lib files'' and tables are ACL2's
  answer to that request.

  Abstractly, each table is an association list mapping ``keys'' to
  ``values.'' In addition, each table has a ``[47m:guard[0m,'' which is a
  term that must be true of any key and value used.  By setting the
  [47m:guard[0m on a table you may enforce an invariant on the objects in
  the table, e.g., that all keys are positive integers and all values
  are symbols.  Note that attachments are allowed when evaluating a
  table guard (see [defattach]).  Each table has a ``name,'' which
  must be a symbol.  Given a table name, the following operations can
  be performed on the table.

  [47m:put[0m --- associate a value with a key (possibly changing the value
  currently associated with that key).

  [47m:get[0m --- retrieve the value associated with a key (or nil if no value
  has been associated with that key).

  [47m:alist[0m --- return an alist showing all keys and non-nil values in the
  table.

  [47m:clear[0m --- clear the table (so that every value is nil), or if val is
  supplied then set table to that value (which must be an alist).

  [47m:guard[0m --- fetch or set the [47m:guard[0m of the table.  See
  [set-table-guard] for a convenient way to set a table's [47m:guard[0m to
  produce user-friendly error messages.

  When the operations above suggest that the table or its [47m:guard[0m are
  modified, what is actually meant is that the current [state] is
  redefined so that in it, the affected table name has the
  appropriate properties.  In such cases, the [47mtable[0m form is an event
  (see [events]).  In the [47m:put[0m case, if the key is already in the
  table and associated with the proposed value, then the [47mtable[0m event
  is redundant (see [redundant-events]).

  [47mTable[0m forms are commonly typed by the user while interacting with the
  system.  [47m:Put[0m and [47m:get[0m forms are especially common.  Therefore, we
  have adopted a positional syntax that is intended to be convenient
  for most applications.  Essentially, some operations admit a
  ``short form'' of invocation.

    (table name key-term value-term :put)   ; long form
    (table name key-term value-term)        ; short form

  evaluates the key- and value-terms, obtaining two objects that we
  call [47mkey[0m and [47mvalue[0m, checks that the [47mkey[0m and [47mvalue[0m satisfy the
  [47m:guard[0m on the named table and then ``modifies'' the named table so
  that the value associated with [47mkey[0m is [47mvalue[0m.  When used like this,
  [47mtable[0m is actually an event in the sense that it changes the ACL2
  [world].  In general, the forms that are evaluated to obtain the
  [47mkey[0m and [47mvalue[0m may involve two variables: [47mWORLD[0m, which is bound to
  the then-current [world]; and [47mENS[0m, which is bound to the enabled
  structure representing the current theory.  (The enabled structure
  is passed as a formal parameter to many built-in functions; for
  example, see [system-utilities] for a description of built-in
  utilities [47menabled-numep[0m and [47menabled-runep[0m.)  However, in the
  special case that the table in question is named
  [47m[ACL2-defaults-table][0m, the [47mkey[0m and [47mvalue[0m terms may not contain any
  variables.  Essentially, the keys and values used in [events]
  setting the [47m[ACL2-defaults-table][0m must be explicitly given
  constants.  See [ACL2-defaults-table].

    (table name key-term nil :get)          ; long form
    (table name key-term)                   ; short form

  evaluates the key-term (see note below), obtaining an object, [47mkey[0m,
  and returns the value associated with [47mkey[0m in the named table (or,
  [47mnil[0m if there is no value associated with [47mkey[0m).  When used like
  this, [47mtable[0m is not an event; the value is simply returned.

    (table name nil nil :alist)             ; long form
    (table name)                            ; short form

  returns an alist representing the named table; for every key in the
  table with a non-[47mnil[0m associated value, the alist pairs the key and
  its value.  The order in which the keys are presented is
  unspecified.  When used like this, [47mtable[0m is not an event; the alist
  is simply returned.

    (table name nil val :clear)

  sets the named table to the alist [47mval[0m, making the checks that [47m:put[0m
  makes for each key and value of [47mval[0m.  When used like this, [47mtable[0m is
  an event because it changes the ACL2 [world].

    (table name nil nil :guard)

  returns the translated form of the guard of the named table.

    (table name nil nil :guard term)

  This event sets the [47m:guard[0m of the named table to [47mterm[0m, provided the
  following requirements are met.  The named table must be empty and
  it must not have been assigned a [47m:guard[0m yet.  [47mTerm[0m (which is not
  evaluated) should be a term that mentions at most the variables
  [47mKEY[0m, [47mVAL[0m, [47mWORLD[0m, [47mENS[0m, and [47mSTATE[0m.  In the common case [47mterm[0m will
  evaluate to a single value, but it can return two values as
  discussed later below; either way, it must not return [47mSTATE[0m.

  Whenever a subsequent [47m:put[0m occurs, [47mterm[0m will be evaluated with [47mKEY[0m
  bound to the key argument of the [47m:put[0m, [47mVAL[0m bound to the [47mval[0m
  argument of the [47m:put[0m, [47mWORLD[0m bound to the then current [world], [47mENS[0m
  bound to the enabled structure representing the current theory, and
  [47mSTATE[0m bound to the ACL2 [state].  The term is evaluated.  An error
  will be caused by the [47m:put[0m if the result of the evaluation is [47mnil[0m
  when a single value is returned; what if two values are returned?

  If the term returns multiple values [47m(mv okp msg)[0m, then an error will
  be caused if [47mokp[0m is [47mnil[0m.  In that case, if [47mmsg[0m is also [47mnil[0m then a
  generic error message is printed about the illegal key/value pair,
  just as in the single-value return case.  Otherwise [47mmsg[0m should be a
  [47m[msgp][0m --- a string or a cons suitable for printing with the [47m[fmt][0m
  directive, [47m~@[0m.  In that case, [47mmsg[0m is printed (using [47m[fmt][0m [47m~@[0m)
  instead of the generic error message.  Here is a simple example
  adapted from former code in the ACL2 sources.

    (defun my-table-guard (fn val wrld)
      (let ((msg0 ; nil if fn/val is OK as a key/value pair, else a msg
             (my-table-guard-msg fn val wrld)))
        (cond
         (msg0 (mv nil
                   (msg
                    \"Illegal my-table key and value (see :DOC ~
                     memoize-partial):~|key = ~y0value  = ~y1Reason:~%~@2~|~%\"
                    fn val msg0)))
         (t (mv t nil)))))

    (table my-table nil nil
           :guard
           (my-table-guard key val world))

  Note that it is not allowed to change the [47m:guard[0m on a table once it
  has been explicitly set.  Before the [47m:guard[0m is explicitly set, it
  is effectively just [47mt[0m.  After it is set it can be changed only by
  undoing the event that set it.  The purpose of this restriction is
  to prevent the user from changing the [47m:guards[0m on tables provided by
  other people or the system.

  The intuition behind the [47m:guard[0m mechanism on tables is to enforce
  invariants on the keys and values in a table, so that the values,
  say, can be used without run-time checking.  But if the [47m:guard[0m of a
  table is sensitive to the ACL2 [world], it may be possible to cause
  some value in the table to cease satisfying the [47m:guard[0m without
  doing any operations on the table.  Consider for example the [47m:guard[0m
  ``no value in this table is the name of an event.'' As described,
  that is enforced each time a value is stored.  Thus, [47m'bang[0m can be
  [47m:put[0m in the table provided there is no event named [47mbang[0m.  But once
  it is in the table, there is nothing to prevent the user from
  defining [47mbang[0m as a function, causing the table to contain a value
  that could not be [47m:put[0m there anymore.  Observe that not all
  state-sensitive [47m:guard[0ms suffer this problem.  The [47m:guard[0m ``every
  value is an event name'' remains invariant, courtesy of the fact
  that undoing back through an event name in the table would
  necessarily undo the [47m:put[0m of the name into the table.

  [47mTable[0m was designed primarily for convenient top-level use.  Tables
  are not especially efficient.  Each table is represented by an
  alist stored on the property list of the table name.  [47m:Get[0m is just
  a [47mgetprop[0m and [47m[assoc-equal][0m.  [47m:Put[0m does a [47mgetprop[0m to the get the
  table alist, a [47mput-assoc-equal[0m to record the new association, and a
  [47mputprop[0m to store the new table alist --- plus the overhead
  associated with [47m:guard[0ms and undoable [events], and checking (for
  redundancy) if the key is already bound to its proposed value.
  Note that there are never duplicate keys in the resulting [47malist[0m; in
  particular, when the operation [47m:clear[0m is used to install new [47malist[0m,
  duplicate keys are removed from that alist.

  A table name may be any symbol whatsoever.  Symbols already in use as
  function or theorem names, for example, may be used as table names.
  Symbols in use only as table names may be defined with [47m[defun][0m,
  etc.  Because there are no restrictions on the user's choice of
  table names, table names are not included among the logical names.
  Thus, [47m:pe name[0m will never display a table event (for a logical name
  other than [47m:here[0m).  Either [47m:pe name[0m will display a ``normal'' event
  such as [47m(defun name ...)[0m or [47m(defthm name ...)[0m or else [47m:pe name[0m will
  cause an error indicating that [47mname[0m is not a logical name.  This
  happens even if [47mname[0m is in use as a table name.


Subtopics

  [ACL2-defaults-table]
      A [table] specifying certain defaults, e.g., the default
      [defun-mode]

  [Set-table-guard]
      Set the [47m:guard[0m for a [table]

  [Using-tables-efficiently]
      Notes on how to use tables efficiently")
 (TABLE-ALIST (POINTERS) "See [table].")
 (TAG-TREE (POINTERS) "See [ttree].")
 (TAIL-BITING
  (DEBUGGING)
  "Rewriting a true term to [47mNIL[0m

  On rare occasions, a true term can [rewrite] to [47mNIL[0m.  Such
  ``tail-biting'' behavior can make the prover fail to prove a
  theorem but will not make it ``prove'' a non-theorem.  This topic
  explains this behavior, first with one paragraph explaining it in
  high-level terms and then, for those interested in details, with a
  specific example.  That example includes discussion that exposes
  more of the ACL2 implementation than is usually exposed in
  documentation topics, so we expect that most readers will skip it.

  When backchaining to rewrite a hypothesis [47mH[0m of a [rewrite] or
  [linear] rule, ACL2 uses the following heuristic: assume that [47mH[0m is
  false when trying to prove it.  That is sound: proposition [47mP[0m is
  equivalent to proposition [47m(implies (not P) P)[0m.  We do not discuss
  why ACL2 does this or why it rarely results in so-called
  ``tail-biting'': rewriting the hypothesis to [47mNIL[0m by using the fact
  that it has been assumed false.  But that can happen on rare
  occasions.  So if you see a term rewrite to [47mNIL[0m when you know it to
  be true, consider whether this is because it was encountered
  earlier during the backchaining process, when it was assumed false.

  ===== Maybe stop here (lower-level explanation follows)! =====

  The example below shows how tail-biting can happen.  As noted above,
  beware: this explanation is closer to the implementation than is
  found in most of the ACL2 documentation.  We give the example in
  full first, and then we conclude with a more concise summary.  Key
  to this explanation is the notion of the [3mancestors-stack[0m, which is
  a data structure kept by the rewriter as it backchains through
  hypotheses, to record the negation of each hypothesis encountered
  during backchaining.

  We begin with a very simple definition and theorem.  Note that we
  treat [47m[member][0m below as [47m[member-equal][0m, to simplify the exposition.

    (defun copylist (x)
      (if (endp x)
          nil
          (cons (car x) (copylist (cdr x)))))

    (defthm key-rule
      (implies
       (not (member a lst)) ; hypothesis later denoted as ``H''
       (not (member a (copylist lst)))))

  The following ``weird'' rule backchains from [47m(member a (cdr lst))[0m to
  [47m(member a lst)[0m, sort of un-opening [47mmember[0m.

    (defthm weird
      (implies (and (consp lst)
                    (member a lst)
                    (not (equal a (car lst))))
               (member a (cdr lst))))

  Now here is our main theorem.  It ought to follow by simplification
  from [47mkey-rule[0m above, if we can just establish the hypothesis [47mH[0m of
  [47mkey-rule[0m from the hypotheses of [47mmain[0m.  The instance of [47mH[0m is [47m(not
  (member aaa (cdr xxx)))[0m.  The rewriter cannot establish this
  because it requires a proof by induction.  So the proof is bound to
  fail here.

    (defthm main
      (implies (and (consp (cdr xxx))
                    (nat-listp xxx)
                    (symbolp aaa))
               (not (member aaa (copylist (cdr xxx)))))
      :hints ((\"Goal\"
               :do-not-induct t
               :do-not '(eliminate-destructors))))

  So we decide to monitor key-rule and see why it failed:

    (monitor! '(:rewrite key-rule) t)

    (defthm main ...) ; exactly as above

    :eval
    :a!

  And we see that [47m[brr][0m reports that ``[47m:HYP 1 rewrote to 'NIL[0m'', i.e.,
  that the relevant instance of [47mH[0m, [47m(not (member aaa (cdr xxx)))[0m,
  rewrote to [47mNIL[0m.  This seems to suggest [47maaa[0m is in [47m(cdr xxx)[0m.

  But we know it can't be!  The hypotheses of main say [47maaa[0m is a symbol
  and [47mxxx[0m is a list of natural numbers.  So [47maaa[0m can't be in [47m(cdr
  xxx)[0m. We can prove it:

    (defthm hyps-of-main-imply-hyp-1
      (implies (and (consp (cdr xxx))
                    (nat-listp xxx)
                    (symbolp aaa))
               (not (member aaa (cdr xxx)))))

  And using that rule we can now prove [47mmain[0m:

    (defthm main
      (implies (and (consp (cdr xxx))
                    (nat-listp xxx)
                    (symbolp aaa))
               (not (member aaa (copylist (cdr xxx)))))
      :hints ((\"Goal\"
               :do-not-induct t
               :do-not '(eliminate-destructors))))

  So the question is: why did the hypothesis of [47mkey-rule[0m rewrite to
  [47mNIL[0m?

  Let's undo back through [47mhyps-of-main-imply-hyp-1[0m and monitor
  [47mkey-rule[0m, [47mweird[0m, and the definition of [47m[member-equal][0m, and also
  [trace] system function [47mancestors-check-builtin[0m, which queries the
  ancestor-stack, and then repeat the doomed proof attempt for [47mmain[0m.

    (ubt! 'hyps-of-main-imply-hyp-1)
    (monitor '(:rewrite key-rule) ''(:go))
    (monitor '(:rewrite weird) ''(:go))
    (monitor '(:definition member-equal) ''(:go))
    (trace$ ancestors-check-builtin)

    (defthm main
      (implies (and (consp (cdr xxx))
                    (nat-listp xxx)
                    (symbolp aaa))
               (not (member aaa (copylist (cdr xxx)))))
      :hints ((\"Goal\"
               :do-not-induct t
               :do-not '(eliminate-destructors))))

  Here is the series of breaks on (:REWRITE WEIRD), except that the
  second break is elided because you will see at the subsequent ``2x
  (:REWRITE WEIRD) failed...'' that everything that goes on there is
  irrelevant.  Also deleted are some irrelevant calls of
  [47mancestors-check-builtin[0m, but the important one remains.

    (1 Breaking (:REWRITE KEY-RULE) on (MEMBER-EQUAL AAA (COPYLIST (CDR XXX))):
    1 ACL2 >:GO

    (2 Breaking (:REWRITE WEIRD) on (MEMBER-EQUAL AAA (CDR XXX)):
    ...
    2x (:REWRITE WEIRD) failed because :HYP 2 rewrote to
    (MEMBER-EQUAL AAA (CDR XXX)).
    2)

    (2 Breaking (:DEFINITION MEMBER-EQUAL) on (MEMBER-EQUAL AAA (CDR XXX)):
    2 ACL2 >:GO

    (3 Breaking (:REWRITE WEIRD) on (MEMBER-EQUAL AAA (CDR (CDR XXX))):
    3 ACL2 >:GO
    1> (ANCESTORS-CHECK-BUILTIN (MEMBER-EQUAL AAA (CDR XXX))
                                (((MEMBER-EQUAL AAA (CDR XXX))
                                  (MEMBER-EQUAL AAA (CDR XXX))
                                  2 2 0 ((:REWRITE KEY-RULE))
                                  . 1))
                                ((:REWRITE WEIRD)))
    <1 (ANCESTORS-CHECK-BUILTIN T T)

    3 (:REWRITE WEIRD) produced 'T.
    3)

    2 (:DEFINITION MEMBER-EQUAL) produced 'T.
    2)

    1x (:REWRITE KEY-RULE) failed because :HYP 1 rewrote to 'NIL.  (See
    :DOC tail-biting if this surprises you.)
    1)

  So we've entered the break on [47mkey-rule[0m and backchained to prove its
  hypothesis, [47m(not (member aaa (cdr xxx)))[0m.  We thus assume the
  negation, [47m(member aaa (cdr xxx))[0m, on the ancestors stack and then
  open [47m(member aaa (cdr xxx))[0m with the definition.  That results in a
  call of [47m(member aaa (cdr (cdr xxx)))[0m and we backchain through [47mweird[0m
  to [47m(member aaa (cdr xxx))[0m and find it assumed true (on the
  ancestors-stack).  So [47mweird[0m rewrites [47m(member-aaa (cdr (cdr xxx)))[0m
  to [47mT[0m (propositionally) and so [47mmember-equal[0m returns [47mT[0m, so [47mH[0m rewrites
  to [47mNIL[0m.

  This is not unsound; it is just tail biting.  Here is a summary of
  what has happened.

  1. Attempt to rewrite [47m(not (member aaa (copylist (cdr xxx))))[0m to [47mT[0m.

  2. Attempt to rewrite [47m(member aaa (copylist (cdr xxx)))[0m to [47mNIL[0m.

  3. Backchain with [47mkey-rule[0m to [47m(not (member aaa (cdr xxx)))[0m.

  4. Assume [47m(member aaa (cdr xxx))[0m by putting it on the
  ancestors-stack.  This is sound because we are trying to prove [47m(not
  (member aaa (cdr xxx)))[0m, and it is sound to assume [47m(not P)[0m when
  proving [47mP[0m.

  5. Expand [47m(member aaa (cdr xxx))[0m, given [47m(consp (cdr xxx))[0m, to [47m(or
  (equal aaa (cadr xxx)) (member aaa (cddr xxx)))[0m

  6. Rewrite [47m(member aaa (cddr xxx))[0m) using [47mweird[0m.

  7. Backchain with weird on (member aaa (cddr xxx)) and relieve its
  hypotheses under the substitution [47ma := aaa[0m, [47mlst := (cdr xxx)[0m.

      * a. [47m(consp (cdr xxx))[0m is true (hypothesis of [47mmain[0m).

      * b. [47m(member aaa (cdr xxx))[0m is true (TAIL BITING!).

      * c. [47m(not (equal aaa (car (cdr xxx))))[0m is true, presumably from
        expansion of hypotheses of [47mmain[0m.

  8. So [47mweird[0m applies, hence the following are true:

      * From 6. [47m(member aaa (cddr xxx))[0m

      * From 5. [47m(member aaa (cdr xxx))[0m

  So 3 fails because [47m(not (member aaa (cdr xxx)))[0m rewrites to [47mNIL[0m.")
 (TAKE
  (LISTS ACL2-BUILT-INS)
  "Initial segment (first n elements) of a list

  For any natural number [47mn[0m not exceeding the length of [47ml[0m, [47m(take n l)[0m
  collects the first [47mn[0m elements of the list [47ml[0m.

  The following is a theorem:

    (equal (length (take n l)) (nfix n))

  If [47mn[0m is an integer greater than the length of [47ml[0m, then [47mtake[0m pads the
  list with the appropriate number of [47mnil[0m elements.  Thus, the
  following is also a theorem (though it takes some effort, including
  lemmas, to get ACL2 to prove it).

    (implies (and (integerp n)
                  (true-listp l)
                  (<= (length l) n))
             (equal (take n l)
                    (append l (make-list (- n (length l))))))

  For related functions, see [nthcdr] and see [butlast].

  The [guard] for [47m(take n l)[0m is that [47mn[0m is a nonnegative integer and [47ml[0m
  is a true list.

  [31;1mFunction: [0m<first-n-ac>

    (defun first-n-ac (i l ac)
      (declare (type (integer 0 *) i)
               (xargs :guard (and (true-listp l) (true-listp ac))))
      (cond ((zp i) (revappend ac nil))
            (t (first-n-ac (1- i)
                           (cdr l)
                           (cons (car l) ac)))))

  [31;1mFunction: [0m<take>

    (defun take (n l)
      (declare (xargs :guard (and (integerp n)
                                  (not (< n 0))
                                  (true-listp l))))
      (mbe :logic
           (if (zp n)
               nil
             (cons (car l) (take (1- n) (cdr l))))
           :exec (first-n-ac n l nil)))")
 (TALKS
  (ACL2-TUTORIAL)
  "Some talks about ACL2

  The list below contains links to talks about ACL2.  This list may
  grow over time.  Please email the [ACL2-help] mailing list if you
  find a broken link or if you care to contribute another link to a
  talk (or simply make the changes yourself if you have permission to
  do so on GitHub).

    * Links to several introductory/overview talks on ACL2 may be found on
      the {page of talks by Matt Kaufmann |
      http://www.cs.utexas.edu/users/kaufmann/selected-presentations.html},
      including {a general introductory talk on ACL2 by Matt Kaufmann
      and J Moore |
      http://www.cs.utexas.edu/users/kaufmann/visions-moore-kaufmann.pdf}
      from 2006.

    * Several introductory/overview talks on ACL2 by J Moore:

        * {Two talks given July 6 and 7, 2017 |
          http://www.cs.utexas.edu/users/moore/acl2/talks/big-proof-talks/},
          at the {Big Proof workshop |
          https://www.newton.ac.uk/event/bpr} at the Isaac Newton
          Institute for Mathematical Sciences in Cambridge, England.
          The first talk focuses on the role of mechanized
          proof,specifically ACL2, to verify hardware and software of
          interest to industry.  The second talk touches upon how the
          ACL2 prover works, how the user directs it, and some of the
          features of particular importance to its industrial
          applications.

        * {Industrial Hardware and Software Verification with ACL2 |
          http://www.cs.utexas.edu/users/moore/acl2/talks/royal-society/talk.pdf},
          presented at the Royal Society, London, in April, 2016
          (co-authored with Warren A. Hunt, Jr., Matt Kaufmann, and
          Anna Slobodova).

        * This page for {Mechanized Operational Semantics |
          http://www.cs.utexas.edu/users/moore/publications/talks/marktoberdorf-08/index.html}
          contains links not only to talks given at the Marktoberdorf
          Summer School (Germany, August, 2008) but also to
          supplemental materials.

    * The ``Talks'' section of {Warren Hunt's home page |
      http://www.cs.utexas.edu/users/hunt/index.html} has an
      annotated list of links to several talks about the use of ACL2
      for hardware specification and verification.

  Note that many talks are also available from the {ACL2 Workshops |
  http://www.cs.utexas.edu/users/moore/acl2/workshops.html} pages and
  on the {University of Texas ACL2 Seminar page |
  http://www.cs.utexas.edu/users/moore/acl2/seminar/}.")
 (TAME
  (APPLY$)
  "Definitions of the various notions of tameness

  The adjective ``tame'' can be applied to four different kinds of
  objects, [47mLAMBDA[0m objects, function symbols, expressions, and lists
  of expressions.  Formally, these notions are defined mutually
  recursively as the macro [47mtamep-lambdap[0m and the [47m:logic[0m mode
  functions named [47mtamep-functionp[0m, [47mtamep[0m, and [47msuitably-tamep-listp[0m,
  respectively.  We exhibit the formal definitions at the end of this
  documentation.


Definitions

    * [31;1mtame [47mLAMBDA[0m[31;1m object[0m aka [47mtamep-lambdap[0m: An object is a tame [47mLAMBDA[0m
      object if is of the form [47m(LAMBDA vars body)[0m or [47m(LAMBDA vars dcl
      body)[0m where [47mvars[0m is a list of symbols and [47mbody[0m is a tame
      expression.  Formally, an object [47mx[0m is a tame [47mLAMBDA[0m object iff
      [47m(tamep-lambdap x)[0m.  [47mTamep-lambdap[0m is actually a macro.

    * [31;1mtame function[0m aka [47mtamep-functionp[0m: An object is a [3mtame function[0m iff
      it is either (a) a badged symbol and ilks is [47mT[0m, or (b) a tame
      [47mLAMBDA[0m object (see above).  Formally, an object [47mx[0m is a tame
      function iff [47m(tamep-functionp x)[0m.

    * [31;1mtame expression[0m aka [47mtamep[0m: An object is a [3mtame expression[0m iff it is a
      symbol, a quoted constant, the call of an badged function
      symbol on the correct number of suitably tame expressions with
      respect to the ilks of the function symbol, or the call of a
      tame [47mLAMBDA[0m expression on the correct number of tame
      expressions.  Formally, an object [47mx[0m is a tame expression iff
      [47m(tamep x)[0m.  Note that tameness implies every function symbol in
      the expression is badged but [3mnot necessarily warranted[0m.

    * [31;1msuitably tame with (respect to arity and ilks)[0m aka
      [47msuitably-tamep-listp[0m: A list of objects [47mx[0m is [3msuitably tame[0m with
      respect to an arity [47mn[0m and a list of [47milks[0m iff [47mx[0m is a true list
      of length [47mn[0m, and when an ilk is [47m:FN[0m the corresponding object is
      a [3mquoted[0m tame function, when an ilk is [47m:EXPR[0m the object is a
      [3mquoted[0m tame expression, and when an ilk is [47mNIL[0m the object is a
      tame expression.  Formally, an object [47mx[0m is suitably tame with
      respect to [47mn[0m and [47milks[0m iff [47m(suitably-tamep-listp n ilks x)[0m.
      Note in particular our use of the word ``quoted'' above.  We
      illustrate this in the example below.

  Note that the various notions of tameness make no mention of whether
  the function symbols involved are in [47m:program[0m or [47m:logic[0m mode.  The
  function symbols must have badges but need not have warrants.

  Intuitively, a tame expression can be built out of functions that are
  not themselves tame, e.g., scions, by making sure that every [47m:FN[0m
  slot is occupied by a quoted tame function.  Put another way, if we
  were to trace the calls of [47mapply$[0m while evaluating a tame
  expression every branch eventually bottoms out on a call of a
  primitive.  This is illustrated below.


Examples

  We assume the following events have been processed.

    (include-book \"projects/apply/top\" :dir :system)

    (defun$ sq (x) (* x x))

    (defun$ foldr (lst fn init)
      (if (endp lst)
          init
          (apply$ fn
                  (list (car lst)
                        (foldr (cdr lst) fn init)))))

  [47mSq[0m and [47mfoldr[0m above are defined as [47m:logic[0m mode functions and are
  badged and warranted (note the use of [47mdefun$[0m).  But for our
  purposes they could have been introduced by [47mdefun[0m in [47m:program[0m mode
  and then badged with two calls of [47mdefbadge[0m.

  As a result, we see the following badges:

    symbol           badge

    CONS    (APPLY$-BADGE 2 1 . T)  ; . T means all args ordinary
    SQ      (APPLY$-BADGE 1 1 . T)  ; . T means all args ordinary
    FOLDR   (APPLY$-BADGE 1 1 NIL :FN NIL)

  Consider the following expression.

    (foldr lst (lambda$ (x y) (foldr y 'cons (list (sq x)))) nil)

  Forgetting about tameness for a moment, what does this term compute?
  Study the definition of [47mfoldr[0m if you're not familiar with it and
  work it out!  Answer: It collects, in reverse order, the squares of
  the elements of [47mlst[0m.  E.g., if [47mlst[0m is [47m(1 2 3 4)[0m the value of the
  [47mfoldr[0m expression above is [47m(16 9 4 1)[0m.

  But we are interested in whether it is tame.  Tameness is a concept
  applied to objects representing formal (fully translated) terms (or
  components of terms in the case of ``tame functions,'' ``tame
  lambdas,'' etc.).  Saying ``[3mx[0m is a tame expression'' is just a
  colloquial way of saying ``[47m(tamep [0m[3mx[0m[47m)[0m = [47mt[0m.  So we can evaluate this
  term in the top-level ACL2 loop,

    (tamep '(foldr lst (lambda$ (x y) (foldr y 'cons (list (sq x)))) nil))

  and the result is [47mnil[0m because [47mlambda$[0m is not a ``badged function
  symbol.'' In fact, [47mlambda$[0m is not a function symbol.  It is a
  macro.  We're really interested in the formal translation of the
  [47mfoldr[0m expression.  One way to understand the situation is that
  [47mtamep[0m does not expand macros.

  The translation of the above term is

    (FOLDR LST
           '(LAMBDA (X Y)
                    (DECLARE (IGNORABLE X Y))
                    (RETURN-LAST 'PROGN
                                 '(LAMBDA$ (X Y)
                                           (FOLDR Y 'CONS (LIST (SQ X))))
                                 (FOLDR Y 'CONS (CONS (SQ X) 'NIL))))
           'NIL)

  The [47mRETURN-LAST[0m subterm is a marker that records the original
  user-supplied [47mlambda$[0m expression, which is needed during
  compilation and execution in raw Lisp.  But the value of that
  [47mRETURN-LAST[0m is the expected [47mFOLDR[0m expression in its last argument.
  To simplify our discussion of tameness let's determine whether the
  following equivalent term is tame.

    (FOLDR LST
           '(LAMBDA (X Y)
              (FOLDR Y
                     'CONS
                     (CONS (SQ X) 'NIL)))
           'NIL)

  The answer is yes, it is a tame expression.  In particular

    (tamep '(FOLDR LST
                   '(LAMBDA (X Y)
                      (FOLDR Y
                             'CONS
                             (CONS (SQ X) 'NIL)))
                   'NIL))
    = T

  By the way, [47mtamep[0m answers the same way on the quotation of the actual
  translation of the [47mfoldr[0m term.

  We explain below how [47mtamep[0m computes this result.  But before we dive
  into details consider what this example illustrates.  [47mFOLDR[0m is [3mnot
  a tame function[0m according to the definitions above. But it can be
  used in the construction of tame expressions provided, mainly, that
  its second argument is a quoted tame function.  Indeed, the example
  illustrates that we can even call [47mFOLDR[0m within the [47mLAMBDA[0m
  expression passed to another [47mFOLDR[0m and still have a tame
  expression.

  If we were to [47m[trace$][0m the functions [47mtamep[0m, [47mtamep-functionp[0m, and
  [47msuitably-tamep-listp[0m, and then call [47mtamep[0m on the [47mFOLDR[0m term above
  we would see a tree of calls of the various tameness notions.  Here
  are selected calls from that tree.  All of the calls return [47mT[0m.  We
  discuss each of these calls below.

    (tamep '(CONS (SQ X) 'NIL))                                    ; [1]

    (suitably-tamep-listp 3                                        ; [2]
                          '(NIL :FN NIL)
                          '(Y 'CONS (CONS (SQ X) 'NIL)))

    (tamep '(FOLDR Y 'CONS (CONS (SQ X) 'NIL)))                    ; [3]

    (tamep-functionp '(LAMBDA (X Y)                                ; [4]
                              (FOLDR Y 'CONS (CONS (SQ X) 'NIL))))

    (tamep '(FOLDR LST                                             ; [5]
                   '(LAMBDA (X Y)
                            (FOLDR Y 'CONS (CONS (SQ X) 'NIL)))
                   'NIL))

  [47m[1][0m: The object here, [47m(CONS (SQ X) 'NIL)[0m, is tame because both [47mCONS[0m
  and [47mSQ[0m are tame functions and they are applied to the correct
  number of tame expressions.

  [47m[2][0m: The list of objects here, [47m(Y 'CONS (CONS (SQ X) 'NIL))[0m is a
  suitably tame list of length [47m3[0m with ilks [47mNIL[0m, [47m:FN[0m, and [47mNIL[0m because
  [47mY[0m and [47m'NIL[0m are both tame and [47m'CONS[0m is a [3mquoted[0m tame function, [47mCONS[0m.

  [47m[3][0m: The object here is tame because [47mFOLDR[0m is a badged function of
  arity 3 and its actuals are suitably tame with respect to its arity
  and ilks as shown by example [47m[2][0m.

  [47m[4][0m: The [47mLAMBDA[0m object here is a tame function because it is of the
  form [47m(LAMBDA vars body)[0m, where [47mvars[0m is the list of symbols [47m(X Y)[0m
  and body is the tame object shown in example [47m[4][0m.

  [47m[5][0m: The object here, a call of [47mFOLDR[0m, is tame because there are 3
  actuals, the first and third are tame expressions and the second is
  a [3mquoted[0m tame function as shown in Example [47m[4][0m.


Logical Definitions

  The various notions of tameness, [47mtamep-functionp[0m, [47mtamep[0m, and
  [47msuitably-tamep-listp[0m, are defined mutually recursively as [47m:logic[0m
  mode functions.  The definition employs the macro [47mtamep-lambdap[0m,
  which is used by [47mtamep-functionp[0m to handle the [47mLAMBDA[0m case.

  [31;1mFunction: [0m<tamep-functionp>

    (defun tamep-functionp (fn)
      (declare (xargs :guard t))
      (if (symbolp fn)
          (let ((bdg (badge fn)))
            (and bdg
                 (eq (access apply$-badge bdg :ilks) t)))
        (and (consp fn) (tamep-lambdap fn))))

  [31;1mFunction: [0m<tamep>

    (defun tamep (x)
     (declare (xargs :guard t))
     (cond
      ((atom x) (symbolp x))
      ((eq (car x) 'quote)
       (and (consp (cdr x)) (null (cddr x))))
      ((symbolp (car x))
       (let ((bdg (badge (car x))))
         (cond ((null bdg) nil)
               ((eq (access apply$-badge bdg :ilks) t)
                (suitably-tamep-listp (access apply$-badge bdg :arity)
                                      nil (cdr x)))
               (t (suitably-tamep-listp (access apply$-badge bdg :arity)
                                        (access apply$-badge bdg :ilks)
                                        (cdr x))))))
      ((consp (car x))
       (let ((fn (car x)))
         (and (tamep-lambdap fn)
              (suitably-tamep-listp (length (cadr fn))
                                    nil (cdr x)))))
      (t nil)))

  [31;1mFunction: [0m<suitably-tamep-listp>

    (defun suitably-tamep-listp (n flags args)
      (declare (xargs :guard (and (natp n) (true-listp flags))))
      (cond ((zp n) (null args))
            ((atom args) nil)
            (t (and (let ((arg (car args)))
                      (case (car flags)
                        (:fn (and (consp arg)
                                  (eq (car arg) 'quote)
                                  (consp (cdr arg))
                                  (null (cddr arg))
                                  (tamep-functionp (cadr arg))))
                        (:expr (and (consp arg)
                                    (eq (car arg) 'quote)
                                    (consp (cdr arg))
                                    (null (cddr arg))
                                    (tamep (cadr arg))))
                        (otherwise (tamep arg))))
                    (suitably-tamep-listp (- n 1)
                                          (cdr flags)
                                          (cdr args))))))

  [31;1mMacro: [0m<tamep-lambdap>

    (defmacro tamep-lambdap (fn)
      (list 'let
            (list (list 'fn fn))
            '(and (lambda-object-shapep fn)
                  (symbol-listp (lambda-object-formals fn))
                  (tamep (lambda-object-body fn)))))

  At the top-level of the ACL2 loop you can determine whether an object
  satisfies one of these predicates by calling the appropriate formal
  notion on the object.  But because these functions are defined in
  terms of [47m[badge][0m these notions of tameness are evaluable only in
  the evaluation theory (where [47m[warrant][0ms are implicitly assumed).
  If you want to prove that an object is tame, you may need warrant
  hypotheses.  See [guarantees-of-the-top-level-loop].")
 (TAMEP (POINTERS) "See [tame].")
 (TAMEP-FUNCTIONP (POINTERS)
                  "See [tame].")
 (TAMEP-LAMBDAP (POINTERS) "See [tame].")
 (TAU-DATA
  (TAU-SYSTEM)
  "To see what tau knows about a function symbol

    Examples:
    (tau-data binary-+)

    General Form:
    (tau-data fn)

  This macro returns a list structure that indicates what facts about
  the symbol [47mfn[0m are known to the tau system.  [47mFn[0m should either be a
  function symbol or else a macro associated with [47mfn[0m; see
  [macro-aliases-table].  See [introduction-to-the-tau-system] for
  background details.

  The list structure should be self-explanatory given the following
  brief comments.  The ``index'' of a function, when non-[47mnil[0m, means
  the function is a monadic Boolean function treated by the tau
  system as a tau predicate.

  The ``positive'' and ``negative implicants'' are conjunctions that
  indicate the tau implied by the given one or its negation.

  The ``signatures'' entry is a formula indicating all the known
  signatures.  If the signatures formula is [47mT[0m it means there are no
  known signatures.  (Signatures is the conjunction of all signature
  rules and the empty conjunction is [47mT[0m.)

  If you wish to see a long list of all the runes from which some tau
  information has been gleaned, evaluate [47m(get-tau-runes (w state))[0m.")
 (TAU-DATABASE
  (TAU-SYSTEM HISTORY)
  "To see the tau database as a (very large) object

    Example:
    (tau-database (w state))

  This function returns a large list object that shows in a
  human-readable way what the tau system knows about every function
  symbol.  It is supposed to be self-explanatory.  See
  [introduction-to-the-tau-system] for background details.

  If the output is not self-explanatory, please contact the
  implementors and we will improve the output or the documentation.")
 (TAU-INTERVAL-DOM
  (TAU-SYSTEM)
  "Access the domain of a tau interval

  It is the case that

    (tau-interval-dom (make-tau-interval dom lo-rel lo hi-rel hi)) = dom

  For a well-formed interval, [47mdom[0m is one of the symbols [47mINTEGERP[0m,
  [47mRATIONALP[0m, [47mACL2-NUMBERP[0m, or [47mNIL[0m.  When the domain is [47mNIL[0m there is
  no domain restriction.

  When the domain is [47mINTEGERP[0m, there are additional constraints on the
  other components.  See [make-tau-interval].")
 (TAU-INTERVAL-HI
  (TAU-SYSTEM)
  "Access the upper bound of a tau interval

  It is the case that

    (tau-interval-hi (make-tau-interval dom lo-rel lo hi-rel hi)) = hi

  For a well-formed interval, [47mhi[0m is either [47mnil[0m, denoting positive
  infinity, or a rational number giving the upper bound of the
  interval.  It must be the case that the upper bound is weakly above
  the lower bound of a well-formed interval.

  When the domain of an interval is [47mINTEGERP[0m, there are additional
  constraints on the other components.  See [make-tau-interval].")
 (TAU-INTERVAL-HI-REL
  (TAU-SYSTEM)
  "Access the upper bound relation of a tau interval

  It is the case that

    (tau-interval-hi-rel (make-tau-interval dom lo-rel lo hi-rel hi)) = hi-rel

  For a well-formed interval, [47mhi-rel[0m is a Boolean, where [47mt[0m denotes the
  [47m[<][0m (strong inequality or ``less-than'') relation and [47mnil[0m denotes
  [47m[<=][0m (weak inequality or ``less-than-or-equal'') relation between
  the elements of the interval and the upper bound.

  When the domain of an interval is [47mINTEGERP[0m, there are additional
  constraints on the other components.  See [make-tau-interval].")
 (TAU-INTERVAL-LO
  (TAU-SYSTEM)
  "Access the lower bound of a tau interval

  It is the case that

    (tau-interval-lo (make-tau-interval dom lo-rel lo hi-rel hi)) = lo

  For a well-formed interval, [47mlo[0m is either [47mnil[0m, denoting negative
  infinity, or a rational number giving the lower bound of the
  interval.  It must be the case that the lower bound is weakly below
  the upper bound of a well-formed interval.

  When the domain of an interval is [47mINTEGERP[0m, there are additional
  constraints on the other components.  See [make-tau-interval].")
 (TAU-INTERVAL-LO-REL
  (TAU-SYSTEM)
  "Access the lower bound relation of a tau interval

  It is the case that

    (tau-interval-lo-rel (make-tau-interval dom lo-rel lo hi-rel hi)) = lo-rel

  For a well-formed interval, [47mlo-rel[0m is a Boolean, where [47mt[0m denotes the
  [47m[<][0m (strong inequality or ``less-than'') relation and [47mnil[0m denotes
  [47m[<=][0m (weak inequality or ``less-than-or-equal'') relation between
  the lower bound and the elements of the interval.

  When the domain of an interval is [47mINTEGERP[0m, there are additional
  constraints on the other components.  See [make-tau-interval].")
 (TAU-INTERVALP
  (TAU-SYSTEM)
  "Boolean recognizer for tau intervals

    General Form:
    (tau-intervalp x)

  An interval is a structure of the form: [47m([0m[3mdom[0m [47m([0m[3mlo-rel[0m [47m.[0m [3mlo[0m[47m)[0m [47m.[0m [47m([0m[3mhi-rel[0m
  [47m.[0m [3mhi[0m[47m))[0m.  Every tau contains an interval used to represent the
  domain and the upper and lower bounds of the objects recognized by
  the tau.

  Restrictions on the components of an interval are as follows.  For an
  interpretation of the meaning of the components, see
  [47m[in-tau-intervalp][0m or [47m[make-tau-interval][0m.

  [3mDom[0m (``domain'') must be one of four symbols: [47mINTEGERP[0m, [47mRATIONALP[0m,
  [47mACL2-NUMBERP[0m, or [47mNIL[0m.

  The two ``relations,'' [3mlo-rel[0m and [3mhi-rel[0m, must be Booleans.

  [3mLo[0m and [3mhi[0m must be either [47mnil[0m or explicit rational numbers.  [3mLo[0m must
  be no greater than [3mhi[0m (where [47mnil[0ms represent negative or positive
  infinity for [3mlo[0m and [3mhi[0m respectively.

  Finally, if the [3mdom[0m is [47mINTEGERP[0m, then both relations must [47mnil[0m and [3mlo[0m
  and [3mhi[0m must be integers when they are non-[47mnil[0m.

  Recall that [47m[make-tau-interval][0m constructs intervals.  The intervals
  it constructs are well-formed only if the arguments to
  [47mmake-tau-interval[0m satisfy the rules above; [47mmake-tau-interval[0m does
  not coerce or adjust its arguments in any way.  Thus, it can be
  (mis-)used to create non-intervals.  Here are examples of
  [47mtau-intervalp[0m using [47mmake-tau-interval[0m.

    ; integers: 0 <= x <= 10:
    (tau-intervalp (make-tau-interval 'INTEGERP nil 0 nil 10))      = t

    ; integers: 0 <= x (i.e., the natural numbers):
    (tau-intervalp (make-tau-interval 'INTEGERP nil 0 nil nil))     = t

    ; violations of domain rules:
    (tau-intervalp (make-tau-interval 'INTEGERP t 0 t 10))          = nil
    (tau-intervalp (make-tau-interval 'INTEGERP nil 0 nil 10/11))   = nil

    ; violation of rule that bounds must be rational if non-nil:
    (tau-intervalp (make-tau-interval 'ACL2-NUMBERP t 0 t #c(3 5))) = nil

    ; violation of rule that lo <= hi:
    (tau-intervalp (make-tau-interval 'ACL2-NUMBERP t 0 t -10))     = nil

    ; rationals: 0 < x <= 22/7:
    (tau-intervalp (make-tau-interval 'RATIONALP t 0 nil 22/7))     = t

    ; numbers: -10 < x < 10:
    (tau-intervalp (make-tau-interval 'ACL2-NUMBERP t -10 t 10))    = t

    ; any: -10 < x < 10:
    (tau-intervalp (make-tau-interval nil t -10 t 10))              = t

    : any:
    (tau-intervalp (make-tau-interval nil nil nil nil nil))         = t

  Note that the second-to-last interval, with domain [47mnil[0m contains all
  non-numbers as well as numbers strictly between -10 and 10.  The
  reason is that the interval contains [47m0[0m and all non-numbers are
  coerced to [47m0[0m by the inequality functions.

  Note that the last interval contains all ACL2 objects.  It is called
  the ``universal interval.''")
 (TAU-STATUS
  (TAU-SYSTEM)
  "Query or set tau system status

    Examples:
    (tau-status)
    (tau-status :system t)
    (tau-status :auto-mode nil)
    (tau-status :system t :auto-mode nil)

    General Form:
    (tau-status :system a :auto-mode b)

  where [47ma[0m and [47mb[0m are Booleans.  Both keyword arguments are optional and
  they may be presented in either order.  Value [47ma[0m controls whether
  the [47m[tau-system][0m is used during subsequent proofs.  Value [47mb[0m
  controls whether tau system rules are added automatically
  (``greedily'') when rules of other [47m[rule-classes][0m are added.  If no
  arguments are supplied, this is not an event and just returns an
  [error-triple] indicating the current settings.  See
  [introduction-to-the-tau-system] for background details.

  The two flags are independent.  For example, the tau system may be
  disabled in proof attempts even though it is automatically (and
  silently) extending its database as rules of other classes are
  added.

  Flag (a) is actually toggled by enabling or disabling the
  [47m:[0m[47m[executable-counterpart][0m of [47m[tau-system][0m.  Flag (b) is toggled
  with the function [47m[set-tau-auto-mode][0m, which manipulates the
  [47m[ACL2-defaults-table][0m.

  This macro expands into zero, one, or two [events], as required by
  the supplied values of flags [47ma[0m and [47mb[0m.

  If no arguments are supplied the form is not an event and simply
  returns (as an [error-triple], [47m(mv nil ans state)[0m) the current
  settings of the two flags.  For example:

    ACL2 !>(tau-system)
     ((:SYSTEM NIL) (:AUTO-MODE T))

  intended to be self-explanatory.")
 (TAU-SYSTEM
  (RULE-CLASSES)
  "Make a rule for the ACL2 ``type checker''

  This documentation topic describes the syntactic form of
  ``tau-system'' rules; these rules extend ACL2's ``type checker.''
  For an introduction to the tau system, see
  [introduction-to-the-tau-system].

  There happens to be a [3mfunction[0m named [47mtau-system[0m, defined as the
  identity function.  Its only role is to provide the rune
  [47m(:EXECUTABLE-COUNTERPART TAU-SYSTEM)[0m, which is used to enable and
  disable the tau system.  Otherwise the function [47mtau-system[0m has no
  purpose and we recommend that you avoid using it so you are free to
  enable and disable the tau system.

  When in the default (``greedy'') mode (see [47m[set-tau-auto-mode][0m),
  every [47m[defun][0m and every [47m:corollary[0m (see [47m:[0m[47m[rule-classes][0m) of every
  [47m[defthm][0m stored as a rule [3mof any[0m [47m:rule-class[0m is inspected to
  determine if it is of one of the forms below.  Rules of these forms
  are added to the tau database, even if they are not labeled as
  [47m:tau-system[0m rules, e.g., a [47m:[0m[47m[rewrite][0m rule might contribute to the
  tau database!  To add a rule to the tau database without adding any
  other kind of rule, tag it with [47m:[0m[47m[rule-classes][0m [47m:tau-system[0m.  If a
  theorem has [47m:[0m[47m[rule-classes][0m [47mnil[0m, it is not considered for the tau
  database.

    General Forms:
    [3mBoolean[0m:
    (booleanp (p v))

    [3mEval[0m:
    (p 'const) or
    (p *const*)

    [3mSimple[0m:
    (implies (p v) (q v))

    [3mConjunctive[0m:
    (implies (and (p1 v) ... (pk v)) (q v)), ; Here k must exceed 1.

    [3mSignature Form 1[0m:
    (implies (and (p1 x1) (p2 x2) ...)
             (q (fn x1 x2 ...)))

    [3mSignature Form 2[0m:
    (implies (and (p1 x1) (p2 x2) ...)
             (q (mv-nth 'n (fn x1 x2 ...))))

    [3mBounder Form 1 (or Form 2)[0m:
    (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 [3mtarget[0m
                                    (bounder-fn i1 ...))))

    where [3mtarget[0m is
    (fn x1 ... y1 ...)             in [3mForm 1[0m, and
    (mv-nth 'n (fn x1 ... y1 ...)) in [3mForm 2[0m

    [3mBig Switch[0m:
    (equal (fn . formals) body)

    [3mMV-NTH Synonym[0m:
    (equal (nth-alt x y) (mv-nth x y)) or
    (equal (mv-nth x y) (nth-alt x y))

  The symbols [47mp[0m, [47mq[0m, [47mp1[0m, etc., denote monadic (one-argument)
  Boolean-valued function symbols, or equalities in which one
  argument is constant, arithmetic comparisons in which one argument
  is a rational or integer constant, or the logical negations of such
  terms.  By ``equalities'' we allow [47m[equal][0m, [47m[eq][0m, [47m[eql][0m, and [47m[=][0m.
  By ``arithmetic comparison'' we mean [47m[<][0m, [47m[<=][0m, [47m[>=][0m, or [47m[>][0m.  Any
  of these tau predicates may appear negated.

  The notation [47m(p v)[0m above might stand for any one of:

    (INTEGERP X)
    (EQUAL V 'MONDAY)
    (<= I 16)
    (NOT (EQUAL X 'SUNDAY))

  The different rule forms above affect different aspects of the tau
  system.  We discuss each form in more detail below.

  The documentation below is written as though the tau system is in
  auto mode!  To ensure that the only rules added to the tau system
  are those explicitly assigned to [47m:rule-class[0m [47m:tau-system[0m, you
  should use [47m[set-tau-auto-mode][0m to select manual mode.

    General Form: [3mBoolean[0m:
    (booleanp (p v))

  Here [47mp[0m must be a function symbol and [47mv[0m must be a variable.  Such a
  [47m:tau-system[0m rule adds [47mp[0m to the list of tau predicates.  If [47mp[0m was
  recognized as Boolean when it was defined, there is no need to
  state this rule.  This form is needed if you define a monadic
  Boolean function in such a way that the system does not recognize
  that it is Boolean.

    General Form: [3mEval[0m:
    (p 'const) or
    (p *const*)

  Here [47mp[0m must be a function symbol.  In addition, recall that these
  general tau predicate forms may appear negated.  So the form above
  includes such theorems as [47m(NOT (GOOD-STATEP *INITIAL-STATE*))[0m.  A
  theorem of this form thus records whether a named predicate is true
  or false on the given constant.

  Generally, when the tau system must determine whether an enabled tau
  predicate is true or false on a constant, it simply evaluates the
  predicate on the constant.  This can be impossible or very
  inefficient if [47mp[0m is not defined but constrained, or if [47mp[0m is defined
  in a hard-to-compute way (e.g., [47m(defun p (x) (evenp (ack x x)))[0m
  where [47mack[0m is the Ackermann function), or perhaps if the constant is
  very large.  By proving a [47m:tau-system[0m rule of Eval form, you cause
  the tau system to note the value of the predicate on the constant
  and henceforth to look it up instead of evaluating the definition.

  A difficulty, however, is determining that a slow down is due to the
  evaluation of tau predicates and not some other reason.  The first
  step is determining that tau is slowing the proof down.  See
  [47m[time-tracker-tau][0m for an explanation of [47mTIME-TRACKER-NOTE[0ms output
  during some proofs involving tau reasoning.  These notes can alert
  you to the fact that significant amounts of time are being spent in
  the tau system.  [47m[Time-tracker-tau][0m gives some ways of determining
  whether tau predicate evaluation is involved.  (If worse comes to
  worst, consider the following hack: In the ACL2 source file
  [47mtau.lisp[0m, immediately after the definition of the system function
  [47mev-fncall-w-tau-recog[0m, 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.)  However, once a
  recognizer and the constants on which it is being evaluated are
  identified, the tau system can be sped up by proving Eval rules to
  pre-compute and store the values of the recognizer on those
  constants.  Alternatively, at the possible loss of some
  completeness in the tau system, the executable-counterpart of the
  recognizer can be disabled.

    General Form: [3mSimple[0m:
    (implies (p v) (q v))

  Here [47mv[0m must be a variable symbol.  This rule builds-in the
  information that anything satisfying [47mp[0m must also satisfy [47mq[0m, i.e.,
  the ``type'' [47mq[0m includes the ``type'' [47mp[0m.  Recall that the forms may
  be negated.  Most of the time, [47mp[0m and [47mq[0m will be predicate symbols
  but it is possible they will be equalities- or
  inequalities-with-constants.  Examples of Simple rules include the
  following, which are in fact built-in:

    (implies (natp x) (integerp x))
    (implies (integerp x) (rationalp x))
    (implies (integerp x) (not (true-listp x)))
    (implies (natp x) (not (< x 0)))
    (implies (symbol-alistp x) (alistp x))

  Because the tau system records the transitive closure of the Simple
  rules, any time a term is known to satisfy [47mnatp[0m it is also known to
  satisfy [47mintegerp[0m and [47mrationalp[0m, and known not to satisfy
  [47mtrue-listp[0m, and known to be non-negative.

    General Form: [3mConjunctive[0m:
    (implies (and (p1 v) ... (pk v)) (q v)), ; Here k must exceed 1.

  The [47mpi[0m and [47mq[0m may be any tau predicates or their negations, [47mv[0m must be
  a variable symbol, and [47mi[0m must exceed 1 or else this is a Simple
  rule.  An obvious operational interpretation of this rule is that
  if an object is known to satisfy all of the [47mpi[0m, then it is known to
  satisfy [47mq[0m.  However, the actual interpretation is more general.
  For example, if an object is known to satisfy all but one of the [47mpi[0m
  and is known not to satisfy [47mq[0m, then the object is known not to
  satisfy the ``missing'' [47mpi[0m.

  For example, the following Conjunctive rule allows tau to conclude
  that if weekday [47mD[0m is not [47mMON[0m, [47mTUE[0m, [47mTHU[0m or [47mFRI[0m, then it is [47mWED[0m:

    (implies (and (weekdayp d)
                  (not (eq d 'MON))
                  (not (eq d 'TUE))
                  (not (eq d 'WED))
                  (not (eq d 'THU)))
             (eq d 'FRI))

  The tau database is not closed under conjunctive rules; they are
  applied dynamically.

    General Form: [3mSignature Form 1[0m:
    (implies (and (p1 x1) (p2 x2) ... (pn xn) dep-hyp)
             (q (fn x1 x2 ... xn)))

  The [47mpi[0m and [47mq[0m may be any tau predicates or their negations, [47mfn[0m must be
  a function symbol of arity [47mn[0m, the [47mxi[0m must be distinct variable
  symbols and [47mdep-hyp[0m may be any term, provided it is not of the [47m(pi
  xi)[0m shape and the only variables in it are the [47mxi[0m.

  The Signature form actually allows multiple tau predicates to be
  applied to each variable, e.g., x1 might be required to be both an
  [47mINTEGERP[0m and [47mEVENP[0m.  The Signature form allows there to be multiple
  hypotheses classified as [47mdep-hyp[0ms, i.e., not fitting any of the
  previous shapes, and they are implicitly just conjoined.  The name
  ``dep-hyp'' is an abbreviation of ``dependent hypothesis'' and
  stems from the fact they often express relations between several of
  the function's inputs rather than type-like constraints on
  individual inputs.

  A Signature rule informs tau that the function [47mfn[0m returns an object
  satisfying [47mq[0m provided that the arguments satisfy the respective [47mpi[0m
  and provided that [47mdep-hyp[0m occurs in the current context.  Note: to
  be precise, dependent hypotheses are relieved only by applying
  ACL2's most primitive form of reasoning, type reasoning (see
  [TYPE-REASONING]) (using [type-set]).  In particular, tau reasoning
  is not used to establish dependent hypotheses.  The presence of a
  [47mdep-hyp[0m in a signature rule may severely restrict its
  applicability.  We discuss this after showing a few mundane
  examples.

  An example Signature rule is

    (implies (and (integer-listp x)
                  (integer-listp y))
             (integer-listp (append x y)))

  Of course, a function may have multiple signatures:

    (implies (and (symbol-listp x)
                  (symbol-listp y))
             (symbol-listp (append x y)))

  Here is a Signature rule for the function [47mpairlis$[0m:

    (implies (and (symbol-listp x)
                  (integer-listp y))
             (symbol-alistp (pairlis$ x y)))

  The tau system can consequently check this theorem by composing the
  last two rules shown and exploiting Simple rule stating that
  symbol-alists are also alists:

    (thm (implies (and (symbol-listp a)
                       (symbol-listp b)
                       (integer-listp y))
                  (alistp (pairlis$ (append a b) y))))

  Since [47ma[0m and [47mb[0m are known to be lists of symbols and a signature for
  [47mappend[0m is that it preserves that predicate, the first argument to
  the [47mpairlis$[0m expression is known to be a list of symbols.  This
  means the Signature rule for [47mpairlis$[0m tells us the result is a
  [47msymbol-alistp[0m, but the previously mentioned Simple rule, [47m(implies
  (symbol-alistp x) (alistp x))[0m, tells us the result is also an
  [47malistp[0m.

  When a Signature rule has an [47mdep-hyp[0m, that hypothesis is not an
  expression in the tau system.  Tau is not used to check that
  hypothesis.  Instead, tau uses the more primitive [type-set]
  mechanism of ACL2.  Here is an example of a Signature rule with a
  [47mdep-hyp[0m:

    (implies (and (natp n)
                  (integer-listp a)
                  (< n (len a)))
             (integerp (nth n a)))

  Note that the last hypothesis is a dependent hypothesis: it is not a
  tau predicate but a relationship between [47mn[0m and [47ma[0m.  It is relieved
  by [type-set].  If one is trying to compute the signature of an
  [47m(nth n a)[0m expression in a context in which [47m(< n (len a))[0m is
  explicitly assumed, then this mechanism would establish the
  dependent hypothesis.  But one can easily imagine an almost
  identical context where, say [47m(< n (len (rev a)))[0m is explicitly
  assumed.  In that context, the Signature rule would not be fired
  because [47m[type-set][0m cannot establish [47m(< n (len a))[0m from [47m(< n (len
  (rev a)))[0m, even though it would be easily proved by rewriting using
  the theorem [47m(equal (len (rev a)) (len a))[0m.

  Note also that if this signature could be phrased in a way that
  eliminates the dependency between [47mn[0m and [47ma[0m it would be more
  effective.  For example, here is a related Signature rule without a
  dependent hypothesis:

    (implies (and (natp n)
                  (register-filep a)
                  (< n 16))
             (integerp (nth n a)))

  In this theorem we require only that [47mn[0m be less than 16, which is a
  tau predicate and hence just an additional tau constraint on [47mn[0m.

    General Form: [3mSignature Form 2[0m:
    (implies (and (p1 x1) (p2 x2) ... (pn xn) dep-hyp)

             (q (mv-nth 'n (fn x1 x2 ... xn))))

  This form of signature rule is just like form 1 except that it is
  useful for functions that return [multiple-value]s and allows us to
  ``type-check'' their individual outputs.

    General Form: [3mBounder Forms 1 and 2[0m:
    (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 [3mtarget[0m
                                    (bounder-fn i1 ...))))

  where [3mtarget[0m is either [47m(fn x1 ... y1 ...)[0m in [3mForm 1[0m or [47m(mv-nth 'n (fn
  x1 ... y1 ...))[0m in [3mForm 2[0m.

  This form is for advanced users only and the schema given above is
  just a reminder of the general shape.  A ``bounder'' for a given
  function symbol, [47mfn[0m, is a function symbol [47mbounder-fn[0m that computes
  an interval containing [47m(fn x1 ... y1 ...)[0m (or its [47mn[0mth component in
  the case of Form 2 rules) from the intervals containing certain of
  the arguments of [47mfn[0m.  The correctness theorem for a bounder
  function informs the tau system that bounds for [47mfn[0m are computed by
  [47mbounder-fn[0m and sets up the correspondence between the relevant
  arguments, [47mxi[0m, of [47mfn[0m and the intervals containing those arguments,
  [47mii[0m to which [47mbounder-fn[0m is applied.  When the tau system computes
  the tau for a call of [47mfn[0m, it computes the tau of the relevant
  arguments and applies the bounder to the intervals of those tau.
  This provides a domain and upper and/or lower bounds for the value
  of the term.  The tau system then further augments that with
  signature rules.  See [bounders] for details on intervals,
  bounders, and bounder correctness theorems.

    General Form: [3mBig Switch[0m:
    (equal (fn . formals) body)

  In the Big Switch form, [47mfn[0m must be a function symbol, [47mformals[0m must be
  a list of distinct variable symbols, and [47mbody[0m must be a ``big
  switch'' term, i.e., one that case splits on tau predicates about a
  single variable and produces a term not involving that variable.
  An example of a Big Switch rule is

    (equal (conditional-type x y)
           (if (consp x)
               (consp y)
               (integerp y)))

  The idea is that the tau system can treat calls of [47mconditional-type[0m
  as a tau-predicate after determining the tau of an argument.

  Since equality-to-constants are tau predicates, a more common example
  of a Big Switch rule is

    (equal (dtypep x expr)
           (case x
                 (STMT (stmt-typep expr))
                 (EXPR (expr-typep expr))
                 (MODULE (module-typep expr))
                 (otherwise nil)))

  This is because [47m(case x (STMT ...) ...)[0m macroexpands in ACL2 to [47m(if
  (eql x 'STMT) ... ...)[0m and [47m(eql x 'STMT)[0m is a tau predicate about
  [47mx[0m.

  Big Switch rules are recognized when a function is defined (if tau is
  in automatic mode).  They generally do not have to be proved
  explicitly, though they might be when mutual recursion is involved.
  Only the first detected Big Switch rule about a function [47mfn[0m is
  recognized.

    General Form: [3mMV-NTH Synonym[0m:
    (equal (nth-alt x y) (mv-nth x y)) or
    (equal (mv-nth x y) (nth-alt x y))

  Rules of this form just tell the tau system that the user-defined
  function [47mnth-alt[0m is synonymous with the ACL2 primitive function
  [47m[mv-nth][0m.  Because ACL2's rewriter gives special handling to [47mmv-nth[0m
  by default, users sometimes define their own versions of that
  function so they can disable them and control rewriting better.  By
  revealing to the tau system that such a synonym has been introduced
  you allow Signature rules of Form 2 to be used.


Subtopics

  [Bounders]
      Intervals, bounder functions, and bounder correctness

  [In-tau-intervalp]
      Boolean membership in a tau interval

  [Introduction-to-the-tau-system]
      A decision procedure for runtime types

  [Make-tau-interval]
      Make a tau interval

  [Set-tau-auto-mode]
      Turn on or off automatic (``greedy'') generation of [47m:tau-system[0m
      rules

  [Tau-data]
      To see what tau knows about a function symbol

  [Tau-database]
      To see the tau database as a (very large) object

  [Tau-interval-dom]
      Access the domain of a tau interval

  [Tau-interval-hi]
      Access the upper bound of a tau interval

  [Tau-interval-hi-rel]
      Access the upper bound relation of a tau interval

  [Tau-interval-lo]
      Access the lower bound of a tau interval

  [Tau-interval-lo-rel]
      Access the lower bound relation of a tau interval

  [Tau-intervalp]
      Boolean recognizer for tau intervals

  [Tau-status]
      Query or set tau system status

  [Time-tracker-tau]
      Messages about expensive use of the [tau-system]")
 (TC
  (MACROS)
  "translate form and clean it up

    Examples:
    :tc  (member e a)
    :tc  (list (cadr x) (loop$ for e in lst collect (+ 1 e)))
    :tcp (list (cadr x) (loop$ for e in lst collect (+ 1 e)))
    :tca (list (cadr x) (loop$ for e in lst collect (+ 1 e)))

    General Form:
    :tc form
    :tca form
    :tcp form
    (tc 'form)
    (tca 'form)
    (tcp 'form)

  The [47m:[0m[47m[trans][0m command prints the translation of a form into a formal
  term.  However, sometimes the translation can be hard to understand
  because various tags and declarations are included, usually for
  execution efficiency.

  For example, consider [47m:trans[0m versus [47m:tcp[0m of [47m(member e a)[0m.

    ACL2 !>:trans (member e a)

    ((LAMBDA (X L)
       (RETURN-LAST 'MBE1-RAW
                    (MEMBER-EQL-EXEC X L)
                    (RETURN-LAST 'PROGN
                                 (MEMBER-EQL-EXEC$GUARD-CHECK X L)
                                 (MEMBER-EQUAL X L))))
     E A)

    => *

    ACL2 !>:tcp (member e a)
     (MEMBER-EQUAL E A)

  The [47m:tc[0m command and its variants, [47m:tca[0m and [47m:tcp[0m, translate the given
  form and then ``clean'' it up, returning the result in an
  [error-triple].  These commands are especially useful when [47m[loop$][0m,
  [scion]s or [47m[lambda$][0m forms are involved in the form to be
  translated.  But they are also useful when [47m[mbe][0m, [47m[return-last][0m,
  [47m[progn$][0m and other special forms are used or show up in the
  translation.  The [47mtc[0m commands are macros that expand into terms
  involving [47m[state][0m, since errors are signaled when ill-formed forms
  are submitted.

    * [47m:tc[0m [3mform[0m --- translate [3mform[0m and remove everything not relevant to the
      logical value.  This is the logical semantics [3mform[0m and is
      returned in the ``internal format'' of ACL2 terms, i.e., macros
      have been expanded and all constants are quoted.  The prover
      will reduce [3mform[0m to this term almost immediately.  Typically,
      this is the term that the rewriter will encounter during a
      proof involving this [3mform[0m.  Of course, rewrite rules can
      further change the form.  However, see the note below
      concerning warrants.

    * [47m:tcp[0m [3mform[0m --- translate [3mform[0m and remove everything not relevant to
      the logical value as above, and then [47m[untranslate][0m, restoring
      the use of such system macros as [47m[lambda$][0m, [47m[let][0m, [47m[and][0m,
      [47m[list][0m, [47m[cadr][0m, and [47m[+][0m and [47m[*][0m.  This is the semantics of [3mform[0m
      in a ``user friendly'' syntax.  The suffix ``p'' in [47m:tcp[0m stands
      for ``pretty.''

    * [47m:tca[0m [3mform[0m --- translate [3mform[0m and then [47muntranslate[0m as noted above.
      This effectively leaves ``annotations'' in place such as a
      [47mprog2$[0m joining each [47mloop$[0m in [3mform[0m to its semantics, [47mdeclare[0m
      forms in [47mlambda[0m objects, and [47m[let][0m forms associating user
      variable names to values.  This term is mainly meant as a
      pedagogical device to help you understand how [47mloop$[0ms are
      translated.  The suffix ``a'' in [47m:tca[0m stands for ``annotated.''

  The terms returned by the three flavors of [47mtc[0m are all provably
  equivalent to each other and to the original [3mform[0m provided the
  necessary warrants are assumed.

  For example, if [47msq[0m is a user-defined function of arity 1 and
  [47m(defwarrant sq)[0m has issued a warrant for [47msq[0m, then

    ACL2 !>:tc (loop$ for e in lst collect (sq e))    ; sq is warranted
    (COLLECT$ '(LAMBDA (LOOP$-IVAR) (SQ LOOP$-IVAR))
             LST)

  Nevertheless, the equivalence of the input and output of [47m:tc[0m above
  cannot be proved unless the warrants are assumed.  That is,

    (thm
      (equal (loop$ for e in lst collect (sq e))
             (COLLECT$ '(LAMBDA (LOOP$-IVAR) (SQ LOOP$-IVAR))
                       LST)))

  will fail with a checkpoint indicating that the warrant for [47msq[0m must
  be provided.  However,

    (thm
      (implies (warrant sq)
               (equal (loop$ for e in lst collect (sq e))
                      (COLLECT$ '(LAMBDA (LOOP$-IVAR) (SQ LOOP$-IVAR))
                                LST))))

  succeeds.

  If there is no warrant for [47msq[0m but there is a badge, then [47m:tc[0m cannot
  clean up the translation because without a warrant the [47mlambda[0m
  object calling [47msq[0m is not [tame].  Thus,

    ACL2 !>:tc (loop$ for e in lst collect (sq e))   ; sq is badged not warranted
    (COLLECT$ '(LAMBDA (LOOP$-IVAR)
                       (RETURN-LAST 'PROGN
                                    '(LAMBDA$ (LOOP$-IVAR)
                                              (LET ((E LOOP$-IVAR))
                                                   (DECLARE (IGNORABLE E))
                                                   (SQ E)))
                                    ((LAMBDA (E) (SQ E)) LOOP$-IVAR)))
              LST)

  By the way, if you see a quoted [47mlambda[0m objects like that above in
  output from the prover, it probably means the [47mlambda[0m object
  contains unwarranted user-defined symbols!

  The differences between [47m:trans[0m and the three commands ([47m:tc[0m, [47m:tcp[0m, and
  [47m:tca[0m) are perhaps best illustrated by considering their respective
  outputs on a single [47m[loop$][0m statement.

    ACL2 !>:trans (list (cadr x) (loop$ for e in lst collect (+ 1 e)))

    (CONS (CAR (CDR X))
          (CONS (RETURN-LAST
                 'PROGN
                 '(LOOP$ FOR E IN LST COLLECT (+ 1 E))
                 (COLLECT$ '(LAMBDA (LOOP$-IVAR)
                                    (DECLARE (IGNORABLE LOOP$-IVAR))
                                    (RETURN-LAST 'PROGN
                                                 '(LAMBDA$ (LOOP$-IVAR)
                                                    (LET ((E LOOP$-IVAR))
                                                      (DECLARE (IGNORABLE E))
                                                      (+ 1 E)))
                                                 ((LAMBDA (E) (BINARY-+ '1 E))
                                                  LOOP$-IVAR)))
                           LST))
                'NIL))

    => *

    ACL2 !>:tc  (list (cadr x) (loop$ for e in lst collect (+ 1 e)))
     (CONS (CAR (CDR X))
           (CONS (COLLECT$ '(LAMBDA (LOOP$-IVAR)
                                    (BINARY-+ '1 LOOP$-IVAR))
                           LST)
                 'NIL))

    ACL2 !>:tcp (list (cadr x) (loop$ for e in lst collect (+ 1 e)))
     (LIST (CADR X)
           (COLLECT$ (LAMBDA$ (LOOP$-IVAR) (+ 1 LOOP$-IVAR))
                     LST))

    ACL2 !>:tca (list (cadr x) (loop$ for e in lst collect (+ 1 e)))
     (LIST (CADR X)
           (PROG2$ '(LOOP$ FOR E IN LST COLLECT (+ 1 E))
                   (COLLECT$ (LAMBDA$ (LOOP$-IVAR)
                                      (LET ((E LOOP$-IVAR))
                                           (DECLARE (IGNORABLE E))
                                           (+ 1 E)))
                             LST)))

  First, notice that [47m:trans[0m also reports the output signature of the
  term but the [47m:tc[0m commands do not.  They all return the cleaned up
  translation in an error triple.  Second, [47m:tc[0m returns a term in the
  internal format: the [47mlambda[0m objects are quoted list constants and
  their bodies are in internal format, e.g., note the [47mbinary-+[0m and
  quoted constant [47m1[0m in the output of [47m:tc[0m above.  If you use the [47m:tc[0m
  command on the left-hand side of the conclusion of a [47m:rewrite[0m rule
  the term you see is the term under which the rule is stored, i.e.,
  the rule will be tried to rewrite instances of that term.

  The other two commands have ``prettied up'' the output into a more
  user-friendly format.  Third, the [47m:tca[0m command uses a [47mprog2$[0m to
  show the untranslated [47mloop$[0m as a list constant and then show its
  pretty semantics, with a [47mlet[0m form in the body of the [47mlambda$[0m
  reminding you that [47mloop$-ivar[0m is what was called [47me[0m.

  It is often helpful to look at the semantics of fancy [47mloop$[0ms.

    ACL2 !>:tca (loop$ for x in xlst
                       as  y in ylst
                       collect (+ (* a x) (* b y)))
     (PROG2$
         '(LOOP$ FOR X IN XLST AS
                 Y IN YLST COLLECT (+ (* A X) (* B Y)))
         (COLLECT$+
              (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                       (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                                                   (EQUAL (LEN LOOP$-GVARS) 2)
                                                   (TRUE-LISTP LOOP$-IVARS)
                                                   (EQUAL (LEN LOOP$-IVARS) 2))))
                       (LET ((A (CAR LOOP$-GVARS))
                             (B (CAR (CDR LOOP$-GVARS)))
                             (X (CAR LOOP$-IVARS))
                             (Y (CAR (CDR LOOP$-IVARS))))
                            (DECLARE (IGNORABLE A B X Y))
                            (+ (* A X) (* B Y))))
              (LIST A B)
              (LOOP$-AS (LIST XLST YLST))))

  Notice what happens to the [47m:guard[0m of the [47mlambda$[0m if we insert type
  specifications with [47mof-type[0m.

    ACL2 !>:tca (loop$ for x of-type (satisfies natp) in xlst
                       as  y of-type integer in ylst
                       collect (+ (* a x) (* b y)))
     (PROG2$
      '(LOOP$ FOR X OF-TYPE (SATISFIES NATP)
              IN XLST AS Y OF-TYPE INTEGER
              IN YLST COLLECT (+ (* A X) (* B Y)))
      (COLLECT$+
       (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                (DECLARE (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                                            (EQUAL (LEN LOOP$-GVARS) 2)
                                            (TRUE-LISTP LOOP$-IVARS)
                                            (EQUAL (LEN LOOP$-IVARS) 2)
                                            (NATP (CAR LOOP$-IVARS))
                                            (INTEGERP (CAR (CDR LOOP$-IVARS))))))
                (LET ((A (CAR LOOP$-GVARS))
                      (B (CAR (CDR LOOP$-GVARS)))
                      (X (CAR LOOP$-IVARS))
                      (Y (CAR (CDR LOOP$-IVARS))))
                     (DECLARE (TYPE (SATISFIES NATP) X)
                              (TYPE INTEGER Y)
                              (IGNORABLE A B X Y))
                     (+ (* A X) (* B Y))))
       (LIST A B)
       (LOOP$-AS (LIST XLST YLST))))

  And notice how the [47m:guard[0m keyword after the [47mcollect[0m in the [47mloop$[0m
  statement is added to the [47m:guard[0m of the generated [47mlambda$[0m.

    ACL2 !>:tca (loop$ for x of-type (satisfies natp) in xlst
                       as  y of-type integer in ylst
                       collect
                       :guard (and (rationalp a)
                                   (complex-rationalp b))
                       (+ (* a x) (* b y)))
     (PROG2$
      '(LOOP$ FOR X OF-TYPE (SATISFIES NATP)
              IN XLST AS
              Y OF-TYPE INTEGER IN YLST COLLECT :GUARD
              (AND (RATIONALP A)
                   (COMPLEX-RATIONALP B))
              (+ (* A X) (* B Y)))
      (COLLECT$+
       (LAMBDA$
        (LOOP$-GVARS LOOP$-IVARS)
        (DECLARE
          (XARGS :GUARD (AND (TRUE-LISTP LOOP$-GVARS)
                             (EQUAL (LEN LOOP$-GVARS) 2)
                             (TRUE-LISTP LOOP$-IVARS)
                             (EQUAL (LEN LOOP$-IVARS) 2)
                             (NATP (CAR LOOP$-IVARS))
                             (INTEGERP (CAR (CDR LOOP$-IVARS)))
                             (AND (RATIONALP (CAR LOOP$-GVARS))
                                  (COMPLEX-RATIONALP (CAR (CDR LOOP$-GVARS)))))))
        (LET ((A (CAR LOOP$-GVARS))
              (B (CAR (CDR LOOP$-GVARS)))
              (X (CAR LOOP$-IVARS))
              (Y (CAR (CDR LOOP$-IVARS))))
             (DECLARE (TYPE (SATISFIES NATP) X)
                      (TYPE INTEGER Y)
                      (IGNORABLE A B X Y))
             (+ (* A X) (* B Y))))
       (LIST A B)
       (LOOP$-AS (LIST XLST YLST))))

  Of course, while these declarations play a role in [47m:guard[0m
  verification and execution in raw Lisp, they are irrelevant to the
  formal semantics, as made clear by [47m:tcp[0m.

    ACL2 !>:tcp (loop$ for x of-type (satisfies natp) in xlst
                       as  y of-type integer in ylst
                       collect
                       :guard (and (rationalp a)
                                   (complex-rationalp b))
                       (+ (* a x) (* b y)))
     (COLLECT$+ (LAMBDA$ (LOOP$-GVARS LOOP$-IVARS)
                         (+ (* (CAR LOOP$-GVARS)
                               (CAR LOOP$-IVARS))
                            (* (CADR LOOP$-GVARS)
                               (CADR LOOP$-IVARS))))
                (LIST A B)
                (LOOP$-AS (LIST XLST YLST)))")
 (TCA
  (MACROS)
  "translate a form and clean it up into an annotated pretty term

  See [47m[tc][0m.")
 (TCP
  (MACROS)
  "translate a form and clean it up into a pretty term

  See [47m[tc][0m.")
 (TENTH
  (NTH ACL2-BUILT-INS)
  "Tenth member of the list

  See any Common Lisp documentation for details.")
 (TERM
  (MISCELLANEOUS)
  "The three senses of well-formed ACL2 expressions or formulas

  Also see [untranslate] for a relevant utility (and a more abbreviated
  explanation of terms).

    Examples of Terms:
    (cond ((caar x) (cons t x)) (t 0))   ; an untranslated term

    (if (car (car x)) (cons 't x) '0)    ; a translated term

    (car (cons x y) 'nil v)              ; a pseudo-term

  In traditional first-order predicate calculus a ``term'' is a
  syntactic entity denoting some object in the universe of
  individuals.  Often, for example, the syntactic characterization of
  a term is that it is either a variable symbol or the application of
  a function symbol to the appropriate number of argument terms.
  Traditionally, ``atomic formulas'' are built from terms with
  predicate symbols such as ``equal'' and ``member;'' ``formulas''
  are then built from atomic formulas with propositional
  ``operators'' like ``not,'' ``and,'' and ``implies.'' Theorems are
  formulas.  Theorems are ``valid'' in the sense that the value of a
  theorem is true, in any model of the axioms and under all possible
  assignments of individuals to variables.

  However, in ACL2, terms are used in place of both atomic formulas and
  formulas.  ACL2 does not have predicate symbols or propositional
  operators as distinguished syntactic entities.  The ACL2 universe
  of individuals includes a ``true'' object (denoted by [47mt[0m) and a
  ``false'' object (denoted by [47mnil[0m), predicates and propositional
  operators are functions that return these objects.  Theorems in
  ACL2 are terms and the ``validity'' of a term means that, under no
  assignment to the variables does the term evaluate to [47mnil[0m.

  We use the word ``term'' in ACL2 in three distinct senses.  We will
  speak of ``translated'' terms, ``untranslated'' terms, and
  ``pseudo-'' terms.

  [3mTranslated Terms: The Strict Sense and Internal Form[0m

  In its most strict sense, a ``term'' is either a legal variable
  symbol, a quoted constant, or the application of an n-ary function
  symbol or closed [47mlambda[0m expression to a true list of n terms.

  The legal variable symbols are symbols other than [47mt[0m or [47mnil[0m which are
  not in the keyword package, do not start with ampersand, do not
  start and end with asterisks, and if in the main Lisp package, do
  not violate an appropriate restriction (see [name]).

  Quoted constants are expressions of the form [47m(quote x)[0m, where [47mx[0m is
  any ACL2 object.  Such expressions may also be written [47m'x[0m.

  Closed [47mlambda[0m expressions are expressions of the form [47m(lambda (v1 ...
  vn) body)[0m where the [47mvi[0m are distinct legal variable symbols, [47mbody[0m is
  a term, and the only free variables in [47mbody[0m are among the [47mvi[0m.

  The function [47mtermp[0m, which takes two arguments, an alleged term [47mx[0m and
  a logical world [47mw[0m (see [world]), recognizes terms of a given
  extension of the logic.  [47mTermp[0m is defined in [47m:[0m[47m[program][0m mode.  Its
  definition may be inspected with [47m:[0m[47m[pe][0m [47mtermp[0m for a complete
  specification of what we mean by ``term'' in the most strict sense.
  Most ACL2 term-processing functions deal with terms in this strict
  sense and use [47mtermp[0m as a [guard].  That is, the ``internal form''
  of a term satisfies [47mtermp[0m, the strict sense of the word ``term.''

  [3mUntranslated Terms: What the User Types[0m

  While terms in the strict sense are easy to explore (because their
  structure is so regular and simple) they can be cumbersome to type.
  Thus, ACL2 supports a more sugary syntax that includes uses of
  macros and constant symbols.  Very roughly speaking, macros are
  functions that produce terms as their results.  Constants are
  symbols that are associated with quoted objects.  Terms in this
  sugary syntax are ``translated'' to terms in the strict sense; the
  sugary syntax is more often called ``untranslated.'' Roughly
  speaking, translation just implements macroexpansion, the
  replacement of constant symbols by their quoted values, and the
  checking of all the rules governing the strict sense of ``term.''

  More precisely, macro symbols are as described in the documentation
  for [47m[defmacro][0m.  A macro, [47mmac[0m, can be thought of as a function,
  [47mmac-fn[0m, from ACL2 objects to an ACL2 object to be treated as an
  untranslated term.  For example, [47m[caar][0m is defined as a macro
  symbol; the associated macro function maps the object [47mx[0m into the
  object [47m(car (car x))[0m.  A macro form is a ``call'' of a macro
  symbol, i.e., a list whose [47m[car][0m is the macro symbol and whose
  [47m[cdr][0m is an arbitrary true list of objects, used as a term.
  Macroexpansion is the process of replacing in an untranslated term
  every occurrence of a macro form by the result of applying the
  macro function to the appropriate arguments.  The ``appropriate''
  arguments are determined by the exact form of the definition of the
  macro; macros support positional, keyword, optional and other kinds
  of arguments.  See [defmacro].

  In addition to macroexpansion and constant symbol dereferencing,
  translation implements the mapping of [47m[let][0m and [47m[let*][0m forms into
  applications of [47mlambda[0m expressions and closes [47mlambda[0m expressions
  containing free variables.  Thus, the translation of

    (let ((x (1+ i))) (cons x k))

  can be seen as a two-step process that first produces

    ((lambda (x) (cons x k)) (1+ i))

  and then

    ((lambda (x k) (cons x k)) (1+ i) k) .

  Observe that the body of the [47m[let][0m and of the first [47mlambda[0m expression
  contains a free [47mk[0m which is finally bound and passed into the second
  [47mlambda[0m expression.

  Translation also maps [47m[flet][0m forms into applications of [47mlambda[0m
  expressions.  See [flet].

  When we say, of an event-level function such as [47m[defun][0m or [47m[defthm][0m,
  that some argument ``must be a term'' we mean an untranslated term.
  The event functions translate their term-like arguments.

  To better understand the mapping between untranslated terms and
  translated terms it is convenient to use the keyword command
  [47m:[0m[47m[trans][0m to see examples of translations.  See [trans] and also see
  [trans1].

  Finally, we note that the theorem prover prints terms in untranslated
  form.  But there can be more than one correct untranslated term
  corresponding to a given translated term.  For example, the
  translated term [47m(if x y 'nil)[0m can be untranslated as [47m(if x y nil)[0m
  and can also be untranslated as [47m(and x y)[0m.  The theorem prover
  attempts to print an untranslated term that is as helpful to the
  user as possible.  In particular, consider a term of the form [47m(nth
  k st)[0m where [47mst[0m is a single-threaded object (see [stobj]) and the
  [47mkth[0m accessor of [47mst[0m is, say, [47mkn[0m.  The theorem prover typically would
  expand [47m(kn st)[0m to [47m(nth k st)[0m.  If [47mk[0m is large then it could be
  difficult for the user to make sense out of a proof transcript that
  mentions the expanded term.  Fortunately, the untranslation of [47m(nth
  k st)[0m would be [47m(nth *kn* st)[0m; here [47m*kn*[0m would be a constant (see
  [defconst]) added by the [47m[defstobj][0m event introducing [47mst[0m, defined
  to have value [47mk[0m.  The user can extend this user-friendly style of
  printing applications of [47m[nth][0m to stobjs; see [add-nth-alias].
  These remarks about printing applications of function [47m[nth][0m extend
  naturally to function [47m[update-nth][0m.  Moreover, the prover will
  attempt to treat terms as [stobj]s for the above purpose when
  appropriate.  For example, if function [47mfoo[0m has [signature] [47m((foo *
  st) => (mv * * * st))[0m, where [47mst[0m is introduced with [47m(defstobj st f0
  f1)[0m, then the [term] [47m(nth '1 (mv-nth '3 (foo x st0)))[0m will be
  printed as [47m(nth *f1* (mv-nth 3 (foo x st0)))[0m.

  [3mPseudo-Terms: A Common Guard for Metafunctions[0m

  Because [47mtermp[0m is defined in [47m:[0m[47m[program][0m mode, it cannot be used
  effectively in conjectures to be proved.  Furthermore, from the
  perspective of merely guarding a term processing function, [47mtermp[0m
  often checks more than is required.  Finally, because [47mtermp[0m
  requires the logical [world] as one of its arguments it is
  impossible to use [47mtermp[0m as a [guard] in places where the logical
  [world] is not itself one of the arguments.

  For these reasons we support the idea of ``pseudo-terms.'' A
  pseudo-term is either a symbol (but not necessarily one having the
  syntax of a legal variable symbol), a true list of length 2
  beginning with [47mquote[0m, or the ``application of'' a symbol or pseudo
  [47mlambda[0m expression to a true list of pseudo-terms.  A pseudo [47mlambda[0m
  expression is an expression of the form [47m(lambda (v1 ... vn) body)[0m
  where the [47mvi[0m are all symbols and [47mbody[0m is a pseudo-term.

  Pseudo-terms are recognized by the unary function [47m[pseudo-termp][0m.  If
  [47m(termp x w)[0m is true, then [47m(pseudo-termp x)[0m is true.  However, if [47mx[0m
  fails to be a (strict) term it may nevertheless still be a
  pseudo-term.  For example, [47m(car a b)[0m is not a term, because [47m[car][0m
  is applied to the wrong number of arguments, but it is a
  pseudo-term.

  The structures recognized by [47m[pseudo-termp][0m can be recursively
  explored with the same simplicity that terms can be.  In
  particular, if [47mx[0m is not a [47mvariablep[0m or an [47mfquotep[0m, then [47m(ffn-symb
  x)[0m is the function ([47msymbol[0m or [47mlambda[0m expression) and [47m(fargs x)[0m is
  the list of argument pseudo-terms.  A metafunction (see [meta]) or
  clause-processor (see [clause-processor]) may use [47m[pseudo-termp][0m as
  the [guard].


Subtopics

  [Guard-holders]
      Remove trivial calls from a [term]

  [Kwote]
      Quote an arbitrary object

  [Kwote-lst]
      Quote an arbitrary true list of objects

  [L<]
      Ordering on naturals or lists of naturals

  [Lambda]
      Lambda expressions, [47mLAMBDA[0m objects, and [47mlambda$[0m expressions

  [Pseudo-term-listp]
      A predicate for recognizing lists of term-like s-expressions

  [Pseudo-termp]
      A predicate for recognizing term-like s-expressions

  [Term-order]
      The ordering relation on terms used by ACL2

  [Termify]
      the process of converting a clause to a term

  [Termp]
      recognizer for the quotation of a [term]")
 (TERM-LIST-LISTP
  (ACL2-BUILT-INS)
  "recognizer for a list of [clause]s

    Example:
    (term-list-listp
     '(((NOT (ENDP X)) (NATP (LEN X)))
       ((ENDP X) (NOT (NATP (LEN (CDR X)))) (NATP (LEN X))))
     (w state))

    General Form:
    (term-list-listp x w)

  where [47mx[0m is any ACL2 object and [47mw[0m is an ACL2 logical [world].  The
  result is [47mt[0m or [47mnil[0m according to whether [47mx[0m is a true list of true
  lists of quotations of well-formed terms in [47mw[0m.

  This function is the standard ACL2 idiom for recognizing a ``set of
  clauses.'' See [clause] and see [47m[clause-processor][0m.  Each clause
  processor is supposed to take a clause (i.e., [47mterm-listp[0m) as input
  and yield a list of clauses (i.e., [47mterm-list-listp[0m) as output.
  When a clause processor is run by the theorem prover its input is
  guaranteed to be a well-formed clause by invariants maintained by
  ACL2.  But its output is checked by an explicit call to this
  function unless the user has proved that the clause processor
  always returns a list of clauses (see [well-formedness-guarantee])
  or has taken the risk of disabling the runtime test with
  [47m[set-skip-meta-termp-checks][0m.

  [31;1mFunction: [0m<term-list-listp>

    (defun term-list-listp (l w)
      (declare (xargs :guard (plist-worldp-with-formals w)))
      (if (atom l)
          (equal l nil)
        (and (term-listp (car l) w)
             (term-list-listp (cdr l) w))))")
 (TERM-LISTP
  (ACL2-BUILT-INS)
  "recognizer for a list of quotations of terms and of [clause]s

    Example:
    (term-listp '((ZP X) 'NIL (CONS X Y)) (w state))

    General Form:
    (term-listp x w)

  where [47mx[0m is any ACL2 object and [47mw[0m is an ACL2 logical [world].  The
  result is [47mt[0m or [47mnil[0m according to whether [47mx[0m is a true list of
  quotations of well-formed terms in [47mw[0m.

  This function is used in the definition of [47m[termp][0m.  In addition,
  [47mterm-listp[0m is the standard ACL2 idiom for recognizing a clause
  (``set of literals'').  See [clause] and see [47m[clause-processor][0m.
  Each clause processor is supposed to take a clause (i.e.,
  [47mterm-listp[0m) as input and yield a list of clauses (i.e.,
  [47m[term-list-listp][0m) as output.  When a clause processor is run by
  the theorem prover its input is guaranteed to be a well-formed
  clause by invariants maintained by ACL2.  But its output is checked
  by an explicit call of [47m[term-list-listp][0m unless the user has proved
  that the clause processor always returns a list of clauses (see
  [well-formedness-guarantee]) or has taken the risk of disabling the
  runtime test with [47m[set-skip-meta-termp-checks][0m.

  [47m[Term-listp][0m is mutually recursive with [47m[termp][0m.

  [31;1mFunction: [0m<term-listp>

    (defun term-listp (x w)
      (declare (xargs :guard (plist-worldp-with-formals w)))
      (cond ((atom x) (equal x nil))
            ((termp (car x) w)
             (term-listp (cdr x) w))
            (t nil)))")
 (TERM-ORDER
  (TERM ACL2-BUILT-INS)
  "The ordering relation on terms used by ACL2

  ACL2 must occasionally choose which of two terms is syntactically
  smaller.  The need for such a choice arises, for example, when
  using equality hypotheses in conjectures (the smaller term is
  substituted for the larger elsewhere in the formula), in stopping
  loops in permutative rewrite rules (see [loop-stopper]), and in
  choosing the order in which to try to cancel the addends in linear
  arithmetic inequalities.  When this notion of syntactic size is
  needed, ACL2 uses ``term order.'' Popularly speaking, term order is
  just a lexicographic ordering on terms.  But the situation is
  actually more complicated.

  We define term order only with respect to terms in translated form.
  See [trans].  Constants are viewed as built up by [3mpseudo-function[0m
  applications, as described at the end of this documentation.

  [47mTerm1[0m comes before [47mterm2[0m in the term order iff

      (a) the number of variable occurrences in [47mterm1[0m is less than that in
      [47mterm2[0m, or

      (b) the numbers of variable occurrences in the two terms are equal
      but the number of function applications in [47mterm1[0m is less than
      that in [47mterm2[0m, or

      (c) the numbers of variable occurrences in the two terms are equal,
      the numbers of functions applications in the two terms are
      equal, but pseudo-function application count for [47mterm1[0m is less
      than that for [47mterm2[0m, or

      (d) the numbers of variable occurrences in the two terms are equal,
      the numbers of functions applications in the two terms are
      equal, the pseudo-function application counts for the two terms
      are equal, and [47mterm1[0m comes before [47mterm2[0m in a lexicographic
      ordering, [47m[lexorder][0m, based their structure as Lisp objects:
      see [lexorder].

  The function [47mterm-order[0m, when applied to the translations of two ACL2
  terms, returns [47mt[0m iff the first is ``less than or equal'' to the
  second in the term order.

  By ``number of variable occurrences'' we do not mean ``number of
  distinct variables'' but ``number of times a variable symbol is
  mentioned.'' [47m(Cons x x)[0m has two variable occurrences, not one.
  Thus, perhaps counterintuitively, a large term that contains only
  one variable occurrence, e.g., [47m(standard-char-p (car (reverse x)))[0m
  comes before [47m(cons x x)[0m in the term order.

  Since constants contain no variable occurrences and non-constant
  expressions must contain at least one variable occurrence,
  constants come before non-constants in the term order, no matter
  how large the constants.  For example, the list constant

    '(monday tuesday wednesday thursday friday)

  comes before [47mx[0m in the term order.  Because term order is involved in
  the control of permutative rewrite rules and used to shift smaller
  terms to the left, a set of permutative rules designed to allow the
  permutation of any two tips in a tree representing the nested
  application of some function will always move the constants into
  the left-most tips.  Thus,

    (+ x 3 (dx i j) (car (reverse klst))) ,

  which in translated form is

    (binary-+ x
              (binary-+ '3
                        (binary-+ (dx i j)
                                  (car (reverse klst))))),

  will be permuted under the built-in commutativity rules to

    (binary-+ '3
              (binary-+ x
                        (binary-+ (car (reverse klst))
                                  (dx i j))))

  or

    (+ 3 x (car (reverse klst)) (dx i j)).

  Two terms with the same numbers of variable occurrences and function
  applications and the same pseudo-function application count are
  ordered by lexicographic means, based on their structures.  See
  [lexorder].  Thus, if two terms [47m(member ...)[0m and [47m(reverse ...)[0m
  contain the same numbers of variable occurrences and function
  applications, and no quoted constants, then the [47m[member][0m term is
  first in the term order because [47m[member][0m comes before [47m[reverse][0m in
  the term order (which is here reduced to alphabetic ordering).

  It remains to discuss the notion of [3mpseudo-function application
  count[0m.

  Clearly, two constants are ordered using cases (c) and (d) of term
  order, since they each contain 0 variable occurrences and no
  function calls.  This raises the question ``How many function
  applications are in a constant?'' Because we regard the number of
  function applications as a more fundamental measure of the size of
  a constant than lexicographic considerations, we decided that for
  the purposes of term order, constants would be seen as being built
  by primitive constructor functions.  These constructor functions
  are not actually defined in ACL2 but merely imagined for the
  purposes of term order.  We here use suggestive names for these
  imagined functions, ignoring entirely the prior use of these names
  within ACL2.  The imagined applications of these functions are what
  we refer to as [3mpseudo-function[0m applications.

  The constant function [47mz[0m constructs [47m0[0m.  Positive integers are
  constructed from [47m(z)[0m by the successor function, [47ms[0m.  Thus [47m2[0m is [47m(s (s
  (z)))[0m and contains three function applications.  [47m100[0m contains one
  hundred and one applications.  Negative integers are constructed
  from their positive counterparts by [47m[-][0m.  Thus, [47m-2[0m is [47m(- (s (s
  (z))))[0m and has four applications.  Ratios are constructed by the
  dyadic function [47m[/][0m.  Thus, [47m-1/2[0m is

    (/ (- (s (z))) (s (s (z))))

  and contains seven applications.  Complex rationals are similarly
  constructed from rationals.  All character objects are considered
  primitive and are constructed by constant functions of the same
  name.  Thus [47m#\\a[0m and [47m#\\b[0m both contain one application.  Strings are
  built from the empty string, [47m(o)[0m by the ``string-cons'' function
  written [47mcs[0m.  Thus [47m\"AB\"[0m is [47m(cs (#\\a) (cs (#\\b) (o)))[0m and contains
  five applications.  Symbols are obtained from strings by
  ``packing'' the [47m[symbol-name][0m with the unary function [47mp[0m.  Thus [47m'ab[0m
  is

    (p (cs (#\\a) (cs (#\\b) (o))))

  and has six applications.  Note that packages are here ignored and
  thus [47m'acl2::ab[0m and [47m'my-package::ab[0m each contain just six
  applications.  Finally, [cons]es are built with [47m[cons][0m, as usual.
  So [47m'(1 . 2)[0m is [47m(cons '1 '2)[0m and contains six applications, since [47m'1[0m
  contains two and [47m'2[0m contains three.  This, for better or worse,
  answers the question ``How many function applications are in a
  constant?''

  Finally, when we refer to the ``pseudo-function application count'',
  we mean the number of pseudo-function applications as described
  above, except that we bound this number by the constant
  [47m(fn-count-evg-max-val)[0m.  (This bound is important for efficiency,
  so that constants that are very large [47mcons[0m structures do not cause
  significant slowdown as ACL2 attempts to walk through them while
  computing their pseudo-function application count.)")
 (TERM-TABLE
  (META)
  "A table used to validate meta rules

    Example:
    (table term-table t '((binary-+ x y) '3 'nil (car x)))

  See [table] for a general discussion of tables and the [47mtable[0m event
  used to manipulate tables.

  The ``[47mterm-table[0m'' is used at the time a meta rule is checked for
  syntactic correctness.  Each proposed metafunction is run on each
  term in this table, and the result in each case is checked to make
  sure that it is a [47mtermp[0m in the current world.  In each case where
  this test fails, a warning is printed.

  By default, when a metafunction is run in support of the application
  of a meta rule, the result must be a term (see [47m[termp][0m) in the
  current world.  When the result is not a term, a hard error arises.
  (However, see the last paragraph below.)  The [47mterm-table[0m is simply
  a means for providing feedback to the user at the time a meta rule
  is submitted, warning of the definite possibility that such a hard
  error will occur at some point in the future.

  The key used in [47mterm-table[0m is arbitrary.  The top-most value is
  always the one that is used; it is the entire list of terms to be
  considered.  Each must be a [47mtermp[0m in the current ACL2 world.

  The runtime check on the output of metafunctions can be avoided by
  proving that it will always succeed (see
  [well-formedness-guarantee]) or by telling ACL2 to skip the test at
  the risk of soundness (see [47m[set-skip-meta-termp-checks][0m).")
 (TERMIFY
  (TERM)
  "the process of converting a clause to a term

  The ACL2 prover represents its goals and subgoals as [clause]s, e.g.,
  lists of [term]s treated as disjunctions.  The individual elements
  of a clause are called [3mliterals[0m.  For example a goal printed as
  [47m(IMPLIES (AND p q) r)[0m is internally represented as the 3-literal
  clause [47m((NOT p) (NOT q) r)[0m.  A clause containing just one literal
  is called a [3munit clause[0m.

  To [3mtermify[0m a clause containing multiple literals, we convert the
  clause to a unit clause using [47mIF[0m to express the disjunction.  For
  example, the 3-literal clause [47m((NOT p) (NOT q) r)[0m is
  propositionally equivalent to the term [47m(IF (NOT P) 'T (IF (NOT Q)
  'T R))[0m.  By embedding that [47mIF[0m-term in a singleton list we obtain a
  unit clause equivalent to the original 3-literal clause.

  Applying an induction scheme to a clause containing multiple literals
  can produce an exponential number of cases.  This does not happen
  if the clause is a unit clause.  So the ACL2 induction mechanism
  sometimes termifies its goal clause before applying the induction
  scheme to shift the case-analysis burden to the rest of the prover.")
 (TERMINATION-THEOREM
  (LEMMA-INSTANCE MEASURE HINTS)
  "Use a (functional instance of a) previously-proved measure theorem

  See [lemma-instance] for a discussion of [47m:termination-theorem[0m and
  [47m:termination-theorem![0m lemma instances, and see [tthm] for a related
  user-level query utility.  Also see [termination-theorem-example]
  for simple examples of the use of measure (termination) theorems in
  [hints].  For a related utility, see [make-termination-theorem].")
 (TERMINATION-THEOREM-EXAMPLE
  (LEMMA-INSTANCE MEASURE HINTS)
  "How to use a previously-proved measure theorem

  See [lemma-instance] for a discussion of [47m:termination-theorem[0m and
  [47m:termination-theorem![0m lemma instances, and see [tthm] for a related
  user-level query utility.  In this topic, we illustrate the use of
  such lemma instances to take advantage of a measure theorem already
  proved for an existing definition, when attempting to admit a new
  definition.  We present two examples: a basic one, and then another
  that shows how an existing termination theorem can be automatically
  functionally instantiated.  For a related utility, see
  [make-termination-theorem].

  The following very simple example is contrived but should get the
  main idea across.  Suppose that the following event was previously
  executed, for example when including a book, in order to define the
  log base 10 of [47mx[0m.

    (encapsulate
      ()
      (local (include-book \"arithmetic-5/top\" :dir :system))
      (defun log10 (x) ; log base 10 of x
        (if (or (zp x)
                (< x 10))
            0
          (1+ (log10 (floor x 10))))))

  Now suppose we want to admit the following definition, whose
  recursion pattern is similar to that above.  The simplest way might
  be to include the same book as above, but perhaps that is
  impossible because the [formula] for some name in that book
  conflicts with the formula for that name in the current session.
  Without that book, it could be challenging to develop lemmas that
  allow the termination proof to succeed for this proposed
  definition.  So we provide a hint, specifying the use of the
  termination theorem already proved for [47mlog10[0m, as follows.

    (defun base10-digits (x)
      (declare (xargs :hints
                      ((\"Goal\" :use ((:termination-theorem log10))))))
      (if (or (zp x)
              (< x 10))
          (list x)
        (append (base10-digits (floor x 10))
                (list (mod x 10)))))

  With this hint, the termination proof succeeds, printing the
  following line in the event [summary].

    Hint-events: ((:USE LOG10))

  This line says that the only [47m:use[0m hint was based on the event [47mlog10[0m.
  This may surprise you; perhaps you would expect to see something
  instead such as [47m(:USE (:TERMINATION-THEOREM LOG10))[0m.  However, the
  [47mHint-events[0m field of the summary is intended only to show the names
  of [events] that support the hints.  For example, if you replace
  the [47m:use[0m hint in the example above with

    :use ((:rewrite car-cons) (:termination-theorem log10))

  then the [47mHint-events[0m [summary] line will be as follows.

    Hint-events: ((:USE CAR-CONS) (:USE LOG10))

  Similarly, proof output for a [47m:use[0m hint (provided when not in
  [gag-mode]) is also given at the level of events.  For the
  definition above, we get the following output.

    We augment the goal with the hypothesis provided by the :USE hint.
    The hypothesis can be obtained from LOG10.  We are left with the following
    subgoal.

  Again, perhaps one would expect to see ``[47mobtained from the
  termination theorem for LOG10[0m''.  But for the modified hint shown
  above, using [47m(:rewrite car-cons)[0m, we similarly see only event
  names, not a [rune].

    These hypotheses can be obtained from CAR-CONS and LOG10.

  Next, we consider an example where a function symbol being defined
  occurs in the measure theorem.

    (defun left (x)
      (car x))
    (defun right (x)
      (car x))
    (defun first-natp (x)
      (if (atom x)
          (if (natp x) x nil)
        (or (first-natp (left x))
            (first-natp (right x)))))

  The measure (termination) theorem for [47mfirst-natp[0m is as follows.

    (AND (IMPLIES (NOT (ATOM X))
                  (O< (ACL2-COUNT (LEFT X))
                      (ACL2-COUNT X)))
         (IMPLIES (AND (NOT (ATOM X))
                       (NOT (FIRST-NATP (LEFT X))))
                  (O< (ACL2-COUNT (RIGHT X))
                      (ACL2-COUNT X))))

  Now suppose the functions [47mleft[0m and [47mright[0m are [disable]d and we then
  try to admit the analogous definition below.  This sort of
  situation may be common; imagine a library of books in which
  [47mfirst-natp[0m is defined followed by disabling of [47mleft[0m and [47mright[0m, and
  we have included that book in hopes of re-using the termination
  theorem.

    (in-theory (disable left right))

    (defun first-symbolp (x)
      (if (atom x)
          (if (symbolp x) x nil)
        (or (first-symbolp (left x))
            (first-symbolp (right x)))))

  This time the termination theorem is as follows.

    (AND (IMPLIES (NOT (ATOM X))
                  (O< (ACL2-COUNT (LEFT X))
                      (ACL2-COUNT X)))
         (IMPLIES (AND (NOT (ATOM X))
                       (NOT (FIRST-SYMBOLP (LEFT X))))
                  (O< (ACL2-COUNT (RIGHT X))
                      (ACL2-COUNT X))))

  Notice that this theorem is not an immediate consequence of the
  termination theorem for [47mfirst-natp[0m, because of the call
  [47mfirst-symbolp[0m in the latter that replaces the call [47mfirst-natp[0m in
  the former.  ACL2 provides support to work around this difficulty,
  however.  When you give a [47m:termination-theorem[0m [lemma-instance] in
  your :hints for the termination proof, then ACL2 automatically
  replaces the old function symbol (here, [47mfirst-natp[0m) in the old
  termination theorem by the new function symbol (here,
  [47mfirst-symbolp[0m), before applying the hint.  So the following
  definition is admitted, because the old termination theorem, thus
  modified, is exactly the new termination theorem.

    (defun first-symbolp (x)
      (declare (xargs :hints
                      ((\"Goal\" :by (:termination-theorem first-natp)))))
      (if (atom x)
          (if (symbolp x) x nil)
        (or (first-symbolp (left x))
            (first-symbolp (right x)))))

  Such a substitution is made provided the old and new function symbols
  each have the same number of formal parameters.  In general a
  [47m:termination-theorem[0m may be used for admitting either a
  singly-recursive function or a nest of mutually-recursive
  functions; the general criterion is that the number of formals must
  match for corresponding functions.

  The functional substitution can be provided explicitly.  The
  following example has identical behavior to that above.

    (defun first-symbolp (x)
      (declare (xargs :hints
                      ((\"Goal\" :by (:termination-theorem
                                    first-natp
                                    ((first-natp first-symbolp)))))))
      (if (atom x)
          (if (symbolp x) x nil)
        (or (first-symbolp (left x))
            (first-symbolp (right x)))))

  Finally, note that a [47m:by[0m hint is not guaranteed to work; a [47m:use[0m hint
  may be a bit slower, and may require the use of [47m:instance[0m (see
  [lemma-instance], but it can be more reliable.

  We conclude with a remark about what happens when the termination
  theorem does not exist, even though (as required) the indicated
  function symbol is in [logic] mode.  (For example, imagine that you
  are generating such hints programmatically, without analyzing
  whether the indicated function symbol was defined using recursion.)
  In that case, using [47m:termination-theorem[0m will fail.  Here, for
  example, is what happens if [47mf[0m was defined non-recursively.

    ACL2 !>(defun g (x)
             (declare (xargs :hints
                             ((\"Goal\" :use ((:termination-theorem f))))))
             (if (consp x)
                 (g (cddr x))
               x))


    ACL2 Error in ( DEFUN G ...):  The object (:TERMINATION-THEOREM F)
    is an ill-formed lemma instance because there is no termination theorem
    for F.  The function F is not recursive.  See :DOC lemma-instance.


    Summary
    Form:  ( DEFUN G ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

    ACL2 Error in ( DEFUN G ...):  See :DOC failure.

    ******** FAILED ********
    ACL2 !>

  The alternative, [47m:termination-theorem![0m, is provided in order to avoid
  this sort of error.  Here is the corresponding (edited) log, with
  [gag-mode] off.  Notice that since there is no termination theorem
  stored for [47mf[0m, the [47m:use[0m hint specifies the use of [47mT[0m for the
  termination theorem.

    ACL2 !>(defun g (x)
             (declare (xargs :hints
                             ((\"Goal\" :use ((:termination-theorem! f))))))
             (if (consp x)
                 (g (cddr x))
               x))

    For the admission of G 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

    Goal
    (IMPLIES (CONSP X)
             (O< (ACL2-COUNT (CDDR X))
                 (ACL2-COUNT X))).

    [Note:  A hint was supplied for the goal above.  Thanks!]

    We augment the goal with the hypothesis provided by the :USE hint.
    The hypothesis can be obtained from F.  We are left with the following
    subgoal.

    Goal'
    (IMPLIES T
             (OR (NOT (CONSP X))
                 (O< (ACL2-COUNT (CDDR X))
                     (ACL2-COUNT X)))).

    By case analysis we reduce the conjecture to

    [[.. output elided ..]]

    Hint-events: ((:USE F))
    Time:  0.02 seconds (prove: 0.01, print: 0.01, other: 0.00)
    Prover steps counted:  1121
     G
    ACL2 !>")
 (TERMP
  (TERM ACL2-BUILT-INS)
  "recognizer for the quotation of a [term]

    Example:
    (termp '(CAR (CONS X Y)) (w state))

    General Form:
    (termp x w)

  where [47mx[0m is any ACL2 object and [47mw[0m is an ACL2 logical [world].  The
  result is [47mt[0m or [47mnil[0m according to whether [47mx[0m is the quotation of a
  translated (well-formed) term in the [world], [47mw[0m.  See [term] for a
  discussion of translated terms.

  Each metafunction (see [47m[meta][0m) is supposed to take (the quotation of)
  a translated term as input and yield (the quotation of) a
  translated term as output.  When a metafunction is run by the
  simplifier its input is guaranteed to be well-formed by invariants
  maintained by ACL2.  But its output is checked by an explicit call
  of [47mtermp[0m unless the user has proved that the metafunction always
  returns a term (see [well-formedness-guarantee]) or has taken the
  risk of disabling the runtime test with
  [47m[set-skip-meta-termp-checks][0m.

  [47m[Termp][0m is mutually recursive with [47m[term-listp][0m.

  [31;1mFunction: [0m<termp>

    (defun termp (x w)
      (declare (xargs :guard (plist-worldp-with-formals w)))
      (cond ((atom x) (legal-variablep x))
            ((eq (car x) 'quote)
             (and (consp (cdr x)) (null (cddr x))))
            ((symbolp (car x))
             (let ((arity (arity (car x) w)))
               (and arity (term-listp (cdr x) w)
                    (eql (length (cdr x)) arity))))
            ((and (consp (car x))
                  (true-listp (car x))
                  (eq (car (car x)) 'lambda)
                  (eql 3 (length (car x)))
                  (arglistp (cadr (car x)))
                  (termp (caddr (car x)) w)
                  (null (set-difference-eq (all-vars (caddr (car x)))
                                           (cadr (car x))))
                  (term-listp (cdr x) w)
                  (eql (length (cadr (car x)))
                       (length (cdr x))))
             t)
            (t nil)))

  [31;1mFunction: [0m<term-listp>

    (defun term-listp (x w)
      (declare (xargs :guard (plist-worldp-with-formals w)))
      (cond ((atom x) (equal x nil))
            ((termp (car x) w)
             (term-listp (cdr x) w))
            (t nil)))


Subtopics

  [Logic-fns-list-listp]
      Recognizer for when a given list of lists of [term]s calls only
      [47m:[0m[47m[logic][0m-mode function symbols

  [Logic-fns-listp]
      Recognizer for when a given list of [term]s calls only [47m:[0m[47m[logic][0m-mode
      function symbols

  [Logic-fnsp]
      Recognizer for when a given [term] calls only [47m:[0m[47m[logic][0m-mode function
      symbols

  [Logic-term-list-listp]
      Recognizer for lists of lists of [term]s that call only
      [47m:[0m[47m[logic][0m-mode function symbols

  [Logic-term-listp]
      Recognizer for lists of [term]s that call only [47m:[0m[47m[logic][0m-mode
      function symbols

  [Logic-termp]
      Recognizer for [term]s that call only [47m:[0m[47m[logic][0m-mode function symbols")
 (THE
  (GUARD COMPILATION ACL2-BUILT-INS)
  "Special form for execution efficiency or run-time type checks

  [47mTHE[0m is a Common Lisp special form.  It is usually used as a way to
  boost performance by telling the Common Lisp compiler that a
  certain expression will always produce a result of a certain type.
  This information may allow the Common Lisp compiler to avoid
  certain run-time checks.  When evaluating code directly in the
  top-level loop or in [47m:[0m[47m[logic][0m-mode functions that have not been
  [guard]-verified, [47mTHE[0m can perform run-time type checks.  See
  [declare] and [type-spec] for general, related background.

  General form:

    (the <typ> <val>)   ;; returns <val>, or causes a run-time error

    * [47m<typ>[0m is a [type-spec]

    * [47m<val>[0m is some expression that should produce a value of that type.

  Typical example:

    (defun merge-bytes (b1 b2)
      ;; Combine two 8-bit bytes into a 16-bit result.
      (declare (type (unsigned-byte-p 8) b1 b2))
      (the (unsigned-byte 16)
           (logior (the (unsigned-byte 16) (ash b1 8))
                   b2)))

  On most Lisp implementations 16-bit numbers are fixnums.  The [47mTHE[0m
  forms above are promises to the Lisp compiler that these [47mash[0m and
  [47mlogior[0m operations will always produce 16-bit numbers.  Ideally, the
  compiler could use this information to generate more efficient
  code, i.e., by omitting whatever code is normally required to
  handle bignum results.  (Of course, a sufficiently smart compiler
  could have figured this out on its own; in practice Lisp compilers
  vary in their reasoning abilities.)


Relation to Guards

  To justify that type declarations are correct, [47mTHE[0m is integrated into
  ACL2's [guard] mechanism.  A call of [47m(the TYPE EXPR)[0m in the body of
  a function definition generates a guard proof obligation that the
  type, [47mTYPE[0m, holds for the value of the expression, [47mEXPR[0m.  Consider
  the following example.

    (defun f (x)
      (declare (xargs :guard (p1 x)))
      (if (p2 x)
          (the integer (h x))
        17))

  The [guard] proof obligation generated for the [47mTHE[0m expression above
  is as follows.

    (implies (and (p1 x) (p2 x))
             (let ((var (h x))) (integerp var)))

  For [47mTHE[0m to provide any execution speed benefit, [guard]s must be
  verified (see [VERIFY-GUARDS]).

  In contexts where guards have [3mnot[0m been verified, [47mTHE[0m acts as a
  low-level, run-time type check that [47mval[0m satisfies the type
  specification [47mtyp[0m (see [type-spec]).  An error is caused if the
  check fails; otherwise, [47mval[0m is returned.  Here are some examples:

    (the integer 3)       ; returns 3
    (the (integer 0 6) 3) ; returns 3
    (the (integer 0 6) 7) ; causes an error (see below for exception)

  There is an exception to the rule that failure of the type-check
  causes an error: there is no error when [guard]-checking has been
  turned off, that is, in any of the following ways; also
  [set-guard-checking] and see [with-guard-checking].

    * [47m:set-guard-checking nil[0m

    * [47m(with-guard-checking nil ...)[0m

    * [47m:set-guard-checking :none[0m

    * [47m(with-guard-checking :none ...)[0m


Further resources

  The [b*] macro provides a special syntax that may make using [47mTHE[0m
  forms more pleasant; see [patbind-the] for more information.

  When optimizing functions with type declarations, you may wish to
  manually inspect the compiler's output with [disassemble$] or
  conduct experiments to measure the impact of your optimizations.

  A term of the form [47m(the double-float <term>)[0m will assist ACL2's
  syntax checking by telling ACL2 that [47m<term>[0m returns a df.  See [df]
  for relevant background.

  [47mTHE[0m is defined in Common Lisp.  See any Common Lisp documentation for
  more information.


Subtopics

  [Type-spec]
      Type specifiers can be used in Common Lisp type declarations and
      [the] forms, and may result in improved efficiency of
      execution.")
 (THE-METHOD
  (ACL2-TUTORIAL)
  "How to find proofs

  Also see [introduction-to-the-theorem-prover] for a more detailed
  tutorial on how to prove theorems with ACL2.

  Many users develop proof scripts in an Emacs buffer and submit one
  event at a time to the theorem prover running in a [47m*shell*[0m buffer.
  The script buffer is logically divided into two regions: the events
  that have been accepted by the theorem prover and those that have
  not yet been accepted.  An imaginary ``barrier'' divides these two
  regions.  The region above the barrier describes the state of the
  [47m*shell*[0m buffer (and ACL2's logical world).  The region below the
  barrier is the ``to do'' list.

  We usually start a proof project by typing the key lemmas, and main
  goal into the to do list.  Definitions are here just regarded as
  theorems to prove (i.e., the measure conjectures).  Then we follow
  ``The Method.''

  (1) Think about the proof of the first theorem in the to do list.
  Structure the proof either as an induction followed by
  simplification or just simplification.  Have the necessary lemmas
  been proved? That is, are the necessary lemmas in the done list
  already?  If so, proceed to Step 2.  Otherwise, add the necessary
  lemmas at the front of the to do list and repeat Step 1.

  (2) Call the theorem prover on the first theorem in the to do list
  and let the output stream into the *shell* buffer.  Abort the proof
  if it runs more than a few seconds.

  (3) If the theorem prover succeeded, advance the barrier past the
  successful command and go to Step 1.

  (4) Otherwise, inspect the failed proof attempt, starting from the
  beginning, not the end.  Basically you should look for the first
  place the proof attempt deviates from your imagined proof.  If your
  imagined proof was inductive, inspect the induction scheme used by
  ACL2.  If that is ok, then find the first subsequent subgoal that
  is stable under simplification and think about why it was not
  proved by the simplifier.  If your imagined proof was not
  inductive, then think about the first subgoal stable under
  simplification, as above.  Modify the script appropriately.  It
  usually means adding lemmas to the to do list, just in front of the
  theorem just tried.  It could mean adding hints to the current
  theorem.  In any case, after the modifications go to Step 1.

  We do not seriously suggest that this or any rotely applied algorithm
  will let you drive ACL2 to difficult proofs.  Indeed, to remind you
  of this we call this ``The Method'' rather than ``the method.''
  That is, we are aware of the somewhat pretentious nature of any
  such advice.  But these remarks have helped many users approach
  ACL2 in a constructive and disciplined way.

  We say much more about The Method in the ACL2 book.  See the home
  page.  Also see [set-gag-mode] for a discussion of a way for ACL2
  to help you to use The Method.  And again, see
  [introduction-to-the-theorem-prover] for a more detailed tutorial.

  Learning to read failed proofs is a useful skill.  There are several
  kinds of ``checkpoints'' in a proof: (1) a formula to which
  induction is being (or would be) applied, (2) the first formula
  stable under simplification, (3) a formula that is possibly
  generalized, either by cross-fertilizing with and throwing away an
  equivalence hypothesis or by explicit generalization of a term with
  a new variable.

  At the induction checkpoint, confirm that you believe the formula
  being proved is a theorem and that it is appropriately strong for
  an inductive proof.  Read the selected induction scheme and make
  sure it agrees with your idea of how the proof should go.

  At the post-simplification checkpoint, which is probably the most
  commonly seen, consider whether there are additional rewrite rules
  you could prove to make the formula simplify still further.  Look
  for compositions of function symbols you could rewrite.  Look for
  contradictions among hypotheses and prove the appropriate
  implications: for example, the checkpoint might contain the two
  hypotheses [47m(P (F A))[0m and [47m(NOT (Q (G (F A))))[0m and you might realize
  that [47m(implies (p x) (q (g x)))[0m is a theorem.  Look for signs that
  your existing rules did not apply, e.g., for terms that should have
  been rewritten, and figure out why they were not.  Possible causes
  include that they do not exactly match your old rules, that your
  old rules have hypotheses that cannot be relieved here --- perhaps
  because some other rules are missing, or perhaps your old rules are
  disabled.  If you cannot find any further simplifications to make
  in the formula, ask yourself whether it is valid.  If so, sketch a
  proof.  Perhaps the proof is by appeal to a combination of lemmas
  you should now prove?

  At the two generalization checkpoints --- where hypotheses are
  discarded or terms are replaced by variables --- ask yourself
  whether the result is a theorem.  It often is not.  Think about
  rewrite rules that would prove the formula.  These are often
  restricted versions of the overly-general formulas created by the
  system's heuristics.

  See [proof-tree] for a discussion of a tool to help you navigate
  through ACL2 proofs.")
 (THE-NUMBER
  (NUMBERS ACL2-BUILT-INS)
  "Coerce an expected number to a number

  Like [47m[fix][0m, [47mthe-number[0m logically returns its argument unchanged if
  that argument is numeric and [47m0[0m otherwise.  Unlike [47mfix[0m, the [guard]
  for [47m(the-number x)[0m is [47m(acl2-numberp x)[0m, and [47m(the-number x)[0m
  evaluates to [47mx[0m in raw Lisp (see [guards-and-evaluation] for
  relevant discussion).

  [31;1mFunction: [0m<the-number>

    (defun the-number (x)
      (declare (xargs :guard (acl2-numberp x)))
      (mbe :logic (fix x) :exec x))")
 (THE-TRUE-LIST
  (TRUE-LISTP ACL2-BUILT-INS)
  "Coerce an expected true list to a true list

  Like [47m[true-list-fix][0m, [47mthe-true-list[0m logically returns its argument
  unchanged if that argument satisfies [47m[true-listp][0m and otherwise
  returns a corresponding ``fixed'' true list.  Unlike [47mtrue-list-fix[0m,
  the [guard] for [47m(the-true-list x)[0m is [47m(true-listp x)[0m, and
  [47m(the-true-list x)[0m evaluates immediately to [47mx[0m in raw Lisp (see
  [guards-and-evaluation] for relevant discussion).

  [31;1mFunction: [0m<the-true-list>

    (defun the-true-list (x)
      (declare (xargs :guard (true-listp x)))
      (mbe :logic (true-list-fix x) :exec x))")
 (THEORIES
  (ACL2)
  "Sets of [rune]s to [enable]/[disable] in concert

    Example: '((:definition app) ; or (:d app)
               (:executable-counterpart app)
               (:i app)
               rv
               (rv)
               (:r assoc-of-app))

  See:

  A theory is a list of ``runic designators'' as described below.  Each
  runic designator denotes a set of ``runes'' (see [rune]) and by
  unioning together the runes denoted by each member of a theory we
  define the set of runes corresponding to a theory.  Theories are
  used to control which rules are ``[enable]d,'' i.e., available for
  automatic application by the theorem prover.  There is always a
  ``current'' theory.  A rule is [enable]d precisely if its [rune] is
  an element of the set of [rune]s corresponding to the current
  theory.  At the top-level, the current theory is the theory
  selected by the most recent [47m[in-theory][0m event, extended with the
  rule names introduced since then.  Inside the theorem prover, the
  [47m:[0m[47m[in-theory][0m hint (see [hints]) can be used to select a particular
  theory as current during the proof attempt for a particular goal.

  Theories are generally constructed by ``theory expressions.''
  Formally, a theory expression is any term, containing at most the
  single free variable [47m[world][0m, that when evaluated with [47m[world][0m
  bound to the current ACL2 world (see [world]) produces a theory.
  ACL2 provides various functions for the convenient construction and
  manipulation of theories.  These are called ``theory functions''
  (see [theory-functions]).  For example, the theory function
  [47m[union-theories][0m takes two theories and produces their union.  The
  theory function [47m[universal-theory][0m returns the theory containing
  all known rule names as of the introduction of a given logical
  name.  But a theory expression can contain constants, e.g.,

    '(len (len) (:rewrite car-cons) car-cdr-elim)

  and user-defined functions.  The only important criterion is that a
  theory expression mention no variable freely except [47m[world][0m and
  evaluate to a theory.

  More often than not, theory expressions typed by the user do not
  mention the variable [47m[world][0m.  This is because user-typed theory
  expressions are generally composed of applications of ACL2's theory
  functions.  These ``functions'' are actually macros that expand
  into terms in which [47m[world][0m is used freely and appropriately.
  Thus, the technical definition of ``theory expression'' should not
  mislead you into thinking that interesting theory expressions must
  mention [47m[world][0m; they probably do and you just didn't know it!

  One aspect of this arrangement is that theory expressions cannot
  generally be evaluated at the top-level of ACL2, because [47m[world][0m is
  not bound.  To see the value of a theory expression, [47mexpr[0m, at the
  top-level, type

    ACL2 !>(LET ((WORLD (W STATE))) expr).

  However, because the built-in theories are quite long, you may be
  sorry you printed the value of a theory expression!

  A theory is a true list of runic designators and to each theory there
  corresponds a set of [rune]s, obtained by unioning together the
  sets of [rune]s denoted by each runic designator.  For example, the
  theory constant

    '(len (len) (:e nth) (:rewrite car-cons) car-cdr-elim)

  corresponds to the set of [rune]s

    {(:definition len)
     (:induction len)
     (:executable-counterpart len)
     (:executable-counterpart nth)
     (:rewrite car-cons)
     (:elim car-cdr-elim)} .

  Observe that the theory contains five elements but its runic
  correspondent contains six.  That is because runic designators can
  denote sets of several [rune]s, as is the case for the first
  designator, [47mlen[0m.  If the above theory were selected as current then
  the six rules named in its runic counterpart would be [enable]d and
  all other rules would be [disable]d.

  We now precisely define the runic designators and the set of [rune]s
  denoted by each.  When we refer below to the ``macro-aliases
  dereference of'' a symbol, [47msymb[0m, we mean the (function) symbol
  corresponding to [47msymb[0m in the macro-aliases-table if there is such a
  symbol, else [47msymb[0m itself; see [macro-aliases-table].  For example,
  the macro-aliases dereference of [47m[append][0m is [47m[binary-append][0m, and
  the macro-aliases dereference of [47m[nth][0m is [47mnth[0m.

    * A [rune] is a runic designator and denotes the singleton set
      containing that rune.

    * Suppose that [47msymb[0m is a symbol and [47msymb'[0m is the macro-aliases
      dereference of [47msymb[0m, where [47msymb'[0m is a function symbol
      introduced with a [47m[defun][0m (or [47m[defuns][0m) event.  Then [47msymb[0m is a
      runic designator and denotes the set containing the runes
      [47m(:definition symb')[0m and [47m(:induction symb')[0m, omitting the latter
      if no such [induction] rune exists (presumably because the
      definition of [47msymb'[0m is not singly recursive).

    * Suppose that [47msymb[0m is a symbol and [47msymb'[0m is the macro-aliases
      dereference of [47msymb[0m, where [47msymb'[0m is a function symbol
      introduced with a [47m[defun][0m (or [47m[defuns][0m) event.  Then [47m(symb)[0m is
      a runic designator and denotes the singleton set containing the
      rune [47m(:executable-counterpart symb')[0m.

    * If [47msymb[0m is the name of a [47m[defthm][0m (or [47m[defaxiom][0m) event that
      introduced at least one rule, then [47msymb[0m is a runic designator
      and denotes the set of the names of all rules introduced by the
      named event.

    * If [47mstr[0m is the string naming some [47m[defpkg][0m event and [47msymb[0m is the
      symbol returned by [47m(intern (concatenate 'string str \"-PACKAGE\")
      \"ACL2\")[0m, then [47msymb[0m is a runic designator and denotes the
      singleton set containing [47m(:rewrite symb)[0m, which is the name of
      the rule stating the conditions under which the
      [47m[symbol-package-name][0m of [47m(intern x str)[0m is [47mstr[0m.

    * If [47msymb[0m is the name of a [47m[deftheory][0m event, then [47msymb[0m is a runic
      designator and denotes the runic theory (as defined below)
      corresponding to [47msymb[0m.

    * Finally, suppose that [47msymb[0m is a symbol and [47msymb'[0m is the macro-aliases
      dereference of [47msymb[0m.  Then [47m(:KWD symb . rest)[0m is a runic
      designator, known as a ``runic abbreviation'', if [47m(:KWD' symb'
      . rest)[0m is a [rune], where: [47m:KWD[0m is one of [47m:d[0m, [47m:e[0m, [47m:i[0m, [47m:r[0m, or
      [47m:t[0m; and [47m:KWD'[0m is [47m:definition[0m, [47m:executable-counterpart[0m,
      [47m:induction[0m, [47m:rewrite[0m, or [47m:type-prescription[0m, respectively.  In
      this case, [47m(:KWD symb . rest)[0m denotes the runic theory (as
      defined below) corresponding to the rune [47m(:KWD' symb' . rest)[0m.

  Note that including a function name, e.g., [47m[len][0m, in the current
  theory [enable]s that function but does not [enable] the
  [executable-counterpart].  Similarly, including [47m(len)[0m or [47m(:e len)[0m
  [enable]s the executable-counterpart but not the symbolic
  definition.  And including the name of a proved lemma [enable]s all
  of the rules added by the event.  Of course, one can include
  explicitly the [rune]s naming the rules in question and so can
  avoid entirely the use of non-runic elements in theories.

  Because a [rune] is a runic designator denoting the set containing
  that [rune], a list of [rune]s is a theory and denotes itself.
  There is a natural ``canonical'' ordering of runes by order of
  their creation.  We call a canonically ordered true list of runes a
  ``runic theory.'' To every theory there corresponds a runic theory,
  sometimes called its runic correspondent, obtained by unioning
  together the sets denoted by each designator in the theory.  When a
  theory is selected as ``current'' it is actually its runic
  correspondent that is effectively used.  That is, a [rune] is
  [enable]d iff it is a member of the runic correspondent of the
  current theory.  The value of a theory defined with [47m[deftheory][0m is
  the runic correspondent of the theory computed by the defining
  theory expression.  The theory manipulation functions, e.g.,
  [47m[union-theories][0m, actually convert their theory arguments to their
  runic correspondents before performing the required set operation.
  The manipulation functions always return runic theories.  Thus, it
  is sometimes convenient to think of (non-runic) theories as merely
  abbreviations for their runic correspondents, abbreviations which
  are ``expanded'' at the first opportunity by theory manipulation
  functions and the ``theory consumer'' functions such as [47m[in-theory][0m
  and [47m[deftheory][0m.


Subtopics

  [Active-or-non-runep]
      Require a [rune] to exist, and check that it is [enable]d

  [Active-runep]
      Check that a [rune] exists and is [enable]d

  [Current-theory]
      Currently [enable]d rules as of logical name

  [Deftheory]
      Define a theory (to [enable] or [disable] a set of rules)

  [Deftheory-static]
      Define a `static' theory (to [enable] or [disable] a set of rules)

  [Defthy]
      Define a theory (to [enable] or [disable] a set of rules)

  [Disable]
      Deletes names from current theory

  [Disabledp]
      Determine whether a given name or rune is disabled

  [E/d]
      Enable/disable rules

  [Enable]
      Adds names to current theory

  [Executable-counterpart-theory]
      [Executable-counterpart] rules as of logical name

  [Function-theory]
      Function symbol rules as of logical name

  [Ground-zero]
      [enable]d rules in the [startup] theory

  [Hands-off-lambda-objects-theory]
      how to specify no modification of lambda objects

  [In-theory]
      Designate ``current'' theory (enabling its rules)

  [Incompatible]
      Declaring that two rules should not both be [enable]d

  [Incompatible!]
      Declaring that two rules must exist and should not both be [enable]d

  [Intersection-theories]
      Intersect two [theories]

  [Minimal-theory]
      A minimal theory to enable

  [Rewrite-lambda-objects-theory]
      how to specify rewriting of lambda objects

  [Rule-names]
      How rules are named.

  [Rune]
      A rule name

  [Set-difference-theories]
      Difference of two [theories]

  [Syntactically-clean-lambda-objects-theory]
      how to specify syntactic cleaning of lambda objects

  [Theories-and-primitives]
      Warnings from disabling or enabling certain built-in functions

  [Theory]
      Retrieve named theory

  [Theory-functions]
      Functions for obtaining or producing [theories]

  [Union-theories]
      Union two [theories]

  [Universal-theory]
      All rules as of logical name

  [Using-enabled-rules]
      Avoiding [47m:use[0m [hints] for [enable]d [47m:[0m[47m[rewrite][0m rules")
 (THEORIES-AND-PRIMITIVES
  (THEORIES)
  "Warnings from disabling or enabling certain built-in functions

  When you [disable] the [definition] or [executable-counterpart] of a
  built-in function, you may see a warning, for example as follows.

    ACL2 !>(in-theory (disable mv-nth iff length))

    ACL2 Warning [Theory] in ( IN-THEORY (DISABLE ...)):  The :DEFINITION
    rules for the built-in functions MV-NTH and IFF are disabled by the
    theory expression (DISABLE MV-NTH IFF LENGTH), but some expansions
    of their calls may still occur.  See :DOC theories-and-primitives.

  This warning is telling us that the built-in functions [47m[mv-nth][0m and
  [47m[iff][0m are given certain special handling, hence their calls may be
  expanded even when their definitions are disabled.  This behavior
  applies to the functions in the list obtained by evaluating the
  constant, [47m*definition-minimal-theory*[0m.

  These warnings can be eliminated by turning off all theory warnings
  (see [set-inhibit-warnings]) or even turning off all warnings (see
  [set-inhibit-output-lst]), or simply by evaluating the following
  form.

    (assign verbose-theory-warning nil)

  But before you eliminate such theory warnings, you may wish to read
  the following to gain more understanding of their significance.

  First consider the following example, evaluated after the [47m[in-theory][0m
  event displayed above.

    ACL2 !>(thm (equal (mv-nth 2 (list a b c d e)) c))

    Q.E.D.

    Summary
    Form:  ( THM ...)
    Rules: ((:DEFINITION MV-NTH)
            (:FAKE-RUNE-FOR-TYPE-SET NIL))
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
    Prover steps counted:  18

    Proof succeeded.
    ACL2 !>

  Note that even though the [definition] of [47m[mv-nth][0m had been
  [disable]d, nevertheless its definition rule was used in proving
  this theorem.  It is as though [47m[mv-nth][0m had not been disabled after
  all!  The warning is intended to indicate that expansion of [47mmv-nth[0m
  calls may be made by the theorem prover even when [47mmv-nth[0m is
  disabled.  Indeed, the prover has special-purpose code for
  simplifying certain [47mmv-nth[0m calls.

  A similar issue can arise for [47mexecutable-counterpart[0m rules, as the
  following log illustrates.

    ACL2 !>(in-theory (disable (:e symbolp)))

    ACL2 Warning [Theory] in ( IN-THEORY (DISABLE ...)):  The :EXECUTABLE-
    COUNTERPART rule for the built-in function SYMBOLP is disabled by the
    theory expression (DISABLE (:E SYMBOLP)), but some evaluations of its
    calls may still occur.  See :DOC theories-and-primitives.


    Summary
    Form:  ( IN-THEORY (DISABLE ...))
    Rules: NIL
    Warnings:  Theory
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
     (:NUMBER-OF-ENABLED-RUNES 4268)
    ACL2 !>(thm (symbolp 'a))

    Q.E.D.

    Summary
    Form:  ( THM ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

    Proof succeeded.
    ACL2 !>

  In general, ACL2 warns when [47m[in-theory][0m [events] or [hints] leave you
  in a theory where rules for certain built-in functions have just
  been disabled, yet these rules may be applied in some cases
  nonetheless, because of special-purpose prover code for handling
  calls of that function.  The built-in function symbols with such
  [definition] rules or [executable-counterpart] rules are those in
  the following two lists, which are the respective values of
  built-in constants [47m*definition-minimal-theory*[0m and
  [47m*built-in-executable-counterparts*[0m.

  [31;1mDefinition: [0m<*definition-minimal-theory*>

    (defconst *definition-minimal-theory*
      (list* 'mv-nth
             'iff
             *expandable-boot-strap-non-rec-fns*))

  [31;1mDefinition: [0m<*built-in-executable-counterparts*>

    (defconst *built-in-executable-counterparts*
      '(acl2-numberp binary-* binary-+ unary-- unary-/
                     < car cdr char-code characterp code-char
                     complex complex-rationalp coerce
                     cons consp denominator equal if imagpart
                     integerp intern-in-package-of-symbol
                     numerator pkg-witness pkg-imports
                     rationalp realpart stringp symbol-name
                     symbol-package-name symbolp not))

  A third class of warnings pertains to [primitive]s that do not have
  definitions, such as [47mcons[0m.  Here is an example of such a warning,
  for the event [47m(in-theory (disable cons))[0m.

    ACL2 Warning [Theory] in ( IN-THEORY (DISABLE ...)):  There is no effect
    from disabling or enabling :DEFINITION rules for primitive functions
    (see :DOC primitive).  For the expression (DISABLE CONS), the attempt
    to disable CONS will therefore have no effect for its definition.
    See :DOC theories-and-primitives.

  Unlike the warnings discussed above, warnings about primitives can
  occur not only when disabling definitions but also when enabling
  them.  Here is what happens when we submit [47m(in-theory (enable
  cons))[0m immediately after the event just above.

    ACL2 Warning [Theory] in ( IN-THEORY (ENABLE ...)):  There is no effect
    from disabling or enabling :DEFINITION rules for primitive functions
    (see :DOC primitive).  For the expression (ENABLE CONS), the attempt
    to enable CONS will therefore have no effect for its definition.  See
    :DOC theories-and-primitives.

  If however we submit [47m(in-theory (enable cons))[0m again, or in a fresh
  session, there is no warning.  To see why, understand that all of
  these warnings are based on a comparison of the preceding current
  [theory] with the new one.  If [47mcons[0m is already enabled, then
  [47m(in-theory (enable cons))[0m is a no-op; hence, there is no warning.

  There is another case in which there is no warning: if all
  definitions of primitives transition from disabled to enabled, or
  vice-versa.  For example, such a transition occurs for consecutive
  events [47m(in-theory (current-theory 'ground-zero))[0m and [47m(in-theory
  (theory 'minimal-theory))[0m.

  We conclude with a note for advanced users only.  You can eliminate
  all special treatment discussed above for expanding the definition
  of [47m[mv-nth][0m (but not for any of the other primitives listed above)
  by evaluating the following form (also see [defattach-system]).

    (defattach-system simplifiable-mv-nth-p constant-nil-function-arity-0)

  That said, this is probably only useful for very specific cases of
  ``system-level'' programming.  You can restore the default behavior
  as follows.

    (defattach-system simplifiable-mv-nth-p constant-t-function-arity-0)")
 (THEORY
  (THEORIES THEORY-FUNCTIONS)
  "Retrieve named theory

  Examples:

  [3mFor use in [47m[in-theory][0m[3m [events] or [47m:in-theory[0m[3m [hints]:[0m
  [47m(theory 'ground-zero)[0m

  [3mFor direct evaluation at the top-level loop:[0m
  [47m(let ((world (w state))) (theory 'ground-zero))[0m

  In the examples above, the theory returned is the one in force when
  ACL2 is started up (see [ground-zero]).

    General Form:
    (theory name)

  where [47mname[0m is the name of a previously executed [47m[deftheory][0m event
  (otherwise a hard error occurs).  Returns the named theory.  See
  [theories].

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].")
 (THEORY-FUNCTIONS
  (THEORIES)
  "Functions for obtaining or producing [theories]

    Example Calls of Theory Functions:
    (universal-theory :here)
    (union-theories th1 th2)
    (set-difference-theories th1 th2)

  The theory functions are documented individually:

  The functions (actually, macros) mentioned above are convenient ways
  to produce [theories].  (See [theories].) Some, like
  [47m[universal-theory][0m, take a logical name (see [logical-name]) as an
  argument and return the relevant theory as of the time that name
  was introduced.  Others, like [47m[union-theories][0m, take two [theories]
  and produce a new one.  See [redundant-events] for a caution about
  the use of logical names in theory expressions.

  Theory expressions are generally composed of applications of theory
  functions.  Formally, theory expressions are expressions that
  involve, at most, the free variable [47m[world][0m and that when evaluated
  with [47m[world][0m bound to the current ACL2 world (see [world]) return
  [theories].  The ``theory functions'' are actually macros that
  expand into forms that involve the free variable [47m[world][0m.  Thus,
  for example [47m(universal-theory :here)[0m actually expands to
  [47m(universal-theory-fn :here world)[0m and when that form is evaluated
  with [47m[world][0m bound to the current ACL2 [world], [47muniversal-theory-fn[0m
  scans the ACL2 property lists and computes the current universal
  theory.  Because the theory functions all implicitly use [47m[world][0m,
  the variable does not generally appear in anything the user types.


Subtopics

  [Current-theory]
      Currently [enable]d rules as of logical name

  [Disable]
      Deletes names from current theory

  [E/d]
      Enable/disable rules

  [Enable]
      Adds names to current theory

  [Executable-counterpart-theory]
      [Executable-counterpart] rules as of logical name

  [Function-theory]
      Function symbol rules as of logical name

  [Ground-zero]
      [enable]d rules in the [startup] theory

  [Hands-off-lambda-objects-theory]
      how to specify no modification of lambda objects

  [Intersection-theories]
      Intersect two [theories]

  [Minimal-theory]
      A minimal theory to enable

  [Rewrite-lambda-objects-theory]
      how to specify rewriting of lambda objects

  [Set-difference-theories]
      Difference of two [theories]

  [Syntactically-clean-lambda-objects-theory]
      how to specify syntactic cleaning of lambda objects

  [Theory]
      Retrieve named theory

  [Union-theories]
      Union two [theories]

  [Universal-theory]
      All rules as of logical name")
 (THEORY-INVARIANT
  (EVENTS)
  "User-specified invariants on [theories]

    Examples:
    (theory-invariant (not (and (active-runep '(:rewrite left-to-right))
                                (active-runep '(:rewrite right-to-left))))
                      :key my-invariant
                      :error nil)

    ; Equivalent to the above:
    (theory-invariant (incompatible (:rewrite left-to-right)
                                    (:rewrite right-to-left))
                      :key my-invariant
                      :error nil)

    ; As above, but cause an error for non-runes:
    (theory-invariant (incompatible! (:rewrite left-to-right)
                                     (:rewrite right-to-left))
                      :key my-invariant
                      :error nil)

    General Form:
    (theory-invariant term &key key error)

  where:

    * [47mterm[0m is a term that uses no variables other than [47mens[0m and [47m[state][0m;

    * [47mkey[0m is an arbitrary ``name'' for this invariant (if omitted, an
      integer is generated and used); and

    * [47m:error[0m specifies the action to be taken when an invariant is violated
      --- either [47mnil[0m if a warning is to be printed, else [47mt[0m (the
      default) if an error is to be caused.

  [47mTheory-invariant[0m is an event that adds to or modifies the [table] of
  user-supplied theory invariants that are checked each time a theory
  expression is evaluated.

  The theory invariant mechanism is provided via a table (see [table])
  named [47mtheory-invariant-table[0m.  In fact, the [47mtheory-invariant[0m
  ``event'' is just a macro that expands into a use of the [47m[table][0m
  event.  More general access to the [47mtheory-invariant[0m [table] is
  provided by [47m[table][0m itself.  For example, the [table] can be
  inspected or cleared with [47m[table][0m; you can clear an individual
  theory invariant by setting the invariant to [47mt[0m, or eliminate all
  theory invariants with the command [47m(table theory-invariant-table
  nil nil :clear)[0m.

  [47mTheory-invariant-table[0m maps arbitrary keys to records containing
  terms that mention, at most, the variables [47mens[0m and [47m[state][0m.  Every
  time an alleged theory expression is evaluated, e.g., in the
  [47m[in-theory][0m event or [47m:[0m[47m[in-theory][0m hint, each of the terms in
  [47mtheory-invariant-table[0m is evaluated with [47mens[0m bound to a so-called
  ``enabled structure'' obtained from the theory expression and
  [47m[state][0m bound to the current ACL2 state (see [state]).  Users
  generally need not know about the enabled structure, other than
  that it can be accessed using the macros [47mactive-runep[0m and
  [47mincompatible[0m; see [active-runep] and see [incompatible].  (Also see
  variants [active-or-non-runep] and [incompatible!], whose use by
  the theory-invariant mechanism will cause an error any time either
  ``rune'' is not truly a rune.)  If the result is [47mnil[0m, a message is
  printed and an error occurs (except, only a warning occurs if
  [47m:error nil[0m is specified).  Thus, the [table] can be thought of as a
  list of conjuncts.  Each [47mterm[0m in the [table] has a ``name,'' which
  is just the key under which the term is stored.  When a theory
  violates the restrictions specified by some term, both the name and
  the term are printed.  By calling [47mtheory-invariant[0m with a new term
  but the same name, you can overwrite that conjunct of the theory
  invariant; but see the Local Redefinition Caveat at the end of this
  note.  You may want to avoid using explicit names, since otherwise
  the subsequent inclusion of another book that defines a theory
  invariant with the same name will override your theory invariant.

  Theory invariants are particularly useful in the context of large
  rule sets intended for re-use.  Such sets often contain conflicting
  rules, e.g., rules that are to be [enable]d when certain function
  symbols are [disable]d, rules that rewrite in opposite directions
  and thus loop if simultaneously [enable]d, groups of rules which
  should be [enable]d in concert, etc.  The developer of such rule
  sets understands these restrictions and probably documents them.
  The theory invariant mechanism allows the developer to codify his
  restrictions so that the user is alerted when they are violated.

  Since theory invariants are arbitrary terms, macros may be used to
  express commonly used restrictions.  For example, executing the
  event

    (theory-invariant (incompatible (:rewrite left-to-right)
                                    (:rewrite right-to-left)))

  would subsequently cause an error any time the current theory
  contained both of the two [rune]s shown.  Of course, [incompatible]
  is just defined as a macro.  Its definition may be inspected with
  [47m:pe incompatible[0m.

  In order for a [47mtheory-invariant[0m event to be accepted, the proposed
  theory invariant must be satisfied by the current theory (see
  [current-theory]).  The value returned upon successful execution of
  the event is the key (whether user-supplied or generated).

  Local Redefinition Caveat.  Care needs to be taken when redefining a
  theory invariant in a [local] context.  Consider the following
  example.

    (theory-invariant
     (active-runep '(:definition binary-append))
     :key app-inv)

    (encapsulate
     ()
     (local (theory-invariant t :key app-inv))
     (in-theory (disable binary-append))
     (defthm ...))

  The second pass of the [47m[encapsulate][0m will fail, because the
  [47m[in-theory][0m event violates the original [47mtheory-invariant[0m and the
  [47m[local][0m [47mtheory-invariant[0m is skipped in the second pass of the
  [47m[encapsulate][0m.  Of course, [47m[local][0m [47m[theory-invariant][0ms in [books]
  can cause the analogous problem in the second ([47m[include-book][0m) pass
  of a [47m[certify-book][0m.  In both cases, though, the theory invariants
  are only checked at the conclusion of the ([47minclude-book[0m or
  [47mencapsulate[0m) event.  Indeed, theory invariants are checked at the
  end of every event related to [theories], including [47m[defun][0m,
  [47m[defthm][0m, [47m[in-theory][0m, [47m[encapsulate][0m, and [47m[include-book][0m, except
  for events executed on behalf of an [47m[include-book][0m or the second
  pass of an [47m[encapsulate][0m.")
 (THEREIS$ (POINTERS) "See [loop$].")
 (THEREIS$+ (POINTERS) "See [loop$].")
 (THE_ADMISSION_OF_APP
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Admission of App

  {IMAGE} (see [Revisiting_the_Admission_of_App])

  Here is what it looks like to submit the definition of [47mapp[0m to ACL2:

  {IMAGE}

    ACL2 !>[31;1m(defun app (x y)[0m
      [31;1m(cond ((endp x) y)[0m
            [31;1m(t (cons (car x) [0m
                     [31;1m(app (cdr x) y)))))[0m

    The admission of 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 APP is
    described by the theorem (OR (CONSP (APP X Y)) (EQUAL (APP X Y) Y)).
    We used primitive type reasoning.

    Summary
    Form:  ( DEFUN APP ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     APP

  {IMAGE}

  The text between the lines above is one interaction with the ACL2
  command loop.  Interacting with the latest version of ACL2 may not
  produce the very same output, but we trust you'll recognize the
  basics.

  Above you see the user's [31;1minput[0m and how the system responds.  This
  little example shows you what the syntax looks like and is a very
  typical [31;1msuccessful[0m interaction with the definitional principle.

  Let's look at it a little more closely.

  {IMAGE} (see [Revisiting_the_Admission_of_App])")
 (THE_ASSOCIATIVITY_OF_APP
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Associativity of App

  {IMAGE} (see [The_Theorem_that_App_is_Associative])

  {IMAGE}

    ACL2!>[31;1m(let ((a '(1 2))[0m
                [31;1m(b '(3 4))[0m
                [31;1m(c '(5 6)))[0m
            [31;1m(equal (app (app a b) c)[0m
                   [31;1m(app a (app b c))))[0m
    T

  {IMAGE}

  Observe that, for the particular [47ma[0m, [47mb[0m, and [47mc[0m above, [47m(app (app a b) c)[0m
  returns the same thing as [47m(app a (app b c))[0m.  Perhaps [47mapp[0m is
  [31;1massociative[0m.  Of course, to be associative means that the above
  property must hold for all values of [47ma[0m, [47mb[0m, and [47mc[0m, not just the ones
  [31;1mtested[0m above.

  Wouldn't it be cool if you could type

    ACL2!>[31;1m(equal (app (app a b) c)[0m
                 [31;1m(app a (app b c)))[0m

  and have ACL2 compute the value [47mT[0m?  Well, [31;1myou can't![0m If you try it,
  you'll get an error message!  The message says we can't evaluate
  that form because it contains [31;1mfree[0m variables, i.e., variables not
  given values.  Click here (see [Free_Variables_in_Top-Level_Input])
  to see the message.

  We cannot evaluate a form on an infinite number of cases.  But we can
  prove that a form is a theorem and hence know that it will always
  evaluate to true.

  {IMAGE} (see [The_Theorem_that_App_is_Associative])")
 (THE_BASE_CASE_IN_THE_APP_EXAMPLE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Base Case in the App Example

  This formula is the [31;1mBase Case[0m.  It consists of two parts, a test
  identifying the non-inductive case and the conjecture to prove.

    (IMPLIES (ENDP A)                 [31;1m; Test[0m
             (:P A B C))              [31;1m; Conjecture[0m

  When we prove this we can assume

     * [47mA[0m is empty

  and we have to prove the conjecture for [47mA[0m.")
 (THE_END_OF_THE_FLYING_TOUR
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The End of the Flying Tour

  {IMAGE}

  This completes the Flying Tour.

  We recommend that you now take A Walking Tour of ACL2 (see
  [A_Walking_Tour_of_ACL2]).

  Thanks.
  Matt Kaufmann and J Moore

  {IMAGE} (see [A_Walking_Tour_of_ACL2])")
 (THE_END_OF_THE_PROOF_OF_THE_ASSOCIATIVITY_OF_APP
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The End of the Proof of the Associativity of App

  {IMAGE} (see [Guiding_the_ACL2_Theorem_Prover])

    That completes (see [Popping_out_of_an_Inductive_Proof]) the proof of *1.

    Q.E.D. (see [The_Q.E.D._Message])

    Summary
    Form:  ( DEFTHM ASSOCIATIVITY-OF-APP ...)
    Rules (see [The_Rules_used_in_the_Associativity_of_App_Proof]): ((:REWRITE CDR-CONS)
            (:REWRITE CAR-CONS)
            (:DEFINITION NOT)
            (:DEFINITION ENDP)
            (:FAKE-RUNE-FOR-TYPE-SET NIL)
            (:DEFINITION APP))
    Warnings:  None
    Time:  0.27 seconds (prove: 0.10 (see [The_Time_Taken_to_do_the_Associativity_of_App_Proof]), print: 0.05, other: 0.12)
     ASSOCIATIVITY-OF-APP

  {IMAGE}

  {IMAGE} (see [Guiding_the_ACL2_Theorem_Prover])")
 (THE_END_OF_THE_WALKING_TOUR
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The End of the Walking Tour

  {IMAGE}

  This completes the Walking Tour.

  We intend to document many other parts of the system this way, but we
  just haven't gotten around to it.

  To start the two tours over again from the beginning, click on the
  icons below.  If you are really interested in learning how to use
  ACL2, we recommend that you repeat each tour at least once more to
  explore branches of the tour that you might have missed.

  If you want to learn how to use the theorem prover, we now recommend
  that you devote the time necessary to work your way through the
  extended introduction to how to use the prover.

  See [introduction-to-the-theorem-prover].

  This will explain how to interact with ACL2 and has some sample
  problems for you to solve including some challenge proofs to make
  ACL2 find.

  We hope you enjoy ACL2.  We do.

  Matt Kaufmann and J Strother Moore

  {IMAGE} (see [A_Flying_Tour_of_ACL2]) {IMAGE} (see
  [A_Walking_Tour_of_ACL2])")
 (THE_EVENT_SUMMARY
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Event Summary

  At the conclusion of most events (click here (see [About_the_Prompt])
  for a brief discussion of events or see [events] {ICON} (see
  [A_Tiny_Warning_Sign])), ACL2 prints a summary.  The summary for
  [47mapp[0m is:

    Summary
    Form:  ( DEFUN APP ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Warnings:  None
    Time:  0.03 seconds (prove: 0.00, print: 0.00, other: 0.03)
     APP

  The ``rules'' listed are those used in function admission or proof
  summarized.  What is actually listed are ``runes'' (see [rune])
  {ICON} (see [A_Tiny_Warning_Sign])) which are list-structured names
  for rules in the ACL2 database or ``[world]'' {ICON} (see
  [A_Tiny_Warning_Sign]).  Using [theories] {ICON} (see
  [A_Tiny_Warning_Sign]) you can ``enable'' and ``disable'' rules so
  as to make them available (or not) to the ACL2 theorem prover.

  The ``warnings'' mentioned (none are listed for [47mapp[0m) remind the
  reader whether the event provoked any warnings.  The warnings
  themselves would have been printed earlier in the processing and
  this part of the summary just names the earlier warnings printed.

  The ``time'' indicates how much processing time was used and is
  divided into three parts: the time devoted to proof, to printing,
  and to syntactic checks, pre-processing and database updates.
  Despite the fact that ACL2 is an applicative language it is
  possible to measure time with ACL2 programs.  The [47m[state][0m {ICON}
  (see [A_Tiny_Warning_Sign]) contains a clock.  The times are
  printed in decimal notation but are actually counted in integral
  units.  Note that by default, each time is a runtime, also known as
  a cpu time, as opposed to being a real time, also known as a wall
  clock time.

  The final [47mAPP[0m is the value of the [47mdefun[0m command and was printed by
  the read-eval-print loop.  The fact that it is indented one space
  is a subtle reminder that the command actually returned an ``error
  triple'', consisting of a flag indicating (in this case) that no
  error occurred, a value (in this case the symbol [47mAPP[0m), and the
  final [47m[state][0m {ICON} (see [A_Tiny_Warning_Sign])).  See
  [ld-post-eval-print] {ICON} (see [A_Tiny_Warning_Sign]) for some
  details.  If you really want to follow that link, however, you
  might see [ld] {ICON} (see [A_Tiny_Warning_Sign]) first.

  You should now return to the Walking Tour (see
  [Revisiting_the_Admission_of_App]).")
 (THE_EXPANSION_OF_ENDP_IN_THE_INDUCTION_STEP_{STEP_0}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Expansion of ENDP in the Induction Step (Step 0)

    Subgoal *1/2
    (IMPLIES (AND (NOT ( (see [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_1}])ENDP A))
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP (APP A B) C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above (the open parenthesis before [47mENDP[0m) to replace
  [47m(ENDP A)[0m by its definition.")
 (THE_EXPANSION_OF_ENDP_IN_THE_INDUCTION_STEP_{STEP_1}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Expansion of ENDP in the Induction Step (Step 1)

    Subgoal *1/2
    (IMPLIES (AND ( (see [The_Expansion_of_ENDP_in_the_Induction_Step_{Step_2}])NOT [31;1m(NOT (CONSP A))[0m)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP (APP A B) C)
                    (APP A (APP B C)))).

  {IMAGE}

  The [31;1mbold[0m text is the instantiated definition of [47mENDP[0m.

  Now click on the link above to simplify (NOT (NOT (CONSP A)))")
 (THE_EXPANSION_OF_ENDP_IN_THE_INDUCTION_STEP_{STEP_2}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Expansion of ENDP in the Induction Step (Step 2)

    Subgoal *1/2'
    (IMPLIES (AND [31;1m(CONSP A)[0m
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP (APP A B) C)
                    (APP A (APP B C)))).

  {IMAGE}

  Note that this is [47mSubgoal *1/2'.[0m

  You may click here (see
  [Overview_of_the_Simplification_of_the_Induction_Step_to_T]) to
  return to the main proof.")
 (THE_FALLING_BODY_MODEL
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Falling Body Model

  {IMAGE}

  One particularly famous and very simple model is the equation of a
  falling body: the distance d an object falls is proportional to the
  square of the time t.  If the time is measured in seconds and the
  distance in feet, the equation relating these two is

           2
    d = 16t

  This equation is a [31;1mmodel[0m of falling objects.  It can be used to
  predict how long it takes a cannonball to fall from the top of a
  200 foot tower (3.5 seconds).  This might be important if your
  product is designed to drop cannonballs on moving targets.")
 (THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_0}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Final Simplification in the Base Case (Step 0)

    Subgoal *1/1'
    (IMPLIES (NOT (CONSP A))
             (EQUAL (APP ( (see [The_Final_Simplification_in_the_Base_Case_{Step_1}])APP A B) C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to replace [47m(APP A B)[0m by its definition.  Note
  that the hypothesis [47m(NOT (CONSP A))[0m allows us to simplify the [47mIF[0m in
  [47mAPP[0m to its [31;1mfalse branch[0m this time.")
 (THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_1}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Final Simplification in the Base Case (Step 1)

    Subgoal *1/1'
    (IMPLIES (NOT (CONSP A))
             (EQUAL (APP [31;1mB[0m C)
                    ( (see [The_Final_Simplification_in_the_Base_Case_{Step_2}])APP A (APP B C)))).

  {IMAGE}

  Click on the link above to expand the definition of [47mAPP[0m.  Again, we
  come out through the false branch because of the hypothesis.")
 (THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_2}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Final Simplification in the Base Case (Step 2)

    Subgoal *1/1'
    (IMPLIES (NOT (CONSP A))
             ( (see [The_Final_Simplification_in_the_Base_Case_{Step_3}])EQUAL (APP B C)
                    [31;1m(APP B C)[0m)).

  {IMAGE}

  Click on the link above to use the Axiom [47m(EQUAL x x) = t[0m")
 (THE_FINAL_SIMPLIFICATION_IN_THE_BASE_CASE_{STEP_3}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Final Simplification in the Base Case (Step 3)

    Subgoal *1/1'
    (IMPLIES (NOT (CONSP A))
             [31;1mT[0m)

  {IMAGE}

  Now that its conclusion is identically [47mT[0m the [47mIMPLIES[0m will simplify to
  [47mT[0m (not shown) and we are done with [47mSubgoal *1/1'[0m.

  You may click here (see
  [Overview_of_the_Simplification_of_the_Base_Case_to_T]) to return
  to the main proof.")
 (THE_FIRST_APPLICATION_OF_THE_ASSOCIATIVITY_RULE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The First Application of the Associativity Rule

  So here we see our associativity rule being used!

  The rewriter sweeps the conjecture in a [31;1mleftmost innermost[0m fashion,
  applying rewrite rules as it goes.

  The associativity rule is used many times in this sweep.  The first
  ``target'' is highlighted below.  Click on it to see what happens:

    [31;1mCurrent Conjecture[0m:
    (equal (app (app (app (app x1 x2) (app x3 x4)) (see [A_Sketch_of_How_the_Rewriter_Works]) (app x5 x6)) x7)
           (app x1 (app (app x2 x3) (app (app x4 x5) (app x6 x7)))))")
 (THE_INDUCTION_SCHEME_SELECTED_FOR_THE_APP_EXAMPLE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Induction Scheme Selected for the App Example

    (AND
       (IMPLIES (AND (NOT (ENDP A))         ; Induction Step: test
                     (:P (CDR A) B C))      ;  and induction hypothesis
                (:P A B C))                 ;  implies induction conclusion.
       (IMPLIES (ENDP A) (:P A B C)))       ; Base Case

  The formula beginning with this parenthesis is the induction scheme
  suggested by [47m(APP A B)[0m applied to [47m(P A B C)[0m.

  It is a [31;1mconjunction[0m ([47m[and][0m {ICON} (see [A_Tiny_Warning_Sign])) of two
  formulas.

  The first is the [31;1minduction step[0m and the second is the [31;1mbase case[0m.")
 (THE_INDUCTION_STEP_IN_THE_APP_EXAMPLE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Induction Step in the App Example

  This formula is the [31;1mInduction Step[0m.  It basically consists of three
  parts, a test identifying the inductive case, an induction
  hypothesis and an induction conclusion.

    (IMPLIES (AND (NOT (ENDP A))      [31;1m; Test[0m
                  (:P (CDR A) B C))   [31;1m; Induction Hypothesis[0m
             (:P A B C))              [31;1m; Induction Conclusion[0m

  When we prove this we can assume

     * [47mA[0m is not empty, and that

      * the associativity conjecture holds for a ``smaller'' version of [47mA[0m,
        namely, [47m(CDR A)[0m.

  Under those hypotheses we have to prove the associativity conjecture
  for [47mA[0m itself.")
 (THE_INSTANTIATION_OF_THE_INDUCTION_SCHEME
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Instantiation of the Induction Scheme

  The induction scheme just shown is just an abbreviation for our real
  goal.

  To obtain our actual goals we have to replace the schema [47m:P[0m by the
  associativity conjecture (instantiated as shown in the scheme).

  This produces two actual goals, the induction step and the base case.")
 (THE_JUSTIFICATION_OF_THE_INDUCTION_SCHEME
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Justification of the Induction Scheme

  This paragraph explains why the induction selected is legal.  The
  explanation is basically the same as the explanation for why the
  recursion in [47m(APP A B)[0m terminates.")
 (THE_PROOF_OF_THE_ASSOCIATIVITY_OF_APP
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Proof of the Associativity of App

  {IMAGE} (see
  [Overview_of_the_Simplification_of_the_Induction_Step_to_T])

  Here is the theorem prover's output when it processes the [31;1mdefthm[0m
  command for the associativity of [47mapp[0m.  We have highlighted text for
  which we offer some explanation, and broken the presentation into
  several pages.  (The most recent version of ACL2 may print slightly
  different output but the basics are the same.)  Just follow the
  Walking Tour after exploring the explanations.

  However, before exploring this output you should understand that ACL2
  users rarely read successful proofs!  Instead, they look at certain
  subgoals printed in failed proofs, figure whether and how those
  subgoals can be proved, and give ACL2 directions for proving them,
  usually by simply proving other lemmas.  Furthermore, to be a good
  user of ACL2 you do not have to understand how the theorem prover
  works.  You just have to understand how to interact with it.  We
  explain this in great detail later.  But basically all new users
  are curious to know how ACL2 works and this little tour attempts to
  give some answers, just to satisfy your curiosity.  The first
  command below, [47m:set-gag-mode nil[0m, instructs ACL2 to supply its full
  prover output; normally that output is restricted considerably
  (``gagged''), but we include it all below in support of the
  associated explanations.

  {IMAGE}

    ACL2!>[31;1m:set-gag-mode nil[0m
    <state>
    ACL2!>[31;1m(defthm associativity-of-app[0m
            [31;1m(equal (app (app a b) c)[0m
                   [31;1m(app a (app b c))))[0m

    Name the formula above *1 (see [Name_the_Formula_Above]).

    [Perhaps] we can prove *1 by induction.  Three induction schemes are
    suggested (see [Suggested_Inductions_in_the_Associativity_of_App_Example]) by this conjecture.  Subsumption (see [Subsumption_of_Induction_Candidates_in_App_Example]) reduces that number to two.
    However, one of these is flawed (see [Flawed_Induction_Candidates_in_App_Example]) and so we are left with one viable
    candidate.

    We will induct according to a scheme suggested by (APP A B).  If we
    let  (:P A B C) denote *1 above then the induction scheme we'll use
    is
    ( (see [The_Induction_Scheme_Selected_for_the_App_Example])AND
       ( (see [The_Induction_Step_in_the_App_Example])IMPLIES (AND (NOT (ENDP A))
                     (:P (CDR A) B C))
                (:P A B C))
       ( (see [The_Base_Case_in_the_App_Example])IMPLIES (ENDP A) (:P A B C))).
    This induction is justified (see [The_Justification_of_the_Induction_Scheme]) by the same argument used to admit APP,
    namely, the measure (ACL2-COUNT A) is decreasing according to the relation
    O< (which is known to be well-founded on the domain recognized
    by O-P).  When applied (see [The_Instantiation_of_the_Induction_Scheme]) to the goal at hand the above induction
    scheme produces the following two nontautological subgoals (see [Nontautological_Subgoals]).

  {IMAGE} (see
  [Overview_of_the_Simplification_of_the_Induction_Step_to_T])")
 (THE_Q.E.D._MESSAGE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Q.E.D. Message

  [31;1mQ.E.D.[0m stands for ``quod erat demonstrandum'' which is Latin for
  ``which was to be demonstrated'' and is the signal that a proof is
  completely done.")
 (THE_RULES_USED_IN_THE_ASSOCIATIVITY_OF_APP_PROOF
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Rules used in the Associativity of App Proof

  Note that under [31;1mRules[0m we list the runes (see [RUNE]) {ICON} (see
  [A_Tiny_Warning_Sign]) of all the rules used in the proof.  This
  list says that we used the rewrite rules [47mCAR-CONS[0m and [47mCDR-CONS[0m, the
  definitions of the functions [47mNOT[0m, [47mENDP[0m and [47mAPP[0m, and primitive type
  reasoning (which is how we simplified the [47mIF[0m and [47mEQUAL[0m terms).

  For what it is worth, [47mIMPLIES[0m and [47mAND[0m are actually macros (see
  [DEFMACRO]) {ICON} (see [A_Tiny_Warning_Sign]) that are expanded
  into [47mIF[0m expressions before the proof ever begins.  The use of
  macros is not reported among the rules.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_0}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 0)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_1}])APP A B) C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to replace [47m(APP A B)[0m by its definition.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_10}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 10)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_11}])[31;1mEQUAL (APP (APP (CDR A) B) C)[0m
                    [31;1m(APP (CDR A) (APP B C)))[0m).

  {IMAGE}

  Click on the link above to use the Induction Hypothesis (which is the
  second of the two hypotheses above and which is identical to the
  rewritten conclusion).")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_11}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 11)

    Subgoal *1/2'
    ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_12}])IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             [31;1mT[0m)

  {IMAGE}

  Click on the link above to use the definition of [47mIMPLIES[0m.  Since the
  conclusion of the implication is now identically [47mT[0m, the implication
  simplifies to [47mT[0m.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_12}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 12)

    Subgoal *1/2'
    [31;1mT[0m

  {IMAGE}

  So, indeed, [47mSubgoal *1/2'[0m [31;1mdoes[0m simplify to T!

  You can see that even in an example as simple as this one, quite a
  lot happens in simplification.

  You may click here (see
  [Overview_of_the_Simplification_of_the_Induction_Step_to_T]) to
  return to the main proof.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_1}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 1)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP [31;1m(IF [0m( (see [The_Simplification_of_the_Induction_Conclusion_{Step_2}])[31;1mCONSP A)[0m
                             [31;1m(CONS (CAR A) (APP (CDR A) B))[0m
                             [31;1mB)[0m
                         C)
                    (APP A (APP B C)))).

  {IMAGE}

  Note that the [47mIF[0m expression above is the simplified body of [47mAPP[0m.  But
  we know the test [47m(CONSP A)[0m is true, by the first hypothesis.  Click
  on the link above to replace the test by [47mT[0m.  Actually this step and
  several subsequent ones are done during the simplification of the
  body of [47mAPP[0m but we want to illustrate the basic principles of
  simplification without bothering with every detail.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_2}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 2)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (APP ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_3}])IF [31;1mT[0m
                             (CONS (CAR A) (APP (CDR A) B))
                             B)
                         C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to apply the Axiom [47m(IF T x y) = x[0m.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_3}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 3)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_4}])APP [31;1m(CONS (CAR A) (APP (CDR A) B))[0m
                         C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to expand the definition of [47mAPP[0m here.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_4}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 4)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (IF ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_5}])[31;1mCONSP (CONS (CAR A) (APP (CDR A) B)))[0m
                        [31;1m(CONS (CAR (CONS (CAR A) (APP (CDR A) B)))[0m
                              [31;1m(APP (CDR (CONS (CAR A) (APP (CDR A) B)))[0m
                                   [31;1mC))[0m
                        [31;1mC)[0m
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to apply the Axiom [47m(CONSP (CONS x y)) = T[0m.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_5}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 5)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (IF [31;1mT[0m
                        (CONS ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_6}])CAR (CONS (CAR A) (APP (CDR A) B)))
                              (APP (CDR (CONS (CAR A) (APP (CDR A) B)))
                                   C))
                        C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to apply the Axiom [47m(CAR (CONS x y)) = x[0m.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_6}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 6)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL (IF T
                        (CONS [31;1m(CAR A)[0m
                              (APP ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_7}])CDR (CONS (CAR A) (APP (CDR A) B)))
                                   C))
                        C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to apply the Axiom [47m(CDR (CONS x y)) = y[0m.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_7}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 7)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_8}])IF T
                        (CONS (CAR A)
                              (APP [31;1m(APP (CDR A) B)[0m
                                   C))
                        C)
                    (APP A (APP B C)))).

  {IMAGE}

  Click on the link above to apply the Axiom [47m(IF T x y) = x[0m.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_8}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 8)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             (EQUAL [31;1m(CONS (CAR A)[0m
                          [31;1m(APP (APP (CDR A) B)[0m
                               [31;1mC))[0m
                    ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_9}])APP A (APP B C)))).

  {IMAGE}

  Click on the link above to expand the definition of [47mAPP[0m here.  This
  time, we'll do the whole expansion at once, including the
  simplification of the resulting [47mIF[0m.  This is how ACL2 actually does
  it.")
 (THE_SIMPLIFICATION_OF_THE_INDUCTION_CONCLUSION_{STEP_9}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Simplification of the Induction Conclusion (Step 9)

    Subgoal *1/2'
    (IMPLIES (AND (CONSP A)
                  (EQUAL (APP (APP (CDR A) B) C)
                         (APP (CDR A) (APP B C))))
             ( (see [The_Simplification_of_the_Induction_Conclusion_{Step_10}])EQUAL (CONS (CAR A)
                          (APP (APP (CDR A) B)
                               C))
                    [31;1m(CONS (CAR A)[0m
                          [31;1m(APP (CDR A) (APP B C))[0m))).

  {IMAGE}

  Click on the link above to apply the Axiom that [47m(EQUAL (CONS x y)
  (CONS u v))[0m is equal to the conjunction of [47m(EQUAL x u)[0m and [47m(EQUAL y
  v)[0m.  In this case, [47m(EQUAL x u)[0m is trivial, [47m(EQUAL (CAR A) (CAR A))[0m.")
 (THE_SUMMARY_OF_THE_PROOF_OF_THE_TRIVIAL_CONSEQUENCE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Summary of the Proof of the Trivial Consequence

  Note that at the conclusion of the proof, the system reminds you of
  the earlier [31;1mWarning[0m.

  It is a good idea, when the [31;1mQ.E.D.[0m flies by, to see if there were any
  Warnings.")
 (THE_THEOREM_THAT_APP_IS_ASSOCIATIVE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Theorem that App is Associative

  {IMAGE} (see [The_Proof_of_the_Associativity_of_App])

    ACL2!>[31;1m(defthm associativity-of-app[0m
            [31;1m(equal (app (app a b) c)[0m
                   [31;1m(app a (app b c))))[0m

  The formula above says [47mapp[0m is associative.  The [47m[defthm][0m {ICON} (see
  [A_Tiny_Warning_Sign]) command instructs ACL2 to prove the formula
  and to name it [47massociativity-of-app[0m.  Actually, the [47mdefthm[0m command
  also builds the formula into the database as a [47m[rewrite][0m {ICON}
  (see [A_Tiny_Warning_Sign]) rule, but we won't go into that just
  yet.

  What we will consider is how the ACL2 theorem prover proves this
  formula.

  If you proceed you will find the actual output of ACL2 in response to
  the command above.  Some of the text is highlighted for the
  purposes of the tour.  ACL2 does not highlight its output.

  You will note that we sometimes highlight a single open parenthesis.
  This is our way of drawing your attention to the subformula that
  begins with that parenthesis.  By clicking on the parenthesis you
  will get an explanation of the subformula or its processing.

  {IMAGE} (see [The_Proof_of_the_Associativity_of_App])")
 (THE_TIME_TAKEN_TO_DO_THE_ASSOCIATIVITY_OF_APP_PROOF
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Time Taken to do the Associativity of App Proof

  The time it took us to explain this proof may leave the impression
  that the proof is complicated.  In a way, it is.  But it happens
  quickly.

  The time taken to do this proof is about 1/10 second.  The rest of
  the time (about 2/10 seconds) is spent in pre- and post-processing.

  Basically, this proof flashes across your screen before you can read
  it; you see the [31;1mQ.E.D.[0m and don't bother to scroll back to read it.
  You have more important things to do than read successful proofs.")
 (THE_TOURS
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The Tours

  ACL2 is a very large, multipurpose system.  You can use it as a
  programming language, a specification language, a modeling
  language, a formal mathematical logic, or a semi-automatic theorem
  prover, just to name its most common uses.  It has been used on a
  number of industrial applications (see [INTERESTING-APPLICATIONS]).
  If you're uncertain as to whether your project is appropriate for
  ACL2 we urge you to look over this list or contact the ACL2
  developers.

  This home page includes all of ACL2's online documentation, which is
  quite extensive (over 4 megabytes).  To help ease your introduction
  to ACL2, we have built two tours through this documentation.

  If you are familiar with at least some of the industrial applications
  (see [INTERESTING-APPLICATIONS]) of ACL2, then you will understand
  the distance between the simple examples we talk about in these
  tours and the kinds of things ACL2 users do with the system.

  Newcomers to ACL2 should first take the ``Flying Tour.'' Then, if you
  want to know more, take the ``Walking Tour.'' On your first
  reading, follow the two Tours linearly, clicking only on the icon
  of the Tour you're on.  Beware of other links, which might jump you
  from one tour to the other or into the ACL2 User's Manual!  Once
  you've had a coherent overview of the system, you might quickly
  repeat both Tours to see if there are unvisited links you're
  interested in, using your browser's Back Button to return to your
  starting points.

  If after all this you want to learn how to use the theorem prover
  (!), see [introduction-to-the-theorem-prover].

  To start a tour, click on the appropriate icon below.

  {IMAGE} (see [A_Flying_Tour_of_ACL2]) {IMAGE} (see
  [A_Walking_Tour_of_ACL2])

  If you take the tours in a text-based format (such as using the :DOC
  command in Emacs), they will probably be unsatisfying because we
  use gif files and assume you can navigate ``back.''")
 (THE_WARNING_ABOUT_THE_TRIVIAL_CONSEQUENCE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "The WARNING about the Trivial Consequence

  This [31;1mWarning[0m alerts us to the fact that when treated as a [31;1mrewrite[0m
  rule, the new rule [47mTRIVIAL-CONSEQUENCE[0m, rewrites terms of the same
  form as a rule we have already proved, namely [47mASSOCIATIVITY-OF-APP[0m.

  When you see this warning you should [31;1mthink about your rules[0m!

  In the current case, it would be a good idea [31;1mnot[0m to make
  [47mTRIVIAL-CONSEQUENCE[0m a rule at all.  We could do this with
  [47m:[0m[47m[rule-classes][0m {ICON} (see [A_Tiny_Warning_Sign]) nil.

  ACL2 proceeds to try to prove the theorem, even though it printed
  some warnings.  The basic assumption in ACL2 is that the [31;1muser[0m
  [31;1munderstands what he or she is doing[0m but may need a little reminding
  just to manage a complicated set of facts.")
 (THIRD
  (NTH ACL2-BUILT-INS)
  "Third member of the list

  See any Common Lisp documentation for details.")
 (THM
  (MISCELLANEOUS)
  "Prove a theorem

    Example:
    (thm (equal (app (app a b) c)
                (app a (app b c))))

  Also see [defthm].  Unlike [47m[defthm][0m, [47mthm[0m does not store an event; it
  merely causes the theorem prover to attempt a proof.  But like
  [47mdefthm[0m, calls of [47mthm[0m are legal in event contexts (see
  [embedded-event-form]).

    General Form:
    (thm term
         :instructions instructions
         :hints        hints
         :otf-flg      otf-flg)

  where [47mterm[0m is a term alleged to be a theorem, and [47m[instructions][0m,
  [47m[hints][0m, and [47m[otf-flg][0m are as described in the corresponding
  [documentation] topics.  The keyword arguments are optional.

  For information on how [47mthm[0m is implemented using [47m[make-event][0m, see
  [make-event-example-3].


Subtopics

  [Otf-flg]
      Allow more than one initial subgoal to be pushed for induction")
 (TIDBITS
  (ACL2-TUTORIAL)
  "Some basic hints for using ACL2

  See [books] for a discussion of books.  Briefly, a book is a file
  whose name ends in ``.lisp'' that contains ACL2 [events]; see
  [events].

  See [history] for a list of useful commands.  Some examples:

    :pbt :here      ; print the current event
    :pbt (:here -3) ; print the last four events
    :u              ; undo the last event
    :pe append      ; print the definition of append

  See [documentation] to learn how to print documentation to the
  terminal.  There are also versions of the [documentation] for web
  browsers and for Emacs (see [ACL2-Doc]).

  There are quite a few kinds of rules allowed in ACL2 besides
  [47m:[0m[47m[rewrite][0m rules, though we hope that beginners won't usually need
  to be aware of them.  See [rule-classes] for details.  In
  particular, there is support for [congruence] rewriting.  See
  [rune] (``RUle NamE'') for a description of the various kinds of
  rules in the system.  Also see [theories] for a description of how
  to build [theories] of [rune]s, which are often used in hints; see
  [hints].

  A ``[programming] mode'' is supported; see [program], see
  [defun-mode], and see [default-defun-mode].  It can be useful to
  prototype functions after executing the command [47m:[0m[47m[program][0m, which
  will cause definitions to be syntax-checked only.

  ACL2 supports mutual recursion, though this feature is not tied into
  the automatic discovery of [induction] schemas and is often not the
  best way to proceed when you expect to be reasoning about the
  functions.  See [defuns]; also see [mutual-recursion].

  See [ld] for discussion of how to load files of [events].  There are
  many options to [47m[ld][0m, including ones to suppress proofs and to
  control output.

  The [47m:[0m[47m[otf-flg][0m (Onward Thru the Fog FLaG) is a useful feature that
  Nqthm users have often wished for.  It prevents the prover from
  aborting a proof attempt and inducting on the original conjecture.
  See [otf-flg].

  ACL2 supports redefinition and redundancy in [events]; see
  [ld-redefinition-action] and see [redundant-events].

  A [proof-tree] display feature is available for use with Emacs.  This
  feature provides a view of ACL2 proofs that can be much more useful
  than reading the stream of [characters] output by the theorem
  prover as its ``proof.'' See [proof-tree].

  An interactive feature similar to Pc-Nqthm is supported in ACL2.  See
  [verify] and see [proof-builder].

  ACL2 allows you to [monitor] the use of [rewrite] rules.  See
  [break-rewrite].

  See [arrays] to read about applicative, fast [arrays] in ACL2.

  To quit the ACL2 [command] loop, or (in gcl) to return to the ACL2
  [command] loop after an interrupt, type [47m:[0m[47m[q][0m.  To continue (resume)
  after an interrupt (in gcl), type [47m:r[0m.  To cause an interrupt hit
  control-C (twice, if inside Emacs).  To exit ACL2 altogether, type
  [47m:[0m[47m[quit][0m.

  See [state] to read about the von Neumannesque ACL2 [state] object
  that records the ``current state'' of the ACL2 session.  Also see
  [@], and see [assign], to learn about reading and setting global
  [state] variables.

  If you want your own von Neumannesque object, e.g., a structure that
  can be ``destructively modified'' but which must be used with some
  syntactic restrictions, see [stobj].")
 (TIME$
  (PROGRAMMING ACL2-BUILT-INS)
  "Time the evaluation of a given form

  Semantically, [47m(time$ x ...)[0m equals [47mx[0m.  However, its evaluation writes
  timing output to the trace output (which is usually the terminal),
  as explained further below.

  Note: Some of the functionality below is available only for certain
  host Common Lisp implementations.

    Examples:

    ; Basic examples:

    (time$ (foo 3 4))
    (time$ (mini-proveall))
    (defun bar (x) (time$ (f x)))

    ; Custom examples, which use a custom timing message rather than a built-in
    ; message from Lisp:

    ; Report only if real time is at least 1/2 second (two equivalent forms).
    (time$ (foo) :mintime 1/2)
    (time$ (foo) :real-mintime 1/2)

    ; Report only if allocation is at least 1000 bytes (and if the Lisp supports
    ; :minalloc).
    (time$ (foo) :minalloc 1000)

    ; Report only if real time is at least 1/2 second and (if the Lisp supports
    ; :minalloc) allocation is at least 931 bytes.
    (time$ (foo) :real-mintime 1/2 :minalloc 931)

    ; Print \"Hello Moon, Goodbye World\" instead of any timing data.
    (time$ (foo)
           :msg \"Hello ~s0, ~s1 World.\"
           :args (list \"Moon\" \"Goodbye\"))

    ; Print default custom timing message (same as omitting :mintime 0):
    (time$ (foo)
           :mintime 0)

    ; Print supplied custom timing message.
    (let ((bar ...))
      (time$ (foo)
             :msg \"The execution of ~xf took ~st seconds of real ~
                   time and ~sc seconds of run time (cpu time), and ~
                   allocated ~sa bytes.  In an unrelated note, bar ~
                   currently has the value ~x0.~%\"
             :args (list bar)))

    General Forms:
    (time$ form)
    (time$ form ; arguments below are optional
           :real-mintime  <rational number of seconds>
           :run-mintime   <rational number of seconds>
           :minalloc      <number of bytes>
           :msg           <fmt string>
           :args          <list of arguments for msg>
           )
    ; Note: :real-mintime can be replaced by :mintime

  where [47mform[0m is processed as usual except that the host Common Lisp
  times its evaluation.

  The simplest form is [47m(time$ x)[0m, which will call the [47mtime[0m utility in
  the underlying Lisp, and will print a small default message.  If
  you want to see a message printed by the host Lisp, use [47m(time$ x
  :mintime nil)[0m instead, which may provide detailed,
  implementation-specific data such as the amounts of time spent in
  user and system mode, the gc time, the number of page faults
  encountered, and so on.  Of you can create a custom message,
  configured using the [47m:msg[0m and [47m:args[0m parameters.  [47mTime$[0m can also be
  made to report timing information only conditionally: the
  [47m:real-mintime[0m (or equivalently, [47m:mintime[0m), [47m:run-mintime[0m, and
  [47m:minalloc[0m arguments can be used to avoid reporting timing
  information for computations that take a small amount of time
  (perhaps as might be expected in ordinary cases), but to draw the
  user's attention to computations that take longer or allocate more
  memory than expected.

  We next document the keyword arguments in some detail.

      Keyword arguments [47m:real-mintime[0m (or [47m:mintime[0m) and [47m:run-mintime[0m can be
      used to specify a minimum time threshold for time reporting.
      That is, no timing information will be printed if the execution
      of [47mform[0m takes less than the specified number of seconds of real
      (total) time or run (cpu) time, respectively.  Note that
      rational numbers like 1/2 may be used to specify a fractional
      amount of seconds.  It is an error to specify both
      [47m:real-mintime[0m and its synonym, [47m:mintime[0m.

      Keyword argument [47m:minalloc[0m is not supported on all Lisps.  When it is
      not supported, it is ignored.  But on supported Lisps,
      [47m:minalloc[0m can be used to specify a minimum memory allocation
      threshold.  If [47mform[0m results in fewer than this many bytes being
      allocated, then no timing information will be reported.

      Keyword argument [47m:msg[0m, when provided, should be a string accepted by
      the [47mfmt[0m family of functions (see [fmt]), and it may refer to
      the elements of [47m:args[0m by their positions, just as for [47mcw[0m (see
      [cw]).

  The following directives allow you to report timing information using
  the [47m:msg[0m string.  The examples at the top of this documentation
  topic illustrate the use of these directives.

      [47m~xf[0m --- the form that was executed

      [47m~sa[0m --- the amount of memory allocated, in bytes (in supported Lisps)

      [47m~st[0m --- the real time taken, in seconds

      [47m~sc[0m --- the run time (cpu time) taken, in seconds

      The following apply only when the host Lisp is GCL.  The two system
      times will likely be [47mnil[0m unless the GCL version is 2.6.10 or
      later.  Note the upper-case characters for child times.

      [47m~sC[0m --- the child run time (cpu time) taken, in seconds

      [47m~ss[0m --- the system time taken, in seconds

      [47m~sS[0m --- the child system time taken, in seconds

  We turn now to an example that illustrates how [47mtime$[0m can be called in
  function bodies.  Consider the following definition of the
  Fibonacci function, followed by the definition of a function that
  times [47mk[0m calls of this function.

    (defun fib (n)
      (if (zp n)
          1
        (if (= n 1)
            1
          (+ (fib (- n 1))
             (fib (- n 2))))))

    (defun time-fib (k)
      (if (zp k)
          nil
        (prog2$
         (time$ (fib k)
                :mintime 1/2
                :msg \"(fib ~x0) took ~st seconds, ~sa bytes allocated.~%\"
                :args (list k))
         (time-fib (1- k)))))

  The following log shows a sample execution of the function defined
  just above.

    ACL2 !>(time-fib 36)
    (fib 36) took 3.19 seconds, 1280 bytes allocated.
    (fib 35) took 1.97 seconds, 1280 bytes allocated.
    (fib 34) took 1.21 seconds, 1280 bytes allocated.
    (fib 33) took 0.75 seconds, 1280 bytes allocated.
    NIL
    ACL2 !>

  Notes:

  (1) Common Lisp specifies that the [47mtime[0m utility prints to ``trace
  output'', and [47mtime$[0m follows this convention.  Thus, if you have
  opened a [trace] file (see [open-trace-file]), then you can expect
  to find the [47mtime$[0m output there.

  (2) Unless the [47m:msg[0m argument is supplied, an explicit call of [47mtime$[0m
  in the top-level loop will show that the form being timed is a call
  of the ACL2 evaluator function [47mev-rec[0m.  This is normal; the curious
  are invited, at their own risk, to see [return-last] for an
  explanation.


Subtopics

  [Time-tracker]
      Display time spent during specified evaluation")
 (TIME-LIMIT (POINTERS)
             "See [with-prover-time-limit].")
 (TIME-TRACKER
  (DEBUGGING TIME$ ACL2-BUILT-INS)
  "Display time spent during specified evaluation

  The [47mtime-tracker[0m macro is a utility for displaying time spent during
  specified evaluation.  In general, the user provides this
  specification.  However, ACL2 itself uses this utility for tracking
  uses of its [tau-system] reasoning utility (see
  [time-tracker-tau]).  We discuss that use as an example before
  discussing the general form for calls of [47mtime-tracker[0m.

  Note that by default, the time being tracked is runtime (cpu time);
  to switch to realtime (elapsed time), see [get-internal-time].

  Remark for ACL2(p) users (see [parallelism]): [47mtime-tracker[0m is merely
  a no-op in ACL2(p).

  During the development of the [tau-system], we were concerned about
  the possibility that it would slow down proofs without any
  indication of how one might avoid the problem.  We wanted a utility
  that would alert the user in such situations.  However, the
  tau-system code does not return [state], so we could not track time
  spent in the state.  We developed the [47mtime-tracker[0m utility to track
  time and print messages, and we did it in a general way so that
  others can use it in their own code.  Here is an example of such a
  message that could be printed during a proof.

    TIME-TRACKER-NOTE [:TAU]: Elapsed runtime in tau is 2.58 secs; see
    :DOC time-tracker-tau.

  And here is an example of such a message that could be printed at the
  end of the proof.

    TIME-TRACKER-NOTE [:TAU]: For the proof above, the total time spent
    in the tau system was 20.29 seconds.  See :DOC time-tracker-tau.

  The [47mtime-tracker[0m utility tracks computation time spent on behalf of a
  user-specified ``tag''.  In the case of the tau-system, we chose
  the tag, [47m:tau[0m.  The first argument of [47mtime-tracker[0m is the tag,
  which in our running example is always [47m:tau[0m.  Note that although
  all arguments of [47mtime-tracker[0m are evaluated, the first argument is
  typically a keyword and the second is always a keyword, and such
  arguments evaluate to themselves.

  An ACL2 function invoked at the start of a proof includes
  approximately the following code.

    (progn$
     (time-tracker :tau :end)
     (time-tracker :tau :init
                   :times '(1 2 3 4 5)
                   :interval 5
                   :msg \"Elapsed runtime in tau is ~st secs; see :DOC ~
                         time-tracker-tau.~|~%\")
     ...)

  The first [47mtime-tracker[0m call (above) ends any existing time-tracking
  for tag [47m:tau[0m.  One might have expected it to be put into code
  managing the proof [summary], but we decided not to rely on that
  code being executed, say, in case of an interrupt.  When a given
  tag is not already being time-tracked, then [47m:end[0m is a no-op (rather
  than an error).

  The second [47mtime-tracker[0m call (above) initiates time-tracking for the
  tag, [47m:tau[0m.  Moreover, it specifies the effect of the [47m:print?[0m
  keyword.  Consider the following abbreviated definition from the
  ACL2 source code.

    (defun tau-clausep-lst-rec (clauses ens wrld ans ttree state calist)
      (cond
       ((endp clauses)
        (mv (revappend ans nil) ttree calist))
       (t (mv-let
           (flg1 ttree1 calist)
           (tau-clausep (car clauses) ens wrld state calist)
           (prog2$ (time-tracker :tau :print?)
                   (tau-clausep-lst-rec (cdr clauses) ...))))))

  Notice that [47m(time-tracker :tau :print?)[0m is executed immediately after
  [47mtau-clausep[0m is called.  The idea is to check whether the total time
  elapsed inside the tau-system justifies printing a message to the
  user.  The specification of [47m:times '(1 2 3 4 5)[0m in the [47m:init[0m form
  above says that a message should be printed after 1 second, after 2
  seconds, ..., and after 5 seconds.  Thereafter, the specification
  of [47m:interval 5[0m in the [47m:init[0m form above says that each time we
  print, at least 5 additional seconds should have been tracked
  before [47m(time-tracker :tau :print?)[0m prints again.  Finally, the [47m:msg[0m
  keyword above specifies just what should be printed.  If it is
  omitted, then a reasonable default message is printed (as discussed
  below), but in this case we wanted to print a custom message.  The
  [47m:msg[0m string above is what is printed using formatted printing (see
  [fmt]), where the character [47m#\\t[0m is bound to a string giving a
  decimal representation with two decimal points of the time tracked
  so far for tag [47m:tau[0m.  (As our general description below points out,
  [47m:msg[0m can also be a ``message'' list rather than a string.)

  But when is time actually tracked for [47m:tau[0m?  Consider the following
  definition from the ACL2 source code.

    (defun tau-clausep-lst (clauses ens wrld ans ttree state calist)
      (prog2$ (time-tracker :tau :start!)
              (mv-let
               (clauses ttree calist)
               (tau-clausep-lst-rec clauses ens wrld ans ttree state calist)
               (prog2$ (time-tracker :tau :stop)
                       (mv clauses ttree calist)))))

  The two calls of [47mtime-tracker[0m above first start, and then stop,
  time-tracking for the tag, [47m:tau[0m.  Thus, time is tracked during
  evaluation of the call of [47mtau-clausep-lst-rec[0m, which is the
  function (discussed above) that does the [tau-system]'s work.

  Finally, as noted earlier above, ACL2 may print a time-tracking
  message for tag [47m:tau[0m at the end of a proof.  The ACL2 function
  [47mprint-summary[0m contains essentially the following code.

    (time-tracker :tau :print?
                  :min-time 1
                  :msg \"For the proof above, the total runtime ~
                        spent in the tau system was ~st seconds.  ~
                        See :DOC time-tracker-tau.~|~%\")

  The use of [47m:min-time[0m says that we are to ignore the [47m:times[0m and
  [47m:interval[0m established by the [47m:init[0m call described above, and
  instead, print a message if and only if at least 1 second (since 1
  is the value of keyword [47m:min-time[0m) has been tracked for tag [47m:tau[0m.
  Formatted printing (see [fmt]) is used for the value of [47m:msg[0m, where
  the character [47m#\\t[0m is bound to a decimal string representation of
  the time in seconds, as described above.

  The example above covers all legal values for the second argument of
  [47mtime-tracker[0m and discusses all the additional legal keyword
  arguments.  We conclude with a precise discussion of all arguments.
  Note that all arguments are evaluated; thus when we refer to an
  argument, we are discussing the value of that argument.  All times
  discussed are runtimes, i.e., cpu times, unless that default is
  changed; see [get-internal-time].

    General forms:

    (time-tracker t)        ; enable time-tracking (default)

    (time-tracker nil)      ; disable time-tracking

    (time-tracker tag       ; a symbol other than t or nil
                  option    ; :init, :end, :start, :start!, :stop, or :print?
                  ;; keyword arguments:
                  :times    ; non-nil if and only if option is :init
                  :interval ; may only be non-nil with :init option
                  :min-time ; may only be non-nil with :print? option
                  :msg      ; may only be non-nil with :init and :print? options

  Time-tracking is enabled by default.  If the first argument is [47mt[0m or
  [47mnil[0m, then no other arguments are permitted and time-tracking is
  enabled or disabled, respectively.  When time-tracking is disabled,
  nothing below takes place.  Thus we assume time-tracking is enabled
  for the remainder of this discussion.  We also assume below that
  the first argument is neither [47mt[0m nor [47mnil[0m.

  We introduce some basic notions about time-tracking.  A given tag,
  such as [47m:tau[0m in the example above, might or might not currently be
  ``tracked'': [47m:init[0m causes the specified tag to be tracked, while
  [47m:end[0m causes the specified tag not to be tracked.  If the tag is
  being tracked, the tag might or might not be ``active'': [47m:start[0m and
  [47m:start![0m cause the tag to be in an active state, while [47m:stop[0m causes
  the tag not to be active.  Note that only tracked tags can be in an
  active or inactive state.  For a tag that is being tracked, the
  ``accumulated time'' is the total time spent in an active state
  since the time that the tag most recently started being tracked,
  and the ``checkpoint list'' is a non-empty list of rational numbers
  specifying when printing may take place, as described below.

  We now consider each legal value for the second argument, or
  ``option'', for a call of [47mtime-tracker[0m on a given tag.

  [47m:Init[0m specifies that the tag is to be tracked.  It also establishes
  defaults for the operation of [47m:print?[0m, as described below, using
  the [47m:times[0m, [47m:interval[0m, and [47m:msg[0m keywords.  Of these three, only
  [47m:times[0m is required, and its value must be a non-empty list of
  rational numbers specifying the initial checkpoint list for the
  tag.  It is an error to specify [47m:init[0m if the tag is already being
  tracked.  (So if you don't care whether or not the tag is already
  being tracked and you want to initiate tracking for that tag, use
  [47m:end[0m first.)

  [47m:End[0m specifies that if the tag is being tracked, then it should stop
  being tracked.  If the tag is not being tracked, then [47m:end[0m has no
  effect.

  [47m:Start[0m specifies that the tag is to be active.  It is an error to
  specify [47m:start[0m if the tag is not being tracked or is already
  active.

  [47m:Start![0m has the same effect as [47m:start[0m, except that it does not cause
  an error when the tag is already active.  In effect, [47m:start![0m first
  invokes [47m:stop[0m if the tag is already active, and then invokes [47mstart[0m.

  [47m:Stop[0m specifies that the tag is to stop being active.  It is an error
  to specify [47m:stop[0m if the tag is not being tracked or is not active.

  [47m:Print?[0m specifies that if the tag is being tracked (not necessarily
  active), then a message should be printed if a suitable condition
  is met.  The nature of that message and that condition depend on
  the keyword options supplied with [47m:print?[0m as well as those supplied
  with the [47m:init[0m option that most recently initiated tracking.
  [47m:Print?[0m has no effect if the tag is not being tracked, except that
  if certain keyword values are checked if supplied with [47m:print?[0m:
  [47m:min-time[0m must be a rational number or [47mnil[0m, and [47m:msg[0m must be either
  a string, a true-list whose [47mcar[0m is a string, or [47mnil[0m.  The remainder
  of this documentation describes the [47m:print?[0m option in detail under
  the assumption that the tag is being tracked: first, giving the
  conditions under which it causes a message to be printed, and
  second, explaining what is printed.

  When [47m:print?[0m is supplied a non-[47mnil[0m value of [47m:min-time[0m, that value
  must be a rational number, in which case a message is printed if
  the accumulated time for the tag is at least that value.  Otherwise
  a message is printed if the accumulated time is greater than or
  equal to the [47mcar[0m of the checkpoint list for the tag.  In that case,
  the tracking state for the tag is updated in the following two
  ways.  First, the checkpoint list is scanned from the front and as
  long as the accumulated time is greater than or equal to the [47mcar[0m of
  the remaining checkpoint list, that [47mcar[0m is popped off the
  checkpoint list.  Second, if the checkpoint list has been
  completely emptied and a non-[47mnil[0m [47m:interval[0m was supplied when
  tracking was most recently initiated with the [47m:init[0m option, then
  the checkpoint list is set to contain a single element, namely the
  sum of the accumulated time with that value of [47m:interval[0m.

  Finally, suppose the above criteria are met, so that [47m:print?[0m results
  in printing of a message.  We describe below the message, [47mmsg[0m, that
  is printed.  Here is how it is printed (see [fmt]), where
  [47mseconds-as-decimal-string[0m is a string denoting the number of
  seconds of accumulated time for the tag, with two digits after the
  decimal point.

    (fms \"TIME-TRACKER-NOTE [~x0]: ~@1~|\"
         (list (cons #0 tag)
               (cons #1 msg)
               (cons #t seconds-as-decimal-string))
         (proofs-co state) state nil)

  The value of [47mmsg[0m is the value of the [47m:msg[0m keyword supplied with
  [47m:print?[0m, if non-[47mnil[0m; else, the value of [47m:msg[0m supplied when most
  recently initialization with the [47m:init[0m option, if non-[47mnil[0m; and
  otherwise, the string [47m\"~st s\"[0m (the final ``s'' abbreviating the
  word ``seconds'').  It is convenient to supply [47m:msg[0m as a call [47m(msg
  str arg-0 arg-1 ... arg-k)[0m, where [47mstr[0m is a string and each [47marg-i[0m is
  the value to be associated with [47m#\\i[0m upon formatted printing (as
  with [47m[fmt][0m) of the string [47mstr[0m.")
 (TIME-TRACKER-TAU
  (TAU-SYSTEM)
  "Messages about expensive use of the [tau-system]

  This [documentation] topic explains messages printing by the theorem
  prover about the [tau-system], as follows.

  During a proof you may see a message such as the following.

    TIME-TRACKER-NOTE [:TAU]: Elapsed runtime in tau is 4.95 secs; see
    :DOC time-tracker-tau.

  Just below a proof [summary] you may see a message such as the
  following.

    TIME-TRACKER-NOTE [:TAU]: For the proof above, the total runtime spent
    in the tau system was 30.01 seconds.  See :DOC time-tracker-tau.

  Both of these messages are intended to let you know that certain
  prover heuristics (see [tau-system]) may be slowing proofs down
  more than they are helping.  If you are satisfied with the prover's
  performance, you may ignore these messages or even turn them off by
  disabling time-tracking entirely (see [time-tracker]).  Otherwise,
  here are some actions that you can take to solve such a performance
  problem.

  The simplest solution is to disable the tau-system, in either of the
  following equivalent ways.

    (in-theory (disable (:executable-counterpart tau-system)))
    (in-theory (disable (tau-system)))

  But if you want to leave the tau-system enabled, you could
  investigate the possibility that the tau-system is causing an
  expensive [47m:[0m[47m[logic][0m-mode function to be executed.  You can diagnose
  that problem by observing the rewriter --- see [dmr] --- or by
  interrupting the system and getting a backtrace (see
  [set-debugger-enable]).  A solution in that case is to disable the
  [executable-counterpart] of that function, for example in any of
  these equivalent ways.

    (in-theory (disable (:executable-counterpart foo)))
    (in-theory (disable (:e foo)))
    (in-theory (disable (foo)))

  As a result, the tau-system will be weakened, but perhaps only
  negligibly.

  In either case above, you may prefer to provide [47m:[0m[47m[in-theory][0m hints
  rather than [47m:in-theory[0m [events]; see [hints].

  A more sophisticated solution is to record values of the
  [47m:[0m[47m[logic][0m-mode function in question, so that the tau-system will
  look up the necessary values rather than calling the function,
  whether or not the executable-counterpart of that function is
  enabled.  Here is an example of a lemma that can provide such a
  solution.  See [tau-system].

    (defthm lemma
      (and (foo 0)
           (foo 17)
           (foo t)
           (not (foo '(a b c))))
      :rule-classes :tau-system)")
 (TIPS
  (ACL2-TUTORIAL)
  "Some hints for using the ACL2 prover

  We present here some tips for using ACL2 effectively.  Though this
  collection is somewhat [3mad hoc[0m, we try to provide some organization,
  albeit somewhat artificial: for example, the sections overlap, and
  no particular order is intended.  This material has been adapted by
  Bill Young from a very similar list for Nqthm that appeared in the
  conclusion of: ``Interaction with the Boyer-Moore Theorem Prover: A
  Tutorial Study Using the Arithmetic-Geometric Mean Theorem,'' by
  Matt Kaufmann and Paolo Pecchiari, CLI Technical Report 100, June,
  1995.  We also draw from a similar list in Chapter 13 of ``A
  Computational Logic Handbook'' by R.S. Boyer and J S. Moore
  (Academic Press, 1988).  We'll refer to this as ``ACLH'' below.

  These tips are organized roughly as follows.

      A. ACL2 Basics

      B. Strategies for creating events

      C. Dealing with failed proofs

      D. Performance tips

      E. Miscellaneous tips and knowledge

      F. Some things you DON'T need to know

  [3mACL2 BASICS[0m

  [31;1mA1. The ACL2 logic.[0m
  This is a logic of total functions.  For example, if [47mA[0m and [47mB[0m are
  less than or equal to each other, then we need to know something
  more in order to conclude that they are equal (e.g., that they are
  numbers).  This kind of twist is important in writing definitions;
  for example, if you expect a function to return a number, you may
  want to apply the function [47m[fix][0m or some variant (e.g., [47m[nfix][0m or
  [47m[ifix][0m) in case one of the formals is to be returned as the value.

  ACL2's notion of ordinals is important on occasion in supplying
  ``measure [hints]'' for the acceptance of recursive definitions.
  Be sure that your measure is really an ordinal.  Consider the
  following example, which ACL2 fails to admit (as explained below).

    (defun cnt (name a i x)
      (declare (xargs :measure (+ 1 i)))
      (cond ((zp (+ 1 i))
             0)
            ((equal x (aref1 name a i))
             (1+ (cnt name a (1- i) x)))
            (t (cnt name a (1- i) x))))

  One might think that [47m(+ 1 i)[0m is a reasonable measure, since we know
  that [47m(+ 1 i)[0m is a positive integer in any recursive call of [47mcnt[0m,
  and positive integers are ACL2 ordinals (see [o-p]).  However, the
  ACL2 logic requires that the measure be an ordinal unconditionally,
  not just under the governing assumptions that lead to recursive
  calls.  An appropriate fix is to apply [47m[nfix][0m to [47m(+ 1 i)[0m, i.e., to
  use

    (declare (xargs :measure (nfix (+ 1 i))))

  in order to guarantee that the measure will always be an ordinal (in
  fact, a positive integer).

  For more about admissibility of recursive definitions, see [defun],
  in particular the discussion of termination.

  [31;1mA2. Simplification.[0m
  The ACL2 simplifier is basically a rewriter, with some ``[linear]
  arithmetic'' thrown in.  One needs to understand the notion of
  conditional rewriting.  See [rewrite].

  [31;1mA3. Parsing of rewrite rules.[0m

  ACL2 parses [rewrite] rules roughly as explained in ACLH, [3mexcept[0m that
  it never creates ``unusual'' rule classes.  In ACL2, if you want a
  [47m:[0m[47m[linear][0m rule, for example, you must specify [47m:[0m[47m[linear][0m in the
  [47m:[0m[47m[rule-classes][0m.  See [rule-classes], and also see [rewrite] and
  see [linear].

  [31;1mA4. Linear arithmetic.[0m
  On this subject, it should suffice to know that the prover can
  handle truths about [47m[+][0m and [47m[-][0m, and that [linear] rules (see
  above) are somehow ``thrown in the pot'' when the prover is doing
  such reasoning.  Perhaps it's also useful to know that [linear]
  rules can have hypotheses, and that conditional rewriting is used
  to relieve those hypotheses.

  [31;1mA5. Events.[0m
  Over time, the expert ACL2 user will know some subtleties of its
  [events].  For example, [47m[in-theory][0m [events] and [hints] are
  important, and they distinguish between a function's definition and
  its [executable-counterpart].

  [3mB. STRATEGIES FOR CREATING EVENTS[0m

  In this section, we concentrate on the use of definitions and
  [rewrite] rules.  There are quite a few kinds of rules allowed in
  ACL2 besides [rewrite] rules, though most beginning users probably
  won't usually need to be aware of them.  See [rule-classes] for
  details.  In particular, there is support for [congruence]
  rewriting.  Also see [rune] (``RUle NamE'') for a description of
  the various kinds of rules in the system.

  [31;1mB1. Use high-level strategy.[0m
  Decompose theorems into ``manageable'' lemmas (admittedly,
  experience helps here) that yield the main result ``easily.'' It's
  important to be able to outline non-trivial proofs by hand (or in
  your head).  In particular, avoid submitting goals to the prover
  when there's no reason to believe that the goal will be proved and
  there's no ``sense'' of how an induction argument would apply.  It
  is often a good idea to avoid induction in complicated theorems
  unless you have a reason to believe that it is appropriate.

  [31;1mB2. Write elegant definitions.[0m
  Try to write definitions in a reasonably modular style, especially
  recursive ones.  Think of ACL2 as a [programming] language whose
  procedures are definitions and lemmas, hence we are really
  suggesting that one follow good [programming] style (in order to
  avoid duplication of ``code,'' for example).

  When possible, complex functions are best written as compositions of
  simpler functions.  The theorem prover generally performs better on
  primitive recursive functions than on more complicated recursions
  (such as those using accumulating parameters).

  Avoid large non-recursive definitions which tend to lead to large
  case explosions.  If such definitions are necessary, try to prove
  all relevant facts about the definitions and then [disable] them.

  Whenever possible, avoid mutual recursion if you care to prove
  anything about your functions.  The induction heuristics provide
  essentially no help with reasoning about mutually defined
  functions.  Mutually recursive functions can usually be combined
  into a single function with a ``flag'' argument.  (However, see
  [mutual-recursion-proof-example] for a small example of proof
  involving mutually recursive functions.)

  [31;1mB3. Look for analogies.[0m
  Sometimes you can easily edit sequences of lemmas into sequences of
  lemmas about analogous functions.

  [31;1mB4. Write useful rewrite rules.[0m
  As explained in A3 above, every [rewrite] rule is a directive to the
  theorem prover, usually to replace one [term] by another.  The
  directive generated is determined by the syntax of the [47m[defthm][0m
  submitted.  Never submit a [rewrite] rule unless you have
  considered its interpretation as a proof directive.

  [31;1mB4a.  Rewrite rules should simplify.[0m
  Try to write [rewrite] rules whose right-hand sides are in some
  sense ``simpler than'' (or at worst, are variants of) the left-hand
  sides.  This will help to avoid infinite loops in the rewriter.

  [31;1mB4b.  Avoid needlessly expensive rules.[0m
  Consider a rule whose conclusion's left-hand side (or, the entire
  conclusion) is a [term] such as [47m(consp x)[0m that matches many [term]s
  encountered by the prover.  If in addition the rule has complicated
  hypotheses, this rule could slow down the prover greatly.  Consider
  switching the conclusion and a complicated hypothesis (negating
  each) in that case.

  [31;1mB4c. The ``Knuth-Bendix problem''.[0m
  Be aware that left sides of [rewrite] rules should match the
  ``normalized forms'', where ``normalization'' (rewriting) is inside
  out.  Be sure to avoid the use of nonrecursive function symbols on
  left sides of [rewrite] rules, except when those function symbols
  are [disable]d, because they tend to be expanded away before the
  rewriter would encounter an instance of the left side of the rule.
  Also assure that subexpressions on the left hand side of a rewrite
  rule are in simplified form; see [community-books] example
  [47mbooks/demos/knuth-bendix-problem-1.lisp[0m.

  [31;1mB4d. Avoid proving useless rules.[0m
  Sometimes it's tempting to prove a [rewrite] rule even before you
  see how it might find application.  If the rule seems clean and
  important, and not unduly expensive, that's probably fine,
  especially if it's not too hard to prove.  But unless it's either
  part of the high-level strategy or, on the other hand, intended to
  get the prover past a particular unproved goal, it may simply waste
  your time to prove the rule, and then clutter the database of rules
  if you are successful.

  [31;1mB4e. State rules as strongly as possible, usually.[0m
  It's usually a good idea to state a rule in the strongest way
  possible, both by eliminating unnecessary hypotheses and by
  generalizing subexpressions to variables.

  Advanced users may choose to violate this policy on occasion, for
  example in order to avoid slowing down the prover by excessive
  attempted application of the rule.  However, it's a good rule of
  thumb to make the strongest rule possible, not only because it will
  then apply more often, but also because the rule will often be
  easier to prove (see also B6 below).  New users are sometimes
  tempted to put in extra hypotheses that have a ``type restriction''
  appearance, without realizing that the way ACL2 handles (total)
  functions generally lets it handle trivial cases easily.

  [31;1mB4f. Avoid circularity.[0m
  A stack overflow in a proof attempt almost always results from
  circular rewriting.  Use [47m[brr][0m to investigate the stack; see
  [break-lemma].  Because of the complex heuristics, it is not always
  easy to define just when a [rewrite] will cause circularity.  See
  the very good discussion of this topic in ACLH.

  See [break-lemma] for a trick involving use of the forms [47mbrr t[0m and
  [47m(cw-gstack)[0m for inspecting loops in the rewriter.

  [31;1mB4g. Remember restrictions on permutative rules.[0m
  Any rule that permutes the variables in its left hand side could
  cause circularity.  For example, the following axiom is
  automatically supplied by the system:

    (defaxiom commutativity-of-+
              (equal (+ x y) (+ y x))).

  This would obviously lead to dangerous circular rewriting if such
  ``permutative'' rules were not governed by a further restriction.
  The restriction is that such rules will not produce a [term] that
  is ``lexicographically larger than'' the original [term] (see
  [loop-stopper]).  However, this sometimes prevents intended
  rewrites.  See Chapter 13 of ACLH for a discussion of this problem.

  [31;1mB5. Conditional vs. unconditional rewrite rules.[0m
  It's generally preferable to form unconditional [rewrite] rules
  unless there is a danger of case explosion.  That is, rather than
  pairs of rules such as

    (implies p
             (equal term1 term2))

  and

    (implies (not p)
             (equal term1 term3))

  consider:

    (equal term1
           (if p term2 term3))

  However, sometimes this strategy can lead to case explosions: [47m[if][0m
  [term]s introduce cases in ACL2.  Use your judgment.  (On the
  subject of [47m[if][0m: [47m[cond][0m, [47m[case][0m, [47m[and][0m, and [47m[or][0m are macros that
  abbreviate [47m[if][0m forms, and propositional functions such as
  [47m[implies][0m quickly expand into [47m[if][0m [term]s.)

  [31;1mB6. Create elegant theorems.[0m
  Try to formulate lemmas that are as simple and general as possible.
  For example, sometimes properties about several functions can be
  ``factored'' into lemmas about one function at a time.  Sometimes
  the elimination of unnecessary hypotheses makes the theorem easier
  to prove, as does generalizing first by hand.

  [31;1mB7. Use[0m [47m[defaxiom][0ms [31;1mtemporarily to explore possibilities.[0m
  When there is a difficult goal that seems to follow immediately (by
  a [47m:use[0m hint or by rewriting) from some other lemmas, you can create
  those lemmas as [47m[defaxiom][0m [events] (or, the application of
  [47m[skip-proofs][0m to [47m[defthm][0m [events]) and then double-check that the
  difficult goal really does follow from them.  Then you can go back
  and try to turn each [47m[defaxiom][0m into a [47m[defthm][0m.  When you do that,
  it's often useful to [disable] any additional [rewrite] rules that
  you prove in the process, so that the ``difficult goal'' will still
  be proved from its lemmas when the process is complete.

  Better yet, rather than disabling [rewrite] rules, use the [47m[local][0m
  mechanism offered by [47m[encapsulate][0m to make temporary rules
  completely [47m[local][0m to the problem at hand.  See [encapsulate] and
  see [local].

  [31;1mB9. Use books.[0m
  Consider using previously certified [books], especially for
  [arithmetic] reasoning.  This cuts down the duplication of effort
  and starts your specification and proof effort from a richer
  foundation.  See [community-books].

  [3mC. DEALING WITH FAILED PROOFS[0m

  [31;1mC1. Look in proof output for goals that can't be further simplified.[0m
  Use the ``[proof-tree]'' utility to explore the proof space.
  However, you don't need to use that tool to use the ``checkpoint''
  strategy.  The idea is to think of ACL2 as a ``simplifier'' that
  either proves the theorem or generates some goal to consider.  That
  goal is the first ``checkpoint,'' i.e., the first goal that does
  not further simplify.  Exception: it's also important to look at
  the induction scheme in a proof by induction, and if induction
  seems appropriate, then look at the first checkpoint [3mafter[0m the
  induction has begun.

  Consider whether the goal on which you focus is even a theorem.
  Sometimes you can execute it for particular values to find a
  counterexample.

  When looking at checkpoints, remember that you are looking for any
  reason at all to believe the goal is a theorem.  So for example,
  sometimes there may be a contradiction in the hypotheses.

  Don't be afraid to skip the first checkpoint if it doesn't seem very
  helpful.  Also, be willing to look a few lines up or down from the
  checkpoint if you are stuck, bearing in mind however that this
  practice can be more distracting than helpful.

  [31;1mC2. Use the ``break rewrite'' facility.[0m
  [47m[Brr][0m and related utilities let you inspect the ``rewrite stack.''
  These can be valuable tools in large proof efforts.  See
  [break-lemma] for an introduction to these tools, and see
  [break-rewrite] for more complete information.

  The break facility is especially helpful in showing you why a
  particular rewrite rule is not being applied.

  [31;1mC3. Use induction hints when necessary.[0m Of course, if you can define
  your functions so that they suggest the correct inductions to ACL2,
  so much the better!  But for complicated inductions, induction
  [hints] are crucial.  See [hints] for a description of [47m:induct[0m
  [hints].

  [31;1mC4. Use the interactive ``Proof-Builder'' to explore.[0m
  The [47m[verify][0m command supplied by ACL2 allows one to explore problem
  areas ``by hand.'' However, even if you succeed in proving a
  conjecture with [47m[verify][0m, it is useful to prove it without using
  it, an activity that will often require the discovery of [rewrite]
  rules that will be useful in later proofs as well.

  [31;1mC5. Don't have too much patience.[0m
  Interrupt the prover fairly quickly when simplification isn't
  succeeding.

  [31;1mC6. Simplify rewrite rules.[0m
  When it looks difficult to relieve the hypotheses of an existing
  [rewrite] rule that ``should'' apply in a given setting, ask
  yourself if you can eliminate a hypothesis from the existing
  [rewrite] rule.  If so, it may be easier to prove the new version
  from the old version (and some additional lemmas), rather than to
  start from scratch.

  [31;1mC7. Deal with base cases first.[0m
  Try getting past the base case(s) first in a difficult proof by
  induction.  Usually they're easier than the inductive step(s), and
  rules developed in proving them can be useful in the inductive
  step(s) too.  Moreover, it's pretty common that mistakes in the
  statement of a theorem show up in the base case(s) of its proof by
  induction.

  [31;1mC8. Use[0m [47m:expand[0m [31;1mhints.[0m Consider giving [47m:expand[0m [hints].  These are
  especially useful when a proof by induction is failing.  It's
  almost always helpful to open up a recursively defined function
  that is supplying the induction scheme, but sometimes ACL2 is too
  timid to do so; or perhaps the function in question is [disable]d.

  [3mD. PERFORMANCE TIPS[0m

  [31;1mD1. Disable rules.[0m
  There are a number of instances when it is crucial to [disable]
  rules, including (often) those named explicitly in [47m:use[0m [hints].
  Also, [disable] recursively defined functions for which you can
  prove what seem to be all the relevant properties.  The prover can
  spend significant time ``behind the scenes'' trying to open up
  recursively defined functions, where the only visible effect is
  slowness.

  [31;1mD2. Turn off the ``break rewrite'' facility.[0m Remember to execute [47m:brr
  nil[0m after you've finished with the ``break rewrite'' utility (see
  [break-rewrite]), in order to bring the prover back up to full
  speed.

  [3mE. MISCELLANEOUS TIPS AND KNOWLEDGE[0m

  [31;1mE1. Order of application of rewrite rules.[0m
  Keep in mind that the most recent [rewrite] rules in the [history]
  are tried first.

  [31;1mE2. Relieving hypotheses is not full-blown theorem proving.[0m
  Relieving hypotheses on [rewrite] rules is done by rewriting and
  [linear] arithmetic alone, not by case splitting or by other prover
  processes ``below'' simplification.

  [31;1mE3. ``Free variables'' in rewrite rules.[0m
  The set of ``free variables'' of a [rewrite] rule is defined to
  contain those variables occurring in the rule that do not occur in
  the left-hand side of the rule.  It's often a good idea to avoid
  rules containing free variables because they are ``weak,'' in the
  sense that hypotheses containing such variables can generally only
  be proved when they are ``obviously'' present in the current
  context.  This weakness suggests that it's important to put the
  most ``interesting'' (specific) hypotheses about free variables
  first, so that the right instances are considered.  For example,
  suppose you put a very general hypothesis such as [47m(consp x)[0m first.
  If the context has several [term]s around that are known to be
  [47m[consp][0ms, then [47mx[0m may be bound to the wrong one of them.  For much
  more information on free variables, see [free-variables].

  [31;1mE4. Obtaining information[0m
  Use [47m:[0m[47m[pl][0m [47mfoo[0m to inspect [rewrite] rules whose left hand sides are
  applications of the function [47mfoo[0m.  Another approach to seeing which
  [rewrite] rules apply is to enter the interactive [proof-builder]
  with [47m[verify][0m, and use the [47mshow-rewrites[0m or [47msr[0m command.

  [31;1mE5. Consider esoteric rules with care.[0m
  If you care to see [rule-classes] and peruse the list of subtopics
  (which will be listed right there in most versions of this
  [documentation]), you'll see that ACL2 supports a wide variety of
  rules in addition to [47m:[0m[rewrite] rules.  Should you use them?  This
  is a complex question that we are not ready to answer with any
  generality.  Our general advice is to avoid relying on such rules
  as long as you doubt their utility.  More specifically: be careful
  not to use conditional type prescription rules, as these have been
  known to bring ACL2 to its knees, unless you are conscious that you
  are doing so and have reason to believe that they are working well.

  [3mF. SOME THINGS YOU DON'T NEED TO KNOW[0m

  Most generally: you shouldn't usually need to be able to predict too
  much about ACL2's behavior.  You should mainly just need to be able
  to react to it.

  [31;1mF1. Induction heuristics.[0m
  Although it is often important to read the part of the prover's
  output that gives the induction scheme chosen by the prover, it is
  not necessary to understand how the prover made that choice.
  (Granted, advanced users may occasionally gain minor insight from
  such knowledge.  But it's truly minor in many cases.)  What [3mis[0m
  important is to be able to tell it an appropriate induction when it
  doesn't pick the right one (after noticing that it doesn't).  See
  C3 above.

  [31;1mF2. Heuristics for expanding calls of recursively defined functions.[0m
  As with the previous topic, the important thing isn't to understand
  these heuristics but, rather, to deal with cases where they don't
  seem to be working.  That amounts to supplying [47m:expand[0m [hints] for
  those calls that you want opened up, which aren't.  See also C8
  above.

  [31;1mF3. The ``waterfall''.[0m
  As discussed many times already, a good strategy for using ACL2 is
  to look for checkpoints (goals stable under simplification) when a
  proof fails, perhaps using the [proof-tree] facility.  Thus, it is
  reasonable to ignore almost all the prover output, and to avoid
  pondering the meaning of the other ``processes'' that ACL2 uses
  besides simplification (such as elimination, cross-fertilization,
  generalization, and elimination of irrelevance).")
 (TO-DF (POINTERS) "See [df].")
 (TO-DFP (POINTERS) "See [df].")
 (TOGGLE-INHIBIT-ER
  (OUTPUT-CONTROLS ERRORS)
  "Add or delete an error output string from the [47minhibit-er-table[0m

  See [set-inhibit-er] for relevant background.

    General Form:
    (toggle-inhibit-er string)

  where [47mstring[0m is the name of some error output like [47m\"Translate\"[0m or
  [47m\"Failure\"[0m.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [toggle-inhibit-er!] for a corresponding non-[47m[local][0m
  event.  Indeed, [47m(toggle-inhibit-er str)[0m is equivalent to [47m(local
  (toggle-inhibit-er! str))[0m.

  The given string is added to the list of strings used for inhibiting
  error output if it is not there already and is deleted from the
  list if it is there.  Case is unimportant in [47mstring[0m.  See
  [47m[set-inhibit-er][0m.")
 (TOGGLE-INHIBIT-ER!
  (OUTPUT-CONTROLS ERRORS)
  "Toggle an [47minhibit-er-table[0m entry non-[47m[local][0mly

  Please see [toggle-inhibit-er], which is the same as
  [47mtoggle-inhibit-er![0m except that the latter is not [47m[local][0m to the
  [47m[encapsulate][0m or the book in which it occurs.  Probably
  [toggle-inhibit-er] is to be preferred unless you have a good
  reason for wanting to export the effect of this event outside the
  enclosing [47m[encapsulate][0m or book.")
 (TOGGLE-INHIBIT-WARNING
  (OUTPUT-CONTROLS)
  "Add or delete a warning string from the [47minhibit-warnings-table[0m

    General Form:
    (toggle-inhibit-warning string)

  where [47mstring[0m is the name of some warning like [47m\"Subsume\"[0m, [47m\"Non-rec\"[0m or
  [47m\"Rewrite-lambda-object\"[0m.

  Note: This is an event!  It does not print the usual event [summary]
  but nevertheless changes the ACL2 logical [world] and is so
  recorded.  It is [47m[local][0m to the book or [47m[encapsulate][0m form in which
  it occurs; see [toggle-inhibit-warning!] for a corresponding
  non-[47m[local][0m event.  Indeed, [47m(toggle-inhibit-warning str)[0m is
  equivalent to [47m(local (toggle-inhibit-warning! str))[0m.

  The given string is added to the list of inhibited warnings if it is
  not there already and is deleted from the list if it is there.
  Case is unimportant in [47mstring[0m.  See [47m[set-inhibit-warnings][0m.")
 (TOGGLE-INHIBIT-WARNING!
  (OUTPUT-CONTROLS)
  "Toggle an [47minhibit-warnings-table[0m entry non-[47m[local][0mly

  Please see [toggle-inhibit-warning], which is the same as
  [47mtoggle-inhibit-warning![0m except that the latter is not [47m[local][0m to
  the [47m[encapsulate][0m or the book in which it occurs.  Probably
  [toggle-inhibit-warning] is to be preferred unless you have a good
  reason for wanting to export the effect of this event outside the
  enclosing [47m[encapsulate][0m or book.")
 (TOGGLE-PC-MACRO
  (PROOF-BUILDER)
  "Change an ordinary macro command to an atomic macro, or vice-versa

    Example:
    (toggle-pc-macro pro)

  Change [47mpro[0m from an atomic macro command to an ordinary one (or
  vice-versa, if [47mpro[0m happens to be an ordinary macro command)

    General Form:
    (toggle-pc-macro name &optional new-tp)

  If name is an atomic macro command then this turns it into an
  ordinary one, and vice-versa.  However, if [47mnew-tp[0m is supplied and
  not [47mnil[0m, then it should be the new type (the symbol [47mmacro[0m or
  [47matomic-macro[0m, in any package), or else there is no change.")
 (TOO-MANY-IFS (POINTERS)
               "See [efficiency].")
 (TOP-LEVEL
  (MISCELLANEOUS)
  "Evaluate a top-level form as a function body

  Some forms, such as calls of [47m[with-local-stobj][0m, are illegal when
  supplied directly to the ACL2 top-level loop.  The macro [47mtop-level[0m
  provides a workaround in such cases, by defining a temporary
  [47m:[0m[47m[program][0m-mode function named [47mtop-level-fn[0m whose only argument is
  [47mstate[0m and whose body is the form to be evaluated.  When the call of
  [47mtop-level[0m returns there is no change to the existing ACL2 logical
  [world].  The following edited log illustrates all of the above
  points.

    ACL2 !>:pbt 0
              0  (EXIT-BOOT-STRAP-MODE)
    ACL2 !>(defstobj st fld)

    Summary
    Form:  ( DEFSTOBJ ST ...)
    Rules: NIL
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
     ST
    ACL2 !>(top-level
            (with-local-stobj
             st
             (mv-let (result st)
                     (let ((st (update-fld 17 st)))
                       (mv (fld st) st))
                     result)))
    17
    ACL2 !>(top-level
            (with-local-stobj
             st
             (mv-let (result st)
                     (let ((st (update-fld 17 st)))
                       (mv (fld st) st))
                     (mv nil result state))))
     17
    ACL2 !>(top-level
            (with-local-stobj
             st
             (mv-let (result st)
                     (let ((st (update-fld 17 st)))
                       (mv (fld st) st))
                     (mv result state))))
    (17 <state>)
    ACL2 !>:pbt 0
              0  (EXIT-BOOT-STRAP-MODE)
       d      1:x(DEFSTOBJ ST FLD)
    ACL2 !>

  Each argument of [47mtop-level[0m after the first should be a [47m[declare][0m form
  or [documentation] string, as the list of these extra arguments
  will be placed before the first argument when forming the
  definition of [47mtop-level-fn[0m.

  [47m[Top-level][0m generates a call of [47m[ld][0m, so that the value returned is
  printed in the normal way.  The call of [47m[top-level][0m itself actually
  evaluates to [47m(mv erp :invisible state)[0m, where [47merp[0m is [47mt[0m if and only
  evaluation of the call of [47mtop-level-fn[0m caused an error, which
  normally results in no additional output.  (For details about
  ``caused an error'', see the definition of [47mtop-level[0m in the ACL2
  source code, and see [ld-error-action].)

  Since the defined function [47mtop-level[0m takes only [47mstate[0m as a parameter,
  the given form should not include any user-defined [stobj]s that
  occur free in the form.

  Finally, note that since [47mtop-level[0m runs a function that is defined in
  [47m:[0m[47m[program][0m mode, it is possible for a raw lisp error to occur.
  Here is an example.

    ACL2 !>(top-level (car 3))

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  The value 3 is not of the expected type LIST.
    While executing: CAR
    ***********************************************")
 (TOP-LEVEL-LOOP (POINTERS)
                 "See [guarantees-of-the-top-level-loop].")
 (TRACE
  (DEBUGGING)
  "Tracing functions in ACL2

  ACL2 provides a trace utility, [47m[trace$][0m, with corresponding reverse
  operation [47m[untrace$][0m.  These can be used without any dependence on
  the underlying Lisp utility, and are the tracing utilities of
  choice in ACL2; see [trace$] and see [untrace$].

  However, for advanced users we note that the underlying host Lisp may
  also provide a trace utility, [47mtrace[0m, and corresponding [47muntrace[0m.
  Moreover, these have been modified in the case that the host Lisp
  is GCL, Allegro CL, or CCL (OpenMCL), to provide limited support
  for [47m:entry[0m, [47m:exit[0m, and perhaps [47m:cond[0m keywords, to hide certain
  large data structures (world, enabled structure, rewrite constant),
  and to trace executable-counterparts (see [evaluation]).  See
  source files [47m*-trace.lisp[0m.  For the above Lisps, you can invoke the
  original [47mtrace[0m and [47muntrace[0m by invoking [47mold-trace[0m and [47mold-untrace[0m,
  respectively, in raw Lisp rather than in the normal ACL2 loop.


Subtopics

  [Break-on-error]
      Break when encountering a hard or soft error caused by ACL2

  [Close-trace-file]
      Stop redirecting trace output to a file

  [Open-trace-file]
      Redirect trace output to a file

  [Set-trace-evisc-tuple]
      Set the trace evisc tuple

  [Trace!]
      Trace the indicated functions after creating an active trust tag

  [Trace$]
      Trace function evaluations

  [Untrace$]
      Untrace functions

  [Wet]
      Evaluate a form and print subsequent error trace")
 (TRACE!
  (TRACE)
  "Trace the indicated functions after creating an active trust tag

    Example:
    (trace! (fact :native t :entry *foo*))

    General Form:
    (trace! spec1 ... specn)

  where the [47mspeci[0m are suitable arguments to [47m[trace$][0m.

  See [trace$] for a way to trace function calls.  Some calls of [47mtrace$[0m
  are potentially dangerous and thus require a trust tag (see
  [defttag]).  But it can be a nuisance to call [47mdefttag[0m explicitly,
  so the [47mtrace![0m macro is provided in order to avoid the need to do
  that: [47mtrace![0m automatically defines a (temporary) trust tag.

  See [untrace$] for how to undo the effect of [47m[trace!][0m.

  The evaluation of a [47mtrace![0m form causes temporary creation of an
  active trust tag, [47m:trace![0m, followed by the corresponding [47mtrace$[0m
  form.  The trust tag will disappear when the call to [47mtrace![0m
  completes.  Even though [47mtrace![0m will remove its temporary ttag, it
  will still print a ``[47mTTAG NOTE[0m'', which indicates that the session
  is suspect.  See [defttag] and see [ttags-seen] for further remarks
  on this issue.

  Because of the active trust tag, it is possible to do things with
  [47mtrace![0m that are useful but without logical justification.  Below is
  an example of how to use [47mtrace![0m to cause a function call to change
  [state], even though the function does not take [47m[state][0m as a
  parameter.  Note: It may be helpful to see [evaluation] in order to
  understand the package prefix [47m\"ACL2_*1*_ACL2\"[0m displayed below.

    ACL2 !>(defun fact (n)
             (declare (xargs :guard (natp n) :verify-guards nil))
             (if (zp n)
                 1
               (* n (fact (1- n)))))

    The admission of FACT 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 N).  We observe that the type of FACT is described by the
    theorem (AND (INTEGERP (FACT N)) (< 0 (FACT N))).  We used the :compound-
    recognizer rule ZP-COMPOUND-RECOGNIZER and primitive type reasoning.

    Summary
    Form:  ( DEFUN FACT ...)
    Rules: ((:COMPOUND-RECOGNIZER ZP-COMPOUND-RECOGNIZER)
            (:FAKE-RUNE-FOR-TYPE-SET NIL))
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     FACT
    ACL2 !>(defun update-foo (n value state)
             (declare (xargs :stobjs state :verify-guards nil))
             (assign foo (cons (cons n value) (@ foo))))

    Since UPDATE-FOO is non-recursive, its admission is trivial.  We observe
    that the type of UPDATE-FOO is described by the theorem
    (AND (CONSP (UPDATE-FOO N VALUE STATE))
         (TRUE-LISTP (UPDATE-FOO N VALUE STATE))).
    We used primitive type reasoning.

    (UPDATE-FOO * * STATE) => (MV * * STATE).

    Summary
    Form:  ( DEFUN UPDATE-FOO ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     UPDATE-FOO
    ACL2 !>(trace! (fact :exit (update-foo n value state)))

    TTAG NOTE: Adding ttag :TRACE! from the top level loop.
     ((FACT :EXIT (UPDATE-FOO N VALUE STATE)))
    ACL2 !>(assign foo nil)
     NIL
    ACL2 !>(fact 7)
    1> (ACL2_*1*_ACL2::FACT 7)
      2> (ACL2_*1*_ACL2::FACT 6)
        3> (ACL2_*1*_ACL2::FACT 5)
          4> (ACL2_*1*_ACL2::FACT 4)
            5> (ACL2_*1*_ACL2::FACT 3)
              6> (ACL2_*1*_ACL2::FACT 2)
                7> (ACL2_*1*_ACL2::FACT 1)
                  8> (ACL2_*1*_ACL2::FACT 0)
                  <8 NIL
                <7 NIL
              <6 NIL
            <5 NIL
          <4 NIL
        <3 NIL
      <2 NIL
    <1 NIL
    5040
    ACL2 !>(@ foo)
    ((7 . 5040)
     (6 . 720)
     (5 . 120)
     (4 . 24)
     (3 . 6)
     (2 . 2)
     (1 . 1)
     (0 . 1))
    ACL2 !>(verify-guards fact)

    Computing the guard conjecture for FACT....

    The guard conjecture for FACT is trivial to prove, given the :compound-
    recognizer rules NATP-COMPOUND-RECOGNIZER and ZP-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 NATP-COMPOUND-RECOGNIZER)
            (:COMPOUND-RECOGNIZER ZP-COMPOUND-RECOGNIZER)
            (:FAKE-RUNE-FOR-TYPE-SET NIL)
            (:TYPE-PRESCRIPTION FACT))
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     FACT
    ACL2 !>(assign foo nil)
     NIL
    ACL2 !>(fact 7)
    1> (ACL2_*1*_ACL2::FACT 7)
      2> (FACT 7)
        3> (FACT 6)
          4> (FACT 5)
            5> (FACT 4)
              6> (FACT 3)
                7> (FACT 2)
                  8> (FACT 1)
                    9> (FACT 0)
                    <9 NIL
                  <8 NIL
                <7 NIL
              <6 NIL
            <5 NIL
          <4 NIL
        <3 NIL
      <2 NIL
    <1 NIL
    5040
    ACL2 !>(@ foo)
    ((7 . 5040)
     (7 . 5040)
     (6 . 720)
     (5 . 120)
     (4 . 24)
     (3 . 6)
     (2 . 2)
     (1 . 1)
     (0 . 1))
    ACL2 !>(trace! (fact :exit (progn (update-foo n value state)
                                      (cons traced-fn values))))

    TTAG NOTE: Adding ttag :TRACE! from the top level loop.
     ((FACT :EXIT (PROGN (UPDATE-FOO N VALUE STATE)
                         (CONS TRACED-FN VALUES))))
    ACL2 !>(assign foo nil)
     NIL
    ACL2 !>(fact 7)
    1> (ACL2_*1*_ACL2::FACT 7)
      2> (FACT 7)
        3> (FACT 6)
          4> (FACT 5)
            5> (FACT 4)
              6> (FACT 3)
                7> (FACT 2)
                  8> (FACT 1)
                    9> (FACT 0)
                    <9 (FACT 1)
                  <8 (FACT 1)
                <7 (FACT 2)
              <6 (FACT 6)
            <5 (FACT 24)
          <4 (FACT 120)
        <3 (FACT 720)
      <2 (FACT 5040)
    <1 (ACL2_*1*_ACL2::FACT 5040)
    5040
    ACL2 !>(@ foo)
    ((7 . 5040)
     (7 . 5040)
     (6 . 720)
     (5 . 120)
     (4 . 24)
     (3 . 6)
     (2 . 2)
     (1 . 1)
     (0 . 1))
    ACL2 !>

  Finally, we remark that using [47mtrace![0m can cause errors in situations
  where tracing is automatically suspended and re-introduced.  This
  is likely to be a rare occurrence, but consider the following
  example.

    (trace! (lexorder :native t :multiplicity 1))
    (certify-book \"foo\" 0 t)

  If the certify-book causes compilation, you may see an error such as
  the following.

    ACL2 Error in (CERTIFY-BOOK \"foo\" ...):  The keyword :NATIVE cannot
    be used in a trace spec unless there is an active trust tag.  The trace
    spec (LEXORDER :NATIVE T :MULTIPLICITY 1) is thus illegal.  Consider
    using trace! instead.  The complete list of keywords that require a
    trust tag for use in a trace spec is: (:NATIVE :DEF :MULTIPLICITY).

  This error is harmless.  The function will appear, when calling
  [47m(trace$)[0m, to remain traced, but in fact there will be no tracing
  behavior, so you may want to call [47m[untrace$][0m on the function symbol
  in question.")
 (TRACE$
  (TRACE)
  "Trace function evaluations

    Examples:
    (trace$ foo bar)     ; trace foo and bar
    (trace$)             ; return current trace info (no new tracing specified)
    (trace$ (foo :entry  ; trace foo, printing first actual parameter upon entry
                 (car arglist)))
    (trace$ (foo :exit   ; trace foo, using fmt to print upon exit
                 (:fmt (msg \"Exiting FOO with ~x0\"
                            value))))
    (trace$ (foo :native t))

    General Forms:
    (trace$ spec1 spec2 ... specn) ; n >= 1
    (trace$)

  where the [47mspeci[0m are trace specs, as described below.

  [47mTrace$[0m installs alternate code for the indicated functions that
  prints information upon entry to, and exit from, calls of the
  functions.  For an alternate tracing utility used for educational
  purposes in ACL2s (see [ACL2-SEDAN]), see community book
  [47mbooks/misc/trace-star.lisp[0m.

  From a logical perspective all trace printing is a fiction.  (But see
  [trace!] for a way to get around this and modify [state].)  For a
  related fiction, see [cw].  [47m(Trace$)[0m returns the list of
  currently-active trace specs, while the application of [47mtrace$[0m to at
  least one argument returns the list of its arguments that are
  successfully acted on.

  Output from [47m[trace$][0m normally goes to the screen, i.e., to
  [47m[standard-co][0m.  But it can be redirected to a file; see [trace-co].

  See [untrace$] for how to undo the effect of [47m[trace$][0m.  Also see
  [trace] for mention of modifications made to raw Lisp trace, which
  is accessible (as described below) using the [47m:native[0m keyword.

  Note that when [47mtrace$[0m is applied to a function without option
  [47m:native[0m, that function's declarations and documentation are
  discarded.

  Next, we introduce tracing with some examples.  After that, we
  provide reference documentation for individual trace options
  allowed in a trace spec.  Note that although our example focuses on
  user-defined functions, [47mtrace$[0m can also be applied to built-in
  functions, though perhaps only system hackers should take advantage
  of this observation.

  We begin by illustrating the simplest sort of trace spec: a function
  symbol.  For example, the form [47m(trace$ foo bar)[0m directs the tracing
  of functions [47mfoo[0m and [47mbar[0m by virtue of the two trace specs [47mfoo[0m and
  [47mbar[0m.  We can see tracing in action by first defining:

    (defun f (x)
      (cons x x))

    (defun g (x)
      (list (f x) 3))

  The following log then illustrates tracing of these two functions.
  Notice that before [guard]s have been verified, the
  ``executable-counterpart functions'' are called but the
  corresponding submitted functions are not (see [evaluation] for
  relevant background); but after guard verification of [47mf[0m, the
  submitted function for [47mf[0m is indeed called.  (See [guard] and see
  [guard-evaluation-examples-log].)

    ACL2 !>(trace$ f g)
     ((F) (G))
    ACL2 !>(g 7)
    1> (ACL2_*1*_ACL2::G 7)
      2> (ACL2_*1*_ACL2::F 7)
      <2 (ACL2_*1*_ACL2::F (7 . 7))
    <1 (ACL2_*1*_ACL2::G ((7 . 7) 3))
    ((7 . 7) 3)
    ACL2 !>(verify-guards f)

    Computing the guard conjecture for F....

    The guard conjecture for F is trivial to prove.  F is compliant with
    Common Lisp.

    Summary
    Form:  ( VERIFY-GUARDS F)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     F
    ACL2 !>(g 7)
    1> (ACL2_*1*_ACL2::G 7)
      2> (ACL2_*1*_ACL2::F 7)
        3> (F 7)
        <3 (F (7 . 7))
      <2 (ACL2_*1*_ACL2::F (7 . 7))
    <1 (ACL2_*1*_ACL2::G ((7 . 7) 3))
    ((7 . 7) 3)
    ACL2 !>

  The following example introduces trace specs other than function
  symbols.  Consider the following definition.

    (defun fact (n)
      (declare (xargs :guard (natp n)))
      (if (zp n)
          1
        (* n (fact (1- n)))))

  The following log illustrates the use of trace options [47m:cond[0m
  (condition for entering trace), [47m:entry[0m (what to print on entry),
  and [47m:exit[0m (what to print on exit).  The reason for two calls on
  argument 4 is that we are seeing such calls for the
  executable-counterpart of [47mfact[0m and also its raw Lisp function.

    ACL2 !>(trace$ (fact :cond (evenp (car arglist))
                         :entry (cons 'factorial-call arglist)
                         :exit (car values)))
     ((FACT :COND (EVENP (CAR ARGLIST))
            :ENTRY (CONS 'FACTORIAL-CALL ARGLIST)
            :EXIT (CAR VALUES)))
    ACL2 !>(fact 4)
    1> (FACTORIAL-CALL 4)
      2> (FACTORIAL-CALL 4)
        3> (FACTORIAL-CALL 2)
          4> (FACTORIAL-CALL 0)
          <4 1
        <3 2
      <2 24
    <1 24
    24
    ACL2 !>

  Notice that [47mVALUES[0m above is the list of all values returned, which is
  a one-element list unless [47m[mv][0m return is used, as illustrated in
  the following example, after defining: [47m(defun two-vals (x) (mv x
  7))[0m.

    ACL2 !>(trace$ two-vals)
     ((TWO-VALS))
    ACL2 !>(two-vals 3)
    1> (ACL2_*1*_ACL2::TWO-VALS 3)
    <1 (ACL2_*1*_ACL2::TWO-VALS 3 7)
    (3 7)
    ACL2 !>(verify-guards two-vals)

    Computing the guard conjecture for TWO-VALS....

    The guard conjecture for TWO-VALS is trivial to prove, given the :executable-
    counterpart of CONS.  TWO-VALS is compliant with Common Lisp.

    Summary
    Form:  ( VERIFY-GUARDS TWO-VALS)
    Rules: ((:EXECUTABLE-COUNTERPART CONS))
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     TWO-VALS
    ACL2 !>(two-vals 3)
    1> (ACL2_*1*_ACL2::TWO-VALS 3)
      2> (TWO-VALS 3)
      <2 (TWO-VALS 3 7)
    <1 (ACL2_*1*_ACL2::TWO-VALS 3 7)
    (3 7)
    ACL2 !>

  We now document all of the options that may appear in a trace spec.
  A trace spec with options is of the form

    (fn :kwd1 val1 :kwd2 val2 ... :kwdn valn)

  and here we document each legal keyword [47m:kwdi[0m and corresponding
  expected value [47mvali[0m.  Note that [47mtrace$[0m is intended primarily for
  functions defined in the ACL2 command loop (see [lp]).  If you want
  to trace a function that is defined in raw Lisp, then you can use
  option [47m:native[0m (see below), but then many other [47mtrace$[0m options will
  not be available to you: all of them except [47m:multiplicity[0m and
  [47m:native[0m itself will be passed directly to the [47mtrace[0m utility of the
  underlying Common Lisp.

  [47m:COND[0m, [47m:ENTRY[0m, and [47m:EXIT[0m


Introduction

  For each of these three options, the value is a (user-level) term,
  except that for [47m:entry[0m and [47m:exit[0m the value can be of the form [47m(:fmt
  u)[0m or [47m(:fmt! u)[0m, where [47mu[0m is a user-level term.  We skip these two
  latter cases for now and return to them later.  Then the indicated
  term is evaluated as indicated in the next paragraph, and if the
  [47m:cond[0m term is omitted or evaluates to non-[47mnil[0m, then the value of
  the [47m:entry[0m term is printed on entry and the value of the [47m:exit[0m term
  is printed on exit.  By default, where [47m:entry[0m is omitted or is
  specified as [47mnil[0m, the value printed for [47m:entry[0m is the list obtained
  by consing the calling function symbol onto the list of actual
  parameters: in the notation described below, this is [47m(cons
  TRACED-FN ARGLIST)[0m.  Similarly, the default for printing at the
  exit of the function call, i.e. where [47m:exit[0m is omitted or is
  specified as [47mnil[0m, is [47m(cons TRACED-FN VALUES)[0m where [47mVALUES[0m is the
  list of values returned as described below.


Available Variables

    NOTE.  The symbols mentioned below, for example [47mARGLIST[0m, are all in
    the [47m\"ACL2\"[0m package.  If you are in another package you may need
    an [47m\"ACL2::\"[0m package prefix, e.g., [47mACL2::ARGLIST[0m.

  In the evaluations of the term described below upon a call of [47mfn[0m,
  each formal parameter of the definition of [47mfn[0m will be bound to the
  corresponding actual of the call, the variable [47mARGLIST[0m will be
  bound to the list of actuals, and the variable [47mTRACED-FN[0m will be
  bound to the function being called (either [47mfn[0m or its
  executable-counterpart function; see above).  Additionally in the
  case of [47m:exit[0m, the variable [47mVALUES[0m will be bound to the multiple
  values returned (thus, a one-element list if [47m[mv][0m is not used in
  the return).  Also for [47m:exit[0m, we bind [47mVALUE[0m to the logical value
  returned, i.e., to the suitable list of values returned in the [47m[mv][0m
  case and otherwise to the single value returned.  So in the [47mmv[0m
  case, [47mVALUE[0m is the same as [47mVALUES[0m, and otherwise [47mVALUE[0m is [47m(car
  VALUES)[0m.  Finally, the variable [47mTRACE-LEVEL[0m will be bound to the
  level, or depth, of tracing; that is, the number printed at entry
  and exit (e.g., 3 in [47m`3>'[0m and [47m`<3'[0m).  Other than these variables
  and [47m[state][0m, no other variable may occur in the term, whose value
  must be a single non-[47m[stobj][0m value, unless there is an active trust
  tag (see [defttag]).


Basic Options

  Now suppose [47mfn[0m is called.  First: If [47m:cond[0m is supplied and the result
  of evaluating the [47m:cond[0m term is [47mnil[0m, then no tracing is done.
  Otherwise tracing proceeds as follows.  First the [47m:entry[0m form is
  evaluated, and the result is printed.  Then the call of [47mfn[0m is
  evaluated.  Finally the [47m:exit[0m term is evaluated and the result is
  printed.  As indicated above, the default for the [47m:entry[0m term if
  omitted or explicitly [47mnil[0m is [47m(cons TRACED-FN ARGLIST)[0m, and the
  default for the [47m:exit[0m term if omitted or explicitly [47mnil[0m is [47m(cons
  TRACED-FN VALUES)[0m.

  Note that if the function has a formal named [47mARGLIST[0m, then [47mARGLIST[0m
  will nevertheless refer to the entire list of formals, not the
  single formal named [47mARGLIST[0m; similarly for [47mTRACED-FN[0m, and
  additionally for [47mVALUE[0m and [47mVALUES[0m in the case of [47m:exit[0m.

  As mentioned above, for each of [47m:entry[0m and [47m:exit[0m, a value of [47mnil[0m
  specifies the default behavior.  If you really want a value of [47mnil[0m,
  use a non-[47mnil[0m form that evaluates to [47mnil[0m, for example [47m(car nil)[0m or
  [47m'nil[0m.  However, for [47m:cond[0m a value of [47mnil[0m means what it says: do not
  evaluate the [47m:entry[0m or [47m:exit[0m forms.

  Finally we discuss the case that the [47m:entry[0m or [47m:exit[0m term is of the
  form [47m(:fmt u)[0m or [47m(:fmt! u)[0m.  In these cases, the term [47mu[0m is
  evaluated as described above to produce a value, say [47mmsg[0m, but
  instead of printing [47mmsg[0m directly, ACL2 calls [47mfmt1[0m using the string
  [47m\"~@0\"[0m and the alist that binds just character [47m#\\0[0m to [47mmsg[0m.  The
  following example illustrates this point, where [47mfact[0m is defined as
  above.  Also see [fmt].  Note that [47m(msg string . vals)[0m produces a
  value suitable for a [47m\"~@\"[0m directive to the [47mfmt[0m family of print
  functions.

    ACL2 !>(trace$
            (fact
             :entry (:fmt (msg \"Tracing ~x0 on ~x1\" traced-fn arglist))
             :exit (car values)))
     ((FACT :ENTRY (:FMT (MSG \"Tracing ~x0 on ~x1\" TRACED-FN ARGLIST))
            :EXIT (CAR VALUES)))
    ACL2 !>(fact 3)
    1> Tracing ACL2_*1*_ACL2::FACT on (3)
      2> Tracing FACT on (3)
        3> Tracing FACT on (2)
          4> Tracing FACT on (1)
            5> Tracing FACT on (0)
            <5 1
          <4 1
        <3 2
      <2 6
    <1 6
    6
    ACL2 !>

  If [47m:fmt![0m is used instead of [47m:fmt[0m, then indentation as is the prefix
  string, [47m\"n> \"[0m or [47m\"<n \"[0m.  The following example illustrates the use
  of [47m:fmt![0m.

    ACL2 !>(trace$
            (fact
             :entry (:fmt! (msg \"Tracing ~x0 on ~x1\" traced-fn arglist))
             :exit (:fmt! (msg \"From input ~x0: ~x1\"
                               (car arglist) (car values)))))
     ((FACT :ENTRY (:FMT! (MSG \"Tracing ~x0 on ~x1\" TRACED-FN ARGLIST))
            :EXIT (:FMT! (MSG \"From input ~x0: ~x1\" (CAR ARGLIST)
                              (CAR VALUES)))))
    ACL2 !>(fact 3)
    Tracing ACL2_*1*_ACL2::FACT on (3)
    Tracing FACT on (3)
    Tracing FACT on (2)
    Tracing FACT on (1)
    Tracing FACT on (0)
    From input 0: 1
    From input 1: 1
    From input 2: 2
    From input 3: 6
    From input 3: 6
    6
    ACL2 !>

  Here is the same example, with user-managed indentation.

    ACL2 !>(trace$
            (fact
             :entry (:fmt! (msg \"~t0Tracing ~x1 on ~x2\"
                                (+ 3 (* 2 trace-level))
                                traced-fn arglist))
             :exit (:fmt! (msg \"~t0From input ~x1: ~x2\"
                               (1+ (* 2 trace-level))
                               (car arglist) (car values)))))
     ((FACT :ENTRY (:FMT! (MSG \"~t0Tracing ~x1 on ~x2\"
                               (+ 3 (* 2 TRACE-LEVEL))
                               TRACED-FN ARGLIST))
            :EXIT (:FMT! (MSG \"~t0From input ~x1: ~x2\"
                              (1+ (* 2 TRACE-LEVEL))
                              (CAR ARGLIST)
                              (CAR VALUES)))))
    ACL2 !>(fact 3)
       Tracing ACL2_*1*_ACL2::FACT on (3)
         Tracing FACT on (3)
           Tracing FACT on (2)
             Tracing FACT on (1)
               Tracing FACT on (0)
               From input 0: 1
             From input 1: 1
           From input 2: 2
         From input 3: 6
       From input 3: 6
    6
    ACL2 !>


Advanced Options (alphabetical list)

  [47m:COMPILE[0m

  The tracing of [47mfn[0m installs a substitute definition of [47mfn[0m that prints
  trace information.  If the [47m:compile[0m option is omitted or has value
  [47m:same[0m, then the new definition will be compiled if and only if the
  existing definition is already compiled.  Otherwise, the new
  definition will be compiled exactly when the value of [47m:compile[0m is
  not [47mnil[0m.

  [47m:DEF[0m, [47m:MULTIPLICITY[0m

  ACL2's [47mtrace$[0m mechanism often needs to know the number of outputs of
  a traced function, in the sense of [47m[mv][0m.  If you trace a function
  that was not defined inside the ACL2 loop (hence you are using the
  [47m:native[0m option), or if you provide an alternative definition using
  option [47m:def[0m (see below) and the new definition changes the number
  of values returned, then a natural number value for [47m:multiplicity[0m
  informs the trace utility of the number of expected outputs of the
  function being traced.  In the case that [47m:native[0m is supplied, the
  effect of a non-[47mnil[0m [47m:multiplicity[0m value depends on the host Lisp.
  In the case of Lisps for which ACL2 uses the built-in Lisp
  mechanism for returning multiple values (see [mv]), which are CCL
  and threaded SBCL as of June, 2010, [47m:multiplicity[0m is not needed and
  is ignored with [47m:native t[0m.  For GCL and Allegro CL, [47m:multiplicity[0m
  is used to generate a suitable [47m:exit[0m form if the [47m:exit[0m keyword was
  not already supplied.  For the other Lisps, the [47m:multiplicity[0m value
  is treated essentially as 1 whether it is supplied or not, because
  we do not know how to pass suitable information based on this value
  to the host Lisp's built-in tracing mechanism.

  Note that even supplying a [47m:multiplicity[0m option does not change the
  meaning of the variable [47mvalues[0m.  See the discussion of [47m:native[0m
  below.

  A useful option can be to supply a definition as the value of [47m:def[0m.
  (Again, note that if [47m:native[0m is used, then all options other than
  [47m:multiplicity[0m are passed directly to the underlying Lisp; in
  particular, [47m:def[0m will have no effect with [47m:native[0m except in the
  unlikely case that the raw Lisp provides some sort of support for
  [47m:def[0m.)  Note that this definition should be like a [47m[defun][0m form,
  but without the leading [47mdefun[0m symbol; and it should define the
  function symbol being traced, with the same formal parameter list.
  However, tracing of the ``executable-counterpart'' of a function
  (see [evaluation] is not sensitive to the [47m:def[0m option; rather, if a
  function has an executable-counterpart then that
  executable-counterpart is traced.

  [47m:EVISC-TUPLE[0m

  The printing described above is, by default, done using the current
  default trace evisc-tuple, which can be set using
  [47m[set-trace-evisc-tuple][0m (for the shape of this tuple, see
  [evisc-tuple]); see [set-trace-evisc-tuple].  This tuple is based
  by default on the raw Lisp variables [47m*print-level*[0m and
  [47m*print-length*[0m, and will hide the ACL2 [world] and handle [stobj]s
  appropriately.  You may override this default by supplying an evisc
  tuple with the [47m:evisc-tuple[0m argument in your trace spec.  Be
  careful to supply a valid evisc-tuple, or you may get a raw Lisp
  error!

  A special value, [47m:print[0m, is useful if you are doing system hacking
  that can produce objects that are not valid ACL2 objects, such as
  raw Lisp arrays or objects in supporting packages not visible in
  the ACL2 read-eval-print loop.  If you supply [47m:evisc-tuple :print[0m,
  then the printing described above will be done with raw Lisp
  printing rather than ACL2 printing.  Note that [stobj]s will be
  printed as vectors (rather than their usual hiding with symbols
  such as [47m<st>[0m) when using [47m:evisc-tuple :print[0m, but other structures
  will still be hidden unless [47m:hide nil[0m is supplied.

  A second special value for [47m:evisc-tuple[0m, [47m:no-print[0m, avoids printing
  the values of the [47m:entry[0m and [47m:exit[0m forms (or their defaults, if not
  specified).  This option is of use for side effects; for an example
  see community book [47mbooks/misc/wet.lisp[0m.

  Note that if [47m:evisc-tuple X[0m is supplied, then the form [47mX[0m will be
  evaluated before the function body is entered.  You can thus pull
  some tricks to print extra information before the [47m:entry[0m form is
  evaluated, for example as follows for a factorial function, [47mfact[0m.

    ACL2 !>(trace$ (fact :evisc-tuple
                         (prog2$ (cw \"~|**** HERE IS CW ****~|\")
                                 nil)))
     ((FACT :EVISC-TUPLE (PROG2$ (CW \"~|**** HERE IS CW ****~|\")
                                 NIL)))
    ACL2 !>(fact 3)
    **** HERE IS CW ****
    1> (ACL2_*1*_ACL2::FACT 3)
    **** HERE IS CW ****
      2> (ACL2_*1*_ACL2::FACT 2)
    **** HERE IS CW ****
        3> (ACL2_*1*_ACL2::FACT 1)
    **** HERE IS CW ****
          4> (ACL2_*1*_ACL2::FACT 0)
          <4 (ACL2_*1*_ACL2::FACT 1)
        <3 (ACL2_*1*_ACL2::FACT 1)
      <2 (ACL2_*1*_ACL2::FACT 2)
    <1 (ACL2_*1*_ACL2::FACT 6)
    6
    ACL2 !>

  [47m:FORMALS[0m

  Normally ACL2 can figure out the formals for a given function.  This
  is always the case for functions defined in the ACL2 command loop
  and when option [47m:def[0m is supplied.  If neither of these cases
  applies then you can still trace a function (even without using the
  [47m:native[0m option) by supplying option [47m:notinline :fncall[0m, but you
  will still need to supply the list of formal parameters.  The value
  of the [47m:formals[0m option should be the list of formals in this case.

  [47m:HIDE[0m

  The default value for this advanced option is [47mt[0m, which causes
  [stobj]s and the logical [world] to be printed as single symbols,
  along with certain large structures of interest to developers
  (rewrite constants, enabled structures, and event and command index
  structures).  (For an exception regarding stobjs, see the
  discussion of [47m:evisc-tuple :print[0m above.)  If however the value [47mnil[0m
  is supplied, then this default behavior is defeated.  In that case,
  you can still arrange to print the logical world as a symbol and to
  print [stobj]s without breaking the trace printing: see
  [set-trace-evisc-tuple] for how to do this globally, or similarly
  use the [47m:evisc-tuple[0m option to [47mtrace$[0m to do this with a single
  trace spec.  Note however that with value [47mnil[0m specified for [47m:hide[0m,
  such use of an evisc-tuple will not deal properly with local stobjs
  (see [with-local-stobj]) or stobjs bound by [47m[stobj-let][0m, or with
  the aforementioned large structures other than the logical [world].

  [47m:NATIVE[0m

  If [47m:native[0m is supplied with a non-[47mnil[0m value, then the trace spec is
  passed to the native Lisp trace (after removing the [47m:native[0m
  option).  A trust tag (see [defttag]) is required in order to use
  this option, because no syntactic check is made on the [47m:cond[0m,
  [47m:entry[0m, or [47m:exit[0m forms --- arbitrary raw Lisp may occur in them!

  Note that by ``native Lisp trace'' we mean the currently installed
  [47mtrace[0m.  As discussed briefly elsewhere (see [trace]), ACL2 has
  modified that trace to be more useful if the underlying host Lisp
  is GCL, Allegro CL, or CCL (OpenMCL).  If you need the original
  trace utility supplied for those Lisps, quit the ACL2 loop with [47m:q[0m
  and call [47mold-trace[0m and [47mold-untrace[0m in raw Lisp where you would
  otherwise call [47mtrace[0m and [47muntrace[0m.  Note that the original trace
  utility supplied with a given Lisp will not hide the ACL2 logical
  [world] or give special treatment to [stobj]s.

  It is important to understand that if [47m:native t[0m is specified, then
  all other options are interpreted by the native Lisp trace.  For
  example, that trace probably has no understanding of the use of
  [47m:fmt[0m described above for [47m:entry[0m or [47m:exit[0m.  Indeed, the native trace
  may not even accept any of [47m:cond[0m, [47m:entry[0m or [47m:exit[0m, let alone any of
  the advanced options!  Moreover, if [47m:native t[0m is specified, then
  even a [47m:multiplicity[0m option does not provide the meaning of the
  variable [47mvalues[0m that one might desire.  In GCL for example, in the
  case of an [47m[mv][0m return of a function defined only in raw Lisp (not
  in ACL2), this variable will be bound to a list containing only the
  first result.

  [47m:NOTINLINE[0m

  By default, a new definition installed by [47mtrace$[0m will include a
  [47mnotinline[0m declaration so that recursive calls will always be
  traced.  (But see Remark (0) below for an exception involving
  [invariant-risk].)  To avoid this declaration, supply value [47mnil[0m.

  A special value for [47m:notinline[0m, [47m:fncall[0m, will cause the traced
  function to call its original definition.  Without this special
  value, the new installed definition for the traced function will
  include the body of the original definition.  This [47m:fncall[0m behavior
  is the default only in the following cases:

    * for functions whose definitions are built into ACL2;

    * for functions that have been added (using a trust tag, an advanced
      feature, so most users can probably ignore this case) to either
      of the [47m[state][0m global variables [47mprogram-fns-with-raw-code[0m or
      [47mlogic-fns-with-raw-code[0m;

    * for [47m[memoize][0md functions.

  The legal values for [47m:notinline[0m are [47mt[0m (the default for other than the
  cases displayed above), [47mnil[0m, and [47m:fncall[0m.


Remarks

  (0) For a [47m:[0m[47m[program][0m mode function with [invariant-risk], recursive
  calls are never traced.  To see these recursive calls, use one of
  the two methods to defeat invariant-risk checking; see
  [invariant-risk]. (Implementation note: This behavior on recursive
  calls is a consequence of how ACL2 defines the
  executable-counterpart --- also known as the ``*1* function'' (see
  [evaluation]) --- to call a local function to do the computation.)

  (1) If some of the given trace specs have errors, then [47mtrace$[0m will
  generally print error messages for those but will still process
  those that do not have errors.  The value returned will indicate
  the trace specs that were processed successfully.

  (2) If you certify or include a book that redundantly defines a
  function that is currently traced, then tracing behavior may
  disappear if a compiled definition is installed for the submitted
  function or its executable-counterpart (see [evaluation] for
  relevant background).

  (3) Some predefined functions are called during tracing.  In order to
  avoid infinite loops, such calls of traced predefined functions
  will be made using the original predefined functions, not using
  their code installed by [47mtrace$[0m.

  (4) For a [wormhole] such as the [break-rewrite] loop, all calls of
  [47mtrace$[0m and [47m[untrace$][0m inside that wormhole are undone upon exit
  from the wormhole.  In particular, if you trace or untrace a
  function during a [47m[brr][0m break, then effects of that trace or
  untrace will disappear when you proceed using a keyword such as
  [47m:eval[0m or [47m:go[0m.")
 (TRACE-CO
  (IO ACL2-BUILT-INS)
  "The [trace] character output channel

  See [io] for relevant background.  [47m(Trace-co state)[0m is an open
  character output channel.  [Trace] output is printed to this
  channel.  Evaluate [47m(set-trace-co CHAN state)[0m to set [47m(Trace-co
  state)[0m to the channel, [47mCHAN[0m.

  ``Trace-co'' stands for ``trace character output.'' The initial value
  of [47mtrace-co[0m is the same as the value of [47m[*standard-co*][0m.")
 (TRANS
  (MACROS)
  "Print the translation of a form

    Examples:
    :trans (list a b c)
    :trans (caddr x)
    :trans (cond (p q) (r))

  ACL2 accepts user-level syntax as input, but [3mtranslates[0m it to an
  internal syntax.  This translation includes macroexpansion,
  replacing [47m[let][0m forms by [47m[lambda][0m expressions, quoting constants,
  and so on.  See [term] for relevant background.

  [47mTrans[0m takes one argument, an alleged term in user syntax, and
  translates it, expanding the macros in it completely.  Either an
  error is caused or the internal syntax for the term (representing
  its formal meaning) is printed.  We also print the ``output
  signature'' which indicates how many results are returned and which
  are single-threaded objects.  For example, a term that returns one
  ordinary object (e.g., an object other than [47m[state][0m or a
  user-defined single-threaded object (see [defstobj])) has the
  output signature

    => *

  A term that returns the single-threaded object [47mSTATE[0m has the output
  signature

    => STATE

  and a term that returns four results might have the output signature

    => (MV $MEM * * STATE)

  This signature indicates that the first result is the (user defined)
  single-threaded object [47m$MEM[0m, that the next two results are
  ordinary, and that the last result is [47mSTATE[0m.

  See [trans!] for a corresponding command that does not enforce
  restrictions of single-threaded objects.  See [trans*] for a
  command that can show intermediate expansion results.

  The argument supplied to [47m:trans[0m may contain variables, including
  [stobj] names.  However, variables that are not stobj names are
  assumed not to be dfs (see [df]).  For example, [47m:trans (df+ x y)[0m
  causes an error; to see the desired translation use [47m:trans! (df+ x
  y)[0m.

  It is sometimes more convenient to use [47m[trans1][0m which is like trans
  but which only does top-level macroexpansion.

  For more, see [term].")
 (TRANS!
  (MACROS)
  "Print the translation of a form without code restrictions

    Examples:
    :trans! (list a b c)
    :trans! (append x state)
    :trans! (cons (mv 3 4) x)

  [47m:Trans![0m is identical to [47m:[0m[47m[trans][0m, except that [47m:trans![0m is more
  permissive: it allows expressions that may occur in theorems but
  are illegal in code.  In particular, [47m:trans![0m allows violations of
  single-threadedness and multiple-value restrictions.  Thus, the
  second and third forms above are legal for [47m:trans![0m even though they
  are illegal for [47m:trans[0m.  Also see [trans], see [trans1], and see
  [trans*].")
 (TRANS*
  (MACROS)
  "Show intermediate expansion results for the translation of a form

  See [term] for background on translated and untranslated terms.  See
  [trans], [trans!], and [47m[trans1][0m for other utilities that expand and
  translate their input.

  Unlike [47mtrans[0m, the [47mtrans*[0m command can show not only the translation of
  a given expression but also the intermediate expansions leading to
  that translation, and [47mtrans*[0m can also show [47m[make-event][0m expansions.
  Another difference between [47mtrans*[0m and [47mtrans[0m is that [47mtrans*[0m does not
  enforce code restrictions; thus, multiple-value mismatches and
  violations of single-threadedness are permitted by [47mtrans*[0m.  That
  is: when [47mtrans*[0m takes steps to convert an untranslated term to a
  translated term, it does so as though one is translating a theorem
  statement, not a definition body.

  For discussion of how one may use a keyword command like [47m:trans*[0m in
  place of calling the corresponding utility, in this case [47mtrans*[0m,
  see [keyword-commands].  Below we focus on the use of the keyword
  command, [47m:trans*[0m.

  We begin with some simple examples that may suffice to explain how to
  use [47mtrans*[0m.  We then document this utility before concluding with
  further details.


Introductory Examples

  The examples below assume that the following definition has been
  submitted.

    (defmacro mac (x y) `(append ,y (rest ,x)))

  Here is a log showing a typical use of [47m:trans*[0m; comments are below.

    ACL2 !>:trans* t (mac u v)

    Iteration 1 produces (by expansion):
    (APPEND V (REST U))
    ----------

    Iteration 2 produces (by expansion):
    (BINARY-APPEND V (REST U))
    ----------

    Iteration 3 produces (by translation):
    (BINARY-APPEND V (CDR U))
    ----------
    ACL2 !>

  We see that Iteration 1 expands away the call of the macro, [47mmac[0m.  The
  next iteration expands away the resulting call of the macro,
  [47mappend[0m.  Those two steps are labeled with ``(by expansion)''
  because they are removing top-level macro calls.  The result of the
  second iteration is not a macro call, so [47m:trans*[0m finishes up by
  translating that result to obtain the final result; notice
  translation of the second argument of the [47mbinary-append[0m call by
  expanding [47m[rest][0m to [47m[cdr][0m.

  The example above illustrates a couple of aspects of [47m:trans*[0m.

    * An expansion step occurs only with a top-level macro call.

    * A translation step is always last.

  The result is the same for input [47m:trans* 3 (mac u v)[0m, i.e., if first
  argument [47mt[0m is replaced by [47m3[0m or, in fact, any integer that is at
  least the total number of iterations produced with argument [47mt[0m.  But
  we can specify that we want to stop before the final step.  One way
  is to specify a number less than the number of iterations.  Here is
  what we get when we specify that we should stop after 1 iteration.

    ACL2 !>:trans* 1 (mac u v)

    Iteration 1 produces (by expansion):
    (APPEND V (REST U))
    ----------
    ACL2 !>

  Another way to stop early is to rule out the final translation step.
  Here is an example by using [47mnil[0m or a negative integer as the first
  argument.

    ACL2 !>:trans* -5 (mac u v) ; same for nil, -2, -3, -4, etc. instead of -5

    Iteration 1 produces (by expansion):
    (APPEND V (REST U))
    ----------

    Iteration 2 produces (by expansion):
    (BINARY-APPEND V (REST U))
    ----------
    ACL2 !>

  If you are only interested in obtaining the final result, with no
  intermediate printing, put parentheses around the first argument.
  Here is what happens when we make that modification to the example
  immediately above.

    ACL2 !>:trans* (-5) (mac u v) ; same answer for nil, -2, -3, etc instead of -5
     (BINARY-APPEND V (REST U))
    ACL2 !>

  Note the single space of indentation in the result above.  That
  indicates that what is actually returned is multiple values, [47m(mv
  nil (BINARY-APPEND V (REST U)) state)[0m.  Without the parentheses,
  [47m(mv nil :invisible state)[0m is returned.  See [error-triple].


Documentation

    General Forms:
    :trans t form
    :trans nil form
    :trans n form
    :trans -n form
    :trans (x) form ; for x = t, nil, n, or -n

  where [47mn[0m is a positive integer and [47mform[0m is any ACL2 expression (i.e.,
  any untranslated term; see [term]).  These commands repeat
  translation steps as described later below, according to the value
  of the first argument, as follows.

    * [47mt[0m: iterate to completion, printing intermediate results

    * [47mnil[0m: iterate to completion except for skipping the final translation
      step, printing intermediate results

    * [47mn[0m: iterate at most [47mn[0m steps, printing intermediate results

    * [47m-n[0m: iterate at most [47mn[0m steps except for skipping a final translation
      step, printing intermediate results

    * [47m(x)[0m: same as [47mx[0m but without printing intermediate results, and
      returning an [error-triple] [47m(mv nil val state)[0m where [47mval[0m is the
      final result,

  It is reasonable to think of a first argument of [47mt[0m as ``infinity''
  and of [47mnil[0m as ``minus infinity''.  Although a first argument of [47m(t)[0m
  is much like using [47m[trans][0m, key differences besides enforcement of
  code restrictions (as discussed above) are that [47mtrans*[0m performs
  [47m[make-event][0m expansion and discards certain ``wrappers'' like
  [47m[with-output][0m, as described below.  The related utility [47m[trans*-][0m
  differs from [47mtrans*[0m in only one way: [47mtrans*-[0m does not perform
  [47mmake-event[0m expansion.

  Here is a specification of the iteration step performed on a given
  form, which is initially the second argument of [47mtrans*[0m and is
  updated by each iteration.  If the form is not a true-list then
  iteration halts without any further result.  Otherwise the form may
  be written as a call [47m(caller arg1 ... argk)[0m, and the next step's
  result, if any, depends on [47mcaller[0m as follows.

    * If [47mcaller[0m is in the list of ``event wrappers'', [47m(local skip-proofs
      with-cbd with-current-package with-guard-checking-event
      with-output with-prover-step-limit with-prover-time-limit)[0m,
      then the next step's result is the last argument of the call,
      denoted [47margk[0m above.

    * Else if [47mcaller[0m is [47m[make-event][0m, the result is the form's [47mmake-event[0m
      expansion.  (This step is skipped when [47m[trans*-][0m is used rather
      than [47mtrans*[0m.)

    * Else if [47mcaller[0m is a built-in event constructor such as [47m[defun][0m or
      [47m[defthm][0m, or one of [47m[certify-book][0m, [47m[defpkg][0m, or [47m[in-package][0m,
      then iteration is halted.  (Technical note: The actual test
      used here is whether [47mcaller[0m is a key of the alist value of the
      constant, [47m*syms-not-callable-in-code-fal*[0m.)

    * Else if [47mcaller[0m is a macro, expand the macro call.

    * Otherwise translate the form, except that as noted above, if the
      first argument of [47mtrans*[0m is [47mnil[0m or a negative integer, then
      this step is skipped and instead iteration is halted.


Further Details

  While [47mtrans*[0m will almost always determine accurately how the given
  input expands and is ultimately translated, it is not quite 100%
  reliable for that purpose.  In particular, [47mmake-event[0m expansion
  isn't guaranteed to check that the expansion is an embedded event
  form, as is required for [47m[make-event][0m.  Another limitation for
  [47mmake-event[0m expansion is that when an iteration reaches the form
  [47m(:OR ev1 ... evk)[0m, the iteration concludes rather than evaluating
  the events [47mevi[0m (see [make-event]).

  A similar utility, [47m[trans*-][0m, stops iteration at a call of [47mmake-event[0m
  without continuing with its [47mmake-event[0m expansion.  That is, in
  fact, the only difference between [47mtrans*[0m and [47mtrans*-[0m.

  We conclude by adding emphasis to an aspect of [47mtrans*[0m that is already
  noted above: expansion (whether macroexpansion or [47mmake-event[0m
  expansion) and elimination of event wrappers only take place for
  the top-level call, not calls occurring in subterms.  Of course,
  one can call [47mtrans*[0m on subterms.  Consider the following example.

    ACL2 !>:trans* t (defund-nx f (x) x)

    Iteration 1 produces (by expansion):
    (WITH-OUTPUT
         :STACK
         :PUSH :OFF
         :ALL
         (PROGN (ENCAPSULATE NIL
                  (LOGIC)
                  (SET-STATE-OK T)
                  (WITH-OUTPUT :STACK :POP
                               (DEFUND F (X)
                                 (DECLARE (XARGS :NON-EXECUTABLE T :MODE :LOGIC))
                                 (PROG2$ (THROW-NONEXEC-ERROR 'F (LIST X))
                                         X)))
                  (WITH-OUTPUT :STACK :POP :OFF
                               SUMMARY (IN-THEORY (DISABLE (:E F)))))
                (WITH-OUTPUT :STACK :POP :OFF SUMMARY
                             (VALUE-TRIPLE '(:DEFUND-NX F)))))
    ----------

    Iteration 2 is dropping the WITH-OUTPUT wrapper:
    (PROGN (ENCAPSULATE NIL
             (LOGIC)
             (SET-STATE-OK T)
             (WITH-OUTPUT :STACK :POP
                          (DEFUND F (X)
                            (DECLARE (XARGS :NON-EXECUTABLE T :MODE :LOGIC))
                            (PROG2$ (THROW-NONEXEC-ERROR 'F (LIST X))
                                    X)))
             (WITH-OUTPUT :STACK :POP :OFF
                          SUMMARY (IN-THEORY (DISABLE (:E F)))))
           (WITH-OUTPUT :STACK :POP :OFF
                        SUMMARY (VALUE-TRIPLE '(:DEFUND-NX F))))
    ----------
    ACL2 !>

  One can then call [47mtrans*[0m on the [47m[defund][0m subterm to see its
  expansion.")
 (TRANS*-
  (MACROS)
  "Variant of [47m[trans*][0m the skips [47m[make-event][0m expansion

  See [trans*].  The only difference between [47mtrans*[0m and [47mtrans*-[0m is that
  the latter does not do [47m[make-event][0m expansion, but rather, stops
  the iterations when reaching a form that is a call of [47mmake-event[0m.")
 (TRANS-EVAL
  (SYSTEM-UTILITIES)
  "Evaluate a form

  This relatively advanced system utility translates and evaluates a
  form.  The following examples illustrate that an [error-triple] is
  returned whose value component is [47m(stobjs-out . values)[0m.

    ACL2 !>(trans-eval '(+ 3 4) 'my-ctx state nil)
     ((NIL) . 7)
    ACL2 !>(trans-eval '(mv (+ 3 4) (car '(5))) 'my-ctx state nil)
     ((NIL NIL) 7 5)
    ACL2 !>

    General Form:

    (trans-eval form  ; an untranslated form
                ctx   ; a context
                state
                aokp) ; allow attachments

  The result is an [error-triple], [47m(mv erp val state)[0m.  The value of
  [47merp[0m is non-[47mnil[0m if there is an error when translating [47mform[0m.
  Otherwise [47merp[0m is typically [47mnil[0m, in which case [47mval[0m is a [47mcons[0m pair
  whose [47mcar[0m is the [47m[stobjs-out][0m --- a list whose length is the number
  of values returned, with [47mnil[0m in each position except when occupied
  by a returned [stobj] for that position --- and whose [47mcdr[0m is the
  returned value or list of values in the [multiple-value] case.

  Also see [47msimple-translate-and-eval-cmp[0m in the ACL2 sources, and see
  [trans-eval-error-triple] (and, which is perhaps less useful,
  [trans-eval-state]).

  If you use [47mtrans-eval[0m then you may see a warning, for example as
  follows.

    ACL2 !>(foo st state)

    ACL2 Warning [User-stobjs-modified] in FOO:  A call of the ACL2 evaluator
    on the term (UPDATE-FLD '4 ST) may have modified the user stobj ST.  See
    :DOC user-stobjs-modified-warning.

    (4 <state> <st>)
    ACL2 !>

  These warnings indicate a potentially serious violation of
  applicative semantics when one is also updating user-defined stobjs
  outside calls of [47mtrans-eval[0m!  To understand and perhaps avoid such
  warnings, see [user-stobjs-modified-warnings].  Also see
  [trans-eval-and-locally-bound-stobjs] for discussion of how
  [47mtrans-eval[0m modifies global stobj values, not locally-bound stobjs.


Subtopics

  [Trans-eval-and-locally-bound-stobjs]
      [47m[Trans-eval][0m deals in global [stobj]s.

  [Trans-eval-and-stobjs]
      How user-defined [stobj]s are handled by [47m[trans-eval][0m

  [User-stobjs-modified-warnings]
      Interactions of [47m[trans-eval][0m with [stobj]s that violate applicative
      semantics")
 (TRANS-EVAL-AND-LOCALLY-BOUND-STOBJS
  (TRANS-EVAL STOBJ)
  "[47m[Trans-eval][0m deals in global [stobj]s.

  This topic assumes familiarity with the relatively advanced utility,
  [47m[trans-eval][0m.  In particular, see [trans-eval-and-stobjs] for
  relevant background.  It may also be helpful to see
  [user-stobjs-modified-warnings].

  A stobj may be locally bound by [47m[stobj-let][0m or [47m[with-local-stobj][0m.
  But [47m[trans-eval][0m ignores such local bindings!  The following
  example illustrates this point.

    (defstobj st fld)

    (defun f (x state)
      (declare (xargs :stobjs state :mode :program))
      (with-local-stobj
        st
        (mv-let (state local-fld st)
          (mv-let (erp val state)
            (trans-eval `(update-fld ',x st) 'f state nil)
            (declare (ignore erp val))
            (mv state (fld st) st))
          (mv state local-fld))))

    ; The following returns (<state> NIL).  Thus, the return value of local-fld
    ; indicated above, which is the value of the fld of the locally-bound st, is
    ; nil: trans-eval did not update the locally-bound stobj!
    (f 3 state)

    ; On the other hand the global stobj, st, was indeed updated by the call of f
    ; just above.
    (assert-event (equal (fld st) 3))

  Here is another such example, this time using [nested-stobjs] instead
  of [47m[with-local-stobj][0m.

    (defstobj sub1 sub1-fld1)
    (defstobj top1 (top1-fld :type sub1))

    (defun g (x top1 state)
      (declare (xargs :stobjs (top1 state) :mode :program))
      (stobj-let
       ((sub1 (top1-fld top1))) ; bindings
       (sub1 state)             ; producer variables
       (mv-let (erp val state)  ; producer

    ; NOTE: The reference to sub1 inside the following trans-eval call is actually
    ; a reference to the global sub1 from the user-stobj-alist, not to the sub1
    ; bound by stobj-let above.  Thus, this trans-eval call updates the global
    ; stobj, sub1, not the locally bound sub1 that is a field of top1.

               (trans-eval `(update-sub1-fld1 ',x sub1) 'g state t)
               (declare (ignore erp val))
               (mv sub1 state))
       (mv top1 state)          ; consumer
      ))

    (g 7 top1 state)
    ; The global stobj, sub1, has been updated by the call of g just above.
    (assert-event (equal (sub1-fld1 sub1) 7))

    (g 8 top1 state)
    ; The global stobj, sub1, has been updated by the call of g just above.
    (assert-event (equal (sub1-fld1 sub1) 8))

    ; Obtain the sub1 field of top1.
    (defun get-sub1-of-top1 (top1)
      (declare (xargs :stobjs top1 :mode :program))
      (stobj-let
       ((sub1 (top1-fld top1)))  ; bindings
       (val)                     ; producer variable
       (sub1-fld1 sub1)          ; producer
       val                       ; consumer
      ))

    ; The calls of g above did not update the locally bound sub1.
    ; That is, they did not update the sub1 field of top1.
    (assert-event (equal (get-sub1-of-top1 top1) nil))")
 (TRANS-EVAL-AND-STOBJS
  (TRANS-EVAL STOBJ)
  "How user-defined [stobj]s are handled by [47m[trans-eval][0m

  See [trans-eval] for basic background on the relatively advanced
  system utility, [47mtrans-eval[0m.  In this topic we discuss how
  [47mtrans-eval[0m handles user-defined [stobj]s.

  A field of the ACL2 [state], the [47muser-stobj-alist[0m, is an association
  list (alist) that maps each user-defined [stobj] name to its
  current value.  [47mTrans-eval[0m evaluates with respect to this alist, so
  that any time a variable (which must be a stobj name) is to be
  evaluated, its value is looked up in that alist.

  For example, suppose that you evaluate the following forms in the
  top-level ACL2 loop.

    (defstobj st fld)
    (fld st)

  To evaluate the expression, [47m(fld st)[0m, ACL2 calls [47m[trans-eval][0m --- or
  more accurately its variant, [47m[trans-eval-default-warning][0m --- on
  that expression.  (We generally consider all such variants to be
  the same as [47mtrans-eval[0m for purposes of this documentation topic.)
  Although [47mst[0m has the syntax of a global variable, it is bound in the
  [47muser-stobj-alist[0m.  Here we see [47mtrans-eval[0m in action.

    ACL2 !>(trace$ trans-eval-default-warning)
     ((TRANS-EVAL-DEFAULT-WARNING))
    ACL2 !>(fld st)
    1> (TRANS-EVAL-DEFAULT-WARNING (FLD ST)
                                   TOP-LEVEL |*the-live-state*| T)
    <1 (TRANS-EVAL-DEFAULT-WARNING NIL ((NIL))
                                   |*the-live-state*|)
    NIL
    ACL2 !>

  This call of [47mtrans-eval[0m (or more accurately,
  [47mtrans-eval-default-warning[0m) invokes an ACL2 evaluator [47m(ev form
  alist state ...)[0m, by calling it on the form [47m(fld st)[0m and an alist
  that binds the variable [47mst[0m to its value in the [47muser-stobj-alist[0m
  component of the ACL2 [state].  We may refer to this value as the
  ``global value of'' [47mst[0m.

  We can of course update this stobj.

    ACL2 !>(update-fld 3 st)
    1> (TRANS-EVAL-DEFAULT-WARNING (UPDATE-FLD 3 ST)
                                   TOP-LEVEL |*the-live-state*| T)
    <1 (TRANS-EVAL-DEFAULT-WARNING NIL ((ST) . REPLACED-ST)
                                   |*the-live-state*|)
    <st>
    ACL2 !>(fld st) ; check that the update occurred
    1> (TRANS-EVAL-DEFAULT-WARNING (FLD ST)
                                   TOP-LEVEL |*the-live-state*| T)
    <1 (TRANS-EVAL-DEFAULT-WARNING NIL ((NIL) . 3)
                                   |*the-live-state*|)
    3
    ACL2 !>

  We see above that the global value of [47mst[0m was indeed updated by
  evaluating the [47mupdate-fld[0m call.  That is: the value of [47mst[0m in the
  [47muser-stobj-alist[0m of the ACL2 [47m[state][0m was updated by calling
  [47m[trans-eval][0m on the expression, [47m(update-fld 3 st)[0m.  More generally:
  as [47mtrans-eval[0m returns, it updates the [47muser-stobj-alist[0m of the ACL2
  [state] according to all stobj values that have been returned.")
 (TRANS-EVAL-DEFAULT-WARNING (POINTERS)
                             "See [user-stobjs-modified-warnings].")
 (TRANS-EVAL-NO-WARNING (POINTERS)
                        "See [user-stobjs-modified-warnings].")
 (TRANS1
  (MACROS)
  "Print the one-step macroexpansion of a form

  See [term] for background on translated and untranslated terms,
  including some discussion of macros.

    Examples:
    :trans1 (list a b c)
    :trans1 (caddr x)
    :trans1 (cond (p q) (r))

  This utility takes one argument, an alleged untranslated term, and
  expands the top-level macro in it for one step only.  Either an
  error is caused, which happens when the form is not a call of a
  macro, or the result is printed.  Also see [trans], which
  translates the given form completely.

  On very rare occasions, complete translation is not quite the same as
  translating the output of [47m:trans1[0m, though the two should still be
  logically equivalent.  This can happen for a call of [47m[stobj-let][0m in
  the body of a function: its translation may include a check for
  duplicate indices that is omitted in the single-step
  macroexpansion.")
 (TRANSLAM
  (APPLY$)
  "Print the translation of a lambda$ expression

    :translam (lambda$ (x) (+ 1 x))
    :translam (lambda (x) (+ 1 x))

  This function takes a [47mlambda$[0m term or an unquoted [47mLAMBDA[0m constant.
  In the former case, it translates the [47mlambda$[0m and prints the
  result.  In the latter case it puts the [47mLAMBDA[0m in a [47mQUOTE[0m and
  translates it as though it occurred in a [47m:FN[0m slot.  Unless an error
  is signaled it prints the same [47mLAMBDA[0m object as the result.

  This utility exists because you cannot write, say,

    :trans (lambda$ (x) (+ 1 x))

  because the [47mtrans[0m utility assumes its argument in an ordinary (ilk
  [47mNIL[0m) slot.  In such slots, [47mlambda$[0m terms are disallowed and no
  restrictions are enforced on quoted [47mLAMBDA[0m objects.

  This utility is useful for seeing what the formal translation of a
  [47mlambda$[0m term is.  For example,

    ACL2 !>:translam (lambda$ (x)
                              (declare (type (satisfies natp) x))
                              (* x x))

  produces the quoted well-formed [47mLAMBDA[0m expression:

    '(LAMBDA (X)
             (DECLARE (TYPE (SATISFIES NATP) X)
                      (XARGS :GUARD (NATP X) :SPLIT-TYPES T)
                      (IGNORABLE X))
             (RETURN-LAST 'PROGN
                          '(LAMBDA$ (X)
                                    (DECLARE (TYPE (SATISFIES NATP) X))
                                    (* X X))
                          (BINARY-* X X)))

  You might now have an inkling about why we discourage you from trying
  to enter quoted well-formed [47mLAMBDA[0m objects by hand!  The normal
  form of a quoted well-formed [47mLAMBDA[0m object is complicated so that
  [47mapply$[0m can rapidly identify the parts, generate guard conditions,
  compile the object, recognize objects coming from [47mlambda$[0m terms,
  etc.")
 (TRANSLATE (POINTERS)
            "See [system-utilities].")
 (TRANSLATE-CMP (POINTERS)
                "See [system-utilities].")
 (TRANSLATE-HINTS (POINTERS)
                  "See [system-utilities].")
 (TRANSLATE1 (POINTERS)
             "See [system-utilities].")
 (TRANSLATE1-CMP (POINTERS)
                 "See [system-utilities].")
 (TRANSLATE11 (POINTERS)
              "See [system-utilities].")
 (TRANSPARENT-FUNCTIONS
  (META)
  "Working around restrictions on the use of evaluators in meta-level
  rules

  See [evaluator-restrictions] for relevant background.  For examples
  of the use of transparent functions, see [community-book] file
  [47mbooks/system/tests/transparent-functions-input.lsp[0m, with
  corresponding output in file [47mtransparent-functions-log.txt[0m in the
  same directory.

  A function is called a ``transparent function symbol'' when it is
  declared with [47m:transparent t[0m in a [signature] of an [47m[encapsulate][0m
  event.  By thus declaring a function to be transparent, you are
  modifying the notion of ``ancestor'' of a meta-level function as
  follows, for purposes of the ancestor restriction described in
  [evaluator-restrictions]: when a transparent function [47mf[0m has an
  attachment [47mg[0m (see [defattach]), then [47mg[0m is the sole ancestor
  (supporter) of [47mf[0m.

  We illustrate with a (contrived) example, which shows how declaring a
  function to be transparent can avoid an error.  Consider what
  happens when we submit the following events in a fresh ACL2
  session.

    (defstub f0 (x) t)

    (encapsulate
      (((f1 *) => *)
       ((f2 *) => *))
      (local (defun f1 (x) (f0 x)))
      (local (defun f2 (x) (f0 x)))
      (defthm f2-is-f1
        (implies (f0 x)
                 (equal (f2 x) (f1 x)))
        :rule-classes nil))

    (defn g0 (x) x)

    (defattach f0 g0)

    (with-output :off :all ; avoid noisy output
      (defevaluator evl evl-list
        ((f0 x))))

    (defn meta-fn1 (x)
      (if (f1 x)
          x
        x))

    (defattach (f1 consp) (f2 consp))

    (defthm thm1
      (equal (evl x a)
             (evl (meta-fn1 x) a))
      :rule-classes ((:meta :trigger-fns (nth))))

  The final ([47m[defthm][0m) event results in the following error.

    ACL2 Error in ( DEFTHM THM1 ...):  The proposed :META rule, THM1, is
    illegal because the attached function F0 is ancestral in both the evaluator
    and meta functions.  See :DOC evaluator-restrictions and see :DOC transparent-
    functions.

    The following is an ancestor path from F0 to the meta function META-FN1,
    i.e., each function symbol is a supporter of the next:

    (F0 F1 META-FN1)

    The following is an ancestor path from F0 to the evaluator function
    EVL, i.e., each function symbol is a supporter of the next:

    (F0 EVL)

  The events above make it clear that the alleged ancestor paths are
  indeed ancestor paths, in the sense that each function symbol in
  the path occurs in the definition or [constraint] for the function
  symbol immediately after it.

  To avoid this error, we need to arrange that [47mf0[0m is no longer a common
  ancestor of [47mmeta-fn1[0m and [47mevl[0m.  The notion of ancestor doesn't
  change for the path leading to the evaluator function; but for the
  path leading to the meta function, a transparent function symbol
  has its attachment as its ancestor instead of the function symbols
  in its [constraint].  In particular, [47mf1[0m normally has [47mf0[0m as an
  ancestor, since [47mf0[0m occurs in the constraint on [47mf1[0m; but if [47mf1[0m is
  transparent and has an attachment, then its attachment is the sole
  ancestor of [47mf0[0m, as though [47mf1[0m had been defined to be [47mf0[0m.  Thus, if
  we replace the [47m[encapsulate][0m event in our example simply by
  declaring its [signature] functions to be transparent, as follows,
  then the error disappears.

    (encapsulate
      (((f1 *) => * :transparent t)
       ((f2 *) => * :transparent t))
      (local (defun f1 (x) (f0 x)))
      (local (defun f2 (x) (f0 x)))
      (defthm f2-is-f1
        (implies (f0 x)
                 (equal (f2 x) (f1 x)))
        :rule-classes nil))

  We close with some restrictions pertaining to transparent function
  symbols.

    * If any function is declared with [47m:transparent t[0m in the signatures of
      an [47mencapsulate[0m event, then all must be.

    * If any function is declared with [47m:transparent t[0m in the signatures of
      an [47mencapsulate[0m event, then every signature in a superior or
      inferior [47mencapsulate[0m event must also specify [47m:transparent t[0m.

    * The value of the [47m:transparent[0m keyword in a signature must be [47mt[0m or the
      default, [47mnil[0m.

    * The signatures of a [47m[partial-encapsulate][0m (or of any encapsulate with
      a call of [47mset-unknown-constraints-supporters[0m) must not specify
      [47m:transparent t[0m in its signatures.

    * When a [47m[defattach][0m event attaches to a transparent function symbol [47mf[0m,
      that event must attach to every function symbol constrained in
      an encapsulate with [47mf[0m, and only to such function symbols.  The
      same holds for unattaching in place of attaching.")
 (TRUE-LIST-FIX
  (TRUE-LISTP ACL2-BUILT-INS)
  "Coerce to a true list

  Many functions that process lists follows the [31;1mtrue-list-fix
  convention[0m: whenever [47mf[0m is given some non-[47m[true-listp][0m [47mx[0m where it
  expected a list, that is, some [47mx[0m with a non-[47mnil[0m [47m[final-cdr][0m, it
  will act as though it had been given [47m(true-list-fix x)[0m instead.  As
  a few examples, logically,

    * [47m(endp x)[0m ignores the final [47mcdr[0m of [47mx[0m

    * [47m(len x)[0m ignores the final [47mcdr[0m of [47mx[0m

    * [47m(append x y)[0m ignores the final [47mcdr[0m of [47mx[0m (but not [47my[0m)

    * [47m(member a x)[0m ignores the final [47mcdr[0m of [47mx[0m

  [47mTrue-list-fix[0m is often useful when writing theorems about how
  list-processing functions behave.  For example, it allows us to
  write strong, hypothesis-free theorems such as:

    (equal (character-listp (append x y))
           (and (character-listp (true-list-fix x))
                (character-listp y)))

  Indeed, [47mtrue-list-fix[0m is the basis for [list-equiv], an extremely
  common [equivalence] relation.

  Efficiency note.  In practice, most lists are [47mnil[0m-terminated.  As an
  optimization, [47mtrue-list-fix[0m tries to avoid any consing by first
  checking whether its argument is a [true-listp], and, in that case,
  it simply returns its argument unchanged.

  For a logically equivalent utility that returns its argument
  unchanged (with no checking) during normal evaluation, see
  [the-true-list].

  [31;1mFunction: [0m<true-list-fix-exec>

    (defun true-list-fix-exec (x)
      (declare (xargs :guard t))
      (if (consp x)
          (cons (car x)
                (true-list-fix-exec (cdr x)))
        nil))

  [31;1mFunction: [0m<true-list-fix>

    (defun true-list-fix (x)
      (declare (xargs :guard t))
      (mbe :logic
           (if (consp x)
               (cons (car x) (true-list-fix (cdr x)))
             nil)
           :exec
           (if (true-listp x)
               x
             (true-list-fix-exec x))))")
 (TRUE-LIST-LISTP
  (LISTS TRUE-LISTP ACL2-BUILT-INS)
  "Recognizer for true (proper) lists of true lists

  [47mTrue-list-listp[0m is the function that checks whether its argument is a
  list that ends in, or equals, [47mnil[0m, and furthermore, all of its
  elements have that property.  Also see [true-listp].

  [31;1mFunction: [0m<true-list-listp>

    (defun true-list-listp (x)
      (declare (xargs :guard t))
      (cond ((atom x) (eq x nil))
            (t (and (true-listp (car x))
                    (true-list-listp (cdr x))))))")
 (TRUE-LISTP
  (LISTS ACL2-BUILT-INS)
  "Recognizer for proper ([47mnil[0m-terminated) lists

  [47mTrue-listp[0m is the function that checks whether its argument is a list
  that ends in, or equals, [47mnil[0m.

For a discussion of whether requiring lists to be [47mnil[0m-terminated is
right for you, see [std::strict-list-recognizers].
  [31;1mFunction: [0m<true-listp>

    (defun true-listp (x)
      (declare (xargs :guard t))
      (if (consp x)
          (true-listp (cdr x))
        (eq x nil)))


Subtopics

  [The-true-list]
      Coerce an expected true list to a true list

  [True-list-fix]
      Coerce to a true list

  [True-list-listp]
      Recognizer for true (proper) lists of true lists")
 (TRUNCATE
  (NUMBERS ACL2-BUILT-INS)
  "Division returning an integer by truncating toward 0

    Example Forms:
    ACL2 !>(truncate 14 3)
    4
    ACL2 !>(truncate -14 3)
    -4
    ACL2 !>(truncate 14 -3)
    -4
    ACL2 !>(truncate -14 -3)
    4
    ACL2 !>(truncate -15 -3)
    5
    ACL2 !>(truncate 10/4 3/4)
    3

  [47m(Truncate i j)[0m is the result of taking the quotient of [47mi[0m and [47mj[0m and
  dropping the fraction.  For example, the quotient of [47m-14[0m by [47m3[0m is [47m-4
  2/3[0m, so dropping the fraction [47m2/3[0m, we obtain a result for [47m(truncate
  -14 3)[0m of [47m-4[0m.

  The [guard] for [47m(truncate i j)[0m requires that [47mi[0m and [47mj[0m are rational
  ([real], in ACL2(r)) numbers and [47mj[0m is non-zero.

  [47mTruncate[0m is a Common Lisp function.  However, note that unlike Common
  Lisp, the ACL2 [47mtruncate[0m function returns only a single value, Also
  see [nonnegative-integer-quotient], which is appropriate for
  integers and may simplify reasoning, unless a suitable arithmetic
  library is loaded, but be less efficient for evaluation on concrete
  objects.

  [31;1mFunction: [0m<truncate>

    (defun truncate (i j)
      (declare (xargs :guard (and (real/rationalp i)
                                  (real/rationalp j)
                                  (not (eql j 0)))))
      (let* ((q (* i (/ j)))
             (n (numerator q))
             (d (denominator q)))
        (cond ((= d 1) n)
              ((>= n 0)
               (nonnegative-integer-quotient n d))
              (t (- (nonnegative-integer-quotient (- n)
                                                  d))))))")
 (TRUST-MFC
  (EXTENDED-METAFUNCTIONS)
  "A macro that supports testing of extended metafunctions)

    Example Form:
    (trust-mfc (mfc-ts term mfc state))

    General Form:
    (trust-mfc form)

  where [47mform[0m is any form, but is typically a call of an extended
  metafunction such as [47mmfc-ts[0m or [47mmfc-rw[0m.

  Extended metafunctions (see [extended-metafunctions]) may normally
  only be invoked during proofs.  [47mTrust-mfc[0m is an advanced utility
  that relaxes that requirement, thus supporting the testing of
  extended-metafunctions outside calls of the ACL2 prover.  When you
  use [47mtrust-mfc[0m, you are taking on the responsibility to pass only
  well-formed [47m[mfc][0m arguments to your calls of
  extended-metafunctions, since otherwise raw Lisp errors may be
  signaled.  Because of this danger, the logical definition of
  [47mtrust-mfc[0m causes an error, thus making it useless at the top level
  and in [47m:[0m[47m[logic][0m-mode code:

  [31;1mMacro: [0m<trust-mfc>

    (defmacro trust-mfc (&whole whole form)
     (cons
      'prog2$
      (cons
       (cons
        'er
        (cons
         'hard
         (cons
          ''trust-mfc
          (cons
           '\"It is illegal to run ~x0 except in raw Lisp, ~
                                     typically by way of a :program-mode function ~
                                     body. ~ See :DOC trust-mfc.  Evaluation of ~
                                     the form ~x1 has led to this error.\"
           (cons ''trust-mfc
                 (cons (cons 'quote (cons whole 'nil))
                       'nil))))))
       (cons form 'nil))))

  However, [47mtrust-mfc[0m can be very useful when used in [47m:[0m[47m[program][0m-mode
  code that calls extended metafunctions, which makes it useful for
  [47m:logic[0m-mode code as well; see [program-wrapper].  The log below
  illustrates typical usage.

    ACL2 !>(defun my-mfc (state)
             ;; Define a simple metafunction-contextx.
             (declare (xargs :mode :program :guard t :stobjs state))
             (make metafunction-context
                   :rdepth 10000
                   :type-alist nil
                   :obj '?
                   :geneqv nil
                   :wrld (w state)
                   :fnstack nil
                   :ancestors nil
                   :backchain-limit nil
                   :simplify-clause-pot-lst nil
                   :rcnst (initial-rcnst-from-ens (ens state) (w state) state nil)
                   :gstack nil
                   :ttree nil
                   :unify-subst nil))

    Summary
    Form:  ( DEFUN MY-MFC ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     MY-MFC
    ACL2 !>(mfc-ts '(cons x y) (my-mfc state) state) ; error: not in prover


    Meta-level function Problem:  This error can quite possibly be avoided;
    see :DOC trust-mfc.  You or some meta-level function applied MFC-TS
    but not from within the theorem prover's meta-level function handler.
    This suggests you are trying to test a meta-level function and have
    evidently manufactured an allegedly suitable context.  Perhaps so.
    But that is so difficult to check that we don't bother.  Instead we
    cause this error and urge you to test your meta-level function by having
    the meta-level function handler invoke it as part of a test proof-
    attempt. To do this, assume the metatheorem that you intend eventually
    to prove.  You may do this by executing the appropriate DEFTHM event
    embedded in a SKIP-PROOFS form.  Then use THM to submit conjectures
    for proof and observe the behavior of your metafunction.  Remember
    to undo the assumed metatheorem before you attempt genuine proofs!
    If this suggestion isn't applicable to your situation, contact the
    authors.



    ACL2 Error in TOP-LEVEL:  ACL2 cannot ev the call of non-executable
    function MFC-TS on argument list:

    ((CONS X Y) MFC STATE)

    To debug see :DOC print-gv, see :DOC trace, and see :DOC wet.

    ACL2 !>(trust-mfc (mfc-ts '(cons x y) (my-mfc state) state)) ; top-level (bad)


    HARD ACL2 ERROR in TRUST-MFC:  It is illegal to run TRUST-MFC except
    in raw Lisp, typically by way of a :program-mode function body.  See
    :DOC trust-mfc.  Evaluation of the form
    (TRUST-MFC (MFC-TS '(CONS X Y) (MY-MFC STATE) STATE)) has led to this
    error.



    ACL2 Error in TOP-LEVEL:  Evaluation aborted.  To debug see :DOC print-
    gv, see :DOC trace, and see :DOC wet.

    ACL2 !>(defun my-mfc-ts (term mfc state)
             (declare (xargs :mode :program :stobjs state))
             (trust-mfc (mfc-ts term mfc state)))

    Summary
    Form:  ( DEFUN MY-MFC-TS ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     MY-MFC-TS
    ACL2 !>(my-mfc-ts '(cons x y) (my-mfc state) state)
    3072
    ACL2 !>(decode-type-set 3072) ; let's see that the result above is reasonable
    *TS-CONS*
    ACL2 !>")
 (TRUST-TAG (POINTERS) "See [defttag].")
 (TTAG (POINTERS) "See [defttag].")
 (TTAGS-SEEN
  (MISCELLANEOUS)
  "List some declared trust tags (ttags)

    General Forms:
    :ttags-seen
    (ttags-seen)

  Suppose the output is as follows.

    (T NIL)
    (FOO \"/home/bob/bar.lisp\"
         \"/home/cindy/bar.lisp\")
    Warning: This output is minimally trustworthy (see :DOC TTAGS-SEEN).

  This output indicates that the current logical [world] has seen the
  declaration of trust tag [47mT[0m at the top-level (see [defttag]) and the
  declaration of trust tag [47mFOO[0m in the two books included from the
  listed locations.  The warning emphasizes that this command cannot
  be used to validate the ``purity'' of an ACL2 session, because
  using a ttag renders enough power to hide from this or any other
  command the fact that the ttag was ever declared.

  As discussed elsewhere (see [defttag]), the only reliable way to
  validate the ``purity'' of a session is to watch for ``[47mTTAG NOTE[0m''
  output.

  Another shortcoming of this command is that it only checks the
  current logical [world] for ttag declarations.  For example, one
  could execute a [47m[defttag][0m event; then use [47m[progn!][0m and
  [47m[set-raw-mode][0m to replace system functions with corrupt definitions
  or to introduce inconsistent axioms in the [47m[ground-zero][0m [world];
  and finally, execute [47m:[0m[47m[ubt!][0m[47m 1[0m to remove all evidence of the ttag
  in the [world] while leaving in place the corrupt definitions or
  axioms.  The base world is now tainted, meaning we could prove [47mnil[0m
  or certify a book that proves [47mnil[0m, but the resulting session or
  book would contain no trace of the ttag that tainted it!

  Despite shortcomings, this command might be useful to system hackers.
  It also serves to illustrate the inherent flaw in asking a session
  whether or how it is ``tainted'', justifying the ``[47mTTAG NOTE[0m''
  approach (see [defttag]).")
 (TTHM
  (HISTORY MEASURE)
  "The [measure] (termination) theorem for a given function symbol

    Example Forms:
    :tthm FN
    (tthm 'FN) ; equivalent to the above

  where [47mFN[0m is a function symbol.  This shows the [measure]
  (termination) theorem for [47mFN[0m.  More precisely, evaluation of a call
  of this macro --- pronounced ``tee-thumb'' --- either results in an
  error or returns an [error-triple] whose value component is the
  user-level (untranslated) version of that termination theorem.
  Also see [lemma-instance] for discussion of a related
  [47m:termination-theorem[0m prover hint.

  Technical note: a corresponding evaluation that provides a
  (translated) [termp] is: [47m(termination-theorem 'FN (w state))[0m.")
 (TTREE
  (MISCELLANEOUS)
  "Tag-trees

  Many low-level ACL2 functions take and return ``tag trees'' or
  ``ttrees'' (pronounced ``tee-trees'') which contain useful
  information such as the lemmas used, the linearize assumptions
  made, etc.  Here we present only minimal user-level information,
  for example in support of the use of the [break-rewrite] utility or
  writing metafunctions.  Implementation-level information about tag
  trees may be found in the Developer's Guide; users should probably
  not visit that topic (see [DEVELOPERS-GUIDE-UTILITIES]) unless they
  plan to become ACL2 developers.

  Abstractly a tag-tree represents a list of sets, each member set
  having a name given by one of the ``tags'' (which are symbols) of
  the ttree.  The elements of the set named [47mtag[0m are all of the
  objects tagged [47mtag[0m in the tree.

  The rewriter, for example, takes a term and a ttree (among other
  things), and returns a new term, term', and new ttree, ttree'.
  Term' is equivalent to term (under the current assumptions) and the
  ttree' is an extension of ttree.  If we focus just on the set
  associated with the tag [47mLEMMA[0m in the ttrees, then the set for
  ttree' is the extension of that for ttree obtained by unioning into
  it all the [rune]s used by the rewrite.  The set associated with
  [47mLEMMA[0m can be obtained by [47m(tagged-objects 'LEMMA ttree)[0m.")
 (TUTORIAL1-TOWERS-OF-HANOI
  (ANNOTATED-ACL2-SCRIPTS)
  "The Towers of Hanoi Example

  This example was written almost entirely by Bill Young of
  Computational Logic, Inc.

  We will formalize and prove a small theorem about the famous ``Towers
  of Hanoi'' problem.  This problem is illustrated by the following
  picture.

       |        |        |
       |        |        |
      ---       |        |
     -----      |        |
    -------     |        |

       A        B        C

  We have three pegs --- [47ma[0m, [47mb[0m, and [47mc[0m --- and [47mn[0m disks of different
  sizes.  The disks are all initially on peg [47ma[0m.  The goal is to move
  all disks to peg [47mc[0m while observing the following two rules.

  1. Only one disk may be moved at a time, and it must start and finish
  the move as the topmost disk on some peg;

  2. A disk can never be placed on top of a smaller disk.

  Let's consider some simple instances of this problem.  If [47mn[0m = 1,
  i.e., only one disk is to be moved, simply move it from [47ma[0m to [47mc[0m.  If
  [47mn[0m = 2, i.e., two disks are to be moved, the following sequence of
  moves suffices: move from [47ma[0m to [47mb[0m, move from [47ma[0m to [47mc[0m, move from [47mb[0m to
  [47mc[0m.

  In this doc topic we will show an ACL2 function that generates a
  suitable list of moves for a tower of [47mn[0m disks.  Then we will use
  ACL2 to prove that the number of moves is [47m(- (expt 2 n) 1)[0m.  For an
  ACL2 script that proves the correctness of (a version of) this
  function, see the community book [47m\"misc/hanoi.lisp\"[0m in the [47mbooks[0m
  directory of your ACL2 sources.

  In general, this problem has a straightforward recursive solution.
  Suppose that we desire to move [47mn[0m disks from [47ma[0m to [47mc[0m, using [47mb[0m as the
  intermediate peg.  For the basis, we saw above that we can always
  move a single disk from [47ma[0m to [47mc[0m.  Now if we have [47mn[0m disks and assume
  that we can solve the problem for [47mn-1[0m disks, we can move [47mn[0m disks as
  follows.  First, move [47mn-1[0m disks from [47ma[0m to [47mb[0m using [47mc[0m as the
  intermediate peg; move the single disk from [47ma[0m to [47mc[0m; then move [47mn-1[0m
  disks from [47mb[0m to [47mc[0m using [47ma[0m as the intermediate peg.

  In ACL2, we can write a function that will return the sequence of
  moves.  One such function is as follows.  Notice that we have two
  base cases.  If [47m(zp n)[0m then [47mn[0m is not a positive integer; we treat
  that case as if [47mn[0m were 0 and return an empty list of moves.  If [47mn[0m
  is 1, then we return a list containing the single appropriate move.
  Otherwise, we return the list containing exactly the moves dictated
  by our recursive analysis above.

    (defun move (a b)
      (list 'move a 'to b))

    (defun hanoi (a b c n)
      (if (zp n)
          nil
        (if (equal n 1)
            (list (move a c))
          (append (hanoi a c b (1- n))
                  (cons (move a c)
                        (hanoi b a c (1- n)))))))

  Notice that we give [47mhanoi[0m four arguments: the three pegs, and the
  number of disks to move.  It is necessary to supply the pegs
  because, in recursive calls, the roles of the pegs differ.  In any
  execution of the algorithm, a given peg will sometimes be the
  source of a move, sometimes the destination, and sometimes the
  intermediate peg.

  After submitting these functions to ACL2, we can execute the [47mhanoi[0m
  function on various specific arguments.  For example:

    ACL2 !>(hanoi 'a 'b 'c 1)
    ((MOVE A TO C))

    ACL2 !>(hanoi 'a 'b 'c 2)
    ((MOVE A TO B)
     (MOVE A TO C)
     (MOVE B TO C))

    ACL2 !>(hanoi 'a 'b 'c 3)
    ((MOVE A TO C)
     (MOVE A TO B)
     (MOVE C TO B)
     (MOVE A TO C)
     (MOVE B TO A)
     (MOVE B TO C)
     (MOVE A TO C))

  From the algorithm it is clear that if it takes [47mm[0m moves to transfer [47mn[0m
  disks, it will take [47m(m + 1 + m) = 2m + 1[0m moves for [47mn+1[0m disks.  From
  some simple calculations, we see that we need the following number
  of moves in specific cases:

    Disks   0   1   2   3   4   5   6   7  ...
    Moves   0   1   3   7  15  31  63  127 ...

  The pattern is fairly clear.  To move [47mn[0m disks requires [47m(2^n - 1)[0m
  moves.  Let's attempt to use ACL2 to prove that fact.

  First of all, how do we state our conjecture?  Recall that [47mhanoi[0m
  returns a list of moves.  The length of the list (given by the
  function [47mlen[0m) is the number of moves required.  Thus, we can state
  the following conjecture.

    (defthm hanoi-moves-required-first-try
      (equal (len (hanoi a b c n))
             (1- (expt 2 n))))

  When we submit this to ACL2, the proof attempt fails.  Along the way
  we notice subgoals such as:

    Subgoal *1/1'
    (IMPLIES (NOT (< 0 N))
             (EQUAL 0 (+ -1 (EXPT 2 N)))).

  This tells us that the prover is considering cases that are
  uninteresting to us, namely, cases in which [47mn[0m might be negative.
  The only cases that are really of interest are those in which [47mn[0m is
  a non-negative natural number.  Therefore, we revise our theorem as
  follows:

    (defthm hanoi-moves-required
      (implies (and (integerp n)
                    (<= 0 n))    ;; n is at least 0
               (equal (len (hanoi a b c n))
                      (1- (expt 2 n)))))

  and submit it to ACL2 again.

  Again the proof fails.  Examining the proof script we encounter the
  following text.  (How did we decide to focus on this goal?  Some
  information is provided in ACLH, and the ACL2 documentation on
  [tips] may be helpful.  But the simplest answer is: this was the
  first goal suggested by the ``[proof-tree]'' tool below the start
  of the proof by induction.  See [proof-tree].)

    Subgoal *1/5''
    (IMPLIES (AND (INTEGERP N)
                  (< 0 N)
                  (NOT (EQUAL N 1))
                  (EQUAL (LEN (HANOI A C B (+ -1 N)))
                         (+ -1 (EXPT 2 (+ -1 N))))
                  (EQUAL (LEN (HANOI B A C (+ -1 N)))
                         (+ -1 (EXPT 2 (+ -1 N)))))
             (EQUAL (LEN (APPEND (HANOI A C B (+ -1 N))
                                 (CONS (LIST 'MOVE A 'TO C)
                                       (HANOI B A C (+ -1 N)))))
                    (+ -1 (* 2 (EXPT 2 (+ -1 N))))))

  It is difficult to make much sense of such a complicated goal.
  However, we do notice something interesting.  In the conclusion is
  a [term] of the following shape.

    (LEN (APPEND ... ...))

  We conjecture that the length of the [47m[append][0m of two lists should be
  the sum of the lengths of the lists.  If the prover knew that, it
  could possibly have simplified this [term] earlier and made more
  progress in the proof.  Therefore, we need a [rewrite] rule that
  will suggest such a simplification to the prover.  The appropriate
  rule is:

    (defthm len-append
      (equal (len (append x y))
             (+ (len x) (len y))))

  We submit this to the prover, which proves it by a straightforward
  induction.  The prover stores this lemma as a [rewrite] rule and
  will subsequently (unless we [disable] the rule) replace [term]s
  matching the left hand side of the rule with the appropriate
  instance of the [term] on the right hand side.

  We now resubmit our lemma [47mhanoi-moves-required[0m to ACL2.  On this
  attempt, the proof succeeds and we are done.

  One bit of cleaning up is useful.  We needed the hypotheses that:

    (and (integerp n) (<= 0 n)).

  This is an awkward way of saying that [47mn[0m is a natural number; natural
  is not a primitive data type in ACL2.  We could define a function
  [47mnaturalp[0m, but it is somewhat more convenient to define a macro as
  follows:

    (defmacro naturalp (x)
      (list 'and (list 'integerp x)
                    (list '<= 0 x)))

  Subsequently, we can use [47m(naturalp n)[0m wherever we need to note that a
  quantity is a natural number.  See [defmacro] for more information
  about ACL2 macros.  With this macro, we can reformulate our theorem
  as follows:

    (defthm hanoi-moves-required
      (implies (naturalp n)
               (equal (len (hanoi a b c n))
                      (1- (expt 2 n))))).

  Another interesting (but much harder) theorem asserts that the list
  of moves generated by our [47mhanoi[0m function actually accomplishes the
  desired goal while following the rules.  When you can state and
  prove that theorem, you'll be a very competent ACL2 user.

  By the way, the name ``Towers of Hanoi'' derives from a legend that a
  group of Vietnamese monks works day and night to move a stack of 64
  gold disks from one diamond peg to another, following the rules set
  out above.  We're told that the world will end when they complete
  this task.  From the theorem above, we know that this requires
  18,446,744,073,709,551,615 moves:

    ACL2 !>(1- (expt 2 64))
    18446744073709551615
    ACL2 !>

  We're guessing they won't finish any time soon.")
 (TUTORIAL2-EIGHTS-PROBLEM
  (ANNOTATED-ACL2-SCRIPTS)
  "The Eights Problem Example

  This example was written almost entirely by Bill Young of
  Computational Logic, Inc.

  This simple example was brought to our attention as one that Paul
  Jackson has solved using the NuPrl system.  The challenge is to
  prove the theorem:

    for all n > 7, there exist naturals i and j such that: n = 3i + 5j.

  In ACL2, we could phrase this theorem using quantification.  However
  we will start with a constructive approach, i.e., we will show that
  values of [47mi[0m and [47mj[0m exist by writing a function that will construct
  such values for given [47mn[0m.  Suppose we had a function [47m(split n)[0m that
  returns an appropriate pair [47m(i . j)[0m.  Our theorem would be as
  follows:

    (defthm split-splits
      (let ((i (car (split n)))
            (j (cdr (split n))))
        (implies (and (integerp n)
                      (< 7 n))
                 (and (integerp i)
                      (<= 0 i)
                      (integerp j)
                      (<= 0 j)
                      (equal (+ (* 3 i) (* 5 j))
                             n)))))

  That is, assuming that [47mn[0m is a natural number greater than 7, [47m(split
  n)[0m returns values [47mi[0m and [47mj[0m that are in the appropriate relation to
  [47mn[0m.

  Let's look at a few cases:

     8 = 3x1 + 5x1;    11 = 3x2 + 5x1;     14 = 3x3 + 5x1;   ...
     9 = 3x3 + 5x0;    12 = 3x4 + 5x0;     15 = 3x5 + 5x0;   ...
    10 = 3x0 + 5x2;    13 = 3x1 + 5x2;     16 = 3x2 + 5x2;   ...

  Maybe you will have observed a pattern here; any natural number
  larger than 10 can be obtained by adding some multiple of 3 to 8,
  9, or 10.  This gives us the clue to constructing a proof.  It is
  clear that we can write split as follows:

    (defun bump-i (x)
      ;; Bump the i component of the pair
      ;; (i . j) by 1.
      (cons (1+ (car x)) (cdr x)))

    (defun split (n)
      ;; Find a pair (i . j) such that
      ;; n = 3i + 5j.
      (if (or (zp n) (< n 8))
          nil ;; any value is really reasonable here
        (if (equal n 8)
            (cons 1 1)
          (if (equal n 9)
              (cons 3 0)
            (if (equal n 10)
                (cons 0 2)
              (bump-i (split (- n 3))))))))

  Notice that we explicitly compute the values of [47mi[0m and [47mj[0m for the cases
  of 8, 9, and 10, and for the degenerate case when [47mn[0m is not a
  natural or is less than 8.  For all naturals greater than [47mn[0m, we
  decrement [47mn[0m by 3 and bump the number of 3's (the value of i) by 1.
  We know that the recursion must terminate because any integer value
  greater than 10 can eventually be reduced to 8, 9, or 10 by
  successively subtracting 3.

  Let's try it on some examples:

    ACL2 !>(split 28)
    (6 . 2)

    ACL2 !>(split 45)
    (15 . 0)

    ACL2 !>(split 335)
    (110 . 1)

  Finally, we submit our theorem [47msplit-splits[0m, and the proof succeeds.
  In this case, the prover is ``smart'' enough to induct according to
  the pattern indicated by the function split.

  For completeness, we'll note that we can state and prove a quantified
  version of this theorem.  We introduce the notion [47msplit-able[0m to
  mean that appropriate [47mi[0m and [47mj[0m exist for [47mn[0m.

    (defun-sk split-able (n)
      (exists (i j)
              (equal n (+ (* 3 i) (* 5 j)))))

  Then our theorem is given below.  Notice that we prove it by
  observing that our previous function [47msplit[0m delivers just such an [47mi[0m
  and [47mj[0m (as we proved above).

    (defthm split-splits2
      (implies (and (integerp n)
                    (< 7 n))
               (split-able n))
      :hints ((\"Goal\" :use (:instance split-able-suff
                                      (i (car (split n)))
                                      (j (cdr (split n)))))))

  Unfortunately, understanding the mechanics of the proof requires
  knowing something about the way [47m[defun-sk][0m works.  See [defun-sk]
  or see [Tutorial4-Defun-Sk-Example] for more on that subject.")
 (TUTORIAL3-PHONEBOOK-EXAMPLE
  (ANNOTATED-ACL2-SCRIPTS)
  "A Phonebook Specification

  The other tutorial examples are rather small and entirely self
  contained.  The present example is rather more elaborate, and makes
  use of a feature that really adds great power and versatility to
  ACL2, namely: the use of previously defined collections of lemmas,
  in the form of ``[books].''

  This example was written almost entirely by Bill Young of
  Computational Logic, Inc.  It was updated in December, 2024 (from
  the original version of about two decades ago) thanks to Andrei
  Koltsov, to work with recent ACL2 versions.

  This example is based on one developed by Ricky Butler and Sally
  Johnson of NASA Langley for the PVS system, and subsequently
  revised by Judy Crow, [3met al[0m, at SRI.  It is a simple phone book
  specification.  We will not bother to follow their versions
  closely, but will instead present a style of specification natural
  for ACL2.

  The idea is to model an electronic phone book with the following
  properties.

      Our phone book will store the phone numbers of a city.

      It must be possible to retrieve a phone number, given a name.

      It must be possible to add and delete entries.

  Of course, there are numerous ways to construct such a model.  A
  natural approach within the Lisp/ACL2 context is to use
  ``association lists'' or ``alists.'' Briefly, an alist is a list of
  pairs [47m(key .  value)[0m associating a value with a key.  A phone book
  could be an alist of pairs [47m(name . pnum)[0m.  To find the phone number
  associated with a given name, we merely search the alist until we
  find the appropriate pair.  For a large city, such a linear list
  would not be efficient, but at this point we are interested only in
  [31;1mmodeling[0m the problem, not in deriving an efficient implementation.
  We could address that question later by proving our alist model
  equivalent, in some desired sense, to a more efficient data
  structure.

  We could build a theory of alists from scratch, or we can use a
  previously constructed theory (book) of alist definitions and
  facts.  By using an existing book, we build upon the work of
  others, start our specification and proof effort from a much richer
  foundation, and hopefully devote more of our time to the problem at
  hand.  Unfortunately, it is not completely simple for the new user
  to know what [books] are available and what they contain.
  Documentation is available for the growing collection of
  [community-books] that are typically downloaded with ACL2, and a
  mailing list, [47macl2-help[0m, is available (see the {ACL2 home page |
  http://www.cs.utexas.edu/users/moore/acl2/}.  For present purposes,
  the beginning user can simply take our word that a book exists
  containing useful alist definitions and facts.  These definitions
  and lemmas can be introduced into the current theory using the
  [command]:

    (include-book \"data-structures/alist-defthms\" :dir :system)

  This book has been ``certified,'' which means that the definitions
  and lemmas have been mechanically checked and stored in a safe
  manner.  (See [books] and see [include-book] for details.)

  Including this book makes available a collection of functions
  including the following:

    (ALISTP A)    ; is A an alist (actually a primitive ACL2 function)

    (BIND X V A)  ; associate the key X with value V in alist A

    (BINDING X A) ; return the value associated with key X in alist A

    (BOUND? X A)  ; is key X associated with any value in alist A

    (DOMAIN A)    ; return the list of keys bound in alist A

    (RANGE A)     ; return the list of values bound to keys in alist A

    (REMBIND X A) ; remove the binding of key X in alist A

  Along with these function definitions, the book also provides a
  number of proved lemmas that aid in simplifying expressions
  involving these functions.  (See [rule-classes] for the way in
  which lemmas are used in simplification and rewriting.)  For
  example,

    (defthm bound?-bind
      (equal (bound? x (bind y v a))
             (or (equal x y)
                 (bound? x a))))

  asserts that [47mx[0m will be bound in [47m(bind y v a)[0m if and only if: either [47mx
  = y[0m or [47mx[0m was already bound in [47ma[0m.  Also,

    (defthm binding-bind
      (equal (binding x (bind y v a))
             (if (equal x y)
                 v
               (binding x a))))

  asserts that the resulting binding will be [47mv[0m, if [47mx = y[0m, or the
  binding that [47mx[0m had in [47ma[0m already, if not.

  Thus, the inclusion of this book essentially extends our
  specification and reasoning capabilities by the addition of new
  operations and facts about these operations that allow us to build
  further specifications on a richer and possibly more intuitive
  foundation.

  However, it must be admitted that the use of a book such as this has
  two potential limitations:

      the definitions available in a book may not be ideal for your
      particular problem;

      it is (extremely) likely that some useful facts (especially,
      [rewrite] rules) are not available in the book and will have to
      be proved.

  For example, what is the value of [47mbinding[0m when given a key that is
  not bound in the alist?  We can find out by examining the function
  definition.  Look at the definition of the [47mbinding[0m function (or any
  other defined function), using the [47m:[0m[47m[pe][0m command:

    ACL2 !>:pe binding
       d   1  (INCLUDE-BOOK \"data-structures/alist-defthms\"
                            :DIR ...)

              [Included books, outermost to innermost:
               \".../acl2/books/data-structures/alist-defthms.lisp\"
               \".../acl2/books/data-structures/alist-defuns.lisp\"
              ]

    >V d       (DEFUN
                BINDING (X A)
                \"The value bound to X in alist A.\"
                (DECLARE
                   (XARGS :GUARD (AND (ALISTP A)
                                      (OR (EQLABLEP X) (EQLABLE-ALISTP A)))))
                (CDR (ASSOC X A)))

  This tells us that [47mbinding[0m was introduced by the given [47m[include-book][0m
  form, is currently [disable]d in the current theory, and has the
  definition given by the displayed [47m[defun][0m form.  We see that
  [47mbinding[0m is actually defined in terms of the primitive [47m[assoc][0m.  If
  we submit [47m:pe assoc[0m then we can see that [47massoc[0m is a macro that
  essentially serves as an abbreviation for the primitive function
  [47m[assoc-equal][0m.  We say no more about [47massoc[0m here but instead focus
  on [47massoc-equal[0m.  If we use [47m:pe[0m to look at the definition of
  [47m[assoc-equal][0m:

    PV    -8489  (DEFUN ASSOC-EQUAL (X ALIST)
                   (DECLARE (XARGS :GUARD (ALISTP ALIST)))
                   (COND ((ENDP ALIST) NIL)
                         ((EQUAL X (CAR (CAR ALIST)))
                          (CAR ALIST))
                         (T (ASSOC-EQUAL X (CDR ALIST)))))

  we can see that [47m[assoc-equal][0m returns [47mnil[0m upon reaching the end of an
  unsuccessful search down the alist.  So [47mbinding[0m returns [47m(cdr nil)[0m
  in that case, which is [47mnil[0m.  Notice that we could also have
  investigated this question by trying some simple examples.

    ACL2 !>(binding 'a nil)
    NIL

    ACL2 !>(binding 'a (list (cons 'b 2)))
    NIL

  These definitions aren't ideal for all purposes. For one thing,
  there's nothing that keeps us from having [47mnil[0m as a value bound to
  some key in the alist.  Thus, if [47mbinding[0m returns [47mnil[0m we don't
  always know if that is the value associated with the key in the
  alist, or if that key is not bound.  We'll have to keep that
  ambiguity in mind whenever we use [47mbinding[0m in our specification.
  Suppose instead that we wanted [47mbinding[0m to return some error string
  on unbound keys.  Well, then we'd just have to write our own
  version of [47mbinding[0m.  But then we'd lose much of the value of using
  a previously defined book.  As with any specification technique,
  certain tradeoffs are necessary.

  Why not take a look at the definitions of other alist functions and
  see how they work together to provide the ability to construct and
  search alists?  We'll be using them rather heavily in what follows
  so it will be good if you understand basically how they work.
  Simply start up ACL2 and execute the form shown earlier, but
  substituting our directory name for the top-level ACL2 directory
  with yours.  Alternatively, just

    (include-book \"data-structures/alist-defthms\" :dir :system)

  Then, you can use [47m:[0m[pe] to look at function definitions.  You'll soon
  discover that almost all of the definitions are built on
  definitions of other, more primitive functions, as [47mbinding[0m is built
  on [47m[assoc-equal][0m.  You can look at those as well, of course, or in
  many cases visit their documentation.

  The other problem with using a predefined book is that it will seldom
  be ``sufficiently complete,'' in the sense that the collection of
  [rewrite] rules supplied won't be adequate to prove everything we'd
  like to know about the interactions of the various functions.  If
  it were, there'd be no real reason to know that [47mbinding[0m is built on
  top of [47m[assoc-equal][0m, because everything we'd need to know about
  [47mbinding[0m would be nicely expressed in the collection of theorems
  supplied with the book.  However, that's very seldom the case.
  Developing such a collection of rules is currently more art than
  science and requires considerable experience.  We'll encounter
  examples later of ``missing'' facts about [47mbinding[0m and our other
  alist functions.  So, let's get on with the example.

  Notice that alists are mappings of keys to values; but, there is no
  notion of a ``type'' associated with the keys or with the values.
  Our phone book example, however, does have such a notion of types;
  we map names to phone numbers.  We can introduce these ``types'' by
  explicitly defining them, e.g., names are strings and phone numbers
  are integers.  Alternatively, we can [31;1mpartially define[0m or axiomatize
  a recognizer for names without giving a full definition.  A way to
  safely introduce such ``constrained'' function symbols in ACL2 is
  with the [47m[encapsulate][0m form.  For example, consider the following
  form.

    (encapsulate
      ;; Introduce a recognizer for names and give a ``type'' lemma.
      (((namep *) => *))
      ;;
      (local (defun namep (x)
               ;; This declare is needed to tell
               ;; ACL2 that we're aware that the
               ;; argument x is not used in the body
               ;; of the function.
               (declare (ignore x))
               t))
      ;;
      (defthm namep-booleanp
        (booleanp (namep x))))

  This [47m[encapsulate][0m form introduces the new function [47mnamep[0m of one
  argument and one result and constrains [47m(namep x)[0m to be Boolean, for
  all inputs [47mx[0m.  More generally, an encapsulation establishes an
  environment in which functions can be defined and theorems and
  rules added without necessarily introducing those functions,
  theorems, and rules into the environment outside the encapsulation.
  To be admissible, all the events in the body of an encapsulate must
  be admissible.  But the effect of an encapsulate is to assume only
  the non-local events.

  The first ``argument'' to [47mencapsulate[0m, [47m(((namep *) => *))[0m above,
  declares the intended [signature]s of new function symbols that
  will be ``exported'' from the encapsulation without definition.
  The [47m[local][0m [47m[defun][0m of [47mname[0m defines name within the encapsulation
  always to return [47mt[0m.  The [47mdefthm[0m event establishes that [47mnamep[0m is
  Boolean.  By making the [47mdefun[0m local but the [47mdefthm[0m non-[47mlocal[0m this
  encapsulate constrains the undefined function [47mnamep[0m to be Boolean;
  the admissibility of the encapsulation establishes that there
  exists a Boolean function (namely the constant function returning
  [47mt[0m).

  We can subsequently use [47mnamep[0m as we use any other Boolean function,
  with the proviso that we know nothing about it except that it
  always returns either [47mt[0m or [47mnil[0m.  We use [47mnamep[0m to ``recognize''
  legal keys for our phonebook alist.

  We wish to do something similar to define what it means to be a legal
  phone number.  We submit the following form to ACL2.

    (encapsulate
      ;; Introduce a recognizer for phone numbers.
      (((pnump *) => *))
      ;;
      (local (defun pnump (x)
               (not (equal x nil))))
      ;;
      (defthm pnump-booleanp
        (booleanp (pnump x)))
      ;;
      (defthm nil-not-pnump
        (not (pnump nil))))

  This introduces a Boolean-valued recognizer [47mpnump[0m, with the
  additional proviso that the constant [47mnil[0m is not a [47mpnump[0m.  We impose
  this restriction to guarantee that we'll never bind a name to [47mnil[0m
  in our phone book and thereby introduce the kind of ambiguity
  described above regarding the use of [47mbinding[0m.

  Now a legal phone book is an alist mapping from [47mnamep[0ms to [47mpnump[0ms.  We
  can define this as follows:

    (defun name-phonenum-pairp (x)
      ;; Recognizes a pair of (name . pnum).
      (and (consp x)
           (namep (car x))
           (pnump (cdr x))))

    (defun phonebookp (l)
      ;; Recognizes a list of such pairs.
      (if (not (consp l))
          (null l)
        (and (name-phonenum-pairp (car l))
             (phonebookp (cdr l)))))

  Thus, a phone book is really a list of pairs [47m(name . pnum)[0m.  Notice
  that we have not assumed that the keys of the phone book are
  distinct.  We'll worry about that question later.  (It is not
  always desirable to insist that the keys of an alist be distinct.
  But it may be a useful requirement for our specific example.)

  Now we are ready to define some of the functions necessary for our
  phonebook example.  The functions we need are:

    (IN-BOOK? NM BK)          ; does NM have a phone number in BK

    (FIND-PHONE NM BK)        ; find NM's phone number in phonebook BK

    (ADD-PHONE NM PNUM BK)    ; give NM the phone number PNUM in BK

    (CHANGE-PHONE NM PNUM BK) ; change NM's phone number to PNUM in BK

    (DEL-PHONE NM PNUM)       ; remove NM's phone number from BK

  Given our underlying theory of alists, it is easy to write these
  functions.  But we must take care to specify appropriate
  ``boundary'' behavior.  Thus, what behavior do we want when, say,
  we try to change the phone number of a client who is not currently
  in the book?  As usual, there are numerous possibilities; here
  we'll assume that we return the phone book unchanged if we try
  anything ``illegal.''

  Possible definitions of our phone book functions are as follows.
  (Remember, an [47minclude-book[0m form such as the ones shown earlier must
  be executed in order to provide definitions for functions such as
  [47mbound?[0m.)

    (defun in-book? (nm bk)
      (bound? nm bk))

    (defun find-phone (nm bk)
      (binding nm bk))

    (defun add-phone (nm pnum bk)
      ;; If nm already in-book?, make no change.
      (if (in-book? nm bk)
          bk
        (bind nm pnum bk)))

    (defun change-phone (nm pnum bk)
      ;; Make a change only if nm already has a phone number.
      (if (in-book? nm bk)
          (bind nm pnum bk)
        bk))

    (defun del-phone (nm bk)
      ;; Remove the binding from bk, if there is one.
      (rembind nm bk))

  Notice that we don't have to check whether a name is in the book
  before deleting, because [47mrembind[0m is essentially a no-op if [47mnm[0m is
  not bound in [47mbk[0m.

  In some sense, this completes our specification.  But we can't have
  any real confidence in its correctness without validating our
  specification in some way.  One way to do so is by proving some
  properties of our specification.  Some candidate properties are:

      1. A name will be in the book after we add it.

      2. We will find the most recently added phone number for a client.

      3. If we change a number, we'll find the change.

      4. Changing and then deleting a number is the same as just deleting.

      5. A name will not be in the book after we delete it.

  Let's formulate some of these properties.  The first one, for
  example, is:

    (defthm add-in-book
      (in-book? nm (add-phone nm pnum bk))).

  You may wonder why we didn't need any hypotheses about the ``types''
  of the arguments.  In fact, [47madd-in-book[0m is really expressing a
  property that is true of alists in general, not just of the
  particular variety of alists we are dealing with.  Of course, we
  could have added some extraneous hypotheses and proved

    (defthm add-in-book
      (implies (and (namep nm)
                    (pnump pnum)
                    (phonebookp bk))
               (in-book? nm (add-phone nm pnum bk))))

  but that would have yielded a weaker and less useful lemma because it
  would apply to fewer situations.  In general, it is best to state
  lemmas in the most general form possible and to eliminate
  unnecessary hypotheses whenever possible.  The reason for that is
  simple: lemmas are usually stored as rules and used in later
  proofs.  For a lemma to be used, its hypotheses must be relieved
  (proved to hold in that instance); extra hypotheses require extra
  work.  So we avoid them whenever possible.

  There is another, more important observation to make about our lemma.
  Even in its simpler form (without the extraneous hypotheses), the
  lemma [47madd-in-book[0m may be useless as a [rewrite] rule.  Notice that
  it is stated in terms of the non-recursive functions [47min-book?[0m and
  [47madd-phone[0m.  If such functions appear in the left hand side of the
  conclusion of a lemma, the lemma may not ever be used.  Suppose in
  a later proof, the theorem prover encountered a [term] of the form:

    (in-book? nm (add-phone nm pnum bk)).

  Since we've already proved [47madd-in-book[0m, you'd expect that this would
  be immediately reduced to true.  However, the theorem prover will
  often ``expand'' the non-recursive definitions of [47min-book?[0m and
  [47madd-phone[0m using their definitions [31;1mbefore[0m it attempts rewriting with
  lemmas.  After this expansion, lemma [47madd-in-book[0m won't ``match''
  the [term] and so won't be applied.  Look back at the proof script
  for [47madd-in-proof[0m and you'll notice that at the very end the prover
  warned you of this potential difficulty when it printed:

    Warnings:  Non-rec
    Time:  0.18 seconds (prove: 0.05, print: 0.00, other: 0.13)
    ADD-IN-BOOK

  The ``Warnings'' line notifies you that there are non-recursive
  function calls in the left hand side of the conclusion and that
  this problem might arise.  Of course, it may be that you don't ever
  plan to use the lemma for rewriting or that your intention is to
  [disable] these functions.  [Disable]d functions are not expanded
  and the lemma should apply.  However, you should always take note
  of such warnings and consider an appropriate response.  By the way,
  we noted above that [47mbinding[0m is [disable]d.  If it were not, none of
  the lemmas about [47mbinding[0m in the book we included would likely be of
  much use for exactly the reason we just gave.

  For our current example, let's assume that we're just investigating
  the properties of our specifications and not concerned about using
  our lemmas for rewriting.  So let's go on.  If we really want to
  avoid the warnings, we can add [47m:rule-classes nil[0m to each [47mdefthm[0m
  event; see [rule-classes].

  Property 2 is: we always find the most recently added phone number
  for a client.  Try the following formalization:

    (defthm find-add-first-cut
      (equal (find-phone nm (add-phone nm pnum bk))
             pnum))

  and you'll find that the proof attempt fails.  Examining the proof
  attempt and our function definitions, we see that the lemma is
  false if [47mnm[0m is already in the book.  We can remedy this situation
  by reformulating our lemma in at least two different ways:

    (defthm find-add1
      (implies (not (in-book? nm bk))
               (equal (find-phone nm (add-phone nm pnum bk))
                      pnum)))

    (defthm find-add2
      (equal (find-phone nm (add-phone nm pnum bk))
             (if (in-book? nm bk)
                 (find-phone nm bk)
                 pnum)))

  For technical reasons, lemmas such as [47mfind-add2[0m, i.e., which do not
  have hypotheses, are usually slightly preferable.  This lemma is
  stored as an ``unconditional'' [rewrite] rule (i.e., has no
  hypotheses) and, therefore, will apply more often than [47mfind-add1[0m.
  However, for our current purposes either version is all right.

  Property 3 says: If we change a number, we'll find the change.  This
  is very similar to the previous example.  The formalization is as
  follows.

    (defthm find-change
      (equal (find-phone nm (change-phone nm pnum bk))
             (if (in-book? nm bk)
                 pnum
               (find-phone nm bk))))

  Property 4 says: changing and then deleting a number is the same as
  just deleting.  We can model this as follows.

    (defthm del-change
      (equal (del-phone nm (change-phone nm pnum bk))
             (del-phone nm bk)))

  Unfortunately, our attempt to prove it failed with the following
  subgoal under a top-level induction.

    Subgoal *1/4''
    (IMPLIES (AND (CONSP BK)
                  (NOT (EQUAL NM (CAR (CAR BK))))
                  (NOT (BOUND?-EQUAL NM (CDR BK)))
                  (BOUND?-EQUAL NM BK))
             (EQUAL (REMBIND-EQUAL NM (BIND-EQUAL NM PNUM (CDR BK)))
                    (REMBIND-EQUAL NM (CDR BK))))

  We have defined [47mdel-phone[0m using [47mrembind[0m, and [47mchange-phone[0m using
  [47min-book[0m (which uses [47mbound?[0m) and [47mbind[0m; but we have ``equal''
  suffixes in the subgoal.  The cause is theorems of the form
  [47m***->***-equal[0m, which are given in the included book.  We can use
  [history]'s [47m:[0m[47m[pl][0m command to print the rules for a given name or
  term.  Here is the part of [47m:[0m[47m[pl][0m's output we are interested in now,
  for the [47mrembind[0m function:

    ACL2 !>:pl rembind
    ...

    Rune:         (:REWRITE REMBIND->REMBIND-EQUAL)
    Enabled:      T
    Hyps:         T
    Equiv:        EQUAL
    Lhs:          (REMBIND X A)
    Rhs:          (REMBIND-EQUAL X A)
    Backchain-limit-lst: NIL
    Subclass:     ABBREVIATION

    ...

  We can see that [rewrite] rule [47mrembind->rembind-equal[0m is [enable]d
  and that it replaces [3mlhs[0m with [3mrhs[0m.  For functions [47mbind[0m, [47mbinding[0m and
  [47mbound?[0m we have similar rules.

  Our intuition about [47mrembind[0m and [47mbind[0m tells us that this goal should
  be true even without the hypotheses.  We attempt to prove the
  following lemma.

    (defthm rembind-equal-bind-equal
      (equal (rembind-equal nm (bind-equal nm pnum bk))
             (rembind-equal nm bk)))

  The prover proves this by induction, and stores it as a rewrite rule.
  After that, the prover has no difficulty in proving [47mdel-change[0m.

  The need to prove lemma [47mrembind-equal-bind-equal[0m illustrates a point
  we made early in this example: the collection of [rewrite] rules
  supplied by a previously certified book will almost never be
  everything you'll need. It would be nice if we could operate purely
  in the realm of names, phone numbers, and phone books without ever
  having to prove any new facts about alists.  Unfortunately, we
  needed a fact about the relation between [47mrembind-equal[0m and
  [47mbind-equal[0m that wasn't supplied with the alists theory. Hopefully,
  such omissions will be rare.

  Let's take two steps back now (just enter the [47m:u[0m command twice) to
  get acquainted with a method that will be very useful to us.  What
  happens if we state the previous lemma another way?

    (defthm rembind-bind
      (equal (rembind name (bind name num book))
             (rembind name book)))

  An attempt to prove [47mdel-change[0m would fail then with the same subgoal
  as above.  In this case we can give to the prover the hint to use
  [47mrembind-bind[0m as an instance of [47mdel-change[0m (see [hints] and find
  keywords [47m:use[0m and [47m:instance[0m):

    (defthm del-change-lemma-instance-example
      (equal (del-phone nm (change-phone nm pnum bk))
             (del-phone nm bk))
      :hints ((\"Goal\" :use (:instance rembind-bind
                                      (name nm)
                                      (num pnum)
                                      (book bk)))))

  As described in [hints], a [47m:use[0m hint causes the prover to replace a
  goal [47mG[0m with new goal ([47mIMPLIES[0m [47mP[0m [47mG[0m), where [47mP[0m is the specified
  theorem to use.  The [47m:instance[0m form specifies instantiation of the
  free variables of a previously proved theorem.  See
  [lemma-instance] for more information on this subject.

  Finally, let's consider our property 5 above: a name will not be in
  the book after we delete it.  We formalize this as follows:

    (defthm in-book-del
      (not (in-book? nm (del-phone nm bk))))

  This proves easily.  But notice that it's only true because [47mdel-phone[0m
  (actually [47mrembind[0m) removes [31;1mall[0m occurrences of a name from the phone
  book.  If it only removed, say, the first one it encountered, we'd
  need a hypothesis that said that [47mnm[0m occurs at most once in [47mbk[0m.  Ah,
  maybe that's a property you hadn't considered.  Maybe you want to
  ensure that [31;1many[0m name occurs at most once in any valid phonebook.

  To complete this example, let's consider adding an [31;1minvariant[0m to our
  specification.  In particular, suppose we want to ensure that no
  client has more than one associated phone number.  One way to
  ensure this is to require that the domain of the alist is a ``set''
  (has no duplicates).

    (defun setp (l)
      (if (atom l)
          (null l)
        (and (not (member-equal (car l) (cdr l)))
             (setp (cdr l)))))

    (defun valid-phonebookp (bk)
      (and (phonebookp bk)
           (setp (domain bk))))

  Now, we want to show under what conditions our operations preserve
  the property of being a [47mvalid-phonebookp[0m.  The operations [47min-book?[0m
  and [47mfind-phone[0m don't return a phone book, so we don't really need
  to worry about them.  Since we're really interested in the
  ``types'' of values preserved by our phonebook functions, let's
  look at the types of those operations as well.

    (defthm in-book-booleanp
      (booleanp (in-book? nm bk)))

    (defthm in-book-namep
      (implies (and (phonebookp bk)
                    (in-book? nm bk))
               (namep nm))
      :hints ((\"Goal\" :in-theory (enable bound?-equal))))

    (defthm find-phone-pnump
      (implies (and (phonebookp bk)
                    (in-book? nm bk))
               (pnump (find-phone nm bk)))
      :hints ((\"Goal\" :in-theory (enable bound?-equal
                                         binding-equal))))

  Note the ``[47m:[0m[47m[hints][0m'' on the last two lemmas.  Neither of these would
  prove without these [hints], because once again there are some
  facts about [47mbound?-equal[0m and [47mbinding-equal[0m not available in our
  current context.  Now, we could figure out what those facts are and
  try to prove them.  Alternatively, we can [enable] [47mbound?-equal[0m and
  [47mbinding-equal[0m and hope that by opening up these functions, the
  conjectures will reduce to versions that the prover does know
  enough about, perhaps using proof by induction.  In this case, this
  strategy works.  The hints tell the prover to [enable] the
  functions in question when considering the designated goal and any
  subgoals of it.

  It's important to understand that it's not enough to [enable] the
  [47mbound?[0m and [47mbinding[0m functions.  That's because rewrite rules of the
  form [47m***->***-equal[0m (mentioned above) will replace [enable]d
  functions with [disable]d ones for which there are not sufficient
  rules to complete the proof.  We can use [history]'s very
  informative command [47m:[0m[pl] to get a lot of information about rules
  for a given name.

  Below we develop the theorems showing that [47madd-phone[0m, [47mchange-phone[0m,
  and [47mdel-phone[0m preserve our proposed invariant.  Notice that along
  the way we have to prove some subsidiary facts, some of which are
  pretty ugly.  It would be a good idea for you to try, say,
  [47madd-phone-preserves-invariant[0m without introducing the following
  four lemmas first.  Perhaps you will use the instantiation of
  lemmas method, described above.  See if you can develop the proof
  and only add these lemmas as you need assistance.  Then try
  [47mchange-phone-preserves-invariant[0m and [47mdel-phone-preserves-invariant[0m.
  They will be easier.  It is illuminating to think about why
  [47mdel-phone-preserves-invariant[0m does not need any ``type''
  hypotheses.

    (defthm bind-preserves-phonebookp
      (implies (and (phonebookp bk)
                    (namep nm)
                    (pnump num))
               (phonebookp (bind nm num bk))))

    (defthm member-equal-strip-cars-bind-equal
      (implies (and (not (equal x y))
                    (not (member-equal x (strip-cars a))))
               (not (member-equal x (strip-cars (bind-equal y z a))))))

    (defthm bind-equal-preserves-domain-setp
      (implies (and (alistp bk)
                    (setp (domain bk)))
               (setp (domain (bind-equal nm num bk))))
      :hints ((\"Goal\" :in-theory (enable domain))))

  Let's take two steps back (using [47m:u[0m twice) and prove the following
  instead of [47mmember-equal-strip-cars-bind-equal[0m:

    (defthm member-equal-strip-cars-bind
      (implies (and (not (equal x y))
                    (not (member-equal x (strip-cars a))))
               (not (member-equal x (strip-cars (bind y z a))))))

  Then [47mbind-equal-preserves-domain-setp[0m fails:

    Subgoal *1/5''
    (IMPLIES (AND (CONSP BK)
             (NOT (EQUAL NM (CAR (CAR BK))))
             (SETP (STRIP-CARS (BIND-EQUAL NM NUM (CDR BK))))
             (CONSP (CAR BK))
             (ALISTP (CDR BK))
             (NOT (MEMBER-EQUAL (CAR (CAR BK))
                                (STRIP-CARS (CDR BK))))
             (SETP (STRIP-CARS (CDR BK))))
        (NOT (MEMBER-EQUAL (CAR (CAR BK))
                           (STRIP-CARS (BIND-EQUAL NM NUM (CDR BK))))))

  We can use a [lemma-instance] to prove it:

    (defthm bind-equal-preserves-domain-setp
      (implies (and (alistp bk)
                    (setp (domain bk)))
               (setp (domain (bind-equal nm num bk))))
      :hints ((\"Goal\" :in-theory (enable domain))
              (\"Subgoal *1/5''\" :use (:instance
                                      member-equal-strip-cars-bind
                                      (x (car (car bk)))
                                      (y nm)
                                      (z num)
                                      (a (cdr bk))))))

  The use of [lemma-instance] is somewhat artificial in this example,
  but this method gives great opportunities to lead ACL2 in proving
  theorems.  That said, it is generally preferable to avoid [47m:use[0m
  hints in favor of developing a useful set of [rewrite] rules, since
  those rules can help to automate future proof attempts.

  We continue now with proofs that our operations preserve the
  [47mphonebook'[0m invariant.

    (defthm phonebookp-alistp
      (implies (phonebookp bk)
               (alistp bk)))

    (defthm bind-equal-preserves-phonebookp
      (implies (and (phonebookp bk)
                    (namep nm)
                    (pnump num))
               (phonebookp (bind-equal nm num bk))))

    (defthm add-phone-preserves-invariant
      (implies (and (valid-phonebookp bk)
                    (namep nm)
                    (pnump num))
               (valid-phonebookp (add-phone nm num bk)))
      :hints ((\"Goal\" :in-theory (disable domain-bind-equal))))

    (defthm change-phone-preserves-invariant
      (implies (and (valid-phonebookp bk)
                    (namep nm)
                    (pnump num))
               (valid-phonebookp (change-phone nm num bk)))
      :hints ((\"Goal\" :in-theory (disable domain-bind-equal))))

    (defthm member-remove-equal
      (implies (and (not (equal a b))
                    (not (member a x)))
               (not (member a (remove-equal b x)))))

    (defthm remove-equal-preserves-setp
      (implies (setp l)
               (setp (remove-equal x l))))

    (defthm del-phone-preserves-invariant
      (implies (valid-phonebookp bk)
               (valid-phonebookp (del-phone nm bk))))

  As a final test of your understanding, try to formulate and prove an
  invariant that says that no phone number is assigned to more than
  one name.  The following hints may help.

      1. Define the appropriate invariant.  (Hint: remember the function
      [47mrange[0m.)

      2. Do our current definitions of [47madd-phone[0m and [47mchange-phone[0m
      necessarily preserve this property?  If not, consider what
      hypotheses are necessary in order to guarantee that they do
      preserve this property.

      3. Study the definition of the function [47mrange[0m and notice that it is
      defined in terms of the function [47m[strip-cdrs][0m.  Understand how
      this defines the range of an alist.

      4. Formulate the correctness theorems and attempt to prove them.
      You'll probably benefit from studying the invariant proof
      above.  In particular, you may need some fact about the
      function [47m[strip-cdrs][0m analogous to the lemma
      [47mmember-equal-strip-cars-bind[0m above.

  Below is one solution to this exercise.  Don't look at the solution,
  however, until you've struggled a bit with it.  Notice that we
  didn't actually change the definitions of [47madd-phone[0m and
  [47mchange-phone[0m, but added a hypothesis saying that the number is
  ``new.'' We could have changed the definitions to check this and
  return the phonebook unchanged if the number was already in use.

    (defun pnums-in-use (bk)
      (range bk))

    (defun phonenums-unique (bk)
      (setp (pnums-in-use bk)))

    (defun new-pnump (pnum bk)
      (not (member-equal pnum (pnums-in-use bk))))

    (defthm member-equal-strip-cdrs-rembind
      (implies (not (member-equal x (strip-cdrs y)))
               (not (member-equal x (strip-cdrs
                                     (rembind-equal z y))))))

    (defthm del-phone-preserves-phonenums-unique
      (implies (phonenums-unique bk)
               (phonenums-unique (del-phone nm bk)))
      :hints ((\"Goal\" :in-theory (enable range))))

    (defthm strip-cdrs-bind-non-member
      (implies (and (not (bound?-equal x a))
                    (alistp a))
               (equal (strip-cdrs (bind-equal x y a))
                      (append (strip-cdrs a) (list y))))
      :hints ((\"Goal\" :in-theory (enable bound?-equal))))

    (defthm member-append
      (iff (member e (append x y))
           (or (member e x)
               (member e y))))

    (defthm setp-append-list
      (implies (setp l)
               (equal (setp (append l (list x)))
                      (not (member-equal x l)))))

    (defthm add-phone-preserves-phonenums-unique
      (implies (and (phonenums-unique bk)
                    (new-pnump pnum bk)
                    (alistp bk))
               (phonenums-unique (add-phone nm pnum bk)))
      :hints ((\"Goal\" :in-theory (enable range))))

    (defthm member-equal-strip-cdrs-bind-equal
      (implies (and (not (member-equal z (strip-cdrs a)))
                    (not (equal z y)))
               (not (member-equal z (strip-cdrs
                                     (bind-equal x y a))))))

    (defthm change-phone-preserves-phonenums-unique
      (implies (and (phonenums-unique bk)
                    (new-pnump pnum bk)
                    (alistp bk))
               (phonenums-unique (change-phone nm pnum bk)))
      :hints ((\"Goal\" :in-theory (enable range))))")
 (TUTORIAL4-DEFUN-SK-EXAMPLE
  (ANNOTATED-ACL2-SCRIPTS)
  "Example of quantified notions

  This example illustrates the use of [47m[defun-sk][0m and [47m[defthm][0m [events]
  to reason about quantifiers.  See [defun-sk].  For a more through,
  systematic beginner's introduction to quantification in ACL2, see
  [quantifier-tutorial].

  Many users prefer to avoid the use of quantifiers, since ACL2
  provides only very limited support for reasoning about quantifiers.

  Here is a list of [events] that proves that if there are arbitrarily
  large numbers satisfying the disjunction [47m(OR P R)[0m, then either
  there are arbitrarily large numbers satisfying [47mP[0m or there are
  arbitrarily large numbers satisfying [47mR[0m.

    ; Introduce undefined predicates p and r.
    (defstub p (x) t)
    (defstub r (x) t)

    ; Define the notion that something bigger than x satisfies p.
    (defun-sk some-bigger-p (x)
      (exists y (and (< x y) (p y))))

    ; Define the notion that something bigger than x satisfies r.
    (defun-sk some-bigger-r (x)
      (exists y (and (< x y) (r y))))

    ; Define the notion that arbitrarily large x satisfy p.
    (defun-sk arb-lg-p ()
      (forall x (some-bigger-p x)))

    ; Define the notion that arbitrarily large x satisfy r.
    (defun-sk arb-lg-r ()
      (forall x (some-bigger-r x)))

    ; Define the notion that something bigger than x satisfies p or r.
    (defun-sk some-bigger-p-or-r (x)
      (exists y (and (< x y) (or (p y) (r y)))))

    ; Define the notion that arbitrarily large x satisfy p or r.
    (defun-sk arb-lg-p-or-r ()
      (forall x (some-bigger-p-or-r x)))

    ; Prove the theorem promised above.  Notice that the functions open
    ; automatically, but that we have to provide help for some rewrite
    ; rules because they have free variables in the hypotheses.  The
    ; ``witness functions'' mentioned below were introduced by DEFUN-SK.

    (thm
     (implies (arb-lg-p-or-r)
              (or (arb-lg-p)
                  (arb-lg-r)))
     :hints ((\"Goal\"
              :use
              ((:instance some-bigger-p-suff
                          (x (arb-lg-p-witness))
                          (y (some-bigger-p-or-r-witness
                              (max (arb-lg-p-witness)
                                   (arb-lg-r-witness)))))
               (:instance some-bigger-r-suff
                          (x (arb-lg-r-witness))
                          (y (some-bigger-p-or-r-witness
                              (max (arb-lg-p-witness)
                                   (arb-lg-r-witness)))))
               (:instance arb-lg-p-or-r-necc
                          (x (max (arb-lg-p-witness)
                                  (arb-lg-r-witness))))))))

    ; And finally, here's a cute little example.  We have already
    ; defined above the notion (some-bigger-p x), which says that
    ; something bigger than x satisfies p.  Let us introduce a notion
    ; that asserts that there exists both y and z bigger than x which
    ; satisfy p.  On first glance this new notion may appear to be
    ; stronger than the old one, but careful inspection shows that y and
    ; z do not have to be distinct.  In fact ACL2 realizes this, and
    ; proves the theorem below automatically.

    (defun-sk two-bigger-p (x)
      (exists (y z) (and (< x y) (p y) (< x z) (p z))))

    (thm (implies (some-bigger-p x) (two-bigger-p x)))

    ; A technical point:  ACL2 fails to prove the theorem above
    ; automatically if we take its contrapositive, unless we disable
    ; two-bigger-p as shown below.  That is because ACL2 needs to expand
    ; some-bigger-p before applying the rewrite rule introduced for
    ; two-bigger-p, which contains free variables.  The moral of the
    ; story is:  Don't expect too much automatic support from ACL2 for
    ; reasoning about quantified notions.

    (thm (implies (not (two-bigger-p x)) (not (some-bigger-p x)))
         :hints ((\"Goal\" :in-theory (disable two-bigger-p))))")
 (TUTORIAL5-MISCELLANEOUS-EXAMPLES
  (ANNOTATED-ACL2-SCRIPTS)
  "Miscellaneous ACL2 examples

  The following examples are more advanced examples of usage of ACL2.
  They are included largely for reference, in case someone finds them
  useful.


Subtopics

  [File-reading-example]
      Example of reading files in ACL2

  [Functional-instantiation-example]
      A small proof demonstrating functional instantiation

  [Guard-example]
      A brief transcript illustrating [guard]s in ACL2

  [Mutual-recursion-proof-example]
      A small proof about mutually recursive functions")
 (TYPE
  (POINTERS)
  "Disambiguation page for [3mtype[0m-related concepts.

  The word [31;1mtype[0m might mean many things in ACL2.

    Built-in Types
      ACL2 can reason about and compute with certain different kinds of
      objects, such as [numbers], [strings], [characters], and
      [conses].  See [About_Types] for basic background on the
      different kinds of ACL2 objects; also see [type-reasoning] for
      additional relevant background.
    User-Defined Types
      When modeling systems with ACL2, you may often want to introduce
      certain concepts as new data types.  For instance, if you are
      modeling a network, you might want [47mhost[0m and [47mconnection[0m objects.
      ACL2 does not directly support introducing new types.  Instead,
      such types are usually ``emulated'' by introducing a new
      [3mrecognizer[0m function, say [47mhostp[0m, and perhaps some related
      [3mconstructor[0m and [3maccessor[0m functions, say [47mmake-host[0m and
      [47mhost->name[0m.  Macro libraries can help to assist with
      introducing common types.  See for instance [std/util],
      [defdata], or [fty].
    Type Declarations
      For more efficient Common Lisp execution, ACL2 functions can be
      annotated with Common Lisp type specifiers (see [type-spec])
      that may boost performance by reducing run-time type checking.
      This mechanism is integrated with ACL2's [guard] mechanism, so
      you can prove your type declarations are correct.  See also
      [declare] and [the], and also [patbind-the].
    Type Prescriptions
      ACL2 includes a limited but efficient ``type reasoning (see
      [TYPE-REASONING])'' engine for determining whether objects are
      of certain [31;1mbuilt-in[0m types.  This engine can be extended with
      [type-prescription] rules.  Such rules are often inferred
      automatically when new functions are introduced with [defun].
      Type reasoning can assist other reasoning engines like
      [forward-chaining], [linear-arithmetic], and rewriting.
      Type-set information is stored in a [type-alist] data
      structure; see [type-reasoning] for relevant basic
      background...
    Tau
      ACL2 includes another reasoning engine, the [tau-system], for
      reasoning about type-like predicates.  Unlike [type-set], Tau
      can also be used for reasoning about [31;1muser-defined types[0m, and
      can also carry out certain interval arithmetic reasoning.  See
      the [introduction-to-the-tau-system] for more information about
      Tau.")
 (TYPE-ALIST
  (TYPE-SET)
  "An ACL2 representation of contextual knowledge

  See [type-reasoning] for basic background on type reasoning in ACL2.

  The ACL2 prover maintains many structures that need not be understood
  by the user.  One of these, the [3mtype-alist[0m structure, is usually in
  this category.  But some utilities refer to the type-alist, so we
  summarize it here.

  A type-alist is an association list, each element of which is of the
  form [47m(u ts . ttree)[0m, where [47mu[0m is a [term] (in internal,
  ``translated'' form), [47mts[0m is a [type-set], and [47mttree[0m is a tag-tree
  (see [ttree]).  Such an element means that the term [47mu[0m has the
  type-set [47mts[0m, which is a number.  While you are welcome to see the
  [documentation] of [type-set] for details, this is not necessary,
  since user-level utilities generally display a type-alist without
  displaying numeric type-sets.  Instead, they often use a symbol of
  the form [47m*TS-typ*[0m to denote the type described by [47mtyp[0m, and for
  complements they use [47m(TS-COMPLEMENT *TS-typ*)[0m.  For example, a
  context in which the terms [47m(p x y)[0m, [47m(no-duplicatesp-equal y)[0m, and
  [47m(natp x)[0m are assumed to be true (i.e., non-[47mnil[0m) may be displayed
  using the following lines.

    -----
    Terms with type *TS-T*:
    (NO-DUPLICATESP-EQUAL Y)
    -----
    Terms with type (TS-COMPLEMENT *TS-NIL*):
    (P X Y)
    -----
    Terms with type *TS-NON-NEGATIVE-INTEGER*:
    X
    -----

  These lines says that [47m(no-duplicatesp-equal y)[0m is the symbol [47mt[0m, [47m(p x
  y)[0m is not the symbol [47mnil[0m, and [47mx[0m is a non-negative integer (i.e., a
  [47m[natp][0m).

  ACL2 computes a type-alist based on contextual information including
  the hypotheses of the current goal (technically: the negations of
  the literals in the goal that are not currently being rewritten),
  [forward-chaining] from those literals, and the surrounding tests
  in calls of [47mif[0m.  The type-alist is of course not all that is known,
  since an entire logical [world] of facts is also known; and
  additional known information may be recorded in the current
  database of [linear] rules.")
 (TYPE-PRESCRIPTION
  (RULE-CLASSES)
  "Make a rule that specifies the type of a term

  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.
  Also see [type-reasoning] for basic background on type reasoning in
  ACL2.

  In this topic we focus on user-defined type-prescription rules, but
  note that ACL2 also introduces type-prescription rules when
  introducing a function with [47m[defun][0m; see
  [type-prescription-debugging] for discussion of how to influence
  the generation of such rules.

    Examples:
    (defthm integerp-foo                       ; Assumes that foo has been
      (integerp (foo x y))                     ; defined; then, states that
      :rule-classes :type-prescription)        ; (foo x y) is of type integer.

    (defthm characterp-nth-type-prescription   ; (Nth n lst) is of type character
      (implies                                 ; provided the hypotheses can be
       (and (character-listp lst)              ; established by type reasoning.
            (<= 0 n)
            (< n (len lst)))
       (characterp (nth n lst)))
      :rule-classes :type-prescription)

    (defthm characterp-nth-type-prescription-alt ; equivalent to the above
      (implies
       (and (character-listp lst)
            (<= 0 n)
            (< n (len lst)))
       (characterp (nth n lst)))
      :rule-classes ((:type-prescription :typed-term (nth n lst))))

    (defthm demodulize-type-for-quote-value  ; (Demodulize a lst 'value ans) is
      (implies                               ; either a nonnegative integer or
       (and (atom a)                         ; of the same type as ans, provided
            (true-listp lst)                 ; the hyps can be established by type
            (member-equal a lst))            ; reasoning ;
       (or (and (integerp (demodulize a lst 'value ans))
                (>= (demodulize a lst 'value ans) 0))
           (equal (demodulize a lst 'value ans) ans)))
      :rule-classes :type-prescription)

  To specify the term whose type (see [type-set]) is described by the
  rule, provide that term as the value of the [47m:typed-term[0m field of
  the rule class object.

    General Form (after preprocessing; see below):
    (implies hyps
             (or type-restriction1-on-pat
                 ...
                 type-restrictionk-on-pat
                 (equal pat var1)
                 ...
                 (equal pat varj)))

  where [47mpat[0m is the application of some function symbol to some
  arguments, each [47mtype-restrictioni-on-pat[0m is a term involving [47mpat[0m
  and containing no variables outside of the occurrences of [47mpat[0m, and
  each [47mvari[0m is one of the variables of [47mpat[0m.  Generally speaking, the
  [47mtype-restriction[0m terms ought to be terms that inform us as to the
  type of [47mpat[0m.  Ideally, they should be ``primitive recognizing
  expressions'' about [47mpat[0m; see [compound-recognizer].  We describe
  preprocessing at the end of this topic.

  If the [47m:typed-term[0m is not provided in the rule class object, it is
  computed heuristically by looking for a term in the conclusion
  whose type is being restricted.  An error is caused if no such term
  is found.

  Roughly speaking, the effect of adding such a rule is to inform the
  ACL2 typing mechanism that [47mpat[0m has the type described by the
  conclusion, when the hypotheses are true.  In particular, the type
  of [47mpat[0m is within the union of the types described by the several
  disjuncts.  The ``type described by'' [47m(equal pat vari)[0m is the type
  of [47mvari[0m.

  More operationally, when asked to determine the type of a term that
  is an instance of [47mpat[0m, ACL2 will first attempt to establish the
  hypotheses.  [31;1mThis is done by type reasoning alone, not rewriting![0m
  However, if some hypothesis is a call of [47m[force][0m, then forcing may
  occur, which may ultimately invoke the rewriter; see [force] and
  see [case-split].  So-called free variables in hypotheses are
  treated specially; see [free-variables].  Provided the hypotheses
  are established by type reasoning, ACL2 then unions the types
  described by the [47mtype-restrictioni-on-pat[0m terms together with the
  types of those subexpressions of [47mpat[0m identified by the [47mvari[0m.  The
  final type computed for a term is the intersection of the types
  implied by each applicable rule.  Type prescription rules may be
  disabled.

  You can limit the recursive establishment of hypotheses of rules; see
  [set-backchain-limit].

  Because only type reasoning is used to establish the hypotheses of
  [47m:type-prescription[0m rules, some care must be taken with the
  hypotheses.  Suppose, for example, that the non-recursive function
  [47mmy-statep[0m is defined as

    (defun my-statep (x)
      (and (true-listp x)
           (equal (len x) 2)))

  and suppose [47m(my-statep s)[0m occurs as a hypothesis of a
  [47m:type-prescription[0m rule that is being considered for use in the
  proof attempt for a conjecture with the hypothesis [47m(my-statep s)[0m.
  Since the hypothesis in the conjecture is rewritten, it will become
  the conjunction of [47m(true-listp s)[0m and [47m(equal (len s) 2)[0m.  Those two
  terms will be assumed to have type [47mt[0m in the context in which the
  [47m:type-prescription[0m rule is tried.  But type reasoning will be
  unable to deduce that [47m(my-statep s)[0m has type [47mt[0m in this context.
  Thus, either [47mmy-statep[0m should be disabled (see [disable]) during
  the proof attempt or else the occurrence of [47m(my-statep s)[0m in the
  [47m:type-prescription[0m rule should be replaced by the conjunction into
  which it rewrites.

  While this example makes it clear how non-recursive predicates can
  cause problems, non-recursive functions in general can cause
  problems.  For example, if [47m(mitigate x)[0m is defined to be [47m(if
  (rationalp x) (1- x) x)[0m then the hypothesis [47m(pred (mitigate s))[0m in
  the conjecture will rewrite, opening [47mmitigate[0m and splitting the
  conjecture into two subgoals, one in which [47m(rationalp s)[0m and [47m(pred
  (1- x))[0m are assumed and the other in which [47m(not (rationalp s))[0m and
  [47m(pred x)[0m are assumed.  But [47m(pred (mitigate s))[0m will not be typed as
  [47mt[0m in either of these contexts.  The moral is: beware of
  non-recursive functions occurring in the hypotheses of
  [47m:type-prescription[0m rules.

  Because of the freedom one has in forming the conclusion of a
  type-prescription, we have to use heuristics to recover the
  pattern, [47mpat[0m, whose type is being specified.  In some cases our
  heuristics may not identify the intended term and the
  [47m:type-prescription[0m rule will be rejected as illegal because the
  conclusion is not of the correct form.  When this happens you may
  wish to specify the [47mpat[0m directly.  This may be done by using a
  suitable rule class token.  In particular, when the token
  [47m:type-prescription[0m is used it means ACL2 is to compute pat with its
  heuristics; otherwise the token should be of the form
  [47m(:type-prescription :typed-term pat)[0m, where [47mpat[0m is the term whose
  type is being specified.

  The defun event may generate a [47m:type-prescription[0m rule.  Suppose [47mfn[0m
  is the name of the function concerned.  Then [47m(:type-prescription
  fn)[0m is the rune given to the type-prescription, if any, generated
  for [47mfn[0m by [47m[defun][0m.  (The trivial rule, saying [47mfn[0m has unknown type,
  is not stored, but [47m[defun][0m still allocates the rune and the
  corollary of this rune is known to be [47mt[0m.)

  We close with a discussion of how, before a term is parsed into a
  [47m:type-prescription[0m rule, it is preprocessed.  We describe this
  preprocessing in some detail below, but first consider the
  following (contrived) example.

    (defthm append-tp-example
      (let ((result (append x y)))
        (implies (nat-listp x)
                 (implies (let ((second-hyp (integer-listp y)))
                            second-hyp)
                          (true-listp result))))
      :rule-classes :type-prescription)

  This theorem is parsed into a type-prescription rule with the
  following hypotheses and conclusion.

    (nat-listp x) ; first hypothesis
    ((lambda (second-hyp) second-hyp) (integer-listp y)) ; second hypothesis
    (true-listp (binary-append x y)) ; conclusion

  Notice that the top-level [47m[let][0m was expanded, i.e., [47m(append x y)[0m was
  substituted for [47mresult[0m --- more accurately, [47m(binary-append x y)[0m was
  substituted for [47mresult[0m, since [47m[append][0m is a macro that abbreviates
  [47m[binary-append][0m.  Also notice that the two hypotheses were
  ``flattened'' in the sense that they were gathered up into a list.
  Finally, notice that the [47m[let][0m in the second hypothesis was not
  expanded (it was merely translated to internal form, using [47mLAMBDA[0m).
  If you actually submit the theorem above, you will get warnings,
  which you may choose to ignore; the application of
  [47mtype-prescription[0m rules is somewhat subtle, so if you use them then
  you may wish to experiment to see which forms work best for you.

  Here is the detail promised above, for parsing a term into a
  [47m:type-prescription[0m rule.  There are two steps.  (1) ACL2 first
  translates the term, expanding all macros (see [trans]) and also
  removing [guard-holders].  (2) Then the translated term is
  traversed top-down, expanding away [47mlambda[0ms ([47m[let][0m, [47m[let*][0m, and
  [47m[mv-let][0m expressions) and flattening the [47m[implies][0m structure, until
  the conclusion is exposed; then the conclusion's [47mlambda[0ms are also
  expanded away.  The simplest way to understand (2) may be to look
  at the definition of ACL2 source function [47munprettyify-tp[0m, which
  implements Step (2), say by evaluating [47m:[0m[47m[pe][0m[47m unprettyify-tp[0m.


Subtopics

  [Backchain-limit]
      Limiting the effort expended on relieving hypotheses

  [Case-split]
      Like force but immediately splits the top-level goal on the
      hypothesis

  [Force]
      Identity function used to force a hypothesis

  [Type-prescription-debugging]
      Improve a built-in [type-prescription] rule")
 (TYPE-PRESCRIPTION-DEBUGGING
  (DEBUGGING TYPE-PRESCRIPTION)
  "Improve a built-in [type-prescription] rule

  A [type-prescription] rule is introduced automatically when a
  function is defined (see [defun]).  However, that rule might not be
  what you expect.  In this topic we explore how you might be able to
  improve that rule, by way of an example.

  First consider the following definition.

    ACL2 !>(defun f (x) (alistp x))

    Since F is non-recursive, its admission is trivial.  We observe that
    the type of F is described by the theorem
    (OR (EQUAL (F X) T) (EQUAL (F X) NIL)).  We used the :type-prescription
    rule ALISTP.

    Summary
    Form:  ( DEFUN F ...)
    Rules: ((:TYPE-PRESCRIPTION ALISTP))
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.00)
     F
    ACL2 !>

  Notice in particular the phrase, ``We used the :type-prescription
  rule ALISTP,'' and the corresponding [rune] [47m(:TYPE-PRESCRIPTION
  ALISTP)[0m in the list of rules printed in the [summary].  These are
  telling us that ACL2 used the indicated rule during the process of
  computing a [type-prescription] rule for [47mf[0m.

  Now suppose that in a different session we instead proceed as
  follows.

    ACL2 !>(in-theory (disable (:type-prescription alistp)))

    Summary
    Form:  ( IN-THEORY (DISABLE ...))
    Rules: NIL
    Time:  0.01 seconds (prove: 0.00, print: 0.00, other: 0.01)
     (:NUMBER-OF-ENABLED-RUNES 3298)
    ACL2 !>(defun f (x) (alistp x))

    Since F is non-recursive, its admission is trivial.  We could deduce
    no constraints on the type of F.

    Summary
    Form:  ( DEFUN F ...)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     F
    ACL2 !>

  Notice that this time ``We could deduce no constraints on the type of
  F,'' because in this context, [type-set] reasoning does not see
  that the body of [47mf[0m is a Boolean, because [47m(:type-prescription
  alistp)[0m has been [disable]d.  Thus, the ``Rules'' field of the
  summary is empty this time.

  Consider the following story.  On Monday, you run the first session,
  and a subsequent proof uses [type-set] reasoning to conclude that
  [47m(f x)[0m is Boolean, even after you [disable] the [definition] of [47mf[0m.
  Then on Tuesday, you run the second session, and are surprised to
  find that ACL2 no longer reasons (during that same subsequent proof
  attempt) that [47m(f x)[0m is Boolean.  You want to debug this problem, so
  you look back in the log where you defined [47mf[0m, and you see the
  ``deduce no constraints'' message --- but then you look further
  back, at Monday's log, where you find the definition of [47mf[0m ``used
  the :type-prescription rule ALISTP'' to conclude that ``the type of
  F is described by the theorem (OR (EQUAL (F X) T) (EQUAL (F X)
  NIL))''.  The mention of ALISTP in that definition's output from
  Monday, together with the corresponding mention of
  [47m(:TYPE-PRESCRIPTION ALISTP)[0m in the ``Rules'' field of the summary,
  leads you to resolve the issue as follows.  On Monday, when
  [47m(:TYPE-PRESCRIPTION ALISTP)[0m was [enable]d, ACL2 used type-set
  reasoning to conclude that the body of [47mf[0m is Boolean, but on
  Tuesday, [47m(:TYPE-PRESCRIPTION ALISTP)[0m was disabled at that point and
  hence the body of [47mf[0m was not known to be Boolean by type-set
  reasoning.  Hence on Tuesday, no Boolean type-prescription rule was
  stored for [47mf[0m at definition time, which is why the subsequent proof
  attempt failed to use such a rule.  So you avoid disabling
  [47m(:TYPE-PRESCRIPTION ALISTP)[0m until after submitting the [47m[defun][0m for
  [47mf[0m, and now ACL2's type reasoning (see [TYPE-REASONING]) knows that
  [47mf[0m returns a Boolean.")
 (TYPE-REASONING
  (RULE-CLASSES)
  "ACL2 reasoning with ``types''

  ACL2 has a ``type reasoning'' system, which may be viewed as a
  relatively basic rule-based theorem prover for questions about
  Common Lisp types, e.g., ``does this expression produce a
  [47m[consp][0m?'', ``does this expression produce some kind of ACL2
  number, e.g., an [47m[integerp][0m, a [47m[rationalp][0m, or a
  [47m[complex-rationalp][0m?'', ``does this expression produce a non-[47mnil[0m
  value (i.e., is it true)?'', etc.  This system uses built-in
  reasoning about types, for example that a rational number is not a
  cons; when the ACL2 prover reports that a goal is simplified using
  ``primitive type reasoning'', it is referring to such built-in type
  reasoning.  However, type reasoning is also driven by
  [type-prescription] rules, as we'll discuss shortly.

  ACL2 reasoning, including type reasoning, takes place with respect to
  a context that associates terms with values that represent their
  ``types''.  These contexts are called [type-alist]s, and those
  values are called [type-set]s; however, unless you write certain
  sophisticated tools, perhaps such as [clause-processor]s, you
  probably do not need to know more than that about these two
  notions.  (If you're curious about them, you can see [type-set] and
  see [type-alist].)  For example, when ACL2 attempts to prove a
  conjecture [47m(implies (and (p x) (integerp (f x))) (p2 x))[0m, it builds
  a type-alist recording that [47m(p x)[0m and [47m(integerp (f x))[0m are true
  when attempting to reason about [47m(p2 x)[0m.  That type-alist associates
  [47m(p x)[0m with a value representing the complement of the set, [47m{nil}[0m,
  meaning that [47m(p x)[0m is non-[47mnil[0m, i.e., true.  But for [47m(integerp (f
  x))[0m something a bit more clever takes place: since [47mintegerp[0m
  recognizes a Boolean combination of built-in types --- see
  [compound-recognizer] --- the context associates [47m(f x)[0m with a value
  representing the set of integers.  So for example, type reasoning
  can conclude from that type-alist that [47m(not (consp (f x)))[0m is true,
  since the built-in types for integer and cons are disjoint.

  As noted above, type reasoning can take advantage of
  [type-prescription] rules.  In short, such a rule tells ACL2 that
  any instance of the ``typed-term'' of the rule must have a
  specified type.  To relieve the hypotheses of type-prescription
  rules, the type-reasoning system recursively invokes itself.  This
  can be done for any hypothesis, whether it is ``type-like'' or not,
  since any proposition, [47mp[0m, can be phrased as the type-like question
  ``does [47mp[0m produce an object of type [47mnil[0m?'' However, as you might
  expect, the type system is not very good at establishing hypotheses
  that are not type-like, unless they are represented rather
  explicitly in the context in which the question is posed.  Consider
  the following example from the [type-prescription] documentation.

    (defthm characterp-nth-type-prescription   ; (Nth n lst) is of type character
      (implies                                 ; provided the hypotheses can be
       (and (character-listp lst)              ; established by type reasoning.
            (<= 0 n)
            (< n (len lst)))
       (characterp (nth n lst)))
      :rule-classes :type-prescription)

  It may seem impossible to relieve the hypothesis [47m(character-listp
  lst)[0m by type reasoning, since there is no suitable ``type'' for
  [47mlst[0m, i.e., [47mcharacter-listp[0m does not recognize a Boolean combination
  of ACL2 types (see [compound-recognizer]).  However, suppose we are
  attempting to prove a theorem of the form [47m(implies (and
  (character-listp x) p) q)[0m and ACL2 is in the process of simplifying
  either [47mp[0m or [47mq[0m.  In that case, the context --- that is, the
  type-alist --- will associate the term [47m(character-listp x)[0m with a
  value indicating that this term is true, i.e., non-[47mnil[0m.  Then if
  ACL2 encounters the term [47m(nth k x)[0m, it will try to apply the
  type-prescription rule above, matching [47mk[0m to [47mn[0m and matching [47mlst[0m to
  [47mx[0m.  The instantiated first hypothesis of that rule will then be
  [47m(character-listp x)[0m.  Since the type-alist designates
  [47m(character-listp x)[0m as true, that hypothesis is successfully
  relieved.  Again, there was no [47mcharacter-listp[0m ``type'' involved;
  what was typed was the entire term, [47m(character-listp x)[0m.

  The instantiated hypothesis above was relieved because it was in the
  context, so no rewriting was necessary to establish it.  See
  [force] for how to involve the ACL2 rewriter to establish
  hypotheses of type-prescription rules.


Subtopics

  [Set-dwp]
      Affect the effort made in [type-reasoning]

  [Set-dwp!]
      Affect the effort made in [type-reasoning], non-[47m[local][0mly")
 (TYPE-SET
  (MISCELLANEOUS)
  "How type information is encoded in ACL2

  See [type-reasoning] for basic background on type reasoning in ACL2.

  To help you experiment with type-sets we briefly note the following
  utility functions.

  [47m(type-set-quote x)[0m will return the type-set of the object [47mx[0m.  For
  example, [47m(type-set-quote \"test\")[0m is [47m2048[0m and [47m(type-set-quote '(a b
  c))[0m is [47m512[0m.

  [47m(type-set 'term nil nil nil (ens state) (w state) nil nil nil)[0m will
  return the type-set of [47mterm[0m with respect to the current world and
  the top-level enabled structure.  For example,

    (type-set '(integerp x) nil nil nil (ens state) (w state) nil nil nil)

  will return (mv 192 nil).  192, otherwise known as [47m*ts-boolean*[0m, is
  the type-set containing [47mt[0m and [47mnil[0m.  The second result may be
  ignored in these experiments.  [47mTerm[0m must be in the [47mtranslated[0m,
  internal form shown by [47m:[0m[47m[trans][0m.  See [trans] and see [term].

  [47m(type-set-implied-by-term 'x nil 'term (ens state)(w state) nil)[0m will
  return the type-set deduced for the variable symbol [47mx[0m assuming the
  [47mtranslated[0m term, [47mterm[0m, true.  The second result may be ignored in
  these experiments.  For example,

    (type-set-implied-by-term 'v nil '(integerp v)
                              (ens state) (w state) nil)

  returns [47m11[0m.

  [47m(convert-type-set-to-term 'x ts (ens state) (w state) nil)[0m will
  return a term whose truth is equivalent to the assertion that the
  term [47mx[0m has type-set [47mts[0m.  The second result may be ignored in these
  experiments.  For example

    (convert-type-set-to-term 'v 523 (ens state) (w state) nil)

  returns a term expressing the claim that [47mv[0m is either an integer or a
  non-[47mnil[0m true-list.  [47m523[0m is the [47mlogical-or[0m of [47m11[0m (which denotes the
  integers) with [47m512[0m (which denotes the non-[47mnil[0m true-lists).

  The ``actual primitive types'' of ACL2 are listed in
  [47m*actual-primitive-types*[0m, whose elements are shown below.  Each
  actual primitive type denotes a set --- sometimes finite and
  sometimes not --- of ACL2 objects and these sets are pairwise
  disjoint.  For example, [47m*ts-zero*[0m denotes the set containing 0
  while [47m*ts-negative-integer*[0m denotes the set containing all of the
  negative integers.

    *TS-ZERO*                  ;;; {0}
    *TS-ONE*                   ;;; {1}
    *TS-INTEGER>1*             ;;; integers greater than 1
    *TS-POSITIVE-RATIO*        ;;; positive non-integer rationals
    *TS-NEGATIVE-INTEGER*      ;;; negative integers
    *TS-NEGATIVE-RATIO*        ;;; negative non-integer rationals
    *TS-COMPLEX-RATIONAL*      ;;; complex rationals
    *TS-NIL*                   ;;; {nil}
    *TS-T*                     ;;; {t}
    *TS-NON-T-NON-NIL-SYMBOL*  ;;; symbols other than nil, t
    *TS-PROPER-CONS*           ;;; nil-terminated non-empty lists
    *TS-IMPROPER-CONS*         ;;; conses that are not proper
    *TS-STRING*                ;;; strings
    *TS-CHARACTER*             ;;; characters

  The actual primitive types were chosen by us to make theorem proving
  convenient.  Thus, for example, the actual primitive type [47m*ts-nil*[0m
  contains just [47mnil[0m so that we can encode the hypothesis ``[47mx[0m is [47mnil[0m''
  by saying ``[47mx[0m has type [47m*ts-nil*[0m'' and the hypothesis ``[47mx[0m is
  non-[47mnil[0m'' by saying ``[47mx[0m has type complement of [47m*ts-nil*[0m.'' We
  similarly devote a primitive type to [47mt[0m, [47m*ts-t*[0m, and to a third
  type, [47m*ts-non-t-non-nil-symbol*[0m, to contain all the other ACL2
  symbols.

  Let [47m*ts-other*[0m denote the set of all Common Lisp objects other than
  those in the actual primitive types.  Thus, [47m*ts-other*[0m includes
  such things as floating point numbers and CLTL array objects.  The
  actual primitive types together with [47m*ts-other*[0m constitute what we
  call [47m*universe*[0m.  Note that [47m*universe*[0m is a finite set containing
  one more object than there are actual primitive types; that is,
  here we are using [47m*universe*[0m to mean the finite set of primitive
  types, not the infinite set of all objects in all of those
  primitive types.  [47m*Universe*[0m is a partitioning of the set of all
  Common Lisp objects: every object belongs to exactly one of the
  sets in [47m*universe*[0m.

  Abstractly, a ``type-set'' is a subset of [47m*universe*[0m.  To say that a
  term, [47mx[0m, ``has type-set [47mts[0m'' means that under all possible
  assignments to the variables in [47mx[0m, the value of [47mx[0m is a member of
  some member of [47mts[0m.  Thus, [47m(cons x y)[0m has type-set [47m{*ts-proper-cons*
  *ts-improper-cons*}[0m.  A term can have more than one type-set.  For
  example, [47m(cons x y)[0m also has the type-set [47m{*ts-proper-cons*
  *ts-improper-cons* *ts-nil*}[0m.  Extraneous types can be added to a
  type-set without invalidating the claim that a term ``has'' that
  type-set.  Generally we are interested in the smallest type-set a
  term has, but because the entire theorem-proving problem for ACL2
  can be encoded as a type-set question, namely, ``Does [47mp[0m have
  type-set complement of [47m*ts-nil*[0m?,'' finding the smallest type-set
  for a term is an undecidable problem.  When we speak informally of
  ``the'' type-set we generally mean ``the type-set found by our
  heuristics'' or ``the type-set assumed in the current context.''

  Note that if a type-set, [47mts[0m, does not contain [47m*ts-other*[0m as an
  element then it is just a subset of the actual primitive types.  If
  it does contain [47m*ts-other*[0m it can be obtained by subtracting from
  [47m*universe*[0m the complement of [47mts[0m.  Thus, every type-set can be
  written as a (possibly complemented) subset of the actual primitive
  types.

  By assigning a unique bit position to each actual primitive type we
  can encode every subset, [47ms[0m, of the actual primitive types by the
  nonnegative integer whose ith bit is on precisely if [47ms[0m contains the
  ith actual primitive type.  The type-sets written as the complement
  of [47ms[0m are encoded as the two's-complement bitwise [47m`not'[0m of the
  encoding of [47ms[0m.  Those type-sets are thus negative integers.  The
  bit positions assigned to the actual primitive types are enumerated
  from [47m0[0m in the same order as the types are listed in
  [47m*actual-primitive-types*[0m.  At the concrete level, a type-set is an
  integer between [47m*min-type-set*[0m and [47m*max-type-set*[0m, inclusive.

  For example, [47m*ts-nil*[0m has bit position [47m7[0m.  The type-set containing
  just [47m*ts-nil*[0m is thus represented by [47m128[0m.  If a term has type-set
  [47m128[0m then the term is always equal to [47mnil[0m.  The type-set containing
  everything but [47m*ts-nil*[0m is the bitwise [47m`not'[0m of [47m128[0m, which is [47m-129[0m.
  If a term has type-set [47m-129[0m, it is never equal to [47mnil[0m.  By
  ``always'' and ``never'' we mean under all, or under no,
  assignments to the variables, respectively.

  Here is a more complicated example.  Let [47ms[0m be the type-set containing
  all of the symbols and the natural numbers.  The relevant actual
  primitive types, their bit positions and their encodings are:

    actual primitive type       bit    value

    *ts-zero*                    0       1
    *ts-one*                     1       2
    *ts-integer>1*               2       4
    *ts-nil*                     7     128
    *ts-t*                       8     256
    *ts-non-t-non-nil-symbol*    9     512

  Thus, the type-set [47ms[0m is represented by [47m(+ 1 2 4 128 256 512)[0m = [47m903[0m.
  The complement of [47ms[0m, i.e., the set of all objects other than the
  natural numbers and the symbols, is [47m-904[0m.  We can get ACL2 to
  provide such information as follows.

    ACL2 !>(decode-type-set 903)
    (TS-UNION *TS-SYMBOL* *TS-NON-NEGATIVE-INTEGER*)
    ACL2 !>(decode-type-set -904)
    (TS-COMPLEMENT (TS-UNION *TS-SYMBOL* *TS-NON-NEGATIVE-INTEGER*))
    ACL2 !>


Subtopics

  [Type-alist]
      An ACL2 representation of contextual knowledge")
 (TYPE-SET-INVERTER
  (RULE-CLASSES)
  "Exhibit a new decoding for an ACL2 type-set

  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.
  Also see [type-reasoning] for basic background on type reasoning in
  ACL2.

    Example Rule Class:
    (:type-set-inverter
      :corollary (equal (and (counting-number x) (not (equal x 0)))
                        (and (integerp x) (< 0 x)))
      :type-set 2)

    General Forms of Rule Class:
    :type-set-inverter, or
    (:type-set-inverter :type-set n)

    General Form of Theorem or Corollary:
    (EQUAL new-expr old-expr)

  where [47mn[0m is a [47m[type-set][0m (see [type-set]) and [47mold-expr[0m is the term
  containing [47mx[0m as a free variable that ACL2 currently uses to
  recognize [47m[type-set][0m [47mn[0m.  For a given [47mn[0m, the exact form of [47mold-expr[0m
  is generated by

    (convert-type-set-to-term 'x n (ens state) (w state) nil)].

  If the [47m:[0m[47m[type-set][0m field of the rule-class is omitted, we attempt to
  compute it from the right-hand side, [47mold-expr[0m, of the corollary.
  That computation is done by [47mtype-set-implied-by-term[0m (see
  [type-set]).  However, it is possible that the type-set we compute
  from [47mlhs[0m does not have the required property that when inverted
  with [47mconvert-type-set-to-term[0m the result is [47mlhs[0m.  If you omit
  [47m:[0m[47m[type-set][0m and an error is caused because [47mlhs[0m has the incorrect
  form, you should manually specify both [47m:[0m[47m[type-set][0m and the [47mlhs[0m
  generated by [47mconvert-type-set-to-term[0m.

  The rule generated will henceforth make [47mnew-expr[0m be the term used by
  ACL2 to recognize type-set [47mn[0m.  If this rule is created by a
  [47m[defthm][0m event named [47mname[0m then the rune of the rule is
  [47m(:type-set-inverter name)[0m and by disabling that rune you can
  prevent its being used to decode type-sets.

  Type-sets are inverted when forced assumptions are turned into
  formulas to be proved.  In their internal form, assumptions are
  essentially pairs consisting of a context and a goal term, which
  was forced.  Abstractly a context is just a list of hypotheses
  which may be assumed while proving the goal term.  But actually
  contexts are alists which pair terms with type-sets, encoding the
  current hypotheses.  For example, if the original conjecture
  contained the hypothesis [47m(integerp x)[0m then the context used while
  working on that conjecture will include the assignment to [47mx[0m of the
  type-set [47m*ts-integer*[0m.")
 (TYPE-SPEC
  (DECLARE THE)
  "Type specifiers can be used in Common Lisp type declarations and
  [the] forms, and may result in improved efficiency of execution.

  ACL2 permits the use of type declarations in certain contexts; see
  [declare] for background.  Here is an example of a type
  declaration; here the symbol, [47minteger[0m, is what we refer to as a
  ``type-spec'':

    (let ((x (+ a b)))
      (declare (type integer x))   ;; <-- type declaration
      (+ 1 x))

  A Common Lisp compiler might be able to use the above declaration to
  improve the execution efficiency of the resulting code.  In
  particular, the Common Lisp [+] operation is rather elaborate: it
  must be capable of adding together integers, rationals, floats,
  etc.  When we tell the compiler that this [47mx[0m is surely an integer,
  it may be able to use a more efficient version of [47m(+ 1 x)[0m that only
  deals with the integer case.

  Type declarations can be added to functions, [47m[let][0m bindings, and
  other places as described in [declare], and interact with the
  ACL2's [guard] mechanism.  For instance, during guard verification,
  the above type declaration will result in a guard obligation: we
  will need to prove that [47m(+ a b)[0m is always an integer.  Type
  declarations about the formals of a function generally become part
  of the guard of the function, but see also [split-types] for a way
  to gain more control over this.

  Whether or not a particular type declaration will actually improve
  the efficiency of your functions depends on the Lisp compiler.  For
  instance, many Lisp compilers will not benefit much from a plain
  [47minteger[0m declaration.  If you are trying to optimize code by adding
  type declarations, it may be useful to use [disassemble$] to
  inspect the impact that your declarations have on the resulting
  code.

  While type specs may be used in [defstobj] events, the [47mHASH-TABLE[0m and
  [47mSTOBJ-TABLE[0m type specs may only be used in those events.  We say
  nothing further about them in the present topic.


Type Specs

  The syntax that Common Lisp compilers use for these type
  declarations---e.g., the symbol [47minteger[0m above---is different than
  the usual syntax of ACL2.

  We use the name [31;1mtype-spec[0m to refer to the supported types that can be
  mentioned in declarations.  For instance:

    Declaration	|  Type-Spec	|
    [47m(type string x y z)[0m	|  [47mstring[0m	|
    [47m(type (integer 0 7) x)[0m	|  [47m(integer 0 7)[0m	|
    [47m(type rational x)[0m	|  [47mrational[0m	|
    [47m(type (rational 1 *) x)[0m	|  [47m(rational 1 *)[0m	|

  The supported type-specs and their meanings (when applied to the
  variable [47mx[0m as in [47m(declare (type type-spec x))[0m are given below.

    type-spec              meaning
    ----------------------------------------------------------------------
    (AND type1 ... typek)  (AND (p1 X) ... (pk X))
                           where (pj x) is the meaning for type-spec typej
    ATOM                   (ATOM X)
    BIT                    (OR (EQUAL X 1) (EQUAL X 0))
    CHARACTER              (CHARACTERP X)
    COMPLEX                (AND (COMPLEX-RATIONALP X)
                                (RATIONALP (REALPART X))
                                (RATIONALP (IMAGPART X)))
    (COMPLEX RATIONAL)     same as COMPLEX, above
    (COMPLEX type)         (AND (COMPLEX-RATIONALP X)
                                (p (REALPART X))
                                (p (IMAGPART X)))
                           where (p x) is the meaning for type-spec type
    CONS                   (CONSP X)
    DOUBLE-FLOAT           (DFP X) ; See :DOC df.
    INTEGER                (INTEGERP X)
    (INTEGER i j)          (AND (INTEGERP X)   ; See notes below.
                                (<= i X)
                                (<= X j))
    (MEMBER x1 ... xn)     (MEMBER X '(x1 ... xn))
    (MOD i)                same as (INTEGER 0 i-1)
    NIL                    NIL
    (NOT type)             (NOT (p X))
                           where (p x) is the meaning for type-spec type
    NULL                   (EQ X NIL)
    NUMBER                 (ACL2-NUMBERP x)
    (OR type1 ... typek)   (OR (p1 X) ... (pk X))
                           where (pj x) is the meaning for type-spec typej
    RATIO                  (AND (RATIONALP X) (NOT (INTEGERP X)))
    RATIONAL               (RATIONALP X)
    (RATIONAL i j)         (AND (RATIONALP X)  ; See notes below.
                                (<= i X)
                                (<= X j))
    REAL                   (RATIONALP X)       ; (REALP X) in ACL2(r)
    (REAL i j)             (AND (RATIONALP X)  ; See notes below.
                                (<= i X)
                                (<= X j))
    (SATISFIES pred)       (pred X) ; Lisp requires a unary function, not a macro
    SIGNED-BYTE            (INTEGERP X)
    (SIGNED-BYTE i)        same as (INTEGER k m) where k=-2^(i-1), m=2^(i-1)-1
    STANDARD-CHAR          (STANDARD-CHARP X)
    STRING                 (STRINGP X)
    (STRING max)           (AND (STRINGP X) (EQUAL (LENGTH X) max))
    SYMBOL                 (SYMBOLP X)
    T                      T
    UNSIGNED-BYTE          same as (INTEGER 0 *)
    (UNSIGNED-BYTE i)      same as (INTEGER 0 (2^i)-1)
    ----------------------------------------------------------------------

  Notes

  In general, [47m(integer i j)[0m means

    (AND (INTEGERP X)
         (<= i X)
         (<= X j)).

  But if [47mi[0m is the symbol [47m*[0m, the first inequality is omitted.  If [47mj[0m is
  the symbol [47m*[0m, the second inequality is omitted.  If instead of
  being an integer, the second element of the type specification is a
  list containing an integer, [47m(i)[0m, then the first inequality is made
  strict.  An analogous remark holds for the [47m(j)[0m case.  The [47mrational[0m
  and [47mreal[0m type specifiers are similarly generalized.

  Common Lisp supports a richer set of type specifiers than ACL2
  supports.")
 (TYPESPEC-CHECK (POINTERS)
                 "See [meta-extract].")
 (U
  (HISTORY UNDO)
  "Undo last [command], without a query

  See [undo] for an introduction to undoing commands.

    Example:
    :u

  The keyword [command] [47m:u[0m is the same as [47m:[0m[47m[ubt!][0m [47m:x[0m.  [47m:[0m[47m[Oops][0m will
  undo the last [47m:u[0m.  See [ubt!].")
 (UBT
  (HISTORY UNDO)
  "Undo the [command]s back through a [command] descriptor

  See [undo] for an introduction to undoing commands.

    Examples:
    :ubt :max      ; undo back through the most recent command
                   ; (which just means undo the most recent command)
    :ubt :x        ; same as :ubt :max
    :u             ; same as :ubt :max with no questions asked
    :ubt fn        ; undo back through the introduction of fn
                   ; (including all the other events in fn's block)
    :ubt 5         ; undo back through the fifth command executed
    :ubt (:max -4) ; undo back through the most recent five commands
    :ubt (:x -4)   ; undo back through the most recent five commands

  See [command-descriptor].

  [47mUbt[0m takes one argument, a [command] descriptor, and undoes the
  [command]s from [47m:[0m[47m[max][0m (aka [47m:x[0m) through the one described.  See
  [command-descriptor].  [47m[Pbt][0m will print the [command]s that [47mubt[0m
  will undo.  [47m:[0m[47m[Oops][0m will undo the undo.  See [oops].

  [47mUbt[0m can cause errors but not queries.  To get queries as well, see
  [ubt?].  To get neither errors nor queries, see [ubt!]..

  It is important to remember that a [command] may create several
  [events].  That is, the [command] that introduces [47mfn1[0m may also
  introduce [47mfn2[0m.  Undoing the [command] that created either of these
  will undo them both.  The [events] created by a [command]
  constitute the [command]'s ``block'' and we can only undo entire
  blocks.  Use [47m[pcb][0m to print the [command] block of a [command] if
  you wish to see what will be lost by undoing the [command].

  [47mUbt[0m will not undo into ``prehistory''.  [47m:Ubt 1[0m will undo all of your
  [command]s.  But [47m:ubt -5[0m will cause an error, warning you that [47m:ubt[0m
  cannot undo system initialization.

  See [u] for how to undo just the latest command.  See [ubu], [ubu!],
  and [ubu?] for how to undo back up to, but not including, the
  current command.")
 (UBT!
  (HISTORY UNDO)
  "Undo [command]s, without a query or an error

  See [undo] for an introduction to undoing commands.

    Example:
    :ubt! :x-4

  The keyword [command] [47m:ubt![0m is the same as [47m:[0m[47m[ubt][0m, but with a
  guarantee that it is ``error-free.'' More precisely, the value
  returned by [47m:ubt![0m will always be of the form [47m(mv nil val state)[0m.
  Note that [47m:ubt![0m will not print error messages.

  [47m:[0m[47m[Oops][0m will undo the last [47m:ubt![0m.  See [ubt], [ubt?], [ubu!], [ubu],
  [ubu?], and [u].")
 (UBT-PREHISTORY
  (HISTORY UNDO)
  "Undo the [command]s back through the last [47m[reset-prehistory][0m event

  See [undo] for an introduction to undoing commands.

  This command is only used to eliminate a [47m[reset-prehistory][0m event.
  If your most recent [47mreset-prehistory[0m event does not have a flag
  argument of [47mt[0m, then [47m:ubt-prehistory[0m undoes all command back
  through, and including, that [47mreset-prehistory[0m event.")
 (UBT?
  (HISTORY UNDO)
  "Undo [command]s, with queries as appropriate

  See [undo] for an introduction to undoing commands.

    Example:
    :ubt? :x-4

  The keyword [command] [47m:ubt?[0m is the same as [47m:[0m[47m[ubt][0m, but with
  appropriate queries made.  [47m:[0m[47m[Oops][0m will undo the last [47m:ubt?[0m.  See
  [ubt!], [ubt], [ubu!], [ubu], [ubu?], and [u].")
 (UBU
  (HISTORY UNDO)
  "Undo the [command]s back up to (not including) a [command] descriptor

  See [undo] for an introduction to undoing commands.

    Examples:
    :ubu :x-3      ; undo the last three commands (same as :ubt :x-2)
    :ubu (:x -3)   ; same as above
    :ubu fn        ; undo back up to, but not including the introduction of fn
                   ; (so fn will continue to be defined)
    :ubu 5         ; undo back up to, but not including, the fifth command
                   ; executed (leaving the first five commands in place)

  See [command-descriptor].

  [47mUbu[0m takes one argument, a [command] descriptor, and undoes the
  [command]s from [47m:[0m[47m[max][0m (aka [47m:x[0m) up to, but not including, the
  indicated command.  See [command-descriptor].

  [47mUbu[0m can cause errors.  To avoid these, see [ubu!].

  For appropriate queries to be made, see [ubu?].

  Also see [ubt], which is similar but also undoes the indicated
  command.  As for [47m:[0m[47m[ubt][0m, [47m:[0m[47m[oops][0m will undo the undo (see [oops])
  and [47m[ubu][0m will not undo into ``prehistory''.

  See [u] for how to undo just the latest command, and see [ubt],
  [ubt!], and [ubt?] for how to undo back through (that is,
  including) the current command.")
 (UBU!
  (HISTORY UNDO)
  "Undo [command]s, without a query or an error

  See [undo] for an introduction to undoing commands.

    Example:
    :ubu! :x-4

  The keyword [command] [47m:ubu![0m is the same as [47m:[0m[47m[ubu][0m, but with a
  guarantee that it is ``error-free.'' More precisely, the
  [error-triple] returned by [47m:ubu![0m will always be of the form [47m(mv nil
  val state)[0m. Note that [47m:ubu![0m will not print error messages.

  [47m:[0m[47m[Oops][0m will undo the last [47m:ubu![0m.  Also see [ubu], [ubu?], [ubt],
  [ubt!], [ubt?], and [u].")
 (UBU?
  (HISTORY UNDO)
  "Undo [command]s, with queries as appropriate

  See [undo] for an introduction to undoing commands.

    Example:
    :ubu? :x-4

  The keyword [command] [47m:ubu?[0m is the same as [47m:[0m[47m[ubu][0m, but with
  appropriate queries made.  [47m:[0m[47m[Oops][0m will undo the last [47m:ubu?[0m.  Also
  see [ubu!], [ubu], [ubt!], [ubt], [ubt?], and [u].")
 (UNARY--
  (NUMBERS ACL2-BUILT-INS)
  "Arithmetic negation function

  Completion Axiom ([47mcompletion-of-unary-minus[0m):

    (equal (unary-- x)
           (if (acl2-numberp x)
               (unary-- x)
             0))

  [Guard] for [47m(unary-- x)[0m:

    (acl2-numberp x)

  Notice that like all arithmetic functions, [47munary--[0m treats non-numeric
  inputs as [47m0[0m.

  Calls of the macro [47m[-][0m on one argument expand to calls of [47munary--[0m;
  see [-].")
 (UNARY-/
  (NUMBERS ACL2-BUILT-INS)
  "Reciprocal function

  Completion Axiom ([47mcompletion-of-unary-/[0m):

    (equal (unary-/ x)
           (if (and (acl2-numberp x)
                    (not (equal x 0)))
               (unary-/ x)
             0))

  [Guard] for [47m(unary-/ x)[0m:

    (and (acl2-numberp x)
         (not (equal x 0)))

  Notice that like all arithmetic functions, [47munary-/[0m treats non-numeric
  inputs as [47m0[0m.

  Calls of the macro [47m[/][0m on one argument expand to calls of [47munary-/[0m;
  see [/].")
 (UNARY-DF- (POINTERS) "See [df].")
 (UNARY-DF-LOG (POINTERS) "See [df].")
 (UNARY-DF/ (POINTERS) "See [df].")
 (UNCERTIFIED-BOOKS
  (BOOKS)
  "Invalid [certificate]s and uncertified [books]

  For relevant background see [books], see [books-tour], see
  [certificate], and see [portcullis].

  You may have been led to this topic by a warning or error message
  such as the following.

    There is no certificate on file for /u/smith/foo.lisp.  See :DOC
    uncertified-books.

  The remedy is to [3mcertify[0m the indicated book; see [certify-book].
  Such certification is typically a [3mvery[0m good idea, as discussed
  further below.  After certification succeeds, the book will have a
  valid [certificate] and the message will no longer be printed.  The
  rest of this topic explains issues pertaining to books that are
  [3muncertified[0m, that is, have not been certified.

  [47m[Include-book][0m has a special provision for dealing with an
  uncertified book, i.e., a file whose [certificate] is missing or
  invalid (e.g., one for a different ACL2 version or whose
  [book-hash] value describes a file other than the one actually
  read).  In this case, a warning is printed (as above) and the book
  is usually processed much as though it were certified.  If a book
  [47mB.lisp[0m was previously certified, it will probably have a
  corresponding file [47mB.port[0m representing the [portcullis] [command]s
  for that previous certification.  (See keyword argument [47m:write-port[0m
  of [47m[certify-book][0m.)  Then if [47mB.lisp[0m is currently uncertified and
  [47mB.port[0m exists, evaluation of [47m(include-book \"B\")[0m will cause the
  forms in [47mB.port[0m to be evaluated before the forms in [47mB.lisp[0m.  To
  avoid such evaluation for [47m.port[0m files, see [compilation].

  The ability to include uncertified [books] is handy but it can have
  disastrous consequences, ranging from hard lisp errors, to damaged
  memory, to quiet logical inconsistency.

  It is possible for the inclusion of an uncertified book to render the
  logic inconsistent.  For example, one of its non-[47m[local][0m [events]
  might be [47m(defthm t-is-nil (equal t nil))[0m.  It is also possible for
  the inclusion of an uncertified book to cause hard errors or
  [breaks] into raw Common Lisp.  For example, if the file has been
  edited since it was certified, it may contain too many open
  parentheses, causing Lisp to read past ``end of file.'' Similarly,
  it might contain non-ACL2 objects such as [47m3.1415[0m or ill-formed
  event forms that cause ACL2 code to break.

  Even if a book is perfectly well formed and could be certified (in a
  suitable extension of ACL2's initial [world]), its uncertified
  inclusion might cause Lisp errors or inconsistencies!  For example,
  it might mention packages that do not exist in the host [world],
  especially if the [47m.port[0m file (discussed above) does not exist from
  an earlier certification attempt.  The [portcullis] of a certified
  book ensures that the correct [47m[defpkg][0ms have been admitted, but if
  a book is read without actually raising its [portcullis], symbols
  in the file, e.g., [47macl2-arithmetic::fn[0m, could cause ``unknown
  package'' errors in Common Lisp.  Perhaps the most subtle disaster
  occurs if the host [world] does have a [47m[defpkg][0m for each package
  used in the book but the host [47m[defpkg][0m imports different symbols
  than those required by the [portcullis].  In this case, it is
  possible that formulas which were theorems in the certified book
  are non-theorems in the host [world], but those formulas can be
  read without error and will then be quietly assumed.

  In short, if you include an uncertified book, [31;1mall bets are off[0m
  regarding the validity of the future behavior of ACL2.

  That said, it should be noted that ACL2 is pretty tough and if errors
  don't occur, the chances are that deductions after the inclusion of
  an uncertified book are probably justified in the (possibly
  inconsistent) logical extension obtained by assuming the
  admissibility and validity of the definitions and conjectures in
  the book.")
 (UNDO
  (HISTORY)
  "Undoing and perhaps redefining

  This topic provides a high-level view of how one can undo a
  definition, perhaps replacing it with a new definition.  We begin
  with some background.

  ACL2 maintains a stack of [command]s.  For example, suppose we submit
  the following [events] in a new session.

    (defun f (x) x)
    (defun g (x) (* x x))
    (defthm f^2-is-g
      (equal (expt (f x) 2) (g x))
      :hints ((\"Goal\" :expand ((expt x 2)))))

  Then we can see the stack of commands by using [47m:[0m[47m[pcb][0m (``Print
  Command Block'') back to command 0, that is back to the start.

    ACL2 !>:pbt 0
               0  (EXIT-BOOT-STRAP-MODE)
     L         1  (DEFUN F (X) ...)
     L         2  (DEFUN G (X) ...)
               3:x(DEFTHM F^2-IS-G ...)
    ACL2 !>

  Now suppose that we want to redefine [47mg[0m.  The cleanest, safest way is
  to unwind the stack with [47m:[0m[47m[ubt][0m (``Undo Back Through'') all the way
  back through (and including) [47mg[0m.

    ACL2 !>:ubt g
     L         1:x(DEFUN F (X) ...)
    ACL2 !>:pbt 0
               0  (EXIT-BOOT-STRAP-MODE)
     L         1:x(DEFUN F (X) ...)
    ACL2 !>

  Now we can define [47mg[0m again and proceed from there.

    ACL2 !>(defun g (x) (expt x 2))
    [[.. output omitted here ..]]
     G
    ACL2 !>:pbt 0
               0  (EXIT-BOOT-STRAP-MODE)
     L         1  (DEFUN F (X) ...)
     L         2:x(DEFUN G (X) ...)
    ACL2 !>(defthm f^2-is-g
             (equal (expt (f x) 2) (g x)))
    [[.. output omitted here ..]]
     F^2-IS-G
    ACL2 !>:pbt 0
               0  (EXIT-BOOT-STRAP-MODE)
     L         1  (DEFUN F (X) ...)
     L         2  (DEFUN G (X) ...)
               3:x(DEFTHM F^2-IS-G ...)
    ACL2 !>

  See [ubt] for more information, including variants such as [47m:u[0m, which
  undoes a single command (the most recent one).  Also see [oops] for
  how to undo an undo.

  It can occasionally be inconvenient to undo a large number of
  commands when one's goal is only to redefine a single function.  In
  such cases one might wish to enable redefinition, even though it
  can be unsafe.  Here is an example (admittedly contrived) for how
  to continue the session above.  Note that there are variants of
  [47m:redef[0m --- see [redef] --- for example to avoid the query shown
  below and answered with `[47my[0m'.

    ACL2 !>:redef
     (:QUERY . :OVERWRITE)
    ACL2 !>(defun f (x) (+ 10 x))

    ACL2 Query (:REDEF):  The name F is in use as a function.  Its current
    defun-mode is :logic. Do you want to redefine it?  (N, Y, E, O or ?):
    y

    Since F is non-recursive, its admission is trivial.  We observe that
    the type of F is described by the theorem (ACL2-NUMBERP (F X)).  We
    used primitive type reasoning.

    Summary
    Form:  ( DEFUN F ...)
    Rules: ((:FAKE-RUNE-FOR-TYPE-SET NIL))
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)
     F
    ACL2 !>:pbt 0
               0  (EXIT-BOOT-STRAP-MODE)
     L         1  (DEFUN F (X) ...)
     L         2  (DEFUN G (X) ...)
               3  (DEFTHM F^2-IS-G ...)
     L         4:x(DEFUN F (X) ...)
    ACL2 !>

  Notice that the ``theorem'' [47mf^2-is-g[0m is still in our session, even
  though it is no longer valid now that [47mf[0m has been redefined.  This
  shows one reason we say that redefinition can be unsafe; it can be
  unsound!  Other possible dangers include execution errors and
  ignoring, in existing definitions, redefinitions of constants and
  macros.  Thus, undoing (and then redoing) is generally preferable
  to redefinition.  Indeed, redefinition is disallowed in [books].

  You can inspect both commands that introduce a definition for [47mf[0m with
  [47m:pcb[0m (``Print Command Block'' in full; see [pcb]).

    ACL2 !>:pcb! 1
     L         1  (DEFUN F (X) X)
    ACL2 !>:pcb! 3
     L         3:x(DEFUN F (X) (CAR (CONS X X)))
    ACL2 !>


Subtopics

  [U]
      Undo last [command], without a query

  [Ubt]
      Undo the [command]s back through a [command] descriptor

  [Ubt!]
      Undo [command]s, without a query or an error

  [Ubt-prehistory]
      Undo the [command]s back through the last [47m[reset-prehistory][0m event

  [Ubt?]
      Undo [command]s, with queries as appropriate

  [Ubu]
      Undo the [command]s back up to (not including) a [command]
      descriptor

  [Ubu!]
      Undo [command]s, without a query or an error

  [Ubu?]
      Undo [command]s, with queries as appropriate")
 (UNDOCUMENTED_TOPIC
      (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
      "Undocumented Topic

  This topic has not yet been documented.  Sorry")
 (UNDOING (POINTERS) "See [undo].")
 (UNION$
  (LISTS ACL2-BUILT-INS)
  "A list that contains exactly the elements of the given lists

    General Forms:
    (union$ l1 l2 ... lk)
    (union$ l1 l2 ... lk :test 'eql) ; same as above
    (union$ l1 l2 ... lk :test 'eq)    ; same, but eq is equality test
    (union$ l1 l2 ... lk :test 'equal) ; same, but equal is equality test

  [47m(Union$ x y)[0m equals a list that contains both the members of [47mx[0m and
  the members of [47my[0m.  More precisely, the resulting list is the same
  as one would get by first deleting the members of [47my[0m from [47mx[0m, and
  then concatenating the result to the front of [47my[0m.  The optional
  keyword, [47m:TEST[0m, has no effect logically, but provides the test
  (default [47m[eql][0m) used for comparing members of the two lists.

  [47mUnion$[0m need not take exactly two arguments: [47m(union$)[0m is [47mnil[0m, [47m(union$
  x)[0m is [47mx[0m, [47m(union$ x y z ... :test test)[0m is [47m(union$ x (union$ y z ...
  :test test) :test test)[0m, and if [47m:TEST[0m is not supplied, then [47m(union$
  x y z ...)[0m is [47m(union$ x (union$ y z ...))[0m.  For the discussion
  below we restrict ourselves, then, to the cases [47m(union$ x y)[0m and
  [47m(union$ x y :test test)[0m.

  The [guard] for a call of [47munion$[0m (in the two cases just above)
  depends on the test.  In all cases, both arguments must satisfy
  [47m[true-listp][0m.  If the test is [47m[eql][0m, then one of the arguments must
  satisfy [47m[eqlable-listp][0m.  If the test is [47m[eq][0m, then one of the
  arguments must satisfy [47m[symbol-listp][0m.

  See [equality-variants] for a discussion of the relation between
  [47munion$[0m and its variants:

      [47m(union-eq x lst)[0m is equivalent to [47m(union$ x lst :test 'eq)[0m;

      [47m(union-equal x lst)[0m is equivalent to [47m(union$ x lst :test 'equal)[0m.

  In particular, reasoning about any of these primitives reduces to
  reasoning about the function [47munion-equal[0m.

  [31;1mFunction: [0m<union-equal>

    (defun union-equal (l1 l2)
      (declare (xargs :guard (and (true-listp l1) (true-listp l2))))
      (cond ((endp l1) l2)
            ((member-equal (car l1) l2)
             (union-equal (cdr l1) l2))
            (t (cons (car l1)
                     (union-equal (cdr l1) l2)))))

  Note that [47munion-eq[0m can take any number of arguments, in analogy to
  [47munion$[0m; indeed, [47m(union-eq ...)[0m expands to [47m(union$ ... :test 'eq)[0m.
  However, [47munion-equal[0m is a function, not a macro, and takes exactly
  two arguments.

  [47mUnion$[0m is similar to the Common Lisp primitive [47munion[0m.  However,
  Common Lisp does not specify the order of elements in the result of
  a call of [47munion[0m.")
 (UNION-EQ (POINTERS) "See [union$].")
 (UNION-EQUAL (POINTERS) "See [union$].")
 (UNION-THEORIES
  (THEORIES THEORY-FUNCTIONS)
  "Union two [theories]

    Example:
    (union-theories (current-theory 'lemma3)
                    (theory 'arith-patch))

    General Form:
    (union-theories th1 th2)

  where [47mth1[0m and [47mth2[0m are theories (see [theories]).  To each of the
  arguments there corresponds a runic theory.  This function returns
  the union of those two runic [theories], represented as a list and
  ordered chronologically.

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].")
 (UNIVERSAL-THEORY
  (THEORIES THEORY-FUNCTIONS)
  "All rules as of logical name

    Examples:
    (universal-theory :here)
    (universal-theory 'lemma3)

  See [logical-name].

    General Form:
    (universal-theory logical-name)

  Returns the theory consisting of all the [rune]s that existed
  immediately after [47m[logical-name][0m was introduced.  See [theories]
  and see [logical-name].  The theory includes [47m[logical-name][0m itself
  (if there is a rule by that name).  (Note that since some [events]
  do not introduce rules (e.g., [47m[defmacro][0m, [47m[defconst][0m or [47m[defthm][0m
  with [47m:[0m[47m[rule-classes][0m [47mnil[0m), the universal-theory does not
  necessarily include a [rune] for every event name.)  The
  universal-theory is very long and you will probably regret printing
  it.

  You may experience a fencepost problem in deciding which
  [logical-name] to use.  [47m[Deflabel][0m can always be used to mark
  unambiguously for future reference a particular point in the
  development of your theory.  This is convenient because [47m[deflabel][0m
  does not introduce any rules and hence it doesn't matter if you
  count it as being in the interval or not.  The order of [events] in
  the vicinity of an [47m[encapsulate][0m is confusing.  See [encapsulate].

  This ``function'' is actually a macro that expands to a term
  mentioning the single free variable [47m[world][0m.  When theory
  expressions are evaluated by [47m[in-theory][0m or the [47m:[0m[47m[in-theory][0m hint,
  [47m[world][0m is bound to the current ACL2 [world].

  Also see [current-theory].  [47mCurrent-theory[0m is much more commonly used
  than [47muniversal-theory[0m.  The former includes only the [enable]d
  [rune]s as of the given [47m[logical-name][0m, which is probably what you
  want, while the latter includes [disable]d ones as well.")
 (UNKNOWN-CONSTRAINTS (POINTERS)
                      "See [partial-encapsulate].")
 (UNMEMOIZE
  (MEMOIZE PROGRAMMING HONS-AND-MEMOIZATION EVENTS)
  "Turn off memoization for the specified function

    Example:
    (unmemoize 'foo) ; turn off memoization of foo

    General Form:
    (unmemoize fn)

  where [47mfn[0m evaluates to a function symbol that is currently memoized;
  see [memoize].  An exception is that as with [47m[memoize][0m, [47mfn[0m may
  evaluate to the name of a macro that is associated with such a
  function symbol; see [macro-aliases-table].

  Calls of this macro generate events of the form [47m(table memoize-table
  fn nil)[0m.  When successful, the returned value is of the form [47m(mv
  nil function-symbol state)[0m.

  To remove the effects of all [47m[memoize][0m [events], evaluate:
  [47m(clear-memo-table)[0m.  To save and restore memoization, see
  [save-and-clear-memoization-settings] and see
  [restore-memoization-settings].  These are both legal [event]
  forms.  Note: These events do not affect memoization from [47m[memoize][0m
  events that either are derived from calls of [47m[memoize-partial][0m or
  have a non-[47mnil[0m value of [47m[memoize][0m argument [47m:invoke[0m")
 (UNMONITOR
  (BREAK-REWRITE)
  "To stop monitoring a rule name

    Examples:
    (unmonitor '(:rewrite assoc-of-app))
    :unmonitor (:rewrite assoc-of-app)
    :unmonitor :all

    General Forms:
    (unmonitor rune)
    (unmonitor :all)

  Here, [47mrune[0m is a [rune] that is currently among those with break
  points installed.  This function removes the break.  See [monitor].

  Subtle point: Because you may want to unmonitor a ``[rune]'' that is
  no longer a [rune] in the current ACL2 [world], we don't actually
  check this about [47mrune[0m.  We simply check that [47mrune[0m is currently
  monitored and remove it.  If [47mrune[0m corresponds to no entry on the
  list of monitored runes we cause an error since it may indicate a
  misspelling.")
 (UNQUOTE
  'ACL2-BUILT-INS
  "Obtain the object being quoted

  [47mUnquote[0m is just an abbreviation for [47m[cadr][0m.  Its intended use is to
  obtain an object being quoted.  For example, if [47mx[0m is [47m(quote (3 4))[0m
  then [47m(unquote x)[0m is [47m(3 4)[0m:

    ACL2 !>(let ((x '(quote (3 4))))
             (unquote x))
    (3 4)
    ACL2 !>")
 (UNSAVE
  (PROOF-BUILDER)
  "Remove a [proof-builder] state

    Example:
    (unsave assoc-of-append)

    General Form:
    (unsave name)

  Eliminates the association of an interactive [proof-builder] state
  with [47mname[0m.  See [unsave] or see [ACL2-pc::unsave].

  Also see [ACL2-pc::save] and see [retrieve].")
 (UNSIGNED-BYTE-P
  (NUMBERS ACL2-BUILT-INS)
  "Recognizer for natural numbers that fit in a specified bit width

  [47m(Unsigned-byte-p bits x)[0m is [47mT[0m when [47mbits[0m is a positive integer and [47mx[0m
  is a nonnegative integer that fits into a bit-width of [47mbits[0m, i.e.,
  [47m0 <= x < 2^bits[0m.

  Note that a [type-spec] of [47m(unsigned-byte i)[0m for a variable [47mx[0m in a
  function's [47m[declare][0m form translates to a [guard] condition of
  [47m(unsigned-byte-p i x)[0m.

  The [guard] for [47munsigned-byte-p[0m is [47mT[0m.

  [31;1mFunction: [0m<unsigned-byte-p>

    (defun unsigned-byte-p (bits x)
      (declare (xargs :guard t))
      (and (integerp bits)
           (<= 0 bits)
           (integer-range-p 0 (expt 2 bits) x)))")
 (UNSUPPORTED-PARALLELISM-FEATURES
  (PARALLELISM)
  "ACL2 features not supported in ACL2(p)

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].
  See [parallelism-tutorial] for an introduction to parallel
  programming in ACL2.

  For proof features of ACL2 that are not yet supported when parallel
  execution is enabled for the primary ACL2 proof process, generally
  known as ``the waterfall'', see
  [unsupported-waterfall-parallelism-features].

  Please note that this topic discusses ACL2 features that are disabled
  when using ACL2(p) (see [compiling-ACL2p]).  These features are
  disabled regardless of whether waterfall parallelism is enabled.

  Calls of [47m[observation-cw][0m simply convert to calls of [47m[cw][0m, so
  suppressing [47m[observation][0ms (see [set-inhibit-output-lst]) will not
  suppress these messages.

  Memoization is not supported when executing in parallel.  See
  [Unsupported-waterfall-parallelism-features] for memoization
  details related to waterfall parallelism.

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

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

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

  The [47m[time-tracker][0m utility is a no-op for ACL2(p).

  When executing calls of [47m[hons-get][0m in parallel, you may see messages
  about [47m\"Fast alist discipline\"[0m violations.  This can happen because
  each thread uses its own underlying hash table for fast access by
  [47mhons-get[0m, but typical top-level calls of [47m[hons-acons][0m and
  [47m[make-fast-alist][0m only affect that main thread's hash table.  You
  can use [47m(set-slow-alist-action nil)[0m to eliminate this warning
  entirely; see [slow-alist-warning].")
 (UNSUPPORTED-WATERFALL-PARALLELISM-FEATURES
  (PARALLEL-PROOF)
  "Proof features not supported with waterfall-parallelism enabled

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

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

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

  Without a trust tag (see [defttag]): We support [clause-processor]s,
  [computed-hints], and [custom-keyword-hints] that do not modify
  [state], but we do not permit [override-hints], regardless of
  whether they modify state.  With a trust tag, the user can use
  [clause-processor]s that modify state and can also use
  [override-hints] (see [set-waterfall-parallelism-hacks-enabled] for
  a convenient mechanism for adding a trust tag).  See
  [error-triples-and-parallelism] for a discussion of how to avoid
  modifying state in such situations.  Regardless of whether a trust
  tag is active: We do not support checkers of [custom-keyword-hints]
  to be anything but the default checker.

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

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

    * The standard `make'-based process for book certification will not use
      [waterfall-parallelism], which is disabled by default (even
      when [compiling-ACL2p] by using the [47mACL2_PAR[0m flag).  See
      [books-certification] and see [books-certification-classic],
      which explain that [ACL2-customization] files are ignored
      during that process unless specified explicitly on the command
      line or in the environment.

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

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

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

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

  The [47m:[0m[47m[brr][0m and [47m[with-brr-data][0m utilities are not supported.

  The [47m[accumulated-persistence][0m utility is not supported.

  Tracking for [forward-chaining-reports] is not supported (see
  [set-fc-criteria]).

  Time limits (see [with-prover-time-limit]) aren't supported.

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

  Use [47m[wormhole][0ms at your own risk.  Although they use locks, there has
  been some concern that they may cause race conditions.  They are
  used in ACL2(p) source code (macro [47m[observation-cw][0m), however, thus
  we have hope that they perform acceptably.

  Output specific to [47m:OR[0m [hints] is disabled.

  Proof trees are likely not to work as originally designed.

  The use of [47m[set-inhibit-output-lst][0m may not fully inhibit proof
  output.

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

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

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

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

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

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

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

  Proof output for splitter rules (see [splitter]) is currently
  unsupported when waterfall-parallelism is enabled.

  Profiling may cause proofs to hang when waterfall-parallelism is
  enabled (GitHub Issue #638).

  During proofs with [waterfall-parallelism] enabled, you may see
  messages about [47m\"Fast alist discipline\"[0m violations, even when using
  [47m[hons-get][0m appropriately.  This can happen because each thread uses
  its own underlying hash table for fast access by [47mhons-get[0m, but
  typical top-level calls of [47m[hons-acons][0m and [47m[make-fast-alist][0m only
  affect that main thread's hash table.  You can use
  [47m(set-slow-alist-action nil)[0m to eliminate this warning entirely; see
  [slow-alist-warning].")
 (UNTIL$ (POINTERS) "See [loop$].")
 (UNTIL$+ (POINTERS) "See [loop$].")
 (UNTOUCHABLE
  (DEFTTAG)
  "Function symbols and state globals that cannot be referenced

  Untouchables are functions that cannot be called, as well as [state]
  global variables (see [programming-with-state]) that cannot be
  modified or unbound.  To add or remove untouchables, see
  [push-untouchable] and see [remove-untouchable].  Macros can be
  made effectively untouchable as well; see [defmacro-untouchable].")
 (UNTOUCHABLE-MARKER (POINTERS)
                     "See [defmacro-untouchable].")
 (UNTRACE$
  (TRACE)
  "Untrace functions

    Examples:
    (untrace$)         ; untrace all functions previously
                       ; traced (e.g. with trace$ or trace!)
    (untrace$ foo bar) ; as above, except only untrace foo and bar

    General Forms:
    (untrace$)                 ; untrace all (as noted above)
    (untrace$ fn1 fn2 ... fnk) ; untrace the indicated functions

  where the [47mfni[0m were previously traced (e.g. with [47m[trace$][0m or
  [47m[trace!][0m).

  [47mUntrace$[0m undoes the effect of [47m[trace$][0m.  See [trace$].  The value
  returned by [47muntrace$[0m gives the list of functions for which tracing
  is being removed.")
 (UNTRANS-TABLE
  (MACROS)
  "Associates a function symbol with a macro for printing user-level
  terms

    Examples:
    ACL2 !>(untrans-table (w state))
    ((BINARY-+ + . T)
     (BINARY-* * . T)
     (BINARY-APPEND APPEND . T)
     (BINARY-LOGAND LOGAND . T)
     (BINARY-LOGIOR LOGIOR . T)
     (BINARY-LOGXOR LOGXOR . T)
     (BINARY-LOGEQV LOGEQV . T)
     (BINARY-POR POR . T)
     (BINARY-PAND PAND . T))

  See [table] for a general discussion of tables.

  See [add-macro-fn] for a more general discussion of this [table] and
  for a way to associate a macro name with a function name in theory
  events.")
 (UNTRANSLATE
  (SYSTEM-UTILITIES)
  "Show a user-level representation of a term

  ACL2 uses a strict notion of ``[term]'' for its internal
  computations; see [pseudo-termp].  Such expressions are sometimes
  called ``translated terms''.  However, ACL2 provides user-level
  output --- for example, in output from the theorem prover --- in
  the form of so-called ``untranslated terms''.  For example, the
  untranslated term [47m(<= 3 x)[0m corresponds to the translated term [47m(not
  (< x '3))[0m, as is illustrated by applying [47m:[0m[47m[trans][0m to the
  untranslated term:

    ACL2 !>:trans (<= 3 x)

    (NOT (< X '3))

    => *

    ACL2 !>

  Notice for example that the macro [47m<=[0m has been eliminated in favors of
  the functions [47mnot[0m and [47m<[0m, and that the constant [47m3[0m has been quoted.

  The call [47m(untranslate term iff-flg wrld)[0m returns an untranslated term
  corresponding to the given translated term, [47mterm[0m, with respect to
  the given logical [world], [47mwrld[0m.  If [47miff-flg[0m is not [47mnil[0m, then that
  untranslated term is merely propositionally equivalent to the input
  term, as the following example illustrates.

    ACL2 !>:trans (and x t)

    (IF X 'T 'NIL)

    => *

    ACL2 !>(untranslate '(IF X 'T 'NIL) nil (w state))
    (AND X T)
    ACL2 !>(untranslate '(IF X 'T 'NIL) t (w state))
    X
    ACL2 !>

  The latter result, [47mx[0m, is what one might want to see if the term is
  being used as the first argument of a call of the function, [47mif[0m.
  Indeed, [47muntranslate[0m is defined so that the [47miff[0m flag is
  automatically set in the test position of an [47mif[0m call.

    ACL2 !>:trans (if (and x t) y z)

    (IF (IF X 'T 'NIL) Y Z)

    => *

    ACL2 !>(untranslate '(IF (IF X 'T 'NIL) Y Z) nil (w state))
    (IF X Y Z)
    ACL2 !>

  Also see [user-defined-functions-table] and [add-macro-fn].")
 (UNTRANSLATE-PREPROCESS (POINTERS)
                         "See [user-defined-functions-table].")
 (UPDATE-NTH
  (LISTS ACL2-BUILT-INS)
  "Modify a list by putting the given value at the given position

  [47m(Update-nth key val l)[0m returns a list that is the same as the list [47ml[0m,
  except that the value at the [47m0[0m-based position [47mkey[0m (a natural
  number) is [47mval[0m.

  If [47mkey[0m is an integer at least as large as the length of [47ml[0m, then [47ml[0m
  will be padded with the appropriate number of [47mnil[0m elements, as
  illustrated by the following example.

    ACL2 !>(update-nth 8 'z '(a b c d e))
    (A B C D E NIL NIL NIL Z)

  We have the following theorem.

    (implies (and (true-listp l)
                  (integerp key)
                  (<= 0 key))
             (equal (length (update-nth key val l))
                    (if (< key (length l))
                        (length l)
                      (+ 1 key))))

  The [guard] of [47mupdate-nth[0m requires that its first (position) argument
  is a natural number and its last (list) argument is a true list.

  [31;1mFunction: [0m<update-nth>

    (defun update-nth (key val l)
      (declare (xargs :guard (true-listp l))
               (type (integer 0 *) key))
      (cond ((zp key) (cons val (cdr l)))
            (t (cons (car l)
                     (update-nth (1- key) val (cdr l))))))


Subtopics

  [Nth-aliases-table]
      A [table] used to associate names for nth/update-nth printing")
 (UPDATE-NTH-ARRAY
  (STOBJ ACL2-BUILT-INS)
  "Update a stobj array

  [47mUpdate-nth-array[0m is called by [stobj] updaters to modify stobj array
  fields.  See [stobj-example-3] for a discussion of this function
  and how it plays that role.

  [31;1mFunction: [0m<update-nth-array>

    (defun update-nth-array (j key val l)
      (declare (xargs :guard (and (integerp j)
                                  (integerp key)
                                  (<= 0 j)
                                  (<= 0 key)
                                  (true-listp l)
                                  (true-listp (nth j l)))))
      (update-nth j (update-nth key val (nth j l))
                  l))")
 (UPPER-CASE-P
  (CHARACTERS ACL2-BUILT-INS)
  "Recognizer for upper case characters

  [47m(Upper-case-p x)[0m is true if and only if [47mx[0m is an upper case character,
  i.e., a member of the list [47m#\\A[0m, [47m#\\B[0m, ..., [47m#\\Z[0m.

  The [guard] for [47mupper-case-p[0m states that its argument is a character.

  [47mUpper-case-p[0m 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 [soundness], specifically Example
  1 in the Section, ``Examples of divergence among Lisp
  implementations''.

  [31;1mFunction: [0m<upper-case-p>

    (defun upper-case-p (x)
      (declare (xargs :guard (characterp x)))
      (cond ((standard-char-p x)
             (and (member x
                          '(#\\A #\\B #\\C #\\D #\\E #\\F #\\G
                                #\\H #\\I #\\J #\\K #\\L #\\M #\\N #\\O #\\P #\\Q
                                #\\R #\\S #\\T #\\U #\\V #\\W #\\X #\\Y #\\Z))
                  t))
            (t (upper-case-p-non-standard x))))")
 (USE (POINTERS)
      "See [hints] for information about the keyword [47m:use[0m.")
 (USELESS-RUNES
  (CERTIFY-BOOK ACCUMULATED-PERSISTENCE)
  "Speed up proofs by disabling useless [rune]s

  This topic documents the [47m:useless-runes[0m keyword argument of
  [47m[certify-book][0m and [47m[ld][0m, which makes it possible to speed up
  repeated running of a book's [events].  This option is ignored in
  ACL2(r) (see [real]) and, when [waterfall-parallelism] is active,
  in ACL2(p) (see [parallelism]).


Introduction

  For a given [event], the so-called ``useless'' rules are those that
  do not contribute to the progress of any proof supporting that
  event.  For more background see [accumulated-persistence], which is
  typically used for finding rules (or more precisely, [rune]s) to
  [disable] during proofs.  The feature described in the present
  topic provides automation for the discovery and effective disabling
  of useless rules.

  Below, we focus first on the use of [47m:useless-runes[0m for [47m[certify-book][0m
  rather than for [47m[ld][0m.  The main time to use this option with [47m[ld][0m
  may be when developing a book that is to be certified eventually
  with a [47m:useless-runes[0m option.  We return to discuss [47mld[0m later in
  this topic (in Section ``Modifications for [47m[ld][0m'').

  To use the [47m:useless-runes[0m option of [47m[certify-book][0m, first certify
  your book --- say, [47mfoo.lisp[0m --- by supplying option [47m:useless-runes
  :write[0m.  This creates a file in the subdirectory [47m.sys[0m of the book's
  directory, creating that directory if it does not already exist.
  This new file, [47m.sys/foo@useless-runes.lsp[0m, associates names of
  [47m[defthm][0m, [47m[defun][0m, and [47m[verify-guards][0m [events] with sets of
  ``useless'' [rune]s'': rule names (``[rune]s'') not contributing to
  the progress of the proof.  Then, future certifications can use
  option [47m:useless-runes :read[0m --- or some limited variations of [47m:read[0m
  using numeric values, as discussed below) --- which, during
  evaluation of an event, will effectively [disable] rules associated
  with that event in file [47mfoo@useless-runes.lsp[0m.

  Environment variable [47mACL2_USELESS_RUNES[0m can take the value [47m\"write\"[0m or
  [47m\"read\"[0m to be used in place of the [47m:useless-runes[0m option [47m:read[0m or
  [47m:write[0m (respectively) of [47mcertify-book[0m.  [47mACL2_USELESS_RUNES[0m can also
  have value [47m\"nil\"[0m (case-insensitive) or a string representing a
  legal numeric value for the [47m:useless-runes[0m option of
  [47m[certify-book][0m.  This is all discussed below.

  By default, certification of the [community-books], when using either
  [47mmake[0m (as described elsewhere; see [books-certification]) or
  [build::cert.pl], is performed with environment variable
  [47mACL2_USELESS_RUNES[0m set to [47m\"-25\"[0m.  This setting, for each book
  [47mfoo.lisp[0m, causes part of the corresponding file
  [47m.sys/foo@useless-runes.lsp[0m, if it exists, to be consulted as
  described below.  However, useless runes are entirely ignored (both
  their use and for writing to [47m.sys/foo@useless-runes.lsp[0m files) both
  in ACL2(r) (see [real]) and, when [waterfall-parallelism] is
  active, in ACL2(p) (see [parallelism]).


Detailed Documentation

  Again, the [47m:useless-runes[0m option provides a way to automate discovery
  and, in subsequent uses, disabling of useless runes that can speed
  up proofs.  Information about useless runes is communicated using a
  file, which we call the ``@useless-runes.lsp file'' (or, sometimes,
  ``useless-runes file''), whose name is obtained by adding the
  suffix [47m\"@useless-runes.lsp\"[0m to the book name, and which is placed
  in the [47m.sys[0m subdirectory of the book's directory, after creating
  that subdirectory if it does not already exist.  For example, if
  the book's filename is [47m\"foo.lisp\"[0m then the corresponding
  @useless-runes.lsp has filename [47m\".sys/foo@useless-runes.lsp\"[0m.

  The following table summarizes the legal values for the option
  [47m:useless-runes[0m; further explanation follows.

    :write   ; Write the @useless-runes.lsp file to speed up future proofs.
    :read or ; Read the @useless-runes.lsp file to speed up proofs;
    :read?   ;   file must exist for :read, but need not exist for :read?.
    N, -N    ; N is a positive integer not exceeding 100.  Then |N|% of the rules
             ;   indicated by the @useless-runes.lsp file are to be kept disabled.
             ;   The @useless-runes.lsp file needs to exist for N but not for -N.
    nil      ; Do not read or write the @useless-runes.lsp file.

  Notice in particular that [47m:useless-runes 100[0m is equivalent to
  [47m:useless-runes :read[0m, while [47m:useless-runes -100[0m is equivalent to
  [47m:useless-runes :read?[0m.

  The option [47m:useless-runes :write[0m directs that a corresponding
  @useless-runes.lsp file is to be written.  Each top-level entry of
  this file that is non-trivial (see below) has the form

    (name
     (frames-1 tries-1 rune-1)
     (frames-2 tries-2 rune-2)
     ...
     (frames-k tries-k rune-k)
     )

  where [47mname[0m is the name of a [47m[defthm][0m, [47m[defun][0m, or [47m[verify-guards][0m
  event, and each tuple [47m(frames-i tries-i rune-i)[0m indicates the
  number of frames and tries for [47mrune-i[0m recorded for the proofs done
  on behalf of that event.  ACL2 claims that none of the indicated
  rules contributed to the progress of the proof.  See
  [accumulated-persistence], but also see
  [accumulated-persistence-subtleties] for some limitations.  These
  top-level entries are listed in order of event in the book, from
  top to bottom.  Because of [local] [events], the same name may
  appear more than once; we say more about this in the ``Subtleties''
  section, below.

  Note that ``trivial'' entries are possible, where there are no
  tuples; in that case, just [47m(name)[0m is printed, on a single line.
  Otherwise printing uses the format shown above, where the first
  line contains a left parenthesis on the left margin followed by the
  name, and each tuple is on a single line starting in column 1
  (i.e., after a single space), as is the final right parenthesis.

  The option [47m:useless-runes :read[0m or [47m:useless-runes :read?[0m directs use
  of the corresponding @useless-runes.lsp file, if it exists.  If
  that file does not exist, an error is caused when the option value
  is [47m:read[0m but the option is simply ignored when the option value is
  [47m:read?[0m.

  The value of [47m:useless-runes[0m may also be a non-zero integer between
  -100 and 100, inclusive.  The absolute value of this number is the
  percentage of the runes associated with the current event that are
  to be effectively kept [disable]d, starting with the useless rune
  with the highest number of frames built (see
  [accumulated-persistence]).  For example, if the value is 20 then
  1/5 of the runes associated with the current event in the
  @useless-runes.lsp file are to be kept disabled; so if the relevant
  top-level form in that file is

    (name
     (frames-1 tries-1 rune-1)
     (frames-2 tries-2 rune-2)
     (frames-3 tries-3 rune-3)
     (frames-4 tries-4 rune-4)
     (frames-5 tries-5 rune-5)
     (frames-6 tries-6 rune-6)
     (frames-7 tries-7 rune-7)
     )

  then 1/5 of the 7 runes are to be disabled, so since the first
  integer greater than or equal to 7/5 is 2, the runes [47mrune-1[0m and
  [47mrune-2[0m will be kept disabled.  Note again that the value [47m100[0m for
  [47m:useless-runes[0m gives the same behavior as the value [47m:read[0m, and the
  value [47m-100[0m gives the same behavior as the value [47m:read?[0m.

  The [47m:useless-runes[0m option need not be given explicitly to
  [47m[certify-book][0m.  Suppose that the environment variable
  [47mACL2_USELESS_RUNES[0m has a non-empty value.  Then that value
  implicitly invokes the [47m:useless-runes[0m option as indicated by the
  following table, which shows how that environment variable value
  corresponds to a value for the [47m:useless-runes[0m option.

    ACL2_USELESS_RUNES value          :useless-runes value
    ------------------------          --------------------

    WRITE (case insensitive)          :write
    READ (case insensitive)           :read
    READ? (case insensitive)          :read?
    i, ij, -i, -ij, 100, -100         corresponding integer, which cannot be 0
      (i and j are base-10 digits)

  [31;1mImportant[0m.  An explicitly supplied [47m:useless-runes[0m value normally
  takes priority over the value of environment variable
  [47mACL2_USELESS_RUNES[0m.  However, for [47mcertify-book[0m the environment
  variable takes priority if its (case insensitive) value is [47m\"WRITE\"[0m
  provided [47m:useless-runes nil[0m is not supplied explicitly.  This
  feature supports the use of the environment variable when using
  [47mmake[0m to update @useless-runes.lsp files for the community books.

  If you want certification to avoid reading the book's
  @useless-runes.lsp file even when this environment variable has a
  non-empty value that specifies reading, use option [47m:useless-runes
  nil[0m.

  A reason for allowing integer values, rather than only [47m:read[0m and
  [47m:read?[0m, is that the disabling of useless runes can cause a proof to
  fail.  Although this is probably uncommon, it can happen, for
  example because an otherwise useless rule rewrites the hypothesis
  of rule R to something that can not be proved by rewriting, thus
  blocking the use of rule R; but with the useless rule disabled, R
  is successfully applied, sending the proof in a direction that
  leads to failure.  This problem may disappear when using only a
  portion of the useless rules.  See also
  [accumulated-persistence-subtleties].

  Note that when using the @useless-runes.lsp file for a given event's
  proofs, then the appropriate rules are effectively [disable]d not
  only at the top level, but also whenever [hints] are supplied.  So
  if an [47m:[0m[47m[in-theory][0m hint specifies a [theory] that includes rule R,
  but rule R is specified for disabling for the current event by the
  @useless-runes.lsp file, then R will be removed from the theory
  before installing that hint.  In particular, even the hint
  [47m:in-theory (enable [0mR[47m)[0m will not enable R in this case.

  Finally, we remark that the @useless-runes.lsp file is somewhat
  robust in the following sense.  Suppose that rule R is specified in
  that file, but at the time the @useless-runes.lsp is read, rule R
  has been removed from one's books.  Then the inclusion of R as a
  useless rule will simply be ignored, rather than causing an error.


Subtleties

  The @useless-runes.lsp files do not contain any
  [47m:[0m[47m[executable-counterpart][0m runes, because there are many places that
  ACL2 does not track such runes for [47m[accumulated-persistence][0m.
  (Details are in a comment in the ACL2 source definition of function
  [47mprint-useless-runes[0m.)

  On rare occasions, when using the [47m:read[0m option or related values that
  specify reading from an appropriate @useless-runes.lsp file, the
  [package] of a rune's name might not be known to ACL2 at read time.
  In that case, that rune will be ignored.

  Because of [local] [events], more than one event may be associated
  with a name in a given @useless-runes.lsp file.  When using the
  [47m:read[0m option or related values that specify reading from an
  appropriate @useless-runes.lsp file, ACL2 considers entries for a
  given name from top to bottom in the @useless-runes.lsp file,
  attempting to match them to [47m[defthm][0m, [47m[defun][0m, and [47m[verify-guards][0m
  events from top to bottom in the book.

  As suggested by discussions above, a @useless-runes.lsp file is
  intended not to cause proof failures, even if it is older than the
  corresponding book or even older than other books containing runes
  that are listed in that @useless-runes.lsp file.  That said, an
  out-of-date @useless-runes.lsp might cause proofs to fail.  In
  particular, imagine that there are several lemmas in the
  corresponding book all with the same name (and thus all [local] to
  an [47m[encapsulate][0m event except perhaps the last), and one of those
  lemmas other than the last is deleted from the book.  Then
  references to the later such lemmas will be wrong in the
  @useless-runes.lsp file.  If you run into this problem, then either
  regenerate the @useless-runes.lsp file (e.g., using [47mcertify-book[0m
  with environment variable [47mACL2_USELESS_RUNES[0m set to [47m\"write\"[0m), or
  give distinct names to your book's lemmas, or even consider adding
  a line like the following to a suitable [47m.acl2[0m file (see
  [build::custom-certify-book-commands]).

    ; cert-flags: ? t :useless-runes nil


Adaptations for [47m[ld][0m

  The [47m:useless-runes[0m keyword argument was originally developed for
  [47m[certify-book][0m, and that is probably still where it is most useful.
  But when developing or updating a book [47m\"BK\"[0m, it may be convenient
  to evaluate the book's [events] using [47m(ld \"BK.lisp\" ..
  :useless-runes ..)[0m.  In that case, it is probably a good idea to
  run that [47mld[0m command in the same certification [world] (i.e., the
  world with the same sequence of [portcullis] commands) as will be
  encountered when certifying the book, so that the accesses to the
  @useless-runes.lsp will match up between the [47mld[0m call and a
  corresponding [47mcertify-book[0m call.  The following observations may
  help in that respect.

    * If [47m\"BK.lisp\"[0m has previously been certified, there should be a file
      [47m\"BK.port\"[0m.  By executing [47m(ld \"BK.port\")[0m, you will put yourself
      in the appropriate certification world (unless the book's
      [portcullis] commands have changed since the time it was
      certified).

    * If your [47mld[0m of the book ends prematurely in an error, then before you
      call [47mld[0m again with a [47m:useless-runes[0m argument, it would very
      likely be best to back up (using [47m:[0m[47m[ubt][0m) so that you are once
      again in the intended certification world.

  Here are a few differences between [47mld[0m and [47mcertify-book[0m with respect
  to useless-runes.  For purposes of this discussion, let's say a
  call of [47mld[0m is ``a book-like call'' if the first argument is a
  string ending with [47m\".lisp\"[0m.

    * Just as how [47mcertify-book[0m consults environment variable
      [47mACL2_USELESS_RUNES[0m for an implicit value of omitted keyword
      argument [47m:useless-runes[0m, a book-like call of [47mld[0m consults
      environment variable [47mACL2_USELESS_RUNES_LD[0m.  For example, if
      environment variable [47mACL2_USELESS_RUNES_LD[0m has value [47m\"50\"[0m, then
      the call [47m(ld \"foo.lisp\")[0m will be treated as though it were the
      call [47m(ld \"foo.lisp\" :useless-runes 50)[0m.

    * If environment variable [47mACL2_USELESS_RUNES_LD[0m takes on the special
      value [47m\"cert\"[0m, case-insensitive, then [47mld[0m will consult
      environment variable [47mACL2_USELESS_RUNES[0m just as [47mcertify-book[0m
      does.

    * It is an error for a call of [47mld[0m that is not book-like to have a
      non-[47mnil[0m [47m:useless-runes[0m argument.  For a call of [47mld[0m without a
      [47m:useless-runes[0m argument, environment variables supply a
      useless-runes value (as described above) only if it is a
      book-like call.

    * The value of keyword argument [47m:useless-runes[0m in a call of
      [47mcertify-book[0m or [47mld[0m does not persist to a subsidiary call of
      [47mcertify-book[0m or [47mld[0m.  If you want a useless-runes value to
      persist, use environment variables.

    * Recall that for [47mcertify-book[0m, the environment variable takes priority
      if its (case insensitive) value is [47m\"write\"[0m provided the
      [47m:useless-runes nil[0m keyword argument is not supplied.  But for
      [47mld[0m, an explicit value of the [47m:useless-runes[0m keyword argument
      always takes priority; environment variables, even with value
      [47m\"write\"[0m, do not override any such value.


Performance

  In ``everything'' testing of all of the [community-books] during (not
  quite complete) development of this capability, we found that
  writing the @useless-runes.lsp files (by setting the environment
  variable [47mACL2_USELESS_RUNES[0m to [47m\"write\"[0m) caused an 11% slowdown from
  the normal time, but a fresh such test when reading the
  @useless-runes.lsp files by setting the environment variable
  [47mACL2_USELESS_RUNES[0m to [47m\"25\"[0m cut 24% from the normal time.  Books
  varied considerably, however.  For example, after finding a
  specific time reduction that was particularly significant, we
  re-certified on standalone runs (i.e., on an otherwise unloaded
  machine) and found that the time was reduced from 17 minutes and
  1.9 seconds down to 34.93 seconds, thus eliminating 96.6% of the
  time.


Subtopics

  [Useless-runes-failures]
      Failures caused by [useless-runes]")
 (USELESS-RUNES-FAILURES
  (FAILURE USELESS-RUNES)
  "Failures caused by [useless-runes]

  When an event fails you may see the following message:

    *NOTE*: Useless-runes were in use and can affect proof attempts.  See
    :DOC useless-runes-failures.

  This message may be printed after the usual failure message when a
  [useless-runes] file has been consulted during proofs, as is
  usually the case when using build system tools (see
  [books-certification] and [build::cert.pl]).  It is intended to
  suggest that you consider removing or regenerating the associated
  [useless-runes] file in the situation described below.

  Suppose that you have developed a book --- say, [47mfoo.lisp[0m --- and
  placed it into the [community-books].  Then [regression] runs may
  occasionally generate (or regenerate) the associated
  [useless-runes] file.  Now suppose you modify [47mfoo.lisp[0m or some
  books that are included in it.  You successfully run [47m(certify-book
  \"foo\")[0m; yet, certification of [47mfoo.lisp[0m subsequently fails as part
  of a [regression] run or when you use [47m[build::cert.pl][0m to certify
  [47mfoo.lisp[0m.  This could be unsettling!

  In that case, what is probably happening is that the [useless-runes]
  file is no longer suitable.  If you are a contributor to the ``ACL2
  System and Community Books'' GitHub project (see
  [git-quick-start]), you can update repository as follows (followed
  by the usual actions when updating the repository).

    git rm .sys/foo@useless-runes.lsp

  Or, if you like, you could regenerate the useless-runes file, for
  example as follows.

    (certify-book \"foo\" ? t :useless-runes :write)

  Or if you prefer to avoid this useless-runes file from now on, you
  could add a line like the following to [47mfoo.acl2[0m (see
  [build::custom-certify-book-commands]) and also, ideally, delete
  the useless-runes file using the [47m\"git rm\"[0m command displayed above.

    ; cert-flags: ? t :useless-runes nil")
 (USER-DEFINED-FUNCTIONS-TABLE
  (MACROS)
  "An advanced [table] used to replace certain system functions

    Examples:
    (table user-defined-functions-table 'untranslate-preprocess 'my-preprocess)
    (table user-defined-functions-table 'untranslate 'my-untranslate)

  This feature should perhaps only be used by advanced users who have a
  thorough understanding of the system functions being replaced.
  There are currently two ways a user can affect the way ACL2 prints
  terms.

  The first example associates the user-defined function symbol
  [47mmy-preprocess[0m with [47muntranslate-preprocess[0m.  As a result, when ACL2
  prints a term, say during a proof, using its so-called
  ``untranslate'' process the first thing it does is to call
  [47mmy-preprocess[0m on two arguments: that term and the current ACL2
  logical [world].  If the call produces a non-[47mnil[0m result, then that
  result is passed to the untranslate process.

  The second example associates the user-defined function symbol
  [47mmy-untranslate[0m with the built-in function symbol [47muntranslate[0m.  As a
  result, the code for [47mmy-untranslate[0m will be run whenever the
  untranslate process is run.  The formals of the two functions must
  agree and must not contain any [stobj] names.  Note that these
  overrides fail to occur upon guard violations and some other
  evaluation errors.

  The [47muntranslate-preprocess[0m approach may suffice for most cases in
  which a user wants to modify the way output is produced by the
  theorem prover.  We present an example immediately below, but see
  [untranslate-patterns] for a more elaborate example.  If the
  [47muntranslate-preprocess[0m approach does not seem sufficient for your
  purposes, you are invited to look at community book
  [47mbooks/misc/rtl-untranslate.lisp[0m or the source code for [define] for
  an example of user-defined [47muntranslate[0m (i.e., following the second
  example displayed above).

  Suppose you have a large constant that you would prefer not to see in
  proofs.  For example, you may have submitted the following
  definition (but imagine a much larger constant, say, a list of
  length 1,000,000).

    (defconst *a* '(a b c d))

  If you submit the following (silly) theorem

    (thm (equal (cons x *a*) (car (cons yyy zzz))))

  then you will see the following output:

    (EQUAL (CONS X '(A B C D)) YYY).

  If [47m*a*[0m had represented a much larger structure, we would wish we
  could see the following instead.

    (EQUAL (CONS X *A*) YYY)

  That can be accomplished as follows.  First we make the following
  definition.

    (defun my-preprocess (term wrld)
      (declare (ignore wrld))
      (if (equal term (list 'quote *a*))
          '*a*
        nil))

  Now we submit the following [47m[table][0m event.

    (table user-defined-functions-table
           'untranslate-preprocess
           'my-preprocess)

  This will install [47mmy-preprocess[0m as a preprocessor before the normal
  untranslation routine is applied to printing a term.  When the
  untranslation routine encounters the constant [47m(QUOTE (A B C D))[0m, it
  will replace it with [47m*a*[0m, and the usual untranslation routine will
  print this as [47m*A*[0m.")
 (USER-STOBJS-MODIFIED-WARNINGS
  (TRANS-EVAL STOBJ)
  "Interactions of [47m[trans-eval][0m with [stobj]s that violate applicative
  semantics

  The utility, [47m[trans-eval][0m, may be called to evaluate arbitrary ACL2
  forms.  It can thus be useful for writers of tools.  This topic
  discusses certain [warnings] that may be issued by [47mtrans-eval[0m for
  [stobj] updates that may violate applicative semantics.  Also see
  [trans-eval-and-locally-bound-stobjs] for how [47mtrans-eval[0m relates to
  updates of locally bound stobjs.

  Please see [trans-eval] and [trans-eval-and-stobjs] for relevant
  background.

  Consider the following log.

    ACL2 !>(foo st state)

    ACL2 Warning [User-stobjs-modified] in FOO:  A call of the ACL2 evaluator
    on the term (UPDATE-FLD '4 ST) may have modified the user stobj ST.  See
    :DOC user-stobjs-modified-warnings.

    (4 <state> <st>)
    ACL2 !>

  The warning is intended to indicate that a [stobj] may have been
  modified even though that stobj was accessed indirectly, through
  the ACL2 [state].  If you see such a warning, it is probably caused
  by a utility that you are invoking.  At this time there are no
  special tools for identifying which tool is issuing those warnings,
  but the ``context'' on the first line of the warning --- [47mFOO[0m, above
  --- may give a clue.

  Below we discuss the following events, which were evaluated before
  producing the log above.

    (defstobj st fld)

    (defun foo (st state)
      (declare (xargs :stobjs (st state)
                      :mode :program))
      (let ((st (update-fld 3 st)))
        (mv-let (erp val state)
          (trans-eval '(update-fld 4 st) 'foo state nil)
          (declare (ignore erp val))
          (mv (fld st) state st))))

  After submitting these two forms, we can submit to ACL2 the form [47m(foo
  st state)[0m to produce the log displayed near the top of this topic.
  That log is actually very surprising if you think about it, since
  the [47mtrans-eval[0m call in the definition of [47mfoo[0m modifies only the
  [47mstate[0m parameter, not the [47mst[0m parameter, and yet the value [47mst[0m has
  changed: [47m(fld st)[0m has changed from 3 to 4, while evaluating code in
  which [47mst[0m does not occur free!  Let us discuss this point further.

  First consider the definition of [47mfoo[0m.  Now [47mtrans-eval[0m returns an
  [error-triple], say [47m(mv erp val state)[0m, where [47merp[0m and [47mval[0m are
  ordinary (non-[stobj]) values.  In particular, [47mtrans-eval[0m does not
  return the user-defined stobj, [47mst[0m.  It ``should'' follow, then,
  that the only modification to [47mst[0m before returning is by the form
  [47m(update-fld 3 st)[0m.  So the final value of [47m(fld st)[0m ``should'' be 3;
  yet, it is 4, not 3!  So the first return value of 4, above, can
  very reasonably be considered to violate applicative semantics.
  ACL2 acknowledges this concern --- that is, the concern that an
  operation (i.e., [47mfld[0m) now gives a different result on an object
  (i.e., [47mst[0m) that ``should'' not have changed, thus violating normal
  applicative semantics --- by printing the warning displayed above.

  To see how this can happen, consider that in raw Lisp the stobj, [47mst[0m,
  is actually a one-element array whose unique value is [47m(fld st)[0m.
  The [47mtrans-eval[0m call in [47mfoo[0m replaces that element, in this case 3,
  with a new value, in this case 4.  It does this [3mdestructively[0m: the
  memory location of [47mst[0m is not changed.  Thus, evaluation of [47m(fld st)[0m
  after the [47mtrans-eval[0m call now returns the new array element, which
  is 4.

  Worse yet, there are similar cases where there is [3mno[0m such violation
  of applicative semantics!  We return to this point later below.
  First we provide some additional discussion of such warnings, as
  well as observations for tool writers who want to eliminate the
  warnings.

  In general, such a warning is printed whenever the [47mstobjs-out[0m
  returned in the [47mcar[0m of the value, as discussed above, contains a
  user-defined stobj name, that is, a non-[47mnil[0m value other than [47mstate[0m.

  Fortunately, this behavior can only happen with [47m:[0m[47m[program][0m-mode
  functions; [47mtrans-eval[0m will never be in [47m:[0m[47m[logic][0m mode, and
  therefore, neither will its callers.  Nevertheless, even without
  proving [47mnil[0m one might reasonably be frustrated by this sort of
  violation of applicative semantics.  The warning is, at least, an
  acknowledgment of this situation.

  We next discuss how to write tools that avoid producing such
  warnings, and the advisability (or not) of doing so.

  There may be cases in which you want to write a tool that calls
  [47mtrans-eval[0m and modifies user-defined stobjs, but you don't want the
  users of your tool to see the warning, perhaps because you are
  convinced that no stobj parameter is modified indirectly using
  [47mtrans-eval[0m.  Think carefully about whether you really don't want
  them to see the warning!  After all, they may be relying on normal
  applicative semantics, even with [47m:program[0m-mode functions.

  If indeed you want to avoid warnings, you can call the function
  [47mtrans-eval-no-warning[0m exactly as you call [47mtrans-eval[0m.  For example,
  if you replace [47mtrans-eval[0m by [47mtrans-eval-no-warning[0m in the
  definition above, and then you evaluate [47m(foo st state)[0m, you will
  not see the warning printed above.  Again, consider whether you
  really want to suppress that warning.

  Remark pertaining to [47m(ld ...)[0m.  There is another alternative to
  [47mtrans-eval[0m, [47mtrans-eval-default-warning[0m.  This alternative behaves
  like [47mtrans-eval[0m when the [47mld[0m special,
  [47mld-user-stobjs-modified-warning[0m, is [47mt[0m; otherwise it behaves like
  [47mtrans-eval-no-warning[0m.  See [ld].  There are several calls of
  [47mtrans-eval-default-warning[0m in the ACL2 source code: in function
  [47mld-read-eval-print[0m, which evaluates on behalf of the top-level
  loop, and in some functions that support [events], such as those
  supporting the proof-builder.  But for user-level code it may be
  more appropriate to call [47mtrans-eval[0m so that violations of
  applicative semantics are reported.  These warnings are unimportant
  for the top-level calls of [47mtrans-eval[0m that implement the ACL2
  read-eval-print loop, because one expects stobjs to be updated by
  evaluation.  End of Remark.

  For [trans-eval] and [47mtrans-eval-default-warning[0m, the normal way of
  inhibiting warnings is supported: [47m(set-inhibit-warnings
  \"User-stobjs-modified\")[0m.

  We now elaborate on a point made briefly above, that there are cases
  where the usual violation of applicative semantics does not take
  place.  This happens when the underlying raw Lisp stobj is actually
  replaced, which happens when there is a single stobj field that is
  either an array being resized or a hash table being initialized
  (with the ``clear'' or ``init'' function); see [defstobj].
  Consider the following example.

    (defstobj st2 (ar :type (array t (10)) :resizable t))

    (defun foo2 (st2 state)
      (declare (xargs :stobjs (st2 state)
                      :mode :program))
      (let ((st2 (update-ari 3 'old st2)))
        (mv-let (erp val state)
          (trans-eval '(let ((st2 (resize-ar 20 st2)))
                         (update-ari 3 'new st2))
                      'foo state nil)
          (declare (ignore erp val))
          (mv (ari 3 st2) state st2))))

  After submitting these forms, evaluation of the form [47m(foo2 st2 state)[0m
  produces [47m(OLD <state> <st2>)[0m.  But based on the first example, [47mfoo[0m,
  we might expect that destructive modification of [47mst2[0m would result
  instead in [47m(NEW <state> <st2>)[0m.  Indeed, if the first argument of
  [47mtrans-eval[0m in the definition of [47mfoo2[0m is instead [47m(update-ari 3 'new
  st2))[0m, then the result is [47m(NEW <state> <st2>)[0m.  So why do we get
  the OLD result using the definition of [47mfoo2[0m displayed above?

  The reason is that when a stobj has a single field, and that field is
  an array or hash table, then in raw Lisp the stobj [3mis[0m exactly that
  field.  When we call [47mresize-ar[0m, the entire array is rebuilt, and
  thus the stobj is at a new memory location.  To be precise: After
  the resizing, then the value of [47mst2[0m in the [47muser-stobj-alist[0m of the
  ACL2 state is a new stobj: the actual parameter [47mst2[0m of [47mfoo2[0m is not
  destructively modified.  Thus, normal applicative semantics apply:
  the final value of [47m(fld st2)[0m is independent of the replacement of
  [47mst2[0m in the [47muser-stobj-alist[0m hence is still 3 (from the first
  update).

  We close with a more realistic example.  (It is based on our
  experience modifying the definition of the macro, [47mlocal-test[0m, in
  [community-book] [47mbooks/system/tests/nested-stobj-tests.lisp[0m, when
  we changed ACL2 so that the stobj is the entire array field when
  there is only that one field.)  The [47m[make-event][0m call below fails,
  because the resizing operation replaces the stobj in the global
  [47muser-stobj-alist[0m of the ACL2 [state], but the call of [47mEQUAL[0m still
  references the original stobj.  This failure is thus exactly as
  expected for an applicative semantics.  However, it fails only
  because the resize operation is not destructive: it replaces the
  entire stobj.

    (defstobj st3 (ar3 :type (array t (10)) :resizable t))

    ; Fails (see discussion above):
    (make-event
     (er-progn (trans-eval '(let ((st3 (resize-ar3 30 st3)))
                              (update-ar3i 24 'done st3))
                           'top
                           state t)
               (value (equal (ar3i 24 st3) 'done))
               (value '(value-triple :success))))

    ; Passes because by now, the user-stobj-alist has been updated by
    ; the top-level call of trans-eval to implement the ACL2
    ; read-eval-print loop:
    (assert-event (equal (ar3i 24 st3) 'done))

    ; The following version passes because the second trans-eval call
    ; below references the value of st3 in the user-stobj-alist that was
    ; produced by the first trans-eval call below.
    (make-event
     (er-progn (trans-eval '(let ((st3 (resize-ar3 40 st3)))
                              (update-ar3i 34 'new st3))
                           'top state t)
               (trans-eval '(if (equal (ar3i 34 st3) 'new)
                                (value nil)
                              (er soft 'top \"Failed!\"))
                           'top state t)
               (value '(value-triple :success))))")
 (USING-COMPUTED-HINTS
  (COMPUTED-HINTS HINTS)
  "How to use computed hints

  Computed hints (see [computed-hints]) are extraordinarily powerful.
  We show a few examples here to illustrate their use.  We recommend
  that the [47musing-computed-hints-n[0m topics be read in the order
  [47musing-computed-hints-1[0m, [47musing-computed-hints-2[0m, and so on.


Subtopics

  [Using-computed-hints-1]
      Driving Home the Basics

  [Using-computed-hints-2]
      One Hint to Every Top-Level Goal in a Forcing Round

  [Using-computed-hints-3]
      Hints as a Function of the Goal (not its Name)

  [Using-computed-hints-4]
      Computing the Hints

  [Using-computed-hints-5]
      Debugging Computed Hints

  [Using-computed-hints-6]
      Using the computed-hint-replacement feature

  [Using-computed-hints-7]
      Using the [47mstable-under-simplificationp[0m flag

  [Using-computed-hints-8]
      Some Final Comments")
 (USING-COMPUTED-HINTS-1
  (USING-COMPUTED-HINTS)
  "Driving Home the Basics

  The common hint

    (\"Subgoal 3.2.1''\" :use lemma42)

  has the same effect as the computed hint

    (if (equal id '((0) (3 2 1) . 2))
        '(:use lemma42)
        nil)

  which, of course, is equivalent to

    (and (equal id '((0) (3 2 1) . 2))
         '(:use lemma42))

  which is also equivalent to the computed hint

    my-special-hint

  provided the following [47mdefun[0m has first been executed

    (defun my-special-hint (id clause world)
      (declare (xargs :mode :program)
               (ignore clause world))
      (if (equal id '((0) (3 2 1) . 2))
          '(:use lemma42)
          nil))

  It is permitted for the [47mdefun[0m to be in :LOGIC mode (see [defun-mode])
  also.

  Just to be concrete, the following three events all behave the same
  way (if [47mmy-special-hint[0m is as above):

    (defthm main (big-thm a b c)
      :hints ((\"Subgoal 3.2.1''\" :use lemma42)))

    (defthm main (big-thm a b c)
      :hints ((and (equal id '((0) (3 2 1) . 2)) '(:use lemma42))))

    (defthm main (big-thm a b c)
      :hints (my-special-hint))")
 (USING-COMPUTED-HINTS-2
  (USING-COMPUTED-HINTS)
  "One Hint to Every Top-Level Goal in a Forcing Round

  Suppose the main proof completes with a forcing round on three
  subgoals, \"[1]Subgoal 3\", \"[1]Subgoal 2\", and \"[1]Subgoal 1\".
  Suppose you wish to [47m:use lemma42[0m in all top-level goals of the
  first forcing round.  This can be done supplying the hint

    (if test '(:use lemma42) nil),

  where [47mtest[0m is an expression that returns [47mt[0m when [47mID[0m is one of the
  clause ids in question.

        goal-spec     (parse-clause-id goal-spec)

    \"[1]Subgoal 3\"        ((1) (3) . 0)
    \"[1]Subgoal 2\"        ((1) (2) . 0)
    \"[1]Subgoal 1\"        ((1) (1) . 0)

  Recall (see [clause-identifier]) that [47mparse-clause-id[0m maps from a
  goal spec to a clause id, so you can use that function on the goal
  specs printed in the failed proof attempt to determine the clause
  ids in question.

  So one acceptable [47mtest[0m is

    (member-equal id '(((1) (3) . 0)
                       ((1) (2) . 0)
                       ((1) (1) . 0)))

  or you could use [47mparse-clause-id[0m in your computed hint if you don't
  want to see clause ids in your script:

    (or (equal id (parse-clause-id \"[1]Subgoal 3\"))
        (equal id (parse-clause-id \"[1]Subgoal 2\"))
        (equal id (parse-clause-id \"[1]Subgoal 1\")))

  or you could use the inverse function (see [clause-identifier]):

    (member-equal (string-for-tilde-@-clause-id-phrase id)
                  '(\"[1]Subgoal 3\"
                    \"[1]Subgoal 2\"
                    \"[1]Subgoal 1\"))

  Recall that what we've shown above are the tests to use in the
  computed hint.  The hint itself is [47m(if test '(:use lemma42) nil)[0m or
  something equivalent like [47m(and test '(:use lemma42))[0m.

  The three tests above are all equivalent.  They suffer from the
  problem of requiring the explicit enumeration of all the goal specs
  in the first forcing round.  A change in the script might cause
  more forced subgoals and the ones other than those enumerated would
  not be given the hint.

  You could write a test that recognizes all first round top-level
  subgoals no matter how many there are.  Just think of the
  programming problem: how do I recognize all the clause id's of the
  form [47m((1) (n) . 0)[0m?  Often you can come to this formulation of the
  problem by using [47mparse-clause-id[0m on a few of the candidate
  goal-specs to see the common structure.  A suitable test in this
  case is:

    (and (equal (car id) '(1))     ; forcing round 1, top-level (pre-induction)
         (equal (len (cadr id)) 1) ; Subgoal n (not Subgoal n.i ...)
         (equal (cddr id) 0))      ; no primes

  The test above is ``overkill'' because it recognizes precisely the
  clause ids in question.  But recall that once a computed hint is
  used, it is (by default) removed from the hints available to the
  children of the [clause].  Thus, we can widen the set of clause ids
  recognized to include all the children without worrying that the
  hint will be applied to those children.

  In particular, the following test supplies the hint to every
  top-level goal of the first forcing round:

    (equal (car id) '(1))

  You might worry that it would also supply the hint to the subgoal
  produced by the hint --- the cases we ruled out by the ``overkill''
  above.  But that doesn't happen since the hint is unavailable to
  the children.  You could even write:

    (equal (car (car id)) 1)

  which would supply the hint to every goal of the form \"[1]Subgoal
  ...\"  and again, because we see and fire on the top-level goals
  first, we will not fire on, say, \"[1]Subgoal *1.3/2\", i.e., the id
  '((1 1 3) (2) . 0) even though the test recognizes that id.

  Finally, the following test supplies the hint to every top-level goal
  of every forcing round (except the 0th, which is the ``gist'' of
  the proof, not ``really'' a forcing round):

    (not (equal (car (car id)) 0))

  Recall again that in all the examples above we have exhibited the
  [47mtest[0m in a computed hint of the form [47m(if test '(:key1 val1 ...)
  nil)[0m.")
 (USING-COMPUTED-HINTS-3
  (USING-COMPUTED-HINTS)
  "Hints as a Function of the Goal (not its Name)

  Sometimes it is desirable to supply a hint whenever a certain term
  arises in a conjecture.  For example, suppose we have proved

    (defthm all-swaps-have-the-property
       (the-property (swap x))
       :rule-classes nil)

  and suppose that whenever [47m(SWAP A)[0m occurs in a goal, we wish to add
  the additional hypothesis that [47m(THE-PROPERTY (SWAP A))[0m.  Note that
  this is equivalent supplying the hint

    (if test
        '(:use (:instance all-swaps-have-the-property (x A)))
        nil)

  where [47mtest[0m answers the question ``does the [clause] contain [47m(SWAP
  A)[0m?'' That question can be asked with [47m(occur-lst '(SWAP A) clause)[0m.
  Briefly, [47moccur-lst[0m takes the representation of a translated term,
  x, and a list of translated terms, y, and determines whether x
  occurs as a subterm of any term in y.  (By ``subterm'' here we mean
  proper or improper, e.g., the subterms of [47m(CAR X)[0m are [47mX[0m and [47m(CAR
  X)[0m.)

  Thus, the computed hint:

    (if (occur-lst '(swap a) clause)
        '(:use (:instance all-swaps-have-the-property (x A)))
        nil)

  will add the hypothesis [47m(THE-PROPERTY (SWAP A))[0m to every goal
  containing [47m(SWAP A)[0m --- except the children of goals to which the
  hypothesis was added.

  [31;1mA COMMON MISTAKE[0m users are likely to make is to forget that they are
  dealing with translated terms.  For example, suppose we wished to
  look for [47m(SWAP (LIST 1 A))[0m with [47moccur-lst[0m.  We would never find it
  with

    (occur-lst '(SWAP (LIST 1 A)) clause)

  because that presentation of the term contains macros and other
  abbreviations.  By using :trans (see [trans]) we can obtain the
  translation of the target term.  Then we can look for it with:

    (occur-lst '(SWAP (CONS '1 (CONS A 'NIL))) clause)

  Note in particular that you must

    * eliminate all macros and
    * explicitly quote all constants.

  We recommend using [47m:trans[0m to obtain the translated form of the terms
  in which you are interested, before programming your hints.

  An alternative is to use the expression [47m(prettyify-clause clause nil
  nil)[0m in your hint to convert the current goal clause into the
  s-expression that is actually printed.  For example, the clause

    ((NOT (CONSP X)) (SYMBOLP Y) (EQUAL (CONS '1 (CAR X)) Y))

  ``prettyifies'' to

    (IMPLIES (AND (CONSP X)
                  (NOT (SYMBOLP Y)))
             (EQUAL (CONS 1 (CAR X)) Y))

  which is what you would see printed by ACL2 when the goal clause is
  that shown.

  However, if you choose to convert your clauses to prettyified form,
  you will have to write your own explorers (like our [47moccur-lst[0m),
  because all of the ACL2 term processing utilities work on
  translated and/or clausal forms.  This should not be taken as a
  terrible burden.  You will, at least, gain the benefit of knowing
  what you are really looking for, because your explorers will be
  looking at exactly the s-expressions you see at your terminal.  And
  you won't have to wade through our still undocumented term/clause
  utilities.  The approach will slow things down a little, since you
  will be paying the price of independently consing up the
  prettyified term.

  We make one more note on this example.  We said above that the
  computed hint:

    (if (occur-lst '(swap a) clause)
        '(:use (:instance all-swaps-have-the-property (x A)))
        nil)

  will add the hypothesis [47m(THE-PROPERTY (SWAP A))[0m to every goal
  containing [47m(SWAP A)[0m --- except the children of goals to which the
  hypothesis was added.

  It bears noting that the subgoals produced by induction and top-level
  forcing round goals are not children.  For example, suppose the
  hint above fires on \"Subgoal 3\" and produces, say, \"Subgoal 3'\".
  Then the hint will not fire on \"Subgoal 3'\" even though it (still)
  contains [47m(SWAP A)[0m because \"Subgoal 3'\" is a child of a goal on
  which the hint fired.

  But now suppose that \"Subgoal 3'\" is pushed for induction.  Then the
  goals created by that induction, i.e., the base case and induction
  step, are not considered children of \"Subgoal 3'\".  All of the
  original hints are available.

  Alternatively, suppose that \"Subgoal 3' is proved but forces some
  other subgoal, \"[1]Subgoal 1\" which is attacked in Forcing Round 1.
  That top-level forced subgoal is not a child.  All the original
  hints are available to it.  Thus, if it contains [47m(SWAP A)[0m, the hint
  will fire and supply the hypothesis, producing \"[1]Subgoal 1'\".
  This may be unnecessary, as the hypothesis might already be present
  in \"[1]Subgoal 1\".  In this case, no harm is done.  The hint won't
  fire on \"[1]Subgoal 1'\" because it is a child of \"[1]Subgoal 1\" and
  the hint fired on that.")
 (USING-COMPUTED-HINTS-4
  (USING-COMPUTED-HINTS)
  "Computing the Hints

  So far we have used computed hints only to compute when a fixed set
  of keys and values are to be used as a hint.  But computed hints
  can, of course, compute the set of keys and values.  You might, for
  example, write a hint that recognizes when a [clause] ``ought'' to
  be provable by a [47m:BDD[0m hint and generate the appropriate hint.  You
  might build in a set of useful lemmas and check to see if the
  clause is provable [47m:BY[0m one of them.  You can keep all function
  symbols disabled and use computed hints to compute which ones you
  want to [47m:EXPAND[0m.  In general, you can write a theorem prover for
  use in your hints, provided you can get it to do its job by
  directing our theorem prover.

  Suppose for example we wish to find every occurrence of an instance
  of [47m(SWAP x)[0m and provide the corresponding instance of
  [47mALL-SWAPS-HAVE-THE-PROPERTY[0m.  Obviously, we must explore the clause
  looking for instances of [47m(SWAP x)[0m and build the appropriate
  instances of the lemma.  We could do this in many different ways,
  but below we show a general purpose set of utilities for doing it.
  The functions are not defined in ACL2 but could be defined as
  shown.

  Our plan is: (1) Find all instances of a given pattern (term) in a
  clause, obtaining a set of substitutions.  (2) Build a set of
  [47m:instance[0m expressions for a given lemma name and set of
  substitutions.  (3) Generate a [47m:use[0m hint for those instances when
  instances are found.

  The pair of functions below find all instances of a given pattern
  term in either a term or a list of terms.  The functions each
  return a list of substitutions, each substitution accounting for
  one of the matches of pat to a subterm.  At this level in ACL2
  substitutions are lists of pairs of the form [47m(var . term)[0m.  All
  terms mentioned here are presumed to be in translated form.

  The functions take as their third argument a list of substitutions
  accumulated to date and add to it the substitutions produced by
  matching pat to the subterms of the term.  We intend this
  accumulator to be nil initially.  If the returned value is nil,
  then no instances of pat occurred.

    (mutual-recursion

    (defun find-all-instances (pat term alists)
     (declare (xargs :mode :program))
     (mv-let
      (instancep alist)
      (one-way-unify pat term)
      (let ((alists (if instancep (add-to-set-equal alist alists) alists)))
        (cond
         ((variablep term) alists)
         ((fquotep term) alists)
         (t (find-all-instances-list pat (fargs term) alists))))))

    (defun find-all-instances-list (pat list-of-terms alists)
     (declare (xargs :mode :program))
     (cond
      ((null list-of-terms) alists)
      (t (find-all-instances pat
                             (car list-of-terms)
                             (find-all-instances-list pat
                                                      (cdr list-of-terms)
                                                      alists))))))

  Caveat: The following aside has nothing to do with computed hints.
  Does an instance of [47m(CAR (CDR x))[0m occur in [47m((LAMBDA (V) (CAR V))
  (CDR A))[0m?  It does if one beta-reduces the lambda-expression to
  [47m(CAR (CDR A))[0m; the appropriate substitution is to replace [47mx[0m by [47mA[0m.
  But the definition of [47mfind-all-instances[0m above does [3mnot[0m find this
  instance because it does not do beta-reduction.

  We now turn our attention to converting a list of substitutions into
  a list of lemma instances, each of the form

    (:INSTANCE name (var1 term1) ... (vark termk))

  as written in [47m:use[0m hints.  In the code shown above, substitutions are
  lists of pairs of the form [47m(var . term)[0m, but in lemma instances we
  must write ``doublets.'' So here we show how to convert from one to
  the other:

    (defun pairs-to-doublets (alist)
      (declare (xargs :mode :program))
      (cond ((null alist) nil)
            (t (cons (list (caar alist) (cdar alist))
                     (pairs-to-doublets (cdr alist))))))

  Now we can make a list of lemma instances:

    (defun make-lemma-instances (name alists)
      (declare (xargs :mode :program))
      (cond
       ((null alists) nil)
       (t (cons (list* :instance name (pairs-to-doublets (car alists)))
                (make-lemma-instances name (cdr alists))))))

  Finally, we can package it all together into a hint function.  The
  function takes a pattern, [47mpat[0m, which must be a translated term, the
  name of a lemma, [47mname[0m, and a clause.  If some instances of [47mpat[0m
  occur in [47mclause[0m, then the corresponding instances of [47mname[0m are [47m:USE[0md
  in the computed hint.  Otherwise, the hint does not apply.

    (defun add-corresponding-instances (pat name clause)
      (declare (xargs :mode :program))
      (let ((alists (find-all-instances-list pat clause nil)))
        (cond
         ((null alists) nil)
         (t (list :use (make-lemma-instances name alists))))))

  The design of this particular hint function makes it important that
  the variables of the pattern be the variables of the named lemma
  and that all of the variables we wish to instantiate occur in the
  pattern.  We could, of course, redesign it to allow ``free
  variables'' or some sort of renaming.

  We could now use this hint as shown below:

    (defthm ... ...
      :hints ((add-corresponding-instances
               '(SWAP x)
               'ALL-SWAPS-HAVE-THE-PROPERTY
               clause)))

  The effect of the hint above is that any time a clause arises in
  which any instance of [47m(SWAP x)[0m appears, we add the corresponding
  instance of [47mALL-SWAPS-HAVE-THE-PROPERTY[0m.  So for example, if
  Subgoal *1/3.5 contains the subterm [47m(SWAP (SWAP A))[0m then this hint
  fires and makes the system behave as though the hint:

    (\"Subgoal *1/3.5\"
     :USE ((:INSTANCE ALL-SWAPS-HAVE-THE-PROPERTY (X A))
           (:INSTANCE ALL-SWAPS-HAVE-THE-PROPERTY (X (SWAP A)))))

  had been present.")
 (USING-COMPUTED-HINTS-5
  (USING-COMPUTED-HINTS)
  "Debugging Computed Hints

  We have found that it is sometimes helpful to define hints so that
  they print out messages to the terminal when they fire, so you can
  see what hint was generated and which of your computed hints did
  it.

  To that end we have defined a macro we sometimes use.  Suppose you
  have a [47m:hints[0m specification such as:

    :hints (computed-hint-fn (hint-expr id))

  If you defmacro the macro below you could then write instead:

    :hints ((show-hint computed-hint-fn 1)
            (show-hint (hint-expr id) 2))

  with the effect that whenever either hint is fired (i.e., returns
  non-[47mnil[0m), a message identifying the hint by the marker (1 or 2,
  above) and the non-[47mnil[0m value is printed.

    (defmacro show-hint (hint &optional marker)
      (cond
       ((and (consp hint)
             (stringp (car hint)))
        hint)
       (t
        `(let ((marker ,marker)
               (ans ,(if (symbolp hint)
                         `(,hint id clause world stable-under-simplificationp)
                       hint)))
           (if ans
               (prog2$
                (cw \"~%***** Computed Hint~#0~[~/ (from hint ~x1)~]~%~x2~%~%\"
                    (if (null marker) 0 1)
                    marker
                    (cons (string-for-tilde-@-clause-id-phrase id)
                          ans))
                ans)
             nil)))))

  Note that when [47mshow-hint[0m is applied to a hint that is a symbol, e.g.,
  [47mcomputed-hint-fn[0m, it applies the symbol to the four computed-hint
  arguments: [47mid[0m, [47mclause[0m, [47mworld[0m, and [47mstable-under-simplificationp[0m.  If
  [47mcomputed-hint-fn[0m is of arity 3 the code above would cause an error.
  One way to avoid it is to write

    :hints ((show-hints (computed-hint-fn id clause world) 1)
            (show-hint (hint-expr id) 2)).

  If you only use computed hints of arity 3, you might eliminate the
  occurrence of [47mstable-under-simplificationp[0m in the definition of
  [47mshow-hint[0m above.

  Putting a [47mshow-hint[0m around a common hint has no effect.  If you find
  yourself using this utility let us know and we'll consider putting
  it into the system itself.  But it does illustrate that you can use
  computed hints to do unusual things.")
 (USING-COMPUTED-HINTS-6
  (USING-COMPUTED-HINTS)
  "Using the computed-hint-replacement feature

  So far none of our computed hints have used the
  [47m:COMPUTED-HINT-REPLACEMENT[0m feature.  We now illustrate that.

  The [47m:computed-hint-replacement[0m feature can easily lead to loops.  So
  as you experiment with the examples in this section and your own
  hints using this feature, be ready to interrupt the theorem prover
  and abort!

  A non-looping use of the [47m:computed-hint-replacement[0m feature would be
  a hint like this:

    (if (certain-terms-present clause)
        '(:computed-hint-replacement t
          :in-theory (enable lemma25))
        '(:computed-hint-replacement t
          :in-theory (disable lemma25)))

  In this hint, if certain terms are present in [47mclause[0m, as determined
  by the function with the obvious name (here undefined), then this
  hint enables [47mlemma25[0m and otherwise disables it.  [47mLemma25[0m might be a
  very expensive lemma, e.g., one that matches frequently and has an
  expensive and rarely established hypothesis.  One might wish it
  enabled only under certain conditions.  Recall that theories are
  inherited by children.  So once [47mlemma25[0m is enabled it ``stays''
  enabled for the children, until disabled; and vice versa.  If the
  [47m:computed-hint-replacement[0m feature were not present and computed
  hints were always deleted after they had been used, then [47mlemma25[0m
  would be left enabled (or disabled) for all the children produced
  by the first firing of the hint.  But with the arrangement here,
  every subgoal gets a theory deemed suitable by the hint, and the
  hint persists.

  Now we will set up a toy to allow us to play with computed hints to
  understand them more deeply.  To follow the discussion it is best
  to execute the following events.

    (defstub wrapper (x) t)
    (defaxiom wrapper-axiom (wrapper x) :rule-classes nil)

  Now submit the following event and watch what happens.

    (thm (equal u v)
      :hints (`(:use (:instance wrapper-axiom (x a)))))

  The theorem prover adds [47m(wrapper a)[0m to the goal and then abandons the
  proof attempt because it cannot prove the subgoal.  Since the
  computed hint is deleted upon use, the hint is not applied to the
  subgoal (i.e., the child of the goal).

  What happens if we do the following?

    (thm (equal u v)
      :hints (`(:computed-hint-replacement t
                :use (:instance wrapper-axiom (x a)))))

  As one might expect, this loops forever: The hint is applied to the
  child and adds the hypothesis again.  When the hint fires, nothing
  is actually changed, since [47m(wrapper a)[0m is already in the subgoal.

  So let's change the experiment a little.  Let's make the hint add the
  hypothesis [47m(wrapper p)[0m where [47mp[0m is the first literal of the
  [clause].  This is silly but it allows us to explore the behavior
  of computed hints a little more.

    (thm (equal u v)
      :hints (`(:use (:instance wrapper-axiom (x ,(car clause))))))

  So in this case, the theorem prover changes the goal to

    (IMPLIES (WRAPPER (EQUAL U V)) (EQUAL U V))

  which then simplifies to

    (IMPLIES (WRAPPER NIL) (EQUAL U V))

  because the concluding equality can be assumed false in the
  hypothesis (e.g., think of the contrapositive version).  Nothing
  else happens because the hint has been removed and so is not
  applicable to the child.

  Now consider the following --- and be ready to interrupt it and
  abort!

    (thm (equal u v)
      :hints (`(:computed-hint-replacement t
                :use (:instance wrapper-axiom (x ,(car clause))))))

  This time the hint is not removed and so is applied to the child.  So
  from [47mGoal[0m we get

    Goal'
    (IMPLIES (WRAPPER (EQUAL U V))
             (EQUAL U V))

  and then

    Goal''
    (IMPLIES (AND (WRAPPER (NOT (WRAPPER (EQUAL U V))))
                  (WRAPPER (EQUAL U V)))
             (EQUAL U V))

  etc.

  First, note that the hint is repeatedly applied to its children.
  That is because we wrote [47m:computed-hint-replacement t[0m.  But second,
  note that [47mGoal'[0m is not even being simplified before [47mGoal''[0m is
  produced from it.  If it were being simplified, the [47m(equal u v)[0m's
  in the hypotheses would be replaced by [47mnil[0m.  This is a feature.  It
  means after a computed hint has fired, other hints are given a
  chance at the result, even the hint itself unless it is removed
  from the list of hints.

  As an exercise, let's arrange for the hint to stay around and be
  applied indefinitely but with a simplification between each use of
  the hint.  To do this we need to pass information from one
  application of the hint to the next, essentially to say ``stay
  around but don't fire.''

  First, we will define a function to use in the hint.  This is more
  than a mere convenience; it allows the hint to ``reproduce itself''
  in the replacement.

    (defun wrapper-challenge (clause parity)
      (if parity
          `(:computed-hint-replacement ((wrapper-challenge clause nil))
            :use (:instance wrapper-axiom (x ,(car clause))))
          `(:computed-hint-replacement ((wrapper-challenge clause t)))))

  Note that this function is not recursive, even though it uses its own
  name.  That is because the occurrence of its name is in a quoted
  constant.

  Now consider the following.  What will it do?

    (thm (equal u v)
      :hints ((wrapper-challenge clause t)))

  First, observe that this is a legal hint because it is a term that
  mentions only the free variable [47mCLAUSE[0m.  When defining hint
  functions you may sometimes think their only arguments are the four
  variables [47mid[0m, [47mclause[0m, [47mworld[0m, and [47mstable-under-simplificationp[0m.
  That is not so.  But in your hints you must call those functions so
  that those are the only free variables.  Note also that the
  occurrence of [47mclause[0m inside the [47m:computed-hint-replacement[0m is not
  an occurrence of the variable clause but just a constant.  Just
  store this note away for a moment.  We'll return to it momentarily.

  Second, the basic cleverness of this hint is that every time it fires
  it reproduces itself with the opposite parity.  When the parity is
  [47mt[0m it actually changes the goal by adding a hypothesis.  When the
  parity is [47mnil[0m it doesn't change the goal and so allows
  simplification to proceed --- but it swaps the parity back to [47mt[0m.
  What you can see with this simple toy is that we can use the
  computed hints to pass information from parent to child.

  Ok, so what happens when the event above is executed?  Try it.  You
  will see that ACL2 applied the hint the first time.  It doesn't get
  around to printing the output because an error is caused before it
  can print.  But here is a blow-by-blow description of what happens.
  The hint is evaluated on [47mGoal[0m with the [47mclause[0m [47m((equal u v))[0m.  It
  produces a hint exactly as though we had typed:

    (\"Goal\" :use (:instance wrapper-axiom (x (equal u v))))

  which is applied to this goal. In addition, it produces the new hints
  argument

    :hints ((wrapper-challenge clause nil)).

  By applying the [47m\"Goal\"[0m hint we get the new subgoal

    Goal'
    (implies (wrapper (equal u v))
             (equal u v))

  but this is not printed because, before printing it, the theorem
  prover looks for hints to apply to it and finds

    (wrapper-challenge clause nil)

  That is evaluated and produces a hint exactly as though we had typed:

    (\"Goal'\" )

  and the new hints argument:

    :hints ((wrapper-challenge clause nil)).

  But if you supply the hint [47m(\"Goal'\" )[0m, ACL2 will signal an error
  because it does not allow you to specify an empty hint!

  So the definition of [47mwrapper-challenge[0m above is almost correct but
  fatally flawed.  We need a non-empty ``no-op'' hint.  One such hint
  is to tell the system to expand a term that will always be expanded
  anyway.  So undo [47mwrapper-challenge[0m, redefine it, and try the proof
  again.  Now remember the observation about [47mclause[0m that we asked you
  to ``store'' above.  The new definition of [47mwrapper-challenge[0m
  illustrates what we meant.  Note that the first formal parameter of
  [47mwrapper-challenge[0m, below, is no longer named [47mclause[0m but is called
  [47mcl[0m instead.  But the ``call'' of [47mwrapper-challenge[0m in the
  replacements is on [47mclause[0m.  This may seem to violate the rule that
  a function definition cannot use variables other than the formals.
  But the occurrences of [47mclause[0m below are not variables but constants
  in an object that will eventually be treated as a hint term.

    :ubt wrapper-challenge

    (defun wrapper-challenge (cl parity)
      (if parity
          `(:computed-hint-replacement ((wrapper-challenge clause nil))
            :use (:instance wrapper-axiom (x ,(car cl))))
          `(:computed-hint-replacement ((wrapper-challenge clause t))
            :expand ((atom zzz)))))

    (thm (equal u v)
      :hints ((wrapper-challenge clause t)))

  This time, things go as you might have expected!  [47mGoal'[0m is produced
  and simplified, to

    Goal''
    (implies (wrapper nil)
             (equal u v)).

  Simplification gets a chance because when the new hint
  [47m(wrapper-challenge clause nil)[0m is fired it does not change the
  goal.  But it does change the parity in the hints argument so that
  before [47mGoal''[0m is simplified again, the hint fires and adds the
  hypothesis:

    Goal'''
    (IMPLIES (AND (WRAPPER (NOT (WRAPPER NIL)))
                  (WRAPPER NIL))
             (EQUAL U V)).

  This simplifies, replacing the first [47m(NOT (WRAPPER NIL))[0m by [47mNIL[0m,
  since [47m(WRAPPER NIL)[0m is known to be true here.  Thus the goal
  simplifies to

    Goal'4'
    (IMPLIES (WRAPPER NIL) (EQUAL U V)).

  The process repeats indefinitely.

  So we succeeded in getting a hint to fire indefinitely but allow a
  full simplification between rounds.")
 (USING-COMPUTED-HINTS-7
  (USING-COMPUTED-HINTS)
  "Using the [47mstable-under-simplificationp[0m flag

  A problem with the example in [using-computed-hints-6] is that
  exactly one simplification occurs between each (effective) firing
  of the hint.  Much more commonly we wish to fire a hint once a
  subgoal has become stable under simplification.

  A classic example of this is when we are dealing with an interpreter
  for some state machine.  We typically do not want the ``step''
  function to open up on the symbolic representation of a state until
  that state has been maximally simplified.  We will illustrate with
  a simple state machine.

  Let us start by defining the step function, [47mstp[0m, and the
  corresponding [47mrun[0m function that applies it a given number of times.

    (defun stp (s)
      (+ 1 s))

    (defun run (s n)
      (if (zp n)
          s
          (run (stp s) (- n 1))))

  The step function here is trivial: a state is just a number and the
  step function increments it.  In this example we will not be
  interested in the theorems we prove but in how we prove them.  The
  formula we will focus on is

    (thm (equal (run s 7) xxx))

  This is not a theorem, of course.  But we want to test our advice on
  non-theorems because we do not want the advice to work only for
  proofs that succeed.  (In the past, we gave advice about using
  computed hints and that advice caused the theorem prover to run
  forever when given formulas that it couldn't prove --- but most of
  the time the system is presented with formulas it cannot prove!)

  Furthermore, without some kind of additional rules, the [47m(run s 7)[0m
  expression in the conjecture above will not expand at all, because
  ACL2's heuristics do not approve.

  In fact, we do not want to take chances that [47mrun[0m will be expanded ---
  we want to control its expansion completely.  Therefore, disable
  [47mrun[0m.

    (in-theory (disable run))

  Now, what do we want?  (That is always a good question to ask!)  We
  want [47m(run s 7)[0m to expand ``slowly.'' In particular, we want it to
  expand once, to [47m(run (stp s) 6)[0m.  Then we want the [47mstp[0m to be
  expanded and fully simplified before the [47mrun[0m expression is expanded
  again.  That is, we want to force the expansion of [47mrun[0m whenever the
  goal is stable under simplification.  This is sometimes called
  ``staged simplification.''

  We can achieve staged simplification for any given function symbol by
  defining the functions shown below and then using a simple computed
  hint:

    (thm (equal (run s 7) xxx)
         :hints ((stage run)))

  By inspecting how [47mstage[0m is defined you can see how to extend it, but
  we explain as we go.  To experiment, you can just paste the
  definitions (and defmacro) below into your ACL2 shell and then try
  the [47mthm[0m command.

  First, define this pair of mutually recursive functions.
  [47mFind-first-call[0m finds the first call of the function symbol [47mfn[0m in a
  given term.

    (mutual-recursion
     (defun find-first-call (fn term)
     ; Find the first call of fn in term.
      (cond ((variablep term) nil)
            ((fquotep term) nil)
            ((equal (ffn-symb term) fn)
             term)
            (t (find-first-call-lst fn (fargs term)))))
     (defun find-first-call-lst (fn lst)
     ; Find the first call of fn in a list of terms.
      (cond ((endp lst) nil)
            (t (or (find-first-call fn (car lst))
                   (find-first-call-lst fn (cdr lst)))))))

  We will arrange for the computed hint to generate an [47m:EXPAND[0m hint for
  the first call of [47mfn[0m, whenever the goal becomes stable under
  simplification.  If no call is found, the hint will do nothing.  To
  make sure the hint will not loop indefinitely (for example, by
  forcing [47mfn[0m to expand only to have the rewriter ``fold'' it back up
  again), we will provide the hint with a bound that stops it after
  some number of iterations.  Here is the basic function that creates
  the [47mexpand[0m hint and replaces itself to count down.

    (defun stage1 (fn max clause flg)
    ; If the clause is stable under simplification and there is a call of
    ; fn in it, expand it.  But don't do it more than max times.
     (let ((temp (and flg
                      (find-first-call-lst fn clause))))
       (if temp
           (if (zp max)
               (cw \"~%~%HINT PROBLEM:  The maximum repetition count of ~
                    your STAGE hint has been reached without eliminating ~
                    all of the calls of ~x0.  You could supply a larger ~
                    count with the optional second argument to STAGE ~
                    (which defaults to 100).  But think about what is ~
                    happening! Is each stage permanently eliminating a ~
                    call of ~x0?~%~%\"
                   fn)
             `(:computed-hint-replacement
                ((stage1 ',fn ,(- max 1)
                         clause
                         stable-under-simplificationp))
               :expand (,temp)))
         nil)))

  Suppose that when [47mstage1[0m is called, [47mfn[0m is the function we want to
  expand, [47mmax[0m is the maximum number of iterations of this expansion,
  [47mclause[0m is the current goal [clause], and [47mflg[0m is the value of the
  [47mstable-under-simplificationp[0m flag.  Then if [47mclause[0m is stable and we
  can find a call of [47mfn[0m in it, we ask whether [47mmax[0m is exhausted.  If
  so, we print an ``error message'' to the comment window with [47m[cw][0m
  and return [47mnil[0m (the value of [47mcw[0m).  That [47mnil[0m means the hint does
  nothing.  But if [47mmax[0m is not yet exhausted, we return a new hint.
  As you can see above, the hint replaces itself with another [47mstage1[0m
  hint with the same [47mfn[0m and a decremented [47mmax[0m to be applied to the
  new [47mclause[0m and the then-current value of
  [47mstable-under-simplificationp[0m.  The hint also contains an [47m:expand[0m
  directive for the call of [47mfn[0m found.

  Thus, if the computed hint was:

    (stage1 'run 5 clause stable-under-simplificationp)

  and [47m(run s 7)[0m occurs in the clause, then it will generate

    (:computed-hint-replacement
      ((stage1 'run 4 clause stable-under-simplificationp))
     :expand ((run s 7)))

  which will in turn replace the old [47mstage1[0m hint with the new one and
  will apply [47m:expand ((run s 7))[0m to the current goal.

  We can make this more convenient by defining the macro:

    (defmacro stage (fn &optional (max '100))
     `(stage1 ',fn ,max clause stable-under-simplificationp))

  Note that the macro allows us to either provide the maximum bound or
  let it default to 100.

  Henceforth, we can type

    (thm (equal (run s 7) xxx)
         :hints ((stage run)))

  to stage the opening of [47mrun[0m up to 100 times, or we can write

    (thm (equal (run s 7) xxx)
         :hints ((stage run 5)))

  to stage it only 5 times.  In the latter example, the system will
  print an ``error message'' after the fifth expansion.

  Note that if we executed

    (set-default-hints '((stage run)))

  then we could attack all theorems (involving [47mrun[0m) with staged
  simplification (up to bound 100), without typing an explicit hint.

    (thm (equal (run s 7) xxx))

  Using techniques similar to those above we have implemented
  ``priority phased simplification'' and provided it as a book.  See
  community book [47mbooks/misc/priorities.lisp[0m.  This is an idea
  suggested by Pete Manolios, by which priorities may be assigned to
  rules and then the simplifier simplifies each subgoal maximally
  under the rules of a given priority before enabling the rules of
  the next priority level.  The book above documents both how we
  implement it with computed hints and how to use it.

  Here is another example of using the [47mstable-under-simplificationp[0m
  flag to delay certain actions.  It defines a default hint, see
  [default-hints], which will enable [non-linear-arithmetic] on
  precisely those goals which are stable-under-simplificationp.  It
  also uses the [47mHISTORY[0m and [47mPSPV[0m variables to determine when toggling
  [non-linear-arithmetic] is appropriate.  These variables are
  documented only in the source code.  If you start using these
  variables extensively, please contact the developers of ACL2 or
  Robert Krug ([47mrkrug@cs.utexas.edu[0m) and let us know how we can help.

    (defun nonlinearp-default-hint (stable-under-simplificationp hist pspv)
      (cond (stable-under-simplificationp
             (if (not (access rewrite-constant
                              (access prove-spec-var pspv :rewrite-constant)
                              :nonlinearp))
                 '(:computed-hint-replacement t
                   :nonlinearp t)
               nil))
            ((access rewrite-constant
                     (access prove-spec-var pspv :rewrite-constant)
                     :nonlinearp)
             (if (not (equal (caar hist) 'SETTLED-DOWN-CLAUSE))
                 '(:computed-hint-replacement t
                   :nonlinearp nil)
               nil))
            (t
             nil)))")
 (USING-COMPUTED-HINTS-8
  (USING-COMPUTED-HINTS)
  "Some Final Comments

  None of the examples show the use of the variable [47mWORLD[0m, which is
  allowed in computed hints.  There are some (undocumented) ACL2
  utilities that might be useful in programming hints, but these
  utilities need access to the ACL2 logical world (see [world]).

  A very useful fact to know is that [47m(table-alist name world)[0m returns
  an alist representation of the current value of the [47m[table][0m named
  [47mname[0m.

  The ACL2 source code is littered with [47m:[0m[47m[program][0m mode functions for
  manipulating world.  In our source code, the world is usually bound
  a variable named [47mwrld[0m; so searching our code for that name might be
  helpful.

  Using these utilities to look at the [47mWORLD[0m one can, for example,
  determine whether a symbol is defined recursively or not, get the
  body and formals of a defined function, or fetch the statement of a
  given lemma.  Because these utilities are not yet documented, we do
  not expect users to employ [47mWORLD[0m in computed hints.  But experts
  might and it might lead to the formulation of a more convenient
  language for computed hints.

  None of our examples illustrated the 7 argument form of a computed
  hint, [47m(fn ID CLAUSE WORLD STABLE-UNDER-SIMPLIFICATIONP HIST PSPV
  CTX)[0m.  When used, the variables [47mHIST[0m, [47mPSPV[0m, and [47mCTX[0m, are bound to
  the [clause] history, the package of ``special variables''
  governing the clause, and the ``error message context.'' These
  variables are commonly used throughout our source code but are,
  unfortunately, undocumented.  Again, we expect a few experts will
  find them useful in developing computed hints.

  If you start using computed hints extensively, please contact the
  developers of ACL2 and let us know what you are doing with them and
  how we can help.")
 (USING-ENABLED-RULES
  (THEORIES)
  "Avoiding [47m:use[0m [hints] for [enable]d [47m:[0m[47m[rewrite][0m rules

  Consider the following (admittedly silly) example.

    (thm (equal (append (append x y) z) (append x y z))
         :hints ((\"Subgoal *1/1\" :use cdr-cons)))

  ACL2's output includes the following warning.

    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 *1/1.
    See :DOC using-enabled-rules.

  The warning is saying that if you leave the rewrite rule enabled,
  ACL2 may simplify away the hypothesis added by the [47m:use[0m hint.  We
  now explain this danger in more detail and show how disabling the
  rule can solve this problem.

  Recall (see [hints]) how [47m:use[0m [hints] work.  Such a hint specifies a
  formula, [47mF[0m, which is based on an existing lemma.  Then the
  indicated goal, [47mG[0m, is replaced by the implication [47m(implies F G)[0m.
  The intention is that the truth of [47mF[0m will help in the
  simplification of [47mG[0m to [47mT[0m (true).  The ``[Use]'' warning shown above
  is telling us of the danger that [47mF[0m may be rewritten to [47mT[0m, reducing
  the implication above to [47m(implies T G)[0m --- thus, sadly, [47mF[0m has
  disappeared and is not available to help with the simplification of
  [47mG[0m.

  Consider the following tiny example.

    (defun p (x) (cons x x))
    (defthm car-p
       (equal (car (p x)) x))
    (in-theory (disable p (:type-prescription p)))
    (thm (implies (equal (p x1) (p x2))
                  (equal x1 x2))
         :hints ((\"Goal\"
                  :use ((:instance car-p (x x1))
                        (:instance car-p (x x2))))))

  The proof of the final [47m[thm][0m form fails, because the new hypotheses
  are rewritten to [47mt[0m using the [47m:[0m[47m[rewrite][0m rule [47mCAR-P[0m, in the manner
  described above.  The following proof log shows the new hypotheses
  and their disappearance via rewriting.

    We augment the goal with the hypotheses provided by the :USE hint.
    These hypotheses can be derived from CAR-P via instantiation.  We are
    left with the following subgoal.

    Goal'
    (IMPLIES (AND (EQUAL (CAR (P X1)) X1)
                  (EQUAL (CAR (P X2)) X2))
             (IMPLIES (EQUAL (P X1) (P X2))
                      (EQUAL X1 X2))).

    By the simple :rewrite rule CAR-P we reduce the conjecture to

    Goal''
    (IMPLIES (EQUAL (P X1) (P X2))
             (EQUAL X1 X2)).

  When we disable the rule [47mCAR-P[0m as follows, the proof succeeds.

    (thm (implies (equal (p x1) (p x2))
                  (equal x1 x2))
         :hints ((\"Goal\"
                  :use ((:instance car-p (x x1))
                        (:instance car-p (x x2)))
                  :in-theory (disable car-p))))

  In general, then, a solution is to disable the rewrite rule that you
  are supplying in a [47m:use[0m hint.")
 (USING-TABLES-EFFICIENTLY
  (TABLE)
  "Notes on how to use tables efficiently

  (Thanks to Jared Davis for contributing this [documentation] topic,
  to which we have made only minor modifications.)

  Suppose your book contains [47m[table][0m [events], or macros that expand
  into [47mtable[0m events, of the following form:

    (table my-table 'my-field <computation>)

  Then [47m<computation>[0m will be evaluated [3mtwice[0m during [47m[certify-book][0m and
  [3magain[0m every time you include the book with [47m[include-book][0m.  In some
  cases this overhead can be avoided using [47m[make-event][0m.

  See also [defconsts] for an analogous trick involving [47m[defconst][0m.

  As an example, suppose we want to store numbers in a table only if
  they satisfy some computationally expensive predicate.  We'll
  introduce a new book, [47mnumber-table.lisp[0m, and create a table to
  store these numbers:

    (table number-table 'data nil)

  Instead of implementing a ``computationally expensive predicate,''
  we'll write a function that just prints a message when it is called
  and accepts even numbers:

    (defun expensive-computation (n)
      (prog2$ (cw \"Expensive computation on ~x0.~%\" n)
              (evenp n)))

  Now we'll implement a macro, [47madd-number[0m, which will add its argument
  to the table only if it satisfies the expensive predicate:

    (defmacro add-number (n)
      `(table number-table 'data
              (let ((current-data
                     (cdr (assoc-eq 'data (table-alist 'number-table world)))))
                (if (expensive-computation ,n)
                    (cons ,n current-data)
                  current-data))))

  Finally, we'll call [47madd-number[0m a few times to finish the book.

    (add-number 1)
    (add-number 2)
    (add-number 3)

  When we now invoke [47m(certify-book \"number-table\")[0m, we see the
  expensive predicate being called twice for each number: once in
  Step 2, the main pass, then again in Step 3, the admissibility
  check.  Worse, the computation is performed again for each number
  when we use [47m[include-book][0m to load [47mnumber-table[0m, e.g.,

    ACL2 !>(include-book \"number-table\")
    Expensive computation on 1.
    Expensive computation on 2.
    Expensive computation on 3.

  To avoid these repeated executions, we can pull the test out of the
  [47mtable[0m event using [47m[make-event][0m.  Here's an alternate implementation
  of [47madd-number[0m that won't repeat the computation:

    (defmacro add-number (n)
      `(make-event
        (if (expensive-computation ,n)
            '(table number-table 'data
                    (cons ,n (cdr (assoc 'data
                                         (table-alist 'number-table world)))))
          '(value-triple :expensive-computation-failed))))

  When we recertify [47mnumber-table.lisp[0m, we'll see the expensive
  computation is still called once for each number in Step 2, but is
  no longer called during Step 3.  Similarly, the [47m[include-book][0m no
  longer shows any calls of the expensive computation.")
 (USING_THE_ASSOCIATIVITY_OF_APP_TO_PROVE_A_TRIVIAL_CONSEQUENCE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "Using the Associativity of App to Prove a Trivial Consequence

  {IMAGE} (see [Overview_of_the_Proof_of_a_Trivial_Consequence])

  If we have proved the [47massociativity-of-app[0m rule, then the following
  theorem is trivial:

    (defthm trivial-consequence
      (equal (app (app (app (app x1 x2) (app x3 x4)) (app x5 x6)) x7)
             (app x1 (app (app x2 x3) (app (app x4 x5) (app x6 x7))))))

  Below we show the proof

  {IMAGE} (see [Overview_of_the_Proof_of_a_Trivial_Consequence])")
 (VALUE (POINTERS)
        "See [system-utilities].")
 (VALUE-CMP (POINTERS)
            "See [context-message-pair].")
 (VALUE-TRIPLE
  (EVENTS ACL2-BUILT-INS ERRORS)
  "Compute a value, optionally checking that it is not [47mnil[0m


Simple Example

    ; Return the value 7 as an error triple, i.e., (mv nil 7 state)).
    (value-triple (+ 3 4))


Examples Involving Keyword Arguments

    ; Print \"hi\" even when skipping proofs.
    (value-triple (cw \"hi\") :on-skip-proofs t)

    ; Return an error triple containing the value of a state global.
    ; (This shows that it's OK to reference state.)
    (value-triple (@ ld-pre-eval-print))

    ; Check that the given form returns a non-nil value.
    (value-triple (equal (+ 3 4) 7) :check t)

    ; Check that the given defun is admissible, then revert the world.
    (value-triple (er-progn (defun foo (x) (cons x x))
                            (value :success))
                  :stobjs-out :auto)


General Form

    (value-triple form
                  :check chk             ; default nil
                  :ctx                   ; default 'value-triple
                  :on-skip-proofs sp     ; default nil
                  :safe-mode safe-mode   ; default :same
                  :stobjs-out stobjs-out ; default nil
                  )

  where all keyword arguments are evaluated and optional, and the
  defaults shown above represent values after evaluation.

  The following example illustrates all of the keyword arguments, which
  are documented below.

    (value-triple (mv nil (equal (+ 3 4) 7) state)
                  :check (msg \"Oops, I forgot what ~x0+~x1 is!\" 3 4)
                  :ctx '(value-triple . <some-mv>)
                  :on-skip-proofs t
                  :safe-mode nil ; legacy behavior (rarely used)
                  :stobjs-out '(nil nil state))


Description

  [47mValue-triple[0m provides a convenient way to evaluate a form in a
  context where an [event] is expected; thus, a call of [47mvalue-triple[0m
  may occur in [47m[progn][0m and [47m[encapsulate][0m forms and in [books].  By
  default, the form should evaluate to a single, non-[stobj] value
  (but see the discussion below about the [47m:STOBJS-OUT[0m keyword
  argument).  Calls of [47mvalue-triple[0m are skipped by default when
  proofs are being skipped (but see the discussion below about the
  [47m:ON-SKIP-PROOFS[0m keyword argument).  By default, a [47mvalue-triple[0m call
  has no effect other than to evaluate its form, but see the
  discussion of the [47m:CHECK[0m keyword below for how to check the result.

  A call of [47mvalue-triple[0m returns an [error-triple], [47m(mv erp val state)[0m.
  By default or when [47m:CHECK nil[0m is supplied: [47merp[0m is [47mnil[0m when
  evaluation completes without error and [47mval[0m is the value returned by
  evaluating the given form.  However, when the keyword argument
  [47m:CHECK[0m has a non-[47mnil[0m value, there is a check that [47mval[0m is non-[47mnil[0m.
  Note that the value of keyword argument [47m:STOBJS-OUT[0m can affect this
  notion of ``the value returned'' (by evaluation), as discussed
  below.


Keyword Arguments

  Here is documentation for the keyword arguments, arranged
  alphabetically and followed by relevant remarks.

  [47m:CHECK chk[0m (default: [47mnil[0m)

  When [47mchk[0m is supplied and non-[47mnil[0m, the value returned by evaluating
  the given form must be non-[47mnil[0m, or else an error occurs: The error
  message is generic if [47mchk[0m is [47mt[0m.  (By default a single value is
  returned, so the notion of ``the value returned'' is clear; but see
  the discussion of [47m:STOBJS-OUT[0m below for the notion of ``the value
  returned'' in the general case.)  If [47mchk[0m is supplied and is neither
  [47mt[0m nor [47mnil[0m, then it should be a ``message'' (see [msg]) that is used
  when printing the error message.

  [47m:CTX ctx[0m (default: [47m'value-triple[0m)

  Error messages from [47mvalue-triple[0m start, by default, with ``ACL2 Error
  in VALUE-TRIPLE''.  To replace [47mVALUE-TRIPLE[0m with a different
  context (see [ctx]), [47mctx[0m, supply keyword argument [47m:CTX ctx[0m.

  [47m:ON-SKIP-PROOFS sp[0m (default: [47mnil[0m)

  By default or when [47m:ON-SKIP-PROOFS[0m has value [47mnil[0m, the form is not
  evaluated when proofs are being skipped.  The form is, however,
  evaluated when [47m:ON-SKIP-PROOFS t[0m is supplied.  The other legal
  value for [47m:ON-SKIP-PROOFS[0m is [47m:interactive[0m, which is more
  restrictive than [47mt[0m.  [47m:Interactive[0m directs the [47mvalue-triple[0m call to
  be skipped when executing an [47m[include-book][0m or making a second pass
  through an [47m[encapsulate][0m, but not merely because
  [47m(set-ld-skip-proofsp t state)[0m has been executed.

  [47m:SAFE-MODE safe-mode[0m (default: [47m:same[0m)

  It is usually safe to ignore this option, which is available for
  backward compatibility: [47m:SAFE-MODE t[0m gives the behavior of
  [47massert-event[0m from before April, 2021.  Normally ACL2 operates
  without so-called ``safe-mode''; see [safe-mode].  The value [47m:same[0m
  prevents any change in whether safe-mode is on or off; otherwise
  the value is [47mt[0m to evaluate the form with safe-mode on and [47mnil[0m for
  safe-mode off.

  [47m:STOBJS-OUT stobjs-out[0m (default: [47mnil[0m)

  When [47mstobjs-out[0m has its default value of [47mnil[0m, which abbreviates the
  value [47m(nil)[0m, the form supplied to [47mvalue-triple[0m is expected to
  evaluate to a single value that is neither a [stobj] nor a [df].
  However, [multiple-value] return is also allowed, including stobjs
  (user-defined stobjs as well as [47mstate[0m).  The return shape is
  specified by supplying [47mstobjs-out[0m as a true list corresponding to
  the values returned, with stobj names in stobj positions and, [47m:DF[0m
  in df positions, and [47mnil[0m elsewhere.  (The list has length one if a
  single value is returned.)  For example, if [47mstobjs-out[0m is [47m(nil st1
  nil st2)[0m then the form should evaluate to a [multiple-value]
  return, with ordinary values in (zero-based) positions 0 and 2,
  stobj [47mst1[0m in position 1, and stobj [47mst2[0m in position 3.

  [47mStobjs-out[0m may also be [47m:auto[0m, which allows arbitrary returns.

  We speak of ``the value returned''.  When the evaluation results in a
  single value, that is of course the value returned.  When multiple
  values are returned, the first of those values is normally what we
  mean by ``the value returned'', with the following exception.  When
  an [error-triple] is returned --- say [47m(mv erp val state)[0m where [47merp[0m
  is an ordinary value, [47mval[0m is a non-[stobj] value, and [47mstate[0m is the
  ACL2 [state] --- then [47mval[0m is considered to be the value returned if
  [47merp[0m is [47mnil[0m; but if [47merp[0m is not [47mnil[0m, then there is no value returned,
  and [47mvalue-triple[0m results in an error.

  If [47m:CHECK[0m has a non-[47mnil[0m value then the value returned must not be a
  stobj.  Otherwise, when the value returned is a stobj it is
  replaced by the stobj's name, as discussed below.


Remarks

  We conclude by remarking on some details.  These remarks also apply
  to [assert-event], since it expands to make corresponding calls of
  [47mvalue-triple[0m.

   1. Since [47mvalue-triple[0m is an [event] macro, it returns an [error-triple],
      that is, the multiple values [47m(mv erp val state)[0m, where [47merp[0m is
      [47mnil[0m exactly when the event completes without error.  If the
      value of keyword argument [47m:CHECK[0m is non-[47mnil[0m and [47merp[0m is [47mnil[0m,
      then [47mval[0m is [47m:passed[0m.  Otherwise [47mval[0m is the value returned as
      discussed above.  To be precise: [47mval[0m is the result of
      evaluating the given form in the default case, when [47m:STOBJS-OUT[0m
      is not provided (or is [47mnil[0m or [47m(nil)[0m), but in general there
      several cases possible, as follows.

          * If the evaluation of the given form results in a single ordinary
            value, then [47mval[0m is that value.

          * If the evaluation of the given form results in a single stobj value,
            then [47mval[0m is that stobj's name (a symbol).  In particular,
            if the value is state, then [47mval[0m is the symbol [47mSTATE[0m (in
            the [47m\"ACL2\"[0m package).

          * If the evaluation of the given form results in a single [df] value,
            then [47mval[0m is the corresponding rational number.

          * If the evaluation of the given form results in multiple values [47m(mv x1
            ...)[0m, then [47mval[0m is [47mx1[0m if [47mx1[0m is not a stobj (but converted
            to a rational if [47mx1[0m is a [df]), else [47mval[0m is the name of
            that stobj.

   2. When [47m:STOBJS-OUT[0m is [47m:auto[0m and at least one user-defined [stobj] is
      returned, you will see a [47m\"User-stobjs-modified\"[0m warning unless
      warnings have been suppressed.  Although warnings are typically
      suppressed by general utilities such as
      [47m[set-inhibit-output-lst][0m, [47m[set-inhibit-warnings][0m, and
      [47m[with-output][0m, a more direct way to avoid this warning is to
      specify [47m:STOBJS-OUT[0m as a list (as discussed above).

   3. As noted above, the ACL2 [state] may change when keyword option
      [47m:STOBJS-OUT[0m has a value other than [47mnil[0m or [47m(nil)[0m.  Nevertheless,
      ACL2 ensures that certain parts of the state, including the
      logical [world], are the same after the [47mvalue-triple[0m call
      completes as they were before (as with [47mmake-event[0m expansion;
      see [make-event]).  Also, trust tags (see [defttag]) must not
      be introduced during such evaluation.

   4. (Ignore this remark unless you make many, many calls of
      [47mvalue-triple[0m.)  Evaluation may be much faster when [47m:STOBJS-OUT[0m
      is omitted or is specified as [47mnil[0m (the default) or [47m(nil)[0m.  That
      is because otherwise, since the return shape is checked only
      after evaluation completes, therefore a somewhat complex
      environment set-up is performed prior to evaluation, in which
      certain parts of the ACL2 [state] are protected as for
      [47m[make-event][0m (using [47m[revert-world][0m, and also as discussed in
      the documentation for [47m[make-event][0m about
      [47m*protected-system-state-globals*[0m).  Moreover, evaluation is
      faster still if in addition, the given form is [47mt[0m, [47mnil[0m, a
      [keyword], or of the form [47m(QUOTE x)[0m.")
 (VARIABLEP (POINTERS)
            "See [system-utilities].")
 (VERBOSE-PSTACK
  (PSTACK)
  "Seeing what the prover is up to (for system hackers)

  NOTE: This utility is a low-level debugging utility, which may not be
  useful except to those familiar with ACL2 source code.

    General Forms:
    (verbose-pstack t)   ; get trace-like information on prover during proofs
    (verbose-pstack '(fn1 fn2 ...))
                         ; as above, but omit calls of the indicated functions
    (verbose-pstack nil) ; turn off trace-like information on prover

  For example, (verbose-pstack '(ev-fncall)) will provide a trace of
  various prover functions during proofs, except for the function
  [47mev-fncall[0m.

  By evaluating [47m(verbose-pstack t)[0m one can get trace-like information
  during subsequent proofs about prover functions, including time
  summaries, printed to the screen during a proof.  To turn off this
  feature, evaluate [47m(verbose-pstack nil)[0m.  Also see [pstack].")
 (VERIFY
  (PROOF-BUILDER)
  "Enter the interactive proof-builder

  For proof-builder command summaries, see [proof-builder].

    Examples:
    (VERIFY (implies (and (true-listp x) (true-listp y))
                          (equal (append (append x y) z)
                                 (append x (append y z)))))
       -- Attempt to prove the given term interactively.

    (VERIFY (p x)
            :event-name p-always-holds
            :rule-classes (:rewrite :generalize)
            :instructions ((rewrite p-always-holds-lemma)
                           change-goal))
       -- Attempt to prove (p x), where the intention is to call the
          resulting DEFTHM event by the name p-always-holds, with
          rule-classes as indicated.  The two indicated instructions
          will be run immediately to start the proof.

    (VERIFY)
       -- Re-enter the interactive proof-builder in the state at which
          it was most recently left.

    General Form:
    (VERIFY &OPTIONAL raw-term
            &KEY
            event-name
            rule-classes
            instructions)

  [47mVerify[0m is the function used for entering the interactive
  [proof-builder]'s read-eval-print loop.

  Note that you can use [47mverify[0m to create an event, by using the [47mexit[0m
  command (see [ACL2-pc::exit]).  For example, after evaluating

    (verify (equal y y) :instructions (s (exit foo nil t)))

  we can see that the expected event was successfully created:

    ACL2 !>:pe foo
               1:x(VERIFY (EQUAL Y Y) :INSTRUCTIONS ...)

    >              (DEFTHM FOO (EQUAL Y Y)
                           :RULE-CLASSES NIL
                           :INSTRUCTIONS (:S))
    ACL2 !>

  That said, it's probably not a good idea to save [events] with
  [47m:instructions[0m.  There are at least two general reasons to avoid
  [47m:instructions[0m: (1) to encourage the development of [rewrite] rules
  and other ways to help with later proofs, and (2) to make the
  proofs less brittle, that is, more likely to survive when there are
  small changes to earlier events.")
 (VERIFY-GUARD-IMPLICATION
  (MEMOIZE GUARD-FORMULA-UTILITIES)
  "[Guard] implication for [47m[memoize][0m keyword [47m:invoke[0m

    Examples:
    (verify-guard-implication f g)
    (verify-guard-implication f g
                              :hints ((\"Goal\" :in-theory (enable nth))))

    General Form:
    (verify-guard-implication fn1 fn2 &key hints otf-flg)

  where none of the arguments is evaluated.  This macro creates a
  [47m[defthm][0m event with [47m:[0m[47m[rule-classes][0m [47mnil[0m, using [47m:hints[0m and [47m:otf-flg[0m
  if provided.  The formula of that event is generally an implication
  formed from the guards of the two functions, but might be [47mT[0m, as we
  now describe.

  Let [47mguard-fn1[0m be the [guard] for [47mfn1[0m, and let [47mguard-fn2[0m be the result
  of substituting the formals of [47mfn1[0m for the formals of [47mfn2[0m in the
  guard for [47mfn2[0m.  If [47mguard-fn1[0m tautologically implies [47mguard-fn2[0m (for
  example, the two are equal or [47mguard-fn2[0m is [47m'T[0m), then the formula of
  the generated event is [47mT[0m.  Otherwise, the formula is [47m(IMPLIES
  guard-fn1 guard-fn2)[0m.

  Note that the formula might be unpleasant for a human to read, since
  [47mguard-fn1[0m and [47mguard-fn2[0m are translated terms (see [term]).")
 (VERIFY-GUARDS
  (EVENTS GUARD)
  "Verify the [guard]s of a function

  See [guard] for a general discussion of guards.

  Before discussing the [47mverify-guards[0m [event], we first discuss [guard]
  verification, which can take place at definition time or, later,
  using [47mverify-guards[0m.  Typically, guard verification takes place at
  definition time if a guard (or type, or [stobjs]) has been supplied
  explicitly unless [47m:verify-guards nil[0m has been specified; see
  [defun] and see [xargs], and see [set-verify-guards-eagerness] for
  how to change this default.  The point of guard verification is to
  ensure that during evaluation of an expression without free
  variables, no guard violation takes place.

  Technical Notes: (1) The first argument of [47mverify-guards[0m must be a
  function symbol, the name of a [47m[defthm][0m or [47m[defaxiom][0m event, a
  [47m[lambda$][0m expression, or an unquoted well-formed [47mLAMBDA[0m object; it
  must not be a macro-alias for a function symbol (see
  [macro-aliases-table]).  See [verify-guards+] for a utility that
  does not have this restriction.  (2) When the guards of a defined
  function, [47mfn[0m, are verified, [47mverify-guards[0m also includes the guards
  of all the functions that are mutually recursive with [47mfn[0m, if any,
  plus the guards of all the quoted well-formed [47mLAMBDA[0m objects used
  by [47mfn[0m or any function in its mutually-recursive clique.  Guard
  obligations for [47mlambda$[0m and [47mLAMBDA[0m objects are [3mnot[0m included when
  the first argument is the name of a theorem or axiom.  Details are
  discussed further below.

  Guard verification is intended to guarantee that for any call of a
  given function, if its [guard] holds for that call then the [guard]
  will hold for every function call in the body of that function.
  Moreover, in order to avoid guard violations during evaluation of
  the function's guard itself, guard verification also is intended to
  guarantee that the guards are satisfied for all calls in the guard
  itself.  Consider the following simple example.

    (defun f (x)
      (declare (xargs :guard (and (consp x)
                                  (integerp (car x)))))
      (if (rationalp (cdr x))
          (+ (car x) (cdr x))
        17))

  If you evaluate [47m(f t)[0m, for example, in the top-level loop, you will
  (by default) get a guard error.  The point of guard verification is
  to guarantee the absence of guard errors, and we start by using
  this example to illustrate the proof obligations that guarantee
  such absence.

  The body of the above definition has the following function calls,
  where the first is the entire body.

    (if (rationalp (cdr x))
        (< (car x) (cdr x))
      17)
    (rationalp (cdr x)) ; the test of the top-level IF call
    (cdr x)             ; from (rationalp (cdr x))
    (< (car x) (cdr x)) ; the true branch of the top-level IF call
    (car x)             ; from (< (car x) (cdr x))
    (cdr x)             ; from (< (car x) (cdr x))

  We thus see potentially six conditions to prove, one for each call.
  The guards of the function symbols of those calls are [47mt[0m for [47m[if][0m
  and [47m[rationalp][0m, [47m(or (consp x) (equal x nil))[0m for both [47m(car x)[0m and
  [47m(cdr x)[0m, and finally that both arguments are rationals for [47m<[0m.
  Moreover, we can take advantage of ``contextual assumptions'': the
  [47mif[0m-test conditions and the top-level [47m:guard[0m.  Thus, for
  [47mverify-guards[0m the proof obligation from the body of [47mf[0m is as
  follows.

    (implies
     (and (consp x) (integerp (car x))) ; from the :guard
     (and t ; from the top-level IF call
          t ; from (rationalp (cdr x))
          (or (consp x) (equal x nil)) ; from the first (cdr x)
          (implies
           (rationalp (cdr x)) ; IF-test for calls in the true branch
           (and (or (consp x) (equal x nil)) ; from (car x)
                (or (consp x) (equal x nil)) ; from the second (cdr x)
                (and (rationalp (car x)) (rationalp (cdr x))) ; from the < call
                ))))

  But the [47m:guard[0m itself generates a similar sort of proof obligation.
  Note that the guard [47m(and (consp x) (integerp (car x)))[0m is really an
  abbreviation (i.e. via the macro [47m[and][0m) for the term [47m(if (consp x)
  (integerp (car x)) nil)[0m.  The guard proof obligation for the guard
  itself is thus as follows.

    (and t ; from (consp x)
         (implies (consp x)
                  (and t         ; from (integerp (car x)) ;
                       (consp x) ; from (car x) ;
                       )))

  All of the above proof obligations are indeed theorems, and guard
  verification succeeds for the above definition of [47mf[0m.

  The example above illustrates the general procedure for generating
  the guard proof obligation.  Each function call is considered in
  the body or guard of the function, and it is required that the
  guard is met for that call, under certain ``contextual
  assumptions'', which are as follows.  In the case of the body of
  the named function, it is assumed that the guard holds for that
  function on its formal parameters.  And in both cases --- the body
  of the named function and also its guard --- the governing tests
  from superior calls of [47m[if][0m are also assumed.  (However, additional
  conjectures are generated for [47mloop$[0m statements.  See the section
  [31;1mSpecial Guard Conjectures for LOOP$[0m in the documentation for
  [47m[loop$][0m.)

  As mentioned above, if the guard on a function is not [47mt[0m, then guard
  verification requires not only consideration of the body under the
  assumption that the guard is true, but also consideration of the
  guard itself.  Thus, for example, guard verification fails in the
  following example, even though there are no proof obligations
  arising from the body, because the guard itself can cause a guard
  violation when evaluated for an arbitrary value of [47mx[0m:

    (defun foo (x)
      (declare (xargs :guard (car x)))
      x)

  We turn now to the [47mverify-guards[0m event as a way of verifying the
  [guard]s for a function or theorem.

    Examples:
    (verify-guards flatten)
    (verify-guards flatten
                   :hints ((\"Goal\" :use (:instance assoc-of-app)))
                   :guard-debug t ; default = nil
                   :guard-simplify :limited ; default = t
                   :otf-flg t)
    (verify-guards (lambda$ (x)
                     (declare (xargs :guard (natp x)))
                     (+ 1 x)))
    (verify-guards
      (LAMBDA (X)
              (DECLARE (XARGS :GUARD (NATP X) :SPLIT-TYPES T))
              (RETURN-LAST 'PROGN
                           '(LAMBDA$ (X)
                                     (DECLARE (XARGS :GUARD (NATP X)))
                                     (+ 1 X))
                           (BINARY-+ '1 X))))

    General Form:
    (verify-guards name
            :hints          hints
            :guard-debug    gdbg ; default generally nil; any value is legal
            :guard-simplify gsmp ; default generally t; may be set to :limited
            :otf-flg        otf-flg)

  In the General Form above, [47mname[0m may be the name of a [47m:[0m[47m[logic][0m mode
  function (see [defun-mode]).  In that case, the first three
  keywords may default to values in an existing definition as
  discussed below.  Otherwise, [47mname[0m is the name of a theorem or
  axiom, or it is a [47m[lambda$][0m expression or a well-formed [47mLAMBDA[0m
  object (not [3mquoted[0m).  [Mixed-mode-functions] cannot be guard
  verified.

  In the most common case [47mname[0m is the name of a function that has not
  yet had its [guard]s verified, each subroutine of which has had its
  [guard]s verified.  The values [47m[hints][0m, [47m[otf-flg][0m, and
  [47m[guard-debug][0m are as described in the corresponding [documentation]
  entries, but [47mhints[0m and [47mguard-debug[0m can be taken from the existing
  definition of [47mname[0m; we return to that point later.  The keyword
  arguments above are all optional.  To admit this event, the
  conjunction of the guard proof obligations must be proved.  If all
  the guard obligations are proved, [47mname[0m is considered to have had
  its [guard]s verified.  The [47m:guard-simplify[0m option controls certain
  simplifications that may be applied to the guard conjecture while
  generating the initial goal: its default is [47mt[0m, which doesn't
  restrict such simplification, and the other legal value is
  [47m:limited[0m, which skips all simplifications that depend on the set of
  currently [enable]d rules; but as with [47mhints[0m and [47mguard-debug[0m, the
  value can be taken from the existing definition of [47mname[0m, as
  described further below.  See also [guard-simplification].

  If [47mname[0m is a [47mlambda$[0m expression it is translated (to a quoted
  well-formed [47mLAMBDA[0m object), the formals, declaration, and body are
  extracted, and [47mverify-guards[0m behaves as though [47mname[0m were the name
  of some defined function with those formals, declaration, and body.
  If [47mname[0m is a [47mLAMBDA[0m object, it is checked for well-formedness (see
  [47m[well-formed-lambda-objectp][0m), the formals, declaration, and body
  are extracted [47mverify-guards[0m behaves as though [47mname[0m were the name of
  some defined function with those formals, declaration, and body.
  for [47mlambda$[0m.  We henceforth limit our attention to [47mname[0m being the
  name of a function, theorem or axiom.

  Note: Since we encourage you to use [47mlambda$[0m instead of trying to type
  quoted well-formed [47mLAMBDA[0m objects, you might wonder why we allow
  [47mverify-guards[0m to operate on well-formed [47mLAMBDA[0m objects instead of
  [47mlambda$[0m expressions.  The answer is that in proof output and in
  [47m[print-cl-cache][0m output you see quoted well-formed [47mLAMBDA[0m objects
  and we expect you might grab the text of such an object and submit
  it to [47mverify-guards[0m.

  See [guard-formula-utilities] for related utilities, including ones
  that let you view the formula to be proved by [47mverify-guards[0m, but
  without creating an event.

  If [47mname[0m is one of several functions in a mutually recursive clique,
  [47mverify-guards[0m will attempt to verify the [guard]s of all of the
  functions.

  As promised above, we now describe the case that [47mname[0m was defined
  function symbol whose definition supplies the value of [47m:hints[0m,
  [47m:guard-debug[0m, and/or [47m:guard-simplify[0m.  This happens when those
  keywords are not supplied with the [47mverify-guards[0m event but the
  existing definition specifies [47m:guard-hints[0m, [47m:guard-debug[0m, and/or
  [47m:guard-simplify[0m, respectively, in its [47m[xargs][0m [declaration].  Note
  that when [47mname[0m is defined as part of a [47m[mutual-recursion][0m event,
  only declarations in the definition of [47mname[0m are relevant, but those
  in definitions of other functions in the clique.  Consider the
  following example.

    (defun my-consp (x)
      (declare (xargs :guard t))
      (consp x))

    (defun my-cdr (x)
      (declare (xargs :guard (my-consp x)))
      (cdr x))

    (mutual-recursion
     (defun evenlp (x)
       (declare (xargs :verify-guards nil))
       (if (consp x) (oddlp (my-cdr x)) t))
     (defun oddlp (x)
       (declare (xargs :guard-hints
                       ((\"Goal\" :in-theory (disable my-consp (tau-system))))))
       (if (consp x) (evenlp (my-cdr x)) nil)))

  Each of the following succeeds or fails for the reason given.

    ; Succeeds: :guard-hints for oddlp are ignored.
    (verify-guards evenlp)

    ; Fails: :guard-hints for oddlp defeat the proof attempt.
    (verify-guards oddlp)

    ; Succeeds: guard-hints for oddlp are ignored because :hints was supplied
    ; explicitly (even though :hints is nil, which is the default).
    (verify-guards oddlp :hints nil)

  If the guard or body of [47mname[0m include any quoted well-formed [47mLAMBDA[0m
  objects, [47mverify-guards[0m include their proof obligations in those
  generated for [47mname[0m.  Roughly speaking, the guard obligations for a
  well-formed [47mLAMBDA[0m object are exactly those that would be generated
  for a separately defined non-recursive function with the formals,
  guard, and body of the [47mLAMBDA[0m object.  We discuss this further in
  the ``Remarks on [47mLAMBDA[0m objects in defined functions'' below.  As a
  non-logical side-effect of the successful verification of all the
  proof obligations, all well-formed [47mLAMBDA[0m objects in the guard or
  body of [47mname[0m (including [47mname[0m itself if it is a [47mlambda$[0m expression
  or [47mLAMBDA[0m object) are added to the compiled lambda cache.  This
  will speed up the execution of [47mname[0m in the evaluation theory when
  those well-formed [47mLAMBDA[0m objects are [47mapply$[0md.  See
  [47m[print-cl-cache][0m.

  If [47mname[0m is a theorem or axiom name, [47mverify-guards[0m verifies the guards
  of the associated formula.  When a theorem has had its guards
  verified then you know that the theorem will evaluate to non-[47mnil[0m in
  all Common Lisps, without causing a runtime error (other than
  possibly a resource error).  In particular, you know that the
  theorem's validity does not depend upon ACL2's arbitrary completion
  of the domains of partial Common Lisp functions.

  For example, if [47mapp[0m is defined as

    (defun app (x y)
      (declare (xargs :guard (true-listp x)))
      (if (endp x)
          y
          (cons (car x) (app (cdr x) y))))

  then we can verify the guards of [47mapp[0m and we can prove the theorem:

    (defthm assoc-of-app
      (equal (app (app a b) c) (app a (app b c))))

  However, if you go into almost any Common Lisp in which [47mapp[0m is
  defined as shown and evaluate

    (equal (app (app 1 2) 3) (app 1 (app 2 3)))

  we get an error or, perhaps, something worse like [47mnil[0m!  How can this
  happen since the formula is an instance of a theorem?  It is
  supposed to be true!

  It happens because the theorem exploits the fact that ACL2 has
  completed the domains of the partially defined Common Lisp
  functions like [47m[car][0m and [47m[cdr][0m, defining them to be [47mnil[0m on all
  non-conses.  The formula above violates the guards on [47mapp[0m.  It is
  therefore ``unreasonable'' to expect it to be valid in Common Lisp.

  But the following formula is valid in Common Lisp:

    (if (and (true-listp a)
             (true-listp b))
        (equal (app (app a b) c) (app a (app b c)))
        t)

  That is, no matter what the values of [47ma[0m, [47mb[0m and [47mc[0m the formula above
  evaluates to [47mt[0m in all Common Lisps (unless the Lisp engine runs out
  of memory or stack computing it).  Furthermore the above formula is
  a theorem:

    (defthm guarded-assoc-of-app
      (if (and (true-listp a)
               (true-listp b))
          (equal (app (app a b) c) (app a (app b c)))
          t))

  This formula, [47mguarded-assoc-of-app[0m, is very easy to prove from
  [47massoc-of-app[0m.  So why prove it?  The interesting thing about
  [47mguarded-assoc-of-app[0m is that we can verify the guards of the
  formula.  That is, [47m(verify-guards guarded-assoc-of-app)[0m succeeds.
  Note that it has to prove that if [47ma[0m and [47mb[0m are true lists then so is
  [47m(app a b)[0m to establish that the guard on the outermost [47mapp[0m on the
  left is satisfied.  By verifying the guards of the theorem we know
  it will evaluate to true in all Common Lisps.  Put another way, we
  know that the validity of the formula does not depend on ACL2's
  completion of the partial functions or that the formula is
  ``well-typed.''

  One last complication: The careful reader might have thought we could
  state [47mguarded-assoc-of-app[0m as

    (implies (and (true-listp a)
                  (true-listp b))
             (equal (app (app a b) c)
                    (app a (app b c))))

  rather than using the [47mif[0m form of the theorem.  We cannot!  The reason
  is technical: [47m[implies][0m is defined as a function in ACL2.  When it
  is called, both arguments are evaluated and then the obvious truth
  table is checked.  That is, [47mimplies[0m is not ``lazy.'' Hence, when we
  write the guarded theorem in the [47mimplies[0m form we have to prove the
  guards on the conclusion without knowing that the hypothesis is
  true.  It would have been better had we defined [47mimplies[0m as a macro
  that expanded to the [47mif[0m form, making it lazy.  But we did not and
  after we introduced guards we did not want to make such a basic
  change.  For a utility that deals with this sort of problem
  automatically, see [47m[defthmg][0m.

  Recall however that [47mverify-guards[0m is almost always used to verify the
  guards on a function definition rather than a theorem.  We now
  return to that discussion.

  [47mVerify-guards[0m must often be used when the value of a recursive call
  of a defined function is given as an argument to a subroutine that
  is [guard]ed.  An example of such a situation is given below.
  Suppose [47mapp[0m (read ``append'') has a [guard] requiring its first
  argument to be a [47m[true-listp][0m.  Consider

    (defun rev (x)
      (declare (xargs :guard (true-listp x)))
      (cond ((endp x) nil)
            (t (app (rev (cdr x)) (list (car x))))))

  Observe that the value of a recursive call of [47mrev[0m is being passed
  into a [guard]ed subroutine, [47mapp[0m.  In order to verify the [guard]s
  of this definition we must show that [47m(rev (cdr x))[0m produces a
  [47m[true-listp][0m, since that is what the [guard] of [47mapp[0m requires.  How
  do we know that [47m(rev (cdr x))[0m is a [47m[true-listp][0m?  The most elegant
  argument is a two-step one, appealing to the following two lemmas:
  (1) When [47mx[0m is a [47m[true-listp][0m, [47m(cdr x)[0m is a [47m[true-listp][0m.  (2) When
  [47mz[0m is a [47m[true-listp][0m, [47m(rev z)[0m is a [47m[true-listp][0m.  But the second
  lemma is a generalized property of [47mrev[0m, the function we are
  defining.  This property could not be stated before [47mrev[0m is defined
  and so is not known to the theorem prover when [47mrev[0m is defined.

  Therefore, we might break the admission of [47mrev[0m into three steps:
  define [47mrev[0m without addressing its [guard] verification, prove some
  general properties about [47mrev[0m, and then verify the [guard]s.  This
  can be done as follows:

    (defun rev (x)
      (declare (xargs :guard (true-listp x)
                      :verify-guards nil))    ; Note this additional xarg.
      (cond ((endp x) nil)
            (t (app (rev (cdr x)) (list (car x))))))

    (defthm true-listp-rev
      (implies (true-listp x2)
               (true-listp (rev x2))))

    (verify-guards rev)

  The ACL2 system can actually admit the original definition of [47mrev[0m,
  verifying the [guard]s as part of the [47m[defun][0m event.  The reason is
  that, in this particular case, the system's heuristics just happen
  to hit upon the lemma [47mtrue-listp-rev[0m.  But in many more complicated
  functions it is necessary for the user to formulate the inductively
  provable properties before [guard] verification is attempted.

  [31;1mRemarks on [47mLAMBDA[0m[31;1m objects in defined functions[0m.  The guard
  obligations of a function, [47mname[0m, include the guard obligations of
  every quoted well-formed [47mLAMBDA[0m object occurring in either the
  guard or body of [47mname[0m.  We point this out because quoted
  well-formed [47mLAMBDA[0m objects are, after all, just quoted constants
  and no other quoted constant generates guard obligations!  Note
  also that we collect [3mall[0m quoted well-formed [47mLAMBDA[0m objects, not
  just the translations of [47m[lambda$][0m expressions and not just objects
  in slots of [ilk] [47m:FN[0m.  (We do not actually expect the user to
  write quoted well-formed [47mLAMBDA[0m objects in non-[47m:FN[0m slots -- it
  can't be done with [47mlambda$[0m expressions -- but we collect them all
  anyway.  If such a quoted constant is not guard verifiable, you
  could always use so-called Bypass 1 of
  [gratuitous-lambda-object-restrictions] and avoid quoting it.)  We
  assume that when calls of [47mname[0m are executed some of those [47mLAMBDA[0m
  objects may reach [47mapply$[0m and be applied.  Those applications will
  be faster if the guards for the [47mLAMBDA[0ms are verified too.  The
  guard obligations of a quoted well-formed [47mLAMBDA[0m object are just
  those obligations that would be generated by a defined function
  with the same formals, guard, and body as the [47mLAMBDA[0m object.  Those
  obligations are unioned with the rest of the obligations generated
  for [47mname[0m and all must be proved for [47m(verify-guards name)[0m to be
  successful.  If the guards of some [47mLAMBDA[0m object requires hints to
  prove, the hints may be supplied to [47mverify-guards[0m as you would for
  any other failing guard obligation in [47mname[0m.  When successful, the
  [47mLAMBDA[0m objects thus verified are added, behind the scenes, to the
  compiled lambda cache (see [47m[print-cl-cache][0m) to speed up [47mapply$[0m in
  the evaluation theory.

  Since, in general, [47mLAMBDA[0m objects can be passed around or re-used in
  different contexts, the guard obligations generated for a quoted
  well-formed [47mLAMBDA[0m object occurring in [47mname[0m are entirely
  independent of the guard on the [47mname[0m itself.  This is best
  explained by example.

  In the [47mdefun[0m below, which contains a [47mlambda$[0m expression in its body,
  we assume each function has the guard shown below:

    function        formals              guard
    f                 (x)                (fp x)
    g                 (x y)              (gp x y)
    the lambda$       (x)                (lp x)
    r                 (x)                (rp x)
    s                 (x)                (sp x)

  We also assume that the ilks of [47mg[0m are [47m:FN[0m and [47mNIL[0m.  Then the guard
  obligations generated for

    (defun f (x)
     (declare (xargs :guard (fp x)))
     (g (lambda$ (x)
                 (declare (xargs :guard (lp x)))
                 (r x))
        (s x)))

  is

    (and
     (implies (fp x) (sp x))        ; f can call s
     (implies (fp x)                ; f can call g
              (gp (lambda$ (x)
                           (declare (xargs :guard (hg x)))
                           (r x))
                  (s x)))
     (implies (lp x) (rp x))        ; the lambda$ can call r
     )

  Note: The actual obligation will have been generated from the fully
  translated body of [47mf[0m and the [47mlambda$[0m expression will have been
  converted to a quoted well-formed [47mLAMBDA[0m object.  But we will refer
  to it as a [47mlambda$[0m here for clarity.

  In particular note that the last conjecture, establishing that the
  [47mlambda$[0m can call [47mr[0m, does not have [47mf[0m's guard as a hypothesis.  The
  [47mlambda$[0m is being guard verified in a ``context free'' way because
  we cannot (or at least do not) trace the hypotheses governing every
  time it is called in [47mg[0m and the variable [47mx[0m in [47mf[0m and its guard is
  unrelated to the local variable [47mx[0m in the [47mlambda$[0m.  Furthermore, if
  [47mapply$[0m ever encounters this [47mlambda$[0m it will know it has been guard
  verified (because it finds it marked as such in the cache) and it
  may well [3mnot[0m be under a call of [47mf[0m.  Be that as it may, the guard
  obligations of the [47mlambda$[0m are included in the guard obligations
  for [47mf[0m.  As of ACL2 Version 8.1, the guard obligation that [47mg[0m can
  call the [47mlambda$[0m is checked by computation every time the [47mlambda$[0m
  is [47mapply$[0md.  That is, [47m(lp x)[0m is run on each object the [47mlambda$[0m is
  [47mapply$[0md to and the compiled code for the [47mlambda$[0m is run only if its
  guard approves.

  [31;1mRemark on computation of guard conjectures and evaluation[0m.  When ACL2
  computes the [guard] conjecture for the body of a function, it
  evaluates any ground subexpressions (those with no free variables),
  for calls of functions whose [47m:[0m[47m[executable-counterpart][0m [rune]s are
  [47m[enable][0md.  Note that here, ``enabled'' refers to the current
  global [theory], not to any [47m:[0m[47m[hints][0m given to the guard
  verification process; after all, the guard conjecture is computed
  even before its initial goal is produced.  Also note that this
  evaluation is done in an environment as though [47m:set-guard-checking
  :all[0m had been executed, so that we can trust that this evaluation
  takes place without guard violations; see [set-guard-checking].

  If you want to verify the [guard]s on functions that are built into
  ACL2, you will first need to put them into [47m:[0m[47m[logic][0m mode.  See
  [verify-termination], specifically the ``Remark on system
  functions'' in that [documentation].


Subtopics

  [Verify-guards-for-system-functions]
      Arranging that source functions come up as guard-verified")
 (VERIFY-GUARDS+
  (EVENTS)
  "Verify the [guard]s of a function

  We assume familiarity with [guard] verification; see [verify-guards].
  Unlike [47mverify-guards[0m, the macro call [47m(verify-guards+ mac ...)[0m will
  verify guards for a function, [47mfn[0m, such that the macro [47mmac[0m is
  associated with the function symbol [47mfn[0m in [47m[macro-aliases-table][0m
  (also see [add-macro-alias]).  For example, if you define a macro
  [47mapp[0m and list append function [47mbinary-app[0m, and you associate macro
  [47mapp[0m with function symbol [47mbinary-app[0m in [47m[macro-aliases-table][0m, then
  evaluation of the form [47m(verify-guards+ app)[0m will have the effect of
  evaluating [47m(verify-guards fn)[0m.  Note that in this setting,
  evaluation of [47m(verify-guards app)[0m would cause an error, because [47mapp[0m
  is a macro and [47mverify-guards[0m, unlike [47mverify-guards+[0m, cannot handle
  macros.

  The rest of this [documentation] topic discusses why we do not simply
  arrange that [47mverify-guards[0m be permitted to take a macro alias.  The
  following example shows a soundness issue in doing so.

    (encapsulate
     ()
     (defun f1 (x)
       (declare (xargs :guard (consp x)
                       :verify-guards nil))
       (car x))
     (defun f2 (x)
       (declare (xargs :guard t
                       :verify-guards nil))
       (cdr x))
     (defmacro mac (x)
       x)
     (add-macro-alias mac f2) ; silly macro alias ;
     (local (add-macro-alias mac f1)) ; alternate silly macro alias ;
     (verify-guards mac))

  If we were to allow macro aliases in [47m[verify-guards][0m, this event
  would be admitted, because on the first pass we are verifying
  guards of [47mf1[0m.  But after the [47m[encapsulate][0m form completes
  evaluation, it would appear that [47mf2[0m is guard-verified.  That could
  of course cause a raw Lisp error.

  The enhanced functionality provided by [47mverify-guards+[0m does not have
  the above problem, because it takes advantage of [47m[make-event][0m to
  avoid taking advantage of the contradictory results produced by the
  two calls of [47madd-macro-alias[0m.  See [make-event].  If the specific
  example above is modified by replacing [47mverify-guards[0m with
  [47mverify-guards+[0m, then the first pass through the [47m[encapsulate][0m form
  will expand the form [47m(verify-guards+ mac)[0m to [47m(verify-guards f1)[0m.
  That same expansion will be used for the [47mverify-guards+[0m call during
  the second pass through the [47mencapsulate[0m form, which is evaluated
  successfully and leaves us in a [world] where [47mf1[0m is guard-verified
  and [47mf2[0m is not.")
 (VERIFY-GUARDS-EAGERNESS (POINTERS)
                          "See [set-verify-guards-eagerness].")
 (VERIFY-GUARDS-FOR-SYSTEM-FUNCTIONS
  (VERIFY-TERMINATION VERIFY-GUARDS)
  "Arranging that source functions come up as guard-verified

  ACL2 is maintained solely by Matt Kaufmann and J Moore.  However, we
  anticipate that a few others will eventually contribute as well.
  Here we discuss how to put built-in functions into [47m:[0m[47m[logic][0m mode.
  Since ACL2 insists that its built-in [47m:logic[0m mode functions are
  [guard]-verified, we actually explain how to arrange that built-in
  [47m:[0m[47m[program][0m mode functions become built-in guard-verified [47m:logic[0m
  mode functions.

  To put a system function into guard-verified [47m:logic[0m mode, you might
  first need or want to modify your local copy of the ACL2 sources,
  for example replacing [47m(null lst)[0m by [47m(endp lst)[0m in a function's
  definition in support of the termination proof and then specifying
  [47m(true-listp lst)[0m in its guard.  You don't need to become a system
  developer to do this, but see [developers-guide] if you are an
  experienced ACL2 user and system development interests you.
  IMPORTANT: Eventually you will probably want to undo your changes;
  this will be explained further below.

  After making such changes, build an ACL2 executable image containing
  your modified code, to test that the modified code builds.  The
  next step is typically to create a new file, perhaps named after
  the main function(s) whose guards you want to verify, in directory
  [47mbooks/system[0m.  Community book [47mbooks/system/too-many-ifs.lisp[0m is a
  good example.  Ultimately, this file should be a certifiable book
  that verifies the desired termination and guards.  Include this
  book in [47mbooks/system/top.lisp[0m.  Of course, you can instead add to
  some existing file in the same directory that is already included
  in [47mbooks/system/top.lisp[0m, rather than creating a new book and
  including it there.

  In general, in this new file or new file addition, it is necessary to
  use both [47m[verify-termination][0m and [47m[verify-guards][0m on the system
  functions in question, in order to both put them in logic mode and
  verify their guards. However, as explained in the documentation of
  [47m[verify-termination][0m, sometimes [47m[verify-termination][0m also verifies
  the guards (see also [47m[set-verify-guards-eagerness][0m).  In this case,
  it is good practice to add a comment `[47m; and guards[0m' just after the
  [47m[verify-termination][0m form, on the same line, as can be seen in some
  of the files under [community-books] directory [47msystem/[0m.

  Now it is time to add entries to the value of constant
  [47m*system-verify-guards-alist*[0m in your local copy of the ACL2
  sources, which specifies functions whose guard-verification is
  completed by including [community-book]
  [47mbooks/system/devel-check.lisp[0m (which includes
  [47mbooks/system/top.lisp[0m.  Each entry is of the form [47m(function-symbol
  . measure)[0m.  For example, the entry [47m(ARITY-ALISTP ACL2-COUNT ALIST)[0m
  signifies that the function symbol [47marity-alistp[0m is to have measure
  [47m(acl2-count alist)[0m, while the entry [47m(ARGLISTP)[0m signifies that
  function symbol [47marglistp[0m has no measure (i.e., we use [47mnil[0m for the
  measure), presumably because its definition is not recursive.
  After you make those additions, then follow the steps below.

   1. Build a so-called ``devel'' copy in which the functions in
      [47m*system-verify-guards-alist*[0m remain in [47m:program[0m mode.  For
      example, the following command will create ``devel'' executable
      [47msaved_acl2d[0m.

          (time nice make ACL2_DEVEL=d) >& make-devel.log

   2. Check that the build seems to have worked, for example by finding the
      string [47m\"Successfully built\"[0m near the end of your log file.

   3. Run a ``devel'' regression, for example as follows if starting in the
      ACL2 sources directory.  Note that including
      ``[47mACL2_USELESS_RUNES= [0m'' as shown below may be necessary
      because of how proofs differ between normal and ``devel''
      versions of ACL2.

          make clean-books ACL2=`pwd`/saved_acl2d
          cd books
          (time nice make -j 8 \\
                     ACL2=`pwd`/../saved_acl2d \\
                     ACL2_USELESS_RUNES= \\
                     system/devel-check.cert) \\
            >& make-devel-regression.log&

      The last of these commands should run much more quickly than a
      normal regression.  You can of course check on it as follows.

          tail make-devel-regression.log

   4. Check that there are no errors, by checking that the following
      produces no output.

          fgrep -a '**' make-devel-regression.log

   5. Run the following check from your ACL2 sources directory.

          make devel-check ACL2=`pwd`/saved_acl2d

      You should see output like the following.

          SUCCESS for chk-new-verified-guards
          SUCCESS for check-system-events
          SUCCESS for devel-check

   6. Now clean the books (see [47mmake clean-books[0m above) and then do a normal
      build and regression.

   7. Finally, send your changes to Matt Kaufmann, with a request that they
      be incorporated into the ACL2 sources and books.

  We now return to the remark labeled ``IMPORTANT'' above: undoing your
  changes.  This isn't necessary if you will not be using that local
  copy of ACL2 in the future.  But otherwise you may run into
  problems when you try to use git to merge changes into that local
  ACL2+books copy.  One option is to throw your changes away by
  standing in your local ACL2 directory and using the shell command:
  [47mgit checkout -f[0m.  But be careful --- this will throw away all your
  work!  So you might want to wait until your changes make it into
  the main (master) git branch.")
 (VERIFY-GUARDS-FORMULA
  (GUARD-FORMULA-UTILITIES)
  "View the guard proof obligation, without proving it

  See [verify-guards] and see [guard] for a discussion of guards.  This
  utility, which does not evaluate its argument, provides output
  showing the guard proof obligation (also known as the guard
  theorem) as printed by [47mverify-guards[0m, but without then carrying out
  a proof attempt.  See also [guard-formula-utilities] for related
  utilities.

    Example Forms:
    (verify-guards-formula foo)
    (verify-guards-formula foo :guard-debug t)
    (verify-guards-formula foo :guard-debug t :guard-simplify :limited)
    (verify-guards-formula foo :rrp t :otf-flg dont-care :xyz whatever)
    (verify-guards-formula (+ (foo x) (bar y)) :guard-debug t)

  [47mVerify-guards-formula[0m allows all keywords, but only pays attention to
  [47m:guard-debug[0m and [47m:guard-simplify[0m, which have the same effect as in
  [47m[verify-guards][0m (also see [guard-debug] and
  [guard-simplification]), and to [47m:rrp[0m, described below.  Apply
  [47mverify-guards-formula[0m to a name just as you would use
  [47m[verify-guards][0m, but when you only want the output that shows the
  guard proof obligation, without attempting a proof or creating an
  event.  If the first argument is not a symbol, then it is treated
  as the body of a [47m[defthm][0m event for which you want the guard proof
  obligation.

  The [47m:rrp[0m argument (``return redundant p'') is [47mnil[0m by default.  If its
  value is not [47mnil[0m, then in the case that the first argument is a
  guard-verified function symbol, the keyword [47m:REDUNDANT[0m is returned
  without any output.")
 (VERIFY-TERMINATION
  (EVENTS)
  "Convert a function from :program mode to :logic mode

    Example:
    (verify-termination fact)

    General Forms:
    (verify-termination fn dcl ... dcl)
    (verify-termination (fn1 dcl ... dcl)
                        (fn2 dcl ... dcl)
                        ...)

  where [47mfn[0m and the [47mfni[0m are function symbols having [47m:[0m[47m[program][0m mode (see
  [defun-mode]) and all of the [47mdcl[0ms are either [47m[declare][0m forms or
  [documentation] strings.  The first form above is an abbreviation
  for

    (verify-termination (fn dcl ... dcl))

  so we limit our discussion to the second form.  Each of the [47mfni[0m must
  be in the same clique of mutually recursively defined functions,
  but not every function in the clique need be among the [47mfni[0m.

  [47mVerify-termination[0m attempts to establish the admissibility of the
  [47mfni[0m. [47mVerify-termination[0m retrieves their definitions, creates
  modified definitions using the [47mdcl[0ms supplied above, and resubmits
  these definitions.  You could avoid using [47mverify-termination[0m by
  typing the new definitions yourself.  So in that sense,
  [47mverify-termination[0m adds no new functionality.  But if you have
  prototyped your system in [47m:[0m[47m[program][0m mode and tested it, you can
  use [47mverify-termination[0m to resubmit your definitions and change
  their [defun-mode]s to [47m:[0m[47m[logic][0m, adding [hints] without having to
  retype or recopy the code.

  The [47m[defun][0m [command] executed by [47mverify-termination[0m is obtained by
  retrieving the [47m[defun][0m (or [47m[mutual-recursion][0m) [command] that
  introduced the clique in question and then possibly modifying each
  definition as follows.  Consider a function, [47mfn[0m, in the clique.  If
  [47mfn[0m is not among the [47mfni[0m above, its definition is left unmodified
  other than to add [47m(declare (xargs :mode :logic))[0m.  Otherwise, [47mfn[0m is
  some [47mfni[0m and we modify its definition by inserting into it the
  corresponding [47mdcl[0ms listed with [47mfni[0m in the arguments to
  [47mverify-termination[0m, as well as [47m(declare (xargs :mode :logic))[0m.  In
  addition, we throw out from the old declarations in [47mfn[0m the [47m:mode[0m
  specification and anything that is specified in the new [47mdcl[0ms.

  For example, suppose that [47mfact[0m was introduced with:

    (defun fact (n)
      (declare (type integer n)
               (xargs :mode :program))
      (if (zp n) 1 (* n (fact (1- n))))).

  Suppose later we do [47m(verify-termination fact)[0m.  Then the following
  definition is submitted.

    (defun fact (n)
      (declare (type integer n))
      (if (zp n) 1 (* n (fact (1- n))))).

  Observe that this is the same definition as the original one, except
  the old specification of the [47m:mode[0m has been deleted so that the
  [defun-mode] now defaults to [47m:[0m[47m[logic][0m.  Although the termination
  proof succeeds, ACL2 also tries to verify the [guard], because we
  have (implicitly) provided a [guard], namely [47m(integerp n)[0m, for this
  function.  (See [guard] for a general discussion of guards, and see
  [type-spec] for a discussion of how type declarations are used in
  guards.)  Unfortunately, the [guard] verification fails, because
  the subterm [47m(zp n)[0m requires that [47mn[0m be nonnegative, as can be seen
  by invoking [47m:args zp[0m.  (For a discussion of termination issues
  relating to recursion on the naturals, see [zero-test-idioms].)  So
  we might be tempted to submit the following:

    (verify-termination
     fact
     (declare (xargs :guard (and (integerp n) (<= 0 n))))).

  However, this is considered a changing of the guard (from [47m(integerp
  n)[0m), which is illegal.  If we instead change the guard in the
  earlier [47mdefun[0m after undoing that earlier definition with [47m:[0m[47m[ubt][0m[47m
  fact[0m, then [47m(verify-termination fact)[0m will succeed.

  It may be necessary to specify an appropriate [47m:ruler-extenders[0m in a
  [47mdcl[0m supplied to [47mverify-termination[0m.  This determines the [rulers]
  used in the termination proofs and also the case analysis in the
  induction scheme suggested by the admitted function.  See
  [induction-coarse-v-fine-grained].

  [31;1mRemark on system functions.[0m There may be times when you want to apply
  [47mverify-termination[0m (and also, perhaps, [47m[verify-guards][0m) to
  functions that are predefined in ACL2.  It may be necessary in such
  cases to modify the system code first.  See
  [verify-guards-for-system-functions] for a discussion of the
  process for contributing updates to the system code and [books]
  with such [47mverify-termination[0m or [47m[verify-guards][0m [events], perhaps
  resulting in more system functions being built-in as
  [guard]-verified.  To see which built-in functions have already
  received such treatment, see community books directory
  [47mbooks/system/[0m; or, evaluate the constant
  [47m*system-verify-guards-alist*[0m, which specifies a list of functions
  whose guard-verification is proved by including that book.  See the
  above URL for more details.

  Note that if [47mfn1[0m is already in [47m:[0m[47m[logic][0m mode, then the
  [47mverify-termination[0m call has no effect.  It is generally considered
  to be redundant, in the sense that it returns without error; but if
  the [47mfn1[0m is a constrained function (i.e., introduced in the
  signature of an [47m[encapsulate][0m, or by [47m[defchoose][0m), then an error
  occurs.  This error is intended to highlight unintended uses of
  [47mverify-termination[0m; but if you do not want to see an error in this
  case, you can write and use your own macro in place of
  [47mverify-termination[0m.  The following explanation of the
  implementation of [47mverify-termination[0m may help with such a task.

  We conclude with a discussion of the use of [47m[make-event][0m to implement
  [47mverify-termination[0m.  This discussion can be skipped; we include it
  only for those who want to create variants of [47mverify-termination[0m,
  or who are interested in seeing an application of [47m[make-event][0m.

  Consider the following proof of [47mnil[0m, which succeeded up through
  Version_3.4 of ACL2.

    (encapsulate
     ()
     (defun foo (x y)
       (declare (xargs :mode :program))
       (if (or (zp x) (zp y))
           (list x y)
         (foo (1+ x) (1- y))))
     (local (defun foo (x y)
              (declare (xargs :measure (acl2-count y)))
              (if (or (zp x) (zp y))
                  (list x y)
                (foo (1+ x) (1- y)))))
     (verify-termination foo))

    (defthm bad-lemma
      (zp x)
      :hints ((\"Goal\" :induct (foo x 1)))
      :rule-classes nil)

  How did this work?  In the first pass of the [47m[encapsulate][0m, the
  second [47m[defun][0m of [47mfoo[0m promoted [47mfoo[0m from [47m:program[0m to [47m:logic[0m mode,
  with [47my[0m as the unique measured variable.  The following call to
  [47mverify-termination[0m was then redundant.  However, on the second pass
  of the [47m[encapsulate][0m, the second ([47m[local][0m) definition of [47mfoo[0m was
  skipped, and the [47mverify-termination[0m event then used the first
  definition of [47mfoo[0m to guess the measure, based (as with all guesses
  of measures) on a purely syntactic criterion.  ACL2 incorrectly
  chose [47m(acl2-count x)[0m as the measure, installing [47mx[0m as the unique
  measured variable, which in turn led to an unsound induction scheme
  subsequently used to prove [47mnil[0m (lemma [47mbad-lemma[0m, above)

  Now, [47mverify-termination[0m is a macro whose calls expand to [47m[make-event][0m
  calls.  So in the first pass above, the [47mverify-termination[0m call
  generated a [47mdefun[0m event identical to the [47m[local][0m [47m[defun][0m of [47mfoo[0m,
  which was correctly identified as redundant.  That expansion was
  recorded, and on the second pass of the [47m[encapsulate][0m, the
  expansion was recalled and used in place of the [47mverify-termination[0m
  call (that is how [47m[make-event][0m works).  So instead of a measure
  being guessed for the [47mverify-termination[0m call on the second pass,
  the same measure was used as was used on the first pass, and a
  sound induction scheme was stored.  The attempt to prove [47mnil[0m (lemma
  [47mbad-lemma[0m) then failed.


Subtopics

  [Verify-guards-for-system-functions]
      Arranging that source functions come up as guard-verified

  [Verify-termination-on-raw-program-okp]
      Permit [47m[verify-termination][0m for functions with raw Lisp code.")
 (VERIFY-TERMINATION-ON-RAW-PROGRAM-OKP
  (VERIFY-TERMINATION)
  "Permit [47m[verify-termination][0m for functions with raw Lisp code.

  By default, it is not permitted to verify termination (see
  [VERIFY-TERMINATION]) for functions with raw Lisp code.  This
  restriction is important in general for preserving soundness; see
  [program-only].  However, in some cases it may be harmless to
  remove this restriction.  That can be done as follows.  Note that
  an active trust tag is required: in principle you can render ACL2
  unsound with this action!

    (defttag t)
    (remove-untouchable verify-termination-on-raw-program-okp nil)
    ; In the following, t can be replaced by an expression that evaluates to a
    ; list of symbols for which it is permitted to verify termination.
    (assign verify-termination-on-raw-program-okp t)")
 (VERSION
  (ABOUT-ACL2)
  "ACL2 Version Number

  To determine the version number of your copy of ACL2, evaluate the
  form [47m(@ acl2-version)[0m.  The value will be a string.  For example,

    ACL2 !>(@ acl2-version)
    \"ACL2 Version 3.4\"

  The part of the string after [47m\"ACL2 Version \"[0m is of the form [47mx.y[0m or
  [47mx.y.z[0m, optionally followed by a succession of values in
  parentheses, where [47mx[0m, [47my[0m, and [47mz[0m are natural numbers.  If [47mz[0m is
  omitted then it is implicitly 0.  We refer to [47mX[0m, [47my[0m, and [47mz[0m as the
  ``major'', ``minor'', and ``incrl'' fields, respectively.  The
  incrl field is used for incremental releases.  The discussion just
  below assumes that incremental releases are not employed at the
  user's site, i.e., the incrl fields are always 0.  We remove this
  assumption when we discuss incremental releases at the end of this
  documentation topic.

  [Books] are considered certified only in the same version of ACL2 in
  which the certification was done.  The [certificate] file records
  the version number of the certifying ACL2 and [include-book]
  considers the book uncertified if that does not match the current
  version number.  Thus, each time we release a new version of ACL2,
  previously certified books should be recertified.

  Note that there are over 150 constants in the system, most having to
  do with the fact that ACL2 is coded in ACL2.  Many of these, for
  example [47m*common-lisp-specials-and-constants*[0m and [47m*acl2-exports*[0m,
  may change from version to version, and this can cause unsoundness.
  For example, the symbol [47m'set-difference-eq[0m was added to
  [47m*acl2-exports*[0m in Version_2.9, so we can certify a book in
  Version_2.8 containing the following theorem, which is false in
  Version_2.9.

    (null (member 'set-difference-eq *acl2-exports*))

  Therefore, we need to disallow inclusion of such a book in a
  Version_2.9 session, which otherwise would allow us to prove [47mnil[0m.
  Furthermore, it is possible that from one version of the system to
  another we might change, say, the default values on some system
  function or otherwise make ``intentional'' changes to the axioms.
  It is even possible one version of the system is discovered to be
  unsound and we release a new version to correct our error.

  Therefore we adopted the draconian policy that books are certified by
  a given version of ACL2 and ``must'' be recertified to be used in
  other versions.  We put ``must'' in quotes because in fact, ACL2
  allows a book that was certified in one ACL2 version to be included
  in a later version, using [47m[include-book][0m.  But ACL2 does not allow
  [47m[certify-book][0m to succeed when such an [47m[include-book][0m is executed
  on its behalf.  Also, you may experience undesirable behavior if
  you avoid recertification when moving to a different version.
  Hence we recommend that you stick to the draconion policy of
  recertifying books when updating to a new ACL2 version.

  Furthermore, all bets are off if you certify a book using ACL2 built
  on one host Lisp implementation and include the book using ACL2
  built on a different host Lisp implementation.  For example, for
  most host Lisp implementations, the Lisp reader will interpret the
  token [47m2f[0m as a symbol; however, Common Lisp allows for the
  possibility that [47m2f[0m is read as a number.  In such a case, one could
  use the former ACL2 executable to certify a book containing the
  form

    (defthm my-thm
      (symbolp '2f)
      :rule-classes nil)

  but then use the latter ACL2 executable to include the book, even
  though for the latter ACL2 executable, [47m2f[0m is a number, not a
  symbol.  Of course, one would expect an error because of a
  [book-hash] mismatch) in such case.  But these do not provide
  guaranteed protection against including uncertified books.

  [3mIncremental releases.[0m

  From time to time, so-called ``incremental releases'' of ACL2 are
  made available.  These releases are thoroughly tested on at least
  two platforms; ``normal'' releases, on the other hand, are
  thoroughly tested on many more platforms (perhaps a dozen or so)
  and are accompanied by updates to the ACL2 home page.  We provide
  incremental releases in order to provide timely updates for ACL2
  users who want them, without imposing unnecessary burdens on either
  on the ACL2 implementors or on ACL2 users who prefer to update less
  frequently.  The implementors expect users to update their copies
  of ACL2 when normal releases are made available, but not
  necessarily when incremental releases are made available.

  Incremental releases are accompanied by a bump in the incrl field of
  the version field, while normal releases are accompanied by a bump
  in the minor or (much less frequently) major field and zeroing out
  of the incrl field.  Note that incremental releases are
  full-fledged releases.")
 (W
  (STATE)
  "The current ACL2 [world]

  The value of the form [47m(w state)[0m is the current ACL2 world.  See
  [world].")
 (WALKABOUT
  (DEBUGGING)
  "Explore an ACL2 cons tree

  By typing [47m(walkabout x state)[0m for an ACL2 term [47mx[0m whose value is a
  [47m[cons][0m tree, you can walk around that tree.  For example, ACL2
  developers often use this utility to explore the ACL2 logical
  [world].

  When you issue a [47mwalkabout[0m command, a summary of commands will be
  printed before you enter an interactive loop.

    Commands:
    1, 2, ..., up, nx, bk, pp, (pp n), (pp lev len), =, (= symb),
    (cmds c1 c2 ... cn), and q.

  In the interactive [47mwalkabout[0m loop, a positive integer n takes you to
  the nth position, while [47mup[0m takes you up a level.  The commands [47mnx[0m
  and [47mbk[0m take you to the next and previous position, respectively, at
  the same level.  The command [47mpp[0m prints the current object in full,
  while [47m(pp level length)[0m hides sub-objects below the indicated level
  and past the indicated length, if non-[47mnil[0m; see [evisc-tuple].  The
  command [47m(pp n)[0m abbreviates [47m(pp n n)[0m, so in particular [47m(pp nil)[0m is
  equivalent to [47mpp[0m.  The commands [47m=[0m and [47mcmds[0m are described below.

  Note that the commands above work in any package: [47mup[0m, [47mnx[0m, [47mbk[0m, [47mpp[0m, [47m=[0m,
  [47mcmds[0m, and [47mq[0m are converted to the [47m\"ACL2\"[0m package if the current
  package is not [47m\"ACL2\"[0m.  Also, as a convenience, the single
  character [47m0[0m is accepted as equivalent to [47mup[0m.

  The following example illustrates the commands described above.

    ACL2 !>(walkabout (append '(a (b1 b2 b3)) '(c d e f)) state)

    Commands:
    1, 2, ..., up, nx, bk, pp, (pp n), (pp lev len), =, (= symb),
    (cmds c1 c2 ... cn), and q.

    (A (B1 B2 B3) C ...)
    :2
    (B1 B2 B3)
    :3
    B3
    :up
    (B1 B2 B3)
    :nx
    C
    :nx
    D
    :up
    (A (B1 B2 B3) C ...)
    :pp
    (A (B1 B2 B3) C D E F)
    :(pp 4)
    (A (B1 B2 B3) C D ...)
    :(pp 1 4)
    (A # C D ...)
    :(pp nil 2)
    (A (B1 B2 ...) ...)
    :q
    ACL2 !>

  The command [47m(cmds c1 c2 ... cn)[0m just executes each of the [47mci[0m,
  sequentially.

  The command [47mq[0m simply causes an exit from the [47mwalkabout[0m loop.

  The command [47m=[0m also exits, but returns the current object as the value
  in an ACL2 [error-triple].

  The command [47m(= symb)[0m saves an association of [47msymb[0m with the current
  object, which can be retrieved outside the [47mwalkabout[0m loop using the
  macro [47mwalkabout=[0m, as illustrated below.

    ...
    :pp
    (B1 B2 B3)
    :(= my-list)
    (walkabout= MY-LIST) is
    (B1 B2 B3)
    :q
    ACL2 !>(walkabout= MY-LIST)
    (B1 B2 B3)
    ACL2 !>

  Finally, we remark that for trees that are not true-lists, [47mwalkabout[0m
  treats the dot as an object that can be ``walked about''.  The
  following example illustrates this point.

    ACL2 !>(walkabout '(c d e . f) state)

    Commands:
    1, 2, ..., up, nx, bk, pp, (pp n), (pp lev len), =, (= symb),
    (cmds c1 c2 ... cn), and q.

    (C D E . F)
    :3
    E
    :nx
    .
    :nx
    F
    :up
    (C D E . F)
    :4
    .
    :up
    (C D E . F)
    :5
    F
    :")
 (WARNINGS
  (OUTPUT-CONTROLS)
  "Warnings emitted by the ACL2 proof process

  The prover can emit many warnings when processing [events].  See
  [set-inhibit-warnings] and see [set-inhibit-output-lst] for how to
  disable and enable them.  See also [47m[toggle-inhibit-warning][0m and
  [47m[set-warnings-as-errors][0m.


Subtopics

  [Set-warnings-as-errors]
      Changing [warnings] to hard [errors] (and vice-versa)")
 (WARRANT
  (APPLY$)
  "Giving [47m[apply$][0m permission to handle a user-defined function in
  proofs

  The word ``warrant'' is defined in the Merriam-Webster dictionary as
  ``a commission or document giving authority to do something....''

  The discussion below mentions the concept of [47m[badge][0ms, which are
  easily confused with warrants.  See the discussion of [31;1mBadges versus
  Warrants[0m at the top of [47m[defbadge][0m.  But roughly put, badges extend
  the ACL2 syntax and warrants extend the proof theory.  You'll need
  a badge for [47mfn[0m to allow the system to syntactically analyze [47m(apply$
  'fn ...)[0m.  You'll need a both a badge and a warrant for [47mfn[0m if you
  wish to reason about that term with ACL2.  Badges and warrants also
  have impact on evaluation of forms in the top-level loop.  See
  [guarantees-of-the-top-level-loop].

  In the ACL2 proof theory, the functions [47m[badge][0m and [47m[apply$][0m are
  undefined on user-defined function symbols.  To be precise, when
  presented with a user-defined function symbol, [47mbadge[0m calls the
  weakly constrained function [47mbadge-userfn[0m and [47mapply$[0m calls the
  weakly constrained function [47mapply$-userfn[0m.  Warrants are terms
  that, if available as hypotheses in a conjecture, further constrain
  those functions for specific function symbols.  If there is a
  warrant for [47mfn[0m among the hypotheses of a conjecture, [47m(badge 'fn)[0m
  and [47m(apply$ 'fn ...)[0m can be simplified appropriately.  In
  particular, [47m(badge 'fn)[0m is simplified to the actual badge of [47mfn[0m and
  [47m(apply$ 'fn ...)[0m is simplified to the appropriate application of [47mfn[0m
  provided the arguments are suitably [tame].  We think of the
  warrant for [47mfn[0m giving [47mbadge[0m and [47mapply$[0m authority to expand on [47m'fn[0m.
  For reasons of logical consistency not every [47mfn[0m can have a warrant.
  Warrants are issued, when possible, by [47m[defwarrant][0m.

  In the ACL2 evaluation theory --- a consistent extension of the proof
  theory --- all warrants issued by [47mdefwarrant[0m are implicitly
  assumed, meaning [47mbadge[0m and [47mapply$[0m can be executed on warranted
  user-defined function symbols at the top-level of the ACL2 loop
  without explicit mention of the warrants.  In fact, just as the
  evaluation theory can --- ``magically'' --- execute [47m:program[0m mode
  functions despite the absence of any axioms about them, the
  evaluation theory can execute a well-formed [47mapply$[0m on any [47m:program[0m
  mode function that has a [47m[badge][0m.  However, for a [47m:logic[0m mode
  function [47mfn[0m, the top-level loop cannot evaluate [47m(apply$ 'fn ...)[0m
  unless [47m(defwarrant fn)[0m has previously succeeded.  See
  [guarantees-of-the-top-level-loop].)  For a discussion of the
  restrictions on when a [47mfn[0m can be warranted, see [47m[defwarrant][0m.  This
  topic discusses warrants [3mper se[0m, their names, their logical
  meaning, when they must be explicitly added as hypotheses to
  conjectures, and their consistency.


Logical Definition of the Warrant of a Function

  If [3mfn[0m has a warrant, then the warrant is the term
  [47m(apply$-warrant-[0m[3mfn[0m[47m)[0m, i.e., a call of the 0-ary warrant function
  named, [47mapply$-warrant-[0m[3mfn[0m.  That warrant function name is admitted
  to the logic when [47mdefwarrant[0m succeeds on [47mfn[0m.

  The warrant function for [47mfn[0m, introduced by [47m(defwarrant fn)[0m, is
  defined with [47m[defun-sk][0m because the warrant must specify the values
  returned by [47m(apply$ 'fn args)[0m [3mfor all possible[0m [47margs[0m.  Recall that
  [47m[badge][0m and [47m[apply$][0m defer to two undefined functions, [47mbadge-userfn[0m
  and [47mapply$-userfn[0m, when they are applied to user-defined function
  symbols.  The warrant for [47mfn[0m is actually phrased in terms of those
  two undefined functions.  By stipulating their values on [47m'fn[0m the
  warrant determines the values of [47m(badge 'fn)[0m and [47m(apply$ 'fn ...)[0m.
  To create the warrant function for [47mfn[0m, [47mdefwarrant[0m must turn the
  ilks of [47mfn[0m into tameness requirements on the corresponding elements
  of the [47margs[0m to which [47mfn[0m will be applied by [47mapply$[0m.  Each [47m:FN[0m
  argument must be a [tame] function and each [47m:EXPR[0m argument must be
  a [tame] expression.

  It is easiest to understand the above paragraph by looking at the
  generated warrant function for [47mfoldr[0m, whose definition is shown at
  the top of the documentation for [47m[apply$][0m and whose [badge] is
  [47m(APPLY$-BADGE 3 1 NIL :FN NIL)[0m, indicating that [47mfoldr[0m takes 3
  arguments of ilks [47mNIL[0m, [47m:FN[0m, and [47mNIL[0m, and returns 1 result.  The
  warrant function for [47mfoldr[0m is defined as follows.

    (defun-sk apply$-warrant-foldr ()
      (forall (args)
        (implies (tamep-functionp (cadr args))
                 (and (equal (badge-userfn 'FOLDR)
                             '(APPLY$-BADGE 3 1 NIL :FN NIL))
                      (equal (apply$-userfn 'FOLDR args)
                             (foldr (car args)
                                    (cadr args)
                                    (caddr args))))))
      :constrain t)

  Notice also that the tameness hypothesis involves the universally
  quantified variable [47margs[0m, but that the first conjunct of the
  conclusion does not mention that variable.  So we can read
  [47m(apply$-warrant-foldr)[0m as equivalent to the conjunction of:

    (equal (badge-userfn 'FOLDR)
           '(APPLY$-BADGE 3 1 NIL :FN NIL))

  and

    (forall (args)
        (implies (tamep-functionp (cadr args))
                 (equal (apply$-userfn 'FOLDR args)
                        (foldr (car args)
                               (cadr args)
                               (caddr args)))))

  The first specifies the value of the undefined function used by [47mbadge[0m
  to find the badge of a user-defined function.  The second specifies
  the behavior of the undefined function used by [47mapply$[0m to [47mapply$[0m
  [47m'FOLDR[0m and requires that the second element of [47margs[0m be a [tame]
  function.

  Finally, notice that the warrant function for [47mfoldr[0m,
  [47mapply$-warrant-foldr[0m, ancestrally depends on [47mfoldr[0m: [47mfoldr[0m is called
  in the [47mdefun-sk[0m.  That is crucial to avoiding the [47mLOCAL[0m problem
  noted in [introduction-to-apply$].  If the warrant for [47mfoldr[0m is
  required for a theorem's proof (which it will be if the proof
  involves ``expanding'' [47m(apply$ 'FOLDR ...)[0m), then the theorem is
  ancestrally dependent on [47mfoldr[0m even though that function symbol may
  not be otherwise mentioned in the theorem.  That, in turn, means
  that [47mfoldr[0m may not be a locally defined symbol in the environment
  from which the theorem is exported.

  Now consider a function symbol that returns more than one result.
  Suppose the badge of [47madd-and-subtract[0m is [47m(APPLY$-BADGE 2 2 . T)[0m,
  meaning it takes two ordinary objects and returns two results.  The
  function is tame and so no tameness requirements are imposed on its
  application.  Its warrant is defined

    (defun-sk apply$-warrant-add-and-subtract ()
      (forall (args)
        (and (equal (badge-userfn 'add-and-subtract)
                    '(APPLY$-BADGE 2 2 . T))
             (equal (apply$ 'add-and-subtract args)
                    (mv-list 2
                             (add-and-subtract (car args) (cadr args)))))))


Rewrite Rules that Lift and Force the Warrant

  Once [47mdefwarrant[0m has introduced the warrant function for [3mfn[0m it proves
  two rewrite rules, conjoined under the name [47mapply$-[0m[3mfn[0m, that
  ``lifts'' the warrant from the level of the two undefined functions
  to the level of [47mbadge[0m and [47mapply$[0m.  In the case of [47mfoldr[0m the rules
  are:

    (defthm apply$-foldr
      (and (implies (force (apply$-warrant-foldr))
                    (equal (badge 'FOLDR)
                           '(APPLY$-BADGE 3 1 NIL :FN NIL)))
           (implies (and (force (apply$-warrant-foldr))
                         (tamep-functionp (car (cdr args))))
                    (equal (apply$ 'FOLDR args)
                           (foldr (car args)
                                  (car (cdr args))
                                  (car (cdr (cdr args))))))))

  Observe that these rules say that if [47m(apply$-warrant-foldr)[0m is
  available as a hypothesis, then [47m(badge 'FOLDR)[0m is [47m(APPLY$-BADGE 3 1
  NIL :FN NIL)[0m and [47m(apply$ 'FOLDR args)[0m has the naively expected
  behavior of calling [47mfoldr[0m, provided the second element of [47margs[0m is a
  [47mtamep-functionp[0m.  Also note that the warrant hypothesis is [47m[force][0md
  in both rules.

  The effect of these rules is if either [47m(badge 'FOLDR)[0m or any instance
  of [47m(apply$ 'FOLDR args)[0m arises during a proof, the warrant for
  [47mfoldr[0m is raised and either relieved or forced.  The [47mbadge[0m and
  [47mapply$[0m terms are simplified whether the warrant is present or not,
  but if the warrant is not among the hypotheses and the proof is
  otherwise successful, the warrant for [47mfoldr[0m will show up in a
  checkpoint.

  If no warrant has been issued for [47mfoldr[0m these terms will not
  simplify.


Determining the Necessary Warrants

  [3mThere is no easy way to determine the warrants you'll need to make a
  formula a theorem.[0m At first this seems to be a problem that could
  be solved with a few rules of thumb and indeed, there are a few
  useful rules.  But they don't guarantee success.

  [3mRule 1.[0m One way to determine sufficient warrants for a formula to be
  a theorem is to attempt to prove the formula without warrants and
  see the checkpoints.  This may have to be repeated to collect
  sufficient warrants and can be frustrating.  Furthermore, as
  illustrated further below, it can lead to unnecessary warrants.

  Most users attempt to anticipate what warrants are needed.

  [3mRule 2.[0m You will probably need a warrant hypothesis for every
  user-defined function symbol mentioned in the fully translated term
  occupying any slot of ilk [47m:FN[0m in the formula you're trying to
  prove.  The two common situations are quoted user-defined function
  symbols in such slots and [47m[lambda$][0m expressions.  In the latter
  case, you must consider every user-defined function symbol in the
  [3mfully translated[0m body of the [47m[lambda$][0m expression.  (If you've
  ignored our recommendations to use [47mlambda$[0m instead of hand-typed
  quoted [47mLAMBDA[0m objects, you'll have to look at those too.)

  But Rule 2 says ``probably need a warrant'' because whether you do or
  not depends on what you're proving.  In the examples below, suppose
  we have carried out these events.

    (include-book \"projects/apply/top\" :dir :system)

    (defun$ sq (x) (* x x))

  and recall that [47mcollect$[0m is [47m[loop$][0m scion logically defined as

    (defun$ collect$ (fn lst)
      (if (endp lst)
          nil
          (cons (apply$ fn (list (car lst)))
                (collect$ fn (cdr lst)))))

  No warrant is [3mreally[0m needed to prove

    (thm (equal (collect$ 'sq (append a b))
                (append (collect$ 'sq a) (collect$ 'sq b))))

  because it [3mcould[0m be proved by appealing to the more general

    (thm (equal (collect$ fn (append a b))
                (append (collect$ fn a)
                        (collect$ fn b))))

  which makes clear that the properties of [47msq[0m are totally irrelevant to
  the proof of this formula.

  But if you followed Rule 1 and just submitted

    (thm (equal (collect$ 'sq (append a b))
                (append (collect$ 'sq a)
                        (collect$ 'sq b))))

  the proof would fail with a checkpoint indicating that you need the
  warrant for [47msq[0m.  That happens because the :rewrite rules proved by
  [47mdefwarrant[0m, discussed in the previous section and named [47mapply$-sq[0m
  in the case of [47msq[0m, fire and force that warrant.  However, you could
  disable that rule and get the proof without a warrant.

  To further dim our hopes for a simple way to identify warrants,
  consider

    (defun$ square (i) (apply$ 'sq (list i)))

  and then the proof of

    (thm (equal (square i) (* i i)))

  This theorem requires the warrant for [47msq[0m even though [47m'sq[0m is not
  mentioned in the top-level statement of the theorem.  The problem,
  of course, is that the mention of [47m'sq[0m in a [47m:FN[0m slot is mentioned in
  the definition of [47msquare[0m.

  [3mRule 3.[0m You may need warrants for any symbols used in [47m:FN[0m slots in
  the definitions of any function appearing in the formula.

  And then of course there is the usual reason you need forgotten
  hypotheses: some lemma critical to your proof has that hypothesis.

  For example, one could imagine proving

    (defthm lemma
      (implies (apply$-warrant-sq)
               (equal (square x) (sq x))))

  and then try to prove

    (thm (equal (square x) (* x x))
         :hints ((\"Goal\" :in-theory (disable square))))

  hoping the lemma would reduce [47m(square x)[0m to [47m(sq x)[0m and then [47m(sq x)[0m
  would expand to [47m(* x x)[0m.  But of course, the lemma isn't applicable
  because we can't establish its hypothesis.  The point here is that
  another source of required warrants can be the warrant hypotheses
  of any lemmas needed for the proof.  We could posit a ``Rule 4''
  but what's the point?

  Returning to the first thing we said in this section, there is no
  easy sure-fire way to determine the warrants you'll need.  It just
  depends on the functions you're manipulating, the cases explored in
  the proof, the hypotheses of crucial lemmas, etc.  However, our
  experience is that it's not nearly so hard as we're suggesting
  here!

  Basically you'll need a warrant for [47mfn[0m if the proof requires [47mapply$[0m
  to behave as naively expected on [47m'fn[0m or the warrant is required for
  some lemma.  Chances are you'll know when you're depending on the
  meaning of a quoted symbol and when you're not.  And Rule 1 will
  eventually get you there though it may generate unnecessary warrant
  hypotheses.

  There is another piece of good news perhaps best explained by
  example.

  Imagine that you've defined and warranted your own versions of the
  familiar list concatenation and list reverse functions under the
  names [47map[0m and [47mrv[0m.

    (defun$ ap (x y)
      (if (endp x)
          y
          (cons (car x)
                (ap (cdr x) y))))

    (defun$ rv (x)
      (if (endp x)
          nil
          (ap (rv (cdr x))
              (list (car x)))))

  What warrant(s) do you need to prove

    (implies (true-listp x)
             (equal (apply$ 'rv (list (apply$ 'rv (list x)))) x))?

  You clearly need the warrant for [47mrv[0m.  But do you need the warrant for
  its subfunction [47map[0m?  Some users fall into the trap of thinking they
  do.  They think they'll need warrants for all the subfunctions of
  any function requiring a warrant.  We fall into this trap when we
  think [3mall evaluation[0m is carried out by [47mev$[0m and [47mapply$[0m.  Put another
  way, if we defined

    (defun$ rv1 (x)
      (if (endp x)
          nil
          (apply$ 'ap
                  (list (rv1 (cdr x))
                        (list (car x))))))

  and then tried to prove

    (implies (true-listp x)
             (equal (apply$ 'rv1 (list (apply$ 'rv1 (list x)))) x))

  we would indeed need warrants for both [47mrv1[0m and [47map[0m, as per Rule 3,
  because [47mrv1[0m [47mapply$[0ms [47m'ap[0m.

  But the warrant for the original [47mrv[0m says that [47m(apply$ 'rv args)[0m is
  (unconditionally) equal to [47m(rv (car args))[0m.  There are no [47mapply$[0ms
  left in the problem once we get to a call of the ACL2 function [47mrv[0m.
  We don't need any warrants, even to evaluate a function we called
  via [47mapply$[0m unless the definition of the function itself involves
  further [47mapply$[0ms.


A Convenient Macro for Conjoining Warrants

  Because ``[47mAPPLY$-WARRANT-[0m[3mfn[0m'' is hard to remember, we provide a macro
  for referring to the conjunction of warrant terms for a list of
  functions.

    General Form:
    (warrant fn1 fn2 ... fnk)

  where each [47mfni[0m is the name of a defined function on which [47mdefwarrant[0m
  has been previously called and succeeded.  (Actually, we allow the
  [47mfni[0m to include certain primitive function symbols already built
  into [47mapply$[0m, but for the moment we ignore the possible presence of
  such symbols among the arguments to [47mwarrant[0m.)  [47m(Warrant fn1 fn2 ...
  fnk)[0m expands to:

    (AND (FORCE (APPLY$-WARRANT-fn1))
         (FORCE (APPLY$-WARRANT-fn2))
         ...
         (FORCE (APPLY$-WARRANT-fnk)))

  Because there are over 800 ACL2 primitives built into [47mapply$[0m, it can
  be hard to look at a conjecture involving, say, a [47m[lambda$][0m term,
  and list all and only the function names that need warrants.  For
  example, if the body of the [47mlambda$[0m term calls [47mlogeqv[0m it will
  expand into [47mbinary-logeqv[0m and the diligent user might anticipate,
  accurately, that the [47mev$[0m of that body will involve [47m(apply$
  'BINARY-LOGEQV ...)[0m and thus might suppose that [47mbinary-logeqv[0m be
  included among the [47mfni[0m listed in the [47mwarrant[0m hypothesis.  But no
  warrant for [47mbinary-logeqv[0m exists, that is,
  [47mapply$-warrant-binary-logeqv[0m is not defined, because [47mbinary-logeqv[0m
  is built into [47mapply$[0m.  For this reason, we do not insist that every
  [47mfni[0m in [47mwarrant[0m's argument be a function possessing a warrant.
  Instead, the [47mwarrant[0m macro ignores those [47mfni[0m built into [47mapply$[0m.  It
  does cause an error if one of the [47mfni[0m has no warrant and is not
  built in.

  The [47m(warrant fn1 fn2 ... fnk)[0m macro [47m[force][0ms the warrants because (a)
  we assume the only use of the macro is to add warrant hypotheses to
  conjectures and (b) by forcing warrants aggressively the prover
  ``almost completes'' more proofs and enters a forcing round that
  highlights the need to assume those warrants.  When a rewrite rule,
  for example, is conditioned on a warrant that is not forced (as
  would happen if you added the hyps [47m(apply$-warrant-fn1)[0m,
  [47m(apply$-warrant-fn2)[0m, etc.), then the rule will not fire if a
  subsequent conjecture omitted the warrants.  Of course, this raises
  the question ``But are all the warrants really true?''


Why Warrants Don't Render Theorems Vacuous

  Adding warrants to formulas certainly restricts (weakens) the
  resulting theorem since it is only applicable when the warrant is
  assumed.  But an important question to ponder is whether adding
  warrants can actually make a formula vacuously valid?  That is, can
  a set of warrants simply be unsatisfiable so that any formula
  having that set of warrants among its hypotheses is a theorem?  Put
  another way, is there a model for the set of all warrants
  introduced by [47m[defwarrant][0m?

  The answer is yes.  This is discussed in {``Limited Second-Order
  Functionality in a First-Order Setting'' |
  http://www.cs.utexas.edu/users/kaufmann/papers/apply/index.html} by
  Matt Kaufmann and J Strother Moore.  For any set of functions
  warranted by [47mdefwarrant[0m it is possible to [3mdefine[0m, under the
  standard ACL2 definitional principle, versions of those functions
  (together with [47mapply$[0m, [47mev$[0m, etc.) and then make attachments to the
  undefined [47mbadge-userfn[0m and [47mapply$-userfn[0m, and so that every warrant
  is provably equal to [47mT[0m.  In fact, the resultant theory is the basis
  of ACL2's evaluation theory where all warranted functions can be
  [47mapply$[0md (under the appropriate tameness requirements) without
  explicit mention of warrants.  The crux of the proof is admitting a
  big mutually recursive clique containing versions of [47mapply$[0m and all
  of its [scion]s, by inventing a measure that provably decreases as
  [47mapply$[0m and the scions call each other.  The keys to that measure's
  existence are the restrictions imposed by [47m[defwarrant][0m and
  [tame]ness.  See the paper for a sketch of the proof and see the
  comment titled [47mEssay on Admitting a Model for Apply$ and the
  Functions that Use It[0m in the ACL2 source file [47mapply-raw.lisp[0m.")
 (WATERFALL (POINTERS)
            "See [hints-and-the-waterfall].")
 (WATERFALL-PARALLELISM
  (PARALLEL-PROOF)
  "For ACL2(p): configuring the parallel execution of the waterfall

  See [set-waterfall-parallelism].")
 (WATERFALL-PARALLELISM-FOR-BOOK-CERTIFICATION
  (PARALLELISM)
  "For ACL2(p): using waterfall parallelism during book certification

  This [documentation] topic relates to the experimental extension of
  ACL2 supporting parallel execution and proof; see [parallelism].

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

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

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

  Note that there are books that will not certify when
  waterfall-parallelism is enabled.  See file
  [47macl2-customization-files/README[0m for more information, including how
  to certify essentially all books using waterfall parallelism.")
 (WATERFALL-PRINTING
  (PARALLEL-PROOF)
  "For ACL2(p): configuring the printing within the parallelized
  waterfall

  See [set-waterfall-printing].")
 (WEAK-LD-HISTORY-ENTRY-P (POINTERS)
                          "See [ld-history].")
 (WELL-FORMED-LAMBDA-OBJECTP
  (APPLY$)
  "Predicate for recognizing well-formed [47mLAMBDA[0m objects

    Example:                                    value
    (well-formed-lambda-objectp                   T
     '(lambda (x) (binary-+ '1 x))
     (w state))

    (well-formed-lambda-objectp                   NIL
     '(lambda (x) (+ 1 x))
     (w state))

    (well-formed-lambda-objectp                   T
     '(lambda (x)
        (declare (type (satisfies natp) x)
                 (xargs :guard (natp x)
                        :split-types t))
        (binary-+ '1 x))
     (w state))

    (well-formed-lambda-objectp                   NIL
     '(lambda (x)
        (declare (type (satisfies natp) x))
        (binary-+ '1 x))
     (w state))

    General Form:
    (well-formed-lambda-objectp obj wrld)

  [47mWell-formed-lambda-objectp[0m is a [47m:program[0m mode function that checks
  the well-formedness of an arbitrary ACL2 object being used as a
  [47mLAMBDA[0m object by [47m[apply$][0m.

  Before we tell you what ``well-formedness'' means in this context we
  collect some random related facts that we consider more important
  than its precise meaning!

  [47mLambda$[0m terms always translate to quoted well-formed [47mLAMBDA[0m objects
  unless translate signals an explanatory error.  Don't try to type
  well-formed [47mLAMBDA[0m objects as explicitly quoted constants.  Use
  [47m[lambda$][0m!

  Only well-formed [47mLAMBDA[0m objects can be compiled.  Use [47m[lambda$][0m.

  But the compiled code is not necessarily always run when a
  well-formed [47mLAMBDA[0m object is [47mapply$[0md!  The object must additionally
  be guard verified and its guards must be satisfied by the arguments
  supplied by [47mapply$[0m.  Well-formedness does not do guard
  verification.

  The definitional axiom for [47m[apply$][0m knows nothing about
  well-formedness.  It checks that the purported [47mLAMBDA[0m object
  satisfies [47m[tamep-lambdap][0m, which is a simpler [47m:logic[0m mode concept.
  If you are writing a definition or theorem about an arbitrary
  object to be used as a [47mLAMBDA[0m object by [47mapply$[0m, and want to
  restrict it to the kind of objects handled as [47mLAMBDA[0m objects by
  [47mapply$[0m, use the predicate [47mtamep-lambdap[0m to characterize the object.
  (Since [47mwell-formed-lambda-objectp[0m is in [47m:[0m[47m[program][0m mode and
  requires access to the world, using it in a [47m:logic[0m mode context
  would involve a lot of work!)

  Well-formedness implies tameness.  So if you write your [47mLAMBDA[0m
  objects with [47mlambda$[0m [47mapply$[0m will be able to handle them. But [47mapply$[0m
  can handle more objects than the Common Lisp compiler can.  Some
  tame [47mLAMBDA[0m objects can be applied faster than others.  The fast
  ones are recognized by [47mwell-formed-lambda-objectp[0m -- but also have
  to be guard verified and guard checked.  Applications of ill-formed
  but tame [47mLAMBDA[0m objects are evaluable, but the evaluation is done
  more slowly.  See the performance comparison in [47m[print-cl-cache][0m.

  We compare well-formedness to tameness at the end of this topic.

  You can't call this predicate on a [47mlambda$[0m term, as by

    (well-formed-lambda-objectp (lambda$ (x) x) (w state))

  because [47mlambda$[0m can only be called in slots of ilk [47m:FN[0m.  Furthermore,
  there's no point!  [47mLambda$[0m terms always translate to well-formed
  [47mLAMBDA[0m objects unless an explanatory error is signaled by
  translation.

  If you want to [3msee[0m the translation of a [47mlambda$[0m term, e.g., to copy
  the text and modify it to produce some similar [47mLAMBDA[0m object, use
  [47m:[0m[47m[translam][0m.  We sometimes do this to explore by example the
  restrictions on well-formedness.

  If you have a [47mLAMBDA[0m object, e.g., one printed by [47m[print-cl-cache][0m,
  that you suspect is ill-formed, this function won't tell you [3mwhy[0m it
  is ill-formed!  It will just tell you whether it's ill-formed.  If
  you want to know why, translate the quoted [47mLAMBDA[0m object with
  [47m:[0m[47m[translam][0m, which generates sometimes verbose error messages.

  The global setting of [47mset-ignore-ok[0m has no effect on well-formedness
  of [47mLAMBDA[0m objects.  [47mIGNORE[0m and [47mIGNORABLE[0m declarations inside the
  [47mLAMBDA[0m are effective.

    ACL2 !>(set-ignore-ok t)
    T
    ACL2 !>(well-formed-lambda-objectp
            '(LAMBDA (X Y)
               (DECLARE (XARGS :GUARD (NATP X) :SPLIT-TYPES T))
               (BINARY-+ '1 X))
            (w state))
    NIL

    ACL2 !>(well-formed-lambda-objectp
            '(LAMBDA (X Y)
               (DECLARE (XARGS :GUARD (NATP X) :SPLIT-TYPES T)
                        (IGNORE Y))
               (BINARY-+ '1 X))
            (w state))
    T

  There should be very few occasions on which you need to know what
  this predicate checks!

  That said, here are the rules enforced.

  An object is a well-formed [47mLAMBDA[0m object iff it has one of the
  following two forms:

    (LAMBDA vars tbody)          ; ``simple''  LAMBDA object
    (LAMBDA vars tdcl tbody)     ; ``declared'' LAMBDA object

  where

    * [47mvars[0m is a list of distinct legal variable names

    * [47mtdcl[0m, if present, is a [47mDECLARE[0m form containing, at most, [47mTYPE[0m,
      [47mIGNORE[0m, [47mIGNORABLE[0m, and [47mXARGS[0m keys.  The user of [47m[lambda$][0m may
      provide multiple [47mDECLARE[0m forms but when translated they are
      combined into one as shown here.

    * If an [47mXARGS[0m key is present it has exactly this form [47m(XARGS :GUARD
      tguard :SPLIT-TYPES T)[0m, where [47mtguard[0m is a [3mfully translated[0m
      logic mode term involving only the formal variables, [47mvars[0m.
      Note that the user of [47m[lambda$][0m may supply [47m:SPLIT-TYPES[0m [47mNIL[0m and
      may do so before or after the [47m:GUARD[0m, and the guard term need
      not be in translated form, but the resulting [47mLAMBDA[0m object has
      the form described here.

    * The [47m:GUARD[0m specified in [47mXARGS[0m must include as a conjunct every [47mTYPE[0m
      expression generated by any [47mTYPE[0m specs.  E.g., [47m(INTEGERP x)[0m
      must be a conjunct of [47mtguard[0m if [47m(TYPE INTEGER ... x ...)[0m is
      declared.  That is consistent with the [47m:SPLIT-TYPES[0m [47mT[0m setting
      and means the guard does not need to be extended any further
      with the [47mTYPES[0m.  The point of this restriction is to guarantee
      that the guard implies the types declared to the compiler.  But
      this is a purely syntactic check and so may at times require
      entering silly-looking guards.  For example, [47m(declare (type
      rational x) (xargs :guard (integerp x) :split-types t))[0m is
      ruled ill-formed because [47m(rationalp x)[0m is not a conjunct of the
      guard, even though it is logically implied by the guard.  So
      you'd have to use [47m(declare (type rational x) (xargs :guard (if
      (integerp x) (rationalp x) 'nil) :split-types t))[0m.  Note also
      that the guard is a fully translated conjunction, i.e., an [47mIF[0m,
      not an [47mAND[0m!  Order of the conjuncts does not matter.

      Note: The guard need not be tame (or even fully badged) because
      guards are irrelevant to the axioms of [47mapply$[0m.  But guards must
      be in [47m:logic[0m mode from the outset because we may have to prove
      guard obligations on-the-fly in evaluation (we do not want to
      try to convert functions used in the guard from from [47m:program[0m
      to [47m:logic[0m mode while doing an evaluation of an [47mapply$[0m).

    * [47mtbody[0m is a fully translated, [tame] term, involving no free variables
      and respecting the declared [47mIGNORE[0m and [47mIGNORABLE[0m declarations.

      Furthermore, in the case of a lambda object generated by [47mlambda$[0m,
      [47mtbody[0m is a ``tagged'' version of the translation of the body
      used in the [47mlambda$[0m expression.  Tagging involves use of a
      special form generated by [47mtag-translated-lambda$-body[0m and
      recognized by [47mlambda$-bodyp[0m.  This form contains the
      untranslated [47mlambda$[0m expression as well as the translation of
      its body.  For example, [47m(lambda$ (x) (+ 1 x))[0m translates to the
      tagged lambda object [47m'(LAMBDA (X) (RETURN-LAST 'PROGN
      'orig-form tbody))[0m, where [47morig-form[0m is [47m(LAMBDA$ (X) (+ 1 X))[0m
      and [47mtbody[0m is [47m(BINARY-+ '1 X)[0m.

      It may be helpful to use [47m:[0m[47m[translam][0m to inspect examples of the
      translations of [47mlambda$[0m expressions.


The Differences Between Well-Formed and Merely Tame Lambda Objects

  Roughly put, tame [47mLAMBDA[0m objects have to have one of the two basic
  shapes described above (simple or declared), the listed formals
  merely have to be symbols -- not necessarily variable symbols and
  not necessarily distinct.  The declaration, if present, is
  completely irrelevant and the body merely has to be a tame
  expression -- not necessarily closed with respect to the formals or
  respecting [47mIGNORE[0m or [47mIGNORABLE[0m declarations.  The meaning assigned
  to such an object when applied to some arguments is just the result
  delivered by [47mev$[0m under an alist formed by pairing the formals --
  including non-variables and any duplicates -- with the actuals.  If
  a free variable is encountered, [47mev$[0m gives it the value [47mNIL[0m courtesy
  of [47massoc[0m.

  This behavior is implemented by compiled Common Lisp only when
  well-formedness, guard verification, and guard checking approve of
  the object and its application.")
 (WELL-FORMEDNESS-GUARANTEE
  (RULE-CLASSES)
  "Guarantee that a metafunction or clause-processor returns a
  well-formed answer

  A [47m:well-formedness-guarantee[0m is a keyword attribute available in the
  [47m:[0m[47m[meta][0m and [47m:[0m[47m[clause-processor][0m [47m:[0m[47m[rule-classes][0m.  By default, when
  a metafunction or clause processor is applied, ACL2 checks that the
  output is well-formed (and does not contain certain ``forbidden''
  functions; see [47m[set-skip-meta-termp-checks][0m).  By providing a
  [47m:well-formedness-guarantee[0m when you store a [47m:meta[0m or
  [47m:clause-processor[0m rule, you can cause ACL2 to skip these runtime
  checks.

  This is considered an advanced feature that requires that you prove
  certain theorems; this is probably only worthwhile if your
  metafunctions or clause processors produce very large terms.
  Henceforth, we assume you are familiar with metafunctions and
  clause processors.

  This topic first exhibits a simple example of a well-formedness
  guarantee for a metafunction.  This example is really an outline; a
  self-contained, runnable example may be found in the
  [community-books] in file
  [47mbooks/demos/meta-wf-guarantee-example.lisp[0m.  Then we describe the
  acceptable values of the [47m:well-formedness-guarantee[0m keyword of both
  the [47m:meta[0m and [47m:clause-processor[0m rule-classes.  Next we show the
  forms of the theorems you must prove to provide such guarantees.
  Finally, we discuss the runtime effects of providing such
  guarantees.

  Example

  Suppose that [47mfn[0m is a vanilla metafunction that rewrites terms with
  top function symbol [47mTARGET[0m, of [47m[arity][0m 1.  The event storing [47mfn[0m as
  a metafunction would normally be something like this:

      (defthm fn-is-correct
        (implies (and (pseudo-termp x)
                      (alistp a))
                 (equal (evl x a)
                        (evl (fn x) a)))
        :rule-classes
        ((:meta :trigger-fns (TARGET))))

  where [47mevl[0m is an evaluator for all the function symbols known to [47mfn[0m.
  Suppose that to prove this theorem, [47mevl[0m must be able to interpret
  the symbols [47mTARGET[0m, [47mCONS[0m, and [47mIF[0m.  While the metatheorem for [47mfn[0m
  establishes that [47mfn[0m returns something with the same ``meaning''
  (under [47mevl[0m) as its input, it does not answer the question: does [47mfn[0m
  return a well-formed term, all of whose function symbols are in
  [47m:[0m[47m[logic][0m mode?  Given the above [47m:rule-class[0m, whenever the
  simplifier fires the [47m:meta[0m rule [47mfn-is-correct[0m by applying [47mfn[0m to a
  term, it checks that the value, [47mval[0m, is well-formed, by evaluating
  [47m(logic-termp val (w state))[0m.  The function [47m[logic-termp][0m checks
  that its argument is a [term] all of whose function symbols are in
  [47m:logic[0m mode.

  [31;1mFunction: [0m<logic-termp>

    (defun logic-termp (x wrld)
      (declare (xargs :guard (plist-worldp-with-formals wrld)))
      (and (termp x wrld)
           (logic-fnsp x wrld)))

  The [47mlogic-termp[0m check can be avoided if, before you store the rule
  [47mfn-is-correct[0m, you prove:

      (defthm fn-is-well-formed
        (implies (and (logic-termp x w)
                      (arities-okp '((TARGET . 1)
                                     (CONS . 2)
                                     (IF . 3))
                                   w))
                 (logic-termp (fn x) w))
        :rule-classes nil)

  and then you store [47mfn-is-correct[0m this way:

      (defthm fn-is-correct
        (implies (and (pseudo-termp x)
                      (alistp a))
                 (equal (evl x a)
                        (evl (fn x) a)))
        :rule-classes
        ((:meta :trigger-fns (TARGET)
                :well-formedness-guarantee fn-is-well-formed)))

  Acceptable Values

  Now we describe the values you may provide with the
  [47m:well-founded-guarantee[0m keyword of the [47m:meta[0m and the
  [47m:clause-processor[0m rule-classes.

      General Forms:
      :well-formedness-guarantee thm-name1
      :well-formedness-guarantee (thm-name1)
      :well-formedness-guarantee (thm-name1 thm-name2)

  where both [47mthm-name1[0m and [47mthm-name2[0m are the names of previously
  proved ``well-formedness theorems'' (see the next section);
  furthermore, [47mthm-name1[0m must be about the metafunction or clause
  processor being introduced, and [47mthm-name2[0m must be about the
  hypothesis metafunction (if any) associated with the metafunction.
  For [47m:meta[0m rules, all three forms are accepted, but the last form is
  required if the [47m:meta[0m rule involves a hypothesis metafunction.
  That is, to provide a [47m:well-formedness-guarantee[0m for a metatheorem
  with a hypothesis metafunction, you must supply both [47mthm-name1[0m and
  [47mthm-name2[0m.  For [47m:clause-processor[0m rules, you must use the first
  form.

  Each well-formedness theorem provides an ``arity alist'' that
  specifies the assumed arities of the function symbols known to the
  metafunction or clause processor.  The arities shown for the
  function symbols listed in that alist must be the same as the
  arities of those functions in the actual ACL2 logical [world]
  current at the time the [47m:meta[0m or [47m:clause-processor[0m is stored.
  Moreover, the function symbols in that alist must all be in
  [47m:[0m[47m[logic][0m mode.

  Furthermore, none of the function symbols in the arity alists should
  be ``forbidden'' function symbols as explained in
  [47m[set-skip-meta-termp-checks][0m.

  When the [47m:meta[0m or [47m:clause-processor[0m rule is stored, notes are made
  that will prevent the function symbols on the arity alists from
  becoming untouchable (and thus forbidden).  See [47m[push-untouchable][0m.

  The only way a function's arity or forbidden status can change, or
  that a function can transition out of [47m:logic[0m mode, is if the user
  has engaged in redefinition or activated a trust tag to add or
  remove untouchables.  Thus, the restrictions above are unimportant
  to most users.

  Well-Formedness Theorems

  Theorems must be proved to establish that metafunctions and clause
  processors return well-formed results.  These are called
  ``well-formedness theorems.'' Note: To say a theorem is a
  ``well-formedness theorem'' is a remark about the shape of the
  formula, not its rule-class.  There is no [47m:well-formedness-theorem[0m
  rule-class and a well-formedness theorem may be stored with any
  [47m:[0m[47m[rule-classes][0m that accept the syntax of the formula or as
  [47m:rule-classes[0m [47mnil[0m.  Indeed, if one of your metafunctions uses
  another function to produce a subterm of the metafunction's answer,
  you might need to prove a well-formedness theorem for the
  sub-function and make it a [47m:rewrite[0m rule.

  Well-formedness theorems for metafunctions and clause processors are
  similar but slightly different.  We deal with metafunctions and
  their corresponding hypothesis metafunctions (if any) first.  The
  shapes of the well-formedness theorems for a metafunction and
  hypothesis metafunction are identical, but remember that you must
  prove a well-formedness theorem for both the metafunction and the
  associated hypothesis metafunction.  So suppose [47mfn[0m is a
  metafunction or a hypothesis metafunction and let [47m(fn x ...)[0m be a
  legal call on distinct variable symbols.  (Recall that extended
  metafunctions and their hypothesis functions can take three
  arguments.)  Then the general form a well-formedness theorem for [47mfn[0m
  states that [47mfn[0m returns a [47m[termp][0m when given one, provided the
  arities of certain function symbols are as expected:

      General Form of Well-Formedness Theorem for a Metafunction:
      (implies (and (logic-termp x w)
                    (arities-okp '<alist> w))
               (logic-termp (fn x ...) w))

  where [47m<alist>[0m is an alist pairing function symbols with their
  assumed arities as illustrated in the opening example.  Note that
  the first argument of [47marities-okp[0m in the theorem is a quoted
  constant.  You may omit or reorder the hypotheses above and you may
  use different variable symbols in place of [47mx[0m and [47mw[0m, but they must
  be distinct and different from the variables in the ``[47m...[0m.''

  An example of [47m<alist>[0m is [47m((TARGET . 1) (CONS . 2) (IF . 3))[0m.
  Generally, the [47m<alist>[0m you provide should assign arities to every
  symbol known to [47mfn[0m, i.e., every function symbol known to the
  evaluator used in your correctness theorem.  If you inspect the
  definition of [47m[termp][0m you will see that it uses [47mw[0m to obtain arities
  of the function symbols in [47mx[0m.  The [47m[arities-okp][0m hypothesis
  restricts [47mw[0m to worlds where the function symbols known to [47mfn[0m have
  the arities you expect and are in [47m:[0m[47m[logic][0m-mode.  For example,
  given the [47m(arities-okp '<alist> w)[0m hypothesis for the [47m<alist>[0m
  above, the theorem prover will rewrite [47m(arity 'IF w)[0m to 3.  By
  default [47m[arity][0m and [47m[arities-okp][0m are disabled; and the following
  rewrite rules, which are part of ACL2's initial [world], will take
  care of calls like [47m(arity 'IF w)[0m and [47m(logicp fn w)[0m.

  [31;1mTheorem: [0m<arities-okp-implies-arity>

    (defthm arities-okp-implies-arity
      (implies (and (arities-okp user-table w)
                    (assoc fn user-table))
               (equal (arity fn w)
                      (cdr (assoc fn user-table)))))

  [31;1mTheorem: [0m<arities-okp-implies-logicp>

    (defthm arities-okp-implies-logicp
      (implies (and (arities-okp user-table w)
                    (assoc fn user-table))
               (logicp fn w)))

  Now we turn to the well-formedness theorem for a clause processor,
  [47mcl-proc[0m.  Let [47m(cl-proc x ...)[0m be a legal call on distinct variable
  symbols.  The theorem establishes that [47mcl-proc[0m returns a list of
  clauses when given a clause, provided certain functions have the
  expected arities.  But the recognizer for a clause is the function
  [47m[logic-term-listp][0m and the recognizer for a list of clauses is
  [47m[logic-term-list-listp][0m:

    General Forms of Well-Formedness Theorem for a Clause Processor
    (implies (and (logic-term-listp x w)
                  (arities-okp '<alist> w))
             (logic-term-list-listp (cl-proc x ...) w))

    (implies (and (logic-term-listp x w)
                  (arities-okp '<alist> w))
             (logic-term-list-listp (clauses-result (cl-proc x ...)) w))

  The first form above is for a [47mcl-proc[0m that returns a single value and
  the second form is for a [47mcl-proc[0m that returns multiple values.

  The discussion about metafunctions, above, applies here as well.
  [47m<Alist>[0m is an alist pairing function symbols with their assumed
  arities.  You may omit or reorder the hypotheses and you may use
  different variable symbols in place of [47mx[0m and [47mw[0m, but they must be
  distinct and different from the variables in the ``[47m...[0m.''

  Runtime Effects

  In the absence of a [47m:well-formedness-guarantee[0m, if a metafunction or
  clause processor is applied during a proof and produces [47mval[0m, then
  certain checks are made on [47mval[0m before it is used in the proof
  attempt.  In the case of a metafunction, [47m(logic-termp val (w
  state))[0m is checked and [47mval[0m is scanned to ensure that it contains no
  forbidden function symbols.  In the case of a clause processor,
  [47m(logic-term-list-listp val (w state))[0m is checked and [47mval[0m is scanned
  to ensure that it contains no forbidden function symbols.

  If [47mval[0m is large (e.g., because the input is large), these checks can
  take more time than the metafunction or clause processor did to
  produce [47mval[0m!  It is for this reason that we provide for
  [47m:well-formedness-guarantee[0ms.

  When a [47m:well-formedness-guarantee[0m is provided no checks are made on
  [47mval[0m.  However, ACL2 will check that the arity alist(s) involved in
  the guarantee still correctly shows the arities of the function
  symbols listed.  Because those function symbols were not forbidden
  when the guarantee was made and are prohibited from being forbidden
  thereafter, no check is necessary to ensure that no forbidden
  symbols are introduced into the proof.")
 (WELL-FOUNDED-RELATION
  (RULE-CLASSES)
  "Show that a relation is well-founded on a set

  See [well-founded-relation-rule] for discussion of well-founded
  relations in ACL2.  A related utility, [47mwell-founded-relation[0m, may
  be found in the [community-books], file
  [47mkestrel/utilities/system/world-queries.lisp[0m.")
 (WELL-FOUNDED-RELATION-RULE
  (RULE-CLASSES)
  "Show that a relation is well-founded on a set

  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.

    Example:
    (defthm lex2p-is-well-founded-relation
      (and (implies (pairp x) (o-p (ordinate x)))
           (implies (and (pairp x)
                         (pairp y)
                         (lex2p x y))
                    (o< (ordinate x) (ordinate y))))
      :rule-classes :well-founded-relation)

  The example above creates a [47m:well-founded-relation[0m rule, where of
  course the functions [47mpairp[0m, [47mlex2p[0m, and [47mordinate[0m would have to be
  defined first.  It establishes that [47mlex2p[0m is a well-founded
  relation on [47mpairp[0ms.  We explain and give details below.

  Exactly two general forms are recognized:

    General Forms
    (AND (IMPLIES (mp x) (O-P (fn x)))              ; Property 1
         (IMPLIES (AND (mp x)                       ; Property 2
                       (mp y)
                       (rel x y))
                  (O< (fn x) (fn y)))),

  or

    (AND (O-P (fn x))                               ; Property 1
         (IMPLIES (rel x y)                         ; Property 2
                  (O< (fn x) (fn y))))

  where [47mmp[0m, [47mfn[0m, and [47mrel[0m are function symbols, [47mx[0m and [47my[0m are distinct
  variable symbols, and no other [47m:well-founded-relation[0m theorem about
  [47mfn[0m has been proved.  When the second general form is used, we act
  as though the first form were used with [47mmp[0m being the function that
  ignores its argument and returns [47mt[0m.  The discussion below therefore
  considers only the first general form.

  Note: We are very rigid when checking that the submitted formula is
  of one of these forms.  For example, in the first form, we insist
  that all the conjuncts appear in the order shown above.  Thus,
  interchanging the two properties in the top-level conjunct or
  rearranging the hypotheses in the second conjunct both produce
  unrecognized forms.  The requirement that each [47mfn[0m be proved
  well-founded at most once ensures that for each well-founded
  relation, [47mfn[0m, there is a unique [47mmp[0m that recognizes the domain on
  which [47mrel[0m is well-founded.  We impose this requirement simply so
  that [47mrel[0m can be used as a short-hand when specifying the
  well-founded relations to be used in definitions; otherwise the
  specification would have to indicate which [47mmp[0m was to be used.

  We also insist that the new ordering be embedded into the ordinals as
  handled by [47m[o-p][0m and [47m[o<][0m and not some into previously admitted
  user-defined well-founded set and relation.  This restriction
  should pose no hardship.  If [47mmp[0m and [47mrel[0m were previously shown to be
  well-founded via the embedding [47mfn[0m, and you know how to embed some
  new set and relation into [47mmp[0m and [47mrel[0m, then by composing [47mfn[0m with
  your new embedding and using the previously proved well-founded
  relation lemma you can embed the new set and relation into the
  ordinals.

  [47mMp[0m is a predicate that recognizes the objects that are supposedly
  ordered in a well-founded way by [47mrel[0m.  We call such an object an
  ``[47mmp[0m-measure'' or simply a ``measure'' when [47mmp[0m is understood.
  Property 1 tells us that every measure can be mapped into an ACL2
  ordinal.  (See [o-p].)  This mapping is performed by [47mfn[0m.  Property
  2 tells us that if the measure [47mx[0m is smaller than the measure [47my[0m
  according to [47mrel[0m, then the image of [47mx[0m under [47mfn[0m is smaller than that
  of [47my[0m, according to the well-founded relation [47m[o<][0m.  (See [o<].)
  Thus, the general form of a [47m:well-founded-relation[0m formula
  establishes that there exists a [47mrel[0m-order preserving embedding
  (namely via [47mfn[0m) of the [47mmp[0m-measures into the ordinals.  We can thus
  conclude that [47mrel[0m is well-founded on [47mmp[0m-measures.

  Such well-founded relations are used in the admissibility test for
  recursive functions, in particular, to show that the recursion
  terminates.  To illustrate how such information may be used,
  consider a generic function definition

    (defun g (x) (if (test x) (g (step x)) (base x))).

  If [47mrel[0m has been shown to be well-founded on [47mmp[0m-measures, then [47mg[0m's
  termination can be ensured by finding a measure, [47m(m x)[0m, with the
  property that [47mm[0m produces a measure:

    (mp (m x)),                                     ; Defun-goal-1

  and that the argument to [47mg[0m gets smaller (when measured by [47mm[0m and
  compared by [47mrel[0m) in the recursion,

    (implies (test x) (rel (m (step x)) (m x))).    ; Defun-goal-2

  If [47mrel[0m is selected as the [47m:well-founded-relation[0m to be used in the
  definition of [47mg[0m, the definitional principal will generate and
  attempt to prove [47mdefun-goal-1[0m and [47mdefun-goal-2[0m to justify [47mg[0m.  We
  show later why these two goals are sufficient to establish the
  termination of [47mg[0m.  Observe that neither the ordinals nor the
  embedding, [47mfn[0m, of the [47mmp[0m-measures into the ordinals is involved in
  the goals generated by the definitional principal.

  Suppose now that a [47m:well-founded-relation[0m theorem has been proved for
  [47mmp[0m and [47mrel[0m.  How can [47mrel[0m be ``selected as the
  [47m:well-founded-relation[0m'' by [47m[defun][0m?  There are two ways.  First,
  an [47m[xargs][0m keyword to the [47m[defun][0m event allows the specification of
  a [47m:well-founded-relation[0m.  Thus, the definition of [47mg[0m above might be
  written

    (defun g (x)
     (declare (xargs :well-founded-relation rel))
     (if (test x) (g (step x)) (base x)))

  Alternatively, [47mrel[0m may be specified as the
  [47m:default-well-founded-relation[0m in [47m[ACL2-defaults-table][0m by
  executing the event

    (set-well-founded-relation rel).

  When a [47m[defun][0m event does not explicitly specify the relation in its
  [47m[xargs][0m the default relation is used.  When ACL2 is initialized,
  the default relation is [47m[o<][0m.

  Finally, though it is probably obvious, we now show that [47mdefun-goal-1[0m
  and [47mdefun-goal-2[0m are sufficient to ensure the termination of [47mg[0m
  provided [47mproperty-1[0m and [47mproperty-2[0m of [47mmp[0m and [47mrel[0m have been proved.
  To this end, assume we have proved [47mdefun-goal-1[0m and [47mdefun-goal-2[0m as
  well as [47mproperty-1[0m and [47mproperty-2[0m and we show how to admit [47mg[0m under
  the primitive ACL2 definitional principal (i.e., using only the
  ordinals).  In particular, consider the definition event

    (defun g (x)
     (declare (xargs :well-founded-relation o<
                     :measure (fn (m x))))
     (if (test x) (g (step x)) (base x)))

  Proof that [47mg[0m is admissible: To admit the definition of [47mg[0m above we
  must prove

    (o-p (fn (m x)))                        ; *1

  and

    (implies (test x)                               ; *2
             (o< (fn (m (step x))) (fn (m x)))).

  But *1 can be proved by instantiating [47mproperty-1[0m to get

    (implies (mp (m x)) (o-p (fn (m x)))),

  and then relieving the hypothesis with [47mdefun-goal-1[0m, [47m(mp (m x))[0m.

  Similarly, *2 can be proved by instantiating [47mproperty-2[0m to get

    (implies (and (mp (m (step x)))
                  (mp (m x))
                  (rel (m (step x)) (m x)))
             (o< (fn (m (step x))) (fn (m x))))

  and relieving the first two hypotheses by appealing to two instances
  of [47mdefun-goal-1[0m, thus obtaining

    (implies (rel (m (step x)) (m x))
             (o< (fn (m (step x))) (fn (m x)))).

  By chaining this together with [47mdefun-goal-2[0m,

    (implies (test x)
             (rel (m (step x)) (m x)))

  we obtain *2.  Q.E.D.")
 (WET
  (TRACE)
  "Evaluate a form and print subsequent error trace

  The acronym ``wet'' stands for ``with-error-trace''.  [47mWet[0m provides a
  convenient way to obtain a backtrace when evaluation causes a guard
  violation or other error.


Summary Documentation

    General Form:
    (wet form           ; an arbitrary form
         :book bk-form  ; optional, not evaluated; specify different wet book
         ;;; the rest are optional and evaluated:
         :compile c     ; :same, t, or nil; default :same (nil if :fns supplied)
         :fullp h       ; nil by default, else handle some raw Lisp errors
         :evisc-tuple e ; an evisc-tuple
         :fns fns       ; :all, or a list of functions to show in a backtrace

  [47mForm[0m is evaluated.  If there is an error, a backtrace stack is
  printed to the standard output ([47m[*standard-co*][0m), containing (by
  default) the user-defined function calls made before the error.
  Such printing is controlled by the [47m:evisc-tuple[0m if supplied;
  otherwise, hiding of large structures will occur.


Discussion

  The basic idea is that [47m(wet form)[0m evaluates [47mform[0m and, if there is an
  error, shows a backtrace of calls that led to that error.  Note
  however that by default only calls of user-defined (not built-in)
  functions ``supporting'' [47mform[0m in the following sense will show up
  in the backtrace: those that occur in the macroexpansion of [47mform[0m or
  (recursively) support any of those functions.  So for example,
  since [47m(make-event form)[0m macroexpands to [47m(make-event-fn (quote form)
  ...)[0m, calls of functions occurring in [47mform[0m will likely not show up
  in the backtrace by default.  The option [47m:fns all[0m overrides this
  default, with potential loss of speed; more on this below.

  The following example explains the use of [47mwet[0m.  First, submit the
  following three definitions:

    (defun foo (x) (declare (xargs :guard (consp x))) (car x))
    (defun bar (x) (foo (cdr x)))
    (defun g (x) (bar (cdr x)))

  Now imagine you have obtained the following guard violation:

    ACL2 !>(g '(3 4))

    ACL2 Error in TOP-LEVEL:  The guard for the function call (FOO X),
    which is (CONSP X), is violated by the arguments in the call (FOO 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 !>

  With [47mwet[0m, you can get a backtrace of user-defined functions.  The
  package prefixes shown below, [47mACL2_*1*_[0m, indicate that the
  executable-counterparts of the corresponding submitted functions
  are being called; see [evaluation].  Don't forget to start with
  [47m(include-book \"misc/wet\" :dir :system)[0m.

    ACL2 !>(wet (g '(3 4)))
    ; Fast loading /projects/acl2/devel/books/misc/wet.fasl

    TTAG NOTE: Adding ttag :TRACE! from the top level loop.

    ACL2 Error in WET:  The guard for the function call (FOO X), which
    is (CONSP X), is violated by the arguments in the call (FOO 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.

    Backtrace stack:
    ----------------
    1. (ACL2_*1*_ACL2::FOO NIL)
    2. (ACL2_*1*_ACL2::BAR (4))
    3. (ACL2_*1*_ACL2::G (3 4))

    ACL2 !>

  By default, large structures are hidden during the printing of the
  backtrace stack.  (Technical detail: by default the global
  abbrev-evisc-tuple is used, if bound; see [set-evisc-tuple].  But
  you can supply a value for keyword argument [47m:evisc-tuple[0m to modify
  the printing: [47mnil[0m to avoid hiding, else a suitable evisc-tuple, as
  shown below (see [evisc-tuple]).

    ACL2 !>(wet (g '(3 4)) :evisc-tuple (evisc-tuple 1 1 nil nil))
    ; Fast loading /projects/acl2/devel/books/misc/wet.fasl

    TTAG NOTE: Adding ttag :TRACE! from the top level loop.

    ACL2 Error in WET:  The guard for the function call (FOO X), which
    is (CONSP X), is violated by the arguments in the call (FOO 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.

    Backtrace stack:
    ----------------
    1. (ACL2_*1*_ACL2::FOO ...)
    2. (ACL2_*1*_ACL2::BAR ...)
    3. (ACL2_*1*_ACL2::G ...)

    ACL2 !>

  For a backtrace as a data object, evaluate the form [47m(@ wet-stack)[0m.
  But note that this object may not be a legal ACL2 value, for
  example because of the ``[47m*1*[0m'' symbols shown above.


Keyword Arguments

  The [47m:fullp[0m option.  Consider the following example.

    (program)
    (defun foo (x) (declare (xargs :guard (consp x))) (car x))
    (defun bar (x) (foo (cdr x)))
    (defun g (x) (bar (cdr x)))
    ; Raw Lisp error:
    (g '(3 4 . 5))

  We may be initially disappointed using [47mwet[0m on this example, as
  follows --- it didn't work!

    ACL2 p!>(wet (g '(3 4 . 5)))

    TTAG NOTE: Adding ttag :TRACE! from the top level loop.

    ***********************************************
    ************ ABORTING from raw Lisp ***********
    ********** (see :DOC raw-lisp-error) **********
    Error:  Fault during read of memory address #x2D
    While executing: FOO
    ***********************************************

    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)
    ACL2 p!>

  The fix is to use [47m:fullp t[0m.

    ACL2 p!>(wet (g '(3 4 . 5)) :fullp t)

    TTAG NOTE: Adding ttag :TRACE! from the top level loop.


    ACL2 Error in WET:  The guard for the :program function call (FOO X),
    which is (CONSP X), is violated by the arguments in the call (FOO 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.


    Backtrace stack:
    ----------------
    1. (ACL2_*1*_ACL2::FOO 5)
    2. (ACL2_*1*_ACL2::BAR (4 . 5))
    3. (ACL2_*1*_ACL2::G (3 4 . 5))

    ACL2 p!>

  Why doesn't [47mwet[0m always do things this way?  The answer pertains to
  performance.  When [47m:fullp[0m is non-nil, [47mwet[0m sets guard-checking to
  [47m:all[0m before evaluating the given form; see [set-guard-checking].
  This may slow down evaluation substantially, which is why it is not
  the default behavior.

  The [47m:fns[0m option.  As mentioned above, by default the [47mwet[0m backtrace
  shows user-defined functions that syntactically ``support'' the
  form being evaluated.  This default can be overridden by supplying
  an explicit list, [47mfns[0m, of functions, using option [47m:fns fns[0m; these
  will then be the functions whose calls are eligible for inclusion
  in the backtrace.  The special value [47m:fns :all[0m will allow all
  user-defined function calls in the backtrace.  This value can be
  useful when using [47m[magic-ev-fncall][0m, for example, since the
  function being applied isn't typically included as a syntactic
  supporter of the form being evaluated.

  The [47m:compile[0m option.  [47mWet[0m uses the [47m[trace$][0m utility to modify the
  definitions of affected functions so that they can record
  information for the backtrace.  As described above, these affected
  functions are those that syntactically ``support'' the form unless
  specified by the [47m:fns[0m option.  As is the case for [47mtrace$[0m --- see
  [trace$] --- the new definitions of these affected functions may or
  may not be compiled.  For [47mtrace$[0m and for [47mwet[0m, the default is to
  compile the new definition if and only if the original definition
  was compiled, except: For [47mwet[0m, if option [47m:fns :all[0m is provided,
  then the default is not to compile the affected definitions.  And
  for [47mtrace$[0m and [47mwet[0m, the [47m:compile[0m option overrides the default, to
  specify what will be compiled: value [47m:same[0m to compile each affected
  function if and only if its original definition was compiled, value
  [47mt[0m to compile all affected functions, and value [47mnil[0m to skip
  compilation.

  The [47m:book[0m option.  [47mWet[0m actually works by temporarily including a
  community book,

    (include-book \"misc/wet\" :dir :system)

  and then passing its arguments to macro [47mwet![0m, defined in that book.
  The keyword argument [47m:book[0m allows you to specify a different book
  that defines a macro [47mwet![0m to which to pass its arguments.  If the
  value of [47m:book[0m is a string, then the book named by that string is
  temporarily included using [47m[include-book][0m: [47m(include-book \"bk\")[0m.
  Otherwise [47m:book[0m should be a list of arguments, to be provided
  (unevaluated) to [47m[include-book][0m, for example [47m(\"my-wet\" :dir
  :my-utils)[0m.  Thus you can experiment by copying community book
  [47mbooks/misc/wet.lisp[0m to your own directory and making modifications
  to the copy.  If you make changes, we invite you to share them with
  the ACL2 community (see [books]).  Note that you can also supply
  [47m:book nil[0m, in which case the definition of [47mwet![0m in your current
  session will be used without including a book.


Concluding Remark

  Also see [trace$] for a general tracing utility.  As mentioned above,
  [47mwet[0m is implemented using [47mtrace$[0m.  [47mWet[0m actually first applies
  [47m[untrace$][0m; upon completion, [47mwet[0m then applies [47m[trace$][0m to re-trace
  any functions that it had untraced, using their original trace
  specs.")
 (WHAT_IS_ACL2{Q}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "What Is ACL2?

  {IMAGE} (see [What_is_a_Mathematical_Logic{Q}])

  ACL2 is a [31;1mmathematical logic[0m together with a [31;1mmechanical theorem
  prover[0m to help you reason in the logic.

  The logic is just a subset of applicative Common Lisp (see
  [Common_Lisp]).  (This link takes you off the main route of the
  tour.  You'll see some Common Lisp on the tour, so visit this
  later!)

  The theorem prover is an ``industrial strength'' version of the
  Boyer-Moore theorem prover, Nqthm.

  [31;1mModels[0m of all kinds of computing systems can be built in ACL2, just
  as in Nqthm, even though the formal logic is Lisp.

  Once you've built an ACL2 model of a system, you can run it.

  You can also use ACL2 to prove theorems about the model.

  {IMAGE} (see [What_is_a_Mathematical_Logic{Q}])")
 (WHAT_IS_A_MATHEMATICAL_LOGIC{Q}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "What is a Mathematical Logic?

  {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}])

  {IMAGE}

  A mathematical logic is a formal system of formulas ([31;1maxioms[0m) and
  [31;1mrules[0m for deriving other formulas, called [31;1mtheorems[0m.

  A [31;1mproof[0m is a derivation of a theorem.  To see a concrete proof tree,
  click here (see [A_Trivial_Proof]).

  Why should you care?  The neat thing about Theorems is that they are
  ``true.'' More precisely, if all the axioms are valid and the rules
  are validity preserving, then anything derived from the axioms via
  the rules is valid.

  So, if you want to determine if some formula is true, [31;1mprove it[0m.

  {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}])")
 (WHAT_IS_A_MECHANICAL_THEOREM_PROVER{Q}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "What is a Mechanical Theorem Prover?

  {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}_{cont}])

  A [31;1mmechanical theorem prover[0m is a computer program that finds proofs
  of theorems.

  {IMAGE}

  The ideal mechanical theorem prover is [31;1mautomatic[0m: you give it a
  formula and it gives you a proof of that formula or tells you there
  is no proof.

  Unfortunately, automatic theorem provers can be built only for very
  simple logics (e.g., [31;1mpropositional calculus[0m) and even then
  practical considerations (e.g., how many centuries you are willing
  to wait) limit the problems they can solve.

  {IMAGE} (see [What_is_a_Mechanical_Theorem_Prover{Q}_{cont}])")
 (WHAT_IS_A_MECHANICAL_THEOREM_PROVER{Q}_{CONT}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "What is a Mechanical Theorem Prover? (cont)

  {IMAGE} (see [About_Models]) To get around this, mechanical theorem
  provers often require help from the [31;1muser[0m.

  {IMAGE}

  Click here (see [ACL2_as_an_Interactive_Theorem_Prover]) to continue
  downward.

  {IMAGE} (see [About_Models])")
 (WHAT_IS_REQUIRED_OF_THE_USER{Q}
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "What is Required of the User?

  {IMAGE} (see [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}])

  It is not easy to build ACL2 models of complex systems.  To do so,
  the user must [31;1munderstand[0m

    * the system being modeled, and

    * ACL2, at least as a programming language.

  It is not easy to get ACL2 to prove hard theorems.  To do so, the
  user must [31;1munderstand[0m

    * the model,

    * ACL2 as a mathematical logic, and

    * be able to construct a proof (in interaction with ACL2).

  ACL2 will help construct the proof but its primary role is to prevent
  logical mistakes.  The creative burden --- the mathematical insight
  into [31;1mwhy the model has the desired property[0m --- is the user's
  responsibility.

  {IMAGE} (see [How_Long_Does_It_Take_to_Become_an_Effective_User{Q}])")
 (WHEN$ (POINTERS) "See [loop$].")
 (WHEN$+ (POINTERS) "See [loop$].")
 (WHY-BRR
  (BREAK-REWRITE)
  "An explanation of why ACL2 has an explicit [47m[brr][0m mode

  Why isn't [47m[brr][0m mode automatically disabled when there are no
  monitored runes?  The reason is that the list of monitored runes is
  kept in a wormhole state.

  See [wormhole] for more information on wormholes in general.  But the
  fundamental property of the wormhole function is that it is a
  logical [47mno-op[0m, a constant function that does not take state as an
  argument.  When entering a wormhole, arbitrary information can be
  passed in (including the external state).  That information is used
  to construct a near copy of the external state and that ``wormhole
  state'' is the one with respect to which interactions occur during
  breaks.  But no information is carried by ACL2 out of a wormhole
  --- if that were allowed wormholes would not be logical no-ops.
  The only information carried out of a wormhole is in the user's
  head.

  [47m[Break-rewrite][0m interacts with the user in a wormhole state because
  the signature of the ACL2 rewrite function does not permit it to
  modify [47m[state][0m.  Hence, only wormhole interaction is possible.
  (This has the additional desirable property that the correctness of
  the rewriter does not depend on what the user does during
  interactive breaks within it; indeed, it is logically impossible
  for the user to affect the course of [47m[rewrite][0m.)

  Now consider the list of monitored runes.  Is that kept in the
  external state as a normal state global or is it kept in the
  wormhole state?  If it is in the external state then it can be
  inspected within the wormhole but not changed.  This is
  unacceptable; it is common to change the [monitor]ed rules as the
  proof attempt progresses, installing monitors when certain rules
  are about to be used in certain contexts.  Thus, the list of
  monitored runes must be kept as a wormhole variable.  Hence, its
  value cannot be determined outside the wormhole, where the proof
  attempt is ongoing.

  This raises another question: If the list of monitored runes is
  unknown to the rewriter operating on the external state, how does
  the rewriter know when to break?  The answer is simple: it breaks
  every time, for every rune, if [47m[brr][0m mode is enabled.  The wormhole
  is entered (silently), computations are done within the wormhole
  state to determine if the user wants to see the break, and if so,
  interactions begin.  For unmonitored runes and runes with false
  break conditions, the silent wormhole entry is followed by a silent
  wormhole exit and the user perceives no break.

  Thus, the penalty for running with [47m[brr][0m mode enabled when there are
  no monitored runes is high: a wormhole is entered on every
  application of every rune and the user is simply unaware of it.
  The user who has finally unmonitored all runes is therefore
  strongly advised to carry this information out of the wormhole and
  to do [47m:[0m[47m[brr][0m [47mnil[0m in the external state when the next opportunity
  arises.")
 (WINDOWS-INSTALLATION
  (BREAK-REWRITE)
  "Installing ACL2 on Windows

  Windows users will probably want to do one of the following to
  install and run ACL2 on their systems.  Thanks to David Rager for
  his help with this topic.

    * Use a Virtual Machine platform, such as VMware Player (free for
      non-commercial use) or Oracle Virtualbox (free even for
      commercial use) to install Linux, and then follow the normal
      installation instructions to install ACL2.  As of 2014, at
      least a couple of our power users are very happy with this
      solution, as it provides first-class access to utilities
      relevant to maintaining the ACL2 system and books (like GNU
      Make and perl).

    * Set up {Windows Subsystem for Linux |
      https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux}
      (WSL) on a 64-bit version of Windows 10 (or later, once
      available).  Within that subsystem, follow the setup and
      installation instructions for ACL2. See the below section
      regarding the ACL2 Sedan Windows installation instructions for
      more info, as that involves installing the ACL2 Sedan in WSL on
      Windows.

    * Use the ACL2 Sedan (ACL2s) Windows installation instructions --- see
      [ACL2s::ACL2s-installation] for more details. This will install
      ACL2 and the ACL2s system (including a copy of the Eclipse IDE
      with ACL2s support) in a Windows Subsystem for Linux distro.
      This distro is configured to automatically open Eclipse when
      the distro starts up, but one can start the distro without
      Eclipse by running [47mwsl -d acl2s -e /bin/bash --noprofile[0m.

  You are welcome to {obtain a Windows installer for a previous ACL2
  release |
  http://www.cs.utexas.edu/users/moore/acl2/v3-6/distrib/windows/},
  which mimics some of Linux and provides Emacs.  Updated ACL2
  binaries have been successfully installed in such an environment.")
 (WITH-BRR-DATA
  (DEBUGGING BREAK-REWRITE)
  "Finding the source of a term in prover output

  When a proof attempt fails, a good first step is typically to look at
  [3mcheckpoints[0m; see [the-method].  That step is often sufficient.  But
  occasionally a checkpoint contains an undesirable term whose source
  is a mystery, and it may be useful to find the origin of that term.
  [47mWith-brr-data[0m is a utility that collects such data that can be
  queried by various utilities, for example as follows.

    Example:

    ; Collect brr-data when attempting the indicated proof:
    (with-brr-data (thm (equal (append x y) (append y x))))

    ; Show a path leading to a rewrite result that contains
    ; (append y (cdr x)) as a subterm:
    (cw-gstack-for-subterm (append y (cdr x)))

    ; Same as above, except enter a loop to query for additional such results:
    (cw-gstack-for-subterm* (append y (cdr x)))

  The rest of this documentation topic is structured as follows.  It
  may suffice to read only the first two sections.

    * Introduction

    * Connections with [break-rewrite]

    * General form of [47mwith-brr-data[0m calls

    * General forms of queries

    * Keyword arguments of [47mwith-brr-data[0m (optional)

    * Low-level details (optional)

    * Using attachments to modify functionality of [47mwith-brr-data[0m


Introduction

  [47m(With-brr-data form)[0m evaluates [47mform[0m while collecting data on rule
  application --- often [rewrite] and [definition] rules, but also
  [linear] and [rewrite-quoted-constant] rules.  Query utilities
  allow one to search the collected data for a specified result of a
  rule application and print a stack of operations leading to that
  result.  The name ``brr'' is suggestive of the [break-rewrite]
  utility, which shares some aspects with the [47mwith-brr-data[0m utility:
  in particular, the [47m:path+[0m command of break-rewrite shows a stack of
  operations in the same way as the query utilities for
  [47mwith-brr-data[0m.  The next section, ``Connection with
  [break-rewrite]'', further explores the relationship between
  break-rewrite and [47mwith-brr-data[0m.

  The collection of break-rewrite data can slow down the theorem
  prover, but the slowdown will probably be modest, perhaps adding an
  extra 15% or so to the time.

  We turn now to examples that illustrate how [47mwith-brr-data[0m works with
  associated query utilities.  These examples are intended to make it
  clear how to use these utilities, but further information is
  provided in later sections for those who are interested.  Note that
  each of these examples attempts to prove a non-theorem; they are
  chosen simply to illustrate tool usage.

  Example Set 1

  Our first illustration of [47mwith-brr-data[0m and associated query
  utilities uses the following (non-theorem) example, mentioned
  earlier.

    (with-brr-data (thm (equal (append x y) (append y x))))

  ACL2 produces the following checkpoints, exactly as though the [47m[thm][0m
  call were evaluated without the surrounding call of [47mwith-brr-data[0m.
  (The optional section on ``Low-level details'' discusses the ``ACL2
  Observation:'' printed at the end by [47mwith-brr-data[0m.)

    *** Key checkpoint at the top level: ***

    Goal
    (EQUAL (APPEND X Y) (APPEND Y X))

    *** Key checkpoints under a top-level induction
        before generating a goal of NIL (see :DOC nil-goal): ***

    Subgoal *1/2''
    (IMPLIES (AND (CONSP X)
                  (EQUAL (APPEND (CDR X) Y)
                         (APPEND Y (CDR X))))
             (EQUAL (CONS (CAR X) (APPEND Y (CDR X)))
                    (APPEND Y X)))

    Subgoal *1/1''
    (IMPLIES (NOT (CONSP X))
             (EQUAL Y (APPEND Y X)))

    ACL2 Error [Failure] in ( THM ...):  See :DOC failure.

    ******** FAILED ********

    ACL2 Observation:  (LENGTH (@ BRR-DATA-LST)) = 16
    ACL2 !>

  Consider the term [47m(APPEND Y (CDR X))[0m occurring in one of these
  checkpoints.  It might not be clear, at least at first glance, how
  this term came about during the proof.  We can find at least one
  source of that term by issuing the [47mcw-gstack-for-subterm[0m query
  shown below, which searches ``top-level'' rewrites --- those not
  invoked when relieving hypotheses of rules --- for a result that
  contains the given term, in this case [47m(append y (cdr x))[0m, as a
  subterm.  The output is similar to the output of the utility,
  [47m[cw-gstack][0m, followed by the result of the bottom-most rewriter
  call, which contains the given term as a subterm.  (See [term] for
  discussion of ``translated'' and ``untranslated'' terms.)

    ACL2 !>(cw-gstack-for-subterm (append y (cdr x)))
    1. Simplifying the clause
         ((NOT (CONSP X))
          (NOT (EQUAL (BINARY-APPEND (CDR X) Y)
                      (BINARY-APPEND Y (CDR X))))
          (EQUAL (BINARY-APPEND X Y)
                 (BINARY-APPEND Y X)))
    2. Rewriting (to simplify) the atom of the third literal,
         (EQUAL (BINARY-APPEND X Y)
                (BINARY-APPEND Y X)),
    3. Rewriting (to simplify) the first argument,
         (BINARY-APPEND X Y),
    4. Attempting to apply (:DEFINITION BINARY-APPEND) to
         (BINARY-APPEND X Y)
    The resulting (translated) term is
      (CONS (CAR X)
            (BINARY-APPEND Y (CDR X))).
    ACL2 !>

  One might realize that [47m(BINARY-APPEND Y (CDR X))[0m comes about from
  expanding [47m(BINARY-APPEND X Y)[0m to expose the term [47m(BINARY-APPEND
  (CDR X) Y)[0m and then using the inductive hypothesis to swap the
  arguments.  In that case, the mystery of the term's appearance is
  solved!  But if that isn't clear, one at least has the clue from
  Frame 4 above that the term is produced by applying the definition
  of [47m[binary-append][0m.  With that information one can issue a
  [47m[monitor!][0m command as follows.

    :monitor! (:definition binary-append)
              (equal (brr@ :target) '(binary-append x y))

  We now issue the [47m[thm][0m call above, with or without the wrapper of
  [47mwith-brr-data[0m.  After breaking twice (see [break-rewrite]) and
  proceeding with [47m:go[0m to find two failed attempts to use the
  definition of [47mbinary-append[0m, we explore at the third break as
  follows.

    1 ACL2 >:type-alist

    Decoded type-alist:
    -----
    Terms with type *TS-T*:
    (EQUAL (APPEND (CDR X) Y)
           (APPEND Y (CDR X)))
    -----
    Terms with type *TS-CONS*:
    X

    ==========
    Use (GET-BRR-LOCAL 'TYPE-ALIST STATE) to see actual type-alist.
    1 ACL2 >:target
    (BINARY-APPEND X Y)
    1 ACL2 >:eval

    1! (:DEFINITION BINARY-APPEND) produced
    (CONS (CAR X) (BINARY-APPEND Y (CDR X))).

    1 ACL2 >

  The log above shows how the term [47m(BINARY-APPEND Y (CDR X))[0m was
  produced: the definition of [47mbinary-append[0m was expanded on the term
  [47m(BINARY-APPEND X Y)[0m, and the inductive hypothesis --- represented
  in the [47m:type-alist[0m command's output --- is applied to swap the
  resulting arguments.

  We can find more sources of the same term by using the ``[47m*[0m'' version
  of the [47mcw-gstack-for-subterm[0m command as follows.  By repeatedly
  responding with ``[47my[0m'' to the query presented by the system, we find
  three additional paths leading to the desired subterm.

    (cw-gstack-for-subterm* (append y (cdr x)))

  While [47mcw-gstack-for-subterm[0m and [47mcw-gstack-for-subterm*[0m may be the
  most useful queries in general, one may wish to search for paths
  leading to [3mexactly[0m a given term rather than paths to a term
  [3mcontaining[0m that term (as above).  The queries [47mcw-gstack-for-term[0m
  and [47mcw-gstack-for-term*[0m may be used for this purpose, for example
  as follows.

    (cw-gstack-for-term (append y (cdr x)))
    (cw-gstack-for-term* (append y (cdr x)))

  Finally, these queries support searching for [3minstances[0m of a term or
  subterm, by supplying a ``term'' of the form [47m(:free (v1 ... vn) u)[0m
  where [47mv1[0m through [47mvn[0m are distinct variables and [47mu[0m is a term.  Each
  of the following produces the path shown above.

    (cw-gstack-for-term (:free (u v) (cons u v)))
    (cw-gstack-for-term* (:free (u v) (cons u v)))

  Notice that the use of this [47m:free[0m construct allows one to search for
  the source of a call of any function symbol [47mf[0m, as with [47mcons[0m above.
  If [47mf[0m has k formals, then one can supply the argument [47m(:free (x1 ...
  xk) (f x1 ... xk))[0m to find a rewriter call that produces a call of
  [47mf[0m.

  Example Set 2

  Consider the following (admittedly contrived) example.

    (defstub f0 (x) t)

    (defun f1 (x)
      (cons x x))

    (defun f2 (x)
      (f1 (f0 x)))

    (defun f3 (x)
      (if (atom x)
          (f2 x)
        (f2 (car x))))

    (with-brr-data
     (thm (equal (f3 x)
                 yyy)))

  The call of [47m[thm][0m produces the following checkpoint.

    (IMPLIES (CONSP X)
             (EQUAL (CONS (F0 (CAR X)) (F0 (CAR X)))
                    YYY))

  In this simple example it's easy to figure out how the term [47m(F0 (CAR
  X))[0m was produced.  But suppose we were surprised to see that term.
  We might issue the following query but be disappointed in the
  result.

    ACL2 !>(cw-gstack-for-term (F0 (CAR X)))
    There are no results.
    ACL2 !>

  To see why there are no results, recall that [47mwith-brr-data[0m collects
  data from rule applications.  However, no rule produced the term
  [47m(F0 (CAR X))[0m.  This becomes clear if we issue a query that looks
  for that term as a subterm of a rule application's result.

    ACL2 !>(cw-gstack-for-subterm (F0 (CAR X)))
    1. Simplifying the clause
         ((EQUAL (F3 X) YYY))
    2. Rewriting (to simplify) the atom of the first literal,
         (EQUAL (F3 X) YYY),
    3. Rewriting (to simplify) the first argument,
         (F3 X),
    4. Attempting to apply (:DEFINITION F3) to
         (F3 X)
    5. Rewriting (to simplify) the body,
         (IF (CONSP X) (F2 (CAR X)) (F2 X)),
       under the substitution
         X : X
    6. Rewriting (to simplify) the second argument,
         (F2 (CAR X)),
       under the substitution
         X : X
    7. Attempting to apply (:DEFINITION F2) to
         (F2 (CAR X))
    8. Rewriting (to simplify) the rhs of the conclusion,
         (F1 (F0 X)),
       under the substitution
         X : (CAR X)
    9. Attempting to apply (:DEFINITION F1) to
         (F1 (F0 (CAR X)))
    The resulting (translated) term is
      (CONS (F0 (CAR X)) (F0 (CAR X))).
    Note: The first lemma application above that provides a suitable result
    is at frame 4, and that result is
      (IF (CONSP X)
          (CONS (F0 (CAR X)) (F0 (CAR X)))
        (CONS (F0 X) (F0 X))).
    ACL2 !>

  We see that the term [47m(FO (CAR X))[0m is not itself the result of a rule
  application.  This example illustrates that one may often get
  better results using [47mcw-gstack-for-subterm[0m rather than
  [47mcw-gstack-for-term[0m.

  It is also interesting to look at the ``Note'' printed at the end.
  The query utilities search for the first rule application that
  produced a suitable result, and then they search from that point
  for a maximally deeper rule application that produced a suitable
  result.  In this case, the first rule that produced a term
  containing [47m(FO (CAR X))[0m is shown in the frame at position 4, as per
  the Note.  The rule at frame 9 also produced such a term (though a
  different one than at frame 4), and there was no deeper such rule
  application --- that is, from the time the definition at frame 9
  was applied till the time its body was fully rewritten, no rule
  produced a term containing [47m(FO (CAR X))[0m.  (This notion of
  ``deeper'' is discussed at some length in the section below on
  ``General forms of queries''.)

  Next we'll explore a limitation of these tools and how to get around
  it.  We start as follows (following the definitions above).

    (with-brr-data
     (thm (equal (append (f3 x) y)
                 z)
          :hints ((\"Goal\" :in-theory (disable append)))))

  This proof attempt results in the following checkpoint.

    (IMPLIES (CONSP X)
             (EQUAL (APPEND (CONS (F0 (CAR X)) (F0 (CAR X)))
                            Y)
                    Z))

  The following log may be surprising, especially since the indicated
  term need only be a subterm of a rewriter result, and we see this
  exact term in the checkpoint above!

    ACL2 !>(cw-gstack-for-subterm (APPEND (CONS (F0 (CAR X)) (F0 (CAR X))) Y))
    There are no results.
    ACL2 !>

  A solution is to choose a subterm of that input term, as shown in the
  log below.  The resulting output shows why the query above yielded
  no results: frame 6 below shows that the first argument, [47m(F3 X)[0m, of
  [47mbinary-append[0m (see frame 3 below) generates a call of [47mIF[0m, so the
  rewrite at frame 3 will generate a term of the form [47m(BINARY-APPEND
  (IF ...)  ...)[0m, not of the form [47m(BINARY-APPEND (CONS ...) ...)[0m.

    ACL2 !>(cw-gstack-for-subterm (cons (f0 (car x)) (f0 (car x))))
    1. Simplifying the clause
         ((EQUAL (BINARY-APPEND (F3 X) Y) Z))
    2. Rewriting (to simplify) the atom of the first literal,
         (EQUAL (BINARY-APPEND (F3 X) Y) Z),
    3. Rewriting (to simplify) the first argument,
         (BINARY-APPEND (F3 X) Y),
    4. Rewriting (to simplify) the first argument,
         (F3 X),
    5. Attempting to apply (:DEFINITION F3) to
         (F3 X)
    6. Rewriting (to simplify) the body,
         (IF (CONSP X) (F2 (CAR X)) (F2 X)),
       under the substitution
         X : X
    7. Rewriting (to simplify) the second argument,
         (F2 (CAR X)),
       under the substitution
         X : X
    8. Attempting to apply (:DEFINITION F2) to
         (F2 (CAR X))
    9. Rewriting (to simplify) the rhs of the conclusion,
         (F1 (F0 X)),
       under the substitution
         X : (CAR X)
    10. Attempting to apply (:DEFINITION F1) to
         (F1 (F0 (CAR X)))
    The resulting (translated) term is
      (CONS (F0 (CAR X)) (F0 (CAR X))).
    Note: The first lemma application above that provides a suitable result
    is at frame 5, and that result is
      (IF (CONSP X)
          (CONS (F0 (CAR X)) (F0 (CAR X)))
        (CONS (F0 X) (F0 X))).
    ACL2 !>

  The careful reader may notice another reason that the [47mappend[0m call
  does not yield a match: no such call is the result of a rewriter
  call.

  The moral of this story is that if a term fails to give you a match,
  then use a subterm of it.  You can also use the [47m:free[0m construct
  mentioned above, for example as follows --- this gives the same
  output as shown in the log just above.

    (cw-gstack-for-subterm (:free (v) (cons (f0 v) (f0 v))))


Connections with break-rewrite

  We noted above that after running [47mwith-brr-data[0m, the stacks (paths)
  displayed by query commands such as [47mcw-gstack-for-term[0m are the same
  as the stacks displayed by the [break-rewrite] command, [47m:path+[0m.

  But there are these additional connections between [47mwith-brr-data[0m and
  the break-rewrite utility.

    * The same rewriting processes are considered by [47mwith-brr-data[0m as by
      break-rewrite; in particular, abbreviation rules are not
      considered during preprocessing (see [monitor]).

    * When a query command ([47mcw-gstack-for-term[0m etc.) finds a match with a
      rewriting result, it discards the result if the input --- the
      [47m:target[0m, in the parlance of [break-rewrite] --- contains that
      match.

    * [Monitor]ed [rune]s are indeed monitored during evaluation of a call
      of [47mwith-brr-data[0m, even if break-rewrite has not been enabled
      globally (using [47m:[0m[47m[brr][0m or [47m[monitor!][0m).  If this is not desired,
      then [unmonitor] runes before calling [47mwith-brr-data[0m.

    * There is the following low-level way to collect brr-data for queries
      such as [47mcw-gstack-for-term[0m without calling [47mwith-brr-data[0m:
      [47m(assign gstack :brr-data)[0m.  But you may want to clear such data
      afterwards, which you can do by evaluating the form,
      [47m(clear-brr-data-lst)[0m.  Otherwise the brr-data from later proof
      attempts will be combined, probably in unexpected ways, with
      brr-data from earlier proof attempts.

    * [47mWith-brr-data[0m and its queries pay no attention to ``near-miss''
      breaks (see [break-rewrite] for discussion of these breaks).

  The first item above is worth emphasizing.  Consider the following
  example.

    (include-book \"std/lists/rev\" :dir :system)
    (with-brr-data
     (thm (implies (and (natp n)
                        (< n (len x)))
                   (equal (nth n (revappend x y))
                          (nth n (reverse x))))
          :hints ((\"Goal\" :do-not '(preprocess)))))
    (cw-gstack-for-subterm (APPEND (REV X) Y))

  The [47mcw-gstack-for-subterm[0m query yields a result in this example, but
  not if we change it to remove the [47m:[0m[47m[hints][0m.  If we use [47m:[0m[47m[pso][0m on
  the proof attempt without the [47m:hints[0m, we notice that the requested
  subterm was introduced by ``the simple :rewrite rule
  REVAPPEND-REMOVAL''; here ``simple'' indicates the use of the
  [3mpreprocess[0m process for simplification, which avoids the usual
  rewriter.  If we instead query the no-hints version with
  [47m(cw-gstack-for-subterm (REV X))[0m, the output below shows that a
  chain of rewrites generates [47m(APPEND (REV X) Y)[0m as an intermediate
  term but not as the result of a rewrite.

    ACL2 !>(cw-gstack-for-subterm (REV X))
    1. Simplifying the clause
         ((NOT (INTEGERP N))
          (< N '0)
          (NOT (< N (LEN X)))
          (EQUAL (NTH N (BINARY-APPEND (REV X) Y))
                 (NTH N (REVERSE X))))
    2. Rewriting (to simplify) the atom of the fourth literal,
         (EQUAL (NTH N (BINARY-APPEND (REV X) Y))
                (NTH N (REVERSE X))),
    3. Rewriting (to simplify) the second argument,
         (NTH N (REVERSE X)),
    4. Rewriting (to simplify) the second argument,
         (REVERSE X),
    5. Attempting to apply (:DEFINITION REVERSE) to
         (REVERSE X)
    6. Rewriting (to simplify) the body,
         (IF (STRINGP X)
             (COERCE (REVAPPEND (COERCE X 'LIST) 'NIL)
                     'STRING)
           (REVAPPEND X 'NIL)),
       under the substitution
         X : X
    7. Rewriting (to simplify) the third argument,
         (REVAPPEND X 'NIL),
       under the substitution
         X : X
    8. Attempting to apply (:REWRITE REVAPPEND-REMOVAL) to
         (REVAPPEND X 'NIL)
    9. Rewriting (to simplify) the rhs of the conclusion,
         (BINARY-APPEND (REV X) Y),
       under the substitution
         Y : 'NIL
         X : X
    10. Attempting to apply (:REWRITE APPEND-ATOM-UNDER-LIST-EQUIV) to
         (BINARY-APPEND (REV X) 'NIL)
    The resulting (translated) term is
      (REV X).
    Note: The first lemma application above that provides a suitable result
    is at frame 5, and that result is
      (IF (STRINGP X)
          (COERCE (REV (COERCE X 'LIST)) 'STRING)
        (REV X)).
    ACL2 !>

  The version of this example without [47m:hints[0m also illustrates the
  second item above, about discarding matches that occur in the
  [47m:target[0m of rewriting.  Without that restriction we would see a
  result for the query [47m(cw-gstack-for-subterm (APPEND (REV X) Y))[0m
  from an attempt to rewrite the term [47m(NTH N (APPEND (REV X) Y))[0m.
  But that would not help us to find the source of the term [47m(APPEND
  (REV X) Y)[0m.


General form of [47mwith-brr-data[0m calls

  The general form, including optional keyword arguments, is

    (with-brr-data form :global-var var :brr-data-returned bool)

  where [47mform[0m is typically an event but is only required to evaluate to
  an [error-triple].  By default (i.e., when the keyword arguments
  are omitted), that error triple is returned by the [47mwith-brr-data[0m
  call.

  There is probably little reason for most users to supply either
  keyword argument.  They are documented in the section after next.

  [31;1mNotes[0m.

    * The data collected by a call of [47mwith-brr-data[0m will persist until the
      next call of [47mwith-brr-data[0m.

    * Behavior is undefined for nested calls of [47mwith-brr-data[0m.  (If this
      presents a problem then you may ask the ACL2 implementors to
      consider specifying that behavior.)


General forms of queries

  The four queries (all illustrated above) are as follows, where the
  keyword argument is optional.

    (cw-gstack-for-subterm u :global-var var)
    (cw-gstack-for-subterm* u :global-var var)
    (cw-gstack-for-term u :global-var var)
    (cw-gstack-for-term* u :global-var var)

  In each case, [47mu[0m is either a term (which can be a user-level term,
  i.e., not necessarily translated; see [term]) or of the form [47m(:free
  (v1 ... vk) u1)[0m where [47mu1[0m is a term.  In the latter case, [47mv1[0m through
  [47mvk[0m must be distinct variables that all occur in (the translation
  of) [47mu1[0m.

  These queries are effective after data collection using
  [47mwith-brr-data[0m, which is typically wrapped around an event that
  calls the theorem prover.  To understand how the queries work, it
  is useful to view a proof attempt as generating ``initial'' calls
  of the rewriter, such as when rewriting a hypothesis or the
  conclusion of a goal (technically, a literal of the goal clause;
  see [clause]): that is, initial rewriter calls are those that are
  not under another rewriter call.  Then data collection under each
  initial call creates a tree of ``top-level'' calls --- those not
  made under an attempt to relieve a hypothesis --- for which that
  initial call is the root.  Thus each node of that tree corresponds
  to a rewriter call, and each child of that node is a top-level call
  of the rewriter that is immediately under that call, where the
  order of calls is respected by the ordering of child nodes from
  left to right.  For example, the top-level application a rewrite
  rule corresponds to a node, and the call to rewrite the right-hand
  side of the rule (with appropriate variable bindings) corresponds
  to a child of that node.  Another example is when an attempt to
  rewrite a function call leads to an attempt to rewrite an argument
  of that call: the latter corresponds to a child node of the former.
  Each of the four query utilities looks for the first root node, and
  the left-most branch under that node, that results in a rewriter
  result that ``matches'' the input in the following sense.

  This notion of ``matches'' depends on the call, as follows.  First
  assume that the input is a term.  For [47mcw-gstack-for-subterm[0m and
  [47mcw-gstack-for-subterm*[0m, the result matches when it contains the
  given term as a subterm.  For [47mcw-gstack-for-term[0m and
  [47mcw-gstack-for-term*[0m, the result matches when it is exactly the
  given term.  Now suppose the input is [47m(:free (v1 ... vk) u)[0m.  Then
  the notion of ``matches'' is modified to allow any instance [47mu/s[0m for
  a substitution [47ms[0m that instantiates only the variables [47mvi[0m.

  When a matching node [47mN1[0m is found for the input term, or in the case
  of [47m(:free (v1 ... vk) u)[0m, some instance of [47mu[0m, then a further search
  below [47mN[0m is made to find a maximal left-most branch below it that
  terminates in a node [47mN2[0m that also matches, using the same
  substitution in the case of [47m:free[0m.  If no such branch is found,
  then [47mN2[0m is [47mN[0m.  Either way, the term or instance that matched at [47mN[0m
  (as a subterm in the case of [47mcw-gstack-for-subterm[0m or
  [47mcw-gstack-for-subterm*[0m, else as an exact match) also matches at [47mN2[0m.
  The output then shows a path to [47mN2[0m, but if [47mN1[0m and [47mN2[0m differ then
  the output also notes that the first match was at [47mN1[0m, as we have
  seen in each ``Note'' at the end of logs displayed above.

  The discussion above characterizes the behavior of
  [47mcw-gstack-for-subterm[0m and [47mcw-gstack-for-term[0m; now let us consider
  [47mcw-gstack-for-subterm*[0m and [47mcw-gstack-for-term*[0m.  These ``[47m*[0m''
  versions query after each result to ask if another result is
  desired.  If so, the search starts strictly after [47mN[0m; it does not
  look for a second successor [47mN2[0m of [47mN[0m.  The search continues until
  either the user answers [47mn[0m (regardless of the package; the query
  cares only that the [47m[symbol-name][0m is [47m\"Y\"[0m or [47m\"N\"[0m) or there are no
  more results.


Keyword arguments of [47mwith-brr-data[0m (optional)

  As noted above, the general form of a call of [47mwith-brr-data[0m is as
  follows.

    (with-brr-data form :global-var var :brr-data-returned bool)

  The keywords have aspects that are quite technical, so unless you are
  somewhat familiar with ACL2 implementation issues you will probably
  want to skip this section.

  Neither keyword argument is evaluated.  The behavior of the keyword
  arguments depends on a list, [47mBDL[0m (``Brr-Data List''), that is
  typically made available by a call of [47mwith-brr-data[0m, as described
  below.  The members of [47mBDL[0m represent successful initial calls of
  the rewriter, in order.  Each of those members is a [47mbrr-data[0m
  record, as described in the next section.  After the [47mwith-brr-data[0m
  call returns, then [47m(mv nil BDL state)[0m is returned by evaluation of
  [47m(brr-data-lst state)[0m, until the next time that either a call of
  [47mwith-brr-data[0m or the form [47m(clear-brr-data-lst)[0m is evaluated.
  Implementation notes: information is stored in the [47mbrr-data[0m
  [wormhole]; [47m(brr-data-lst state)[0m extracts that information and
  reorders appropriately before producing [47mBDL[0m; and
  [47m(clear-brr-data-lst)[0m removes that information from the [47mbrr-data[0m
  wormhole.

  We now explain the keyword arguments in terms of the list [47mBDL[0m.

    * [47m:global-var var[0m
      The symbol [47mvar[0m defaults to the symbol, [47mbrr-data-lst[0m.  [47mVar[0m is either
      [47mnil[0m or a state global variable (see [programming-with-state]),
      which by default is [47mbrr-data-lst[0m.  If [47mvar[0m is not [47mnil[0m, then the
      [47mwith-brr-data[0m call modifies [state] by setting the value of the
      state global, [47mvar[0m, to [47mBDL[0m.

    * [47m:brr-data-returned bool[0m
      Suppose that the [47mform[0m argument of the [47mwith-brr-data[0m call evaluates
      to [47m(mv erp val state)[0m.  Then when [47mbool[0m is [47mnil[0m (which is the
      default), the [47mwith-brr-data[0m call returns that same
      [error-triple], [47m(mv erp val state)[0m.  If however [47mbool[0m is not
      [47mnil[0m, then instead the [47mwith-brr-data[0m call returns [47m(mv erp BDL
      state)[0m.


Low-level details (optional)

  This implementation-level section further describes the [47mbrr-data[0m
  structure mentioned above.  It is probably of interest only to
  those who consider writing their own tools to query the data
  produced by [47mwith-brr-data[0m.

  A [47mbrr-data[0m record is a structure that has a field [47m:brr-data-1[0m
  representing information from entry into the rewriter, a field
  [47m:brr-data-2[0m representing information from the corresponding exit
  from the rewriter, and a field [47m:completed[0m that is the list of
  [47mbrr-data[0m records produced between that entry and exit, in order.
  (Implementation detail: these are produced inside the [47mbrr-data[0m
  [wormhole] by the same functions, [47mbrkpt1[0m and [47mbrkpt2[0m, that implement
  the [break-rewrite] utility.)

    (defrec brr-data
      (pre post . completed)
      nil)

    (defrec brr-data-1
      (((lemma . target) . (unify-subst type-alist . geneqv))
       .
       ((pot-list . ancestors) . (rcnst initial-ttree . gstack)))
      nil)

    (defrec brr-data-2
      ((failure-reason unify-subst . brr-result)
       .
       (rcnst final-ttree . gstack))
      nil)

  The [47mbrr-data[0m definition introduces a recursive data type (as per ACL2
  source function [47mbrr-data-p[0m, since the [47m:completed[0m field is a list of
  [47mbrr-data[0m records.  These correspond to immediate sub-calls of the
  rewriter, yielding ``child nodes'' as described in the section,
  ``General forms of queries''.

  We have seen above that the use of [47mwith-brr-data[0m activates the
  collection of break-rewrite data.  Collection may also be activated
  by assigning the [state] global, [47mgstackp[0m, to the value [47m:brr-data[0m.
  (See [programming-with-state] for relevant programming background.)
  You can use [47m:[0m[47m[trans1][0m on a [47mwith-brr-data[0m call to see how
  [47mwith-brr-data[0m sets [47mgstackp[0m.  Note that setting (or binding) [47mgstackp[0m
  to [47m:brr-data[0m has the effect of [47m:[0m[47m[brr][0m[47m t[0m but enhanced with
  collection of [47mbrr-data[0m records.  When [47mgstackp[0m has value [47m:brr-data[0m,
  [47m:brr t[0m is treated as a no-op and [47m:brr nil[0m is an error, to avoid
  inadvertently turning off [47mbrr-data[0m record collection.  Note that
  although [47mwith-brr-data[0m is disallowed in ACL2(p) (see [parallelism])
  when [waterfall-parallelism] is enabled, this prohibition can be
  circumvented by assigning [47mgstackp[0m to [47m:brr-data[0m; however, in that
  case [47mwith-brr-data[0m might well not behave correctly.

  The programmer who manipulates [47mbrr-data[0m records may wish to look at
  the ACL2 source code and the [break-rewrite] documentation to
  understand the fields of the [47mbrr-data-1[0m and [47mbrr-data-2[0m records.
  The form [47m(brr-data-listp t lst)[0m recognizes a list of well-formed
  [47mbrr-data[0m records.  The [47m:failure-reason[0m field of the [47mbrr-data-2[0m
  record may be of particular interest; see ACL2 source function
  [47mtilde-@-failure-reason-phrase1[0m for the forms that this field may
  take.

  It is easy to see the list of [47mbrr-data[0m records created by a call of
  [47mwith-brr-data[0m.  A big hint is given in the output printed at the
  completion of a [47mwith-brr-data[0m call, as suggested in the first
  example in the introduction, with the following output.

    ACL2 Observation:  (LENGTH (@ BRR-DATA-LST)) = 16

  The form [47m(@ BRR-DATA-LST)[0m evaluates to the resulting list of [47mbrr-data[0m
  records, one for each so-called ``initial call'' of the rewriter,
  in the sense described in the section above on ``Keyword
  arguments''.  The utility [47mshow-brr-data-lst[0m can be applied to such
  a list to show the most interesting parts of each record, for
  example, [47m(show-brr-data-lst (@ brr-data-lst))[0m.  Also you can call
  the utility [47mshow-brr-data[0m on a single [47mbrr-data[0m record.


Using attachments to modify functionality of [47mwith-brr-data[0m

  The behavior of [47mwith-brr-data[0m is customizable by using attachments
  (see [defattach]).  The macro, [47mset-brr-data-attachments[0m, has been
  provided for this purpose.  This section provides only minimal
  documentation on this customizability; those who want to implement
  new such attachments can look at the following examples in the
  [community-books] to get a sense of how that might be done.  Note
  that the query utilities work the same regardless of the
  attachments, and the relevant data structures are also unchanged.

    books/kestrel/utilities/brr-data-all.lisp
    books/kestrel/utilities/brr-data-failures.lisp

  When the macro is called with no arguments, i.e.,
  [47m(set-brr-data-attachments)[0m, behavior is restored to the built-in
  behavior as described above.  But this macro can be given an
  argument that indicates a string: it is either a string or a
  symbol, where a symbol indicates its [47m[symbol-name][0m.  The indicated
  string, which we write below as [47m\"<S>\"[0m, is added as a suffix after a
  hyphen to create four system attachments.  These are [47m[defattach][0m
  calls rather than [47m[defattach-system][0m calls, so that their effect is
  not [local] to the enclosing book.

    (defattach (brkpt1-brr-data-entry brkpt1-brr-data-entry-<S> :system-ok t)
    (defattach (brkpt2-brr-data-entry brkpt2-brr-data-entry-<S> :system-ok t)
    (defattach (update-brr-data-1 update-brr-data-1-<S>) :system-ok t)
    (defattach (update-brr-data-2 update-brr-data-2-<S>) :system-ok t)

  The four [47m\"-<S>\"[0m functions must be defined to match the signatures of
  the functions to which they are attached.  Those functions have the
  following arguments and results, where [47m*[0m indicates an ordinary
  (non-[stobj]) value.

    (brkpt1-brr-data-entry ancestors gstack rcnst state) => *
    (brkpt2-brr-data-entry ancestors gstack rcnst state) => *
    (update-brr-data-1 lemma target unify-subst type-alist ancestors
                       initial-ttree gstack rcnst pot-lst whs-data) => *
    (update-brr-data-2 wonp failure-reason unify-subst gstack brr-result
                       final-ttree rcnst ancestors whs-data) => *

  Note that [47m(set-brr-data-attachments)[0m is actually equivalent to
  [47m(set-brr-data-attachments builtin)[0m.  That is, the initial
  (built-in) attachments to the functions above all have the suffix,
  [47m\"-BUILTIN\"[0m.")
 (WITH-CBD
  (BOOKS-REFERENCE)
  "To bind the connected book directory

  [47mWith-cbd[0m sets the connected book directory (see [cbd]) within its
  scope.

    Example Forms:

    ; Equivalent to (include-book \"dir1/dir2/foo\"):
    (with-cbd \"dir1\"
              (include-book \"dir2/foo\"))

    ; Equivalent to evaluation of the form,
    ; (include-book \"arithmetic/top\" :dir :system)'):
    (with-cbd (cdr (assoc-eq :system (project-dir-alist (w state))))
              (include-book \"arithmetic/top\"))

  See [cbd] for a description of the connected book directory.  The
  ``Technical Remark'' there, about Lisp using the [47mcbd[0m to elaborate
  relative pathnames, applied to [47mwith-cbd[0m as well.

    General Form:
    (with-cbd str form)

  where [47mstr[0m evaluates to a nonempty string that represents the desired
  directory (see [pathname]) and [47mform[0m evaluates to an [error-triple].

  The effect of [47m(with-cbd str form)[0m is to evaluate first [47m(set-cbd str)[0m
  and then to evaluate [47mform[0m, after which the connected book directory
  is restored to the value it had before that evaluation of [47mset-cbd[0m.
  However, the implementation is designed so that the connected book
  directory is restored even when the evaluation of [47mform[0m causes an
  error.

  The form [47m(with-cbd str ev)[0m is an [event] form if [47mev[0m is an event form;
  thus, it may occur in [books] as well as [47m[encapsulate][0m and [47m[progn][0m
  events.  See [embedded-event-form].  But in an [event] context, [47mstr[0m
  must be a string, not merely an expression that evaluates to a
  string.

  Finally, note that Lisp compilers may vary in how they handle
  functions defined within the scope of [47mwith-cbd[0m.  If you find an
  example of slower execution caused by using [47mwith-cbd[0m, please feel
  free to send it to the ACL2 implementors.")
 (WITH-CURRENT-PACKAGE
  (BOOKS-REFERENCE)
  "To bind the [current-package]

  Evaluation of a form [47m(with-current-package \"pkg\" form[0m) causes [47mform[0m to
  be evaluated with the [current-package] bound to [47m\"pkg\"[0m.

  Example and [31;1mWARNING[0m.  The current-package is not modified until after
  the form is read!  Consider the following log that was produced
  when the value of the current-package was the default, [47m\"ACL2\"[0m.

    ACL2 !>(with-current-package \"ACL2-USER\"
                                 (value (cw \"~x0~%\" 'abcd)))
    ACL2::ABCD
     NIL
    ACL2 !>

  We see that the call of [47m[cw][0m did its printing relative to the
  [47m\"ACL2-USER\"[0m package, producing output [47m\"ACL2::ABCD\"[0m.  This
  illustrates that the form was [3mread[0m with respect to package [47m\"ACL2\"[0m
  but that its [3mevaluation[0m took place with respect to package
  [47m\"ACL2-USER\"[0m.

    General Form:
    (with-current-package str form)

  where [47mstr[0m evaluates to a nonempty string that represents the desired
  package (see [current-package]) and [47mform[0m evaluates to an
  [error-triple].

  Evaluation of [47m(with-current-package str form)[0m first switches to the
  indicated package, as with [47m(in-package str)[0m, and evaluates [47mform[0m,
  after which the current-package is restored to the value it had
  before that evaluation of [47mwith-current-package[0m.  The implementation
  is designed so that the current-package is restored even when the
  evaluation of [47mform[0m causes an error.

  The following example drives home the behavior of
  [47mwith-current-package[0m; explanation follows.

    ACL2 !>'common-lisp::defun
    DEFUN
    ACL2 !>'acl2-user::defun
    DEFUN
    ACL2 !>(with-current-package
            \"ACL2-USER\"
            (er-progn (set-current-package \"ACL2-PC\" state)
                      (value (cw \"~x0~%\" 'defun))))
    COMMON-LISP::DEFUN
     NIL
    ACL2 !>

  The symbol [47mcommon-lisp::defun[0m is imported from the [47m\"COMMON-LISP\"[0m
  package into both the [47m\"ACL2\"[0m package and, as shown in the first two
  evaluation results above, the [47m\"ACL2-USER\"[0m package.  But it's not
  imported into the [47m\"ACL2-PC\"[0m package.  The call above of
  [47mwith-current-package[0m reads [47m'defun[0m into the current package, [47m\"ACL2\"[0m.
  Then for evaluation the package changes to [47m\"ACL2-USER\"[0m; then the
  package is changed again to [47m\"ACL2-PC\"[0m before evaluating the [47m[cw][0m
  call in that package, necessitating the [47m\"COMMON-LISP::\"[0m prefix
  since the [47mdefun[0m symbol in that [47mcw[0m call is not in the [47m\"ACL2-PC\"[0m
  package.  But notice that the prompt comes back as [47m\"ACL2 !>\"[0m,
  indicating that we are back in the [47m\"ACL2\"[0m package.  The original
  package is restored after the [47mwith-current-package[0m call completes
  evaluation, even when the current-package is changed during
  evaluation.

  The form [47m(with-current-package str ev)[0m is an [event] form if [47mev[0m is an
  event form; thus, it may occur in [books] as well as [47m[encapsulate][0m
  and [47m[progn][0m events.  See [embedded-event-form].  But in an [event]
  context, [47mstr[0m must be a string, not merely an expression that
  evaluates to a string.

  Finally, note that Lisp compilers may vary in how they handle
  functions defined within the scope of [47mwith-current-package[0m.  If you
  find an example of slower execution caused by using
  [47mwith-current-package[0m, please feel free to send it to the ACL2
  implementors.")
 (WITH-FAST-ALIST
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(with-fast-alist name form)[0m causes [47mname[0m to be a fast alist for the
  execution of [47mform[0m.

  Logically, [47mwith-fast-alist[0m just returns [47mform[0m.

  Under the hood, we cause [47malist[0m to become a fast alist before
  executing [47mform[0m.  If doing so caused us to introduce a new hash
  table, the hash table is automatically freed after [47mform[0m completes.

  More accurately, under the hood [47m(with-fast-alist name form)[0m
  essentially expands to something like:

    (if (already-fast-alist-p name)
        form
      (let ((<temp> (make-fast-alist name)))
        (prog1 form
               (fast-alist-free <temp>))))

  Practically speaking, [47mwith-fast-alist[0m is frequently a better choice
  then just using [47m[make-fast-alist][0m, and is particularly useful for
  writing functions that can take either fast or slow alists as
  arguments.  That is, consider the difference between:

    (defun bad (alist ...)
      (let* ((fast-alist (make-fast-alist alist))
             (answer     (expensive-computation fast-alist ...)))
       (prog2$ (fast-alist-free fast-alist)
               answer)))

    (defun good (alist ...)
       (with-fast-alist alist
         (expensive-computation alist ...)))

  Either approach is fine if the caller provides a slow [47malist[0m.  But if
  the input [47malist[0m is already fast, [47mbad[0m will (perhaps unexpectedly)
  free it!  On the other hand, [47mgood[0m is able to take advantage of an
  already-fast argument and will not cause it to be inadvertently
  freed.

  See also the macro [47mwith-fast-alists[0m defined in the community book
  [47m\"books/centaur/misc/hons-extra.lisp\"[0m, which allows you to call
  [47m[with-fast-alist][0m on several alists simultaneously.

  The community book [47m\"books/centaur/misc/hons-extra.lisp\"[0m extends the
  [b*] macro with the [47mwith-fast[0m pattern binder.  That is, after
  executing [47m(include-book \"centaur/misc/hons-extra.lisp\" :dir
  :system)[0m you may write something like this:

    (b* (...
         ((with-fast a b c ...))
         ...)
      ...)

  which causes [47ma[0m, [47mb[0m, and [47mc[0m to become fast alists until the completion
  of the [47mb*[0m form.

  Note that [47mwith-fast-alist[0m will cause logically tail-recursive
  functions not to execute tail-recursively if its cleanup phase
  happens after the tail-recursive call returns.")
 (WITH-GLOBAL-STOBJ
  (STOBJ ACL2-BUILT-INS)
  "Operate on a global single-threaded object

  See [stobj] for an introduction to single-threaded objects.  Also see
  [defstobj] for additional background.

  The [47mwith-global-stobj[0m macro is a relatively advanced utility that
  allows stobjs to be accessed directly from the ACL2 [state].
  Examples may be found in [community-book] file
  [47mbooks/system/tests/with-global-stobj-input.lsp[0m; we draw heavily
  from them below.

    Example Forms:

    ; Read-only form (length 3)
    (with-global-stobj st
      ;; body:
      (fld st))

    ; Updating form (length 4; (returns state))
    (with-global-stobj
      st ; bound stobj
      (st) ; output signature of body
      ;; body:
      (update-fld x st))

    ; Updating form (length 4; returns (mv * * state st2))
    (with-global-stobj
      st ; bound stobj
      (nil st nil state st2) ; output signature of body
      ;; body:
      (let* ((st (update-fld x st))
             (st2 (update-fld2 x st2)))
        (mv (fld st) st (fld st2) state st2)))

  In the forms above, we call [47mst[0m the stobj that is ``bound by'' the
  [47mwith-global-stobj[0m call, and the ``body'' of the form is the last
  argument.  The read-only form above, like all read-only forms, has
  a body that does not return the stobj bound by the form.  Each
  updating form above specifies an output signature as a list, which
  must contain the stobj bound by the form, whose elements are all
  [47mnil[0m (designating a non-stobj value) or a stobj name.  That output
  signature reflects the result of the body; the entire form does not
  return the bound stobj, but does return [47m[state][0m, as explained
  below.

  [47mWith-global-stobj[0m is a macro, and the example forms above expand as
  follows.

    ACL2 !>:trans1 (with-global-stobj st
                     (fld st))
     (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE)))
          (FLD ST))
    ACL2 !>:trans1 (with-global-stobj st
                     (st)
                     (update-fld x st))
     (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE)))
          (LET ((ST (UPDATE-FLD X ST)))
               (WRITE-USER-STOBJ-ALIST 'ST ST STATE)))
    ACL2 !>:trans1 (with-global-stobj st
                     (nil st nil state st2)
                     (let* ((st (update-fld x st))
                            (st2 (update-fld2 x st2)))
                       (mv (fld st) st (fld st2) state st2)))
     (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE)))
          (MV-LET ({WGS}0 ST {WGS}1 STATE ST2)
                  (LET* ((ST (UPDATE-FLD X ST))
                         (ST2 (UPDATE-FLD2 X ST2)))
                        (MV (FLD ST) ST (FLD ST2) STATE ST2))
                  (LET ((STATE (WRITE-USER-STOBJ-ALIST 'ST ST STATE)))
                       (MV? {WGS}0 {WGS}1 STATE ST2))))
    ACL2 !>

  The first illustrates that in the read-only form, the bound stobj,
  which is [47mst[0m in that example, is bound to its value in the
  [47muser-stobj-alist[0m field of the ACL2 [state].  The second and third
  similarly bind the stobj, [47mst[0m, but then update that stobj according
  to the body of the [47mwith-global-stobj[0m call (its last argument) and
  then update the [47muser-stobj-alist[0m of the state with that stobj's
  resulting value.  You can of course use [47m:[0m[47m[trans1][0m in this way to
  see expansions of other [47mwith-global-stobj[0m calls.

  Note that ACL2 expects you to use [47mwith-global-stobj[0m, not its
  expansions in terms of the [non-executable] functions
  [47mread-user-stobj-alist[0m, which accesses the bound stobj from the
  user-stobj-alist of [47mstate[0m, and [47mwrite-user-stobj-alist[0m, which
  completes the write for updating [47mwith-global-stobj[0m forms.  These
  are defined as follows, in terms of the ACL2 state's
  user-stobj-alist field, which maps stobj names to their values.

    (defun-nx read-user-stobj-alist (st state)
      (declare (xargs :guard (symbolp st)
                      :stobjs state))
      (cdr (assoc-eq st (user-stobj-alist1 state))))

    (defun-nx write-user-stobj-alist (st val state)
      (declare (xargs :guard (symbolp st)
                      :stobjs state))
      (update-user-stobj-alist1
       (put-assoc-eq st val (user-stobj-alist1 state))
       state))

  [47mWith-global-stobj[0m can be useful when you want a function to read or
  write a stobj but you don't want to pass that stobj as a formal
  parameter.  As long as you pass [47mstate[0m as a formal parameter, you
  can access the stobj using [47mwith-global-stobj[0m.

  This topic is intended to be sufficient preparation for the use of
  [47mwith-global-stobj[0m.  Those who want to read more about design and
  underlying theory are welcome to peruse the (long) ACL2 source code
  comments, ``Essay on the Design of With-global-stobj'' and ``Essay
  on Correctness of Evaluation with Stobjs''.


More Examples

  As noted above, examples may be found in [community-book] file
  [47mbooks/system/tests/with-global-stobj-input.lsp[0m.  Here we discuss
  some of those examples.

  Let us start by introducing a couple of stobjs.

    (defstobj st fld)
    (defstobj st2 fld2 :congruent-to st)

  Calls of [47mwith-global-stobj[0m are illegal at the top level (as opposed
  to occurrences in the bodies of a definition or a theorem).

    (with-global-stobj st (fld st))

  One solution may be to use [47m[top-level][0m.

    (top-level (with-global-stobj st (fld st)))

  Normally, however, [47mwith-global-stobj[0m is used inside definition
  bodies.  Here we read and write the stobj, [47mst[0m, directly from the
  ACL2 [state].

    (defun rd0 (state)
      (declare (xargs :stobjs state))
      (with-global-stobj st (fld st)))

    (defun wr0 (x state)
      (declare (xargs :stobjs state))
      (with-global-stobj st (st) (update-fld x st)))

  Let's see these in action, first writing and then reading.

    ACL2 !>(wr0 2 state)
    <state>
    ACL2 !>(rd0 state)
    2
    ACL2 !>(fld st)
    2
    ACL2 !>

  We can use various stobj operations, even the rather fancy
  [47m[swap-stobjs][0m, in the body of a [47mwith-global-stobj[0m call.  The
  following events are admissible.

    (update-fld 1 st)
    (update-fld 2 st2)

    (defun f3 (st2 state)
      (declare (xargs :stobjs (st2 state)))
      (with-global-stobj
        st
        (st2 st)
        (swap-stobjs st2 st)))

    (f3 st2 state)

    (assert-event (and (equal (fld st) 2)
                       (equal (fld st2) 1)))

  The following function writes to both [47mst[0m and [47mst2[0m without passing in
  either one (just [47mstate[0m).  Notice that the inner [47mwith-global-stobj[0m
  call has a body that returns the indicated values [47mst[0m and [47mst2[0m, but
  since [47mst2[0m is bound by the call, it is dropped before returning from
  the call, and [47mstate[0m is added --- which explains the list [47m(st state)[0m
  supplied to the outer call.

    (defun write-global-st-st2 (fld fld2 state)
      (declare (xargs :stobjs state))
      (with-global-stobj st
        (st state)
        (let ((st (update-fld fld st)))
          (with-global-stobj st2
            (st st2)
            (let ((st2 (update-fld fld2 st2)))
              (mv st st2))))))

  Let's check that this works as expected.

    ACL2 !>(write-global-st-st2 'a 'b state)
    <state>
    ACL2 !>(fld st)
    A
    ACL2 !>(fld st2)
    B
    ACL2 !>

  We can also read both fields.

    (defun read-global-st-st2 (state)
      (declare (xargs :stobjs state))
      (with-global-stobj st
        (with-global-stobj st2
          (list (fld st) (fld st2)))))

  Then, continuing with the session above:

    ACL2 !>(read-global-st-st2 state)
    (A B)
    ACL2 !>

  We can reason about [47mwith-global-stobj[0m by reasoning about its
  expansions.  Consider the following theorem (continuing the session
  above).

    (defthm rd0-of-wr0
      (equal (rd0 (wr0 val state))
             val))

  This fails to prove, but each of the two checkpoints has a term of
  the form [47m(ASSOC-EQUAL 'ST (PUT-ASSOC-EQUAL 'ST _ _))[0m.  That
  suggests the following lemma.

    (defthm assoc-equal-put-assoc-equal
      (equal (assoc-equal key (put-assoc-equal key val alist))
             (cons key val)))

  This lemma proves automatically, after which [47mrd0-of-wr0[0m proves
  automatically.


Syntax and Semantics

  This section provides a reference for [47mwith-global-stobj[0m.  The next
  section discusses restrictions that avoid aliasing problems.

    General Forms:
    ; Read-only form (length 3):
    (with-global-stobj st form)
    ; Updating form (length 4):
    (with-global-stobj st lst form)

  where [47mst[0m is the name of a [stobj] that is user-defined (i.e., not
  [47mstate[0m), [47mform[0m is subject to syntactic restrictions discussed below,
  and [47mlst[0m is a list, sometimes called an ``output signature''.  That
  list indicates the list of [47mN[0m values returned by [47mform[0m, which must
  include the bound stobj, [47mst[0m: thus [47mlst[0m is [47m(st)[0m if [47mN[0m is 1, indicating
  that [47mform[0m returns an instance of that stobj; and otherwise [47mform[0m
  returns multiple values [47m(x0 x1 ... xk)[0m where [47mk[0m is [47mN-1[0m and for each
  [47mi[0m, [47mxi[0m is either [47mnil[0m if the [47mi[0mth value is an ordinary value or else
  is the name of a stobj returned in that position (and one such
  stobj name is the bound stobj).

  In each General Form above, [47mst[0m and [47mform[0m are called the ``bound
  stobj'' and ``body'' of the [47mwith-global-stobj[0m call (respectively).

  For the read-only form, the bound stobj (which is [47mst[0m above) must not
  be returned by the body of the form.

  For the updating form, the values actually returned are obtained by
  removing [47mst[0m from [47mlst[0m and then, if [47mstate[0m is not already in [47mlst[0m,
  adding [47mstate[0m at the end of [47mlst[0m.  Consider the following example.

    (defun f0 (st2 state)
      (declare (xargs :stobjs (st2 state)))
      (with-global-stobj
        st
        (st st2 nil state)
        (mv st st2 nil state)))

  In this case, [47mlst[0m is [47m(st st2 nil state)[0m, and the following expansion
  shows that [47mst[0m has been dropped from the returned values.

    ACL2 !>:trans1 (with-global-stobj
                     st
                     (st st2 nil state)
                     (mv st st2 nil state))
     (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE)))
          (MV-LET (ST ST2 {WGS}0 STATE)
                  (MV ST ST2 NIL STATE)
                  (LET ((STATE (WRITE-USER-STOBJ-ALIST 'ST ST STATE)))
                       (MV? ST2 {WGS}0 STATE))))
    ACL2 !>

  Evaluation of an updating [47mwith-global-stobj[0m form always updates
  [47mstate[0m: specifically it updates its [47muser-stobj-alist[0m field (see
  [state]).  The following example is similar to the one above,
  except that this time the body of the [47mwith-global-stobj[0m call does
  not return state; nevertheless, the entire call does return state.
  It illustrates that when [47mstate[0m is not in the list given as the
  second argument of an updating [47mwith-global-stobj[0m call, then the
  [47mwith-global-stobj[0m form not only drops the bound stobj from its
  return values but also adds [47mstate[0m as the last returned value (or,
  if the bound stobj was the sole symbol in the list, then the call
  returns [47mstate[0m as the sole value).

    ACL2 !>:trans1 (with-global-stobj
                     st
                     (st st2 nil)
                     (mv st st2 nil))
     (LET ((ST (READ-USER-STOBJ-ALIST 'ST STATE)))
          (MV-LET (ST ST2 {WGS}0)
                  (MV ST ST2 NIL)
                  (LET ((STATE (WRITE-USER-STOBJ-ALIST 'ST ST STATE)))
                       (MV? ST2 {WGS}0 STATE))))
    ACL2 !>

  Note that because [47mwith-global-stobj[0m updates [47mstate[0m, then [47mstate[0m must be
  a known stobj when [47mwith-global-stobj[0m is called.  In particular, in
  order to call [47mwith-global-stobj[0m in the body of a function, [47mstate[0m
  should be a formal parameter of that function.


Syntactic Restrictions to Avoid Aliasing

  For the examples in this section, we continue to assume that the
  following [47m[defstobj][0m [events] have been evaluated.

    (defstobj st fld)
    (defstobj st2 fld2 :congruent-to st)

  Consider the following definition.

    (defun foo (st state)
      (declare (xargs :stobjs (st state)))
      (let ((state (with-global-stobj st
                     (st)
                     (update-fld 3 st))))
        (mv (fld st) state)))

  ACL2 admits that form, but causes an error with the following call of
  [47mfoo[0m.

    ACL2 !>(foo st state)


    ACL2 Error in TOP-LEVEL:  Illegal top-level form, (FOO ST STATE).
    The stobj ST occurs free, yet may be bound by an updating WITH-GLOBAL-
    STOBJ form, as the top-level form calls FOO, which makes an updating
    WITH-GLOBAL-STOBJ call that binds ST.  See :DOC with-global-stobj.

    ACL2 !>

  Let us see why this call must be illegal; then we'll study the error
  message.  The [47mwith-global-stobj[0m form above will set the field, [47mfld[0m,
  of [47mst[0m to the value, 3.  Moreover, ACL2 uses destructive update on
  stobjs: the actual Lisp object representing [47mst[0m has value 3 in its
  field, and this is the same object for which we return [47m(fld st)[0m
  from [47mfoo[0m.  So if [47m(foo st state)[0m were allowed to execute, it would
  return the multiple values [47m(3 <state>)[0m.  However, ACL2 can prove
  that ACL2 returns [47m(fld st)[0m unchanged:

    (thm (implies (stp st)
                  (equal (mv-nth 0 (foo st state))
                         (fld st))))

  What we are seeing is a violation of single-threadedness.

  Now let's look at the error message above.  It explains that ``the
  stobj ST occurs free'' in [47m(foo st state)[0m: indeed, [47mst[0m is the first
  argument of that call.  Therefore, [47mst[0m can be accessed in that
  top-level form; indeed, we have seen that it is returned as the
  first value.  However, [47mst[0m can also be destructively modified
  because of the updating [47mwith-global-stobj[0m call in the body of [47mfoo[0m:
  ``the top-level form calls FOO, which makes an updating
  WITH-GLOBAL-STOBJ call that binds ST.'' As we have discussed, that
  updating call destroys single-threadedness, and hence must be
  avoided.  We may call this an ``aliasing problem'', since the bound
  stobj shares structure with the formal parameter.

  By contrast, there is no such problem if we replace [47mst[0m by its
  congruent stobj, [47mst2[0m, in the top-level call.

    ACL2 !>(foo st2 state)
    (NIL <state>)
    ACL2 !>(fld st2)
    NIL
    ACL2 !>(fld st)
    3
    ACL2 !>

  In this case there is no aliasing problem.  The formal parameter [47mst[0m
  of [47mfoo[0m is bound to the (global) value of [47mst2[0m, which does not share
  structure with the (global) value of stobj [47mst[0m that is updated by
  the [47mwith-global-stobj[0m form.

  Note that the aliasing problem can be buried through a chain of
  function calls, as we now illustrate.  Function [47mfoo2[0m is like [47mfoo[0m
  above, with two changes: instead of updating the field with [47m3[0m we
  update it with the formal parameter, [47mval[0m; and that update is done
  inside the called function, [47mfoo2-sub[0m, rather than directly in the
  body of [47mfoo2[0m.

    (defun foo2-sub (val state)
      (declare (xargs :stobjs state))
      (with-global-stobj st
        (st)
        (update-fld val st)))

    (defun foo2 (val st state)
      (declare (xargs :stobjs (st state)))
      (let ((state (foo2-sub val state)))
        (mv (fld st) state val)))

  The error message is essentially the same, except that the chain of
  calls is shown that leads to the problematic updating
  [47mwith-global-stobj[0m form.  The behavior on [47mst2[0m instead of [47mst[0m is fine,
  as before.

    ACL2 !>(foo2 3 st state)


    ACL2 Error in TOP-LEVEL:  Illegal top-level form, (FOO2 3 ST STATE).
    The stobj ST occurs free, yet may be bound by an updating WITH-GLOBAL-
    STOBJ form, as the top-level form calls FOO2, which calls FOO2-SUB,
    which makes an updating WITH-GLOBAL-STOBJ call that binds ST.  See
    :DOC with-global-stobj.

    ACL2 !>(foo2 4 st2 state)
    (NIL <state> 4)
    ACL2 !>(fld st2)
    NIL
    ACL2 !>(fld st)
    4
    ACL2 !>

  So far we have seen just one aliasing problem, i.e., between a free
  stobj in a top-level form and a subsidiary updating
  [47mwith-global-stobj[0m form.  Another case is where the free stobj in a
  top-level form is actually returned (we might say, updated) by that
  form; in that case, any subsidiary [47mwith-global-stobj[0m form is
  problematic, even if it is read-only.  Here is an example.

    (defun g2 (val st state)
      (declare (xargs :stobjs (st state)))
      (let ((st (update-fld val st)))
        (let ((f (with-global-stobj st (fld st))))
          (mv f (fld st) st state))))

    (g2 nil st state)

  As before, the definition is fine, but the ensuing top-level call is
  not.  And as before, if we replace the top-level stobj occurrence
  by one that is congruent to [47mst[0m, there is no error: [47m(g2 5 st2
  state)[0m.

  Note that there is no aliasing problem when there is no update of the
  stobj, either in the top-level form or in the subsidiary
  [47mwith-global-stobj[0m form.  The following are perfectly legal, for
  example.

    (defun g1 (st state)
      (declare (xargs :stobjs (st state)))
      (let ((f (with-global-stobj st (fld st))))
        (mv f state (fld st))))

    (g1 st state)

  So far we have seen two similar error cases due to aliasing: both are
  top-level calls involving a stobj occurrence that has an occurrence
  below bound by [47mwith-global-stobj[0m, where at least one of the two
  occurrences updates the stobj.  Consider this: a top-level call
  like [47m(foo st state)[0m could be viewed as grabbing [47mst[0m from the ACL2
  state, hence could be viewed as being [47m(with-global-stobj st (foo st
  state))[0m.  So we can think of the restrictions as being about nested
  [47mwith-global-stobj[0m calls, and that leads us to the final two cases.
  Here is a summary of all the restrictions to prevent aliasing,
  starting with the two discussed above about top-level evaluation,
  and ending with the two new ones about nested [47mwith-global-stobj[0m
  calls.

    * In a form [47mu[0m that is legal at the top-level, where [47mu[0m has a free
      occurrence of stobj [47mst[0m, there is no updating [47mwith-global-stobj[0m
      call that binds [47mst[0m and is invoked during evaluation of [47mu[0m.

    * In a form [47mu[0m that is legal at the top-level, where [47mu[0m returns stobj [47mst[0m,
      there is no [47mwith-global-stobj[0m call that binds [47mst[0m and is invoked
      during evaluation of [47mu[0m.

    * In a form [47m(with-global-stobj st u)[0m, there is no updating
      [47mwith-global-stobj[0m call that binds [47mst[0m and is invoked during
      evaluation of [47mu[0m.

    * In an updating form [47m(with-global-stobj st lst u)[0m, there is no
      [47mwith-global-stobj[0m call that binds [47mst[0m and is invoked during
      evaluation of [47mu[0m.

  Our restrictions that prevent aliasing are syntactic ones, sufficient
  to prevent the invocations described above.  They are implemented
  by searching for calls of [47mread-user-stobj-alist[0m to identify
  expansions of [47mwith-global-stobj[0m calls, and by searing for calls of
  [47mwrite-user-stobj-alist[0m to identify expansions of updating
  [47mwith-global-stobj[0m calls.

  Finally, we note that the syntactic restrictions extend to [guard]s.
  Consider again the function [47mrd0[0m as defined above, and let's use it
  in the guard of a function.

    (defun rd0 (state)
      (declare (xargs :stobjs state))
      (with-global-stobj st (fld st)))

    (defun call-rd0-in-guard (state)
      (declare (xargs :stobjs state
                      :guard (rd0 state))
               (ignore state))
      17)

  Then as before, it is an error for a top-level form to update [47mst[0m and
  also call a function that may lead to a [47mwith-global-stobj[0m call that
  binds [47mst[0m.

    ACL2 !>(let ((st (update-fld 3 st)))
             (mv st (call-rd0-in-guard state)))


    ACL2 Error in TOP-LEVEL:  Illegal top-level form,
    (LET ((ST (UPDATE-FLD 3 ST))) (LIST ST (CALL-RD0-IN-GUARD STATE))).
    The stobj ST is returned by evaluation of that form, yet is bound by
    a WITH-GLOBAL-STOBJ form, as the top-level form calls CALL-RD0-IN-GUARD,
    which calls RD0, which makes a WITH-GLOBAL-STOBJ call that binds ST.
    See :DOC with-global-stobj.

    ACL2 !>


Constrained Functions and Defattach

  Consider the following constrained function introduction.

    (encapsulate
      (((crn0 state) => *))
      (local (defun crn0 (state)
               (declare (xargs :stobjs state))
               (state-p state))))

  If we try to attach [47mrd0[0m (defined above) to [47mcrn0[0m we get an error, as
  shown just below.  In short, this error says that since [47mrd0[0m may
  lead to a call of [47mwith-global-stobj[0m that binds [47mst[0m, then with this
  attachment, [47mcrn0[0m may lead to such a call; yet there is no record in
  the [world] that [47mcrn0[0m may lead to such a call.

    ACL2 !>(defattach crn0 rd0)


    ACL2 Error in ( DEFATTACH CRN0 RD0):  The attachment of RD0 to CRN0
    restricts stobjs bound by WITH-GLOBAL-STOBJ under calls of RD0, according
    to the :GLOBAL-STOBJS keyword (default nil) in the signature introducing
    CRN0.  But this restriction is violated for stobj ST:  the attempt
    is to attach RD0, which makes a WITH-GLOBAL-STOBJ call that binds ST,
    yet that stobj is not specified by the :GLOBAL-STOBJS keyword of CRN0.
    See :DOC with-global-stobj.


    Summary
    Form:  ( DEFATTACH CRN0 RD0)
    Rules: NIL
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

    ACL2 Error [Failure] in ( DEFATTACH CRN0 RD0):  See :DOC failure.

    ******** FAILED ********
    ACL2 !>

  The solution is to note, in the signature of the constrained
  function, that it may lead to a [47mwith-global-stobj[0m call.  This is
  accomplished by using the keyword, [47m:GLOBAL-STOBJS[0m, in the signature
  of the function.  The value of that keyword is [47mnil[0m by default,
  indicating that there is no such call.  Otherwise the value is a
  cons of the form [47m(r . w)[0m, where [47mr[0m and [47mw[0m are disjoint lists of
  stobjs.  Their interpretation is as follows: [47mw[0m includes all stobjs
  for which an attachment may have an updating [47mwith-global-stobj[0m
  call, and [47mr[0m includes all stobjs not in [47mw[0m for which an attachment
  may have a [47mwith-global-stobj[0m call.  Consider the following
  modification of the [47m[encapsulate][0m form above.

    (encapsulate
      (((crn1 state) => * :global-stobjs ((st) . nil)))
      (local (defun crn1 (state)
               (declare (xargs :stobjs state))
               (state-p state))))

  Then the form [47m(defattach crn1 rd0)[0m is legal: unlike [47mcrn0[0m, [47mcrn1[0m has
  specified that [47mst[0m may be bound by [47mwith-global-stobj[0m in an
  attachment.

  The requirement is thus as follows.  Consider attachment of [47mg[0m to a
  constrained function [47mf[0m, where [47mg[0m may lead to updating
  [47mwith-global-stobj[0m calls that bind stobjs [47mw1[0m, [47mw2[0m, ..., [47mwk[0m, and also
  [47mg[0m may lead to [47mwith-global-stobj[0m calls that bind, in addition to the
  [47mwi[0m, stobjs [47mr1[0m, [47mr2[0m, ..., [47mrn[0m.  Then the signature of [47mf[0m must specify a
  value [47m(r . w)[0m for the keyword [47m:GLOBAL-STOBJS[0m, where [47mr[0m and [47mw[0m are
  lists of stobjs such that: [47mw[0m includes all [47mwi[0m, and the union of [47mr[0m
  and [47mw[0m includes all [47mri[0m.")
 (WITH-GUARD-CHECKING
  (GUARD ACL2-BUILT-INS)
  "Suppress or enable guard-checking for a form

    Example:

    ; Turn off all guard-checking for the indicated calls of append and car:
    (with-guard-checking :none
                         (append 3 4))

    General Form:
    (with-guard-checking val form)

  where [47mval[0m evaluates to a legal [guard]-checking value (see
  [set-guard-checking], or evaluate [47m*guard-checking-values*[0m to see
  the list of such values), and [47mform[0m is a form that does not mention
  [47m[state][0m (unless there is an active trust tag, in which case mention
  of [47mstate[0m can be unsound; see below).  See
  [with-guard-checking-error-triple] and [with-guard-checking-event]
  for analogous utilities to be used with forms that return
  [error-triple]s.  [47mForm[0m is to be evaluated in a scope such that, in
  essence, [47m(set-guard-checking val)[0m is first executed locally in that
  scope.  However, this guard-checking setting is ignored once
  evaluation passes into raw Lisp functions (see
  [guards-and-evaluation]).

  Note that the addition of [47mwith-guard-checking[0m does not change the
  proof obligations generated for guard verification.  However,
  [47m[ec-call][0m can be used in order to eliminate those proof
  obligations.  Consider the following example.

    (defun f1 (x)
      (declare (xargs :guard t))
      (with-guard-checking nil (ec-call (nth t x))))

  Then guard verification succeeds, and evaluation of the form [47m(f1 '(1
  2 3))[0m will return [47m1[0m, without causing a guard violation.  However,
  if [47mec-call[0m is instead removed from this definition, then guard
  verification will fail, and for good reason, as illustrated by the
  following example.

    (defun f2 (x)
      (declare (xargs :guard t))
      (with-guard-checking nil (nth t x)))

    (defun f3 (x)
      (declare (xargs :guard t))
      (f2 x))

  Suppose guard verification were to succeed for [47mf2[0m.  Then of course it
  would also succeed for [47mf3[0m.  But the call [47m(f3 nil)[0m would then cause
  a raw Lisp error (at least in many host Lisps), because it would
  lead to a raw-Lisp call of [47mnth[0m whose first argument is not a
  number.

  The remainder of this topic provides a remark for advanced users.
  [47mWith-guard-checking[0m is implemented using [47m[return-last][0m, which you
  can in principle call directly; use [47m:[0m[47m[trans][0m or [47m:[0m[47m[trans1][0m to see
  how a call of [47mwith-guard-checking[0m expands to a corresponding call
  of [47mreturn-last[0m.  However, ACL2 enforces a couple of checks that can
  only be circumvented if there is an active trust tag.  The
  following example from Jared Davis shows why those checks are
  required (in particular, it shows how circumventing them with a
  trust tag can be unsound).  We start by defining our own version of
  the utility, which omits the check that the form has no occurrences
  of [47mstate[0m.

    (defmacro my-with-guard-checking (val form)
      `(with-guard-checking1 (chk-with-guard-checking-arg ,val)
                             ,form))

  Submitting the following event results in the error shown just below
  it.

    (defun foo (state)
      (declare (xargs :stobjs state
                      :guard (f-boundp-global 'guard-checking-on state)))
      (my-with-guard-checking :all (f-get-global 'guard-checking-on state)))

    ACL2 Error in ( DEFUN FOO ...):  The form
    (RETURN-LAST 'WITH-GUARD-CHECKING1-RAW
                 (CHK-WITH-GUARD-CHECKING-ARG :ALL)
                 (F-GET-GLOBAL 'GUARD-CHECKING-ON STATE))
    is essentially a call of WITH-GUARD-CHECKING, but without certain checks
    performed.  This is illegal unless there is an active trust tag; see
    :DOC defttag.  To avoid this error without use of a trust tag, call
    WITH-GUARD-CHECKING directly.  Note:  this error occurred in the context
    (WITH-GUARD-CHECKING1 (CHK-WITH-GUARD-CHECKING-ARG :ALL)
                          (F-GET-GLOBAL 'GUARD-CHECKING-ON
                                        STATE)).

  But if we first evaluate [47m(defttag t)[0m, then the [47m[defun][0m event above is
  admitted, and we can subsequently prove something that is not true.

    (thm (equal (foo state)
                (f-get-global 'guard-checking-on state)))

    (assert-event (not (equal (foo state)
                              (f-get-global 'guard-checking-on state))))")
 (WITH-GUARD-CHECKING-ERROR-TRIPLE
  (GUARD ACL2-BUILT-INS)
  "Suppress or enable guard-checking for a form

  See documentation on the closely related utility,
  [with-guard-checking], for relevant background.

    Example:

    ; Turn off all guard-checking for the indicated calls of append and car:
    (with-guard-checking-error-triple :none
                                       (value (append 3 4)))

    General Form:
    (with-guard-checking-error-triple val form)

  where [47mval[0m evaluates to a legal guard-checking value (see
  [set-guard-checking], or evaluate [47m*guard-checking-values*[0m to see
  the list of such values), and [47mform[0m is a form that returns an error
  triple, [47m(mv erp val state)[0m; see [error-triple].  Thus,
  [47mwith-guard-checking-error-triple[0m is much like
  [47m[with-guard-checking][0m, but the former is to be used if [47mform[0m
  mentions the ACL2 [state]; indeed, [47mwith-guard-checking-error-triple[0m
  requires [47mform[0m to evaluate to an error triple.  As with
  [47mwith-guard-checking[0m, [47mform[0m is evaluated in a context where
  guard-checking has been set to the value of [47mval[0m, but this
  guard-checking setting is ignored once evaluation passes into raw
  Lisp functions (see [guards-and-evaluation]).

  Also see [with-guard-checking-event] for a similar utility to be used
  for creating [events], specifically, [embedded-event-form]s.")
 (WITH-GUARD-CHECKING-EVENT
  (GUARD ACL2-BUILT-INS)
  "Suppress or enable guard-checking for an event form

  See documentation on the closely related utility,
  [with-guard-checking], for relevant background.

    General Forms:
    (with-guard-checking-event val form)
    (with-guard-checking-event (quote val) form)

  where [47mval[0m is a legal guard-checking value (see [set-guard-checking],
  or evaluate [47m*guard-checking-values*[0m to see the list of such
  values), and [47mform[0m is a form that returns an [error-triple], [47m(mv erp
  val state)[0m.  This macro is identical to
  [47m[with-guard-checking-error-triple][0m, except that the first argument
  of a call of [47mwith-guard-checking-event[0m must be a constant as
  described above, and it will generate a legal event form
  [embedded-event-form].  For example, the following (uninteresting)
  form may be placed in a book.

    (with-guard-checking-event
     :none
     (make-event (prog2$ (car 3) '(defun f (x) x))))

  In raw Lisp, [47m(with-guard-checking-event x y)[0m macroexpands to [47my[0m; thus,
  wrapping an event with [47mwith-guard-checking-event[0m has effect only
  inside the ACL2 read-eval-print loop.  Because of that behavior,
  calls of [47mwith-guard-checking-event[0m must not be used in function
  definitions; use [47m[with-guard-checking-error-triple][0m in such cases.")
 (WITH-LIVE-STATE
  (PROGRAMMING-WITH-STATE ACL2-BUILT-INS)
  "Allow a reference to [47mstate[0m in raw Lisp

  The macro [47mwith-live-state[0m is an advanced feature that very few users
  will need (basically, only system hackers).  Indeed, it is
  essentially [untouchable], defined with [47m[defmacro-untouchable][0m;
  [remove-untouchable] for how to enable calling [47mwith-live-state[0m in
  the ACL2 loop.

    Example Form:
    (with-live-state (assign y 3))

    General form:
    (with-live-state form)

  where form is an arbitrary form with a free reference to the variable
  [47m[state][0m.

  Logically, [47m(with-live-state FORM)[0m macroexpands to [47mFORM[0m.  However, in
  raw Lisp it expands to:

    (let ((state *the-live-state*))
      FORM)

  If a form that mentions the variable [47m[state][0m might be executed in raw
  Lisp --- that is, either outside the ACL2 loop or in raw mode (see
  [set-raw-mode]) --- then the surrounding the form with
  [47mwith-live-state[0m as shown above can avoid potential warnings or
  (much less likely) errors.  Note however that if [47mstate[0m is lexically
  bound to a state other than the usual ``live'' state, surprising
  behavior may occur when evaluating a call of [47mwith-live-state[0m in raw
  Lisp or raw mode (either directly by evaluation or at compile
  time), because [47mwith-live-state[0m will override that lexical binding
  of [47m[state][0m by a lexical binding of [47mstate[0m to the usual ``live''
  state.")
 (WITH-LOCAL-STATE
  (STOBJ ACL2-BUILT-INS)
  "Locally bind state

  This is an advanced topic, probably of interest only to system
  developers.

  Consider the following example form:

    (with-local-state
     (mv-let (result state)
             (compute-with-state x state)
             result))

  This is equivalent to the following form.

    (with-local-stobj
     state
     (mv-let (result state)
             (compute-with-state x state)
             result))

  By default, this form is illegal, because ACL2 does not have a way to
  unwind all changes to the ACL2 [state]; we say more on this issue
  below.  There may however be situations where you are willing to
  manage or overlook this issue.  In that case you may execute the
  following form to enable the use of [47mwith-local-state[0m, by enabling
  the use of [47m[with-local-stobj][0m on [47mstate[0m; but note that it requires
  an active trust tag (see [defttag]).

    (remove-untouchable create-state t)

  Please be aware that no local [state] is actually created, however!
  In particular, users of [47mwith-local-state[0m need either to ensure that
  channels are closed and state global variables are returned to
  their original values, or else be willing to live with changes made
  to state that are not justified by the code that has been
  evaluated.  You are welcome to look in the ACL2 source code at the
  definition of macro [47mchannel-to-string[0m, which employs
  [47mwith-local-state[0m to create a local [state] for the purpose of
  creating a string.

  Here is an example use of [47mwith-local-state[0m.  Notice the use of
  [47m[defttag][0m --- and indeed, please understand that we are just
  hacking here, and in general it takes significant effort to be sure
  that one is using [47mwith-local-state[0m correctly!

    (defttag t)

    (remove-untouchable create-state t)

    (set-state-ok t)

    (defun foo (state)
      (declare (xargs :mode :program))
      (mv-let
       (channel state)
       (open-input-channel \"my-file\" :object state)
       (mv-let (eofp obj state)
               (read-object channel state)
               (declare (ignore eofp))
               (let ((state (close-input-channel channel state)))
                 (mv obj state)))))

    (defun bar ()
      (declare (xargs :mode :program))
      (with-local-state (mv-let (result state)
                                (foo state)
                                result)))

    ; Multiple-value return version:

    (defun foo2 (state)
      (declare (xargs :mode :program))
      (mv-let
       (channel state)
       (open-input-channel \"my-file\" :object state)
       (mv-let (eofp obj state)
               (read-object channel state)
               (let ((state (close-input-channel channel state)))
                 (mv eofp obj state)))))

    (defun bar2 ()
      (declare (xargs :mode :program))
      (with-local-state (mv-let (eofp result state)
                                (foo2 state)
                                (mv eofp result))))

  Note for ACL2(p) users: When [parallel-execution] is enabled,
  invocations of [47mwith-local-state[0m are surrounded by a lock.")
 (WITH-LOCAL-STOBJ
  (STOBJ ACL2-BUILT-INS)
  "Locally bind a single-threaded object

  See [stobj] for an introduction to single-threaded objects.  Also see
  [defstobj] for additional background.

    Example Form:
    (with-local-stobj
     st
     (mv-let (result st)
             (compute-with-st x st)
             result))

  [47mWith-local-stobj[0m can be thought of as a macro, where the example form
  above expands as follows.

    (mv-let (result st)
            (let ((st (create-st)))
              (compute-with-st x st))
            (declare (ignore st))
            result)

  However, ACL2 expects you to use [47mwith-local-stobj[0m, not its expansion.
  More precisely, stobj creator functions are only allowed via
  [47mwith-local-stobj[0m or in logic-only situations (like theorems and
  hints).  Moreover, neither [47mwith-local-stobj[0m nor its expansions are
  legal when typed directly at the top-level loop.  See [top-level]
  for a way to use [47mwith-local-stobj[0m in the top-level loop.

    General Forms:
    (with-local-stobj stobj-name mv-let-form)
    (with-local-stobj stobj-name mv-let-form creator-name)

  where [47mstobj-name[0m is the name of a [stobj], [47mmv-let-form[0m is a call of
  [47m[mv-let][0m that binds [47mstobj-name[0m but does not return [47mstobj-name[0m ---
  in fact, if [47mmv-let-form[0m is [47m(mv-let (...)  ... body)[0m, then [47mbody[0m does
  not even reference [47mstobj-name[0m --- and if [47mcreator-name[0m is supplied
  then it should be the name of the creator function for [47mstobj-name[0m.
  For the example form above, its expansion would use [47mcreator-name[0m,
  if supplied, in place of [47mcreate-st[0m.  Note that [47mstobj-name[0m must not
  be [47m[state][0m (the ACL2 state), except in special situations probably
  of interest only to system developers; see [with-local-state].

  Note that if a stobj [47mST[0m is bound upon beginning evaluation of a form
  [47m(with-local-stobj ST ...)[0m, then the value of [47mST[0m is the same
  immediately before evaluating that form as it is immediately after
  that evaluation.  In other words, only a local version of [47mST[0m is
  modified inside that [47mwith-local-stobj[0m form.

  [47mWith-local-stobj[0m can be useful when a stobj is used to memoize
  intermediate results during a computation, yet it is desired not to
  make the [47mstobj[0m a formal parameter for the function and its callers.

  ACL2 can reason about these ``local stobjs,'' and in particular about
  stobj creator functions.  For technical reasons, ACL2 will not
  allow you to enable the [47m:EXECUTABLE-COUNTERPART[0m [rune] of a stobj
  creator function.

  Finally, here is a small example concocted in order to illustrate
  that [47mwith-local-stobj[0m calls can be nested.

    (defstobj st fld1)

    (defun foo ()
      (with-local-stobj
       st ; Let us call this the ``outer binding of st''.
       (mv-let (val10 val20 st)
         (let ((st (update-fld1 10 st)))
           ;; At this point the outer binding of st has fld1 = 10.
           (let ((result (with-local-stobj
                          st ; Let us call this the ``inner binding of st''.
                          (mv-let (val st)
                            (let ((st (update-fld1 20 st)))
                              ;; Now fld1 = 20 for the inner binding of st.
                              (mv (fld1 st) st))
                            val))))
             ;; So result has been bound to 20 above, but here we are once again
             ;; looking at the outer binding of st, where fld1 is still 10.
             (mv (fld1 st) result st)))
         (mv val10 val20))))

    (thm (equal (foo) (mv 10 20))) ; succeeds")
 (WITH-OUTPUT
  (OUTPUT-CONTROLS)
  "Suppressing or turning on specified output for an event

  The macro [47mwith-output[0m can be used to control ACL2 output.  It can be
  wrapped around an event to create a new event; see
  [embedded-event-form].  The macro [47mwith-output![0m is identical except
  that it does not create an event and, unlike [47mwith-output[0m, it can be
  called in code.


Examples

    ; Turn off all controllable output during evaluation of the indicated thm form.
    (with-output
     :off :all
     :gag-mode nil
     :inhibit-er-hard t
     (thm (equal (app (app x y) z) (app x (app y z)))))

    ; Equivalent to the example just above.
    (with-output
     :off :all!
     (thm (equal (app (app x y) z) (app x (app y z)))))

    ; Prove the indicated theorem with the event summary turned off and
    ; using the :goals setting for gag-mode.
    (with-output
       :off summary
       :gag-mode :goals
       (defthm app-assoc (equal (app (app x y) z) (app x (app y z)))))

    ; Same effect as just above:
    (with-output
       :on summary
       :summary-off :all
       :gag-mode :goals
       (defthm app-assoc (equal (app (app x y) z) (app x (app y z)))))

    ; Turn off all but the ``time'' and ``rules'' parts of the summary.
    (with-output
       :on summary
       :summary-off (:other-than time rules)
       :gag-mode :goals ; default: use gag-mode, with goal names printed
       (defthm app-assoc (equal (app (app x y) z) (app x (app y z)))))

    ; Same as specifying :off :all!, but with output types made explicit
    ; (that is, using the value of constant *valid-output-names*):
    (with-output
     :off (error warning warning! observation prove proof-builder event history
                 summary proof-tree)
     :gag-mode nil
     (thm (equal (app (app x y) z) (app x (app y z)))))

    ; Same as above, but :stack :push says to save the current
    ; inhibit-output-lst, which can be restored in a subsidiary with-output call
    ; that specifies :stack :pop.
    (with-output
     :stack :push
     :off :all
     :gag-mode nil
     (thm (equal (app (app x y) z) (app x (app y z)))))

    ; Abbreviate printing in gag-mode for guard goals and induction schemes, but
    ; defeat abbreviated printing (if any) for terms.
    (with-output
     :evisc (:gag-mode (evisc-tuple 3 4 nil nil)
             :term nil)
     (defun h (x)
       (declare (xargs :guard t))
       (append (cons (make-list 10) x) x)))

    ; The following use of :ctx causes the error message to start with
    ; ``ACL2 Error in MY-CUSTOM-CTX'' instead of
    ; ``ACL2 Error in ( DEFUN FOO ...)''.
    (with-output
     :ctx 'my-custom-ctx
     (defun foo (x) y))


General Form

    (with-output :key1 val1 ... :keyk valk form)

  where [47mform[0m should evaluate to an [error-triple].  That evaluation
  takes place with output that is according to the values [47mvali[0m of the
  keywords, [47m:keyi[0m, as described below.  When the scope of [47mwith-output[0m
  is exited, then all modifications are undone, including the states
  of output and summary inhibition, [47m[gag-mode][0m, and [evisc-tuple]s.
  Each keyword may occur at most once.

  Use of the argument [47m:off :all![0m is treated exactly the same as using
  arguments [47m:off :all :gag-mode nil[0m.  We assume below that any use of
  [47m:off :all![0m has been expanded away in that manner.


On-off specs

  Before discussing the keywords we introduce the notion of ``on-off
  specs'', which are the legal values of the keywords [47m:on[0m, [47m:off[0m,
  [47m:summary-on[0m, and [47m:summary-off[0m.  (As noted above, we ignore [47m:off
  :all![0m below, as it is just an abbreviation for [47m:off :all :gag-mode
  nil[0m.)  An on-off spec has one of the following forms, where each
  [47msymi[0m is a symbol, and subject to restrictions discussed below

    * [47m:all[0m

    * [47msym[0m ; a symbol that is not [47m:all[0m

    * [47m(sym1 ... symk)[0m

    * [47m(:other-than sym1 ... symk)[0m

  The set of ``associated valid symbols'' is defined as follows.  For
  [47m:off[0m or [47m:on[0m, these symbols are the [3moutput types[0m that can be
  inhibited --- that is, members of the list stored in the constant
  [47m*valid-output-names*[0m, which is the list [47m(proof-tree error warning!
  warning observation prove event summary proof-builder comment
  history)[0m --- and they are treated as in [47m[set-inhibit-output-lst][0m.
  Similarly, for [47m:summary-on[0m or [47m:summary-off[0m, these are the [3msummary
  types[0m: the parts of the [summary] that can be inhibited as in
  [47m[set-inhibited-summary-types][0m, that is, members of the list stored
  in the constant [47m*summary-types*[0m, which is the list [47m(errors form
  header hint-events redundant rules splitter-rules steps
  system-attachments time value warnings)[0m.  An on-off spec consisting
  of associated valid symbols, [47m(sym1 ... symk)[0m, indicates the set of
  symbols, [47m{sym1,...,symk}[0m.  The other legal forms of on-off spec and
  their meanings are as follows: [47m:all[0m represents the set of all
  associated valid symbols, any other symbol [47msym[0m abbreviates [47m(sym)[0m,
  and [47m(:other-than sym1 ... symk)[0m represents the set of associated
  valid symbols that are not in the list [47m(sym1 ... symk)[0m.

  Note that these two notions of ``associated valid symbols'' --- the
  [3moutput types[0m controlled by keywords [47m:on[0m and [47m:off[0m, and the [3msummary
  types[0m controlled by keywords [47m:summary-on[0m and [47m:summary-off[0m ---
  operate independently in the following sense.  The keywords [47m:on[0m and
  [47m:off[0m control output types from the list [47m*valid-output-names*[0m
  displayed above, one of whose members is [47mSUMMARY[0m.  The keywords
  [47m:summary-on[0m and [47m:summary-off[0m control summary types from the list
  [47m*summary-types*[0m displayed above, indicating which types of summary
  are to be printed in the case that [47mSUMMARY[0m is among the output
  types that are on.  This summary control persists even as the
  [47mSUMMARY[0m type changes state between off and on.  Consider the
  following example.

    (with-output :off (summary)
     (with-output :summary-off (time)
      (with-output :on (summary)
       (thm (equal (car (append x y)) (if (consp x) (car x) (car y)))))))

  The resulting output does not include [47mTIME[0m output in the summary.
  The reason is that the second [47mwith-output[0m form specifies that [47mTIME[0m
  summary output is off; then when the third (innermost) output turns
  [47mSUMMARY[0m output on, still, the [47mTIME[0m summary output is off, so the
  [47mTHM[0m call does not print the [47mTIME[0m part of the summary output.  Note
  that the same reasoning applies if the third [47mwith-output[0m call above
  specifies [47m:on :all[0m instead of [47m:on (summary)[0m; that case also
  produces no time output in the summary.  That is, the use of [47m:on
  :all[0m specifies which output types are on, but does not affect which
  summary types are on; again, output types and summary types are
  controlled independently by the respective pairs [47m:on/:off[0m and
  [47m:summary-on/:summary-off[0m.


Keyword arguments

  We turn now to a discussion of the keyword arguments.

  [47m:on[0m, [47m:off[0m

  The values for these keywords, which are not evaluated, must be
  on-off specs for these keywords (as discussed above).  If [47m:on :all[0m
  is specified, then then every output type is turned on except for
  those in the set specified by the value of [47m:off[0m.  Otherwise, if
  [47m:off :all[0m is specified, then every output type is inhibited except
  as specified by the value of [47m:on[0m.  Otherwise [47m:all[0m is not specified
  for either [47m:on[0m or [47m:off[0m, and the currently-inhibited output types
  are reduced as specified by the value of [47m:on[0m and then extended as
  specified by the value of [47m:off[0m.

  [47m:summary-on[0m, [47m:summary-off[0m

  The values for these keywords, which are not evaluated, must be
  on-off specs for these keywords.  They are interpreted exactly as
  are the values for [47m:on[0m and [47m:off[0m as described above, except that
  instead of output types they are interpreted with respect to the
  summary types (i.e., in the terminology introduced above, with
  respect to the set of associated valid symbols for [47m:summary-on[0m and
  [47m:summary-off[0m).

  [47m:gag-mode[0m

  The value should evaluate to one of the legal values for
  [47m[set-gag-mode][0m.  The effect is as though [47mset-gag-mode[0m has been
  called with this argument, before modifying how output is
  inhibited, at the start of evaluating the given form.

  [47m:evisc[0m

  The value should evaluate to a [47m[keyword-value-listp][0m, where each key
  is a legal keyword for the [47m:sites[0m keyword argument of
  [47m[set-evisc-tuple][0m other than [47m:trace[0m and [47m:brr[0m (that is, a member of
  the list [47m(:term :ld :abbrev :gag-mode)[0m), and each value evaluates
  to a legal [evisc-tuple] for that keyword.  The effect is as though
  [47mset-evisc-tuple[0m has been called, before modifying how output is
  inhibited, with this argument at the start of evaluating the given
  form.

  [47m:ctx[0m

  The value should evaluate to a context --- see [ctx] --- that will
  generally be used throughout evaluation of the given form, in place
  of the usual event context (including the [47m\"Form\"[0m field of the
  [summary]).

  [47m:stack[0m

  The value, which is not evaluated, must be [47m:push[0m or [47m:pop[0m.  The effect
  of [47m:push[0m is essentially to create a new environment for inferior
  calls of [47mwith-output[0m that can be reverted (popped) by inferior
  calls of [47mwith-output[0m, as discussed in the next section.  Note that
  the handling of the [47m:stack[0m argument pays no attention to the
  [47m:summary-on[0m or [47m:summary-off[0m arguments.

  [47m:inhibit-er-hard[0m

  By default, ACL2 prints messages for hard errors --- errors whose
  message starts with ``HARD ACL2 ERROR'' --- even when [47merror[0m output
  is inhibited (whether by using the keyword, [47m:off[0m, or by calling
  [47m[set-inhibit-output-lst][0m).  This behavior holds when [state] global
  [47minhibit-er-hard[0m has its default value of [47mnil[0m; see
  [set-inhibit-output-lst].  When keyword [47m:inhibit-er-hard[0m is
  supplied an expression, the value [47mv[0m of that expression overrides
  the global value of [47minhibit-er-hard[0m: thus when error output is
  inhibited, hard error messages are printed if [47mv[0m is [47mnil[0m and they are
  not printed if [47mv[0m is not [47mnil[0m.  Note that this behavior automatically
  takes place when [47mwith-output[0m is supplied the arguments [47m:off :all![0m,
  but not [47m:off :all[0m.


More about the [47mstack[0m argument

  The [47m:stack[0m keyword's effect is illustrated by the following example,
  where ``[47m(encapsulate nil)[0m'' may replaced by ``[47m(progn[0m'' without any
  change to the output that is printed.

    (with-output
     :stack :push :off :all
     (encapsulate ()
       (defun f1 (x) x)
       (with-output :stack :pop (defun f2 (x) x))
       (defun f3 (x) x)
       (with-output :stack :pop :off warning (in-theory nil))
       (defun f4 (x) x)))

  The outer [47mwith-output[0m call saves the current output settings (as may
  have been modified by earlier calls of [47m[set-inhibit-output-lst][0m),
  by pushing them onto a stack, and then turns off all output.  Each
  inner [47mwith-output[0m call temporarily pops that stack, restoring the
  starting output settings, until it completes and undoes the effects
  of that pop.  Unless [47mevent[0m output was inhibited at the top level
  (see [set-inhibit-output-lst]), the following output is shown:

    Since F2 is non-recursive, its admission is trivial.  We observe that
    the type of F2 is described by the theorem (EQUAL (F2 X) X).

  And then, if [47msummary[0m output was not inhibited at the top level, we
  get the rest of this output:

    Summary
    Form:  ( DEFUN F2 ...)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

    Summary
    Form:  ( IN-THEORY NIL)
    Rules: NIL
    Warnings:  None
    Time:  0.00 seconds (prove: 0.00, print: 0.00, other: 0.00)

  Note that the use of [47m:off warning[0m suppresses a [47m\"Theory\"[0m warning for
  the [47m(in-theory nil)[0m event, and that in no case will output be
  printed for definitions of [47mf1[0m, [47mf3[0m, or [47mf4[0m, or for the [47m[encapsulate][0m
  event itself.

  The following more detailed explanation of [47m:stack[0m is intended only
  for advanced users.  After [47m:gag-mode[0m and [47m:evisc[0m are handled (if
  present) but before [47m:on[0m or [47m:off[0m is handled, the value of [47m:stack[0m is
  handled as follows.  If the value is [47m:push[0m, then [state] global
  [47minhibit-output-lst-stack[0m is modified by pushing the cons of the
  values of [state] globals [47minhibit-output-lst[0m and [47mgag-mode[0m onto the
  value of [state] global [47minhibit-output-lst-stack[0m, which is [47mnil[0m at
  the top level.  If the value is [47m:pop[0m, then [state] global
  [47minhibit-output-lst-stack[0m is modified only if non-[47mnil[0m, in which case
  its top element is popped and provides the values of [state]
  globals [47minhibit-output-lst[0m and [47mgag-mode[0m.


Concluding remarks

  [47mWith-output[0m has no effect in raw Lisp, in the sense that a call
  [47m(with-output ... form)[0m macroexpands to [47mform[0m in raw Lisp.  Normally
  this produces desired behavior, but occasionally you may be a bit
  surprised.  Consider for example the following book.

    (in-package \"ACL2\")

    (with-output
      :off :all
      (make-event (prog2$ (cw \"@@@ NOISE @@@\")
                          '(defun f (x) x))
                  :check-expansion t))

    (make-event (with-output!
                  :off :all
                  (value (prog2$ (cw \"@@@ QUIET @@@\")
                                 '(defun g (x) x))))
                :check-expansion t)

  When certifying this book, we do not see either `[47mNOISE[0m' or `[47mQUIET[0m'.
  But then when we include this book, we see `[47mNOISE[0m' (but not
  `[47mQUIET[0m').  To see why, we first note that both events are evaluated
  in raw Lisp when including the book (as discussed briefly in the
  documentation topic, [book-compiled-file]).  The first calls
  [47mwith-output[0m, which (as noted above) disappears during
  macroexpansion.  The second calls [47mwith-output![0m, which has the
  desired effect of suppressing output.")
 (WITH-OUTPUT! (POINTERS)
               "See [with-output].")
 (WITH-OUTPUT-LOCK
  (PARALLEL-PROGRAMMING ACL2-BUILT-INS)
  "Provides a mutual-exclusion mechanism for performing output in
  parallel

  This documentation topic relates to an experimental extension of
  ACL2, ACL2(p), created initially by David L. Rager.  See
  [compiling-ACL2p] for how to build an executable image that
  supports parallel execution.  Also see community books directory
  [47mbooks/parallel/[0m for examples.

  One may wish to perform output while executing code in parallel.  If
  threads are allowed to print concurrently, the output will be
  interleaved and often unreadable.  To avoid this, the user can
  surround forms that perform output with the [47mwith-output-lock[0m macro.
  Warning: [47mwith-output-lock[0m may not perform as expected when called
  directly in the loop; see [parallelism-at-the-top-level].

  Take the following definition of [47mpfib[0m as an example.

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

  With [parallel-execution] enabled, a call of [47m(pfib 5)[0mresults in
  non-deterministically interleaved output, for example as follows.

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

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

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

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

    <snip>

    ACL2 !>(pfib 5)
    Computing pfib 4
    Computing pfib 3
    Computing pfib 3
    Computing pfib 2
    Computing pfib 2
    Computing pfib 1
    Computing pfib 2
    Computing pfib 1
    Computing pfib 1
    Computing pfib 0
    Computing pfib 1
    Computing pfib 0
    Computing pfib 1
    Computing pfib 0
    5
    ACL2 !>")
 (WITH-PROVER-STEP-LIMIT
  (MISCELLANEOUS)
  "Limit the number of steps for proofs

  Logically, [47m(with-prover-step-limit expr form)[0m is equivalent to [47mform[0m,
  except that if the number of ``prover steps'' executed during
  evaluation of [47mform[0m exceeds a bound specified by the value of [47mexpr[0m,
  then that proof will abort.  See [set-prover-step-limit] for a
  related utility that sets the limit on prover steps globally
  instead of setting it for just one form, and for a discussion of
  the notion of ``prover steps'', which could change in future ACL2
  releases.  For a related utility based on time instead of prover
  steps, see [with-prover-time-limit]; but as discussed in the
  [documentation] for [47m[set-prover-step-limit][0m, there is at best a
  loose connection between the counting of steps and
  [47m[with-prover-time-limit][0m.

  The arguments of [47m(with-prover-step-limit expr form)[0m are evaluated.
  However, the (optional) argument [47mflg[0m is not evaluated in
  [47m(with-prover-step-limit expr flg form)[0m.

  Depending on the machine you are using, you may have less than a
  half-hour of time before the number of prover steps exceeds the
  maximum limit on prover steps that may be imposed, which is one
  less than the value of [47m*default-step-limit*[0m.  But there is no limit
  unless you explicitly call [47mwith-prover-step-limit[0m or
  [47m[set-prover-step-limit][0m.

  For examples of how step-limits work besides those presented below,
  see the community book [47mbooks/misc/misc2/step-limits.lisp[0m.

  For a utility that returns an indicator of the number of prover steps
  most recently taken, see [last-prover-steps].

  Note that [47mwith-prover-step-limit[0m may not be called inside
  definitions, and that it is simply the identity macro in raw Lisp.
  However, [47mwith-prover-step-limit![0m may be called in place of
  [47mwith-prover-step-limit[0m, with the effect described here even in raw
  Lisp.

    Examples:

    ; Limit (mini-proveall) to 100,000 prover steps (which happens to suffice)
    (with-prover-step-limit 100000 (mini-proveall))

    ; Same as above for the inner call of with-prover-step-limit; so the
    ; mini-proveall call completes, but then we get an error because the second
    ; argument of the outer with-prover-step-limit call took more than 200
    ; steps.
    (with-prover-step-limit
     200
     (with-prover-step-limit 100000 (mini-proveall)))

    ; Same as preceding form just above, except that this time there is no error,
    ; because the inner call of with-prover-step-limit has an extra argument
    ; of t inserted into the second argument position, which specifies that this
    ; entire inner call is treated as though it uses no prover steps.
    (with-prover-step-limit
     200
     (with-prover-step-limit 100000 t (mini-proveall)))

    ; The inner call limits (mini-proveall) to 200 prover steps, which fails
    ; almost immediately.
    (with-prover-step-limit 100000 (with-prover-step-limit 200 (mini-proveall)))

    ; Do not limit the number of prover steps, regardless of such a limit imposed
    ; globally or by the surrounding context.
    (with-prover-step-limit nil (mini-proveall))

    ; Same as just above (indeed, nil above is converted to
    ; *default-step-limit*):
    (with-prover-step-limit *default-step-limit* (mini-proveall))

    ; Advanced example: Limit the indicated theorem to 100 steps, and when the
    ; proof does not complete, then put down a label instead.
    (mv-let (erp val state)
            (with-prover-step-limit
             100
             (thm (equal (append (append x x) x)
                         (append x x x))))
            (if erp
                (deflabel foo :doc \"Attempt failed.\")
              (value (list :succeeded-with val))))

    ; Use extra argument of t to avoid ``charging'' steps for the indicated
    ; form.
    (with-prover-step-limit
     500
     (encapsulate
      ()
      (with-prover-step-limit
       500
       t ; Don't charge prover steps for this first defthm.
       (defthm test1
         (equal (append x (append y z))
                (append (append x y) z))
         :rule-classes nil))
      (defthm test2
        (equal (append x (append y z))
               (append (append x y) z))
        :rule-classes nil)))

    General Forms:
    (with-prover-step-limit expr form)
    (with-prover-step-limit expr flg form)

  where [47mform[0m is an arbitrary form to evaluate, and [47mexpr[0m evaluates to
  one of the following: [47mnil[0m; a natural number not exceeding the value
  of [47m*default-step-limit*[0m; or the special value, [47m:START[0m.  The
  optional extra argument in the second position, [47mflg[0m, must be
  Boolean if supplied.

  If the value of [47mexpr[0m is a natural number less than the value of
  [47m*default-step-limit*[0m, then that value is the maximum number of
  prover steps permitted during evaluation of [47mform[0m before an error
  occurs.  If however the value of [47mexpr[0m is [47mnil[0m or is the value of
  [47m*default-step-limit*[0m, then no limit is placed on the number of
  prover steps during processing of [47mform[0m.  Otherwise, the value of
  [47mexpr[0m should be the keyword [47m:START[0m, which is intended for use by the
  ACL2 implementation and may have semantics that change with new
  ACL2 versions.

  Finally we describe the optional extra Boolean argument, [47mflg[0m.  If [47mflg[0m
  is [47mnil[0m or omitted, then a running count of prover steps is
  maintained after [47mform[0m is evaluated; otherwise, that count is not
  affected by evaluation of [47mform[0m.  To see how this works when [47mflg[0m is
  nil or omitted, consider an event of shape [47m(progn form1 form2)[0m,
  where we are tracking prover steps (say, because of a superior call
  of [47mwith-prover-step-limit[0m).  If [47mn[0m is the number of prover steps
  available when the [47m[progn][0m form is entered, and if [47ms[0m prover steps
  are executed while evaluating [47mform1[0m, then [47mn-s[0m steps are available
  for evaluation of [47mform2[0m provided [47ms[0m does not exceed [47mn[0m; otherwise, an
  error occurs.  In particular, this is the case if [47mform1[0m is an event
  [47m(with-prover-step-limit k form1')[0m.  However, if [47mform1[0m is an event
  [47m(with-prover-step-limit k t form1')[0m, then because of the extra
  argument of [47mt[0m, no steps are ``charged'' to [47mform[0m; that is, all [47mn[0m
  steps, rather than [47mn-s[0m steps, are available for evaluation of
  [47mform2[0m.


Subtopics

  [Last-prover-steps]
      The number of prover steps most recently taken")
 (WITH-PROVER-STEP-LIMIT! (POINTERS)
                          "See [with-prover-step-limit].")
 (WITH-PROVER-TIME-LIMIT
  (MISCELLANEOUS)
  "Limit the time for proofs

    Examples:

    ; Limit (mini-proveall) to about 1/4 second:
    (with-prover-time-limit 1/4 (mini-proveall))

    ; Limit (mini-proveall) to about 1/4 second, even if surrounding call of
    ; with-prover-time-limit provides for a more restrictive bound:
    (with-prover-time-limit '(1/4) (mini-proveall))

    ; Limit the indicated theorem to about 1/50 second, and if the proof does not
    ; complete or it fails, then put down a label instead.
    (mv-let (erp val state)
            (with-prover-time-limit
             1/50
             (thm (equal (append (append x x) x)
                         (append x x x))))
            (if erp
                (deflabel foo :doc \"Attempt failed.\")
              (value (list :succeeded-with val))))

    General Form:
    (with-prover-time-limit time form)

  where [47mtime[0m evaluates to a positive rational number or to a list
  containing such, and [47mform[0m is arbitrary.  Logically,
  [47m(with-prover-time-limit time form)[0m is equivalent to [47mform[0m.  However,
  if the time for evaluation of [47mform[0m exceeds the value specified by
  [47mtime[0m, and if ACL2 notices this fact during a proof, then that proof
  will abort, for example like this:

    ACL2 Error in ( DEFTHM PERM-REFLEXIVE ...):  Out of time in the rewriter.

  If there is already a surrounding call of [47mwith-prover-time-limit[0m that
  has set up an expiration time, the inner [47mwith-prover-time-limit[0m
  call is not allowed to push that time further into the future
  unless the inner time is specified as a list containing a rational,
  rather than as a rational.

  Note that by default, the time used is runtime (cpu time); to switch
  to realtime (elapsed time), see [get-internal-time].

  For a related utility based on prover steps instead of time, see
  [with-prover-step-limit]; also see [set-prover-step-limit].  Those
  utilities have the advantage of having platform-independent
  behavior, unlike time limits, which of course are generally less
  restrictive for faster processors.  But note that the prover steps
  counted need not correspond closely to prover time.  For other
  utilities that limit time, see [with-timeout] and
  [oracle-timelimit].

  Although [47mwith-prover-time-limit[0m behaves like an ACL2 function in the
  sense that it evaluates both its arguments, it is however actually
  a macro that behaves as follows.  (1) The value of its first (time
  limit) argument affects the evaluation of its second argument (by
  causing an error during that evaluation if the time for completion
  is insufficient).  (2) The second argument can return multiple
  values (see [mv]), which are then returned by the call of
  [47mwith-prover-time-limit[0m.  (3) Thus, there is not a fixed number of
  values returned by [47mwith-prover-time-limit[0m.

  If you find that the time limit appears to be implemented too
  loosely, it may be because the prover only checks the time elapsed
  at certain points during the proof process, for example at entry to
  the rewriter.  For example, if you write your own
  [47m[clause-processor][0m that does an expensive computation, the time is
  unlikely to be checked during its execution.  If however you find
  the time limit seems to be ignored even during ordinary prover
  operation, you are encouraged to email an example to the ACL2
  implementors with instructions on how to observe the undesirable
  behavior.  This information can perhaps be used to improve ACL2 by
  the insertion of more checks for expiration of the time limit.

  The rest of this documentation topic explains the rather subtle
  logical story, and is not necessary for understanding how to use
  [47mwith-prover-time-limit[0m.  The ACL2 [47m[state][0m object logically contains
  a field called the [47macl2-oracle[0m, which is an arbitrary true list of
  objects; see [47m[read-ACL2-oracle][0m.  Our claim is that every ACL2
  session makes sense for [31;1msome[0m value of [47macl2-oracle[0m in the initial
  [47mstate[0m for that session.  Logically, [47mwith-prover-time-limit[0m is a
  no-op, just returning its second value.  But under the hood, it
  provides a ``hint'' for the [47macl2-oracle[0m, so that (logically
  speaking) when its first element ([47m[car][0m) is consulted by ACL2's
  prover to see if the time limit has expired, it gets the ``right''
  answer (specifically, either nil if all is well or else a message
  to print if the time limit has expired).  Logically, the
  [47macl2-oracle[0m is then [47m[cdr][0m'ed --- that is, its first element is
  popped off --- so that future results from [47mread-acl2-oracle[0m are
  independent of the one just obtained.")
 (WITH-SERIALIZE-CHARACTER
  (SERIALIZE ACL2-BUILT-INS)
  "Control output mode for [47mprint-object$[0m

  See [serialize] for a discussion of ``serialization'' routines,
  contributed by Jared Davis for saving ACL2 objects in files for
  later loading.

  NOTE: To control the use of the serialize writer by the system,
  rather than by the user (as discussed below), see
  [set-serialize-character-system].

  The expression [47m(with-serialize-character char form)[0m evaluates to the
  value of [47mform[0m, but with the serialize-character of the [47m[state][0m
  assigned to [47mchar[0m, which should be one of [47mnil[0m, [47m#\\Y[0m, or [47m#\\Z[0m.  We
  describe the effect of that assignment below.  But note that if you
  are doing this because of one or more specific calls of
  [47mprint-object$[0m, such as [47m(print-object$ x channel state)[0m, then you
  may wish instead to evaluate [47m(print-object$-fn x
  serialize-character channel state)[0m, in which case you will not need
  to use [47mwith-serialize-character[0m.

    General forms:
    (with-serialize-character nil form)
    (with-serialize-character #Y form)
    (with-serialize-character #Z form)

  where [47mform[0m should evaluate to an [error-triple].

  You can get the current serialize-character as follows.

    (get-serialize-character state)

  Note that if you prefer to obtain the same behavior (as described
  below) globally, rather than only within the scope of
  [47mwith-serialize-character[0m, then use [47mset-serialize-character[0m in a
  corresponding manner:

    (set-serialize-character nil state)
    (set-serialize-character #\\Y state)
    (set-serialize-character #\\Z state)

  In each case above, calls of [47mprint-object$[0m (see [io]) in [47mform[0m will
  produce a readable object.  In the first case, that object is
  printed as one might expect at the terminal, as an ordinary Lisp
  s-expression.  But in the other cases, the object is printed by
  first laying down either [47m#Y[0m or [47m#Z[0m (respectively) and then calling
  [47m[serialize-write][0m (or more precisely, the underlying function
  called by [47mserialize-write[0m that prints to a stream).

  Consider what happens when the ACL2 reader encounters an object
  produced as described above (in the [47m#Y[0m or [47m#Z[0m case).  When the
  object was written, information was recorded on whether that object
  was a [hons].  In the case of [47m#Z[0m, the object will be read as a hons
  if and only if it was originally written as a hons.  But in the
  case of [47m#Y[0m, it will never be read as a hons.  Thus, [47m#Y[0m and [47m#Z[0m will
  behave the same if the original written object was not a hons,
  creating an object that is not a hons.  For an equivalent
  explanation and a bit more discussion, see [serialize-read], in
  particular the discussion of the hons-mode.  The value [47m:smart[0m
  described there corresponds to [47m#Z[0m, while [47m:never[0m corresponds to [47m#Y[0m.")
 (WITH-STOLEN-ALIST
  (FAST-ALISTS ACL2-BUILT-INS)
  "[47m(with-stolen-alist name form)[0m ensures that [47mname[0m is a fast alist at
  the start of the execution of [47mform[0m.  At the end of execution, it
  ensures that [47mname[0m is a fast alist if and only if it was originally.
  That is, if [47mname[0m was not a fast alist originally, its hash table
  link is freed, and if it was a fast alist originally but its table
  was modified during the execution of [47mform[0m, that table is restored.
  Note that any extended table created from the original fast alist
  during [47mform[0m must be manually freed.

  Logically, [47mwith-stolen-alist[0m just returns [47mform[0m.

  Under the hood, we cause [47malist[0m to become a fast alist before
  executing [47mform[0m, and we check the various conditions outlined above
  before returning the final value.

  Note that [47mwith-stolen-alist[0m will cause logically tail-recursive
  functions not to execute tail-recursively if its cleanup phase
  happens after the tail-recursive call returns.")
 (WITHOUT-EVISC
  (IO ACL2-BUILT-INS)
  "Print output in full

    General Form:
    (without-evisc form)

  where [47mform[0m is any expression to evaluate.  The effect is to evaluate
  [47mform[0m as though the [47mwithout-evisc[0m wrapper were absent, except that
  expressions are printed in full for the ensuing output, regardless
  of the current evisc-tuples (see [set-evisc-tuple]).  See
  [set-iprint] for an example.

  More precisely, [47mwithout-evisc[0m binds each of the term-evisc-tuple,
  ld-evisc-tuple, abbrev-evisc-tuple and gag-mode-evisc-tuple to [47mnil[0m
  (see [set-evisc-tuple]).  It does not modify the trace or brr
  evisc-tuples, so trace and brr output are not modified by
  [47mwithout-evisc[0m.  Also note that calls of printing functions such as
  [47m[fmt][0m that include explicit evisc-tuples will not have those
  evisc-tuples overridden.  The following example illustrates this
  point.

    ACL2 !>(without-evisc
            (fms \"~x0~%\"
                 (list (cons #0 '((a b ((c d)) e f g) u v w x y)))
                 *standard-co*
                 state
                 (evisc-tuple 2 3 nil nil)))

    ((A B # ...) U V ...)
    <state>
    ACL2 !>

  We conclude with two remarks.  (1) A call of [47mwithout-evisc[0m on
  expression [47mexp[0m actually invokes a specialized call of [47m[ld][0m on a
  one-element list containing [47mexp[0m, which prints the value returned by
  evaluation of [47mexp[0m.  It actually returns the useless value [47m(mv nil
  :invisible state)[0m, except that if an error is detected then it
  generally returns [47m(mv t nil state)[0m, indicating an error; see
  [error-triple].  So do not use [47mwithout-evisc[0m in programs if you
  want the value of the computation to be returned, rather than
  merely printed.  (2) Even when using without-evisc, if the ACL2
  logical [world] is part of the value returned, it will be printed
  in abbreviated form because the ACL2 read-eval-print loop always
  arranges for this to be the case, regardless of the ld-evisc-tuple.
  For example:

    ACL2 !>(without-evisc (w state))
    <world>
    ACL2 !>

  An alternative to the use of [47mwithout-evisc[0m is to explore large
  objects using the ACL2 function [47m(walkabout object state)[0m; see
  [walkabout].")
 (WOF
  (OUTPUT-CONTROLS IO)
  "Direct standard output and proofs output to a file

    Example Form:
    (wof \"tmp\" (pso)) ; same as (psof \"tmp\")

    General Form:
    (wof filename form)

  where [47mfilename[0m is a writable filename and [47mform[0m is any form that
  evaluates to an error triple (see [programming-with-state]), that
  is, a multiple value of the form [47m(mv erp val state)[0m.  All output to
  channels [47m[standard-co][0m and [47m[proofs-co][0m will be directed to the
  indicated file.  It is acceptable to replace [47mfilename[0m with [47m(quote
  filename)[0m.

  For a general discussion about redirection of output to a file, see
  [output-to-file].

  Note that so-called comment-window output (see [cw] and see
  [observation-cw]) is not redirected by [47mwof[0m to a file, nor is
  printing from a [wormhole].")
 (WORLD
  (STATE)
  "ACL2 property lists and the ACL2 logical database

  The ACL2 logical world is a data structure that includes all logical
  content resulting from the [command]s evaluated, back through and
  including initialization, but not including commands that have been
  undone (see [ubt]).  Thus in particular, the world includes a
  representation of the current logical theory, as well as some
  extra-logical information such as the values of ACL2 [table]s.  The
  rest of this topic focuses on the structure of the ACL2 world and,
  more generally, the ``world'' data structure.

  A ``world'' is a list of triples, each of the form [47m(sym prop . val)[0m,
  implementing the ACL2 notion of property lists.  ACL2 permits the
  simultaneous existence of many property list worlds.  ``The world''
  is often used as a shorthand for ``the ACL2 logical world'' which
  is the particular property list world used within the ACL2 system
  to maintain a database that contains rules, [table]s, and so on.

  Common Lisp provides the notion of ``property lists'' by which one
  can attach ``properties'' and their corresponding ``values'' to
  symbols.  For example, one can arrange for the [47m'color[0m property of
  the symbol [47m'box-14[0m to be [47m'purple[0m and the [47m'color[0m property of the
  symbol [47m'triangle-7[0m to be [47m'yellow[0m.  Access to property lists is
  given via the Common Lisp function [47mget[0m.  Thus, [47m(get 'box-14 'color)[0m
  might return [47m'purple[0m.  Property lists can be changed via the
  special form [47msetf[0m.  Thus, [47m(setf (get 'box-14 'color) 'blue)[0m changes
  the Common Lisp property list configuration so that [47m(get 'box-14
  'color)[0m returns [47m'blue[0m.  It should be obvious that ACL2 cannot
  provide this facility, because Common Lisp's [47mget[0m ``function'' is
  not a function of its argument, but instead a function of some
  implicit state object representing the property list settings for
  all symbols.

  ACL2 provides the functions [47mgetprop[0m and [47mputprop[0m which allow one to
  mimic the Common Lisp property list facility.  However, ACL2's
  [47mgetprop[0m takes as one of its arguments a list that is a direct
  encoding of what was above called the ``state object representing
  the property list settings for all symbols.'' Because ACL2 already
  has a notion of ``[state]'' that is quite distinct from that used
  here, we call this property list object a ``world.'' A world is
  just a true list of triples.  Each triple is of the form [47m(sym prop
  . val)[0m.  This world can be thought of as a slightly elaborated form
  of association list and [47mgetprop[0m is a slightly elaborated form of
  [47m[assoc][0m that takes two keys.  When [47mgetprop[0m is called on a symbol,
  [47ms[0m, property [47mp[0m, and world, [47mw[0m, it scans [47mw[0m for the first triple whose
  [47msym[0m is [47ms[0m and [47mprop[0m is [47mp[0m and returns the corresponding [47mval[0m. [47mGetprop[0m
  has two additional arguments: one controls what it returns if no
  such [47msym[0m and [47mprop[0m exist in [47mw[0m, and the other allows an extremely
  efficient implementation.  To set some property's value for some
  symbol, ACL2 provides [47mputprop[0m.  [47m(putprop sym prop val w)[0m merely
  returns a new world, [47mw'[0m, in which [47m(sym prop . val)[0m has been
  [47m[cons][0med onto the front of [47mw[0m, thus ``overwriting'' the [47mprop[0m value
  of [47msym[0m in [47mw[0m to [47mval[0m and leaving all other properties in [47mw[0m unchanged.

  One aspect of ACL2's property list arrangement is that it is possible
  to have many different property list worlds.  For example, [47m'box-14[0m
  can have [47m'color[0m [47m'purple[0m in one world and can have [47m'color[0m [47m'yes[0m in
  another, and these two worlds can exist simultaneously because
  [47mgetprop[0m is explicitly provided the world from which the property
  value is to be extracted.

  The efficiency alluded to above stems from the fact that Common Lisp
  provides property lists.  Using Common Lisp's provisions behind the
  scenes, ACL2 can ``install'' the properties of a given world into
  the Common Lisp property list state so as to make retrieval via
  [47mgetprop[0m very fast in the special case that the world provided to
  [47mgetprop[0m has been installed.  To permit more than one installed
  world, each of which is permitted to be changed via [47mputprop[0m, ACL2
  requires that worlds be named and these names are used to
  distinguish installed versions of the various worlds.  See
  [extend-world] and [retract-world] for how to install a world.

  However, the ACL2 system uses a property list world, named
  [47m'current-acl2-world[0m, in which to store the succession of user
  [command]s and their effects on the logic.  This world is often
  referred to in our [documentation] as ``the world'' though it
  should be stressed that the user is permitted to have worlds and
  ACL2's is in no way distinguished except that the user is not
  permitted to modify it except via event [command]s.  The ACL2 world
  is part of the ACL2 [state] and may be obtained via [47m(w state)[0m.

  [31;1mWarning[0m: The ACL2 world is very large.  Its length as of this writing
  (Version 2.5) is over [47m40,000[0m and it grows with each release.
  Furthermore, some of the values stored in it are pointers to old
  versions of itself.  Printing [47m(w state)[0m is something you should
  avoid because you likely will not have the patience to await its
  completion.  For these practical reasons, the only thing you should
  do with [47m(w state)[0m is provide it to [47mgetprop[0m, as in the form

    (getprop sym prop default 'current-acl2-world (w state))

  or its convenient abbreviation

    (getpropc sym prop default)

  to inspect properties within it, or to pass it to ACL2 primitives,
  such as theory functions, where it is expected.

  Some ACL2 [command] forms, such as theory expressions (see
  [theories]) and the values to be stored in tables (see [table]),
  are permitted to use the variable symbol [47mworld[0m freely with the
  understanding that when these forms are evaluated that variable is
  bound to [47m(w state)[0m.  Theoretically, this gives those forms complete
  knowledge of the current logical configuration of ACL2.  However,
  at the moment, few world scanning functions have been documented
  for the ACL2 user.  Instead, supposedly convenient macro forms have
  been created and documented.  For example, [47m(current-theory :here)[0m,
  which is the theory expression which returns the currently
  [enable]d theory, actually macroexpands to [47m(current-theory-fn :here
  world)[0m.  When evaluated with [47mworld[0m bound to [47m(w state)[0m,
  [47mcurrent-theory-fn[0m scans the current ACL2 world and computes the set
  of [rune]s currently [enable]d in it.


Subtopics

  [Extend-world]
      Install an extension of a given ACL2 [world]

  [Formula]
      The formula of a name or [rune]

  [Getprop]
      Access fast property lists

  [Getpropc]
      Access fast property lists

  [Logical-name]
      A name created by a logical event

  [Props]
      Print the ACL2 properties on a symbol

  [Putprop]
      Update fast property lists

  [Redefined-names]
      To collect the names that have been redefined

  [Retract-world]
      Install an initial segment (retraction) of a given ACL2 [world]")
 (WORMHOLE
  (STATE LD)
  "[47m[ld][0m without [47m[state][0m --- a short-cut to a parallel universe

    Example Form:
    ; The following form enters a recursive read-eval-print loop on a
    ; copy of the current state, allowing you to interact with that loop.
    ; Note that the form does not mention the ACL2 state variable!
    ; Evaluate the form below. Inside the resulting loop, define some function,
    ; e.g., with [47m(defun foo (x) x)[0m.  Then exit with [47m:q[0m and observe,
    ; e.g., with [47m:pe foo[0m, that the external state did not change.

    (wormhole 'foo
              '(lambda (whs) (set-wormhole-entry-code whs :ENTER))
              nil
              '(list 'hello 'there))

    General Form:
    (wormhole name entry-lambda input form
      :current-package    ...  ; known package name
      :ld-skip-proofsp    ...  ; nil, t or 'include-book
      :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 level length hiding-cars)
      :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

  The keyword arguments above are exactly those of [47m[ld][0m (see [ld])
  except that three of [47m[ld][0m's keyword arguments are missing: the
  three that specify the channels [47m[standard-oi][0m, [47m[standard-co][0m and
  [47m[proofs-co][0m, which default in [47mwormhole[0m to ACL2's comment window.

  There are two ways to create and enter a wormhole: [47mwormhole[0m as
  described here and the simpler [47m[wormhole-eval][0m.  We recommend you
  read this full account of wormholes before using [47mwormhole-eval[0m.

  Ignoring the use of [47mentry-lambda[0m, [47mwormhole[0m manufactures a named
  ``wormhole [state]'' and calls the general-purpose ACL2
  read-eval-print loop [47m[ld][0m on it.  However, when [47mld[0m exits, the
  wormhole evaporates and the function [47mwormhole[0m returns [47mnil[0m.  The
  manufactured state is like the ``current'' ACL2 [state] except for
  two things.  First, some information from the last wormhole state
  of this name is transferred into the new state; this allows a
  wormhole to maintain some state from one call to the next.  Second,
  some information from the wormhole call itself is transferred into
  the new state; this allows the wormhole to be sensitive to context.
  These two changes to the current state are reflected in the
  settings [47m(@ wormhole-status)[0m and [47m(@ wormhole-input)[0m when in the
  wormhole.  This is discussed in detail below.

  Note that [47mwormhole[0m may be called from environments in which [47m[state][0m
  is not bound.  It is still applicative because it always returns
  [47mnil[0m.

  There are some restrictions about what can be done inside a wormhole.
  As you may imagine, we really do not ``copy the current state'' but
  rather just keep track of how it is modified while in the wormhole
  and we undo those modifications upon exit.  In particular, when
  exiting a wormhole, values of state globals (see
  [programming-with-state]) are restored to their values at the time
  the wormhole was entered.  Note that information about traced
  functions is stored in state globals (see [trace$]); accordingly,
  all tracing and untracing done inside a wormhole is undone upon
  exit from the wormhole.

  An error is signaled if you try to modify state in an unsupported
  way.  For this same reason, wormholes do not allow updating of any
  user-defined single-threaded objects.  See [stobj].

  One example wormhole is the implementation of the ACL2
  [47m[accumulated-persistence][0m facility for tracking the frequency with
  which rules are tried.  To implement this feature directly the
  theorem prover would have to take the tracking data as an argument
  and pass it around so that updates could be accumulated.  This
  would greatly clutter the code.  Instead, the tracking data is
  maintained in a wormhole.  The theorem prover enters the wormhole
  to update the data as rules are tried.  When you request a display
  of the data, [47m[show-accumulated-persistence][0m enters the wormhole and
  prints the data.  But the data is never available outside that
  wormhole.  The ACL2 system uses a second wormhole, named [47m[brr][0m, to
  implement the [break-rewrite] facility, allowing the user to
  interact with the rewriter as rules are applied.

  We now specify the arguments and behavior of [47mwormhole[0m.

  The [47mname[0m argument must be a quoted constant and is typically a
  symbol.  It will be the ``name'' of the wormhole.  A wormhole of
  that name will be created the first time [47mwormhole[0m, [47m[wormhole-eval][0m,
  or [47m[set-persistent-whs-and-ephemeral-whs][0m is called.  However, it
  is forbidden to invoke these functions on any name listed in
  [47m*protected-system-wormhole-names*[0m, which includes [47mbrr[0m (the
  [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and
  [47mfc-wormhole[0m (the name of the wormhole managing
  [forward-chaining-reports]), among others.

  Every wormhole name has a ``status.'' The status of a wormhole is
  stored outside of ACL2 at a location known to hold the ``persistent
  wormhole status'' or ``persistent-whs'' of that wormhole.  Before
  [47mwormhole[0m enters its read-eval-print loop the persistent-whs is
  assigned to the state global variable [47mwormhole-status[0m and so while
  inside the wormhole the status is available as [47m(@ wormhole-status)[0m.
  [47mWormhole-status[0m is untouchable: you cannot change it directly as
  with [47m(assign wormhole-status ...)[0m.  But the persistent-whs can be
  changed, e.g., with [47mwormhole[0m, [47mwormhole-eval[0m, or
  [47mset-persistent-whs-and-ephemeral-whs[0m.  See [47m[wormhole-status][0m for a
  discussion of the ramifications of there being two places a
  wormhole's status might be found and of the importance of the
  notion of ``wormhole coherence.''

  Upon the first call on name of [47mwormhole[0m (or the other wormhole
  creator functions mentioned above) the status of that name is [47mnil[0m.
  But in general you should arrange for the status to be a cons.  The
  status is set by the quoted [47mlambda[0m every time [47mwormhole[0m is called;
  but it may also be by set in the [47mform[0m argument of [47mwormhole[0m using
  [47mset-persistent-whs-and-ephemeral-whs[0m or
  [47m[sync-ephemeral-whs-with-persistent-whs][0m.

  The [47mcar[0m of the status should be either [47m:ENTER[0m or [47m:SKIP[0m and is called
  the wormhole's ``entry code.'' The entry code of [47mnil[0m or, indeed, of
  any value other than [47m:SKIP[0m is treated as thought it were [47m:ENTER[0m.
  The [47mcdr[0m of the status is arbitrary data maintained by the author of
  the wormhole.

  When the wormhole is exited --- typically because the form [47m:q[0m was
  read by [47mld[0m --- the then-current ephemeral-whs (i.e., (@
  wormhole-status)) is moved to the persistent-whs so that it can be
  restored when this wormhole is entered again.  (Note: The
  break-rewrite wormhole, [47mbrr[0m, is handled differently.  When it is
  exited back to the top-level, the persistent-whs is set to what it
  was when ACL2 was last at the top-level.)  The rest of the wormhole
  state is lost upon exit.

  This allows a sequence of entries and exits to a wormhole to maintain
  some history in the status and this information can be manipulated
  by ACL2 functions executing inside the wormhole.

  The second argument to [47mwormhole[0m must be a quoted lambda expression.
  We explain it later.

  The third argument, [47minput[0m, may be any term.  The value of the term is
  passed into the manufactured wormhole state, allowing you to pass
  in information about the calling context.  Inside the wormhole, the
  [47minput[0m is available via [47m(@ wormhole-input)[0m and may be assigned with
  [47m[assign][0m.

  The fourth argument, [47mform[0m, may be any term; when [47m[ld][0m is called on
  the manufactured wormhole state, the first form evaluated by [47mld[0m
  will be the value of [47mform[0m.  Note that [47mform[0m will be translated by
  [47mld[0m.  Errors, including guard violations, in the translation or
  execution of that first form will exit the wormhole.

  When used properly, the first form allows you to greet your user
  before reading the first interactive command or simply to do
  whatever computation you want to do inside the wormhole and exit
  silently.  We give examples below.

  Manufacturing a wormhole state is relatively expensive; in addition,
  the forms executed by [47mld[0m must be read, translated, and interpreted
  as with any user type-in.  The [47mentry-lambda[0m offers a way to avoid
  this or, at least, to decide whether to incur that expense.

  Before the wormhole state is manufactured and entered, the
  [47mentry-lambda[0m is applied to the persistent-whs with [47m[wormhole-eval][0m.
  That [47mlambda[0m application must produce a new wormhole status, which
  is stored as the wormhole's new persistent-whs.  The entry code for
  the new status determines whether [47mwormhole[0m actually manufactures a
  wormhole state and calls [47mld[0m.

  If the entry code for that new status is [47m:SKIP[0m the wormhole state is
  not manufactured; the new persistent-whs is merely saved and
  [47mwormhole[0m returns nil.  Otherwise, a new state is manufactured and
  entered.  Note therefore that the [47mentry-lambda[0m may be used to
  perform two functions: (a) to determine if it is really necessary
  to manufacture a state and (b) to update the data in the wormhole
  status as a function of the old status without invoking [47mld[0m.

  The [47mentry-lambda[0m must be a quoted lambda expression of at most one
  argument.  Thus, the argument must be either

    '(lambda (whs) <body>)

  or

    '(lambda () <body>)

  Note the quote.  If a formal, e.g., [47mwhs[0m, is provided, it must be used
  as a variable in the [47mlambda[0m body.  The [47mlambda[0m-expression may
  contain free variables, that is, the body may mention variables
  other than the [47mlambda[0m formal.  These free variables are understood
  in the caller's environment.  These conventions allow us to compile
  the [47mentry-lambda[0m application very efficiently when the guard has
  been verified.

  The guard on a call of [47mwormhole[0m is the conjunction of the guards on
  the arguments conjoined with the guard on the body of the
  [47mentry-lambda[0m.  See [wormhole-eval] for a discussion of the guard on
  the [47mlambda[0m-expression.

  The functions [47m[wormhole-statusp][0m, [47m[wormhole-entry-code][0m,
  [47m[wormhole-data][0m, [47m[set-wormhole-entry-code][0m, [47m[set-wormhole-data][0m,
  and [47m[make-wormhole-status][0m may be useful in manipulating entry
  codes and data in the [47mentry-lambda[0m.

  See [47m[wormhole-programming-tips][0m for some advice about using
  wormholes, maintaining (or not maintaining) coherence, etc.

  Pragmatic Advice on Designing a Wormhole: Suppose you are using
  wormholes to implement some extra-logical utility.  You must
  contemplate how you will use your wormhole's status to store hidden
  information.  You might be tempted to exploit the entry code as
  part of the status.  For example, you may think of [47m:ENTER[0m as
  indicating that your utility is ``turned on'' and [47m:SKIP[0m as
  indicating that your utility is ``turned off.'' We advise against
  such a design.  We recommend you base your decisions on the
  wormhole data.  We recommend that you set but not read the wormhole
  entry code to signal whether you wish to enter a full-fledged
  wormhole.  To use the entry code as a flag overloads it and invites
  confusion when your facility is ``turned off'' but you have to
  enter the wormhole for some reason.

  For a behind-the-scenes description of how wormholes work, See
  [wormhole-implementation].

  Here are some sample situations handled by [47mwormhole-eval[0m and
  [47mwormhole[0m.  The wormhole in question will be named [47mdemo[0m and it is
  created in the answer to the first question below.  The functions
  below all maintain the convention that the status is either [47mnil[0m or
  of the form [47m(:key . lst)[0m, where [47m:key[0m is either [47m:skip[0m or [47m:enter[0m and
  [47mlst[0m is a true-list of arbitrary objects.  But since there is no way
  to prevent the user from entering the [47mdemo[0m wormhole interactively
  and doing something to the status, this convention cannot be
  enforced.  Thus, the functions below do what we say they do, e.g.,
  remember all the values of [47mx[0m ever seen, only if they're the only
  functions messing with the [47mDEMO[0m status.  On the other hand, the
  guards of all the functions below can be verified.  We have
  explicitly declared that the guards on the functions below are to
  be verified, to confirm that they can be.  Guard verification is
  optional but wormholes (and [47mwormhole-eval[0m in particular) are more
  efficient when guards have been verified.  All of the functions
  defined below return [47mnil[0m.

  The examples below build on each other.  If you really want to
  understand wormholes we recommend that you evaluate each of the
  forms below, in the order they are discussed.

  [31;1mQ.[0m How do I initialize the status of the [47mdemo[0m wormhole?

  Actually, it is often unnecessary to explicitly initialize the status
  of a new wormhole because it is [47mnil[0m by default, the
  [47m[wormhole-entry-code][0m of [47mnil[0m is [47m:enter[0m and the [47m[wormhole-data][0m of
  [47mnil[0m is [47mnil[0m, which often is enough.  But if the data field of your
  wormhole needs more structure for whatever you're planning to do
  with it to make sense, you can initialize it by executing a form
  like this, where the [47mnil[0m below is the contents of the initial data
  field.

    ACL2 !>(wormhole-eval 'demo
                          '(lambda (whs) (make-wormhole-status whs :enter nil))
                          nil)
    NIL
    ACL2 !>(get-persistent-whs 'demo state)
     (:ENTER)

  [31;1mQ.[0m How do I define a function that prints the (persistent) status of
  the [47mdemo[0m wormhole to the comment window?

    (defun demo-status ()
      (declare (xargs :verify-guards t))
      (wormhole-eval 'demo
                     '(lambda (whs)
                        (prog2$ (cw \"DEMO status:~%~x0~%\" whs)
                                whs))
                     nil))

  Note the [47mprog2$[0m above.  After printing the status to the comment
  window we return the unchanged status [47mwhs[0m.  Had we just written the
  [47mcw[0m term, which returns [47mnil[0m, without then returning [47mwhs[0m, the
  function would print the status and then set it to [47mnil[0m!

  [31;1mQ.[0m How can I define a function, [47mdemo-collect[0m, that does not take or
  return [47m[state][0m but that can collect every symbol passed to it (but
  not collect non-symbols)?

    (defun demo-collect (x)
       (declare (xargs :verify-guards t))
       (wormhole-eval 'demo
                      '(lambda (whs)
                         (make-wormhole-status whs
                                               (wormhole-entry-code whs)
                                               (if (symbolp x)
                                                   (cons x (wormhole-data whs))
                                                   (wormhole-data whs))))
                      nil))

  We could have also defined this function this way:

    (defun demo-collect (x)
      (declare (xargs :verify-guards t))
      (if (symbolp x)
          (wormhole-eval 'demo
                         '(lambda (whs)
                            (set-wormhole-data whs
                                               (cons x (wormhole-data whs))))
                         nil)
          nil))

  Both versions always return [47mnil[0m and both versions collect into the
  wormhole data field just the symbols [47mx[0m upon which [47mdemo-collect[0m is
  called.  Note that the [47mlambda[0m expressions used in both definitions
  mention [47mx[0m as a free variable.

  [31;1mQ.[0m How do I use [47mdemo-collect[0m?  Below we show an interactive session
  log with [47mdemo-collect[0m and [47mdemo-status[0m.  Notice that [47mstate[0m is
  nowhere involved but that the functions always return [47mnil[0m.  The
  computation, collection, and printing are done inside the wormhole.

    ACL2 !>(demo-status)
    DEMO status:
    (:ENTER)
    NIL
    ACL2 !>(demo-collect 'a)
    NIL
    ACL2 !>(demo-status)
    DEMO status:
    (:ENTER A)
    NIL
    ACL2 !>(demo-collect 'b)
    NIL
    ACL2 !>(demo-collect 'c)
    NIL
    ACL2 !>(demo-status)
    DEMO status:
    (:ENTER C B A)
    NIL

  [31;1mQ.[0m How do I reset the data to [47mnil[0m?

  The answer is the same as the answer to the first question, use
  [47mwormhole-eval[0m as we did there.  But we'll repeat it as a session
  log because in the next question we want the data field to start
  off at [47mnil[0m again.

    ACL2 !>(wormhole-eval 'demo
                          '(lambda (whs) (make-wormhole-status whs :enter nil))
                          nil)
    NIL
    ACL2 !>(demo-status)
    DEMO status:
    (:ENTER)
    NIL

  [31;1mQ.[0m How can I use [47mdemo-collect[0m in a function?  Below is a function
  that maps over a list and computes its length.  But it has been
  annotated with a call to [47mdemo-collect[0m on every element.  We
  illustrate a call below.

    (defun my-len (lst)
      (if (endp lst)
          0
          (+ 1
             (prog2$ (demo-collect (car lst))
                     (my-len (cdr lst))))))

  Thus, for example, if we call [47mmy-len[0m on a list of length [47m5[0m it returns
  [47m5[0m but accumulates the symbols into the [47mdemo[0m wormhole, without
  [47mstate[0m.  From a logical perspective [47mmy-len[0m is just [47mlen[0m and that can
  be proved trivially.

    ACL2 !>(my-len '(4 temp car \"Hi\" fix))
    5
    ACL2 !>(demo-status)
    DEMO status:
    (:ENTER FIX CAR TEMP)
    NIL
    ACL2 !>(thm (equal (my-len x) (len x)))
    ...
    Proof succeeded.

  [31;1mQ.[0m How do I set the entry code to [47m:enter[0m or [47m:skip[0m according to
  whether [47mname[0m is a [47mmember-equal[0m of the list of things seen so far?
  Note that we cannot check this condition outside the wormhole,
  because it depends on the list of things collected so far.  We make
  the decision inside the [47mlambda[0m-expression.  Note that we explicitly
  check that the guard of [47mmember-equal[0m is satisfied by the current
  wormhole data, since we cannot rely on the invariant that no other
  function interferes with the status of the [47mdemo[0m wormhole.  In the
  case that the data is not a true-list we act like the data is [47mnil[0m
  and set the status to [47m(:skip . nil)[0m.

    (defun demo-set-entry-code (name)
      (declare (xargs :verify-guards t))
      (wormhole-eval 'demo
                     '(lambda (whs)
                        (if (true-listp (wormhole-data whs))
                            (set-wormhole-entry-code
                             whs
                             (if (member-equal name (wormhole-data whs))
                                 :enter
                                 :skip))
                            '(:skip . nil)))
                     nil))

  Thus

    ACL2 !>(demo-set-entry-code 'monday)
    NIL
    ACL2 !>(demo-status)
    DEMO status:
    (:SKIP FIX CAR TEMP)
    NIL
    ACL2 !>(demo-set-entry-code 'fix)
    NIL
    ACL2 !>(demo-status)
    DEMO status:
    (:ENTER FIX CAR TEMP)
    NIL
    ACL2 !>

  We won't be using [47mdemo-set-entry-code[0m again in these questions and
  answers, so don't spend time learning more about it!

  [31;1mQ.[0m Suppose I want to collect every symbol and then, if the symbol has
  an [47mabsolute-event-number[0m property in the ACL2 logical world, print
  the defining event with [47m:pe[0m and then enter an interactive loop; but
  if the symbol does not have an [47mabsolute-event-number[0m, don't print
  anything and don't enter an interactive loop.

  Here it is not important to know what [47mabsolute-event-number[0m is; this
  example just shows that we can use a wormhole to access the ACL2
  logical world, even in a function that does not take the state as
  an argument.

  In the code below, we use [47mwormhole[0m instead of [47mwormhole-eval[0m, because
  we might have to access the logical world and enter an interactive
  loop.  But for efficiency we do as much as we can inside the entry
  [47mlambda[0m, where we can check whether [47mx[0m is symbol and collect it into
  the data field of the wormhole status.  Note that if we collect [47mx[0m,
  we also set the entry code to [47m:enter[0m.  If we don't collect [47mx[0m, we
  set the entry code to [47m:skip[0m.

    (defun demo-collect-symbols-and-print-events (x)
      (declare (xargs :guard t))
      (wormhole 'demo
                '(lambda (whs)
                   (if (symbolp x)
                       (make-wormhole-status whs
                                             :enter
                                             (cons x (wormhole-data whs)))
                       (set-wormhole-entry-code whs :skip)))

    ; The wormhole will not get past here is unless the entry code is
    ; :enter.  If we get past here, wormhole will manufacture a state, put
    ; x into (@ wormhole-input) and call ld in such a way that the
    ; first form executed is the quoted if-expression below.

                x
                '(if (getpropc (@ wormhole-input) 'absolute-event-number)
                     (er-progn
                      (mv-let (col state)
                              (fmt \"~%Entering a wormhole on the event name ~x0~%~
                                     Exit with :q~%~%\"
                                   (list (cons #\\0 (@ wormhole-input)))
                                   *standard-co* state nil)
                              (declare (ignore col))
                              (value nil))
                      (pe (@ wormhole-input))
                      (set-ld-prompt 'wormhole-prompt state)
                      (value :invisible))
                     (value :q))
                :ld-verbose nil
                :ld-prompt nil))

  The ``first form'' --- so called because it is the first form
  executed by the wormhole's read-eval-print loop --- is the quoted
  [47mif[0m-expression in the fourth argument of [47mwormhole[0m.  It asks whether
  the [47mwormhole-input[0m (i.e., [47mx[0m) has an [47mabsolute-event-number[0m property.

  The true branch of that [47mif[0m is an [47m[er-progn][0m to perform a sequence of
  commands, each of which returns an ACL2 error triple (see
  [programming-with-state]).  The first form uses [47m[fmt][0m to print a
  greeting.  Since [47mfmt[0m returns [47m(mv col state)[0m and we must return an
  error triple, we embed the [47mfmt[0m term in an [47m(mv-let (col state) ...
  (value nil))[0m.  The macro [47mvalue[0m takes an object and returns a
  ``normal return'' error triple.  The second form in the [47mer-progn[0m
  uses the ACL2 history macro [47mpe[0m (see [pe]) to print the defining
  event for a name.  The third form sets the prompt of this
  read-eval-print loop to the standard function for printing the
  wormhole prompt.  We silenced the printing of the prompt when we
  called [47mld[0m, thanks to the [47m:ld-prompt nil[0m keyword option.  More on
  this below.  The fourth form returns the error triple value
  [47m:invisible[0m as the value of the first form.  This prevents [47mld[0m from
  printing the value of the first form.  Since we have not exited [47mld[0m,
  that function just continues by reading the next form from the
  comment window.  The user perceives this as entering a
  read-eval-print loop and being prompted for input.  We continue in
  the loop until the user types [47m:q[0m.

  The false branch of the [47mif[0m is taken when [47mx[0m has no
  [47mabsolute-event-number[0m property.  We execute the form [47m(value :q)[0m,
  which is the programming equivalent of typing [47m:q[0m.  That causes the
  [47mld[0m to exit.

  The [47mld[0m special variables set in the call to [47mwormhole[0m and further
  manipulated inside the first form to [47mld[0m may require explanation.
  By setting [47m:[0m[47m[ld-verbose][0m to [47mnil[0m, we prevent [47mld[0m from printing the
  familiar ACL2 banner when [47mld[0m is called.  If [47m:ld-verbose nil[0m is
  deleted, then you would see something like

    ACL2 Version  4.0.  Level 2.
    ...
    Type (good-bye) to quit completely out of ACL2.

  every time the first form is read and evaluated.

  By setting [47m:[0m[47m[ld-prompt][0m to [47mnil[0m we prevent [47mld[0m from printing the prompt
  before reading and evaluating the first form.

  As this example shows, to use full-blown wormholes you must
  understand the protocol for using wormhole status to control
  whether a wormhole state is manufactured for [47mld[0m and you must also
  understand programming with [47m[state][0m and the effects of the various
  [47m[ld][0m ``special variables.''

  Had we defined [47mdemo-collect-symbols-and-print-events[0m before [47mmy-len[0m we
  could have called it instead of [47mdemo-collect[0m.  Then

    ACL2 !>(my-len '(4 temp car \"Hi\" fix))

  would have still collected all the symbols into the [47mdemo[0m wormhole,
  but on the symbols [47mcar[0m and [47mfix[0m it would have entered an interactive
  break.  Here is the break that would be triggered when this version
  of [47mmy-len[0m encounters the [47mfix[0m.

    Entering a wormhole on the event name FIX
    Exit with :q

    V     -8055  (DEFUN FIX (X)
                    (DECLARE (XARGS :GUARD T :MODE :LOGIC))
                    (IF (ACL2-NUMBERP X) X 0))
    Wormhole ACL2 !>(fix 123)
    123
    Wormhole ACL2 !>(fix t)
    0
    Wormhole ACL2 !>:q

  After printing the [47m(DEFUN FIX ...)[0m above the user in this session
  called [47mfix[0m twice to see how it behaves.  Then the user issued the
  [47m:q[0m command to exit the interactive loop, allowing [47mmy-len[0m to
  continue.  When [47mmy-len[0m finishes processing the list, it would
  return [47m5[0m.

  From the discussion above we see that wormholes can be used to create
  formatted output without passing in the ACL2 [47m[state][0m.  For examples
  see [cw], in particular the discussion at the end of that
  documentation topic.


Subtopics

  [Get-persistent-whs]
      Make a wormhole's status visible outside the wormhole

  [Make-wormhole-status]
      Creates a wormhole status object from given status, entry code, and
      data

  [Set-persistent-whs-and-ephemeral-whs]
      maintaining wormhole coherence

  [Set-wormhole-data]
      Sets the wormhole data object in a wormhole status object

  [Set-wormhole-entry-code]
      Sets the wormhole entry code in a wormhole status object

  [Sync-ephemeral-whs-with-persistent-whs]
      establishing wormhole coherence

  [Wormhole-data]
      Determines the wormhole data object from a wormhole status object

  [Wormhole-entry-code]
      Determines the wormhole entry code from a wormhole status object

  [Wormhole-eval]
      State-saving without [state] --- a short-cut to a parallel universe

  [Wormhole-implementation]
      Notes on how wormholes are implemented

  [Wormhole-p]
      Predicate to determine if you are inside a [47m[wormhole][0m

  [Wormhole-programming-tips]
      some tips for how to use wormholes

  [Wormhole-status]
      the two senses of a wormhole's status

  [Wormhole-statusp]
      Predicate recognizing well-formed wormhole status object")
 (WORMHOLE-COHERENCE (POINTERS)
                     "See [wormhole-status].")
 (WORMHOLE-DATA
  (WORMHOLE)
  "Determines the wormhole data object from a wormhole status object

    General Form:  (wormhole-data whs)

  See [wormhole].  Returns the wormhole data from a well-formed
  wormhole status [47mwhs[0m.  If [47mwhs[0m is [47mnil[0m or not well-formed, the data is
  [47mnil[0m.")
 (WORMHOLE-ENTRY-CODE
  (WORMHOLE)
  "Determines the wormhole entry code from a wormhole status object

    General Form:  (wormhole-entry-code whs)

  See [wormhole].  Returns [47m:ENTER[0m or [47m:SKIP[0m given a well-formed wormhole
  status [47mwhs[0m.  If [47mwhs[0m is [47mnil[0m or not well-formed, the entry code is
  [47m:ENTER[0m.")
 (WORMHOLE-EVAL
  (WORMHOLE)
  "State-saving without [state] --- a short-cut to a parallel universe

    Example Form:
    (wormhole-eval 'demo
       '(lambda (whs)
          (set-wormhole-data whs
                             (cons (cons name info)
                                   (wormhole-data whs))))
       (prog2$ info name))

    General Form:
    (wormhole-eval name lambda varterm)

  where [47mname[0m must be a quoted wormhole name and [47mlambda[0m must be a quoted
  [47mlambda[0m-expression as described below.  It is forbidden to invoke
  [47mwormhole-eval[0m on the names listed in
  [47m*protected-system-wormhole-names*[0m, which includes [47mbrr[0m (the
  [break-rewrite] wormhole name), [47maccumulated-persistence[0m, and
  [47mfc-wormhole[0m (the name of the wormhole managing
  [forward-chaining-reports]), among others.

  The [47mlambda[0m-expression must have at most one formal parameter but the
  body of the [47mlambda[0m-expression may contain other variables.  Note
  that in the example form given above, the [47mlambda[0m has one formal,
  [47mwhs[0m, and uses [47mname[0m and [47minfo[0m freely.  Note that the [47mlambda[0m is
  quoted.  The third argument of [47mwormhole-eval[0m, [47mvarterm[0m, is an
  arbitrary term that should mention all of the free variables in the
  [47mlambda[0m-expression.  That term establishes your ``right'' to refer
  to those free variables in the environment in which the
  [47mwormhole-eval[0m expression occurs.  The value of [47mvarterm[0m is
  irrelevant and if you provide [47mnil[0m ACL2 will automatically provide a
  suitable term, namely a [47mprog2$[0m form like the one shown in the
  example above.

  Aside: Exception for ACL2(p) (see [parallelism]) to the irrelevance
  of [47mvarterm[0m.  By default, calls of [47mwormhole-eval[0m employ a lock,
  [47m*wormhole-lock*[0m.  To avoid such a lock, include the symbol
  [47m:NO-WORMHOLE-LOCK[0m in [47mvarterm[0m; for example, you might replace a last
  argument of [47mnil[0m in [47mwormhole-eval[0m by [47m:NO-WORMHOLE-LOCK[0m.  End of
  Aside.

  See [wormhole] for a full explanation of wormholes.  Most relevant
  here is that every wormhole has a name and a status.  The status is
  generally a cons pair whose [47mcar[0m is the keyword [47m:ENTER[0m or the
  keyword [47m:SKIP[0m and whose [47mcdr[0m is an arbitrary object used to store
  information from one wormhole call to the next.

  Here is a succinct summary of [47mwormhole-eval[0m.  If the
  [47mlambda[0m-expression has a local variable, [47mwormhole-eval[0m applies the
  [47mlambda[0m-expression to the persistent-whs (see [47m[wormhole-status][0m) of
  the named wormhole and remembers the value as the new
  persistent-whs.  If the [47mlambda[0m has no formal parameter, the [47mlambda[0m
  is applied to no arguments and the value is the new persistent-whs.
  [47mWormhole-eval[0m returns [47mnil[0m.  Thus, the formal parameter of the
  [47mlambda[0m-expression, if provided, denotes the wormhole's hidden
  status information; the value of the [47mlambda[0m is the new status and
  is hidden away.

  The guard of a [47mwormhole-eval[0m call is the guard of the body of the
  [47mlambda[0m-expression, with a fresh variable symbol used in place of
  the formal so that no assumptions are possible about the hidden
  wormhole status.  If the guard of a [47mwormhole-eval[0m is verified, the
  call is macroexpanded inline to the evaluation of the body in a
  suitable environment.  Thus, it can be a very fast way to access
  and change the persistent-whs, but the results remain hidden.  To
  interact with the wormhole's state you must use [47m[wormhole][0m.

  Functions that are probably useful in the body of the [47m[lambda][0m or the
  guard of a function using [47mwormhole-eval[0m include the following:
  [47m[wormhole-statusp][0m, [47m[wormhole-entry-code][0m, [47m[wormhole-data][0m,
  [47m[set-wormhole-entry-code][0m, [47m[set-wormhole-data][0m, and
  [47m[make-wormhole-status][0m.

  [47mWormhole-eval[0m is intended to be fast, but it is further optimized
  when the given [47mlambda[0m is of the following form.  In this case
  [47mwormhole-eval[0m returns immediately when the [47m[wormhole-data][0m is [47mnil[0m,
  which is reasonable since the old and new status are equal in this
  case.

    (lambda (whs)
            (let ((info (wormhole-data whs)))
                    (cond ((null info) whs)
                          ...)))

  See [wormhole] for a series of example uses of [47mwormhole-eval[0m and
  [47mwormhole[0m.

  For a behind-the-scenes description of how wormholes work, See
  [wormhole-implementation].


Subtopics

  [Wormhole-programming-tips]
      some tips for how to use wormholes")
 (WORMHOLE-IMPLEMENTATION
  (WORMHOLE)
  "Notes on how wormholes are implemented

  What happens when you call [47m[wormhole][0m?  Recall that a typical call of
  the function looks like this:

    (wormhole 'name
              '(lambda (whs) ...)
              input
              form
              :ld-verbose ...
              ...)

  A brief recap of the advertised semantics for [47mwormhole[0m establishes
  our terminology: When the above [47mwormhole[0m is evaluated, the
  [47mlambda[0m-expression is applied to the persistent-whs and the result
  is stored as the new persistent-whs.  Then, if the entry-code of
  the new status is [47m:ENTER[0m (actually, if it is not [47m:SKIP[0m), [47m[ld][0m is
  invoked on a copy of the ``current state'' with the specified [47mld-[0m
  ``special variables;'' output is directed to the comment window.
  In that copy of the state, the state global variables
  [47mwormhole-name[0m, [47mwormhole-input[0m and [47mwormhole-status[0m are assigned
  [47mname[0m, the the value of [47minput[0m and the persistent-whs, respectively.
  Thus, inside the wormhole, [47m(@ wormhole-name)[0m returns the name of
  the current wormhole, [47m(@ wormhole-input)[0m returns the list of
  inputs, [47m(@ wormhole-status)[0m returns the ephemeral-whs.  The first
  form executed by the [47mld[0m is the value of [47mform[0m and unless that form
  returns [47m(value :q)[0m, causing the [47mld[0m to quit, the [47mld[0m proceeds to take
  subsequent input from the comment window.  Upon exiting from [47mld[0m,
  the ephemeral-whs is written to the persistent-whs and the wormhole
  state ``evaporates.'' The next time the wormhole is entered its
  ephemeral-whs will be what it was when it last exited.

  Here is what really happens.

  Each wormhole's persistent-whs is recorded in an alist stored in a
  Common Lisp global variable named [47m*wormhole-status-alist*[0m.  This
  variable is not part of the ACL2 state.  If you exit the ACL2 loop
  with [47m:q[0m you can inspect the value of [47m*wormhole-status-alist*[0m.
  However, be cautious about printing it because the persistent-whs
  of some wormholes can be quite large.  When the [47mlambda[0m-expression
  is evaluated it is applied to the value associated with [47mname[0m in the
  alist and the result is stored back into that alist.  This step is
  performed by [47m[wormhole-eval][0m.  To make things more efficient,
  [47mwormhole-eval[0m is just a macro that expands into a [47mlet[0m that binds
  the [47mlambda[0m formal to the current status and whose body is the
  [47mlambda[0m body.  [Guard] [clause]s are generated from the body, with
  one exception: the [47mlambda[0m formal is replaced by a new variable so
  that no prior assumptions are available about the value of the
  wormhole status.

  If the newly computed status has an entry code other than [47m:SKIP[0m [47m[ld][0m
  will be invoked.  But we don't really copy state, of course.
  Instead we will invoke [47mld[0m on the live state, which is always
  available in the von Neumann world in which ACL2 is implemented.
  To give the illusion of copying state, we will undo changes to the
  state upon exiting.  To support this, we do two things just before
  invoking [47mld[0m: we bind a Common Lisp special variable, [47m*wormholep*[0m,
  to [47mt[0m to record that ACL2 is in a wormhole, and we initialize an
  accumulator that will be used to record state changes made while in
  the wormhole.  Then we assign the three state globals
  [47mwormhole-name[0m, [47mwormhole-input[0m, and [47mwormhole-status[0m.  Those
  assignments are made undoably since [47m*wormholep*[0m is set.

  Then [47mld[0m is invoked, with first argument, [47mstandard-oi[0m, being set to
  [47m(cons form *standard-oi*)[0m.  According to the standard semantics of
  [47mld[0m, the first read from this [47mstandard-oi[0m returns [47mform[0m and
  subsequent reads, if any, come from [47m*standard-oi*[0m.  The standard
  channels are directed to and from the terminal, which is the
  physical realization of the comment window.

  All state modifying functions of ACL2 are sensitive to the special
  variable [47m*wormholep*[0m that indicates that evaluation is in a
  wormhole.  Some ACL2 state-modifying functions (e.g., those that
  modify the file system like [47m[write-byte$][0m) are made to cause an
  error if invoked inside a wormhole on a file other than the
  terminal.  Others, like [47mf-put-global[0m (the function behind such
  features as [47massign[0m and maintenance of the ACL2 logical world by
  such events as [47m[defun][0m and [47m[defthm][0m) are made to record the old
  value of the state component being changed; these records are kept
  in the accumulator initialized above.

  Upon exit from [47mld[0m for any reason, the ephemeral-whs is transferred to
  the persistent-whs, i.e., the final value of [47m(@ wormhole-status)[0m is
  stored under the current [47mwormhole-name[0m in [47m*wormhole-status-alist*[0m
  and then the accumulator is used to ``undo'' all the state changes.

  [47mWormhole[0m always returns [47mnil[0m.

  The system wormhole named [47mbrr[0m, which implements [break-rewrite], is
  treated a little differently.  When [47mld[0m exits due to an abort the
  ephemeral-whs is not transferred to the persistent-whs.  Instead,
  the persistent-whs is set to what it was at the time break-rewrite
  was first entered from the top-level.  See the Essay on
  Break-Rewrite in the source code file [47mrewrite.lisp[0m for details
  about the implementation of break-rewrite, which is intimately
  connected to wormholes.")
 (WORMHOLE-P
  (WORMHOLE)
  "Predicate to determine if you are inside a [47m[wormhole][0m

  See [wormhole] for a discussion of wormholes.  [47m(Wormhole-p state)[0m
  returns [47m(mv nil t state)[0m when evaluated inside a wormhole, else [47m(mv
  nil nil state)[0m.")
 (WORMHOLE-PROGRAMMING-TIPS
  (WORMHOLE WORMHOLE-EVAL)
  "some tips for how to use wormholes

  Wormholes allow one to collect data and print without having access
  to ACL2's [47m[state][0m.  Many ACL2 utilities are implemented in terms of
  wormholes.  Examples include [break-rewrite],
  [47m[accumulated-persistence][0m, and [47m[forward-chaining-reports][0m.  So an
  ACL2 developer wishing to add features or fixing misbehaviors in
  these system utilities must be familiar with programming wormholes.
  But users might also employ wormholes to implement utilities in
  their own models.  Thus, this documentation topic is as much for
  future ACL2 developers and maintainers as for ACL2 users (but items
  meant primarily for developers often include references to
  functions in the ACL2 source code which other users may just
  ignore).  This is simply a list of tips for a person programming
  with wormholes.  This list doesn't replace the topics [47m[wormhole][0m
  and [47m[wormhole-eval][0m, and their subtopics including the particularly
  relevant [wormhole-status].  But this list of tips might serve as a
  useful reminder when you're programming with wormholes.

    * The ``function'' [47m[wormhole][0m is really a macro that expands in raw
      Lisp into a call of [47m[wormhole-eval][0m to set the entry code and
      then a call of [47mwormhole1[0m to do the interactive work.  But in
      addition, the source code functions [47mev-rec[0m,
      [47mtranslate11-wormhole-eval[0m, [47mtranslate11-call-1[0m, and
      [47mtranslate11-call[0m all contain special provisions for wormholes.
      Do not think you can add features to wormholes by just changing
      the definition of [47mwormhole[0m or [47mwormhole1[0m!  These functions are
      in what we call the wormhole implementation nexus and there is
      entitled ``[47m; Essay on the Wormhole Implementation Nexus[0m'' in
      the source file [47maxioms.lisp[0m.

    * The built-in ACL2 system wormholes are protected by mechanisms in
      [47mtranslate11-call-1[0m and [47mtranslate11-call[0m so that code executed
      during ACL2's boot-strapping process is allowed to manipulate
      system wormholes but code executed after boot-strap cannot.
      Search the source code for occurrences of
      [47m*protected-system-wormhole-names*[0m.

    * System implementors and maintainers may be hampered by being unable
      to invoke wormhole functions on system wormholes like [47mbrr[0m or
      [47maccumulated-persistence[0m.  One way around that, e.g., to test
      changes to existing code, is to execute [47m(defconst
      *protected-system-wormhole-names* nil)[0m after doing [47m(redef+)[0m.

    * Users may wish to employ wormholes so they can build tools allowing
      the [47m[state][0m-less exploration of their models.  But we confess
      that to make wormholes as useful to other tool developers as
      they are to the ACL2 developers we will need to add some
      protection features (similar to those in the item above) to
      user-defined wormholes.  Ideas we have toyed with but not
      implemented include pairing a wormhole's name with various
      attributes such as a flag to prevent its use except through
      named interfaces, a wrapper form or filter that applies to
      every form read, translated, and evaluated by the [47mld[0m inside
      that wormhole, and what should happen when the wormhole is
      exited.  But these ideas are not implemented.  If you really
      need them, let us know.

    * Each wormhole has a name, which is typically but not necessarily a
      symbol.

    * Each wormhole has a current status.  The status is a cons whose [47mcar[0m
      is either [47m:ENTER[0m or [47m:SKIP[0m, and whose [47mcdr[0m is an arbitrary ACL2
      object managed by the creator of the wormhole.  The [47mcar[0m of the
      status is called the ``entry code''.  The [47mcdr[0m is called the
      ``data''.  See [47m[wormhole-entry-code][0m, [47m[wormhole-data][0m, and
      [47m[make-wormhole-status][0m.

    * The status object of a wormhole named [47mnm[0m is stored in raw Lisp in a
      part of memory inaccessible to ACL2 terms other than the ACL2
      oracle (see [47m[read-ACL2-oracle][0m).  We call this the [3mpersistent
      wormhole status[0m or [3mpersistent-whs[0m.  If you're in raw Lisp ---
      which you can reach by exiting the ACL2 loop with [47m:q[0m or by
      invoking [47m[break$][0m --- you can recover the persistent-whs of the
      [47mnm[0m wormhole with [47m(cdr (assoc nm *wormhole-status-alist*))[0m.
      However, the logic-mode function [47m[get-persistent-whs][0m takes a
      name and [47mstate[0m returns an error triple containing the
      persistent status.  [47mGet-persistent-whs[0m reads the ACL2 oracle
      (see [read-ACL2-oracle]) to get the otherwise hidden status of
      the wormhole.  In doing so it changes the state.  So if you're
      not in a context in which you have [47mstate[0m and can return a
      modified state, you can't use [47mget-persistent-whs[0m.

    * [47m[Wormhole-eval][0m gives you a way, without access to state, to set the
      persistent-whs of a named wormhole as a function of its current
      persistent-whs.  [47mWormhole-eval[0m takes a wormhole name, a lambda
      expression, and a term (which is functionally irrelevant),
      applies the lambda expression to the persistent-whs, stores as
      the new persistent-whs, and returns [47mnil[0m.

    * [47m[Wormhole][0m is a function that allows you to set and test the status
      of a named wormhole and if the resulting status has an entry
      code of [47m:enter[0m you will enter a read-eval-print loop.  Wormhole
      has two other arguments, the so-called ``input'' object and the
      ``first form'' to execute if and when the loop is entered.

    * The read-eval-print loop is managed by [47m[ld][0m, the same function that
      manages ACL2's top-level read-eval-print loop.  The [47mwormhole[0m
      function allows you to specify the standard [47mld[0m variables (e.g.,
      [47m[ld-error-action][0m, etc.).  One of those variables is
      [47m[ld-keyword-aliases][0m which specifies the behaviors of keyword
      commands issued in the wormhole's loop.

    * Before [47mwormhole[0m (actually [47mwormhole1[0m) calls [47mld[0m it sets the three
      important state global variables mentioned below.  Then while
      in the interactive loop:

          (@ wormhole-name) = nm

          (@ wormhole-input) = the ``input'' object supplied to wormhole

          (@ wormhole-status) = the wormhole's persistent-whs at the time of entry

    * When inside the interactive loop of the wormhole we call the value of
      [47mwormhole-status[0m the [3mephemeral wormhole status[0m or [3mephemeral-whs[0m.
      It ``disappears'' when the wormhole is exited but it is easy to
      read without changing state while inside the wormhole.

    * The ``first form'' is very often the only form executed!  We
      typically use that form to grab the input and the status and
      print stuff.  Then the first form returns [47m(value :q)[0m.  Recall
      that typing [47m(value :q)[0m to the ACL2 loop (i.e., to [47m[ld][0m) exits
      the loop, which exits the wormhole.  See the example in the
      documentation topic [47m[wormhole][0m, starting with \"[47m(wormhole
      'demo[0m\".  If the first form returns any other non-erroneous
      value triple, user input is read and evaluated.  So if your
      first form always returns [47m(value :q)[0m you're in complete control
      of your wormhole --- and if it doesn't, you're not because the
      next thing that happens is the wormhole reads and evaluates
      whatever the user types!

    * The use of [47mld[0m to manage the read-eval-print loop means that the user
      can execute virtually any ACL2 term.  If you use [47mwormhole[0m and
      allow input from the user, you have no control over the
      operations performed.

    * If, while in the [47mnm[0m wormhole, you execute [47m(wormhole-eval nm ...)[0m it
      will set the persistent-whs but not set the ephemeral-whs.
      (Recall, [47mwormhole-eval[0m does not have access to [47mstate[0m.)  This
      means that you can't trust [47m(@ wormhole-status)[0m after a call of
      [47mwormhole-eval[0m --- or of any function that calls [47mwormhole-eval[0m
      --- from within the wormhole.

    * This brings us to the [3mWormhole Coherence Convention[0m.  The problem
      described in the bullet above is akin to the cache coherence
      problem.  Think of the persistent-whs stored in
      [47m*wormhole-status-alist*[0m as being stored in a distant memory
      location and the ephemeral-whs stored in [47m(@ wormhole-status)[0m as
      a nearby, easily accessible cache when you're in the wormhole.
      [47mWormhole-eval[0m reads and writes the persistent-whs and does not
      update the cache.  The Wormhole Coherence Convention is to keep
      persistent-whs and the ephemeral-whs equal.  Of course, the
      convention is meant to hold except in the region of code
      between updating the two locations.

    * The wormhole programmer is responsible for maintaining the wormhole
      coherence --- or not.  It's up to you.  But remember: if your
      wormhole permits user interaction, you can't prevent the
      execution of certain forms.

    * The state global variable [47mwormhole-status[0m is untouchable, so the user
      cannot just execute [47m(assign wormhole-status new-status)[0m to
      change it.  But [47mwormhole-status[0m can be changed by certain
      special functions available to the user, namely
      [47m[sync-ephemeral-whs-with-persistent-whs][0m and
      [47m[set-persistent-whs-and-ephemeral-whs][0m, though these will only
      have effect after executing [47m[wormhole-eval][0m or [47m[wormhole][0m.

    * We have already mentioned [47mwormhole-eval[0m, which writes to the
      persistent-whs not to the ephemeral-whs.  But the other two
      utilities mentioned above are helpful in establishing and
      maintaining coherence.

    * [47m(sync-ephemeral-whs-with-persistent-whs nm state)[0m moves the
      ``distant'' memory status into the cached status.  It returns
      the modified state.

    * [47m(set-persistent-whs-and-ephemeral-whs nm new-status state)[0m writes
      [47mnew-status[0m to the persistent-whs of [47mnm[0m and, if you're in the
      wormhole [47mnm[0m, it also updates the ephemeral-whs status.  It
      returns a new state.

    * Using [47msync-ephemeral-whs-with-persistent-whs[0m and
      [47mset-persistent-whs-and-ephemeral-whs[0m you can program your
      wormhole operations to establish and maintain coherence.  But
      you can't prevent the user from breaking it if you allow user
      interaction.

    * While it may seem that [47mset-persistent-whs-and-ephemeral-whs[0m is the
      preferred way to update the status of a wormhole, that function
      suffers from the requirement that you have to have the new
      status in hand when you call
      [47mset-persistent-whs-and-ephemeral-whs[0m.  So from a practical
      perspective [47mset-persistent-whs-and-ephemeral-whs[0m is either used
      outside the wormhole to initialize the status to some standard
      value or is used inside the wormhole after having obtained the
      current status from the cache and modifying it to create the
      new status.

    * Both [47msync-ephemeral-whs-with-persistent-whs[0m and
      [47mset-persistent-whs-and-ephemeral-whs[0m take and return [47mstate[0m and
      so can only be used in contexts allowing that.

    * In contrast, [47mwormhole-eval[0m allows you to compute the new status as a
      function of the old status, [3mWITHOUT HAVING PRIOR ACCESS[0m to the
      old status and without access to [47mstate[0m.  But then remember to
      call [47msync-ephemeral-whs-with-persistent-whs[0m, which will restore
      coherence.

    * The most direct way to establish and maintain the wormhole coherence
      is to avoid use of fully interactive calls of [47mwormhole[0m (i.e.,
      make sure the first form executed always returns [47m(value :q)[0m),
      and do all modifications to the wormhole status with
      [47mwormhole-eval[0m, which reads and writes the persistent-whs.  For
      example, search the ACL2 sources for occurrences of
      [47m'accumulated-persistence[0m.  You'll see [47mwormhole-eval[0m is used to
      collect all the data.  Then in [47mshow-accumulated-persistence-fn[0m,
      [47mwormhole[0m is used to display the data and exit with [47m(value :q)[0m.

    * But the [47m[break-rewrite][0m wormhole, named [47mbrr[0m, is necessarily different
      because the whole intention is to allow interaction with the
      user!  So there is special code here and there throughout ACL2
      to maintain coherence.  We're sorry we don't provide suitable
      provisions for other users!

    * If you're in a wormhole, all modifications to state globals during
      the execution of the commands in the read-eval-print loop will
      be undone when the loop is exited.  This cleanup is done in the
      raw Lisp code for [47mwormhole1[0m, by evaluating the raw Lisp form
      held in [47m*wormhole-cleanup-form*[0m.  That form is destructively
      modified every time an [47mf-put-global[0m is executed from within
      some wormhole.  The modification introduces code to undo each
      [47mf-put-global[0m and restore the previous values.

    * The cleanup form just mentioned contains special code for the
      [47mbreak-rewrite[0m wormhole!  Look for [47m'brr[0m in [47mwormhole1[0m and read
      the comments.")
 (WORMHOLE-STATUS
  (WORMHOLE)
  "the two senses of a wormhole's status

  As noted in the discussion of [47mwormhole[0ms, every wormhole has a current
  status, which is some ACL2 object whose shape is largely determined
  by the author of the wormhole.  That object is not stored in the
  ACL2 state.  When the wormhole is entered, its status is assigned
  to the state global variable [47mwormhole-status[0m, making it visible.
  When the wormhole is exited, the value of [47mwormhole-status[0m is
  transferred back to its ``hidden'' location outside of the state.
  Thus, the next time it is entered the [47mwormhole-status[0m is the same
  as it was when it was last exited.

  We call the ``hidden'' version of a wormhole's status the [3mpersistent
  wormhole status[0m or [3mpersistent-whs[0m and the version occasionally
  found in the state global [47mwormhole-status[0m as the [3mephemeral wormhole
  status[0m or [3mephemeral-whs[0m.  It is helpful to think of the
  persistent-whs as the wormhole's status as stored in some distant
  location and its ephemeral-whs as an easily accessible, nearby
  cache.  When the two locations hold the same value we say the
  wormhole is [3mcoherent[0m.

  The state global variable [47mwormhole-status[0m is untouchable: you can
  read it but not directly write to it via [47m[assign][0m or
  [47m[f-put-global][0m.  But you can write to the persistent-whs.  That is
  what [47m[wormhole-eval][0m does.  So while a wormhole is coherent when
  you first enter it it can become incoherent if you use
  [47mwormhole-eval[0m to change its persistent-whs while inside the
  wormhole.  And remember, the use of [47mwormhole-eval[0m can be disguised
  via a function definition.

  The following script illustrates this.  First, create a wormhole
  named [47mdemo[0m whose data field is empty.  We'll use it to accumulate
  items without modifying state.  We define [47m(save x)[0m to cons [47mx[0m onto
  the data field of the [47mdemo[0m wormhole.  So execute these five
  commands at the top-level of ACL2.

    (wormhole-eval 'demo '(lambda nil '(:enter . nil)) nil)
    (defun save (x)
      (wormhole-eval
       'demo
       '(lambda (whs)(set-wormhole-data whs (cons x (wormhole-data whs))))
       nil))
    (save 'a)
    (save 'b)
    (save 'c)

  Then inspect the persistent-whs of [47mdemo[0m:

    ACL2 !>(get-persistent-whs 'demo state)
     (:ENTER C B A)

  So [47msave[0m works as we planned.  But now let's enter the [47mdemo[0m wormhole.
  Inside the wormhole we first inspect the ephemeral-whs (i.e., [47m(@
  wormhole-status)[0m, and the persistent-whs to confirm the wormhole is
  coherent.  Then we execute [47m(save 'd)[0m to add [47mD[0m to the accumulator.
  Inspecting the persistent-whs shows that it worked.  But the
  ephemeral-whs did not change!  The wormhole is now incoherent,
  thanks to the ``disguised'' use of [47mwormhole-eval[0m while in the
  wormhole.

    ACL2 !>(wormhole 'demo '(lambda (whs) whs) nil '(quote (welcome!)))

    Project-dir-alist:
    ((:SYSTEM . \"/Users/moore/Desktop/v85k1/books/\")).
    Type :help for help.
    Type (quit) to quit completely out of ACL2.

    Wormhole ACL2 !>(WELCOME!)
    Wormhole ACL2 !>(@ wormhole-status)
    (:ENTER C B A)
    Wormhole ACL2 !>(get-persistent-whs 'demo state)
     (:ENTER C B A)
    Wormhole ACL2 !>(save 'd)
    NIL
    Wormhole ACL2 !>(get-persistent-whs 'demo state)
     (:ENTER D C B A)
    Wormhole ACL2 !>(@ wormhole-status)
    (:ENTER C B A)
    Wormhole ACL2 !>:q
    NIL

  The [47m:q[0m above exits the wormhole.  Now re-enter the wormhole and
  inspect the ephemeral-whs and persistent-whs.

    ACL2 !>(wormhole 'demo '(lambda (whs) whs) nil '(quote (welcome back!)))

    Project-dir-alist:
    ((:SYSTEM . \"/Users/moore/Desktop/v85k1/books/\")).
    Type :help for help.
    Type (quit) to quit completely out of ACL2.

    Wormhole ACL2 !>(WELCOME BACK!)
    Wormhole ACL2 !>(@ wormhole-status)
    (:ENTER C B A)
    Wormhole ACL2 !>(get-persistent-whs 'demo state)
     (:ENTER C B A)
    Wormhole ACL2 !>(value :q)
    NIL

  The wormhole is coherent of course; wormholes are always coherent
  upon entry.  But notice the value of the data field!  It doesn't
  list [47mD[0m!  That happened because when we exited the wormhole, the
  ephemeral-whs was written back to the persistent-whs, and the
  ephemeral-whs of the incoherent status did not contain [47mD[0m.

  There are ways ensure that your wormholes remain coherent and they
  all involve using the function
  [47m[sync-ephemeral-whs-with-persistent-whs][0m, which does what its name
  says.  For example, we could have defined [47msave[0m this way instead.

    (defun save (x state)
      (prog2$
        (wormhole-eval
         'demo
         '(lambda (whs)(set-wormhole-data whs (cons x (wormhole-data whs))))
         nil)
        (sync-ephemeral-whs-with-persistent-whs 'demo state)))

  But note that we must now provide [47mstate[0m as an argument to all calls
  of [47msave[0m and [47msave[0m must return [47mstate[0m because [47m[read-ACL2-oracle][0m was
  used to reach out to the [47mpersistent-whs[0m to refresh the
  ephemeral-whs.  This means we can only call this version of [47msave[0m in
  environments in which we have [47mstate[0m and can return [47mstate[0m.

  Perhaps a better way preserve coherence is to keep [47msave[0m defined in
  the earlier, [47mstate[0m-less way but to call
  [47msync-ephemeral-whs-with-persistent-whs[0m from within the wormhole
  after we call [47m(save 'd)[0m.  That is easy enough to do if you are in
  complete control of the [47mdemo[0m wormhole.  Recall the specification of
  [47m[wormhole][0m.  If the entry [47mlambda[0m sets the [47m[wormhole-entry-code][0m to
  [47m:enter[0m, then [47m[ld][0m is invoked but the first form executed by the
  resulting read-eval-print loop is the [47mform[0m argument of [47mwormhole[0m.
  We used the [47mform[0m argument in the script above to just print a
  greeting but it can be an arbitrary form.  If [47mform[0m returns [47m(value
  nil)[0m the [47mld[0m is exited without ever giving the user the opportunity
  to type and evaluate an arbitrary form.

  But if the [47mdemo[0m wormhole allows a user to type and evaluate arbitrary
  forms (including forms like [47mwormhole-eval[0m or the [47mstate[0m-less [47msave[0m),
  there is no way to ensure coherency.  We admit this is an
  unfortunate aspect of the current design.

  The simplest way to avoid such problems is to use [47mwormhole-eval[0m
  exclusively and avoid use of the interactive read-eval-print loop
  provided by [47m[wormhole][0m, except loops intended for experts.  This is
  the approach taken by such system utilities as
  [47m[accumulated-persistence][0m and [47m[fc-report][0m: [47mwormhole-eval[0m is used to
  collect data and either [47mwormhole-eval[0m or a non-interactive [47mwormhole[0m
  is used to display it.")
 (WORMHOLE-STATUSP
  (WORMHOLE)
  "Predicate recognizing well-formed wormhole status object

    General Form:  (wormhole-statusp whs)

  See [wormhole].  This predicate is useful in guards for wormholes.
  It checks whether [47mwhs[0m is either [47mnil[0m or a cons whose car is [47m:ENTER[0m
  or [47m:SKIP[0m.")
 (WRITE-BYTE$ (POINTERS) "See [io].")
 (XARGS
  (DEFUN DECLARE)
  "Extra arguments, for example to give [hints] to [47m[defun][0m

  Common Lisp's [47m[defun][0m function does not easily allow one to pass
  extra arguments such as ``[hints]''.  ACL2 therefore supports a
  peculiar new declaration (see [declare]) designed explicitly for
  passing additional arguments to [47m[defun][0m via a keyword-like syntax.
  This declaration can also be used with [47m[defmacro][0m, but only for
  [47mxargs[0m keyword [47m:guard[0m; so we restrict attention below to use of
  [47mxargs[0m in [47m[defun][0m [events].

  The following declaration is nonsensical but does illustrate all of
  the [47mxargs[0m keywords for [47m[defun][0m (which are the members of the list
  [47m*xargs-keywords*[0m).

    (declare (xargs :guard (symbolp x)
                    :guard-debug t
                    :guard-simplify :limited
                    :guard-hints ((\"Goal\" :in-theory (theory batch1)))
                    :hints ((\"Goal\" :in-theory (theory batch1)))
                    :loop$-recursion t
                    :measure (- i j)
                    :measure-debug t
                    :mode :logic
                    :non-executable t
                    :normalize nil
                    :otf-flg t ; the default for defun
                    :ruler-extenders :basic
                    :split-types t
                    :stobjs ($s)
                    :dfs (v1 v2)
                    :type-prescription (natp (foo x y))
                    :verify-guards t
                    :well-founded-relation my-wfr))

    General Form:
    (xargs :key1 val1 ... :keyn valn)

  where the keywords and their respective values are as shown below.
  Note that once ``inside'' the xargs form, the ``extra arguments''
  to [47m[defun][0m are passed exactly as though they were keyword
  arguments.

  [47m:guard[0m
  [47mValue[0m is a term involving only the formals of the function being
  defined.  The actual [guard] used for the definition is the
  conjunction of all the [guard]s and types declared, in the order
  lexically given, preceded by conjuncts corresponding to the
  [47m:[0m[47m[stobj][0m declarations (if any, and including [47m(state-p state)[0m if
  [47mstate[0m is a formal).  Also see [declare].
  Note that if no [47m:guard[0m is specified explicitly, then a guard of [47mt[0m is
  assumed, as though one had declared [47m(xargs :guard t)[0m.  (Note that [47mt[0m
  is indeed a term involving only the formals; it specifies that the
  guard requirement is always met.)  However, by default, a [47m:[0m[47m[logic][0m
  mode function definition will not attempt to verify guards unless
  an explicit [47mxargs[0m [47m:guard[0m declaration is provided.  For details on
  this point, as well as how to change that default behavior, see
  [set-verify-guards-eagerness].

  [47m:guard-debug[0m
  [47mValue[0m: [47mnil[0m by default, else directs ACL2 to decorate each guard
  proof obligation with hypotheses indicating its sources.  See
  [guard-debug].

  [47m:guard-hints[0m
  [47mValue[0m: hints (see [hints]), to be used during the [guard]
  verification proofs as opposed to the termination proofs of the
  [47m[defun][0m.  Note that these hints apply only to guard proofs, not to
  the generation of guard proof obligations; for that, see
  [guard-simplification].

  [47m:guard-simplify[0m
  [47mValue[0m: [47mt[0m by default, which supports simplification performed while
  generating the guard proof obligation.  The value can also be
  [47m:limited[0m, which directs ACL2 to skip such simplification that
  depends on which rules are currently [enable]d.  This has the same
  effect as the corresponding keyword argument to [47m[verify-guards][0m.
  Also see [guard-simplification] and [guard-formula-utilities].

  [47m:[0m[47m[hints][0m
  Value: hints (see [hints]), to be used during the termination proofs
  as opposed to the [guard] verification proofs of the [47m[defun][0m.

  [47m:[0m[47m[loop$-recursion][0m
  Value: this flag must be set to [47mt[0m or [47mnil[0m; [47mnil[0m is the default.  The
  flag must be [47mt[0m if and only if the function being defined calls
  itself recursively from within a [47m[loop$][0m body or within a [47mwhen[0m or
  [47muntil[0m clause.  See [loop$-recursion].

  [47m:measure[0m
  [47mValue[0m is a term involving only the formals of the function being
  defined.  This term indicates what is getting smaller in the
  recursion.  The well-founded relation with which successive
  measures are compared is [47m[o<][0m by default, but can be changed using
  the [47m:well-founded-relation[0m keyword or with the
  [set-well-founded-relation] event.  Also allowed is a special case,
  [47m(:? v1 ... vk)[0m, where [47m(v1 ... vk)[0m enumerates a subset of the formal
  parameters such that some valid measure involves only those formal
  parameters.  However, this special case is only allowed for
  definitions that are redundant (see [redundant-events]) or are
  executed when skipping proofs (see [skip-proofs]).  Another special
  case is [47m:measure nil[0m, which is treated the same as if [47m:measure[0m is
  omitted.  Note that a [47m:measure[0m is not allowed for a non-recursive
  definition (other than the ``measure'' [47mnil[0m) unless the definition
  is part of a [mutual-recursion]; moreover, if a [47m:measure[0m is
  supplied, then it must be a legal term. Apart from these
  restrictions, the [47m:measure[0m is ignored in [47m:[0m[47m[program][0m mode; see
  [defun-mode].

  [47m:measure-debug[0m
  [47mValue[0m: [47mnil[0m by default, else directs ACL2 to decorate each
  termination proof obligation with hypotheses indicating its
  sources.  See [measure-debug].

  [47m:mode[0m
  [47mValue[0m is [47m:[0m[47m[program][0m or [47m:[0m[47m[logic][0m, indicating the [47m[defun][0m mode of the
  function introduced.  See [defun-mode].  If unspecified, the
  [47m[defun][0m mode defaults to the default [47m[defun][0m mode of the current
  [world].  To convert a function from [47m:[0m[47m[program][0m mode to [47m:[0m[47m[logic][0m
  mode, see [verify-termination].

  [47m:non-executable[0m
  [47mValue[0m is normally [47mt[0m or [47mnil[0m (the default).  Rather than stating
  [47m:non-executable t[0m directly, which requires [47m:[0m[47m[logic][0m mode and that
  the definitional body has a certain form, we suggest using the
  macro [47mdefun-nx[0m or [47mdefund-nx[0m; see [defun-nx].  A third value of
  [47m:non-executable[0m for advanced users is [47m:program[0m, which is generated
  by expansion of [47mdefproxy[0m forms; see [defproxy].  For another way to
  deal with non-executability, see [non-exec].

  [47m:normalize[0m
  Value is a flag telling [47m[defun][0m whether to perform certain
  simplification before storing the body of the function; see
  [normalize].  Since the default is to do such [normalization], the
  value supplied is only of interest when it is [47mnil[0m.  (See [defun]).

  [47m:[0m[47m[otf-flg][0m
  Value is a flag indicating ``Onward Through the Fog'', to keep the
  prover from starting over when it encounters a second subgoal to be
  pushed for later proof by induction.  See [otf-flg]).  The default
  is [47mt[0m when processing a [47m[defun][0m or [47m[verify-termination][0m event and
  [47mnil[0m otherwise.

  [47m:ruler-extenders[0m
  For recursive definitions (possibly mutually recursive), [47mvalue[0m
  controls termination analysis and the resulting stored induction
  scheme.  See [rulers] for a discussion of legal values and their
  effects.  See [induction-coarse-v-fine-grained] for a discussion of
  how a well-chosen [47m:ruler-extenders[0m setting may improve the
  induction scheme suggested by a function.

  [47m:[0m[47msplit-types[0m
  [47mValue[0m is [47mt[0m or [47mnil[0m, indicating whether or not [type]s are to be
  proved from the [guard]s.  The default is [47mnil[0m, indicating that type
  declarations (see [declare]) contribute to the [guard]s.  If the
  value is [47mt[0m, then instead, the expressions corresponding to the type
  declarations (see [type-spec]) are conjoined into a ``split-type
  expression,'' and guard verification insists that this term is
  implied by the specified [47m:guard[0m.  Suppose for example that a
  definition has the following [47m[declare][0m form.

    (declare (xargs :guard (p x y) :split-types t)
             (type integer x)
             (type (satisfies good-bar-p) y))

  Then for guard verification, [47m(p x y)[0m is assumed, and in addition to
  the usual proof obligations derived from the body of the
  definition, guard verification requires a proof that [47m(p x y)[0m
  implies both [47m(integerp x)[0m and [47m(good-bar-p y)[0m.  See community book
  [47mdemos/split-types-examples.lisp[0m for small examples.

  [47m:stobjs[0m
  [47mValue[0m is either a single [47m[stobj][0m name or a true list of stobj names
  (see [stobj] and see [defstobj], and perhaps see [defabsstobj]).
  Every stobj name among the formals of the function must be listed,
  if the corresponding actual is to be treated as a stobj.  That is,
  if a function uses a stobj name as a formal parameter but the name
  is not declared among the [47m:stobjs[0m then the corresponding argument
  is treated as ordinary.  The only exception to this rule is
  [47m[state][0m: whether you include it or not, [47mstate[0m is always treated as
  a single-threaded object.  This declaration has two effects.  One
  is to enforce the syntactic restrictions on single-threaded
  objects.  The other is to strengthen the [47m[guard][0m of the function
  being defined so that it includes conjuncts specifying that each
  declared single-threaded object argument satisfies the recognizer
  for the corresponding single-threaded object.

  [47m:dfs[0m
  [47mValue[0m is either a single variable or a true list of variables.  See
  [df].

  [47m:type-prescription[0m
  [47mValue[0m is either [47mnil[0m (the default) or a formula that is suitable for
  a hypothesis-free [47m:[0m[47m[type-prescription][0m rule.  That rule must be
  appropriate for the [47m:typed-term[0m that is the application of the
  defined function symbol to its formal parameters.  For example, a
  legal value for [47m:type-prescription[0m in [47m(defun f (x y) ...)[0m could be
  [47m(or (consp (f x y)) (equal (f x y) y))[0m, but not [47m(or (consp (f u v))
  (equal (f u v) v))[0m.  The specified formula must provide a type that
  is implied by the built-in type that is computed for the defined
  function.  Normally these will be equal, but if the value of
  [47m:type-prescription[0m specifies a strictly weaker type than the
  computed built-in type then a warning will be printed (unless of
  course such warnings have been suppressed; see
  [set-inhibit-output-lst] and [set-inhibit-warnings]).  It is an
  error to supply a non-[47mnil[0m value for [47m:type-prescription[0m if there is
  no built-in type computed for the function.  See also
  [type-prescription].

  [47m:[0m[47m[verify-guards][0m
  [47mValue[0m is [47mt[0m or [47mnil[0m, indicating whether or not [guard]s are to be
  verified upon completion of the termination proof.  This flag
  should only be [47mt[0m if the [47m:mode[0m is unspecified but the default
  [47m[defun][0m mode is [47m:[0m[47m[logic][0m, or else the [47m:mode[0m is [47m:[0m[47m[logic][0m.

  [47m:[0m[47m[well-founded-relation][0m
  [47mValue[0m is a function symbol that is known to be a well-founded
  relation in the sense that a rule of class [47m:well-founded-relation[0m
  has been proved about it.  The effect is to replace the default
  well-founded relation, which is typically [47m[o<][0m, by the specified
  value.  See [well-founded-relation-rule] and see
  [set-well-founded-relation] for further discussion, including how
  to change the default well-founded-relation.


Subtopics

  [Guard]
      Restricting the domain of a function

  [Measure]
      Declare a measure for a [47m[defun][0m

  [Normalize]
      Storing simplified [definition] bodies and [guard]s

  [Otf-flg]
      Allow more than one initial subgoal to be pushed for induction")
 (XOR
  (BASICS ACL2-BUILT-INS)
  "Logical ``exclusive or''

  [47mXor[0m is the ACL2 exclusive-or function.  [47m(xor P Q)[0m means that either [47mP[0m
  or [47mQ[0m, but not both, is false (i.e., [47mnil[0m).

  [31;1mFunction: [0m<xor>

    (defun xor (p q)
      (declare (xargs :guard t))
      (if p (if q nil t) (if q t nil)))")
 (YOU_MUST_THINK_ABOUT_THE_USE_OF_A_FORMULA_AS_A_RULE
  (PAGES_WRITTEN_ESPECIALLY_FOR_THE_TOURS)
  "You Must Think about the Use of a Formula as a Rule

  {IMAGE} (see
  [Using_the_Associativity_of_App_to_Prove_a_Trivial_Consequence])

  This is [31;1mgood[0m and [31;1mbad[0m.

  The good news is that you can [31;1mprogram[0m ACL2's simplifier.

  The bad news is that when you command ACL2 to prove a theorem you
  must give some thought to [31;1mhow that theorem is to be used as a rule[0m!

  For example, if after proving [47massociativity-of-app[0m as previously
  shown, you engaged in the mathematically trivial act of proving it
  again but with the equality reversed, you would have programmed
  ACL2's rewriter to loop forever.

  You can avoid adding any rule by using the command:

    (defthm associativity-of-app
      (equal (app (app a b) c)
             (app a (app b c)))
      [31;1m:rule-classes nil[0m)

  {IMAGE} (see
  [Using_the_Associativity_of_App_to_Prove_a_Trivial_Consequence])")
 (ZERO-TEST-IDIOMS
  (NUMBERS)
  "How to test for 0

  Below are six commonly used idioms for testing whether [47mx[0m is [47m0[0m.  [47m[Zip][0m
  and [47m[zp][0m are the preferred termination tests for recursions down
  the integers and naturals, respectively.

    idiom       logical              guard                 primary
                meaning                                 compiled code*

    (equal x 0) (equal x 0)          t                   (equal x 0)

    (eql x 0)   (equal x 0)          t                   (eql x 0)

    (zerop x)   (equal x 0)          x is a number       (= x 0)

    (= x 0)     (equal x 0)          x is a number       (= x 0)

    (zip x)     (equal (ifix x) 0)   x is an integer     (= x 0)

    (zp x)      (equal (nfix x) 0)   x is a natural      (int= x 0)

    (zpf x)     (equal (nfix x) 0)   x is a fixnum >= 0  (eql (the-fixnum x) 0)

  *See [guards-and-evaluation], especially the subsection titled
  ``Guards and evaluation V: efficiency issues''.  Primary code is
  relevant only if [guard]s are verified.  The ``compiled code''
  shown is only suggestive.

  The first four idioms all have the same logical meaning and differ
  only with respect to their executability and efficiency.  In the
  absence of compiler optimizing, [47m(= x 0)[0m is probably the most
  efficient, [47m(equal x 0)[0m is probably the least efficient, and [47m(eql x
  0)[0m is in between.  However, an optimizing compiler could always
  choose to compile [47m(equal x 0)[0m as [47m(eql x 0)[0m and, in situations where
  [47mx[0m is known at compile-time to be numeric, [47m(eql x 0)[0m as [47m(= x 0)[0m.  So
  efficiency considerations must, of course, be made in the context
  of the host compiler.

  Note also that [47m(zerop x)[0m and [47m(= x 0)[0m are indistinguishable.  They
  have the same meaning and the same [guard], and can reasonably be
  expected to generate equally efficient code.

  Note that [47m(zip x)[0m and [47m(zp x)[0m do not have the same logical meanings as
  the others or each other.  They are not simple tests for equality
  to [47m0[0m.  They each coerce [47mx[0m into a restricted domain, [47m[zip][0m to the
  integers and [47m[zp][0m to the natural numbers, choosing [47m0[0m for [47mx[0m when [47mx[0m
  is outside the domain.  Thus, [47m1/2[0m, [47m#c(1 3)[0m, and [47m'abc[0m, for example,
  are all ``recognized'' as zero by both [47m[zip][0m and [47m[zp][0m.  But [47m[zip][0m
  reports that [47m-1[0m is different from [47m0[0m while [47m[zp][0m reports that [47m-1[0m
  ``is'' [47m0[0m.  More precisely, [47m(zip -1)[0m is [47mnil[0m while [47m(zp -1)[0m is [47mt[0m.

  Note that the last five idioms all have [guard]s that restrict their
  Common Lisp executability.  If these last five are used in
  situations in which [guard]s are to be verified, then proof
  obligations are incurred as the price of using them.  If guard
  verification is not involved in your project, then the first five
  can be thought of as synonymous.

  [47m[Zip][0m and [47m[zp][0m are not provided by Common Lisp but are ACL2-specific
  functions.  Why does ACL2 provide these functions?  The answer has
  to do with the admission of recursively defined functions and
  efficiency.  [47m[Zp][0m is provided as the zero-test in situations where
  the controlling formal parameter is understood to be a natural
  number.  [47m[Zip][0m is analogously provided for the integer case.  We
  illustrate below.

  Here is an admissible definition of factorial

    (defun fact (n) (if (zp n) 1 (* n (fact (1- n)))))

  Observe the classic recursion scheme: a test against [47m0[0m and recursion
  by [47m[1-][0m.  Note however that the test against [47m0[0m is expressed with
  the [47m[zp][0m idiom.  Note also the absence of a [guard] making explicit
  our intention that [47mn[0m is a natural number.

  This definition of factorial is readily admitted because when [47m(zp n)[0m

  is false (i.e., [47mnil[0m) then [47mn[0m is a natural number other than [47m0[0m and so
  [47m(1- n)[0m is less than [47mn[0m.  The base case, where [47m(zp n)[0m is true,
  handles all the ``unexpected'' inputs, such as arise with [47m(fact -1)[0m
  and [47m(fact 'abc)[0m.  When calls of [47mfact[0m are evaluated, [47m(zp n)[0m checks
  [47m(integerp n)[0m and [47m(> n 0)[0m.  [Guard] verification is unsuccessful for
  this definition of [47mfact[0m because [47m[zp][0m requires its argument to be a
  natural number and there is no [guard] on [47mfact[0m, above.  Thus the
  primary raw lisp for [47mfact[0m is inaccessible and only the [47m:[0m[47m[logic][0m
  definition (which does runtime ``type'' checking) is used in
  computation.  In summary, this definition of factorial is easily
  admitted and easily manipulated by the prover but is not executed
  as efficiently as it could be.

  Runtime efficiency can be improved by adding a [guard] to the
  definition.

    (defun fact (n)
      (declare (xargs :guard (and (integerp n) (>= n 0))))
      (if (zp n) 1 (* n (fact (1- n)))))

  This [guard]ed definition has the same termination conditions as
  before --- termination is not sensitive to the [guard].  But the
  [guard]s can be verified.  This makes the primary raw lisp
  definition accessible during execution.  In that definition, the
  [47m(zp n)[0m above is compiled as [47m(= n 0)[0m, because [47mn[0m will always be a
  natural number when the primary code is executed.  Thus, by adding
  a [guard] and verifying it, the elegant and easily used definition
  of factorial is also efficiently executed on natural numbers.

  Now let us consider an alternative definition of factorial in which
  [47m(= n 0)[0m is used in place of [47m(zp n)[0m.

    (defun fact (n) (if (= n 0) 1 (* n (fact (1- n)))))

  This definition does not terminate.  For example [47m(fact -1)[0m gives rise
  to a call of [47m(fact -2)[0m, etc.  Hence, this alternative is
  inadmissible.  A plausible response is the addition of a [guard]
  restricting [47mn[0m to the naturals:

    (defun fact (n)
     (declare (xargs :guard (and (integerp n) (>= n 0))))
     (if (= n 0) 1 (* n (fact (1- n)))))

  But because the termination argument is not sensitive to the [guard],
  it is still impossible to admit this definition.  To influence the
  termination argument one must change the conditions tested.  Adding
  a runtime test that [47mn[0m is a natural number would suffice and allow
  both admission and [guard] verification.  But such a test would
  slow down the execution of the compiled function.

  The use of [47m(zp n)[0m as the test avoids this dilemma.  [47m[Zp][0m provides the
  logical equivalent of a runtime test that [47mn[0m is a natural number but
  the execution efficiency of a direct [47m[=][0m comparison with [47m0[0m, at the
  expense of a [guard] conjecture to prove.  In addition, if [guard]
  verification and most-efficient execution are not needed, then the
  use of [47m(zp n)[0m allows the admission of the function without a
  [guard] or other extraneous verbiage.

  While general rules are made to be broken, it is probably a good idea
  to get into the habit of using [47m(zp n)[0m as your terminating ``[47m0[0m
  test'' idiom when recursing down the natural numbers.  It provides
  the logical power of testing that [47mn[0m is a non-[47m0[0m natural number and
  allows efficient execution.

  We now turn to the analogous function, [47m[zip][0m.  [47m[Zip][0m is the preferred
  [47m0[0m-test idiom when recursing through the integers toward [47m0[0m.  [47m[Zip][0m
  considers any non-integer to be [47m0[0m and otherwise just recognizes [47m0[0m.
  A typical use of [47m[zip][0m is in the definition of [47m[integer-length][0m,
  shown below.  (ACL2 can actually accept this definition, but only
  after appropriate lemmas have been proved.)

    (defun integer-length (i)
      (declare (xargs :guard (integerp i)))
      (if (zip i)
          0
        (if (= i -1)
          0
          (+ 1 (integer-length (floor i 2))))))

  Observe that the function recurs by [47m(floor i 2)[0m.  Hence, calling the
  function on [47m25[0m causes calls on [47m12[0m, [47m6[0m, [47m3[0m, [47m1[0m, and [47m0[0m, while calling it
  on [47m-25[0m generates calls on [47m-13[0m, [47m-7[0m, [47m-4[0m, [47m-2[0m, and [47m-1[0m.  By making [47m(zip
  i)[0m the first test, we terminate the recursion immediately on
  non-integers.  The [guard], if present, can be verified and allows
  the primary raw lisp definition to check [47m(= i 0)[0m as the first
  terminating condition (because the primary code is executed only on
  integers).")
 (ZEROP
  (NUMBERS ACL2-BUILT-INS)
  "Test an acl2-number against 0

  [47m(zerop x)[0m is [47mt[0m if [47mx[0m is [47m0[0m and is [47mnil[0m otherwise.  Thus, it is logically
  equivalent to [47m(equal x 0)[0m.

  [47m(Zerop x)[0m has a [guard] requiring [47mx[0m to be numeric and can be expected
  to execute more efficiently than [47m(equal x 0)[0m in properly [guard]ed
  compiled code.

  In recursions down the natural numbers, [47m(zp x)[0m is preferred over
  [47m(zerop x)[0m because the former coerces [47mx[0m to a natural and allows the
  termination proof.  In recursions through the integers, [47m(zip x)[0m is
  preferred.  See [zero-test-idioms].

  [47mZerop[0m is a Common Lisp function.  See any Common Lisp documentation
  for more information.

  [31;1mFunction: [0m<zerop>

    (defun zerop (x)
      (declare (xargs :guard (acl2-numberp x)))
      (eql x 0))")
 (ZIP
  (NUMBERS ACL2-BUILT-INS)
  "Testing an ``integer'' against 0

  [47m(Zip i)[0m is logically equivalent to [47m(equal (ifix i) 0)[0m and is the
  preferred termination test for recursion through the integers.
  [47m(Zip i)[0m returns [47mt[0m if [47mi[0m is [47m0[0m or not an integer; it returns [47mnil[0m
  otherwise.  Thus,

    i         (zip i)
    3         nil
    0         t
    -2        nil
    5/2       t
    #c(1 3)   t
    'abc      t

  [47m(Zip i)[0m has a [guard] requiring [47mi[0m to be an integer.

  For a discussion of the various idioms for testing against [47m0[0m, see
  [zero-test-idioms].

  [47mZip[0m is typically used as the termination test in recursions through
  the integers.  It has the advantage of ``coercing'' its argument to
  an integer and hence allows the definition to be admitted without
  an explicit type check in the body.  [Guard] verification allows
  [47mzip[0m to be compiled as a direct [47m[=][0m-comparison with [47m0[0m.

  [31;1mFunction: [0m<zip>

    (defun zip (x)
      (declare (xargs :guard (integerp x)))
      (if (integerp x) (= x 0) t))")
 (ZP
  (NUMBERS ACL2-BUILT-INS)
  "Testing a ``natural'' against 0

  [47m(Zp n)[0m is logically equivalent to [47m(equal (nfix n) 0)[0m and is the
  preferred termination test for recursion down the natural numbers.
  [47m(Zp n)[0m returns [47mt[0m if [47mn[0m is [47m0[0m or not a natural number; it returns [47mnil[0m
  otherwise.  Thus, in the ACL2 logic (ignoring the issue of
  [guard]s):

     n       (zp n)
    3         nil
    0         t
    -1        t
    5/2       t
    #c(1 3)   t
    'abc      t

  [47m(Zp n)[0m has a [guard] requiring [47mn[0m to be a natural number.

  For a discussion of the various idioms for testing against [47m0[0m, see
  [zero-test-idioms].

  [47mZp[0m is typically used as the termination test in recursions down the
  natural numbers.  It has the advantage of ``coercing'' its argument
  to a natural and hence allows the definition to be admitted without
  an explicit type check in the body.  [Guard] verification allows [47mzp[0m
  to be compiled as a direct [47m[=][0m-comparison with [47m0[0m.

  [31;1mFunction: [0m<zp>

    (defun zp (x)
      (declare (xargs :guard (and (integerp x) (<= 0 x))))
      (if (integerp x) (<= x 0) t))")
 (ZPF
  (NUMBERS ACL2-BUILT-INS)
  "Testing a nonnegative fixnum against 0

  [47mZpf[0m is exactly the same as [47m[zp][0m, except that [47mzpf[0m is intended for, and
  faster for, fixnum arguments.  Its guard is specified with a type
  declaration, [47m(type (unsigned-byte 29) x)[0m.  (See [declare] and see
  [type-spec].)  Also see [zp].

  [31;1mFunction: [0m<zpf>

    (defun zpf (x)
      (declare (type (unsigned-byte 60) x))
      (if (integerp x) (<= x 0) t))")
 (ACL2-PC::=
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) attempt an equality (or equivalence) substitution

    Examples:
    =     -- replace the current subterm by a term equated to it in
             one of the hypotheses (if such a term exists)
    (= x) -- replace the current subterm by x, assuming that the prover
             can show that they are equal
    (= (+ x y) z)
          -- replace all occurrences of the term (+ x y) by the term z
             inside the current subterm, assuming that the prover can
             prove (equal (+ x y) z) from the current top-level
             hypotheses or that this term or (equal z (+ x y)) is among
             the current top-level hypotheses or the current governors
    (= & z)
          -- exactly the same as above, if (+ x y) is the current
             subterm
    (= (+ x y) z :hints :none)
          -- same as (= (+ x y) z), except that a new subgoal is
             created with the current goal's hypotheses and governors
             as its top-level hypotheses and (equal (+ x y) z) as its
             conclusion
    (= (+ x y) z 0)
          -- exactly the same as immediately above
    (= (p x)
       (p y)
       :equiv iff
       :otf-flg t
       :hints ((\"Subgoal 2\" :BY FOO) (\"Subgoal 1\" :use bar)))
          -- same as (= (+ x y) z), except that the prover uses
             the indicated values for otf-flg and hints, and only
             propositional (iff) equivalence is used (however, it
             must be that only propositional equivalence matters at
             the current subterm)

    General Forms:
    (= x)
    (= x y)
    (= x y :kwd1 val1 ... :kwdn valn)
    (= x y atom :kwd1 val1 ... :kwdn valn)

  where each [47m:kwdi[0m is one of [47m:hints[0m, [47m:otf-flg[0m, or [47m:equiv[0m, without
  repetition.  In the last form, [47matom[0m is a non-keyword atom and no
  [47mkwdi[0m may be [47m:hints[0m; that atom, if supplied, is equivalent to [47m:hints
  atom[0m, which indicates that instead of performing a proof that the
  two indicated terms (as described below) are suitably equivalent, a
  new such goal is created.

  If terms [47mx[0m and [47my[0m are supplied, then replace [47mx[0m by [47my[0m everywhere inside
  the current subterm if they are ``known'' to be equal, or more
  generally, equivalent in the sense described below.  Here ``known''
  means the following: except in the cases that no arguments are
  provided or else [47m:hints atom[0m is provided as described above, the
  prover is called as in the [47mprove[0m command (using keyword arguments
  [47m:otf[0m and [47m:hints[0m, if supplied, where the value of [47m:hints[0m is not an
  atom) to prove equivalence of [47mx[0m and [47my[0m under the current governors
  and top-level hypotheses.  By default, this equivalence is
  equality; however the keyword argument [47m:equiv[0m can specify a known
  equivalence relation.  In cases other than equality, substitution
  only takes place where justified by the equivalence maintained at
  the current subterm.

  For the keyword arguments, [47m:equiv[0m defaults to [47mequal[0m if not supplied
  or [47mnil[0m; if it is not [47mequal[0m (either explicitly or by default), then
  it should be the name of a known ACL2 [equivalence] relation, and
  substitution will only take place at subterm occurrences for which
  the [47m:equiv[0m is among the [equivalence] relations being maintained
  without the use of [patterned-congruence]s.


Remarks on defaults

    * If there are at least two arguments, then [47mx[0m may be the symbol [47m&[0m, in
      any package except the keyword package, which represents the
      current subterm.

    * The one-argument command [47m(= a)[0m is equivalent to [47m(= & a)[0m.

    * If there are no arguments, then we look for a top-level hypothesis or
      a governor of the form [47m(equal c u)[0m or [47m(equal u c)[0m, where [47mc[0m is
      the current subterm.  In that case we replace the current
      subterm by [47mu[0m.

    * As with the [47mprove[0m command, we allow goals to be given ``bye''s in the
      proof, which may be generated by a [47m:hints[0m keyword argument in
      [47mkeyword-args[0m.  These result in the creation of new subgoals.

    * It is allowed to use abbreviations (see [ACL2-pc::add-abbreviation])
      in the hints.")
 (ACL2-PC::ACL2-WRAP
  (PROOF-BUILDER-COMMANDS)
  "(macro) same as [47m(lisp x)[0m

    Example:
    (acl2-wrap (pe :here))

    General Form:
    (acl2-wrap form)

  Same as [47m(lisp form)[0m.  This is provided for interface tools that want
  to be able to execute the same form in raw Lisp, in the
  proof-builder, or in the ACL2 top-level loop [47m(lp)[0m.")
 (ACL2-PC::ADD-ABBREVIATION
  (PROOF-BUILDER-COMMANDS)
  "(primitive) add an abbreviation

  Example: [47m(add-abbreviation v (* x y))[0m causes future occurrences of [47m(*
  x y)[0m to be printed as [47m(? v)[0m, until (unless) a corresponding
  invocation of [47mremove-abbreviations[0m occurs.  In this case we say
  that [47mv[0m ``abbreviates'' [47m(* x y)[0m.

    General Form:
    (add-abbreviation var &optional raw-term)

  Let [47mvar[0m be an abbreviation for [47mraw-term[0m, if [47mraw-term[0m is supplied,
  else for the current subterm.  Note that [47mvar[0m must be a variable
  that does not already abbreviate some term.

  A way to think of abbreviations is as follows.  Imagine that whenever
  an abbreviation is added, say [47mv[0m abbreviates [47mexpr[0m, an entry
  associating [47mv[0m to [47mexpr[0m is made in an association list, which we will
  call ``[47m*abbreviations-alist*[0m''.  Then simply imagine that [47m?[0m is a
  function defined by something like:

    (defun ? (v)
      (let ((pair (assoc v *abbreviations-alist*)))
        (if pair (cdr pair)
          (error ...))))

  Of course the implementation isn't exactly like that, since the
  ``constant'' [47m*abbreviations-alist*[0m actually changes each time an
  [47madd-abbreviation[0m instruction is successfully invoked.
  Nevertheless, if one imagines an appropriate redefinition of the
  ``constant'' [47m*abbreviations-alist*[0m each time an [47madd-abbreviation[0m is
  invoked, then one will have a clear model of the meaning of such an
  instruction.

  The effect of abbreviations on output is that before printing a term,
  each subterm that is abbreviated by a variable [47mv[0m is first replaced
  by [47m(?  v)[0m.

  The effect of abbreviations on input is that every built-in
  proof-builder command accepts abbreviations wherever a term is
  expected as an argument, i.e., accepts the syntax [47m(? v)[0m whenever [47mv[0m
  abbreviates a term.  For example, the second argument of
  [47madd-abbreviation[0m may itself use abbreviations that have been
  defined by previous [47madd-abbreviation[0m instructions.

  See also [ACL2-pc::remove-abbreviations] and see
  [ACL2-pc::show-abbreviations].")
 (ACL2-PC::AL
  (PROOF-BUILDER-COMMANDS)
  "(macro) same as apply-linear

    Example:
    (al 3)

  See [ACL2-pc::apply-linear], as [47mal[0m and [47mapply-linear[0m are identical.")
 (ACL2-PC::APPLY-LINEAR
  (PROOF-BUILDER-COMMANDS)
  "(primitive) apply a linear rule

    Examples:
    (apply-linear foo)
       -- apply the linear rule `foo'
    (apply-linear (:linear foo))
       -- same as above
    (apply-linear 2)
       -- apply the second linear rule, as displayed by show-linears
    rewrite
       -- apply the first rewrite rule, as displayed by show-rewrites
    (apply-linear foo ((y 7)))
       -- apply the linear rule foo with the substitution
          that associates 7 to the ``free variable'' y
    (apply-linear foo ((x 2) (y 3)) t)
       -- apply the linear rule foo by substituting 2 and 3 for free
          variables x and y, respectively, and also binding all other
          free variables possible by using the current context
          (hypotheses and governors)

    General Form:
    (apply-linear &optional rule-id substitution instantiate-free)

  Add a new top-level hypothesis by applying a [linear] rule to the
  current subterm.  The new hypothesis will be created according to
  the information provided by the [47mshow-linears[0m ([47msls[0m) command.

  A short name for this command is [47mal[0m.

  We assume familiarity with the interactive [proof-builder]'s [47mrewrite[0m
  ([47mr[0m) command (see [ACL2-pc::rewrite]).  In brief, the [47mapply-linear[0m
  command is an analogue of the [47mrewrite[0m command, but for [linear]
  rules in place of [rewrite] rules.  There is a significant
  difference: for the [47mapply-linear[0m command, instead of rewriting the
  current subterm as is done by the [47mrewrite[0m command, the conclusion
  of the applicable linear rule, suitably instantiated, is added as a
  new (and last) top-level hypothesis of the goal.  There is another
  significant difference: the automatic application of [linear] rules
  in the theorem prover is somewhat more complex than the automatic
  application of [rewrite] rules, so the [47mapply-linear[0m command may not
  correspond as closely to the prover's automatic use of a linear
  rule as the [47mrewrite[0m command corresponds to the prover's automatic
  use of a rewrite rule.

  Below, we refer freely to the [documentation] for the interactive
  proof-builder's [47mrewrite[0m command (see [ACL2-pc::rewrite]).

  The [47mrule-id[0m is treated just as it is by the [47mrewrite[0m command.  If
  [47mrule-id[0m is a positive integer [47mn[0m, then the [47mn[0mth rule as displayed by
  [47mshow-linears[0m is the one that is applied.  If [47mrule-id[0m is [47mnil[0m or is
  not supplied, then it is treated as the number 1.  Otherwise,
  [47mrule-id[0m should be either a symbol or else a [47m:linear[0m [rune].  If a
  symbol is supplied, then any [linear] rule of that name may be
  used.

  Consider the following example.  Suppose that the current subterm is
  [47m(< (g (h y)) y)[0m and that [47mfoo[0m is the name of the following linear
  rule.

    (implies (true-listp x)
             (< (g x) 15))

  Then the instruction [47m(apply-linear foo)[0m applies [47mfoo[0m by adding a new
  hypothesis [47m(< (g (h y)) 15)[0m.  In addition, a new goal with
  conclusion [47m(true-listp y)[0m is created unless the current context
  (top-level hypotheses and governors) implies [47m(true-listp y)[0m using
  only ``trivial reasoning'', just as for the [47mrewrite[0m command.

  If the [47mrule-id[0m argument is a number or is not supplied, then the
  system will store an instruction of the form [47m(apply-linear name
  ...)[0m, where [47mname[0m is the name of a [linear] rule; this is in order
  to make it easier to replay instructions when there have been
  changes to the history.  Except: instead of the name (whether the
  name is supplied or calculated), the system stores the [rune] if
  there is any chance of ambiguity.  (Formally, ``ambiguity'' here
  means that the rune being applied is of the form [47m(:rewrite name .
  index)[0m, where index is not [47mnil[0m.)

  Speaking in general, then, an [47mapply-linear[0m instruction works as
  follows.

  First, a [linear] rule is selected according to the arguments of the
  instruction.  The selection is made as explained under ``General
  Form'' above.

  Next, a trigger term of the rule (see [linear]) is matched with the
  current subterm, i.e., a substitution [47munify-subst[0m is found such
  that if one instantiates that trigger term of the rule with
  [47munify-subst[0m, then one obtains the current subterm.  If this match
  fails, then the instruction fails.

  Next, an attempt is made to relieve (discharge) the hypotheses,
  possibly handling free variables (see [free-variables]), exactly as
  is done with hypotheses when applying the interactive
  [proof-builder] command, [47mrewrite[0m ([47mr[0m).

  Finally, the instruction is applied exactly as the [47mrewrite[0m
  instruction is applied, except instead of replacing the current
  subterm, the rule's instantiated conclusion is added to the end of
  the list of top-level hypotheses of the goal.

  Note that as for the [47mrewrite[0m command, the substitution argument
  should be a list whose elements have the form [47m(variable term)[0m,
  where [47mterm[0m may contain abbreviations.")
 (ACL2-PC::BASH
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) call the ACL2 theorem prover's simplifier

    Examples:
    bash -- attempt to prove the current goal by simplification alone
    (bash (\"Subgoal 2\" :by foo) (\"Subgoal 1\" :use bar))
         -- attempt to prove the current goal by simplification alone,
            with the indicated hints

    General Form:
    (bash &rest hints)

  Call the theorem prover's simplifier, creating a subgoal for each
  resulting goal.

  Notice that unlike [47mprove[0m, the arguments to [47mbash[0m are spread out, and
  are all hints.

  [47mBash[0m is similar to [47mreduce[0m in that neither of these allows induction.
  But [47mbash[0m only allows simplification, while [47mreduce[0m allows processes
  [47meliminate-destructors[0m, [47mfertilize[0m, [47mgeneralize[0m, and
  [47meliminate-irrelevance[0m.

  [31;1mRemark:[0m All forcing rounds will be skipped (unless there are more
  than 15 subgoals generated in the first forcing round, an injustice
  that should be rectified, but might remain unless there is pressure
  to fix it).")
 (ACL2-PC::BDD
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) prove the current goal using bdds

    Examples:
    bdd
    (bdd :vars nil :bdd-constructors (cons) :prove t :literal :all)

  The general form is as shown in the latter example above, but with
  any keyword-value pairs omitted and with values as described for
  the [47m:[0m[47m[bdd][0m hint; see [hints].

  This command simply calls the theorem prover with the indicated bdd
  hint for the top-level goal.  Note that if [47m:prove[0m is [47mt[0m (the
  default), then the proof will succeed entirely using bdds or else
  it will fail immediately.  See [bdd].")
 (ACL2-PC::BK
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) move backward one argument in the enclosing term

    Example and General Form:
    bk

  For example, if the conclusion is [47m(= x (* (- y) z))[0m and the current
  subterm is [47m(* (- y) z)[0m, then after executing [47mbk[0m, the current
  subterm will be [47mx[0m.

  Move to the previous argument of the enclosing term.

  This is the same as [47mup[0m followed by [47m(dive n-1)[0m, where [47mn[0m is the
  position of the current subterm in its parent term in the
  conclusion.  Thus in particular, the [47mnx[0m command fails if one is
  already at the top of the conclusion.

  Also see [ACL2-pc::up], [ACL2-pc::dive], [ACL2-pc::top], and
  [ACL2-pc::nx].")
 (ACL2-PC::BOOKMARK
  (PROOF-BUILDER-COMMANDS)
  "(macro) insert matching ``bookends'' comments

    Example:
    (bookmark final-goal)

    General Form:
    (bookmark name &rest instruction-list)

  Run the instructions in [47minstruction-list[0m (as though this were a call
  of [47mdo-all[0m; see [ACL2-pc::do-all]), but first insert a begin bookend
  with the given name and then, when the instructions have been
  completed, insert an end bookend with that same name.  See
  [ACL2-pc::comm] for an explanation of bookends and how they can
  affect the display of instructions.")
 (ACL2-PC::CASESPLIT
  (PROOF-BUILDER-COMMANDS)
  "(primitive) split into two cases

    Example:
    (casesplit (< x y)) -- assuming that we are at the top of the
                           conclusion, add (< x y) as a new top-level
                           hypothesis in the current goal, and create a
                           subgoal identical to the current goal except
                           that it has (not (< x y)) as a new top-level
                           hypothesis

    General Form:
    (casesplit expr &optional use-hyps-flag do-not-flatten-flag)

  When the current subterm is the entire conclusion, this instruction
  adds [47mexpr[0m as a new top-level hypothesis, and create a subgoal
  identical to the existing current goal except that it has the
  negation of [47mexpr[0m as a new top-level hypothesis.  Also see
  [ACL2-pc::claim].  The optional arguments control the use of
  governors and the ``flattening'' of new hypotheses, as we now
  explain.

  The argument [47muse-hyps-flag[0m is only of interest when there are
  governors.  (To read about governors, see [ACL2-pc::hyps]).  In
  that case, if [47muse-hyps-flag[0m is not supplied or is [47mnil[0m, then the
  description above is correct; but otherwise, it is not [47mexpr[0m but
  rather it is [47m(implies govs expr)[0m that is added as a new top-level
  hypothesis (and whose negation is added as a top-level hypothesis
  for the new goal), where [47mgovs[0m is the conjunction of the governors.

  If [47mdo-not-flatten-flag[0m is supplied and not [47mnil[0m, then that is all
  there is to this command.  Otherwise (thus this is the default),
  when the claimed term (first argument) is a conjunction ([47mand[0m) of
  terms and the [47mclaim[0m instruction succeeds, then each (nested)
  conjunct of the claimed term is added as a separate new top-level
  hypothesis.  Consider the following example, assuming there are no
  governors.

    (casesplit (and (and (< x y) (integerp a)) (equal r s)) t)

  Three new top-level hypotheses are added to the current goal, namely
  [47m(< x y)[0m, [47m(integerp a)[0m, and [47m(equal r s)[0m.  In that case, only one
  hypothesis is added to create the new goal, namely the negation of
  [47m(and (< x y) (integerp a) (equal r s))[0m.  If the negation of this
  term had been [47mclaim[0med, then it would be the other way around: the
  current goal would get a single new hypothesis while the new goal
  would be created by adding three hypotheses.

  [31;1mRemark:[0m It is allowed to use abbreviations in the hints.")
 (ACL2-PC::CG
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) change to another goal.

    Examples:
    (cg (main . 1)) -- change to the goal (main . 1)
    cg              -- change to the next-to-top goal

    General Form:
    (CG &OPTIONAL goal-name)

  Same as [47m(change-goal goal-name t)[0m, i.e. change to the indicated and
  move the current goal to the end of the goal stack.")
 (ACL2-PC::CHANGE-GOAL
  (PROOF-BUILDER-COMMANDS)
  "(primitive) change to another goal.

    Examples:
    (change-goal (main . 1)) -- change to the goal (main . 1)
    change-goal              -- change to the next-to-top goal

    General Form:
    (change-goal &optional goal-name end-flg)

  Change to the goal with the name [47mgoal-name[0m, i.e. make it the current
  goal.  However, if [47mgoal-name[0m is [47mnil[0m or is not supplied, then it
  defaults to the next-to-top goal, i.e., the second goal in the
  stack of goals.  If [47mend-flg[0m is supplied and not [47mnil[0m, then move the
  current goal to the end of the goal stack; else merely swap it with
  the next-to-top goal.  Also see [ACL2-pc::cg].")
 (ACL2-PC::CL-PROC
  (PROOF-BUILDER-COMMANDS)
  "(macro) same as [47mclause-processor[0m

  This is simply an abbreviation for [ACL2-pc::clause-processor].")
 (ACL2-PC::CLAIM
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) add a new hypothesis

    Examples:
    (claim (< x y))   -- attempt to prove (< x y) from the current
                         top-level hypotheses and if successful, then
                         add (< x y) as a new top-level hypothesis in
                         the current goal
    (claim (< x y)
           :otf-flg t
           :hints ((\"Goal\" :induct t)))
                      -- as above, but call the prover using the
                         indicated values for the otf-flg and hints
    (claim (< x y) 0) -- as above, except instead of attempting to
                         prove (< x y), create a new subgoal with the
                         same top-level hypotheses as the current goal
                         that has (< x y) as its conclusion
    (claim (< x y) :hints :none)
                      -- same as immediately above

    General Form:
    (claim expr &rest rest-args)

  This command creates a new subgoal with the same top-level hypotheses
  as the current goal but with a conclusion of [47mexpr[0m.  If [47mrest-args[0m is
  a non-empty list headed by a non-keyword, then there will be no
  proof attempted for the new subgoal.  With that possible exception,
  [47mrest-args[0m should consist of keyword arguments.  The keyword
  argument [47m:do-not-flatten[0m controls the ``flattening'' of new
  hypotheses, just as with the [47mcasesplit[0m command (see
  [ACL2-pc::casesplit]).  The remaining [47mrest-args[0m are used with a
  call the [47mprove[0m command on the new subgoal, except that if [47m:hints[0m is
  a non-[47mnil[0m atom, then the prover is not called --- rather, this is
  the same as the situation described above, where [47mrest-args[0m is a
  non-empty list headed by a non-keyword.

  [31;1mRemarks:[0m (1) Unlike the [47mcasesplit[0m command, the [47mclaim[0m command is
  completely insensitive to governors. (2) It is allowed to use
  abbreviations in the hints.  (3) The keyword [47m:[0m[47mnone[0m has the special
  role as a value of [47m:[0m[47mhints[0m that is shown clearly in an example
  above.")
 (ACL2-PC::CLAUSE-PROCESSOR
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) use a clause-processor

    Example:
    (cl-proc :function
             note-fact-clause-processor
            :hint '(equal a a)) -- Invoke the indicated clause processor function
            with the indicated hint argument (see the beginning of community book
            [47mbooks/clause-processors/basic-examples.lisp[0m.

    General Form:
    (cl-proc &rest cl-proc-args)

  Invoke a clause-processor as indicated by cl-proc-args, which is a
  list of arguments that can serve as the value of a
  [47m:[0m[47m[clause-processor][0m hint; see [hints].

  This command calls the [47mprove[0m command, and hence should only be used
  at the top of the conclusion.")
 (ACL2-PC::COMM
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) display instructions from the current interactive session

    Examples:
    comm
    (comm 10)

    General Form:
    (comm &optional n)

  Prints out instructions in reverse order.  This is actually the same
  as [47m(commands n t)[0m --- or, [47m(commands nil t)[0m if [47mn[0m is not supplied.
  As for [47mcommands[0m (see [ACL2-pc::commands]), the final argument of [47mt[0m
  causes suppression of instructions occurring between so-called
  ``matching bookends,'' which we now explain.

  A ``begin bookend'' is an instruction of the form

    (COMMENT :BEGIN x . y).

  Similarly, an ``end bookend'' is an instruction of the form

    (COMMENT :END x' . y').

  The ``name'' of the first bookend is [47mx[0m and the ``name'' of the second
  bookend is [47mx'[0m.  When such a pair of instructions occurs in the
  current state-stack, we call them ``matching bookends'' provided
  that they have the same name (i.e. [47mx[0m equals [47mx'[0m) and if no other
  begin or end bookend with name [47mx[0m occurs between them.  The idea now
  is that [47mcomm[0m hides matching bookends together with the instructions
  they enclose.  Here is a more precise explanation of this
  ``hiding''; probably there is no value in reading on!

  A [47mcomm[0m instruction hides bookends in the following manner.  (So does
  a [47mcomment[0m instruction when its second optional argument is supplied
  and non-[47mnil[0m.)  First, if the first argument [47mn[0m is supplied and not
  [47mnil[0m, then we consider only the last [47mn[0m instructions from the
  state-stack; otherwise, we consider them all.  Now the resulting
  list of instructions is replaced by the result of applying the
  following process to each pair of matching bookends: the pair is
  removed, together with everything in between the begin and end
  bookend of the pair, and all this is replaced by the
  ``instruction''

    (\"***HIDING***\" :COMMENT :BEGIN name ...)

  where [47m(comment begin name ...)[0m is the begin bookend of the pair.
  Finally, after applying this process to each pair of matching
  bookends, each begin bookend of the form [47m(comment begin name ...)[0m
  that remains is replaced by

    (\"***UNFINISHED***\" :COMMENT :BEGIN name ...) .")
 (ACL2-PC::COMMANDS
  (PROOF-BUILDER-COMMANDS)
  "(macro) display instructions from the current interactive session

    Examples:
    commands
    (commands 10 t)

    General Forms:

    commands or (commands nil)
    Print out all the instructions (in the current state-stack) in
    reverse order, i.e. from the most recent instruction to the starting
    instruction.

    (commands n) [n a positive integer]
    Print out the most recent n instructions (in the current
    state-stack), in reverse order.

    (commands x abbreviate-flag)
    Same as above, but if abbreviate-flag is non-NIL, then do not
    display commands between ``matching bookends''.  See documentation
    for comm for an explanation of matching bookends.

  [31;1mRemark[0m: If there are more than [47mn[0m instructions in the state-stack,
  then [47m(commands n)[0m is the same as [47mcommands[0m (and also, [47m(commands n
  abb)[0m is the same as [47m(commands nil abb)[0m).")
 (ACL2-PC::COMMENT
  (PROOF-BUILDER-COMMANDS)
  "(primitive) insert a comment

    Example:
    (comment now begin difficult final goal)

    General Form:
    (comment &rest x)

  This instruction makes no change in the state except to insert the
  [47mcomment[0m instruction.

  Some comments can be used to improve the display of commands; see
  [ACL2-pc::comm].")
 (ACL2-PC::CONTRADICT
      (PROOF-BUILDER-COMMANDS)
      "(macro) same as [47mcontrapose[0m

  See [ACL2-pc::contrapose].")
 (ACL2-PC::CONTRAPOSE
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) switch a hypothesis with the conclusion, negating both

    Example:
    (contrapose 3)

    General Form:
    (contrapose &optional n)

  The (optional) argument [47mn[0m should be a positive integer that does not
  exceed the number of hypotheses.  Negate the current conclusion and
  make it the [47mn[0mth hypothesis, while negating the current [47mn[0mth
  hypothesis and making it the current conclusion.  If no argument is
  supplied then the effect is the same as for [47m(contrapose 1)[0m.

  [31;1mRemark:[0m By ``negate'' we mean an operation that replaces [47mnil[0m by [47mt[0m, [47mx[0m
  by [47mnil[0m for any other explicit value [47mx[0m, [47m(not x)[0m by [47mx[0m, and any other
  [47mx[0m by [47m(not x)[0m.")
 (ACL2-PC::DEMOTE
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) move top-level hypotheses to the conclusion

    Examples:
    demote        -- demote all top-level hypotheses
    (demote 3 5)  -- demote hypotheses 3 and 5

  For example, if the top-level hypotheses are [47mx[0m and [47my[0m and the
  conclusion is [47mz[0m, then after execution of [47mdemote[0m, the conclusion
  will be [47m(implies (and x y) z)[0m and there will be no (top-level)
  hypotheses.

    General Form:
    (demote &rest hyps-indices)

  Eliminate the indicated (top-level) hypotheses, but replace the
  conclusion [47mconc[0m with [47m(implies hyps conc)[0m where [47mhyps[0m is the
  conjunction of the hypotheses that were eliminated.  If no
  arguments are supplied, then all hypotheses are demoted, i.e.
  [47mdemote[0m is the same as [47m(demote 1 2 ... n)[0m where [47mn[0m is the number of
  top-level hypotheses.

  [31;1mRemark[0m: You must be at the top of the conclusion in order to use this
  command.  Otherwise, first invoke [47mtop[0m.  Also, [47mdemote[0m fails if there
  are no top-level hypotheses or if indices are supplied that are out
  of range.")
 (ACL2-PC::DIVE
  (PROOF-BUILDER-COMMANDS)
  "(primitive) move to the indicated subterm

    Examples:
    (DIVE 1)    -- assign the new current subterm to be the first
                   argument of the existing current subterm
    (DIVE 1 2)  -- assign the new current subterm to be the result of
                   first taking the 1st argument of the existing
                   current subterm, and then the 2nd argument of that

  For example, if the current subterm is

    (* (+ a b) c),

  then after [47m(dive 1)[0m it is

    (+ a b).

  If after that, then [47m(dive 2)[0m is invoked, the new current subterm will
  be

    b.

  Instead of [47m(dive 1)[0m followed by [47m(dive 2)[0m, the same current subterm
  could be obtained by instead submitting the single instruction
  [47m(dive 1 2)[0m.

    General Form:
    (dive &rest naturals-list)

  If [47mnaturals-list[0m is a non-empty list [47m(n_1 ... n_k)[0m of natural
  numbers, let the new current subterm be the result of selecting the
  [47mn_1[0m-st argument of the current subterm, and then the [47mn_2[0m-th subterm
  of that, ..., finally the [47mn_k[0m-th subterm.

  [31;1mRemark:[0m [47mDive[0m is related to the command [47mpp[0m, in that the diving is done
  according to raw (translated, internal form) syntax.  Use the
  command [47mdv[0m if you want to dive according to the syntax displayed by
  the command [47mp[0m.  Note that [47m(dv n)[0m can be abbreviated by simply [47mn[0m.

  [31;1mRemark:[0m Emacs users who load (into Emacs) the file [47memacs-acl2.el[0m
  (from a suitable directory; see [emacs]) will have defined a
  command, [47mControl-t Control-d[0m, that avoids the need to type [47mdive[0m
  commands.  After you print the current term using the [47mpp[0m command,
  you may position the cursor on a subterm and type [47mControl-t
  Control-d[0m.  Emacs will respond by pasting the appropriate [47mdive[0m
  command immediately after the interactive proof-builder's prompt.
  You can then simply type [47m<RETURN>[0m in order to dive to the desired
  subterm.")
 (ACL2-PC::DO-ALL
  (PROOF-BUILDER-COMMANDS)
  "(macro) run the given instructions

    Example:
    (do-all induct p prove)

    General Form:
    (do-all &rest instruction-list)

  Run the indicated instructions until there is a hard ``failure''.
  The instruction ``succeeds'' if and only if each instruction in
  [47minstruction-list[0m does.  (See [ACL2-pc::sequence] for an explanation
  of ``success'' and ``failure.'') As each instruction is executed,
  the system will print the usual prompt followed by that
  instruction, unless the value of [47m(access pc-info (@ pc-info)
  :print-prompt-and-instr-flg)[0m is [47mnil[0m.

  [31;1mRemark:[0m If [47mdo-all[0m ``fails'', then the failure is hard if and only if
  the last instruction it runs has a hard ``failure''.

  Obscure point: For the record, [47m(do-all ins_1 ins_2 ... ins_k)[0m is the
  same as [47m(sequence (ins_1 ins_2 ... ins_k))[0m.")
 (ACL2-PC::DO-ALL-NO-PROMPT
  (PROOF-BUILDER-COMMANDS)
  "(macro) run the given instructions, halting once there is a
  ``failure''

    Example:
    (do-all-no-prompt induct p prove)

    General Form:
    (do-all-no-prompt &rest instruction-list)

  [47mDo-all-no-prompt[0m is the same as [47mdo-all[0m, except that the prompt and
  instruction are not printed each time, regardless of the value of
  [47mpc-print-prompt-and-instr-flg[0m.  Also, restoring is disabled.  See
  [ACL2-pc::do-all].")
 (ACL2-PC::DO-STRICT
  (PROOF-BUILDER-COMMANDS)
  "(macro) run the given instructions, halting once there is a
  ``failure''

    Example:
    (do-strict induct p prove)

    General Form:
    (do-strict &rest instruction-list)

  Run the indicated instructions until there is a (hard or soft)
  ``failure''.  In fact [47mdo-strict[0m is identical in effect to [47mdo-all[0m,
  except that [47mdo-all[0m only halts once there is a hard ``failure''.
  See [ACL2-pc::do-all].")
 (ACL2-PC::DOC
  (PROOF-BUILDER-COMMANDS)
  "(macro) access documentation inside the interactive proof-builder

    Examples:

    (doc rewrite)          -- documentation on rewriting in ACL2
    (doc acl2-pc::rewrite) -- documentation on the proof-builder rewrite command
    (doc)                  -- same as (help doc) or (doc acl2-pc::doc)
    doc                    -- same as above

    General Forms:
    (doc) ; or, just: help
    (doc topic-name)

  For any [documentation] topic, [47mA[0m, [47m(doc A)[0m prints documentation on [47mA[0m
  to the terminal.  You can read that documentation online or in the
  Emacs [ACL2-Doc] browser; see [documentation].  This
  [proof-builder] command provides a direct interface to the ACL2
  [47m:[0m[47m[doc][0m command at the terminal.

  Also see [ACL2-pc::help], which provides help for proof-builder
  commands.  For example, submitting [47m(help rewrite)[0m to the
  proof-builder is equivalent to submitting [47m(doc acl2-pc::rewrite)[0m to
  the proof-builder, which corresponds to submitting [47m:doc
  acl2-pc::rewrite[0m directly to the ACL2 loop.")
 (ACL2-PC::DROP
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) drop top-level hypotheses

    Examples:
    (drop 2 3) -- drop the second and third hypotheses
    drop       -- drop all top-level hypotheses

    General Forms:
    (drop n1 n2 ...) -- Drop the hypotheses with the indicated indices.

    drop             -- Drop all the top-level hypotheses.

  [31;1mRemark:[0m If there are no top-level hypotheses, then the instruction
  [47mdrop[0m will fail.  If any of the indices is out of range, i.e. is not
  an integer between one and the number of top-level hypotheses
  [47m(inclusive)[0m, then [47m(drop n1 n2 ...)[0m will fail.")
 (ACL2-PC::DV
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) move to the indicated subterm

    Examples:
    (dv 1)    -- assign the new current subterm to be the first argument
                 of the existing current subterm
    (dv 1 2)  -- assign the new current subterm to be the result of
                 first taking the 1st argument of the existing
                 current subterm, and then the 2nd argument of that

  For example, if the current subterm is

    (* (+ a b) c),

  then after [47m(dv 1)[0m it is

    (+ a b).

  If after that, then [47m(dv 2)[0m is invoked, the new current subterm will
  be

    b.

  Instead of [47m(dv 1)[0m followed by [47m(dv 2)[0m, the same current subterm could
  be obtained by instead submitting the single instruction [47m(dv 1 2)[0m.

    General Form:
    (dv &rest naturals-list)

  If [47mnaturals-list[0m is a non-empty list [47m(n_1 ... n_k)[0m of natural
  numbers, let the new current subterm be the result of selecting the
  [47mn_1[0m-st argument of the current subterm, and then the [47mn_2[0m-th subterm
  of that, ..., finally the [47mn_k[0m-th subterm.

  [31;1mRemark:[0m [47m(dv n)[0m may be abbreviated by simply [47mn[0m, so we could have typed
  [47m1[0m instead of [47m(dv 1)[0m in the first example above.

  [31;1mRemark:[0m Emacs users who load (into Emacs) the file [47memacs-acl2.el[0m
  (from a suitable directory; see [emacs]) will have defined a
  command, [47mControl-t d[0m, that avoids the need to type [47mdv[0m commands.
  After you print the current term using the [47mp[0m or [47mth[0m command, you may
  position the cursor on a subterm and type [47mControl-t d[0m.  Emacs will
  respond by pasting the appropriate [47mdv[0m command immediately after the
  interactive proof-builder's prompt.  You can then simply type
  [47m<RETURN>[0m in order to dive to the desired subterm.

  [31;1mRemark:[0m A similar command is [47mdive[0m, which is related to the command
  [47mpp[0m, in that the diving is done according to raw (translated,
  internal form) syntax.  (See [ACL2-pc::dive].)  Use the command [47mdv[0m
  if you want to dive according to the syntax displayed by the
  command [47mp[0m.  Thus, the command ``[47mup[0m'' is the inverse of [47mdive[0m, not of
  [47mdv[0m.  The following example illustrates this point.

    ACL2 !>(verify (equal (* a b c) x))
    ->: p ; print user-level term
    (EQUAL (* A B C) X)
    ->: pp ; print internal-form (translated) term
    (EQUAL (BINARY-* A (BINARY-* B C)) X)
    ->: exit
    Exiting....
     NIL
    ACL2 !>(verify (equal (* a b c) x))
    ->: p
    (EQUAL (* A B C) X)
    ->: 1 ; same as (dv 1)
    ->: p ; print user-level term
    (* A B C)
    ->: pp ; print internal-form (translated) term
    (BINARY-* A (BINARY-* B C))
    ->: 3 ; dive to third argument of (* A B C)
    ->: p
    C
    ->: up ; go up one level in (BINARY-* A (BINARY-* B C))
    ->: p
    (* B C)
    ->: pp
    (BINARY-* B C)
    ->:


Subtopics

  [Dive-into-macros-table]
      Right-associated function information for the [proof-builder]")
 (ACL2-PC::ELIM
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) call the ACL2 theorem prover's elimination process

    Example and General Form:
    elim

  Upon running the [47melim[0m command, the system will create a subgoal will
  be created for each goal that would have been pushed for proof by
  induction in an ordinary proof, where [31;1monly[0m elimination is used; not
  even simplification is used!")
 (ACL2-PC::EQUIV
  (PROOF-BUILDER-COMMANDS)
  "(primitive) attempt an equality (or congruence-based) substitution

    Examples:
    (equiv (* x y) 3) -- replace (* x y) by 3 everywhere inside the
                         current subterm, if their equality is among the
                         top-level hypotheses or the governors
    (equiv x t iff)   -- replace x by t everywhere inside the current
                         subterm, where only propositional equivalence
                         needs to be maintained at each occurrence of x

    General form:
    (equiv old new &optional relation)

  Substitute [47mnew[0m for [47mold[0m everywhere inside the current subterm,
  provided that either [47m(relation old new)[0m or [47m(relation new old)[0m is
  among the top-level hypotheses or the governors (possibly by way of
  backchaining and/or refinement; see below).  If [47mrelation[0m is [47mnil[0m or
  is not supplied, then it defaults to [47mequal[0m.  If [47mrelation[0m is not
  [47mequal[0m (either explicitly or by default), then substitution of [47mnew[0m
  for [47mold[0m will only take place at occurrences for which [47mrelation[0m is
  among the [equivalence] relations being maintained without the use
  of [patterned-congruence]s.  Also see [47macl2-pc::=[0m for a much more
  flexible command.  Note that the [47mequiv[0m command fails if no
  substitution is actually made.

  [31;1mRemark:[0m No substitution takes place inside explicit values.  So for
  example, the instruction [47m(equiv 3 x)[0m will cause [47m3[0m to be replaced by
  [47mx[0m if the current subterm is, say, [47m(* 3 y)[0m, but not if the current
  subterm is [47m(* 4 y)[0m even though [47m4 = (1+ 3)[0m.

  The following remarks are quite technical and mostly describe a
  certain weak form of ``backchaining'' that has been implemented for
  [47mequiv[0m in order to support the [47m=[0m command.  In fact neither the term
  [47m(relation old new)[0m nor the term [47m(relation new old)[0m needs to be
  [31;1mexplicitly[0m among the current ``assumptions'', i.e., the top-level
  hypothesis or the governors.  Rather, there need only be such an
  assumption that ``tells us'' [47m(r old new)[0m or [47m(r new old)[0m, for [31;1msome[0m
  equivalence relation [47mr[0m that [31;1mrefines[0m [47mrelation[0m.  Here, ``tells us''
  means that either one of the indicated terms is among those
  assumptions, or else there is an assumption that is an implication
  whose conclusion is one of the indicated terms and whose hypotheses
  (gathered up by appropriately flattening the first argument of the
  [47mimplies[0m term) are all among the current assumptions.")
 (ACL2-PC::EX
  (PROOF-BUILDER-COMMANDS)
  "(macro) exit after possibly saving the state

    Example and General Form:
    ex

  Same as [47mexit[0m, except that first the instruction [47msave[0m is executed.

  If [47msave[0m queries the user and is answered negatively, then the exit is
  aborted.")
 (ACL2-PC::EXIT
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(meta) exit the interactive proof-builder

    Examples:
    exit                        -- exit the interactive proof-builder
    (exit t)                    -- exit after printing a bogus defthm event
    (exit append-associativity) -- exit and create a defthm
                                   event named append-associativity

    General Forms:

    exit --  Exit without storing an event.

    (exit t) -- Exit after printing a bogus defthm event, showing :INSTRUCTIONS.

    (exit event-name &optional rule-classes do-it-flg) --
    Exit, and perhaps store an event

  The command [47mexit[0m returns you to the ACL2 loop.  At a later time,
  [47m(acl2::verify)[0m may be executed to get back into the same
  interactive proof-builder state, as long as there hasn't been an
  intervening use of the proof-builder (otherwise see
  [ACL2-pc::save]).

  When given one or more arguments as shown above, [47mexit[0m still returns
  you to the ACL2 loop, but first, if the interactive proof is
  complete, then it attempts create a [47mdefthm[0m event with the specified
  [47mevent-name[0m and [47mrule-classes[0m (which defaults to [47m(:rewrite)[0m if not
  supplied).  The event will be printed to the terminal, and then
  normally the user will be queried whether an event should really be
  created.  However, if the final optional argument [47mdo-it-flg[0m is
  supplied and not [47mnil[0m, then an event will be made without a query.

  For example, the form

    (exit top-pop-elim (:elim :rewrite) t)

  causes a [47mdefthm[0m event named [47mtop-pop-elim[0m to be created with
  rule-classes [47m(:elim :rewrite)[0m, without a query to the user (because
  of the argument [47mt[0m).

  [31;1mRemark:[0m it is permitted for [47mevent-name[0m to be [47mnil[0m.  In that case, the
  name of the event will be the name supplied during the original
  call of [47mverify[0m.  (See [verify] and [ACL2-pc::commands].)  Also in
  that case, if [47mrule-classes[0m is not supplied then it defaults to the
  rule-classes supplied in the original call of [47mverify[0m.

  [47mComments[0m on ``success'' and ``failure''.  An [47mexit[0m instruction will
  always ``fail'', so for example, if it appears as an argument of a
  [47mdo-strict[0m instruction then none of the later (instruction)
  arguments will be executed.  Moreover, the ``failure'' will be
  ``hard'' if an event is successfully created or if the instruction
  is simply [47mexit[0m; otherwise it will be ``soft''.  See
  [ACL2-pc::sequence] for an explanation of hard and soft
  ``failures''.  An obscure but potentially important fact is that if
  the ``failure'' is hard, then the error signal is a special signal
  that the top-level interactive loop can interpret as a request to
  exit.  Thus for example, a sequencing command that turns an error
  triple [47m(mv erp val state)[0m into [47m(mv t val state)[0m would never cause
  an exit from the interactive loop.

  If the proof is not complete, then neither [47m(exit event-name ...)[0m nor
  [47m(exit t)[0m will cause an exit from the interactive loop.  However, in
  that case either one will print out the original user-supplied goal
  (the one that was supplied with the call to [47mverify[0m) and the current
  list of instructions.")
 (ACL2-PC::EXPAND
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) expand the current function call without simplification

    Examples:
    expand -- expand and do not simplify.

  Also see [ACL2-pc::x], which performs simplification, and see
  [ACL2-pc::x-dumb], which provides a simple interface to
  [47macl2-pc::expand[0m.

  For example, if the current subterm is [47m(append a b)[0m, then after
  [47mexpand[0m the current subterm will be the term:

    (if (consp a)
        (cons (car a) (append (cdr a) b))
      b)

  regardless of the top-level hypotheses and the governors.

    General Form:
    (expand &optional do-not-expand-lambda-flg)

  Expand the function call at the current subterm, and do not simplify.
  The options have the following meanings:

    do-not-expand-lambda-flg:   default is nil; otherwise, the result
                                should be a lambda expression")
 (ACL2-PC::FAIL
  (PROOF-BUILDER-COMMANDS)
  "(macro) cause a failure

    Examples:
    fail
    (fail t)

    General Form:
    (fail &optional hard)

  This is probably only of interest to writers of macro commands.  The
  only function of [47mfail[0m is to fail to ``succeed''.

  The full story is that [47mfail[0m and [47m(fail nil)[0m simply return [47m(mv nil nil
  state)[0m, while [47m(fail hard)[0m returns [47m(mv hard nil state)[0m if [47mhard[0m is
  not [47mnil[0m.  Also see [ACL2-pc::do-strict], [ACL2-pc::do-all], and
  [ACL2-pc::sequence].")
 (ACL2-PC::FINISH
  (PROOF-BUILDER-COMMANDS)
  "(macro) require completion of instructions; save error if inside
  [47m:[0m[47m[hints][0m

    Example:
    (finish induct prove bash)

    General Form:
    (finish &rest instructions)

  Run the indicated instructions, stopping at the first failure.  If
  there is any failure, or if any new goals are created and remain at
  the end of the indicated instructions, then consider the call of
  [47mfinish[0m to be a failure.  See [proof-builder-commands] and see
  [ACL2-pc::sequence] for a discussion of the notion of ``failure''
  for interactive [proof-builder] commands.")
 (ACL2-PC::FORWARDCHAIN
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) forward chain from an implication in the hyps

    Example:
    (forwardchain 2) ; Second hypothesis should be of the form
                     ; (IMPLIES hyp concl), and the result is to replace
                     ; that hypothesis with concl.

    General Forms:
    (forwardchain hypothesis-number)
    (forwardchain hypothesis-number hints)
    (forwardchain hypothesis-number hints quiet-flg)

  This command replaces the hypothesis corresponding to the given
  index.  That hypothesis --- call it [47mH[0m --- must be of the form
  [47m(IMPLIES hyp concl)[0m.  The effect of this command is to replace [47mH[0m by
  [47mconcl[0m, which becomes the final hypothesis.

  The prover must be able to prove [47mconcl[0m from the hypotheses other than
  [47mH[0m (more precisely, to prove [47mconcl[0m after removing the hypothesis at
  the given index), or else the command will fail.  The [47m:hints[0m
  argument is used in this prover call, and should have the usual
  syntax of hints to the prover.

  Output is suppressed if [47mquiet-flg[0m is supplied and not [47mnil[0m.")
 (ACL2-PC::FREE
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) create a ``free variable''

    Example:
    (free x)

    General Form:
    (free var)

  Mark [47mvar[0m as a ``free variable''.  Free variables are only of interest
  for the [47mput[0m command; see [ACL2-pc::put].")
 (ACL2-PC::GENEQV
  (PROOF-BUILDER-COMMANDS)
  "(macro) show the generated equivalence relation maintained at the
  current subterm

    General Forms:
    geneqv     ; show list of equivalence relations being maintained
    (geneqv t) ; as above, but pair each relation with a justifying rune

  This is an advanced command, whose effect is to print the so-called
  ``generated equivalence relation'' (or ``geneqv'') that is
  maintained at the current subterm of the conclusion.  That
  structure is a list of equivalence relations, representing the
  transitive closure [47mE[0m of the union of those relations, such that it
  suffices to maintain [47mE[0m at the current subterm: if that subterm, [47mu[0m,
  is replaced in the goal's conclusion, [47mG[0m, by another term equivalent
  to [47mu[0m with respect to [47mE[0m, then the resulting conclusion is Boolean
  equivalent to [47mG[0m.  Also see [defcong].

  The command `[47mgeneqv[0m' prints the above list of equivalence relations,
  or more precisely, the list of function symbols for those
  relations.  If however [47mgeneqv[0m is given a non-[47mnil[0m argument, then a
  list is printed whose elements are each of the form [47m(s r)[0m, where [47ms[0m
  is the symbol for an equivalence relation and [47mr[0m is a [47m:[0m[47m[congruence][0m
  [rune] justifying the inclusion of [47ms[0m in the list of equivalence
  relations being maintained at the current subterm.")
 (ACL2-PC::GENERALIZE
  (PROOF-BUILDER-COMMANDS)
  "(primitive) perform a generalization

    Example:
    (generalize
     ((and (true-listp x) (true-listp y)) 0)
     ((append x y) w))

    General Form:
    (generalize &rest substitution)

  Generalize using the indicated substitution, which should be a
  non-empty list.  Each element of that list should be a two-element
  list of the form [47m(term variable)[0m, where [47mterm[0m may use abbreviations.
  The effect of the instruction is to replace each such term in the
  current goal by the corresponding variable.  This replacement is
  carried out by a parallel substitution, outside-in in each
  hypothesis and in the conclusion.  More generally, actually, the
  ``variable'' (second) component of each pair may be [47mnil[0m or a
  number, which causes the system to generate a new name of the form
  [47m_[0m or [47m_n[0m, with [47mn[0m a natural number; more on this below.  However,
  when a variable is supplied, it must not occur in any goal of the
  current state of the interactive proof-builder.

  When the ``variable'' above is [47mnil[0m, the system will treat it as the
  variable [47m|_|[0m if that variable does not occur in any goal of the
  current proof-builder state.  Otherwise it treats it as [47m|_0|[0m, or
  [47m|_1|[0m, or [47m|_2|[0m, and so on, until one of these is not among the
  variables of the current proof-builder state.  If the ``variable''
  is a non-negative integer [47mn[0m, then the system treats it as [47m|_n|[0m
  unless that variable already occurs among the current goals, in
  which case it increments n just as above until it obtains a new
  variable.

  [31;1mRemark:[0m The same variable may not occur as the variable component of
  two different arguments (though [47mnil[0m may occur arbitrarily many
  times, as may a positive integer).")
 (ACL2-PC::GOALS
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) list the names of goals on the stack

    Example and General Form:
    goals

  [47mGoals[0m lists the names of all goals that remain to be proved.  They
  are listed in the order in which they appear on the stack of
  remaining goals, which is relevant for example to the effect of a
  [47mchange-goal[0m instruction.")
 (ACL2-PC::HELP
  (PROOF-BUILDER-COMMANDS)
  "(macro) proof-builder help facility

    Examples:

    (help rewrite)   -- documentation on the proof-builder rewrite command
    (help)           -- this help
    (help help)      -- same as (help) or simply, help
    (help all)       -- same as (doc proof-builder-commands)

    General Forms:
    (help) ; or, just: help
    (help command)
    (help all)

  For any interactive proof-builder command, [47mC[0m, [47m(help C)[0m prints
  documentation on [47mC[0m to the terminal.  You can read that
  documentation online or in the Emacs [ACL2-Doc] browser by viewing
  topic [47macl2-pc::C[0m; see [documentation].

  To see a list of all interactive proof-builder commands, you can
  submit [47m(help all)[0m.  This is actually equivalent to [47m(doc
  proof-builder-commands)[0m, which prints the documentation for topic
  [proof-builder-commands] (which, as discussed above, you can view
  online or with [ACL2-Doc]).

  Also see [ACL2-pc::doc], which provides a direct interface to the
  ACL2 [47m:[0m[47m[doc][0m command.  For example, submitting [47m(help rewrite)[0m to the
  interactive proof-builder is equivalent to submitting [47m(doc
  acl2-pc::rewrite)[0m to the proof-builder or submitting [47m:doc
  acl2-pc::rewrite[0m directly to the ACL2 loop.")
 (ACL2-PC::HYPS
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the hypotheses

    Examples:
    hyps               -- print all (top-level) hypotheses
    (hyps (1 3) (2 4)) -- print hypotheses 1 and 3 and governors 2 and 4
    (hyps (1 3) t)     -- print hypotheses 1 and 3 and all governors

    General Form:
    (hyps &optional hyps-indices govs-indices)

  Print the indicated top-level hypotheses and governors.  (The notion
  of ``governors'' is defined below.)  Here, [47mhyps-indices[0m and
  [47mgovs-indices[0m should be lists of indices of hypotheses and governors
  (respectively), except that the atom [47mt[0m may be used to indicate that
  one wants all hypotheses or governors (respectively).

  The list of ``governors'' is defined as follows.  Actually, we define
  here the notion of the governors for a pair of the form [47m<term[0m,
  address>]; we're interested in the special case where the term is
  the conclusion and the address is the current address.  If the
  address is [47mnil[0m, then there are no governors, i.e., the list of
  governors is [47mnil[0m.  If the term is of the form [47m(if x y z)[0m and the
  address is of the form [47m(2 . rest)[0m or [47m(3 . rest)[0m, then the list of
  governors is the result of [47mcons[0ming [47mx[0m or its negation (respectively)
  onto the list of governors for the pair [47m<y, rest>[0m or the pair [47m<z,
  rest>[0m (respectively).  If the term is of the form [47m(implies x y)[0m and
  the address is of the form [47m(2 . rest)[0m, then the list of governors
  is the result of [47mcons[0ming [47mx[0m onto the list of governors for the pair
  [47m<y, rest>[0m.  Otherwise, the list of governors for the pair [47m<term, (n
  .  rest)>[0m is exactly the list of governors for the pair [47m<argn,
  rest>[0m where [47margn[0m is the [47mn[0mth argument of [47mterm[0m.

  If all goals have been proved, a message saying so will be printed.
  (as there will be no current hypotheses or governors!).

  The [47mhyps[0m command never causes an error.  It ``succeeds'' (in fact its
  value is [47mt[0m) if the arguments (when supplied) are appropriate, i.e.
  either [47mt[0m or lists of indices of hypotheses or governors,
  respectively.  Otherwise it ``fails'' (its value is [47mnil[0m).")
 (ACL2-PC::ILLEGAL
  (PROOF-BUILDER-COMMANDS)
  "(macro) illegal instruction

    Example:
    (illegal -3)

    General Form:
    (illegal instruction)

  Probably not of interest to most users; always ``fails'' since it
  expands to the [47mfail[0m command.

  The [47millegal[0m command is used mainly in the implementation.  For
  example, the instruction [47m0[0m is ``read'' as [47m(illegal 0)[0m, since [47mdive[0m
  expects positive integers.")
 (ACL2-PC::IN-THEORY
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) set the current proof-builder theory

    Example:
    (in-theory
       (union-theories (theory 'minimal-theory) '(true-listp binary-append)))

    General Form:
    (in-theory &optional atom-or-theory-expression)

  If the argument is not supplied, then this command sets the current
  interactive proof-builder theory (see below for explanation) to
  agree with the current ACL2 theory.  Otherwise, the argument should
  be a theory expression, and in that case the proof-builder theory
  is set to the value of that theory expression.

  The current interactive proof-builder theory is used in all calls to
  the ACL2 theorem prover and rewriter from inside the proof-builder.
  Thus, the most recent [47min-theory[0m instruction in the current
  [47mstate-stack[0m has an effect in the proof-builder totally analogous to
  the effect caused by an [47min-theory[0m hint or event in ACL2.  All
  [47min-theory[0m instructions before the last are ignored, because they
  refer to the current theory in the ACL2 [47m[state][0m, not to the
  existing proof-builder theory.  For example:

    ACL2 !>:trans1 (enable bar)
     (UNION-THEORIES (CURRENT-THEORY :HERE)
                     '(BAR))
    ACL2 !>:trans1 (CURRENT-THEORY :HERE)
     (CURRENT-THEORY-FN :HERE WORLD)
    ACL2 !>

  Thus [47m(in-theory (enable bar))[0m modifies the current theory of the
  current ACL2 world.  So for example, suppose that [47mfoo[0m is disabled
  outside the proof-builder and you execute the following
  instructions, in this order.

    (in-theory (enable foo))
    (in-theory (enable bar))

  Then after the second of these, [47mbar[0m will be enabled in the
  proof-builder, but [47mfoo[0m will be disabled.  The reason is that
  [47m(in-theory (enable bar))[0m instructs the proof-builder to modify the
  current theory (from outside the proof-builder, not from inside the
  proof-builder) by enabling [47mbar[0m.

  Note that [47min-theory[0m instructions in the proof-builder have no effect
  outside the proof-builder's interactive loop.

  If the most recent [47min-theory[0m instruction in the current state of the
  proof-builder has no arguments, or if there is no [47min-theory[0m
  instruction in the current state of the proof-builder, then the
  proof-builder will use the current ACL2 theory.  This is true even
  if the user has interrupted the interactive loop by exiting and
  changing the global ACL2 theory.  However, if the most recent
  [47min-theory[0m instruction in the current state of the proof-builder had
  an argument, then global changes to the current theory will have no
  effect on the proof-builder state.")
 (ACL2-PC::INDUCT
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) generate subgoals using induction

    Examples:
    induct, (induct t)
       -- induct according to a heuristically-chosen scheme, creating
          a new subgoal for each base and induction step
    (induct (append (reverse x) y))
       -- as above, but choose an induction scheme based on the term
          (append (reverse x) y) rather than on the current goal

    General Form:
    (induct &optional term)

  Induct as in the corresponding [47m:induct[0m hint given to the theorem
  prover, creating new subgoals for the base and induction steps.  If
  term is [47mt[0m or is not supplied, then use the current goal to
  determine the induction scheme; otherwise, use that term.

  [31;1mRemark:[0m As usual, abbreviations are allowed in the term.

  [31;1mRemark:[0m [47mInduct[0m actually calls the [47mprove[0m command with all processes
  turned off.  Thus, you must be at top of the goal for an [47minduct[0m
  instruction.")
 (ACL2-PC::LEMMAS-USED
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the runes (definitions, lemmas, ...) used

  This is just an alias for [47mrunes[0m.")
 (ACL2-PC::LISP
  (PROOF-BUILDER-COMMANDS)
  "(meta) evaluate the given form in Lisp

    Example:
    (lisp (assign xxx 3))

    General Form:
    (lisp form)

  Evaluate [47mform[0m.  The [47mlisp[0m command is mainly of interest for side
  effects.  Also see [ACL2-pc::print], [ACL2-pc::skip], and
  [ACL2-pc::fail].

  The rest of the documentation for [47mlisp[0m is of interest only to those
  who use it in macro commands.  If the Lisp evaluation (by
  [47mtrans-eval[0m) of form returns an [error-triple] of the form [47m(mv erp
  ((NIL NIL STATE) . (erp-1 val-1 &)) state)[0m, then the [47mlisp[0m command
  returns the appropriate error triple

    (mv (or erp erp-1)
        val-1
        state) .

  Otherwise, the [47mtrans-eval[0m of form must return an error triple of the
  form [47m(mv erp (cons stobjs-out val) &)[0m, and the [47mlisp[0m command returns
  the appropriate error triple

    (mv erp
        val
        state).

  Note that the output signature of the form has been lost.  The user
  must know the signature in order to use the output of the [47mlisp[0m
  command.  Trans-eval, which is undocumented except by comments in
  the ACL2 source code, has replaced, in [47mval[0m, any occurrence of the
  current state or the current values of stobjs by simple symbols
  such as [47mREPLACED-STATE[0m.  The actual values of these objects may be
  recovered, in principle, from the [47mstate[0m returned and the
  [47muser-stobj-alist[0m within that state.  However, in practice, the
  stobjs cannot be recovered because the user is denied access to
  [47muser-stobj-alist[0m.  The moral is: do not try to write macro commands
  that manipulate stobjs.  Should the returned [47mval[0m contain
  [47mREPLACED-STATE[0m the value may simply be ignored and [47mstate[0m used,
  since that is what [47mREPLACED-STATE[0m denotes.")
 (ACL2-PC::NEGATE
  (PROOF-BUILDER-COMMANDS)
  "(macro) run the given instructions, and ``succeed'' if and only if
  they ``fail''

  Example: (negate prove)

    General form:
    (negate &rest instruction-list)

  Run the indicated instructions exactly in the sense of [47mdo-all[0m, and
  ``succeed'' if and only if they ``fail''.

  [31;1mRemark:[0m [47mNegate[0m instructions will never produce hard ``failures''.")
 (ACL2-PC::NIL
  (PROOF-BUILDER-COMMANDS)
  "(macro) used for interpreting [47mcontrol-d[0m

    Example and General form:
    nil

  (or, [47mcontrol-d[0m).

  The whole point of this command is that there have been Lisps where
  if you type [47mcontrol-d[0m then it seems, on occasion, to get
  interpreted as [47mnil[0m.  Without this command, one seems to get into an
  infinite loop.")
 (ACL2-PC::NOISE
  (PROOF-BUILDER-COMMANDS)
  "(meta) run instructions with prover output

    Example:
    (noise induct prove)

    General Form:
    (noise &rest instruction-list)

  Run the [47minstruction-list[0m through the top-level loop with prover
  output.

  In fact, having prover output is the default.  [47mNoise[0m is useful inside
  a surrounding call of [47mquiet[0m, when one temporarily wants output.
  For example, if one wants to see output for a [47mprove[0m command
  immediately following an [47minduct[0m command but before an [47ms[0m command,
  one may want to submit an instruction like [47m(quiet induct (noise
  prove) s)[0m.  Also see [ACL2-pc::quiet] and [ACL2-pc::noise!].")
 (ACL2-PC::NOISE!
  (PROOF-BUILDER-COMMANDS)
  "(meta) run instructions with prover and proof-tree output

    Example:
    (noise! induct prove)

    General Form:
    (noise! &rest instruction-list)

  Run the [47minstruction-list[0m through the top-level loop with prover
  output and [proof-tree] output.  See [ACL2-pc::noise]; the [47mnoise![0m
  command is the same, except for adding proof-tree output.")
 (ACL2-PC::NX
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) move forward one argument in the enclosing term

    Example and General Form:
    nx

  For example, if the conclusion is [47m(= x (* (- y) z))[0m and the current
  subterm is [47mx[0m, then after executing [47mnx[0m, the current subterm will be
  [47m(* (- y) z)[0m.

  This is the same as [47mup[0m followed by [47m(dive n+1)[0m, where [47mn[0m is the
  position of the current subterm in its parent term in the
  conclusion.  Thus in particular, the [47mnx[0m command fails if one is
  already at the top of the conclusion.

  Also see [ACL2-pc::up], [ACL2-pc::dive], [ACL2-pc::top], and
  [ACL2-pc::bk].")
 (ACL2-PC::ORELSE
  (PROOF-BUILDER-COMMANDS)
  "(macro) run the first instruction; if (and only if) it ``fails'', run
  the second

    Example:
    (orelse top (print \"Couldn't move to the top\"))

    General form:
    (orelse instr1 instr2)

  Run the first instruction.  Then if it ``fails'', run the second
  instruction also; otherwise, stop after the first.

  This instruction ``succeeds'' if and only if either [47minstr1[0m
  ``succeeds'', or else [47minstr2[0m ``succeeds''.  If it ``fails'', then
  the failure is soft.")
 (ACL2-PC::P
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) prettyprint the current term in the usual user-level
  (untranslated) syntax

    Example and General Form:
    p

  Prettyprint the current term.  The usual user (untranslated) syntax
  is used, so that for example one would see [47m(and x y)[0m rather than
  [47m(if x y 'nil)[0m.  (See also [47mpp[0m.)  Also, abbreviations are inserted
  where appropriate; see [ACL2-pc::add-abbreviation].

  The ``current term'' is the entire conclusion unless [47mdive[0m commands
  have been given, in which case it may be a subterm of the
  conclusion.

  If all goals have been proved, a message saying so will be printed
  (as there will be no current [47mterm[0m!).")
 (ACL2-PC::P-TOP
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) prettyprint the conclusion, highlighting the current term

    Example and General Form:
    p-top

  For example, if the conclusion is [47m(equal (and x (p y)) (foo z))[0m and
  the current subterm is [47m(p y)[0m, then [47mp-top[0m will print [47m(equal (and x
  (*** (p y) ***)) (foo z))[0m.

  Prettyprint the conclusion, highlighting the current term.  The usual
  user syntax is used, as with the command [47mp[0m (as opposed to [47mpp[0m).
  This is illustrated in the example above, where one would [3m*not*[0m see
  [47m(equal (if x (*** (p y) ***) 'nil) (foo z))[0m.

  [31;1mRemark[0m (obscure): In some situations, a term of the form [47m(if x t y)[0m
  occurring inside the current subterm will not print as [47m(or x y)[0m,
  when [47mx[0m isn't a call of a boolean primitive.  There's nothing
  incorrect about this, however.")
 (ACL2-PC::PL
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the rules for a given name

    Examples:
    pl
    (pl foo)

    General Form:
    (pl &optional x)

  This command simply invokes the corresponding command of the
  top-level ACL2 loop; see [pl].  If no argument is given, or if the
  argument is [47mnil[0m, then the current subterm should be a call of a
  function symbol, and the argument is taken to be that symbol.

  If you want information about applying rewrite rules to the current
  subterm, consider the [47mshow-rewrites[0m (or equivalently, [47msr[0m) command.")
 (ACL2-PC::POT-LST
  (PROOF-BUILDER-COMMANDS)
  "(macro) display the linear arithmetic database based on the current
  context

  This is a relatively advanced command.  For discussion of a related
  but more elementary command, including remarks about the utility of
  such a command, see [ACL2-pc::type-alist].  See [linear-arithmetic]
  for a description of the ACL2 linear arithmetic decision procedure

    Examples:
    (pot-lst nil t)   ; display linear pot-lst based on governors only (default)
    pot-lst           ; same as (pot-lst nil t) -- governors only (default)
    (pot-lst nil)     ; same as (pot-lst nil t) -- governors only (default)
    (pot-lst nil t nil nil) ; same as above
    (pot-lst nil t nil t)   ; same as above, except: raw format
    (pot-lst t t)     ; display pot-lst based on conclusion and governors
    (pot-lst t)       ; same as (pot-lst t nil) -- conclusion only
    (pot-lst nil nil) ; based on neither conclusion nor governors

    General Form:
    (pot-lst &optional concl-flg govs-flg rawp)

  where if [47mgovs-flg[0m is omitted then it defaults to [47m(not concl-flg)[0m, and
  each of the other optional arguments defaults to [47mnil[0m.

  This command displays the linear database, also known as the linear
  [3mpot-lst[0m, that is computed from a suitable set of assumptions.  That
  set of assumptions always includes all top-level hypotheses.  By
  default, and when [47mgovs-flg[0m is supplied a non-[47mnil[0m value, the set of
  assumptions includes all governors (which are based on surrounding
  if-expressions that must be true or false).  The negation of the
  current goal's top-level conclusion is also included in the
  assumptions when [47mconcl-flg[0m is supplied a non-[47mnil[0m value.

  The computed pot-lst is based on the result of forward chaining from
  the set of assumptions as described above.  By default, that
  pot-lst is displayed in a self-explanatory way.  Here is an
  (admittedly contrived) example.

    ACL2 !>(verify (implies (and (>= (- (nth 3 x) a) 7)
                                 (< (nth 3 x) b)
                                 (< c b))
                            (< (nth 3 x) d)))
    ->: promote
    ->: th
    *** Top-level hypotheses:
    1. (<= 7 (+ (NTH 3 X) (- A)))
    2. (< (NTH 3 X) B)
    3. (< C B)

    The current subterm is:
    (< (NTH 3 X) D)
    ->: pot-lst
    Current pot-lst:
    -----
    For maximal term B
    the list of polynomials is:
    ((A + 7 < B))
    -----
    For maximal term C
    the list of polynomials is:
    ((C < B))
    -----
    For maximal term (NTH '3 X)
    the list of polynomials is:
    (((NTH '3 X) < B) (A + 7 <= (NTH '3 X)))

    NIL
    ->: (pot-lst t t)
    Current pot-lst:
    -----
    For maximal term B
    the list of polynomials is:
    ((A + 7 < B))
    -----
    For maximal term C
    the list of polynomials is:
    ((C < B))
    -----
    For maximal term D
    the list of polynomials is:
    ((D < B))
    -----
    For maximal term (NTH '3 X)
    the list of polynomials is:
    (((NTH '3 X) < B) (A + 7 <= (NTH '3 X)) (D <= (NTH '3 X)))

    NIL
    ->:

  You can get the internal form of the pot-lst by supplying all
  optional arguments including a non-[47mnil[0m value for [47mrawp[0m.")
 (ACL2-PC::PP
  (PROOF-BUILDER-COMMANDS)
  "(macro) prettyprint the current term in internal (translated) form

    Example and General Form:
    pp

  This is the same as [47mp[0m (see its documentation), except that raw syntax
  (internal form) is used.  So for example, one would see [47m(if x y
  'nil)[0m rather than [47m(and x y)[0m.  Abbreviations are however still
  inserted, as with [47mp[0m.")
 (ACL2-PC::PR
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the rules for a given name

    Examples:
    pr
    (pr foo)

    General Form:
    (pr &optional x)

  This command simply invokes the corresponding command of the
  top-level ACL2 loop; see [pr].  If no argument is given, or if the
  argument is [47mnil[0m, then the current subterm should be a call of a
  function symbol, and the argument is taken to be that symbol.

  If you want information about applying rewrite rules to the current
  subterm, consider the [47mshow-rewrites[0m (or equivalently, [47msr[0m) command.")
 (ACL2-PC::PRINT
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the result of evaluating the given form

    Example:
    (print (append '(a b) '(c d)))
    Print the list (a b c d) to the terminal

    General Forms:
    (print form)
    (print form t)

  Prettyprints the result of evaluating form.  The evaluation of [47mform[0m
  should return a single value that is not [47m[state][0m or a
  single-threaded object (see [stobj]).  The optional second argument
  causes printing to be done without elision (so-called
  ``evisceration''; see [evisc-tuple]).

  If the form you want to evaluate does not satisfy the criterion
  above, you should create an appropriate call of the [47mlisp[0m command
  instead.  Notice that this command always returns [47m(mv nil nil
  state)[0m where the second result will always be [47mREPLACED-STATE[0m.")
 (ACL2-PC::PRINT-ALL-CONCS
  (PROOF-BUILDER-COMMANDS)
  "(macro) print all the conclusions of (as yet unproved) goals

  Example and General Form: print-all-concs

  Prints all the conclusions of goals that remain to be proved, in a
  pleasant format, ordered as by the command, [47m[ACL2-pc::goals][0m.  Also
  see [ACL2-pc::print-all-goals].")
 (ACL2-PC::PRINT-ALL-GOALS
  (PROOF-BUILDER-COMMANDS)
  "(macro) print all the (as yet unproved) goals

  Example and General Form: print-all-goals

  Prints all the goals that remain to be proved, in a pleasant format,
  ordered as by the command, [47m[ACL2-pc::goals][0m.  Also see
  [ACL2-pc::print-all-concs].")
 (ACL2-PC::PRINT-MAIN
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the original goal

    Example and General Form:
    print-main

  Print the goal as originally entered.")
 (ACL2-PC::PRO
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) repeatedly apply promote

    Example and General Form:
    pro

  Apply the [47mpromote[0m command until there is no change.  This command
  ``succeeds'' exactly when at least one call of [47mpromote[0m
  ``succeeds''.  In that case, only a single new proof-builder state
  will be created.

  Note: The [47msplit[0m command is probably more helpful in many cases than
  [47mpro[0m.")
 (ACL2-PC::PROMOTE
  (PROOF-BUILDER-COMMANDS)
  "(primitive) move antecedents of conclusion's [47mimplies[0m term to
  top-level hypotheses

    Examples:
    promote
    (promote t)

  For example, if the conclusion is [47m(implies (and x y) z)[0m, then after
  execution of [47mpromote[0m, the conclusion will be [47mz[0m and the terms [47mx[0m and
  [47my[0m will be new top-level hypotheses.

    General Form:
    (promote &optional do-not-flatten-flag)

  Replace conclusion of [47m(implies hyps exp)[0m or [47m(if hyps exp t)[0m with
  simply [47mexp[0m, adding [47mhyps[0m to the list of top-level hypotheses.
  Moreover, if [47mhyps[0m is viewed as a conjunction then each conjunct
  will be added as a separate top-level hypothesis.  An exception is
  that if [47mdo-not-flatten-flag[0m is supplied and not [47mnil[0m, then only one
  top-level hypothesis will be added, namely [47mhyps[0m.

  [31;1mRemark[0m: You must be at the top of the conclusion in order to use this
  command.  Otherwise, first invoke [47mtop[0m.")
 (ACL2-PC::PROTECT
  (PROOF-BUILDER-COMMANDS)
  "(macro) run the given instructions, reverting to existing state upon
  failure

    Example:
    (protect induct p prove)

    General Form:
    (protect &rest instruction-list)

  [47mProtect[0m is the same as [47mdo-strict[0m, except that as soon as an
  instruction ``fails'', the state-stack reverts to what it was
  before the [47mprotect[0m instruction began, and [47mrestore[0m is given the same
  meaning that it had before the [47mprotect[0m instruction began.  See
  [ACL2-pc::do-strict].")
 (ACL2-PC::PROVE
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) call the ACL2 theorem prover to prove the current goal

    Examples:
    prove -- attempt to prove the current goal
    (prove :otf-flg t
           :hints ((\"Subgoal 2\" :by foo) (\"Subgoal 1\" :use bar)))
          -- attempt to prove the current goal, with the indicated hints
             and with OTF-FLG set

    General Form:
    (prove &rest rest-args)

  Attempt to prove the current goal, where [47mrest-args[0m is as in the
  keyword arguments to [47mdefthm[0m except that only [47m:hints[0m and [47m:otf-flg[0m
  are allowed.  The command succeeds exactly when the corresponding
  [47mdefthm[0m would succeed, except that it is all right for some goals to
  be given ``bye''s.  Each goal given a ``bye'' will be turned into a
  new subgoal.  (See [hints] for an explanation of [47m:by[0m hints.)

  [31;1mRemark:[0m Use [47m(= t)[0m instead if you are not at the top of the
  conclusion.  Also note that if there are any hypotheses in the
  current goal, then what is actually attempted is a proof of
  [47m(implies hyps conc)[0m, where [47mhyps[0m is the conjunction of the top-level
  hypotheses and [47mconc[0m is the goal's conclusion.

  [31;1mRemark:[0m It is allowed to use abbreviations in the hints.")
 (ACL2-PC::PSO
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the most recent proof attempt from inside the
  proof-builder

    Example and General Form:
    pso

  Print the most recent proof attempt from inside the interactive
  proof-builder.  This includes prover calls, including for example
  [proof-builder] commands [47minduct[0m, [47msplit[0m, and [47mbash[0m, in addition to
  [47mprove[0m.  So for example, you can follow [47m(quiet prove)[0m with [47mpso[0m to
  see the proof, including [proof-tree] output, if it failed.

  Related [proof-builder] commands are [47mpsog[0m and [47mpso![0m; see
  [ACL2-pc::psog] and [ACL2-pc::pso!].")
 (ACL2-PC::PSO!
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the most recent proof attempt from inside the
  proof-builder

    Example and General Form:
    pso!

  Print the most recent proof attempt from inside the interactive
  proof-builder.  This includes prover calls, including for example
  [proof-builder] commands [47minduct[0m, [47msplit[0m, and [47mbash[0m, in addition to
  [47mprove[0m.  So for example, you can follow [47m(quiet prove)[0m with [47mpso![0m to
  see the proof, including [proof-tree] output, if it failed.

  Related [proof-builder] commands are [47mpso[0m and [47mpsog[0m; see [ACL2-pc::pso]
  and [ACL2-pc::psog].")
 (ACL2-PC::PSOG
  (PROOF-BUILDER-COMMANDS)
  "(macro) print the most recent proof attempt from inside the
  proof-builder

    Example and General Form:
    psog

  Print the most recent proof attempt from inside the interactive
  proof-builder, including goal names.  This includes prover calls,
  including for example [proof-builder] commands [47minduct[0m, [47msplit[0m, and
  [47mbash[0m, in addition to [47mprove[0m.  So for example, you can follow [47m(quiet
  prove)[0m with [47mpsog[0m to see the proof, including [proof-tree] output,
  if it failed.

  Related [proof-builder] commands are [47mpso[0m and [47mpso![0m; see [ACL2-pc::pso]
  and [ACL2-pc::pso!].")
 (ACL2-PC::PUT
  (PROOF-BUILDER-COMMANDS)
  "(macro) substitute for a ``free variable''

    Example:
    (put x 17)

    General Form:
    (put var expr)

  Substitute [47mexpr[0m for the ``free variable'' [47mvar[0m, as explained below.

  A ``free variable'' is, for our purposes, a variable [47mvar[0m such that
  the instruction [47m(free var)[0m has been executed earlier in the
  state-stack.  What [47m(free var)[0m really does is to let [47mvar[0m be an
  abbreviation for the term [47m(hide var)[0m (see
  [ACL2-pc::add-abbreviation]).  What [47m(put var expr)[0m really does is
  to unwind the state-stack, replacing that [47mfree[0m instruction with the
  instruction [47m(add-abbreviation var expr)[0m, so that future references
  to [47m(? var)[0m become reference to [47mexpr[0m rather than to [47m(hide var)[0m, and
  then to replay all the other instructions that were unwound.
  Because [47mhide[0m was used, the expectation is that in most cases, the
  instructions will replay successfully and [47mput[0m will ``succeed''.
  However, if any replayed instruction ``fails'', then the entire
  replay will abort and ``fail'', and the state-stack will revert to
  its value before the [47mput[0m instruction was executed.

  If [47m(put var expr)[0m ``succeeds'', then [47m(remove-abbreviation var)[0m will
  be executed at the end.

  [31;1mRemark[0m: The [47mrestore[0m command will revert the state-stack to its value
  present before the [47mput[0m instruction was executed.")
 (ACL2-PC::QUIET
  (PROOF-BUILDER-COMMANDS)
  "(meta) run instructions without prover output

    Example:
    (quiet induct prove)

    General Form:
    (quiet &rest instruction-list)

  Run the [47minstruction-list[0m through the top-level loop with no output.

  Also see [ACL2-pc::noise] and [ACL2-pc::quiet!].")
 (ACL2-PC::QUIET!
  (PROOF-BUILDER-COMMANDS)
  "(meta) run instructions without prover output

    Example:
    (quiet! induct prove)

    General Form:
    (quiet! &rest instruction-list)

  Run the [47minstruction-list[0m through the top-level loop with no output.
  See [ACL2-pc::quiet]; the two commands are equivalent, except that
  the [47mquiet![0m command additionally suppresses the printing of goal
  identifiers (as with [47m[set-print-clause-ids][0m).")
 (ACL2-PC::R
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) same as rewrite

    Example:
    (r 3)

  See [ACL2-pc::rewrite].")
 (ACL2-PC::REDUCE
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) call the ACL2 theorem prover's simplifier

    Examples:
    reduce -- attempt to prove the current goal without using induction
    (reduce (\"Subgoal 2\" :by foo) (\"Subgoal 1\" :use bar))
           -- attempt to prove the current goal without using
              induction, with the indicated hints

    General Form:
    (reduce &rest hints)

  Attempt to prove the current goal without using induction, using the
  indicated hints (if any).  A subgoal will be created for each goal
  that would have been pushed for proof by induction in an ordinary
  proof.

  Notice that unlike [47mprove[0m, the arguments to [47mreduce[0m are spread out, and
  are all hints.

  [47mReduce[0m is similar to [47mbash[0m in that neither of these allows induction.
  But [47mbash[0m only allows simplification, while [47mreduce[0m allows processes
  [47meliminate-destructors[0m, [47mfertilize[0m, [47mgeneralize[0m, and
  [47meliminate-irrelevance[0m.

  [31;1mRemark:[0m Induction will be used to the extent that it is ordered
  explicitly in the hints.")
 (ACL2-PC::REDUCE-BY-INDUCTION
  (PROOF-BUILDER-COMMANDS)
  "(macro) call the ACL2 prover without induction, after going into
  induction

    Examples:
    reduce-by-induction
      -- attempt to prove the current goal after going into induction,
         with no further inductions

    (reduce-by-induction (\"Subgoal 2\" :by foo) (\"Subgoal 1\" :use bar))
      -- attempt to prove the current goal after going into induction,
         with no further inductions, using the indicated hints

    General Form:
    (reduce-by-induction &rest hints)

  A subgoal will be created for each goal that would have been pushed
  for proof by induction in an ordinary proof, except that the proof
  begins with a top-level induction.

  Notice that unlike [47mprove[0m, the arguments to [47mreduce-by-induction[0m are
  spread out, and are all hints.  Also see [ACL2-pc::prove],
  [ACL2-pc::reduce], and [ACL2-pc::bash].

  [31;1mRemark[0m: Induction and the various processes will be used to the
  extent that they are specified explicitly in the [47m:induct[0m and
  [47m:do-not[0m [hints].")
 (ACL2-PC::REMOVE-ABBREVIATIONS
  (PROOF-BUILDER-COMMANDS)
  "(primitive) remove one or more abbreviations

    Examples:
    remove-abbreviations -- remove all abbreviations
    (remove-abbreviations v w)
                         -- assuming that V and W currently abbreviate
                            terms, then they are ``removed'' in the
                            sense that they are no longer considered to
                            abbreviate those terms

    General Forms:
    (remove-abbreviations &rest vars)

  If vars is not empty (i.e., not [47mnil[0m), remove the variables in [47mvars[0m
  from the current list of abbreviations, in the sense that each
  variable in [47mvars[0m will no longer abbreviate a term.

  [31;1mRemark:[0m The instruction fails if at least one of the arguments fails
  to be a variable that abbreviates a term.

  Also see [ACL2-pc::add-abbreviation] for a discussion of
  abbreviations in general, and see [ACL2-pc::show-abbreviations].")
 (ACL2-PC::REPEAT
  (PROOF-BUILDER-COMMANDS)
  "(macro) repeat the given instruction until it ``fails''

    Example:
    (repeat promote)

    General Form:
    (repeat instruction)

  The given [47minstruction[0m is run repeatedly until it ``fails''.  A call
  of [47m:repeat[0m always ``succeeds''.

  [31;1mRemark:[0m There is nothing here in general to prevent the instruction
  from being run after all goals have been proved, though it may then
  fail, thus causing [47m:repeat[0m to return.")
 (ACL2-PC::REPEAT-REC
      (PROOF-BUILDER-COMMANDS)
      "(macro) auxiliary to [47mrepeat[0m

  See [ACL2-pc::repeat].")
 (ACL2-PC::REPLAY
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) replay one or more instructions

    Examples:
    REPLAY     -- replay all instructions in the current session
                  (i.e., state-stack)
    (REPLAY 5) -- replay the most recent 5 instructions
    (REPLAY 5
            (COMMENT deleted dive command here))
               -- replace the 5th most recent instruction with the
                  indicated comment instruction, and then replay it
                  followed by the remaining 4 instructions

    General Form:
    (REPLAY &OPTIONAL n replacement-instruction)

  Replay the last [47mn[0m instructions if [47mn[0m is a positive integer; else [47mn[0m
  should be [47mnil[0m or not supplied, and replay all instructions.
  However, if [47mreplacement-instruction[0m is supplied and not [47mnil[0m, then
  before the replay, replace the [47mnth[0m instruction (from the most
  recent, as shown by [47mcommands[0m) with [47mreplacement-instruction[0m.

  If this command ``fails'', then the [47mrestore[0m command will revert the
  state-stack to its value present before the [47mreplay[0m instruction was
  executed.")
 (ACL2-PC::RESTORE
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(meta) remove the effect of an UNDO command

    Example and General Form:
    restore

  [47mRestore[0m removes the effect of an [47mundo[0m command.  This always works as
  expected if [47mrestore[0m is invoked immediately after [47mundo[0m, without
  intervening instructions.  However, other commands may also
  interact with [47mrestore[0m, notably ``sequencing'' commands such as
  [47mdo-all[0m, [47mdo-strict[0m, [47mprotect[0m, and more generally, [47msequence[0m.

  [31;1mRemark:[0m Another way to control the saving of proof-builder state is
  with the [47msave[0m command; see [ACL2-pc::save].

  The [47mrestore[0m command always ``succeeds''; it returns [47m(mv nil t state)[0m.")
 (ACL2-PC::RETAIN
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) drop all [31;1mbut[0m the indicated top-level hypotheses

    Example:
    (RETAIN 2 3) -- keep the second and third hypotheses, and drop
                    the rest

    General Form:
    (retain &rest args)

  Drop all top-level hypotheses [31;1mexcept[0m those with the indicated
  indices.

  There must be at least one argument, and all must be in range (i.e.
  integers between one and the number of top-level hypotheses,
  inclusive).")
 (ACL2-PC::RETRIEVE
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) re-enter the proof-builder

    Examples:
    (retrieve associativity-of-permutationp)
    retrieve

    General Form:
    (retrieve &optional name)

  Must be used from [47moutside[0m the interactive proof-builder loop.  If
  name (which must be a symbol) is supplied and not [47mnil[0m, this causes
  re-entry to the interactive proof-builder loop in the state at
  which [47msave[0m was last executed for the indicated name.  (See
  [ACL2-pc::save].)  If [47mname[0m is [47mnil[0m or is not supplied, then the user
  is queried regarding which proof-builder state to re-enter.  The
  query is omitted, however, if there only one proof-builder state is
  present that was saved with [47msave[0m, in which case that is the one
  that is used.  Also see [ACL2-pc::unsave].")
 (ACL2-PC::REWRITE
  (PROOF-BUILDER-COMMANDS)
  "(primitive) apply a rewrite rule

    Examples:
    (rewrite reverse-reverse)
       -- apply the rewrite rule `reverse-reverse'
    (rewrite (:rewrite reverse-reverse))
       -- same as above
    (rewrite 2)
       -- apply the second rewrite rule, as displayed by show-rewrites
    rewrite
       -- apply the first rewrite rule, as displayed by show-rewrites
    (rewrite transitivity-of-< ((y 7)))
       -- apply the rewrite rule transitivity-of-< with the substitution
          that associates 7 to the ``free variable'' y
    (rewrite foo ((x 2) (y 3)) t)
       -- apply the rewrite rule foo by substituting 2 and 3 for free
          variables x and y, respectively, and also binding all other
          free variables possible by using the current context
          (hypotheses and governors)

    General Form:
    (rewrite &optional rule-id substitution instantiate-free)

  Replace the current subterm with a new term by applying a [rewrite]
  or [definition] rule.  The replacement will be done according to
  the information provided by the [47mshow-rewrites[0m ([47msr[0m) command.

  If [47mrule-id[0m is a positive integer [47mn[0m, then the [47mn[0mth rule as displayed by
  [47mshow-rewrites[0m is the one that is applied.  If [47mrule-id[0m is [47mnil[0m or is
  not supplied, then it is treated as the number 1.  Otherwise,
  [47mrule-id[0m should be either a symbol or else a [47m:rewrite[0m or [47m:definition[0m
  [rune].  If a symbol is supplied, then any ([47m:rewrite[0m or
  [47m:definition[0m) rule of that name may be used.  We say more about
  this, and describe the other optional arguments, below.

  Consider first the following example.  Suppose that the current
  subterm is [47m(reverse (reverse y))[0m and that there is a [rewrite] rule
  called [47mreverse-reverse[0m of the form

    (implies (true-listp x)
             (equal (reverse (reverse x)) x)) .

  Then the instruction [47m(rewrite reverse-reverse)[0m causes the current
  subterm to be replaced by [47my[0m and creates a new goal with conclusion
  [47m(true-listp y)[0m.  An exception is that if the top-level hypotheses
  imply [47m(true-listp y)[0m using only ``trivial reasoning'' (more on this
  below), then no new goal is created.

  If the [47mrule-id[0m argument is a number or is not supplied, then the
  system will store an instruction of the form [47m(rewrite name ...)[0m,
  where [47mname[0m is the name of a rewrite rule; this is in order to make
  it easier to replay instructions when there have been changes to
  the history.  Except: instead of the name (whether the name is
  supplied or calculated), the system stores the [rune] if there is
  any chance of ambiguity.  (Formally, ``ambiguity'' here means that
  the rune being applied is of the form [47m(:rewrite name . index)[0m,
  where index is not [47mnil[0m.)

  Speaking in general, then, a [47mrewrite[0m instruction works as follows:

  First, a [rewrite] or [definition] rule is selected according to the
  arguments of the [47mrewrite[0m instruction.  The selection is made as
  explained under ``General Form'' above.

  Next, the left-hand side of the rule is matched with the current
  subterm, i.e., a substitution [47munify-subst[0m is found such that if one
  instantiates the left-hand side of the rule with [47munify-subst[0m, then
  one obtains the current subterm.  If this match fails, then the
  instruction fails.

  Next, an attempt is made to relieve (discharge) the hypotheses, much
  as the theorem prover relieves hypotheses except that there is no
  call to the rewriter.  First, the substitution [47munify-subst[0m is
  extended with the [47msubstitution[0m argument, which may bind free
  variables (see [free-variables]).  Each hypothesis of the rule is
  then considered in turn, from first to last.  For each hypothesis,
  first the current substitution is applied, and then the system
  checks whether the hypothesis is ``clearly'' true in the current
  context.  If there are variables in the hypotheses of the rule that
  are not bound by the current substitution, then a weak attempt is
  made to extend that substitution so that the hypothesis is present
  in the current context (see [ACL2-pc::hyps]), much as would be done
  by the theorem prover's rewriter.

  If in the process above there are free variables (see
  [free-variables]), but the interactive proof-builder can see how to
  bind them to relieve all hypotheses, then it will do so in both the
  [47mshow-rewrites[0m ([47msr[0m) and [47mrewrite[0m commands.  But normally, if even one
  hypothesis remains unrelieved, then no automatic extension of the
  substitution is made.  Except, if [47minstantiate-free[0m is not [47mnil[0m, then
  that extension to the substitution is kept.  (Technical note: in
  the case of an unrelieved hypothesis and a non-[47mnil[0m value of
  [47minstantiate-free[0m, if a [47m[bind-free][0m hypothesis produces a list of
  binding alists, then the last of those alists is the one that is
  used to extend the substitution.)

  Finally, the instruction is applied as follows.  The current subterm
  is replaced by applying the final substitution described above to
  the right-hand side of the selected rule.  And, one new subgoal is
  created for each unrelieved hypothesis of the rule, whose top-level
  hypotheses are the governors and top-level hypotheses of the
  current goal and whose conclusion and current subterm are the
  instance, by that same final substitution, of that unrelieved
  hypothesis.

  [31;1mRemark:[0m The substitution argument should be a list whose elements
  have the form [47m(variable term)[0m, where [47mterm[0m may contain
  abbreviations.")
 (ACL2-PC::RUN-INSTR-ON-GOAL
      (PROOF-BUILDER-COMMANDS)
      "(macro) auxiliary to THEN

  See [ACL2-pc::then].")
 (ACL2-PC::RUN-INSTR-ON-NEW-GOALS
      (PROOF-BUILDER-COMMANDS)
      "(macro) auxiliary to [47mthen[0m

  See [ACL2-pc::then].")
 (ACL2-PC::RUNES
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) print the runes (definitions, lemmas, ...) used

    Examples and general forms:
    (runes t)   ; print all [rune]s used during this interactive proof
    (runes nil) ; print all [rune]s used by the most recent command
    (runes)     ; same as (runes nil)
    runes       ; same as (runes nil)

  This command does not change the state of the interactive
  [proof-builder].  Rather, it simply reports runes (see [rune]) that
  have participated in the interactive proof.

  Note that [47m(runes nil)[0m will show the [rune]s used by the most recent
  primitive or macro command (as displayed by [47m:comm[0m).")
 (ACL2-PC::S
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) simplify the current subterm

    Examples:
    S  -- simplify the current subterm
    (S :backchain-limit 2 :normalize t :expand (append x z))
       -- simplify the current subterm, but during the rewriting
          process, normalization, which will push IFs to the
          top-level, and also force the term (append x z) to be
          expanded during the rewriting process

    General Form:
    (s &key rewrite linear normalize backchain-limit repeat in-theory hands-off
            expand)

  Simplify the current subterm according to the keyword parameters
  supplied.  First [normalization] is applied (unless the [47m:normalize[0m
  argument is [47mnil[0m), so that for example, each subterm of the form [47m(f
  ... (if test x y) ...)[0m is replaced by the term [47m(if test (f ... x
  ...) (f ... y ...))[0m --- except, of course, when [47mf[0m is [47mif[0m and the
  indicated [47mif[0m subterm is in the second or third argument position.
  See [normalize] for details.  Then rewriting is applied (unless the
  rewrite argument is [47mnil[0m).  Finally this pair of actions is repeated
  --- until the rewriting step causes no change in the term.  A
  description of each parameter follows.

    :rewrite -- default t

  When non-[47mnil[0m, instructs the system to use ACL2's rewriter (or,
  something close to it) during simplification.

    :linear -- default t (except, default nil if :rewrite has value nil)

  When non-[47mnil[0m, instructs the system to use ACL2's linear arithmetic
  (see [LINEAR-ARITHMETIC]) to build a suitable context (a ``linear
  pot list'') from the assumptions (the top-level hypotheses and the
  governors (see [ACL2-PC::HYPS])).  Note that linear arithmetic is
  used by the rewriter regardless; by default, when [47m:s[0m invokes the
  rewriter then linear arithmetic can take advantage of the
  information in the top-level hypotheses and the governors.

    :normalize -- default t

  When non-[47mnil[0m, instructs the system to use [normalization] (as
  described above) during simplification.

    :backchain-limit -- default 0

  Sets the number of recursive calls to the rewriter that are allowed
  for backchaining.  Even with the default of 0, some reasoning is
  allowed (technically speaking, type reasoning (see
  [TYPE-REASONING]) is allowed) in the relieving of hypotheses.  The
  value should be [47mnil[0m or a non-negative integer, and limits
  backchaining only for rewriting, not for type reasoning.

    :repeat -- default 0

  Sets the number of times the current term is to be rewritten.  If
  this value is [47mt[0m, then the default is used (as specified by the
  constant [47m*default-s-repeat-limit*[0m).

    :in-theory, :hands-off, :expand

  These have their usual meaning; see [hints].

  [31;1mRemark:[0m if conditional rewrite rules are used that cause case splits
  because of the use of [47mforce[0m, then appropriate new subgoals will be
  created, i.e., with the same current subterm (and address) but with
  each new (forced) hypothesis being negated and then used to create
  a corresponding new subgoal.  In that case, the current goal will
  have all such new hypotheses added to the list of top-level
  hypotheses.")
 (ACL2-PC::S-PROP
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) simplify propositionally

    Example:
    s-prop

    General Form:
    (s-prop &rest names)

  Simplify, using the default settings for [47ms[0m (which include
  [normalization] and rewriting without real backchaining), but with
  respect to a theory in which only basic functions and rules (the
  ones in [47m(theory 'minimal-theory)[0m), together with the names (or
  parenthesized names) in the [47m&rest[0m argument [47mnames[0m, are enabled.

  Also see [ACL2-pc::s].")
 (ACL2-PC::SAVE
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) save the proof-builder state (state-stack)

    Example:
    (save lemma3-attempt)

    General Form:
    (save &optional name do-it-flg)

  Saves the current state of the interactive proof-builder by
  ``associating'' it with the given name, which must be a symbol.
  Submit [47m(retrieve name)[0m to Lisp to get back to this proof-builder
  state.  If [47mverify[0m was originally supplied with an event name, then
  the argument can be omitted in favor of that name as the default.

  [31;1mRemark[0m that if a [47msave[0m has already been done with the indicated name
  (or the default event name), then the user will be queried
  regarding whether to go ahead with the save --- except, if
  [47mdo-it-flg[0m is supplied and not [47mnil[0m, then there will be no query and
  the [47msave[0m will be effected.

  Also see [ACL2-pc::retrieve] and [ACL2-pc::unsave].")
 (ACL2-PC::SEQUENCE
  (PROOF-BUILDER-COMMANDS)
  "(meta) run the given list of instructions according to a multitude of
  options

    Example:
    (sequence (induct p prove) t)

  This is a very general command that is used to define other
  sequencing commands; see [ACL2-pc::do-all], [ACL2-pc::do-strict],
  [ACL2-pc::protect], and [ACL2-pc::succeed].

    General Form:
    (sequence
     instruction-list
     &optional
     strict-flg protect-flg success-expr no-prompt-flg no-restore-flg)

  Each instruction in the list [47minstruction-list[0m is run, and the
  instruction ``succeeds'' if every instruction in [47minstruction-list[0m
  ``succeeds''.  However, it might ``succeed'' even if some
  instructions in the list ``fail''; more generally, the various
  arguments control a number of aspects of the running of the
  instructions.  All this is explained in the paragraphs below.
  First we embark on a general discussion of the instruction
  interpreter, including the notions of ``succeed'' and ``fail''.

  [31;1mRemark:[0m The arguments are [31;1mnot[0m evaluated, except (in a sense) for
  [47msuccess-expr[0m, as described below.

  Each primitive and meta instruction can be thought of as returning an
  [error-triple], say [47m(erp val state)[0m.  An instruction (primitive or
  meta) ``succeeds'' if [47merp[0m is [47mnil[0m and [47mval[0m is not [47mnil[0m; otherwise it
  ``fails''.  (When we use the words ``succeed'' or ``fail'' in this
  technical sense, we'll always include them in double quotes.)  If
  an instruction ``fails,'' we say that the failure is ``soft'' if
  [47merp[0m is [47mnil[0m; otherwise the failure is ``hard''.  The [47msequence[0m
  command gives the user control over how to treat ``success'' and
  ``failure'' when sequencing instructions, though we have created a
  number of handy macro commands for this purpose, notably [47mdo-all[0m,
  [47mdo-strict[0m and [47mprotect[0m.

  Here is precisely what happens when a [47msequence[0m instruction is run.
  The instruction interpreter is run on the instructions supplied in
  the argument [47minstruction-list[0m (in order).  The interpreter halts
  the first time there is a hard ``failure.'' except that if
  [47mstrict-flg[0m is supplied and not [47mnil[0m, then the interpreter halts the
  first time there is any ``failure.'' The error triple [47m(erp val
  state)[0m returned by the [47msequence[0m instruction is the triple returned
  by the last instruction executed (or, the triple [47m(nil t state)[0m if
  [47minstruction-list[0m is [47mnil[0m), except for the following provision.  If
  [47msuccess-expr[0m is supplied and not [47mnil[0m, then it is evaluated with the
  state global variables [47mpc-erp[0m and [47mpc-val[0m (in the \"ACL2\" package)
  bound to the corresponding components of the error triple returned
  (as described above).  At least two values should be returned, and
  the first two of these will be substituted for [47merp[0m and [47mval[0m in the
  triple finally returned by [47msequence[0m.  For example, if [47msuccess-expr[0m
  is [47m(mv erp val)[0m, then no change will be made to the error triple,
  and if instead it is [47m(mv nil t)[0m, then the [47msequence[0m instruction will
  ``succeed''.

  That concludes the description of the error triple returned by a
  [47msequence[0m instruction, but it remains to explain the effects of the
  arguments [47mprotect-flg[0m and [47mno-prompt-flg[0m.

  If [47mprotect-flg[0m is supplied and not [47mnil[0m and if also the instruction
  ``fails'' (i.e., the error component of the triple is not [47mnil[0m or
  the value component is [47mnil[0m), then the state is reverted so that the
  interactive proof-builder's state (including the behavior of
  [47mrestore[0m) is set back to what it was before the [47msequence[0m instruction
  was executed.  Otherwise, unless [47mno-restore-flg[0m is set, the state
  is changed so that the [47mrestore[0m command will now undo the effect of
  this [47msequence[0m instruction (even if there were nested calls to
  [47msequence[0m).

  Finally, as each instruction in [47minstruction-list[0m is executed, the
  prompt and that instruction will be printed, unless the global
  state variable [47mpc-print-prompt-and-instr-flg[0m is unbound or [47mnil[0m and
  the parameter [47mno-prompt-flg[0m is supplied and not [47mnil[0m.")
 (ACL2-PC::SHOW-ABBREVIATIONS
  (PROOF-BUILDER-COMMANDS)
  "(macro) display the current abbreviations

    Examples:
    (show-abbreviations v w)
       -- assuming that v and w currently abbreviate terms,
          then this instruction displays them together with
          the terms they abbreviate
    show-abbreviations
       -- display all abbreviations

  Also see [ACL2-pc::add-abbreviation] for a general discussion of
  abbreviations and see [ACL2-pc::remove-abbreviations].

    General Form:
    (show-abbreviations &rest vars)

  Display each argument in [47mvars[0m together with the term it abbreviates
  (if any).  If there are no arguments, i.e. the instruction is
  simply [47mshow-abbreviations[0m, then display all abbreviations together
  with the terms they abbreviate.

  If the term abbreviated by a variable, say [47mv[0m, contains a proper
  subterm that is also abbreviate by (another) variable, then both
  the unabbreviated term and the abbreviated term (but not using [47m(?
  v)[0m to abbreviate the term) are displayed with together with [47mv[0m.")
 (ACL2-PC::SHOW-LINEARS
  (PROOF-BUILDER-COMMANDS)
  "(macro) display the applicable [linear] rules

    Example:
    show-linears

    General Form:
    (show-linears &optional rule-id enabled-only-flg)

  This command displays [linear] rules with a trigger term that matches
  the current subterm, and shows how they can be applied.  This
  command is analogous to the [47mshow-rewrites[0m [proof-builder] command;
  see [ACL2-pc::show-rewrites].  Also see [ACL2-pc::apply-linear] for
  how to apply [linear] rules.")
 (ACL2-PC::SHOW-REWRITES
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) display the applicable [rewrite] rules

    Example:
    show-rewrites

    General Form:
    (show-rewrites &optional rule-id enabled-only-flg)

  This command displays [rewrite] rules whose left-hand side matches
  the current subterm, and shows how that command can be applied.
  For each rule displayed, hypotheses are shown that would need to be
  proved after the rule is applied.  Note that hypotheses are omitted
  from the display when the system can trivially verify that they
  hold; to see all hypotheses for each rule in a display that is
  independent of the arguments of the current subterm, use the [47mpl[0m or
  [47mpr[0m command.

  Here are details on the arguments and the output.  If [47mrule-id[0m is
  supplied and is a name (non-[47mnil[0m symbol) or a [47m:[0m[47m[rewrite][0m or
  [47m:[0m[47m[definition][0m [rune], then only the corresponding rewrite rule(s)
  will be displayed, while if [47mrule-id[0m is a positive integer [47mn[0m, then
  only the [47mn[0mth rule that would be in the list is displayed.  In each
  case, the display will point out when a rule is currently disabled
  (in the interactive environment), except that if [47menabled-only-flg[0m
  is supplied and not [47mnil[0m, then disabled rules will not be displayed
  at all.  Finally, among the free variables of any rule (see
  [free-variables]), those that would remain free if the rule were
  applied will be displayed.  Also see [rewrite].")
 (ACL2-PC::SHOW-TYPE-PRESCRIPTIONS
  (PROOF-BUILDER-COMMANDS)
  "(macro) display the applicable [type-prescription] rules

    Example:
    show-type-prescriptions

    General Form:
    (show-type-prescriptions &optional rule-id)

  Display [type-prescription] rules that apply to the current subterm.
  If [47mrule-id[0m is supplied and is a name (non-[47mnil[0m symbol) or a
  [47m:[0m[47m[rewrite][0m or [47m:[0m[47m[definition][0m [rune], then only the corresponding
  rewrite rule(s) will be displayed.  In each case, the display will
  point out when a rule is currently disabled (in the interactive
  environment).  Also see [type-prescription].")
 (ACL2-PC::SKIP
  (PROOF-BUILDER-COMMANDS)
  "(macro) ``succeed'' without doing anything

    Example and General Form:
    skip

  Make no change in the state-stack, but ``succeed''.  Same as
  [47m(sequence nil)[0m.")
 (ACL2-PC::SL
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) simplify with lemmas

    Examples:
    sl
    (sl 3)

    General Form:
    (sl &optional backchain-limit)

  Simplify, but with all function definitions disabled (see
  [function-theory] in the top-level ACL2 loop), except for a few
  basic functions (the ones in [47m(theory 'minimal-theory)[0m).  The
  [47mbackchain-limit[0m has a default of 0, but if it is supplied and not
  [47mnil[0m, then it should be a nonnegative integer; see [ACL2-pc::s].

  WARNING: This command completely ignores [47min-theory[0m commands that are
  executed inside the interactive [proof-builder].")
 (ACL2-PC::SLS
  (PROOF-BUILDER-COMMANDS)
  "(macro) same as SHOW-LINEARS

    Example:
    sls

    General Form:
    (sls &optional rule-id enabled-only-flg)

  See [ACL2-pc::show-linears].  NOTE: In analogy to the [47msr[0m abbreviation
  for [47mshow-rewrites[0m, one might expect this command to be [47msl[0m; but that
  name was taken (``simplify with lemmas'') before [47msls[0m was
  implemented.")
 (ACL2-PC::SPLIT
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) split the current goal into cases

    Example:
    split

  For example, if the current goal has one hypothesis [47m(or x y)[0m and a
  conclusion of [47m(and a b)[0m, then [47msplit[0m will create four new goals:

    one with hypothesis X and conclusion A
    one with hypothesis X and conclusion B
    one with hypothesis Y and conclusion A
    one with hypothesis Y and conclusion B.

    General Form:
    SPLIT

  Replace the current goal by subgoals whose conjunction is equivalent
  (primarily by propositional reasoning) to the original goal, where
  each such goal cannot be similarly split.

  [31;1mRemark:[0m The new goals will all have their hypotheses promoted; in
  particular, no conclusion will have a top function symbol of
  [47mimplies[0m.  Also note that [47msplit[0m will fail if there is exactly one
  new goal created and it is the same as the existing current goal.

  The way [47msplit[0m really works is to call the ACL2 theorem prover with
  only simplification (and preprocessing) turned on, and with only a
  few built-in functions (especially, propositional ones) enabled,
  namely, the ones in the list [47m(theory 'minimal-theory)[0m.  However,
  because the prover is called, [type-reasoning] can be used to
  eliminate some cases.  For example, if [47m(true-listp x)[0m is in the
  hypotheses, then probably [47m(true-listp (cdr x))[0m will be reduced to
  [47mt[0m.")
 (ACL2-PC::SR
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) same as SHOW-REWRITES

    Example:
    sr

    General Form:
    (sr &optional rule-id enabled-only-flg)

  See [ACL2-pc::show-rewrites].")
 (ACL2-PC::ST
  (PROOF-BUILDER-COMMANDS)
  "(macro) same as SHOW-TYPE-PRESCRIPTIONS

    Example:
    sr

    General Form:
    (st &optional rule-id)

  See [ACL2-pc::show-type-prescriptions].")
 (ACL2-PC::SUCCEED
  (PROOF-BUILDER-COMMANDS)
  "(macro) run the given instructions, and ``succeed''

    Example:
    (succeed induct p prove)

    General Form:
    (succeed &rest instruction-list)

  Run the indicated instructions until there is a hard ``failure'', and
  ``succeed''.  (See [ACL2-pc::sequence] for an explanation of
  ``success'' and ``failure''.)")
 (ACL2-PC::TH
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(macro) print the top-level hypotheses and the current subterm

    Examples:
    th               -- print all (top-level) hypotheses and the current
                        subterm
    (th (1 3) (2 4)) -- print hypotheses 1 and 3 and governors 2 and 4,
                        and the current subterm
    (th (1 3) t)     -- print hypotheses 1 and 3 and all governors, and
                        the current subterm

    General Form:
    (th &optional hyps-indices govs-indices)

  Print hypotheses and the current subterm.  The printing of hypotheses
  (and perhaps governors) are controlled as in the [47mhyps[0m command; see
  [ACL2-pc::hyps].

  Historical note: The name [47mth[0m is adapted from the Gypsy Verification
  Environment, where [47mth[0m abbreviates the command [47mtheorem[0m, which says
  to print information on the current goal.")
 (ACL2-PC::THEN
  (PROOF-BUILDER-COMMANDS)
  "(macro) apply one instruction to current goal and another to new
  subgoals

    Example:
    (then induct prove)

    General Form:
    (then first-instruction &optional completion must-succeed-flg)

  Run [47mfirst-instruction[0m, and then run [47mcompletion[0m (another instruction)
  on each subgoal created by [47mfirst-instruction[0m.  If [47mmust-succeed-flg[0m
  is supplied and not [47mnil[0m, then halt at the first ``failure'' and
  remove the effects of the invocation of [47mcompletion[0m that ``failed''.

  The default for completion is [47mreduce[0m.")
 (ACL2-PC::TOP
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) move to the top of the goal

    Example and General Form:
    top

  For example, if the conclusion is [47m(= x (* (- y) z))[0m and the current
  subterm is [47my[0m, then after executing [47mtop[0m, the current subterm will be
  the same as the conclusion, i.e., [47m(= x (* (- y) z))[0m.

  [47mTop[0m is the same as [47m(up n)[0m, where [47mn[0m is the number of times one needs
  to execute [47mup[0m in order to get to the top of the conclusion.  The
  [47mtop[0m command fails if one is already at the top of the conclusion.

  Also see [ACL2-pc::up], [ACL2-pc::dive], [ACL2-pc::nx], and
  [ACL2-pc::bk].")
 (ACL2-PC::TYPE-ALIST
  (PROOF-BUILDER-COMMANDS)
  "(macro) display the [type-alist] from the current context

    Examples:
    (type-alist nil t nil) ; display type-alist based on governors (default)
    type-alist             ; same as (type-alist nil t) -- governors only
    (type-alist t t)       ; display type-alist based on conclusion and governors
    (type-alist t t t)     ; as above, but also display forward-chaining report
    type-alist             ; same as (type-alist nil t) -- governors only
    (type-alist nil)       ; same as (type-alist nil t) -- governors only
    (type-alist t)         ; same as (type-alist t nil) -- conclusion only
    (type-alist nil nil)   ; based on neither conclusion nor governors
    (type-alist nil t nil nil)  ; same as type-alist (default) -- governors only
    (type-alist nil t nil :raw) ; governors only, raw alist format
    (type-alist nil t nil t)    ; governors only, simple alist format

    General Form:
    (type-alist &optional concl-flg govs-flg fc-report-flg alistp)

  where if [47mgovs-flg[0m is omitted then it defaults to [47m(not concl-flg)[0m, and
  each of the other optional arguments defaults to [47mnil[0m.

  Display the current assumptions as a [type-alist].  Note that this
  display includes the result of forward chaining.  When
  [47mfc-report-flg[0m is supplied a non-[47mnil[0m value, the display also
  includes a forward-chaining report; otherwise,the presence or
  absence of such a report is controlled by the usual global settings
  (see [forward-chaining-reports]).  By default, the display is
  organized by type, with terms shown of each type; but when [47malistp[0m
  is [47m:raw[0m then the underlying type-alist structure is shown, which is
  made more user-friendly when any other non-[47mnil[0m value of [47malistp[0m is
  provided.

  There are two basic reasons contemplated for using this command.

  1. The theorem prover has failed (either outside the interactive
  proof-builder or using a proof-builder command such as [47mbash[0m or
  [47mreduce[0m and you want to debug by getting an idea of what the prover
  knows about the context.

      a. You really are interested in the context for the current term.
      Include hypotheses and governors (i.e., accounting for tests of
      surrounding [47mif[0m-expressions that must be true or false) but not
      the current conclusion (which the theorem prover's heuristics
      would generally ignore for contextual information).  Command:
      [47m(type-alist nil t)[0m ; equivalently, [47mtype-alist[0m or [47m(type-alist nil)[0m

      b. You are not thinking in particular about the current term; you
      just want to get an idea of the context that the prover would
      build at the top-level, for forward-chaining.  Incorporate the
      conclusion but not the governors.  Command:
      [47m(type-alist t nil)[0m ; equivalently, [47m(type-alist t)[0m

  2. You intend to use one of the interactive [proof-builder-commands]
  that does simplification, such as [47ms[0m or [47mx[0m, and you want to see the
  context.  Then include the surrounding [47mif[0m-term governors but not
  the goal's conclusion.  Command:
  [47m(type-alist nil t)[0m ; equivalently, [47mtype-alist[0m or [47m(type-alist nil)[0m

  See [type-set] (also see [type-prescription]) for information about
  ACL2's type system, which can assist in understanding the output of
  the [47mtype-alist[0m command.")
 (ACL2-PC::UNDO
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(meta) undo some instructions

    Examples:
    (undo 7)
    undo

    General Forms:

    (undo n) -- Undo the last n instructions.  The argument n should be
                a positive integer.

    undo     -- Same as (undo 1).

  [31;1mRemark:[0m To remove the effect of an [47mundo[0m command, use [47mrestore[0m; see
  [ACL2-pc::restore].

  [31;1mRemark:[0m If the argument [47mn[0m is greater than the total number of
  interactive instructions in the current session, then [47m(undo n)[0m will
  simply take you back to the start of the session.

  The [47mundo[0m meta command always ``succeeds''; it returns [47m(mv nil t
  state)[0m unless its optional argument is supplied and of the wrong
  type (i.e. not a positive integer) or there are no instructions to
  undo.")
 (ACL2-PC::UNSAVE
  (PROOF-BUILDER-COMMANDS)
  "(macro) remove a proof-builder state

    Example:
    (unsave assoc-of-append)

    General Form:
    (unsave &optional name)

  Eliminates the association of an interactive proof-builder state with
  [47mname[0m, if [47mname[0m is supplied and not [47mnil[0m.  The name may be [47mnil[0m or not
  supplied, in which case it defaults to the event name supplied with
  the original call to [47mverify[0m (if there is one --- otherwise, the
  instruction ``fails'' and there is no change).  The ACL2 function
  [47munsave[0m may also be executed outside the interactive loop, with the
  same syntax.

  Also see [ACL2-pc::save] and [ACL2-pc::retrieve].")
 (ACL2-PC::UP
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(primitive) move to the parent (or some ancestor) of the current
  subterm

    Examples:  if the conclusion is (= x (* (- y) z)) and the
               current subterm is y, then we have:
    up or (up 1) -- the current subterm becomes (- y)
    (up 2)       -- the current subterm becomes (* (- y) z)
    (up 3)       -- the current subterm becomes the entire conclusion
    (up 4)       -- no change; can't go up that many levels

    General Form:
    (up &optional n)

  Move up [47mn[0m levels in the conclusion from the current subterm, where [47mn[0m
  is a positive integer.  If [47mn[0m is not supplied or is [47mnil[0m, then move
  up one level, i.e., treat the instruction as [47m(up 1)[0m.

  Also see [ACL2-pc::dive], [ACL2-pc::top], [ACL2-pc::nx], and
  [ACL2-pc::bk].")
 (ACL2-PC::USE
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) use a lemma instance

    Example:
    (USE true-listp-append
         (:instance assoc-of-append (x a) (y b) (z c)))
    -- Add two top-level hypotheses, one the lemma called
       true-listp-append, and the other an instance of the lemma called
       assoc-of-append by the substitution in which x is assigned a, y
       is assigned b, and z is assigned c.

    General Form:
    (use &rest args)

  Add the given lemma instances to the list of top-level hypotheses.
  See [hints] for the syntax of [47m:use[0m hints in [47mdefthm[0m, which is
  essentially the same as the syntax here (see the example above).

  This command calls the [47mprove[0m command, and hence should only be used
  at the top of the conclusion.")
 (ACL2-PC::WRAP
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) execute the indicated instructions and combine all the
  new goals

    Example:
    (wrap induct) ; induct, then replace first new goal by the conjunction of all
                  ; the new goals, and drop all new goals after the first

    General Form:
    (wrap &rest instrs)

  First the instructions in [47minstrs[0m are executed, as in [47mdo-all[0m.  If this
  ``fails'' then no additional action is taken.  Otherwise, the
  current goal after execution of [47minstrs[0m is conjoined with all
  ``new'' goals, in the sense that their names are not among the
  names of goals at the time [47minstrs[0m was begun.  This conjunction
  becomes the new current goal and those ``new'' goals are dropped.

  See the code for the interactive [proof-builder] command,
  [47mwrap-induct[0m, for an example of the use of [47mwrap[0m.")
 (ACL2-PC::WRAP-INDUCT
  (PROOF-BUILDER-COMMANDS)
  "(atomic macro) same as induct, but create a single goal

    Examples:
    wrap-induct
    (wrap-induct t)
    (wrap-induct (append (reverse x) y))

    General Form:
    (wrap-induct &optional term)

  The [47mwrap-induct[0m command is identical to the interactive
  [47m[proof-builder][0m's [47minduct[0m command (see [ACL2-pc::induct]), except
  that only a single goal is created: the conjunction of the base and
  induction steps.

  Note: The output will generally indicate that more than goal has been
  created, e.g.:

    Creating two new goals:  (MAIN . 1) and (MAIN . 2).

  However, [47mwrap-induct[0m always creates a unique goal (when it succeeds).
  A subsequent message clarifies this, for example:

    NOTE: Created ONLY one new goal, which is the current goal:
      (MAIN . 1)")
 (ACL2-PC::WRAP1
  (PROOF-BUILDER-COMMANDS)
  "(primitive) combine goals into a single goal

    Examples:
    ; Keep (main . 1) and (main . 2) if they exist, as well as the current goal;
    ; and for each other goal, conjoin it into the current goal and delete it:
    (wrap1 ((main . 1) (main . 2)))

    ; As explained below, conjoin all subsequent siblings of the current goal
    ; into the current goal, and then delete them:
    (wrap1)

    General Form:
    (wrap1 &optional kept-goal-names)

  If [47mkept-goal-names[0m is not [47mnil[0m, the current goal is replaced by
  conjoining it with all goals other than the current goal and those
  indicated by [47mkept-goal-names[0m, and those other goals are deleted.
  If [47mkept-goal-names[0m is omitted, then the current goal must be of the
  form [47m(name . n)[0m, and the goals to conjoin into the current goal
  (and delete) are those with names of the form [47m(name . k)[0m for [47mk[0m >=
  [47mn[0m.

  NOTE: [47mWrap1[0m always ``succeeds'', even if there are no other goals to
  conjoin into the current goal (a message is printed in that case),
  and it always leaves you with no hypotheses at the top of the
  current goal's conclusion (as though [47mtop[0m and [47mdemote[0m had been
  executed, if necessary).

  Also see [ACL2-pc::wrap].")
 (ACL2-PC::X
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) expand and (maybe) simplify function call at the
  current subterm

    Examples:
    x --  expand and simplify.

  Also see [ACL2-pc::expand] and see [ACL2-pc::x-dumb], which do not
  perform simplification.

  For example, if the current subterm is (append a b), then after [47mx[0m the
  current subterm will probably be (cons (car a) (append (cdr a) b))
  if (consp a) is among the top-level hypotheses and governors.  If
  there are no top-level hypotheses and governors, then after [47mx[0m the
  current subterm will probably be:

    (if (consp a)
        (cons (car a) (append (cdr a) b))
        b).

    General Form:
    (X &key
       rewrite normalize backchain-limit in-theory hands-off expand)

  Expand the function call at the current subterm, and simplify using
  the same conventions as with the [47ms[0m command (see [ACL2-pc::s]).

  Unlike [47ms[0m, it is permitted to set both [47m:rewrite[0m and [47m:normalize[0m to [47mnil[0m,
  which will result in no simplification; see [ACL2-pc::x-dumb].

  [31;1mRemark[0m (obscure): On rare occasions the current address may be
  affected by the use of [47mx[0m.  For example, suppose we have the
  definition

    (defun g (x) (if (consp x) x 3))

  and then we enter the interactive proof-builder with

    (verify (if (integerp x) (equal (g x) 3) t)) .

  Then after invoking the instruction [47m(dive 2 1)[0m, so that the current
  subterm is [47m(g x)[0m, followed by the instruction [47mx[0m, we would expect
  the conclusion to be [47m(if (integerp x) (equal 3 3) t)[0m.  However, the
  system actually replaces [47m(equal 3 3)[0m with [47mt[0m (because we use the
  ACL2 term-forming primitives), and hence the conclusion is actually
  [47m(if (integerp x) t t)[0m.  Therefore, the current address is put at
  [47m(2)[0m rather than [47m(2 1)[0m.  In such cases, a warning ``[47mNOTE[0m'' will be
  printed to the terminal.

  The other primitive commands to which the above ``truncation'' note
  applies are [47mequiv[0m, [47mrewrite[0m, and [47ms[0m.")
 (ACL2-PC::X-DUMB
  (PROOF-BUILDER-COMMANDS PROOF-BUILDER-COMMANDS-SHORT-LIST)
  "(atomic macro) expand function call at the current subterm, without
  simplifying

    General Form:
    x-dumb:  expand without simplification.

  Same as [47m(expand t)[0m.  See [ACL2-pc::expand].

  Also see [ACL2-pc::x], which performs simplification.")
 (BIB::BEVIER87
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "W. R. Bevier, [3mVerified Operating System Kernel[0m
  [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/bevier.pdf)[0m, University of
  Texas at Austin, Ph.D. dissertation, 1987.
  [31;1mRelevance:[0m first verified operating system and a component of the CLI
  stack

---------
  The verified operating system kernel used in the CLI Verified Stack
  as reported in [bib::bhmy89] is described here.

  See the Nqthm script [47mexamples/bevier/kit.events[0m.")
 (BIB::BGM90
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. S. Boyer, M. W. Green, and J S. Moore, ``{The Use of a Formal
  Simulator to Verify a Simple Real Time Control Program |
  http://www.cs.utexas.edu/users/moore/publications/controller.pdf}'',
  in W.H.J. Feijen, A.J.M. van Gasteren, D. Gries, and J. Misra,
  editors, [3mBeauty is Our Business: A Birthday Salute to Edsger W.
  Dijkstra[0m, Springer-Verlag Texts and Monographs in Computer Science,
  pp. 54-66, 1990.
  [31;1mRelevance:[0m operational semantics modeling a hybrid physical/digital
  system

---------
  Abstract

  We present an initial and elementary investigation of the formal
  specification and mechanical verification of programs that interact
  with environments.  We describe a formal, mechanically produced
  proof that a simple real time control program keeps a vehicle on a
  straightline course in a variable crosswind.  To formalize the
  specification we define a mathematical function which models the
  interaction of the program and its environment.  We then state and
  prove two theorems about this function: the simulated vehicle never
  gets farther than three units away from the intended course and
  homes to the course if the wind remains steady for at least four
  sampling intervals.

---------
  It is easiest to think of the problem as a one-dimensional control
  problem, e.g., a thermostat or speed control.  But the problem was
  posed as follows.  Consider the task of steering a vehicle along
  the x-axis with a crosswind along the y-axis.  The wind speed
  varies.  The vehicle carries a sensor that indicates whether the
  vehicle is above, on, or below the x-axis.  The vehicle also has
  actuators that can adjust the sideways velocity of vehicle by a
  fixed amount.  Write, specify, and verify a control program that
  never allows the vehicle to drift too far from the x-axis and homes
  to the x-axis when the wind stays steady sufficiently long.

  This can be modeled as a ``clocked'' state machine, except the clock
  is a sequence of changes in wind velocity.  The ``physics'' is
  modeled extremely simply because the prover only supported natural
  numbers; but anybody who has ever written a simulator of a physical
  system will recognize it.  The proof involved defining and
  verifying an invariant on the state, under the assumption that the
  wind changed sufficiently smoothly.

  The work was done at SRI, probably between 1979 and 1980.  It was
  submitted for publication at that time but rejected because its
  formal approach to real-time control was too unconventional.  The
  reviewers overlooked the fact that this approach accommodated a
  hybrid system, where the control program was digital but the
  ``simulator'' was describing the physical world.  It was eventually
  published about a decade after the work was done, when the authors
  were invited to submit a paper to a volume in honor of Edsger
  Dijkstra.

  See the Nqthm script [47mexamples/basic/controller.events[0m.")
 (BIB::BH97
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "B. Brock and W. A. Hunt, Jr., ``{Formally Specifying and Mechanically
  Verifying Programs for the Motorola Complex Arithmetic Processor
  DSP | https://ieeexplore.ieee.org/document/628846}'', in [3m1997 IEEE
  International Conference on Computer Design[0m, IEEE Computer Society,
  pp. 31-36, October, 1997.
  [31;1mRelevance:[0m first public announcement of the CAP DSP formalization
  (this short article was superseded by [bib::bh99])

---------
  Abstract

  We describe our formal specification of Motorola's Complex Arithmetic
  Processor (CAP) DSP and our subsequent use of this specification to
  verify the correctness of several DSP algorithms. We wrote the
  specification in the ACL2 logic and carried out the mechanical
  proofs using the ACL2 theorem-proving system. Motorola's CAP is a
  super-scalar, pipelined DSP with seven memories and more than 20
  functional units. Our formal specification is bit-for-bit exact,
  and was created by hand translating Motorola's drawings for the
  CAP. We believe that the specification developed is the largest of
  its kind, as this is the only formal specification of which we are
  aware for a complete commercial design. Proving the correctness of
  the DSP algorithms (programs) required proving the correctness of
  programs with 317-bit instructions and a non-interlocking execution
  pipeline. This Motorola DSP has a 1.8 million transistor
  implementation. This project involved both CLI and Motorola
  personnel and represents more than eight man-years of effort.

---------
  See the discussion of the CAP DSP project in
  [operational-semantics-2__other-examples].")
 (BIB::BH99
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "B. Brock and W. A. Hunt, Jr., ``{Formal Analysis of the Motorola CAP
  DSP'' |
  https://link.springer.com/chapter/10.1007/978-1-4471-0523-7_5#citeas},
  in M. Hinchey and J. Bowen, editors, [3mIndustrial-Strength Formal
  Methods[0m, Springer-Verlag, pp. 81-115, 1999.
  [31;1mRelevance:[0m first industrial application of operational semantics with
  ACL2 and the first complete formal specification of a commercially
  designed microprocessor

---------
  Abstract

  We describe our formal specification of Motorola's Complex Arithmetic
  Processor (CAP) Digital Signal Processor (DSP) and our subsequent
  use of this specification in formal analyses of the CAP hardware
  and software. The CAP was designed by Motorola Government Systems
  and Technology Group (Scottsdale, Arizona), which, as a part of
  their business, builds and sells purpose-built products. The CAP is
  an ASIC that was designed to efficiently implement a number of
  signal processing algorithms required in digital communications.
  Motorola's CAP is a super-scalar, pipelined DSP with seven memories
  and more than 20 functional units. Motorola's specification for the
  CAP was captured using the Cadence Signal Processing (SPW)
  (Cadence, 1994) toolsuite; the design is represented as a series of
  drawings that specify register files, data manipulation units, and
  interconnecting busses. We have completely specified the CAP
  (Gilfeather et al, 1994) using the formal logic ACL2 (Kaufmann and
  Moore, 1996). Our specification is executable and can be used as a
  simulator as well as a basis for proving the correctness of the CAP
  hardware design and CAP programs. We believe our specification is
  bit-for-bit exact with respect to the SPW specification produced by
  Motorola, and was created by hand translating Motorola's SPW
  drawings for the CAP. We have used our CAP specification to analyse
  the CAP instruction pipeline and various CAP algorithms. We believe
  that the specification developed is the largest of its kind, as
  this is the only formal specification of which we are aware for a
  complete commercial design. We believe that the use of mathematical
  logic for modeling and reasoning about hardware designs such as we
  have demonstrated here can provide assurance of circuit design
  correctness well beyond what is available from current CAD
  techniques.

---------
  See the discussion of the CAP DSP project in
  [operational-semantics-2__other-examples].")
 (BIB::BHMY89
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "W.R. Bevier, W.A. Hunt, Jr., J S. Moore, and W.D. Young, [3mSpecial
  Issue on System Verification[0m, [3mJournal of Automated Reasoning[0m, [31;1m5[0m(4),
  pp. 409-530, 1989.
  [31;1mRelevance:[0m Computational Logic Inc. (CLI) Verified Stack --- a
  seminal achievement in formal methods and operational semantics

---------
  The Computational Logic, Inc (CLI) Verified Stack was reported in
  this Special Issue of the JAR.

  The CLI stack was composed of four verified components: a gate-level
  design for a microprocessor (by Warren Hunt), an
  assembler/linker/loader that provided an execute-only, stack-based
  instruction set with subroutine call and return (Moore), a compiler
  for a small subset of a programming language related to Pascal
  (Bill Young, see [bib::young88]), and a simple operating system
  kernel (Bill Bevier; see [bib::bevier87]).  All components were
  verified with Nqthm, so that a high-level program could be
  compiled, assembled, linked, loaded, and run on the gate-level
  machine with mathematical certainty that it behaved as specified by
  the semantics of the high-level programming language.  All the
  models just mentioned involved [operational-semantics] and proofs
  in the style described in here.  Indeed, this project basically
  convinced the community that this style of semantics was practical
  for both execution and verification of models.

  The verification of the relations between each component --- gates to
  machine code, machine code to assembly language, assembly language
  to high level language, operating system to assembly language ---
  must be considered a ``first'' for relating practical machines of
  each kind.  To the best of our knowledge, no one had ever verified
  a gate-level implementation of an ISA for a practical
  microprocessor before Hunt's 1985 work [bib::hunt85].  With the
  same caveat, no one had ever verified an assembler/linker/loader
  before Moore's 1988 Piton work (see [bib::moore96] for a history)
  or verified an operating system kernel for a practical machine
  before Bevier's 1987 work.  And while McCarthy and Painter verified
  (by a traditional ``hand proof'') an expression compiler, which
  various formal methods researchers tackled in the 1970s (including
  Boyer and Moore in 1979 [bib::bm79], where a history of the
  challenge is sketched), both the high- and low- level machines
  involved in that earlier ``compiler'' work were trivial compared to
  what Young dealt with in 1988.  The messy reality of each component
  was fundamentally due to the requirement that each layer, starting
  at the gates, provide sufficient functionality to implement the
  higher layers.

  In 1989, the ``hardware'' at the bottom of the CLI stack was a
  gate-level description of a machine called FM8502.  The FM8502 was
  a 32-bit version of Hunt's earlier 16-bit FM8501; see
  [bib::hunt85].  Hunt designed and verified FM8502 to make Moore's
  job of writing an assembler a little easier.  Moore, with Matt
  Kaufmann's help with some proofs, verified that the FM8502 code
  produced by the assembler/linker/loader implemented the semantics
  of the Piton assembly language.  But the FM8502 could not be
  fabricated because its gate-level description was not compatible
  with commercial fabrication tools, e.g., there was unrealistic
  fan-out.  But the 1989 CLI Verified Stack demonstrated that it was
  practical to prove that a gate-level design implemented a given
  instruction set architecture (ISA) and that the operational
  semantic approach allowed the mechanized proofs of formal relations
  between different abstraction hierarchies.

  In 1991, Hunt and Bishop Brock designed a formal hardware description
  language (HDL) and used it to describe the FM9001 microprocessor
  which they then verified to implement its ISA; see [bib::hb92].
  The FM9001 was fabricated.  In 1991, Moore retargeted the
  code-generators in the 1989 assembler/linker/loader and re-verified
  that part of the stack, making it possible to port the rest of the
  verified stack to a fabricated, running machine; see
  [bib::moore96].

  In 1992, two other interesting projects related to Piton and FM9001
  were completed.  Art Flatau completed the implementation and Nqthm
  verification of a second compiler, one that compiled a small subset
  of the Nqthm functional programming language into Piton (see
  [bib::flatau92]).

  At about the same time, Matt Wilding completed the implementation and
  verification of several real-time control programs in Piton and
  verified their functional correctness and resource bounds
  (instruction counts and stack sizes).  See [bib::wilding92] and
  [bib::wilding93].  One of the programs carried out a winning
  strategy for the game of Nim (if one exists from the given Nim
  starting state).

  Wilding wrote ([bib::wilding93], page 278) ``An FM9001 was fabricated
  and runs a compiled version of the Nim program. The fabricated
  FM9001 microprocessor, the Piton compiler, and the Nim program were
  never tested in a conventional manner during development or after
  completion. Even so, each worked the first time and we would have
  been surprised if any had not.''")
 (BIB::BKM96
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "B. Brock, M. Kaufmann, and J S. Moore, ``{ACL2 Theorems about
  Commercial Microprocessors |
  http://www.cs.utexas.edu/users/moore/publications/bkm96.pdf}'', in
  M. Srivas and A. Camilleri, editors, [3mFormal Methods in
  Computer-Aided Design (FMCAD'96)[0m, Springer-Verlag, LNCS [31;1m1166[0m, pp.
  275-293, doi 10.1007/BFb0031816, 1996.
  [31;1mRelevance:[0m early (mid-1990s) applications of ACL2 in industry
  (Motorola CAP DSP via operational semantics and the AMD K5 FDIV via
  a shallow embedding)

---------
  Abstract

  ACL2 is a mechanized mathematical logic intended for use in
  specifying and proving properties of computing machines.  In two
  independent projects, industrial engineers have collaborated with
  researchers at Computational Logic, Inc. (CLI), to use ACL2 to
  model and prove properties of state-of-the-art commercial
  microprocessors prior to fabrication.  In the first project,
  Motorola Inc., and CLI collaborated to specify Motorola's complex
  arithmetic processor (CAP), a single-chip, digital signal processor
  (DSP) optimized for communications signal processing.  Using the
  specifications, we proved the correctness of several CAP microcode
  programs.  The second industrial collaboration involving ACL2 was
  between Advanced Micro Devices, Inc. (AMD) and CLI.  In this work
  we proved the correctness of the kernel of the floating-point
  division operation on AMD's first Pentium-class microprocessor, the
  AMD5K86.  In this paper, we discuss ACL2 and these industrial
  applications, with particular attention to the microcode
  verification work.

---------
  This paper contains a good sketch of the Motorola CAP digital signal
  processor project, from capturing the design as an ACL2 operational
  model to proving microcode correct with respect to the model.  The
  paper also includes a timeline describing how long different phases
  of the project took.

  The paper also discusses the first use of ACL2, in 1995, to deal with
  floating-point arithmetic: verifying microcode for floating-point
  division on AMD's first Pentium-class microprocessor, the AMD5k86.
  However, the formalization of the division microcode was not via
  operational semantics but rather a ``shallow embedding'' of the
  microcode into ACL2.  So while both the CAP project and
  floating-point project are of great relevance to the use of formal
  methods in industry, we have stressed the CAP work in this doc
  topic on operational semantics.  For a technical description of the
  division proof, see J S. Moore, T. Lynch, and M. Kaufmann, ``{A
  Mechanically Checked Proof of the Correctness of the Kernel of the
  AMD5k86 Floating-Point Division Program |
  https://www.cs.utexas.edu/~moore/publications/divide_paper.pdf}'',
  [3mIEEE Transactions on Computers[0m, [31;1m47[0m(9), pp. 913-926, Sep., 1998.")
 (BIB::BM05
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "B. Brock and J S. Moore, ``{A Mechanically Checked Proof of a
  Comparator Sort Algorithm |
  https://www.cs.utexas.edu/~moore/publications/csort/main.pdf}'', in
  M. Broy, J. Gruenbauer, D. Harel, and C. A. R. Hoare, editors,
  [3mEngineering Theories of Software Intensive Systems[0m, Springer NATO
  Science Series II, [31;1m195[0m, pp. 141-175, 2005.
  [31;1mRelevance:[0m an example of proving that the state transformation
  effected by running a CAP model on commercial microcode implements
  the high level specification

---------
  Abstract

  We describe a mechanically checked correctness proof for the
  comparator sort algorithm underlying a microcode program in a
  commercially designed digital signal processing chip.  The abstract
  algorithm uses an unlimited number of systolic comparator modules
  to sort a stream of data.  In addition to proving that the
  algorithm produces an ordered permutation of its input, we prove
  two theorems that are important to verifying the microcode
  implementation.  These theorems describe how positive and negative
  ``infinities'' can be streamed into the array of comparators to
  achieve certain effects.  Interesting generalizations are necessary
  in order to prove these theorems inductively.  The mechanical
  proofs were carried out with the ACL2 theorem prover.  We find
  these proofs both mathematically interesting and illustrative of
  the kind of mathematics that must be done to verify software.

---------
  For the 1997 ACL2 proof script see [47mbooks/misc/csort.lisp[0m.  The long
  delay between when the work was done (1997) and when it was
  published (2005) is due both to the understandable sensitivity of
  companies to permit publication of anything that might reveal
  proprietary intellectual property, combined with the rarity of
  suitable venues to describe exceedingly practical formal methods
  applications.  (Despite this phenomenon, working closely with
  industry is the only way to build tools that meet their needs.)

  See the discussion of the CAP DSP project in
  [operational-semantics-2__other-examples].")
 (BIB::BM73
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. S. Boyer and J S. Moore, ``{Proving Theorems about LISP Functions
  | https://www.cs.utexas.edu/~moore/publications/bm-ijcai-73.pdf}'',
  in [3mProceedings of the Third International Joint Conference on
  Artificial Intelligence (IJCAI)[0m, Stanford University, pp. 486-493,
  1973.
  [31;1mRelevance:[0m journal article about the Edinburgh Pure Lisp Theorem
  Prover (PLTP)

---------
  For a longer, journal version of this paper see R. S. Boyer and J S.
  Moore, ``{Proving Theorems about LISP Functions |
  https://www.cs.utexas.edu/~moore/publications/bm75.pdf}'', [3mJournal
  of the ACM[0m, [31;1m22[0m(1), pp. 129-144, 1975.

  The IJCAI'73 paper was the first widely accessible description of the
  Edinburgh Pure Lisp Theorem Prover (PLTP).  The key ideas in the
  theorem prover were the use of Lisp as a logic, the reliance on
  recursive function definitions, extensive use of rewriting and
  symbolic evaluation, and an induction heuristic based on the
  failure of symbolic evaluation.  The system was fully automatic;
  there were no provisions for user supplied lemmas or hints.

  The ``proveall'' (regression suite) included such theorems as
  associativity of [47mappend[0m, [47mreverse-reverse[0m, and the correctness of
  insertion sort.  The paper was hailed as a landmark in theorem
  proving because these theorems had never been proved automatically
  before.  But early critics said that proving theorems about pure
  Lisp was irrelevant because serious applications were not written
  in pure Lisp.  However, Boyer and Moore argued that Lisp was a
  logic with features necessary to the specification and proof of
  program properties, namely recursive definitions and mathematical
  induction.

  {The PLTP Archive |
  https://www.cs.utexas.edu/~moore/best-ideas/pltp/index.html}
  contains a wealth of information about PLTP and its 1973
  implementation in POP-2, including the POP-2 Reference Manual,
  scanned OCR listings of the PLTP source code, listings of proof
  output, and modern reconstructions of PLTP in OCaml (by Grant
  Passmore) and ACL2 (by J Moore).")
 (BIB::BM79
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. S. Boyer and J S. Moore, [3m{A Computational Logic |
  https://archive.org/details/acl_20240626}[0m, Academic Press, 1979.
  [31;1mRelevance:[0m implementation details of the prover that became Nqthm

---------
  This book described the ``Boyer-Moore theorem prover'' as it stood in
  1979, when the prover was locally known as ``Thm.'' Unlike the
  Edinburgh Pure Lisp Theorem Prover (PLTP), Thm supported datatypes
  other than pairs, well-founded ordinals, a conservative
  definitional principle, and named previously proved lemmas stored
  as rules.  Unlike the later Nqthm, Thm did not support
  [47mquote[0m-notation and so represented logical constants inefficiently.
  Thm also lacked the linear-arithmetic decision procedure, and
  lacked user-supplied hints.  Of course, there were also many
  heuristic changes along the way from PLTP to Nqthm.

  One outstanding feature of [3mA Computational Logic[0m was noted by Boyer
  and Moore in the Preface to the First Edition of [bib::bm97] ``we
  know of three independent successful efforts to construct the
  theorem prover from the book.'' If you want to a good idea of how
  Nqthm and ACL2 ``work,'' read this book!")
 (BIB::BM80
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. S. Boyer and J S. Moore, ``{On Why It Is Impossible to Prove that
  the BDX930 Dispatcher Implements a Time-Sharing System |
  https://www.cs.utexas.edu/~moore/publications/BDX930-Report-1978-81.pdf}'',
  in Sections 14 and 15 of P.M. Melliar-Smith, K. Levitt, R.
  Schwartz, R. Boyer, J Moore, D. Hare, R. Shostak, M. Moriconi, M.
  Green, and W.D. Elliot, [3mInvestigation, Development, and Evaluation
  of Performance Proving for Fault-Tolerant Computer Final Report,
  covering the period September 1978 to June 1982[0m, SRI, July 1982.
  [31;1mRelevance:[0m operational semantic model of (a fragment) of a 1970s
  flight control computer

---------
  Boyer and Moore's formalization of a subset of the instruction set of
  the Bendix BDX930 flight control computer is reported in this
  document.  The document is part of the Final Report for the
  Software Implemented Fault Tolerance (SIFT) project of SRI,
  sponsored by the National Aeronautics and Space Administration,
  Langley Research Center, Hampton, Va 23665.  Section 14 explains
  why it was impossible to verify that the code for the SIFT
  dispatcher implemented a time-sharing system; Section 15 contains
  the 30 page listing of the operational semantics for the BDX930
  fragment in question, written in the logic of Thm/Nqthm.  The two
  sections do not contain dates.  The whole report covers the period
  1978 through 1982.  Boyer and Moore left SRI in 1981.  The BDX930
  work was probably done in 1979 or 1980 as it was influential in the
  evolution of Thm to Nqthm, as noted in
  [operational-semantics-5__history-etc].")
 (BIB::BM96
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. S. Boyer and J S. Moore, ``{Mechanized Formal Reasoning about
  Programs and Computing Machines |
  https://www.cs.utexas.edu/~moore/publications/bm96.pdf}'', in R.
  Veroff, editor, [3mAutomated Reasoning and Its Applications: Essays in
  Honor of Larry Wos[0m, MIT Press, 1966.
  [31;1mRelevance:[0m the basic Nqthm/ACL2 style of operational semantics as a
  book chapter

---------
  Abstract

  The design of a new processor often requires the invention and use of
  a new machine-level programming language, especially when the
  processor is meant to serve some special purpose.  It is possible
  to specify formally the semantics of such a programming language so
  that one obtains a simulator for the new language from the formal
  semantics.  Furthermore, it is possible to configure some
  mechanical theorem provers so that they can be used directly to
  reason about the behavior of programs in the new language,
  permitting the expeditious formal modeling of the new design as
  well as experimentation with and mechanically checked proofs about
  new programs.  We here study a very simple machine-level language
  to illustrate how such modeling, experimentation, and reasoning may
  be done using the ACL2 automated reasoning system.  Of particular
  importance is how we control the reasoning system so that it can
  deal with the complexity of the machine being modeled.  The
  methodology we describe has been used on industrial problems and
  has been shown to scale to the complexity of state-of-the-art
  processors.

---------
  This paper describes the basic methodology used to model and reason
  about machines with ACL2: states as objects, a step function, a run
  function, clock functions for programs, lemmas to control
  expansion, and the basic methodology for specifying and verifying
  programs.  The vehicle for this explanation here is a machine
  almost identical to M1 and this paper covers essentially the same
  ground as the documentation topic
  [operational-semantics-1__simple-example].  Referring to the work
  described in [operational-semantics-5__history-etc] and early ACL2
  work, the paper says

    The approach we describe is essentially that used in the Nqthm and
    ACL2 projects described above.  Furthermore, the Nqthm and ACL2
    users above were taught this method of formalization via examples
    very similar to this one, primarily in our graduate class,
    [3mRecursion and Induction[0m, at the University of Texas at Austin.
    That this technique scales up to languages that are many orders
    of magnitude more complicated than this one is demonstrated by
    [5, 9].  Therefore, simplicity [3mhere[0m should be looked upon as a
    virtue.

  While the paper does not name the machine being formalized, it was in
  fact called [47msmall-machine[0m rather than [47mm1[0m and it goes all the way
  back to Nqthm.  Indeed, among the students who learned this
  methodology in [3mRecursion and Induction[0m in the early 1980s were
  Bevier, Hunt, Young, Flatau, and Wilding --- all principals in the
  CLI Verified Stack work [bib::bhmy89].  See the 1991 Nqthm script
  [47mexamples/basic/small-machine.events[0m, which demonstrates that most
  of the methodology described here was developed before ACL2.
  Coincidentally, it also shows that what we're calling [47mm1[0m today ---
  informally described as a ``toy'' Java Virtual Machine --- predates
  the Java and the JVM.

  The ACL2 version of the [47msmall-machine[0m proof script may be found in
  the ACL2 book at
  [47mhttps://www.cs.utexas.edu/~moore/publications/small-machine.lisp[0m.

  By the way, notes for [3mRecursion and Induction[0m have been incorporated
  into ACL2's documentation.  See [recursion-and-induction].  But
  when the course was taught by Boyer and Moore in the 1980s the
  notes were essentially just a list of conjectures to prove or
  disprove and the class was rather free-form in the sense that
  student participation was critical and often determined the kinds
  of problems posed in the latter part of the semester.  Operational
  semantics is not mentioned in the recursion-and-induction
  documentation.")
 (BIB::BM97
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. S. Boyer and J S. Moore, [3m{ A Computational Logic Handbook, Second
  Edition |
  https://drive.google.com/file/d/0B2yFYLn0Spf1TloxMjNxdzBWN1E/}[0m,
  Academic Press, New York, 1997.
  [31;1mRelevance:[0m Nqthm user's manual

---------
  This book is the ``final'' user's manual for Nqthm.  It was written
  about 8 years after the ACL2 project was started, by which time
  ACL2 had gained a sizeable user community despite the fact that
  Nqthm was still being used by some students and industrial
  researchers.")
 (BIB::BOH03
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. E. Bryant and D. R. O'Hallaron, [3mComputer Systems: A Programmer's
  Perspective[0m, Prentice-Hall. First edition 2003, second edition
  2011, third edition 2015.
  [31;1mRelevance:[0mone of the most popular and influential textbooks on modern
  computer systems; its relevance here is that the book introduced
  the y86.

---------
  Abstract

  For Computer Systems, Computer Organization and Architecture courses
  in CS, EE, and ECE departments. Few students studying computer
  science or computer engineering will ever have the opportunity to
  build a computer system. On the other hand, most students will be
  required to use and program computers on a near daily basis.
  [3mComputer Systems: A Programmer's Perspective[0m introduces the
  important and enduring concepts that underlie computer systems by
  showing how these ideas affect the correctness, performance, and
  utility of application programs. The text's hands-on approach
  (including a comprehensive set of labs) helps students understand
  the under-the-hood operation of a modern computer system and
  prepares them for future courses in systems topics such as
  compilers, computer architecture, operating systems, and
  networking.

---------
  The y86 introduced in this textbook is can be thought of as a ``toy''
  x86 and is an excellent starting point for the formalization of
  that larger machine.

  The y86 has been modeled in ACL2, by Warren A. Hunt, Jr., and M.
  Kaufmann, and some programs proved correct with it.  In particular,
  the ACL2 book [47m/books/models/y86/y86-basic/y86/y86.lisp[0m is a
  faithful operational semantic model of the 36-bit y86 described in
  the first edition of the Bryant-O'Hallaron book.")
 (BIB::BY96
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "R. S. Boyer and Y. Yu, ``{Automated Proofs of Object Code for a
  Widely Used Microprocessor |
  https://dl.acm.org/doi/10.1145/227595.227603}'', [3mJournal of the ACM[0m
  [31;1m43[0m(1), pp. 166-192, January, 1996.
  [31;1mRelevance:[0m operational model of the Motorola 68020 and verification
  of object code generated by commercial compilers

---------
  Abstract

  We have formally described a substantial subset of the MC68020, a
  widely used microprocessor built by Motorola, within the
  mathematical logic of the automated reasoning system Nqthm, a.k.a.
  the Boyer-Moore Theorem Prover.  Using this formal description, we
  have mechanically checked the correctness of MC68020 object code
  programs for for binary search, Hoare's Quick Sort, twenty-one
  functions from the Berkeley Unix C string library, and other
  well-known algorithms.  The object code for these examples was
  generated using the Gnu C, the Verdix Ada, and the AKCL common Lisp
  compilers.  We have mechanized a mathematical theory to facilitate
  automated reasoning about object code programs.  We describe a
  two-stage methodology we use to do our proofs.

---------
  See also the Nqthm scripts [47mexamples/yu/[0m where you will find the
  definition of the MC68020 model and the proofs of the programs
  mentioned.")
 (BIB::FLATAU92
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "A. D. Flatau [3mA verified implementation of an applicative language
  with dynamic storage allocation[0m
  [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/flatau.pdf)[0m, University of
  Texas at Austin, Ph.D. dissertation, 1992 (minus some appendices).
  [31;1mRelevance:[0m a second verified compiler hosted on the CLI Verified
  Stack

---------
  Abstract

  A compiler for a subset of the Nqthm logic and a mechanically checked
  proof of its correctness is described.  The Nqthm logic defines an
  applicative programming language very similar to McCarthy's pure
  Lisp [20].  The compiler compiles programs in the Nqthm logic into
  the Piton assembly level language [23].  The correctness of the
  compiler is proven by showing that the result of executing the
  Piton code is the same as produced by the Nqthm interpreter [47mV&C$[0m.
  The Nqthm logic defines several different abstract data types, or
  shells, as they are called in Nqthm.  The user can also define
  additional shells.  The definition of a shell includes the
  definition of a constructor function that returns new objects with
  the type of that shell.  These objects can become garbage, so the
  run-time system of the compiler includes a garbage collector.  The
  proof of the correctness of the compiler has not been entirely
  mechanically checked.  A plan for completing the proof is
  described.

---------
  The version of the compiler presented in the dissertation included
  code for creating new shells and a garbage collector.  But these
  features of the compiler were not fully verified at the time the
  dissertation was defended.  An earlier version of the compiler
  dealt only with the Nqthm primitives [47mCAR[0m, [47mCDR[0m, [47mCONS[0m, [47mFALSE[0m, [47mLISTP[0m,
  [47mNLISTP[0m, [47mTRUE[0m, [47mTRUEP[0m, and [47mIF[0m, as well as recursive functions.  The
  run-time of that simpler system included dynamic storage allocation
  (to allocate conses in Piton's array space).  But it did not
  include a garbage collector.  It was that simpler implementation
  that was mechanically verified.  The completion of the proofs of
  the full system was never completed.

  The Nqthm events for this work may be found in the [47m*.events[0m files of
  [47mexamples/flatau/[0m.")
 (BIB::GHK13
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Abstract Stobjs and
  Their Application to ISA Modeling |
  http://eptcs.org/content.cgi?ACL22013}'', in R. Gamboa and J.
  Davis, editors, [3mProceedings of ACL2 Workshop 2013[0m, Electronic
  Proceedings in Theoretical Computer Science, Volume 114, pp. 54-69,
  2013.
  [31;1mRelevance:[0m an ACL2 feature introduced to support operational semantic
  models

---------
  Abstract

  We introduce a new ACL2 feature, the abstract stobj, and show how to
  apply it to modeling the instruction set architecture of a
  microprocessor. Benefits of abstract stobjs over traditional
  (``concrete'') stobjs can include faster execution, support for
  symbolic simulation, more efficient reasoning, and resilience of
  proof developments under modeling optimization.

---------
  Aside from the specific advantages abstract stobjs (see
  [47m[defabsstobj][0m) confer on ACL2 state machines, this papers
  illustrates how attention to operational semantics has influenced
  the development of ACL2.")
 (BIB::GHK17
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "S. Goel, W. A. Hunt, Jr., and M. Kaufmann, ``{Engineering a Formal,
  Executable x86 ISA Simulator for Software Verification |
  https://link.springer.com/chapter/10.1007/978-3-319-48628-4_8}'',
  in M. Hinchey, J. P. Bowen, and E.-R. Olderog, editors, [3mProvably
  Correct Systems[0m Springer, pp. 173-209, 2017.
  [31;1mRelevance:[0m operational model of the x86 at both the user- and
  system-level and code proofs

---------
  Abstract

  Construction of a formal model of a computing system is a necessary
  practice in formal verification. The results of formal analysis can
  only be valued to the same degree as the model itself. Model
  development is error-prone, not only due to the complexity of the
  system being modeled, but also because it involves addressing
  disparate requirements. For example, a formal model should be
  defined using simple constructs to enable efficient reasoning but
  it should also be optimized to offer fast concrete simulations.
  Models of large computing systems are themselves large software
  systems and must be subject to rigorous validation. We describe our
  formal, executable model of the x86 instruction-set architecture;
  we use our model to reason about x86 machine-code programs.
  Validation of our x86 ISA model is done by co-simulating it
  regularly against a physical x86 machine. We present design
  decisions made during model development to optimize both validation
  and verification, i.e., efficiency of both simulation and
  reasoning. Our engineering process provides insight into the
  development of a software verification and model animation
  framework from the points of view of accuracy, efficiency,
  scalability, maintainability, and usability.

---------
  See the collection of ACL2 books and files at [47mbooks/projects/x86isa/[0m.

  Also relevant are [bib::goel16] and the following earlier papers
  [bib::hk12], [bib::ghk13],and [bib::ghkg14].")
 (BIB::GHKG14
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "S. Goel, W. A. Hunt, Jr., M. Kaufmann, and S. Ghosh, ``{Simulation
  and Formal Verification of x86 Machine-Code Programs that Make
  System Calls |
  http://www.cs.utexas.edu/users/hunt/FMCAD/FMCAD14/proceedings/18_goel.pdf}'',
  in [3mProceedings of Formal Methods in Computer-Aided Design
  (FMCAD'14)[0m, pp. 91-98, 2014.
  [31;1mRelevance:[0m modeling and verifying machine-code programs that exhibit
  non-determinism

---------
  Abstract

  We present an approach to modeling and verifying machine-code
  programs that exhibit non-determinism. Specifically, we add support
  for system calls to our formal, executable model of the user-level
  x86 instruction-set architecture (ISA). The resulting model,
  implemented in the ACL2 theorem-proving system, allows both formal
  analysis and efficient simulation of x86 machine-code programs; the
  logical mode characterizes an external environment to support
  reasoning about programs that interact with an operating system,
  and the execution mode directly queries the underlying operating
  system to support simulation. The execution mode of our x86 model
  is validated against both its logical mode and the real machine,
  providing test-based assurance that our model faithfully represents
  the semantics of an actual x86 processor. Our framework is the
  first that enables mechanical proofs of functional correctness of
  user-level x86 machine-code programs that make system calls. We
  demonstrate the capabilities of our model with the mechanical
  verification of a machine-code program, produced by the GCC
  compiler, that computes the number of characters, lines, and words
  in an input stream. Such reasoning is facilitated by our libraries
  of ACL2 lemmas that allow automated proofs of a program's
  memory-related properties.")
 (BIB::GOEL16
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "S. Goel, [3m{Formal Verification of Application and System Programs
  Based on a Validated x86 ISA Model |
  https://repositories.lib.utexas.edu/server/api/core/bitstreams/858b2f9b-5532-4b2a-bed1-fb889a265f6c/content}[0m,
  University of Texas at Austin, Ph.D. dissertation, 2016.
  [31;1mRelevance:[0m details of the x86 model

---------
  Goel writes on page viii of the dissertation

  This dissertation demonstrates that formal verification of complex
  program properties can be made practical, without any loss of
  accuracy or expressiveness, by employing a machine-code analysis
  framework implemented using a mechanical theorem prover. To this
  end, we constructed a formal and executable model of the x86
  Instruction-Set Architecture using the ACL2 theorem-proving system.
  This model includes a specification of 400+ x86 opcodes and
  architectural features like segmentation and paging. The model's
  high execution speed allows it to be validated routinely by
  performing co-simulations against a physical x86 processor ---
  thus, formal analysis based on this model is reliable. We also
  developed a general framework for x86 machine-code analysis that
  can lower the overhead associated with the verification of a broad
  range of program properties, including correctness with respect to
  behavior, security, and resource requirements. We illustrate the
  capabilities of our framework by describing the verification of two
  application programs, population count and word count, and one
  system program, zero copy.

---------
  Because of the concern for validating the ACL2 x86 model against x86
  hardware by various manufacturers it was important the ACL2 x86
  execute efficiently.  When running in the application-level mode
  the ACL2 model executes at about 3.3 million x86 instructions per
  second (ips); in the system-level mode it executes at about 912,000
  ips.

  See the collection ACL2 books and files at [47mbooks/projects/x86isa/[0m.")
 (BIB::HB92
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "W. A. Hunt, Jr. and B. Brock, ``{A Formal HDL and its use in the
  FM9001 Verification |
  https://royalsocietypublishing.org/doi/abs/10.1098/rsta.1992.0024}'',
  [3mProceedings of the Royal Society[0m, North Holland, April, 1992.
  [31;1mRelevance:[0m a formalized hardware description language and the
  verification of a fabricated microprocessor described with it; this
  describes three foundational achievements in formal methods

---------
  Abstract

  A synchronous, hierarchical, occurrence-oriented, hardware
  description language (HDL) has been formalized with the Boyer-Moore
  logic. Well-formed HDL circuits are recognized by a predicate, and
  a unit-clock simulator defines the meaning of circuits expressed in
  the HDL. This HDL has been used to specify an implementation of the
  FM9001 microprocessor that has been mechanically proved to
  implement the FM9001 instruction-level specification. All proofs
  were mechanically checked using the Boyer-Moore theorem-proving
  system. The formalization of the HDL, the FM9001 user-level
  specification, and the FM9001 HDL implementation architecture
  specification required more than 700 function definitions. The
  mechanical proof is composed of thousands of theorem prover proof
  requests and millions of theorem prover inference steps.

---------
  The verified fabricated microprocessor described here was used in the
  final hosting of the CLI Verified Stack [bib::bhmy89].

  But aside from its importance to the Verified Stack, this paper
  describes three foundational achievements in formal methods:

    * the first formal definition of a hardware description language (HDL),

    * the first complete proof of a microprocessor design -- including its
      embedded test logic -- with respect to its high-level ISA
      specification, and

    * the first (and still, only) verified microprocessor that was
      manufactured and demonstrated to function properly.

  For complete details, see the Nqthm script
  [47mexamples/fm9001-piton/fm9001/fm9001-replay.events[0m.")
 (BIB::HK12
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "W. A. Hunt, Jr. and M. Kaufmann, ``{Towards a Formal Model of the x86
  ISA |
  http://apps.cs.utexas.edu/tech_reports/reports/tr/TR-2075.pdf}'',
  University of Texas at Austin, Computer Science Department
  Technical Report TR-12-07, May, 2012.
  [31;1mRelevance:[0m a ``toy model'' of the x86, built as a warm up exercise

---------
  Abstract

  We present a preliminary formalization of a subset of the x86
  instruction set. Our model is written in the logic of the ACL2
  theorem prover. It can be executed as a Lisp program on concrete
  data, which provides the capability to validate the model against
  results delivered by actual x86 processors. We demonstrate how bugs
  in our model can also be eliminated by using the ACL2 prover to
  verify guards (semantic preconditions) for our functions.

---------
  This work preceded the development of the full x86 model described in
  [bib::ghk13], [bib::ghkg14], [bib::goel16], and [bib::ghk17].")
 (BIB::HKMS17
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "W. A. Hunt, Jr., M. Kaufmann, J S. Moore, and A. Slobodova,
  ``{Industrial hardware and software verification with ACL2 |
  https://royalsocietypublishing.org/doi/10.1098/rsta.2015.0399}'' in
  P. Gardner, P. O'Hearn, M. Gordon, G. Morrisett and F. B.
  Schneider, editors), [3mVerified Trustworthy Software Systems[0m,
  Philosophical Transactions A, Royal Society Publishing, [31;1m374[0m, DOI
  10.1098/rsta.2015.0399, September, 2017.
  [31;1mRelevance:[0m how ACL2 is used in industry, and why

---------
  Abstract

  The ACL2 theorem prover has seen sustained industrial use since the
  mid-1990s. Companies that have used ACL2 regularly include AMD,
  Centaur Technology, IBM, Intel, Kestrel Institute,
  Motorola/Freescale, Oracle and Rockwell Collins. This paper
  introduces ACL2 and focuses on how and why ACL2 is used in
  industry. ACL2 is well-suited to its industrial application to
  numerous software and hardware systems, because it is an integrated
  programming/proof environment supporting a subset of the ANSI
  standard Common Lisp programming language. As a programming
  language ACL2 permits the coding of efficient and robust programs;
  as a prover ACL2 can be fully automatic but provides many features
  permitting domain-specific human-supplied guidance at various
  levels of abstraction. ACL2 specifications and models often serve
  as efficient execution engines for the modelled artefacts while
  permitting formal analysis and proof of properties. Crucially, ACL2
  also provides support for the development and verification of other
  formal analysis tools. However, ACL2 did not find its way into
  industrial use merely because of its technical features. The core
  ACL2 user/development community has a shared vision of making
  mechanized verification routine when appropriate and has been
  committed to this vision for the quarter century since the
  Computational Logic, Inc., Verified Stack. The community has
  focused on demonstrating the viability of the tool by taking on
  industrial projects (often at the expense of not being able to
  publish much).

---------
  This is does not discuss operational semantics [3mper se[0m but instead
  focuses on how ACL2 is used in industry and how ACL2 gained
  traction in industrial use.  The paper discusses how ACL2 is used
  at Centaur Technology, Inc.  When a previously verified module of a
  microprocessor design is modified by the designers and checked back
  in to the data base, ACL2 is run that night to attempt to verify
  the modified design, ``bugs introduced today are detected tonight
  and fixed tomorrow.'' The Centaur design and verification teams
  were acquired by Intel in 2021 and ACL2 continues to be so used at
  Intel.  In addition the paper describes features of ACL2 (and of
  the ACL2 community of users) that are particularly important to
  industry.")
 (BIB::HUNT85
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "W. A. Hunt, Jr., [3mFM8501: A Verified Microprocessor[0m, University of
  Texas at Austin, Ph.D. dissertation, 1985 (also published as a book
  of the same title, Springer-Verlag LNAI 795, Heidelberg, 1994.
  [31;1mRelevance:[0m first microprocessor verified at the gate level and the
  bottommost component of the CLI stack

---------
  The precursor to the verified microprocessor used in the CLI Verified
  Stack as reported in [bib::bhmy89] is described here.  See the
  Nqthm script [47mexamples/hunt/fm8501.events[0m).

  FM8501, which had 8 registers and a 16-bit wordsize, was verified to
  implement a conventional orthogonal instruction set.  The semantics
  of the gate-level design of the FM8501 and of the instruction set
  were described operationally.  The CLI Stack was ultimately based
  on the FM8502, which was like the FM8501 except (a) the wordsize
  was 32-bits and (b) extra bits were allocated in the instruction
  word to permit programmer control over ALU condition code flags.
  These changes were requested by Moore during his design of an
  assembler for the machine.  For more detail on the evolutionary
  pressure that the assembler put on the underlying machine see
  Section 1.5 of [bib::moore96].  Since the gate-level design of the
  FM8501 was parameterized by the word length (including the ALU),
  the description and verification of the 32-bit FM8502 was easier
  for Hunt than one might otherwise expect.  The FM8502 is described
  in more detail in Hunt's article in [bib::bhmy89].  Because of the
  way the gate-level designs of FM8501 and FM8502 were expressed, it
  was impractical to fabricate either machine.  However, see
  [bib::hb92].")
 (BIB::KMM00A
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning: An
  Approach |
  https://www.cs.utexas.edu/~moore/publications/acl2-books/car/index.html}[0m,
  Kluwer Academic Publishers, 2000.
  [31;1mRelevance:[0m introduction to ACL2

---------
  This book explains how to program in the ACL2 functional programming
  language, how that language is formalized as a logic, and how to
  use the theorem prover.  While the language and logic have acquired
  additional features in subsequent years, most new features are
  orthogonal to the system described here.  Thus, the system here
  describes a subset of the functionality of the current version of
  ACL2.  Probably the single most ``incompatible'' addition was the
  change of representation of the ordinals.  But the Errata published
  online in the link above explains how to restore the default
  representation assumed in the book.  Thus, this is an excellent
  beginner's introduction to how to use the system.  In contains many
  exercises and the solutions are available online.")
 (BIB::KMM00B
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "M. Kaufmann, P. Manolios, J S. Moore, [3m{Computer-Aided Reasoning: ACL2
  Case Studies |
  https://www.cs.utexas.edu/~moore/publications/acl2-books/acs/index.html}[0m,
  Kluwer Academic Publishers, 2000.
  [31;1mRelevance:[0m tutorial examples of ACL2 applications

---------
  This book is a companion to [bib::kmm00a].  It contains fourteen
  articles by ACL2 experts, explaining how they formalized and solved
  fourteen different problems.  It also includes exercises.")
 (BIB::LIU06
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "H. Liu, [3m{Formal Specification and Verification of a JVM and its
  Bytecode Verifier |
  https://www.cs.utexas.edu/~moore/publications/liu-dissertation.pdf}[0m,
  University of Texas at Austin, Ph.D. dissertation, 2006
  [31;1mRelevance:[0m most complete ACL2 model of the JVM

---------
  The source files for this effort have been updated in October, 2024
  (because of changes to ACL2 since 2006) and now reside in the
  [community-books], in directory [47mbooks/models/jvm/m6/[0m.

  This dissertation, available at the link above, describes the ``M6''
  model of the JVM and some important proofs about it.  It was the
  most complete model constructed in ACL2.  It executed most J2ME
  Java programs (except those with significant I/O or
  floating-point).  It supported

    * all data types (except floats),

    * multi-threading,

    * dynamic class loading,

    * class initialization, and

    * synchronization via monitors.

  The M6 state includes an ``external class table'' where classes
  reside until they are loaded.  The entire Sun CLDC API library (672
  methods in 87 classes) are translated into the external
  representation and are available for loading, constituting about
  500 pages of data.  The model includes 21 out of 41 native APIs
  that appeared in Sun's CLDC API library.  The M6 description itself
  is about 160 pages of ACL2.

  It was created with support from Sun Microsystems.

  On page 322, Liu describes the size of the proof effort: ``We have
  defined 2104 ACL2 functions. We proved over 4764 theorems. 196 of
  them are ``skip-proofed''. To prove the rest of them, 971
  inductions are necessary. The total line count of the ACL2 input is
  136000. They are organized in 282 files. The dependency graph
  between the 282 ACL2 books has 2012 edges.''

  [3mNote from J Moore, dissertation supervisor: The [47m[skip-proofs][0m[3m tag on
  a ``theorem'' means the conjecture is assumed rather than proved.
  So having even one [47mskip-proofs[0m[3m makes it impossible to fully trust
  the results.  However, the skipped conjectures in this work are
  relatively low-level results very similar to other theorems already
  proved.  Liu and I agreed that these conjectures were very probably
  provable and we were more interested in the higher-level
  conclusions drawn from those assumptions.[0m

  An informal summary of the dissertation, by Liu, states

  Will a bytecode-verified Java program run safely? Why? What do we
  mean by ``safely''?

  This dissertation sets out to address these questions by first
  building a precise model of the JVM and its bytecode verifier.

  The models are written in ACL2, for which we have computer-aided
  mechanical reasoning support.

  We studied how static type checking during bytecode verification can
  provide runtime type safety. We did this by examining the JVM type
  hierarchy and proving that safety conditions on operations enforced
  by the bytecode verifier can guarantee runtime type safety of the
  program.

  We also studied how the JVM type hierarchy is extended in a safe way
  by the JVM class loader that introduces new types into the
  environment.  We proved a set of theorems stating that the class
  loading process preserves the consistency of the JVM type
  hierarchy.

  We studied a third aspect of the JVM safety. We focused on the safety
  across method invocation and return.  We studied why the bytecode
  verifier can examine each method individually and provide a safety
  guarantee about the runtime execution of a program.  We note that
  the execution of a program is characterized by a stack of partially
  executed methods and a current executing method.

  We used the full JVM model in ACL2 to study the first two aspects of
  JVM safety.  We proved a set of theorems that stated the
  effectiveness of the bytecode verification about individual
  operations and safety of the JVM class loading.

  We used a simplified JVM model, which we call the small machine, to
  study the third aspect of the JVM safety.  The small machine has
  only one data type. It has branching instructions and method
  invocation and return instructions.  We proved that any small
  program verified by the corresponding simplified JVM bytecode
  verifier can execute safely without overflowing or underflowing the
  operand stacks.")
 (BIB::MANOLIOS00
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "P. Manolios, ``{Correctness of Pipelined Machines |
  https://dl.acm.org/doi/10.5555/646186.683220}'', in W. A. Hunt, Jr
  and S. D. Johnson, editors, [3mFormal Methods in Computer-Aided Design
  (FMCAD 2000)[0m, Springer-Verlag LNCS [31;1m1954[0m, Heidelberg, pp. 161-178,
  2000.
  [31;1mRelevance:[0m an alternative approach to verifying operational models of
  a pipelined machine

---------
  Abstract

  The correctness of pipelined machines is a subject that has been
  studied extensively. Most of the recent work has used variants of
  the Burch and Dill notion of correctness. As new features are
  modeled, e.g., interrupts, new notions of correctness are
  developed. Given the plethora of correctness conditions, the
  question arises: what is a reasonable notion of correctness? We
  discuss the issue at length and show, by mechanical proof, that
  variants of the Burch and Dill notion of correctness are flawed. We
  propose a notion of correctness based on WEBs (Well-founded
  Equivalence Bisimulations). Briefly, our notion of correctness
  implies that the ISA (Instruction Set Architecture) and MA
  (Micro-Architecture) machines have the same observable infinite
  paths, up to stuttering. This implies that the two machines satisfy
  the same CTL*X properties and the same safety and liveness
  properties (up to stuttering). To test the utility of the idea, we
  use ACL2 to verify several variants of the simple pipelined machine
  described by Sawada. Our variants extend the basic machine by
  adding exceptions (to deal with overflows), interrupts, and
  fleshed-out 128-bit ALUs (one of which is described in a netlist
  language). In all cases, we prove the same final theorem. We
  develop a methodology with mechanical support that we used to
  verify Sawada's machine. The resulting proof is substantially
  shorter than the original and does not require any intermediate
  abstractions; in fact, given the definitions and some
  general-purpose books (collections of theorems), the proof is
  automatic. A practical and noteworthy feature of WEBs is their
  compositionality. This allows us to prove the correctness of the
  more elaborate machines in manageable stages.")
 (BIB::MCCARTHY62
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J. McCarthy, ``{Towards a mathematical science of computation |
  http://jmc.stanford.edu/articles/towards/towards.pdf},''
  [3mProceedings of the Information Processing Cong. 62[0m, North-Holland,
  Munich, West Germany, pp. 21-28, August, 1962.
  [31;1mRelevance:[0m a seminal paper in the history of formal operational
  semantics

---------
  The pdf linked above is dated 1996, but the original paper was
  written in 1962.  In a brief preface (found on the [47m.html[0m file at
  the same site as the link above) to the 1996 paper McCarthy wrote:

  ``[3mTowards a Mathematical Science of Computation was given at the
  congress IFIP-62 and published in the proceedings of that
  conference. It extends the results of A Basis for a Mathematical
  Theory of Computation which was first given in 1961.[0m''

  In the 1962 paper (page 19) he wrote

  ``The semantic description of the language must tell what the
  programs mean. The meaning of a program is its effect on the state
  vector in the case of a machine independent language, and its
  effect on the contents of memory in the case of a machine language
  program.''

  He goes on to sketch the approach to operational semantics used most
  often in ACL2 and its predecessors.  See page 22.")
 (BIB::MMRV06
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J. Matthews, J S. Moore, S. Ray and D. Vroon, ``{ Verification
  Condition Generation via Theorem Proving |
  http://ece.ufl.edu/wp-content/uploads/sites/119/publications/lpar06.pdf}'',
  in [3mProceedings of 13th International Conference on Logic for
  Programming, Artificial Intelligence, and Reasoning (LPAR 2006)[0m,
  LNCS [31;1m4246[0m, pp. 362-376, 2006.
  [31;1mRelevance:[0m how to conduct inductive assertion-style proofs from an
  operational semantics without a verification condition generator

---------
  Abstract

  We present a deductive method to convert (i) a formal operational
  semantics for a given machine language, and (ii) an off-the-shelf
  theorem prover, into a high assurance verification condition
  generator (VCG). Our method automatically generates verification
  conditions from assertions at join points of basic blocks of a
  program, analogous to those produced by a custom-built VCG. We show
  how to achieve this with a theorem prover by symbolic simulation on
  the operational semantics. Thus no separate VCG needs to be
  implemented for the target language. Furthermore, we can employ the
  full power of the theorem prover to generate and discharge the
  verification conditions.  Our method can handle both partial and
  total correctness, and recursive procedures. It is also
  compositional, in that the correctness of a subroutine needs only
  be proved once, rather than at each call site. The method has been
  used to verify several machine-level programs in the ACL2 theorem
  prover, including the functional correctness of JVM bytecodes for a
  CBC-mode encryption algorithm.")
 (BIB::MOORE03A
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{Proving Theorems about Java and the JVM with ACL2 |
  https://www.cs.utexas.edu/~moore/publications/marktoberdorf-02/main_final.pdf}'',
  in M. Broy and M. Pizka, editors, [3mModels, Algebras and Logic of
  Engineering Software[0m, IOS Press, Amsterdam, pp. 227-290, 2003.
  [31;1mRelevance:[0m M5: a JVM model with method invocation, classes, and
  threads, with some example proofs including about mutual-exclusion

---------
  This paper was the basis for a series of talks at the 2002
  Marktoberdorf Summer School, Germany.  Among other topics, it
  describes the M5 JVM model (ACL2 script
  [47mbooks/models/jvm/m5/m5.lisp[0m) and the use of the model to formalize
  and prove properties of a variety of JVM programs, including the
  so-called ``Apprentice Challenge'' [bib::mp02].  You can find the
  ACL2 scripts for these proofs on the [47mbooks/models/jvm/m5/[0m.  See the
  [47mREADME[0m on that directory.  The M5 work here is both a fairly
  complicated operational model and a good demonstration of the
  ``clock''-based proof methodology.")
 (BIB::MOORE03B
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{ Inductive Assertions and Operational Semantics |
  https://www.cs.utexas.edu/~moore/publications/trecia/long.pdf}'',
  in D. Geist, editor, CHARME 2003,, Springer Verlag, LNCS [31;1m2860[0m, pp.
  289-303, 2003.
  [31;1mRelevance:[0mThe URL above points to a longer version of the paper
  presented at CHARME.  Using a subset of M5 the paper shows how
  partial symbolic evaluation of a program can be used to generate
  and prove verification conditions produced from inductive
  assertions

---------
  Abstract

  This paper shows how classic inductive assertions can be used in
  conjunction with an operational semantics to prove partial
  correctness properties of programs. The method imposes only the
  proof obligations that would be produced by a verification
  condition generator but does not require the definition of a
  verification condition generator. The paper focuses on iterative
  programs but recursive programs are briefly discussed. Assertions
  are attached to the program by defining a predicate on states. This
  predicate is then ``completed'' to an alleged invariant by the
  definition of a partial function defined in terms of the state
  transition function of the operational semantics. If this alleged
  invariant can be proved to be an invariant under the state
  transition function, it follows that the assertions are true every
  time they are encountered in execution and thus that the
  post-condition is true if reached from a state satisfying the
  pre-condition. But because of the manner in which the alleged
  invariant is defined, the verification conditions are sufficient to
  prove invariance. Indeed, the ``natural'' proof generates the
  classical verification conditions as subgoals. The invariant
  function may be thought of as a state-based verification condition
  generator for the annotated program. The method allows standard
  inductive assertion style proofs to be constructed directly in an
  operational semantics setting. The technique is demonstrated by
  proving the partial correctness of simple bytecode programs with
  respect to a pre-existing operational model of the Java Virtual
  Machine.

---------
  See also the paper [bib::rm04].")
 (BIB::MOORE14
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{ Proof Pearl: Proving a Simple Von Neumann Machine
  Turing Complete |
  https://www.cs.utexas.edu/~moore/publications/m1-is-turing-equiv.pdf}''
  in G. Klein and R. Gamboa, editors, [3mInteractive Theorem Proving,
  ITP 2014[0m, Springer LNCS [31;1m8558[0m, doi.org/10.1007/978-3-319-08970-6_26,
  2014.
  [31;1mRelevance:[0mM1 can compute anything a Turing machine can.  (The paper
  ought to be re-titled ``Proving M1 Turing Equivalent.'')

---------
  The ``Simple Von Neumann machine'' in question is M1.  See the ACL2
  directory [47mbooks/models/jvm/m1/[0m and the [47mREADME[0m file there.

  Abstract

  In this paper we sketch an ACL2-checked proof that a simple but
  unbounded Von Neumann machine model is Turing Complete, i.e., can
  do anything a Turing machine can do. The project formally revisits
  the roots of computer science. It requires re-familiarizing oneself
  with the definitive model of computation from the 1930s, dealing
  with a simple ``modern'' machine model, thinking carefully about
  the formal statement of an important theorem and the specification
  of both total and partial programs, writing a verifying compiler,
  including implementing an X86-like call/return protocol and
  implementing computed jumps, codifying a code proof strategy, and a
  little ``creative'' reasoning about the non-termination of two
  machines.

---------
  See the ACL2 book [47mbooks/models/jvm/m1/theorems-a-and-b.lisp[0m.")
 (BIB::MOORE15
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{ Stateman: Using Metafunctions to Manage Large Terms
  Representing Machine States |
  https://www.cs.utexas.edu/~moore/publications/stateman.pdf},'' in
  M. Kaufmann and D. Rager, editors, [3mProceedings of the 13th
  International Workshop on the ACL2 Theorem Prover[0m, EPTCS, [31;1m192[0m, pp.
  93-109, 2015.
  [31;1mRelevance:[0m some ACL2 tools for managing the terms representing states
  of operational models

---------
  Abstract

  When ACL2 is used to model the operational semantics of computing
  machines, machine states are typically represented by terms
  recording the contents of the state components. When models are
  realistic and are stepped through thousands of machine cycles,
  these terms can grow quite large and the cost of simplifying them
  on each step grows. In this paper we describe an ACL2 book that
  uses HIDE and metafunctions to facilitate the management of large
  terms representing such states. Because the metafunctions for each
  state component updater are solely responsible for creating state
  expressions (i.e., ``writing'') and the metafunctions for each
  state component accessor are solely responsible for extracting
  values (i.e., ``reading'') from such state expressions, they can
  maintain their own normal form, use HIDE to prevent other parts of
  ACL2 from inspecting them, and use honsing to uniquely represent
  state expressions. The last feature makes it possible to memoize
  the metafunctions, which can improve proof performance in some
  machine models. This paper describes a general-purpose ACL2 book
  modeling a byte-addressed memory supporting ``mixed'' reads and
  writes. By ``mixed'' we mean that reads need not correspond (in
  address or number of bytes) with writes. Verified metafunctions
  simplify such ``read-over-write'' expressions while hiding the
  potentially large state expression. A key utility is a function
  that determines an upper bound on the value of a symbolic
  arithmetic expression, which plays a role in resolving writes to
  addresses given by symbolic expressions. We also report on a
  preliminary experiment with the book, which involves the production
  of states containing several million function calls.

---------
  The utility described here is available in the ACL2 book
  [47mbooks/projects/stateman/stateman22.lisp[0m.  See also the other files
  on that directory.  See [bib::moore17] for a description of the
  ``key utility,'' defined in the [47mstateman22.lisp[0m file, that computes
  the bounds of an address.")
 (BIB::MOORE17
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{ Computing Verified Machine Address Bounds during
  Symbolic Exploration of Code |
  https://www.cs.utexas.edu/~moore/publications/ainni.pdf},'' in J.
  Bowen, H. Langmaack and E.-R. Olderog, editors, [3mProvably Correct
  Systems[0m, Springer, pp. 151-172, 2017.
  [31;1mRelevance:[0m an ACL2 tool for determining whether two symbolic machine
  addresses may be equal

---------
  Abstract

  When operational semantics is used as the basis for mechanized
  verification of machine code programs it is often necessary for the
  theorem prover to determine whether one expression denoting a
  machine address is unequal to another. For example, this problem
  arises when trying to determine whether a read at the address given
  by expression [3ma[0m is affected by an earlier write at the address
  given by [3mb[0m. If it can be determined that [3ma[0m and [3mb[0m are definitely
  unequal, the write does not affect the read. Such address
  expressions are typically composed of ``machine arithmetic function
  symbols'' such as [47m+[0m, [47m*[0m, [47mmod[0m, [47mash[0m, [47mlogand[0m, [47mlogxor[0m, etc., as well as
  numeric constants and values read from other addresses. In this
  paper we present an abstract interpreter for machine address
  expressions that attempts to produce a bounded natural number
  interval guaranteed to contain the value of the expression. The
  interpreter has been proved correct by the ACL2 theorem prover and
  is one of several key technologies used to do fast symbolic
  execution of machine code programs with respect to a formal
  operational semantics. We discuss the interpreter, what has been
  proved about it by ACL2, and how it is used in symbolic reasoning
  about machine code.

---------
  The utility described here is available in the ACL2 book
  [47mbooks/projects/stateman/stateman22.lisp[0m.")
 (BIB::MOORE19
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{Milestones from The Pure Lisp Theorem Prover to ACL2 |
  https://doi.org/10.1007/s00165-019-00490-3}'', [3mFormal Aspects of
  Computing[0m, Springer, DOI
  https://doi.org/10.1007/s00165-019-00490-3, 2019.
  [31;1mRelevance:[0m how the Edinburgh Pure Lisp Theorem Prover (PLTP) evolved
  into ACL2

---------
  Abstract

  We discuss the evolutionary path from the Edinburgh Pure Lisp Theorem
  Prover of the early 1970s to its modern counterpart, A
  Computational Logic for Applicative Common Lisp, aka ACL2, which is
  in regular industrial use. Among the milestones in this evolution
  are the adoption of a first-order subset of a programming language
  as a logic; the analysis of recursive definitions to guess
  appropriate mathematical induction schemes; the use of
  simplification in inductive proofs; the incorporation of rewrite
  rules derived from user-suggested lemmas; the generalization of
  that idea to allow the user to affect other proof techniques
  soundly; the recognition that evaluation efficiency is paramount so
  that formal models can serve as prototypes and the logic can be
  used to reprogram the system; use of the system to prove extensions
  correct; the incorporation of decision procedures; the provision of
  hierarchically structured libraries of previously certified results
  to configure the prover; the provision of system programming
  features to allow verification tools to be built and verified
  within the system; the release of many verified collections of
  lemmas supporting floating point, programming languages, and
  hardware platforms; a verified ``bit-bashing'' tool exploiting
  verified BDD and checked external SAT procedures; and the provision
  of certain higher-order features within the first-order setting. As
  will become apparent, some of these milestones were suggested or
  even prototyped by users. Some additional non-technical aspects of
  the project are also critical. Among these are a devotion to
  soundness, good documentation, freely available source code,
  production of a system usable by industry, responsiveness to user
  needs, and a dedicated, passionate, and brilliant user community.")
 (BIB::MOORE73
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{Computational Logic: Structure Sharing and Proof of
  Program Properties | http://www.era.lib.ed.ac.uk/handle/1842/2245},
  University of Edinburgh, Ph.D. dissertation, 1973.
  [31;1mRelevance:[0m details of the Edinburgh Pure Lisp Theorem Prover (PLTP)

---------
  Part II of Moore's dissertation describes the Edinburgh Pure Lisp
  Theorem Prover (PLTP) in detail.  The work was carried out jointly
  with Bob Boyer.")
 (BIB::MOORE96
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, [3mPiton: A Mechanically Verified Assembly-Level Language[0m, J
  S. Moore, Automated Reasoning Series, Kluwer Academic Publishers,
  1996.
  [31;1mRelevance:[0m verified assembler/linker/loader and a component of the
  CLI Verified Stack

---------
  The verified assembler/linker/loader in the final version of the CLI
  Stack (see [bib::bhmy89]) is described here.  See also the 1991
  Nqthm script [47mexamples/fm9001-piton/piton.events[0m.  The Preface to
  the book and the comment at the top of the [47m.events[0m file give a lot
  of history of the evolution of the components of the CLI Stack.

  Of particular interest to users who wish to verify the correct
  implementation of one programming language on top of a state
  machine is decomposition of the main theorem into ``commuting
  diagrams'' that stack various layers of abstraction between the
  assembly language and the binary image.  Among other things these
  layers of abstraction solve the problem of ``hidden resources,'' in
  which the lower level machine state has resources that are not
  reflected in the upper level.  For example at the high level, if
  one pushes items on the high level stack and then pops them off,
  there is no change to the stack when viewed from the high level.
  But the low level machine still records, in the region of memory
  dedicated to the stack but beyond the current top of stack, the
  items last pushed.  Furthermore, those residual values can be
  accessed by the low level machine.  So one has to prove that they
  are not.  The Piton proof dealt with this by imposing an
  intermediate abstract machine just above the low level machine but
  with an instruction set in which it is impossible to access beyond
  the top of stack.")
 (BIB::MOORE99A
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{Proving Theorems about Java-like Byte Code |
  https://www.cs.utexas.edu/~moore/publications/tjvm/main.pdf},'' in
  E.-R. Olderog and B. Steffen, editors, [3mCorrect System Design --
  Recent Insights and Advances[0m, LNCS [31;1m1710[0m, pp. 139-162, 1999.
  [31;1mRelevance:[0m M2: a JVM model similar to M1 but with method invocation
  (i.e., subroutine call)

---------
  Recall that in [operational-semantics-1__simple-example] we described
  a simple machine akin to the JVM but providing only a few
  stack-based arithmetic instructions and conditional and
  unconditional jump instructions.  In this paper a similar machine
  is formalized which provides method invocation and return for both
  static and virtual methods, and simple class-like instance objects
  with inheritance.  In the paper this machine is called the ``toy
  JVM'' or ``tjvm.'' But if we place it in the evolving sequence of
  approximations to the JVM it should be named ``M2.''

  The ACL2 scripts providing the definition and theorems of the paper
  (but now using the name [47mm2[0m instead of [47mtjvm[0m) may be found in the
  ACL2 directory [47mbooks/models/jvm/m2/[0m.  See the [47mREADME[0m file there.")
 (BIB::MOORE99B
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore, ``{A Mechanically Checked Proof of a Multiprocessor
  Result via a Uniprocessor View |
  https://www.cs.utexas.edu/~moore/publications/multi-v-uni.pdf}'', J
  S. Moore, [3mFormal Methods in System Design[0m, [31;1m14[0m(2), pp. 213-228,
  March, 1999.
  [31;1mRelevance:[0m proving a relationship between two state machines

---------
  Abstract

  We describe a mechanically checked correctness proof for a system of
  [3mn[0m processes, each running a simple, non-blocking counter algorithm.
  We prove that if the system runs longer than [3m5n[0m steps, the counter
  is increased.  The theorem is formalized in applicative Common Lisp
  and proved with the ACL2 theorem prover.  The value of this paper
  lies not so much in the trivial algorithm addressed as in the
  method used to prove it correct.  The method allows one to reason
  accurately about the behavior of a concurrent, multiprocess system
  by reasoning about the sequential computation carried out by a
  selected process, against a memory that is changed externally.
  Indeed, we prove general lemmas that allow shifting between the
  multiprocess and uniprocess views.  We prove a safety property
  using a multiprocess view, project the property to a uniprocess
  view, and then prove a global progress property via a local,
  sequential computation argument.  Our uniprocessor view is a formal
  compositional semantics for a shared memory system.

---------
  See the ACL2 script [47mbooks/misc/multi-v-uni.lisp[0m.")
 (BIB::MP02
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J S. Moore and G. Porter, ``{The Apprentice Challenge |
  https://www.cs.utexas.edu/~moore/publications/m5/apprentice.pdf}'',
  [3mACM TOPLAS[0m, [31;1m24[0m(3), pp. 1-24, May, 2002.
  [31;1mRelevance:[0m M5 and mutual-exclusion via monitors: an unbounded number
  of JVM threads competing for access to a shared resource

---------
  Abstract

  We describe a mechanically checked proof of a property of a small
  system of Java programs involving an unbounded number of threads
  and synchronization via monitors.  We adopt the output of the [47mjavac[0m
  compiler as the semantics and verify the system at the bytecode
  level under an operational semantics for the JVM.  We assume a
  sequentially consistent memory model and atomicity at the bytecode
  level.  Our operational semantics is expressed in ACL2, a
  Lisp-based logic of recursive functions.  Our proofs are checked
  with the ACL2 theorem prover.  The proof involves reasoning about
  arithmetic, infinite loops, the creation and modification of
  instance objects in the heap, including threads, the inheritance of
  fields from superclasses, pointer chasing and smashing, the
  invocation of instance methods (and the concomitant dynamic method
  resolution), use of the [47mstart[0m method on thread objects, the use of
  monitors to attain synchronization between threads, and
  consideration of all possible interleavings (at the bytecode level)
  over an unbounded number of threads.  Readers familiar with
  monitor-based proofs of mutual-exclusion will recognize our proof
  as fairly classical.  The novelty here comes from (i) the
  complexity of the individual operations on the abstract machine,
  (ii) the dependencies between Java threads, heap objects, and
  synchronization, (iii) the bytecode-level interleaving, (iv) the
  unbounded number of threads, (v) the presence in the heap of
  incompletely initialized threads and other objects, and (vi) the
  proof engineering permitting automatic mechanical verification of
  code-level theorems.  We discuss these issues.  The problem posed
  here is also put forth as a benchmark against which to measure
  other approaches to formally proving properties of multi-threaded
  Java programs.")
 (BIB::MP67
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J. McCarthy and J. Painter, ``{Correctness of a Compiler for
  Arithmetic Expressions |
  http://jmc.stanford.edu/articles/mcpain/mcpain.pdf}'', [3mProceedings
  of Symposia in Applied Mathematics[0m, [31;1m19[0m, American Mathematical
  Society, 1967.
  [31;1mRelevance:[0m an early (perhaps the first) compiler proof

---------
  This paper by gives a conventional ``hand proof'' (not a mechanized
  proof) of the correctness of a compiler for simple arithmetic
  expressions.  It demonstrates the use of an operational semantics
  for the underlying machine.

  This was a famous and popular challenge problem in the early history
  of formal methods.  See Chapter 17 [bib::bm79] for a mechanized
  proof a similar result and a discussion of the history of the
  mechanization of such compiler proofs.")
 (BIB::PLOTKIN04A
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "G. D. Plotkin, ``{ A Structural Approach to Operational Semantics |
  https://homepages.inf.ed.ac.uk/gdp/publications/sos_jlap.pdf}'',
  Computer Science Department, Aarhus University, Denmark, DAIMI
  FN-19, 1981 (reprised in a 2004 submission to the [3mThe Journal of
  Logic and Algebraic Programming[0m).
  [31;1mRelevance:[0m Plotkin's introduction of the term ``structural
  operational semantics''

---------
  In the introduction to this historically important ``Aahus note''
  Plotkin wrote:

  1.1 Introduction

  It is the purpose of these notes to develop a simple and direct
  method for specifying the semantics of programming languages. Very
  little is required in the way of mathematical background; all that
  will be involved is ``symbol-pushing'' of one kind or another of
  the sort which will already be familiar to readers with experience
  of either the non-numerical aspects of programming languages or
  else formal deductive systems of the kind employed in mathematical
  logic.

  Apart from a simple kind of mathematics the method is intended to
  produce concise comprehensible semantic definitions. Indeed the
  method is even intended as a direct formalisation of (many aspects
  of) the usual informal natural language descriptions. I should
  really confess here that while I have some experience what has been
  expressed above is rather a pious hope than a statement of fact. I
  would therefore be most grateful to readers for their comments and
  particularly their criticisms.

  I will follow the approach to programming languages taken by such
  authors as Gordon [Gor] and Tennent [Ten] considering the main
  syntactic classes --- expressions, commands and declarations ---
  and the various features found in each. The linguistic approach is
  that developed by the Scott-Strachey school (together with Landin
  and McCarthy and others) but within an operational rather than a
  denotational framework. These notes should be considered as an
  attempt at showing the feasibility of such an approach. Apart from
  various inadequacies of the treatment as presented many topics of
  importance are omitted. These include data structures and data
  types; various forms of control structure from jumps to exceptions
  and coroutines; concurrency including semaphores, monitors and
  communicating process.")
 (BIB::PLOTKIN04B
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "G. D. Plotkin, ``{ The origins of structural operational semantics |
  https://www.sciencedirect.com/science/article/pii/S1567832604000268}'',
  [3mThe Journal of Logic and Algebraic Programming[0m, [31;1m60[0m and [31;1m61[0m, pp.
  3-15, July and December 2004.
  [31;1mRelevance:[0m an interesting historical account of the most popular
  (non-ACL2) approach to operational semantics

---------
  The term ``structural Operational Semantics'' was introduced by
  Gordon Plotkin in technical note DAIMI FN-19, Computer Science
  Department, Aarhus University, 1981.  That sense of ``operational
  semantics'' is probably the most popular today and the literature
  has grown enormously since the original note.  For that reason, we
  cite this ``origins'' paper because it was published in a two
  volume special issue of [3mThe Journal of Logic and Algebraic
  Programming[0m.  Furthermore, the original 1981 ``Aarhus note'' is
  included in that issue, and that special issue can be downloaded in
  full from this citation.

  The approach to operational semantics most widely used in the ACL2
  community is different from structural operational semantics.
  Plotkin formalized machines operationally but as inference rules
  (reminiscent of Hoare logic), whereas in ACL2 the logic is fixed
  --- it is the logic of the ACL2 theorem prover --- and in ACL2 the
  theory is extended via conservative definitions to describe the
  operation of the machines in question.

  In this origins paper, Plotkin writes

      ``The IBM Vienna school [41,42] were interested in specifying real
      programming languages, and, in particular, worked on an
      abstract interpreting machine for PL/I using VDL, their Vienna
      Definition Language; they were influenced by the ideas of
      McCarthy, Landin and Elgot [18].

      I remember attending a seminar at Edinburgh where the intricacies of
      their PL/I abstract machine were explained. The states of these
      machines are tuples of various kinds of complex trees and there
      is also a stack of environments; the transition rules involve
      much tree traversal to access syntactical control points,
      handle jumps, and to manage concurrency. I recall not much
      liking this way of doing operational semantics. It seemed far
      too complex, burying essential semantical ideas in masses of
      detail; further, the machine states were too big. The lesson I
      took from this was that abstract interpreting machines do not
      scale up well when used as a human-oriented method of
      specification for real languages (but see below for further
      comment).''

  There is no doubt that interpretive operational semantics for
  commercial microprocessors is enormously complicated and much of
  that complexity is buried in data structures, but we in the ACL2
  community tend to regard that as an unavoidable consequence of how
  the machines are designed and the fact that the structure of the
  designs manifest themselves in behaviors that users see.  Would a
  structural operational semantics for the system-level view of x86
  be less complex than the ACL2 x86 model described in [bib::goel16]?
  We also agree with Plotkin's observation that the interpretive
  approach does not scale well [3mwhen used as a human-oriented method
  of specification for real languages[0m.  However, our focus is on
  [3mmechanized[0m reasoning about machines and we are optimistic that
  mechanization can manage the complexity.  Furthermore, we believe
  the examples discussed in [operational-semantics-2__other-examples]
  support our optimism.  Of course, as noted in
  [operational-semantics-1__simple-example], the ACL2 user is
  responsible for configuring ACL2's prover to manage the complexity
  but the evidence is that expert users are capable of doing that,
  exploiting such ACL2 features as rewrite rules, metafunctions,
  enabling and disabling, pragmas for controlling rules, and hints
  (including computed hints).")
 (BIB::RHMM07
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "S. Ray, W. A. Hunt, Jr., J. Matthews, and J S. Moore, `{A Mechanical
  Analysis of Program Verification Strategies |
  https://link.springer.com/article/10.1007/s10817-008-9098-1},''
  [3mJournal of Automated Reasoning[0m, [31;1m40[0m(4), pp. 245-269, May, 2008.
  [31;1mRelevance:[0m stepwise invariants, clock functions, and inductive
  assertion proof styles are all equivalent

---------
  Abstract

  We analyze three proof strategies commonly used in deductive
  verification of deterministic sequential programs formalized with
  operational semantics. The strategies are (i) stepwise invariants,
  (ii) clock functions, and (iii) inductive assertions. We show how
  to formalize the strategies in the logic of the ACL2 theorem
  prover. Based on our formalization, we prove that each strategy is
  both sound and complete. The completeness result implies that given
  any proof of correctness of a sequential program one can derive a
  proof in each of the above strategies. The soundness and
  completeness theorems have been mechanically checked with ACL2.

---------
  See also [bib::rm04].")
 (BIB::RM04
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "S. Ray and J S. Moore, ``{Proof Styles in Operational Semantics |
  https://www.ece.ufl.edu/wp-content/uploads/sites/119/publications/fmcad04.pdf},''
  in A. J. Hu and A. K. Martin, editors, [3mFormal Methods in
  Computer-Aided Design (FMCAD-2004)[0m, Springer, LNCS [31;1m3312[0m, pp. 67-81,
  2004.
  [31;1mRelevance:[0m ACL2 tools for transforming inductive assertion-style
  proofs to clock function style and vice versa

---------
  Abstract

  We relate two well-studied methodologies in deductive verification of
  operationally modeled sequential programs, namely the use of
  inductive invariants and clock functions. We show that the two
  methodologies are equivalent and one can mechanically transform a
  proof of a program in one methodology to a proof in the other. Both
  partial and total correctness are considered. This mechanical
  transformation is compositional; different parts of a program can
  be verified using different methodologies to achieve a complete
  proof of the entire program. The equivalence theorems have been
  mechanically checked by the ACL2 theorem prover and we implement
  automatic tools to carry out the transformation between the two
  methodologies in ACL2.

---------
  See also the files by S. Ray on the ACL2 directory
  [47mbooks/proofstyles/[0m.")
 (BIB::SAWADA00
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J. Sawada, ``Verification of a Simple Pipelined Machine Model,'' in
  M. Kaufmann, P. Manolios, J S. Moore, editors, [3mComputer-Aided
  Reasoning: ACL2 Case Studies[0m, Kluwer Academic Publishers, Chapter
  9, pp. 137-150, 2000. (See also {ACL2 books |
  https://www.cs.utexas.edu/~moore/publications/acl2-papers.html#Books}).
  [31;1mRelevance:[0m operational model of a pipelined machine and its
  verification

---------
  Abstract

  The difficulty of pipelined machine verification derives from the
  fact that there is a complex time-abstraction between the pipelined
  implementation and its specification which executes instructions
  sequentially.  To study this problem, we define a simple
  three-stage pipelined machine in ACL2.  We prove that this
  pipelined machine returns the same result as its specification
  machine.  In order to ease the proof, we define an intermediate
  abstraction called MAETT.  This abstraction models the behavior of
  instructions in the pipelined architecture, and it allows us to
  define directly and verify invariant conditions about executed
  instructions.  The author used a similar approach to verify a more
  realistic pipelined machine.  This chapter serves as an
  introduction to the verification of pipelined machines.")
 (BIB::SH98
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "J. Sawada and W. A. Hunt, Jr, ``{Processor Verification with Precise
  Exceptions and Speculative Execution |
  https://link.springer.com/chapter/10.1007/BFb0028740}'', in A. J.
  Hu and M. Y. Vardi, editors, [3mComputer Aided Verification, (CAV
  '98)[0m, Springer-Verlag LNCS [31;1m1427[0m, Heidelberg, pp. 135-146, 1998.
  [31;1mRelevance:[0m proof method for dealing with exceptions and speculative
  execution

---------
  Abstract

  We describe a framework for verifying a pipelined microprocessor
  whose implementation contains precise exceptions, external
  interrupts, and speculative execution. We present our correctness
  criterion which compares the state transitions of pipelined and
  non-pipelined machines in presence of external interrupts. To
  perform the verification, we created a table-based model of
  pipeline execution. This model records committed and in-flight
  instructions as performed by the microarchitecture. Given that
  certain requirements are met by this table-based model, we have
  mechanically verified our correctness criterion using the ACL2
  theorem prover.")
 (BIB::WILDING92
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "M. M. Wilding, [3mMachine-checked real-time system verification[0m
  [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/wilding.pdf)[0m, University of
  Texas at Austin, Ph.D. dissertation, 1996.
  [31;1mRelevance:[0m a non-trivial applications program on the CLI Verified
  Stack

---------
  In the introduction to this dissertation, the author writes:

  ``The complexity and importance of real-time systems makes their
  formalization and verification crucial.  We ensure proper real-time
  system behavior in several ways through mathematical proof.  We
  check proofs using Nqthm, a mechanical proof system also known as
  the Boyer-Moore theorem prover.

  ...

  We verify a high-level language application that, using a proved
  compiler and microprocessor design, assures the optimality and
  timely behavior of an application.  The verified program uses a
  clever algorithm to meet its specification and a method for
  structuring proofs allows large verified programs to be developed.
  An interpreter-based language semantics allows reliable execution
  behavior reasoning, including reasoning about timing.''

---------
  The dissertation deals with several programs written in the Piton
  assembly language ([bib::moore96]) for the FM9001 ([bib::hb92]).
  In addition to establishing functional correctness, the proofs
  ensure that the Piton images fit in the space provided by the
  fabricated FM9001, provide upper bounds on the instruction counts,
  and the sizes of both the control stack and the temporary stack
  implemented by Piton on the FM9001.  See also [bib::wilding93] for
  a discussion of one of these programs, namely one that implements a
  winning strategy for the game of Nim.

  See the Nqthm scripts by downloading and extracting the [47m*.events[0m
  files from
  [47mftp://ftp.cs.utexas.edu/pub/boyer/diss/wilding-diss-events.tar[0m.")
 (BIB::WILDING93
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "M. M. Wilding, ``{A Mechanically Verified Application for a
  Mechanically Verified Environment |
  https://link.springer.com/content/pdf/10.1007/3-540-56922-7_22}, in
  C. Courcoubetis, editor, [3mProceedings of Computer-Aided Verification
  -- CAV '93[0m, Springer-Verlag, LNCS [31;1m697[0m, Heidelberg, pp. 268-279,
  DOI:10.1007/3-540-56922-7_22, 1993.
  [31;1mRelevance:[0m functional correctness and resource utilization of a
  Nim-playing program on the CLI Verified Stack

---------
  Abstract

  We have developed a verified application proved to be both effective
  and efficient. The application generates moves in the puzzle-game
  Nim and is coded in Piton, a language with a formal semantics and a
  compiler verified to preserve its semantics on the underlying
  machine. The Piton compiler is targeted to the FM9001, a recently
  fabricated verified microprocessor. The Nim program correctness
  proof makes use of the language semantics that the compiler is
  proved to implement. Like the Piton compiler proof and FM9001
  design proof, the Nim correctness proof is generated using Nqthm, a
  proof system sometimes known as the Boyer-Moore theorem prover.

---------
  The paper proves that a Piton program constructed by the author
  implements a winning strategy (if one exists for a given starting
  state) of the game of Nim.  In addition, he proved a bound on the
  number of instructions executed on each move as well as bounds on
  the sizes of both the control stack and the temporary stack.

  In the conclusion of the paper (page 278) the author writes

  ``Mechanical verification of programs in this manner is
  time-consuming and difficult. Nevertheless, and quite remarkably,
  the experience of building the Nim program suggests that
  development time scales linearly with program length. Once a Piton
  subroutine has been proved correct, a call to this subroutine can
  be reasoned about as easily as any basic Piton statement.

  ...

  An FM9001 was fabricated and runs a compiled version of the Nim
  program. The fabricated FM9001 microprocessor, the Piton compiler,
  and the Nim program were never tested in a conventional manner
  during development or after completion. Even so, each worked the
  first time and we would have been surprised if any had not.''")
 (BIB::YOUNG88
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "W. D. Young, [3mA Verified Code Generator for a Subset of Gypsy[0m
  [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/young.pdf)[0m, University of
  Texas at Austin, Ph.D. dissertation, 1988.
  [31;1mRelevance:[0m a verified compiler (from a small Pascal-like subset to an
  assembly language) and a component of the CLI Verified Stack

---------
  The verified compiler used in the CLI Verified Stack as reported in
  [bib::bhmy89] is described here.  By the way, we could not find the
  original Nqthm script for this effort, but the complete script is
  included in Appendix B of the linked pdf file above, pages 206-860.")
 (BIB::YU92
  (OPERATIONAL-SEMANTICS-3__ANNOTATED-BIBLIOGRAPHY)
  "Y. Yu, [3mAutomated proofs of object code for a widely used
  microprocessor[0m [47m(ftp://ftp.cs.utexas.edu/pub/boyer/diss/yu.pdf)[0m,
  University of Texas at Austin, Ph.D. dissertation, 1992.
  [31;1mRelevance:[0m details of the operational model of the Motorola 68020

---------
  Abstract

  Computing devices can be specified and studied mathematically.
  Formal specification of computing devices has many advantages ---
  it provides a precise characterization of the computational model
  and allows for mathematical reasoning about models of the computing
  devices and programs executed on them.  While there has been a
  large body of research on program proving, work has almost
  exclusively focused on programs written in high level programming
  languages.  This thesis addresses the very important but largely
  ignored problem of machine code program proving.  In this thesis we
  have formally described a substantial subset of the MC68020, a
  widely used microprocessor built by Motorola, within the
  mathematical logic of the automated reasoning system Nqthm, a.k.a.
  the Boyer-Moore Theorem Proving System.  Based on this formal
  model, we have mechanized a mathematical theory to facilitate
  automated reasoning about object code programs.  We then have
  mechanically checked the correctness of MC68020 object code
  programs for binary search, Hoare's Quick Sort, the Berkeley Unix C
  string library, and other well-known algorithms.  The object code
  for these examples were generated using the Gnu C, the Verdix Ada,
  and the AKCL common Lisp compilers.

---------
  See also the Nqthm scripts [47mexamples/yu/[0m where you will find the
  definition of the MC68020 model and the proofs of the programs
  mentioned."))

)