(atomic macro) attempt an equality (or equivalence) substitution

=     -- replace the current subterm by a term equated to it in
         one of the hypotheses (if such a term exists)
(= x) -- replace the current subterm by x, assuming that the prover
         can show that they are equal
(= (+ x y) z)
      -- replace the term (+ x y) by the term z inside the current
         subterm, assuming that the prover can prove
         (equal (+ x y) z) from the current top-level hypotheses
         or that this term or (equal z (+ x y)) is among the
         current top-level hypotheses or the current governors
(= & z)
      -- exactly the same as above, if (+ x y) is the current
(= (+ x y) z :hints :none)
      -- same as (= (+ x y) z), except that a new subgoal is
         created with the current goal's hypotheses and governors
         as its top-level hypotheses and (equal (+ x y) z) as its
(= (+ x y) z 0)
      -- exactly the same as immediately above
(= (p x)
   (p y)
   :equiv iff
   :otf-flg t
   :hints (("Subgoal 2" :BY FOO) ("Subgoal 1" :use bar)))
      -- same as (= (+ x y) z), except that the prover uses
         the indicated values for otf-flg and hints, and only
         propositional (iff) equivalence is used (however, it
         must be that only propositional equivalence matters at
         the current subterm)

General Form:
(= &optional x y &rest keyword-args)
If terms x and y are supplied, then replace x by y inside the current subterm if they are ``known'' to be ``equal''. Here ``known'' means the following: the prover is called as in the prove command (using keyword-args) to prove (equal x y), except that a keyword argument :equiv is allowed, in which case (equiv x y) is proved instead, where equiv is that argument. (See below for how governors are handled.)

Actually, keyword-args is either a single non-keyword or is a list of the form ((kw-1 x-1) ... (kw-n x-n)), where each kw-i is one of the keywords :equiv, :otf-flg, :hints. Here :equiv defaults to equal if the argument is not supplied or is nil, and otherwise should be the name of an ACL2 equivalence relation. :Otf-flg and :hints give directives to the prover, as explained above and in the documentation for the prove command; however, no prover call is made if :hints is a non-nil atom or if keyword-args is a single non-keyword (more on this below).

Remarks on defaults

(1) If there is only one argument, say a, then x defaults to the current subterm, in the sense that x is taken to be the current subterm and y is taken to be a.

(2) If there are at least two arguments, then x may be the symbol &, which then represents the current subterm. Thus, (= a) is equivalent to (= & a). (Obscure point: actually, & can be in any package, except the keyword package.)

(3) If there are no arguments, then we look for a top-level hypothesis or a governor of the form (equal c u) or (equal u c), where c is the current subterm. In that case we replace the current subterm by u.

As with the prove command, we allow goals to be given ``bye''s in the proof, which may be generated by a :hints keyword argument in keyword-args. These result in the creation of new subgoals.

A proof is attempted unless the :hints argument is a non-nil atom other than :none, or unless there is one element of keyword-args and it is not a keyword. In that case, if there are any hypotheses in the current goal, then what is attempted is a proof of the implication whose antecedent is the conjunction of the current hypotheses and governors and whose conclusion is the appropriate equal term.

Remarks: (1) It is allowed to use abbreviations in the hints. (2) The keyword :none has the special role as a value of :hints that is shown clearly in an example above. (3) If there are governors, then the new subgoal has as additional hypotheses the current governors.