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

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

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

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

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

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

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


File: acl2-doc-emacs.info,  Node: ACL2-PC||APPLY-LINEAR,  Next: ACL2-PC||BASH,  Prev: ACL2-PC||AL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||APPLY-LINEAR    (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 show-linears (sls) command.

A short name for this command is al.

We assume familiarity with the proof-checker's rewrite (r) command.  In
brief, the apply-linear command is an analogue of the rewrite command,
but for linear rules in place of rewrite rules.  There is a significant
difference: for the apply-linear command, instead of rewriting the
current subterm as is done by the rewrite 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 apply-linear command may not
correspond as closely to the prover's automatic use of a linear rule as
the rewrite command corresponds to the prover's automatic use of a
rewrite rule.

Below, we refer freely to the documentation for the proof-checker's
rewrite command.

The rule-id is treated just as it is by the rewrite command.  If
rule-id is a positive integer n, then the nth rule as displayed by
show-linears is the one that is applied.  If rule-id is nil or is not
supplied, then it is treated as the number 1.  Otherwise, rule-id
should be either a symbol or else a :linear 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 (<
(g (h y)) y) and that foo is the name of the following linear rule.

     (implies (true-listp x)
              (< (g x) 15))

Then the instruction (apply-linear foo) applies foo by adding a new
hypothesis (< (g (h y)) 15).  In addition, a new goal with conclusion
(true-listp y) is created unless the current context (top-level
hypotheses and governors) implies (true-listp y) using only "trivial
reasoning", just as for the rewrite command.

If the rule-id argument is a number or is not supplied, then the system
will store an instruction of the form (apply-linear name ...), where
name 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 (:rewrite name . index), where index is not nil.)

Speaking in general, then, an apply-linear 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 *note LINEAR::) is matched with
the current subterm, i.e., a substitution unify-subst is found such
that if one instantiates that trigger term of the rule with
unify-subst, 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 *note FREE-VARIABLES::), exactly as is
done with hypotheses when applying the proof-checker command, rewrite
(r).

Finally, the instruction is applied exactly as the rewrite 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 rewrite command, the substitution argument should
be a list whose elements have the form (variable term), where term may
contain abbreviations.


File: acl2-doc-emacs.info,  Node: ACL2-PC||BASH,  Next: ACL2-PC||BDD,  Prev: ACL2-PC||APPLY-LINEAR,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||BASH    (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 prove, the arguments to bash are spread out, and are
all hints.

Bash is similar to reduce in that neither of these allows induction.
But bash only allows simplification, while reduce allows processes
eliminate-destructors, fertilize, generalize, and eliminate-irrelevance.

*Remark:*  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).


File: acl2-doc-emacs.info,  Node: ACL2-PC||BDD,  Next: ACL2-PC||BK,  Prev: ACL2-PC||BASH,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||BDD    (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 :bdd
hint; see *note HINTS::.

This command simply calls the theorem prover with the indicated bdd
hint for the top-level goal.  Note that if :prove is t (the default),
then the proof will succeed entirely using bdds or else it will fail
immediately.  See *note BDD::.


File: acl2-doc-emacs.info,  Node: ACL2-PC||BK,  Next: ACL2-PC||BOOKMARK,  Prev: ACL2-PC||BDD,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||BK    (atomic macro)
move backward one argument in the enclosing term

     Example and General Form:
     bk

For example, if the conclusion is (= x (* (- y) z)) and the current
subterm is (* (- y) z), then after executing bk, the current subterm
will be x.

Move to the previous argument of the enclosing term.

This is the same as up followed by (dive n-1), where n is the position
of the current subterm in its parent term in the conclusion.  Thus in
particular, the nx command fails if one is already at the top of the
conclusion.

See also up, dive, top, and bk.


File: acl2-doc-emacs.info,  Node: ACL2-PC||BOOKMARK,  Next: ACL2-PC||CASESPLIT,  Prev: ACL2-PC||BK,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||BOOKMARK    (macro)
insert matching "bookends" comments

     Example:
     (bookmark final-goal)

     General Form:
     (bookmark name &rest instruction-list)

Run the instructions in instruction-list (as though this were a call of
do-all; see the documentation for 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 the
documentation of comm for an explanation of bookends and how they can
affect the display of instructions.


File: acl2-doc-emacs.info,  Node: ACL2-PC||CASESPLIT,  Next: ACL2-PC||CG,  Prev: ACL2-PC||BOOKMARK,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CASESPLIT    (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 expr as a new top-level hypothesis, and create a subgoal identical
to the existing current goal except that it has the negation of expr as
a new top-level hypothesis.  See also claim.  The optional arguments
control the use of governors and the "flattening" of new hypotheses, as
we now explain.

The argument use-hyps-flag is only of interest when there are
governors.  (To read about governors, see the documentation for the
command hyps).  In that case, if use-hyps-flag is not supplied or is
nil, then the description above is correct; but otherwise, it is not
expr but rather it is (implies govs expr) that is added as a new
top-level hypothesis (and whose negation is added as a top-level
hypothesis for the new goal), where govs is the conjunction of the
governors.

If do-not-flatten-flag is supplied and not nil, then that is all there
is to this command.  Otherwise (thus this is the default), when the
claimed term (first argument) is a conjunction (and) of terms and the
claim 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 (<
x y), (integerp a), and (equal r s).  In that case, only one hypothesis
is added to create the new goal, namely the negation of (and (< x y)
(integerp a) (equal r s)).  If the negation of this term had been
claimed, 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.

*Remark:*  It is allowed to use abbreviations in the hints.


File: acl2-doc-emacs.info,  Node: ACL2-PC||CG,  Next: ACL2-PC||CHANGE-GOAL,  Prev: ACL2-PC||CASESPLIT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CG    (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 (change-goal goal-name t), i.e. change to the indicated and
move the current goal to the end of the goal stack.


File: acl2-doc-emacs.info,  Node: ACL2-PC||CHANGE-GOAL,  Next: ACL2-PC||CL-PROC,  Prev: ACL2-PC||CG,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CHANGE-GOAL    (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 goal-name, i.e. make it the current
goal.  However, if goal-name is nil or is not supplied, then it
defaults to the next-to-top goal, i.e., the second goal in the stack of
goals.  If end-flg is supplied and not nil, then move the current goal
to the end of the goal stack; else merely swap it with the next-to-top
goal.  Also see documentation for cg.


File: acl2-doc-emacs.info,  Node: ACL2-PC||CL-PROC,  Next: ACL2-PC||CLAIM,  Prev: ACL2-PC||CHANGE-GOAL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CL-PROC    (macro)
same as clause-processor

See the documentation for proof-checker command clause-processor, which
is identical to cl-proc.


File: acl2-doc-emacs.info,  Node: ACL2-PC||CLAIM,  Next: ACL2-PC||CLAUSE-PROCESSOR,  Prev: ACL2-PC||CL-PROC,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CLAIM    (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 expr.  If rest-args 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, rest-args
should consist of keyword arguments.  The keyword argument
:do-not-flatten controls the "flattening" of new hypotheses, just as
with the casesplit command (as described in its documentation).  The
remaining rest-args are used with a call the prove command on the new
subgoal, except that if :hints is a non-nil atom, then the prover is
not called -- rather, this is the same as the situation described
above, where rest-args is a non-empty list headed by a non-keyword.

*Remarks:*  (1) Unlike the casesplit command, the claim command is
completely insensitive to governors. (2) It is allowed to use
abbreviations in the hints.  (3) The keyword :none has the special role
as a value of :hints that is shown clearly in an example above.


File: acl2-doc-emacs.info,  Node: ACL2-PC||CLAUSE-PROCESSOR,  Next: ACL2-PC||COMM,  Prev: ACL2-PC||CLAIM,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CLAUSE-PROCESSOR    (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
     books/clause-processors/basic-examples.lisp.

     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 :clause-processor hint;
see *note HINTS::.

This command calls the prove command, and hence should only be used at
the top of the conclusion.


File: acl2-doc-emacs.info,  Node: ACL2-PC||COMM,  Next: ACL2-PC||COMMANDS,  Prev: ACL2-PC||CLAUSE-PROCESSOR,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||COMM    (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
(commands n t) -- or, (commands nil t) if n is not supplied.  As
explained in the documentation for commands, the final argument of t
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 x and the "name" of the second
bookend is x'.  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. x equals x') and if no other begin or end bookend
with name x occurs between them.  The idea now is that comm 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 comm instruction hides bookends in the following manner.  (So does a
comment instruction when its second optional argument is supplied and
non-nil.)  First, if the first argument n is supplied and not nil, then
we consider only the last n 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 (comment begin name ...) is the begin bookend of the pair.
Finally, after applying this process to each pair of matching bookends,
each begin bookend of the form (comment begin name ...)  that remains
is replaced by

     ("***UNFINISHED***" :COMMENT :BEGIN name ...) .


File: acl2-doc-emacs.info,  Node: ACL2-PC||COMMANDS,  Next: ACL2-PC||COMMENT,  Prev: ACL2-PC||COMM,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||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.

*Remark*:  If there are more than n instructions in the state-stack,
then (commands n) is the same as commands (and also, (commands n abb)
is the same as (commands nil abb)).


File: acl2-doc-emacs.info,  Node: ACL2-PC||COMMENT,  Next: ACL2-PC||CONTRADICT,  Prev: ACL2-PC||COMMANDS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||COMMENT    (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
comment instruction.

Some comments can be used to improve the display of commands; see
documentation for comm.


File: acl2-doc-emacs.info,  Node: ACL2-PC||CONTRADICT,  Next: ACL2-PC||CONTRAPOSE,  Prev: ACL2-PC||COMMENT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CONTRADICT    (macro)
same as contrapose

see documentation for contrapose


File: acl2-doc-emacs.info,  Node: ACL2-PC||CONTRAPOSE,  Next: ACL2-PC||DEMOTE,  Prev: ACL2-PC||CONTRADICT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||CONTRAPOSE    (primitive)
switch a hypothesis with the conclusion, negating both

     Example:
     (contrapose 3)

     General Form:
     (contrapose &optional n)

The (optional) argument n should be a positive integer that does not
exceed the number of hypotheses.  Negate the current conclusion and
make it the nth hypothesis, while negating the current nth hypothesis
and making it the current conclusion.  If no argument is supplied then
the effect is the same as for (contrapose 1).

*Remark:* By "negate" we mean an operation that replaces nil by t, x by
nil for any other explicit value x, (not x) by x, and any other x by
(not x).


File: acl2-doc-emacs.info,  Node: ACL2-PC||DEMOTE,  Next: ACL2-PC||DIVE,  Prev: ACL2-PC||CONTRAPOSE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||DEMOTE    (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 x and y and the conclusion
is z, then after execution of demote, the conclusion will be (implies
(and x y) z) and there will be no (top-level) hypotheses.

     General Form:
     (demote &rest hyps-indices)

Eliminate the indicated (top-level) hypotheses, but replace the
conclusion conc with (implies hyps conc) where hyps is the conjunction
of the hypotheses that were eliminated.  If no arguments are supplied,
then all hypotheses are demoted, i.e. demote is the same as (demote 1 2
... n) where n is the number of top-level hypotheses.

*Remark*:  You must be at the top of the conclusion in order to use
this command.  Otherwise, first invoke top.  Also, demote fails if
there are no top-level hypotheses or if indices are supplied that are
out of range.


File: acl2-doc-emacs.info,  Node: ACL2-PC||DIVE,  Next: ACL2-PC||DO-ALL,  Prev: ACL2-PC||DEMOTE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||DIVE    (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 (dive 1) it is

     (+ a b).

If after that, then (dive 2) is invoked, the new current subterm will be

     b.

Instead of (dive 1) followed by (dive 2), the same current subterm
could be obtained by instead submitting the single instruction (dive 1
2).

     General Form:
     (dive &rest naturals-list)

If naturals-list is a non-empty list (n_1 ... n_k) of natural numbers,
let the new current subterm be the result of selecting the n_1-st
argument of the current subterm, and then the n_2-th subterm of that,
..., finally the n_k-th subterm.

*Remark:*  Dive is related to the command pp, in that the diving is
done according to raw (translated, internal form) syntax.  Use the
command dv if you want to dive according to the syntax displayed by the
command p.  Note that (dv n) can be abbreviated by simply n.


File: acl2-doc-emacs.info,  Node: ACL2-PC||DO-ALL,  Next: ACL2-PC||DO-ALL-NO-PROMPT,  Prev: ACL2-PC||DIVE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||DO-ALL    (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
instruction-list does.  (See the documentation for 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 global state variable
pc-print-prompt-and-instr-flg is nil.

*Remark:*  If do-all "fails", then the failure is hard if and only if
the last instruction it runs has a hard "failure".

Obscure point:  For the record, (do-all ins_1 ins_2 ... ins_k) is the
same as (sequence (ins_1 ins_2 ... ins_k)).


File: acl2-doc-emacs.info,  Node: ACL2-PC||DO-ALL-NO-PROMPT,  Next: ACL2-PC||DO-STRICT,  Prev: ACL2-PC||DO-ALL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||DO-ALL-NO-PROMPT    (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)

Do-all-no-prompt is the same as do-all, except that the prompt and
instruction are not printed each time, regardless of the value of
pc-print-prompt-and-instr-flg.  Also, restoring is disabled.  See the
documentation for do-all.


File: acl2-doc-emacs.info,  Node: ACL2-PC||DO-STRICT,  Next: ACL2-PC||DROP,  Prev: ACL2-PC||DO-ALL-NO-PROMPT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||DO-STRICT    (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 do-strict is identical in effect to do-all, except
that do-all only halts once there is a hard "failure".  See the
documentation for do-all.


File: acl2-doc-emacs.info,  Node: ACL2-PC||DROP,  Next: ACL2-PC||DV,  Prev: ACL2-PC||DO-STRICT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||DROP    (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.

*Remark:*  If there are no top-level hypotheses, then the instruction
drop 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 (inclusive),
then (drop n1 n2 ...) will fail.


File: acl2-doc-emacs.info,  Node: ACL2-PC||DV,  Next: ACL2-PC||ELIM,  Prev: ACL2-PC||DROP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||DV    (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 (dv 1) it is

     (+ a b).

If after that, then (dv 2) is invoked, the new current subterm will be

     b.

Instead of (dv 1) followed by (dv 2), the same current subterm could be
obtained by instead submitting the single instruction (dv 1 2).

     General Form:
     (dv &rest naturals-list)

If naturals-list is a non-empty list (n_1 ... n_k) of natural numbers,
let the new current subterm be the result of selecting the n_1-st
argument of the current subterm, and then the n_2-th subterm of that,
..., finally the n_k-th subterm.

*Remark:*  (dv n) may be abbreviated by simply n, so we could have
typed 1 instead of (dv 1) in the first example above.

*Remark:*  See also dive, which is related to the command pp, in that
the diving is done according to raw (translated, internal form) syntax.
Use the command dv if you want to dive according to the syntax
displayed by the command p.  Thus, the command "up" is the inverse of
dive, not of dv.  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)
     ->:


File: acl2-doc-emacs.info,  Node: ACL2-PC||ELIM,  Next: ACL2-PC||EQUIV,  Prev: ACL2-PC||DV,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||ELIM    (atomic macro)
call the ACL2 theorem prover's elimination process

     Example and General Form:
     elim

Upon running the elim 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 *only* elimination is used; not
even simplification is used!


File: acl2-doc-emacs.info,  Node: ACL2-PC||EQUIV,  Next: ACL2-PC||EX,  Prev: ACL2-PC||ELIM,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||EQUIV    (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 new for old everywhere inside the current subterm, provided
that either (relation old new) or (relation new old) is among the
top-level hypotheses or the governors (possibly by way of backchaining
and/or refinement; see below).  If relation is nil or is not supplied,
then it defaults to equal.  See also the command =, which is much more
flexible.  Note that this command fails if no substitution is actually
made.

*Remark:*  No substitution takes place inside explicit values.  So for
example, the instruction (equiv 3 x) will cause 3 to be replaced by x
if the current subterm is, say, (* 3 y), but not if the current subterm
is (* 4 y) even though 4 = (1+ 3).

The following remarks are quite technical and mostly describe a certain
weak form of "backchaining" that has been implemented for equiv in
order to support the = command.  In fact neither the term (relation old
new) nor the term (relation new old) needs to be *explicitly* among the
current "assumptions", i.e., the top-level hypothesis or the governors.
Rather, there need only be such an assumption that "tells us" (r old
new) or (r new old), for *some* equivalence relation r that *refines*
relation.  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 implies term) are all among the current assumptions.


File: acl2-doc-emacs.info,  Node: ACL2-PC||EX,  Next: ACL2-PC||EXIT,  Prev: ACL2-PC||EQUIV,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||EX    (macro)
exit after possibly saving the state

     Example and General Form:
     ex

Same as exit, except that first the instruction save is executed.

If save queries the user and is answered negatively, then the exit is
aborted.


File: acl2-doc-emacs.info,  Node: ACL2-PC||EXIT,  Next: ACL2-PC||EXPAND,  Prev: ACL2-PC||EX,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||EXIT    (meta)
exit the interactive proof-checker

     Examples:
     exit                        -- exit the interactive proof-checker
     (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 exit returns you to the ACL2 loop.  At a later time,
(verify) may be executed to get back into the same proof-checker state,
as long as there hasn't been an intervening use of the proof-checker
(otherwise see save).

When given one or more arguments as shown above, exit still returns you
to the ACL2 loop, but first, if the interactive proof is complete, then
it attempts create a defthm event with the specified event-name and
rule-classes (which defaults to (:rewrite) 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 do-it-flg is supplied and not nil, then an
event will be made without a query.

For example, the form

     (exit top-pop-elim (:elim :rewrite) t)

causes a defthm event named top-pop-elim to be created with
rule-classes (:elim :rewrite), without a query to the user (because of
the argument t).

*Remark:* it is permitted for event-name to be nil.  In that case, the
name of the event will be the name supplied during the original call of
verify.  (See the documentation for verify and commands.)  Also in that
case, if rule-classes is not supplied then it defaults to the
rule-classes supplied in the original call of verify.

Comments on "success" and "failure".  An exit instruction will always
"fail", so for example, if it appears as an argument of a do-strict
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 exit; otherwise it
will be "soft".  See the documentation for 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 (mv erp val state) into (mv t val state) would never cause an
exit from the interactive loop.

If the proof is not complete, then (exit event-name ...) will not cause
an exit from the interactive loop.  However, in that case it will print
out the original user-supplied goal (the one that was supplied with the
call to verify) and the current list of instructions.


File: acl2-doc-emacs.info,  Node: ACL2-PC||EXPAND,  Next: ACL2-PC||FAIL,  Prev: ACL2-PC||EXIT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||EXPAND    (primitive)
expand the current function call without simplification

     Examples:
     expand -- expand and do not simplify.

For example, if the current subterm is (append a b), then after (expand
t) the current subterm will be the term:

     (if (true-listp x)
         (if x
             (cons (car x) (append (cdr x) y))
           y)
       (apply 'binary-append (list x y)))

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

See also x, which allows simplification.


File: acl2-doc-emacs.info,  Node: ACL2-PC||FAIL,  Next: ACL2-PC||FINISH,  Prev: ACL2-PC||EXPAND,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||FAIL    (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 fail is to fail to "succeed".

The full story is that fail and (fail nil) simply return (mv nil nil
state), while (fail hard) returns (mv hard nil state) if hard is not
nil.  See also do-strict, do-all, and sequence.


File: acl2-doc-emacs.info,  Node: ACL2-PC||FINISH,  Next: ACL2-PC||FORWARDCHAIN,  Prev: ACL2-PC||FAIL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||FINISH    (macro)
require completion of instructions; save error if inside :hints

     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 finish to
be a failure.  See *note PROOF-CHECKER-COMMANDS:: and visit the
documentation for sequence for a discussion of the notion of "failure"
for proof-checker commands.


File: acl2-doc-emacs.info,  Node: ACL2-PC||FORWARDCHAIN,  Next: ACL2-PC||FREE,  Prev: ACL2-PC||FINISH,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||FORWARDCHAIN    (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 given index,
which should be of the form (IMPLIES hyp concl), with its consequent
concl.  In fact, the given hypothesis is dropped, and the replacement
hypothesis will appear as the final hypothesis after this command is
executed.

The prover must be able to prove the indicated hypothesis from the
other hypotheses, or else the command will fail.  The :hints argument
is used in this prover call, and should have the usual syntax of hints
to the prover.

Output is suppressed if quiet-flg is supplied and not nil.


File: acl2-doc-emacs.info,  Node: ACL2-PC||FREE,  Next: ACL2-PC||GENEQV,  Prev: ACL2-PC||FORWARDCHAIN,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||FREE    (atomic macro)
create a "free variable"

     Example:
     (free x)

     General Form:
     (free var)

Mark var as a "free variable".  Free variables are only of interest for
the put command; see its documentation for an explanation.


File: acl2-doc-emacs.info,  Node: ACL2-PC||GENEQV,  Next: ACL2-PC||GENERALIZE,  Prev: ACL2-PC||FREE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||GENEQV    (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 E of the
union of those relations, such that it suffices to maintain E at the
current subterm: if that subterm, u, is replaced in the goal's
conclusion, G, by another term equivalent to u with respect to E, then
the resulting conclusion is Boolean equivalent to G.  Also see *note
DEFCONG::.

The command `geneqv' prints the above list of equivalence relations, or
more precisely, the list of function symbols for those relations.  If
however geneqv is given a non-nil argument, then a list is printed whose
elements are each of the form (s r), where s is the symbol for an
equivalence relation and r is a :congruence rune justifying the
inclusion of s in the list of equivalence relations being maintained at
the current subterm.


File: acl2-doc-emacs.info,  Node: ACL2-PC||GENERALIZE,  Next: ACL2-PC||GOALS,  Prev: ACL2-PC||GENEQV,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||GENERALIZE    (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 (term variable), where term 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 nil or a number, which causes the system
to generate a new name of the form _ or _n, with n a natural number;
more on this below.  However, when a variable is supplied, it must not
occur in any goal of the current proof-checker state.

When the "variable" above is nil, the system will treat it as the
variable |_| if that variable does not occur in any goal of the current
proof-checker state.  Otherwise it treats it as |_0|, or |_1|, or |_2|,
and so on, until one of these is not among the variables of the current
proof-checker state.  If the "variable" is a non-negative integer n,
then the system treats it as |_n| unless that variable already occurs
among the current goals, in which case it increments n just as above
until it obtains a new variable.

*Remark:*  The same variable may not occur as the variable component of
two different arguments (though nil may occur arbitrarily many times,
as may a positive integer).


File: acl2-doc-emacs.info,  Node: ACL2-PC||GOALS,  Next: ACL2-PC||HELP,  Prev: ACL2-PC||GENERALIZE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||GOALS    (macro)
list the names of goals on the stack

     Example and General Form:
     goals

Goals 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 change-goal
instruction.


File: acl2-doc-emacs.info,  Node: ACL2-PC||HELP,  Next: ACL2-PC||HELP!,  Prev: ACL2-PC||GOALS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||HELP    (macro)
proof-checker help facility

     Examples:

     (help all)     -- list all proof-checker commands
     (help rewrite) -- partial documentation on the rewrite command; the
                       rest is available using more or more!

     (help! rewrite) -- full documentation on the rewrite command

     help, help!     -- this documentation (in part, or in totality,
                        respectively)

     General Forms:
     (help &optional command)
     (help! &optional command)
     more
     more!

The proof checker supports the same kind of documentation as does ACL2
proper.  The main difference is that you need to type

     (help command)

in a list rather than :doc command.  So, to get all the documentation
on command, type (help! command) inside the interactive loop, but to
get only a one-line description of the command together with some
examples, type (help command).  In the latter case, you can get the
rest of the help by typing more!; or type more if you don't necessarily
want all the rest of the help at once.  (Then keep typing more if you
want to keep getting more of the help for that command.)

An exception is (help all), which prints the documentation topic
proof-checker-commands, to show you all possible proof-checker commands.
So for example, when you see ACL2-PC::USE in that list, you can then
submit (help use) or (help! use) to get documentation for the
proof-checker use command.

But summarizing for other than the case of all:  as with ACL2, you can
type either of the following:

     more, more!
     -- to obtain more (or, all the rest of) the documentation last
        requested by help (or, outside the proof-checker's loop, :doc)

It has been arranged that the use of (help command) will tell you just
about everything you could want to know about command, almost always by
way of examples.  For more details about a command, use help!, more, or
more!.

We use the word "command" to refer to the name itself, e.g.  rewrite.
We use the word "instruction" to refer to an input to the interactive
system, e.g. (rewrite foo) or (help split).  Of course, we allow
commands with no arguments as instructions in many cases, e.g. rewrite.
In such cases, command is treated identically to (command).


File: acl2-doc-emacs.info,  Node: ACL2-PC||HELP!,  Next: ACL2-PC||HELP-LONG,  Prev: ACL2-PC||HELP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||HELP!    (macro)
proof-checker help facility

Same as help, except that the entire help message is printed without
any need to invoke more! or more.

Invoke help for documentation about the proof-checker help facility.


File: acl2-doc-emacs.info,  Node: ACL2-PC||HELP-LONG,  Next: ACL2-PC||HYPS,  Prev: ACL2-PC||HELP!,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||HELP-LONG    (macro)
same as help!

See the documentation for help!.

Help-long has been included in addition to help! for historical
reasons.  (Such a command is included in Pc-Nqthm).


File: acl2-doc-emacs.info,  Node: ACL2-PC||HYPS,  Next: ACL2-PC||ILLEGAL,  Prev: ACL2-PC||HELP-LONG,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||HYPS    (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, hyps-indices and govs-indices
should be lists of indices of hypotheses and governors (respectively),
except that the atom t 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 <term,
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
nil, then there are no governors, i.e., the list of governors is nil.
If the term is of the form (if x y z) and the address is of the form (2
. rest) or (3 . rest), then the list of governors is the result of
consing x or its negation (respectively) onto the list of governors for
the pair <y, rest> or the pair <z, rest> (respectively).  If the term
is of the form (implies x y) and the address is of the form (2 . rest),
then the list of governors is the result of consing x onto the list of
governors for the pair <y, rest>.  Otherwise, the list of governors for
the pair <term, (n .  rest)> is exactly the list of governors for the
pair <argn, rest> where argn is the nth argument of term.

If all goals have been proved, a message saying so will be printed.
(as there will be no current hypotheses or governors!).

The hyps command never causes an error.  It "succeeds" (in fact its
value is t) if the arguments (when supplied) are appropriate, i.e.
either t or lists of indices of hypotheses or governors, respectively.
Otherwise it "fails" (its value is nil).


File: acl2-doc-emacs.info,  Node: ACL2-PC||ILLEGAL,  Next: ACL2-PC||IN-THEORY,  Prev: ACL2-PC||HYPS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||ILLEGAL    (macro)
illegal instruction

     Example:
     (illegal -3)

     General Form:
     (illegal instruction)

Probably not of interest to most users; always "fails" since it expands
to the fail command.

The illegal command is used mainly in the implementation.  For example,
the instruction 0 is "read" as (illegal 0), since dive expects positive
integers.


File: acl2-doc-emacs.info,  Node: ACL2-PC||IN-THEORY,  Next: ACL2-PC||INDUCT,  Prev: ACL2-PC||ILLEGAL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||IN-THEORY    (primitive)
set the current proof-checker 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
proof-checker 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-checker theory is set to the
value of that theory expression.

The current proof-checker theory is used in all calls to the ACL2
theorem prover and rewriter from inside the proof-checker.  Thus, the
most recent in-theory instruction in the current state-stack has an
effect in the proof-checker totally analogous to the effect caused by
an in-theory hint or event in ACL2.  All in-theory instructions before
the last are ignored, because they refer to the current theory in the
ACL2 state, not to the existing proof-checker 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 (in-theory (enable bar)) modifies the current theory of the current
ACL2 world.  So for example, suppose that foo is disabled outside the
proof checker and you execute the following instructions, in this order.

        (in-theory (enable foo))
        (in-theory (enable bar))

Then after the second of these, bar will be enabled in the
proof-checker, but foo will be disabled.  The reason is that (in-theory
(enable bar)) instructs the proof-checker to modify the current theory
(from outside the proof-checker, not from inside the proof-checker) by
enabling bar.

Note that in-theory instructions in the proof-checker have no effect
outside the proof-checker's interactive loop.

If the most recent in-theory instruction in the current state of the
proof-checker has no arguments, or if there is no in-theory instruction
in the current state of the proof-checker, then the proof-checker 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 in-theory instruction in the
current state of the proof-checker had an argument, then global changes
to the current theory will have no effect on the proof-checker state.


File: acl2-doc-emacs.info,  Node: ACL2-PC||INDUCT,  Next: ACL2-PC||LEMMAS-USED,  Prev: ACL2-PC||IN-THEORY,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||INDUCT    (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 :induct hint given to the theorem
prover, creating new subgoals for the base and induction steps.  If
term is t or is not supplied, then use the current goal to determine
the induction scheme; otherwise, use that term.

*Remark:*  As usual, abbreviations are allowed in the term.

*Remark:*  Induct actually calls the prove command with all processes
turned off.  Thus, you must be at top of the goal for an induct
instruction.


File: acl2-doc-emacs.info,  Node: ACL2-PC||LEMMAS-USED,  Next: ACL2-PC||LISP,  Prev: ACL2-PC||INDUCT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||LEMMAS-USED    (macro)
print the runes (definitions, lemmas, ...) used

This is just an alias for runes.


File: acl2-doc-emacs.info,  Node: ACL2-PC||LISP,  Next: ACL2-PC||MORE,  Prev: ACL2-PC||LEMMAS-USED,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||LISP    (meta)
evaluate the given form in Lisp

     Example:
     (lisp (assign xxx 3))

     General Form:
     (lisp form)

Evaluate form.  The lisp command is mainly of interest for side
effects.  See also print, skip, and fail.

The rest of the documentation for lisp is of interest only to those who
use it in macro commands.  If the Lisp evaluation (by trans-eval) of
form returns an error triple (see *note ERROR-TRIPLES::) of the form
(mv erp ((NIL NIL STATE) . (erp-1 val-1 &)) state), then the lisp
command returns the appropriate error triple

     (mv (or erp erp-1)
         val-1
         state) .

Otherwise, the trans-eval of form must return an error triple of the
form (mv erp (cons stobjs-out val) &), and the lisp 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 lisp command.
Trans-eval, which is undocumented except by comments in the ACL2 source
code, has replaced, in val, any occurrence of the current state or the
current values of stobjs by simple symbols such as REPLACED-STATE.  The
actual values of these objects may be recovered, in principle, from the
state returned and the user-stobj-alist within that state.  However, in
practice, the stobjs cannot be recovered because the user is denied
access to user-stobj-alist.  The moral is: do not try to write macro
commands that manipulate stobjs.  Should the returned val contain
REPLACED-STATE the value may simply be ignored and state used, since
that is what REPLACED-STATE denotes.


File: acl2-doc-emacs.info,  Node: ACL2-PC||MORE,  Next: ACL2-PC||MORE!,  Prev: ACL2-PC||LISP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||MORE    (macro)
proof-checker help facility

Continues documentation of last proof-checker command visited with help.

Invoke help for documentation about the proof-checker help facility.


File: acl2-doc-emacs.info,  Node: ACL2-PC||MORE!,  Next: ACL2-PC||NEGATE,  Prev: ACL2-PC||MORE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||MORE!    (macro)
proof-checker help facility

Continues documentation of last proof-checker command visited with
help, until all documentation on that command is printed out.

Invoke help for documentation about the proof-checker help facility.


File: acl2-doc-emacs.info,  Node: ACL2-PC||NEGATE,  Next: ACL2-PC||NIL,  Prev: ACL2-PC||MORE!,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||NEGATE    (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 do-all, and
"succeed" if and only if they "fail".

*Remark:*  Negate instructions will never produce hard "failures".


File: acl2-doc-emacs.info,  Node: ACL2-PC||NIL,  Next: ACL2-PC||NOISE,  Prev: ACL2-PC||NEGATE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||NIL    (macro)
used for interpreting control-d

     Example and General form:
     nil

(or, control-d).

The whole point of this command is that in some Lisps (including akcl),
if you type control-d then it seems, on occasion, to get interpreted as
nil.  Without this command, one seems to get into an infinite loop.


File: acl2-doc-emacs.info,  Node: ACL2-PC||NOISE,  Next: ACL2-PC||NX,  Prev: ACL2-PC||NIL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||NOISE    (meta)
run instructions with output

     Example:
     (noise induct prove)

     General Form:
     (noise &rest instruction-list)

Run the instruction-list through the top-level loop with output.

In fact, having output is the default.  Noise is useful inside a
surrounding call of quiet, when one temporarily wants output.  For
example, if one wants to see output for a prove command immediately
following an induct command but before an s command, one may want to
submit an instruction like (quiet induct (noise prove) s).  See also
quiet.


File: acl2-doc-emacs.info,  Node: ACL2-PC||NX,  Next: ACL2-PC||ORELSE,  Prev: ACL2-PC||NOISE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||NX    (atomic macro)
move forward one argument in the enclosing term

     Example and General Form:
     nx

For example, if the conclusion is (= x (* (- y) z)) and the current
subterm is x, then after executing nx, the current subterm will be (*
(- y) z).

This is the same as up followed by (dive n+1), where n is the position
of the current subterm in its parent term in the conclusion.  Thus in
particular, the nx command fails if one is already at the top of the
conclusion.

See also up, dive, top, and bk.


File: acl2-doc-emacs.info,  Node: ACL2-PC||ORELSE,  Next: ACL2-PC||P,  Prev: ACL2-PC||NX,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||ORELSE    (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 instr1 "succeeds", or
else instr2 "succeeds".  If it "fails", then the failure is soft.


File: acl2-doc-emacs.info,  Node: ACL2-PC||P,  Next: ACL2-PC||P-TOP,  Prev: ACL2-PC||ORELSE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||P    (macro)
prettyprint the current term

     Example and General Form:
     p

Prettyprint the current term.  The usual user syntax is used, so that
for example one would see (and x y) rather than (if x y 'nil).  (See
also pp.)  Also, abbreviations are inserted where appropriate; see
add-abbreviation.

The "current term" is the entire conclusion unless dive 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 term!).


File: acl2-doc-emacs.info,  Node: ACL2-PC||P-TOP,  Next: ACL2-PC||PL,  Prev: ACL2-PC||P,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||P-TOP    (macro)
prettyprint the conclusion, highlighting the current term

     Example and General Form:
     p-top

For example, if the conclusion is (equal (and x (p y)) (foo z)) and the
current subterm is (p y), then p-top will print (equal (and x (*** (p
y) ***)) (foo z)).

Prettyprint the the conclusion, highlighting the current term.  The
usual user syntax is used, as with the command p (as opposed to pp).
This is illustrated in the example above, where one would *not* see
(equal (if x (*** (p y) ***) 'nil) (foo z)).

*Remark* (obscure): In some situations, a term of the form (if x t y)
occurring inside the current subterm will not print as (or x y), when x
isn't a call of a boolean primitive.  There's nothing incorrect about
this, however.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PL,  Next: ACL2-PC||PP,  Prev: ACL2-PC||P-TOP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PL    (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 *note PL::.  If no argument is given, or if the argument
is nil, 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 show-rewrites (or equivalently, sr) command.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PP,  Next: ACL2-PC||PR,  Prev: ACL2-PC||PL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PP    (macro)
prettyprint the current term

     Example and General Form:
     pp

This is the same as p (see its documentation), except that raw syntax
(internal form) is used.  So for example, one would see (if x y 'nil)
rather than (and x y).  Abbreviations are however still inserted, as
with p.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PR,  Next: ACL2-PC||PRINT,  Prev: ACL2-PC||PP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PR    (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 *note PR::.  If no argument is given, or if the argument
is nil, 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 show-rewrites (or equivalently, sr) command.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PRINT,  Next: ACL2-PC||PRINT-ALL-CONCS,  Prev: ACL2-PC||PR,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PRINT    (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 form
should return a single value that is not state or a single-threaded
object (see *note STOBJ::).  The optional second argument causes
printing to be done without elision (so-called "evisceration"; see
*note EVISC-TUPLE::).

If the form you want to evaluate does not satisfy the criterion above,
you should create an appropriate call of the lisp command instead.
Notice that this command always returns (mv nil nil state) where the
second result will always be REPLACED-STATE.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PRINT-ALL-CONCS,  Next: ACL2-PC||PRINT-ALL-GOALS,  Prev: ACL2-PC||PRINT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PRINT-ALL-CONCS    (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.  See also the proof-checker command print-all-goals.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PRINT-ALL-GOALS,  Next: ACL2-PC||PRINT-MAIN,  Prev: ACL2-PC||PRINT-ALL-CONCS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PRINT-ALL-GOALS    (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.
See also the proof-checker command print-all-concs.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PRINT-MAIN,  Next: ACL2-PC||PRO,  Prev: ACL2-PC||PRINT-ALL-GOALS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PRINT-MAIN    (macro)
print the original goal

     Example and General Form:
     print-main

Print the goal as originally entered.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PRO,  Next: ACL2-PC||PROMOTE,  Prev: ACL2-PC||PRINT-MAIN,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PRO    (atomic macro)
repeatedly apply promote

     Example and General Form:
     pro

Apply the promote command until there is no change.  This command
"succeeds" exactly when at least one call of promote "succeeds".  In
that case, only a single new proof-checker state will be created.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PROMOTE,  Next: ACL2-PC||PROTECT,  Prev: ACL2-PC||PRO,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PROMOTE    (primitive)
move antecedents of conclusion's implies term to top-level
hypotheses

     Examples:
     promote
     (promote t)

For example, if the conclusion is (implies (and x y) z), then after
execution of promote, the conclusion will be z and the terms x and y
will be new top-level hypotheses.

     General Form:
     (promote &optional do-not-flatten-flag)

Replace conclusion of (implies hyps exp) or (if hyps exp t) with simply
exp, adding hyps to the list of top-level hypotheses.  Moreover, if
hyps is viewed as a conjunction then each conjunct will be added as a
separate top-level hypothesis.  An exception is that if
do-not-flatten-flag is supplied and not nil, then only one top-level
hypothesis will be added, namely hyps.

*Remark*:  You must be at the top of the conclusion in order to use this
command.  Otherwise, first invoke top.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PROTECT,  Next: ACL2-PC||PROVE,  Prev: ACL2-PC||PROMOTE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PROTECT    (macro)
run the given instructions, reverting to existing state upon
failure

     Example:
     (protect induct p prove)

     General Form:
     (protect &rest instruction-list)

Protect is the same as do-strict, except that as soon as an instruction
"fails", the state-stack reverts to what it was before the protect
instruction began, and restore is given the same meaning that it had
before the protect instruction began.  See the documentation for
do-strict.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PROVE,  Next: ACL2-PC||PSO,  Prev: ACL2-PC||PROTECT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PROVE    (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 rest-args is as in the keyword
arguments to defthm except that only :hints and :otf-flg are allowed.
The command succeeds exactly when the corresponding defthm 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 *note
HINTS:: for an explanation of :by hints.)

*Remark:*  Use (= t) 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 (implies hyps
conc), where hyps is the conjunction of the top-level hypotheses and
conc is the goal's conclusion.

*Remark:*  It is allowed to use abbreviations in the hints.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PSO,  Next: ACL2-PC||PSO!,  Prev: ACL2-PC||PROVE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PSO    (macro)
print the most recent proof attempt from inside the proof-checker

     Example and General Form:
     pso

Print the most recent proof attempt from inside the proof-checker
assuming you are in gag-mode or have saved output (see *note
SET-SAVED-OUTPUT::).  This includes all calls to the prover, including
for example proof-checker commands induct, split, and bash, in addition
to prove.  So for example, you can follow (quiet prove) with pso to see
the proof, including proof-tree output, if it failed.

See also documentation for related proof-checker commands psog and pso!.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PSO!,  Next: ACL2-PC||PSOG,  Prev: ACL2-PC||PSO,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PSO!    (macro)
print the most recent proof attempt from inside the proof-checker

     Example and General Form:
     pso!

Print the most recent proof attempt from inside the proof-checker,
including proof-tree output, assuming you are in gag-mode or have saved
output (see *note SET-SAVED-OUTPUT::).  This includes all calls to the
prover, including for example proof-checker commands induct, split, and
bash, in addition to prove.  So for example, you can follow (quiet
prove) with pso! to see the proof, including proof-tree output, if it
failed.

See also documentation for related proof-checker commands pso and psog.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PSOG,  Next: ACL2-PC||PUT,  Prev: ACL2-PC||PSO!,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PSOG    (macro)
print the most recent proof attempt from inside the proof-checker

     Example and General Form:
     psog

Print the most recent proof attempt from inside the proof-checker,
including goal names, assuming you are in gag-mode or have saved output
(see *note SET-SAVED-OUTPUT::).  This includes all calls to the prover,
including for example proof-checker commands induct, split, and bash,
in addition to prove.  So for example, you can follow (quiet prove)
with psog to see the proof, including proof-tree output, if it failed.

See also documentation for related proof-checker commands pso and pso!.


File: acl2-doc-emacs.info,  Node: ACL2-PC||PUT,  Next: ACL2-PC||QUIET,  Prev: ACL2-PC||PSOG,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||PUT    (macro)
substitute for a "free variable"

     Example:
     (put x 17)

     General Form:
     (put var expr)

Substitute expr for the "free variable" var, as explained below.

A "free variable" is, for our purposes, a variable var such that the
instruction (free var) has been executed earlier in the state-stack.
What (free var) really does is to let var be an abbreviation for the
term (hide var) (see documentation for add-abbreviation).  What (put
var expr) really does is to unwind the state-stack, replacing that free
instruction with the instruction (add-abbreviation var expr), so that
future references to (? var) become reference to expr rather than to
(hide var), and then to replay all the other instructions that were
unwound.  Because hide was used, the expectation is that in most cases,
the instructions will replay successfully and put 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 put instruction was executed.

If (put var expr) "succeeds", then (remove-abbreviation var) will be
executed at the end.

*Remark*:  The restore command will revert the state-stack to its value
present before the put instruction was executed.


File: acl2-doc-emacs.info,  Node: ACL2-PC||QUIET,  Next: ACL2-PC||R,  Prev: ACL2-PC||PUT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||QUIET    (meta)
run instructions without output

     Example:
     (quiet induct prove)

     General Form:
     (quiet &rest instruction-list)

Run the instruction-list through the top-level loop with no output.

See also noise.


File: acl2-doc-emacs.info,  Node: ACL2-PC||R,  Next: ACL2-PC||REDUCE,  Prev: ACL2-PC||QUIET,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||R    (macro)
same as rewrite

     Example:
     (r 3)

See the documentation for rewrite, as r and rewrite are identical.


File: acl2-doc-emacs.info,  Node: ACL2-PC||REDUCE,  Next: ACL2-PC||REDUCE-BY-INDUCTION,  Prev: ACL2-PC||R,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||REDUCE    (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 prove, the arguments to reduce are spread out, and
are all hints.

Reduce is similar to bash in that neither of these allows induction.
But bash only allows simplification, while reduce allows processes
eliminate-destructors, fertilize, generalize, and eliminate-irrelevance.

*Remark:*  Induction will be used to the extent that it is ordered
explicitly in the hints.


File: acl2-doc-emacs.info,  Node: ACL2-PC||REDUCE-BY-INDUCTION,  Next: ACL2-PC||REMOVE-ABBREVIATIONS,  Prev: ACL2-PC||REDUCE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||REDUCE-BY-INDUCTION    (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 prove, the arguments to reduce-by-induction are
spread out, and are all hints.  See also prove, reduce, and bash.

*Remark*:  Induction and the various processes will be used to the
extent that they are ordered explicitly in the :induct and :do-not
hints.


File: acl2-doc-emacs.info,  Node: ACL2-PC||REMOVE-ABBREVIATIONS,  Next: ACL2-PC||REPEAT,  Prev: ACL2-PC||REDUCE-BY-INDUCTION,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||REMOVE-ABBREVIATIONS    (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 nil), remove the variables in vars from
the current list of abbreviations, in the sense that each variable in
vars will no longer abbreviate a term.

*Remark:*  The instruction fails if at least one of the arguments fails
to be a variable that abbreviates a term.

See also the documentation for add-abbreviation, which contains a
discussion of abbreviations in general, and show-abbreviations.


File: acl2-doc-emacs.info,  Node: ACL2-PC||REPEAT,  Next: ACL2-PC||REPEAT-REC,  Prev: ACL2-PC||REMOVE-ABBREVIATIONS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||REPEAT    (macro)
repeat the given instruction until it "fails"

     Example:
     (repeat promote)

     General Form:
     (repeat instruction)

The given instruction is run repeatedly until it "fails".

*Remark:*  There is nothing here in general to prevent the instruction
from being run after all goals have been proved, though this is indeed
the case for primitive instructions.


File: acl2-doc-emacs.info,  Node: ACL2-PC||REPEAT-REC,  Next: ACL2-PC||REPLAY,  Prev: ACL2-PC||REPEAT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||REPEAT-REC    (macro)
auxiliary to repeat

See documentation for repeat.


File: acl2-doc-emacs.info,  Node: ACL2-PC||REPLAY,  Next: ACL2-PC||RESTORE,  Prev: ACL2-PC||REPEAT-REC,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||REPLAY    (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 n instructions if n is a positive integer; else n
should be nil or not supplied, and replay all instructions.  However,
if replacement-instruction is supplied and not nil, then before the
replay, replace the nth instruction (from the most recent, as shown by
commands) with replacement-instruction.

If this command "fails", then the restore command will revert the
state-stack to its value present before the replay instruction was
executed.


File: acl2-doc-emacs.info,  Node: ACL2-PC||RESTORE,  Next: ACL2-PC||RETAIN,  Prev: ACL2-PC||REPLAY,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||RESTORE    (meta)
remove the effect of an UNDO command

     Example and General Form:
     restore

Restore removes the effect of an undo command.  This always works as
expected if restore is invoked immediately after undo, without
intervening instructions.  However, other commands may also interact
with restore, notably "sequencing" commands such as do-all, do-strict,
protect, and more generally, sequence.

*Remark:*  Another way to control the saving of proof-checker state is
with the save command; see the documentation for save.

The restore command always "succeeds"; it returns (mv nil t state).


File: acl2-doc-emacs.info,  Node: ACL2-PC||RETAIN,  Next: ACL2-PC||RETRIEVE,  Prev: ACL2-PC||RESTORE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||RETAIN    (atomic macro)
drop all *but* 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 *except* 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).


File: acl2-doc-emacs.info,  Node: ACL2-PC||RETRIEVE,  Next: ACL2-PC||REWRITE,  Prev: ACL2-PC||RETAIN,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||RETRIEVE    (macro)
re-enter the proof-checker

     Examples:
     (retrieve associativity-of-permutationp)
     retrieve

     General Form:
     (retrieve &optional name)

Must be used from outside the interactive proof-checker loop.  If name
is supplied and not nil, this causes re-entry to the interactive
proof-checker loop in the state at which save was last executed for the
indicated name.  (See documentation for save.)  If name is nil or is
not supplied, then the user is queried regarding which proof-checker
state to re-enter.  The query is omitted, however, if there only one
proof-checker state is present that was saved with save, in which case
that is the one that is used.  See also unsave.


File: acl2-doc-emacs.info,  Node: ACL2-PC||REWRITE,  Next: ACL2-PC||RUN-INSTR-ON-GOAL,  Prev: ACL2-PC||RETRIEVE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||REWRITE    (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 show-rewrites (sr) command.

See also the linear command, for an analogous command to use with
linear rules.

If rule-id is a positive integer n, then the nth rule as displayed by
show-rewrites is the one that is applied.  If rule-id is nil or is not
supplied, then it is treated as the number 1.  Otherwise, rule-id
should be either a symbol or else a :rewrite or :definition rune.  If a
symbol is supplied, then any (:rewrite or :definition) 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 (reverse (reverse y)) and that there is a rewrite rule called
reverse-reverse of the form

     (implies (true-listp x)
              (equal (reverse (reverse x)) x)) .

Then the instruction (rewrite reverse-reverse) causes the current
subterm to be replaced by y and creates a new goal with conclusion
(true-listp y).  An exception is that if the top-level hypotheses imply
(true-listp y) using only "trivial reasoning" (more on this below),
then no new goal is created.

If the rule-id argument is a number or is not supplied, then the system
will store an instruction of the form (rewrite name ...), where name 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
(:rewrite name . index), where index is not nil.)

Speaking in general, then, a rewrite instruction works as follows:

First, a rewrite or definition rule is selected according to the
arguments of the rewrite 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 unify-subst is found such that if one
instantiates the left-hand side of the rule with unify-subst, 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 unify-subst is extended with the
substitution argument, which may bind free variables (see *note
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 the documentation for the proof-checker hyps command under
proof-checker-commands), much as would be done by the theorem prover's
rewriter.

If in the process above there are free variables (see *note
FREE-VARIABLES::), but the proof-checker can see how to bind them to
relieve all hypotheses, then it will do so in both the show-rewrites
(sr) and rewrite commands.  But normally, if even one hypothesis
remains unrelieved, then no automatic extension of the substitution is
made.  Except, if instantiate-free is not nil, then that extension to
the substitution is kept.  (Technical note: in the case of an
unrelieved hypothesis and a non-nil value of instantiate-free, if a
bind-free 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.

*Remark:*  The substitution argument should be a list whose elements
have the form (variable term), where term may contain abbreviations.


File: acl2-doc-emacs.info,  Node: ACL2-PC||RUN-INSTR-ON-GOAL,  Next: ACL2-PC||RUN-INSTR-ON-NEW-GOALS,  Prev: ACL2-PC||REWRITE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||RUN-INSTR-ON-GOAL    (macro)
auxiliary to THEN

See documentation for then.


File: acl2-doc-emacs.info,  Node: ACL2-PC||RUN-INSTR-ON-NEW-GOALS,  Next: ACL2-PC||RUNES,  Prev: ACL2-PC||RUN-INSTR-ON-GOAL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||RUN-INSTR-ON-NEW-GOALS    (macro)
auxiliary to then

See documentation for then.


File: acl2-doc-emacs.info,  Node: ACL2-PC||RUNES,  Next: ACL2-PC||S,  Prev: ACL2-PC||RUN-INSTR-ON-NEW-GOALS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||RUNES    (macro)
print the runes (definitions, lemmas, ...) used

     Examples and general forms:
     (runes t)   ; print all runes used during this interactive proof
     (runes nil) ; print all runes used by the most recent command
     (runes)     ; same as (runes nil)
     runes       ; same as (runes nil)

This command does not change the proof-checker state.  Rather, it
simply reports runes (see *note RUNE::) that have participated in the
interactive proof.

Note that (runes nil) will show the runes used by the most recent
primitive or macro command (as displayed by :comm).


File: acl2-doc-emacs.info,  Node: ACL2-PC||S,  Next: ACL2-PC||S-PROP,  Prev: ACL2-PC||RUNES,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||S    (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 first ``normalize'' it by pushing 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 normalize backchain-limit repeat in-theory hands-off
             expand)

Simplify the current subterm according to the keyword parameters
supplied.  First if-normalization is applied (unless the normalize
argument is nil), i.e., each subterm of the form (f ... (if test x y)
...)  is replaced by the term (if test (f ... x ...) (f ... y ...))
except, of course, when f is if and the indicated if subterm is in the
second or third argument position.  Then rewriting is applied (unless
the rewrite argument is nil).  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-nil, instructs the system to use ACL2's rewriter (or,
something close to it) during simplification.

     :normalize -- default t

When non-nil, instructs the system to use if-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-set reasoning is allowed) in the relieving
of hypotheses.  The value should be nil or a non-negative integer, and
limits backchaining only for rewriting, not for type-set reasoning.

     :repeat -- default 0

Sets the number of times the current term is to be rewritten.  If this
value is t, then the default is used (as specified by the constant
*default-s-repeat-limit*).

     :in-theory, :hands-off, :expand

These have their usual meaning; see *note HINTS::.

*Remark:*  if conditional rewrite rules are used that cause case splits
because of the use of force, 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.


File: acl2-doc-emacs.info,  Node: ACL2-PC||S-PROP,  Next: ACL2-PC||SAVE,  Prev: ACL2-PC||S,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||S-PROP    (atomic macro)
simplify propositionally

     Example:
     s-prop

     General Form:
     (s-prop &rest names)

Simplify, using the default settings for s (which include
if-normalization and rewriting without real backchaining), but with
respect to a theory in which only basic functions and rules (the ones in
(theory 'minimal-theory)), together with the names (or parenthesized
names) in the &rest argument names, are enabled.

See also the documentation for s.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SAVE,  Next: ACL2-PC||SEQUENCE,  Prev: ACL2-PC||S-PROP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SAVE    (macro)
save the proof-checker state (state-stack)

     Example:
     (save lemma3-attempt)

     General Form:
     (save &optional name do-it-flg)

Saves the current proof-checker state by "associating" it with the
given name.  Submit (retrieve name) to Lisp to get back to this
proof-checker state.  If verify was originally supplied with an event
name, then the argument can be omitted in favor of that name as the
default.

*Remark* that if a save 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 do-it-flg is supplied
and not nil, then there will be no query and the save will be effected.

See also the documentation for retrieve and unsave.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SEQUENCE,  Next: ACL2-PC||SHOW-ABBREVIATIONS,  Prev: ACL2-PC||SAVE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SEQUENCE    (meta)
run the given list of instructions according to a multitude of
options

     Example:
     (sequence (induct p prove) t)

See also the definitions of commands do-all, do-strict, protect, and
succeed.

     General Form:
     (sequence
      instruction-list
      &optional
      strict-flg protect-flg success-expr no-prompt-flg no-restore-flg)

Each instruction in the list instruction-list is run, and the
instruction "succeeds" if every instruction in instruction-list
"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".

*Remark:*  The arguments are *not* evaluated, except (in a sense) for
success-expr, as described below.

Each primitive and meta instruction can be thought of as returning an
error triple, say (erp val state); see *note ERROR-TRIPLES::.  An
instruction (primitive or meta) "succeeds" if erp is nil and val is not
nil; 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 that the failure is "soft" if
erp is nil; otherwise the failure is "hard".  The sequence 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 do-all, do-strict and protect.

Here is precisely what happens when a sequence instruction is run.  The
instruction interpreter is run on the instructions supplied in the
argument instruction-list (in order).  The interpreter halts the first
time there is a hard "failure." except that if strict-flg is supplied
and not nil, then the interpreter halts the first time there is any
"failure."  The error triple (erp val state) returned by the sequence
instruction is the triple returned by the last instruction executed
(or, the triple (nil t state) if instruction-list is nil), except for
the following provision.  If success-expr is supplied and not nil, then
it is evaluated with the state global variables pc-erp and pc-val (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 erp and
val in the triple finally returned by sequence.  For example, if
success-expr is (mv erp val), then no change will be made to the error
triple, and if instead it is (mv nil t), then the sequence instruction
will "succeed".

That concludes the description of the error triple returned by a
sequence instruction, but it remains to explain the effects of the
arguments protect-flg and no-prompt-flg.

If protect-flg is supplied and not nil and if also the instruction
"fails" (i.e., the error component of the triple is not nil or the
value component is nil), then the state is reverted so that the
proof-checker's state (including the behavior of restore) is set back
to what it was before the sequence instruction was executed.
Otherwise, unless no-restore-flg is set, the state is changed so that
the restore command will now undo the effect of this sequence
instruction (even if there were nested calls to sequence).

Finally, as each instruction in instruction-list is executed, the
prompt and that instruction will be printed, unless the global state
variable pc-print-prompt-and-instr-flg is unbound or nil and the
parameter no-prompt-flg is supplied and not nil.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SHOW-ABBREVIATIONS,  Next: ACL2-PC||SHOW-LINEARS,  Prev: ACL2-PC||SEQUENCE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SHOW-ABBREVIATIONS    (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

See also add-abbreviation and remove-abbreviations.  In particular, the
documentation for add-abbreviation contains a general discussion of
abbreviations.

     General Form:
     (show-abbreviations &rest vars)

Display each argument in vars together with the term it abbreviates (if
any).  If there are no arguments, i.e. the instruction is simply
show-abbreviations, then display all abbreviations together with the
terms they abbreviate.

If the term abbreviated by a variable, say v, contains a proper subterm
that is also abbreviate by (another) variable, then both the
unabbreviated term and the abbreviated term (but not using (? v) to
abbreviate the term) are displayed with together with v.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SHOW-LINEARS,  Next: ACL2-PC||SHOW-REWRITES,  Prev: ACL2-PC||SHOW-ABBREVIATIONS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SHOW-LINEARS    (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 show-rewrites proof-checker command; see its
documentation for details.  Also see the documentation for
proof-checker command apply-linear for how to apply linear rules.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SHOW-REWRITES,  Next: ACL2-PC||SHOW-TYPE-PRESCRIPTIONS,  Prev: ACL2-PC||SHOW-LINEARS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SHOW-REWRITES    (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 pl or pr command.

Here are details on the arguments and the output.  If rule-id is
supplied and is a name (non-nil symbol) or a :rewrite or :definition
rune, then only the corresponding rewrite rule(s) will be displayed,
while if rule-id is a positive integer n, then only the nth 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 enabled-only-flg is supplied and not nil,
then disabled rules will not be displayed at all.  Finally, among the
free variables of any rule (see *note FREE-VARIABLES::), those that
would remain free if the rule were applied will be displayed.  Also see
*note REWRITE::.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SHOW-TYPE-PRESCRIPTIONS,  Next: ACL2-PC||SKIP,  Prev: ACL2-PC||SHOW-REWRITES,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SHOW-TYPE-PRESCRIPTIONS    (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
rule-id is supplied and is a name (non-nil symbol) or a :rewrite or
:definition 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 *note
TYPE-PRESCRIPTION::.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SKIP,  Next: ACL2-PC||SL,  Prev: ACL2-PC||SHOW-TYPE-PRESCRIPTIONS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SKIP    (macro)
"succeed" without doing anything

     Example and General Form:
     skip

Make no change in the state-stack, but "succeed".  Same as (sequence
nil).


File: acl2-doc-emacs.info,  Node: ACL2-PC||SL,  Next: ACL2-PC||SLS,  Prev: ACL2-PC||SKIP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SL    (atomic macro)
simplify with lemmas

     Examples:
     sl
     (sl 3)

     General Form:
     (sl &optional backchain-limit)

Simplify, but with all function definitions disabled (see *note
FUNCTION-THEORY:: in the top-level ACL2 loop), except for a few basic
functions (the ones in (theory 'minimal-theory)).  The backchain-limit
has a default of 0, but if is supplied and not nil, then it should be a
nonnegative integer; see the documentation for s.

WARNING: This command completely ignores in-theory commands that are
executed inside the proof-checker.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SLS,  Next: ACL2-PC||SPLIT,  Prev: ACL2-PC||SL,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SLS    (macro)
same as SHOW-LINEARS

     Example:
     srs

     General Form:
     (srs &optional rule-id enabled-only-flg)

See the documentation for show-linears, as sls and show-linears are
identical.  NOTE: In analogy to the sr abbreviation for show-rewrites,
one might expect this command to be sl; but that name was taken
("simplify with lemmas") before sls was implemented.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SPLIT,  Next: ACL2-PC||SR,  Prev: ACL2-PC||SLS,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SPLIT    (atomic macro)
split the current goal into cases

     Example:
     split

For example, if the current goal has one hypothesis (or x y) and a
conclusion of (and a b), then split 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.

*Remark:*  The new goals will all have their hypotheses promoted; in
particular, no conclusion will have a top function symbol of implies.
Also note that split will fail if there is exactly one new goal created
and it is the same as the existing current goal.

The way split 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 (theory 'minimal-theory).  However, because the
prover is called, type-set reasoning can be used to eliminate some
cases.  For example, if (true-listp x) is in the hypotheses, then
probably (true-listp (cdr x)) will be reduced to t.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SR,  Next: ACL2-PC||ST,  Prev: ACL2-PC||SPLIT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SR    (macro)
same as SHOW-REWRITES

     Example:
     sr

     General Form:
     (sr &optional rule-id enabled-only-flg)

See the documentation for show-rewrites, as sr and show-rewrites are
identical.


File: acl2-doc-emacs.info,  Node: ACL2-PC||ST,  Next: ACL2-PC||SUCCEED,  Prev: ACL2-PC||SR,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||ST    (macro)
same as SHOW-TYPE-PRESCRIPTIONS

     Example:
     sr

     General Form:
     (st &optional rule-id)

See the documentation for show-type-prescriptions, as st and
show-type-prescriptions are identical.


File: acl2-doc-emacs.info,  Node: ACL2-PC||SUCCEED,  Next: ACL2-PC||TH,  Prev: ACL2-PC||ST,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||SUCCEED    (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 the documentation for sequence for an explanation of
"success" and "failure".)


File: acl2-doc-emacs.info,  Node: ACL2-PC||TH,  Next: ACL2-PC||THEN,  Prev: ACL2-PC||SUCCEED,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||TH    (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 hyps command; see its
documentation.

Historical note:  The name th is adapted from the Gypsy Verification
Environment, where th abbreviates the command theorem, which says to
print information on the current goal.


File: acl2-doc-emacs.info,  Node: ACL2-PC||THEN,  Next: ACL2-PC||TOP,  Prev: ACL2-PC||TH,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||THEN    (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 first-instruction, and then run completion (another instruction) on
each subgoal created by first-instruction.  If must-succeed-flg is
supplied and not nil, then halt at the first "failure" and remove the
effects of the invocation of completion that "failed".

The default for completion is reduce.


File: acl2-doc-emacs.info,  Node: ACL2-PC||TOP,  Next: ACL2-PC||TYPE-ALIST,  Prev: ACL2-PC||THEN,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||TOP    (atomic macro)
move to the top of the goal

     Example and General Form:
     top

For example, if the conclusion is (= x (* (- y) z)) and the current
subterm is y, then after executing top, the current subterm will be the
same as the conclusion, i.e., (= x (* (- y) z)).

Top is the same as (up n), where n is the number of times one needs to
execute up in order to get to the top of the conclusion.  The top
command fails if one is already at the top of the conclusion.

See also up, dive, nx, and bk.


File: acl2-doc-emacs.info,  Node: ACL2-PC||TYPE-ALIST,  Next: ACL2-PC||UNDO,  Prev: ACL2-PC||TOP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||TYPE-ALIST    (macro)
display the type-alist from the current context

     Examples:
     (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) ; display type-alist without considering
                          ; conclusion or governors

     General Form:
     (type-alist &optional concl-flg govs-flg fc-report-flg)

where if govs-flg is omitted then it defaults to (not concl-flg), and
concl-flg and fc-report-flg default to nil.

Display the current assumptions as a type-alist.  Note that this display
includes the result of forward chaining.  When fc-report-flg is supplied
a non-nil 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 *note FORWARD-CHAINING-REPORTS::).

There are two basic reasons contemplated for using this command.

1. The theorem prover has failed (either outside the proof-checker or
using a proof-checker command such as bash or reduce 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 if-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:
     (type-alist nil t) ; equivalently, type-alist or (type-alist nil)

     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:
     (type-alist t nil) ; equivalently, (type-alist t)

2. You intend to use one of the proof-checker-commands that does
simplification, such as s or x, and you want to see the context.  Then
include the surrounding if-term governors but not the goal's
conclusion.  Command:
(type-alist nil t) ; equivalently, type-alist or (type-alist nil)

See *note TYPE-SET:: (also see *note TYPE-PRESCRIPTION::) for
information about ACL2's type system, which can assist in understanding
the output of the type-alist command.


File: acl2-doc-emacs.info,  Node: ACL2-PC||UNDO,  Next: ACL2-PC||UNSAVE,  Prev: ACL2-PC||TYPE-ALIST,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||UNDO    (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).

*Remark:*  To remove the effect of an undo command, use restore.  See
the documentation for details.

*Remark:*  If the argument n is greater than the total number of
interactive instructions in the current session, then (undo n) will
simply take you back to the start of the session.

The undo meta command always "succeeds"; it returns (mv nil t state)
unless its optional argument is supplied and of the wrong type (i.e.
not a positive integer) or there are no instructions to undo.


File: acl2-doc-emacs.info,  Node: ACL2-PC||UNSAVE,  Next: ACL2-PC||UP,  Prev: ACL2-PC||UNDO,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||UNSAVE    (macro)
remove a proof-checker state

     Example:
     (unsave assoc-of-append)

     General Form:
     (unsave &optional name)

Eliminates the association of a proof-checker state with name, if name
is supplied and not nil.  The name may be nil or not supplied, in which
case it defaults to the event name supplied with the original call to
verify (if there is one -- otherwise, the instruction "fails" and there
is no change).  The ACL2 function unsave may also be executed outside
the interactive loop, with the same syntax.

See also documentation for save and retrieve.


File: acl2-doc-emacs.info,  Node: ACL2-PC||UP,  Next: ACL2-PC||USE,  Prev: ACL2-PC||UNSAVE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||UP    (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 n levels in the conclusion from the current subterm, where n is
a positive integer.  If n is not supplied or is nil, then move up 1
level, i.e., treat the instruction as (up 1).

See also dive, top, nx, and bk.


File: acl2-doc-emacs.info,  Node: ACL2-PC||USE,  Next: ACL2-PC||WRAP,  Prev: ACL2-PC||UP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||USE    (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
*note HINTS:: for the syntax of :use hints in defthm, which is
essentially the same as the syntax here (see the example above).

This command calls the prove command, and hence should only be used at
the top of the conclusion.


File: acl2-doc-emacs.info,  Node: ACL2-PC||WRAP,  Next: ACL2-PC||WRAP-INDUCT,  Prev: ACL2-PC||USE,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||WRAP    (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 instrs are executed, as in do-all.  If this
"fails" then no additional action is taken.  Otherwise, the current goal
after execution of instrs is conjoined with all "new" goals, in the
sense that their names are not among the names of goals at the time
instrs was begun.  This conjunction becomes the new current goal and
those "new" goals are dropped.

See the code for the proof-checker command wrap-induct for an example
of the use of wrap.


File: acl2-doc-emacs.info,  Node: ACL2-PC||WRAP-INDUCT,  Next: ACL2-PC||WRAP1,  Prev: ACL2-PC||WRAP,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||WRAP-INDUCT    (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 wrap-induct command is identical to the proof-checker induct
command, 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, wrap-induct 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)


File: acl2-doc-emacs.info,  Node: ACL2-PC||WRAP1,  Next: ACL2-PC||X,  Prev: ACL2-PC||WRAP-INDUCT,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||WRAP1    (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 kept-goal-names is not nil, the current goal is replaced by
conjoining it with all goals other than the current goal and those
indicated by kept-goal-names, and those other goals are deleted.  If
kept-goal-names is omitted, then the the current goal must be of the
form (name . n), and the goals to conjoin into the current goal (and
delete) are those with names of the form (name . k) for k >= n.

NOTE: Wrap1 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 top and demote had been executed, if necessary).

Also see proof-checker documentation for wrap (see *note
PROOF-CHECKER-COMMANDS::).


File: acl2-doc-emacs.info,  Node: ACL2-PC||X,  Next: ACL2-PC||X-DUMB,  Prev: ACL2-PC||WRAP1,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||X    (atomic macro)
expand and (maybe) simplify function call at the current subterm

     Examples:
     x --  expand and simplify.

For example, if the current subterm is (append a b), then after x the
current subterm will probably be (cons (car a) (append (cdr a) b)) if
(consp a) and (true-listp a) are among the top-level hypotheses and
governors.  If there are no top-level hypotheses and governors, then
after x the current subterm will probably be:

     (if (true-listp x)
         (if x
             (cons (car x) (append (cdr x) y))
           y)
       (apply 'binary-append (list x y))).

     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 s command (see documentation for s).

Unlike s, it is permitted to set both :rewrite and :normalize to nil,
which will result in no simplification; see x-dumb.

*Remark* (obscure):  On rare occasions the current address may be
affected by the use of x.  For example, suppose we have the definition

     (defun g (x) (if (consp x) x 3))

and then we enter the proof-checker with

     (verify (if (integerp x) (equal (g x) 3) t)) .

Then after invoking the instruction (dive 2 1), so that the current
subterm is (g x), followed by the instruction x, we would expect the
conclusion to be (if (integerp x) (equal 3 3) t).  However, the system
actually replaces (equal 3 3) with t (because we use the ACL2
term-forming primitives), and hence the conclusion is actually (if
(integerp x) t t).  Therefore, the current address is put at (2) rather
than (2 1).  In such cases, a warning "NOTE" will be printed to the
terminal.

The other primitive commands to which the above "truncation" note
applies are equiv, rewrite, and s.


File: acl2-doc-emacs.info,  Node: ACL2-PC||X-DUMB,  Prev: ACL2-PC||X,  Up: PROOF-CHECKER-COMMANDS

ACL2-PC||X-DUMB    (atomic macro)
expand function call at the current subterm, without simplifying

     General Form:
     x-dumb:  expand without simplification.

Same as (expand t new-goals-flg keep-all-guards-flg).  See
documentation for expand.

See also x, which allows simplification.


File: acl2-doc-emacs.info,  Node: RETRIEVE,  Next: TOGGLE-PC-MACRO,  Prev: PROOF-CHECKER-COMMANDS,  Up: PROOF-CHECKER

RETRIEVE    re-enter a (specified) proof-checker state

     Examples:
     (retrieve associativity-of-permutationp)
     retrieve

     General Form:
     (retrieve &optional name)

See *note ACL2-PC||RETRIEVE::, or use (help retrieve) inside the
interactive proof-checker loop.  Also see *note UNSAVE::.


File: acl2-doc-emacs.info,  Node: TOGGLE-PC-MACRO,  Next: UNSAVE,  Prev: RETRIEVE,  Up: PROOF-CHECKER

TOGGLE-PC-MACRO    change an ordinary macro command to an atomic macro, or vice-versa

     Example:
     (toggle-pc-macro pro)

Change pro from an atomic macro command to an ordinary one (or
vice-versa, if pro 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 new-tp is supplied and not nil, then
it should be the new type (the symbol macro or atomic-macro, in any
package), or else there is no change.


File: acl2-doc-emacs.info,  Node: UNSAVE,  Next: VERIFY,  Prev: TOGGLE-PC-MACRO,  Up: PROOF-CHECKER

UNSAVE    remove a proof-checker state

     Example:
     (unsave assoc-of-append)

     General Form:
     (unsave name)

Eliminates the association of a proof-checker state with name.  See
*note UNSAVE:: or see *note ACL2-PC||UNSAVE::.

Also see *note ACL2-PC||SAVE:: and see *note RETRIEVE::.


File: acl2-doc-emacs.info,  Node: VERIFY,  Prev: UNSAVE,  Up: PROOF-CHECKER

VERIFY    enter the interactive proof checker

For proof-checker command summaries, see *note PROOF-CHECKER::.

     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 proof-checker in the state at which is was last
           left.

     General Form:
     (VERIFY &OPTIONAL raw-term
             &KEY
             event-name
             rule-classes
             instructions)

Verify is the function used for entering the proof-checker's
interactive loop.


File: acl2-doc-emacs.info,  Node: PROOF-TREE,  Next: Pages Written Especially for the Tours,  Prev: PROOF-CHECKER,  Up: Top

PROOF-TREE    proof tree displays

A view of ACL2 proofs may be obtained by way of "proof tree displays,"
which appear in proof output (see *note 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
*proof-tree-start-delimiter* are printed, then the proof tree display,
and finally the characters in the constant string
*proof-tree-end-delimiter*.

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 emacs/emacs-acl2.el
distributed with ACL2.

The command :start-proof-tree enables proof-tree output, while
:stop-proof-tree disables proof-tree output; see *note
START-PROOF-TREE:: and see *note STOP-PROOF-TREE::.

* Menu:

* 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

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 *note 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 n 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 k 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 *note PROOF-TREE-EXAMPLES:: for detailed examples.  See *note
CHECKPOINT-FORCED-GOALS:: to learn how to mark goals as checkpoints
that force the creation of goals in forcing rounds.  Finally, see *note
PROOF-TREE-DETAILS:: for some points not covered elsewhere.


File: acl2-doc-emacs.info,  Node: CHECKPOINT-FORCED-GOALS,  Next: PROOF-TREE-DETAILS,  Prev: PROOF-TREE,  Up: PROOF-TREE

CHECKPOINT-FORCED-GOALS    Cause forcing goals to be checkpointed in proof trees

     Example forms:
     (checkpoint-forced-goals t)
     (checkpoint-forced-goals nil)

Also see *note PROOF-TREE::.

By default, goals are not marked as checkpoints by a proof tree display
(as described elsewhere; see *note 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 (checkpoint-forced-goals t) has been executed.  To return to the
default behavior, use the command (checkpoint-forced-goals nil).


File: acl2-doc-emacs.info,  Node: PROOF-TREE-DETAILS,  Next: PROOF-TREE-EXAMPLES,  Prev: CHECKPOINT-FORCED-GOALS,  Up: PROOF-TREE

PROOF-TREE-DETAILS    proof tree details not covered elsewhere

See *note 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
:stop-proof-tree has not been executed, or has been superseded by a
later :start-proof-tree 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 :bye in a proof (see *note 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.  (@
proof-tree-indent) is initially the string "| ":  it is the string that
is laid down the appropriate number of times to effect indentation.  (@
proof-tree-buffer-width) is initially the value of
(fmt-soft-right-margin state), and is used to prevent printing of the
annotation "(forced ...)" in any greater column than this value.
However, (assign proof-tree-buffer-width nil) to avoid any such
suppression.  Finally, (@ checkpoint-processors) is a list of processors
from the constant list *preprocess-clause-ledge*, together with
:induct.  You may remove elements of (@ checkpoint-processors) to limit
which processes are considered checkpoints, but note that this can
affect what is printed by gag-mode (see *note SET-GAG-MODE::).

4.  When :otf-flg is not set to t 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.


File: acl2-doc-emacs.info,  Node: PROOF-TREE-EXAMPLES,  Next: START-PROOF-TREE,  Prev: PROOF-TREE-DETAILS,  Up: PROOF-TREE

PROOF-TREE-EXAMPLES    proof tree example

See *note 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
cancel_equal_plus; 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 ("Goal"), 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 "Subgoal 18",
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 "Goal".  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 t (note that the
"0" shows clearly that no subgoals were created), but that some rule's
hypotheses were forced.  Although this goal is not checkpointed (i.e.,
no "c" appears on the left margin), one can cause such goals to be
checkpointed; see *note 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 "[1]Goal".  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
plus-tree-del, 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 t, 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.


File: acl2-doc-emacs.info,  Node: START-PROOF-TREE,  Next: STOP-PROOF-TREE,  Prev: PROOF-TREE-EXAMPLES,  Up: PROOF-TREE

START-PROOF-TREE    start displaying proof trees during proofs

Also see *note PROOF-TREE:: and see *note STOP-PROOF-TREE::.  Note that
:start-proof-tree works by removing 'proof-tree from the
inhibit-output-lst; see *note SET-INHIBIT-OUTPUT-LST::.

Explanations of proof tree displays may be found elsewhere: see *note
PROOF-TREE::.  In a nutshell: :start-proof-tree causes proof tree
display to be turned on, once it has been turned off by
:stop-proof-tree.

Do not attempt to invoke start-proof-tree during an interrupt in the
middle of a proof.


File: acl2-doc-emacs.info,  Node: STOP-PROOF-TREE,  Prev: START-PROOF-TREE,  Up: PROOF-TREE

STOP-PROOF-TREE    stop displaying proof trees during proofs

Also see *note PROOF-TREE:: and see *note START-PROOF-TREE::.  Note that
:stop-proof-tree works by adding 'proof-tree to the inhibit-output-lst;
see *note SET-INHIBIT-OUTPUT-LST::.

Proof tree displays are explained in the documentation for proof-tree.
:Stop-proof-tree causes proof tree display to be turned off.

It is permissible to submit the form (stop-proof-tree) 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 (stop-proof-tree) in
raw Lisp.


File: acl2-doc-emacs.info,  Node: Pages Written Especially for the Tours,  Next: REAL,  Prev: PROOF-TREE,  Up: Top

Pages Written Especially for the Tours    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 specificially for
the Web user.

Furthermore, browsing the pages below via the ACL2 :DOC command or via
TexInfo is often unsatisfying because those browsers do not support gif
files and the notion of 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.

* Menu:

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

Generally, the topics listed above will not be of use to the ACL2 user.


File: acl2-doc-emacs.info,  Node: A Flying Tour of ACL2,  Next: A Sketch of How the Rewriter Works,  Prev: Pages Written Especially for the Tours,  Up: Pages Written Especially for the Tours

A Flying Tour of ACL2    A Flying Tour of ACL2

Next on the Flying Tour:  *note 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 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.

     The Flight Plan
     * This Documentation
     * What is ACL2?
     * Mathematical Logic
     * Mechanical Theorem Proving
     * Mathematical Models in General
     * Mathematical Models of Computing Machines
          Formalizing Models
          Running Models
          Symbolic Execution of Models
          Proving Theorems about Models
     * Requirements of ACL2
          The User's Skills
          Training
          Host System

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

Next on the Flying Tour:  *note About the ACL2 Home Page::


File: acl2-doc-emacs.info,  Node: A Sketch of How the Rewriter Works,  Next: A Tiny Warning Sign,  Prev: A Flying Tour of ACL2,  Up: Pages Written Especially for the Tours

A Sketch of How the Rewriter Works    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.

The variables of the rewrite rule are instantiated so that the
left-hand side of the rule matches the target:

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

Then the target is replaced by the instantiated right-hand side of the
rule.

Sometimes rules have hypotheses.  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 backchaining.  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 *note
INTRODUCTION-TO-THE-THEOREM-PROVER::, which we will recommend you work
through after you have finished the two tours.


File: acl2-doc-emacs.info,  Node: A Tiny Warning Sign,  Next: A Trivial Proof,  Prev: A Sketch of How the Rewriter Works,  Up: Pages Written Especially for the Tours

A Tiny Warning Sign    A Tiny Warning Sign

This warning sign, which usually appears as "", 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 _user_ of ACL2 rather than the _potential user_.  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.


File: acl2-doc-emacs.info,  Node: A Trivial Proof,  Next: A Typical State,  Prev: A Tiny Warning Sign,  Up: Pages Written Especially for the Tours

A Trivial Proof    A Trivial Proof


File: acl2-doc-emacs.info,  Node: A Typical State,  Next: A Walking Tour of ACL2,  Prev: A Trivial Proof,  Up: Pages Written Especially for the Tours

A Typical State    A Typical State

Next on the Flying Tour:  *note Functions for Manipulating these
Objects::

Observe that the states in typical models talk about

     booleans    integers   vectors     records   caches
     bits        symbols    arrays      stacks    files
     characters  strings    sequences   tables    directories

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

The functions we need to manipulate these objects do things like
concatenate, reverse, sort, search, count, etc.

Next on the Flying Tour:  *note Functions for Manipulating these
Objects::


File: acl2-doc-emacs.info,  Node: A Walking Tour of ACL2,  Next: ACL2 Characters,  Prev: A Typical State,  Up: Pages Written Especially for the Tours

A Walking Tour of ACL2    A Walking Tour of ACL2

Next on the Walking Tour:  *note 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 (<>).  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.

Next on the Walking Tour:  *note Common Lisp::


File: acl2-doc-emacs.info,  Node: ACL2 Characters,  Next: ACL2 Conses or Ordered Pairs,  Prev: A Walking Tour of ACL2,  Up: Pages Written Especially for the Tours

ACL2 Characters    ACL2 Characters

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

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

The function characterp <> recognizes characters.  For more details,
See *note CHARACTERS:: <>.


File: acl2-doc-emacs.info,  Node: ACL2 Conses or Ordered Pairs,  Next: ACL2 Strings,  Prev: ACL2 Characters,  Up: Pages Written Especially for the Tours

ACL2 Conses or Ordered Pairs    ACL2 Conses or Ordered Pairs

The function cons <> creates an ordered pair.  Car <> and cdr <> return
the first and second components, respectively, of an ordered pair.  The
function consp <> 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 *note
PROGRAMMING:: <> 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
nil.  A "true list" (see *note TRUE-LISTP:: <>) is either nil or a
proper cons.  (A b c . 7) is an improper cons and hence not a true list.


File: acl2-doc-emacs.info,  Node: ACL2 Strings,  Next: ACL2 Symbols,  Prev: ACL2 Conses or Ordered Pairs,  Up: Pages Written Especially for the Tours

ACL2 Strings    ACL2 Strings

Strings of 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 stringp <> recognizes strings and char <> will fetch the
nth character of a string.  There are many other primitives for
handling strings, such as string< <> for comparing two strings
lexicographically.  We suggest you See *note PROGRAMMING:: <> where we
list all of the primitive ACL2 functions.  Alternatively, see any
Common Lisp language documentation.


File: acl2-doc-emacs.info,  Node: ACL2 Symbols,  Next: ACL2 System Architecture,  Prev: ACL2 Strings,  Up: Pages Written Especially for the Tours

ACL2 Symbols    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 PLUS and
SMITH::ABC.  All function and variable names in ACL2 are symbols.  When
symbols are used as constants they must be quoted, as in 'PLUS.

The symbol T is commonly used as the Boolean "true."  The symbol NIL is
commonly used both as the Boolean "false" and as the "empty list."
Despite sometimes being called the "empty list" NIL is a symbol not an
"empty cons."  Unlike other symbols, T and NIL may be used as constants
without quoting them.

Usually, symbols are written as sequences of alphanumeric characters
other than those denoting numbers.  Thus, A12, +1A and 1+ are symbols
but +12 is a number.  Roughly speaking, when symbols are read lower case
characters are converted to upper case, so we frequently do not
distinguish ABC from Abc or abc.  See *note 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, |Abc|
is a symbol whose first character is capitalized and whose remaining
characters are in lower case.  |An odd duck| is a symbol containing two
#\Space characters.  See any Common Lisp documentation for the
syntactic rules for symbols.

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 *note SYMBOL-PACKAGE-NAME:: <> and see *note SYMBOL-NAME:: <>.)
The symbol SMITH::ABC is said to be in package "SMITH" and to have the
symbol name "ABC".  The symbol ABC in package "SMITH" is generally not
equal to the symbol ABC in package "JONES".  However, it is possible to
"import" symbols from one package into another one, but in ACL2 this can
only be done when the package is created.  (See *note DEFPKG:: <>.)  If
the current-package <> is "SMITH" then SMITH::ABC may be more briefly
written as just ABC.  Intern <> "creates" a symbol of a given name in a
given package.


File: acl2-doc-emacs.info,  Node: ACL2 System Architecture,  Next: ACL2 as an Interactive Theorem Prover,  Prev: ACL2 Symbols,  Up: Pages Written Especially for the Tours

ACL2 System Architecture    ACL2 System Architecture

Next on the Walking Tour:  *note Rewrite Rules are Generated from
DEFTHM Events::

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

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 Lemma Libraries and Utilities <> link of the
ACL2 home page.

Next on the Walking Tour:  *note Rewrite Rules are Generated from
DEFTHM Events::


File: acl2-doc-emacs.info,  Node: ACL2 as an Interactive Theorem Prover,  Next: ACL2 as an Interactive Theorem Prover (cont),  Prev: ACL2 System Architecture,  Up: Pages Written Especially for the Tours

ACL2 as an Interactive Theorem Prover    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.

The user usually guides ACL2 by suggesting that it first prove key
lemmas.  Lemmas are just theorems used in the proofs of other theorems.


File: acl2-doc-emacs.info,  Node: ACL2 as an Interactive Theorem Prover (cont),  Next: ACL2 is an Untyped Language,  Prev: ACL2 as an Interactive Theorem Prover,  Up: Pages Written Especially for the Tours

ACL2 as an Interactive Theorem Prover (cont)    ACL2 as an Interactive Theorem Prover (cont)

Next on the Walking Tour:  *note ACL2 System Architecture::

When ACL2 proves a lemma, it is converted into one or more rules and
stored in a database.  The theorem prover is rule-driven.  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 knows 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 *note RULE-CLASSES:: <>).

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, you determine how ACL2 should use each formula that it proves.

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

Next on the Walking Tour:  *note ACL2 System Architecture::


File: acl2-doc-emacs.info,  Node: ACL2 is an Untyped Language,  Next: About Models,  Prev: ACL2 as an Interactive Theorem Prover (cont),  Up: Pages Written Especially for the Tours

ACL2 is an Untyped Language    ACL2 is an Untyped Language

The example

     ACL2 !>(app '(a b c) 27)
     (A B C . 27)

illustrates the fact that ACL2's logic is untyped (see *note About
Types:: for a brief discussion of the typed versus untyped nature of
the logic).

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

You can think of (app x y) as building a binary tree by replacing the
right-most tip of the tree x with the tree y.


File: acl2-doc-emacs.info,  Node: About Models,  Next: About Types,  Prev: ACL2 is an Untyped Language,  Up: Pages Written Especially for the Tours

About Models    About Models

Next on the Flying Tour:  *note Models of Computer Hardware and
Software::

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

A mathematical model is a set of mathematical formulas used to predict
the behavior of some artifact.

The use of mathematical models allows faster and cheaper delivery of
better systems.

Models need not be complete or perfectly accurate to be useful to the
trained engineer.

See *note Models in Engineering:: for more discussion of these
assertions in an engineering context.

Next on the Flying Tour:  *note Models of Computer Hardware and
Software::


File: acl2-doc-emacs.info,  Node: About Types,  Next: About the ACL2 Home Page,  Prev: About Models,  Up: Pages Written Especially for the Tours

About Types    About Types

The universe of ACL2 objects includes objects of many different types.
For example, t is a "symbol" and 3 is an "integer."  Roughly speaking
the objects of ACL2 can be partitioned into the following types:

     Numbers                   3, -22/7, #c(3 5/2)
     Characters                #\A, #\a, #\Space
     Strings                   "This is a string."
     Symbols                   'abc, 'smith::abc
     Conses (or Ordered Pairs) '((a . 1) (b . 2))

When proving theorems it is important to know the types of object
returned by a term.  ACL2 uses a complicated heuristic algorithm,
called type-set <>, to determine what types of objects a term may
produce.  The user can more or less program the type-set algorithm by
proving type-prescription <> 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 (+ t 3) which sums the symbol t and
the integer 3.  Common Lisp does not prohibit such expressions.  We
like untyped languages because they are simple to describe, though
proving theorems about them can be awkward because, unless one is
careful in the way one defines or states things, unusual cases (like (+
t 3)) can arise.

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

You might immediately wonder about our claim that ACL2 is Common Lisp,
since (+ t 3) is "an error" (and will sometimes even "signal an error")
in Common Lisp.  It is to handle this problem that ACL2 has guards.  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.


File: acl2-doc-emacs.info,  Node: About the ACL2 Home Page,  Next: About the Admission of Recursive Definitions,  Prev: About Types,  Up: Pages Written Especially for the Tours

About the ACL2 Home Page    About the ACL2 Home Page

Next on the Flying Tour:  *note What Is ACL2(Q)::

The ACL2 Home Page is integrated into the ACL2 online documentation.
Over 4 megabytes of hypertext is available here.

The vast majority of the text is user-level documentation.  For
example, to find out about rewrite <> rules you could click on the link.
(If you do that, remember to use your browser's Back Button to come back
here.)

The tiny warning signs <> 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.

Finally, every page contains two icons at the bottom.  The ACL2 icon
leads you back to the ACL2 Home Page.  The Index icon allows you to
browse an alphabetical listing of all the topics in ACL2's online
documentation.  But both icons take you off the main route of the tour.

Next on the Flying Tour:  *note What Is ACL2(Q)::


File: acl2-doc-emacs.info,  Node: About the Admission of Recursive Definitions,  Next: About the Prompt,  Prev: About the ACL2 Home Page,  Up: Pages Written Especially for the Tours

About the Admission of Recursive Definitions    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 (APP
X Y) so that it was equal to (NOT (APP X Y)) then we could prove
anything.  The purported "definition" of APP must have several
properties to be admitted to the logic as a new axiom.

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 app the measure is the "size" of the first argument, x, as
determined by the primitive function acl2-count <>.  The well-founded
relation used in this example is o-p <>, which is the standard ordering
on the ordinals less than "epsilon naught."  These particular choices
for app were made "automatically" by ACL2.  But they are in fact
determined by various "default" settings.  The user of ACL2 can change
the defaults or specify a "hint" to the defun <> command to specify the
measure and relation.

You should now return to the Walking Tour.


File: acl2-doc-emacs.info,  Node: About the Prompt,  Next: An Example Common Lisp Function Definition,  Prev: About the Admission of Recursive Definitions,  Up: Pages Written Especially for the Tours

About the Prompt    About the Prompt

The string "ACL2 !>" is the ACL2 prompt.

The prompt tells the user that an ACL2 command <>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 :q <> for quitting 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 LD <>
(after Lisp's "load").

When a command is read, all the symbols in it are converted to
uppercase.  Thus, typing (defun app ...) is the same as typing (DEFUN
APP ...) or (defun App ...).  There are ways to force lowercase case
characters into symbols but we won't discuss them here.  A consequence
of Common Lisp's default uppercasing is that you'll see a general lack
of concern over the case used when symbols are displayed in this
documentation.

In addition, symbols "belong" to "packages" which give the user a way to
control namespaces.  The prompt tells us which package is the default
one, namely "ACL2".  That means when we call car, for example, we are
invoking the standard definition of that symbol.  If the packager were
"JONES" then car would refer to the definition of that symbol in that
package (which may or may not be different depending on what symbols
were imported into that package.

A command like (defun app (x y) ...) causes ACL2 to evaluate the defun
<> function on app, (x y) and ....  When that command is evaluated it
prints some information to the terminal explaining the processing of
the proposed definition.  It returns the symbol APP as its value, which
is printed by the command interpreter.  (Actually, defun is not a
function but a macro <> which expands to a form that involves state <>,
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 defun command is an example of a special kind of command called an
"event."  Events <> are those commands that change the "logical world"
by adding such things as axioms or theorems to ACL2's database.  See
*note WORLD:: <>.  But not every command is an event command.

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

A third kind of command is one that display information about the
current logical world or that "roll back" to previous versions of the
world.  Such commands are called "history" <> commands.

What does the ACL2 prompt tell us about the read-eval-print loop?  The
prompt "ACL2 !>" tells us that the command will be read with
current-package <> set to "ACL2", that guard checking (see *note
SET-GUARD-CHECKING:: <>) is on ("!"), and that we are at the top-level
(there is only one ">").  For more about the prompt, see *note
DEFAULT-PRINT-PROMPT:: <>.

You should now return to the Walking Tour.


File: acl2-doc-emacs.info,  Node: An Example Common Lisp Function Definition,  Next: An Example of ACL2 in Use,  Prev: About the Prompt,  Up: Pages Written Especially for the Tours

An Example Common Lisp Function Definition    An Example Common Lisp Function Definition

Next on the Walking Tour:  *note An Example of ACL2 in Use::

Consider the binary trees x and y below.

In Lisp, x is written as the list '(A B) or, equivalently, as '(A B .
NIL).  Similarly, y may be written '(C D E).  Suppose we wish to
replace the right-most tip of x by the entire tree y.  This is denoted
(app x y), where app stands for "append".

We can define app with:

     (defun app (x y)                           ; Concatenate x and y.
       (declare (type (satisfies true-listp) x)); We expect x to end in NIL.
       (cond ((endp x) y)                       ; If x is empty, return y.
             (t (cons (car x)                   ; Else, copy first node
                      (app (cdr x) y)))))       ;  and recur into next.

If you defined this function in some Common Lisp, then to run app on the
x and y above you could then type

     (app '(A B) '(C D E))

and Common Lisp will print the result (A B C D E).

Next on the Walking Tour:  *note An Example of ACL2 in Use::


File: acl2-doc-emacs.info,  Node: An Example of ACL2 in Use,  Next: Analyzing Common Lisp Models,  Prev: An Example Common Lisp Function Definition,  Up: Pages Written Especially for the Tours

An Example of ACL2 in Use    An Example of ACL2 in Use

Next on the Walking Tour:  *note How To Find Out about ACL2 Functions::

To introduce you to ACL2 we will consider the app function discussed in
the Common Lisp page, except we will omit for the moment the declare
form, which in ACL2 is called a guard.

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

     (defun app (x y)
       (cond ((endp x) y)
             (t (cons (car x)
                      (app (cdr x) y)))))

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 app,
       * what one simple theorem about app 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 definitional principle, types, the
ACL2 read-eval-print loop, and how the theorem prover works.

When we complete this part of the tour we will return briefly to the
notion of guards and revisit several of the topics above in that
context.

Next on the Walking Tour:  *note How To Find Out about ACL2 Functions::


File: acl2-doc-emacs.info,  Node: Analyzing Common Lisp Models,  Next: Common Lisp,  Prev: An Example of ACL2 in Use,  Up: Pages Written Especially for the Tours

Analyzing Common Lisp Models    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, (A B C D E F).

But what distinguishes ACL2 (the logic) from applicative Common Lisp
(the language) is that in ACL2 you can prove that the concatenation
function app is associative when its arguments are true-lists, whereas
in Common Lisp all you can do is test that proposition.

That is, in ACL2 it makes sense to say that the following formula is a
"theorem."

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


File: acl2-doc-emacs.info,  Node: Common Lisp,  Next: Common Lisp as a Modeling Language,  Prev: Analyzing Common Lisp Models,  Up: Pages Written Especially for the Tours

Common Lisp    Common Lisp

Next on the Walking Tour:  *note 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, Common Lisp The Language, Digital Press,
12 Crosby Drive, Bedford, MA 01730, 1990.  See also
`http://www.cs.cmu.edu/Web/Groups/AI/html/cltl/cltl2.html'.

ACL2 formalizes only a subset of Common Lisp.  It includes such
familiar Lisp functions as cons, car and cdr for creating and
manipulating list structures, various arithmetic primitives such as +,
*, expt and <=, and intern and symbol-name for creating and manipulating
symbols.  Control primitives include cond, case and if, as well as
function call, including recursion.  New functions are defined with
defun and macros with defmacro.  See *note PROGRAMMING:: <> 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 very small subset of full Common Lisp.  ACL2 does not include
the Common Lisp Object System (CLOS), higher order functions, circular
structures, and other aspects of Common Lisp that are non-applicative.
Roughly speaking, a language is applicative if it follows the rules of
function application.  For example, f(x) must be equal to f(x), which
means, among other things, that the value of f must not be affected by
"global variables" and the object x must not change over time.

Next on the Walking Tour:  *note An Example Common Lisp Function
Definition::


File: acl2-doc-emacs.info,  Node: Common Lisp as a Modeling Language,  Next: Conversion,  Prev: Common Lisp,  Up: Pages Written Especially for the Tours

Common Lisp as a Modeling Language    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 app, please proceed.  Otherwise see *note Common
Lisp:: for an exceedingly brief introduction to Common Lisp and then
come back 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 run 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 app as shown above and then type

     (app '(A B) '(C D E))

in any Common Lisp, the answer will be computed and will be (A B C D E).

The executable 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.

See *note Analyzing Common Lisp Models:: to continue.


File: acl2-doc-emacs.info,  Node: Conversion,  Next: Corroborating Models,  Prev: Common Lisp as a Modeling Language,  Up: Pages Written Especially for the Tours

Conversion    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 _symbols_.
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 |AbC| or you can put a "backslash"
before each lower case character you wish to preserve, as in A\bC.
|AbC| and A\bC 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.


File: acl2-doc-emacs.info,  Node: Corroborating Models,  Next: Evaluating App on Sample Input,  Prev: Conversion,  Up: Pages Written Especially for the Tours

Corroborating Models    Corroborating Models

Next on the Flying Tour:  *note Models of Computer Hardware and
Software::

After producing a model, it must be corroborated 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, graviation 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 prove 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.

Models need not be complete to be useful.

Models need not be perfectly accurate to be useful.

The user of a model must understand its limitations.

Next on the Flying Tour:  *note Models of Computer Hardware and
Software::


File: acl2-doc-emacs.info,  Node: Evaluating App on Sample Input,  Next: Flawed Induction Candidates in App Example,  Prev: Corroborating Models,  Up: Pages Written Especially for the Tours

Evaluating App on Sample Input    Evaluating App on Sample Input

Next on the Walking Tour:  *note The Associativity of App::

     ACL2 !>(app nil '(x y z))
     (X Y Z)

     ACL2 !>(app '(1 2 3) '(4 5 6 7))
     (1 2 3 4 5 6 7)

     ACL2 !>(app '(a b c d e f g) '(x y z))   ; see *note Conversion:: for an explanation
     (A B C D E F G X Y Z)

     ACL2 !>(app (app '(1 2) '(3 4)) '(5 6))
     (1 2 3 4 5 6)

     ACL2 !>(app '(1 2) (app '(3 4) '(5 6)))
     (1 2 3 4 5 6)

     ACL2!>(let ((a '(1 2))
                 (b '(3 4))
                 (c '(5 6)))
             (equal (app (app a b) c)
                    (app a (app b c))))
     T

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

Next on the Walking Tour:  *note The Associativity of App::


File: acl2-doc-emacs.info,  Node: Flawed Induction Candidates in App Example,  Next: Free Variables in Top-Level Input,  Prev: Evaluating App on Sample Input,  Up: Pages Written Especially for the Tours

Flawed Induction Candidates in App Example    Flawed Induction Candidates in App Example

Induction on a is unflawed: every occurrence of a in the conjecture

     (equal (app (app a b) c)
            (app a (app b c)))

is in a position being recursively decomposed!

Now look at the occurrences of b.  The first (shown in bold below) is
in a position that is held constant in the recursion of (app a b).  It
would be "bad" to induct on b here.

     (equal (app (app a b) c)
            (app a (app b c)))


File: acl2-doc-emacs.info,  Node: Free Variables in Top-Level Input,  Next: Functions for Manipulating these Objects,  Prev: Flawed Induction Candidates in App Example,  Up: Pages Written Especially for the Tours

Free Variables in Top-Level Input    Free Variables in Top-Level Input

     ACL2 !>(equal (app (app a b) c)
                   (app a (app b c))))

     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 !>(equal (app (app '(1 2) '(3 4)) '(5 6))
                   (app '(1 2) (app '(3 4) '(5 6))))
     (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 *note STOBJ:: <>.  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 state <>.

ACL2 provides a way for you to use state to save values of computations
at the top-level and refer to them later.  See assign <> and @ <>.


File: acl2-doc-emacs.info,  Node: Functions for Manipulating these Objects,  Next: Guards,  Prev: Free Variables in Top-Level Input,  Up: Pages Written Especially for the Tours

Functions for Manipulating these Objects    Functions for Manipulating these Objects

Next on the Flying Tour:  *note Modeling in ACL2::

Consider a typical "stack" of control frames.

Suppose the model required that we express the idea of "the most recent
frame whose return program counter points into MAIN."

The natural expression of this notion involves

function application -- "fetch the return-pc of this frame"

case analysis --  "if the pc is MAIN, then ..."

iteration or recursion -- "pop this frame off and repeat."

The designers of ACL2 have taken the position that a programming
language is the natural language in which to define such notions,
provided 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.

Next on the Flying Tour:  *note Modeling in ACL2::


File: acl2-doc-emacs.info,  Node: Guards,  Next: Guessing the Type of a Newly Admitted Function,  Prev: Functions for Manipulating these Objects,  Up: Pages Written Especially for the Tours

Guards    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 completion 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 car <>, for
example, is (or (consp x) (equal x nil)), which requires the argument to
be either an ordered pair or nil.  We will discuss later how to specify
a guard for a defined function; when one is not specified, the guard is
t which is just to say all arguments are allowed.

But guards are entirely extra-logical: 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 all
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 *note 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.


File: acl2-doc-emacs.info,  Node: Guessing the Type of a Newly Admitted Function,  Next: Guiding the ACL2 Theorem Prover,  Prev: Guards,  Up: Pages Written Especially for the Tours

Guessing the Type of a Newly Admitted Function    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 app the term is

     (OR (CONSP (APP X Y))
         (EQUAL (APP X Y) Y))

which says that app returns either a cons or its second argument.  This
formula is added to ACL2's rule base as a type-prescription <> 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.


File: acl2-doc-emacs.info,  Node: Guiding the ACL2 Theorem Prover,  Next: Hey Wait! Is ACL2 Typed or Untyped(Q),  Prev: Guessing the Type of a Newly Admitted Function,  Up: Pages Written Especially for the Tours

Guiding the ACL2 Theorem Prover    Guiding the ACL2 Theorem Prover

Next on the Walking Tour:  *note 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.

Look at the picture above.  It is meant to suggest that Q is an
important lemma needed for the proof of P.  Note that to lead the
prover to the proof of P the user first proves Q.  In a way, the
formulation and proof of Q is a hint to the prover about how to prove P.

The user usually doesn't think of Q or recognize the need to prove it
separately until he or she sees the theorem prover fail to prove P
without it "knowing" Q.

The way the user typically discovers the need for Q is to look at failed
proofs.

Next on the Walking Tour:  *note ACL2 as an Interactive Theorem Prover
(cont)::


File: acl2-doc-emacs.info,  Node: Hey Wait! Is ACL2 Typed or Untyped(Q),  Next: How Long Does It Take to Become an Effective User(Q),  Prev: Guiding the ACL2 Theorem Prover,  Up: Pages Written Especially for the Tours

Hey Wait!  Is ACL2 Typed or Untyped(Q)    Hey Wait!  Is ACL2 Typed or Untyped?

The example

     ACL2 !>(app 7 27)

     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 *note Undocumented
Topic:: for a discussion of guards.

The guard on endp <> 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 (see *note About the Prompt::) with its "!".


File: acl2-doc-emacs.info,  Node: How Long Does It Take to Become an Effective User(Q),  Next: How To Find Out about ACL2 Functions,  Prev: Hey Wait! Is ACL2 Typed or Untyped(Q),  Up: Pages Written Especially for the Tours

How Long Does It Take to Become an Effective User(Q)    How Long Does It Take to Become an Effective User?

Next on the Flying Tour:  *note 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."

Next on the Flying Tour:  *note Other Requirements::


File: acl2-doc-emacs.info,  Node: How To Find Out about ACL2 Functions,  Next: How To Find Out about ACL2 Functions (cont),  Prev: How Long Does It Take to Become an Effective User(Q),  Up: Pages Written Especially for the Tours

How To Find Out about ACL2 Functions    How To Find Out about ACL2 Functions

Next on the Walking Tour:  *note How To Find Out about ACL2 Functions
(cont)::

Most ACL2 primitives are documented.  Here is the definition of app
again, with the documented topics highlighted.  <> All of the links
below lead into the ACL2 reference manual.  So follow these links if you
wish, but use your Back Button 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 <> we see that it is a Common Lisp
function and is defined to be the same as atom <>, which recognizes
non-conses.  But endp has a guard.  Since we are ignorning guards for
now, we'll ignore the guard issue on endp.

So this definition reads "to app x and y: if x is an atom, return y;
otherwise, app (cdr x) and y and then cons (car x) onto that."

Next on the Walking Tour:  *note How To Find Out about ACL2 Functions
(cont)::


File: acl2-doc-emacs.info,  Node: How To Find Out about ACL2 Functions (cont),  Next: Modeling in ACL2,  Prev: How To Find Out about ACL2 Functions,  Up: Pages Written Especially for the Tours

How To Find Out about ACL2 Functions (cont)    How To Find Out about ACL2 Functions (cont)

Next on the Walking Tour:  *note The Admission of App::

You can always use the Index <> icon below to find the documentation of
functions.  Try it.  Click on the Index icon below.  Then use the Find
command of your browser to find "endp" in that document and follow the
link.  But remember to come back here.

The ACL2 documentation is also available via Emacs' TexInfo, 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 :doc
command.  If you have ACL2 running, try the command :doc endp.

Another way to find out about ACL2 functions, if you have an ACL2 image
available, is to use the command :args <> 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 app.

Next on the Walking Tour:  *note The Admission of App::


File: acl2-doc-emacs.info,  Node: Modeling in ACL2,  Next: Models in Engineering,  Prev: How To Find Out about ACL2 Functions (cont),  Up: Pages Written Especially for the Tours

Modeling in ACL2    Modeling in ACL2

Next on the Flying Tour:  *note Running Models::

Below we define mc(s,n) to be the function that single-steps n times
from a given starting state, s.  In Common Lisp, "mc(s,n)" is written
(mc s n).

     (defun mc (s n)                     ; To step s n times:
      (if (zp n)                         ; If n is 0
          s                              ;    then return s
          (mc (single-step s) (- n 1)))) ;    else step single-step(s)
                                                           n-1 times.

This is an example of a formal model in ACL2.

Next on the Flying Tour:  *note Running Models::


File: acl2-doc-emacs.info,  Node: Models in Engineering,  Next: Models of Computer Hardware and Software,  Prev: Modeling in ACL2,  Up: Pages Written Especially for the Tours

Models in Engineering    Models in Engineering

Frequently, engineers use mathematical models.  Use of such models
frequently lead to

better designs,

faster completion of acceptable products, and

reduced overall cost,

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.


File: acl2-doc-emacs.info,  Node: Models of Computer Hardware and Software,  Next: Name the Formula Above,  Prev: Models in Engineering,  Up: Pages Written Especially for the Tours

Models of Computer Hardware and Software    Models of Computer Hardware and Software

Next on the Flying Tour:  *note A Typical State::

Computing machines, whether hardware or software or some combintation,
are frequently modeled as "state machines."

To so model a computing machine we must represent its states as objects
in our mathematical framework.

Transitions 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

algebra,

geometry,

trignometry, and

calculus

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.

Next on the Flying Tour:  *note A Typical State::


File: acl2-doc-emacs.info,  Node: Name the Formula Above,  Next: Nontautological Subgoals,  Prev: Models of Computer Hardware and Software,  Up: Pages Written Especially for the Tours

Name the Formula Above    Name the Formula Above

When the theorem prover explicitly assigns a name, like *1, to a
formula, it has decided to prove the formula by induction.


File: acl2-doc-emacs.info,  Node: Nontautological Subgoals,  Next: Numbers in ACL2,  Prev: Name the Formula Above,  Up: Pages Written Especially for the Tours

Nontautological Subgoals    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.


File: acl2-doc-emacs.info,  Node: Numbers in ACL2,  Next: On the Naming of Subgoals,  Prev: Nontautological Subgoals,  Up: Pages Written Especially for the Tours

Numbers in ACL2    Numbers in ACL2

ACL2 numbers are precisely represented and unbounded.  They can be
partitioned into the following subtypes:

     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) ; = 3+(5/2)i

Signed integer constants are usually written (as illustrated above) as
sequences of decimal digits, possibly preceded by + or -.  Decimal
points are not allowed.  Integers may be written in binary, as in #b1011
(= 23) and #b-111 (= -7).  Octal may also be used, #o-777 = -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 +, -, *,
/, =, <, <=, > and >=.  However there are many others, e.g., floor,
ceiling, and lognot.  We suggest you see *note PROGRAMMING:: <> where
we list all of the primitive ACL2 functions.  Alternatively, 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)))


File: acl2-doc-emacs.info,  Node: On the Naming of Subgoals,  Next: Other Requirements,  Prev: Numbers in ACL2,  Up: Pages Written Especially for the Tours

On the Naming of Subgoals    On the Naming of Subgoals

Subgoal *1/2 is the induction step 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.


File: acl2-doc-emacs.info,  Node: Other Requirements,  Next: Overview of the Expansion of ENDP in the Base Case,  Prev: On the Naming of Subgoals,  Up: Pages Written Especially for the Tours

Other Requirements    Other Requirements

Next on the Flying Tour:  *note The End of the Flying Tour::

ACL2 is distributed on the Web without fee.

There is a license agreement based on the 3-clause BSD license.  See the
file LICENSE in the ACL2 distribution.

ACL2 currently runs on Unix, Linux, Windows, and Macintosh OS X
operating systems.

It can be built in any of the following Common Lisps:

       * Allegro Common Lisp,
       * CCL (formerly OpenMCL)
       * CLISP,
       * CMU Common Lisp,
       * GCL (Gnu Common Lisp),
       * LispWorks, and
       * SBCL (Steel Bank Common Lisp)

Next on the Flying Tour:  *note The End of the Flying Tour::


File: acl2-doc-emacs.info,  Node: Overview of the Expansion of ENDP in the Base Case,  Next: Overview of the Expansion of ENDP in the Induction Step,  Prev: Other Requirements,  Up: Pages Written Especially for the Tours

Overview of the Expansion of ENDP in the Base Case    Overview of the Expansion of ENDP in the Base Case

Subgoal *1/1 is the Base Case of our induction.  It simplifies to
Subgoal *1/1' by expanding the ENDP term in the hypothesis, just as we
saw in the earlier proof of Subgoal *1/2.


File: acl2-doc-emacs.info,  Node: Overview of the Expansion of ENDP in the Induction Step,  Next: Overview of the Final Simplification in the Base Case,  Prev: Overview of the Expansion of ENDP in the Base Case,  Up: Pages Written Especially for the Tours

Overview of the Expansion of ENDP in the Induction Step    Overview of the Expansion of ENDP in the Induction Step

In this message the system is saying that Subgoal *1/2 has been
rewritten to the Subgoal *1/2', by expanding the definition of endp.
This is an example of simplification, one of the main proof techniques
used by the theorem prover.

See *note The Expansion of ENDP in the Induction Step (Step 0):: if you
would like to step through the simplification of Subgoal *1/2.


File: acl2-doc-emacs.info,  Node: Overview of the Final Simplification in the Base Case,  Next: Overview of the Proof of a Trivial Consequence,  Prev: Overview of the Expansion of ENDP in the Induction Step,  Up: Pages Written Especially for the Tours

Overview of the Final Simplification in the Base Case    Overview of the Final Simplification in the Base Case

The But is our signal that the goal is proved.

See *note The Final Simplification in the Base Case (Step 0):: to step
through the proof.  It is very simple.


File: acl2-doc-emacs.info,  Node: Overview of the Proof of a Trivial Consequence,  Next: Overview of the Simplification of the Base Case to T,  Prev: Overview of the Final Simplification in the Base Case,  Up: Pages Written Especially for the Tours

Overview of the Proof of a Trivial Consequence    Overview of the Proof of a Trivial Consequence

Next on the Walking Tour:  *note The End of the Walking Tour::

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

     ACL2 Warning [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 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
     Time:  0.20 seconds (prove: 0.02, print: 0.00, other: 0.18)
      TRIVIAL-CONSEQUENCE

You might explore the links before moving on.

Next on the Walking Tour:  *note The End of the Walking Tour::


File: acl2-doc-emacs.info,  Node: Overview of the Simplification of the Base Case to T,  Next: Overview of the Simplification of the Induction Conclusion,  Prev: Overview of the Proof of a Trivial Consequence,  Up: Pages Written Especially for the Tours

Overview of the Simplification of the Base Case to T    Overview of the Simplification of the Base Case to T

Next on the Walking Tour:  *note The End of the Proof of the
Associativity of App::

     Subgoal *1/1
     (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 simplification reduces this to T, using the :definition APP and
     primitive type reasoning.

Next on the Walking Tour:  *note The End of the Proof of the
Associativity of App::


File: acl2-doc-emacs.info,  Node: Overview of the Simplification of the Induction Conclusion,  Next: Overview of the Simplification of the Induction Step to T,  Prev: Overview of the Simplification of the Base Case to T,  Up: Pages Written Especially for the Tours

Overview of the Simplification of the Induction Conclusion    Overview of the Simplification of the Induction Conclusion

In this message the system is saying that Subgoal *1/2' has been
rewritten to T using the rules noted.  The word "But" at the beginning
of the sentence is a signal that the goal has been proved.

See *note The Simplification of the Induction Conclusion (Step 0):: to
step through the proof of Subgoal *1/2'.


File: acl2-doc-emacs.info,  Node: Overview of the Simplification of the Induction Step to T,  Next: Perhaps,  Prev: Overview of the Simplification of the Induction Conclusion,  Up: Pages Written Especially for the Tours

Overview of the Simplification of the Induction Step to T    Overview of the Simplification of the Induction Step to T

Next on the Walking Tour:  *note Overview of the Simplification of the
Base Case to T::

     Subgoal *1/2
     (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 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 simplification reduces this to T, using the :definition APP, the
     :rewrite rules CDR-CONS and CAR-CONS and primitive type reasoning.

Next on the Walking Tour:  *note Overview of the Simplification of the
Base Case to T::


File: acl2-doc-emacs.info,  Node: Perhaps,  Next: Popping out of an Inductive Proof,  Prev: Overview of the Simplification of the Induction Step to T,  Up: Pages Written Especially for the Tours

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


File: acl2-doc-emacs.info,  Node: Popping out of an Inductive Proof,  Next: Proving Theorems about Models,  Prev: Perhaps,  Up: Pages Written Especially for the Tours

Popping out of an Inductive Proof    Popping out of an Inductive Proof

Recall that our induction scheme (see *note The Proof of the
Associativity of App:: to revisit it) had two cases, the induction step
(Subgoal *1/2) and the base case (Subgoal *1/1).  Both have been proved!


File: acl2-doc-emacs.info,  Node: Proving Theorems about Models,  Next: Revisiting the Admission of App,  Prev: Popping out of an Inductive Proof,  Up: Pages Written Especially for the Tours

Proving Theorems about Models    Proving Theorems about Models

Next on the Flying Tour:  *note What is Required of the User(Q)::

But ACL2 is a logic.  We can prove theorems about the model.

     Theorem.  MC 'mult is a multiplier
     (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 mc machine will
correctly multiply any two natural numbers.

It is a statement about an infinite number of test cases!

We know it is true about the model because we proved 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 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 mc.

Next on the Flying Tour:  *note What is Required of the User(Q)::


File: acl2-doc-emacs.info,  Node: Revisiting the Admission of App,  Next: Rewrite Rules are Generated from DEFTHM Events,  Prev: Proving Theorems about Models,  Up: Pages Written Especially for the Tours

Revisiting the Admission of App    Revisiting the Admission of App

Next on the Walking Tour:  *note Evaluating App on Sample Input::

Here is the definition of app 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, except those marked <>.  Then come
back here.

     ACL2 !>(defun app (x y)
       (cond ((endp x) y)
             (t (cons (car x)
                      (app (cdr x) y)))))


     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))
     Warnings:  None
     Time:  0.03 seconds (prove: 0.00, print: 0.00, other: 0.03)
      APP

Next on the Walking Tour:  *note Evaluating App on Sample Input::


File: acl2-doc-emacs.info,  Node: Rewrite Rules are Generated from DEFTHM Events,  Next: Running Models,  Prev: Revisiting the Admission of App,  Up: Pages Written Especially for the Tours

Rewrite Rules are Generated from DEFTHM Events    Rewrite Rules are Generated from DEFTHM Events

Next on the Walking Tour:  *note You Must Think about the Use of a
Formula as a Rule::

By reading the documentation of defthm <> (and especially of its
:rule-classes <> argument) you would learn that when we submitted the
command

     (defthm associativity-of-app
       (equal (app (app a b) c)
              (app a (app b c))))

we not only command the system to prove that app is an associative
function but

       * we commanded it to use that fact as a rewrite rule.

That means that every time the system encounters a term of the form

     (app (app x y) z)

it will replace it with

     (app x (app y z))!

Next on the Walking Tour:  *note You Must Think about the Use of a
Formula as a Rule::


File: acl2-doc-emacs.info,  Node: Running Models,  Next: Subsumption of Induction Candidates in App Example,  Prev: Rewrite Rules are Generated from DEFTHM Events,  Up: Pages Written Especially for the Tours

Running Models    Running Models

Next on the Flying Tour:  *note Symbolic Execution of Models::

Suppose the machine being modeled is some kind of arithmetic unit.
Suppose the model can be initialized so as to multiply x times y and
leave the answer in z.  Then if we initialize s to multiply with x=5
and y=7 and run the machine long enough, we can read the answer 35 in
the final state.

Because ACL2 is a programming language, our model can be run or
executed.

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 s creates
a state ready to run a given application on given inputs x and y.)  You
can emulate or test the model of your machine.

This is obvious because ACL2 is Common Lisp; and Common Lisp is a
programming language.

Next on the Flying Tour:  *note Symbolic Execution of Models::


File: acl2-doc-emacs.info,  Node: Subsumption of Induction Candidates in App Example,  Next: Suggested Inductions in the Associativity of App Example,  Prev: Running Models,  Up: Pages Written Especially for the Tours

Subsumption of Induction Candidates in App Example    Subsumption of Induction Candidates in App Example

After collecting induction suggestions from these three terms

     (app a b)

     (app b c)

     (app a (app b c))

the system notices that the first and last suggest the same
decomposition of a: case split on whether a is empty (i.e., (endp a)),
and in the case where it is not empty, recursively process (cdr a).  So
we are left with two ideas about how to induct:

Decompose a as we would to unwind (app a b).

Decompose b as we would to unwind (app b c).


File: acl2-doc-emacs.info,  Node: Suggested Inductions in the Associativity of App Example,  Next: Symbolic Execution of Models,  Prev: Subsumption of Induction Candidates in App Example,  Up: Pages Written Especially for the Tours

Suggested Inductions in the Associativity of App Example    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 a b)

     (app b c)

     (app a (app b c))

The variable recursively decomposed is indicated in bold.


File: acl2-doc-emacs.info,  Node: Symbolic Execution of Models,  Next: The Admission of App,  Prev: Suggested Inductions in the Associativity of App Example,  Up: Pages Written Especially for the Tours

Symbolic Execution of Models    Symbolic Execution of Models

Next on the Flying Tour:  *note Proving Theorems about Models::

But ACL2 is more than a programming language.

Initialize x to 5 and let y be any legal value.

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 symbolic execution because not all of
the parameters are known.

Next on the Flying Tour:  *note Proving Theorems about Models::


File: acl2-doc-emacs.info,  Node: The Admission of App,  Next: The Associativity of App,  Prev: Symbolic Execution of Models,  Up: Pages Written Especially for the Tours

The Admission of App    The Admission of App

Next on the Walking Tour:  *note Revisiting the Admission of App::

Here is what it looks like to submit the definition of app to ACL2:

     ACL2 !>(defun app (x y)
       (cond ((endp x) y)
             (t (cons (car x)
                      (app (cdr x) y)))))

     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))
     Warnings:  None
     Time:  0.03 seconds (prove: 0.00, print: 0.00, other: 0.03)
      APP

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 input and how the system responds.  This little
example shows you what the syntax looks like and is a very typical
successful interaction with the definitional principle.

Let's look at it a little more closely.

Next on the Walking Tour:  *note Revisiting the Admission of App::


File: acl2-doc-emacs.info,  Node: The Associativity of App,  Next: The Base Case in the App Example,  Prev: The Admission of App,  Up: Pages Written Especially for the Tours

The Associativity of App    The Associativity of App

Next on the Walking Tour:  *note The Theorem that App is Associative::

     ACL2!>(let ((a '(1 2))
                 (b '(3 4))
                 (c '(5 6)))
             (equal (app (app a b) c)
                    (app a (app b c))))
     T

Observe that, for the particular a, b, and c above, (app (app a b) c)
returns the same thing as (app a (app b c)).  Perhaps app is
associative.  Of course, to be associative means that the above
property must hold for all values of a, b, and c, not just the ones
tested above.

Wouldn't it be cool if you could type

     ACL2!>(equal (app (app a b) c)
                  (app a (app b c)))

and have ACL2 compute the value T?  Well, you can't!  If you try it,
you'll get an error message!  The message says we can't evaluate that
form because it contains free variables, i.e., variables not given
values.  See *note 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.

Next on the Walking Tour:  *note The Theorem that App is Associative::


File: acl2-doc-emacs.info,  Node: The Base Case in the App Example,  Next: The End of the Flying Tour,  Prev: The Associativity of App,  Up: Pages Written Especially for the Tours

The Base Case in the App Example    The Base Case in the App Example

This formula is the Base Case.  It consists of two parts, a test
identifying the non-inductive case and the conjecture to prove.

     (IMPLIES (ENDP A)                 ; Test
              (:P A B C))              ; Conjecture

When we prove this we can assume

       * A is empty

and we have to prove the conjecture for A.


File: acl2-doc-emacs.info,  Node: The End of the Flying Tour,  Next: The End of the Proof of the Associativity of App,  Prev: The Base Case in the App Example,  Up: Pages Written Especially for the Tours

The End of the Flying Tour    The End of the Flying Tour

This completes the Flying Tour.

We recommend that you now take A Walking Tour of ACL2.

Thanks.
Matt Kaufmann and J Moore

Next on the Walking Tour:  *note A Walking Tour of ACL2::


File: acl2-doc-emacs.info,  Node: The End of the Proof of the Associativity of App,  Next: The End of the Walking Tour,  Prev: The End of the Flying Tour,  Up: Pages Written Especially for the Tours

The End of the Proof of the Associativity of App    The End of the Proof of the Associativity of App

Next on the Walking Tour:  *note Guiding the ACL2 Theorem Prover::

     That completes the proof of *1.

     Q.E.D.

     Summary
     Form:  ( DEFTHM ASSOCIATIVITY-OF-APP ...)
     Rules: ((: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, print: 0.05, other: 0.12)
      ASSOCIATIVITY-OF-APP

Next on the Walking Tour:  *note Guiding the ACL2 Theorem Prover::


File: acl2-doc-emacs.info,  Node: The End of the Walking Tour,  Next: The Event Summary,  Prev: The End of the Proof of the Associativity of App,  Up: Pages Written Especially for the Tours

The End of the Walking Tour    The End of the Walking Tour

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

Next on the Flying Tour:  *note A Flying Tour of ACL2:: Next on the
Walking Tour:  *note A Walking Tour of ACL2::


File: acl2-doc-emacs.info,  Node: The Event Summary,  Next: The Expansion of ENDP in the Induction Step (Step 0),  Prev: The End of the Walking Tour,  Up: Pages Written Especially for the Tours

The Event Summary    The Event Summary

At the conclusion of most events (see *note About the Prompt:: for a
brief discussion of events or see *note EVENTS:: <>), ACL2 prints a
summary.  The summary for app 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 *note RUNE::) <>)
which are list-structured names for rules in the ACL2 database or
"world" <>.  Using theories <> 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 app) 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 state <> 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 APP is the value of the defun 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 APP), and the final state <>).  See
*note LD-POST-EVAL-PRINT:: <> for some details.  If you really want to
follow that link, however, you might see *note LD:: <> first.

You should now return to the Walking Tour.


File: acl2-doc-emacs.info,  Node: The Expansion of ENDP in the Induction Step (Step 0),  Next: The Expansion of ENDP in the Induction Step (Step 1),  Prev: The Event Summary,  Up: Pages Written Especially for the Tours

The Expansion of ENDP in the Induction Step (Step 0)    The Expansion of ENDP in the Induction Step (Step 0)

     Subgoal *1/2
     (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)))).

Click on the link above (the open parenthesis before ENDP) to replace
(ENDP A) by its definition.


File: acl2-doc-emacs.info,  Node: The Expansion of ENDP in the Induction Step (Step 1),  Next: The Expansion of ENDP in the Induction Step (Step 2),  Prev: The Expansion of ENDP in the Induction Step (Step 0),  Up: Pages Written Especially for the Tours

The Expansion of ENDP in the Induction Step (Step 1)    The Expansion of ENDP in the Induction Step (Step 1)

     Subgoal *1/2
     (IMPLIES (AND (NOT (NOT (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)))).

The bold text is the instantiated definition of ENDP.

Now click on the link above to simplify (NOT (NOT (CONSP A)))


File: acl2-doc-emacs.info,  Node: The Expansion of ENDP in the Induction Step (Step 2),  Next: The Falling Body Model,  Prev: The Expansion of ENDP in the Induction Step (Step 1),  Up: Pages Written Especially for the Tours

The Expansion of ENDP in the Induction Step (Step 2)    The Expansion of ENDP in the Induction Step (Step 2)

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

Note that this is Subgoal *1/2'.

You may see *note Overview of the Simplification of the Induction Step
to T:: to return to the main proof.


File: acl2-doc-emacs.info,  Node: The Falling Body Model,  Next: The Final Simplification in the Base Case (Step 0),  Prev: The Expansion of ENDP in the Induction Step (Step 2),  Up: Pages Written Especially for the Tours

The Falling Body Model    The Falling Body Model

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


File: acl2-doc-emacs.info,  Node: The Final Simplification in the Base Case (Step 0),  Next: The Final Simplification in the Base Case (Step 1),  Prev: The Falling Body Model,  Up: Pages Written Especially for the Tours

The Final Simplification in the Base Case (Step 0)    the Final Simplification in the Base Case (Step 0)

     Subgoal *1/1'
     (IMPLIES (NOT (CONSP A))
              (EQUAL (APP (APP A B) C)
                     (APP A (APP B C)))).

Click on the link above to replace (APP A B) by its definition.  Note
that the hypothesis (NOT (CONSP A)) allows us to simplify the IF in APP
to its false branch this time.


File: acl2-doc-emacs.info,  Node: The Final Simplification in the Base Case (Step 1),  Next: The Final Simplification in the Base Case (Step 2),  Prev: The Final Simplification in the Base Case (Step 0),  Up: Pages Written Especially for the Tours

The Final Simplification in the Base Case (Step 1)    the Final Simplification in the Base Case (Step 1)

     Subgoal *1/1'
     (IMPLIES (NOT (CONSP A))
              (EQUAL (APP B C)
                     (APP A (APP B C)))).

Click on the link above to expand the definition of APP.  Again, we
come out through the false branch because of the hypothesis.


File: acl2-doc-emacs.info,  Node: The Final Simplification in the Base Case (Step 2),  Next: The Final Simplification in the Base Case (Step 3),  Prev: The Final Simplification in the Base Case (Step 1),  Up: Pages Written Especially for the Tours

The Final Simplification in the Base Case (Step 2)    the Final Simplification in the Base Case (Step 2)

     Subgoal *1/1'
     (IMPLIES (NOT (CONSP A))
              (EQUAL (APP B C)
                     (APP B C))).

Click on the link above to use the Axiom (EQUAL x x) = t


File: acl2-doc-emacs.info,  Node: The Final Simplification in the Base Case (Step 3),  Next: The First Application of the Associativity Rule,  Prev: The Final Simplification in the Base Case (Step 2),  Up: Pages Written Especially for the Tours

The Final Simplification in the Base Case (Step 3)    the Final Simplification in the Base Case (Step 3)

     Subgoal *1/1'
     (IMPLIES (NOT (CONSP A))
              T)

Now that its conclusion is identically T the IMPLIES will simplify to T
(not shown) and we are done with Subgoal *1/1'.

You may see *note Overview of the Simplification of the Base Case to T::
to return to the main proof.


File: acl2-doc-emacs.info,  Node: The First Application of the Associativity Rule,  Next: The Induction Scheme Selected for the App Example,  Prev: The Final Simplification in the Base Case (Step 3),  Up: Pages Written Especially for the Tours

The First Application of the Associativity Rule    The First Application of the Associativity Rule

So here we see our associativity rule being used!

The rewriter sweeps the conjecture in a leftmost innermost 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:

     Current Conjecture:
     (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)))))


File: acl2-doc-emacs.info,  Node: The Induction Scheme Selected for the App Example,  Next: The Induction Step in the App Example,  Prev: The First Application of the Associativity Rule,  Up: Pages Written Especially for the Tours

The Induction Scheme Selected for the App Example    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 (APP A B) applied to (P A B C).

It is a conjunction (AND <>) of two formulas.

The first is the induction step and the second is the base case.


File: acl2-doc-emacs.info,  Node: The Induction Step in the App Example,  Next: The Instantiation of the Induction Scheme,  Prev: The Induction Scheme Selected for the App Example,  Up: Pages Written Especially for the Tours

The Induction Step in the App Example    The Induction Step in the App Example

This formula is the Induction Step.  It basically consists of three
parts, a test identifying the inductive case, an induction hypothesis
and an induction conclusion.

     (IMPLIES (AND (NOT (ENDP A))      ; Test
                   (:P (CDR A) B C))   ; Induction Hypothesis
              (:P A B C))              ; Induction Conclusion

When we prove this we can assume

       * A is not empty, and that

       * the associativity conjecture holds for a ``smaller'' version of
         A, namely, (CDR A).

Under those hypotheses we have to prove the associativity conjecture
for A itself.


File: acl2-doc-emacs.info,  Node: The Instantiation of the Induction Scheme,  Next: The Justification of the Induction Scheme,  Prev: The Induction Step in the App Example,  Up: Pages Written Especially for the Tours

The Instantiation of the Induction Scheme    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 :P by the
associativity conjecture (instantiated as shown in the scheme).

This produces two actual goals, the induction step and the base case.


File: acl2-doc-emacs.info,  Node: The Justification of the Induction Scheme,  Next: The Proof of the Associativity of App,  Prev: The Instantiation of the Induction Scheme,  Up: Pages Written Especially for the Tours

The Justification of the Induction Scheme    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 (APP A B) terminates.


File: acl2-doc-emacs.info,  Node: The Proof of the Associativity of App,  Next: The Q.E.D. Message,  Prev: The Justification of the Induction Scheme,  Up: Pages Written Especially for the Tours

The Proof of the Associativity of App    The Proof of the Associativity of App

Next on the Walking Tour:  *note Overview of the Simplification of the
Induction Step to T::

Here is the theorem prover's output when it processes the defthm command
for the associativity of app.  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.

     ACL2!>(defthm associativity-of-app
             (equal (app (app a b) c)
                    (app a (app b c))))

     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 (APP A B).  If we
     let  (:P A B C) denote *1 above then the induction scheme we'll use
     is
     (AND
        (IMPLIES (AND (NOT (ENDP A))
                      (:P (CDR A) B C))
                 (:P A B C))
        (IMPLIES (ENDP A) (:P A B C))).
     This induction is justified 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 to the goal at hand the above induction
     scheme produces the following two nontautological subgoals.

Next on the Walking Tour:  *note Overview of the Simplification of the
Induction Step to T::


File: acl2-doc-emacs.info,  Node: The Q.E.D. Message,  Next: The Rules used in the Associativity of App Proof,  Prev: The Proof of the Associativity of App,  Up: Pages Written Especially for the Tours

The Q.E.D. Message    The Q.E.D. Message

Q.E.D. stands for "quod erat demonstrandum" which is Latin for "which
was to be demonstrated" and is the signal that a proof is completely
done.


File: acl2-doc-emacs.info,  Node: The Rules used in the Associativity of App Proof,  Next: The Simplification of the Induction Conclusion (Step 0),  Prev: The Q.E.D. Message,  Up: Pages Written Especially for the Tours

The Rules used in the Associativity of App Proof    The Rules used in the Associativity of App Proof

Note that under Rules we list the runes <> of all the rules used in the
proof.  This list says that we used the rewrite rules CAR-CONS and
CDR-CONS, the definitions of the functions NOT, ENDP and APP, and
primitive type reasoning (which is how we simplified the IF and EQUAL
terms).

For what it is worth, IMPLIES and AND are actually macros <> that are
expanded into IF expressions before the proof ever begins.  The use of
macros is not reported among the rules.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 0),  Next: The Simplification of the Induction Conclusion (Step 1),  Prev: The Rules used in the Associativity of App Proof,  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 0)    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 (APP A B) C)
                     (APP A (APP B C)))).

Click on the link above to replace (APP A B) by its definition.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 1),  Next: The Simplification of the Induction Conclusion (Step 10),  Prev: The Simplification of the Induction Conclusion (Step 0),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 1)    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 (IF (CONSP A)
                              (CONS (CAR A) (APP (CDR A) B))
                              B)
                          C)
                     (APP A (APP B C)))).

Note that the IF expression above is the simplified body of APP.  But
we know the test (CONSP A) is true, by the first hypothesis.  Click on
the link above to replace the test by T.  Actually this step and several
subsequent ones are done during the simplification of the body of APP
but we want to illustrate the basic principles of simplification without
bothering with every detail.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 10),  Next: The Simplification of the Induction Conclusion (Step 11),  Prev: The Simplification of the Induction Conclusion (Step 1),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 10)    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))))
              (EQUAL (APP (APP (CDR A) B) C)
                     (APP (CDR A) (APP B C)))).

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


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 11),  Next: The Simplification of the Induction Conclusion (Step 12),  Prev: The Simplification of the Induction Conclusion (Step 10),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 11)    the Simplification of the Induction Conclusion (Step 11)

     Subgoal *1/2'
     (IMPLIES (AND (CONSP A)
                   (EQUAL (APP (APP (CDR A) B) C)
                          (APP (CDR A) (APP B C))))
              T)

Click on the link above to use the definition of IMPLIES.  Since the
conclusion of the implication is now identically T, the implication
simplifies to T.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 12),  Next: The Simplification of the Induction Conclusion (Step 2),  Prev: The Simplification of the Induction Conclusion (Step 11),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 12)    the Simplification of the Induction Conclusion (Step 12)

     Subgoal *1/2'
     T

So, indeed, Subgoal *1/2' does simplify to T!

You can see that even in an example as simple as this one, quite a lot
happens in simplification.

You may see *note Overview of the Simplification of the Induction Step
to T:: to return to the main proof.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 2),  Next: The Simplification of the Induction Conclusion (Step 3),  Prev: The Simplification of the Induction Conclusion (Step 12),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 2)    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 (IF T
                              (CONS (CAR A) (APP (CDR A) B))
                              B)
                          C)
                     (APP A (APP B C)))).

Click on the link above to apply the Axiom (IF T x y) = x.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 3),  Next: The Simplification of the Induction Conclusion (Step 4),  Prev: The Simplification of the Induction Conclusion (Step 2),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 3)    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 (APP (CONS (CAR A) (APP (CDR A) B))
                          C)
                     (APP A (APP B C)))).

Click on the link above to expand the definition of APP here.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 4),  Next: The Simplification of the Induction Conclusion (Step 5),  Prev: The Simplification of the Induction Conclusion (Step 3),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 4)    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 (CONSP (CONS (CAR A) (APP (CDR A) B)))
                         (CONS (CAR (CONS (CAR A) (APP (CDR A) B)))
                               (APP (CDR (CONS (CAR A) (APP (CDR A) B)))
                                    C))
                         C)
                     (APP A (APP B C)))).

Click on the link above to apply the Axiom (CONSP (CONS x y)) = T.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 5),  Next: The Simplification of the Induction Conclusion (Step 6),  Prev: The Simplification of the Induction Conclusion (Step 4),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 5)    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 T
                         (CONS (CAR (CONS (CAR A) (APP (CDR A) B)))
                               (APP (CDR (CONS (CAR A) (APP (CDR A) B)))
                                    C))
                         C)
                     (APP A (APP B C)))).

Click on the link above to apply the Axiom (CAR (CONS x y)) = x.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 6),  Next: The Simplification of the Induction Conclusion (Step 7),  Prev: The Simplification of the Induction Conclusion (Step 5),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 6)    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 (CAR A)
                               (APP (CDR (CONS (CAR A) (APP (CDR A) B)))
                                    C))
                         C)
                     (APP A (APP B C)))).

Click on the link above to apply the Axiom (CDR (CONS x y)) = y.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 7),  Next: The Simplification of the Induction Conclusion (Step 8),  Prev: The Simplification of the Induction Conclusion (Step 6),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 7)    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 (IF T
                         (CONS (CAR A)
                               (APP (APP (CDR A) B)
                                    C))
                         C)
                     (APP A (APP B C)))).

Click on the link above to apply the Axiom (IF T x y) = x.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 8),  Next: The Simplification of the Induction Conclusion (Step 9),  Prev: The Simplification of the Induction Conclusion (Step 7),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 8)    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 (CONS (CAR A)
                           (APP (APP (CDR A) B)
                                C))
                     (APP A (APP B C)))).

Click on the link above to expand the definition of APP here.  This
time, we'll do the whole expansion at once, including the
simplification of the resulting IF.  This is how ACL2 actually does it.


File: acl2-doc-emacs.info,  Node: The Simplification of the Induction Conclusion (Step 9),  Next: The Summary of the Proof of the Trivial Consequence,  Prev: The Simplification of the Induction Conclusion (Step 8),  Up: Pages Written Especially for the Tours

The Simplification of the Induction Conclusion (Step 9)    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))))
              (EQUAL (CONS (CAR A)
                           (APP (APP (CDR A) B)
                                C))
                     (CONS (CAR A)
                           (APP (CDR A) (APP B C))))).

Click on the link above to apply the Axiom that (EQUAL (CONS x y) (CONS
u v)) is equal to the conjunction of (EQUAL x u) and (EQUAL y v).  In
this case, (EQUAL x u) is trivial, (EQUAL (CAR A) (CAR A)).


File: acl2-doc-emacs.info,  Node: The Summary of the Proof of the Trivial Consequence,  Next: The Theorem that App is Associative,  Prev: The Simplification of the Induction Conclusion (Step 9),  Up: Pages Written Especially for the Tours

The Summary of the Proof of the Trivial Consequence    The Summary of the Proof of the Trivial Consequence

Note that at the conclusion of the proof, the system reminds you of the
earlier Warning.

It is a good idea, when the Q.E.D. flys by, to see if there were any
Warnings.


File: acl2-doc-emacs.info,  Node: The Theorem that App is Associative,  Next: The Time Taken to do the Associativity of App Proof,  Prev: The Summary of the Proof of the Trivial Consequence,  Up: Pages Written Especially for the Tours

The Theorem that App is Associative    The Theorem that App is Associative

Next on the Walking Tour:  *note The Proof of the Associativity of App::

     ACL2!>(defthm associativity-of-app
             (equal (app (app a b) c)
                    (app a (app b c))))

The formula above says app is associative.  The defthm <> command
instructs ACL2 to prove the formula and to name it
associativity-of-app.  Actually, the defthm command also builds the
formula into the database as a rewrite <> 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.

Next on the Walking Tour:  *note The Proof of the Associativity of App::


File: acl2-doc-emacs.info,  Node: The Time Taken to do the Associativity of App Proof,  Next: The Tours,  Prev: The Theorem that App is Associative,  Up: Pages Written Especially for the Tours

The Time Taken to do the Associativity of App Proof    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 Q.E.D. and don't bother to scroll back to read it.  You
have more important things to do than read successful proofs.


File: acl2-doc-emacs.info,  Node: The Tours,  Next: The WARNING about the Trivial Consequence,  Prev: The Time Taken to do the Associativity of App Proof,  Up: Pages Written Especially for the Tours

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.  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
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 reference 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 brower's
Back Button to return to your starting points.

If after all this you want to learn how to use the theorem prover (!),
see *note INTRODUCTION-TO-THE-THEOREM-PROVER::.

To start a tour, click on the appropriate icon below.

Next on the Flying Tour:  *note A Flying Tour of ACL2:: Next on the
Walking Tour:  *note A Walking Tour of ACL2::

For readers using our :DOC or our TexInfo format in Emacs: The tours
will probably be unsatisfying because we use gif files and assume you
can navigate "back."


File: acl2-doc-emacs.info,  Node: The WARNING about the Trivial Consequence,  Next: Undocumented Topic,  Prev: The Tours,  Up: Pages Written Especially for the Tours

The WARNING about the Trivial Consequence    The WARNING about the Trivial Consequence

This Warning alerts us to the fact that when treated as a rewrite rule,
the new rule TRIVIAL-CONSEQUENCE, rewrites terms of the same form as a
rule we have already proved, namely ASSOCIATIVITY-OF-APP.

When you see this warning you should think about your rules!

In the current case, it would be a good idea not to make
TRIVIAL-CONSEQUENCE a rule at all.  We could do this with :rule-classes
<> nil.

ACL2 proceeds to try to prove the theorem, even though it printed some
warnings.  The basic assumption in ACL2 is that the user understands
what he or she is doing but may need a little reminding just to manage
a complicated set of facts.


File: acl2-doc-emacs.info,  Node: Undocumented Topic,  Next: Using the Associativity of App to Prove a Trivial Consequence,  Prev: The WARNING about the Trivial Consequence,  Up: Pages Written Especially for the Tours

Undocumented Topic    Undocumented Topic

This topic has not yet been documented.  Sorry


File: acl2-doc-emacs.info,  Node: Using the Associativity of App to Prove a Trivial Consequence,  Next: What Is ACL2(Q),  Prev: Undocumented Topic,  Up: Pages Written Especially for the Tours

Using the Associativity of App to Prove a Trivial Consequence    Using the Associativity of App to Prove a Trivial Consequence

Next on the Walking Tour:  *note Overview of the Proof of a Trivial
Consequence::

If we have proved the associativity-of-app 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

Next on the Walking Tour:  *note Overview of the Proof of a Trivial
Consequence::


File: acl2-doc-emacs.info,  Node: What Is ACL2(Q),  Next: What is Required of the User(Q),  Prev: Using the Associativity of App to Prove a Trivial Consequence,  Up: Pages Written Especially for the Tours

What Is ACL2(Q)    What Is ACL2?

Next on the Flying Tour:  *note What is a Mathematical Logic(Q)::

ACL2 is a mathematical logic together with a mechanical theorem prover
to help you reason in the logic.

The logic is just a subset of applicative 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.

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

Next on the Flying Tour:  *note What is a Mathematical Logic(Q)::


File: acl2-doc-emacs.info,  Node: What is Required of the User(Q),  Next: What is a Mathematical Logic(Q),  Prev: What Is ACL2(Q),  Up: Pages Written Especially for the Tours

What is Required of the User(Q)    What is Required of the User?

Next on the Flying Tour:  *note 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 understand

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

       * 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
why the model has the desired property -- is the user's responsibility.

Next on the Flying Tour:  *note How Long Does It Take to Become an
Effective User(Q)::


File: acl2-doc-emacs.info,  Node: What is a Mathematical Logic(Q),  Next: What is a Mechanical Theorem Prover(Q),  Prev: What is Required of the User(Q),  Up: Pages Written Especially for the Tours

What is a Mathematical Logic(Q)    What is a Mathematical Logic?

Next on the Flying Tour:  *note What is a Mechanical Theorem Prover(Q)::

A mathematical logic is a formal system of formulas (axioms) and rules
for deriving other formulas, called theorems.

A proof is a derivation of a theorem.  To see a concrete proof tree,
see *note 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, prove it.

Next on the Flying Tour:  *note What is a Mechanical Theorem Prover(Q)::


File: acl2-doc-emacs.info,  Node: What is a Mechanical Theorem Prover(Q),  Next: What is a Mechanical Theorem Prover(Q) (cont),  Prev: What is a Mathematical Logic(Q),  Up: Pages Written Especially for the Tours

What is a Mechanical Theorem Prover(Q)    What is a Mechanical Theorem Prover?

Next on the Flying Tour:  *note What is a Mechanical Theorem Prover(Q)
(cont)::

A mechanical theorem prover is a computer program that finds proofs of
theorems.

The ideal mechanical theorem prover is automatic: 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., propositional calculus) and even then practical
considerations (e.g., how many centuries you are willing to wait) limit
the problems they can solve.

Next on the Flying Tour:  *note What is a Mechanical Theorem Prover(Q)
(cont)::


File: acl2-doc-emacs.info,  Node: What is a Mechanical Theorem Prover(Q) (cont),  Next: You Must Think about the Use of a Formula as a Rule,  Prev: What is a Mechanical Theorem Prover(Q),  Up: Pages Written Especially for the Tours

What is a Mechanical Theorem Prover(Q) (cont)    What is a Mechanical Theorem Prover? (cont)

Next on the Flying Tour:  *note About Models:: To get around this,
mechanical theorem provers often require help from the user.

See *note ACL2 as an Interactive Theorem Prover:: to continue downward.

Next on the Flying Tour:  *note About Models::


File: acl2-doc-emacs.info,  Node: You Must Think about the Use of a Formula as a Rule,  Prev: What is a Mechanical Theorem Prover(Q) (cont),  Up: Pages Written Especially for the Tours

You Must Think about the Use of a Formula as a Rule    You Must Think about the Use of a Formula as a Rule

Next on the Walking Tour:  *note Using the Associativity of App to
Prove a Trivial Consequence::

This is good and bad.

The good news is that you can program ACL2's simplifier.

The bad news is that when you command ACL2 to prove a theorem you must
give some thought to how that theorem is to be used as a rule!

For example, if after proving associativity-of-app 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)))
       :rule-classes nil)

Next on the Walking Tour:  *note Using the Associativity of App to
Prove a Trivial Consequence::


File: acl2-doc-emacs.info,  Node: REAL,  Next: RELEASE-NOTES,  Prev: Pages Written Especially for the Tours,  Up: Top

REAL    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 <your_lisp> with a path
to your Lisp executable:

     make large-acl2r LISP=<your_lisp>

This will create an executable in your acl2-sources directory named
saved_acl2r.

Note that if you download community books as tarfiles, then you should
be sure to download the `nonstd' books, from
`http://acl2-books.googlecode.com/files/nonstd-6.3.tar.gz'.  Then
certify them from your acl2-sources directory, shown here as <DIR>:

     make regression-nonstd ACL2=<DIR>/saved_acl2r

To check that you are running ACL2(r), see if the prompt includes the
string "(r)", e.g.:

     ACL2(r) !>

Or, look at (@ acl2-version) and see if "(r)" is a substring.

In ACL2 (as opposed to ACL2(r)), when we say "real" we mean "rational."

* Menu:

* 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

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.


File: acl2-doc-emacs.info,  Node: I-CLOSE,  Next: I-LARGE,  Prev: REAL,  Up: REAL

I-CLOSE    ACL2(r) test for whether two numbers are infinitesimally close

(I-close x y) is true if and only if x-y is an infinitesimal number.
This predicate is only defined in ACL2(r) (see *note REAL::).


File: acl2-doc-emacs.info,  Node: I-LARGE,  Next: I-LIMITED,  Prev: I-CLOSE,  Up: REAL

I-LARGE    ACL2(r) recognizer for infinitely large numbers

(I-large x) is true if and only if x is non-zero and 1/x is an
infinitesimal number.  This predicate is only defined in ACL2(r) (see
*note REAL::).


File: acl2-doc-emacs.info,  Node: I-LIMITED,  Next: I-SMALL,  Prev: I-LARGE,  Up: REAL

I-LIMITED    ACL2(r) recognizer for limited numbers

(I-limited x) is true if and only if x is a number that is not
infinitely large.  This predicate is only defined in ACL2(r) (see *note
REAL::).


File: acl2-doc-emacs.info,  Node: I-SMALL,  Next: REAL-LISTP,  Prev: I-LIMITED,  Up: REAL

I-SMALL    ACL2(r) recognizer for infinitesimal numbers

(I-small x) is true if and only if x is an infinitesimal number
(possibly 0).  This predicate is only defined in ACL2(r) (see *note
REAL::).


File: acl2-doc-emacs.info,  Node: REAL-LISTP,  Next: STANDARD-PART,  Prev: I-SMALL,  Up: REAL

REAL-LISTP    ACL2(r) recognizer for a true list of real numbers

The predicate real-listp tests whether its argument is a true list of
real numbers.  This predicate is only defined in ACL2(r) (see *note
REAL::).


File: acl2-doc-emacs.info,  Node: STANDARD-PART,  Next: STANDARDP,  Prev: REAL-LISTP,  Up: REAL

STANDARD-PART    ACL2(r) function mapping limited numbers to standard numbers

(Standard-part x) is, for a given i-limited number x, the unique real
number infinitesimally close (see *note I-CLOSE::) to x.  This function
is only defined in ACL2(r) (see *note REAL::).


File: acl2-doc-emacs.info,  Node: STANDARDP,  Prev: STANDARD-PART,  Up: REAL

STANDARDP    ACL2(r) recognizer for standard objects

(Standardp x) is true if and only if x 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 *note I-LIMITED::).

This predicate is only defined in ACL2(r) (see *note REAL::).


File: acl2-doc-emacs.info,  Node: RELEASE-NOTES,  Next: RULE-CLASSES,  Prev: REAL,  Up: Top

RELEASE-NOTES    pointers to what has changed

* Menu:

* 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

* NOTE1:: Acl2 Version 1.1 Notes

* NOTE2:: Acl2 Version 1.2 Notes

* NOTE3:: Acl2 Version 1.3 Notes

* NOTE4:: Acl2 Version 1.4 Notes

* NOTE5:: Acl2 Version 1.5 Notes

* NOTE6:: Acl2 Version 1.6 Notes

* NOTE7:: ACL2 Version 1.7 (released October 1994) Notes

* NOTE8:: ACL2 Version 1.8 (May, 1995) Notes

* NOTE8-UPDATE:: ACL2 Version 1.8 (Summer, 1995) Notes

* NOTE9:: ACL2 Version 1.9 (Fall, 1996) Notes

This section of the online documentation contains notes on the changes
that distinguish successive released versions of ACL2.

The current version of ACL2 is the value of the constant (@
acl2-version).


File: acl2-doc-emacs.info,  Node: NOTE-2-0,  Next: NOTE-2-1,  Prev: RELEASE-NOTES,  Up: RELEASE-NOTES

NOTE-2-0    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.,
FOO, with a LAMBDA expression containing a free variable (a variable
not among in the LAMBDA formals).  And, second, in one of the
constraints being instantiated there is a call of the function symbol
FOO within the scope of another LAMBDA expression.  Unless you used
such a functional substitution, this bug fix will not affect you.

Less important notes:

The implementation of PRINC$ was changed so that it was no longer
sensitive to the external setting of *print-base* and other Common Lisp
special variables.

Typographical errors were fixed in the documentation.


File: acl2-doc-emacs.info,  Node: NOTE-2-1,  Next: NOTE-2-2,  Prev: NOTE-2-0,  Up: RELEASE-NOTES

NOTE-2-1    ACL2 Version  2.1 (December, 1997) Notes

The identity function case-split has been added.  It is similar to
force 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.


File: acl2-doc-emacs.info,  Node: NOTE-2-2,  Next: NOTE-2-3,  Prev: NOTE-2-1,  Up: RELEASE-NOTES

NOTE-2-2    ACL2 Version  2.2 (August, 1998) Notes

Important changes:

A bug was fixed in the compile command, :comp.  The compiled code
produced by :comp in previous versions could be wildly incorrect
because of a confusion between the printer and the reader regarding
what was the current Lisp *package*.  This bug could manifest itself
only if you used the :comp command to compile previously uncompiled
functions while the current package was different from "ACL2".  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 books subdirectories cli-misc and ihs.  Both have README files.
The ihs 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 ihs books to those modeling ALUs and other arithmetic
components of microprocessors or programming languages.

In previous versions of ACL2, the arithmetic books, found on
books/arithmetic/, 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 rationals-with-axioms.lisp, which was
then used in the uppermost arithmetic books top.lisp and
top-with-meta.lisp.  John Cowles has now provided us with ACL2 proofs
of those "axioms" and so in this release you will find both
rationals-with-axioms.lisp and rationals-with-axioms-proved.lisp.  The
former is provided for compatibility's sake.  The latter is identical
but contains defthms where the former contains defaxioms.  The top-most
books have been rebuilt using "-axioms-proved" book.  Thanks John.

Less important notes:

Bishop Brock found a bug in translated-acl2-unwind-protectp4.  Jun
Sawada reported a bug in linear arithmetic that caused us not to prove
certain trivial theorems concluding with (not (equal i j)).  We have
fixed both.

We now prohibit definitions that call certain event commands such as
DEFTHM and TABLE 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.


File: acl2-doc-emacs.info,  Node: NOTE-2-3,  Next: NOTE-2-4,  Prev: NOTE-2-2,  Up: RELEASE-NOTES

NOTE-2-3    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 f, via an encapsulate.
(2) In the same encapsulation, define a clique of mutually recursive
functions.  This clique must be non-local and in :logic mode.
(3) In that mutually recursive clique, use the constrained function f
(perhaps indirectly) so that the termination argument for the clique
depends on properties of the witness for f.  Thus, f or some other
function dependent upon f, must be used in an argument in a recursive
call or in a term governing a recursive call.  Furthermore, the use of
f must be such that the termination proof cannot be done without
exploiting properties of the witness for f.  Other uses of the
constrained functions in the clique are ok.
(4) Fail to include the exploited properties of f among the constraints
of the encapsulation.
(5) Later, outside the encapsulation, explicitly use a functional
instantiation in which f 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 verify-guards was improved to explain why one
might wish to verify the "guards" of a defthm 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.


File: acl2-doc-emacs.info,  Node: NOTE-2-4,  Next: NOTE-2-5,  Prev: NOTE-2-3,  Up: RELEASE-NOTES

NOTE-2-4    ACL2 Version  2.4 (August, 1999) Notes

Important changes:

We corrected a soundness bug in Version 2.3 related to the handling of
immediate-force-modep.  The bad behavior was noticed by Robert Krug.
Thanks!

We corrected a bug that permitted verify-guards 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 ILLEGAL, which is
logically defined to be nil 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 THE or LETs with internal declarations.

We corrected a bug that permitted some LOCAL DEFAXIOM events to slip
into certified books.

We corrected a bug that prevented the correct undoing of certain DEFPKG
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.


File: acl2-doc-emacs.info,  Node: NOTE-2-5,  Next: NOTE-2-5(R),  Prev: NOTE-2-4,  Up: RELEASE-NOTES

NOTE-2-5    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 books 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 books/README.html.

Improved Unix Makefile support for book certification has also been
written.  See books/README.html.

The list of symbols in *acl2-exports* has been considerably expanded.
If you have packages built by importing *acl2-exports* you might want
to look carefully at the new value of that constant.  The new value
includes all :logic mode functions as of Version  2.5, as well as all
documented macros and all built-in theorem names.

Include-book and certify-book were modified to have some additional
keyword arguments.  It is possible to certify a book containing
defaxiom and/or skip-proofs events and get warning messages or errors
signaled, according to the settings of these new flags.  In addition,
it is possible to specify in include-book 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 defaxiom and/or skip-proofs 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
declare ignore.  In past versions of ACL2, a formal parameter of a
defun was considered ignored if it was not used in the body, the guard
or the measure of the defun.  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 *note 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
*note 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 DEFAXIOM or SKIP-PROOFS events.  (Technically,
DEFAXIOMs do not imperil soundness in the proof- theoretic sense,
though they may imperil the validity of theorems.  But you sould know
when a book has added an axiom to your logic!)  In previous versions of
ACL2, all warnings were inhibited if the token warning was included in
the argument to set-inhibit-output-lst.  Now, soundness related
warnings are printed even if warnings have been inhibited.  To inhibit
all warnings, supply the token warning! to set-inhibit-output-lst.

Several bugs in defstobj were fixed, relating to the possibility that
some of the subfunctions introduced by the defstobj were already
defined.

:Puff no longer tries to expand defstobj 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 hide 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 :elim rules was generalized, permitting arbitrary known
equivalence relations instead of merely equal in the concluding
equality.

The printing of runes (rule names; see *note 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
(< 0 X), and more generally, any hypotheses involving a comparison with
0 (even for example (< X 1) where X is known to be an integer, which is
handled as (<= X 0)).  Thanks to Robert Krug for bringing relevant
examples to our attention.

A new value, :comp, has been implemented for the :load-compiled-file
keyword of include-book.  If this value is supplied, then a compiled
file will always be loaded, even if that requires creating the compiled
file first.

The event include-book now generates a warning when a compiled file is
expected but not found (see *note 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 include-book command.

Certain redefinition warnings generated by Allegro Common Lisp have
been eliminated.

A new key has been implemented for the acl2-defaults-table,
:bogus-mutual-recursion-ok, set with :set-bogus-mutual-recursion-ok.
Thanks to David Russinoff for pointing out the utility of such a key.

A bug was fixed in defun-sk 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 defun-sk events to be rejected.  That problem has been fixed,
and an "Infected" warning has also been eliminated.

The command good-bye 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
local event.

A bug has been fixed in the proof-checker 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 :bdd hint in the presence of
equivalence relations.  Thanks to Pete Manolios for bringing this to our
attention with a simple example.

The functions position and position-equal 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 true-listp 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 let* 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 hard-error and prog2$, and the
documentation for illegal has been improved.  Thanks to Rob Sumners for
a useful suggestion in the examples in documentation for prog2$ and a
fix in documentation for sublis.

The event form certify-book 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 stobjs 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
(set-verify-guards-eagerness 2).  This has been fixed.

The keyword command :comp can now be used to compile only raw Lisp
functions, excluding executable counterparts, by supplying the argument
:raw.

Rewrite rule nth-of-character-listp was removed from source file
axioms.lisp since it is essentially subsumed by characterp-nth.

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 print-object$ now print
characters in lower case for a symbol when the ACL2 state global
variable print-case has value :downcase and vertical bars are not
necessary for printing that symbol.  See *note IO:: for a discussion of
the macros acl2-print-case and set-acl2-print-case.  The default
printing remains unchanged, i.e., symbols are printed in upper case
when vertical bars are not required.

A low-level printing function (prin1$) was modified so that it is not
sensitive to various Common Lisp globals related to printing.  So for
example, the function fmt is no longer sensitive to the value of Common
Lisp global *print-case*.  (The preceding paragraph explains how to
control the case for printing in ACL2.)

The definition of array1p was fixed so that the :maximum-length of an
array must be strictly greater than the number specified in the
:dimensions field; they may no longer be equal.  This was always the
intention; the documentation (see *note ARRAYS::) has remained
unchanged.  The corresponding change was also made to array2p.  Allegro
Common Lisp formerly caused an error when compress1 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 :definition rune, as it has done in earlier versions of
ACL2, but also the corresponding :induction rune.  See *note 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 (in-theory (current-theory 'foo))
followed by (in-theory (enable bar)), where function bar is introduced
after event foo, and bar is recursively defined.  The latter in-theory
form now enables the rune (:induction bar), which implies that the
prover can use the induction scheme stored at definition time for bar.
Formerly, the rune (:induction bar) was not enabled by (in-theory
(enable bar)), and hence the induction scheme for bar was ignored even
when explicit :induct hints were supplied.

You may now supply xargs keyword pair :normalize nil in order to
prevent certain definitions from "hanging" when there are many
if-subexpressions.  see *note DEFUN::.

We now translate type declarations of real into guards, as we have
already done for other types such as rational.  For example, (declare
(type real x)) generates the guard (rationalp x).  See *note
TYPE-SPEC::.

The theorem prover now behaves reasonably under the combination of
specifying a value of t both for :otf-flg and for a hint
:do-not-induct.  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 round.  However, we believe that
the new definition is equivalent to the old.

The definition of Common Lisp function substitute 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 "/" character even when the operating system is not Unix or
     Linux.  See *note PATHNAME::.  ACL2 also continues to support its
     notion of _structured pathnames_ from Version  2.4 and before, but
     might not do so in future releases and hence no longer documents
     such syntax.

     (2) The command :set-cbd may now take a relative pathname as an
     argument.

     (3) When the macro ld is given a file name as a value for
     standard-oi, then if that file name is a relative pathname it
     refers to the result of prepending the connected book directory
     (see *note PATHNAME::, see *note CBD::, and see *note SET-CBD::)
     in order to obtain an absolute pathname.  Simiarly for the ld
     specials standard-co and proofs-co.

It is no longer necessary to issue :set-state-ok t if you include a
stobj declaration for state, for example:

     (declare (xargs :stobjs state))

See *note DECLARE-STOBJS::.

The proof-checker has been cleaned up a bit, including the
documentation and the capability (once again) to define pc-macro
commands (see *note DEFINE-PC-MACRO::) and proof-checker meta commands
(see *note DEFINE-PC-META::).

Recall that events generate summaries that include a line beginning
with "Warnings:", 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 encapsulate or include-book
event did not include the summary strings for warnings generated by
subsidiary events.  This has been fixed.

Macro cw has been documented and now expands to a call of a ;logic mode
function.  See *note CW:: for a way to print to the screen without
having to involve the ACL2 state.  Thanks to Rob Sumners for suggesting
that we document this useful utility.

Functions duplicates, add-to-set-equal, intersection-eq, evens, and
odds are now :logic mode functions.


File: acl2-doc-emacs.info,  Node: NOTE-2-5(R),  Next: NOTE-2-6,  Prev: NOTE-2-5,  Up: RELEASE-NOTES

NOTE-2-5(R)    ACL2 Version  2.5(r) (June, 2000) Notes

Important changes to non-standard version:

Please see *note NOTE-2-5:: for changes to Version  2.5 of ACL2.  We
hope to write more documentation for ACL2(r) in the future.


File: acl2-doc-emacs.info,  Node: NOTE-2-6,  Next: NOTE-2-6(R),  Prev: NOTE-2-5(R),  Up: RELEASE-NOTES

NOTE-2-6    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.

     o New functionality (see *note NOTE-2-6-NEW-FUNCTIONALITY::):
     o Changes in proof engine (see *note NOTE-2-6-PROOFS::):
     o Changes in rules and definitions (see *note NOTE-2-6-RULES::):
     o Guard-related changes (see *note NOTE-2-6-GUARDS::):
     o Proof-checker changes (see *note NOTE-2-6-PROOF-CHECKER::):
     o System-level changes (see *note NOTE-2-6-SYSTEM::):
     o Other (minor) changes (see *note NOTE-2-6-OTHER::):

* Menu:

* 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-CHECKER:: ACL2 Version  2.6 Notes on Proof-checker 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


File: acl2-doc-emacs.info,  Node: NOTE-2-6-GUARDS,  Next: NOTE-2-6-NEW-FUNCTIONALITY,  Prev: NOTE-2-6,  Up: NOTE-2-6

NOTE-2-6-GUARDS    ACL2 Version  2.6 Notes on Guard-related Changes

When you declare that a function treats certain formals as :stobjs, the
guard of the function is automatically extended to include the
corresponding stobj-recognizer calls.  For example, if a definition
includes (declare (xargs :stobjs (ST))) then the guard of the function
is changed by the addition of the conjunct (ST-P ST).

One impact of this is that if you use the built-in ACL2 state as a
formal parameter of a function, (STATE-P STATE) 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
verify-guards, while in the new version, we would attempt guard
verification.  You may wish to add (declare (xargs :verify-guards nil))
to such definitions.

A related change affects users who do not use stobjs or state.  In
previous versions of the system -- as now -- a type declaration
extended the guard you provided explicitly.  Thus, if you wrote
(declare (type integer n)) then (INTEGERP n) was added to your guard.
This is still the case and :stobjs 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 (and (integerp n) (integerp n))
where the first was produced by your type declaration and the second
was your :guard.  We now eliminate redundant conjuncts; this may
rearrange the order of the conjuncts.

The guard conjectures for functions using stobjs 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 *note
STANDARD-CHAR-P:: and see *note STANDARD-CHAR-LISTP::.)

     upper-case-p lower-case-p char-upcase char-downcase
     string-downcase1 string-downcase string-upcase1 string-upcase
     char-equal string-equal1 string-equal

Also, function standard-string-alistp replaces function string-alistp,
with concomitant changes in the guard to assoc-string-equal, and in
variable *acl2-exports*.  Also, lemma
standard-string-alistp-forward-to-alistp replaces lemma
string-alistp-forward-to-alistp.  There is a new lemma
standard-char-p-nth, which has also been added to *acl2-exports*.

The guard had been inadvertently omitted from the definition of the
function substitute (and its subroutine substitute-ac).  This omission
has been corrected; also, the guard is slightly stronger than the
documentation had claimed (and that has been corrected).

