File: entries.tex

package info (click to toggle)
hol88 2.02.19940316dfsg-8
links: PTS
area: main
in suites: sid
size: 65,960 kB
sloc: ml: 199,939; ansic: 9,666; sh: 6,913; makefile: 6,032; lisp: 2,747; yacc: 894; sed: 201; cpp: 87; awk: 5
file content (27922 lines) | stat: -rw-r--r-- 852,613 bytes
parent folder | download | duplicates (9)
\chapter{Pre-defined ML Identifiers}\input{entries-intro}\DOC{ABS\_CONV}

\TYPE {\small\verb%ABS_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion to the body of an abstraction.

\DESCRIBE
If {\small\verb%c%} is a conversion that maps a term {\small\verb%"t"%} to the theorem {\small\verb%|- t = t'%}, then
the conversion {\small\verb%ABS_CONV c%} maps abstractions of the form {\small\verb%"\x.t"%} to theorems
of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\x.t) = (\x.t')
\end{verbatim}
}
\noindent That is, {\small\verb%ABS_CONV c "\x.t"%} applies {\small\verb%c%} to the body of the
abstraction {\small\verb%"\x.t"%}.

\FAILURE
{\small\verb%ABS_CONV c tm%} fails if {\small\verb%tm%} is not an abstraction or if {\small\verb%tm%} has the form
{\small\verb%"\x.t"%} but the conversion {\small\verb%c%} fails when applied to the term {\small\verb%t%}. The
function returned by {\small\verb%ABS_CONV c%} may also fail if the ML function
{\small\verb%c:term->thm%} is not, in fact, a conversion (i.e. a function that maps a term
{\small\verb%t%} to a theorem {\small\verb%|- t = t'%}).

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ABS_CONV SYM_CONV "\x. 1 = x";;
|- (\x. 1 = x) = (\x. x = 1)
\end{verbatim}
}
\SEEALSO
RAND_CONV, RATOR_CONV, SUB_CONV.

\ENDDOC
\DOC{ABS}

\TYPE {\small\verb%ABS : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Abstracts both sides of an equation.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
         A |- t1 = t2
   ------------------------  ABS "x"            [Where x is not free in A]
    A |- (\x.t1) = (\x.t2)
\end{verbatim}
}
\FAILURE
If the theorem is not an equation, or if the variable {\small\verb%x%} is free in the
assumptions {\small\verb%A%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ABS "m:num" (REFL "m:num");;
|- (\m. m) = (\m. m)
\end{verbatim}
}
\SEEALSO
ETA_CONV, EXT, MK_ABS.

\ENDDOC
\DOC{abs\_goals}

\TYPE {\small\verb%abs_goals : (subgoals list -> goalstack)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{ACCEPT\_TAC}

\TYPE {\small\verb%ACCEPT_TAC : thm_tactic%}\egroup

\SYNOPSIS
Solves a goal if supplied with the desired theorem (up to alpha-conversion).

\DESCRIBE
{\small\verb%ACCEPT_TAC%} maps a given theorem {\small\verb%th%} to a tactic that solves any goal whose
conclusion is alpha-convertible to the conclusion of {\small\verb%th%}.

\FAILURE
{\small\verb%ACCEPT_TAC th (A,g)%} fails if the term {\small\verb%g%} is not alpha-convertible to the
conclusion of the supplied theorem {\small\verb%th%}.

\EXAMPLE
{\small\verb%ACCEPT_TAC%} applied to the axiom
{\par\samepage\setseps\small
\begin{verbatim}
   BOOL_CASES_AX = |- !t. (t = T) \/ (t = F)
\end{verbatim}
}
\noindent will solve the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- !x. (x = T) \/ (x = F)
\end{verbatim}
}
\noindent but will fail on the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- !x. (x = F) \/ (x = T)
\end{verbatim}
}
\USES
Used for completing proofs by supplying an existing theorem, such as an axiom,
or a lemma already proved.

\SEEALSO
MATCH_ACCEPT_TAC.

\ENDDOC
\DOC{AC\_CONV}

\TYPE {\small\verb%AC_CONV : ((thm # thm) -> conv)%}\egroup

\SYNOPSIS
Proves equality of terms using associative and commutative laws.

\DESCRIBE
Suppose {\small\verb%_%} is a function, which is assumed to be infix in the following syntax,
and {\small\verb%ath%} and {\small\verb%cth%} are theorems expressing its associativity and
commutativity; they must be of the following form, except that any free
variables may have arbitrary names and may be universally quantified:
{\par\samepage\setseps\small
\begin{verbatim}
   ath = |- m _ (n _ p) = (m _ n) _ p
   cth = |- m _ n = n _ m
\end{verbatim}
}
\noindent Then the conversion {\small\verb%AC_CONV(ath,cth)%} will prove equations whose
left and right sides can be made identical using these associative and
commutative laws.

\FAILURE
Fails if the associative or commutative law has an invalid form, or if the
term is not an equation between AC-equivalent terms.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #AC_CONV(ADD_ASSOC,ADD_SYM)
   #  "x + (SUC t) + ((3 + y) + z) = 3 + (SUC t) + x + y + z";;
   |- (x + ((SUC t) + ((3 + y) + z)) = 3 + ((SUC t) + (x + (y + z)))) = T
\end{verbatim}
}

\COMMENTS
Note that the preproved associative and commutative laws for the operators {\small\verb%+%},
{\small\verb%*%}, {\small\verb%/\%} and {\small\verb%\/%} are already in the right form to give to {\small\verb%AC_CONV%}.

\SEEALSO
SYM_CONV.

\ENDDOC
\DOC{achieve\_first}

\TYPE {\small\verb%achieve_first : (subgoals -> thm -> subgoals)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{achieves}

\TYPE {\small\verb%achieves : (thm -> goal -> bool)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{aconv}

\TYPE {\small\verb%aconv : (term -> term -> bool)%}\egroup

\SYNOPSIS
Tests for alpha-convertibility of terms.

\DESCRIBE
When applied to two terms, {\small\verb%aconv%} returns {\small\verb%true%} if they are
alpha-convertible, and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\EXAMPLE
A simple case of alpha-convertibility is the renaming of a single quantified
variable:
{\par\samepage\setseps\small
\begin{verbatim}
   #aconv "?x. x=T" "?y. y=T";;
   true : bool
\end{verbatim}
}
\SEEALSO
ALPHA, ALPHA_CONV.

\ENDDOC
\DOC{activate\_binders}

\TYPE {\small\verb%activate_binders : (string -> string list)%}\egroup

\SYNOPSIS
Makes the quotation parser treat all binders in the current theory segment as
such.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   activate_binders `thy`
\end{verbatim}
}
\noindent where {\small\verb%thy%} is an ancestor theory ({\small\verb%`-`%} stands for the current
theory), will return a list of all binders on that theory, and make the parser
treat them all as binders, that is, for each binder {\small\verb%b%}, will allow the
syntactic sugaring {\small\verb%"b x. y"%} as a shorthand for {\small\verb%"b (\x. y)"%}. The special
syntactic status may be suppressed by preceding {\small\verb%b%} with a dollar sign. The
function returns a list of all the binders dealt with.

\FAILURE
Never fails.

\COMMENTS
This function is mainly intended for internal use. All binders declared by
{\small\verb%new_binder%} or {\small\verb%new_binder_definition%} are always parsed as such anyway.

\SEEALSO
activate_all_binders, binders, new_binder, parse_as_binder.

\ENDDOC
\DOC{ADD\_ASSUM}

\TYPE {\small\verb%ADD_ASSUM : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Adds an assumption to a theorem.

\DESCRIBE
When applied to a boolean term {\small\verb%s%} and a theorem {\small\verb%A |- t%}, the inference
rule {\small\verb%ADD_ASSUM%} returns the theorem {\small\verb%A u {s} |- t%}.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t
   --------------  ADD_ASSUM "s"
    A u {s} |- t
\end{verbatim}
}
\noindent {\small\verb%ADD_ASSUM%} performs straightforward set union with the new
assumption; it checks for identical assumptions, but not for alpha-equivalent
ones. The position at which the new assumption is inserted into the assumption
list should not be relied on.

\FAILURE
Fails unless the given term has type {\small\verb%bool%}.

\SEEALSO
ASSUME, UNDISCH.

\ENDDOC
\DOC{ADD\_CONV}

\TYPE {\small\verb%ADD_CONV : conv%}\egroup

\SYNOPSIS
Computes the sum of two natural number constants.

\DESCRIBE
If {\small\verb%n%} and {\small\verb%m%} are numeral constants (e.g. {\small\verb%0%}, {\small\verb%1%}, {\small\verb%2%}, {\small\verb%3%},...), then
{\small\verb%ADD_CONV "n + m"%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- n + m = s
\end{verbatim}
}
\noindent where {\small\verb%s%} is the numeral that denotes the sum of the natural
numbers denoted by {\small\verb%n%} and {\small\verb%m%}.

\FAILURE
{\small\verb%ADD_CONV tm%} fails if {\small\verb%tm%} is not of the form  {\small\verb%"n + m"%}, where {\small\verb%n%} and
{\small\verb%m%} are numerals.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ADD_CONV "75 + 25";;
|- 75 + 25 = 100
\end{verbatim}
}
\ENDDOC
\DOC{ALL\_CONV}

\TYPE {\small\verb%ALL_CONV : conv%}\egroup

\SYNOPSIS
Conversion that always succeeds and leaves a term unchanged.

\DESCRIBE
When applied to a term {\small\verb%"t"%}, the conversion {\small\verb%ALL_CONV%} returns the
theorem {\small\verb%|- t = t%}.

\FAILURE
Never fails.

\USES
Identity element for {\small\verb%THENC%}.

\SEEALSO
NO_CONV, REFL.

\ENDDOC
\DOC{ALL\_EL\_CONV}

\TYPE {\small\verb%ALL_EL_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a predicate to elements of a list.

\DESCRIBE
{\small\verb%ALL_EL_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   ALL_EL P [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- ALL_EL P [x0;...xn] = T
\end{verbatim}
}
\noindent if for every {\small\verb%xi%} occurred in the list, {\small\verb%conv "P xi"%} returns a theorem {\small\verb%|- P xi = T%}, otherwise, if for at least one {\small\verb%xi%}, evaluating 
{\small\verb%conv "P xi"%} returns the theorem {\small\verb%|- P xi = F%}, then it returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- ALL_EL P [x0;...xn] = F
\end{verbatim}
}

\FAILURE
{\small\verb%ALL_EL_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above, or
failure occurs when evaluating {\small\verb%conv "P xi"%} for some {\small\verb%xi%}.

\EXAMPLE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   ALL_EL_CONV bool_EQ_CONV "ALL_EL ($= T) [T;F;T]";;
\end{verbatim}
}
\noindent returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ALL_EL($= T)[T;F;T] = F
\end{verbatim}
}
\noindent   In general, if the predicate {\small\verb%P%} is an explicit lambda abstraction
{\small\verb%(\x. P x)%}, the conversion should be in the form
{\par\samepage\setseps\small
\begin{verbatim}
   (BETA_CONV THENC conv')
\end{verbatim}
}

\SEEALSO
SOME_EL_CONV, IS_EL_CONV, FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{allowed\_constant}

\TYPE {\small\verb%allowed_constant : (string -> bool)%}\egroup

\SYNOPSIS
Tests if a string has a permissible name for a constant.

\DESCRIBE
When applied to a string, {\small\verb%allowed_constant%} returns {\small\verb%true%} if the string is a
permissible constant name, that is, if it is an identifier (see the DESCRIPTION
for more details), and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\EXAMPLE
The following shows how the lexical rules can be altered:
{\par\samepage\setseps\small
\begin{verbatim}
   #map allowed_constant [`pi`; `@`; `a name`; `+++++`; `*`];;
   [true; true; false; false; true] : bool list

   #new_special_symbol `+++++`;;
   () : void

   #map allowed_constant [`pi`; `@`; `a name`; `+++++`; `*`];;
   [true; true; false; true; true] : bool list
\end{verbatim}
}
\COMMENTS
Note that this function only performs a lexical test; it does not check whether
there is already a constant of that name in the current theory.

\SEEALSO
constants, is_constant, new_alphanum, new_special_symbol, special_symbols.

\ENDDOC
\DOC{ALL\_TAC}

\TYPE {\small\verb%ALL_TAC : tactic%}\egroup

\SYNOPSIS
Passes on a goal unchanged.

\DESCRIBE
{\small\verb%ALL_TAC%} applied to a goal {\small\verb%g%} simply produces the subgoal list {\small\verb%[g]%}. It is
the identity for the {\small\verb%THEN%} tactical.

\FAILURE
Never fails.

\EXAMPLE
The tactic {\small\verb%INDUCT_TAC THENL [ALL_TAC;tac]%}, applied to a goal {\small\verb%g%}, applies
{\small\verb%INDUCT_TAC%} to {\small\verb%g%} to give a basis and step subgoal; it then returns the
basis unchanged, along with the subgoals produced by applying {\small\verb%tac%} to the
step.

\USES
Used to write tacticals such as {\small\verb%REPEAT%}.
Often used as a place-holder in building compound tactics using tacticals
such as {\small\verb%THENL%}.

\SEEALSO
NO_TAC, REPEAT, THENL.

\ENDDOC
\DOC{ALL\_THEN}

\TYPE {\small\verb%ALL_THEN : thm_tactical%}\egroup

\SYNOPSIS
Passes a theorem unchanged to a theorem-tactic.

\DESCRIBE
For any theorem-tactic {\small\verb%ttac%} and theorem {\small\verb%th%}, the application {\small\verb%ALL_THEN ttac
th%} results simply in {\small\verb%ttac th%}, that is, the theorem is passed unchanged to
the theorem-tactic. {\small\verb%ALL_THEN%} is the identity theorem-tactical.

\FAILURE
The application of {\small\verb%ALL_THEN%} to a theorem-tactic never fails. The resulting
theorem-tactic fails under exactly the same conditions as the original one

\USES
Writing compound tactics or tacticals, e.g. terminating list iterations
of theorem-tacticals.

\SEEALSO
ALL_TAC, FAIL_TAC, NO_TAC, NO_THEN, THEN_TCL, ORELSE_TCL.

\ENDDOC
\DOC{ALPHA\_CONV}

\TYPE {\small\verb%ALPHA_CONV : (term -> conv)%}\egroup

\SYNOPSIS
Renames the bound variable of a lambda-abstraction.

\DESCRIBE
If {\small\verb%"x"%} is a variable of type {\small\verb%ty%} and {\small\verb%"\y.t"%} is an abstraction in which
the bound variable {\small\verb%y%} also has type {\small\verb%ty%}, then {\small\verb%ALPHA_CONV "x" "\y.t"%}
returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\y.t) = (\x'. t[x'/y])
\end{verbatim}
}
\noindent where the variable {\small\verb%x':ty%} is a primed variant of {\small\verb%x%} chosen so
as not to be free in {\small\verb%"\y.t"%}.

\FAILURE
{\small\verb%ALPHA_CONV "x" "tm"%} fails if {\small\verb%x%} is not a variable, if {\small\verb%tm%} is not an
abstraction, or if {\small\verb%x%} is a variable {\small\verb%v%} and {\small\verb%tm%} is a lambda abstraction
{\small\verb%\y.t%} but the types of {\small\verb%v%} and {\small\verb%y%} differ.

\SEEALSO
ALPHA, GEN_ALPHA_CONV.

\ENDDOC
\DOC{ALPHA}

\TYPE {\small\verb%ALPHA : (term -> term -> thm)%}\egroup

\SYNOPSIS
Proves equality of alpha-equivalent terms.

\DESCRIBE
When applied to a pair of terms {\small\verb%t1%} and {\small\verb%t1'%} which are
alpha-equivalent, {\small\verb%ALPHA%} returns the theorem {\small\verb%|- t1 = t1'%}.
{\par\samepage\setseps\small
\begin{verbatim}

   -------------  ALPHA "t1" "t1'"
    |- t1 = t1'
\end{verbatim}
}
\FAILURE
Fails unless the terms provided are alpha-equivalent.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ALPHA "!x:num. x = x" "!y:num. y = y";;
|- (!x. x = x) = (!y. y = y)
\end{verbatim}
}
\COMMENTS
The system shows the type of {\small\verb%ALPHA%} as {\small\verb%term -> conv%}.

\SEEALSO
aconv, ALPHA_CONV, GEN_ALPHA_CONV.

\ENDDOC
\DOC{ancestors}

\TYPE {\small\verb%ancestors : (string -> string list)%}\egroup

\SYNOPSIS
Gets a list of the (proper) ancestors of a theory.

\DESCRIBE
A call to {\small\verb%ancestors `th`%} returns a list of all the proper ancestors (i.e.
parents, parents of parents, etc.) of the theory {\small\verb%th%}.

\FAILURE
Fails if `th` is not an ancestor of the current theory.

\SEEALSO
ancestry, parents.

\ENDDOC
\DOC{ancestry}

\TYPE {\small\verb%ancestry : (void -> string list)%}\egroup

\SYNOPSIS
Gets a list of the ancestors of the current theory.

\DESCRIBE
A call {\small\verb%ancestry()%} returns a list of all the ancestors of the current theory,
i.e. the current theory itself, its parents, parents of parents, etc.

\FAILURE
Never fails.

\COMMENTS
The call {\small\verb%ancestry()%} is considerably more efficient than {\small\verb%ancestors `-`%}.

\SEEALSO
ancestors, parents.

\ENDDOC
\DOC{AND\_EXISTS\_CONV}

\TYPE {\small\verb%AND_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification outwards through a conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(?x.P) /\ (?x.Q)%}, where {\small\verb%x%} is free
in neither {\small\verb%P%} nor {\small\verb%Q%}, {\small\verb%AND_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P) /\ (?x. Q) = (?x. P /\ Q)
\end{verbatim}
}
\FAILURE
{\small\verb%AND_EXISTS_CONV%} fails if it is applied to a term not of the form
{\small\verb%(?x.P) /\ (?x.Q)%}, or if it is applied to a term {\small\verb%(?x.P) /\ (?x.Q)%}
in which the variable {\small\verb%x%} is free in either {\small\verb%P%} or {\small\verb%Q%}.

\SEEALSO
EXISTS_AND_CONV, LEFT_AND_EXISTS_CONV, RIGHT_AND_EXISTS_CONV.

\ENDDOC
\DOC{AND\_FORALL\_CONV}

\TYPE {\small\verb%AND_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification outwards through a conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(!x.P) /\ (!x.Q)%}, the conversion
{\small\verb%AND_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x.P) /\ (!x.Q) = (!x. P /\ Q)
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%(!x.P) /\ (!x.Q)%}.

\SEEALSO
FORALL_AND_CONV, LEFT_AND_FORALL_CONV, RIGHT_AND_FORALL_CONV.

\ENDDOC
\DOC{ANTE\_CONJ\_CONV}

\TYPE {\small\verb%ANTE_CONJ_CONV : conv%}\egroup

\SYNOPSIS
Eliminates a conjunctive antecedent in favour of implication.

\DESCRIBE
When applied to a term of the form {\small\verb%"(t1 /\ t2) ==> t"%}, the conversion
{\small\verb%ANTE_CONJ_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t1 /\ t2 ==> t) = (t1 ==> t2 ==> t)
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%"(t1 /\ t2) ==> t"%}.

\USES
Somewhat ad-hoc, but can be used (with {\small\verb%CONV_TAC%}) to transform a goal of the
form {\small\verb%?- (P /\ Q) ==> R%} into the subgoal {\small\verb%?- P ==> (Q ==> R)%}, so that only
the antecedent {\small\verb%P%} is moved into the assumptions by {\small\verb%DISCH_TAC%}.

\ENDDOC
\DOC{ANTE\_RES\_THEN}

\TYPE {\small\verb%ANTE_RES_THEN : thm_tactical%}\egroup

\SYNOPSIS
Resolves implicative assumptions with an antecedent.

\DESCRIBE
Given a theorem-tactic {\small\verb%ttac%} and a theorem {\small\verb%A |- t%}, the function
{\small\verb%ANTE_RES_THEN%} produces a tactic that attempts to match {\small\verb%t%} to the antecedent
of each implication
{\par\samepage\setseps\small
\begin{verbatim}
   Ai |- !x1...xn. ui ==> vi
\end{verbatim}
}
\noindent (where {\small\verb%Ai%} is just {\small\verb%!x1...xn. ui ==> vi%}) that occurs among the
assumptions of a goal. If the antecedent {\small\verb%ui%} of any implication matches {\small\verb%t%},
then an instance of {\small\verb%Ai u A |- vi%} is obtained by specialization of the
variables {\small\verb%x1%}, ..., {\small\verb%xn%} and type instantiation, followed by an application of
modus ponens.  Because all implicative assumptions are tried, this may result
in several modus-ponens consequences of the supplied theorem and the
assumptions.  Tactics are produced using {\small\verb%ttac%} from all these theorems, and
these tactics are applied in sequence to the goal.  That is,
{\par\samepage\setseps\small
\begin{verbatim}
   ANTE_RES_THEN ttac (A |- t) g
\end{verbatim}
}
\noindent has the effect of:
{\par\samepage\setseps\small
\begin{verbatim}
   MAP_EVERY ttac [A1 u A |- v1; ...; Am u A |- vm] g
\end{verbatim}
}
\noindent where the theorems {\small\verb%Ai u A |- vi%} are all the consequences that can
be drawn by a (single) matching modus-ponens inference from the implications
that occur among the assumptions of the goal {\small\verb%g%} and the supplied theorem
{\small\verb%A |- t%}.  Any negation {\small\verb%~v%} that appears among the assumptions of the goal is
treated as an implication {\small\verb%v ==> F%}.  The sequence in which the theorems
{\small\verb%Ai u A |- vi%} are generated and the corresponding tactics applied is
unspecified.

\FAILURE
{\small\verb%ANTE_RES_THEN ttac (A |- t)%} fails when applied to a goal {\small\verb%g%} if any of the
tactics produced by {\small\verb%ttac (Ai u A |- vi)%}, where {\small\verb%Ai u A |- vi%} is the {\small\verb%i%}th
resolvent obtained from the theorem {\small\verb%A |- t%} and the assumptions of {\small\verb%g%}, fails
when applied in sequence to {\small\verb%g%}.

\SEEALSO
IMP_RES_TAC, IMP_RES_THEN, MATCH_MP, RES_TAC, RES_THEN.

\ENDDOC
\DOC{APPEND\_CONV}

\TYPE {\small\verb%APPEND_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of appending two object-language lists.

\DESCRIBE
For any pair of object language lists of the form {\small\verb%"[x1;...;xn]"%} and
{\small\verb%"[y1;...;ym]"%}, the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   APPEND_CONV "APPEND [x1;...;xn] [y1;...;ym]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- APPEND [x1;...;xn] [y1;...;ym] = [x1;...;xn;y1;...;ym]
\end{verbatim}
}
\noindent The length of either list (or both) may be 0.

\FAILURE
{\small\verb%APPEND_CONV tm%} fails if {\small\verb%tm%} is not of the form {\small\verb%"APPEND l1 l2"%}, where
{\small\verb%l1%} and {\small\verb%l2%} are (possibly empty) object-language lists of the forms
{\small\verb%"[x1;...;xn]"%} and {\small\verb%"[y1;...;ym]"%}.

\ENDDOC

\DOC{append}

\TYPE {\small\verb%append : (* list -> * list -> * list)%}\egroup

\SYNOPSIS
Concatenates two lists.

\DESCRIBE
{\small\verb%append [x1;...;xn] [y1;...;ym]%} returns {\small\verb%[x1;...;xn;y1;...;ym]%}.

\FAILURE
Never fails.

\COMMENTS
Performs the same operation as {\small\verb%$@%}.

\ENDDOC
\DOC{append\_openw}

\TYPE {\small\verb%append_openw : (string -> string)%}\egroup

\SYNOPSIS
Opens a port for appending to a named file.

\DESCRIBE
When applied to a filename {\small\verb%`name`%}, the function {\small\verb%append_openw%} opens the file
{\small\verb%name%} for writing, such that existing contents are appended to rather than
overwritten. It returns a port descriptor string, which can be used by {\small\verb%write%}
to append to the file, and by {\small\verb%close%} to close it.

\EXAMPLE
The following example assumes that HOL is being run under Unix. It will
overwrite an existing file {\small\verb%test-file%} in the current directory.
{\par\samepage\setseps\small
\begin{verbatim}
   #system `echo -n 'Hello ' >test-file`;;
   0 : int

   #let port = append_openw `test-file`;;
   port = `%test-file` : string

   #write(port,`world`);;
   () : void

   #close port;;
   () : void

   #system `cat test-file`;;
   Hello world0 : int
\end{verbatim}
}
\SEEALSO
close, openi, openw, read, write.

\ENDDOC
\DOC{apply\_proof}

\TYPE {\small\verb%apply_proof : (subgoals -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{AP\_TERM}

\TYPE {\small\verb%AP_TERM : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Applies a function to both sides of an equational theorem.

\DESCRIBE
When applied to a term {\small\verb%f%} and a theorem {\small\verb%A |- x = y%}, the
inference rule {\small\verb%AP_TERM%} returns the theorem {\small\verb%A |- f x = f y%}.
{\par\samepage\setseps\small
\begin{verbatim}
      A |- x = y
   ----------------  AP_TERM "f"
    A |- f x = f y
\end{verbatim}
}
\FAILURE
Fails unless the theorem is equational and the supplied term is a function
whose domain type is the same as the type of both sides of the equation.

\SEEALSO
AP_THM, MK_COMB.

\ENDDOC
\DOC{AP\_TERM\_TAC}

\TYPE {\small\verb%AP_TERM_TAC : tactic%}\egroup

\SYNOPSIS
Strips a function application from both sides of an equational goal.

\DESCRIBE
{\small\verb%AP_TERM_TAC%} reduces a goal of the form {\small\verb%A ?- f x = f y%} by stripping away
the function applications, giving the new goal {\small\verb%A ?- x = y%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- f x = f y
   ================  AP_TERM_TAC
     A ?- x = y
\end{verbatim}
}
\FAILURE
Fails unless the goal is equational, with both sides being applications
of the same function.

\SEEALSO
AP_TERM, AP_THM.

\ENDDOC
\DOC{AP\_THM}

\TYPE {\small\verb%AP_THM : (thm -> term -> thm)%}\egroup

\SYNOPSIS
Proves equality of equal functions applied to a term.

\DESCRIBE
When applied to a theorem {\small\verb%A |- f = g%} and a term {\small\verb%x%}, the inference
rule {\small\verb%AP_THM%} returns the theorem {\small\verb%A |- f x = g x%}.
{\par\samepage\setseps\small
\begin{verbatim}
      A |- f = g
   ----------------  AP_THM (A |- f = g) "x"
    A |- f x = g x
\end{verbatim}
}
\FAILURE
Fails unless the conclusion of the theorem is an equation, both sides
of which are functions whose domain type is the same as that of the
supplied term.

\COMMENTS
The type of {\small\verb%AP_THM%} is shown by the system as {\small\verb%thm -> conv%}.

\SEEALSO
AP_TERM, ETA_CONV, EXT, MK_COMB.

\ENDDOC
\DOC{AP\_THM\_TAC}

\TYPE {\small\verb%AP_THM_TAC : tactic%}\egroup

\SYNOPSIS
Strips identical operands from functions on both sides of an equation.

\DESCRIBE
When applied to a goal of the form {\small\verb%A ?- f x = g x%}, the tactic {\small\verb%AP_THM_TAC%}
strips away the operands of the function application:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- f x = g x
   ================  AP_THM_TAC
      A ?- f = g
\end{verbatim}
}
\FAILURE
Fails unless the goal has the above form, namely an equation both sides of
which consist of function applications to the same arguments.

\SEEALSO
AP_TERM, AP_TERM_TAC, AP_THM, EXT.

\ENDDOC
\DOC{arb\_term}

\TYPE {\small\verb%arb_term : term%}\egroup

\SYNOPSIS
This identifier is bound for implementation reasons only.

\DESCRIBE
{\small\verb%arb_term%} is the term {\small\verb%"arb:*"%}, i.e. it is a variable named {\small\verb%arb%} of logical
type {\small\verb%":*"%}.

\ENDDOC
\DOC{arity}

\TYPE {\small\verb%arity : (string -> int)%}\egroup

\SYNOPSIS
Returns the arity of a type operator.

\DESCRIBE
{\small\verb%arity `op`%} returns {\small\verb%n%} if {\small\verb%op%} is the name of an {\small\verb%n%}-ary type operator ({\small\verb%n%}
can be 0), and otherwise fails.

\FAILURE
{\small\verb%arity st%} fails if {\small\verb%st%} is not the name of a type constant or type operator.

\SEEALSO
is_type.

\ENDDOC
\DOC{ascii\_code}

\TYPE {\small\verb%ascii_code : (string -> int)%}\egroup

\SYNOPSIS
Maps a character to corresponding ASCII numeric code.

\DESCRIBE
When given a string, {\small\verb%ascii_code%} returns the numeric encoding in the
ASCII character set of the first character of that string.

\FAILURE
Fails if the string is empty ({\small\verb%``%}).

\SEEALSO
ascii, int_of_string, is_alphanum, is_letter, string_of_int.

\ENDDOC
\DOC{ascii}

\TYPE {\small\verb%ascii : (int -> string)%}\egroup

\SYNOPSIS
Maps an integer to the corresponding ASCII character.

\DESCRIBE
When given an integer, {\small\verb%ascii%} returns a string consisting of
the single character corresponding to that integer under the ASCII
encoding.

\FAILURE
Fails unless the integer supplied is in the range {\small\verb%0 <= x < 128%}.

\SEEALSO
ascii_code, int_of_string, is_alphanum, is_letter, string_of_int.

\ENDDOC
\DOC{ASM\_CASES\_TAC}

\TYPE {\small\verb%ASM_CASES_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Given a term, produces a case split based on whether or not that
term is true.

\DESCRIBE
Given a term {\small\verb%u%}, {\small\verb%ASM_CASES_TAC%} applied to a goal produces two
subgoals, one with {\small\verb%u%} as an assumption and one with {\small\verb%~u%}:
{\par\samepage\setseps\small
\begin{verbatim}
               A ?-  t
   ================================  ASM_CASES_TAC "u"
    A u {u} ?- t   A u {~u} ?- t
\end{verbatim}
}
\noindent {\small\verb%ASM_CASES_TAC u%} is implemented by
{\small\verb%DISJ_CASES_TAC(SPEC u EXCLUDED_MIDDLE)%}, where {\small\verb%EXCLUDED_MIDDLE%} is
the axiom {\small\verb%|- !u. u \/ ~u%}.

\FAILURE
By virtue of the implementation (see above), the decomposition fails if
{\small\verb%EXCLUDED_MIDDLE%} cannot be instantiated to {\small\verb%u%}, e.g. if {\small\verb%u%} does not
have boolean type.

\EXAMPLE
The tactic {\small\verb%ASM_CASES_TAC "u"%} can be used to produce a case analysis
on {\small\verb%"u"%}:
{\par\samepage\setseps\small
\begin{verbatim}
    ASM_CASES_TAC "u:bool" ([],"(P:bool -> bool) u");;
    ([(["u"], "P u"); (["~u"], "P u")], -) : subgoals
\end{verbatim}
}
\USES
Performing a case analysis according to whether a given term is true or false.

\SEEALSO
BOOL_CASES_TAC, COND_CASES_TAC, DISJ_CASES_TAC, SPEC, STRUCT_CASES_TAC.

\ENDDOC
\DOC{ASM\_REWRITE\_RULE}

\TYPE {\small\verb%ASM_REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem including built-in rewrites and the theorem's assumptions.

\DESCRIBE
{\small\verb%ASM_REWRITE_RULE%} rewrites with the tautologies in {\small\verb%basic_rewrites%},
the given list of theorems, and the set of hypotheses of the theorem. All
hypotheses are used. No ordering is specified among applicable rewrites.
Matching subterms are searched for recursively, starting with the entire term
of the conclusion and stopping when no rewritable expressions remain.  For more
details about the rewriting process, see {\small\verb%GEN_REWRITE_RULE%}. To avoid using the
set of basic tautologies, see {\small\verb%PURE_ASM_REWRITE_RULE%}.

\FAILURE
{\small\verb%ASM_REWRITE_RULE%} does not fail, but may result in divergence. To
prevent divergence where it would occur, {\small\verb%ONCE_ASM_REWRITE_RULE%} can be
used.

\SEEALSO
GEN_REWRITE_RULE, ONCE_ASM_REWRITE_RULE,
PURE_ASM_REWRITE_RULE, PURE_ONCE_ASM_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{ASM\_REWRITE\_TAC}

\TYPE {\small\verb%ASM_REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal including built-in rewrites and the goal's assumptions.

\DESCRIBE
{\small\verb%ASM_REWRITE_TAC%} generates rewrites with the tautologies in {\small\verb%basic_rewrites%},
the set of assumptions, and a list of theorems supplied by the user. These are
applied top-down and recursively on the goal, until no more matches are found.
The order in which the set of rewrite equations is applied is an implementation
matter and the user should not depend on any ordering. Rewriting strategies are
described in more detail under {\small\verb%GEN_REWRITE_TAC%}. For omitting the common
tautologies, see the tactic {\small\verb%PURE_ASM_REWRITE_TAC%}. To rewrite with only a
subset of the assumptions use {\small\verb%FILTER_ASM_REWRITE_TAC%}.

\FAILURE
{\small\verb%ASM_REWRITE_TAC%} does not fail, but it can diverge in certain
situations. For rewriting to a limited depth, see
{\small\verb%ONCE_ASM_REWRITE_TAC%}. The resulting tactic may not be valid if the
applicable replacement introduces new assumptions into the theorem
eventually proved.

\EXAMPLE
The use of assumptions in rewriting, specially when they are not in an
obvious equational form, is illustrated below:
{\par\samepage\setseps\small
\begin{verbatim}
   #ASM_REWRITE_TAC[](["P x"],"P x = Q x");;
   ([(["P x"], "Q x")], -) : subgoals

   #ASM_REWRITE_TAC[](["~P x"],"P x = Q x");;
   ([(["~P x"], "~Q x")], -) : subgoals
\end{verbatim}
}
\SEEALSO
basic_rewrites, FILTER_ASM_REWRITE_TAC, FILTER_ONCE_ASM_REWRITE_TAC,
GEN_REWRITE_TAC, ONCE_ASM_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_ASM_REWRITE_TAC, PURE_ONCE_ASM_REWRITE_TAC, PURE_REWRITE_TAC,
REWRITE_TAC, SUBST_TAC.

\ENDDOC
\DOC{assert}

\TYPE {\small\verb%assert : ((* -> bool) -> * -> *)%}\egroup

\SYNOPSIS
Checks that a value satisfies a predicate.

\DESCRIBE
{\small\verb%assert p x%} returns {\small\verb%x%} if the application {\small\verb%p x%} yields {\small\verb%true%}. Otherwise,
{\small\verb%assert p x%} fails.

\FAILURE
{\small\verb%assert p x%} fails with the string {\small\verb%`fail`%} if the predicate {\small\verb%p%} yields
{\small\verb%false%} when applied to the value {\small\verb%x%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#null [];;
true : bool

#assert null [];;
[] : * list

#null [1];;
false : bool

#assert null [1];;
evaluation failed     fail
\end{verbatim}
}
\SEEALSO
can.

\ENDDOC
\DOC{assignable\_print\_term}

\TYPE {\small\verb%assignable_print_term : (term -> void)%}\egroup

\SYNOPSIS
Assignable term-printing function used for printing goals.

\DESCRIBE
The printing of terms can be modified using the ML directive {\small\verb%top_print%}.
However the term printing functions used for printing goals are not affected
by {\small\verb%top_print%}. To make use of user-defined print functions in goals, the
assignable variable {\small\verb%assignable_print_term%} must be changed.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let my_print_term tm =
# do (print_string `<<`;print_term tm;print_string `>>`);;
my_print_term = - : (term -> void)

#"x ==> y";;
"x ==> y" : term

#top_print my_print_term;;
- : (term -> void)

#"x ==> y";;
<<"x ==> y">> : term
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
#g "(x ==> y) /\ (y ==> x) ==> (x = y)";;
"(x ==> y) /\ (y ==> x) ==> (x = y)"

() : void

#expand (REPEAT STRIP_TAC);;
OK..
"x = y"
    [ "x ==> y" ]
    [ "y ==> x" ]

() : void
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
#assignable_print_term := my_print_term;;
- : (term -> void)

#expand ALL_TAC;;
OK..
<<"x = y">>
    [ <<"x ==> y">> ]
    [ <<"y ==> x">> ]

() : void
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
#assignable_print_term := print_term;;
- : (term -> void)

#expand ALL_TAC;;
OK..
"x = y"
    [ "x ==> y" ]
    [ "y ==> x" ]

() : void
\end{verbatim}
}
\SEEALSO
print_term, top_print.

\ENDDOC
\DOC{assoc}

\TYPE {\small\verb%assoc : (* -> (* # **) list -> (* # **))%}\egroup

\SYNOPSIS
Searches a list of pairs for a pair whose first component equals a specified
value.

\DESCRIBE
{\small\verb%assoc x [(x1,y1);...;(xn,yn)]%} returns the first {\small\verb%(xi,yi)%} in the list such
that {\small\verb%xi%} equals {\small\verb%x%}.

\FAILURE
Fails if no matching pair is found. This will always be the case if the list
is empty.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#assoc 2 [(1,4);(3,2);(2,5);(2,6)];;
(2, 5) : (int # int)
\end{verbatim}
}
\SEEALSO
rev_assoc, find, mem, tryfind, exists, forall.

\ENDDOC
\DOC{associate\_restriction}

\TYPE {\small\verb%associate_restriction : ((string # string) -> void)%}\egroup

\SYNOPSIS
Associates a restriction semantics with a binder.

\DESCRIBE
If {\small\verb%B%} is a binder and {\small\verb%RES_B%} a constant then
{\par\samepage\setseps\small
\begin{verbatim}
   associate_restriction(`B`, `RES_B`)
\end{verbatim}
}
\noindent will cause the parser and pretty-printer to support:
{\par\samepage\setseps\small
\begin{verbatim}
               ---- parse ---->
   Bv::P. B                       RES_B  P (\v. B)
              <---- print ----
\end{verbatim}
}
Anything can be written between the binder and {\small\verb%`::`%} that could be
written between the binder and {\small\verb%`.`%} in the old notation. See the
examples below.

Associations between user defined binders and their restrictions are not
stored in the theory, so they have to be set up for each hol session
(e.g. with a {\small\verb%hol-init.ml%} file).

The flag {\small\verb%`print_restrict`%} has default {\small\verb%true%}, but if set to {\small\verb%false%} will
disable the pretty printing. This is useful for seeing what the
semantics of particular restricted abstractions are.

The following associations are predefined:
{\par\samepage\setseps\small
\begin{verbatim}
   \v::P. B    <---->   RES_ABSTRACT P (\v. B)
   !v::P. B    <---->   RES_FORALL   P (\v. B)
   ?v::P. B    <---->   RES_EXISTS   P (\v. B)
   @v::P. B    <---->   RES_SELECT   P (\v. B)
\end{verbatim}
}
Where the constants {\small\verb%RES_ABSTRACT%}, {\small\verb%RES_FORALL%}, {\small\verb%RES_EXISTS%} and
{\small\verb%RES_SELECT%} are defined in the theory {\small\verb%`bool`%} by:
{\par\samepage\setseps\small
\begin{verbatim}
   |- RES_ABSTRACT P B =  \x:*. (P x => B x | ARB:**)

   |- RES_FORALL P B   =  !x:*. P x ==> B x

   |- RES_EXISTS P B   =  ?x:*. P x /\ B x

   |- RES_SELECT P B   =  @x:*. P x /\ B x
\end{verbatim}
}
where {\small\verb%ARB%} is defined in the theory {\small\verb%`bool`%} by:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ARB  =  @x:*. T
\end{verbatim}
}
\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_binder_definition(`DURING`, "DURING(p:num#num->bool) = $!p");;
|- !p. $DURING p = $! p

#"DURING x::(m,n). p x";;
no restriction constant associated with DURING
skipping: x " ;; parse failed

#new_definition
# (`RES_DURING`, "RES_DURING(m,n)p = !x. m<=x /\ x<=n ==> p x");;
|- !m n p. RES_DURING(m,n)p = (!x. m <= x /\ x <= n ==> p x)

#associate_restriction(`DURING`,`RES_DURING`);;
() : void

#"DURING x::(m,n). p x";;
"DURING x :: (m,n). p x" : term

#set_flag(`print_restrict`,false);;
true : bool

#"DURING x::(m,n). p x";;
"RES_DURING(m,n)(\x. p x)" : term
\end{verbatim}
}
\ENDDOC
\DOC{ASSUME}

\TYPE {\small\verb%ASSUME : (term -> thm)%}\egroup

\SYNOPSIS
Introduces an assumption.

\DESCRIBE
When applied to a term {\small\verb%t%}, which must have type {\small\verb%bool%}, the inference rule
{\small\verb%ASSUME%} returns the theorem {\small\verb%t |- t%}.
{\par\samepage\setseps\small
\begin{verbatim}
   --------  ASSUME "t"
    t |- t
\end{verbatim}
}
\FAILURE
Fails unless the term {\small\verb%t%} has type {\small\verb%bool%}.

\COMMENTS
The type of {\small\verb%ASSUME%} is shown by the system as {\small\verb%conv%}.

\SEEALSO
ADD_ASSUM, REFL.

\ENDDOC
\DOC{ASSUME\_TAC}

\TYPE {\small\verb%ASSUME_TAC : thm_tactic%}\egroup

\SYNOPSIS
Adds an assumption to a goal.

\DESCRIBE
Given a theorem {\small\verb%th%} of the form {\small\verb%A' |- u%}, and a goal, {\small\verb%ASSUME_TAC th%}
adds {\small\verb%u%} to the assumptions of the goal.
{\par\samepage\setseps\small
\begin{verbatim}
         A ?- t
    ==============  ASSUME_TAC (A' |- u)
     A u {u} ?- t
\end{verbatim}
}
\noindent Note that unless {\small\verb%A'%} is a subset of {\small\verb%A%}, this tactic is invalid.

\FAILURE
Never fails.

\EXAMPLE
Given a goal {\small\verb%g%} of the form {\small\verb%{x = y, y = z} ?- P%},
where {\small\verb%"x"%}, {\small\verb%"y"%} and {\small\verb%"z"%} have type {\small\verb%":*"%},
the theorem {\small\verb%x = y, y = z |- x = z%} can, first, be inferred by
forward proof
{\par\samepage\setseps\small
\begin{verbatim}
   TRANS(ASSUME "x = y")(ASSUME "y = z")
\end{verbatim}
}
\noindent and then added to the assumptions. This process requires
the explicit text of the assumptions, as well as invocation of
the rule {\small\verb%ASSUME%}:
{\par\samepage\setseps\small
\begin{verbatim}
   ASSUME_TAC(TRANS(ASSUME "x = y")(ASSUME "y = z"))g;;
   ([(["x = z"; "x = y"; "y = z"], "P")], -) : subgoals
\end{verbatim}
}
\noindent This is the naive way of manipulating assumptions; there are more
advanced proof styles (more elegant and less transparent) that achieve the
same effect, but this is a perfectly correct technique in itself.

Alternatively, the axiom {\small\verb%EQ_TRANS%} could be added to the
assumptions of {\small\verb%g%}:
{\par\samepage\setseps\small
\begin{verbatim}
   ASSUME_TAC EQ_TRANS g;;
   ([(["!x y z. (x = y) /\ (y = z) ==> (x = z)"; "x = y"; "y = z"], "P")],
    -)
   : subgoals
\end{verbatim}
}
\noindent A subsequent resolution (see {\small\verb%RES_TAC%}) would then be able to add
the assumption {\small\verb%"x = z"%} to the subgoal shown above. (Aside from purposes of
example, it would be more usual to use {\small\verb%IMP_RES_TAC%} than {\small\verb%ASSUME_TAC%}
followed by {\small\verb%RES_TAC%} in this context.)

\USES
{\small\verb%ASSUME_TAC%} is the naive way of manipulating assumptions (i.e. without
recourse to advanced tacticals); and it is useful for enriching the assumption
list with lemmas as a prelude to resolution ({\small\verb%RES_TAC%}, {\small\verb%IMP_RES_TAC%}),
rewriting with assumptions ({\small\verb%ASM_REWRITE_TAC%} and so on), and other operations
involving assumptions.

\SEEALSO
ACCEPT_TAC, IMP_RES_TAC, RES_TAC, STRIP_ASSUME_TAC.

\ENDDOC
\DOC{ASSUM\_LIST}

\TYPE {\small\verb%ASSUM_LIST : ((thm list -> tactic) -> tactic)%}\egroup

\SYNOPSIS
Applies a tactic generated from the goal's assumption list.

\DESCRIBE
When applied to a function of type {\small\verb%thm list -> tactic%} and a goal,
{\small\verb%ASSUM_LIST%} constructs a tactic by applying {\small\verb%f%} to a list of {\small\verb%ASSUME%}d
assumptions of the goal, then applies that tactic to the goal.
{\par\samepage\setseps\small
\begin{verbatim}
   ASSUM_LIST f ({A1;...;An} ?- t)
         = f [A1 |- A1; ... ; An |- An] ({A1;...;An} ?- t)
\end{verbatim}
}
\FAILURE
Fails if the function fails when applied to the list of {\small\verb%ASSUME%}d assumptions,
or if the resulting tactic fails when applied to the goal.

\COMMENTS
There is nothing magical about {\small\verb%ASSUM_LIST%}: the same effect can usually be
achieved just as conveniently by using {\small\verb%ASSUME a%} wherever the
assumption {\small\verb%a%} is needed. If {\small\verb%ASSUM_LIST%} is used, it is extremely unwise to
use a function which selects elements from its argument list by number, since
the ordering of assumptions should not be relied on.

\EXAMPLE
The tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   ASSUM_LIST SUBST_TAC
\end{verbatim}
}
\noindent makes a single parallel substitution using all the assumptions,
which can be useful if the rewriting tactics are too blunt for the required
task.

\USES
Making more careful use of the assumption list than simply rewriting or
using resolution.

\SEEALSO
ASM_REWRITE_TAC, EVERY_ASSUM, IMP_RES_TAC, POP_ASSUM, POP_ASSUM_LIST,
REWRITE_TAC.

\ENDDOC
\DOC{attempt\_first}

\TYPE {\small\verb%attempt_first : (subgoals -> tactic -> subgoals)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{autoload}

\TYPE {\small\verb%autoload : ((string # string # string list) -> void)%}\egroup

\SYNOPSIS
Sets up a general autoloading action.

\DESCRIBE
After a call {\small\verb%autoload(`name`,`f`,[`arg1`;...;`argn`])%}, a subsequent
occurrence of {\small\verb%name%} in an ML phrase will cause the ML expression
{\small\verb%f [`arg1`;...;`argn`]%} to be evaluated before any of the toplevel phrase
containing {\small\verb%name%} is evaluated. Notice that {\small\verb%f%} is interpreted as a single
identifier denoting a function, whereas the various arguments are string
literals.

\FAILURE
Never fails (obviously failure may occur when the action is actually performed;
the ML phrase could be nonsense).

\EXAMPLE
The following is a simple example:
{\par\samepage\setseps\small
\begin{verbatim}
   #let action = tty_write o hd;;
   action = - : (string list -> void)

   #autoload(`key1`,`action`,[`Hello John!`]);;
   () : void

   #let key1 = 1;;
   Hello John!() : void

   key1 = 1 : int
\end{verbatim}
}
\COMMENTS
There is no obligation to use the argument list; an alternative to achieve the
same as the above is:
{\par\samepage\setseps\small
\begin{verbatim}
   #let action (l:(string)list) = tty_write `Hello John!`;;
   action = - : (string list -> void)

   #autoload(`key2`,`action`,[]);;
   () : void

   #let key2 = 1;;
   Hello John!() : void

   key2 = 1 : int
\end{verbatim}
}
\noindent If a normal autoloading action is all that is required, the function
{\small\verb%autoload_theory%} provides a simpler way.

\SEEALSO
autoload_theory, let_after, let_before, undo_autoload.

\ENDDOC
\DOC{autoload\_theory}

\TYPE {\small\verb%autoload_theory : ((string # string # string) -> void)%}\egroup

\SYNOPSIS
Makes an axiom, definition or theorem autoload when mentioned.

\DESCRIBE
After a call {\small\verb%autoload_theory(`kind`,`thy`,`name`)%}, a subsequent occurrence of
the name {\small\verb%name%} in an ML phrase will cause the relevant autoloading action.
The {\small\verb%kind%} value should be one of {\small\verb%axiom%}, {\small\verb%definition%} (this includes type
definitions) or {\small\verb%theorem%}, and the appropriate entity called {\small\verb%name%} will be
loaded from theory {\small\verb%thy%} before the ML phrase containing {\small\verb%name%} is evaluated.

\FAILURE
Never fails, although the subsequent autoloading action may do.

\EXAMPLE
The following autoload is not necessary because {\small\verb%ETA_AX%} is already bound to an
identifier when HOL is started. However, it shows the general idea.
{\par\samepage\setseps\small
\begin{verbatim}
   #autoload_theory(`axiom`,`bool`,`ETA_AX`);;
   () : void

   #ETA_AX;;
   Axiom ETA_AX autoloaded from theory `bool`.
   ETA_AX = |- !t. (\x. t x) = t

   |- !t. (\x. t x) = t
\end{verbatim}
}
\COMMENTS
More general automatic actions can be achieved using {\small\verb%autoload%}.

\SEEALSO
autoload, undo_autoload.

\ENDDOC
\DOC{axiom}

\TYPE {\small\verb%axiom : (string -> string -> thm)%}\egroup

\SYNOPSIS
Loads an axiom from a given theory segment of the current theory.

\DESCRIBE
A call of {\small\verb%axiom `thy` `ax`%} returns axiom {\small\verb%ax%} from the theory segment {\small\verb%thy%}.
The theory segment {\small\verb%thy%} must be part of the current theory. The name {\small\verb%ax%} is
the name given to the axiom by the user when it was originally added to the
theory segment (by a call to {\small\verb%new_axiom%}).  The name of the current theory
segment can be abbreviated by {\small\verb%`-`%}.

\FAILURE
The call {\small\verb%axiom `thy` `ax`%} will fail if the theory segment {\small\verb%thy%} is not part
of the current theory. It will fail if there does not exist an axiom of name
{\small\verb%ax%} in theory segment {\small\verb%thy%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#axiom `bool` `BOOL_CASES_AX`;;
|- !t. (t = T) \/ (t = F)
\end{verbatim}
}
\SEEALSO
axioms, definition, load_axiom, load_axioms, new_axiom, print_theory, theorem.

\ENDDOC
\DOC{axiom\_lfn}

\TYPE {\small\verb%axiom_lfn : (string list -> thm)%}\egroup

\SYNOPSIS
Loads a given axiom from a given theory.

\DESCRIBE
If {\small\verb%thy%} is an ancestor theory, and {\small\verb%ax%} one of its axioms, then the call
{\par\samepage\setseps\small
\begin{verbatim}
   axiom_lfn [`thy`;`ax`]
\end{verbatim}
}
\noindent will return that axiom.

\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%ax%} is not one of its
axioms.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#axiom_lfn [`bool`;`ETA_AX`];;
|- !t. (\x. t x) = t
\end{verbatim}
}
\COMMENTS
This call has the same effect as {\small\verb%axiom `thy` `ax`%}.

\SEEALSO
axiom, axioms, axiom_msg_lfn, load_axiom, load_axioms.

\ENDDOC
\DOC{axiom\_msg\_lfn}

\TYPE {\small\verb%axiom_msg_lfn : (string list -> thm)%}\egroup

\SYNOPSIS
Loads a given axiom from a given theory, with an autoload message.

\DESCRIBE
If {\small\verb%thy%} is an ancestor theory, and {\small\verb%ax%} one of its axioms, then the call
{\par\samepage\setseps\small
\begin{verbatim}
   axiom_msg_lfn [`thy`;`ax`]
\end{verbatim}
}
\noindent will print a message of the form
{\par\samepage\setseps\small
\begin{verbatim}
   Axiom ax autoloaded from theory `thy`
\end{verbatim}
}
\noindent and cancel any autoloading action associated with the name {\small\verb%ax%},
and will then return that axiom.

\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%ax%} is not one of its
axioms.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#axiom_msg_lfn [`bool`;`ETA_AX`];;
Axiom ETA_AX autoloaded from theory `bool`.
|- !t. (\x. t x) = t
\end{verbatim}
}
\SEEALSO
autoload, autoload_theory, axiom, axioms, axiom_lfn, load_axiom, load_axioms,
undo_autoload.

\ENDDOC
\DOC{axioms}

\TYPE {\small\verb%axioms : (string -> (string # thm) list)%}\egroup

\SYNOPSIS
Returns the axioms of a given theory segment of the current theory.

\DESCRIBE
A call {\small\verb%axioms `thy`%} returns the axioms of the theory segment {\small\verb%thy%} together
with their names. The theory segment {\small\verb%thy%} must be part of the current theory.
The names are those given to the axioms by the user when they were originally
added to the theory segment (by a call to {\small\verb%new_axiom%}). The name of the current
theory segment can be abbreviated by {\small\verb%`-`%}.

\FAILURE
The call {\small\verb%axioms `thy`%} will fail if the theory segment {\small\verb%thy%} is not
part of the current theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#axioms `bool`;;
[(`SELECT_AX`, |- !P x. P x ==> P($@ P));
 (`ETA_AX`, |- !t. (\x. t x) = t);
 (`IMP_ANTISYM_AX`,
  |- !t1 t2. (t1 ==> t2) ==> (t2 ==> t1) ==> (t1 = t2));
 (`BOOL_CASES_AX`, |- !t. (t = T) \/ (t = F));
 (`ARB_THM`, |- $= = $=)]
: (string # thm) list
\end{verbatim}
}
\SEEALSO
axiom, definitions, load_axiom, load_axioms, new_axiom, print_theory, theorems.

\ENDDOC
\DOC{backup}

\TYPE {\small\verb%backup : (void -> void)%}\egroup

\SYNOPSIS
Restores the proof state, undoing the effects of a previous expansion.

\DESCRIBE
The function {\small\verb%backup%} is part of the subgoal package.  It allows backing up
from the last state change (caused by calls to {\small\verb%expand%}, {\small\verb%set_goal%}, {\small\verb%rotate%}
and their abbreviations, or to {\small\verb%set_state%}). The package maintains a backup
list of previous proof states. A call to {\small\verb%backup%}  restores the state to the
previous state (which was on top of the backup list). The current state and the
state on top of the backup list are discarded. The maximum number of proof
states saved on the backup list is one greater than the value of the assignable
variable {\small\verb%backup_limit%}. This variable is initially set to 12. Adding new proof
states after the maximum is reached causes the earliest proof state on the list
to be discarded. The user may backup repeatedly until the list is exhausted.
The state restored includes all unproven subgoals or, if a goal had  been
proved in the previous state, the corresponding theorem. {\small\verb%backup%} is
abbreviated by the function {\small\verb%b%}. For a description of the subgoal package, see
{\small\verb%set_goal%}.

\FAILURE
The function {\small\verb%backup%} will fail if the backup list is empty.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])";;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

() : void

#e CONJ_TAC;;
OK..
2 subgoals
"TL[1;2;3] = [2;3]"

"HD[1;2;3] = 1"

() : void

#backup();;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

() : void

#e (REWRITE_TAC[HD;TL]);;
OK..
goal proved
|- (HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])

Previous subproof:
goal proved
() : void
\end{verbatim}
}
\USES
Back tracking in a goal-directed proof to undo errors or try different tactics.

\SEEALSO
b, backup_limit, e, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{backup\_limit}

\TYPE {\small\verb%backup_limit : int%}\egroup

\SYNOPSIS
Limits the number of proof states saved on the subgoal package backup list.

\DESCRIBE
The assignable variable {\small\verb%backup_limit%} is initially set to 12. Its value is one
less than the maximum number of proof states that may be saved on the backup
list. Adding a new proof state (by, for example, a call to {\small\verb%expand%}) after the
maximum is reached causes the earliest proof state on the list to be discarded.
For a description of the subgoal package, see  {\small\verb%set_goal%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#backup_limit := 0;;
0 : int

#g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])";;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

() : void

#e CONJ_TAC;;
OK..
2 subgoals
"TL[1;2;3] = [2;3]"

"HD[1;2;3] = 1"

() : void

#e (REWRITE_TAC[HD]);;
OK..
goal proved
|- HD[1;2;3] = 1

Previous subproof:
"TL[1;2;3] = [2;3]"

() : void

#b();;
2 subgoals
"TL[1;2;3] = [2;3]"

"HD[1;2;3] = 1"

() : void

#b();;
evaluation failed     backup:  backup list is empty
\end{verbatim}
}
\SEEALSO
b, backup, e, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{backup\_list}

\TYPE {\small\verb%backup_list : goalstack list%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{basic\_rewrites}

\TYPE {\small\verb%basic_rewrites: thm list%}\egroup

\SYNOPSIS
Contains a number of built-in tautologies used, by default, in rewriting.

\DESCRIBE
The variable {\small\verb%basic_rewrites%} contains polymorphic tautologies which
are often used for simplifying and solving a goal through rewriting.
They include the clause for reflexivity:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x. (x = x) = T;
\end{verbatim}
}
\noindent as well as rules to reason about equality:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !t.
      ((T = t) = t) /\ ((t = T) = t) /\ ((F = t) = ~t) /\ ((t = F) = ~t);
\end{verbatim}
}
Negations are manipulated by the following clauses:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!t. ~~t = t) /\ (~T = F) /\ (~F = T);
\end{verbatim}
}
The set of tautologies includes truth tables for conjunctions,
disjunctions, and implications:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !t.
       (T /\ t = t) /\
       (t /\ T = t) /\
       (F /\ t = F) /\
       (t /\ F = F) /\
       (t /\ t = t);
   |- !t.
       (T \/ t = T) /\
       (t \/ T = T) /\
       (F \/ t = t) /\
       (t \/ F = t) /\
       (t \/ t = t);
   |- !t.
       (T ==> t = t) /\
       (t ==> T = T) /\
       (F ==> t = T) /\
       (t ==> t = T) /\
       (t ==> F = ~t);
\end{verbatim}
}
Simple rules for reasoning about conditionals are given by:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !t1 t2. ((T => t1 | t2) = t1) /\ ((F => t1 | t2) = t2);
\end{verbatim}
}
Rewriting with the following tautologies allows simplification of
universally and existentially quantified variables and abstractions:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !t. (!x. t) = t;
   |- !t. (?x. t) = t;
   |- !t1 t2. (\x. t1)t2 = t1;
\end{verbatim}
}
The list {\small\verb%basic_rewrites%} also includes rules for reasoning about
pairs in HOL:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x. FST x,SND x = x;
   |- !x y. FST(x,y) = x;
   |- !x y. SND(x,y) = y]
\end{verbatim}
}
\USES
The {\small\verb%basic_rewrites%} are included in the set of equations used by some
of the rewriting tools.

\SEEALSO
ABS_SIMP, AND_CLAUSES, COND_CLAUSES, EQ_CLAUSES, EXISTS_SIMP,
FORALL_SIMP, FST, GEN_REWRITE_RULE, GEN_REWRITE_TAC, IMP_CLAUSES,
NOT_CLAUSES, OR_CLAUSES, PAIR, REFL_CLAUSE, REWRITE_RULE, REWRITE_TAC,
SND.

\ENDDOC
\DOC{b}

\TYPE {\small\verb%b : (void -> void)%}\egroup

\SYNOPSIS
Restores the proof state undoing the effects of a previous expansion.

\DESCRIBE
The function {\small\verb%b%} is part of the subgoal package. It is an abbreviation for the
function {\small\verb%backup%}. For a description of the subgoal package, see
{\small\verb%set_goal%}.

\FAILURE
As for {\small\verb%backup%}.

\USES
Back tracking in a goal-directed proof to undo errors or try different tactics.

\SEEALSO
backup, backup_limit, e, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{B}

\TYPE {\small\verb%B : ((* -> **) -> (*** -> *) -> *** -> **)%}\egroup

\SYNOPSIS
Performs curried function-composition: {\small\verb%B f g x%} = {\small\verb%f (g x)%}.

\FAILURE
Never fails.

\SEEALSO
\#, C, CB, Co, I, K, KI, o, oo, S, W.

\ENDDOC
\DOC{BETA\_CONV}

\TYPE {\small\verb%BETA_CONV : conv%}\egroup

\SYNOPSIS
Performs a simple beta-conversion.

\DESCRIBE
The conversion {\small\verb%BETA_CONV%} maps a beta-redex {\small\verb%"(\x.u)v"%} to the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\x.u)v = u[v/x]
\end{verbatim}
}
\noindent where {\small\verb%u[v/x]%} denotes the result of substituting {\small\verb%v%} for all free
occurrences of {\small\verb%x%} in {\small\verb%u%}, after renaming sufficient bound variables to avoid
variable capture. This conversion is one of the primitive inference rules of
the HOL system.

\FAILURE
{\small\verb%BETA_CONV tm%} fails if {\small\verb%tm%} is not a beta-redex.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#BETA_CONV "(\x.x+1)y";;
|- (\x. x + 1)y = y + 1

#BETA_CONV "(\x y. x+y)y";;
|- (\x y. x + y)y = (\y'. y + y')
\end{verbatim}
}
\COMMENTS
This primitive inference rule is actually not very primitive, since it does
automatic bound variable renaming. It would be logically cleaner for this
renaming to be derived rather than built-in, but since beta-reduction is so
common this would slow the system down a lot.  It is hoped to document the
exact renaming algorithm used by {\small\verb%BETA_CONV%} in the future.

\SEEALSO
BETA_RULE, BETA_TAC, LIST_BETA_CONV, PAIRED_BETA_CONV, RIGHT_BETA,
RIGHT_LIST_BETA.

\ENDDOC
\DOC{BETA\_RULE}

\TYPE {\small\verb%BETA_RULE : (thm -> thm)%}\egroup

\SYNOPSIS
Beta-reduces all the beta-redexes in the conclusion of a theorem.

\DESCRIBE
When applied to a theorem {\small\verb%A |- t%}, the inference rule {\small\verb%BETA_RULE%} beta-reduces
all beta-redexes, at any depth, in the conclusion {\small\verb%t%}. Variables are renamed
where necessary to avoid free variable capture.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- ....((\x. s1) s2)....
   ----------------------------  BETA_RULE
      A |- ....(s1[s2/x])....
\end{verbatim}
}
\FAILURE
Never fails, but will have no effect if there are no beta-redexes.

\EXAMPLE
The following example is a simple reduction which illustrates variable
renaming:
{\par\samepage\setseps\small
\begin{verbatim}
   #top_print print_all_thm;;
   - : (thm -> void)

   #let x = ASSUME "f = ((\x y. x + y) y)";;
   x = f = (\x y. x + y)y |- f = (\x y. x + y)y

   #BETA_RULE x;;
   f = (\x y. x + y)y |- f = (\y'. y + y')
\end{verbatim}
}
\SEEALSO
BETA_CONV, BETA_TAC, PAIRED_BETA_CONV, RIGHT_BETA.

\ENDDOC
\DOC{BETA\_TAC}

\TYPE {\small\verb%BETA_TAC : tactic%}\egroup

\SYNOPSIS
Beta-reduces all the beta-redexes in the conclusion of a goal.

\DESCRIBE
When applied to a goal {\small\verb%A ?- t%}, the tactic {\small\verb%BETA_TAC%} produces a new goal
which results from beta-reducing all beta-redexes, at any depth, in {\small\verb%t%}.
Variables are renamed where necessary to avoid free variable capture.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- ...((\x. s1) s2)...
   ==========================  BETA_TAC
     A ?- ...(s1[s2/x])...
\end{verbatim}
}
\FAILURE
Never fails, but will have no effect if there are no beta-redexes.

\SEEALSO
BETA_CONV, BETA_TAC, PAIRED_BETA_CONV.

\ENDDOC
\DOC{binders}

\TYPE {\small\verb%binders : (string -> term list)%}\egroup

\SYNOPSIS
Lists the binders in the named theory.

\DESCRIBE
The function {\small\verb%binders%} should be applied to a string which is the name of an
ancestor theory (including the current theory; the special string {\small\verb%`-`%} is
always interpreted as the current theory). It returns a list of all the binders
declared in the named theory.

\FAILURE
Fails unless the given theory is an ancestor of the current theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#binders `bool`;;
["$?!"; "$!"; "$@"] : term list

#binders `ind`;;
[] : term list
\end{verbatim}
}
\SEEALSO
ancestors, axioms, constants, definitions, infixes, new_binder, parents, types.

\ENDDOC
\DOC{bndvar}

\TYPE {\small\verb%bndvar : (term -> term)%}\egroup

\SYNOPSIS
Returns the bound variable of an abstraction.

\DESCRIBE
{\small\verb%bndvar "\var. t"%} returns {\small\verb%"var"%}.

\FAILURE
Fails unless the term is an abstraction.

\SEEALSO
body, dest_abs.

\ENDDOC
\DOC{BODY\_CONJUNCTS}

\TYPE {\small\verb%BODY_CONJUNCTS : (thm -> thm list)%}\egroup

\SYNOPSIS
Splits up conjuncts recursively, stripping away universal quantifiers.

\DESCRIBE
When applied to a theorem, {\small\verb%BODY_CONJUNCTS%} recursively strips off universal
quantifiers by specialization, and breaks conjunctions into a list of
conjuncts.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- !x1...xn. t1 /\ (!y1...ym. t2 /\ t3) /\ ...
   --------------------------------------------------  BODY_CONJUNCTS
          [A |- t1; A |- t2; A |- t3; ...]
\end{verbatim}
}
\FAILURE
Never fails, but has no effect if there are no top-level universal quantifiers
or conjuncts.

\EXAMPLE
The following illustrates how a typical term will be split:
{\par\samepage\setseps\small
\begin{verbatim}
   #let x = ASSUME "!x:bool. A /\ (B \/ (C /\ D)) /\ ((!y:bool. E) /\ F)";;
   x = . |- !x. A /\ (B \/ C /\ D) /\ (!y. E) /\ F

   #BODY_CONJUNCTS x;;
   [. |- A; . |- B \/ C /\ D; . |- E; . |- F] : thm list
\end{verbatim}
}
\SEEALSO
CONJ, CONJUNCT1, CONJUNCT2, CONJUNCTS, CONJ_TAC.

\ENDDOC
\DOC{body}

\TYPE {\small\verb%body : (term -> term)%}\egroup

\SYNOPSIS
Returns the body of an abstraction.

\DESCRIBE
{\small\verb%body "\var. t"%} returns {\small\verb%"t"%}.

\FAILURE
Fails unless the term is an abstraction.

\SEEALSO
bndvar, dest_abs.

\ENDDOC
\DOC{BOOL\_CASES\_TAC}

\TYPE {\small\verb%BOOL_CASES_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Performs boolean case analysis on a (free) term in the goal.

\DESCRIBE
When applied to a term {\small\verb%x%} (which must be of type {\small\verb%bool%} but need not be simply
a variable), and a goal {\small\verb%A ?- t%}, the tactic {\small\verb%BOOL_CASES_TAC%} generates the two
subgoals corresponding to {\small\verb%A ?- t%} but with any free instances of {\small\verb%x%} replaced
by {\small\verb%F%} and {\small\verb%T%} respectively.
{\par\samepage\setseps\small
\begin{verbatim}
              A ?- t
   ============================  BOOL_CASES_TAC "x"
    A ?- t[F/x]    A ?- t[T/x]
\end{verbatim}
}
\noindent The term given does not have to be free in the goal, but if it isn't,
{\small\verb%BOOL_CASES_TAC%} will merely duplicate the original goal twice.

\FAILURE
Fails unless the term {\small\verb%x%} has type {\small\verb%bool%}.

\EXAMPLE
The goal:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (b ==> ~b) ==> (b ==> a)
\end{verbatim}
}
\noindent can be completely solved by using {\small\verb%BOOL_CASES_TAC%} on the variable
{\small\verb%b%}, then simply rewriting the two subgoals using only the inbuilt tautologies,
i.e. by applying the following tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   BOOL_CASES_TAC "b:bool" THEN REWRITE_TAC[]
\end{verbatim}
}
\USES
Avoiding fiddly logical proofs by brute-force case analysis, possibly only
over a key term as in the above example, possibly over all free boolean
variables.

\SEEALSO
ASM_CASES_TAC, COND_CASES_TAC, DISJ_CASES_TAC, STRUCT_CASES_TAC.

\ENDDOC
\DOC{bool\_EQ\_CONV}

\TYPE {\small\verb%bool_EQ_CONV : conv%}\egroup

\SYNOPSIS
Simplifies expressions involving boolean equality.

\DESCRIBE
The conversion {\small\verb%bool_EQ_CONV%} simplifies equations of the form {\small\verb%"t1 = t2"%},
where {\small\verb%t1%} and {\small\verb%t2%} are of type {\small\verb%:bool%}.  When applied to a term of the form
{\small\verb%"t = t"%}, the conversion {\small\verb%bool_EQ_CONV%} returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t = t) = T
\end{verbatim}
}
\noindent When applied to a term of the form {\small\verb%"t = T"%}, the conversion returns
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t = T) = t
\end{verbatim}
}
\noindent And when applied to a term of the form {\small\verb%"T = t"%}, it returns
{\par\samepage\setseps\small
\begin{verbatim}
   |- (T = t) = t
\end{verbatim}
}
\FAILURE
Fails unless applied to a term of the form {\small\verb%"t1 = t2"%}, where {\small\verb%t1%} and {\small\verb%t2%} are
boolean, and either {\small\verb%t1%} and {\small\verb%t2%} are syntactically identical terms or one of
{\small\verb%t1%} and {\small\verb%t2%} is the constant {\small\verb%"T"%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#bool_EQ_CONV "T = F";;
|- (T = F) = F

#bool_EQ_CONV "(0 < n) = T";;
|- (0 < n = T) = 0 < n
\end{verbatim}
}
\ENDDOC
\DOC{bool\_ty}

\TYPE {\small\verb%bool_ty : type%}\egroup

\SYNOPSIS
Holds the logical type {\small\verb%":bool"%}.

\ENDDOC
\DOC{BUTFIRSTN\_CONV}

\TYPE {\small\verb%BUTFIRSTN_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of dropping the initial n elements of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...x(n-k);...;x(n-1)]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   BUTFIRSTN_CONV "BUTFIRSTN k [x0;...x(n-k);...;x(n-1)]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- BUTFIRSTN k [x0;...;x(n-k);...;x(n-1)] = [x(n-k);...;x(n-1)]
\end{verbatim}
}


\FAILURE
{\small\verb%BUTFIRSTN_CONV tm%} fails if {\small\verb%tm%} is not of the form described above, 
or {\small\verb%k%} is greater than the length of the list.

\ENDDOC

\DOC{BUTLAST\_CONV}

\TYPE {\small\verb%BUTLAST_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of stripping the last element of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...x(n-1)]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   BUTLAST_CONV "BUTLAST [x0;...;x(n-1)]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- BUTLAST [x0;...;x(n-1)] = [x0;...; x(n-2)]
\end{verbatim}
}


\FAILURE
{\small\verb%BUTLAST_CONV tm%} fails if {\small\verb%tm%} is an empty list.

\ENDDOC

\DOC{butlast}

\TYPE {\small\verb%butlast : (* list -> * list)%}\egroup

\SYNOPSIS
Computes the sub-list of a list consisting of all but the last element.

\DESCRIBE
{\small\verb%butlast [x1;...;xn]%} returns {\small\verb%[x1;...;x(n-1)]%}.

\FAILURE
Fails if the list is empty.

\SEEALSO
last, hd, tl, el, null.

\ENDDOC
\DOC{BUTLASTN\_CONV}

\TYPE {\small\verb%BUTLASTN_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of dropping the last n elements of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...x(n-k);...;x(n-1)]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   BUTLASTN_CONV "BUTLASTN k [x0;...x(n-k);...;x(n-1)]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- BUTLASTN k [x0;...;x(n-k);...;x(n-1)] = [x0;...;x(n-k-1)]
\end{verbatim}
}


\FAILURE
{\small\verb%BUTLASTN_CONV tm%} fails if {\small\verb%tm%} is not of the form described above, 
or {\small\verb%k%} is greater than the length of the list.

\ENDDOC

\DOC{cached\_theories}

\TYPE {\small\verb%cached_theories : (void -> (string # bool) list)%}\egroup

\SYNOPSIS
Gives a list of cached and uncached theories.

\DESCRIBE
A call {\small\verb%cached_theories()%} returns a list pairs, one for each loaded theory,
associating the name of the theory with either {\small\verb%true%}, indicating that a theory
has been removed from the cache by {\small\verb%delete_cache%}, or {\small\verb%false%} otherwise. For
more details of the cacheing mechanism, see the DESCRIPTION.

\FAILURE
Never fails.

\SEEALSO
delete_cache.

\ENDDOC
\DOC{can}

\TYPE {\small\verb%can : ((* -> **) -> * -> bool)%}\egroup

\SYNOPSIS
Tests for failure.

\DESCRIBE
{\small\verb%can f x%} evaluates to {\small\verb%true%} if the application of {\small\verb%f%} to {\small\verb%x%} succeeds.
It evaluates to {\small\verb%false%} if the application fails.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#hd [];;
evaluation failed     hd

#can hd [];;
false : bool
\end{verbatim}
}
\SEEALSO
assert.

\ENDDOC
\DOC{CASES\_THENL}

\TYPE {\small\verb%CASES_THENL : (thm_tactic list -> thm_tactic)%}\egroup

\SYNOPSIS
Applies the theorem-tactics in a list to corresponding disjuncts in a theorem.

\DESCRIBE
When given a list of theorem-tactics {\small\verb%[ttac1;...;ttacn]%} and a theorem whose
conclusion is a top-level disjunction of {\small\verb%n%} terms, {\small\verb%CASES_THENL%} splits a goal
into {\small\verb%n%} subgoals resulting from applying to the original goal the result of
applying the {\small\verb%i%}'th theorem-tactic to the {\small\verb%i%}'th disjunct. This can be
represented as follows, where the number of existentially quantified variables
in a disjunct may be zero. If the theorem {\small\verb%th%} has the form:
{\par\samepage\setseps\small
\begin{verbatim}
   A' |- ?x11..x1m. t1 \/ ... \/ ?xn1..xnp. tn
\end{verbatim}
}
\noindent where the number of existential quantifiers may be zero,
and for all {\small\verb%i%} from {\small\verb%1%} to {\small\verb%n%}:
{\par\samepage\setseps\small
\begin{verbatim}
     A ?- s
   ========== ttaci (|- ti[xi1'/xi1]..[xim'/xim])
    Ai ?- si
\end{verbatim}
}
\noindent where the primed variables have the same type as their unprimed
counterparts, then:
{\par\samepage\setseps\small
\begin{verbatim}
             A ?- s
   =========================  CASES_THENL [ttac1;...;ttacn] th
    A1 ?- s1  ...  An ?- sn
\end{verbatim}
}
\noindent Unless {\small\verb%A'%} is a subset of {\small\verb%A%}, this is an invalid tactic.

\FAILURE
Fails if the given theorem does not, at the top level,
have the same number of (possibly multiply existentially quantified) disjuncts
as the length of the theorem-tactic list (this includes the case where the
theorem-tactic list is empty), or if any of the tactics generated as specified
above fail when applied to the goal.

\USES
Performing very general disjunctive case splits.

\SEEALSO
DISJ_CASES_THENL, X_CASES_THENL.

\ENDDOC
\DOC{CB}

\TYPE {\small\verb%$CB : ((* -> **) -> (** -> ***) -> * -> ***)%}\egroup

\SYNOPSIS
Composes two functions: {\small\verb%(f CB g) x%} = {\small\verb%g (f x)%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, Co, I, K, KI, o, oo, S, W.

\ENDDOC
\DOC{CCONTR}

\TYPE {\small\verb%CCONTR : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Implements the classical contradiction rule.

\DESCRIBE
When applied to a term {\small\verb%t%} and a theorem {\small\verb%A |- F%}, the inference rule {\small\verb%CCONTR%}
returns the theorem {\small\verb%A - {~t} |- t%}.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- F
   ---------------  CCONTR "t"
    A - {~t} |- t
\end{verbatim}
}
\FAILURE
Fails unless the term has type {\small\verb%bool%} and the theorem has {\small\verb%F%} as its
conclusion.

\COMMENTS
The usual use will be when {\small\verb%~t%} exists in the assumption list; in this case,
{\small\verb%CCONTR%} corresponds to the classical contradiction rule: if {\small\verb%~t%} leads to
a contradiction, then {\small\verb%t%} must be true.

\SEEALSO
CONTR, CONTRAPOS, CONTR_TAC, NOT_ELIM.

\ENDDOC
\DOC{C}

\TYPE {\small\verb%C : ((* -> ** -> ***) -> ** -> * -> ***)%}\egroup

\SYNOPSIS
Permutes first two arguments to curried function: {\small\verb%C f x y%} = {\small\verb%f y x%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, CB, Co, I, K, KI, o, oo, S, W.

\ENDDOC
\DOC{CHANGED\_CONV}

\TYPE {\small\verb%CHANGED_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Makes a conversion fail if applying it leaves a term unchanged.

\DESCRIBE
If {\small\verb%c%} is a conversion that maps a term {\small\verb%"t"%} to a theorem {\small\verb%|- t = t'%}, where
{\small\verb%t'%} is alpha-equivalent to {\small\verb%t%}, then {\small\verb%CHANGED_CONV c%} is a conversion that
fails when applied to the term {\small\verb%"t"%}. If {\small\verb%c%} maps {\small\verb%"t"%} to {\small\verb%|- t = t'%}, where
{\small\verb%t'%} is not alpha-equivalent to {\small\verb%t%}, then {\small\verb%CHANGED_CONV c%} also maps {\small\verb%"t"%} to
{\small\verb%|- t = t'%}. That is, {\small\verb%CHANGED_CONV c%} is the conversion that behaves exactly
like {\small\verb%c%}, except that it fails whenever the conversion {\small\verb%c%} would leave its
input term unchanged (up to alpha-equivalence).

\FAILURE
{\small\verb%CHANGED_CONV c "t"%} fails if {\small\verb%c%} maps {\small\verb%"t"%} to {\small\verb%|- t = t'%}, where {\small\verb%t'%} is
alpha-equivalent to {\small\verb%t%}, or if {\small\verb%c%} fails when applied to {\small\verb%"t"%}.  The function
returned by {\small\verb%CHANGED_CONV c%} may also fail if the ML function {\small\verb%c:term->thm%} is
not, in fact, a conversion (i.e. a function that maps a term {\small\verb%t%} to a theorem
{\small\verb%|- t = t'%}).

\USES
{\small\verb%CHANGED_CONV%} is used to transform a conversion that may leave terms
unchanged, and therefore may cause a nonterminating computation if repeated,
into one that can safely be repeated until application of it fails to
substantially modify its input term.

\ENDDOC
\DOC{CHANGED\_TAC}

\TYPE {\small\verb%CHANGED_TAC : (tactic -> tactic)%}\egroup

\SYNOPSIS
Makes a tactic fail if it has no effect.

\DESCRIBE
When applied to a tactic {\small\verb%T%}, the tactical {\small\verb%CHANGED_TAC%} gives a new tactic
which is the same as {\small\verb%T%} if that has any effect, and otherwise fails.

\FAILURE
The application of {\small\verb%CHANGED_TAC%} to a tactic never fails. The resulting
tactic fails if the basic tactic either fails or has no effect.

\SEEALSO
TRY, VALID.

\ENDDOC
\DOC{change\_state}

\TYPE {\small\verb%change_state : (goalstack -> void)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{CHECK\_ASSUME\_TAC}

\TYPE {\small\verb%CHECK_ASSUME_TAC : thm_tactic%}\egroup

\SYNOPSIS
Adds a theorem to the assumption list of goal, unless it solves the goal.

\DESCRIBE
When applied to a theorem {\small\verb%A' |- s%} and a goal {\small\verb%A ?- t%}, the tactic
{\small\verb%CHECK_ASSUME_TAC%} checks whether the theorem will solve the goal (this
includes the possibility that the theorem is just {\small\verb%A' |- F%}). If so, the goal
is duly solved. If not, the theorem is added to the assumptions of the goal,
unless it is already there.
{\par\samepage\setseps\small
\begin{verbatim}
       A ?- t
   ==============  CHECK_ASSUME_TAC (A' |- F)   [special case 1]


       A ?- t
   ==============  CHECK_ASSUME_TAC (A' |- t)   [special case 2]


       A ?- t
   ==============  CHECK_ASSUME_TAC (A' |- s)   [general case]
    A u {s} ?- t
\end{verbatim}
}
\noindent Unless {\small\verb%A'%} is a subset of {\small\verb%A%}, the tactic will be invalid, although
it will not fail.

\FAILURE
Never fails.

\SEEALSO
ACCEPT_TAC, ASSUME_TAC, CONTR_TAC, DISCARD_TAC, MATCH_ACCEPT_TAC.

\ENDDOC
\DOC{check\_lhs}

\TYPE {\small\verb%check_lhs : (term -> term list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{check\_specification}

\TYPE {\small\verb%check_specification : (* -> (string # string) list -> thm -> goal)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{check\_valid}

\TYPE {\small\verb%check_valid : (goal -> subgoals -> bool)%}\egroup

\SYNOPSIS
Checks whether a prospective proof is valid.

\DESCRIBE
{\small\verb%check_valid (A,t) ([A1,t1;...;An,tn],prf)%} checks whether the applying the
proof {\small\verb%prf%} to the list of theorems {\small\verb%[(A1 |- t1);...;(An |- tn)]%} would produce
a theorem alpha-equivalent to {\small\verb%A |- t%}. This check is done by creating this
list of theorems using {\small\verb%chktac%} and then applying the proof {\small\verb%prf%}.

\FAILURE
Never fails, unless the proof {\small\verb%prf%} fails or the assignable variable {\small\verb%chktac%}
has been rebound to a function that fails.

\SEEALSO
chktac, VALID.

\ENDDOC
\DOC{check\_varstruct}

\TYPE {\small\verb%check_varstruct : (term -> term list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{chktac}

\TYPE {\small\verb%chktac : (subgoals -> thm)%}\egroup

\SYNOPSIS
Applies a proof to a list of theorems created using {\small\verb%mk_thm%}.

\DESCRIBE
Evaluating {\small\verb%chktac ([A1,t1;...;An,tn],prf)%} applies the proof {\small\verb%prf%} to the list
of theorems {\small\verb%[(A1 |- t1);...;(An |- tn)]%}.  The list is created by mapping
{\small\verb%mk_thm%} down the supplied list of subgoals.

{\small\verb%chktac%} is, in fact, an assignable variable in ML, bound when the system is
built to a function that uses {\small\verb%mk_thm%} Its presence therefore introduces a
potential insecurity into the system.  But the function {\small\verb%chktac%} is used only
by {\small\verb%check_valid%} to check the validity of tactics, and users worried about
security can therefore eliminate this insecurity by doing:
{\par\samepage\setseps\small
\begin{verbatim}
   chktak := \(gl,prf). fail
\end{verbatim}
}
\noindent This will disable the validity checking of tactics (using {\small\verb%VALID%}),
but will remove the insecurity.

\FAILURE
Never fails (unless the proof {\small\verb%prf%} fails).

\SEEALSO
check_valid, VALID.

\ENDDOC
\DOC{CHOOSE}

\TYPE {\small\verb%CHOOSE : ((term # thm) -> thm -> thm)%}\egroup

\SYNOPSIS
Eliminates existential quantification using deduction from a
particular witness.

\DESCRIBE
When applied to a term-theorem pair {\small\verb%(v,A1 |- ?x. s)%} and a second
theorem of the form {\small\verb%A2 u {s[v/x]} |- t%}, the inference rule {\small\verb%CHOOSE%}
produces the theorem {\small\verb%A1 u A2 |- t%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- ?x. s[x]    A2 u {s[v/x]} |- t
   ---------------------------------------  CHOOSE ("v",(A1 |- ?x. s))
                A1 u A2 |- t
\end{verbatim}
}
\noindent Where {\small\verb%v%} is not free in {\small\verb%A2%} or {\small\verb%t%}.

\FAILURE
Fails unless the terms and theorems correspond as indicated above; in
particular, 1) {\small\verb%v%} must be a variable and have the same type as the variable
existentially quantified over, and it must not be free in {\small\verb%A2%} or {\small\verb%t%};
2) the second theorem must have {\small\verb%s[v/x]%} in its assumptions.


\SEEALSO
CHOOSE_TAC, EXISTS, EXISTS_TAC, SELECT_ELIM.

\ENDDOC
\DOC{CHOOSE\_TAC}

\TYPE {\small\verb%CHOOSE_TAC : thm_tactic%}\egroup

\SYNOPSIS
Adds the body of an existentially quantified theorem to the assumptions of
a goal.

\DESCRIBE
When applied to a theorem {\small\verb%A' |- ?x. t%} and a goal, {\small\verb%CHOOSE_TAC%} adds
{\small\verb%t[x'/x]%} to the assumptions of the goal, where {\small\verb%x'%} is a variant of {\small\verb%x%}
which is not free in the assumption list; normally {\small\verb%x'%} is just {\small\verb%x%}.
{\par\samepage\setseps\small
\begin{verbatim}
         A ?- u
   ====================  CHOOSE_TAC (A' |- ?x. t)
    A u {t[x'/x]} ?- u
\end{verbatim}
}
\noindent Unless {\small\verb%A'%} is a subset of {\small\verb%A%}, this is not a valid tactic.

\FAILURE
Fails unless the given theorem is existentially quantified.

\EXAMPLE
Suppose we have a goal asserting that the output of an electrical circuit
(represented as a boolean-valued function) will become high at some time:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- ?t. output(t)
\end{verbatim}
}
\noindent and we have the following theorems available:
{\par\samepage\setseps\small
\begin{verbatim}
   t1 = |- ?t. input(t)
   t2 = !t. input(t) ==> output(t+1)
\end{verbatim}
}
\noindent Then the goal can be solved by the application of:
{\par\samepage\setseps\small
\begin{verbatim}
   CHOOSE_TAC t1 THEN EXISTS_TAC "t+1" THEN
     UNDISCH_TAC "input (t:num) :bool" THEN MATCH_ACCEPT_TAC t2
\end{verbatim}
}
\SEEALSO
CHOOSE_THEN, X_CHOOSE_TAC.

\ENDDOC
\DOC{CHOOSE\_THEN}

\TYPE {\small\verb%CHOOSE_THEN : thm_tactical%}\egroup

\SYNOPSIS
Applies a tactic generated from the body of existentially quantified theorem.

\DESCRIBE
When applied to a theorem-tactic {\small\verb%ttac%}, an existentially quantified
theorem {\small\verb%A' |- ?x. t%}, and a goal, {\small\verb%CHOOSE_THEN%} applies the tactic {\small\verb%ttac
(t[x'/x] |- t[x'/x])%} to the goal, where {\small\verb%x'%} is a variant of {\small\verb%x%} chosen not to
be free in the assumption list of the goal. Thus if:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- s1
   =========  ttac (t[x'/x] |- t[x'/x])
    B ?- s2
\end{verbatim}
}
\noindent then
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- s1
   ==========  CHOOSE_THEN ttac (A' |- ?x. t)
    B ?- s2
\end{verbatim}
}
\noindent This is invalid unless {\small\verb%A'%} is a subset of {\small\verb%A%}.

\FAILURE
Fails unless the given theorem is existentially quantified, or if the
resulting tactic fails when applied to the goal.

\EXAMPLE
This theorem-tactical and its relatives are very useful for using existentially
quantified theorems. For example one might use the inbuilt theorem
{\par\samepage\setseps\small
\begin{verbatim}
   LESS_ADD_1 = |- !m n. n < m ==> (?p. m = n + (p + 1))
\end{verbatim}
}
\noindent to help solve the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- x < y ==> 0 < y * y
\end{verbatim}
}
\noindent by starting with the following tactic
{\par\samepage\setseps\small
\begin{verbatim}
   DISCH_THEN (CHOOSE_THEN SUBST1_TAC o MATCH_MP LESS_ADD_1)
\end{verbatim}
}
\noindent which reduces the goal to
{\par\samepage\setseps\small
\begin{verbatim}
   ?- 0 < ((x + (p + 1)) * (x + (p + 1)))
\end{verbatim}
}
\noindent which can then be finished off quite easily, by, for example:
{\par\samepage\setseps\small
\begin{verbatim}
   REWRITE_TAC[ADD_ASSOC; SYM (SPEC_ALL ADD1);
               MULT_CLAUSES; ADD_CLAUSES; LESS_0]
\end{verbatim}
}
\SEEALSO
CHOOSE_TAC, X_CHOOSE_THEN.

\ENDDOC
\DOC{chop\_list}

\TYPE {\small\verb%chop_list : (int -> * list -> (* list # * list))%}\egroup

\SYNOPSIS
Chops a list into two parts at a specified point.

\DESCRIBE
{\small\verb%chop_list i [x1;...;xn]%} returns {\small\verb%([x1;...;xi],[x(i+1);...;xn])%}.

\FAILURE
Fails with {\small\verb%chop_list%} if {\small\verb%i%} is negative or greater than the length of the
list.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#chop_list 3 [1;2;3;4;5];;
([1; 2; 3], [4; 5]) : (int list # int list)
\end{verbatim}
}
\SEEALSO
partition.

\ENDDOC
\DOC{close}

\TYPE {\small\verb%close : (string -> void)%}\egroup

\SYNOPSIS
Closes an {\small\verb%ML%} port.

\DESCRIBE
The function {\small\verb%close%} closes a port that had been opened for
reading (by {\small\verb%openi%}) or writing (by {\small\verb%openw%} or {\small\verb%append_openw%}).
Ports are represented by the strings that are returned by one of the
functions {\small\verb%append-openw%}, {\small\verb%openi%} and {\small\verb%openw%}.

\FAILURE
Fails when the named port is not open.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#openw `foo`;;
`%foo` : string

#close it;;
() : void
\end{verbatim}
}
\SEEALSO
append_openw, openi, openw, read, write

\ENDDOC
\DOC{close\_theory}

\TYPE {\small\verb%close_theory : (void -> void)%}\egroup

\SYNOPSIS
Finishes a session in draft mode, writing changes to the theory file.

\DESCRIBE
Executing {\small\verb%close_theory()%} finishes a session in draft mode. It switches the
system to proof mode. Changes made to the current theory segment are written to
the theory file associated with it. For a theory segment named {\small\verb%`thy`%}, the
associated file will be {\small\verb%thy.th%} in the directory from which HOL was called. If
the theory file does not exist, it will be created.
If HOL is quitted before {\small\verb%close_theory%} is invoked, the additions made to the
segment may not persist to future HOL sessions. Whilst in proof mode, the only
changes which may be made to the theory are the addition of theorems. The
theory segment may later be extended with {\small\verb%extend_theory%}.

\FAILURE
A call to {\small\verb%close_theory%} will fail if the system is not in draft mode.
Since it involves writing to the file system, if the write fails for
any reason {\small\verb%close_theory%} will fail.

\SEEALSO
extend_theory, new_theory, print_theory.

\ENDDOC
\DOC{Co}

\TYPE {\small\verb%$Co : (((* -> ** -> ***) # (**** -> *)) -> ** -> **** -> ***)%}\egroup

\SYNOPSIS
Performs permuted function composition: {\small\verb%(f Co g) x y%} = {\small\verb%f (g y) x%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, CB, I, K, KI, o, oo, S, W.

\ENDDOC
\DOC{combine}

\TYPE {\small\verb%combine : ((* list # ** list) -> (* # **) list)%}\egroup

\SYNOPSIS
Converts a pair of lists into a list of pairs.

\DESCRIBE
{\small\verb%combine ([x1;...;xn],[y1;...;yn])%} returns {\small\verb%[(x1,y1);...;(xn,yn)]%}.

\FAILURE
Fails if the two lists are of different lengths.

\COMMENTS
Has the same effect as {\small\verb%com%}.

\SEEALSO
com, split.

\ENDDOC
\DOC{com}

\TYPE {\small\verb%$com : ((* list # ** list) -> (* # **) list)%}\egroup

\SYNOPSIS
Converts a pair of lists into a list of pairs (infix version).

\DESCRIBE
{\small\verb%[x1;...;xn] com [y1;...;yn]%} returns {\small\verb%[(x1,y1);...;(xn,yn)]%}.

\FAILURE
Fails if the two lists are of different lengths.

\COMMENTS
Has the same effect as {\small\verb%combine%}.

\SEEALSO
combine, split.

\ENDDOC
\DOC{compile}

\TYPE {\small\verb%compile : ((string # bool) -> void)%}\egroup

\SYNOPSIS
Compiles the named ML source file.

\DESCRIBE
Given a pair {\small\verb%(`name`,flag)%}, {\small\verb%compile%} loads the named file and then compiles
it into LISP, generating a file {\small\verb%name_ml.l%}. It then calls the LISP compiler to
create an object file {\small\verb%name_ml.o%}. The intermediate LISP file is automatically
deleted once the {\small\verb%name_ml.o%} file has been generated. If {\small\verb%flag%} is {\small\verb%true%}, a
verbose account of the compilation is generated, if {\small\verb%flag%} is {\small\verb%false%},
compilation is silent.

\FAILURE
Fails if the named {\small\verb%ML%} source file does not exist, or if the load is
unsuccessful. In the latter case, the intermediate {\small\verb%name_ml.l%} file is
left undeleted.

\EXAMPLE
To compile two files {\small\verb%a.ml%} and {\small\verb%b.ml%}, where {\small\verb%b.ml%} depends on definitions
made in {\small\verb%a.ml%}, one can type:
{\par\samepage\setseps\small
\begin{verbatim}
   #compile (`a`,true);;
   #compile (`b`,true);;
\end{verbatim}
}
\noindent Suppose one exists the {\small\verb%HOL%} session and attempts to
load the files in a new session:
{\par\samepage\setseps\small
\begin{verbatim}
   #load(`a`,false);;
   [fasl a_ml.o]
   #load(`b`,false);;
   [fasl b_ml.o]
\end{verbatim}
}
\noindent Note that {\small\verb%load%} always loads an object file if one exists,
regardless of its creation date. Loading {\small\verb%a_ml.o%} sets up the static bindings
necessary for {\small\verb%b_ml.o%} to run. File {\small\verb%b.ml%} may be edited without recompilation
of {\small\verb%a.ml%}, however, if {\small\verb%a.ml%} is edited and recompiled, then {\small\verb%b.ml%} has to be
recompiled before being used. Consequently, if the {\small\verb%ML%} code built into the
system is recompiled, users have to recompile all their programs.

\COMMENTS
Compiled {\small\verb%ML%} runs faster than interpreted {\small\verb%ML%}, and loads almost
instantaneously.

There is a potential problem with compiling code that mentions the names of
theorems set up to be autoloaded.  Suppose a file {\small\verb%f.ml%} is to be compiled and
contains the following code:
{\par\samepage\setseps\small
\begin{verbatim}
   let f x = SPEC x num_CASES;;
\end{verbatim}
}
\noindent where {\small\verb%num_CASES%} is a built-in theorem which is set up to be
autoloaded on demand.  If, in a given session, the theorem {\small\verb%num_CASES%} has
already been autoloaded before the file {\small\verb%f.ml%} is compiled, then the resulting
object code will not itself autoload this theorem; it will just evaluate a
compiled version of the identifier {\small\verb%num_CASES%} when the function {\small\verb%f%} is called.
In particular, an unbound identifier error will occur if the compiled file
{\small\verb%f_ml.o%} is loaded in a separate session and the function {\small\verb%f%} is then called.

To get around this problem, one should rewrite functions that refer to
autoloaded values so that they explicitly fetch the required theorems from
disk. In general, one must arrange for code to be compiled not to invoke any
autoloading action.  For the example shown above, this could be done by
defining the function {\small\verb%f%} as follows.
{\par\samepage\setseps\small
\begin{verbatim}
   let f =
       let thm = theorem `arithmetic` `num_CASES` in
       \x. SPEC x thm;;
\end{verbatim}
}
\noindent Note that {\small\verb%thm%} in this definition is not the name of any
automatically autoloaded theorem.  Note also that it would be most
undesirable to define {\small\verb%f%} by:
{\par\samepage\setseps\small
\begin{verbatim}
   let f x =
       let thm = theorem `arithmetic` `num_CASES` in
       SPEC x thm;;
\end{verbatim}
}
\noindent With this definition, function {\small\verb%f%} fetches {\small\verb%num_CASES%} off disk each
time it is called, rather than just once when it is defined.

\SEEALSO
compilef, compilet, load, loadf, loadt.

\ENDDOC
\DOC{compilef}

\TYPE {\small\verb%compilef : (string -> void)%}\egroup

\SYNOPSIS
Compiles an ML source file `silently'.

\DESCRIBE
Given a string {\small\verb%`name`%}, {\small\verb%compile%} loads the named file, and then compiles it
into LISP generating a file {\small\verb%name_ml.l%}. It then calls the LISP compiler to
create an object file {\small\verb%name_ml.o%}. The intermediate LISP file is automatically
deleted once the {\small\verb%name_ml.o%} file has been generated. Loading and compilation
are silent.

\FAILURE
Fails if the named ML source file does not exist, or if the load is
unsuccessful. In the latter case, the intermediate {\small\verb%name_ml.l%} file is
left undeleted.

\COMMENTS
The function call {\small\verb%compilef `foo`%} is the same as {\small\verb%compile (`foo`,false)%}.

\SEEALSO
compile, compilet, load, loadf, loadt

\ENDDOC
\DOC{compilet}

\TYPE {\small\verb%compilet : (string -> void)%}\egroup

\SYNOPSIS
Compiles the named ML source file with verbose messages.

\DESCRIBE
Given a string {\small\verb%`name`%}, {\small\verb%compile%} loads the named file, and then compiles it
into LISP generating a file {\small\verb%name_ml.l%}. It then calls the LISP compiler to
create an object file {\small\verb%name_ml.o%}. The intermediate LISP file is automatically
deleted once the {\small\verb%name_ml.o%} file has been generated. Loading and compilation
are verbose.

\FAILURE
Fails if the named ML source file does not exist, or if the load is
unsuccessful. In the latter case, the intermediate {\small\verb%name_ml.l%} file is left
undeleted.

\COMMENTS
The function call {\small\verb%compilet `foo`%} is the same as {\small\verb%compile (`foo`,true)%}.

\SEEALSO
compile, compilet, load, loadf, loadt

\ENDDOC
\DOC{compiling}

\TYPE {\small\verb%compiling : bool%}\egroup

\SYNOPSIS
Assignable variable: true when compiling, false when loading.

\DESCRIBE
The identifier {\small\verb%compiling%} is an assignable ML variable of type {\small\verb%bool%} which
used to indicate whether the expressions currently being evaluated by ML are
being compiled or loaded.  At the start of the evaluation of a call to
{\small\verb%compile%} or its variants, the variable {\small\verb%compiling%} is set to {\small\verb%true%}; and at
the start of the evaluation of a call to {\small\verb%load%} or its variants, {\small\verb%compiling%} is
set to {\small\verb%false%}.  In both cases, the previous value of {\small\verb%compiling%} is restored
at the end of evaluation.  The initial value of {\small\verb%compiling%} when HOL is run is
{\small\verb%false%}.

\FAILURE
Evaluation of the variable {\small\verb%compiling%} never fails.

\USES
The main function of {\small\verb%compiling%} is to provide a mechanism by which expressions
may be conditionally evaluated, depending on whether they are being compiled or
not.  In particular, the main purpose of {\small\verb%compiling%} is to allow conditional
loading of files in ML. For example, suppose that the line
{\par\samepage\setseps\small
\begin{verbatim}
   if compiling then load(`foo`,false);;
\end{verbatim}
}
\noindent appears at the start of an ML file {\small\verb%bar.ml%}.  Then whenever the file
{\small\verb%bar.ml%} is compiled, the file {\small\verb%foo.ml%} will be loaded.  But whenever the file
{\small\verb%bar.ml%} is merely loaded (whether in compiled form or not) the file {\small\verb%bar.ml%}
will not be loaded.

\SEEALSO
compiling_stack.

\ENDDOC
\DOC{compiling\_stack}

\TYPE {\small\verb%compiling_stack : bool list%}\egroup

\SYNOPSIS
Keeps track of the value of the assignable variable {\small\verb%compiling%}.

\DESCRIBE
The identifier {\small\verb%compiling_stack%} is an assignable ML variable of type
{\small\verb%bool list%} which used internally by the system to keep track of the value of
the assignable variable {\small\verb%compiling%} during nested calls to {\small\verb%compile%} and {\small\verb%load%}
(and their variants).  The {\small\verb%compiling_stack%} is not intended for general use,
and no value should be assigned by users to this variable.

\FAILURE
Evaluation of the variable {\small\verb%compiling_stack%} never fails.

\SEEALSO
compiling.

\ENDDOC
\DOC{concat}

\TYPE {\small\verb%concat : (string -> string -> string)%}\egroup

\SYNOPSIS
Concatenates two ML strings.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#concat `1` ``;;
`1` : string

#concat `hello` `world`;;
`helloworld` : string

#concat `hello` (concat ` ` `world`);;
`hello world` : string
\end{verbatim}
}
\SEEALSO
concatl, \char'136.

\ENDDOC
\DOC{concatl}

\TYPE {\small\verb%concatl : (string list -> string)%}\egroup

\SYNOPSIS
Concatenates a list of ML strings.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#concatl [];;
`` : string

#concatl [`hello`;`world`];;
`helloworld` : string

#concatl [`hello`;` `;`world`];;
`hello world` : string
\end{verbatim}
}
\SEEALSO
concat, \char'136.

\ENDDOC
\DOC{concl}

\TYPE {\small\verb%concl : (thm -> term)%}\egroup

\SYNOPSIS
Returns the conclusion of a theorem.

\DESCRIBE
When applied to a theorem {\small\verb%A |- t%}, the function {\small\verb%concl%} returns {\small\verb%t%}.

\FAILURE
Never fails.

\SEEALSO
dest_thm, hyp.

\ENDDOC
\DOC{COND\_CASES\_TAC}

\TYPE {\small\verb%COND_CASES_TAC : tactic%}\egroup

\SYNOPSIS
Induces a case split on a conditional expression in the goal.

\DESCRIBE
{\small\verb%COND_CASES_TAC%} searches for a conditional sub-term in the term of a goal,
i.e. a sub-term of the form {\small\verb%p=>u|v%}, choosing one by its own criteria if there
is more than one. It then induces a case split over {\small\verb%p%} as follows:
{\par\samepage\setseps\small
\begin{verbatim}
                             A ?- t
    =======================================================  COND_CASES_TAC
     A u {p} ?- t[u/(p=>u|v)]   A u {~p} ?- t[v/(p=>u|v)]]
\end{verbatim}
}
\noindent where {\small\verb%p%} is not a constant, and the term {\small\verb%p=>u|v%} is free in {\small\verb%t%}.
Note that it both enriches the assumptions and inserts the assumed value into
the conditional.

\FAILURE
{\small\verb%COND_CASES_TAC%} fails if there is no conditional sub-term as described above.

\EXAMPLE
For {\small\verb%"x"%}, {\small\verb%"y"%}, {\small\verb%"z1"%} and {\small\verb%"z2"%} of type {\small\verb%":*"%}, and {\small\verb%"P:*->bool"%},
{\par\samepage\setseps\small
\begin{verbatim}
   COND_CASES_TAC ([], "x = (P y => z1 | z2)");;
   ([(["P y"], "x = z1"); (["~P y"], "x = z2")], -) : subgoals
\end{verbatim}
}
\noindent but it fails, for example, if {\small\verb%"y"%} is not free in the
term part of the goal:
{\par\samepage\setseps\small
\begin{verbatim}
   COND_CASES_TAC ([], "!y. x = (P y => z1 | z2)");;
   evaluation failed     COND_CASES_TAC
\end{verbatim}
}
\noindent In contrast, {\small\verb%ASM_CASES_TAC%} does not perform the replacement:
{\par\samepage\setseps\small
\begin{verbatim}
   ASM_CASES_TAC "P y" ([], "x = (P y => z1 | z2)");;
   ([(["P y"], "x = (P y => z1 | z2)"); (["~P y"], "x = (P y => z1 | z2)")],
    -)
   : subgoals
\end{verbatim}
}
\USES
Useful for case analysis and replacement in one step, when there is a
conditional sub-term in the term part of the goal.  When there is more than
one such sub-term and one in particular is to be analyzed, {\small\verb%COND_CASES_TAC%}
cannot be depended on to choose the `desired' one. It can, however, be used
repeatedly to analyze all conditional sub-terms of a goal.

\SEEALSO
ASM_CASES_TAC, DISJ_CASES_TAC, STRUCT_CASES_TAC.

\ENDDOC
\DOC{COND\_CONV}

\TYPE {\small\verb%COND_CONV : conv%}\egroup

\SYNOPSIS
Simplifies conditional terms.

\DESCRIBE
The conversion {\small\verb%COND_CONV%} simplifies a conditional term {\small\verb%"c => u | v"%} if
the condition {\small\verb%c%} is either the constant {\small\verb%T%} or the constant {\small\verb%F%} or
if the two terms {\small\verb%u%} and {\small\verb%v%} are equivalent up to alpha-conversion.
The theorems returned in these three cases have the forms:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (T => u | v) = u

   |- (F => u | v) = u

   |- (c => u | u) = u
\end{verbatim}
}
\FAILURE
{\small\verb%COND_CONV tm%} fails if {\small\verb%tm%} is not a conditional {\small\verb%"c => u | v"%}, where
{\small\verb%c%} is {\small\verb%T%} or {\small\verb%F%}, or {\small\verb%u%} and {\small\verb%v%} are alpha-equivalent.

\ENDDOC
\DOC{CONJ\_DISCH}

\TYPE {\small\verb%CONJ_DISCH : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Discharges an assumption and conjoins it to both sides of an equation.

\DESCRIBE
Given an term {\small\verb%t%} and a theorem {\small\verb%A |- t1 = t2%}, which is an equation between
boolean terms, {\small\verb%CONJ_DISCH%} returns {\small\verb%A - {t} |- (t /\ t1) = (t /\ t2)%}, i.e.
conjoins {\small\verb%t%} to both sides of the equation, removing {\small\verb%t%} from the assumptions
if it was there.
{\par\samepage\setseps\small
\begin{verbatim}
            A |- t1 = t2
   ------------------------------  CONJ_DISCH "t"
    A - {t} |- t /\ t1 = t /\ t2
\end{verbatim}
}
\FAILURE
Fails unless the theorem is an equation, both sides of which, and the term
provided are of type {\small\verb%bool%}.

\SEEALSO
CONJ_DISCHL.

\ENDDOC
\DOC{CONJ\_DISCHL}

\TYPE {\small\verb%CONJ_DISCHL : (term list -> thm -> thm)%}\egroup

\SYNOPSIS
Conjoins multiple assumptions to both sides of an equation.

\DESCRIBE
Given a term list {\small\verb%[t1;...;tn]%} and a theorem whose conclusion is an equation
between boolean terms, {\small\verb%CONJ_DISCHL%} conjoins all the terms
in the list to both sides of the equation, and removes any of the terms which
were in the assumption list.
{\par\samepage\setseps\small
\begin{verbatim}
                        A |- s = t
   --------------------------------------------------------  CONJ_DISCHL
    A - {t1,...,tn} |- (t1/\.../\tn/\s) = (t1/\.../\tn/\t)     ["t1";...;"tn"]
\end{verbatim}
}
\FAILURE
Fails unless the theorem is an equation, both sides of which, and all the terms
provided, are of type {\small\verb%bool%}.

\SEEALSO
CONJ_DISCH.

\ENDDOC
\DOC{CONJ}

\TYPE {\small\verb%CONJ : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Introduces a conjunction.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1      A2 |- t2
   ------------------------  CONJ
     A1 u A2 |- t1 /\ t2
\end{verbatim}
}
\FAILURE
Never fails.

\SEEALSO
BODY_CONJUNCTS, CONJUNCT1, CONJUNCT2, CONJ_PAIR, LIST_CONJ, CONJ_LIST, CONJUNCTS.

\ENDDOC
\DOC{CONJ\_LIST}

\TYPE {\small\verb%CONJ_LIST : (int -> thm -> thm list)%}\egroup

\SYNOPSIS
Extracts a list of conjuncts from a theorem (non-flattening version).

\DESCRIBE
{\small\verb%CONJ_LIST%} is the proper inverse of {\small\verb%LIST_CONJ%}. Unlike {\small\verb%CONJUNCTS%} which
recursively splits as many conjunctions as possible both to the left and to
the right, {\small\verb%CONJ_LIST%} splits the top-level conjunction and then splits
(recursively) only the right conjunct. The integer argument is required
because the term {\small\verb%tn%} may itself be a conjunction. A list of {\small\verb%n%} theorems is
returned.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 /\ (t2 /\ ( ... /\ tn)...)
   ------------------------------------  CONJ_LIST n (A |- t1 /\ ... /\ tn)
    A |- t1   A |- t2   ...   A |- tn
\end{verbatim}
}
\FAILURE
Fails if the integer argument ({\small\verb%n%}) is less than one, or if the input theorem
has less than {\small\verb%n%} conjuncts.

\EXAMPLE
Suppose the identifier {\small\verb%th%} is bound to the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- (x /\ y) /\ z /\ w
\end{verbatim}
}
\noindent Here are some applications of {\small\verb%CONJ_LIST%} to {\small\verb%th%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #CONJ_LIST 0 th;;
   evaluation failed     CONJ_LIST

   #CONJ_LIST 1 th;;
   [A |- (x /\ y) /\ z /\ w] : thm list

   #CONJ_LIST 2 th;;
   [A |- x /\ y; A |- z /\ w] : thm list

   #CONJ_LIST 3 th;;
   [A |- x /\ y; A |- z; A |- w] : thm list

   #CONJ_LIST 4 th;;
   evaluation failed     CONJ_LIST
\end{verbatim}
}
\SEEALSO
BODY_CONJUNCTS, LIST_CONJ, CONJUNCTS, CONJ, CONJUNCT1, CONJUNCT2, CONJ_PAIR.

\ENDDOC
\DOC{CONJ\_PAIR}

\TYPE {\small\verb%CONJ_PAIR : (thm -> (thm # thm))%}\egroup

\SYNOPSIS
Extracts both conjuncts of a conjunction.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t1 /\ t2
   ----------------------  CONJ_PAIR
    A |- t1      A |- t2
\end{verbatim}
}
\noindent The two resultant theorems are returned as a pair.

\FAILURE
Fails if the input theorem is not a conjunction.

\SEEALSO
BODY_CONJUNCTS, CONJUNCT1, CONJUNCT2, CONJ, LIST_CONJ, CONJ_LIST, CONJUNCTS.

\ENDDOC
\DOC{CONJ\_SET\_CONV}

\TYPE {\small\verb%CONJ_SET_CONV : (term list -> term list -> thm)%}\egroup

\SYNOPSIS
Proves the equivalence of the conjunctions of two equal sets of terms.

\DESCRIBE
The arguments to {\small\verb%CONJ_SET_CONV%} are two lists of terms {\small\verb%[t1;...;tn]%} and
{\small\verb%[u1;...;um]%}.  If these are equal when considered as sets, that is if the sets
{\par\samepage\setseps\small
\begin{verbatim}
   {t1,...,tn} and {u1,...,um}
\end{verbatim}
}
\noindent are equal, then {\small\verb%CONJ_SET_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t1 /\ ... /\ tn) = (u1 /\ ... /\ um)
\end{verbatim}
}
\noindent Otherwise {\small\verb%CONJ_SET_CONV%} fails.

\FAILURE
{\small\verb%CONJ_SET_CONV [t1;...;tn] [u1;...;um]%} fails if {\small\verb%[t1,...,tn]%} and
{\small\verb%[u1,...,um]%}, regarded as sets of terms, are not equal. Also fails
if any {\small\verb%ti%} or {\small\verb%ui%} does not have type {\small\verb%bool%}.

\USES
Used to order conjuncts.  First sort a list of conjuncts {\small\verb%l1%} into the
desired order to get a new list {\small\verb%l2%}, then call {\small\verb%CONJ_SET_CONV l1 l2%}.

\COMMENTS
This is not a true conversion, so perhaps it ought to be called something else.

\SEEALSO
CONJUNCTS_CONV.

\ENDDOC
\DOC{CONJ\_TAC}

\TYPE {\small\verb%CONJ_TAC : tactic%}\egroup

\SYNOPSIS
Reduces a conjunctive goal to two separate subgoals.

\DESCRIBE
When applied to a goal {\small\verb%A ?- t1 /\ t2%}, the tactic {\small\verb%CONJ_TAC%} reduces it to the
two subgoals corresponding to each conjunct separately.
{\par\samepage\setseps\small
\begin{verbatim}
       A ?- t1 /\ t2
   ======================  CONJ_TAC
    A ?- t1      A ?- t2
\end{verbatim}
}
\FAILURE
Fails unless the conclusion of the goal is a conjunction.

\SEEALSO
STRIP_TAC.

\ENDDOC
\DOC{CONJUNCT1}

\TYPE {\small\verb%CONJUNCT1 : (thm -> thm)%}\egroup

\SYNOPSIS
Extracts left conjunct of theorem.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 /\ t2
   ---------------  CONJUNCT1
       A |- t1
\end{verbatim}
}
\FAILURE
Fails unless the input theorem is a conjunction.

\SEEALSO
BODY_CONJUNCTS, CONJUNCT2, CONJ_PAIR, CONJ, LIST_CONJ, CONJ_LIST, CONJUNCTS.

\ENDDOC
\DOC{CONJUNCT2}

\TYPE {\small\verb%CONJUNCT2 : (thm -> thm)%}\egroup

\SYNOPSIS
Extracts right conjunct of theorem.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 /\ t2
   ---------------  CONJUNCT2
       A |- t2
\end{verbatim}
}
\FAILURE
Fails unless the input theorem is a conjunction.

\SEEALSO
BODY_CONJUNCTS, CONJUNCT1, CONJ_PAIR, CONJ, LIST_CONJ, CONJ_LIST, CONJUNCTS.

\ENDDOC
\DOC{CONJUNCTS\_CONV}

\TYPE {\small\verb%CONJUNCTS_CONV : ((term # term) -> thm)%}\egroup

\SYNOPSIS
Prove equivalence under idempotence, symmetry and associativity of conjunction.

\DESCRIBE
{\small\verb%CONJUNCTS_CONV%} takes a pair of terms {\small\verb%"t1"%} and {\small\verb%"t2"%}, and proves
{\small\verb%|- t1 = t2%} if {\small\verb%t1%} and {\small\verb%t2%} are equivalent up to idempotence, symmetry and
associativity of conjunction.  That is, if {\small\verb%t1%} and {\small\verb%t2%} are two (different)
arbitrarily-nested conjunctions of the same set of terms, then {\small\verb%CONJUNCTS_CONV
(t1,t2)%} returns {\small\verb%|- t1 = t2%}. Otherwise, it fails.

\FAILURE
Fails if {\small\verb%t1%} and {\small\verb%t2%} are not equivalent, as described above.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#CONJUNCTS_CONV ("(P /\ Q) /\ R", "R /\ (Q /\ R) /\ P");;
|- (P /\ Q) /\ R = R /\ (Q /\ R) /\ P
\end{verbatim}
}
\USES
Used to reorder a conjunction.  First sort the conjuncts in a term {\small\verb%t1%} into
the desired order (e.g. lexicographic order, for normalization) to get a new
term {\small\verb%t2%}, then call {\small\verb%CONJUNCTS_CONV(t1,t2)%}.

\COMMENTS
This is not a true conversion, so perhaps it ought to be called something else.

\SEEALSO
CONJ_SET_CONV.

\ENDDOC
\DOC{conjuncts}

\TYPE {\small\verb%conjuncts : (term -> term list)%}\egroup

\SYNOPSIS
Iteratively splits conjunctions into a list of conjuncts.

\DESCRIBE
{\small\verb%conjuncts "t1 /\ ... /\ tn"%} returns {\small\verb%["t1";...;"tn"]%}.
The argument term may be any tree of conjunctions.
It need not have the form {\small\verb%"t1 /\ (t2 /\ ( ... /\ tn)...)"%}.
A term that is not a conjunction is simply returned as the sole element of a
list. Note that

{\par\samepage\setseps\small
\begin{verbatim}
   conjuncts(list_mk_conj(["t1";...;"tn"]))
\end{verbatim}
}
\noindent will not return {\small\verb%["t1";...;"tn"]%} if any of {\small\verb%t1%},...,{\small\verb%tn%} are
conjunctions.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_conj ["a /\ b";"c /\ d";"e /\ f"];;
"(a /\ b) /\ (c /\ d) /\ e /\ f" : term

#conjuncts it;;
["a"; "b"; "c"; "d"; "e"; "f"] : term list

#list_mk_conj it;;
"a /\ b /\ c /\ d /\ e /\ f" : term

#conjuncts "1";;
["1"] : term list
\end{verbatim}
}
\COMMENTS
Because {\small\verb%conjuncts%} splits both the left and right sides of a conjunction,
this operation is not the inverse of {\small\verb%list_mk_conj%}. It may be useful to
introduce {\small\verb%list_dest_conj%} for splitting only the right tails of a conjunction.

\SEEALSO
list_mk_conj, dest_conj.

\ENDDOC
\DOC{CONJUNCTS}

\TYPE {\small\verb%CONJUNCTS : (thm -> thm list)%}\egroup

\SYNOPSIS
Recursively splits conjunctions into a list of conjuncts.

\DESCRIBE
Flattens out all conjuncts, regardless of grouping. Returns a singleton list
if the input theorem is not a conjunction.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t1 /\ t2 /\ ... /\ tn
   -----------------------------------  CONJUNCTS
    A |- t1   A |- t2   ...   A |- tn
\end{verbatim}
}
\FAILURE
Never fails.

\EXAMPLE
Suppose the identifier {\small\verb%th%} is bound to the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- (x /\ y) /\ z /\ w
\end{verbatim}
}
\noindent Application of {\small\verb%CONJUNCTS%} to {\small\verb%th%} returns the following list of
theorems:
{\par\samepage\setseps\small
\begin{verbatim}
   [A |- x; A |- y; A |- z; A |- w] : thm list
\end{verbatim}
}
\SEEALSO
BODY_CONJUNCTS, CONJ_LIST, LIST_CONJ, CONJ, CONJUNCT1, CONJUNCT2, CONJ_PAIR.

\ENDDOC
\DOC{CONJUNCTS\_THEN2}

\TYPE {\small\verb%CONJUNCTS_THEN2 : (thm_tactic -> thm_tactic -> thm_tactic)%}\egroup

\SYNOPSIS
Applies two theorem-tactics to the corresponding conjuncts of a theorem.

\DESCRIBE
{\small\verb%CONJUNCTS_THEN2%} takes two theorem-tactics, {\small\verb%f1%} and {\small\verb%f2%}, and a theorem {\small\verb%t%}
whose conclusion must be a conjunction. {\small\verb%CONJUNCTS_THEN2%} breaks {\small\verb%t%} into two
new theorems, {\small\verb%t1%} and {\small\verb%t2%} which are {\small\verb%CONJUNCT1%} and {\small\verb%CONJUNCT2%} of {\small\verb%t%}
respectively, and then returns the tactic {\small\verb%f1 t1 THEN f2 t2%}. Thus
{\par\samepage\setseps\small
\begin{verbatim}
   CONJUNCTS_THEN2 f1 f2 (A |- l /\ r) =  f1 (A |- l) THEN f2 (A |- r)
\end{verbatim}
}
\noindent so if
{\par\samepage\setseps\small
\begin{verbatim}
   A1 ?- t1                     A2 ?- t2
  ==========  f1 (A |- l)      ==========  f2 (A |- r)
   A2 ?- t2                     A3 ?- t3
\end{verbatim}
}
\noindent then
{\par\samepage\setseps\small
\begin{verbatim}
    A1 ?- t1
   ==========  CONJUNCTS_THEN2 f1 f2 (A |- l /\ r)
    A3 ?- t3
\end{verbatim}
}
\FAILURE
{\small\verb%CONJUNCTS_THEN f%} will fail if applied to a theorem whose conclusion is not a
conjunction.

\COMMENTS
The system shows the type as {\small\verb%(thm_tactic -> thm_tactical)%}.

\USES
The construction of complex {\small\verb%tactical%}s like {\small\verb%CONJUNCTS_THEN%}.

\SEEALSO
CONJUNCT1, CONJUNCT2, CONJUNCTS, CONJUNCTS_TAC, CONJUNCTS_THEN2,
STRIP_THM_THEN.

\ENDDOC
\DOC{CONJUNCTS\_THEN}

\TYPE {\small\verb%CONJUNCTS_THEN : thm_tactical%}\egroup

\SYNOPSIS
Applies a theorem-tactic to each conjunct of a theorem.

\DESCRIBE
{\small\verb%CONJUNCTS_THEN%} takes a theorem-tactic {\small\verb%f%}, and a theorem {\small\verb%t%} whose conclusion
must be a conjunction. {\small\verb%CONJUNCTS_THEN%} breaks {\small\verb%t%} into two new theorems, {\small\verb%t1%}
and {\small\verb%t2%} which are {\small\verb%CONJUNCT1%} and {\small\verb%CONJUNCT2%} of {\small\verb%t%} respectively, and then
returns a new tactic: {\small\verb%f t1 THEN f t2%}. That is,
{\par\samepage\setseps\small
\begin{verbatim}
   CONJUNCTS_THEN f (A |- l /\ r) =  f (A |- l) THEN f (A |- r)
\end{verbatim}
}
\noindent so if
{\par\samepage\setseps\small
\begin{verbatim}
   A1 ?- t1                    A2 ?- t2
  ==========  f (A |- l)      ==========  f (A |- r)
   A2 ?- t2                    A3 ?- t3
\end{verbatim}
}
\noindent then
{\par\samepage\setseps\small
\begin{verbatim}
    A1 ?- t1
   ==========  CONJUNCTS_THEN f (A |- l /\ r)
    A3 ?- t3
\end{verbatim}
}
\FAILURE
{\small\verb%CONJUNCTS_THEN f%} will fail if applied to a theorem whose conclusion is not a
conjunction.

\COMMENTS
{\small\verb%CONJUNCTS_THEN f (A |- u1 /\ ... /\ un)%} results in the tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   f (A |- u1) THEN f (A |- u2 /\ ... /\ un)
\end{verbatim}
}
\noindent Unfortunately, it is more likely that the user had wanted the tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   f (A |- u1) THEN ... THEN f(A |- un)
\end{verbatim}
}
\noindent Such a tactic could be defined as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   let CONJUNCTS_THENL (f:thm_tactic) thm =
         itlist $THEN (map f (CONJUNCTS thm)) ALL_TAC;;
\end{verbatim}
}
\noindent or by using {\small\verb%REPEAT_TCL%}.

\SEEALSO
CONJUNCT1, CONJUNCT2, CONJUNCTS, CONJUNCTS_TAC, CONJUNCTS_THEN2,
STRIP_THM_THEN.

\ENDDOC
\DOC{constants}

\TYPE {\small\verb%constants : (string -> term list)%}\egroup

\SYNOPSIS
Returns a list of the constants defined in a named theory.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   constants `thy`
\end{verbatim}
}
\noindent where {\small\verb%thy%} is an ancestor theory (the special string {\small\verb%`-`%} means the
current theory), returns a list of all the constants in that theory.

\FAILURE
Fails if the named theory does not exist, or is not an ancestor of the
current theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#constants `combin`;;
["I"; "S"; "K"; "$o"] : term list
\end{verbatim}
}
\SEEALSO
axioms, binders, definitions, infixes, theorems

\ENDDOC
\DOC{CONTRAPOS\_CONV}

\TYPE {\small\verb%CONTRAPOS_CONV : conv%}\egroup

\SYNOPSIS
Proves the equivalence of an implication and its contrapositive.

\DESCRIBE
When applied to an implication {\small\verb%P ==> Q%}, the conversion {\small\verb%CONTRAPOS_CONV%}
returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (P ==> Q) = (~Q ==> ~P)
\end{verbatim}
}
\FAILURE
Fails if applied to a term that is not an implication.

\SEEALSO
CONTRAPOS.

\ENDDOC
\DOC{CONTRAPOS}

\TYPE {\small\verb%CONTRAPOS : (thm -> thm)%}\egroup

\SYNOPSIS
Deduces the contrapositive of an implication.

\DESCRIBE
When applied to a theorem {\small\verb%A |- s ==> t%}, the inference rule {\small\verb%CONTRAPOS%}
returns its contrapositive, {\small\verb%A |- ~t ==> ~s%}.
{\par\samepage\setseps\small
\begin{verbatim}
     A |- s ==> t
   ----------------  CONTRAPOS
    A |- ~t ==> ~s
\end{verbatim}
}
\FAILURE
Fails unless the theorem is an implication.

\SEEALSO
CCONTR, CONTR, CONTRAPOS_CONV, NOT_ELIM.

\ENDDOC
\DOC{CONTR}

\TYPE {\small\verb%CONTR : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Implements the intuitionistic contradiction rule.

\DESCRIBE
When applied to a term {\small\verb%t%} and a theorem {\small\verb%A |- F%}, the inference rule {\small\verb%CONTR%}
returns the theorem {\small\verb%A |- t%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- F
   --------  CONTR "t"
    A |- t
\end{verbatim}
}
\FAILURE
Fails unless the term has type {\small\verb%bool%} and the theorem has {\small\verb%F%} as its
conclusion.

\SEEALSO
CCONTR, CONTRAPOS, CONTR_TAC, NOT_ELIM.

\ENDDOC
\DOC{CONTR\_TAC}

\TYPE {\small\verb%CONTR_TAC : thm_tactic%}\egroup

\SYNOPSIS
Solves any goal from contradictory theorem.

\DESCRIBE
When applied to a contradictory theorem {\small\verb%A' |- F%}, and a goal {\small\verb%A ?- t%},
the tactic {\small\verb%CONTR_TAC%} completely solves the goal. This is an invalid
tactic unless {\small\verb%A'%} is a subset of {\small\verb%A%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   ========  CONTR_TAC (A' |- F)

\end{verbatim}
}
\FAILURE
Fails unless the theorem is contradictory, i.e. has {\small\verb%F%} as its conclusion.

\SEEALSO
CHECK_ASSUME_TAC, CONTR, CCONTR, CONTRAPOS, NOT_ELIM.

\ENDDOC
\DOC{CONV\_RULE}

\TYPE {\small\verb%CONV_RULE : (conv -> thm -> thm)%}\egroup

\SYNOPSIS
Makes an inference rule from a conversion.

\DESCRIBE
If {\small\verb%c%} is a conversion, then {\small\verb%CONV_RULE c%} is an inference rule that applies
{\small\verb%c%} to the conclusion of a theorem.  That is, if {\small\verb%c%} maps a term {\small\verb%"t"%} to the
theorem {\small\verb%|- t = t'%}, then the rule {\small\verb%CONV_RULE c%} infers {\small\verb%|- t'%} from the
theorem {\small\verb%|- t%}.  More precisely, if {\small\verb%c "t"%} returns {\small\verb%A' |- t = t'%}, then:
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t
   --------------  CONV_RULE c
    A u A' |- t'
\end{verbatim}
}
\noindent Note that if the conversion {\small\verb%c%} returns a theorem with assumptions,
then the resulting inference rule adds these to the assumptions of the
theorem it returns.

\FAILURE
{\small\verb%CONV_RULE c th%} fails if {\small\verb%c%} fails when applied to the conclusion of {\small\verb%th%}. The
function returned by {\small\verb%CONV_RULE c%} will also fail if the ML function
{\small\verb%c:term->thm%} is not, in fact, a conversion (i.e. a function that maps a term
{\small\verb%t%} to a theorem {\small\verb%|- t = t'%}).

\SEEALSO
CONV_TAC, RIGHT_CONV_RULE.

\ENDDOC
\DOC{CONV\_TAC}

\TYPE {\small\verb%CONV_TAC : (conv -> tactic)%}\egroup

\SYNOPSIS
Makes a tactic from a conversion.

\DESCRIBE
If {\small\verb%c%} is a conversion, then {\small\verb%CONV_TAC c%} is a tactic that applies {\small\verb%c%} to the
goal.  That is, if {\small\verb%c%} maps a term {\small\verb%"g"%} to the theorem {\small\verb%|- g = g'%}, then the
tactic {\small\verb%CONV_TAC c%} reduces a goal {\small\verb%g%} to the subgoal {\small\verb%g'%}.  More precisely, if
{\small\verb%c "g"%} returns {\small\verb%A' |- g = g'%}, then:
{\par\samepage\setseps\small
\begin{verbatim}
         A ?- g
     ===============  CONV_TAC c
         A ?- g'
\end{verbatim}
}
\noindent Note that the conversion {\small\verb%c%} should return a theorem whose
assumptions are also among the assumptions of the goal (normally, the
conversion will returns a theorem with no assumptions). {\small\verb%CONV_TAC%} does not
fail if this is not the case, but the resulting tactic will be invalid, so the
theorem ultimately proved using this tactic will have more assumptions than
those of the original goal.

\FAILURE
{\small\verb%CONV_TAC c%} applied to a goal {\small\verb%A ?- g%} fails if {\small\verb%c%} fails when applied to the
term {\small\verb%g%}. The function returned by {\small\verb%CONV_TAC c%} will also fail if the ML
function {\small\verb%c:term->thm%} is not, in fact, a conversion (i.e. a function that maps
a term {\small\verb%t%} to a theorem {\small\verb%|- t = t'%}).

\USES
{\small\verb%CONV_TAC%} is used to apply simplifications that can't be expressed as
equations (rewrite rules).  For example, a goal can be simplified by
beta-reduction, which is not expressible as a single equation, using the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   CONV_TAC(DEPTH_CONV BETA_CONV)
\end{verbatim}
}
\noindent The conversion {\small\verb%BETA_CONV%} maps a beta-redex {\small\verb%"(\x.u)v"%} to the
theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\x.u)v = u[v/x]
\end{verbatim}
}
\noindent and the ML expression {\small\verb%(DEPTH_CONV BETA_CONV)%} evaluates to a
conversion that maps a term {\small\verb%"t"%} to the theorem {\small\verb%|- t=t'%} where {\small\verb%t'%} is
obtained from {\small\verb%t%} by beta-reducing all beta-redexes in {\small\verb%t%}. Thus
{\small\verb%CONV_TAC(DEPTH_CONV BETA_CONV)%} is a tactic which reduces beta-redexes
anywhere in a goal.

\SEEALSO
CONV_RULE.

\ENDDOC
\DOC{current\_theory}

\TYPE {\small\verb%current_theory : (void -> string)%}\egroup

\SYNOPSIS
Returns the name of the current theory.

\DESCRIBE
Within a HOL session there is always a current theory. It is the theory
represented by the current theory segment together with its ancestry. A call
of {\small\verb%current_theory()%} returns the name of the current theory. Initially HOL
has current theory {\small\verb%HOL%}.

\FAILURE
Never fails.

\SEEALSO
close_theory, extend_theory, load_theory, new_theory, print_theory.

\ENDDOC
\DOC{curry}

\TYPE {\small\verb%curry : (((* # **) -> ***) -> * -> ** -> ***)%}\egroup

\SYNOPSIS
Converts a function on a pair to a corresponding curried function.

\DESCRIBE
The application {\small\verb%curry f%} returns {\small\verb%\x y. f(x,y)%}, so that
{\par\samepage\setseps\small
\begin{verbatim}
   curry f x y = f(x,y)
\end{verbatim}
}
\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let increment = curry $+ 1;;
increment = - : (int -> int)

#increment 6;;
7 : int
\end{verbatim}
}
\SEEALSO
uncurry.

\ENDDOC
\DOC{DEF\_EXISTS\_RULE}

\TYPE {\small\verb%DEF_EXISTS_RULE : (term -> thm)%}\egroup

\SYNOPSIS
Proves that a function defined by a definitional equation exists.

\DESCRIBE
This rule accepts a term of the form {\small\verb%"c = ..."%} or {\small\verb%"f x1 ... xn = ..."%}, the
variables of which may be universally quantified, and returns an existential
theorem. The resulting theorem is typically used for generating HOL
specifications.

\FAILURE
{\small\verb%DEF_EXISTS_RULE%} fails if the definition is not an equation, if there
is any variable in the right-hand side which does not occur in the
left-hand side, if the definition is recursive, if there is a free type
variable, or if the name being defined by the function is not allowed.

\EXAMPLE
The effect of this rule can be understood more clearly through an
example:
{\par\samepage\setseps\small
\begin{verbatim}
   #DEF_EXISTS_RULE "max a b = ((a < b) => b | a)" ;;
   |- ?max. !a b. max a b = (a < b => b | a)
\end{verbatim}
}
\COMMENTS
In later versions of HOL this function may be made internal.

\SEEALSO
new_definition, new_gen_definition, new_specification.

\ENDDOC
\DOC{define\_finite\_set\_syntax}

\TYPE {\small\verb%define_finite_set_syntax : ((string # string) -> void)%}\egroup

\SYNOPSIS
Sets up an interpretation of finite set syntax.

\DESCRIBE
The HOL quotation parser supports the notation {\small\verb%"{x1,...,xn}"%}. This is
primarily intended to support the {\small\verb%sets%} library and dependent work,
meaning `the set consisting just of the elements {\small\verb%x1...xn%}', but
this function allows the interpretation of the notation to be changed. A call
{\par\samepage\setseps\small
\begin{verbatim}
   define_finite_set_syntax(`base`,`cons`)
\end{verbatim}
}
\noindent causes
{\par\samepage\setseps\small
\begin{verbatim}
   "{x1,x2,...,xn}"
\end{verbatim}
}
\noindent to be parsed as
{\par\samepage\setseps\small
\begin{verbatim}
   "cons x1 (cons x2 (cons ... (cons xn base) ... ))"
\end{verbatim}
}
\noindent where {\small\verb%base%} and {\small\verb%cons%} should be the names of constants, the former
of which may be an infix. The printer will invert this transformation.

\FAILURE
Fails unless both argument strings are the names of constants of the current
theory.

\EXAMPLE
We can use set notation for special boolean lists as follows
{\par\samepage\setseps\small
\begin{verbatim}
   #new_theory `snork`;;
   () : void

   #new_definition(`cons`,"cons (x:bool) (l:bool list) = CONS x l");;
   |- !x l. cons x l = CONS x l

   #new_definition(`nil`,"nil = ([]:bool list)");;
   |- nil = []

   #define_finite_set_syntax(`nil`,`cons`);;
   () : void

   #"{F,T,T}";;
   "{F,T,T}" : term

   #it = "cons F (cons T (cons T nil))";;
   true : bool
\end{verbatim}
}
\COMMENTS
For more details about the use of set notation, refer to the DESCRIPTION.

\SEEALSO
define_set_abstraction_syntax, load_library.

\ENDDOC
\DOC{define\_load\_lib\_function}

\TYPE {\small\verb%define_load_lib_function = - : (string list -> void -> void)%}\egroup

\SYNOPSIS
Defines a function for loading the contents of a library.

\DESCRIBE
 If a library is loaded while the system is not in draft mode, it may
 not be loaded completely.
 In such case, a function whose name is created by prefixing the name
 of the library with `{\small\verb%load_%}' is defined. This function can be called
 later to complete the loading.

The function {\small\verb%define_load_lib_function%} dynamically defines such a
function. It is called in the generic library loader {\small\verb%library_loader%}.
Due to the way it is called using {\small\verb%let_before%}, it can  take only a
single argument, a string list. The information passed in this list
consists of the library name, the names of theories and the names of
the code files. The library name is the first string in the list and
it is mandatory. The theory names and code file names follow, and they
are separated by a null string. Both of these are optional. E.g. the
simplest case is {\small\verb%[`lib_name`; ``]%}.

When the loading function defined by {\small\verb%define_load_lib_function%} is
called, the code files will be loaded, and the theorems and
definitions in the theories will be set up for autoloading.

\FAILURE
The function {\small\verb%define_load_lib_function%} fails if called with an
argument not in the form described above.
The loading function defined by it will fail if any of the code files
cannot be loaded successfully, or any of the theories is not in the ancestry
of the current theory.

\SEEALSO
library_loader, load_library.

\ENDDOC
\DOC{define\_new\_type\_bijections}

\TYPE {\small\verb%define_new_type_bijections : (string -> string -> string -> thm -> thm)%}\egroup

\SYNOPSIS
Introduces abstraction and representation functions for a defined type.

\DESCRIBE
The result of making a type definition using {\small\verb%new_type_definition%} is a
theorem of the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ?rep:nty->ty. TYPE_DEFINITION P rep
\end{verbatim}
}
\noindent which asserts only the existence of a bijection from the type it
defines (in this case, {\small\verb%nty%}) to the corresponding subset of an existing type
(here, {\small\verb%ty%}) whose characteristic function is specified by {\small\verb%P%}.  To
automatically introduce constants that in fact denote this bijection and its
inverse, the ML function {\small\verb%define_new_type_bijections%} is provided.

This function takes three string arguments and a theorem argument.  The theorem
argument must be a definitional axiom of the form returned by
{\small\verb%new_type_definition%}.  The first string argument is the name under which the
constant definition (a constant specification, in fact) made by
{\small\verb%define_new_type_bijections%} will be stored in the current theory segment. The
second and third string arguments are user-specified names for the two
constants that are to be defined. These constants are defined so as to denote
mutually inverse bijections between the defined type, whose definition is given
by the supplied theorem, and the representing type of this defined type.

If {\small\verb%th%} is a theorem of the form returned by {\small\verb%new_type_definition%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ?rep:newty->ty. TYPE_DEFINITION P rep
\end{verbatim}
}
\noindent then evaluating:
{\par\samepage\setseps\small
\begin{verbatim}
   define_new_type_bijections `name` `abs` `rep` th
\end{verbatim}
}
\noindent automatically defines two new constants {\small\verb%abs:ty->newty%} and
{\small\verb%rep:newty->ty%} such that:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!a. abs(rep a) = a) /\ (!r. P r = (rep(abs r) = r))
\end{verbatim}
}
\noindent This theorem, which is the defining property for the constants {\small\verb%abs%}
and {\small\verb%rep%}, is stored under the name {\small\verb%name%} in the current theory segment.  It
is also the value returned by {\small\verb%define_new_type_bijections%}.  The theorem states
that {\small\verb%abs%} is the left inverse of {\small\verb%rep%} and, for values satisfying {\small\verb%P%}, that
{\small\verb%rep%} is the left inverse of {\small\verb%abs%}.

\FAILURE
A call to {\small\verb%define_new_type_bijections name abs rep th%} fails if {\small\verb%th%} is not a
theorem of the form returned by {\small\verb%new_type_definition%}, or if either {\small\verb%abs%} or
{\small\verb%rep%} is already the name of a constant in the current theory, or there already
exists a constant definition, constant specification, type definition or axiom
named {\small\verb%name%} in the current theory, or HOL is not in draft mode.

\SEEALSO
new_type_definition, prove_abs_fn_one_one, prove_abs_fn_onto,
prove_rep_fn_one_one, prove_rep_fn_onto.

\ENDDOC
\DOC{define\_set\_abstraction\_syntax}

\TYPE {\small\verb%define_set_abstraction_syntax : (string -> void)%}\egroup

\SYNOPSIS
Sets up an interpretation of set abstraction syntax.

\DESCRIBE
The HOL quotation parser supports the notation {\small\verb%"{x | P}"%}. This is primarily
intended for use in the {\small\verb%sets%} library and dependent work, meaning `the set of
elements {\small\verb%x%} such that {\small\verb%P%} is true' (presumably {\small\verb%x%} will be free in {\small\verb%P%}), but
this function allows the interpretation to be changed. A call
{\par\samepage\setseps\small
\begin{verbatim}
   define_set_abstraction_syntax `c`
\end{verbatim}
}
\noindent where {\small\verb%c%} is a constant of the current theory, will make the
quotation parser interpret
{\par\samepage\setseps\small
\begin{verbatim}
   {x | P}
\end{verbatim}
}
\noindent as
{\par\samepage\setseps\small
\begin{verbatim}
   c (\(x1...xn). (x,P))
\end{verbatim}
}
\noindent where the {\small\verb%x1...xn%} are all the variables that occur free in both
{\small\verb%x%} or {\small\verb%P%}.  The printer will invert this transformation.

\FAILURE
Fails if {\small\verb%c%} is not a constant of the current theory.

\COMMENTS
For further details about the use of this function in the {\small\verb%sets%} library, refer
to the DESCRIPTION.

\SEEALSO
define_finite_set_syntax, load_library.

\ENDDOC
\DOC{define\_type}

\TYPE {\small\verb%define_type : (string -> string -> thm)%}\egroup

\SYNOPSIS
Automatically defines a user-specified concrete recursive data type.

\DESCRIBE
The ML function {\small\verb%define_type%} automatically defines any required concrete
recursive type in the logic.  The first argument is the name under which the
results of making the definition will be stored in the current theory segment.
The second argument is a user-supplied specification of the type to be defined.
This specification (explained below) simply states the names of the new type's
constructors and the logical types of their arguments.  The theorem returned by
{\small\verb%define_type%} is an automatically-proved abstract characterization of the
concrete data type described by this specification.

The type specification given as the second argument to {\small\verb%define_type%} must be a
string of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   `op = C1 ty ... ty | C2 ty ... ty | ... | Cn ty ... ty`
\end{verbatim}
}
\noindent where {\small\verb%op%} is the name of the type constant or type operator to be
defined, {\small\verb%C1%}, ..., {\small\verb%Cn%} are identifiers, and each {\small\verb%ty%} is either a (logical)
type expression valid in the current theory (in which case {\small\verb%ty%} must not
contain {\small\verb%op%}) or just the identifier `{\small\verb%op%}' itself.

A string of this form describes an n-ary type operator {\small\verb%op%}, where n is the
number of distinct type variables in the types {\small\verb%ty%} on the right hand side of
the equation.  If n is zero then {\small\verb%op%} is a type constant; otherwise {\small\verb%op%} is an
n-ary type operator.  The type described by the specification has {\small\verb%n%} distinct
constructors {\small\verb%C1%}, ..., {\small\verb%Cn%}.  Each constructor {\small\verb%Ci%} is a function that takes
arguments whose types are given by the associated type expressions {\small\verb%ty%} in the
specification. If one or more of the type expressions {\small\verb%ty%} is the type {\small\verb%op%}
itself, then the equation specifies a recursive data type.  In any
specification, at least one constructor must be non-recursive, i.e. all its
arguments must have types which already exist in the current theory.

Given a type specification of the form described above, {\small\verb%define_type%} makes an
appropriate type definition for the type operator {\small\verb%op%}.  It then makes
appropriate definitions for the constants {\small\verb%C1%}, ..., {\small\verb%Cn%}, and automatically
proves a theorem that states an abstract characterization of the newly-defined
type {\small\verb%op%}.  This theorem, which is stored in the current theory segment under
the name supplied as the first argument and also returned by {\small\verb%define_type%}, has
the form of a `primitive recursion theorem' for the concrete type {\small\verb%op%} (see the
examples given below). This property provides an abstract characterization of
the type {\small\verb%op%} which is both succinct and complete, in the sense that it
completely determines the structure of the values of {\small\verb%op%} up to isomorphism.

\FAILURE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   define_type `name` `op = C1 ty ... ty | ... | Cn ty ... ty`
\end{verbatim}
}
\noindent fails if HOL is not in draft mode; if {\small\verb%op%} is already the name of a
type constant or type operator in the current theory; if the supplied constant
names {\small\verb%C1%}, ..., {\small\verb%Cn%} are not distinct; if any one of {\small\verb%C1%}, ..., {\small\verb%Cn%} is
already a constant in the current theory or is not an allowed name for a
constant; if {\small\verb%ABS_op%} or {\small\verb%REP_op%} are already constants in the current theory;
if there is already an axiom, definition, constant specification or type
definition stored under either the name {\small\verb%op_TY_DEF%} or the name {\small\verb%op_ISO_DEF%} in
the current theory segment; if there is already a theorem stored under the name
{\small\verb%`name`%} in the current theory segment; or (finally) if the input type
specification does not conform in any other respect to the syntax described
above.

\EXAMPLE
The following call to {\small\verb%define_type%} defines {\small\verb%tri%} to be a simple enumerated
type with exactly three distinct values:
{\par\samepage\setseps\small
\begin{verbatim}
   #define_type `tri_DEF` `tri = ONE | TWO | THREE`;;
   |- !e0 e1 e2. ?! fn. (fn ONE = e0) /\ (fn TWO = e1) /\ (fn THREE = e2)
\end{verbatim}
}
\noindent The theorem returned is a degenerate `primitive recursion' theorem
for the concrete type {\small\verb%tri%}.  An example of a recursive type that can be
defined using {\small\verb%define_type%} is a type of binary trees:
{\par\samepage\setseps\small
\begin{verbatim}
   #define_type `btree_DEF` `btree = LEAF * | NODE btree btree`;;
   |- !f0 f1.
        ?! fn.
        (!x. fn(LEAF x) = f0 x) /\
        (!b1 b2. fn(NODE b1 b2) = f1(fn b1)(fn b2)b1 b2)
\end{verbatim}
}
\noindent The theorem returned by {\small\verb%define_type%} in this case asserts the unique
existence of functions defined by primitive recursion over labelled binary
trees.

Note that the type being defined may not occur as a proper subtype in
any of the types of the arguments of the constructors:
{\par\samepage\setseps\small
\begin{verbatim}
   #define_type `name` `ty = NUM num | FUN (ty -> ty)`;;
   evaluation failed     ill-formed type expression(s)
\end{verbatim}
}
\noindent In this example, there is an error because {\small\verb%ty%} occurs within the
type expression {\small\verb%(ty -> ty)%}.

\SEEALSO
INDUCT_THEN, new_recursive_definition, prove_cases_thm,
prove_constructors_distinct, prove_constructors_one_one, prove_induction_thm,
prove_rec_fn_exists.

\ENDDOC
\DOC{definition}

\TYPE {\small\verb%definition : (string -> string -> thm)%}\egroup

\SYNOPSIS
Reads a constant definition from a given theory segment of the current theory.

\DESCRIBE
A call {\small\verb%definition `thy` `def`%} returns constant definition {\small\verb%def%} from the
theory segment {\small\verb%thy%}. The theory segment {\small\verb%thy%} must be part of the current
theory. The name {\small\verb%def%} is the one given to the definition by the user when it
was originally added to the theory segment (by a call to {\small\verb%new_definition%}).
The name of the current theory segment can be abbreviated by {\small\verb%`-`%}.

\FAILURE
The call {\small\verb%definition `thy` `def`%} will fail if the theory segment {\small\verb%thy%} is not
part of the current theory. It will fail if there does not exist a constant
definition of name {\small\verb%def%} in theory segment {\small\verb%thy%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#definition `bool` `ONTO_DEF`;;
|- !f. ONTO f = (!y. ?x. y = f x)
\end{verbatim}
}
\SEEALSO
axiom, definitions, load_definition, load_definitions, new_definition, print_theory, theorem.

\ENDDOC
\DOC{definition\_lfn}

\TYPE {\small\verb%definition_lfn : (string list -> thm)%}\egroup

\SYNOPSIS
Loads a given definition from a given theory.

\DESCRIBE
If {\small\verb%thy%} is an ancestor theory, and {\small\verb%def%} one of its definitions, then the
call
{\par\samepage\setseps\small
\begin{verbatim}
   definition_lfn [`thy`;`def`]
\end{verbatim}
}
\noindent will return that definition.

\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%def%} is not one of its
definitions.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#definition_lfn [`bool`; `EXISTS_DEF`];;
|- $? = (\P. P($@ P))
\end{verbatim}
}
\COMMENTS
This call has the same effect as {\small\verb%definition `thy` `def`%}.

\SEEALSO
definition, definitions, definition_msg_lfn, load_definition, load_definitions.

\ENDDOC
\DOC{definition\_msg\_lfn}

\TYPE {\small\verb%definition_msg_lfn : (string list -> thm)%}\egroup

\SYNOPSIS
Loads a given definition from a given theory, with an autoload message.

\DESCRIBE
If {\small\verb%thy%} is an ancestor theory, and {\small\verb%def%} one of its definitions, then the
call
{\par\samepage\setseps\small
\begin{verbatim}
   definition_msg_lfn [`thy`;`def`]
\end{verbatim}
}
\noindent will print out a message of the form
{\par\samepage\setseps\small
\begin{verbatim}
   Definition def autoloaded from theory `thy`
\end{verbatim}
}
\noindent and cancel any autoloading action associated with the name {\small\verb%def%},
and return that definition.

\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%def%} is not one of its
definitions.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#definition_msg_lfn [`bool`;`NOT_DEF`];;
Definition NOT_DEF autoloaded from theory `bool`.
|- $~ = (\t. t ==> F)
\end{verbatim}
}
\SEEALSO
autoload, autoload_theory, definition, definitions, definition_lfn,
load_definition, load_definitions, undo_autoload.

\ENDDOC
\DOC{definitions}

\TYPE {\small\verb%definitions : (string -> (string # thm) list)%}\egroup

\SYNOPSIS
Returns the constant definitions, type definitions and constant specifications
of a given theory segment of the current theory.

\DESCRIBE
A call of {\small\verb%definitions `thy`%} returns the definitions of the theory segment
{\small\verb%thy%} together with their names. Constant definitions, type definitions and
constant specifications are all retrieved by the function {\small\verb%definitions%}. The
theory segment {\small\verb%thy%} must be part of the current theory. The names are those
given to the definitions by the user when they were originally added to the
theory segment (by a call, for example, to {\small\verb%new_definition%}). The name of the
current theory segment can be abbreviated by {\small\verb%`-`%}.

\FAILURE
The call {\small\verb%definitions `thy`%} will fail if the theory segment {\small\verb%thy%} is not
part of the current theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#definitions `combin`;;
[(`I_DEF`, |- I = S K K);
 (`S_DEF`, |- S = (\f g x. f x(g x)));
 (`K_DEF`, |- K = (\x y. x));
 (`o_DEF`, |- !f g. f o g = (\x. f(g x)))]
: (string # thm) list
\end{verbatim}
}
\SEEALSO
axioms, definition, load_definition, load_definitions, new_definition, print_theory, theorems.

\ENDDOC
\DOC{delete\_cache}

\TYPE {\small\verb%delete_cache : (string -> void)%}\egroup

\SYNOPSIS
Deletes a theory from the theory cache.

\DESCRIBE
A call {\small\verb%delete_cache thy%} deletes the named theory from the theory cache.
For more details of the cacheing mechanism, see the DESCRIPTION.

\FAILURE
Never fails, even if the name is not the name of a loaded theory.

\SEEALSO
cached_theories.

\ENDDOC
\DOC{delete\_thm}

\TYPE {\small\verb%delete_thm : (string -> string -> thm)%}\egroup

\SYNOPSIS
Deletes a theorem from a theory.

\DESCRIBE
If {\small\verb%thy%} is an ancestor theory, and {\small\verb%th%} the name of a theorem of that theory,
then the call
{\par\samepage\setseps\small
\begin{verbatim}
   delete_thm `thy` `th`
\end{verbatim}
}
\noindent will delete the theorem {\small\verb%th%} from the theory {\small\verb%thy%}. As usual, the
special string {\small\verb%`-`%} is allowed as a theory name, standing for the current
theory. The call will return the theorem deleted.

\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%th%} is not one of its
theorems, or for various system-dependent reasons connected with writing to the
theory file.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_theory `geek`;;
() : void

#theorems `-`;;
[] : (string # thm) list

#save_thm(`truth`,TRUTH);;
|- T

#theorems `-`;;
[(`truth`, |- T)] : (string # thm) list

#delete_thm `-` `truth`;;
|- T

#theorems `-`;;
[] : (string # thm) list
\end{verbatim}
}
\COMMENTS
The particular theorems which are stored in a theory have no logical
significance, so this operation is quite safe. By contrast, being able to
delete a definition from a theory would compromise the consistency of the
logic, so it is not allowed.

\SEEALSO
prove_thm, save_thm, theorem, theorems.

\ENDDOC
\DOC{DEPTH\_CONV}

\TYPE {\small\verb%DEPTH_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion repeatedly to all the sub-terms of a term, in bottom-up
order.

\DESCRIBE
{\small\verb%DEPTH_CONV c tm%} repeatedly applies the conversion {\small\verb%c%} to all the subterms of
the term {\small\verb%tm%}, including the term {\small\verb%tm%} itself.  The supplied conversion is
applied repeatedly (zero or more times, as is done by {\small\verb%REPEATC%}) to each
subterm until it fails. The conversion is applied to subterms in bottom-up
order.

\FAILURE
{\small\verb%DEPTH_CONV c tm%} never fails but can diverge if the conversion {\small\verb%c%} can be
applied repeatedly to some subterm of {\small\verb%tm%} without failing.

\EXAMPLE
The following example shows how {\small\verb%DEPTH_CONV%} applies a conversion to all
subterms to which it applies:
{\par\samepage\setseps\small
\begin{verbatim}
   #DEPTH_CONV BETA_CONV "(\x. (\y. y + x) 1) 2";;
   |- (\x. (\y. y + x)1)2 = 1 + 2
\end{verbatim}
}
\noindent Here, there are two beta-redexes in the input term, one of which
occurs within the other. {\small\verb%DEPTH_CONV BETA_CONV%} applies beta-conversion to
innermost beta-redex {\small\verb%(\y. y + x) 1%} first.  The outermost beta-redex is then
{\small\verb%(\x. 1 + x) 2%}, and beta-conversion of this redex gives {\small\verb%1 + 2%}.

Because {\small\verb%DEPTH_CONV%} applies a conversion bottom-up, the final result may still
contain subterms to which the supplied conversion applies.  For example, in:
{\par\samepage\setseps\small
\begin{verbatim}
   #DEPTH_CONV BETA_CONV "(\f x. (f x) + 1) (\y.y) 2";;
   |- (\f x. (f x) + 1)(\y. y)2 = ((\y. y)2) + 1
\end{verbatim}
}
\noindent the right-hand side of the result still contains a beta-redex,
because the redex {\small\verb%"(\y.y)2"%} is introduced by virtue an application of
{\small\verb%BETA_CONV%} higher-up in the structure of the input term.  By contrast, in the
example:
{\par\samepage\setseps\small
\begin{verbatim}
   #DEPTH_CONV BETA_CONV "(\f x. (f x)) (\y.y) 2";;
   |- (\f x. f x)(\y. y)2 = 2
\end{verbatim}
}
\noindent all beta-redexes are eliminated, because {\small\verb%DEPTH_CONV%} repeats the
supplied conversion (in this case, {\small\verb%BETA_CONV%}) at each subterm (in this case,
at the top-level term).

\USES
If the conversion {\small\verb%c%} implements the evaluation of a function in logic, then
{\small\verb%DEPTH_CONV c%} will do bottom-up evaluation of nested applications of it.
For example, the conversion {\small\verb%ADD_CONV%} implements addition of natural number
constants within the logic. Thus, the effect of:
{\par\samepage\setseps\small
\begin{verbatim}
   #DEPTH_CONV ADD_CONV "(1 + 2) + (3 + 4 + 5)";;
   |- (1 + 2) + (3 + (4 + 5)) = 15
\end{verbatim}
}
\noindent is to compute the sum represented by the input term.

\COMMENTS
The implementation of this function uses failure to avoid rebuilding unchanged
subterms. That is to say, during execution the failure string {\small\verb%`QCONV`%} may be
generated and later trapped. The behaviour of the function is dependent on this
use of failure. So, if the conversion given as an argument happens to generate
a failure with string {\small\verb%`QCONV`%}, the operation of {\small\verb%DEPTH_CONV%} will be
unpredictable.

\SEEALSO
ONCE_DEPTH_CONV, REDEPTH_CONV, TOP_DEPTH_CONV.

\ENDDOC
\DOC{dest\_abs}

\TYPE {\small\verb%dest_abs : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart an abstraction into abstracted variable and body.

\DESCRIBE
{\small\verb%dest_abs%} is a term destructor for abstractions:
{\small\verb%dest_abs "\var. t"%} returns {\small\verb%("var","t")%}.

\FAILURE
Fails with {\small\verb%dest_abs%} if term is not an abstraction.

\SEEALSO
mk_abs, is_abs, dest_var, dest_const, dest_comb, strip_abs.

\ENDDOC
\DOC{dest\_comb}

\TYPE {\small\verb%dest_comb : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a combination (function application) into rator and rand.

\DESCRIBE
{\small\verb%dest_comb%} is a term destructor for combinations:
{\par\samepage\setseps\small
\begin{verbatim}
   dest_comb "t1 t2"
\end{verbatim}
}
\noindent returns {\small\verb%("t1","t2")%}.

\FAILURE
Fails with {\small\verb%dest_comb%} if term is not a combination.

\SEEALSO
mk_comb, is_comb, dest_var, dest_const, dest_abs, strip_comb.

\ENDDOC
\DOC{dest\_cond}

\TYPE {\small\verb%dest_cond : (term -> (term # term # term))%}\egroup

\SYNOPSIS
Breaks apart a conditional into the three terms involved.

\DESCRIBE
{\small\verb%dest_cond%} is a term destructor for conditionals:
{\par\samepage\setseps\small
\begin{verbatim}
   dest_cond "t => t1 | t2"
\end{verbatim}
}
\noindent returns {\small\verb%("t","t1","t2")%}.

\FAILURE
Fails with {\small\verb%dest_cond%} if term is not a conditional.

\SEEALSO
mk_cond, is_cond.

\ENDDOC
\DOC{dest\_conj}

\TYPE {\small\verb%dest_conj : (term -> (term # term))%}\egroup

\SYNOPSIS
Term destructor for conjunctions.

\DESCRIBE
{\small\verb%dest_conj("t1 /\ t2")%} returns {\small\verb%("t1","t2")%}.

\FAILURE
Fails with {\small\verb%dest_conj%} if term is not a conjunction.

\SEEALSO
mk_conj, is_conj.

\ENDDOC
\DOC{dest\_cons}

\TYPE {\small\verb%dest_cons : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a `CONS pair' into head and tail.

\DESCRIBE
{\small\verb%dest_cons%} is a term destructor for `CONS pairs'. When applied to a term
representing a nonempty list {\small\verb%"[t;t1;...;tn]"%} (which is equivalent to {\small\verb%"CONS t
[t1;...;tn]"%}), it returns the pair of terms {\small\verb%("t","[t1;...;tn]")%}.

\FAILURE
Fails with {\small\verb%dest_cons%} if the term is not a non-empty list.

\SEEALSO
mk_cons, is_cons, mk_list, dest_list, is_list.

\ENDDOC
\DOC{dest\_const}

\TYPE {\small\verb%dest_const : (term -> (string # type))%}\egroup

\SYNOPSIS
Breaks apart a constant into name and type.

\DESCRIBE
{\small\verb%dest_const%} is a term destructor for constants:
{\par\samepage\setseps\small
\begin{verbatim}
   dest_const "const:ty"
\end{verbatim}
}
\noindent returns {\small\verb%(`const`,":ty")%}.

\FAILURE
Fails with {\small\verb%dest_const%} if term is not a constant.

\SEEALSO
mk_const, is_const, dest_var, dest_comb, dest_abs.

\ENDDOC
\DOC{dest\_definition}

\TYPE {\small\verb%dest_definition : (term -> term)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{dest\_disj}

\TYPE {\small\verb%dest_disj : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a disjunction into the two disjuncts.

\DESCRIBE
{\small\verb%dest_disj%} is a term destructor for disjunctions:
{\par\samepage\setseps\small
\begin{verbatim}
   dest_disj "t1 \/ t2"
\end{verbatim}
}
\noindent returns {\small\verb%("t1","t2")%}.

\FAILURE
Fails with {\small\verb%dest_disj%} if term is not a disjunction.

\SEEALSO
mk_disj, is_disj.

\ENDDOC
\DOC{dest\_eq}

\TYPE {\small\verb%dest_eq : (term -> (term # term))%}\egroup

\SYNOPSIS
Term destructor for equality.

\DESCRIBE
{\small\verb%dest_eq("t1 = t2")%} returns {\small\verb%("t1","t2")%}.

\FAILURE
Fails with {\small\verb%dest_eq%} if term is not an equality.

\SEEALSO
mk_eq, is_eq.

\ENDDOC
\DOC{dest\_exists}

\TYPE {\small\verb%dest_exists : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart an existentially quantified term into quantified variable and body.

\DESCRIBE
{\small\verb%dest_exists%} is a term destructor for existential quantification:
{\small\verb%dest_exists "?var. t"%} returns {\small\verb%("var","t")%}.

\FAILURE
Fails with {\small\verb%dest_exists%} if term is not an existential quantification.

\SEEALSO
mk_exists, is_exists, strip_exists.

\ENDDOC
\DOC{dest\_forall}

\TYPE {\small\verb%dest_forall : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a universally quantified term into quantified variable and body.

\DESCRIBE
{\small\verb%dest_forall%} is a term destructor for universal quantification:
{\small\verb%dest_forall "!var. t"%} returns {\small\verb%("var","t")%}.

\FAILURE
Fails with {\small\verb%dest_forall%} if term is not a universal quantification.

\SEEALSO
mk_forall, is_forall, strip_forall.

\ENDDOC
\DOC{dest\_form}

\TYPE {\small\verb%dest_form : (form -> term)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{dest\_imp}

\TYPE {\small\verb%dest_imp : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart an implication into antecedent and consequent.

\DESCRIBE
{\small\verb%dest_imp%} is a term destructor for implications. Thus
{\par\samepage\setseps\small
\begin{verbatim}
   dest_imp "t1 ==> t2"
\end{verbatim}
}
\noindent returns
{\par\samepage\setseps\small
\begin{verbatim}
   ("t1","t2")
\end{verbatim}
}
\FAILURE
Fails with {\small\verb%dest_imp%} if term is not an implication.

\COMMENTS
Previous version of {\small\verb%dest_imp%} treats negations as an implication
with {\small\verb%F%} as the conclusion. This is renamed to {\small\verb%dest_neg_imp%}.

\SEEALSO
mk_imp, is_imp, strip_imp, dest_neg_imp.

\ENDDOC
\DOC{dest\_let}

\TYPE {\small\verb%dest_let : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a let-expression.

\DESCRIBE
{\small\verb%dest_let%} is a term destructor for general let-expressions:
{\small\verb%dest_let "LET f x"%} returns {\small\verb%("f","x")%}.

\FAILURE
Fails with {\small\verb%dest_let%} if term is not a {\small\verb%let%}-expression or of the more general
{\small\verb%"LET f x"%} form.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#dest_let "LET ($= 1) 2";;
("$= 1", "2") : (term # term)

#dest_let "let x = 2 in (x = 1)";;
("\x. x = 1", "2") : (term # term)
\end{verbatim}
}
\SEEALSO
mk_let, is_let.

\ENDDOC
\DOC{dest\_list}

\TYPE {\small\verb%dest_list : (term -> (term list # type))%}\egroup

\SYNOPSIS
Iteratively breaks apart a list term.

\DESCRIBE
{\small\verb%dest_list%} is a term destructor for lists:
{\small\verb%dest_list("[t1;...;tn]:(ty)list")%} returns {\small\verb%(["t1";...;"tn"],":ty")%}.

\FAILURE
Fails with {\small\verb%dest_list%} if the term is not a list.

\SEEALSO
mk_list, is_list, mk_cons, dest_cons, is_cons.

\ENDDOC
\DOC{dest\_neg}

\TYPE {\small\verb%dest_neg : (term -> term)%}\egroup

\SYNOPSIS
Breaks apart a negation, returning its body.

\DESCRIBE
{\small\verb%dest_neg%} is a term destructor for negations:
{\small\verb%dest_neg "~t"%} returns {\small\verb%"t"%}.

\FAILURE
Fails with {\small\verb%dest_neg%} if term is not a negation.

\SEEALSO
mk_neg, is_neg.

\ENDDOC
\DOC{dest\_neg\_imp}

\TYPE {\small\verb%dest_neg_imp : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart an implication (or negation) into antecedent and consequent.

\DESCRIBE
{\small\verb%dest_neg_imp%} is a term destructor for implications, which treats negations as
implications with consequent {\small\verb%F%}. Thus
{\par\samepage\setseps\small
\begin{verbatim}
   dest_neg_imp "t1 ==> t2"
\end{verbatim}
}
\noindent returns
{\par\samepage\setseps\small
\begin{verbatim}
   ("t1","t2")
\end{verbatim}
}
\noindent and also
{\par\samepage\setseps\small
\begin{verbatim}
   dest_neg_imp "~t"
\end{verbatim}
}
\noindent returns
{\par\samepage\setseps\small
\begin{verbatim}
   ("t","F")
\end{verbatim}
}
\FAILURE
Fails with {\small\verb%dest_neg_imp%} if term is neither an implication nor a negation.

\COMMENTS
Destructs negations for compatibility with PPLAMBDA code.
This function used to be called {\small\verb%dest_imp%}

\SEEALSO
is_neg_imp, dest_imp, strip_imp.

\ENDDOC
\DOC{dest\_pabs}

\TYPE {\small\verb%dest_pabs : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a paired abstraction into abstracted varstruct and body.

\DESCRIBE
{\small\verb%dest_pabs%} is a term destructor for paired abstractions:
{\small\verb%dest_pabs "\(v1..(..)..vn). t"%} returns {\small\verb%("(v1..(..)..vn)","t")%}.

\FAILURE
Fails unless the term is a paired abstraction.

\SEEALSO
mk_pabs, is_pabs, dest_abs, dest_var, dest_const, dest_comb.

\ENDDOC
\DOC{dest\_pair}

\TYPE {\small\verb%dest_pair : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a pair into two separate terms.

\DESCRIBE
{\small\verb%dest_pair%} is a term destructor for pairs:
{\small\verb%dest_pair "(t1,t2)"%} returns {\small\verb%("t1","t2")%}.

\FAILURE
Fails with {\small\verb%dest_pair%} if term is not a pair.

\SEEALSO
mk_pair, is_pair, strip_pair.

\ENDDOC
\DOC{dest\_pred}

\TYPE {\small\verb%dest_pred : (term -> (string # term))%}\egroup

\SYNOPSIS
Breaks apart a combination whose operator is a constant.

\DESCRIBE
Given a term {\small\verb%"op t"%}, {\small\verb%dest_pred%} returns the pair {\small\verb%(`op`,"t")%}, provided
{\small\verb%"op"%} is a constant.

\FAILURE
Fails if the given term is not a combination whose operator is a constant.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
dest_pred "$/\ T";;
(`/\`, "T") : (string # term)
\end{verbatim}
}
\SEEALSO
dest_comb, dest_const, is_pred

\ENDDOC
\DOC{dest\_select}

\TYPE {\small\verb%dest_select : (term -> (term # term))%}\egroup

\SYNOPSIS
Breaks apart a choice term into selected variable and body.

\DESCRIBE
{\small\verb%dest_select%} is a term destructor for choice terms:
{\par\samepage\setseps\small
\begin{verbatim}
   dest_select "@var. t"
\end{verbatim}
}
\noindent returns {\small\verb%("var","t")%}.

\FAILURE
Fails with {\small\verb%dest_select%} if term is not an epsilon-term.

\SEEALSO
mk_select, is_select.

\ENDDOC
\DOC{dest\_thm}

\TYPE {\small\verb%dest_thm : (thm -> goal)%}\egroup

\SYNOPSIS
Breaks a theorem into assumption list and conclusion.

\DESCRIBE
{\small\verb%dest_thm (t1,...,tn |- t)%} returns {\small\verb%(["t1";...;"tn"],"t")%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#dest_thm (ASSUME "p=T");;
(["p = T"], "p = T") : goal
\end{verbatim}
}
\SEEALSO
concl, hyp.

\ENDDOC
\DOC{dest\_type}

\TYPE {\small\verb%dest_type : (type -> (string # type list))%}\egroup

\SYNOPSIS
Breaks apart a type (other than a variable type).

\DESCRIBE
{\small\verb%dest_type(":(ty1,...,tyn)op")%} returns {\small\verb%(`op`,[":ty1";...;":tyn"])%}.

\FAILURE
Fails with {\small\verb%dest_type%} if the type is a type variable.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#dest_type ":bool";;
(`bool`, []) : (string # type list)

#dest_type ":(bool)list";;
(`list`, [":bool"]) : (string # type list)

#dest_type ":num -> bool";;
(`fun`, [":num"; ":bool"]) : (string # type list)
\end{verbatim}
}
\SEEALSO
mk_type, dest_vartype.

\ENDDOC
\DOC{dest\_var}

\TYPE {\small\verb%dest_var : (term -> (string # type))%}\egroup

\SYNOPSIS
Breaks apart a variable into name and type.

\DESCRIBE
{\small\verb%dest_var "var:ty"%} returns {\small\verb%(`var`,":ty")%}.

\FAILURE
Fails with {\small\verb%dest_var%} if term is not a variable.

\SEEALSO
mk_var, is_var, dest_const, dest_comb, dest_abs.

\ENDDOC
\DOC{dest\_vartype}

\TYPE {\small\verb%dest_vartype : (type -> string)%}\egroup

\SYNOPSIS
Breaks a type variable down to its name.

\DESCRIBE
{\small\verb%dest_vartype ":*..."%} returns {\small\verb%`*...`%}.

\FAILURE
Fails with {\small\verb%dest_vartype%} if the type is not a type variable.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#dest_vartype ":*test";;
`*test` : string

#dest_vartype ":bool";;
evaluation failed     dest_vartype

#dest_vartype ":* -> bool";;
evaluation failed     dest_vartype
\end{verbatim}
}
\SEEALSO
mk_vartype, is_vartype, dest_type.

\ENDDOC
\DOC{DISCARD\_TAC}

\TYPE {\small\verb%DISCARD_TAC : thm_tactic%}\egroup

\SYNOPSIS
Discards a theorem already present in a goal's assumptions.

\DESCRIBE
When applied to a theorem {\small\verb%A' |- s%} and a goal, {\small\verb%DISCARD_TAC%}
checks that {\small\verb%s%} is simply {\small\verb%T%} (true), or already exists (up
to alpha-conversion) in the assumption list of the goal. In
either case, the tactic has no effect. Otherwise, it fails.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   ========  DISCARD_TAC (A' |- s)
    A ?- t
\end{verbatim}
}
\FAILURE
Fails if the above conditions are not met, i.e. the theorem's conclusion
is not {\small\verb%T%} or already in the assumption list (up to alpha-conversion).

\SEEALSO
POP_ASSUM, POP_ASSUM_LIST.

\ENDDOC
\DOC{DISCH\_ALL}

\TYPE {\small\verb%DISCH_ALL : (thm -> thm)%}\egroup

\SYNOPSIS
Discharges all hypotheses of a theorem.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
         A1, ..., An |- t
   ----------------------------  DISCH_ALL
    |- A1 ==> ... ==> An ==> t
\end{verbatim}
}
\FAILURE
{\small\verb%DISCH_ALL%} will not fail if there are no hypotheses to discharge, it will
simply return the theorem unchanged.

\COMMENTS
Users should not rely on the hypotheses being discharged in any particular
order.  Two or more alpha-convertible hypotheses will be discharged by a
single implication; users should not rely on which hypothesis appears in the
implication.

\SEEALSO
DISCH, DISCH_TAC, DISCH_THEN, NEG_DISCH, FILTER_DISCH_TAC, FILTER_DISCH_THEN,
STRIP_TAC, UNDISCH, UNDISCH_ALL, UNDISCH_TAC.

\ENDDOC
\DOC{disch}

\TYPE {\small\verb%disch : ((term # term list) -> term list)%}\egroup

\SYNOPSIS
Removes those elements of a list of terms that are alpha equivalent to a
given term.

\DESCRIBE
Given a pair {\small\verb%("t",tl)%}, {\small\verb%disch%} removes those elements of {\small\verb%tl%} that are
alpha equivalent to {\small\verb%"t"%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
disch ("\x:bool.T",["A = T";"B = 3";"\y:bool.T"]);;
["A = T";"B = 3"] : term list
\end{verbatim}
}
\SEEALSO
filter.

\ENDDOC
\DOC{DISCH}

\TYPE {\small\verb%DISCH : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Discharges an assumption.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t
--------------------  DISCH "u"
 A - {u} |- u ==> t
\end{verbatim}
}
\FAILURE
{\small\verb%DISCH%} will fail if {\small\verb%"u"%} is not boolean.

\COMMENTS
The term {\small\verb%"u"%} need not be a hypothesis.  Discharging {\small\verb%"u"%} will remove all
identical and alpha-equivalent hypotheses.

\SEEALSO
DISCH_ALL, DISCH_TAC, DISCH_THEN, FILTER_DISCH_TAC, FILTER_DISCH_THEN,
NEG_DISCH, STRIP_TAC, UNDISCH, UNDISCH_ALL, UNDISCH_TAC.

\ENDDOC
\DOC{DISCH\_TAC}

\TYPE {\small\verb%DISCH_TAC : tactic%}\egroup

\SYNOPSIS
Moves the antecedent of an implicative goal into the assumptions.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- u ==> v
   ==============  DISCH_TAC
    A u {u} ?- v
\end{verbatim}
}
\noindent Note that {\small\verb%DISCH_TAC%} treats {\small\verb%"~u"%} as {\small\verb%"u ==> F"%}, so will also work
when applied to a goal with a negated conclusion.

\FAILURE
{\small\verb%DISCH_TAC%} will fail for goals which are not implications or negations.

\USES
Solving goals of the form {\small\verb%"u ==> v"%} by rewriting {\small\verb%"v"%} with {\small\verb%"u"%}, although
the use of {\small\verb%DISCH_THEN%} is usually more elegant in such cases.

\COMMENTS
If the antecedent already appears in the assumptions, it will be duplicated.

\SEEALSO
DISCH, DISCH_ALL, DISCH_THEN, FILTER_DISCH_TAC, FILTER_DISCH_THEN, NEG_DISCH,
STRIP_TAC, UNDISCH, UNDISCH_ALL, UNDISCH_TAC.

\ENDDOC
\DOC{DISCH\_THEN}

\TYPE {\small\verb%DISCH_THEN : (thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Undischarges an antecedent of an implication and passes it to a theorem-tactic.

\DESCRIBE
{\small\verb%DISCH_THEN%} removes the antecedent and then creates a theorem by {\small\verb%ASSUME%}ing
it. This new theorem is passed to the theorem-tactic given as {\small\verb%DISCH_THEN%}'s
argument. The consequent tactic is then applied. Thus:
{\par\samepage\setseps\small
\begin{verbatim}
   DISCH_THEN f (asl,"t1 ==> t2") = f(ASSUME "t1")(asl,"t2")
\end{verbatim}
}
\noindent For example, if
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   ========  f (ASSUME "u")
    B ?- v
\end{verbatim}
}
\noindent then
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- u ==> t
   ==============  DISCH_THEN f
       B ?- v
\end{verbatim}
}
\noindent Note that {\small\verb%DISCH_THEN%} treats {\small\verb%"~u"%} as {\small\verb%"u ==> F"%}.

\FAILURE
{\small\verb%DISCH_THEN%} will fail for goals which are not implications or negations.

\EXAMPLE
The following shows how {\small\verb%DISCH_THEN%} can be used to preprocess an antecedent
before adding it to the assumptions.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- (x = y) ==> t
   ====================  DISCH_THEN (ASSUME_TAC o SYM)
     A u {y = x} ?- t
\end{verbatim}
}
\noindent In many cases, it is possible to use an antecedent and then throw it
away:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- (x = y) ==> t x
   ======================  DISCH_THEN (\th. PURE_REWRITE_TAC [th])
          A ?- t y
\end{verbatim}
}
\SEEALSO
DISCH, DISCH_ALL, DISCH_TAC, NEG_DISCH, FILTER_DISCH_TAC, FILTER_DISCH_THEN,
STRIP_TAC, UNDISCH, UNDISCH_ALL, UNDISCH_TAC.

\ENDDOC
\DOC{DISJ1}

\TYPE {\small\verb%DISJ1 : (thm -> term -> thm)%}\egroup

\SYNOPSIS
Introduces a right disjunct into the conclusion of a theorem.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t1
   ---------------  DISJ1 (A |- t1) "t2"
    A |- t1 \/ t2
\end{verbatim}
}
\FAILURE
Fails unless the term argument is boolean.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#DISJ1 TRUTH "F";;
|- T \/ F
\end{verbatim}
}
\COMMENTS
The system shows the type of {\small\verb%DISJ1%} as {\small\verb%(thm -> conv)%}.

\SEEALSO
DISJ1_TAC, DISJ2, DISJ2_TAC, DISJ_CASES.

\ENDDOC
\DOC{DISJ1\_TAC}

\TYPE {\small\verb%DISJ1_TAC : tactic%}\egroup

\SYNOPSIS
Selects the left disjunct of a disjunctive goal.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
   A ?- t1 \/ t2
  ===============  DISJ1_TAC
     A ?- t1
\end{verbatim}
}
\FAILURE
Fails if the goal is not a disjunction.

\SEEALSO
DISJ1, DISJ2, DISJ2_TAC.

\ENDDOC
\DOC{DISJ2}

\TYPE {\small\verb%DISJ2 : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Introduces a left disjunct into the conclusion of a theorem.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
      A |- t2
   ---------------  DISJ2 "t1"
    A |- t1 \/ t2
\end{verbatim}
}
\FAILURE
Fails if the term argument is not boolean.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#DISJ2 "F" TRUTH;;
|- F \/ T
\end{verbatim}
}
\SEEALSO
DISJ1, DISJ1_TAC, DISJ2_TAC, DISJ_CASES.

\ENDDOC
\DOC{DISJ2\_TAC}

\TYPE {\small\verb%DISJ2_TAC : tactic%}\egroup

\SYNOPSIS
Selects the right disjunct of a disjunctive goal.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t1 \/ t2
   ===============  DISJ2_TAC
       A ?- t2
\end{verbatim}
}
\FAILURE
Fails if the goal is not a disjunction.

\SEEALSO
DISJ1, DISJ1_TAC, DISJ2.

\ENDDOC
\DOC{DISJ\_CASES}

\TYPE {\small\verb%DISJ_CASES : (thm -> thm -> thm -> thm)%}\egroup

\SYNOPSIS
Eliminates disjunction by cases.

\DESCRIBE
The rule {\small\verb%DISJ_CASES%} takes a disjunctive theorem, and two `case'
theorems, each with one of the disjuncts as a hypothesis while sharing
alpha-equivalent conclusions.  A new theorem is returned with the same
conclusion as the `case' theorems, and the union of all assumptions
excepting the disjuncts.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 \/ t2     A1 u {t1} |- t      A2 u {t2} |- t
   ------------------------------------------------------  DISJ_CASES
                    A u A1 u A2 |- t
\end{verbatim}
}
\FAILURE
Fails if the first argument is not a disjunctive theorem, or if the
conclusions of the other two theorems are not alpha-convertible.

\EXAMPLE
Specializing the built-in theorem {\small\verb%num_CASES%} gives the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- (m = 0) \/ (?n. m = SUC n)
\end{verbatim}
}
\noindent Using two additional theorems, each having one disjunct as a
hypothesis:
{\par\samepage\setseps\small
\begin{verbatim}
   th1 = (m = 0 |- (PRE m = m) = (m = 0))
   th2 = (?n. m = SUC n" |- (PRE m = m) = (m = 0))
\end{verbatim}
}
\noindent a new theorem can be derived:
{\par\samepage\setseps\small
\begin{verbatim}
   #DISJ_CASES th th1 th2;;
   |- (PRE m = m) = (m = 0)
\end{verbatim}
}
\COMMENTS
Neither of the `case' theorems is required to have either disjunct as a
hypothesis, but otherwise {\small\verb%DISJ_CASES%} is pointless.

\SEEALSO
DISJ_CASES_TAC, DISJ_CASES_THEN, DISJ_CASES_THEN2, DISJ_CASES_UNION,
DISJ1, DISJ2.

\ENDDOC
\DOC{DISJ\_CASES\_TAC}

\TYPE {\small\verb%DISJ_CASES_TAC : thm_tactic%}\egroup

\SYNOPSIS
Produces a case split based on a disjunctive theorem.

\DESCRIBE
Given a theorem {\small\verb%th%} of the form {\small\verb%A |- u \/ v%}, {\small\verb%DISJ_CASES_TAC th%}
applied to a goal
produces two subgoals, one with {\small\verb%u%} as an assumption and one with {\small\verb%v%}:
{\par\samepage\setseps\small
\begin{verbatim}
              A ?- t
   ============================  DISJ_CASES_TAC (A |- u \/ v)
    A u {u} ?- t   A u {v}?- t
\end{verbatim}
}
\FAILURE
Fails if the given theorem does not have a disjunctive conclusion.

\EXAMPLE
Given the simple fact about arithmetic {\small\verb%th%}, {\small\verb%|- (m = 0) \/ (?n. m = SUC n)%},
the tactic {\small\verb%DISJ_CASES_TAC th%} can be used to produce a case split:
{\par\samepage\setseps\small
\begin{verbatim}
   #DISJ_CASES_TAC th ([],"(P:num -> bool) m");;
   ([(["m = 0"], "P m");
     (["?n. m = SUC n"], "P m")], -) : subgoals
\end{verbatim}
}
\USES
Performing a case analysis according to a disjunctive theorem.

\SEEALSO
ASSUME_TAC, ASM_CASES_TAC, COND_CASES_TAC, DISJ_CASES_THEN, STRUCT_CASES_TAC.

\ENDDOC
\DOC{DISJ\_CASES\_THEN2}

\TYPE {\small\verb%DISJ_CASES_THEN2 : (thm_tactic -> thm_tactical)%}\egroup

\SYNOPSIS
Applies separate theorem-tactics to the two disjuncts of a theorem.

\DESCRIBE
If the theorem-tactics {\small\verb%f1%} and {\small\verb%f2%}, applied to the {\small\verb%ASSUME%}d left and right
disjunct of a theorem {\small\verb%|- u \/ v%} respectively, produce results as follows when
applied to a goal {\small\verb%(A ?- t)%}:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t                                 A ?- t
   =========  f1 (u |- u)      and        =========  f2 (v |- v)
    A ?- t1                                A ?- t2
\end{verbatim}
}
\noindent then applying {\small\verb%DISJ_CASES_THEN2 f1 f2 (|- u \/ v)%} to the
goal {\small\verb%(A ?- t)%} produces two subgoals.
{\par\samepage\setseps\small
\begin{verbatim}
           A ?- t
   ======================  DISJ_CASES_THEN2 f1 f2 (|- u \/ v)
    A ?- t1      A ?- t2
\end{verbatim}
}
\FAILURE
Fails if the theorem is not a disjunction.  An invalid tactic is
produced if the theorem has any hypothesis which is not
alpha-convertible to an assumption of the goal.

\EXAMPLE
Given the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- (m = 0) \/ (?n. m = SUC n)
\end{verbatim}
}
\noindent and a goal of the form {\small\verb%?- (PRE m = m) = (m = 0)%},
applying the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   DISJ_CASES_THEN2 SUBST1_TAC ASSUME_TAC th
\end{verbatim}
}
\noindent to the goal will produce two subgoals
{\par\samepage\setseps\small
\begin{verbatim}
   ?n. m = SUC n ?- (PRE m = m) = (m = 0)

   ?- (PRE 0 = 0) = (0 = 0)
\end{verbatim}
}
\noindent The first subgoal has had the disjunct {\small\verb%m = 0%} used
for a substitution, and the second has added the disjunct to the
assumption list.  Alternatively, applying the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   DISJ_CASES_THEN2 SUBST1_TAC (CHOOSE_THEN SUBST1_TAC) th
\end{verbatim}
}
\noindent to the goal produces the subgoals:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (PRE(SUC n) = SUC n) = (SUC n = 0)

   ?- (PRE 0 = 0) = (0 = 0)
\end{verbatim}
}
\USES
Building cases tacticals. For example, {\small\verb%DISJ_CASES_THEN%} could be defined by:
{\par\samepage\setseps\small
\begin{verbatim}
  let DISJ_CASES_THEN f = DISJ_CASES_THEN2 f f
\end{verbatim}
}
\SEEALSO
STRIP_THM_THEN, CHOOSE_THEN, CONJUNCTS_THEN, CONJUNCTS_THEN2,
DISJ_CASES_THEN, DISJ_CASES_THENL.

\ENDDOC
\DOC{DISJ\_CASES\_THEN}

\TYPE {\small\verb%DISJ_CASES_THEN : thm_tactical%}\egroup

\SYNOPSIS
Applies a theorem-tactic to each disjunct of a disjunctive theorem.

\DESCRIBE
If the theorem-tactic {\small\verb%f:thm->tactic%} applied to either
{\small\verb%ASSUME%}d disjunct produces results as follows when applied to a goal
{\small\verb%(A ?- t)%}:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t                                A ?- t
   =========  f (u |- u)      and        =========  f (v |- v)
    A ?- t1                               A ?- t2
\end{verbatim}
}
\noindent then applying {\small\verb%DISJ_CASES_THEN f (|- u \/ v)%}
to the goal {\small\verb%(A ?- t)%} produces two subgoals.
{\par\samepage\setseps\small
\begin{verbatim}
           A ?- t
   ======================  DISJ_CASES_THEN f (|- u \/ v)
    A ?- t1      A ?- t2
\end{verbatim}
}
\FAILURE
Fails if the theorem is not a disjunction.  An invalid tactic is
produced if the theorem has any hypothesis which is not
alpha-convertible to an assumption of the goal.

\EXAMPLE
Given the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- (m = 0) \/ (?n. m = SUC n)
\end{verbatim}
}
\noindent and a goal of the form {\small\verb%?- (PRE m = m) = (m = 0)%},
applying the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   DISJ_CASES_THEN ASSUME_TAC th
\end{verbatim}
}
\noindent produces two subgoals, each with one disjunct as an added
assumption:
{\par\samepage\setseps\small
\begin{verbatim}
   ?n. m = SUC n ?- (PRE m = m) = (m = 0)

   m = 0 ?- (PRE m = m) = (m = 0)
\end{verbatim}
}
\USES
Building cases tactics. For example, {\small\verb%DISJ_CASES_TAC%} could be defined by:
{\par\samepage\setseps\small
\begin{verbatim}
   let DISJ_CASES_TAC = DISJ_CASES_THEN ASSUME_TAC
\end{verbatim}
}
\COMMENTS
Use {\small\verb%DISJ_CASES_THEN2%} to apply different tactic generating functions
to each case.

\SEEALSO
STRIP_THM_THEN, CHOOSE_THEN, CONJUNCTS_THEN, CONJUNCTS_THEN2,
DISJ_CASES_TAC, DISJ_CASES_THEN2, DISJ_CASES_THENL.

\ENDDOC
\DOC{DISJ\_CASES\_THENL}

\TYPE {\small\verb%DISJ_CASES_THENL : (thm_tactic list -> thm_tactic)%}\egroup

\SYNOPSIS
Applies theorem-tactics in a list to the corresponding disjuncts in a theorem.

\DESCRIBE
If the theorem-tactics {\small\verb%f1...fn%} applied to the {\small\verb%ASSUME%}d disjuncts of a
theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- d1 \/ d2 \/...\/ dn
\end{verbatim}
}
\noindent produce results as follows when applied to a goal {\small\verb%(A ?- t)%}:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t                                A ?- t
   =========  f1 (d1 |- d1) and ... and =========  fn (dn |- dn)
    A ?- t1                              A ?- tn
\end{verbatim}
}
\noindent then applying {\small\verb%DISJ_CASES_THENL [f1;...;fn] (|- d1 \/...\/ dn)%}
to the goal {\small\verb%(A ?- t)%} produces n subgoals.
{\par\samepage\setseps\small
\begin{verbatim}
           A ?- t
   =======================  DISJ_CASES_THENL [f1;...;fn] (|- d1 \/...\/ dn)
    A ?- t1  ...  A ?- tn
\end{verbatim}
}
\noindent {\small\verb%DISJ_CASES_THENL%} is defined using iteration, hence for
theorems with more than {\small\verb%n%} disjuncts, {\small\verb%dn%} would itself be disjunctive.

\FAILURE
Fails if the number of tactic generating functions in the list exceeds
the number of disjuncts in the theorem.  An invalid tactic is
produced if the theorem has any hypothesis which is not
alpha-convertible to an assumption of the goal.

\USES
Used when the goal is to be split into several cases, where a
different tactic-generating function is to be applied to each case.

\SEEALSO
CHOOSE_THEN, CONJUNCTS_THEN, CONJUNCTS_THEN2,
DISJ_CASES_THEN, DISJ_CASES_THEN2, STRIP_THM_THEN.

\ENDDOC
\DOC{DISJ\_CASES\_UNION}

\TYPE {\small\verb%DISJ_CASES_UNION : (thm -> thm -> thm -> thm)%}\egroup

\SYNOPSIS
Makes an inference for each arm of a disjunct.

\DESCRIBE
Given a disjunctive theorem, and two additional theorems each having one
disjunct as a hypothesis, a new theorem with a conclusion that is the
disjunction of the conclusions of the last two theorems is produced. The
hypotheses include the union of hypotheses of all three theorems less the two
disjuncts.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 \/ t2    A1 u {t1} |- t3     A2 u {t2} |- t4
   ------------------------------------------------------  DISJ_CASES_UNION
                 A u A1 u A2 |- t3 \/ t4
\end{verbatim}
}
\FAILURE
Fails if the first theorem is not a disjunction.

\EXAMPLE
The built-in theorem {\small\verb%LESS_CASES%} can be specialized to:
{\par\samepage\setseps\small
\begin{verbatim}
   th1 = |- m < n \/ n <= m
\end{verbatim}
}
\noindent and used with two additional theorems:
{\par\samepage\setseps\small
\begin{verbatim}
   th2 = (m < n |- (m MOD n = m))
   th3 = ({0 < n, n <= m} |- (m MOD n) = ((m - n) MOD n))
\end{verbatim}
}
\noindent to derive a new theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   #DISJ_CASES_UNION th1 th2 th3;;
   ["0 < n"] |- (m MOD n = m) \/ (m MOD n = (m - n) MOD n)
\end{verbatim}
}
\SEEALSO
DISJ_CASES, DISJ_CASES_TAC, DISJ1, DISJ2.

\ENDDOC
\DOC{DISJ\_IMP}

\TYPE {\small\verb%DISJ_IMP : (thm -> thm)%}\egroup

\SYNOPSIS
Converts a disjunctive theorem to an equivalent implicative theorem.

\DESCRIBE
The left disjunct of a disjunctive theorem becomes the negated
antecedent of the newly generated theorem.
{\par\samepage\setseps\small
\begin{verbatim}
     A |- t1 \/ t2
   -----------------  DISJ_IMP
    A |- ~t1 ==> t2
\end{verbatim}
}
\FAILURE
Fails if the theorem is not a disjunction.

\EXAMPLE
Specializing the built-in theorem {\small\verb%LESS_CASES%} gives the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- m < n \/ n <= m
\end{verbatim}
}
\noindent to which {\small\verb%DISJ_IMP%} may be applied:
{\par\samepage\setseps\small
\begin{verbatim}
   #DISJ_IMP th;;
   |- ~m < n ==> n <= m
\end{verbatim}
}
\SEEALSO
DISJ_CASES.

\ENDDOC
\DOC{disjuncts}

\TYPE {\small\verb%disjuncts : (term -> term list)%}\egroup

\SYNOPSIS
Iteratively breaks apart a disjunction.

\DESCRIBE
{\small\verb%disjuncts "t1 \/ ... \/ tn"%} returns {\small\verb%["t1";...;"tn"]%}.
The argument term may be any tree of disjunctions;
it need not have the form {\small\verb%"t1 \/ (t2 \/ ( ... \/ tn)...)"%}.
A term that is not a disjunction is simply returned as the sole element of a
list. Note that
{\par\samepage\setseps\small
\begin{verbatim}
   disjuncts(list_mk_disj(["t1";...;"tn"]))
\end{verbatim}
}
\noindent will not return {\small\verb%["t1";...;"tn"]%} if any of {\small\verb%t1%},...,{\small\verb%tn%} are
disjunctions.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_disj ["a \/ b";"c \/ d";"e \/ f"];;
"(a \/ b) \/ (c \/ d) \/ e \/ f" : term

#disjuncts it;;
["a"; "b"; "c"; "d"; "e"; "f"] : term list

#list_mk_disj it;;
"a \/ b \/ c \/ d \/ e \/ f" : term

#disjuncts "1";;
["1"] : term list
\end{verbatim}
}
\COMMENTS
Because {\small\verb%disjuncts%} splits both the left and right sides of a disjunction,
this operation is not the inverse of {\small\verb%list_mk_disj%}. It may be useful to
introduce {\small\verb%list_dest_disj%} for splitting only the right tails of a disjunction.

\SEEALSO
list_mk_disj, dest_disj.

\ENDDOC
\DOC{distinct}

\TYPE {\small\verb%distinct : (* list -> bool)%}\egroup

\SYNOPSIS
Checks whether the elements of a list are all distinct.

\DESCRIBE
If all the elements in a list are distinct, returns {\small\verb%true%}, otherwise returns
{\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
setify.

\ENDDOC
\DOC{/}

\TYPE {\small\verb%$/ : ((int # int) -> int)%}\egroup

\SYNOPSIS
Performs division on ML integers.

\FAILURE
Fails on division by zero.

\ENDDOC
\DOC{<<}

\TYPE {\small\verb%$<< : ((* # **) -> bool)%}\egroup

\SYNOPSIS
Performs a lexical comparison of values.

\DESCRIBE
{\small\verb%$<<%} performs a fast ordering on values.  It is substitutive with
respect to equality in ML (i.e. if {\small\verb%x << y%} and {\small\verb%x = x'%} and {\small\verb%y = y'%}
then {\small\verb%x' << y'%}).

\FAILURE
Never fails.

\USES
It is often useful, for example in normalizing terms in some way, to be able to
impose some arbitrary (but definite) ordering on ML values.

\SEEALSO
=.

\ENDDOC
\DOC{<}

\TYPE {\small\verb%$< : ((int # int) -> bool)%}\egroup

\SYNOPSIS
Performs a less-than test on ML integers.

\FAILURE
Never fails.

\ENDDOC
\DOC{=}

\TYPE {\small\verb%$= : ((* # *) -> bool)%}\egroup

\SYNOPSIS
Performs an equality test on two ML values.

\DESCRIBE
{\small\verb%$=%} works as expected on non-function types.  It may give unexpected results
when applied to function types (or types containing them, such as a pair of
functions), and should be considered unreliable in those situations.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#1 = 2;;
false : bool

#1 = 1;;
true : bool

#let f x = x + 1 and g x = x + 2;;
f = - : (int -> int)
g = - : (int -> int)

#let f' = f and h x = f x and h' x = x + 1;;
f' = - : (int -> int)
h = - : (int -> int)
h' = - : (int -> int)

#f=f;;
true : bool

#f = f';;
true : bool

#f = g;;
false : bool

#f =h;;
false : bool

#f=h';;
false : bool

#h = h';;
false : bool
\end{verbatim}
}
\ENDDOC
\DOC{>}

\TYPE {\small\verb%$> : ((int # int) -> bool)%}\egroup

\SYNOPSIS
Performs a greater-than test on ML integers.

\FAILURE
Never fails.

\ENDDOC
\DOC{-}

\TYPE {\small\verb%$- : ((int # int) -> int)%}\egroup

\SYNOPSIS
Performs subtraction on ML integers.

\FAILURE
Never fails.

\COMMENTS
Unary {\small\verb%-%} exists as an internal parser object, but not as a function.  So,
whilst typing in {\small\verb%-1;;%} will work, {\small\verb%-;;%} will return a parse error.

\ENDDOC
\DOC{\char'056}

\TYPE {\small\verb%$. : ((* # * list) -> * list)%}\egroup

\SYNOPSIS
Adds single element to the head of a list.

\DESCRIBE
The {\small\verb%.%} operator is an infixed primitive list constructor, analogous to {\small\verb%CONS%}
in LISP. Its effect is {\small\verb%x . [x1;....;xn]%} = {\small\verb%[x;x1;...;xn]%}.

\FAILURE
Never fails.

\ENDDOC
\DOC{\char'100}

\TYPE {\small\verb%$@ : ((* list # * list) -> * list)%}\egroup

\SYNOPSIS
Concatenates two lists.

\DESCRIBE
{\small\verb%@%} is an infix operator which concatenates two lists.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#[1;2;3] @ [4;5;6];;
[1; 2; 3; 4; 5; 6] : int list
\end{verbatim}
}
\SEEALSO
append.

\ENDDOC
\DOC{*}

\TYPE {\small\verb%$* : ((int # int) -> int)%}\egroup

\SYNOPSIS
Performs multiplication on ML integers.

\FAILURE
Never fails.

\ENDDOC

\DOC{\#}

\TYPE {\small\verb%$# : (((* -> **) # (*** -> ****)) -> (* # ***) -> (** # ****))%}\egroup

\SYNOPSIS
Applies two functions to a pair: {\small\verb%(f # g) (x,y)%} = {\small\verb%(f x, g y)%}.

\FAILURE
Never fails.

\SEEALSO
B, C, CB, Co, I, K, KI, o, oo, S, W.

\ENDDOC
\DOC{+}

\TYPE {\small\verb%$+ : ((int # int) -> int)%}\egroup

\SYNOPSIS
Performs addition on ML integers.

\FAILURE
Never fails.

\ENDDOC
\DOC{do}

\TYPE {\small\verb%$do : (* -> void)%}\egroup

\SYNOPSIS
Evaluates an expression for its side-effects.

\DESCRIBE
The function {\small\verb%do%} evaluates its argument (presumably for its side-effects)
and returns the value {\small\verb%(): void%}.

\FAILURE
Fails iff the evaluation of its argument fails.

\EXAMPLE
The following shows how an assignment can be evaluated for its
side-effects:
{\par\samepage\setseps\small
\begin{verbatim}
   #letref x = 1;;
   x = 1 : int

   #x := x + 1;;
   2 : int

   #do (x := x + 1);;
   () : void

   #x := x + 1;;
   4 : int
\end{verbatim}
}
\COMMENTS
The use of {\small\verb%do%} as if it were a normal ML function should not be confused with
its role as a syntactic construct in a while loop. For example, following on
from the above example, consider the following:
{\par\samepage\setseps\small
\begin{verbatim}
   #while x > 0 do do (x := x - 1);;
   () : void

   #x;;
   0 : int
\end{verbatim}
}
\noindent In the above, the first {\small\verb%do%} is part of the {\small\verb%while%} loop, whereas the
second is function-like.

\ENDDOC
\DOC{draft\_mode}

\TYPE {\small\verb%draft_mode : (void -> bool)%}\egroup

\SYNOPSIS
Tests whether HOL is currently in draft mode.

\DESCRIBE
The call {\small\verb%draft_mode()%} returns {\small\verb%true%} if HOL is in draft mode (see DESCRIPTION
for an explanation of what this means), and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\EXAMPLE
The following session assumes HOL is not in draft mode initially.
{\par\samepage\setseps\small
\begin{verbatim}
   #draft_mode();;
   false : bool

   #new_theory `spong`;;
   () : void

   #draft_mode();;
   true : bool

   #close_theory();;
   () : void

   #draft_mode();;
   false : bool
\end{verbatim}
}
\ENDDOC
\DOC{dropout}

\TYPE {\small\verb%dropout : (void -> void)%}\egroup

\SYNOPSIS
Move from top-level ML to top-level Lisp.

\DESCRIBE
Unlike {\small\verb%lsp%}, which breaks out of ML, and leaves one in a position to
return to it by continuing lisp execution, {\small\verb%dropout%} returns the user to
the Lisp top-level.  The function {\small\verb%(tml)%} must then be invoked to return to
ML.  This is inherently dangerous (internal state may not be consistent),
and should be avoided.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
          _  _    __    _      __    __
   |___   |__|   |  |   |     |__|  |__|
   |      |  |   |__|   |__   |__|  |__|

          Version 1.12 (Sun3/Franz), built on Feb 23 1991

#dropout();;

[Return to top level]
-> ^D
EOF
-> (tml)

          _  _    __    _      __    __
   |___   |__|   |  |   |     |__|  |__|
   |      |  |   |__|   |__   |__|  |__|

          Version 1.12 (Sun3/Franz), built on Feb 23 1991

##
\end{verbatim}
}
\COMMENTS
The behaviour of {\small\verb%dropout%} is unpredictable in Common Lisp, but performs as
advertised in plain Franz Lisp.  {\small\verb%dropout%} is not meant for general use, and
should be treated with great care.  If one is not wary, it is entirely possible
to corrupt HOL by using it.

\SEEALSO
lisp, lsp.

\ENDDOC
\DOC{e}

\TYPE {\small\verb%e : (tactic -> void)%}\egroup

\SYNOPSIS
Applies a tactic to the current goal, stacking the resulting subgoals.

\DESCRIBE
The function {\small\verb%e%} is part of the subgoal package. It is an abbreviation for
{\small\verb%expand%}. For a description of the subgoal package, see {\small\verb%set_goal%}.

\FAILURE
As for {\small\verb%expand%}.

\USES
Doing a step in an interactive goal-directed proof.

\SEEALSO
b, backup, backup_limit, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm, VALID.

\ENDDOC
\DOC{EL\_CONV}

\TYPE {\small\verb%EL_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of indexing an element from a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...xk;...;xn]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   EL_CONV "EL k [x0;...xk;...;xn]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- EL k [x0;...;xk;...;xn] = xk
\end{verbatim}
}


\FAILURE
{\small\verb%EL_CONV tm%} fails if {\small\verb%tm%} is not of the form described above, 
or {\small\verb%k%} is not less than the length of the list.

\SEEALSO
ELL_CONV

\ENDDOC

\DOC{el}

\TYPE {\small\verb%el : (int -> * list -> *)%}\egroup

\SYNOPSIS
Extracts a specified element from a list.

\DESCRIBE
{\small\verb%el i [x1;...;xn]%} returns {\small\verb%xi%}. Note that the elements are numbered starting
from {\small\verb%1%}, not {\small\verb%0%}.

\FAILURE
Fails with {\small\verb%el%} if the integer argument is less than 1 or greater than the
length of the list.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#el 3 [1;2;7;1];;
7 : int
\end{verbatim}
}
\SEEALSO
hd, tl.

\ENDDOC
\DOC{ELL\_CONV}

\TYPE {\small\verb%ELL_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of indexing an element of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[xn-1;...;xk;...x0]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   ELL_CONV "ELL k [xn-1;...;xk;...;x0]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- ELL k [xn-1;...;xk;...;x0] = xk
\end{verbatim}
}
\noindent where {\small\verb%k%} must not be greater then the length of the list.
Note that {\small\verb%ELL%} index the list elements from the tail end.

\FAILURE
{\small\verb%ELL_CONV tm%} fails if {\small\verb%tm%} is not of the form described above, 
or {\small\verb%k%} is not less than the length of the list.

\SEEALSO
EL_CONV

\ENDDOC

\DOC{end\_itlist}

\TYPE {\small\verb%end_itlist : ((* -> * -> *) -> * list -> *)%}\egroup

\SYNOPSIS
List iteration function. Applies a binary function between adjacent elements
of a list.

\DESCRIBE
{\small\verb%end_itlist f [x1;...;xn]%} returns {\small\verb%f x1 ( ... (f x(n-1) xn)...)%}.
Returns {\small\verb%x%} for a one-element list {\small\verb%[x]%}.

\FAILURE
Fails with {\small\verb%end_itlist%} if list is empty.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#end_itlist (\x y. x + y) [1;2;3;4];;
10 : int
\end{verbatim}
}
\SEEALSO
itlist, rev_itlist.

\ENDDOC
\DOC{enter\_form\_rep}

\TYPE {\small\verb%enter_form_rep : ((* # form # * list) -> * list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{enter\_term}

\TYPE {\small\verb%enter_term : ((term # *) -> * term_net -> * term_net)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{enter\_term\_rep}

\TYPE {\small\verb%enter_term_rep : ((* # term # * list) -> * list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{EQF\_ELIM}

\TYPE {\small\verb%EQF_ELIM : (thm -> thm)%}\egroup

\SYNOPSIS
Replaces equality with {\small\verb%F%} by negation.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A |- tm = F
   -------------  EQF_ELIM
     A |- ~tm
\end{verbatim}
}
\FAILURE
Fails if the argument theorem is not of the form {\small\verb%A |- tm = F%}.

\SEEALSO
EQF_INTRO, EQT_ELIM, EQT_INTRO.

\ENDDOC
\DOC{EQF\_INTRO}

\TYPE {\small\verb%EQF_INTRO : (thm -> thm)%}\egroup

\SYNOPSIS
Converts negation to equality with {\small\verb%F%}.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
     A |- ~tm
   -------------  EQF_INTRO
    A |- tm = F
\end{verbatim}
}
\FAILURE
Fails if the argument theorem is not a negation.

\SEEALSO
EQF_ELIM, EQT_ELIM, EQT_INTRO.

\ENDDOC
\DOC{EQ\_IMP\_RULE}

\TYPE {\small\verb%EQ_IMP_RULE : (thm -> (thm # thm))%}\egroup

\SYNOPSIS
Derives forward and backward implication from equality of boolean terms.

\DESCRIBE
When applied to a theorem {\small\verb%A |- t1 = t2%}, where {\small\verb%t1%} and {\small\verb%t2%} both have
type {\small\verb%bool%}, the inference rule {\small\verb%EQ_IMP_RULE%} returns the
theorems {\small\verb%A |- t1 ==> t2%} and {\small\verb%A |- t2 ==> t1%}.
{\par\samepage\setseps\small
\begin{verbatim}
              A |- t1 = t2
   -----------------------------------  EQ_IMP_RULE
    A |- t1 ==> t2     A |- t2 ==> t1
\end{verbatim}
}
\FAILURE
Fails unless the conclusion of the given theorem is an equation between
boolean terms.

\SEEALSO
EQ_MP, EQ_TAC, IMP_ANTISYM_RULE.

\ENDDOC
\DOC{EQ\_LENGTH\_INDUCT\_TAC}

\TYPE {\small\verb%EQ_LENGTH_INDUCT_TAC : tactic%}\egroup

\SYNOPSIS
Performs tactical proof by structural induction on two equal length lists.

\DESCRIBE
{\small\verb%EQ_LENGTH_INDUCT_TAC%} reduces a goal
 {\small\verb%!x y . (LENGTH x = LENGTH y) ==> t[x,y]%},
 where {\small\verb%x%} and {\small\verb%y%} range over lists, to two
subgoals corresponding to the base and step cases in a proof by 
induction on the length of {\small\verb%x%} and {\small\verb%y%}. The induction hypothesis appears among
the assumptions of the
subgoal for the step case.  The specification of {\small\verb%EQ_LENGTH_INDUCT_TAC%} is:
{\par\samepage\setseps\small
\begin{verbatim}
         A ?- !x y . (LENGTH x = LENGTH y) ==> t[x,y]
   ====================================================  EQ_LENGTH_INDUCT_TAC
                            A ?- t[NIL/x][NIL/y]
    A u {LENGTH x = LENGTH y, t[x'/x, y'/y]} ?- 
         !h h'. t[(CONS h x)/x, (CONS h' y)/y]
\end{verbatim}
}

\FAILURE
{\small\verb%EQ_LENGTH_INDUCT_TAC g%} fails unless the conclusion of the goal {\small\verb%g%} has the
 form 
{\par\samepage\setseps\small
\begin{verbatim}
   !x y . (LENGTH x = LENGTH y) ==> t[x,y]
\end{verbatim}
}
\noindent  where the variables {\small\verb%x%} and {\small\verb%y%}
 have types {\small\verb%(xty)list%} and {\small\verb%(yty)list%} for some types {\small\verb%xty%} and {\small\verb%yty%}.
 It also fails if either of the variables {\small\verb%x%} or {\small\verb%y%} appear free in the
 assumptions. 

\USES
use this tactic when  structural induction is performed on two lists and
they have identical length.

\SEEALSO
LIST_APPEND_INDUCT_TAC, LIST_INDUCT_TAC, SNOC_INDUCT_TAC,
LENGTH_LIST_INDUCT_TAC, EQ_LENGTH_SNOC_INDUCT_TAC.

\ENDDOC
\DOC{EQ\_LENGTH\_SNOC\_INDUCT\_TAC}

\TYPE {\small\verb%EQ_LENGTH_SNOC_INDUCT_TAC : tactic%}\egroup

\SYNOPSIS
Performs tactical proof by structural induction on two equal length
lists from the tail end.

\DESCRIBE
{\small\verb%EQ_LENGTH_SNOC_INDUCT_TAC%} reduces a goal
 {\small\verb%!x y . (LENGTH x = LENGTH y) ==> t[x,y]%},
 where {\small\verb%x%} and {\small\verb%y%} range over lists, to two
subgoals corresponding to the base and step cases in a proof by 
induction on the length of {\small\verb%x%} and {\small\verb%y%}. The induction hypothesis appears among
the assumptions of the
subgoal for the step case.  The specification of {\small\verb%EQ_LENGTH_SNOC_INDUCT_TAC%} is:
{\par\samepage\setseps\small
\begin{verbatim}
     A ?- !x y . (LENGTH x = LENGTH y) ==> t[x,y]
   ================================================  EQ_LENGTH_SNOC_INDUCT_TAC
                            A ?- t[NIL/x][NIL/y]
    A u {LENGTH x = LENGTH y, t[x'/x, y'/y]} ?- 
         !h h'. t[(SNOC h x)/x, (SNOC h' y)/y]
\end{verbatim}
}

\FAILURE
{\small\verb%EQ_LENGTH_SNOC_INDUCT_TAC g%} fails unless the conclusion of the goal {\small\verb%g%} has the
 form 
{\par\samepage\setseps\small
\begin{verbatim}
   !x y . (LENGTH x = LENGTH y) ==> t[x,y]
\end{verbatim}
}
\noindent  where the variables {\small\verb%x%} and {\small\verb%y%}
 have types {\small\verb%(xty)list%} and {\small\verb%(yty)list%} for some types {\small\verb%xty%} and {\small\verb%yty%}.
 It also fails if either of the variables {\small\verb%x%} or {\small\verb%y%} appear free in the
 assumptions. 

\USES
use this tactic when  structural induction is performed on two lists and
they have identical length.

\SEEALSO
LIST_APPEND_INDUCT_TAC, LIST_INDUCT_TAC, SNOC_INDUCT_TAC,
LENGTH_LIST_INDUCT_TAC, EQ_LENGTH_INDUCT_TAC

\ENDDOC
\DOC{EQ\_MP}

\TYPE {\small\verb%EQ_MP : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Equality version of the Modus Ponens rule.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- t1 = t2%} and {\small\verb%A2 |- t1%}, the inference
rule {\small\verb%EQ_MP%} returns the theorem {\small\verb%A1 u A2 |- t2%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1 = t2   A2 |- t1
   --------------------------  EQ_MP
         A1 u A2 |- t2
\end{verbatim}
}
\FAILURE
Fails unless the first theorem is equational and its left side
is the same as the conclusion of the second theorem (and is therefore
of type {\small\verb%bool%}), up to alpha-conversion.

\SEEALSO
EQ_IMP_RULE, IMP_ANTISYM_RULE, MP.

\ENDDOC
\DOC{EQ\_TAC}

\TYPE {\small\verb%EQ_TAC : tactic%}\egroup

\SYNOPSIS
Reduces goal of equality of boolean terms to forward and backward implication.

\DESCRIBE
When applied to a goal {\small\verb%A ?- t1 = t2%}, where {\small\verb%t1%} and {\small\verb%t2%} have type {\small\verb%bool%},
the tactic {\small\verb%EQ_TAC%} returns the subgoals {\small\verb%A ?- t1 ==> t2%} and
{\small\verb%A ?- t2 ==> t1%}.
{\par\samepage\setseps\small
\begin{verbatim}
             A ?- t1 = t2
   =================================  EQ_TAC
    A ?- t1 ==> t2   A ?- t2 ==> t1
\end{verbatim}
}
\FAILURE
Fails unless the conclusion of the goal is an equation between boolean terms.

\SEEALSO
EQ_IMP_RULE, IMP_ANTISYM_RULE.

\ENDDOC
\DOC{EQT\_ELIM}

\TYPE {\small\verb%EQT_ELIM : (thm -> thm)%}\egroup

\SYNOPSIS
Eliminates equality with {\small\verb%T%}.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A |- tm = T
   -------------  EQT_ELIM
      A |- tm
\end{verbatim}
}
\FAILURE
Fails if the argument theorem is not of the form {\small\verb%A |- tm = T%}.

\SEEALSO
EQT_INTRO, EQF_ELIM, EQF_INTRO.

\ENDDOC
\DOC{EQT\_INTRO}

\TYPE {\small\verb%EQT_INTRO : (thm -> thm)%}\egroup

\SYNOPSIS
Introduces equality with {\small\verb%T%}.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
      A |- tm
   -------------  EQF_INTRO
    A |- tm = T
\end{verbatim}
}

\FAILURE
Never fails.

\SEEALSO
EQT_ELIM, EQF_ELIM, EQF_INTRO.

\ENDDOC
\DOC{ETA\_CONV}

\TYPE {\small\verb%ETA_CONV : conv%}\egroup

\SYNOPSIS
Performs a toplevel eta-conversion.

\DESCRIBE
{\small\verb%ETA_CONV%} maps an eta-redex {\small\verb%"\x. t x"%}, where {\small\verb%x%} does not occur free in {\small\verb%t%},
to the theorem {\small\verb%|- (\x. t x) = t%}.

\FAILURE
Fails if the input term is not an eta-redex.

\ENDDOC
\DOC{EVERY\_ASSUM}

\TYPE {\small\verb%EVERY_ASSUM : (thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Sequentially applies all tactics given by mapping a function over the
assumptions of a goal.

\DESCRIBE
When applied to a theorem-tactic {\small\verb%f%} and a goal {\small\verb%({A1;...;An} ?- C)%}, the
{\small\verb%EVERY_ASSUM%} tactical maps {\small\verb%f%} over a list of {\small\verb%ASSUME%}d assumptions then
applies the resulting tactics, in sequence, to the goal:
{\par\samepage\setseps\small
\begin{verbatim}
   EVERY_ASSUM f ({A1;...;An} ?- C)
    = (f(A1 |- A1) THEN ... THEN f(An |- An)) ({A1;...;An} ?- C)
\end{verbatim}
}
\noindent If the goal has no assumptions, then {\small\verb%EVERY_ASSUM%} has no effect.

\FAILURE
The application of {\small\verb%EVERY_ASSUM%} to a theorem-tactic and a goal fails
if the theorem-tactic fails when applied to any of the {\small\verb%ASSUME%}d assumptions
of the goal, or if any of the resulting tactics fail when applied
sequentially.

\SEEALSO
ASSUM_LIST, MAP_EVERY, MAP_FIRST, THEN.

\ENDDOC
\DOC{EVERY\_CONV}

\TYPE {\small\verb%EVERY_CONV : (conv list -> conv)%}\egroup

\SYNOPSIS
Applies in sequence all the conversions in a given list of conversions.

\DESCRIBE
{\small\verb%EVERY_CONV [c1;...;cn] "t"%} returns the result of applying the conversions
{\small\verb%c1%}, ..., {\small\verb%cn%} in sequence to the term {\small\verb%"t"%}. The conversions are applied in
the order in which they are given in the list. In particular, if {\small\verb%ci "ti"%}
returns {\small\verb%|- ti=ti+1%} for {\small\verb%i%} from {\small\verb%1%} to {\small\verb%n%}, then
{\small\verb%EVERY_CONV [c1;...;cn] "t1"%} returns {\small\verb%|- t1=t(n+1)%}.  If the supplied list of
conversions is empty, then {\small\verb%EVERY_CONV%} returns the identity conversion.  That
is, {\small\verb%EVERY_CONV [] "t"%} returns {\small\verb%|- t=t%}.

\FAILURE
{\small\verb%EVERY_CONV [c1;...;cn] "t"%} fails if any one of the conversions {\small\verb%c1%}, ...,
{\small\verb%cn%} fails when applied in sequence as specified above.

\SEEALSO
THENC.

\ENDDOC
\DOC{EVERY}

\TYPE {\small\verb%EVERY : (tactic list -> tactic)%}\egroup

\SYNOPSIS
Sequentially applies all the tactics in a given list of tactics.

\DESCRIBE
When applied to a list of tactics {\small\verb%[T1; ... ;Tn]%}, and a goal {\small\verb%g%}, the tactical
{\small\verb%EVERY%} applies each tactic in sequence to every
subgoal generated by the previous one. This can be represented as:
{\par\samepage\setseps\small
\begin{verbatim}
   EVERY [T1;...;Tn] = T1 THEN ... THEN Tn
\end{verbatim}
}
\noindent If the tactic list is empty, the resulting tactic has no effect.

\FAILURE
The application of {\small\verb%EVERY%} to a tactic list never fails. The resulting
tactic fails iff any of the component tactics do.

\COMMENTS
It is possible to use {\small\verb%EVERY%} instead of {\small\verb%THEN%}, but probably
stylistically inferior. {\small\verb%EVERY%} is more useful when applied to a list of
tactics generated by a function.

\SEEALSO
FIRST, MAP_EVERY, THEN.

\ENDDOC
\DOC{EVERY\_TCL}

\TYPE {\small\verb%EVERY_TCL : (thm_tactical list -> thm_tactical)%}\egroup

\SYNOPSIS
Composes a list of theorem-tacticals.

\DESCRIBE
When given a list of theorem-tacticals and a theorem, {\small\verb%EVERY_TCL%} simply
composes their effects on the theorem. The effect is:
{\par\samepage\setseps\small
\begin{verbatim}
   EVERY_TCL [ttl1;...;ttln] = ttl1 THEN_TCL ... THEN_TCL ttln
\end{verbatim}
}
\noindent In other words, if:
{\par\samepage\setseps\small
\begin{verbatim}
   ttl1 ttac th1 = ttac th2  ...  ttln ttac thn = ttac thn'
\end{verbatim}
}
\noindent then:
{\par\samepage\setseps\small
\begin{verbatim}
   EVERY_TCL [ttl1;...;ttln] ttac th1 = ttac thn'
\end{verbatim}
}
\noindent If the theorem-tactical list is empty, the resulting theorem-tactical
behaves in the same way as {\small\verb%ALL_THEN%}, the identity theorem-tactical.

\FAILURE
The application to a list of theorem-tacticals never fails.

\SEEALSO
FIRST_TCL, ORELSE_TCL, REPEAT_TCL, THEN_TCL.

\ENDDOC
\DOC{EXISTENCE}

\TYPE {\small\verb%EXISTENCE : (thm -> thm)%}\egroup

\SYNOPSIS
Deduces existence from unique existence.

\DESCRIBE
When applied to a theorem with a unique-existentially quantified
conclusion, {\small\verb%EXISTENCE%} returns the same theorem with normal existential
quantification over the same variable.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- ?!x. p
   -------------  EXISTENCE
    A |- ?x. p
\end{verbatim}
}
\FAILURE
Fails unless the conclusion of the theorem is unique-existentially quantified.

\SEEALSO
EXISTS_UNIQUE_CONV.

\ENDDOC
\DOC{EXISTS\_AND\_CONV}

\TYPE {\small\verb%EXISTS_AND_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification inwards through a conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%?x. P /\ Q%}, where {\small\verb%x%} is not free in both
{\small\verb%P%} and {\small\verb%Q%}, {\small\verb%EXISTS_AND_CONV%} returns a theorem of one of three forms,
depending on occurrences of the variable {\small\verb%x%} in {\small\verb%P%} and {\small\verb%Q%}.  If {\small\verb%x%} is free
in {\small\verb%P%} but not in {\small\verb%Q%}, then the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P /\ Q) = (?x.P) /\ Q
\end{verbatim}
}
\noindent is returned.  If {\small\verb%x%} is free in {\small\verb%Q%} but not in {\small\verb%P%}, then the
result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P /\ Q) = P /\ (?x.Q)
\end{verbatim}
}
\noindent And if {\small\verb%x%} is free in neither {\small\verb%P%} nor {\small\verb%Q%}, then the result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P /\ Q) = (?x.P) /\ (?x.Q)
\end{verbatim}
}
\FAILURE
{\small\verb%EXISTS_AND_CONV%} fails if it is applied to a term not of the form
{\small\verb%?x. P /\ Q%}, or if it is applied to a term {\small\verb%?x. P /\ Q%} in which the
variable {\small\verb%x%} is free in both {\small\verb%P%} and {\small\verb%Q%}.

\SEEALSO
AND_EXISTS_CONV, LEFT_AND_EXISTS_CONV, RIGHT_AND_EXISTS_CONV.

\ENDDOC
\DOC{exists}

\TYPE {\small\verb%exists : ((* -> bool) -> * list -> bool)%}\egroup

\SYNOPSIS
Tests a list to see if it has at least one element satisfying a predicate.

\DESCRIBE
{\small\verb%exists p l%} applies {\small\verb%p%} to the elements of {\small\verb%l%} in order until one is found
which satisfies {\small\verb%p%}, or until the list is exhausted, returning {\small\verb%true%} or
{\small\verb%false%} accordingly.

\FAILURE
Never fails.

\SEEALSO
forall, find, tryfind, mem, assoc, rev_assoc.

\ENDDOC
\DOC{EXISTS}

\TYPE {\small\verb%EXISTS : ((term # term) -> thm -> thm)%}\egroup

\SYNOPSIS
Introduces existential quantification given a particular witness.

\DESCRIBE
When applied to a pair of terms and a theorem, the first term an existentially
quantified pattern indicating the desired form of the result, and the second a
witness whose substitution for the quantified variable gives a term which is
the same as the conclusion of the theorem, {\small\verb%EXISTS%} gives the desired theorem.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- p[u/x]
   -------------  EXISTS ("?x. p","u")
    A |- ?x. p
\end{verbatim}
}
\FAILURE
Fails unless the substituted pattern is the same as the conclusion of the
theorem.

\EXAMPLE
The following examples illustrate how it is possible to deduce different
things from the same theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   #EXISTS ("?x. x=T","T") (REFL "T");;
   |- ?x. x = T

   #EXISTS ("?x:bool. x=x","T") (REFL "T");;
   |- ?x. x = x
\end{verbatim}
}
\SEEALSO
CHOOSE, EXISTS_TAC.

\ENDDOC
\DOC{EXISTS\_EQ}

\TYPE {\small\verb%EXISTS_EQ : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Existentially quantifies both sides of an equational theorem.

\DESCRIBE
When applied to a variable {\small\verb%x%} and a theorem whose conclusion is
equational, {\small\verb%A |- t1 = t2%}, the inference rule
{\small\verb%EXISTS_EQ%} returns the theorem {\small\verb%A |- (?x. t1) = (?x. t2)%}, provided
the variable {\small\verb%x%} is not free in any of the assumptions.
{\par\samepage\setseps\small
\begin{verbatim}
         A |- t1 = t2
   ------------------------  EXISTS_EQ "x"      [where x is not free in A]
    A |- (?x.t1) = (?x.t2)
\end{verbatim}
}
\FAILURE
Fails unless the theorem is equational with both sides having type {\small\verb%bool%},
or if the term is not a variable, or if the variable to be quantified
over is free in any of the assumptions.

\SEEALSO
AP_TERM, EXISTS_IMP, FORALL_EQ, MK_EXISTS, SELECT_EQ.

\ENDDOC
\DOC{EXISTS\_GREATEST\_CONV}

\TYPE {\small\verb%EXISTS_GREATEST_CONV : conv%}\egroup

\SYNOPSIS
Proves that a nonempty bounded set of natural numbers has a greatest element.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   EXISTS_GREATEST_CONV "(?x. P[x]) /\ (?y. !z. z > y ==> ~P[z])"
\end{verbatim}
}
\noindent returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   (?x. P[x]) /\ (?y. !z. z > y ==> ~P[z]) = ?x. P[x] /\ !z. z > x ==> ~P[z]
\end{verbatim}
}
\noindent This expresses the equivalence of the statements `a property {\small\verb%P%}
is true for some number {\small\verb%x%}, and there is a limit {\small\verb%y%} beyond which {\small\verb%P%} is not
true' and `there is a greatest number such that {\small\verb%P%} is true'.

\FAILURE
{\small\verb%EXISTS_GREATEST_CONV tm%} fails unless {\small\verb%tm%} has the form specified above.

\SEEALSO
EXISTS_LEAST_CONV.

\ENDDOC
\DOC{EXISTS\_IMP\_CONV}

\TYPE {\small\verb%EXISTS_IMP_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification inwards through an implication.

\DESCRIBE
When applied to a term of the form {\small\verb%?x. P ==> Q%}, where {\small\verb%x%} is not free in
both {\small\verb%P%} and {\small\verb%Q%}, {\small\verb%EXISTS_IMP_CONV%} returns a theorem of one of three forms,
depending on occurrences of the variable {\small\verb%x%} in {\small\verb%P%} and {\small\verb%Q%}.  If {\small\verb%x%} is free
in {\small\verb%P%} but not in {\small\verb%Q%}, then the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P ==> Q) = (!x.P) ==> Q
\end{verbatim}
}
\noindent is returned.  If {\small\verb%x%} is free in {\small\verb%Q%} but not in {\small\verb%P%}, then the
result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P ==> Q) = P ==> (?x.Q)
\end{verbatim}
}
\noindent And if {\small\verb%x%} is free in neither {\small\verb%P%} nor {\small\verb%Q%}, then the result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P ==> Q) = (!x.P) ==> (?x.Q)
\end{verbatim}
}
\FAILURE
{\small\verb%EXISTS_IMP_CONV%} fails if it is applied to a term not of the form
{\small\verb%?x. P ==> Q%}, or if it is applied to a term {\small\verb%?x. P ==> Q%} in which the
variable {\small\verb%x%} is free in both {\small\verb%P%} and {\small\verb%Q%}.

\SEEALSO
LEFT_IMP_FORALL_CONV, RIGHT_IMP_EXISTS_CONV.

\ENDDOC
\DOC{EXISTS\_IMP}

\TYPE {\small\verb%EXISTS_IMP : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Existentially quantifies both the antecedent and consequent of an implication.

\DESCRIBE
When applied to a variable {\small\verb%x%} and a theorem {\small\verb%A |- t1 ==> t2%}, the
inference rule {\small\verb%EXISTS_IMP%} returns the theorem {\small\verb%A |- (?x. t1) ==> (?x. t2)%},
provided {\small\verb%x%} is not free in the assumptions.
{\par\samepage\setseps\small
\begin{verbatim}
         A |- t1 ==> t2
   --------------------------  EXISTS_IMP "x"   [where x is not free in A]
    A |- (?x.t1) ==> (?x.t2)
\end{verbatim}
}
\FAILURE
Fails if the theorem is not implicative, or if the term is not a variable, or
if the term is a variable but is free in the assumption list.

\SEEALSO
EXISTS_EQ.

\ENDDOC
\DOC{EXISTS\_LEAST\_CONV}

\TYPE {\small\verb%EXISTS_LEAST_CONV : conv%}\egroup

\SYNOPSIS
Applies the well-ordering property of the natural numbers.

\DESCRIBE
Given a term of the form {\small\verb%"?n:num.P[n]"%}, the conversion {\small\verb%EXISTS_LEAST_CONV%}
proves that this assertion is equivalent to the statement that there is a
least number {\small\verb%n%} such that {\small\verb%P[n]%} holds.  The theorem returned is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?n. P[n]) = ?n. P[n] /\ !n'. (n' < n) ==> ~P[n']
\end{verbatim}
}
\noindent where {\small\verb%n'%} is a primed variant of {\small\verb%n%} that does not appear free in
the input term.  Note that the variable {\small\verb%n%} need not in fact appear free in
the body of the existentially-quantified input term.  For example,
{\small\verb%EXISTS_LEAST_CONV "?n:num.T"%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?n. T) = (?n. T /\ (!n'. n' < n ==> ~T))
\end{verbatim}
}
\FAILURE
{\small\verb%EXISTS_LEAST_CONV tm%} fails if {\small\verb%tm%} is not of the form {\small\verb%"?n:num.P"%}.

\SEEALSO
EXISTS_GREATEST_CONV.

\ENDDOC
\DOC{EXISTS\_NOT\_CONV}

\TYPE {\small\verb%EXISTS_NOT_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification inwards through a negation.

\DESCRIBE
When applied to a term of the form {\small\verb%?x.~P%}, the conversion {\small\verb%EXISTS_NOT_CONV%}
returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x.~P) = ~(!x. P)
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%?x.~P%}.

\SEEALSO
FORALL_NOT_CONV, NOT_EXISTS_CONV, NOT_FORALL_CONV.

\ENDDOC
\DOC{EXISTS\_OR\_CONV}

\TYPE {\small\verb%EXISTS_OR_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification inwards through a disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%?x. P \/ Q%}, the conversion
{\small\verb%EXISTS_OR_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x. P \/ Q) = (?x.P) \/ (?x.Q)
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%?x. P \/ Q%}.

\SEEALSO
OR_EXISTS_CONV, LEFT_OR_EXISTS_CONV, RIGHT_OR_EXISTS_CONV.

\ENDDOC
\DOC{EXISTS\_TAC}

\TYPE {\small\verb%EXISTS_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Reduces existentially quantified goal to one involving a specific witness.

\DESCRIBE
When applied to a term {\small\verb%u%} and a goal {\small\verb%?x. t%}, the tactic
{\small\verb%EXISTS_TAC%} reduces the goal to {\small\verb%t[u/x]%} (substituting {\small\verb%u%}
for all free instances of {\small\verb%x%} in {\small\verb%t%}, with variable renaming if
necessary to avoid free variable capture).
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- ?x. t
   =============  EXISTS_TAC "u"
    A ?- t[u/x]
\end{verbatim}
}
\FAILURE
Fails unless the goal's conclusion is existentially quantified and the
term supplied has the same type as the quantified variable in the goal.

\EXAMPLE
The goal:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- ?x. x=T
\end{verbatim}
}
\noindent can be solved by:
{\par\samepage\setseps\small
\begin{verbatim}
   EXISTS_TAC "T" THEN REFL_TAC
\end{verbatim}
}
\SEEALSO
EXISTS.

\ENDDOC
\DOC{EXISTS\_UNIQUE\_CONV}

\TYPE {\small\verb%EXISTS_UNIQUE_CONV : conv%}\egroup

\SYNOPSIS
Expands with the definition of unique existence.

\DESCRIBE
Given a term of the form {\small\verb%"?!x.P[x]"%}, the conversion {\small\verb%EXISTS_UNIQUE_CONV%}
proves that this assertion is equivalent to the conjunction of two statements,
namely that there exists at least one value {\small\verb%x%} such that {\small\verb%P[x]%}, and that
there is at most one value {\small\verb%x%} for which {\small\verb%P[x]%} holds. The theorem returned is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?! x. P[x]) = (?x. P[x]) /\ (!x x'. P[x] /\ P[x'] ==> (x = x'))
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.  Note that the quantified variable {\small\verb%x%} need not in fact appear
free in the body of the input term.  For example, {\small\verb%EXISTS_UNIQUE_CONV "?!x.T"%}
returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?! x. T) = (?x. T) /\ (!x x'. T /\ T ==> (x = x'))
\end{verbatim}
}
\FAILURE
{\small\verb%EXISTS_UNIQUE_CONV tm%} fails if {\small\verb%tm%} does not have the form {\small\verb%"?!x.P"%}.

\SEEALSO
EXISTENCE.

\ENDDOC
\DOC{expand}

\TYPE {\small\verb%expand : (tactic -> void)%}\egroup

\SYNOPSIS
Applies a tactic to the current goal, stacking the resulting subgoals.

\DESCRIBE
The function {\small\verb%expand%} is part of the subgoal package.  It may be abbreviated by
the function {\small\verb%e%}.  It applies a tactic to the current goal to give a new proof
state. The previous state is stored on the backup list. If the tactic produces
subgoals, the new proof state is formed from the old one by removing the
current goal from the goal stack and adding a new level consisting of its
subgoals. The corresponding justification is placed on the justification stack.
The new subgoals are printed. If more than one subgoal is produced, they are
printed from the bottom of the stack so that the new current goal is  printed
last.

If a tactic solves the current goal (returns an empty subgoal list), then its
justification is used to prove a corresponding theorem. This theorem is
incorporated into the justification of the parent goal and printed. If the
subgoal was the last subgoal of the level, the level is removed and the parent
goal is proved using  its (new) justification. This process is repeated until a
level with unproven subgoals is reached. The next goal on the goal stack then
becomes the current goal. This goal is printed. If all the subgoals are proved,
the resulting proof state consists of the theorem proved by the justifications.

The tactic applied is a validating version of the tactic given. It ensures that
the justification of the tactic does provide a proof of the goal from the
subgoals generated by the tactic. It will cause failure if this is not so. The
tactical {\small\verb%VALID%} performs this validation.

For a description of the subgoal package, see  {\small\verb%set_goal%}.

\FAILURE
{\small\verb%expand tac%} fails if the tactic {\small\verb%tac%} fails for the top goal. It will diverge
if the tactic diverges for the goal. It will fail if there are no unproven
goals. This could be because no goal has been set using {\small\verb%set_goal%} or because
the last goal set has been completely proved. It will also fail in cases when
the tactic is invalid.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#expand CONJ_TAC;;
OK..
evaluation failed     no goals to expand

#g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])";;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

() : void

#expand CONJ_TAC;;
OK..
2 subgoals
"TL[1;2;3] = [2;3]"

"HD[1;2;3] = 1"

() : void

#expand (REWRITE_TAC[HD]);;
OK..
goal proved
|- HD[1;2;3] = 1

Previous subproof:
"TL[1;2;3] = [2;3]"

() : void

#expand (REWRITE_TAC[TL]);;
OK..
goal proved
|- TL[1;2;3] = [2;3]
|- (HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])

Previous subproof:
goal proved
() : void
\end{verbatim}
}
\noindent In the following example an invalid tactic is used. It is invalid
because it assumes something that is not on the assumption list of the goal.
The justification adds this assumption to the assumption list so the
justification would not prove the goal that was set.
{\par\samepage\setseps\small
\begin{verbatim}
#set_goal([],"1=2");;
"1 = 2"

() : void

#expand (REWRITE_TAC[ASSUME "1=2"]);;
OK..
evaluation failed     Invalid tactic
\end{verbatim}
}
\USES
Doing a step in an interactive goal-directed proof.

\SEEALSO
b, backup, backup_limit, e, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm, VALID.

\ENDDOC
\DOC{expandf}

\TYPE {\small\verb%expandf : (tactic -> void)%}\egroup

\SYNOPSIS
Applies a tactic to the current goal, stacking the resulting subgoals.

\DESCRIBE
The function {\small\verb%expandf%} is a faster version of {\small\verb%expand%}. It does not use a
validated version of the tactic. That is, no check is made that the
justification of the tactic does prove the goal from the subgoals it generates.
If an invalid tactic is used, the theorem ultimately proved  may not match the
goal originally set. Alternatively, failure may occur when the justifications
are applied in which case the theorem would not be proved. For a description of
the subgoal package, see under {\small\verb%set_goal%}.

\FAILURE
Calling {\small\verb%expandf tac%} fails if the tactic {\small\verb%tac%} fails for the top goal. It will
diverge if the tactic diverges for the goal. It will fail if there are no
unproven goals. This could be because no goal has been set using {\small\verb%set_goal%} or
because the last goal set has been completely proved. If an invalid tactic,
whose justification actually fails, has been used earlier in the proof,
{\small\verb%expandf tac%} may succeed in applying {\small\verb%tac%} and apparently prove the current
goal. It may then fail as it applies the justifications of the tactics applied
earlier.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #g "HD[1;2;3] = 1";;
   "HD[1;2;3] = 1"

   () : void

   #expandf (REWRITE_TAC[HD;TL]);;
   OK..
   goal proved
   |- HD[1;2;3] = 1

   Previous subproof:
   goal proved
   () : void
\end{verbatim}
}
\noindent The following example shows how the use of an invalid tactic can
yield a  theorem which does not correspond to the  goal set.
{\par\samepage\setseps\small
\begin{verbatim}
   #set_goal([],"1=2");;
   "1 = 2"

   () : void

   #expandf (REWRITE_TAC[ASSUME "1=2"]);;
   OK..
   goal proved
   . |- 1 = 2

   Previous subproof:
   goal proved
   () : void
\end{verbatim}
}
\noindent The proof assumed something which was not on the assumption list.
This assumption appears in the assumption list of the theorem proved, even
though it was not in the goal. An attempt to perform the proof using {\small\verb%expand%}
fails. The validated version of the tactic detects that the justification
produces a theorem which does not correspond to the goal set. It therefore
fails.

\USES
Saving CPU time when doing goal-directed proofs, since the extra validation is
not done. Redoing proofs quickly that are already known to work.

\COMMENTS
The CPU time saved may cause  misery later. If an invalid tactic is used, this
will only be discovered when the proof has apparently been finished and the
justifications are applied.

\SEEALSO
b, backup, backup_limit, e, expand, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm, VALID.

\ENDDOC
\DOC{explode}

\TYPE {\small\verb%explode : (string -> string list)%}\egroup

\SYNOPSIS
Converts a string into a list of single-character strings.

\DESCRIBE
{\small\verb%explode s%} returns the list of single-character strings that make up {\small\verb%s%}, in
the order in which they appear in {\small\verb%s%}. If {\small\verb%s%} is the empty string, then an
empty list is returned.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#explode `example`;;
[`e`; `x`; `a`; `m`; `p`; `l`; `e`] : string list
\end{verbatim}
}
\SEEALSO
implode, concat, concatl.

\ENDDOC
\DOC{EXT}

\TYPE {\small\verb%EXT : (thm -> thm)%}\egroup

\SYNOPSIS
Derives equality of functions from extentional equivalence.

\DESCRIBE
When applied to a theorem {\small\verb%A |- !x. t1 x = t2 x%}, the inference rule
{\small\verb%EXT%} returns the theorem {\small\verb%A |- t1 = t2%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- !x. t1 x = t2 x
   ----------------------  EXT          [where x is not free in t1 or t2]
        A |- t1 = t2
\end{verbatim}
}
\FAILURE
Fails if the theorem does not have the form indicated above, or
if the variable {\small\verb%x%} is free either of the functions {\small\verb%t1%} or {\small\verb%t2%}.

\SEEALSO
AP_THM, ETA_CONV, FUN_EQ_CONV.

\ENDDOC
\DOC{extend\_theory}

\TYPE {\small\verb%extend_theory : (string -> void)%}\egroup

\SYNOPSIS
Allows an existing theory to be extended.

\DESCRIBE
Calling {\small\verb%extend_theory `thy`%} loads the existing theory {\small\verb%thy%} into the system
and makes it the current theory. The message `{\small\verb%Theory thy loaded%}' is printed.
The theory is entered in draft mode. This allows new axioms, constants, types,
constant specifications, infix constants, binders and parents to be added to
the theory segment. Inconsistencies may be introduced to the theory if
inconsistent axioms are asserted.  New theorems can also be added as when in
proof mode. If new type or constant names are added to theory {\small\verb%thy%} which
clash with names in any of its descendants, later attempts to load those
descendants will fail. The extensions to the theory segment might  not be
written to the theory file until the session is finished with a call to
{\small\verb%close_theory%}. If HOL is quitted without closing the session with
{\small\verb%close_theory%}, parts of the theory segment created during the session may be
lost. If the system is in draft mode when a call to {\small\verb%extend_theory%} is made,
the previous session is closed; all changes made in it will be written to the
associated theory file.

\FAILURE
A call to {\small\verb%extend_theory `thy`%} will fail if theory {\small\verb%thy%} does not appear on
the current search path. It will fail unless theory {\small\verb%thy%} is either the
current theory or a descendant of it. It will fail if any of the theory files
of the theory {\small\verb%thy%} have been damaged. It will also fail if an ancestor of
theory {\small\verb%thy%} has been extended with either new types or constants which clash
with names in theory {\small\verb%thy%}. Since it could involve writing to the file
system, if a write fails for any reason {\small\verb%extend_theory%} will fail. On failure,
the system recovers cleanly, unloading any theory segments it had loaded before
the failure was detected. It will diverge if the theory hierarchy within theory
{\small\verb%thy%} contains loops, so that a theory segment is its own ancestor.

\USES
The normal way to build upon a theory is to use it as a parent. You should
only use {\small\verb%extend_theory%} to add declarations, etc., that were mistakenly
omitted from a theory.

\COMMENTS
It would be difficult to implement the necessary checks to ensure that added
types, constants, etc., did not invalidate declarations in the descendant
theories.

\SEEALSO
load_theory, new_parent, new_theory, print_theory, search_path.

\ENDDOC
\DOC{FAIL\_TAC}

\TYPE {\small\verb%FAIL_TAC : (string -> tactic)%}\egroup

\SYNOPSIS
Tactic which always fails, with the supplied string.

\DESCRIBE
Whatever goal it is applied to, {\small\verb%FAIL_TAC s%} always fails
with the string {\small\verb%s%}.

\FAILURE
The application of {\small\verb%FAIL_TAC%} to a string never fails; the resulting
tactic always fails.

\EXAMPLE
The following example uses the fact that if a tactic {\small\verb%t1%} solves
a goal, then the tactic {\small\verb%t1 THEN t2%} never results in the application
of {\small\verb%t2%} to anything, because {\small\verb%t1%} produces no subgoals. In attempting
to solve the following goal:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- x => T | T
\end{verbatim}
}
\noindent the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   REWRITE_TAC[] THEN FAIL_TAC `Simple rewriting failed to solve goal`
\end{verbatim}
}
\noindent will fail with the message provided, whereas:
{\par\samepage\setseps\small
\begin{verbatim}
   CONV_TAC COND_CONV THEN FAIL_TAC `Using COND_CONV failed to solve goal`
\end{verbatim}
}
\noindent will silently solve the goal because {\small\verb%COND_CONV%} reduces it to
just {\small\verb%?- T%}.

\SEEALSO
ALL_TAC, NO_TAC.

\ENDDOC
\DOC{falsity}

\TYPE {\small\verb%falsity : term%}\egroup

\SYNOPSIS
Contains the constant {\small\verb%"F:bool"%}.

\ENDDOC
\DOC{fast\_arith}

\TYPE {\small\verb%fast_arith : (bool -> void)%}\egroup

\SYNOPSIS
Switches fast, finite-precision arithmetic either on or off.

\DESCRIBE
HOL normally does arithmetic using arbitrary precision. It can be changed to
use faster, finite-precision arithmetic by {\small\verb%fast_arith true%}, and the normal
behaviour restored with {\small\verb%fast_arith false%}. The current state does not affect
the mode of arithmetic in previously defined functions, such as {\small\verb%num_CONV%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#fast_arith true;;
() : void

#let pow2 x = funpow x (curry $* 2) 1;;
pow2 = - : (int -> int)

#map pow2 [30; 31; 32; 33];;
[1073741824; -2147483648; 0; 0] : int list
\end{verbatim}
}
\COMMENTS
This function is extremely dependent on the version of Lisp used, and its
behaviour should not be relied upon; it may not work at all in Lisps other than
Franz. It is questionable whether it is ever worthwhile to use it anyway,
because although it cannot compromise the consistency of the logic, it can
lead to confusing failures if one is manipulating numbers larger than the word
size of the machine.

\ENDDOC
\DOC{FILTER\_ASM\_REWRITE\_RULE}

\TYPE {\small\verb%FILTER_ASM_REWRITE_RULE : ((term -> bool) -> thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem including built-in rewrites and some of the theorem's
assumptions.

\DESCRIBE
This function implements selective rewriting with a subset of the assumptions
of the theorem. The first argument (a predicate on terms) is applied to all
assumptions, and the ones which return {\small\verb%true%} are used (along with the set of
basic tautologies and the given theorem list) to rewrite the theorem. See
{\small\verb%GEN_REWRITE_RULE%} for more information on rewriting.

\FAILURE
{\small\verb%FILTER_ASM_REWRITE_RULE%} does not fail. Using {\small\verb%FILTER_ASM_REWRITE_RULE%} may
result in a diverging sequence of rewrites. In such cases
{\small\verb%FILTER_ONCE_ASM_REWRITE_RULE%} may be used.

\USES
This rule can be applied when rewriting with all assumptions results in
divergence. Typically, the predicate can model checks as to whether a certain
variable appears on the left-hand side of an equational assumption, or whether
the assumption is in disjunctive form.

Another use is to improve performance when there are many assumptions
which are not applicable. Rewriting, though a powerful method of
proving theorems in HOL, can result in a reduced performance due to
the pattern matching and the number of primitive inferences involved.

\SEEALSO
ASM_REWRITE_RULE, FILTER_ONCE_ASM_REWRITE_RULE, FILTER_PURE_ASM_REWRITE_RULE,
FILTER_PURE_ONCE_ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_REWRITE_RULE,
PURE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{FILTER\_ASM\_REWRITE\_TAC}

\TYPE {\small\verb%FILTER_ASM_REWRITE_TAC : ((term -> bool) -> thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal including built-in rewrites and some of the goal's assumptions.

\DESCRIBE
This function implements selective rewriting with a subset of the assumptions
of the goal. The first argument (a predicate on terms) is applied to all
assumptions, and the ones which return {\small\verb%true%} are used (along with the set of
basic tautologies and the given theorem list) to rewrite the goal. See
{\small\verb%GEN_REWRITE_TAC%} for more information on rewriting.

\FAILURE
{\small\verb%FILTER_ASM_REWRITE_TAC%} does not fail, but it can result in an invalid tactic
if the rewrite is invalid. This happens when a theorem used for rewriting has
assumptions which are not alpha-convertible to assumptions of the goal. Using
{\small\verb%FILTER_ASM_REWRITE_TAC%} may result in a diverging sequence of rewrites. In
such cases {\small\verb%FILTER_ONCE_ASM_REWRITE_TAC%} may be used.

\USES
This tactic can be applied when rewriting with all assumptions results in
divergence, or in an unwanted proof state. Typically, the predicate can model
checks as to whether a certain variable appears on the left-hand side of an
equational assumption, or whether the assumption is in disjunctive form. Thus
it allows choice of assumptions to rewrite with in a position-independent
fashion.

Another use is to improve performance when there are many assumptions
which are not applicable. Rewriting, though a powerful method of
proving theorems in HOL, can result in a reduced performance due to
the pattern matching and the number of primitive inferences involved.

\SEEALSO
ASM_REWRITE_TAC, FILTER_ONCE_ASM_REWRITE_TAC, FILTER_PURE_ASM_REWRITE_TAC,
FILTER_PURE_ONCE_ASM_REWRITE_TAC, GEN_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_REWRITE_TAC, REWRITE_TAC.

\ENDDOC
\DOC{FILTER\_CONV}

\TYPE {\small\verb%FILTER_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a predicate to elements of a list.

\DESCRIBE
{\small\verb%FILTER_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   FILTER P [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- FILTER P [x0;...xn] = [...xi...]
\end{verbatim}
}
\noindent where for every {\small\verb%xi%} occurred in the right-hand side of the resulting theorem, {\small\verb%conv "P xi"%} returns a theorem {\small\verb%|- P xi = T%}.

\FAILURE
{\small\verb%FILTER_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above.

\EXAMPLE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   FILTER_CONV bool_EQ_CONV "FILTER ($= T) [T;F;T]";;
\end{verbatim}
}
\noindent returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- FILTER($= T)[T;F;T] = [T;T]
\end{verbatim}
}
\noindent   In general, if the predicate {\small\verb%P%} is an explicit lambda abstraction
{\small\verb%(\x. P x)%}, the conversion should be in the form
{\par\samepage\setseps\small
\begin{verbatim}
   (BETA_CONV THENC conv')
\end{verbatim}
}

\SEEALSO
FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{FILTER\_DISCH\_TAC}

\TYPE {\small\verb%FILTER_DISCH_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Conditionally moves the antecedent of an implicative goal into the assumptions.

\DESCRIBE
{\small\verb%FILTER_DISCH_TAC%} will move the antecedent of an implication into the
assumptions, provided its parameter does not occur in the antecedent.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- u ==> v
   ==============  FILTER_DISCH_TAC "w"
    A u {u} ?- v
\end{verbatim}
}
\noindent Note that {\small\verb%DISCH_TAC%} treats {\small\verb%"~u"%} as {\small\verb%"u ==> F"%}. Unlike
{\small\verb%DISCH_TAC%}, the antecedent will be {\small\verb%STRIP%}ed into its various components
before being {\small\verb%ASSUME%}d. This stripping includes generating multiple goals for
case-analysis of disjunctions. Also, unlike {\small\verb%DISCH_TAC%}, should any component
of the discharged antecedent directly imply or contradict the goal, then this
simplification will also be made. Again, unlike {\small\verb%DISCH_TAC%}, {\small\verb%FILTER_DISCH_TAC%}
will not duplicate identical or alpha-equivalent assumptions.

\FAILURE
{\small\verb%FILTER_DISCH_TAC%} will fail if a term which is identical, or alpha-equivalent
to {\small\verb%"w"%} occurs free in the antecedent, or if the theorem is not an implication
or a negation.

\COMMENTS
{\small\verb%FILTER_DISCH_TAC "w"%} behaves like {\small\verb%FILTER_DISCH_THEN STRIP_ASSUME_TAC "w"%}.

\SEEALSO
DISCH, DISCH_ALL, DISCH_TAC, DISCH_THEN, FILTER_DISCH_THEN, NEG_DISCH,
STRIP_TAC, UNDISCH, UNDISCH_ALL, UNDISCH_TAC.

\ENDDOC
\DOC{FILTER\_DISCH\_THEN}

\TYPE {\small\verb%FILTER_DISCH_THEN : (thm_tactic -> term -> tactic)%}\egroup

\SYNOPSIS
Conditionally gives to a theorem-tactic the antecedent of an implicative goal.

\DESCRIBE
If {\small\verb%FILTER_DISCH_THEN%}'s second argument, a term, does not occur in the
antecedent, then {\small\verb%FILTER_DISCH_THEN%} removes the antecedent and then creates a
theorem by {\small\verb%ASSUME%}ing it. This new theorem is passed to {\small\verb%FILTER_DISCH_THEN%}'s
first argument, which is subsequently expanded. For example, if
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   ========  f (ASSUME "u")
    B ?- v
\end{verbatim}
}
\noindent then
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- u ==> t
   ==============  FILTER_DISCH_THEN f
       B ?- v
\end{verbatim}
}
\noindent Note that {\small\verb%FILTER_DISCH_THEN%} treats {\small\verb%"~u"%} as {\small\verb%"u ==> F"%}.

\FAILURE
{\small\verb%FILTER_DISCH_THEN%} will fail if a term which is identical, or alpha-equivalent
to {\small\verb%"w"%} occurs free in the antecedent. {\small\verb%FILTER_DISCH_THEN%} will also fail if
the theorem is an implication or a negation.

\COMMENTS
{\small\verb%FILTER_DISCH_THEN%} is most easily understood by first understanding
{\small\verb%DISCH_THEN%}.

\USES
For preprocessing an antecedent before moving it to the assumptions, or for
using antecedents and then throwing them away.

\SEEALSO
DISCH, DISCH_ALL, DISCH_TAC, DISCH_THEN, FILTER_DISCH_TAC, NEG_DISCH,
STRIP_TAC, UNDISCH, UNDISCH_ALL, UNDISCH_TAC.

\ENDDOC
\DOC{filter}

\TYPE {\small\verb%filter : ((* -> bool) -> * list -> * list)%}\egroup

\SYNOPSIS
Filters a list to the sublist of elements satisfying a predicate.

\DESCRIBE
{\small\verb%filter p l%} applies {\small\verb%p%} to every element of {\small\verb%l%}, returning a list of those
that satisfy {\small\verb%p%}, in the order they appeared in the original list.

\FAILURE
Never fails.

\SEEALSO
mapfilter, partition, remove.

\ENDDOC
\DOC{FILTER\_GEN\_TAC}

\TYPE {\small\verb%FILTER_GEN_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Strips off a universal quantifier, but fails for a given quantified variable.

\DESCRIBE
When applied to a term {\small\verb%s%} and a goal {\small\verb%A ?- !x. t%}, the tactic {\small\verb%FILTER_GEN_TAC%}
fails if the quantified variable {\small\verb%x%} is the same as {\small\verb%s%}, but otherwise
advances the goal in the same way as {\small\verb%GEN_TAC%}, i.e. returns the goal
{\small\verb%A ?- t[x'/x]%} where {\small\verb%x'%} is a variant of {\small\verb%x%} chosen to avoid clashing with
any variables free in the goal's assumption list. Normally {\small\verb%x'%} is just {\small\verb%x%}.
{\par\samepage\setseps\small
\begin{verbatim}
     A ?- !x. t
   ==============  FILTER_GEN_TAC "s"
    A ?- t[x'/x]
\end{verbatim}
}
\FAILURE
Fails if the goal's conclusion is not universally quantified or the
quantified variable is equal to the given term.

\SEEALSO
GEN, GEN_TAC, GENL, GEN_ALL, SPEC, SPECL, SPEC_ALL, SPEC_TAC, STRIP_TAC.

\ENDDOC
\DOC{FILTER\_ONCE\_ASM\_REWRITE\_RULE}

\TYPE {\small\verb%FILTER_ONCE_ASM_REWRITE_RULE : ((term -> bool) -> thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem once including built-in rewrites and some of its assumptions.

\DESCRIBE
The first argument is a predicate applied to the assumptions. The theorem is
rewritten with the assumptions for which the predicate returns {\small\verb%true%}, the
given list of theorems, and the tautologies stored in {\small\verb%basic_rewrites%}. It
searches the term of the theorem once, without applying rewrites recursively.
Thus it avoids the divergence which can result from the application of
{\small\verb%FILTER_ASM_REWRITE_RULE%}. For more information on rewriting rules, see
{\small\verb%GEN_REWRITE_RULE%}.

\FAILURE
Never fails.

\USES
This function is useful when rewriting with a subset of assumptions of
a theorem, allowing control of the number of rewriting passes.

\SEEALSO
ASM_REWRITE_RULE, FILTER_ASM_REWRITE_RULE, FILTER_PURE_ASM_REWRITE_RULE,
FILTER_PURE_ONCE_ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_ASM_REWRITE_RULE,
ONCE_DEPTH_CONV, PURE_ASM_REWRITE_RULE, PURE_ONCE_ASM_REWRITE_RULE,
PURE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{FILTER\_ONCE\_ASM\_REWRITE\_TAC}

\TYPE {\small\verb%FILTER_ONCE_ASM_REWRITE_TAC : ((term -> bool) -> thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal once including built-in rewrites and some of its assumptions.

\DESCRIBE
The first argument is a predicate applied to the assumptions. The goal is
rewritten with the assumptions for which the predicate returns {\small\verb%true%}, the
given list of theorems, and the tautologies stored in {\small\verb%basic_rewrites%}. It
searches the term of the goal once, without applying rewrites recursively. Thus
it avoids the divergence which can result from the application of
{\small\verb%FILTER_ASM_REWRITE_TAC%}. For more information on rewriting tactics, see
{\small\verb%GEN_REWRITE_TAC%}.

\FAILURE
Never fails.

\USES
This function is useful when rewriting with a subset of assumptions of
a goal, allowing control of the number of rewriting passes.

\SEEALSO
ASM_REWRITE_TAC, FILTER_ASM_REWRITE_TAC, FILTER_PURE_ASM_REWRITE_TAC,
FILTER_PURE_ONCE_ASM_REWRITE_TAC, GEN_REWRITE_TAC, ONCE_ASM_REWRITE_TAC,
ONCE_DEPTH_CONV, PURE_ASM_REWRITE_TAC, PURE_ONCE_ASM_REWRITE_TAC,
PURE_REWRITE_TAC, REWRITE_TAC.

\ENDDOC
\DOC{FILTER\_PURE\_ASM\_REWRITE\_RULE}

\TYPE {\small\verb%FILTER_PURE_ASM_REWRITE_RULE : ((term -> bool) -> thm list -> thm ->thm)%}\egroup

\SYNOPSIS
Rewrites a theorem with some of the theorem's assumptions.

\DESCRIBE
This function implements selective rewriting with a subset of the assumptions
of the theorem. The first argument (a predicate on terms) is applied to all
assumptions, and the ones which return {\small\verb%true%} are used to rewrite the goal.
See {\small\verb%GEN_REWRITE_RULE%} for more information on rewriting.

\FAILURE
{\small\verb%FILTER_PURE_ASM_REWRITE_RULE%} does not fail.
Using {\small\verb%FILTER_PURE_ASM_REWRITE_RULE%} may result in a diverging sequence of
rewrites. In such cases {\small\verb%FILTER_PURE_ONCE_ASM_REWRITE_RULE%} may be used.

\USES
This rule can be applied when rewriting with all assumptions results in
divergence. Typically, the predicate can model checks as to whether a certain
variable appears on the left-hand side of an equational assumption, or whether
the assumption is in disjunctive form.

Another use is to improve performance when there are many assumptions
which are not applicable. Rewriting, though a powerful method of
proving theorems in HOL, can result in a reduced performance due to
the pattern matching and the number of primitive inferences involved.

\SEEALSO
ASM_REWRITE_RULE, FILTER_ASM_REWRITE_RULE, FILTER_ONCE_ASM_REWRITE_RULE,
FILTER_PURE_ONCE_ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_REWRITE_RULE,
PURE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{FILTER\_PURE\_ASM\_REWRITE\_TAC}

\TYPE {\small\verb%FILTER_PURE_ASM_REWRITE_TAC : ((term -> bool) -> thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal with some of the goal's assumptions.

\DESCRIBE
This function implements selective rewriting with a subset of the assumptions
of the goal. The first argument (a predicate on terms) is applied to all
assumptions, and the ones which return {\small\verb%true%} are used to rewrite the goal.
See {\small\verb%GEN_REWRITE_TAC%} for more information on rewriting.

\FAILURE
{\small\verb%FILTER_PURE_ASM_REWRITE_TAC%} does not fail, but it can result in an invalid
tactic if the rewrite is invalid. This happens when a theorem used for
rewriting has assumptions which are not alpha-convertible to assumptions of
the goal. Using {\small\verb%FILTER_PURE_ASM_REWRITE_TAC%} may result in a diverging
sequence of rewrites. In such cases {\small\verb%FILTER_PURE_ONCE_ASM_REWRITE_TAC%} may be
used.

\USES
This tactic can be applied when rewriting with all assumptions results in
divergence, or in an unwanted proof state. Typically, the predicate can model
checks as to whether a certain variable appears on the left-hand side of an
equational assumption, or whether the assumption is in disjunctive form. Thus
it allows choice of assumptions to rewrite with in a position-independent
fashion.

Another use is to improve performance when there are many assumptions
which are not applicable. Rewriting, though a powerful method of
proving theorems in HOL, can result in a reduced performance due to
the pattern matching and the number of primitive inferences involved.

\SEEALSO
ASM_REWRITE_TAC, FILTER_ASM_REWRITE_TAC, FILTER_ONCE_ASM_REWRITE_TAC,
FILTER_PURE_ONCE_ASM_REWRITE_TAC, GEN_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_REWRITE_TAC, REWRITE_TAC.

\ENDDOC
\DOC{FILTER\_PURE\_ONCE\_ASM\_REWRITE\_RULE}

\TYPE {\small\verb%FILTER_PURE_ONCE_ASM_REWRITE_RULE : ((term -> bool) -> thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem once using some of its assumptions.

\DESCRIBE
The first argument is a predicate applied to the assumptions. The theorem is
rewritten with the assumptions for which the predicate returns {\small\verb%true%} and the
given list of theorems. It searches the term of the theorem once, without
applying rewrites recursively. Thus it avoids the divergence which can result
from the application of {\small\verb%FILTER_PURE_ASM_REWRITE_RULE%}. For more information
on rewriting rules, see {\small\verb%GEN_REWRITE_RULE%}.

\FAILURE
Never fails.

\USES
This function is useful when rewriting with a subset of assumptions of
a theorem, allowing control of the number of rewriting passes.

\SEEALSO
ASM_REWRITE_RULE, FILTER_ASM_REWRITE_RULE, FILTER_ONCE_ASM_REWRITE_RULE,
FILTER_PURE_ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_ASM_REWRITE_RULE,
ONCE_DEPTH_CONV, PURE_ASM_REWRITE_RULE, PURE_ONCE_ASM_REWRITE_RULE,
PURE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{FILTER\_PURE\_ONCE\_ASM\_REWRITE\_TAC}

\TYPE\egroup
{\small\verb%FILTER_PURE_ONCE_ASM_REWRITE_TAC : ((term -> bool) -> thm list -> tactic)%}

\SYNOPSIS
Rewrites a goal once using some of its assumptions.

\DESCRIBE
The first argument is a predicate applied to the assumptions. The goal is
rewritten with the assumptions for which the predicate returns {\small\verb%true%} and the
given list of theorems. It searches the term of the goal once, without
applying rewrites recursively. Thus it avoids the divergence which can result
from the application of {\small\verb%FILTER_PURE_ASM_REWRITE_TAC%}. For more information
on rewriting tactics, see {\small\verb%GEN_REWRITE_TAC%}.

\FAILURE
Never fails.

\USES
This function is useful when rewriting with a subset of assumptions of
a goal, allowing control of the number of rewriting passes.

\SEEALSO
ASM_REWRITE_TAC, FILTER_ASM_REWRITE_TAC, FILTER_ONCE_ASM_REWRITE_TAC,
FILTER_PURE_ASM_REWRITE_TAC, GEN_REWRITE_TAC, ONCE_ASM_REWRITE_TAC,
ONCE_DEPTH_CONV, PURE_ASM_REWRITE_TAC, PURE_ONCE_ASM_REWRITE_TAC,
PURE_REWRITE_TAC, REWRITE_TAC.

\ENDDOC
\DOC{FILTER\_STRIP\_TAC}

\TYPE {\small\verb%FILTER_STRIP_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Conditionally strips apart a goal by eliminating the outermost connective.

\DESCRIBE
Stripping apart a goal in a more careful way than is done by {\small\verb%STRIP_TAC%} may be
necessary when dealing with quantified terms and implications.
{\small\verb%FILTER_STRIP_TAC%} behaves like {\small\verb%STRIP_TAC%}, but it does not strip apart a goal
if it contains a given term.

If {\small\verb%u%} is a term, then {\small\verb%FILTER_STRIP_TAC u%} is a tactic that removes one
outermost occurrence of one of the connectives {\small\verb%!%}, {\small\verb%==>%}, {\small\verb%~%} or {\small\verb%/\%} from the
conclusion of the goal {\small\verb%t%}, provided the term being stripped does not contain
{\small\verb%u%}.  A negation {\small\verb%~t%} is treated as the implication {\small\verb%t ==> F%}.
{\small\verb%FILTER_STRIP_TAC u%} also breaks apart conjunctions without applying any
filtering.

If {\small\verb%t%} is a universally quantified term, {\small\verb%FILTER_STRIP_TAC u%}
strips off the quantifier:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- !x.v
   ================  FILTER_STRIP_TAC "u"       [where x is not u]
     A ?- v[x'/x]
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant that does not appear free in the
assumptions {\small\verb%A%}.  If {\small\verb%t%} is a conjunction, no filtering is done and
{\small\verb%FILTER_STRIP_TAC u%} simply splits the conjunction:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- v /\ w
   =================  FILTER_STRIP_TAC "u"
    A ?- v   A ?- w
\end{verbatim}
}
\noindent If {\small\verb%t%} is an implication and the antecedent does not contain
a free instance of {\small\verb%u%}, then {\small\verb%FILTER_STRIP_TAC u%} moves the antecedent into the
assumptions and recursively splits the antecedent according to the following
rules (see {\small\verb%STRIP_ASSUME_TAC%}):
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- v1 /\ ... /\ vn ==> v            A ?- v1 \/ ... \/ vn ==> v
   ============================        =================================
       A u {v1,...,vn} ?- v             A u {v1} ?- v ... A u {vn} ?- v

     A ?- ?x.w ==> v
   ====================
    A u {w[x'/x]} ?- v
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a variant of {\small\verb%x%}.

\FAILURE
{\small\verb%FILTER_STRIP_TAC u (A,t)%} fails if {\small\verb%t%} is not a universally quantified term,
an implication, a negation or a conjunction; or if the term being
stripped contains {\small\verb%u%} in the sense described above (conjunction excluded).

\EXAMPLE
When trying to solve the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- !n. m <= n /\ n <= m ==> (m = n)
\end{verbatim}
}
\noindent the universally quantified variable {\small\verb%n%} can be stripped off by using
{\par\samepage\setseps\small
\begin{verbatim}
   FILTER_STRIP_TAC "m:num"
\end{verbatim}
}
\noindent and then the implication can be stripped apart by using
{\par\samepage\setseps\small
\begin{verbatim}
   FILTER_STRIP_TAC "m:num = n"
\end{verbatim}
}
\USES
{\small\verb%FILTER_STRIP_TAC%} is used when stripping outer connectives from a goal in a
more delicate way than {\small\verb%STRIP_TAC%}. A typical application is to keep
stripping by using the tactic {\small\verb%REPEAT (FILTER_STRIP_TAC u)%}
until one hits the term {\small\verb%u%} at which stripping is to stop.

\SEEALSO
CONJ_TAC, FILTER_DISCH_TAC, FILTER_DISCH_THEN, FILTER_GEN_TAC,
STRIP_ASSUME_TAC, STRIP_TAC.

\ENDDOC
\DOC{FILTER\_STRIP\_THEN}

\TYPE {\small\verb%FILTER_STRIP_THEN : (thm_tactic -> term -> tactic)%}\egroup

\SYNOPSIS
Conditionally strips a goal, handing an antecedent to the theorem-tactic.

\DESCRIBE
Given a theorem-tactic {\small\verb%ttac%}, a term {\small\verb%u%} and a goal {\small\verb%(A,t)%},
{\small\verb%FILTER_STRIP_THEN ttac u%} removes one outer connective ({\small\verb%!%}, {\small\verb%==>%}, or {\small\verb%~%})
from {\small\verb%t%}, if the term being stripped does not contain a free instance of {\small\verb%u%}. A
negation {\small\verb%~t%} is treated as the implication {\small\verb%t ==> F%}. The theorem-tactic
{\small\verb%ttac%} is applied only when stripping an implication, by using the antecedent
stripped off. {\small\verb%FILTER_STRIP_THEN%} also breaks conjunctions.

{\small\verb%FILTER_STRIP_THEN%} behaves like {\small\verb%STRIP_GOAL_THEN%}, if the term being stripped
does not contain a free instance of {\small\verb%u%}. In particular, {\small\verb%FILTER_STRIP_THEN
STRIP_ASSUME_TAC%} behaves like {\small\verb%FILTER_STRIP_TAC%}.

\FAILURE
{\small\verb%FILTER_STRIP_THEN ttac u (A,t)%} fails if {\small\verb%t%} is not a universally
quantified term, an implication, a negation or a conjunction;
or if the term being stripped contains the term {\small\verb%u%} (conjunction excluded);
or if the application of {\small\verb%ttac%} fails, after stripping the goal.

\EXAMPLE
When solving the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (n = 1) ==> (n * n = n)
\end{verbatim}
}
\noindent the application of {\small\verb%FILTER_STRIP_THEN SUBST1_TAC "m:num"%}
results in the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- 1 * 1 = 1
\end{verbatim}
}
\USES
{\small\verb%FILTER_STRIP_THEN%} is used when manipulating intermediate results
using theorem-tactics, after stripping outer connectives
from a goal in a more delicate way than {\small\verb%STRIP_GOAL_THEN%}.

\SEEALSO
CONJ_TAC, FILTER_DISCH_TAC, FILTER_DISCH_THEN, FILTER_GEN_TAC,
FILTER_STRIP_TAC, STRIP_ASSUME_TAC, STRIP_GOAL_THEN.

\ENDDOC
\DOC{find}

\TYPE {\small\verb%find : ((* -> bool) -> * list -> *)%}\egroup

\SYNOPSIS
Returns the first element of a list which satisfies a predicate.

\DESCRIBE
{\small\verb%find p [x1;...;xn]%} returns the first {\small\verb%xi%} in the list such that {\small\verb%(p xi)%}
is {\small\verb%true%}.

\FAILURE
Fails with {\small\verb%find%} if no element satisfies the predicate. This will always be
the case if the list is empty.

\SEEALSO
tryfind, mem, exists, forall, assoc, rev_assoc.

\ENDDOC
\DOC{find\_file}

\TYPE {\small\verb%find_file: (string -> string)%}\egroup

\SYNOPSIS
Searches for a named file.

\DESCRIBE
Searches for a named file using the search path, and returns the full pathname
if successful (if the file is in the current directory, this will just be the
argument string).

\FAILURE
Fails if the named file cannot be found using the current search path.

\EXAMPLE
The answer from the following will depend on where HOL is installed:
{\par\samepage\setseps\small
\begin{verbatim}
   #find_file `combin.th`;;
   `/usr/groups/hol/HOL2/sun4_sos/theories/combin.th` : string
\end{verbatim}
}
\SEEALSO
find_ml_file, search_path, set_search_path

\ENDDOC
\DOC{find\_match}

\TYPE {\small\verb%find_match: (term -> term -> ((term # term) list # (type # type) list))%}\egroup

\SYNOPSIS
Determines whether a term matches a subterm of another term.

\DESCRIBE
Recursively destructs its second argument and attempts to match the resulting
subterms with the first term. It returns a list of differing instances of
free variables and types in the matched terms. The search is done in
a depth-first, left-to-right order.

\FAILURE
Fails if the none of the subterms of the second argument match the first.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#find_match "a:num" "a:num";;
([], []) : ((term # term) list # (type # type) list)

#find_match "a:*" "T";;
([("T", "a")], [(":bool", ":*")])
: ((term # term) list # (type # type) list)

#find_match "x:num" "n < 2 ==> (a /\ b)";;
([("n", "x")], []) : ((term # term) list # (type # type) list)

#find_match "x:bool" "n < 2 ==> (a /\ b)";;
([("n < 2 ==> a /\ b", "x")], [])
: ((term # term) list # (type # type) list)

#find_match "x /\ y" "1 < 2 ==> (a /\ b)";;
([("b", "y"); ("a", "x")], [])
: ((term # term) list # (type # type) list)
\end{verbatim}
}
\SEEALSO
match, find_term, find_terms

\ENDDOC
\DOC{find\_ml\_file}

\TYPE {\small\verb%find_ml_file: (string -> string)%}\egroup

\SYNOPSIS
Searches for a named {\small\verb%ML%} file.

\DESCRIBE
Given a {\small\verb%`.ml`%} suffixed string {\small\verb%`foo.ml`%}, {\small\verb%find_ml_file%} searches for the
{\small\verb%ML%} source file {\small\verb%foo.ml%}. If the given string does not have a {\small\verb%`.ml`%} suffix,
then {\small\verb%find_ml_file%} searches for the object file {\small\verb%foo_ml.o%} or the {\small\verb%ML%} source
file {\small\verb%foo.ml%}. If the object file exists, then its name is returned.
Otherwise, the name of the {\small\verb%ML%} source file is returned if it
exists.

\FAILURE
Fails if the appropriate file cannot be found using the current search path.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#find_ml_file `foo`;;
`foo_ml.o` : string

#find_ml_file `foo.ml`;;
`foo.ml` : string
\end{verbatim}
}
\USES
Typically used to determine whether an object file exists for a named {\small\verb%ML%}
source file.

\SEEALSO
find_file, search_path, set_search_path

\ENDDOC
\DOC{find\_term}

\TYPE {\small\verb%find_term: ((term -> bool) -> term -> term)%}\egroup

\SYNOPSIS
Searches a term for a subterm that satisfies a given predicate.

\DESCRIBE
The largest subterm, in a depth-first, left-to-right search
of the given term, that satisfies the predicate is returned.

\FAILURE
Fails if no subterm of the given term satisfies the predicate.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#find_term is_pred "SUC 0";;
"SUC 0" : term

#find_term is_const "SUC 0";;
"SUC" : term

#find_term is_var "SUC n";;
"n" : term
\end{verbatim}
}
\SEEALSO
find_terms

\ENDDOC
\DOC{find\_terms}

\TYPE {\small\verb%find_terms : ((term -> bool) -> term -> term list)%}\egroup

\SYNOPSIS
Searches a term for all subterms that satisfy a predicate.

\DESCRIBE
A list of subterms of a given term that satisfy the predicate is returned. The
terms may not be disjoint.

\FAILURE
Fails if no subterm of the given term satisfies the predicate.

\EXAMPLE
The following shows that the terms returned may overlap or contain each other:
{\par\samepage\setseps\small
\begin{verbatim}
   #find_terms (\tm. rator tm = "SUC" ? false) "SUC(SUC 1 + SUC 2)";;
   ["SUC 2"; "SUC 1"; "SUC((SUC 1) + (SUC 2))"] : term list
\end{verbatim}
}
\SEEALSO
find_term.

\ENDDOC
\DOC{find\_theory}

\TYPE {\small\verb%find_theory : (string -> string)%}\egroup

\SYNOPSIS
Attempts to find a named theory.

\DESCRIBE
Given a string {\small\verb%`foo`%}, {\small\verb%find_theory%} attempts to find the theory file
{\small\verb%`foo.th`%} using the current search path. If it succeeds, it returns a full
pathname (possibly a relative pathname identical to the argument string).

\FAILURE
Fails if the named theory file cannot be found using the current search path.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#find_theory `num`;;
`/usr/groups/hol/HOL2/sun4_sos/theories/num.th` : string
\end{verbatim}
}
\SEEALSO
find_file, find_ml_file, search_path, set_search_path.

\ENDDOC
\DOC{FIRST\_ASSUM}

\TYPE {\small\verb%FIRST_ASSUM : (thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Maps a theorem-tactic over the assumptions, applying first successful tactic.

\DESCRIBE
The tactic
{\par\samepage\setseps\small
\begin{verbatim}
   FIRST_ASSUM ttac ([A1; ...; An], g)
\end{verbatim}
}
\noindent has the effect of applying the first tactic which can be produced by
{\small\verb%ttac%} from the {\small\verb%ASSUME%}d assumptions {\small\verb%(A1 |- A1)%}, ..., {\small\verb%(An |- An)%} and which
succeeds when applied to the goal. Failures of {\small\verb%ttac%} to produce a tactic are
ignored.

\FAILURE
Fails if {\small\verb%ttac (Ai |- Ai)%} fails for every assumption {\small\verb%Ai%}, or if the
assumption list is empty, or if all the tactics produced by {\small\verb%ttac%} fail when
applied to the goal.

\EXAMPLE
The tactic
{\par\samepage\setseps\small
\begin{verbatim}
   FIRST_ASSUM (\asm. CONTR_TAC asm  ORELSE  ACCEPT_TAC asm)
\end{verbatim}
}
\noindent searches the assumptions for either a contradiction or the desired
conclusion. The tactic
{\par\samepage\setseps\small
\begin{verbatim}
   FIRST_ASSUM MATCH_MP_TAC
\end{verbatim}
}
\noindent searches the assumption list for an implication whose conclusion
matches the goal, reducing the goal to the antecedent of the corresponding
instance of this implication.

\SEEALSO
ASSUM_LIST, EVERY, EVERY_ASSUM, FIRST, MAP_EVERY, MAP_FIRST.

\ENDDOC
\DOC{FIRST\_CONV}

\TYPE {\small\verb%FIRST_CONV : (conv list -> conv)%}\egroup

\SYNOPSIS
Apply the first of the conversions in a given list that succeeds.

\DESCRIBE
{\small\verb%FIRST_CONV [c1;...;cn] "t"%} returns the result of applying to the term {\small\verb%"t"%}
the first conversion {\small\verb%ci%} that succeeds when applied to {\small\verb%"t"%}.  The conversions
are tried in the order in which they are given in the list.

\FAILURE
{\small\verb%FIRST_CONV [c1;...;cn] "t"%} fails if all the conversions {\small\verb%c1%}, ..., {\small\verb%cn%} fail
when applied to the term {\small\verb%"t"%}.  {\small\verb%FIRST_CONV cs "t"%} also fails if {\small\verb%cs%} is the
empty list.

\SEEALSO
ORELSEC.

\ENDDOC
\DOC{FIRST}

\TYPE {\small\verb%FIRST : (tactic list -> tactic)%}\egroup

\SYNOPSIS
Applies the first tactic in a tactic list which succeeds.

\DESCRIBE
When applied to a list of tactics {\small\verb%[T1;...;Tn]%}, and a goal {\small\verb%g%}, the tactical
{\small\verb%FIRST%} tries applying the tactics to the goal until one succeeds. If the
first tactic which succeeds is {\small\verb%Tm%}, then the effect is the same as just {\small\verb%Tm%}.
Thus {\small\verb%FIRST%} effectively behaves as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   FIRST [T1;...;Tn] = T1 ORELSE ... ORELSE Tn
\end{verbatim}
}
\FAILURE
The application of {\small\verb%FIRST%} to a tactic list never fails. The resulting
tactic fails iff all the component tactics do when applied to the goal,
or if the tactic list is empty.

\SEEALSO
EVERY, ORELSE.

\ENDDOC
\DOC{FIRSTN\_CONV}

\TYPE {\small\verb%FIRSTN_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of taking the initial n elements of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...x(n-k);...;x(n-1)]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   FIRSTN_CONV "FIRSTN k [x0;...x(n-k);...;x(n-1)]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- FIRSTN k [x0;...;x(n-k);...;x(n-1)] = [x0;...;x(n-k)]
\end{verbatim}
}


\FAILURE
{\small\verb%FIRSTN_CONV tm%} fails if {\small\verb%tm%} is not of the form described above, 
or {\small\verb%k%} is greater than the length of the list.

\ENDDOC

\DOC{FIRST\_TCL}

\TYPE {\small\verb%FIRST_TCL : (thm_tactical list -> thm_tactical)%}\egroup

\SYNOPSIS
Applies the first theorem-tactical in a list which succeeds.

\DESCRIBE
When applied to a list of theorem-tacticals, a theorem-tactic and a theorem,
{\small\verb%FIRST_TCL%} returns the tactic resulting from the application of the first
theorem-tactical to the theorem-tactic and theorem which succeeds. The effect
is the same as:
{\par\samepage\setseps\small
\begin{verbatim}
   FIRST_TCL [ttl1;...;ttln] = ttl1 ORELSE_TCL ... ORELSE_TCL ttln
\end{verbatim}
}
\FAILURE
{\small\verb%FIRST_TCL%} fails iff each tactic in the list fails when applied to the
theorem-tactic and theorem. This is trivially the case if the list is empty.

\SEEALSO
EVERY_TCL, ORELSE_TCL, REPEAT_TCL, THEN_TCL.

\ENDDOC
\DOC{flags}

\TYPE {\small\verb%flags : (void -> string list)%}\egroup

\SYNOPSIS
Returns a list of settable system flags.

\DESCRIBE
Given the {\small\verb%void%} argument {\small\verb%()%}, {\small\verb%flags%} returns a list of settable system
flags. The default values of these flags can be altered by {\small\verb%set_flag%}.

\COMMENTS
A full explanation of the standard flags is given in the DESCRIPTION.

\SEEALSO
set_flag.

\ENDDOC
\DOC{FLAT\_CONV}

\TYPE {\small\verb%FLAT_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of flattening a list of lists.

\DESCRIBE
{\small\verb%FLAT_CONV%} a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   FLAT [[x00;...x0n]; ...; [xm0;...xmn]]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- FLAT  [[x00;...x0n]; ...; [xm0;...xmn]] =
	[x00;...x0n; ...; xm0;...xmn]
\end{verbatim}
}


\FAILURE
{\small\verb%FLAT_CONV tm%} fails if {\small\verb%tm%} is not of the form described above.

\EXAMPLE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   FLAT_CONV "FLAT [[0;2;4];[0;1;2;3;4]]";;
\end{verbatim}
}
\noindent returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- FLAT[[0;2;4];[0;1;2;3;4]] = [0;2;4;0;1;2;3;4]
\end{verbatim}
}

\SEEALSO
FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{flat}

\TYPE {\small\verb%flat : (* list list -> * list)%}\egroup

\SYNOPSIS
Flattens a list of lists into one long list.

\DESCRIBE
{\small\verb%flat [l1;...;ln]%} returns {\small\verb%(l1 @ ... @ ln)%} where each li is a list and {\small\verb%@%}
is list concatenation.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#flat [[1;2];[3;4;5];[6]];;
[1; 2; 3; 4; 5; 6] : int list
\end{verbatim}
}
\ENDDOC
\DOC{FOLDL\_CONV}

\TYPE {\small\verb%FOLDL_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a function to elements of a list.

\DESCRIBE
{\small\verb%FOLDL_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   FOLDL f e [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- FOLDL f e [x0;...xn] = tm'
\end{verbatim}
}
\noindent where {\small\verb%tm'%} is the result of applying the function {\small\verb%f%} iteratively to
the successive elements of the list and the result of the previous
application starting from the tail end of the list. During each
iteration, an expression {\small\verb%f ei xi%} is evaluated. The user supplied
conversion {\small\verb%conv%} is used to derive a theorem 
{\par\samepage\setseps\small
\begin{verbatim}
   |- f ei xi = e(i+1)
\end{verbatim}
}
\noindent which is used in the next iteration.

\FAILURE
{\small\verb%FOLDL_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above.

\EXAMPLE
To sum the elements of a list, one can evaluate
{\par\samepage\setseps\small
\begin{verbatim}
   FOLDL_CONV ADD_CONV "FOLDL $+ 0 [0;1;2;3]";;
\end{verbatim}
}
\noindent which returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- FOLDL $+ 0[0;1;2;3] = 6
\end{verbatim}
}
\noindent In general, if the function {\small\verb%f%} is an explicit lambda abstraction
{\small\verb%(\x x'. t[x,x'])%}, the conversion should be in the form
{\par\samepage\setseps\small
\begin{verbatim}
   ((RATOR_CONV BETA_CONV) THENC BETA_CONV THENC conv'))
\end{verbatim}
}
\noindent  where {\small\verb%conv'%} applied to {\small\verb%t[x,x']%} returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |-t[x,x'] = e''.
\end{verbatim}
}

\SEEALSO
FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{FOLDR\_CONV}

\TYPE {\small\verb%FOLDR_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a function to elements of a list.

\DESCRIBE
{\small\verb%FOLDR_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   FOLDR f e [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- FOLDR f e [x0;...xn] = tm'
\end{verbatim}
}
\noindent where {\small\verb%tm'%} is the result of applying the function {\small\verb%f%} iteratively to
the successive elements of the list and the result of the previous
application starting from the tail end of the list. During each
iteration, an expression {\small\verb%f xi ei%} is evaluated. The user supplied
conversion {\small\verb%conv%} is used to derive a theorem 
{\par\samepage\setseps\small
\begin{verbatim}
   |- f xi ei = e(i+1)
\end{verbatim}
}
\noindent which is used in the next iteration.

\FAILURE
{\small\verb%FOLDR_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above.

\EXAMPLE
To sum the elements of a list, one can evaluate
{\par\samepage\setseps\small
\begin{verbatim}
   FOLDR_CONV ADD_CONV "FOLDR $+ 0 [0;1;2;3]";;
\end{verbatim}
}
\noindent which returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- FOLDR $+ 0[0;1;2;3] = 6
\end{verbatim}
}
\noindent In general, if the function {\small\verb%f%} is an explicit lambda abstraction
{\small\verb%(\x x'. t[x,x'])%}, the conversion should be in the form
{\par\samepage\setseps\small
\begin{verbatim}
   ((RATOR_CONV BETA_CONV) THENC BETA_CONV THENC conv'))
\end{verbatim}
}
\noindent  where {\small\verb%conv'%} applied to {\small\verb%t[x,x']%} returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |-t[x,x'] = e''.
\end{verbatim}
}

\SEEALSO
FOLDL_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{FORALL\_AND\_CONV}

\TYPE {\small\verb%FORALL_AND_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification inwards through a conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%!x. P /\ Q%}, the conversion
{\small\verb%FORALL_AND_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P /\ Q) = (!x.P) /\ (!x.Q)
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%!x. P /\ Q%}.

\SEEALSO
AND_FORALL_CONV, LEFT_AND_FORALL_CONV, RIGHT_AND_FORALL_CONV.

\ENDDOC
\DOC{forall}

\TYPE {\small\verb%forall : ((* -> bool) -> * list -> bool)%}\egroup

\SYNOPSIS
Tests a list to see if all its elements satisfy a predicate.

\DESCRIBE
{\small\verb%forall p [x1;...;xn]%} returns {\small\verb%true%} if {\small\verb%(p xi)%} is true for all {\small\verb%xi%} in the
list. Otherwise it returns {\small\verb%false%}. If the list is empty, this function always
returns true.

\FAILURE
Never fails.

\SEEALSO
exists, find, tryfind, mem, assoc, rev_assoc.

\ENDDOC
\DOC{FORALL\_EQ}

\TYPE {\small\verb%FORALL_EQ : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Universally quantifies both sides of an equational theorem.

\DESCRIBE
When applied to a variable {\small\verb%x%} and a theorem {\small\verb%A |- t1 = t2%}, whose conclusion
is an equation between boolean terms, {\small\verb%FORALL_EQ%} returns the
theorem {\small\verb%A |- (!x. t1) = (!x. t2)%}, unless the variable {\small\verb%x%} is free in any
of the assumptions.
{\par\samepage\setseps\small
\begin{verbatim}
         A |- t1 = t2
   ------------------------  FORALL_EQ "x"      [where x is not free in A]
    A |- (!x.t1) = (!x.t2)
\end{verbatim}
}
\FAILURE
Fails if the theorem is not an equation between boolean terms, or if the
supplied term is not simply a variable, or if the variable is free in any of
the assumptions.

\SEEALSO
AP_TERM, EXISTS_EQ, SELECT_EQ.

\ENDDOC
\DOC{FORALL\_IMP\_CONV}

\TYPE {\small\verb%FORALL_IMP_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification inwards through an implication.

\DESCRIBE
When applied to a term of the form {\small\verb%!x. P ==> Q%}, where {\small\verb%x%} is not free in
both {\small\verb%P%} and {\small\verb%Q%}, {\small\verb%FORALL_IMP_CONV%} returns a theorem of one of three forms,
depending on occurrences of the variable {\small\verb%x%} in {\small\verb%P%} and {\small\verb%Q%}.  If {\small\verb%x%} is free
in {\small\verb%P%} but not in {\small\verb%Q%}, then the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P ==> Q) = (?x.P) ==> Q
\end{verbatim}
}
\noindent is returned.  If {\small\verb%x%} is free in {\small\verb%Q%} but not in {\small\verb%P%}, then the
result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P ==> Q) = P ==> (!x.Q)
\end{verbatim}
}
\noindent And if {\small\verb%x%} is free in neither {\small\verb%P%} nor {\small\verb%Q%}, then the result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P ==> Q) = (?x.P) ==> (!x.Q)
\end{verbatim}
}
\FAILURE
{\small\verb%FORALL_IMP_CONV%} fails if it is applied to a term not of the form
{\small\verb%!x. P ==> Q%}, or if it is applied to a term {\small\verb%!x. P ==> Q%} in which the
variable {\small\verb%x%} is free in both {\small\verb%P%} and {\small\verb%Q%}.

\SEEALSO
LEFT_IMP_EXISTS_CONV, RIGHT_IMP_FORALL_CONV.

\ENDDOC
\DOC{FORALL\_NOT\_CONV}

\TYPE {\small\verb%FORALL_NOT_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification inwards through a negation.

\DESCRIBE
When applied to a term of the form {\small\verb%!x.~P%}, the conversion {\small\verb%FORALL_NOT_CONV%}
returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x.~P) = ~(?x. P)
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%!x.~P%}.

\SEEALSO
EXISTS_NOT_CONV, NOT_EXISTS_CONV, NOT_FORALL_CONV.

\ENDDOC
\DOC{FORALL\_OR\_CONV}

\TYPE {\small\verb%FORALL_OR_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification inwards through a disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%!x. P \/ Q%}, where {\small\verb%x%} is not free in both
{\small\verb%P%} and {\small\verb%Q%}, {\small\verb%FORALL_OR_CONV%} returns a theorem of one of three forms,
depending on occurrences of the variable {\small\verb%x%} in {\small\verb%P%} and {\small\verb%Q%}.  If {\small\verb%x%} is free
in {\small\verb%P%} but not in {\small\verb%Q%}, then the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P \/ Q) = (!x.P) \/ Q
\end{verbatim}
}
\noindent is returned.  If {\small\verb%x%} is free in {\small\verb%Q%} but not in {\small\verb%P%}, then the
result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P \/ Q) = P \/ (!x.Q)
\end{verbatim}
}
\noindent And if {\small\verb%x%} is free in neither {\small\verb%P%} nor {\small\verb%Q%}, then the result is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P \/ Q) = (!x.P) \/ (!x.Q)
\end{verbatim}
}
\FAILURE
{\small\verb%FORALL_OR_CONV%} fails if it is applied to a term not of the form
{\small\verb%!x. P \/ Q%}, or if it is applied to a term {\small\verb%!x. P \/ Q%} in which the
variable {\small\verb%x%} is free in both {\small\verb%P%} and {\small\verb%Q%}.

\SEEALSO
OR_FORALL_CONV, LEFT_OR_FORALL_CONV, RIGHT_OR_FORALL_CONV.

\ENDDOC
\DOC{free\_in}

\TYPE {\small\verb%free_in : (term -> term -> bool)%}\egroup

\SYNOPSIS
Tests if one term is free in another.

\DESCRIBE
When applied to two terms {\small\verb%t1%} and {\small\verb%t2%}, the function {\small\verb%free_in%} returns
{\small\verb%true%} if {\small\verb%t1%} is free in {\small\verb%t2%}, and {\small\verb%false%} otherwise. It is not necessary
that {\small\verb%t1%} be simply a variable.

\FAILURE
Never fails.

\EXAMPLE
In the following example {\small\verb%free_in%} returns {\small\verb%false%} because the {\small\verb%x%} in {\small\verb%SUC x%}
in the second term is bound:
{\par\samepage\setseps\small
\begin{verbatim}
   #free_in "SUC x" "!x. SUC x = x + 1";;
   false : bool
\end{verbatim}
}
\noindent whereas the following call returns {\small\verb%true%} because the first instance
of {\small\verb%x%} in the second term is free, even though there is also a bound instance:
{\par\samepage\setseps\small
\begin{verbatim}
   #free_in "x:bool" "x /\ (?x. x=T)";;
   true : bool
\end{verbatim}
}
\SEEALSO
frees, freesl, thm_frees.

\ENDDOC
\DOC{frees}

\TYPE {\small\verb%frees : (term -> term list)%}\egroup

\SYNOPSIS
Returns a list of the variables which are free in a term.

\DESCRIBE
When applied to a term, {\small\verb%frees%} returns a list of the free variables in
that term. There are no repetitions in the list produced even if there are
multiple free instances of some variables.

\FAILURE
Never fails.

\EXAMPLE
Clearly in the following term, {\small\verb%x%} and {\small\verb%y%} are free, whereas {\small\verb%z%} is bound:
{\par\samepage\setseps\small
\begin{verbatim}
   #frees "(x=1) /\ (y=2) /\ (!z. z >= 0)";;
   ["x"; "y"] : term list
\end{verbatim}
}
\SEEALSO
freesl, free_in, thm_frees.

\ENDDOC
\DOC{freesl}

\TYPE {\small\verb%freesl : (term list -> term list)%}\egroup

\SYNOPSIS
Returns a list of the free variables in a list of terms.

\DESCRIBE
When applied to a list of terms, {\small\verb%freesl%} returns a list of the variables which
are free in any of those terms. There are no repetitions in the list produced
even if several terms contain the same free variable.

\FAILURE
Never fails.

\EXAMPLE
In the following example there are two free instances each of {\small\verb%x%} and {\small\verb%y%},
whereas the only instances of {\small\verb%z%} are bound:
{\par\samepage\setseps\small
\begin{verbatim}
   #freesl ["x+y=2"; "!z. z >= (x-y)"];;
   ["x"; "y"] : term list
\end{verbatim}
}
\SEEALSO
frees, free_in, thm_frees.

\ENDDOC
\DOC{FREEZE\_THEN}

\TYPE {\small\verb%FREEZE_THEN : thm_tactical%}\egroup

\SYNOPSIS
`Freezes' a theorem to prevent instantiation of its free variables.

\DESCRIBE
{\small\verb%FREEZE_THEN%} expects a tactic-generating function {\small\verb%f:thm->tactic%}
and a theorem {\small\verb%(A1 |- w)%} as arguments.  The tactic-generating function {\small\verb%f%}
is applied to the theorem {\small\verb%(w |- w)%}.  If this tactic generates the subgoal:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   =========  f (w |- w)
    A ?- t1
\end{verbatim}
}
\noindent then applying {\small\verb%FREEZE_THEN f (A1 |- w)%}
to the goal {\small\verb%(A ?- t)%} produces the subgoal:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   =========  FREEZE_THEN f (A1 |- w)
    A ?- t1
\end{verbatim}
}
\noindent Since the term {\small\verb%w%} is a hypothesis of the argument to the
function {\small\verb%f%}, none of the free variables present in {\small\verb%w%} may be
instantiated or generalized.  The hypothesis is discharged by
{\small\verb%PROVE_HYP%} upon the completion of the proof of the subgoal.

\FAILURE
Failures may arise from the tactic-generating function.  An invalid
tactic arises if the hypotheses of the theorem are not
alpha-convertible to assumptions of the goal.

\EXAMPLE
Given the goal {\small\verb%([ "b < c"; "a < b" ], "(SUC a) <= c")%}, and the
specialized variant of the theorem {\small\verb%LESS_TRANS%}:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- !p. a < b /\ b < p ==> a < p
\end{verbatim}
}
\noindent {\small\verb%IMP_RES_TAC th%} will generate several unneeded assumptions:
{\par\samepage\setseps\small
\begin{verbatim}
   {b < c, a < b, a < c, !p. c < p ==> b < p, !a'. a' < a ==> a' < b}
       ?- (SUC a) <= c
\end{verbatim}
}
\noindent which can be avoided by first `freezing' the theorem, using
the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   FREEZE_THEN IMP_RES_TAC th
\end{verbatim}
}
\noindent This prevents the variables {\small\verb%a%} and {\small\verb%b%} from being instantiated.
{\par\samepage\setseps\small
\begin{verbatim}
   {b < c, a < b, a < c} ?- (SUC a) <= c
\end{verbatim}
}
\USES
Used in serious proof hacking to limit the matches achievable by
resolution and rewriting.

\SEEALSO
ASSUME, IMP_RES_TAC, PROVE_HYP, RES_TAC, REWR_CONV.

\ENDDOC
\DOC{FRONT\_CONJ\_CONV}

\TYPE {\small\verb%FRONT_CONJ_CONV: (term list -> term -> thm)%}\egroup

\SYNOPSIS
Moves a specified conjunct to the beginning of a conjunction.

\DESCRIBE
Given a list of boolean terms {\small\verb%[t1;...;t;...;tn]%} and a term {\small\verb%t%} which occurs
in the list, {\small\verb%FRONT_CONJ_CONV%} returns:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t1 /\ ... /\ t /\ ... /\ tn) = (t /\ t1 /\ ... /\ tn)
\end{verbatim}
}
\noindent That is, {\small\verb%FRONT_CONJ_CONV%} proves that {\small\verb%t%} can be moved to the
`front' of a conjunction of several terms.

\FAILURE
{\small\verb%FRONT_CONJ_CONV ["t1";...;"tn"] "t"%} fails if {\small\verb%t%} does not occur in the list
{\small\verb%[t1,...,tn]%} or if any of {\small\verb%t1%}, ..., {\small\verb%tn%} do not have type {\small\verb%bool%}.

\COMMENTS
This is not a true conversion, so perhaps it ought to be called something else.
The system shows its type as {\small\verb%(term list -> conv)%}.

\ENDDOC
\DOC{fst}

\TYPE {\small\verb%fst : ((* # **) -> *)%}\egroup

\SYNOPSIS
Extracts the first component of a pair.

\DESCRIBE
{\small\verb%fst (x,y)%} returns {\small\verb%x%}.

\FAILURE
Never fails.

\SEEALSO
snd, pair.

\ENDDOC
\DOC{FUN\_EQ\_CONV}

\TYPE {\small\verb%FUN_EQ_CONV : conv%}\egroup

\SYNOPSIS
Equates normal and extensional equality for two functions.

\DESCRIBE
The conversion {\small\verb%FUN_EQ_CONV%} embodies the fact that two functions are equal
precisely when they give the same results for all values to which they can be
applied. When supplied with a term argument of the form {\small\verb%f = g%}, where {\small\verb%f%} and
{\small\verb%g%} are functions of type {\small\verb%ty1->ty2%}, {\small\verb%FUN_EQ_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (f = g) = (!x. f x = g x)
\end{verbatim}
}
\noindent where {\small\verb%x%} is a variable of type {\small\verb%ty1%} chosen by the conversion.

\FAILURE
{\small\verb%FUN_EQ_CONV tm%} fails if {\small\verb%tm%} is not an equation {\small\verb%f = g%}, where {\small\verb%f%} and {\small\verb%g%}
are functions.

\USES
Used for proving equality of functions.

\SEEALSO
EXT, X_FUN_EQ_CONV.

\ENDDOC
\DOC{funpow}

\TYPE {\small\verb%funpow : (int -> (* -> *) -> * -> *)%}\egroup

\SYNOPSIS
Iterates a function a fixed number of times.

\DESCRIBE
{\small\verb%funpow n f x%} applies {\small\verb%f%} to {\small\verb%x%}, {\small\verb%n%} times, giving the result {\small\verb%f (f ... (f
x)...)%} where the number of {\small\verb%f%}'s is {\small\verb%n%}. {\small\verb%funpow 0 f x%} returns {\small\verb%x%}. If {\small\verb%n%} is
negative, {\small\verb%funpow n f x%} will either fail or loop indefinitely, depending on
the values of {\small\verb%f%} and {\small\verb%x%}.

\FAILURE
{\small\verb%funpow n f x%} fails if any of the {\small\verb%n%} applications of f fail.

\EXAMPLE
Apply {\small\verb%tl%} three times to a list:
{\par\samepage\setseps\small
\begin{verbatim}
   #funpow 3 tl [1;2;3;4;5];;
   [4; 5] : int list
\end{verbatim}
}
\noindent Apply {\small\verb%tl%} zero times:
{\par\samepage\setseps\small
\begin{verbatim}
   #funpow 0 tl [1;2;3;4;5];;
   [1; 2; 3; 4; 5] : int list
\end{verbatim}
}
\noindent Apply {\small\verb%tl%} six times to a list of only five elements:
{\par\samepage\setseps\small
\begin{verbatim}
   #funpow 6 tl [1;2;3;4;5];;
   evaluation failed     tl
\end{verbatim}
}
\noindent Next, an application of {\small\verb%funpow%} in which the integer argument is
negative. Since the function cannot be applied to the argument an arbitrary
number of times, the application of {\small\verb%funpow%} fails.
{\par\samepage\setseps\small
\begin{verbatim}
   #funpow (-1) tl [1;2;3;4;5];;
   evaluation failed     tl
\end{verbatim}
}
\noindent An example that causes indefinite looping:
{\par\samepage\setseps\small
\begin{verbatim}
   #funpow (-1) I [1;2;3;4;5];;
\end{verbatim}
}
\ENDDOC
\DOC{g}

\TYPE {\small\verb%g : (term -> void)%}\egroup

\SYNOPSIS
Initializes the subgoal package with a new goal which has no assumptions.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   g "tm"
\end{verbatim}
}
\noindent is equivalent to
{\par\samepage\setseps\small
\begin{verbatim}
   set_goal([],"tm")
\end{verbatim}
}
\noindent and clearly more convenient if a goal has no assumptions.
For a description of the subgoal package, see  {\small\verb%set_goal%}.

\FAILURE
Fails unless the argument term has type {\small\verb%bool%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])";;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

() : void
\end{verbatim}
}
\SEEALSO
b, backup, backup_limit, e, expand, expandf, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{GEN\_ALL}

\TYPE {\small\verb%GEN_ALL : (thm -> thm)%}\egroup

\SYNOPSIS
Generalizes the conclusion of a theorem over its own free variables.

\DESCRIBE
When applied to a theorem {\small\verb%A |- t%}, the inference rule {\small\verb%GEN_ALL%} returns
the theorem {\small\verb%A |- !x1...xn. t%}, where the {\small\verb%xi%} are all the variables,
if any, which are free in {\small\verb%t%} but not in the assumptions.
{\par\samepage\setseps\small
\begin{verbatim}
         A |- t
   ------------------  GEN_ALL
    A |- !x1...xn. t
\end{verbatim}
}
\FAILURE
Never fails.

\SEEALSO
GEN, GENL, GEN_ALL, SPEC, SPECL, SPEC_ALL, SPEC_TAC.

\ENDDOC
\DOC{GEN\_ALPHA\_CONV}

\TYPE {\small\verb%GEN_ALPHA_CONV : (term -> conv)%}\egroup

\SYNOPSIS
Renames the bound variable of an abstraction, a quantified term, or other
binder application.

\DESCRIBE
The conversion {\small\verb%GEN_ALPHA_CONV%} provides alpha conversion for lambda
abstractions of the form {\small\verb%"\y.t"%}, quantified terms of the forms {\small\verb%"!y.t"%},
{\small\verb%"?y.t"%} or {\small\verb%"?!y.t"%}, and epsilon terms of the form {\small\verb%"@y.t"%}.  In general,
if {\small\verb%B%} is a binder constant, then {\small\verb%GEN_ALPHA_CONV%} implements alpha
conversion for applications of the form {\small\verb%"B y.t"%}.  The function {\small\verb%is_binder%}
determines what is regarded as a binder in this context.

If {\small\verb%tm%} is an abstraction {\small\verb%"\y.t"%} or an application of a binder to
an abstraction {\small\verb%"B y.t"%}, where the bound variable {\small\verb%y%} has type {\small\verb%":ty"%},
and if {\small\verb%"x"%} is a variable also of type {\small\verb%:ty%}, then {\small\verb%GEN_ALPHA_CONV "x" tm%}
returns one of the theorems:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\y.t)  = (\x'. t[x'/y])   
   |- (B y.t)  = (!x'. t[x'/y])
\end{verbatim}
}
\noindent depending on whether the input term is {\small\verb%"\y.t"%} or {\small\verb%"B y.t"%}
respectively.  The variable {\small\verb%x':ty%} in the resulting theorem is a primed
variant of {\small\verb%x%} chosen so as not to be free in the term provided as the second
argument to {\small\verb%GEN_ALPHA_CONV%}.

\FAILURE
{\small\verb%GEN_ALPHA_CONV x tm%} fails if {\small\verb%x%} is not a variable, or if {\small\verb%tm%} does not have
one of the forms {\small\verb%"\y.t"%} or {\small\verb%"B y.t"%}, where {\small\verb%B%} is a binder (that is,
{\small\verb%is_binder `B`%} returns {\small\verb%true%}). {\small\verb%GEN_ALPHA_CONV x tm%} also fails if {\small\verb%tm%}
does have one of these forms, but types of the variables {\small\verb%x%} and {\small\verb%y%} differ.

\SEEALSO
ALPHA, ALPHA_CONV, is_binder.

\ENDDOC
\DOC{GEN\_BETA\_CONV}

\TYPE {\small\verb%GEN_BETA_CONV : conv%}\egroup

\SYNOPSIS
Beta-reduces single or paired beta-redexes, creating a paired argument if
needed.

\DESCRIBE
The conversion {\small\verb%GEN_BETA_CONV%} will perform beta-reduction of simple
beta-redexes in the manner of {\small\verb%BETA_CONV%}, or of tupled beta-redexes in the
manner of {\small\verb%PAIRED_BETA_CONV%}. Unlike the latter, it will force through a
beta-reduction by introducing arbitrarily nested pair destructors if necessary.
The following shows the action for one level of pairing; others are similar.
{\par\samepage\setseps\small
\begin{verbatim}
   GEN_BETA_CONV "(\(x,y). t) p" = t[(FST p)/x, (SND p)/y]
\end{verbatim}
}

\FAILURE
{\small\verb%GEN_BETA_CONV tm%} fails if {\small\verb%tm%} is neither a simple nor a tupled beta-redex.

\EXAMPLE
The following examples show the action of {\small\verb%GEN_BETA_CONV%} on tupled redexes. In
the following, it acts in the same way as {\small\verb%PAIRED_BETA_CONV%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #GEN_BETA_CONV "(\(x,y). x + y) (1,2)";;
   |- (\(x,y). x + y)(1,2) = 1 + 2
\end{verbatim}
}
\noindent whereas in the following, the operand of the beta-redex is not a
pair, so {\small\verb%FST%} and {\small\verb%SND%} are introduced:
{\par\samepage\setseps\small
\begin{verbatim}
   #GEN_BETA_CONV "(\(x,y). x + y) numpair";;
   |- (\(x,y). x + y)numpair = (FST numpair) + (SND numpair)
\end{verbatim}
}
\noindent The introduction of {\small\verb%FST%} and {\small\verb%SND%} will be done more than once as
necessary:
{\par\samepage\setseps\small
\begin{verbatim}
   #GEN_BETA_CONV "(\(w,x,y,z). w + x + y + z) (1,triple)";;
   |- (\(w,x,y,z). w + (x + (y + z)))(1,triple) =
      1 + ((FST triple) + ((FST(SND triple)) + (SND(SND triple))))
\end{verbatim}
}
\SEEALSO
BETA_CONV, PAIRED_BETA_CONV.

\ENDDOC
\DOC{GEN}

\TYPE {\small\verb%GEN : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Generalizes the conclusion of a theorem.

\DESCRIBE
When applied to a term {\small\verb%x%} and a theorem {\small\verb%A |- t%}, the inference rule
{\small\verb%GEN%} returns the theorem {\small\verb%A |- !x. t%}, provided {\small\verb%x%} is a variable not
free in any of the assumptions. There is no compulsion that {\small\verb%x%} should
be free in {\small\verb%t%}.
{\par\samepage\setseps\small
\begin{verbatim}
      A |- t
   ------------  GEN "x"                [where x is not free in A]
    A |- !x. t
\end{verbatim}
}
\FAILURE
Fails if {\small\verb%x%} is not a variable, or if it is free in any of the assumptions.

\EXAMPLE
The following example shows how the above side-condition prevents
the derivation of the theorem {\small\verb%x=T |- !x. x=T%}, which is clearly invalid.
{\par\samepage\setseps\small
\begin{verbatim}
   #top_print print_all_thm;;
   - : (thm -> void)

   #let t = ASSUME "x=T";;
   t = x = T |- x = T

   #GEN "x:bool" t;;
   evaluation failed     GEN
\end{verbatim}
}
\SEEALSO
GENL, GEN_ALL, GEN_TAC, SPEC, SPECL, SPEC_ALL, SPEC_TAC.

\ENDDOC
\DOC{GENL}

\TYPE {\small\verb%GENL : (term list -> thm -> thm)%}\egroup

\SYNOPSIS
Generalizes zero or more variables in the conclusion of a theorem.

\DESCRIBE
When applied to a term list {\small\verb%[x1;...;xn]%} and a theorem {\small\verb%A |- t%}, the inference
rule {\small\verb%GENL%} returns the theorem {\small\verb%A |- !x1...xn. t%}, provided none of the
variables {\small\verb%xi%} are free in any of the assumptions. It is not necessary that
any or all of the {\small\verb%xi%} should be free in {\small\verb%t%}.
{\par\samepage\setseps\small
\begin{verbatim}
         A |- t
   ------------------  GENL "[x1;...;xn]"       [where no xi is free in A]
    A |- !x1...xn. t
\end{verbatim}
}
\FAILURE
Fails unless all the terms in the list are variables, none of which are
free in the assumption list.

\SEEALSO
GEN, GEN_ALL, GEN_TAC, SPEC, SPECL, SPEC_ALL, SPEC_TAC.

\ENDDOC
\DOC{GEN\_REWRITE\_CONV}

\TYPE {\small\verb%GEN_REWRITE_CONV : ((conv -> conv) -> thm list -> thm list -> conv)%}\egroup

\SYNOPSIS
Rewrites a term, selecting terms according to a user-specified strategy.

\DESCRIBE
Rewriting in HOL is based on the use of equational theorems as left-to-right
replacements on the subterms of an object theorem.  This replacement is
mediated by the use of {\small\verb%REWR_CONV%}, which finds matches between left-hand
sides of given equations in a term and applies the substitution.

Equations used in rewriting are obtained from the theorem lists given as
arguments to the function. These are at first transformed into a form suitable
for rewriting. Conjunctions are separated into individual rewrites. Theorems
with conclusions of the form {\small\verb%"~t"%} are transformed into the corresponding
equations {\small\verb%"t = F"%}. Theorems {\small\verb%"t"%} which are not equations are cast as
equations of form {\small\verb%"t = T"%}.

If a theorem is used to rewrite a term, its assumptions
are added to the assumptions of the returned theorem.
The matching involved uses variable instantiation.
Thus, all free variables are generalized, and
terms are instantiated before substitution.
Theorems may have universally quantified variables.

The theorems with which rewriting is done are divided
into two groups, to facilitate implementing other rewriting tools.
However, they are considered in an order-independent fashion. (That
is, the ordering is an implementation detail which is not specified.)

The search strategy for finding matching subterms is the first
argument to the rule. Matching and substitution may occur at any
level of the term, according to the specified search strategy: the
whole term, or starting from any subterm. The search strategy also
specifies the depth of the search: recursively up to an arbitrary
depth until no matches occur, once over the selected subterm, or any
more complex scheme.

\FAILURE
{\small\verb%GEN_REWRITE_CONV%} fails if the search strategy fails. It may also
cause a non-terminating sequence of rewrites, depending on the search
strategy used.

\USES
This conversion is used in the system to implement all other rewritings
conversions, and may provide a user with a method to fine-tune rewriting of
terms.

\EXAMPLE
Suppose we have a term of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   "(1 + 2) + 3 = (3 + 1) + 2"
\end{verbatim}
}
\noindent and we would like to rewrite the left-hand side with the
theorem {\small\verb%ADD_SYM%} without changing the right hand side. This can be
done by using:
{\par\samepage\setseps\small
\begin{verbatim}
   GEN_REWRITE_CONV (RATOR_CONV o ONCE_DEPTH_CONV) []  [ADD_SYM] mythm
\end{verbatim}
}
\noindent Other rules, such as {\small\verb%ONCE_REWRITE_CONV%}, would match and
substitute on both sides, which would not be the desirable result.

As another example, {\small\verb%REWRITE_CONV%} could be implemented as
{\par\samepage\setseps\small
\begin{verbatim}
    GEN_REWRITE_CONV TOP_DEPTH_CONV basic_rewrites
\end{verbatim}
}
\noindent which specifies that matches should be searched recursively
starting from the whole term of the theorem, and {\small\verb%basic_rewrites%} must
be added to the user defined set of theorems employed in rewriting.

\SEEALSO
ONCE_REWRITE_CONV, PURE_REWRITE_CONV, REWR_CONV, REWRITE_CONV.

\ENDDOC
\DOC{GEN\_REWRITE\_RULE}

\TYPE {\small\verb%GEN_REWRITE_RULE : ((conv -> conv) -> thm list -> thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem, selecting terms according to a user-specified strategy.

\DESCRIBE
Rewriting in HOL is based on the use of equational theorems as left-to-right
replacements on the subterms of an object theorem.  This replacement is
mediated by the use of {\small\verb%REWR_CONV%}, which finds matches between left-hand
sides of given equations in a term and applies the substitution.

Equations used in rewriting are obtained from the theorem lists given as
arguments to the function. These are at first transformed into a form suitable
for rewriting. Conjunctions are separated into individual rewrites. Theorems
with conclusions of the form {\small\verb%"~t"%} are transformed into the corresponding
equations {\small\verb%"t = F"%}. Theorems {\small\verb%"t"%} which are not equations are cast as
equations of form {\small\verb%"t = T"%}.

If a theorem is used to rewrite the object theorem, its assumptions
are added to the assumptions of the returned theorem, unless they are
alpha-convertible to existing assumptions.  The matching involved uses
variable instantiation. Thus, all free variables are generalized, and
terms are instantiated before substitution. Theorems may have
universally quantified variables.

The theorems with which rewriting is done are divided
into two groups, to facilitate implementing other rewriting tools.
However, they are considered in an order-independent fashion. (That
is, the ordering is an implementation detail which is not specified.)

The search strategy for finding matching subterms is the first
argument to the rule. Matching and substitution may occur at any
level of the term, according to the specified search strategy: the
whole term, or starting from any subterm. The search strategy also
specifies the depth of the search: recursively up to an arbitrary
depth until no matches occur, once over the selected subterm, or any
more complex scheme.

\FAILURE
{\small\verb%GEN_REWRITE_RULE%} fails if the search strategy fails. It may also
cause a non-terminating sequence of rewrites, depending on the search
strategy used.

\USES
This rule is used in the system to implement all other rewriting
rules, and may provide a user with a method to fine-tune rewriting of
theorems.

\EXAMPLE
Suppose we have a theorem of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   thm = |- (1 + 2) + 3 = (3 + 1) + 2
\end{verbatim}
}
\noindent and we would like to rewrite the left-hand side with the
theorem {\small\verb%ADD_SYM%} without changing the right hand side. This can be
done by using:
{\par\samepage\setseps\small
\begin{verbatim}
   GEN_REWRITE_RULE (RATOR_CONV o ONCE_DEPTH_CONV) []  [ADD_SYM] mythm
\end{verbatim}
}
\noindent Other rules, such as {\small\verb%ONCE_REWRITE_RULE%}, would match and
substitute on both sides, which would not be the desirable result.

As another example, {\small\verb%REWRITE_RULE%} could be implemented as
{\par\samepage\setseps\small
\begin{verbatim}
    GEN_REWRITE_RULE TOP_DEPTH_CONV basic_rewrites
\end{verbatim}
}
\noindent which specifies that matches should be searched recursively
starting from the whole term of the theorem, and {\small\verb%basic_rewrites%} must
be added to the user defined set of theorems employed in rewriting.

\SEEALSO
ASM_REWRITE_RULE, FILTER_ASM_REWRITE_RULE, ONCE_REWRITE_RULE,
PURE_REWRITE_RULE, REWR_CONV, REWRITE_RULE.

\ENDDOC
\DOC{GEN\_REWRITE\_TAC}

\TYPE {\small\verb%GEN_REWRITE_TAC : ((conv -> conv) -> thm list -> thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal, selecting terms according to a user-specified strategy.

\DESCRIBE
Distinct rewriting tactics differ in the search strategies used in
finding subterms on which to apply substitutions, and the
built-in theorems used in rewriting. In the case of {\small\verb%REWRITE_TAC%},
this is a recursive traversal starting from the body of the goal's
conclusion part, while in the case of {\small\verb%ONCE_REWRITE_TAC%}, for example,
the search stops as soon as a term on which a substitution is possible
is found. {\small\verb%GEN_REWRITE_TAC%} allows a user to specify a more complex
strategy for rewriting.

The basis of pattern-matching for rewriting is the notion of
conversions, through the application of {\small\verb%REWR_CONV%}.  Conversions
are rules for mapping terms with theorems equating the given terms to
other semantically equivalent ones.

When attempting to rewrite subterms recursively, the use of
conversions (and therefore rewrites) can be automated further by using
functions which take a conversion and search for instances at which
they are applicable. Examples of these functions are {\small\verb%ONCE_DEPTH_CONV%}
and {\small\verb%RAND_CONV%}. The first argument to {\small\verb%GEN_REWRITE_TAC%} is such a
function, which specifies a search strategy; i.e. it specifies how
subterms (on which substitutions are allowed) should be searched for.

The second and third arguments are lists of theorems used for
rewriting. The order in which these are used is not specified. The
theorems need not be in equational form: negated terms, say {\small\verb%"~ t"%},
are transformed into the equivalent equational form {\small\verb%"t = F"%}, while
other non-equational theorems with conclusion of form {\small\verb%"t"%} are cast
as the corresponding equations {\small\verb%"t = T"%}. Conjunctions are separated
into the individual components, which are used as distinct rewrites.

\FAILURE
{\small\verb%GEN_REWRITE_TAC%} fails if the search strategy fails. It may also
cause a non-terminating sequence of rewrites, depending on the search
strategy used. The resulting tactic is invalid when a theorem which
matches the goal (and which is thus used for rewriting it with) has a
hypothesis which is not alpha-convertible to any of the assumptions of
the goal. Applying such an invalid tactic may result in a proof of
a theorem which does not correspond to the original goal.

\USES
Detailed control of rewriting strategy, allowing a user to specify a
search strategy.

\EXAMPLE
Given a goal such as:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- a - (b + c) = a - (c + b)
\end{verbatim}
}
\noindent we may want to rewrite only one side of it with a theorem,
say {\small\verb%ADD_SYM%}. Rewriting tactics which operate recursively result in
divergence; the tactic {\small\verb%ONCE_REWRITE_TAC [ADD_SYM]%} rewrites on both
sides to produce the following goal:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- a - (c + b) = a - (b + c)
\end{verbatim}
}
\noindent as {\small\verb%ADD_SYM%} matches at two positions. To rewrite on
only one side of the equation, the following tactic can be used:
{\par\samepage\setseps\small
\begin{verbatim}
   GEN_REWRITE_TAC (RAND_CONV o ONCE_DEPTH_CONV) [] [ADD_SYM]
\end{verbatim}
}
\noindent which produces the desired goal:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- a - (c + b) = a - (c + b)
\end{verbatim}
}
As another example, one can write a tactic which will behave similarly
to {\small\verb%REWRITE_TAC%} but will also include {\small\verb%ADD_CLAUSES%} in the set of
theorems to use always:
{\par\samepage\setseps\small
\begin{verbatim}
   let ADD_REWRITE_TAC = GEN_REWRITE_TAC TOP_DEPTH_CONV
                             (ADD_CLAUSES . basic_rewrites) ;;
\end{verbatim}
}
\SEEALSO
ASM_REWRITE_TAC, GEN_REWRITE_RULE, ONCE_REWRITE_TAC, PURE_REWRITE_TAC,
REWR_CONV, REWRITE_TAC,

\ENDDOC
\DOC{GEN\_TAC}

\TYPE {\small\verb%GEN_TAC : tactic%}\egroup

\SYNOPSIS
Strips the outermost universal quantifier from the conclusion of a goal.

\DESCRIBE
When applied to a goal {\small\verb%A ?- !x. t%}, the tactic {\small\verb%GEN_TAC%} reduces it to
{\small\verb%A ?- t[x'/x]%} where {\small\verb%x'%} is a variant of {\small\verb%x%} chosen to avoid clashing with any
variables free in the goal's assumption list. Normally {\small\verb%x'%} is just {\small\verb%x%}.
{\par\samepage\setseps\small
\begin{verbatim}
     A ?- !x. t
   ==============  GEN_TAC
    A ?- t[x'/x]
\end{verbatim}
}
\FAILURE
Fails unless the goal's conclusion is universally quantified.

\USES
The tactic {\small\verb%REPEAT GEN_TAC%} strips away any universal quantifiers, and
is commonly used before tactics relying on the  underlying term structure.

\SEEALSO
FILTER_GEN_TAC, GEN, GENL, GEN_ALL, SPEC, SPECL, SPEC_ALL, SPEC_TAC, STRIP_TAC,
X_GEN_TAC.

\ENDDOC
\DOC{genvar}

\TYPE {\small\verb%genvar : (type -> term)%}\egroup

\SYNOPSIS
Returns a variable whose name has not been used previously.

\DESCRIBE
When given a type, {\small\verb%genvar%} returns a variable of that type whose name has
not been used for a variable or constant in the HOL session so far.

\FAILURE
Never fails.

\EXAMPLE
The following indicates the typical stylized form of the names (this should
not be relied on, of course):
{\par\samepage\setseps\small
\begin{verbatim}
   #genvar ":bool";;
   "GEN%VAR%357" : term

   #genvar ":num";;
   "GEN%VAR%358" : term
\end{verbatim}
}
\noindent Trying to anticipate {\small\verb%genvar%} doesn't work:
{\par\samepage\setseps\small
\begin{verbatim}
   #let v = mk_var(`GEN%VAR%359`,":bool");;
   v = "GEN%VAR%359" : term

   #genvar ":bool";;
   "GEN%VAR%360" : term
\end{verbatim}
}
\USES
The unique variables are useful in writing derived rules, for specializing
terms without having to worry about such things as free variable capture.
If the names are to be visible to a typical user, the function {\small\verb%variant%} can
provide rather more meaningful names.

\SEEALSO
GSPEC, variant.

\ENDDOC
\DOC{get\_const\_type}

\TYPE {\small\verb%get_const_type : (string -> type)%}\egroup

\SYNOPSIS
Gets the generic type of a constant from the name of the constant.

\DESCRIBE
{\small\verb%get_const_type `c`%} returns the generic type of {\small\verb%"c"%}, if {\small\verb%"c"%} is a constant.

\FAILURE
{\small\verb%get_const_type st%} fails if {\small\verb%st%} is not the name of a constant.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#get_const_type `COND`;;
":bool -> (* -> (* -> *))" : type
\end{verbatim}
}
\SEEALSO
dest_const, is_constant.

\ENDDOC
\DOC{getenv}

\TYPE {\small\verb%getenv : (string -> string)%}\egroup

\SYNOPSIS
Returns the value of a Unix environment variable.

\DESCRIBE
{\small\verb%getenv x%} returns the value of {\small\verb%x%} from the current environment list; this
will include shell environment variables set before {\small\verb%HOL%} is run.

\FAILURE
If in a Unix environment, fails with {\small\verb%getenv%} if the variable is undefined,
or has an empty value. In other environments, it will normally fail anyway.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#getenv `SHELL`;;
`/bin/csh` : string
\end{verbatim}
}
\ENDDOC
\DOC{get\_flag\_value}

\TYPE {\small\verb%get_flag_value : (string -> bool)%}\egroup

\SYNOPSIS
Returns the value of one of the system flags.

\DESCRIBE
The call {\small\verb%get_flag_value name%} will read the value of the system flag called
{\small\verb%name%}.

\FAILURE
Fails unless the name denotes a flag.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#get_flag_value `timing`;;
false : bool
\end{verbatim}
}
\COMMENTS
The various flags which are set up by default are detailed in the DESCRIPTION.

\SEEALSO
flags, set_flag_value.

\ENDDOC
\DOC{get\_state}

\TYPE {\small\verb%get_state : (void -> goalstack)%}\egroup

\SYNOPSIS
Returns the current proof state of the subgoal package.

\DESCRIBE
The function {\small\verb%get_state%} is part of the subgoal package. It returns the current
proof state. A proof state of the package consists of either  goal and
justification stacks if a proof is in progress or a theorem if a proof has just
been completed. For a description of the subgoal package, see {\small\verb%set_goal%}.

\USES
Providing additional backup. Pausing in the proof of a goal whilst lemmas
required for its completion are proved. {\small\verb%get_state%} is used in conjunction with
{\small\verb%set_state%}. The current state may be bound to an ML variable using {\small\verb%get_state%}
and later restored using {\small\verb%set_state%}.

\EXAMPLE
In this example, a proof state is bound to the ML variable {\small\verb%main_proof%}.
{\par\samepage\setseps\small
\begin{verbatim}
   #g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])";;
   "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

   () : void

   #let main_proof = get_state();;
   main_proof = - : goalstack
\end{verbatim}
}
\noindent Other goals may now be set and proved. The proof state may later be
restored using {\small\verb%set_state%} and the original proof continued.
{\par\samepage\setseps\small
\begin{verbatim}
   #set_state main_proof;;
   "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

   () : void
\end{verbatim}
}
\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{get\_steps}

\TYPE {\small\verb%get_steps : void -> step list%}\egroup


\SYNOPSIS
Get the proof steps since last time the proof recorder is enabled.

\DESCRIBE
A proof is a list of inference steps. After the proof recorder is
enabled, every inference performed by the system is recorded and
cumulated in an internal buffer. When a proof is completed, the raw
records can then be processed and output to a disk file.

{\small\verb%get_steps%} is a low level user function for managing the proof
recorder. It returns the list of steps cumulated since last time the
proof recorder is enabled, i.e. the function {\small\verb%record_proof%} is called
with the value {\small\verb%true%}. The list of inference step needs to be
processed to produce a proof line list which can be output to a file.


\FAILURE
Never fail.

\EXAMPLE
Below is an example showing how to record an extremely simple proof
in which the function {\small\verb%get_steps%} is called to get the list of
inference steps:
{\par\samepage\setseps\small
\begin{verbatim}
#let th = SPEC_ALL ADD_SYM;;
Theorem ADD_SYM autoloading from theory `arithmetic` ...
ADD_SYM = |- !m n. m + n = n + m

th = |- m + n = n + m

#let v = genvar ":num";;
"GEN%VAR%536" : term

#record_proof true;;
() : void

#let th1 = (REFL "SUC(m + n)");;
th1 = |- SUC(m + n) = SUC(m + n)

#let th2 = SUBST [th,v] "SUC(m + n) = SUC ^v" th1;;
th2 = |- SUC(m + n) = SUC(n + m)

#record_proof false;;
() : void

#write_proof_to `ap_term.prf` `ap_term` [] (get_steps());;
() : void
\end{verbatim}
}
The proof consists of two inference steps: the application of the two
primitive inference rules {\small\verb%REFL%} and {\small\verb%SUBST%}. The function
{\small\verb%write_proof_to%} outputs the proof into a file names {\small\verb%ap_term.prf%}.

\COMMENTS
This function is used to implement higher level user functions for
recording proof in the library {\small\verb%record_proof%}. It is much more
convenient to use those functions than the low level functions
such as {\small\verb%get_steps%} directly.

\SEEALSO
record_proof, is_recording_proof, RecordStep, 
suspend_recording, resume_recording, MakeProof,
current_proof, current_proof_file,
new_proof_file, close_proof_file, begin_proof, end_proof,
TAC_PROOF, PROVE, prove, prove_thm.

\ENDDOC
\DOC{get\_type}

\TYPE {\small\verb%get_type : (term -> type -> type)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{goals}

\TYPE {\small\verb%goals : goalstack%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{GSPEC}

\TYPE {\small\verb%GSPEC : (thm -> thm)%}\egroup

\SYNOPSIS
Specializes the conclusion of a theorem with unique variables.

\DESCRIBE
When applied to a theorem {\small\verb%A |- !x1...xn. t%}, where the number of universally
quantified variables may be zero, {\small\verb%GSPEC%} returns {\small\verb%A |- t[g1/x1]...[gn/xn]%},
where the {\small\verb%gi%} are distinct variable names of the appropriate type, chosen by
{\small\verb%genvar%}.
{\par\samepage\setseps\small
\begin{verbatim}
        A |- !x1...xn. t
   -------------------------  GSPEC
    A |- t[g1/x1]...[gn/xn]
\end{verbatim}
}
\FAILURE
Never fails.

\USES
{\small\verb%GSPEC%} is useful in writing derived inference rules which need to specialize
theorems while avoiding using any variables that may be present elsewhere.

\SEEALSO
GEN, GENL, genvar, GEN_ALL, GEN_TAC, SPEC, SPECL, SPEC_ALL, SPEC_TAC.

\ENDDOC
\DOC{GSUBST\_TAC}

\TYPE {\small\verb%GSUBST_TAC : (((term # term) list -> term -> term) -> thm list -> tactic)%}\egroup

\SYNOPSIS
Makes term substitutions in a goal using a supplied substitution function.

\DESCRIBE
{\small\verb%GSUBST_TAC%} is the basic substitution tactic by means of which other tactics
such as {\small\verb%SUBST_OCCS_TAC%} and {\small\verb%SUBST_TAC%} are defined.  Given a list
{\small\verb%[(v1,w1);...;(vk,wk)]%} of pairs of terms and a term {\small\verb%w%}, a substitution
function replaces occurrences of {\small\verb%wj%} in {\small\verb%w%} with {\small\verb%vj%} according to a specific
substitution criterion. Such a criterion may be, for example, to substitute all
the occurrences or only some selected ones of each {\small\verb%wj%} in {\small\verb%w%}.

Given a substitution function {\small\verb%sfn%}, {\small\verb%GSUBST_TAC sfn [A1|-t1=u1;...;An|-tn=un]
(A,t)%} replaces occurrences of {\small\verb%ti%} in {\small\verb%t%} with {\small\verb%ui%} according to {\small\verb%sfn%}.
{\par\samepage\setseps\small
\begin{verbatim}
              A ?- t
   =============================  GSUBST_TAC sfn [A1|-t1=u1;...;An|-tn=un]
    A ?- t[u1,...,un/t1,...,tn]
\end{verbatim}
}
\noindent The assumptions of the theorems used to substitute with are not added
to the assumptions {\small\verb%A%} of the goal, while they are recorded in the proof.  If
any {\small\verb%Ai%} is not a subset of {\small\verb%A%} (up to alpha-conversion), then {\small\verb%GSUBST_TAC sfn
[A1|-t1=u1;...;An|-tn=un]%} results in an invalid tactic.

{\small\verb%GSUBST_TAC%} automatically renames bound variables to prevent free variables in
{\small\verb%ui%} becoming bound after substitution.

\FAILURE
{\small\verb%GSUBST_TAC sfn [th1;...;thn] (A,t)%} fails if the conclusion of each theorem in
the list is not an equation. No change is made to the goal if the occurrences
to be substituted according to the substitution function {\small\verb%sfn%} do not appear in
{\small\verb%t%}.

\USES
{\small\verb%GSUBST_TAC%} is used to define substitution tactics such as {\small\verb%SUBST_OCCS_TAC%}
and {\small\verb%SUBST_TAC%}. It may also provide the user with a tool for tailoring
substitution tactics.

\SEEALSO
SUBST1_TAC, SUBST_OCCS_TAC, SUBST_TAC.

\ENDDOC
\DOC{GSYM}

\TYPE {\small\verb%GSYM : (thm -> thm)%}\egroup

\SYNOPSIS
Reverses the first equation(s) encountered in a top-down search.

\DESCRIBE
The inference rule {\small\verb%GSYM%} reverses the first equation(s) encountered in a
top-down search of the conclusion of the argument theorem. An equation will be
reversed iff it is not a proper subterm of another equation. If a theorem
contains no equations, it will be returned unchanged.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- ..(s1 = s2)...(t1 = t2)..
   --------------------------------  GSYM
    A |- ..(s2 = s1)...(t2 = t1)..
\end{verbatim}
}
\FAILURE
Never fails, and never loops infinitely.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ADD;;
|- (!n. 0 + n = n) /\ (!m n. (SUC m) + n = SUC(m + n))
Run time: 0.0s

#GSYM ADD;;
|- (!n. n = 0 + n) /\ (!m n. SUC(m + n) = (SUC m) + n)
\end{verbatim}
}
\SEEALSO
NOT_EQ_SYM, REFL, SYM.

\ENDDOC
\DOC{HALF\_MK\_ABS}

\TYPE {\small\verb%HALF_MK_ABS : (thm -> thm)%}\egroup

\SYNOPSIS
Converts a function definition to lambda-form.

\DESCRIBE
When applied to a theorem {\small\verb%A |- !x. t1 x = t2%}, whose conclusion is a
universally quantified equation, {\small\verb%HALF_MK_ABS%} returns the theorem
{\small\verb%A |- t1 = \x. t2%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- !x. t1 x = t2
   --------------------  HALF_MK_ABS            [where x is not free in t1]
    A |- t1 = (\x. t2)
\end{verbatim}
}
\FAILURE
Fails unless the theorem is a singly universally quantified equation whose
left-hand side is a function applied to the quantified variable, or if the
variable is free in that function.

\SEEALSO
ETA_CONV, MK_ABS, MK_COMB, MK_EXISTS.

\ENDDOC
\DOC{\char'136}

\TYPE {\small\verb%$^ : (string -> string -> string)%}\egroup

\SYNOPSIS
Concatenates two ML strings.

\DESCRIBE
The {\small\verb%^%} is the ML infix string concatenation operator.
If {\small\verb%s1%} and {\small\verb%s2%} are strings, then {\small\verb%s1^s2%} gives a string which is their
concatenation.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#`Hello `^`world`;;
`Hello world` : string
\end{verbatim}
}
\COMMENTS
The ML role of the {\small\verb%^%} operator should not be confused with its use in
quoted terms to introduce antiquotation (see DESCRIPTION for details).

\SEEALSO
concat, concatl.

\ENDDOC
\DOC{hd}

\TYPE {\small\verb%hd : (* list -> *)%}\egroup

\SYNOPSIS
Computes the first element (the head) of a list.

\DESCRIBE
{\small\verb%hd [x1;...;xn]%} returns {\small\verb%x1%}.

\FAILURE
Fails with {\small\verb%hd%} if the list is empty.

\SEEALSO
tl, el, null.

\ENDDOC
\DOC{help}

\TYPE {\small\verb%help : (string -> void)%}\egroup

\SYNOPSIS
Displays help on a given identifier in the system.

\DESCRIBE
{\small\verb%help%} will attempt to display the help file associated with a particular
identifier in the system.  The identifier is provided as an ML string, and
the file should be located somewhere on the help search path. Normally the help
file for an identifier {\small\verb%name%} would be called {\small\verb%name.doc%}, but there are a few
exceptions, because some identifiers have characters that cannot be put in
filenames (e.g. `{\small\verb%/%}' under Unix, which is the directory separator).

\FAILURE
Fails if no information can be found on the identifier in question.

\SEEALSO
help_search_path, set_help_search_path.

\ENDDOC
\DOC{help\_search\_path}

\TYPE {\small\verb%help_search_path : (void -> string list)%}\egroup

\SYNOPSIS
Returns the internal search path use by HOL to find online help files.

\DESCRIBE
Evaluating {\small\verb%help_search_path()%} returns a list of strings representing the
pathnames of the directories that are searched when the {\small\verb%help%} function
searches for online help files. Although the help search path can be set to an
arbitrary list of strings, each string is normally expected to be either empty
({\small\verb%``%}) or a pathname with `{\small\verb%/%}' as its final character.  When the {\small\verb%help%}
function looks for an online help file, the directories in the help search path
are searched in the order in which they occur in the list returned by
{\small\verb%help_search_path%}.

\FAILURE
Never fails.

\SEEALSO
install, search_path, set_help_search_path, set_search_path.

\ENDDOC
\DOC{hide\_constant}

\TYPE {\small\verb%hide_constant : (string -> void)%}\egroup

\SYNOPSIS
Stops the quotation parser from recognizing a constant.

\DESCRIBE
A call {\small\verb%hide_constant `c`%} where {\small\verb%c%} is the name of a constant, will
prevent the quotation parser from parsing it as such; it will just be parsed as
a variable. The effect can be reversed by {\small\verb%unhide_constant `c`%}.

\FAILURE
Fails if the given name is not a constant of the current theory, or if the
named constant is already hidden.

\COMMENTS
The hiding of a constant only affects the quotation parser; the constant is
still there in a theory, and may not be redefined.

\SEEALSO
unhide_constant.

\ENDDOC
\DOC{hol\_pathname}

\TYPE {\small\verb%hol_pathname : (void -> string)%}\egroup

\SYNOPSIS
Returns the absolute pathname to the hol system directory.

\DESCRIBE
Evaluating {\small\verb%hol_pathname()%} returns a string giving the absolute pathname
to the directory in which the HOL system is resident.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#hol_pathname();;
`/usr/groups/hol/HOL2/sun4_sos` : string
\end{verbatim}
}
\SEEALSO
library_pathname.

\ENDDOC
\DOC{host\_name}

\TYPE {\small\verb%host_name : (void -> string)%}\egroup

\SYNOPSIS
Returns the name of the host machine.

\EXAMPLE
When the {\small\verb%HOL%} system was being run on the host machine {\small\verb%scaup.cl.cam.ac.uk%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #host_name ();;
   `scaup.cl.cam.ac.uk` : string
\end{verbatim}
}
\COMMENTS
This function uses the facilities provided by the underlying Lisp, which
unfortunately are extremely inconsistent. In Lisps other that Franz, this
function may not work at all. However, the ability to perform system commands
usually provides an adequate alternative, if one is prepared to put in a bit
more work. For example:
{\par\samepage\setseps\small
\begin{verbatim}
   #let host_name2() =
   #system `hostname >/tmp/.hostname`;
   #let handle = openi `/tmp/.hostname` in
   #letref name, char = ``, `` in
   #while not (char = `\
   #`) do (name := name^char; char := read handle);
   #close handle;
   #system `rm /tmp/.hostname`;
   #name;;
   host_name2 = - : (* -> string)

   #host_name();;
   `` : string

   #host_name2();;
   `auk.cl.cam.ac.uk` : string
\end{verbatim}
}
\ENDDOC
\DOC{hyp}

\TYPE {\small\verb%hyp : (thm -> term list)%}\egroup

\SYNOPSIS
Returns the hypotheses of a theorem.

\DESCRIBE
When applied to a theorem {\small\verb%A |- t%}, the function {\small\verb%hyp%} returns {\small\verb%A%}, the
list of hypotheses of the theorem.

\FAILURE
Never fails.

\SEEALSO
dest_thm, concl.

\ENDDOC
\DOC{hyp\_union}

\TYPE {\small\verb%hyp_union : (thm list -> term list)%}\egroup

\SYNOPSIS
Returns union of assumption lists of the given theorems.

\DESCRIBE
When applied to a list of theorems, {\small\verb%hyp_union%} returns the union (see
{\small\verb%union%}) of their assumption lists. Straight repetitions only arise if there
were multiple instances of an assumption in a single assumption list. There is
no elimination of alpha-equivalent pairs of assumptions, only ones which are
actually equal.
{\par\samepage\setseps\small
\begin{verbatim}
   hyp_union [A1 |- t1; ... ; An |- tn] = A1 u...u An
\end{verbatim}
}
\FAILURE
Never fails.

\USES
Designed for internal use, in writing primitive inference rules.

\SEEALSO
union.

\ENDDOC
\DOC{I}

\TYPE {\small\verb%I : (* -> *)%}\egroup

\SYNOPSIS
Performs identity operation: {\small\verb%I x%} = {\small\verb%x%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, CB, Co, K, KI, o, oo, S, W.

\ENDDOC
\DOC{IMP\_ANTISYM\_RULE}

\TYPE {\small\verb%IMP_ANTISYM_RULE : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Deduces equality of boolean terms from forward and backward implications.

\DESCRIBE
When applied to the theorems {\small\verb%A1 |- t1 ==> t2%} and {\small\verb%A2 |- t2 ==> t1%},
the inference rule {\small\verb%IMP_ANTISYM_RULE%} returns the theorem {\small\verb%A1 u A2 |- t1 = t2%}.
{\par\samepage\setseps\small
\begin{verbatim}
   A1 |- t1 ==> t2     A2 |- t2 ==> t1
  -------------------------------------  IMP_ANTISYM_RULE
           A1 u A2 |- t1 = t2
\end{verbatim}
}
\FAILURE
Fails unless the theorems supplied are a complementary implicative
pair as indicated above.

\SEEALSO
EQ_IMP_RULE, EQ_MP, EQ_TAC.

\ENDDOC
\DOC{IMP\_CANON}

\TYPE {\small\verb%IMP_CANON : (thm -> thm list)%}\egroup

\SYNOPSIS
Puts theorem into a `canonical' form.

\DESCRIBE
{\small\verb%IMP_CANON%} puts a theorem in `canonical' form by removing quantifiers
and breaking apart conjunctions, as well as disjunctions which form the
antecedent of implications. It applies the following transformation rules:
{\par\samepage\setseps\small
\begin{verbatim}
      A |- t1 /\ t2           A |- !x. t           A |- (t1 /\ t2) ==> t
   -------------------       ------------         ------------------------
    A |- t1   A |- t2           A |- t             A |- t1 ==> (t2 ==> t)

        A |- (t1 \/ t2) ==> t              A |- (?x. t1) ==> t2
   -------------------------------        ----------------------
    A |- t1 ==> t   A |- t2 ==> t          A |- t1[x'/x] ==> t2
\end{verbatim}
}
\FAILURE
Never fails, but if there is no scope for one of the above reductions,
merely gives a list whose only member is the original theorem.

\COMMENTS
This is a rather ad-hoc inference rule, and its use is not recommended.

\SEEALSO
CONJ1, CONJ2, CONJUNCTS, DISJ1, DISJ2, EXISTS, SPEC.

\ENDDOC
\DOC{IMP\_CONJ}

\TYPE {\small\verb%IMP_CONJ : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Conjoins antecedents and consequents of two implications.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- p ==> r%} and {\small\verb%A2 |- q ==> s%}, the {\small\verb%IMP_CONJ%}
inference rule returns the theorem {\small\verb%A1 u A2 |- p /\ q ==> r /\ s%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- p ==> r    A2 |- q ==> s
   --------------------------------  IMP_CONJ
     A1 u A2 |- p /\ q ==> r /\ s
\end{verbatim}
}
\FAILURE
Fails unless the conclusions of both theorems are implicative.

\SEEALSO
CONJ.

\ENDDOC
\DOC{IMP\_ELIM}

\TYPE {\small\verb%IMP_ELIM : (thm -> thm)%}\egroup

\SYNOPSIS
Transforms {\small\verb%|- s ==> t%} into {\small\verb%|- ~s \/ t%}.

\DESCRIBE
When applied to a theorem {\small\verb%A |- s ==> t%}, the inference rule {\small\verb%IMP_ELIM%}
returns the theorem {\small\verb%A |- ~s \/ t%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- s ==> t
   --------------  IMP_ELIM
    A |- ~s \/ t
\end{verbatim}
}
\FAILURE
Fails unless the theorem is implicative.

\SEEALSO
NOT_INTRO, NOT_ELIM.

\ENDDOC
\DOC{implode}

\TYPE {\small\verb%implode : (string list -> string)%}\egroup

\SYNOPSIS
Converts a list of single-character strings into one string.

\DESCRIBE
{\small\verb%implode [s1;...;sn]%} returns the string formed by concatenating the
single-character strings {\small\verb%s1 ... sn%}. If {\small\verb%n%} is zero (the list is empty),
then the empty string is returned.

\FAILURE
Fails if any of the strings in the argument list are null or longer than one
character.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#implode [`e`;`x`;`a`;`m`;`p`;`l`;`e`];;
`example` : string

#implode [`ex`;`a`;`mpl`;``;`e`];;
evaluation failed     implode
\end{verbatim}
}
\SEEALSO
explode, concat, concatl.

\ENDDOC
\DOC{IMP\_RES\_TAC}

\TYPE {\small\verb%IMP_RES_TAC : thm_tactic%}\egroup

\SYNOPSIS
Enriches assumptions by repeatedly resolving an implication with them.

\DESCRIBE
Given a theorem {\small\verb%th%}, the theorem-tactic {\small\verb%IMP_RES_TAC%} uses {\small\verb%RES_CANON%} to
derive a canonical list of implications, each of which has the form:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- u1 ==> u2 ==> ... ==> un ==> v
\end{verbatim}
}
\noindent {\small\verb%IMP_RES_TAC%} then tries to repeatedly `resolve' these theorems
against the assumptions of a goal by attempting to match the antecedents {\small\verb%u1%},
{\small\verb%u2%}, ..., {\small\verb%un%} (in that order) to some assumption of the goal (i.e. to some
candidate antecedents among the assumptions).  If all the antecedents can be
matched to assumptions of the goal, then an instance of the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   A u {a1,...,an} |- v
\end{verbatim}
}
\noindent called a `final resolvent' is obtained by repeated specialization of
the variables in the implicative theorem, type instantiation, and applications
of modus ponens.  If only the first {\small\verb%i%} antecedents {\small\verb%u1%}, ..., {\small\verb%ui%} can be
matched to assumptions and then no further matching is possible, then the final
resolvent is an instance of the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   A u {a1,...,ai} |- u(i+1) ==> ... ==> v
\end{verbatim}
}
\noindent All the final resolvents obtained in this way (there may be several,
since an antecedent {\small\verb%ui%} may match several assumptions) are added to the
assumptions of the goal, in the stripped form produced by using
{\small\verb%STRIP_ASSUME_TAC%}.  If the conclusion of any final resolvent is a
contradiction `{\small\verb%F%}' or is alpha-equivalent to the conclusion of the goal, then
{\small\verb%IMP_RES_TAC%} solves the goal.

\FAILURE
Never fails.

\SEEALSO
IMP_RES_THEN, RES_CANON, RES_TAC, RES_THEN.

\ENDDOC
\DOC{IMP\_RES\_THEN}

\TYPE {\small\verb%IMP_RES_THEN : thm_tactical%}\egroup

\SYNOPSIS
Resolves an implication with the assumptions of a goal.

\DESCRIBE
The function {\small\verb%IMP_RES_THEN%} is the basic building block for resolution in HOL.
This is not full higher-order, or even first-order, resolution with
unification, but simply one way simultaneous pattern-matching (resulting in
term and type instantiation) of the antecedent of an implicative theorem to the
conclusion of another theorem (the candidate antecedent).

Given a theorem-tactic {\small\verb%ttac%} and a theorem {\small\verb%th%}, the theorem-tactical
{\small\verb%IMP_RES_THEN%} uses {\small\verb%RES_CANON%} to derive a canonical list of implications from
{\small\verb%th%}, each of which has the form:
{\par\samepage\setseps\small
\begin{verbatim}
   Ai |- !x1...xn. ui ==> vi
\end{verbatim}
}
\noindent {\small\verb%IMP_RES_THEN%} then produces a tactic that, when applied to a goal
{\small\verb%A ?- g%} attempts to match each antecedent {\small\verb%ui%} to each assumption {\small\verb%aj |- aj%}
in the assumptions {\small\verb%A%}.  If the antecedent {\small\verb%ui%} of any implication matches the
conclusion {\small\verb%aj%} of any assumption, then an instance of the theorem {\small\verb%Ai u {aj}
|- vi%}, called a `resolvent', is obtained by specialization of the variables
{\small\verb%x1%}, ..., {\small\verb%xn%} and type instantiation, followed by an application of modus
ponens.  There may be more than one canonical implication and each implication
is tried against every assumption of the goal, so there may be several
resolvents (or, indeed, none).

Tactics are produced using the theorem-tactic {\small\verb%ttac%} from all these resolvents
(failures of {\small\verb%ttac%} at this stage are filtered out) and these tactics are then
applied in an unspecified sequence to the goal.  That is,
{\par\samepage\setseps\small
\begin{verbatim}
   IMP_RES_THEN ttac th  (A ?- g)
\end{verbatim}
}
\noindent has the effect of:
{\par\samepage\setseps\small
\begin{verbatim}
   MAP_EVERY (mapfilter ttac [... ; (Ai u {aj} |- vi) ; ...]) (A ?- g)
\end{verbatim}
}
\noindent where the theorems {\small\verb%Ai u {aj} |- vi%} are all the consequences that
can be drawn by a (single) matching modus-ponens inference from the
assumptions of the goal {\small\verb%A ?- g%} and the implications derived from the supplied
theorem {\small\verb%th%}.  The sequence in which the theorems {\small\verb%Ai u {aj} |- vi%} are
generated and the corresponding tactics applied is unspecified.

\FAILURE
Evaluating {\small\verb%IMP_RES_THEN ttac th%} fails with `{\small\verb%no implication%}' if the supplied
theorem {\small\verb%th%} is not an implication, or if no implications can be derived from
{\small\verb%th%} by the transformation process described under the entry for {\small\verb%RES_CANON%}.
Evaluating {\small\verb%IMP_RES_THEN ttac th (A ?- g)%} fails with `{\small\verb%no resolvents%}' if no
assumption of the goal {\small\verb%A ?- g%} can be resolved with the implication or
implications derived from {\small\verb%th%}. Evaluation also fails, with `{\small\verb%no tactics%}', if
there are resolvents, but for every resolvent {\small\verb%Ai u {aj} |- vi%} evaluating
the application {\small\verb%ttac (Ai u {aj} |- vi)%} fails---that is, if for every
resolvent {\small\verb%ttac%} fails to produce a tactic. Finally, failure is propagated if
any of the tactics that are produced from the resolvents by {\small\verb%ttac%} fails when
applied in sequence to the goal.

\EXAMPLE
The following example shows a straightforward use of {\small\verb%IMP_RES_THEN%} to
infer an equational consequence of the assumptions of a goal, use it
once as a substitution in the conclusion of goal, and then `throw it away'.
Suppose the goal is:
{\par\samepage\setseps\small
\begin{verbatim}
   a + n = a  ?- !k. k - n = k
\end{verbatim}
}
\noindent By the built-in theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   ADD_INV_0 = |- !m n. (m + n = m) ==> (n = 0)
\end{verbatim}
}
\noindent the assumption of this goal implies that {\small\verb%n%} equals {\small\verb%0%}.  A
single-step resolution with this theorem followed by substitution:
{\par\samepage\setseps\small
\begin{verbatim}
   IMP_RES_THEN SUBST1_TAC ADD_INV_0
\end{verbatim}
}
\noindent can therefore be used to reduce the goal to:
{\par\samepage\setseps\small
\begin{verbatim}
   a + n = a  ?- !k. k - 0 = m
\end{verbatim}
}
\noindent Here, a single resolvent {\small\verb%a + n = a |- n = 0%} is obtained by
matching the antecedent of {\small\verb%ADD_INV_0%} to the assumption of the goal.  This is
then used to substitute {\small\verb%0%} for {\small\verb%n%} in the conclusion of the goal.

\SEEALSO
IMP_RES_TAC, MATCH_MP, RES_CANON, RES_TAC, RES_THEN.

\ENDDOC
\DOC{IMP\_TRANS}

\TYPE {\small\verb%IMP_TRANS : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Implements the transitivity of implication.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- t1 ==> t2%} and {\small\verb%A2 |- t2 ==> t3%},
the inference rule {\small\verb%IMP_TRANS%} returns the theorem {\small\verb%A1 u A2 |- t1 ==> t3%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1 ==> t2   A2 |- t2 ==> t3
   -----------------------------------  IMP_TRANS
         A1 u A2 |- t1 ==> t3
\end{verbatim}
}
\FAILURE
Fails unless the theorems are both implicative, with the consequent of the
first being the same as the antecedent of the  second (up to alpha-conversion).

\SEEALSO
IMP_ANTISYM_RULE, SYM, TRANS.

\ENDDOC
\DOC{INDUCT}

\TYPE {\small\verb%INDUCT : ((thm # thm) -> thm)%}\egroup

\SYNOPSIS
Performs a proof by mathematical induction on the natural numbers.

\DESCRIBE
The derived inference rule {\small\verb%INDUCT%} implements the rule of mathematical
induction:
{\par\samepage\setseps\small
\begin{verbatim}
      A1 |- P[0]      A2 |- !n. P[n] ==> P[SUC n]
    -----------------------------------------------  INDUCT
               A1 u A2 |- !n. P[n]
\end{verbatim}
}
\noindent When supplied with a theorem {\small\verb%A1 |- P[0]%}, which asserts the base
case of a proof of the proposition {\small\verb%P[n]%} by induction on {\small\verb%n%}, and the theorem
{\small\verb%A2 |- !n. P[n] ==> P[SUC n]%}, which asserts the step case in the induction on
{\small\verb%n%}, the inference rule {\small\verb%INDUCT%} returns {\small\verb%A1 u A2 |- !n. P[n]%}.

\FAILURE
{\small\verb%INDUCT th1 th2%} fails if the theorems {\small\verb%th1%} and {\small\verb%th2%} do not have the forms
{\small\verb%A1 |- P[0]%} and {\small\verb%A2 |- !n. P[n] ==> P[SUC n]%} respectively.

\SEEALSO
INDUCT_TAC.

\ENDDOC
\DOC{INDUCT\_TAC}

\TYPE {\small\verb%INDUCT_TAC : tactic%}\egroup

\SYNOPSIS
Performs tactical proof by mathematical induction on the natural numbers.

\DESCRIBE
{\small\verb%INDUCT_TAC%} reduces a goal {\small\verb%!n.P[n]%}, where {\small\verb%n%} has type {\small\verb%num%}, to two
subgoals corresponding to the base and step cases in a proof by mathematical
induction on {\small\verb%n%}. The induction hypothesis appears among the assumptions of the
subgoal for the step case.  The specification of {\small\verb%INDUCT_TAC%} is:
{\par\samepage\setseps\small
\begin{verbatim}
                A ?- !n. P
    ========================================  INDUCT_TAC
     A ?- P[0/n]     A u {P} ?- P[SUC n'/n]
\end{verbatim}
}
\noindent where {\small\verb%n'%} is a primed variant of {\small\verb%n%} that does not appear free in
the assumptions {\small\verb%A%} (usually, {\small\verb%n'%} just equals {\small\verb%n%}). When {\small\verb%INDUCT_TAC%} is
applied to a goal of the form {\small\verb%!n.P%}, where {\small\verb%n%} does not appear free in {\small\verb%P%},
the subgoals are just {\small\verb%A ?- P%} and {\small\verb%A u {P} ?- P%}.

\FAILURE
{\small\verb%INDUCT_TAC g%} fails unless the conclusion of the goal {\small\verb%g%} has the form {\small\verb%!n.t%},
where the variable {\small\verb%n%} has type {\small\verb%num%}.

\SEEALSO
INDUCT.

\ENDDOC
\DOC{INDUCT\_THEN}

\TYPE {\small\verb%INDUCT_THEN : (thm -> thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Structural induction tactic for automatically-defined concrete types.

\DESCRIBE
The function {\small\verb%INDUCT_THEN%} implements structural induction tactics for
arbitrary concrete recursive types of the kind definable by {\small\verb%define_type%}.  The
first argument to {\small\verb%INDUCT_THEN%} is a structural induction theorem for the
concrete type in question. This theorem must have the form of an induction
theorem of the kind returned by {\small\verb%prove_induction_thm%}. When applied to such a
theorem, the function {\small\verb%INDUCT_THEN%} constructs specialized tactic for
doing structural induction on the concrete type in question.

The second argument to {\small\verb%INDUCT_THEN%} is a function that determines what is be
done with the induction hypotheses in the goal-directed proof by structural
induction.  Suppose that {\small\verb%th%} is a structural induction theorem for a concrete
data type {\small\verb%ty%}, and that {\small\verb%A ?- !x.P%} is a universally-quantified goal in which
the variable {\small\verb%x%} ranges over values of type {\small\verb%ty%}. If the type {\small\verb%ty%} has {\small\verb%n%}
constructors {\small\verb%C1%}, ..., {\small\verb%Cn%} and `{\small\verb%Ci(vs)%}' represents a (curried) application
of the {\small\verb%i%}th constructor to a sequence of variables, then if {\small\verb%ttac%} is a
function that maps the induction hypotheses {\small\verb%hypi%} of the {\small\verb%i%}th subgoal
to the tactic:
{\par\samepage\setseps\small
\begin{verbatim}
      A  ?- P[Ci(vs)/x]
   ======================  MAP_EVERY ttac hypi
         A1 ?- Gi
\end{verbatim}
}
\noindent then {\small\verb%INDUCT_THEN th ttac%} is an induction tactic that decomposes
the goal {\small\verb%A ?- !x.P%} into a set of {\small\verb%n%} subgoals, one for each constructor,
as follows:
{\par\samepage\setseps\small
\begin{verbatim}
            A ?- !x.P
  ================================  INDUCT_THEN th ttac
     A1 ?- G1  ...   An ?- Gn
\end{verbatim}
}
\noindent The resulting subgoals correspond to the cases in a structural
induction on the variable {\small\verb%x%} of type {\small\verb%ty%}, with induction hypotheses treated
as determined by {\small\verb%ttac%}.

\FAILURE
{\small\verb%INDUCT_THEN th ttac g%} fails if {\small\verb%th%} is not a structural induction theorem of
the form returned by {\small\verb%prove_induction_thm%}, or if the goal does not have the
form {\small\verb%A ?- !x:ty.P%} where {\small\verb%ty%} is the type for which {\small\verb%th%} is the induction
theorem, or if {\small\verb%ttac%} fails for any subgoal in the induction.

\EXAMPLE
The built-in structural induction theorem for lists is:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !P. P[] /\ (!t. P t ==> (!h. P(CONS h t))) ==> (!l. P l)
\end{verbatim}
}
\noindent When {\small\verb%INDUCT_THEN%} is applied to this theorem, it constructs
and returns a specialized induction tactic (parameterized by a theorem-tactic)
for doing induction on lists:
{\par\samepage\setseps\small
\begin{verbatim}
   #let LIST_INDUCT_THEN = INDUCT_THEN list_INDUCT;;
   LIST_INDUCT_THEN = - : (thm_tactic -> tactic)
\end{verbatim}
}
\noindent The resulting function, when supplied with the thm-tactic
{\small\verb%ASSUME_TAC%}, returns a tactic that decomposes a goal {\small\verb%?- !l.P[l]%} into the
base case {\small\verb%?- P[NIL]%} and a step case {\small\verb%P[l] ?- !h. P[CONS h l]%}, where the
induction hypothesis {\small\verb%P[l]%} in the step case has been put on the assumption
list.  That is, the tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   LIST_INDUCT_THEN ASSUME_TAC
\end{verbatim}
}
\noindent does structural induction on lists, putting any induction hypotheses
that arise onto the assumption list:
{\par\samepage\setseps\small
\begin{verbatim}
                      A ?- !l. P
   =======================================================
    A |- P[NIL/l]   A u {P[l'/l]} ?- !h. P[(CONS h l')/l]
\end{verbatim}
}
\noindent Likewise {\small\verb%LIST_INDUCT_THEN STRIP_ASSUME_TAC%} will also do induction
on lists, but will strip induction hypotheses apart before adding them to the
assumptions (this may be useful if P is a conjunction or a disjunction, or is
existentially quantified).  By contrast, the tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   LIST_INDUCT_THEN MP_TAC
\end{verbatim}
}
\noindent will decompose the goal as follows:
{\par\samepage\setseps\small
\begin{verbatim}
                      A ?- !l. P
   =====================================================
    A |- P[NIL/l]   A ?- P[l'/l] ==> !h. P[CONS h l'/l]
\end{verbatim}
}
\noindent That is, the induction hypothesis becomes the antecedent of an
implication expressing the step case in the induction, rather than an
assumption of the step-case subgoal.

\SEEALSO
define_type, new_recursive_definition, prove_cases_thm,
prove_constructors_distinct, prove_constructors_one_one, prove_induction_thm,
prove_rec_fn_exists.

\ENDDOC
\DOC{infixes}

\TYPE {\small\verb%infixes : (string -> term list)%}\egroup

\SYNOPSIS
Lists the infixes in the named theory.

\DESCRIBE
The function {\small\verb%infixes%} should be applied to a string which is the name of an
ancestor theory (including the current theory; the special string {\small\verb%`-`%} is
always interpreted as the current theory). It returns a list of all the infixes
declared in that theory.

\FAILURE
Fails unless the given theory is an ancestor of the current theory.

\EXAMPLE
The theory {\small\verb%HOL%} has no infixes:
{\par\samepage\setseps\small
\begin{verbatim}
   #infixes `HOL`;;
   [] : term list
\end{verbatim}
}
\noindent but the theory {\small\verb%arithmetic%} has several:
{\par\samepage\setseps\small
\begin{verbatim}
   #infixes `arithmetic`;;
   ["$DIV"; "$MOD"; "$>="; "$<="; "$>"; "$EXP"; "$*"; "$-"; "$+"]
   : term list
\end{verbatim}
}
\SEEALSO
ancestors, axioms, binders, constants, definitions, new_infix,
new_infix_definition, new_infix_list_rec_definition,
new_infix_prim_rec_definition, parents, types.

\ENDDOC
\DOC{infix\_variable}

\TYPE {\small\verb%infix_variable : string -> void%}\egroup

\SYNOPSIS
Makes a HOL variable parse and print as an infix.

\DESCRIBE 
A call {\small\verb%infix_variable `x`%} makes {\small\verb%x%} an infixed
variable. This is purely an interface property for the current
session. Infixed variables are assumed curried. Infixed variables used
in non-infix positions (e.g. as arguments or when being quantified)
must be preceded by {\small\verb%$%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #new_special_symbol `<<`;;
   () : void

   #infix_variable `<<`;;
   () : void

   #"!$<<. TRANSITIVE $<< = !(x y z:*). x << y /\ y << z ==> x << z";;
   "TRANSITIVE $<< = (!x y z. x << y /\ y << z ==> x << z)" : term
\end{verbatim}
}

\ENDDOC
\DOC{inject\_input}

\TYPE {\small\verb%inject_input : (int list -> void)%}\egroup

\SYNOPSIS
Passes a list of character codes to the ML interpreter.

\DESCRIBE
When applied to a list of character codes, {\small\verb%inject_input%} passes these to the
ML interpreter, which will, after evaluating other pending phrases, interpret
them.

\FAILURE
The injection of input never fails, but of course the subsequent interpretation
may do.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#inject_input (map ascii_code (explode `tty_write \`Yo!\`;;\
#`));;
() : void

Yo!() : void
\end{verbatim}
}
\COMMENTS
The function {\small\verb%ML_eval%} is similar, and easier to use.

\SEEALSO
let_after, let_before, ML_eval.

\ENDDOC
\DOC{inl}

\TYPE {\small\verb%inl : (* -> (* + **))%}\egroup

\SYNOPSIS
Injects into left of disjoint union type.

\DESCRIBE
The function {\small\verb%inl%} is a constructor function for disjoint union (sum) types,
which takes an element of an arbitrary type {\small\verb%*%} and creates an element of type
{\small\verb%* # **%} which holds the same data.

\FAILURE
Never fails

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let x = inl 1;;
x = inl 1 : (int + *)

#let y = inl `hello` : string + int;;
y = inl `hello` : (string + int)
\end{verbatim}
}
\SEEALSO
inr, isl, outl, outr.

\ENDDOC
\DOC{inr}

\TYPE {\small\verb%inr : (* -> (** + *))%}\egroup

\SYNOPSIS
Injects into right of disjoint union type.

\DESCRIBE
The function {\small\verb%inr%} is a constructor function for disjoint union (sum) types,
which takes an element of an arbitrary type {\small\verb%**%} and creates an element of type
{\small\verb%* # **%} which holds the same data.

\FAILURE
Never fails

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let x = inr 1;;
x = inr 1 : (* + int)

#let y = inr 12 : string + int;;
y = inr 12 : (string + int)
\end{verbatim}
}
\SEEALSO
inl, isl, outl, outr.

\ENDDOC
\DOC{install}

\TYPE {\small\verb%install : (string -> void)%}\egroup

\SYNOPSIS
Informs HOL of the absolute pathname to the hol distribution directory.

\DESCRIBE
{\small\verb%install%} reconfigures a running HOL system to a new root directory.  The
string argument to {\small\verb%install%} should be the absolute path name to the
directory in which the HOL system is located. Executing
{\par\samepage\setseps\small
\begin{verbatim}
   install `/dir1/dir2/dir3/.../hol`;;
\end{verbatim}
}
\noindent sets the internal HOL search path to:
{\par\samepage\setseps\small
\begin{verbatim}
   [``; `~/`; `/dir1/dir2/dir3/.../hol/theories/`]
\end{verbatim}
}
\noindent In addition, {\small\verb%install%} sets the internal search path used by HOL to
find the standard online help files and the internal search path used by HOL to
find libraries.

\FAILURE
Never fails.

\COMMENTS
The effect persists only for the current HOL session. To change the image
permanently, use the {\small\verb%save%} function after installation.

\SEEALSO
help_search_path, library_pathname, library_search_path, search_path,
set_help_search_path, set_library_search_path, set_search_path.

\ENDDOC
\DOC{inst\_check}

\TYPE {\small\verb%inst_check : (((type # type) list # term list) -> term list)%}\egroup

\SYNOPSIS
Checks the validity of type instantiations.

\DESCRIBE
If the {\small\verb%t1...tn%} are types (monomorphic or polymorphic), the {\small\verb%v1...vn%} type
variables (e.g. {\small\verb%":*"%}), and {\small\verb%tm1...tmn%} terms, the call
{\par\samepage\setseps\small
\begin{verbatim}
   inst_check ([(t1,v1);...;(tn,vn)],[tm1;...;tmn])
\end{verbatim}
}
\noindent will return a list of the variables free in the {\small\verb%tm1...tmn%}, provided
none of the type variables {\small\verb%v1...vn%} are free in {\small\verb%tm1...tmn%}. If this condition
is not met, or any of the {\small\verb%v%}'s are not simply type variables, the call fails.

\FAILURE
Fails if any of the {\small\verb%v%}'s are not simple type variables, or if any of them are
free in the terms {\small\verb%v1...vn%}.

\USES
Checking the validity of type instantiations (for example, if the terms are the
hypotheses of a theorem).

\SEEALSO
inst, inst_rename_list, inst_type, INST_TYPE.

\ENDDOC
\DOC{inst}

\TYPE {\small\verb%inst : (term list -> (type # type) list -> term -> term)%}\egroup

\SYNOPSIS
Performs type instantiations in a term, avoiding certain ones.

\DESCRIBE
The function {\small\verb%inst%} should be used as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   inst [tm1;...;tmn] [(t1',t1);...;(tn',tn)] tm
\end{verbatim}
}
\noindent where {\small\verb%tm1...tmn%} are variables, {\small\verb%t1...tn,t1'...tn'%} types and {\small\verb%tm%} a
term to be type-instantiated. This call will instantiate, in parallel, the
types {\small\verb%t1'...tn'%} for the types {\small\verb%t1...tn%} wherever they appear in {\small\verb%tm%}
(possibly nowhere). However, if the name (not necessarily the type) of any
variable being instantiated matches one of the {\small\verb%[tm1...tmn]%}, it will be
renamed (by adding primes) prior to the instantiation. This is useful to avoid
obscure problems of free variable capture when type-instantiating theorems.

\FAILURE
Fails if the instantiation list is non-empty and some of the {\small\verb%tm1...tmn%} are
not simply variables.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#inst [] [(":num",":*")] "(x:*) = (x:*)";;
"x = x" : term

#inst ["x:bool"] [(":num",":*")] "(x:*) = (x:*)";;
"x' = x'" : term

#inst [] [(":num",":bool")] "x:bool";;
"x" : term

#type_of it;;
":num" : type
\end{verbatim}
}
\USES
Performing internal functions connected with type instantiation.

\SEEALSO
inst_check, inst_rename_list, inst_type, INST_TYPE.

\ENDDOC
\DOC{INST}

\TYPE {\small\verb%INST : ((term # term) list -> thm -> thm)%}\egroup

\SYNOPSIS
Instantiates free variables in a theorem.

\DESCRIBE
{\small\verb%INST%} is a rule for substituting arbitrary terms for free variables
in a theorem:
{\par\samepage\setseps\small
\begin{verbatim}
             A |- t
   -----------------------------  INST [(t1,x1);...;(tn,xn)]
    A |- t[t1,...,tn/x1,...,xn]
\end{verbatim}
}
\noindent where the variables {\small\verb%x1, ..., xn%} are not free in the
assumptions {\small\verb%A%}.

\FAILURE
{\small\verb%INST%} fails if a variable being instantiated is free in the
assumptions.

\EXAMPLE
In the following example a theorem is instantiated for a specific term:
{\par\samepage\setseps\small
\begin{verbatim}
   #CONJUNCT1 ADD_CLAUSES ;;
   |- 0 + m = m

   #INST [("2 * x","m:num")] (CONJUNCT1 ADD_CLAUSES) ;;
   |- 0 + (2 * x) = 2 * x
\end{verbatim}
}
\SEEALSO
INST_TY_TERM, INST_TYPE, ISPEC, ISPECL, SPEC; SPECL, SUBS, subst, SUBST.

\ENDDOC
\DOC{inst\_rename\_list}

\TYPE {\small\verb%inst_rename_list : (term -> term list)%}\egroup

\SYNOPSIS
Looks for variables which could become bound after type instantiation.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
  inst_rename_list tm
\end{verbatim}
}
\noindent will return a list of those variables in {\small\verb%tm%} which are in the scope
of a binding of a variable with the same name but a different type. This means
that instantiating the type of a variable of that name could lead to free
variable capture.

\FAILURE
Never fails.

\EXAMPLE
The examples needed to exercise this routine cannot be created using a single
quoted term, since the quotation parser assumes that all variables with the
same name are identical.
{\par\samepage\setseps\small
\begin{verbatim}
   #let tm = mk_abs("x:num","~x");;
   tm = "\x. ~x" : term

   #inst_rename_list tm;;
   ["x"] : term list

   #type_of (hd it);;
   ":bool" : type
\end{verbatim}
}
\USES
Checking the validity of type instantiations.

\SEEALSO
inst, inst_check, inst_type, INST_TYPE.

\ENDDOC
\DOC{inst\_type}

\TYPE {\small\verb%inst_type : ((type # type) list -> type -> type)%}\egroup

\SYNOPSIS
Instantiates types in a type.

\DESCRIBE
If {\small\verb%[(t1',t1);...;(tn',tn)]%} is a list of type instantiations, where {\small\verb%t1...tn%}
are the initial types, and {\small\verb%t1'...tn'%} the desired instantiations, and {\small\verb%ty%} is
a type to instantiate, the call
{\par\samepage\setseps\small
\begin{verbatim}
   inst_type [(t1',t1);...;(tn',tn)] ty
\end{verbatim}
}
\noindent will appropriately instantiate the type {\small\verb%ty%}. The instantiations will
be performed in parallel. If several of the type instantiations are applicable,
the choice is undefined. In normal use the {\small\verb%t1...tn%} are type variables,
although this is not essential. Neither is it necessary that any or all of the
types {\small\verb%t1...tn%} should in fact appear in {\small\verb%ty%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#inst_type [(":bool",":*")] ":* # **";;
":bool # **" : type

#inst_type [(":num",":* # **"); (":bool",":*")] ":* # **";;
":num" : type

#inst_type [(":bool",":*"); (":num",":* # **")] ":* # **";;
":num" : type

#inst_type [(":bool",":num"); (":num",":bool")] ":(bool)list";;
":(num)list" : type
\end{verbatim}
}
\SEEALSO
inst, inst_check, inst_type, INST_TYPE.

\ENDDOC
\DOC{INST\_TYPE}

\TYPE {\small\verb%INST_TYPE : ((type # type) list -> thm -> thm)%}\egroup

\SYNOPSIS
Instantiates types in a theorem.

\DESCRIBE
{\small\verb%INST_TYPE%} is a primitive rule in the HOL logic, which allows
instantiation of type variables.
{\par\samepage\setseps\small
\begin{verbatim}
               A |- t
   -----------------------------------  INST_TYPE [(ty1,vty1);...;(tyn,vtyn)]
    A |- t[ty1,...,tyn/vty1,...,vtyn]
\end{verbatim}
}
\noindent where none of the types {\small\verb%vtyi%} are free in the assumption list.
Variables will be renamed if necessary to prevent distinct variables becoming
identical after the instantiation.

\FAILURE
{\small\verb%INST_TYPE%} fails if any of the type variables occurs free in the
hypotheses of the theorem, or if upon instantiation two distinct
variables (with the same name) become equal.

\USES
{\small\verb%INST_TYPE%} is employed to make use of polymorphic theorems.

\EXAMPLE
Suppose one wanted to specialize the theorem {\small\verb%EQ_SYM_EQ%} for
particular values, the first attempt could be to use {\small\verb%SPECL%} as
follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #SPECL ["a:num"; "b:num"] EQ_SYM_EQ ;;
   evaluation failed     SPECL
\end{verbatim}
}
\noindent The failure occurred because {\small\verb%EQ_SYM_EQ%} contains polymorphic types.
The desired specialization can be obtained by using {\small\verb%INST_TYPE%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #SPECL ["a:num"; "b:num"] (INST_TYPE [":num",":*"] EQ_SYM_EQ) ;;
   |- (a = b) = (b = a)
\end{verbatim}
}
\SEEALSO
INST, INST_TY_TERM.

\ENDDOC
\DOC{INST\_TY\_TERM}

\TYPE {\small\verb%INST_TY_TERM : (((term # term) list # (type # type) list) -> thm -> thm)%}\egroup

\SYNOPSIS
Instantiates terms and types of a theorem.

\DESCRIBE
{\small\verb%INST_TY_TERM%} instantiates types in a theorem, in the same way
{\small\verb%INST_TYPE%} does. Then it instantiates some or all of the free
variables in the resulting theorem, in the same way as {\small\verb%INST%}.

\FAILURE
{\small\verb%INST_TY_TERM%} fails under the same conditions as either {\small\verb%INST%} or
{\small\verb%INST_TYPE%} fail.

\SEEALSO
INST, INST_TYPE, ISPEC, SPEC, SUBS, SUBST.

\ENDDOC
\DOC{interface\_map}

\TYPE {\small\verb%interface_map : (void -> (string # string) list)%}\egroup

\SYNOPSIS
Returns the current interface map.

\DESCRIBE
A call {\small\verb%interface_map()%} will return the current interface map. This is a list
of string pairs which specify different toplevel representations for constants;
see the DESCRIPTION for further details.

\FAILURE
Never fails.

\SEEALSO
set_interface_map.

\ENDDOC
\DOC{intersect}

\TYPE {\small\verb%intersect : (* list -> * list -> * list)%}\egroup

\SYNOPSIS
Computes the intersection of two `sets'.

\DESCRIBE
{\small\verb%intersect l1 l2%} returns a list consisting of those elements of {\small\verb%l1%} that
also appear in {\small\verb%l2%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#intersect [1;2;3] [3;5;4;1];;
[1; 3] : int list

#intersect [1;2;4;1] [1;2;3;2];;
[1; 2; 1] : int list
\end{verbatim}
}
\SEEALSO
setify, set_equal, union, subtract.

\ENDDOC
\DOC{int\_of\_string}

\TYPE {\small\verb%int_of_string : (string -> int)%}\egroup

\SYNOPSIS
Maps a string of numbers to the corresponding integer.

\DESCRIBE
Given a string representing an integer in standard decimal notation,
possibly including a leading plus sign or minus sign and/or leading zeros,
{\small\verb%int_of_string%} returns the corresponding integer constant.

\FAILURE
Fails unless the string is a valid decimal representation as specified
above.

\SEEALSO
ascii, ascii_code, string_of_int.

\ENDDOC
\DOC{int\_of\_term}

\TYPE {\small\verb%int_of_term : (term -> int)%}\egroup

\SYNOPSIS
Maps a numeric term to the corresponding ML integer.

\DESCRIBE
Given a term representing a natural number, i.e., of type {\small\verb%:num%}
{\small\verb%int_of_term%} returns the corresponding ML integer constant.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #int_of_term "2";;
   2 : int
\end{verbatim}
}

\SEEALSO
term_of_int, string_of_int, int_of_string.

\ENDDOC
\DOC{is\_abs}

\TYPE {\small\verb%is_abs : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is an abstraction.

\DESCRIBE
{\small\verb%is_abs "\var. t"%} returns {\small\verb%true%}. If the term is not an abstraction the
result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_abs, dest_abs, is_var, is_const, is_comb.

\ENDDOC
\DOC{is\_alphanum}

\TYPE {\small\verb%is_alphanum : (string -> bool)%}\egroup

\SYNOPSIS
Tests whether a character is alphanumeric.

\DESCRIBE
When given a string, which should be of length 1, {\small\verb%is_alphanum%} returns
{\small\verb%true%} iff the character is alphanumeric. By default this means that it
is an upper or lower case letter, a digit, a prime ({\small\verb%'%}) or an
underscore ({\small\verb%_%}). However the definition can be changed using the function
{\small\verb%new_alphanum%}.

\FAILURE
Fails if the string has length greater than 1. Returns {\small\verb%false%} for the
null string ({\small\verb%``%}).

\SEEALSO
ascii, ascii_code, is_letter, new_alphanum, new_letter.

\ENDDOC
\DOC{is\_axiom}

\TYPE {\small\verb%is_axiom : ((string # string) -> bool)%}\egroup

\SYNOPSIS
Tests if there is an axiom with the given name in the given theory.

\DESCRIBE
The call {\small\verb%is_axiom(`th`,`ax`)%}, where {\small\verb%th%} is the name of a theory (as
usual {\small\verb%`-`%} means the current theory), tests if there is an axiom called {\small\verb%ax%}
in that theory.

\FAILURE
Fails unless the given theory is an ancestor.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_axiom(`bool`,`BOOL_CASES_AX`);;
true : bool

#is_axiom(`bool`,`INFINITY_AX`);;
false : bool

#is_axiom(`ind`,`INFINITY_AX`);;
true : bool
\end{verbatim}
}
\SEEALSO
axioms, new_axiom.

\ENDDOC
\DOC{is\_binder}

\TYPE {\small\verb%is_binder : (string -> bool)%}\egroup

\SYNOPSIS
Determines whether a given string represents a binder.

\DESCRIBE
This predicate returns true if the given string argument is the name of
 a binder: it returns false otherwise.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#binders `bool`;;
["$?!"; "$!"; "$@"] : term list

#is_binder `$?!`;;
false : bool

#is_binder `?!`;;
true : bool
\end{verbatim}
}
\SEEALSO
binders, is_binder_type, is_infix, is_constant

\ENDDOC
\DOC{is\_binder\_type}

\TYPE {\small\verb%is_binder_type : (type -> bool)%}\egroup

\SYNOPSIS
Determines whether a given type is an appropriate type for a binder.

\DESCRIBE
The most general binder type is {\small\verb%":(* -> **) -> ***"%}. The function
{\small\verb%is_binder_type%} returns {\small\verb%true%} if the given type is an instance of the
most general binder type: it returns false otherwise.

\FAILURE
Sometimes fails in a nasty way: e.g.,
{\par\samepage\setseps\small
\begin{verbatim}
   #is_binder_type ":(* -> **)";;
   evaluation failed     dest_type
\end{verbatim}
}
\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_binder_type ":(* -> **) -> ***";;
true : bool

#is_binder_type ":(* -> **) -> (* -> **)";;
true : bool

#is_binder_type ":(num -> bool) -> bool";;
true : bool

#is_binder_type ":(num)list";;
false : bool
\end{verbatim}
}
\SEEALSO
is_binder, is_infix_type, is_type

\ENDDOC
\DOC{is\_comb}

\TYPE {\small\verb%is_comb : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a combination (function application).

\DESCRIBE
{\small\verb%is_comb "t1 t2"%} returns {\small\verb%true%}. If the term is not a combination the result
is {\small\verb%false%}.

\FAILURE
Never fails

\SEEALSO
mk_comb, dest_comb, is_var, is_const, is_abs.

\ENDDOC
\DOC{is\_cond}

\TYPE {\small\verb%is_cond : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a conditional.

\DESCRIBE
{\small\verb%is_cond "t => t1 | t2"%} returns {\small\verb%true%}. If the term is not a conditional the
result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_cond, dest_cond.

\ENDDOC
\DOC{is\_conj}

\TYPE {\small\verb%is_conj : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a conjunction.

\DESCRIBE
{\small\verb%is_conj "t1 /\ t2"%} returns {\small\verb%true%}. If the term is not a conjunction the
result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_conj, dest_conj.

\ENDDOC
\DOC{is\_cons}

\TYPE {\small\verb%is_cons : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is an application of {\small\verb%CONS%}.

\DESCRIBE
{\small\verb%is_cons%} returns {\small\verb%true%} of a term representing a non-empty list. Otherwise it
returns {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_cons, dest_cons, mk_list, dest_list, is_list.

\ENDDOC
\DOC{is\_constant}

\TYPE {\small\verb%is_constant : (string -> bool)%}\egroup

\SYNOPSIS
Determines whether a string is the name of a constant.

\DESCRIBE
This predicate returns {\small\verb%true%} if the given string argument is the name
of a constant defined in the current theory or its ancestors:
it returns {\small\verb%false%} otherwise.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_constant `SUC`;;
true : bool

#is_constant `3`;;
true : bool

#is_constant `$!`;;
false : bool

#is_constant `!`;;
true : bool

#is_constant `xx`;;
false : bool
\end{verbatim}
}
\SEEALSO
is_infix, is_binder

\ENDDOC
\DOC{is\_const}

\TYPE {\small\verb%is_const : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a constant.

\DESCRIBE
{\small\verb%is_const "const:ty"%} returns {\small\verb%true%}. If the term is not a constant the
result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_const, dest_const, is_var, is_comb, is_abs.

\ENDDOC
\DOC{is\_definition}

\TYPE {\small\verb%is_definition : (term -> bool)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{is\_disj}

\TYPE {\small\verb%is_disj : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a disjunction.

\DESCRIBE
{\small\verb%is_disj "t1 \/ t2"%} returns {\small\verb%true%}. If the term is not a disjunction the
result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_disj, dest_disj.

\ENDDOC
\DOC{IS\_EL\_CONV}

\TYPE {\small\verb%IS_EL_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of testing whether a list contains acertain element.

\DESCRIBE
{\small\verb%IS_EL_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   IS_EL x [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- IS_EL x [x0;...xn] = F
\end{verbatim}
}
\noindent if for every {\small\verb%xi%} occurred in the list, {\small\verb%conv "x = xi"%}
returns a theorem {\small\verb%|- P xi = F%}, otherwise, if for at least one {\small\verb%xi%},
evaluating {\small\verb%conv "P xi"%} returns the theorem {\small\verb%|- P xi = T%}, then it
returns the theorem 
{\par\samepage\setseps\small
\begin{verbatim}
   |- IS_EL P [x0;...xn] = T
\end{verbatim}
}

\FAILURE
{\small\verb%IS_EL_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above, or
failure occurs when evaluating {\small\verb%conv "x = xi"%} for some {\small\verb%xi%}.

\EXAMPLE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   IS_EL_CONV bool_EQ_CONV "IS_EL T [T;F;T]";;
\end{verbatim}
}
\noindent returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- IS_EL($= T)[F;F] = F
\end{verbatim}
}


\SEEALSO
SOME_EL_CONV, ALL_EL_CONV, FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{is\_eq}

\TYPE {\small\verb%is_eq : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is an equation.

\DESCRIBE
{\small\verb%is_eq "t1 = t2"%} returns {\small\verb%true%}. If the term is not an equation the result
is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_eq, dest_eq.

\ENDDOC
\DOC{is\_exists}

\TYPE {\small\verb%is_exists : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it as an existential quantification.

\DESCRIBE
{\small\verb%is_exists "?var. t"%} returns {\small\verb%true%}. If the term is not an existential
quantification the result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_exists, dest_exists.

\ENDDOC
\DOC{is\_forall}

\TYPE {\small\verb%is_forall : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a universal quantification.

\DESCRIBE
{\small\verb%is_forall "!var. t"%} returns {\small\verb%true%}. If the term is not a universal
quantification the result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_forall, dest_forall.

\ENDDOC
\DOC{is\_hidden}

\TYPE {\small\verb%is_hidden : (string -> bool)%}\egroup

\SYNOPSIS
Determines whether a constant is hidden.

\DESCRIBE
This predicate returns {\small\verb%true%} if the named {\small\verb%ML%} constant has been hidden by
the function {\small\verb%hide_constant%}; it returns {\small\verb%false%} if the constant is not hidden.
Hiding a constant forces the quotation parser to treat the constant as
 a variable (lexical rules permitting).

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_hidden `0`;;
false : bool

#hide_constant `0`;;
() : void

#is_hidden `0`;;
true : bool

#unhide_constant `0`;;
() : void

#is_hidden `0`;;
false : bool
\end{verbatim}
}
\SEEALSO
hide_constant, unhide_constant

\ENDDOC
\DOC{is\_imp}

\TYPE {\small\verb%is_imp : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is an implication.

\DESCRIBE
{\small\verb%is_imp "t1 ==> t2"%} returns {\small\verb%true%}. 
If the term is not an implication the result is {\small\verb%false%}.

\FAILURE
Never fails.

\COMMENTS
This function used to take negation as an implication with {\small\verb%F%} conclusion.
This behaviour is implemented by the function {\small\verb%is_neg_imp%}.

\SEEALSO
mk_imp, dest_imp, dest_neg_imp, is_neg_imp.

\ENDDOC
\DOC{is\_infix}

\TYPE {\small\verb%is_infix : (string -> bool)%}\egroup

\SYNOPSIS
Determines whether an operator is infix.

\DESCRIBE
This predicate returns {\small\verb%true%} if the given string argument is the name of
an infix operator (a constant); it returns {\small\verb%false%} otherwise.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_infix `$+`;;
false : bool

#is_infix `+`;;
true : bool

#is_infix `SUC`;;
false : bool
\end{verbatim}
}
\SEEALSO
infixes, is_binder, is_constant.

\ENDDOC
\DOC{is\_infix\_type}

\TYPE {\small\verb%is_infix_type : (type -> bool)%}\egroup

\SYNOPSIS
Determines whether a given type is an appropriate infix type.

\DESCRIBE
The most general infix type is {\small\verb%":* -> (** -> ***)"%}. The function
{\small\verb%is_infix_type%} returns {\small\verb%true%} if the given type is an instance of the
most general infix type: it returns {\small\verb%false%} otherwise.

\FAILURE
Sometimes fails in a nasty way: e.g.,
{\par\samepage\setseps\small
\begin{verbatim}
   #is_infix_type ":(* -> **)";;
   evaluation failed     dest_type
\end{verbatim}
}
\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_infix_type ":*->**->***";;
true : bool

#is_infix_type ":bool->num->bool";;
true : bool

#is_infix_type ":(bool->bool)";;
false : bool

#is_infix_type ":bool";;
false : bool
\end{verbatim}
}
\SEEALSO
is_infix, is_type, is_binder_type

\ENDDOC
\DOC{isl}

\TYPE {\small\verb%isl : ((* + **) -> bool)%}\egroup

\SYNOPSIS
Tests for membership of left summand.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let x = inl 1 and y = inr 2;;

#isl x;;
true : bool

#isl y;;
false : bool
\end{verbatim}
}
\SEEALSO
inl, inr

\ENDDOC
\DOC{is\_let}

\TYPE {\small\verb%is_let : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a {\small\verb%let%}-expression.

\DESCRIBE
{\small\verb%is_let "LET f x"%} returns {\small\verb%true%}. If the term is not a {\small\verb%let%}-expression (or
of the more general {\small\verb%"LET f x"%} form) the result is {\small\verb%false%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_let "LET ($= 1) 2";;
true : bool

#is_let "let x = 2 in (x = 1)";;
true : bool
\end{verbatim}
}
\SEEALSO
mk_let, dest_let.

\ENDDOC
\DOC{is\_letter}

\TYPE {\small\verb%is_letter : (string -> bool)%}\egroup

\SYNOPSIS
Tests whether a character is a letter.

\DESCRIBE
When given a string, which should be of length 1, {\small\verb%is_letter%} returns
{\small\verb%true%} iff the character is a letter. By default this means what one
would expect, namely one of {\small\verb%a..z A..Z%}. However the scope of the
definition can be increased using {\small\verb%new_letter%}.

\FAILURE
Fails if the string has length greater than 1. Returns {\small\verb%false%} for the
null string ({\small\verb%``%}).

\SEEALSO
ascii, ascii_code, is_alphanum, new_alphanum, new_letter.

\ENDDOC
\DOC{is\_list}

\TYPE {\small\verb%is_list : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a list.

\DESCRIBE
{\small\verb%is_list%} returns {\small\verb%true%} of a term representing a list. Otherwise it returns
{\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_list, dest_list, mk_cons, dest_cons, is_cons.

\ENDDOC
\DOC{is\_ml\_curried\_infix}

\TYPE {\small\verb%is_ml_curried_infix : (string -> bool)%}\egroup

\SYNOPSIS
Tests whether a string is the name of a user-defined curried ML infix.

\DESCRIBE
{\small\verb%is_ml_curried_infix `string`%} returns {\small\verb%true%} if {\small\verb%string%} is the name of a
user-defined curried ML infix, and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\SEEALSO
is_ml_paired_infix, is_ml_infix, ml_curried_infix.

\ENDDOC
\DOC{is\_ml\_infix}

\TYPE {\small\verb%is_ml_infix : (string -> bool)%}\egroup

\SYNOPSIS
Tests whether a string is the name of an ML infix.

\DESCRIBE
{\small\verb%is_ml_infix `string`%} returns {\small\verb%true%} if {\small\verb%string%} is the name of a built-in
or user-defined ML infix, and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\SEEALSO
is_ml_paired_infix, is_ml_curried_infix, ml_paired_infix, ml_curried_infix.

\ENDDOC
\DOC{is\_ml\_paired\_infix}

\TYPE {\small\verb%is_ml_paired_infix : (string -> bool)%}\egroup

\SYNOPSIS
Tests whether a string is the name of a user-defined paired ML infix.

\DESCRIBE
{\small\verb%is_ml_paired_infix `string`%} returns {\small\verb%true%} if {\small\verb%string%} is the name of a
user-defined paired ML infix, and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\SEEALSO
is_ml_curried_infix, is_ml_infix, ml_paired_infix.

\ENDDOC
\DOC{is\_neg}

\TYPE {\small\verb%is_neg : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a negation.

\DESCRIBE
{\small\verb%is_neg "~t"%} returns {\small\verb%true%}. If the term is not a negation the result is
{\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_neg, dest_neg.

\ENDDOC
\DOC{is\_neg\_imp}

\TYPE {\small\verb%is_neg_imp : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is an implication or a negation.

\DESCRIBE
{\small\verb%is_neg_imp "t1 ==> t2"%} returns {\small\verb%true%}. {\small\verb%is_neg_imp "~t"%} returns {\small\verb%true%}.
If the term is neither an implication nor a negation the result is {\small\verb%false%}.

\FAILURE
Never fails.

\COMMENTS
Yields true of negations because {\small\verb%dest_neg_imp%} destructs negations (for
compatibility with PPLAMBDA code). This function used to be called {\small\verb%is_imp%}.

\SEEALSO
dest_neg_imp, is_imp, dest_imp.

\ENDDOC
\DOC{is\_pabs}

\TYPE {\small\verb%is_pabs : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a paired abstraction.

\DESCRIBE
{\small\verb%is_pabs "\(v1..(..)..vn). t"%} returns {\small\verb%true%}. If the term is not a paired
abstraction the result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_pabs, dest_pabs, is_abs, is_var, is_const, is_comb.

\ENDDOC
\DOC{is\_pair}

\TYPE {\small\verb%is_pair : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a pair.

\DESCRIBE
{\small\verb%is_pair "(t1,t2)"%} returns {\small\verb%true%}. If the term is not a pair the result is
{\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_pair, dest_pair.

\ENDDOC
\DOC{ISPEC}

\TYPE {\small\verb%ISPEC : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Specializes a theorem, with type instantiation if necessary.

\DESCRIBE
This rule specializes a quantified variable as does {\small\verb%SPEC%}; it differs
from it in also instantiating the type if needed:
{\par\samepage\setseps\small
\begin{verbatim}
     A |- !x:ty.tm
  -----------------------  ISPEC "t:ty'"
      A |- tm[t/x]
\end{verbatim}
}
\noindent (where {\small\verb%t%} is free for {\small\verb%x%} in {\small\verb%tm%}, and {\small\verb%ty'%} is an instance
of {\small\verb%ty%}).

\FAILURE
{\small\verb%ISPEC%} fails if the input theorem is not universally quantified, if
the type of the given term is not an instance of the type of the
quantified variable, or if the type variable is free in the
assumptions.

\SEEALSO
INST_TY_TERM, INST_TYPE, ISPECL, SPEC, match.

\ENDDOC
\DOC{ISPECL}

\TYPE {\small\verb%ISPECL : (term list -> thm -> thm)%}\egroup

\SYNOPSIS
Specializes a theorem zero or more times, with type instantiation if necessary.

\DESCRIBE
{\small\verb%ISPECL%} is an iterative version of {\small\verb%ISPEC%}
{\par\samepage\setseps\small
\begin{verbatim}
         A |- !x1...xn.t
   ----------------------------  ISPECL ["t1",...,"tn"]
    A |- t[t1,...tn/x1,...,xn]
\end{verbatim}
}
\noindent (where {\small\verb%ti%} is free for {\small\verb%xi%} in {\small\verb%tm%}).

\FAILURE
{\small\verb%ISPECL%} fails if the list of terms is longer than the number of
quantified variables in the term, if the type instantiation fails, or
if the type variable being instantiated is free in the assumptions.

\SEEALSO
INST_TYPE, INST_TY_TERM, ISPEC, MATCH, SPEC, SPECL.

\ENDDOC
\DOC{is\_pred}

\TYPE {\small\verb%is_pred : (term -> bool)%}\egroup

\SYNOPSIS
Determines whether the operator of a combination is a constant.

\DESCRIBE
The function {\small\verb%is_pred%} returns {\small\verb%true%} when applied to a term of the form {\small\verb%"c
tm"%} where {\small\verb%c%} is a constant. Otherwise it returns {\small\verb%false%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #is_pred "SUC 0";;
   true : bool
\end{verbatim}
}
\COMMENTS
This function may be reimplemented.

\SEEALSO
dest_pred

\ENDDOC
\DOC{is\_recording\_proof}

\TYPE {\small\verb%is_recording_proof : void -> bool%}\egroup


\SYNOPSIS
Get the current state of proof recorder.

\DESCRIBE
A proof is a list of inference steps. After the proof recorder is
enabled, every inference performed by the system is recorded and
cumulated in an internal buffer. When a proof is completed, the raw
records can then be processed and output to a disk file.

{\small\verb%is_recording_proof%} is a low level user function for managing the proof
recorder. It returns {\small\verb%true%} is the proof recording is currently enabled.
Otherwise, it returns {\small\verb%false%}.

\FAILURE
Never fail.

\COMMENTS
This function is used to implement higher level user functions for
recording proof in the library {\small\verb%record_proof%}. It is much more
convenient to use those functions than the low level functions
such as {\small\verb%is_recording_proof%} directly.

\SEEALSO
record_proof, RecordStep, get_steps, suspend_recording, resume_recording,
current_proof, current_proof_file,
new_proof_file, close_proof_file, begin_proof, end_proof,
TAC_PROOF, PROVE, prove, prove_thm.

\ENDDOC
\DOC{is\_select}

\TYPE {\small\verb%is_select : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a choice binding.

\DESCRIBE
{\small\verb%is_select "@var. t"%} returns {\small\verb%true%}. If the term is not an epsilon-term the
result is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_select, dest_select.

\ENDDOC
\DOC{is\_type}

\TYPE {\small\verb%is_type : (string -> bool)%}\egroup

\SYNOPSIS
Tests whether a string is the name of a type.

\DESCRIBE
{\small\verb%is_type `op`%} returns {\small\verb%true%} if {\small\verb%`op'%} is the name of a type or type operator
and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\SEEALSO
arity.

\ENDDOC
\DOC{is\_var}

\TYPE {\small\verb%is_var : (term -> bool)%}\egroup

\SYNOPSIS
Tests a term to see if it is a variable.

\DESCRIBE
{\small\verb%is_var "var:ty"%} returns {\small\verb%true%}. If the term is not a variable the result
is {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
mk_var, dest_var, is_const, is_comb, is_abs.

\ENDDOC
\DOC{is\_vartype}

\TYPE {\small\verb%is_vartype : (type -> bool)%}\egroup

\SYNOPSIS
Tests a type to see if it is a type variable.

\DESCRIBE
{\small\verb%is_vartype(":*...")%} returns {\small\verb%true%}. For types which are not type variables
it returns {\small\verb%false%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#is_vartype ":*test";;
true : bool

#is_vartype ":bool";;
false : bool

#is_vartype ":* -> bool";;
false : bool
\end{verbatim}
}
\SEEALSO
mk_vartype, dest_vartype.

\ENDDOC
\DOC{it}

\TYPE {\small\verb%it : (*)%}\egroup

\SYNOPSIS
Binds the value of the last expression evaluated at top level.

\DESCRIBE
The identifier {\small\verb%it%} is bound to the value of the last expression evaluated
at top level. Declarations do not effect the value of {\small\verb%it%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#2 + 3;;
5 : int

#let x = 2*3;;
x = 6 : int

#it;;
5 : int
\end{verbatim}
}
\USES
Used in evaluating expressions that require the value of the last evaluated
expression.

\ENDDOC
\DOC{itlist2}

\TYPE {\small\verb%itlist2 : (((* # **) -> *** -> ***) -> (* list # ** list) -> *** -> ***)%}\egroup

\SYNOPSIS
Applies a paired function between adjacent elements of 2 lists.

\DESCRIBE
{\small\verb%itlist2 f ([x1;...;xn],[y1;...;yn]) z%} returns
{\par\samepage\setseps\small
\begin{verbatim}
   f (x1,y1) (f (x2,y2) ... (f (xn,yn) z)...)
\end{verbatim}
}
\noindent It returns {\small\verb%z%} if both lists are empty.

\FAILURE
Fails with {\small\verb%itlist2%} if the two lists are of different lengths.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#itlist2 (\(x,y) z. (x * y) + z) ([1;2],[3;4]) 0;;
11 : int
\end{verbatim}
}
\SEEALSO
itlist, rev_itlist, end_itlist, uncurry.

\ENDDOC
\DOC{itlist}

\TYPE {\small\verb%itlist : ((* -> ** -> **) -> * list -> ** -> **)%}\egroup

\SYNOPSIS
List iteration function. Applies a binary function between adjacent elements
of a list.

\DESCRIBE
{\small\verb%itlist f [x1;...;xn] y%} returns
{\par\samepage\setseps\small
\begin{verbatim}
   f x1 (f x2 ... (f xn y)...)
\end{verbatim}
}
\noindent It returns {\small\verb%y%} if list is empty.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#itlist (\x y. x + y) [1;2;3;4] 0;;
10 : int
\end{verbatim}
}
\SEEALSO
rev_itlist, end_itlist.

\ENDDOC
\DOC{K}

\TYPE {\small\verb%K : (* -> ** -> *)%}\egroup

\SYNOPSIS
Forms a constant function: {\small\verb%(K x) y%} = {\small\verb%x%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, CB, Co, I, KI, o, oo, S, W.

\ENDDOC
\DOC{KI}

\TYPE {\small\verb%KI : (* -> ** -> **)%}\egroup

\SYNOPSIS
Maps a value to the identity function: {\small\verb%(KI x) y%} = {\small\verb%y%}.

\COMMENTS
This is the combinator dual to {\small\verb%K%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, CB, Co, I, K, o, oo, S, W.

\ENDDOC
\DOC{LAST\_CONV}

\TYPE {\small\verb%LAST_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of taking the last element of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...x(n-1)]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   LAST_CONV "LAST [x0;...;x(n-1)]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- LAST [x0;...;x(n-1)] = x(n-1)
\end{verbatim}
}


\FAILURE
{\small\verb%LAST_CONV tm%} fails if {\small\verb%tm%} is an empty list.

\ENDDOC

\DOC{last}

\TYPE {\small\verb%last : (* list -> *)%}\egroup

\SYNOPSIS
Computes the last element of a list.

\DESCRIBE
{\small\verb%last [x1;...;xn]%} returns {\small\verb%xn%}.

\FAILURE
Fails with {\small\verb%last%} if the list is empty.

\SEEALSO
butlast, hd, tl, el, null.

\ENDDOC
\DOC{LASTN\_CONV}

\TYPE {\small\verb%LASTN_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of taking the last n elements of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...x(n-k);...;x(n-1)]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   LASTN_CONV "LASTN k [x0;...x(n-k);...;x(n-1)]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- LASTN k [x0;...;x(n-k);...;x(n-1)] = [x(n-k);...;x(n-1)]
\end{verbatim}
}


\FAILURE
{\small\verb%LASTN_CONV tm%} fails if {\small\verb%tm%} is not of the form described above, 
or {\small\verb%k%} is greater than the length of the list.

\ENDDOC

\DOC{LEFT\_AND\_EXISTS\_CONV}

\TYPE {\small\verb%LEFT_AND_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification of the left conjunct outwards through a
conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(?x.P) /\ Q%}, the conversion
{\small\verb%LEFT_AND_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x.P) /\ Q = (?x'. P[x'/x] /\ Q)
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%(?x.P) /\ Q%}.

\SEEALSO
AND_EXISTS_CONV, EXISTS_AND_CONV, RIGHT_AND_EXISTS_CONV.

\ENDDOC
\DOC{LEFT\_AND\_FORALL\_CONV}

\TYPE {\small\verb%LEFT_AND_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification of the left conjunct outwards through a
conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(!x.P) /\ Q%}, the conversion
{\small\verb%LEFT_AND_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x.P) /\ Q = (!x'. P[x'/x] /\ Q)
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%(!x.P) /\ Q%}.

\SEEALSO
AND_FORALL_CONV, FORALL_AND_CONV, RIGHT_AND_FORALL_CONV.

\ENDDOC
\DOC{LEFT\_IMP\_EXISTS\_CONV}

\TYPE {\small\verb%LEFT_IMP_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification of the antecedent outwards through an
implication.

\DESCRIBE
When applied to a term of the form {\small\verb%(?x.P) ==> Q%}, the conversion
{\small\verb%LEFT_IMP_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x.P) ==> Q = (!x'. P[x'/x] ==> Q)
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%(?x.P) ==> Q%}.

\SEEALSO
FORALL_IMP_CONV, RIGHT_IMP_FORALL_CONV.

\ENDDOC
\DOC{LEFT\_IMP\_FORALL\_CONV}

\TYPE {\small\verb%LEFT_IMP_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification of the antecedent outwards through an
implication.

\DESCRIBE
When applied to a term of the form {\small\verb%(!x.P) ==> Q%}, the conversion
{\small\verb%LEFT_IMP_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x.P) ==> Q = (?x'. P[x'/x] ==> Q)
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%(!x.P) ==> Q%}.

\SEEALSO
EXISTS_IMP_CONV, RIGHT_IMP_FORALL_CONV.

\ENDDOC
\DOC{LEFT\_OR\_EXISTS\_CONV}

\TYPE {\small\verb%LEFT_OR_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification of the left disjunct outwards through a
disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(?x.P) \/ Q%}, the conversion
{\small\verb%LEFT_OR_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x.P) \/ Q = (?x'. P[x'/x] \/ Q)
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%(?x.P) \/ Q%}.

\SEEALSO
EXISTS_OR_CONV, OR_EXISTS_CONV, RIGHT_OR_EXISTS_CONV.

\ENDDOC
\DOC{LEFT\_OR\_FORALL\_CONV}

\TYPE {\small\verb%LEFT_OR_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification of the left disjunct outwards through a
disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(!x.P) \/ Q%}, the conversion
{\small\verb%LEFT_OR_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x.P) \/ Q = (!x'. P[x'/x] \/ Q)
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%(!x.P) \/ Q%}.

\SEEALSO
OR_FORALL_CONV, FORALL_OR_CONV, RIGHT_OR_FORALL_CONV.

\ENDDOC
\DOC{LENGTH\_CONV}

\TYPE {\small\verb%LENGTH_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the length of an object-language list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x1;x2;...;xn]"%}, where {\small\verb%x1%},
{\small\verb%x2%}, ..., {\small\verb%xn%} are arbitrary terms of the same type, the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   LENGTH_CONV "LENGTH [x1;x2;...;xn]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- LENGTH [x1;x2;...;xn] = n
\end{verbatim}
}
\noindent where {\small\verb%n%} is the numeral constant that denotes the length of the
list.

\FAILURE
{\small\verb%LENGTH_CONV tm%} fails if {\small\verb%tm%} is not of the form {\small\verb%"LENGTH [x1;x2;...;xn]"%} or
{\small\verb%"LENGTH []"%}.

\ENDDOC
\DOC{length}

\TYPE {\small\verb%length : (* list -> int)%}\egroup

\SYNOPSIS
Computes the length of a list: {\small\verb%length [x1;...;xn]%} returns {\small\verb%n%}.

\FAILURE
Never fails.

\ENDDOC
\DOC{let\_after}

\TYPE {\small\verb%let_after : ((string # string # string list) -> void)%}\egroup

\SYNOPSIS
Makes an ML declaration dynamically after other pending declarations.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   let_after(`x`,`f`,[`arg1`;...;`argn`])
\end{verbatim}
}
\noindent puts an ML declaration
{\par\samepage\setseps\small
\begin{verbatim}
   let x = f [`arg1`;...;`argn`];;
\end{verbatim}
}
\noindent at the end of the queue of currently pending toplevel items. It will
be evaluated after the phrase which invoked {\small\verb%let_after%}, and any other pending
evaluations. This gives a way of performing declarations dynamically. Note that
the first two argument strings are interpreted as single identifiers, whereas
the arguments are passed as literal strings.

\FAILURE
Never fails, although the subsequent declaration may well fail for any of the
usual reasons.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let fn = \l:(string)list. 1;;
fn = - : (string list -> int)

#let_after(`x`,`fn`,[]);;
() : void

x = 1 : int

#x;;
1 : int
\end{verbatim}
}
\USES
Performing variants on autoloading.

\SEEALSO
inject_input, let_before, ML_eval.

\ENDDOC
\DOC{let\_before}

\TYPE {\small\verb%let_before : ((string # string # string list) -> void)%}\egroup

\SYNOPSIS
Makes an ML declaration dynamically before other pending declarations.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   let_before(`x`,`f`,[`arg1`;...;`argn`])
\end{verbatim}
}
\noindent puts an ML declaration
{\par\samepage\setseps\small
\begin{verbatim}
   let x = f [`arg1`;...;`argn`];;
\end{verbatim}
}
\noindent at the head of the queue of currently pending toplevel items. It will
be evaluated after the phrase which invoked {\small\verb%let_before%}. This gives a way of
performing declarations dynamically. Note that the first two argument strings
are interpreted as single identifiers, whereas the arguments are passed as
literal strings.

\FAILURE
Never fails, although the subsequent declaration may well fail for any of the
usual reasons.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let fn = \l:(string)list. 1;;
fn = - : (string list -> int)

#let_before(`x`,`fn`,[]);;
() : void

x = 1 : int

#x;;
1 : int
\end{verbatim}
}
\USES
Performing variants on autoloading.

\SEEALSO
inject_input, let_after, ML_eval.

\ENDDOC
\DOC{let\_CONV}

\TYPE {\small\verb%let_CONV : conv%}\egroup

\SYNOPSIS
Evaluates {\small\verb%let%}-terms in the HOL logic.

\DESCRIBE
The conversion {\small\verb%let_CONV%} implements evaluation of object-language {\small\verb%let%}-terms.
When applied to a {\small\verb%let%}-term of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   let v1 = t1 and ... and vn = tn in t
\end{verbatim}
}
\noindent where {\small\verb%v1%}, ..., {\small\verb%vn%} are variables, {\small\verb%let_CONV%} proves and returns
the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (let v1 = t1 and ... and vn = tn in t) = t[t1,...,tn/v1,...,vn]
\end{verbatim}
}
\noindent where {\small\verb%t[t1,...,tn/v1,...,vn]%} denotes the result of substituting
{\small\verb%ti%} for {\small\verb%v1%} in parallel in {\small\verb%t%}, with automatic renaming of bound variables
to prevent free variable capture.

{\small\verb%let_CONV%} also works on {\small\verb%let%}-terms that bind tuples of variables to tuples of
values.  That is, if {\small\verb%<tup>%} is an arbitrarily-nested tuple of distinct
variables {\small\verb%v1%}, ..., {\small\verb%vn%} and {\small\verb%<val>%} is a structurally similar tuple of
values, that is {\small\verb%<val>%} equals {\small\verb%<tup>[t1,...,tn/v1,...,vn]%} for some terms
{\small\verb%t1%}, ..., {\small\verb%tn%}, then:
{\par\samepage\setseps\small
\begin{verbatim}
   let_CONV "let <tup> = <val> in t"
\end{verbatim}
}
\noindent returns
{\par\samepage\setseps\small
\begin{verbatim}
  |- (let <tup> = <val> in t) = t[t1,...,tn/v1,...,vn]
\end{verbatim}
}
\noindent That is, the term {\small\verb%ti%} is substituted for the corresponding variable
{\small\verb%vi%} in {\small\verb%t%}.  This form of {\small\verb%let%}-reduction also works with simultaneous binding
of tuples using {\small\verb%and%}.

Finally, {\small\verb%let_CONV%} also handles {\small\verb%let%}-terms that introduce local definitions
of functions. When applied to a term of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   "let f v1 ... vn = tm in t"
\end{verbatim}
}
\noindent {\small\verb%let_CONV%} returns:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (let f v1 ... vn = tm in t) = t'
\end{verbatim}
}
\noindent where {\small\verb%t'%} is obtained by rewriting all applications of the function
{\small\verb%f%} in {\small\verb%t%} using the defining equation {\small\verb%f v1 ... vn = tm%}. Partial applications
of the form {\small\verb%f x1 ... xm%} where {\small\verb%m%} is less that {\small\verb%n%} are rewritten to
lambda-abstractions (see the example given below).  Simultaneous introduction
of functions using {\small\verb%and%} is handled, and each of {\small\verb%v1%}, ..., {\small\verb%vn%} in the pattern
shown above can be either a variable or a tuple of variables.

\FAILURE
{\small\verb%let_CONV tm%} fails if {\small\verb%tm%} is not a reducible {\small\verb%let%}-term of one of the forms
specified above.

\EXAMPLE
A simple example of the use of {\small\verb%let_CONV%} to eliminate a single local variable
is the following:
{\par\samepage\setseps\small
\begin{verbatim}
   #let_CONV "let x = 1 in x+y";;
   |- (let x = 1 in x + y) = 1 + y
\end{verbatim}
}
\noindent and an example showing a tupled binding is:
{\par\samepage\setseps\small
\begin{verbatim}
   #let_CONV "let (x,y) = (1,2) in x+y";;
   |- (let (x,y) = 1,2 in x + y) = 1 + 2
\end{verbatim}
}
\noindent Simultaneous introduction of two local functions {\small\verb%f%} and {\small\verb%g%}
and rewriting is illustrated by:
{\par\samepage\setseps\small
\begin{verbatim}
   #let_CONV "let f x = x + 1 and g x = x + 2 in !x. g(f(g x)) = x + 5";;
   |- (let f x = x + 1 and g x = x + 2 in (!x. g(f(g x)) = x + 5)) =
      (!x. ((x + 2) + 1) + 2 = x + 5)
\end{verbatim}
}
\noindent and an example of partial application is:
{\par\samepage\setseps\small
\begin{verbatim}
   #let_CONV "let f x y = x+y in f 1";;
   |- (let f x y = x + y in f 1) = (\y. 1 + y)
\end{verbatim}
}
\noindent Note the introduction of a lambda-abstraction in the result.

\SEEALSO
BETA_CONV, PAIRED_BETA_CONV.

\ENDDOC
\DOC{lhs}

\TYPE {\small\verb%lhs : (term -> term)%}\egroup

\SYNOPSIS
Returns the left-hand side of an equation.

\DESCRIBE
{\small\verb%lhs "t1 = t2"%} returns {\small\verb%"t1"%}.

\FAILURE
Fails with {\small\verb%lhs%} if the term is not an equation.

\SEEALSO
rhs, dest_eq.

\ENDDOC
\DOC{libraries}

\TYPE {\small\verb%libraries : (void -> string list)%}\egroup

\SYNOPSIS
Evaluating {\small\verb%libraries()%} returns a list of the libraries that have been
successfully loaded during the current session.

\FAILURE
Never fails.

\SEEALSO
library_pathname, load_library.

\ENDDOC
\DOC{library\_loader}

{\small
\begin{verbatim}
library_loader : ((string # string list # string list #
    string list # string # string # string list) -> void)
\end{verbatim}
}\egroup

\SYNOPSIS
Performs the actual loading of a library.

\DESCRIBE
This function is a generic library loader which carries out the
standard loading procedures for loading library. This provides a
simple interface for library authors to write the library load file.
A library consists of three parts: theories, codes and document. Any
of these may be absent (however, it is strongly recommanded to provide
proper document for all libraries). The standard procedures of loading
a library are:
    1) update the system search path to include the library directory;
    2) load any libraries on which the current library depends;
    3) load the theories (if there are any);
    4) load the codes (if there are any);
    5) update the help search path to include the current library document;
    6) set up auto-loading of theorems, definitions, etc.

When a library, say {\small\verb%foo%}, is loaded into a HOL session by evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   load_library `foo`;;
\end{verbatim}
}
\noindent the system will load a file named `{\small\verb%foo.ml%}' in the directory
`{\small\verb%foo%}' which is in the library search path. The generic library
loader {\small\verb%library_loader%} should be called with appropriate arguments
in this file. In addition to the standard loading procedures, extra
functions may be called in this file to set up special environment
necessary for working with the library.

The function {\small\verb%library_loader%} takes a 6-tuple
{\par\samepage\setseps\small
\begin{verbatim}
   (lib_name, parent_libs, theories, codes, load_parent, part_path, help_paths)
\end{verbatim}
}
\noindent as its argument. The meanings of the fields are described below.
 {\small\verb%lib_name : string%} is the name of the library. It should be the name
    of the directory where the library is found, and the basename of
    the load file.
 {\small\verb%parent_libs : string list%} are the names of the libraries on which the
    current library depends. They will be loaded in the order given
    before the theories and codes of the current library are loaded.
 {\small\verb%theories : string list%} are the names of the theories in this
    library. If the library contains more than one theory, the
    descendant of all other theories should be the first in the list.
    This theory will be loaded and it becomes the current theory or the new
    parent of the current theory depending on whether the system is in
    draft mode. If we are not in draft mode and this theory is not an
    ancestor of the current theory, it will not be loaded. Instead, a
    function whose name is created by prefixing the string {\small\verb%load_%} to
    the name of the library is defined. This may be called later to
    complete the loading of the library. The order of other names is
    not important. The axioms, definitions and theorems in all the
    theories listed are set up to be autoloaded. If there is no theory
    in the library, this field should be a null list.
  {\small\verb%codes : string list%} are the names of the code files. They will be
    loaded in the order given after loading the first theory in
    {\small\verb%theories%}. If there is no code files in the library, this field should
    be a null list.
  {\small\verb%load_parent : string%} is the name of a file to be loaded before the
    code files are loaded. If we are not currently in draft mode, the
    parent libraries may not be loaded completely. Instead, functions
    having name prefixed by {\small\verb%load_%} will be defined. If the codes of
    the current theory depend on the parent libraries, these loading
    functions should be called before loading the codes. A file
    containing the calls of the loading functions and possibly other
    neccessory functions to set up the working environment will be
    loaded. The name of this file is given in this field.
  {\small\verb%part_path : string%} is the directory name of the library part. If
    only part of the library is to be loaded, the string {\small\verb%lib_name%} should have
    the part separator {\small\verb%:%} in it, e.g. {\small\verb%`lib:part`%}. It such case, the
    files of the library part may reside in a sub-directory. The name of
    this sub-directory is specified by this field, and it is added to
    the search path.
  {\small\verb%help_paths : string list%} are the names of directories containing the
    help files. These are relative to the subdirectory `help` of the
    library. They are added to the {\small\verb%help_search_path%}.

\FAILURE
It fails if any parent libraries, theories or files cannot be loaded.

\EXAMPLE
Suppose the the name of the library is {\small\verb%mylib%}. It depends on the
libraries {\small\verb%lib1%} and {\small\verb%lib2%}, and it consists of two theories {\small\verb%thy1%}
and {\small\verb%thy2%}, and a single code file {\small\verb%mylib_convs.ml%}. A load file for
this library will be as below:
{\par\samepage\setseps\small
\begin{verbatim}
   let this_lib_name = `mylib`
   and parent_libs = [`lib1`; `lib2`]
   and theories = [`thy2`; `thy1`]
   and codes = [`mylib_convs`]
   and load_parent = `load_parent`
   and part_path = ``
   and help_paths = [`entries`]
   in
   library_loader (this_lib_name, parent_libs, theories, codes,
    load_parent, part_path, help_paths);;
\end{verbatim}
}
\noindent If both of the libraries {\small\verb%lib1%} and {\small\verb%lib2%} have theories and they are
independent, and if the library {\small\verb%mylib%} is loaded when we are not in
draft mode, a function for loading the second parent {\small\verb%lib2%}, namely
{\small\verb%load_lib2%},  will be defined. This should be called in the file
{\small\verb%load_parent.ml%} to complete the loading of {\small\verb%lib2%}.

\USES
This function is primarily used in library load files. The user
function for loading a library is {\small\verb%load_library%}.

\SEEALSO 
library_pathname, load_library, set_library_search_path,
define_load_lib_function.

\ENDDOC
\DOC{library\_pathname}

\TYPE {\small\verb%library_pathname : (void -> string)%}\egroup

\SYNOPSIS
Returns the pathname to the current library directory.

\DESCRIBE
Evaluating {\small\verb%library_pathname()%} returns a string giving the root pathname of
the current library directory.  Usually, this is just the absolute pathname 
to the HOL system library.  But during the evaluation of a call to
{\small\verb%load_library%}, the string returned by {\small\verb%library_pathname()%} is the library
directory in which the library being loaded resides.

\FAILURE
Never fails.

\EXAMPLE
A very typical application is illustrated by the following code from the
load file for the built-in {\small\verb%string%} library:
{\par\samepage\setseps\small
\begin{verbatim}
   let path = library_pathname() ^ `/string/` in
       set_search_path (union (search_path()) [path]);;
\end{verbatim}
}
\noindent When the {\small\verb%string%} library load file is loaded using {\small\verb%load_library%},
this part of the code adds the pathname to the {\small\verb%string%} library to the internal
HOL search path.

\USES
The main purpose of the function {\small\verb%library_pathname%} is to allow library
load files to update the internal HOL search paths in a site-independent way.

\SEEALSO
install, library_search_path, set_library_search_path.

\ENDDOC
\DOC{library\_search\_path}

\TYPE {\small\verb%library_search_path : (void -> string list)%}\egroup

\SYNOPSIS
Returns the internal search path use by HOL to find libraries.

\DESCRIBE
Evaluating {\small\verb%library_search_path()%} returns a list of strings representing the
pathnames of the directories that are searched when the {\small\verb%load_library%} function
searches for libraries. Although the library search path can be set to an
arbitrary list of strings, each string is normally expected to be a pathname
with `{\small\verb%/%}' as its final character.  When {\small\verb%load_library%} looks for a library
load file, the directories in the library search path are searched in the order
in which they occur in the list returned by {\small\verb%library_search_path%}.

\FAILURE
Never fails.

\SEEALSO 
library_pathname, load_library, set_library_search_path.

\ENDDOC
\DOC{link}

\TYPE {\small\verb%link : ((string # string) -> void)%}\egroup

\SYNOPSIS
Makes a new link to a file.

\DESCRIBE
If {\small\verb%old%} and {\small\verb%new%} are filenames, where {\small\verb%old%} exists and {\small\verb%new%} does not, then
the call
{\par\samepage\setseps\small
\begin{verbatim}
   link(`old`,`new`)
\end{verbatim}
}
\noindent will link the name {\small\verb%new%} to the file {\small\verb%old%} in the manner of the Unix
shell command
{\par\samepage\setseps\small
\begin{verbatim}
   ln old new
\end{verbatim}
}
\FAILURE
A call to {\small\verb%link%} may fail in various system-related ways, in particular if
{\small\verb%old%} does not exist, or is a directory, or {\small\verb%new%} already exists.

\EXAMPLE
The following example is assumed to be run under Unix:
{\par\samepage\setseps\small
\begin{verbatim}
   #system `touch test-file`;;
   0 : int

   #link(`test-file`,`test-link`);;
   () : void
\end{verbatim}
}
\COMMENTS
This call is somewhat Unix-related, and may not work under other operating
systems.

\SEEALSO
system, unlink.

\ENDDOC
\DOC{lisp\_dir\_pathname}

\TYPE {\small\verb%lisp_dir_pathname : string%}\egroup

\SYNOPSIS
Absolute pathname to the HOL lisp sources.

\DESCRIBE
For implementation reasons, the ML variable {\small\verb%lisp_dir_pathname%} is bound when
the system if built to a string giving the absolute pathname of the directory
containing the HOL lisp sources.  This value is not for general use.

\FAILURE
Evaluating {\small\verb%lisp_dir_pathname%} never fails.

\SEEALSO
ml_dir_pathname.

\ENDDOC
\DOC{lisp}

\TYPE {\small\verb%lisp : (string -> void)%}\egroup

\SYNOPSIS
Executes a lisp command from ML.

\DESCRIBE
{\small\verb%lisp%} executes a lisp s-expression (written as an ML string).  Returned
values do not appear on the standard output, unless they are explicitly
printed.

\FAILURE
Fails if the s-expression is improperly constructed or fails when
evaluated by lisp.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#lisp `(princ "hello")`;;
hello() : void

#lisp `(cons 'a 'b)`;;
() : void

#lisp `(princ (cons 'a 'b))`;;
(A . B)() : void

#lisp `(car 'a)`;;
Error: Attempt to take the car of A which is not a cons.
evaluation failed     lisp -- NIL

#lisp `(princ "hello"`;;
Error: eof encountered on input stream #<string input stream  @ #x869fe6>
evaluation failed     lisp -- NIL
\end{verbatim}
}
\COMMENTS
{\small\verb%lisp%} is not meant for general use, and should be treated with great
care.  If one is not wary, it is entirely possible to corrupt HOL by
using it.

\SEEALSO
dropout, lsp.

\ENDDOC
\DOC{LIST\_BETA\_CONV}

\TYPE {\small\verb%LIST_BETA_CONV : conv%}\egroup

\SYNOPSIS
Performs an iterated beta conversion.

\DESCRIBE
The conversion {\small\verb%LIST_BETA_CONV%} maps terms of the form
{\par\samepage\setseps\small
\begin{verbatim}
   "(\x1 x2 ... xn. u) v1 v2 ... vn"
\end{verbatim}
}
\noindent to the theorems of the form
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\x1 x2 ... xn. u) v1 v2 ... vn = u[v1/x1][v2/x2] ... [vn/xn]
\end{verbatim}
}
\noindent where {\small\verb%u[vi/xi]%} denotes the result of substituting {\small\verb%vi%} for all free
occurrences of {\small\verb%xi%} in {\small\verb%u%}, after renaming sufficient bound variables to avoid
variable capture.

\FAILURE
{\small\verb%LIST_BETA_CONV tm%} fails if {\small\verb%tm%} does not have the form
{\small\verb%"(\x1 ... xn. u) v1 ... vn"%} for {\small\verb%n%} greater than 0.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#LIST_BETA_CONV "(\x y. x+y) 1 2";;
|- (\x y. x + y)1 2 = 1 + 2
\end{verbatim}
}
\SEEALSO
BETA_CONV, BETA_RULE, BETA_TAC, RIGHT_BETA, RIGHT_LIST_BETA.

\ENDDOC
\DOC{LIST\_CONJ}

\TYPE {\small\verb%LIST_CONJ : (thm list -> thm)%}\egroup

\SYNOPSIS
Conjoins the conclusions of a list of theorems.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
         A1 |- t1 ... An |- tn
   ----------------------------------  LIST_CONJ
    A1 u ... u An |- t1 /\ ... /\ tn
\end{verbatim}
}
\FAILURE
{\small\verb%LIST_CONJ%} will fail with {\small\verb%`end_itlist`%} if applied to an empty list
of theorems.

\COMMENTS
The system shows the type as {\small\verb%proof%}.

{\small\verb%LIST_CONJ%} does not check for alpha-equivalence of assumptions when forming
their union. If a particular assumption is duplicated within one of the input
theorems assumption lists, then it may be duplicated in the resulting
assumption list.

\SEEALSO
BODY_CONJUNCTS, CONJ, CONJUNCT1, CONJUNCT2, CONJUNCTS, CONJ_PAIR, CONJ_TAC.

\ENDDOC
\DOC{list\_EQ\_CONV}

\TYPE {\small\verb%list_EQ_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Prove equality or inequality of two lists.

\DESCRIBE
{\small\verb%list_EQ_CONV c%} implements a decision procedure for equality of lists of type
{\small\verb%(ty)list%} where the conversion {\small\verb%c%} decides equality of values of type {\small\verb%ty%}.
More precisely, the argument to {\small\verb%list_EQ_CONV%} is expected to be a conversion
{\small\verb%c%} which implements a decision procedure for values of some base type {\small\verb%ty%}, in
the sense that {\small\verb%c "t1 = t2"%} returns {\small\verb%|- (t1 = t2) = T%} if {\small\verb%t1%} denotes the
same value as {\small\verb%t2%} and {\small\verb%|- (t1 = t2) = F%} if {\small\verb%t1%} and {\small\verb%t2%} denote different
values.  Given such a conversion {\small\verb%c%}, evaluating:
{\par\samepage\setseps\small
\begin{verbatim}
   list_EQ_CONV c "[t1;...;tn] = [u1;...;um]"
\end{verbatim}
}
\noindent where all the {\small\verb%ti%} and {\small\verb%ui%} have type {\small\verb%ty%}, returns:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ([t1;...;tn] = [u1;...;um]) = F
\end{verbatim}
}
\noindent if {\small\verb%n%} is not equal to {\small\verb%m%} (i.e. if the two lists have different
lengths) or if {\small\verb%n%} = {\small\verb%m%} and the conversion {\small\verb%c%} proves {\small\verb%|- (ti = ui) = F%} for
some {\small\verb%i%} between {\small\verb%1%} and {\small\verb%n%}. The theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ([t1;...;tn] = [u1;...;um]) = T
\end{verbatim}
}
\noindent is returned if {\small\verb%n%} equals {\small\verb%m%} and for all {\small\verb%i%} from {\small\verb%1%} to {\small\verb%n%} either
{\small\verb%ti%} is syntactically identical to {\small\verb%ui%} or {\small\verb%c%} proves {\small\verb%|- (ti = ui) = T%}

\FAILURE
{\small\verb%list_EQ_CONV t%} fails if {\small\verb%t%} is not a term of the form
{\small\verb%"[t1;...;tn] = [u1;...;um]"%}, or if {\small\verb%n%} equals {\small\verb%m%} and some {\small\verb%ti%} is not
syntactically identical to {\small\verb%ui%} but {\small\verb%c%} fails to prove either of the
theorems {\small\verb%|- (ti = ui) = T%} or {\small\verb%|- (ti = ui) = F%} when applied to {\small\verb%"ti = ui"%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_EQ_CONV num_EQ_CONV "[1;SUC 1;3] = [1;2;3]";;
|- ([1;SUC 1;3] = [1;2;3]) = T
\end{verbatim}
}
\ENDDOC
\DOC{list\_FOLD\_CONV}

\TYPE {\small\verb%list_FOLD_CONV : thm -> conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a function to elements of a list.

\DESCRIBE
Evaluating {\small\verb%list_FOLD_CONV fthm conv tm%} returns a theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- CONST x0' ... xi' ... xn' = tm'
\end{verbatim}
}
\noindent The first argument {\small\verb%fthm%} should be a theorem of the form
{\par\samepage\setseps\small
\begin{verbatim}
  |- !x0 ... xi ... xn. CONST x0 ... xi ... xn = FOLD[LR] f e xi
\end{verbatim}
}
\noindent where {\small\verb%FOLD[LR]%} means either {\small\verb%FOLDL%} or {\small\verb%FOLDR%}. The last
argument {\small\verb%tm%} is a term of the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   CONST x0' ... xi' ... xn'
\end{verbatim}
}
\noindent where {\small\verb%xi'%} is a concrete list. {\small\verb%list_FOLD_CONV%} first
instantiates the input theorem using {\small\verb%tm%}. It then calls either
{\small\verb%FOLDL_CONV%} or {\small\verb%FOLDR_CONV%} with the user supplied conversion {\small\verb%conv%}
on the right-hand side.

\FAILURE
{\small\verb%list_FOLD_CONV fthm conv tm%} fails if {\small\verb%fthm%} or {\small\verb%tm%} is not of the
form described above, or if they do not agree, or the call to
{\small\verb%FOLDL_CONV%} OR {\small\verb%FOLDR_CONV%} fails.

\USES
This function is used to implement conversion for logical constants
which can be expressed in terms of the fold operators. For example,
the constant {\small\verb%SUM%} can be expressed in terms of {\small\verb%FOLDR%} as in the
following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
  |- !l. SUM l = FOLDR $+ 0 l
\end{verbatim}
}
\noindent A conversion for {\small\verb%SUM%} can be implemented as 
{\par\samepage\setseps\small
\begin{verbatim}
   let SUM_CONV =
      list_FOLD_CONV (theorem `list` `SUM_FOLDR`) ADD_CONV;;
\end{verbatim}
}
\noindent Then, evaluating {\small\verb%SUM_CONV "SUM [0;1;2;3]"%} will return
the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- SUM [0;1;2;3] = 6
\end{verbatim}
}

\SEEALSO
FOLDL_CONV, FOLDR_CONV.

\ENDDOC

\DOC{LIST\_INDUCT}

\TYPE {\small\verb%LIST_INDUCT : ((thm # thm) -> thm)%}\egroup

\SYNOPSIS
Performs proof by structural induction on lists.

\DESCRIBE
The derived inference rule {\small\verb%LIST_INDUCT%} implements the rule of mathematical
induction:
{\par\samepage\setseps\small
\begin{verbatim}
     A1 |- P[NIL/l]      A2 |- !t. P[t/l] ==> !h. P[CONS h t/l]
    ------------------------------------------------------------  LIST_INDUCT
                      A1 u A2 |- !l. P
\end{verbatim}
}
\noindent When supplied with a theorem {\small\verb%A1 |- P[NIL]%}, which asserts the base
case of a proof of the proposition {\small\verb%P[l]%} by structural induction on the list
{\small\verb%l%}, and the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   A2 |- !t. P[t] ==> !h. P[CONS h t]
\end{verbatim}
}
\noindent which asserts the step case in the induction on {\small\verb%l%}, the inference
rule {\small\verb%LIST_INDUCT%} returns {\small\verb%A1 u A2 |- !l. P[l]%}.

\FAILURE
{\small\verb%LIST_INDUCT th1 th2%} fails if the theorems {\small\verb%th1%} and {\small\verb%th2%} do not have the
forms {\small\verb%A1 |- P[NIL]%} and {\small\verb%A2 |- !t. P[t] ==> !h. P[CONS h t]%} respectively
(where the empty list {\small\verb%NIL%} in {\small\verb%th1%} and the list {\small\verb%CONS h t%} in {\small\verb%th2%} have
the same type).

\SEEALSO
LIST_INDUCT_TAC.

\ENDDOC
\DOC{LIST\_INDUCT\_TAC}

\TYPE {\small\verb%LIST_INDUCT_TAC : tactic%}\egroup

\SYNOPSIS
Performs tactical proof by structural induction on lists.

\DESCRIBE
{\small\verb%LIST_INDUCT_TAC%} reduces a goal {\small\verb%!l.P[l]%}, where {\small\verb%l%} ranges over lists, to two
subgoals corresponding to the base and step cases in a proof by structural
induction on {\small\verb%l%}. The induction hypothesis appears among the assumptions of the
subgoal for the step case.  The specification of {\small\verb%LIST_INDUCT_TAC%} is:
{\par\samepage\setseps\small
\begin{verbatim}
                     A ?- !l. P
   =====================================================  LIST_INDUCT_TAC
    A |- P[NIL/l]   A u {P[l'/l]} ?- !h. P[CONS h l'/l]
\end{verbatim}
}
\noindent where {\small\verb%l'%} is a primed variant of {\small\verb%l%} that does not appear free in
the assumptions {\small\verb%A%} (usually, {\small\verb%l'%} is just {\small\verb%l%}). When {\small\verb%LIST_INDUCT_TAC%} is
applied to a goal of the form {\small\verb%!l.P%}, where {\small\verb%l%} does not appear free in {\small\verb%P%},
the subgoals are just {\small\verb%A ?- P%} and {\small\verb%A u {P} ?- !h.P%}.

\FAILURE
{\small\verb%LIST_INDUCT_TAC g%} fails unless the conclusion of the goal {\small\verb%g%} has the form
{\small\verb%!l.t%}, where the variable {\small\verb%l%} has type {\small\verb%(ty)list%} for some type {\small\verb%ty%}.

\SEEALSO
LIST_INDUCT.

\ENDDOC
\DOC{list\_mk\_abs}

\TYPE {\small\verb%list_mk_abs : ((term list # term) -> term)%}\egroup

\SYNOPSIS
Iteratively constructs abstractions.

\DESCRIBE
{\small\verb%list_mk_abs(["x1";...;"xn"],"t")%} returns {\small\verb%"\x1 ... xn. t"%}.

\FAILURE
Fails with {\small\verb%list_mk_abs%} if the terms in the list are not variables.

\COMMENTS
The system shows the type as {\small\verb%goal -> term%}.

\SEEALSO
strip_abs, mk_abs.

\ENDDOC
\DOC{list\_mk\_comb}

\TYPE {\small\verb%list_mk_comb : ((term # term list) -> term)%}\egroup

\SYNOPSIS
Iteratively constructs combinations (function applications).

\DESCRIBE
{\small\verb%list_mk_comb("t",["t1";...;"tn"])%} returns {\small\verb%"t t1 ... tn"%}.

\FAILURE
Fails with {\small\verb%list_mk_comb%} if the types of {\small\verb%t1%},...,{\small\verb%tn%} are not equal to the
argument types of {\small\verb%t%}. It is not necessary for all the arguments of {\small\verb%t%} to be
given. In particular the list of terms {\small\verb%t1%},...,{\small\verb%tn%} may be empty.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_comb("1",[]);;
"1" : term

#list_mk_comb("$/\",["T"]);;
"$/\ T" : term

#list_mk_comb("$/\",["1"]);;
evaluation failed     list_mk_comb
\end{verbatim}
}
\SEEALSO
strip_comb, mk_comb.

\ENDDOC
\DOC{list\_mk\_conj}

\TYPE {\small\verb%list_mk_conj : (term list -> term)%}\egroup

\SYNOPSIS
Constructs the conjunction of a list of terms.

\DESCRIBE
{\small\verb%list_mk_conj(["t1";...;"tn"])%} returns {\small\verb%"t1 /\ ... /\ tn"%}.

\FAILURE
Fails with {\small\verb%list_mk_conj%} if the list is empty or if the list has more than
one element, one or more of which are not of type {\small\verb%":bool"%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_conj ["T";"F";"T"];;
"T /\ F /\ T" : term

#list_mk_conj ["T";"1";"F"];;
evaluation failed     list_mk_conj

#list_mk_conj ["1"];;
"1" : term
\end{verbatim}
}
\SEEALSO
conjuncts, mk_conj.

\ENDDOC
\DOC{list\_mk\_disj}

\TYPE {\small\verb%list_mk_disj : (term list -> term)%}\egroup

\SYNOPSIS
Constructs the disjunction of a list of terms.

\DESCRIBE
{\small\verb%list_mk_disj(["t1";...;"tn"])%} returns {\small\verb%"t1 \/ ... \/ tn"%}.

\FAILURE
Fails with {\small\verb%list_mk_disj%} if the list is empty or if the list has more than
one element, one or more of which are not of type {\small\verb%":bool"%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_disj ["T";"F";"T"];;
"T \/ F \/ T" : term

#list_mk_disj ["T";"1";"F"];;
evaluation failed     list_mk_disj

#list_mk_disj ["1"];;
"1" : term
\end{verbatim}
}
\SEEALSO
disjuncts, mk_disj.

\ENDDOC
\DOC{list\_mk\_exists}

\TYPE {\small\verb%list_mk_exists : ((term list # term) -> term)%}\egroup

\SYNOPSIS
Iteratively constructs existential quantifications.

\DESCRIBE
{\small\verb%list_mk_exists(["x1";...;"xn"],"t")%} returns {\small\verb%"?x1 ... xn. t"%}.

\FAILURE
Fails with {\small\verb%list_mk_exists%} if the terms in the list are not variables or if
{\small\verb%t%} is not of type {\small\verb%":bool"%} and the list of terms is non-empty. If the list
of terms is empty the type of {\small\verb%t%} can be anything.

\COMMENTS
The system shows the type as {\small\verb%(goal -> term)%}.

\SEEALSO
strip_exists, mk_exists.

\ENDDOC
\DOC{LIST\_MK\_EXISTS}

\TYPE {\small\verb%LIST_MK_EXISTS : (term list -> thm -> thm)%}\egroup

\SYNOPSIS
Multiply existentially quantifies both sides of an equation using the given
variables.

\DESCRIBE
When applied to a list of terms {\small\verb%[x1;...;xn]%}, where the {\small\verb%ti%} are all
variables, and a theorem {\small\verb%A |- t1 = t2%}, the inference rule
{\small\verb%LIST_MK_EXISTS%} existentially quantifies both sides of the equation
using the variables given, none of which should be free in the assumption
list.
{\par\samepage\setseps\small
\begin{verbatim}
                A |- t1 = t2
   --------------------------------------  LIST_MK_EXISTS ["x1";...;"xn"]
    A |- (?x1...xn. t1) = (?x1...xn. t2)
\end{verbatim}
}
\FAILURE
Fails if any term in the list is not a variable or is free in the assumption
list, or if the theorem is not equational.

\SEEALSO
EXISTS_EQ, MK_EXISTS.

\ENDDOC
\DOC{list\_mk\_forall}

\TYPE {\small\verb%list_mk_forall : ((term list # term) -> term)%}\egroup

\SYNOPSIS
Iteratively constructs a universal quantification.

\DESCRIBE
{\small\verb%list_mk_forall(["x1";...;"xn"],"t")%} returns {\small\verb%"!x1 ... xn. t"%}.

\FAILURE
Fails with {\small\verb%list_mk_forall%} if the terms in the list are not variables or if
{\small\verb%t%} is not of type {\small\verb%":bool"%} and the list of terms is non-empty. If the list
of terms is empty the type of {\small\verb%t%} can be anything.

\COMMENTS
The system shows the type as {\small\verb%(goal -> term)%}.

\SEEALSO
strip_forall, mk_forall.

\ENDDOC
\DOC{list\_mk\_imp}

\TYPE {\small\verb%list_mk_imp : (goal -> term)%}\egroup

\SYNOPSIS
Iteratively constructs implications.

\DESCRIBE
{\small\verb%list_mk_imp(["t1";...;"tn"],"t")%} returns {\small\verb%"t1 ==> ( ... (tn ==> t)...)"%}.

\FAILURE
Fails with {\small\verb%list_mk_imp%} if any of {\small\verb%t1%},...,{\small\verb%tn%} are not of type {\small\verb%":bool"%} or
if the list of terms is non-empty and {\small\verb%t%} is not of type {\small\verb%":bool"%}. If the
list of terms is empty the type of {\small\verb%t%} can be anything.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_imp (["T";"F"],"T");;
"T ==> F ==> T" : term

#list_mk_imp (["T";"1"],"T");;
evaluation failed     list_mk_imp

#list_mk_imp (["T";"F"],"1");;
evaluation failed     list_mk_imp

#list_mk_imp ([],"1");;
"1" : term
\end{verbatim}
}
\SEEALSO
strip_imp, mk_imp.

\ENDDOC
\DOC{list\_mk\_pair}

\TYPE {\small\verb%list_mk_pair : (term list -> term)%}\egroup

\SYNOPSIS
Constructs a tuple from a list of terms.

\DESCRIBE
{\small\verb%list_mk_pair(["t1";...;"tn"])%} returns {\small\verb%"(t1,...,tn)"%}.

\FAILURE
Fails with {\small\verb%list_mk_pair%} if the list is empty.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_pair ["1";"T";"2"];;
"1,T,2" : term

#list_mk_pair ["1"];;
"1" : term
\end{verbatim}
}
\SEEALSO
strip_pair, mk_pair.

\ENDDOC
\DOC{LIST\_MP}

\TYPE {\small\verb%LIST_MP : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Performs a chain of Modus Ponens inferences.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- t1, ..., An |- tn%} and a theorem which is a
chain of implications with the successive antecedents the same as the
conclusions of the theorems in the list (up to alpha-conversion),
{\small\verb%A |- t1 ==> ... ==> tn ==> t%}, the {\small\verb%LIST_MP%} inference rule performs a chain
of {\small\verb%MP%} inferences to deduce {\small\verb%A u A1 u ... u An |- t%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1 ... An |- tn      A |- t1 ==> ... ==> tn ==> t
   ---------------------------------------------------------  LIST_MP
                    A u A1 u ... u An |- t
\end{verbatim}
}
\FAILURE
Fails unless the theorem is a chain of implications whose consequents are the
same as the conclusions of the list of theorems (up to alpha-conversion), in
sequence.

\SEEALSO
EQ_MP, MATCH_MP, MATCH_MP_TAC, MP, MP_TAC.

\ENDDOC
\DOC{list\_of\_binders}

\TYPE {\small\verb%list_of_binders : term list%}\egroup

\SYNOPSIS
List of binders in the current theory.

\DESCRIBE
For implementation reasons, a list containing the binders in the current theory
is maintained in the assignable ML variable {\small\verb%list_of_binders%}.  This variable
is not for general use, and users should never make assignments to it.

\FAILURE
Evaluating the assignable variable {\small\verb%list_of_binders%} never fails.

\ENDDOC
\DOC{load\_axiom}

\TYPE {\small\verb%load_axiom : (string -> string -> void)%}\egroup

\SYNOPSIS
Loads in a given axiom from a given theory.

\DESCRIBE
If {\small\verb%thy%} is the name of an ancestor theory, and {\small\verb%ax%} one of its axioms, then
{\par\samepage\setseps\small
\begin{verbatim}
   load_axiom `thy` `ax`
\end{verbatim}
}
\noindent attempts to load the corresponding axiom, that is, to perform
dynamically the following toplevel binding:
{\par\samepage\setseps\small
\begin{verbatim}
  let ax = axiom `thy` `ax`;;
\end{verbatim}
}
\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%ax%} is not one of its
axioms.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#load_axiom `ind` `INFINITY_AX`;;
() : void

INFINITY_AX = |- ?f. ONE_ONE f /\ ~ONTO f

#INFINITY_AX;;
|- ?f. ONE_ONE f /\ ~ONTO f
\end{verbatim}
}
\USES
Useful for autoloading.

\SEEALSO
axioms, let_after, let_before, load_axioms.

\ENDDOC
\DOC{load\_axioms}

\TYPE {\small\verb%load_axioms : (string -> void list)%}\egroup

\SYNOPSIS
Loads in all the axioms from a given theory.

\DESCRIBE
If {\small\verb%thy%} is the name of an ancestor theory, then the call
{\par\samepage\setseps\small
\begin{verbatim}
   load_axioms `thy`
\end{verbatim}
}
\noindent attempts to load in all the axioms from that theory, that is, for
each axiom {\small\verb%ax%}, to perform dynamically the following toplevel binding:
{\par\samepage\setseps\small
\begin{verbatim}
  let ax = axiom `thy` `ax`;;
\end{verbatim}
}

\FAILURE
Fails unless {\small\verb%thy%} is an ancestor theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#load_axioms `bool`;;
[(); (); (); (); ()] : void list

SELECT_AX = |- !P x. P x ==> P($@ P)

ETA_AX = |- !t. (\x. t x) = t

IMP_ANTISYM_AX = |- !t1 t2. (t1 ==> t2) ==> (t2 ==> t1) ==> (t1 = t2)

BOOL_CASES_AX = |- !t. (t = T) \/ (t = F)

ARB_THM = |- $= = $=
\end{verbatim}
}
\SEEALSO
axioms, let_after, let_before, load_axiom.

\ENDDOC
\DOC{load\_definition}

\TYPE {\small\verb%load_definition : (string -> string -> void)%}\egroup

\SYNOPSIS
Loads in a given definition from a given theory.

\DESCRIBE
If {\small\verb%thy%} is the name of an ancestor theory, and {\small\verb%def%} one of its definitions,
then
{\par\samepage\setseps\small
\begin{verbatim}
   load_definition `thy` `def`
\end{verbatim}
}
\noindent attempts to load the corresponding definition, that is, to perform
dynamically the following toplevel binding:
{\par\samepage\setseps\small
\begin{verbatim}
  let def = definition `thy` `def`;;
\end{verbatim}
}
\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%def%} is not one of its
definitions.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#load_definition `bool` `FORALL_DEF`;;
() : void

FORALL_DEF = |- $! = (\P. P = (\x. T))

#FORALL_DEF;;
|- $! = (\P. P = (\x. T))
\end{verbatim}
}
\USES
Useful for autoloading.

\SEEALSO
definitions, let_after, let_before, load_definitions.

\ENDDOC
\DOC{load\_definitions}

\TYPE {\small\verb%load_definitions : (string -> void list)%}\egroup

\SYNOPSIS
Loads in all the definitions from a given theory.

\DESCRIBE
If {\small\verb%thy%} is the name of an ancestor theory, then the call
{\par\samepage\setseps\small
\begin{verbatim}
   load_definitions `thy`
\end{verbatim}
}
\noindent attempts to load in all the definitions of that theory, that is, for
each definition {\small\verb%def%}, to perform dynamically the following toplevel binding:
{\par\samepage\setseps\small
\begin{verbatim}
  let def = definition `thy` `def`;;
\end{verbatim}
}

\FAILURE
Fails unless {\small\verb%thy%} is an ancestor theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#load_definitions `combin`;;
[(); (); (); ()] : void list

I_DEF = |- I = S K K

S_DEF = |- S = (\f g x. f x(g x))

K_DEF = |- K = (\x y. x)

o_DEF = |- !f g. f o g = (\x. f(g x))
\end{verbatim}
}
\SEEALSO
definitions, let_after, let_before, load_definition.

\ENDDOC
\DOC{load}

\TYPE {\small\verb%load : ((string # bool) -> void)%}\egroup

\SYNOPSIS
Loads ML phrases from the named file.

\DESCRIBE
A call {\small\verb%load(`file`,flag)%} will load ML phrases from the file described by
{\small\verb%file%}. If the boolean value {\small\verb%flag%} is true, then toplevel printing of the
system responses will occur, otherwise just a dot is printed for each toplevel
phrase. The name {\small\verb%file%} is expanded into a real filename using the same
mechanism as {\small\verb%find_ml_file%}.

\FAILURE
Fails if the appropriate file cannot be found on the search path, or if an
error occurs in the ML which is being loaded.

\COMMENTS
It is usual to use either {\small\verb%loadf%} or {\small\verb%loadt%} rather than this function, which
perform the same action with one or the other setting of the flag.

\SEEALSO
find_ml_file, loadf, loadt, search_path, set_search_path.

\ENDDOC
\DOC{loadf}

\TYPE {\small\verb%loadf : (string -> void)%}\egroup

\SYNOPSIS
Loads an ML file with the verbose flag set to {\small\verb%false%}.

\DESCRIBE
The function {\small\verb%loadf%} takes a string indicating the ML file name as
argument and loads it in the same manner as {\small\verb%load%}, except that the
verbose flag is always set to false.

\FAILURE
{\small\verb%loadf%} will fail if the file named by the argument does not exist in
the search path. It will fail in the same manner if the file is not a
valid  ML file. Failure in the ML file will terminate loading.

\EXAMPLE
If we have a ML file called {\small\verb%foo.ml%} which contains the line
{\par\samepage\setseps\small
\begin{verbatim}
   let x=2+2;;
\end{verbatim}
}
\noindent this can be loaded as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #loadf `foo.ml`;;
\end{verbatim}
}
\noindent and the system would respond with:
{\par\samepage\setseps\small
\begin{verbatim}
   .() : void
\end{verbatim}
}
\SEEALSO
load, loadf.

\ENDDOC
\DOC{load\_library}

\TYPE {\small\verb%load_library : (string -> void)%}\egroup

\SYNOPSIS
Load a library.

\DESCRIBE
The function {\small\verb%load_library%} can either be used to load an entire library or to
load only a part of a library. Loading an entire library called `{\small\verb%name%}' is
done by evaluating 
{\par\samepage\setseps\small
\begin{verbatim}
   load_library `name`;;
\end{verbatim}
}
\noindent This will attempt to load the library called {\small\verb%name%} unless it is
already loaded, in which case a message is printed. The loading of a library
{\small\verb%name%} is done by searching for the library's load file `{\small\verb%name/name.ml%}' using
the internal library search path and then loading this file.  For example, if
the library search path contains the pathnames to a local library and to the
system library:
{\par\samepage\setseps\small
\begin{verbatim}
   [`~/lib/`; `/usr/lib/hol/Library/`]
\end{verbatim}
}
\noindent then {\small\verb%load_library%} will load the ML file
{\par\samepage\setseps\small
\begin{verbatim}
   ~/lib/name/name.ml
\end{verbatim}
}
\noindent if this exists in the local library.  Otherwise, the file
{\par\samepage\setseps\small
\begin{verbatim}
   /usr/lib/hol/Library/name/name.ml
\end{verbatim}
}
\noindent will be loaded from the system library.

A named part of a library is loaded by evaluating:
{\par\samepage\setseps\small
\begin{verbatim}
   load_library `name:partname`;;
\end{verbatim}
}
\noindent where {\small\verb%name%} is the name of the library, and {\small\verb%partname%} is the name
of a segment of this library.  In this case, {\small\verb%load_library%} searches along the
library search path for the load file {\small\verb%name/partname.ml%}.  Note that this can
be used to load an arbitrary ML file from the library. Users should not,
however, rely on this feature, but should access libraries only in the ways the
officially supported and documented in library manuals.

The results of evaluation during the loading of a library are displayed if the
flag {\small\verb%print_lib%} is {\small\verb%true%}.  Otherwise, the results of evaluation are not
printed but abbreviated by a series of dots, each of which represents the
evaluation of one ML phrase.

\FAILURE
Fails if the library load file cannot be found or if the ML code being loaded
itself fails for any reason.

\COMMENTS
More detail about the organization of libraries, in particular how to create
your own, can be found in DESCRIPTION, which also gives a list of all the
libraries currently in the standard HOL distribution.

\SEEALSO
libraries, library_pathname, library_search_path, set_library_search_path.

\ENDDOC
\DOC{loadt}

\TYPE {\small\verb%loadt : (string -> void)%}\egroup

\SYNOPSIS
{\small\verb%loadt%} loads an ML file with the verbose flag set to {\small\verb%true%}.

\DESCRIBE
The function {\small\verb%loadt%} takes a string indicating the ML file name as
argument and loads it in the same manner as {\small\verb%load%}, except that the
verbose flag is always set to {\small\verb%true%}.

\FAILURE
{\small\verb%loadt%} will fail if the file named by the argument does not exist in
the search path. It will fail in the same manner if the file is not a
valid ML file. Failure in the ML file will also terminate loading.

\EXAMPLE
If we have an ML file called {\small\verb%foo.ml%} which contains the line
{\par\samepage\setseps\small
\begin{verbatim}
   let x=2+2;;
\end{verbatim}
}
\noindent this can be loaded as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #loadt `foo.ml`;;
\end{verbatim}
}
\noindent and the system would respond with:
{\par\samepage\setseps\small
\begin{verbatim}
   x = 4 : int

   File foo.ml loaded
   () : void
\end{verbatim}
}
\SEEALSO
load, loadf.

\ENDDOC
\DOC{load\_theorem}

\TYPE {\small\verb%load_theorem : (string -> string -> void)%}\egroup

\SYNOPSIS
Loads in a given theorem from a given theory.

\DESCRIBE
If {\small\verb%thy%} is the name of an ancestor theory, and {\small\verb%th%} one of its axioms, then
{\par\samepage\setseps\small
\begin{verbatim}
   load_theorem `thy` `th`
\end{verbatim}
}
\noindent will attempt to load the corresponding theorem, that is, to perform
dynamically the following toplevel binding:
{\par\samepage\setseps\small
\begin{verbatim}
  let th = theorem `thy` `th`;;
\end{verbatim}
}
\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%th%} is not one of its
theorems.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#load_theorem `bool` `PAIR`;;
() : void

PAIR = |- !x. FST x,SND x = x

#PAIR;;
|- !x. FST x,SND x = x
\end{verbatim}
}
\USES
Useful for autoloading.

\SEEALSO
theorems, let_after, let_before, load_theorems.

\ENDDOC
\DOC{load\_theorems}

\TYPE {\small\verb%load_theorems : (string -> void list)%}\egroup

\SYNOPSIS
Loads in all the theorems from a given theory.

\DESCRIBE
If {\small\verb%thy%} is the name of an ancestor theory, then the call
{\par\samepage\setseps\small
\begin{verbatim}
   load_theorems `thy`
\end{verbatim}
}
\noindent attempts to load in all the theorems from that theory, that is, for
each axiom {\small\verb%th%}, to perform dynamically the following toplevel binding:
{\par\samepage\setseps\small
\begin{verbatim}
  let th = theorem `thy` `th`;;
\end{verbatim}
}

\FAILURE
Fails unless {\small\verb%thy%} is an ancestor theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#load_theorems `bool`;;
[(); (); (); (); ()] : void list

PAIR_EQ = |- !x y a b. (x,y = a,b) = (x = a) /\ (y = b)

SND = |- !x y. SND(x,y) = y

FST = |- !x y. FST(x,y) = x

PAIR = |- !x. FST x,SND x = x

PAIR_EXISTS = |- ?p. IS_PAIR p
\end{verbatim}
}
\SEEALSO
let_after, let_before, load_theorem, theorems.

\ENDDOC
\DOC{load\_theory}

\TYPE {\small\verb%load_theory : (string -> void)%}\egroup

\SYNOPSIS
Loads an existing theory into the system.

\DESCRIBE
A call {\small\verb%load_theory `thy`%} loads the existing theory {\small\verb%thy%} into the system
and makes it the current theory. The message `{\small\verb%Theory thy loaded%}' is printed.
The theory is entered in proof mode. Whilst in this mode only theorems may be
added to the theory segment.

\FAILURE
A call to {\small\verb%load_theory `thy`%} will fail if theory {\small\verb%thy%} does not appear on
the current search path. It will fail if theory {\small\verb%thy%} is not a descendant of
the current theory. It will fail if an ancestor of theory {\small\verb%thy%} has been
extended with either new types or constants which clash with names in theory
{\small\verb%thy%}. It will also fail if any of the theory files of the theory {\small\verb%thy%}
have been damaged. On failure, the system recovers cleanly, unloading any
theory segments it had loaded before the failure was detected. It will diverge
if the theory hierarchy within theory {\small\verb%thy%} contains loops, so that a theory
segment is its own ancestor.

\SEEALSO
extend_theory, new_parent, new_theory, print_theory, search_path.

\ENDDOC
\DOC{lookup\_form\_rep}

\TYPE {\small\verb%lookup_form_rep : ((* list # form) -> * list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{lookup\_term}

\TYPE {\small\verb%lookup_term : (* term_net -> term -> * list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{lookup\_term\_rep}

\TYPE {\small\verb%lookup_term_rep : ((* list # term) -> * list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{lsp}

\TYPE {\small\verb%lsp : (void -> void)%}\egroup

\SYNOPSIS
Breaks out of top-level ML to Lisp.

\DESCRIBE
{\small\verb%lsp%} breaks out of top-level ML to Lisp in such a fashion that one finds
oneself in the particular Lisp's break-level debugger.  ML execution may
be continued safely by issuing the appropriate continuation command to
the Lisp in question.  In Franz, this is a {\small\verb%Control-D%}, in Allegro CL it
is {\small\verb%:continue%}, in Lucid CL it is {\small\verb%(q)%}, and in AKCL it is {\small\verb%:r%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#lsp();;

Break nil
<1>: ^D
[Return to top level]

          _  _    __    _      __    __
   |___   |__|   |  |   |     |__|  |__|
   |      |  |   |__|   |__   |__|  |__|

          Version 1.12 (Sun3/Franz), built on Feb 23 1991

#
\end{verbatim}
}
\COMMENTS
{\small\verb%lsp%} is not meant for general use, and should be treated with great
care.  If one is not wary, it is entirely possible to corrupt HOL by
using it.

\SEEALSO
dropout, lisp.

\ENDDOC
\DOC{MAP2\_CONV}

\TYPE {\small\verb%MAP2_CONV : conv -> conv%}\egroup

\SYNOPSIS
Compute the result of mapping a binary function down two lists.

\DESCRIBE 
The function {\small\verb%MAP2_CONV%} is a conversion for computing the result
of mapping a binary function {\small\verb%f:ty1->ty2->ty3%} down two lists
{\small\verb%"[l11;...;l1n]"%} whose elements are of type {\small\verb%ty1%} and
{\small\verb%"[l21;...;l2n]"%} whose elements are of type {\small\verb%ty2%}.  The lengths of
the two lists must be identical. The first
argument to {\small\verb%MAP2_CONV%} is expected to be a conversion 
that computes the result of applying the function {\small\verb%f%} to a pair of
corresponding elements of these lists. When applied to a term
{\small\verb%"f l1i l2i"%}, this conversion should return a theorem of the form
{\small\verb%|- (f l1i l2i) = ri%}, where {\small\verb%ri%} is the result of applying the function
{\small\verb%f%} to the elements {\small\verb%l1i%} and {\small\verb%l2i%}. 

\noindent Given an appropriate {\small\verb%conv%}, the conversion {\small\verb%MAP2_CONV conv%} takes a
term of the form {\small\verb%"MAP2 f [l11;...;dl2tn] [l21;...;l2n]"%} and returns
the theorem 
{\par\samepage\setseps\small
\begin{verbatim}
   |- MAP2 f [l11;...;l1n] [l21;...;l2n] = [r1;...;rn] 
\end{verbatim}
}
\noindent where {\small\verb%conv "f l1i l2i"%} returns {\small\verb%|- (f l1i l2i) = ri%} for
{\small\verb%i%} from {\small\verb%1%} to {\small\verb%n%}. 

\EXAMPLE

The following is a very simple example in which the corresponding
elements from the two lists are summed to form the resulting list:
{\par\samepage\setseps\small
\begin{verbatim}
   #MAP2_CONV ADD_CONV "MAP2 $+ [1;2;3] [1;2;3]";;
   |- MAP2 $+ [1;2;3] [1;2;3] = [2;4;6]
\end{verbatim}
}

\FAILURE 
{\small\verb%MAP2_CONV conv%} fails if applied to a term not of the form
described above.  An application of {\small\verb%MAP2_CONV conv%} to a term
{\small\verb%"MAP2 f [l11;...;l1n] [l21;...;l2n]"%} fails unless for all {\small\verb%i%} where {\small\verb%1<=i<=n%}
evaluating {\small\verb%conv "f l1i l2i"%} returns {\small\verb%|- (f l1i l2i) = ri%} for some {\small\verb%ri%}.

\SEEALSO
MAP_CONV

\ENDDOC

\DOC{map2}

\TYPE {\small\verb%map2 : (((* # **) -> ***) -> (* list # ** list) -> *** list)%}\egroup

\SYNOPSIS
Maps a binary function over two lists to create one new list.

\DESCRIBE
{\small\verb%map2 f ([x1;...;xn],[y1;...;yn])%} returns {\small\verb%[f(x1,y1);...;f(xn,yn)]%}.

\FAILURE
Fails with {\small\verb%map2%} if the two lists are of different lengths.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#map2 $+ ([1;2;3],[3;2;1]);;
[4; 4; 4] : int list
\end{verbatim}
}
\SEEALSO
map, uncurry.

\ENDDOC
\DOC{MAP\_CONV}

\TYPE {\small\verb%MAP_CONV : conv -> conv%}\egroup

\SYNOPSIS
Compute the result of mapping a function down a list.

\DESCRIBE 
The function {\small\verb%MAP_CONV%} is a parameterized conversion for computing the result
of mapping a function {\small\verb%f:ty1->ty2%} down a list {\small\verb%"[t1;...;tn]"%} of elements of
type {\small\verb%ty1%}.  The first argument to {\small\verb%MAP_CONV%} is expected to be a conversion
that computes the result of applying the function {\small\verb%f%} to an element of this
list. When applied to a term {\small\verb%"f ti"%}, this conversion should return a theorem
of the form {\small\verb%|- (f ti) = ri%}, where {\small\verb%ri%} is the result of applying the function
{\small\verb%f%} to the element {\small\verb%ti%}. 

\noindent Given an appropriate {\small\verb%conv%}, the conversion {\small\verb%MAP_CONV conv%} takes a
term of the form {\small\verb%"[MAP f [t1;...;tn]"%} to the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- MAP f [t1;...;tn] = [r1;...;rn] 
\end{verbatim}
}
\noindent where {\small\verb%conv "f ti"%} returns {\small\verb%|- (f ti) = ri%} for {\small\verb%i%} from {\small\verb%1%} to {\small\verb%n%}.

\EXAMPLE

The following is a very simple example in which no computation is done for 
applications of the function being mapped down a list:
{\par\samepage\setseps\small
\begin{verbatim}
   #MAP_CONV NO_CONV "MAP SUC [1;2;1;4]";;
   |- MAP SUC[1;2;1;4] = [SUC 1;SUC 2;SUC 1;SUC 4]
\end{verbatim}
}
\noindent The result just contains applications of {\small\verb%SUC%}, since the supplied 
conversion {\small\verb%ALL_CONV%} does no evaulation.

We now construct a conversion that maps {\small\verb%SUC n%} for any numeral {\small\verb%n%} to the
numeral standing for the successor of {\small\verb%n%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #let SUC_CONV tm =
        let n = int_of_string(fst(dest_const(rand tm))) in
        let sucn = mk_const(string_of_int(n+1), ":num") in
            SYM (num_CONV sucn);;
   SUC_CONV = - : conv
\end{verbatim}
}
\noindent The result is a conversion that inverts {\small\verb%num_CONV%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #num_CONV "4";;
   |- 4 = SUC 3

   #SUC_CONV "SUC 3";;
   |- SUC 3 = 4
\end{verbatim}
}
\noindent The conversion {\small\verb%SUC_CONV%} can then be used to compute the
result of mapping the successor function down a list of numerals:
{\par\samepage\setseps\small
\begin{verbatim}
   #MAP_CONV SUC_CONV "MAP SUC [1;2;1;4]";;
   |- MAP SUC[1;2;1;4] = [2;3;2;5]
\end{verbatim}
}

\FAILURE 
{\small\verb%MAP_CONV conv%} fails if applied to a term not of the form
{\small\verb%"MAP f [t1;...;tn]"%}.  An application of {\small\verb%MAP_CONV conv%} to a term
{\small\verb%"MAP f [t1;...;tn]"%} fails unless for all {\small\verb%ti%} in the list {\small\verb%[t1;...;tn]%},
evaluating {\small\verb%conv "f ti"%} returns {\small\verb%|- (f ti) = ri%} for some {\small\verb%ri%}.

\ENDDOC

\DOC{map}

\TYPE {\small\verb%map : ((* -> **) -> * list -> ** list)%}\egroup

\SYNOPSIS
Applies a function to every element of a list.

\DESCRIBE
{\small\verb%map f [x1;...;xn]%} returns {\small\verb%[(f x1);...;(f xn)]%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#map (\x. x * 2) [];;
[] : int list

#map (\x. x * 2) [1;2;3];;
[2; 4; 6] : int list
\end{verbatim}
}
\ENDDOC
\DOC{MAP\_EVERY}

\TYPE {\small\verb%MAP_EVERY : ((* -> tactic) -> * list -> tactic)%}\egroup

\SYNOPSIS
Sequentially applies all tactics given by mapping a function over a list.

\DESCRIBE
When applied to a tactic-producing function {\small\verb%f%} and an operand list
{\small\verb%[x1;...;xn]%}, the elements of which have the same type as {\small\verb%f%}'s domain type,
{\small\verb%MAP_EVERY%} maps the function {\small\verb%f%} over the list, producing a list of
tactics, then applies these tactics in sequence as in the case of {\small\verb%EVERY%}.
The effect is:
{\par\samepage\setseps\small
\begin{verbatim}
   MAP_EVERY f [x1;...;xn] = (f x1) THEN ... THEN (f xn)
\end{verbatim}
}
\noindent If the operand list is empty, then {\small\verb%MAP_EVERY%} has no effect.

\FAILURE
The application of {\small\verb%MAP_EVERY%} to a function and operand list fails iff
the function fails when applied to any element in the list. The
resulting tactic fails iff any of the resulting tactics fails.

\EXAMPLE
A convenient way of doing case analysis over several boolean variables is:
{\par\samepage\setseps\small
\begin{verbatim}
   MAP_EVERY BOOL_CASES_TAC ["var1:bool";...;"varn:bool"]
\end{verbatim}
}
\SEEALSO
EVERY, FIRST, MAP_FIRST, THEN.

\ENDDOC
\DOC{mapfilter}

\TYPE {\small\verb%mapfilter : ((* -> **) -> * list -> ** list)%}\egroup

\SYNOPSIS
Applies a function to every element of a list, returning a list of results
for those elements for which application succeeds.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#mapfilter hd [[1;2;3];[4;5];[];[6;7;8];[]];;
[1; 4; 6] : int list
\end{verbatim}
}
\SEEALSO
filter, map.

\ENDDOC
\DOC{MAP\_FIRST}

\TYPE {\small\verb%MAP_FIRST : ((* -> tactic) -> * list -> tactic)%}\egroup

\SYNOPSIS
Applies first tactic that succeeds in a list given by mapping a function over a
list.

\DESCRIBE
When applied to a tactic-producing function {\small\verb%f%} and an operand list
{\small\verb%[x1;...;xn]%}, the elements of which have the same type as {\small\verb%f%}'s domain
type, {\small\verb%MAP_FIRST%} maps the function {\small\verb%f%} over the list, producing a list of
tactics, then tries applying these tactics to the goal till one succeeds.
If {\small\verb%f(xm)%} is the first to succeed, then the overall effect is the same
as applying {\small\verb%f(xm)%}. Thus:
{\par\samepage\setseps\small
\begin{verbatim}
   MAP_FIRST f [x1;...;xn] = (f x1) ORELSE ... ORELSE (f xn)
\end{verbatim}
}
\FAILURE
The application of {\small\verb%MAP_FIRST%} to a function and tactic list fails iff
the function does when applied to any of the elements of the list. The
resulting tactic fails iff all the resulting tactics fail when
applied to the goal.

\SEEALSO
EVERY, FIRST, MAP_EVERY, ORELSE.

\ENDDOC
\DOC{maptok}

\TYPE {\small\verb%maptok : ((string -> *) -> string -> * list)%}\egroup

\SYNOPSIS
Maps a function over the constituent words of a string.

\DESCRIBE
{\small\verb%maptok f s%} first splits the string {\small\verb%s%} into a list of substrings, and then
maps the function {\small\verb%f%} over that list. Splitting of the string occurs at each
sequence of blanks and carriage returns (white space). This white space does
not appear in the list of substrings. Leading and trailing white space in the
input string is also thrown away.

\FAILURE
Fails if one of the applications of {\small\verb%f%} to a substring fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#maptok explode `  the cat  sat `;;
[[`t`; `h`; `e`]; [`c`; `a`; `t`]; [`s`; `a`; `t`]] : string list list
\end{verbatim}
}
\USES
Useful when wanting to map a function over a list of constant strings.
Instead of using {\small\verb%map f [`string1`;...;`stringn`]%} one can use:
{\par\samepage\setseps\small
\begin{verbatim}
   (maptok f `string1 ... stringn`)
\end{verbatim}
}
\SEEALSO
words, word_separators, words2, map.

\ENDDOC
\DOC{MATCH\_ACCEPT\_TAC}

\TYPE {\small\verb%MATCH_ACCEPT_TAC : thm_tactic%}\egroup

\SYNOPSIS
Solves a goal which is an instance of the supplied theorem.

\DESCRIBE
When given a theorem {\small\verb%A' |- t%} and a goal {\small\verb%A ?- t'%} where {\small\verb%t%} can be matched
to {\small\verb%t'%} by instantiating variables which are either free or
universally quantified at the outer level, including appropriate type
instantiation, {\small\verb%MATCH_ACCEPT_TAC%} completely solves the goal.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t'
   =========  MATCH_ACCEPT_TAC (A' |- t)

\end{verbatim}
}
\noindent Unless {\small\verb%A'%} is a subset of {\small\verb%A%}, this is an invalid tactic.

\FAILURE
Fails unless the theorem has a conclusion which is instantiable to match that
of the goal.

\EXAMPLE
The following example shows variable and type instantiation at work. We can use
the polymorphic list theorem {\small\verb%HD%}:
{\par\samepage\setseps\small
\begin{verbatim}
   HD = |- !h t. HD(CONS h t) = h
\end{verbatim}
}
\noindent to solve the goal:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- HD [1;2] = 1
\end{verbatim}
}
\noindent simply by:
{\par\samepage\setseps\small
\begin{verbatim}
   MATCH_ACCEPT_TAC HD
\end{verbatim}
}
\SEEALSO
ACCEPT_TAC.

\ENDDOC
\DOC{match}

\TYPE {\small\verb%match : (term -> term -> ((term # term) list # (type # type) list))%}\egroup

\SYNOPSIS
Finds instantiations to match one term to another.

\DESCRIBE
When applied to two terms, with no outer quantifiers in the first, {\small\verb%match%}
attempts to find type and term instantiations for the first term (only) to make
it match the second. If it succeeds, it returns the instantiations in the form
of a pair containing a list of term replacements and a list of type
instantiations. If the first term represents the conclusion of a theorem, the
returned instantiations are of the appropriate form to be passed to
{\small\verb%INST_TY_TERM%}.

\FAILURE
Fails if the term cannot be matched by one-way instantiation.

\EXAMPLE
The following shows how {\small\verb%match%} could be used to match the conclusion of a
theorem to a term.
{\par\samepage\setseps\small
\begin{verbatim}
   #let th = REFL "x:*";;
   th = |- x = x

   #match (concl th) "1 = 1";;
   ([("1", "x")], [(":num", ":*")])
   : ((term # term) list # (type # type) list)

   #INST_TY_TERM it th;;
   |- 1 = 1
\end{verbatim}
}
\COMMENTS
Note that there is no guarantee that the returned instantiations will be
possible for {\small\verb%INST_TY_TERM%} to achieve, because some of the variables (term or
type) which need to be instantiated may be free in the assumptions, eg:
{\par\samepage\setseps\small
\begin{verbatim}
   #top_print print_all_thm;;
   - : (thm -> void)

   #let th = ASSUME "x:* = x";;
   th = x = x |- x = x

   #match (concl th) "1 = 1";;
   ([("1", "x")], [(":num", ":*")])
   : ((term # term) list # (type # type) list)

   #INST_TY_TERM it th;;
   evaluation failed     INST_TYPE: type variable free in assumptions
\end{verbatim}
}
\noindent In fact, for instantiating a theorem, {\small\verb%PART_MATCH%} is usually easier.

\SEEALSO
INST_TY_TERM, PART_MATCH.

\ENDDOC
\DOC{MATCH\_MP}

\TYPE {\small\verb%MATCH_MP : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Modus Ponens inference rule with automatic matching.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- !x1...xn. t1 ==> t2%} and {\small\verb%A2 |- t1'%}, the
inference rule {\small\verb%MATCH_MP%} matches {\small\verb%t1%} to {\small\verb%t1'%} by instantiating free or
universally quantified variables in the first theorem (only), and returns a
theorem {\small\verb%A1 u A2 |- !xa..xk. t2'%}, where {\small\verb%t2'%} is a correspondingly
instantiated version of {\small\verb%t2%}. Polymorphic types are also instantiated if
necessary.

Variables free in the consequent but not the antecedent of the first argument
theorem will be replaced by variants if this is necessary to maintain the full
generality of the theorem, and any which were universally quantified over in
the first argument theorem will be universally quantified over in the result,
and in the same order.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- !x1..xn. t1 ==> t2   A2 |- t1'
   --------------------------------------  MATCH_MP
          A1 u A2 |- !xa..xk. t2'
\end{verbatim}
}
\FAILURE
Fails unless the first theorem is a (possibly repeatedly universally
quantified) implication whose antecedent can be instantiated to match
the conclusion of the second theorem, without instantiating any variables
which are free in {\small\verb%A1%}, the first theorem's assumption list.

\EXAMPLE
In this example, automatic renaming occurs to maintain the most general form of
the theorem, and the variant corresponding to {\small\verb%z%} is universally quantified
over, since it was universally quantified over in the first argument theorem.
{\par\samepage\setseps\small
\begin{verbatim}
   #let ith =
   # (GENL ["x:num"; "z:num"] o DISCH_ALL o AP_TERM "$+ (w + z)")
   #   (ASSUME "x:num = y");;
   ith = |- !x z. (x = y) ==> ((w + z) + x = (w + z) + y)

   #let th = ASSUME "w:num = z";;
   th = w = z |- w = z

   #MATCH_MP5 ith th;;
   w = z |- !z'. (w' + z') + w = (w' + z') + z
\end{verbatim}
}
\SEEALSO
EQ_MP, MATCH_MP_TAC, MP, MP_TAC.

\ENDDOC
\DOC{MATCH\_MP\_TAC}

\TYPE {\small\verb%MATCH_MP_TAC : thm_tactic%}\egroup

\SYNOPSIS
Reduces the goal using a supplied implication, with matching.

\DESCRIBE
When applied to a theorem of the form
{\par\samepage\setseps\small
\begin{verbatim}
   A' |- !x1...xn. s ==> !y1...ym. t
\end{verbatim}
}
\noindent {\small\verb%MATCH_MP_TAC%} produces a tactic that reduces a goal whose conclusion
{\small\verb%t'%} is a substitution and/or type instance of {\small\verb%t%} to the corresponding
instance of {\small\verb%s%}. Any variables free in {\small\verb%s%} but not in {\small\verb%t%} will be existentially
quantified in the resulting subgoal:
{\par\samepage\setseps\small
\begin{verbatim}
     A ?- !v1...vi. t'
  ======================  MATCH_MP_TAC (A' |- !x1...xn. s ==> !y1...tm. t)
     A ?- ?z1...zp. s'
\end{verbatim}
}
\noindent where {\small\verb%z1%}, ..., {\small\verb%zp%} are (type instances of) those variables among
{\small\verb%x1%}, ..., {\small\verb%xn%} that do not occur free in {\small\verb%t%}. Note that this is not a valid
tactic unless {\small\verb%A'%} is a subset of {\small\verb%A%}.

\FAILURE
Fails unless the theorem is an (optionally universally quantified) implication
whose consequent can be instantiated to match the goal. The generalized
variables {\small\verb%v1%}, ..., {\small\verb%vi%} must occur in {\small\verb%s'%} in order for the conclusion {\small\verb%t%} of
the supplied theorem to match {\small\verb%t'%}.

\SEEALSO
EQ_MP, MATCH_MP, MP, MP_TAC.

\ENDDOC
\DOC{max\_print\_depth}

\TYPE {\small\verb%max_print_depth : (int -> int)%}\egroup

\SYNOPSIS
Sets depth of block nesting.

\DESCRIBE
The function {\small\verb%max_print_depth%} is used to define the maximum depth of
nesting that the pretty printer will allow. If the number of blocks
is greater than the the value set by {\small\verb%max_print_depth%} then
the blocks are truncated and this is indicated by the holophrast {\small\verb%&%}.
The function always returns the previous maximum depth setting.

\FAILURE
Never fails.

\EXAMPLE
\noindent If the maximum depth setting is the default (500) and we want to
change this to 20 the command will be:
{\par\samepage\setseps\small
\begin{verbatim}
   #max_print_depth 20;;
\end{verbatim}
}
\noindent The system will then return the following:
{\par\samepage\setseps\small
\begin{verbatim}
   500 : int
\end{verbatim}
}
\SEEALSO
print_begin, print_ibegin, print_end, set_margin, print_break

\ENDDOC
\DOC{mem}

\TYPE {\small\verb%mem : (* -> * list -> bool)%}\egroup

\SYNOPSIS
Tests whether a list contains a certain member.

\DESCRIBE
{\small\verb%mem x [x1;...;xn]%} returns {\small\verb%true%} if some {\small\verb%xi%} in the list is equal to {\small\verb%x%}.
Otherwise it returns {\small\verb%false%}.

\FAILURE
Never fails.

\SEEALSO
find, tryfind, exists, forall, assoc, rev_assoc.

\ENDDOC
\DOC{merge\_nets\_rep}

\TYPE {\small\verb%merge_nets_rep : ((* list # * list) -> * list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{merge\_term\_nets}

\TYPE {\small\verb%merge_term_nets : (* term_net -> * term_net -> * term_net)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{message}

\TYPE {\small\verb%message : (string -> void)%}\egroup

\SYNOPSIS
Prints a message to the terminal.

\DESCRIBE
{\small\verb%message s%} returns {\small\verb%():void%} with the side-effect of printing the string {\small\verb%s%}
to the terminal followed by a carriage return. String quotes are not printed
around the string. The text is queued until the pretty-printer decides where
line breaks are needed, or until the queue is explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#message `This is an example`;;
This is an example
() : void
\end{verbatim}
}
\SEEALSO
print_string, print_tok, print_begin, print_end, print_newline.

\ENDDOC
\DOC{mk\_abs}

\TYPE {\small\verb%mk_abs : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs an abstraction.

\DESCRIBE
{\small\verb%mk_abs "var","t"%} returns the abstraction {\small\verb%"\var. t"%}.

\FAILURE
Fails with {\small\verb%mk_abs%} if first term is not a variable.

\SEEALSO
dest_abs, is_abs, list_mk_abs, mk_var, mk_const, mk_comb.

\ENDDOC
\DOC{MK\_ABS}

\TYPE {\small\verb%MK_ABS : (thm -> thm)%}\egroup

\SYNOPSIS
Abstracts both sides of an equation.

\DESCRIBE
When applied to a theorem {\small\verb%A |- !x. t1 = t2%}, whose conclusion is a
universally quantified equation, {\small\verb%MK_ABS%} returns the theorem
{\small\verb%A |- \x. t1 = \x. t2%}.
{\par\samepage\setseps\small
\begin{verbatim}
        A |- !x. t1 = t2
   --------------------------  MK_ABS
    A |- (\x. t1) = (\x. t2)
\end{verbatim}
}
\FAILURE
Fails unless the theorem is a (singly) universally quantified equation.

\SEEALSO
ABS, HALF_MK_ABS, MK_COMB, MK_EXISTS.

\ENDDOC
\DOC{mk\_comb}

\TYPE {\small\verb%mk_comb : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a combination (function application).

\DESCRIBE
{\small\verb%mk_comb "t1","t2"%} returns the combination {\small\verb%"t1 t2"%}.

\FAILURE
Fails with {\small\verb%mk_comb%} unless {\small\verb%t1%} is a function with domain type {\small\verb%t2%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#mk_comb("$~","T");;
"~T" : term

#mk_comb("T","T");;
evaluation failed     mk_comb
\end{verbatim}
}
\SEEALSO
dest_comb, is_comb, list_mk_comb, mk_var, mk_const, mk_abs.

\ENDDOC
\DOC{MK\_COMB}

\TYPE {\small\verb%MK_COMB : ((thm # thm) -> thm)%}\egroup

\SYNOPSIS
Proves equality of combinations constructed from equal
functions and operands.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- f = g%} and {\small\verb%A2 |- x = y%}, the inference
rule {\small\verb%MK_COMB%} returns the theorem {\small\verb%A1 u A2 |- f x = g y%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- f = g   A2 |- x = y
   ---------------------------  MK_COMB
       A1 u A2 |- f x = g y
\end{verbatim}
}
\FAILURE
Fails unless both theorems are equational and {\small\verb%f%} and {\small\verb%g%} are
functions whose domain types are the same as the types of {\small\verb%x%} and {\small\verb%y%}
respectively.

\SEEALSO
AP_TERM, AP_THM.

\ENDDOC
\DOC{mk\_cond}

\TYPE {\small\verb%mk_cond : ((term # term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a conditional term.

\DESCRIBE
{\small\verb%mk_cond("t","t1","t2")%} returns {\small\verb%"t => t1 | t2"%}.

\FAILURE
Fails with {\small\verb%mk_cond%} if {\small\verb%t%} is not of type {\small\verb%":bool"%} or if {\small\verb%t1%} and {\small\verb%t2%} are
of different types.

\SEEALSO
dest_cond, is_cond.

\ENDDOC
\DOC{mk\_conj}

\TYPE {\small\verb%mk_conj : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a conjunction.

\DESCRIBE
{\small\verb%mk_conj("t1","t2")%} returns {\small\verb%"t1 /\ t2"%}.

\FAILURE
Fails with {\small\verb%mk_conj%} if either {\small\verb%t1%} or {\small\verb%t2%} are not of type {\small\verb%":bool"%}.

\SEEALSO
dest_conj, is_conj, list_mk_conj.

\ENDDOC
\DOC{mk\_cons}

\TYPE {\small\verb%mk_cons : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a {\small\verb%CONS%} pair.

\DESCRIBE
{\small\verb%mk_cons("t","[t1;...;tn]")%} returns {\small\verb%"[t;t1;...;tn]"%}.

\FAILURE
Fails with {\small\verb%mk_cons%} if second term is not a list or if the first term is not
of the same type as the elements of the list.

\SEEALSO
dest_cons, is_cons, mk_list, dest_list, is_list.

\ENDDOC
\DOC{mk\_const}

\TYPE {\small\verb%mk_const : ((string # type) -> term)%}\egroup

\SYNOPSIS
Constructs a constant.

\DESCRIBE
{\small\verb%mk_const(`const`,":ty")%} returns the constant {\small\verb%"const:ty"%}.

\FAILURE
Fails with {\small\verb%mk_const: ...%} if the string supplied is not the name of a known
constant, or if it is known but the type supplied is not the correct type for
the constant.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#mk_const (`T`,":bool");;
"T" : term

#mk_const (`T`,":num");;
evaluation failed     mk_const: wrong type for T supplied

#mk_const (`test`,":bool");;
evaluation failed     mk_const: test not a constant
\end{verbatim}
}
\SEEALSO
dest_const, is_const, mk_var, mk_comb, mk_abs.

\ENDDOC
\DOC{mk\_conv\_net}

\TYPE {\small\verb%mk_conv_net : (thm list -> conv term_net)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{mk\_definition}

\TYPE {\small\verb%mk_definition : (term -> term)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{mk\_disj}

\TYPE {\small\verb%mk_disj : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a disjunction.

\DESCRIBE
{\small\verb%mk_disj("t1","t2")%} returns {\small\verb%"t1 \/ t2"%}.

\FAILURE
Fails with {\small\verb%mk_disj%} if either {\small\verb%t1%} or {\small\verb%t2%} are not of type {\small\verb%":bool"%}.

\SEEALSO
dest_disj, is_disj, list_mk_disj.

\ENDDOC
\DOC{mk\_eq}

\TYPE {\small\verb%mk_eq : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs an equation.

\DESCRIBE
{\small\verb%mk_eq("t1","t2")%} returns {\small\verb%"t1 = t2"%}.

\FAILURE
Fails with {\small\verb%mk_eq%} if {\small\verb%t1%} and {\small\verb%t2%} have different types.

\SEEALSO
dest_eq, is_eq.

\ENDDOC
\DOC{mk\_exists}

\TYPE {\small\verb%mk_exists : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs an existential quantification.

\DESCRIBE
{\small\verb%mk_exists("var","t")%} returns {\small\verb%"?var. t"%}.

\FAILURE
Fails with {\small\verb%mk_exists%} if first term is not a variable or if {\small\verb%t%} is not of
type {\small\verb%":bool"%}.

\SEEALSO
dest_exists, is_exists, list_mk_exists.

\ENDDOC
\DOC{MK\_EXISTS}

\TYPE {\small\verb%MK_EXISTS : (thm -> thm)%}\egroup

\SYNOPSIS
Existentially quantifies both sides of a universally quantified
equational theorem.

\DESCRIBE
When applied to a theorem {\small\verb%A |- !x. t1 = t2%}, the inference rule {\small\verb%MK_EXISTS%}
returns the theorem {\small\verb%A |- (?x. t1) = (?x. t2)%}.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- !x. t1 = t2
   --------------------------  MK_EXISTS
    A |- (?x. t1) = (?x. t2)
\end{verbatim}
}
\FAILURE
Fails unless the theorem is a singly universally quantified equation.

\SEEALSO
AP_TERM, EXISTS_EQ, GEN, LIST_MK_EXISTS, MK_ABS.

\ENDDOC
\DOC{mk\_forall}

\TYPE {\small\verb%mk_forall : ((term # term) -> term)%}\egroup

\SYNOPSIS
Term constructor for universal quantification.

\DESCRIBE
{\small\verb%mk_forall("var","t")%} returns {\small\verb%"!var. t"%}.

\FAILURE
Fails with {\small\verb%mk_forall%} if first term is not a variable or if {\small\verb%t%} is not of
type {\small\verb%":bool"%}.

\SEEALSO
dest_forall, is_forall, list_mk_forall.

\ENDDOC
\DOC{mk\_form}

\TYPE {\small\verb%mk_form : (term -> form)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{mk\_imp}

\TYPE {\small\verb%mk_imp : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs an implication.

\DESCRIBE
{\small\verb%mk_imp("t1","t2")%} returns {\small\verb%"t1 ==> t2"%}.

\FAILURE
Fails with {\small\verb%mk_imp%} if either {\small\verb%t1%} or {\small\verb%t2%} are not of type {\small\verb%":bool"%}.

\SEEALSO
dest_imp, is_imp, list_mk_imp.

\ENDDOC
\DOC{mk\_let}

\TYPE {\small\verb%mk_let : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a {\small\verb%let%} term.

\DESCRIBE
{\small\verb%mk_let("f","x")%} returns {\small\verb%"LET f x"%}. If {\small\verb%f%} is of the form {\small\verb%"\y. t"%} then
the result will be pretty-printed as {\small\verb%"let y=x in t"%}.

\FAILURE
Fails with {\small\verb%mk_let%} if the types of {\small\verb%f%} and {\small\verb%x%} are such that {\small\verb%"LET f x"%} is
not well-typed. {\small\verb%"LET"%} has most general type:
{\par\samepage\setseps\small
\begin{verbatim}
   ":(* -> **) -> * -> **"
\end{verbatim}
}
\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#mk_let("$= 1","2");;
"LET($= 1)2" : term

#mk_let("\x. x = 1","2");;
"let x = 2 in (x = 1)" : term
\end{verbatim}
}
\SEEALSO
dest_let, is_let.

\ENDDOC
\DOC{mk\_list}

\TYPE {\small\verb%mk_list : ((term list # type) -> term)%}\egroup

\SYNOPSIS
Constructs object-level list from list of terms.

\DESCRIBE
{\small\verb%mk_list(["t1";...;"tn"],":ty")%} returns {\small\verb%"[t1;...;tn]:(ty)list"%}.
The type argument is required so that empty lists can be constructed.

\FAILURE
Fails with {\small\verb%mk_list%} if any term in the list is not of the type specified as
the second argument.

\SEEALSO
dest_list, is_list, mk_cons, dest_cons, is_cons.

\ENDDOC
\DOC{mk\_neg}

\TYPE {\small\verb%mk_neg : (term -> term)%}\egroup

\SYNOPSIS
Constructs a negation.

\DESCRIBE
{\small\verb%mk_neg "t"%} returns {\small\verb%"~t"%}.

\FAILURE
Fails with {\small\verb%mk_neg%} unless {\small\verb%t%} is of type {\small\verb%bool%}.

\SEEALSO
dest_neg, is_neg.

\ENDDOC
\DOC{mk\_pabs}

\TYPE {\small\verb%mk_pabs : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a paired abstraction.

\DESCRIBE
{\small\verb%mk_pabs "(v1,..(..)..,vn)","t"%} returns the abstraction
{\small\verb%"\(v1,..(..)..,vn). t"%}.

\FAILURE
Fails unless the first term is an arbitrarily nested pair composed from
variables.

\SEEALSO
dest_pabs, is_pabs, mk_abs.

\ENDDOC
\DOC{mk\_pair}

\TYPE {\small\verb%mk_pair : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs object-level pair from a pair of terms.

\DESCRIBE
{\small\verb%mk_pair("t1","t2")%} returns {\small\verb%"(t1,t2)"%}.

\FAILURE
Never fails.

\SEEALSO
dest_pair, is_pair, list_mk_pair.

\ENDDOC
\DOC{mk\_pp\_thm}

\TYPE {\small\verb%mk_pp_thm : ((form list # form) -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{mk\_pred}

\TYPE {\small\verb%mk_pred : ((string # term) -> term)%}\egroup

\SYNOPSIS
Makes an application of a predicate.

\DESCRIBE
When applied to the name of a constant predicate, that is a constant of type
{\small\verb%":* -> bool"%} for some type `{\small\verb%*%}', and an operand term, {\small\verb%mk_pred%} constructs
an application of the predicate to the operand.

\FAILURE
Fails if there is no constant with the appropriate name and type.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#mk_pred(`~`,"T");;
"~T" : term
\end{verbatim}
}
\SEEALSO
mk_comb, mk_const, new_predicate.

\ENDDOC
\DOC{mk\_primed\_var}

\TYPE {\small\verb%mk_primed_var : ((string # type) -> term)%}\egroup

\SYNOPSIS
Primes a variable name sufficiently to make it distinct from all constants.

\DESCRIBE
When applied to a string {\small\verb%`v`%} and a type {\small\verb%":ty"%}, the function {\small\verb%mk_primed_var%}
constructs a variable whose name consists of {\small\verb%v%} followed by however many
primes are necessary to make it distinct from any constants in the current
theory.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_theory `wombat`;;
() : void

#mk_primed_var(`x`,":bool");;
"x" : term

#new_constant(`x`,":num");;
() : void

#mk_primed_var(`x`,":bool");;
"x'" : term
\end{verbatim}
}
\SEEALSO
genvar, variant.

\ENDDOC
\DOC{mk\_select}

\TYPE {\small\verb%mk_select : ((term # term) -> term)%}\egroup

\SYNOPSIS
Constructs a choice-term.

\DESCRIBE
{\small\verb%mk_select("var","t")%} returns {\small\verb%"@var. t"%}.

\FAILURE
Fails with {\small\verb%mk_select%} if first term is not a variable or if {\small\verb%t%} is not of
type {\small\verb%":bool"%}.

\SEEALSO
dest_select, is_select.

\ENDDOC
\DOC{mk\_thm}

\TYPE {\small\verb%mk_thm : (((term list # term) -> thm))%}\egroup

\SYNOPSIS
Creates an arbitrary theorem (dangerous!)

\DESCRIBE
The function {\small\verb%mk_thm%} can be used to construct an arbitrary theorem. It is
applied to a pair consisting of the desired assumption list (possibly empty)
and conclusion. All the terms therein should be of type {\small\verb%bool%}.
{\par\samepage\setseps\small
\begin{verbatim}
   mk_thm(["a1";...;"an"],"c") = ({a1,...,an} |- c)
\end{verbatim}
}
\FAILURE
Fails unless all the terms provided for assumptions and conclusion are of type
{\small\verb%bool%}.

\EXAMPLE
The following shows how to create a simple contradiction:
{\par\samepage\setseps\small
\begin{verbatim}
   #mk_thm([],"F");;
   |- F
\end{verbatim}
}
\COMMENTS
Although {\small\verb%mk_thm%} can be useful for experimentation or temporarily plugging
gaps, its use should be avoided if at all possible in important proofs, because
it can be used to create theorems leading to contradictions. The example above
is a trivial case, but it is all too easy to create a contradiction by
asserting `obviously sound' theorems.

All theorems which are likely to be needed can be derived using only HOL's
inbuilt 5 axioms and 8 primitive inference rules, which are provably sound (see
the DESCRIPTION). Basing all proofs, normally via derived rules and tactics, on
just these axioms and inference rules gives proofs which are (apart from bugs
in HOL or the underlying system) completely secure. This is one of the great
strengths of HOL, and it is foolish to sacrifice it to save a little work.

Note that the system shows the type of {\small\verb%mk_thm%} as {\small\verb%(goal -> thm)%}.

\SEEALSO
new_axiom.

\ENDDOC
\DOC{mk\_type}

\TYPE {\small\verb%mk_type : ((string # type list) -> type)%}\egroup

\SYNOPSIS
Constructs a type (other than a variable type).

\DESCRIBE
{\small\verb%mk_type(`op`,[":ty1";...;":tyn"])%} returns {\small\verb%":(ty1,...,tyn)op"%} where {\small\verb%op%}
is the name of a known {\small\verb%n%}-ary type constructor.

\FAILURE
Fails with {\small\verb%mk_type%} if the string is not the name of a known type, or if the
type is known but the length of the list of argument types is not equal to
the arity of the type constructor.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#mk_type (`bool`,[]);;
":bool" : type

#mk_type (`list`,[":bool"]);;
":(bool)list" : type

#mk_type (`fun`,[":num";":bool"]);;
":num -> bool" : type
\end{verbatim}
}
\SEEALSO
dest_type, mk_vartype.

\ENDDOC
\DOC{mk\_var}

\TYPE {\small\verb%mk_var : ((string # type) -> term)%}\egroup

\SYNOPSIS
Constructs a variable of given name and type.

\DESCRIBE
{\small\verb%mk_var(`var`,":ty")%} returns the variable {\small\verb%"var:ty"%}.

\FAILURE
Never fails.

\COMMENTS
{\small\verb%mk_var%} can be used to construct variables with names which are not
acceptable to the term parser. In particular, a variable with the name of a
known constant can be constructed using {\small\verb%mk_var%}.

\SEEALSO
dest_var, is_var, mk_const, mk_comb, mk_abs.

\ENDDOC
\DOC{mk\_vartype}

\TYPE {\small\verb%mk_vartype : (string -> type)%}\egroup

\SYNOPSIS
Constructs a type variable of the given name.

\DESCRIBE
{\small\verb%mk_vartype(`*...`)%} returns {\small\verb%":*..."%}.

\FAILURE
Fails with {\small\verb%mk_vartype%} if the string does not begin with {\small\verb%`*`%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#mk_vartype `*test`;;
":*test" : type

#mk_vartype `test`;;
evaluation failed     mk_vartype
\end{verbatim}
}
\COMMENTS
{\small\verb%mk_vartype%} can be used to create type variables with names which will not
parse, i.e. they cannot be entered by quotation.

\SEEALSO
dest_vartype, is_vartype, mk_type.

\ENDDOC
\DOC{ml\_curried\_infix}

\TYPE {\small\verb%ml_curried_infix : (string -> void)%}\egroup

\SYNOPSIS
Declares an ML identifier to have infix status (for curried functions).

\DESCRIBE
{\small\verb%ml_curried_infix `string`%} declares to the ML parser that {\small\verb%string%} has infix
status. The identifier {\small\verb%string%} should be bound to a curried function.

\FAILURE
Only ordinary identifiers and certain single character, non-digit, non-layout
strings can be used as infixes. An attempt to infix other strings may fail,
or it may succeed but have unpredictable effects on the parser.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ml_curried_infix `plus`;;
() : void

#let x plus y = x + y;;
plus = - : (int -> int -> int)

#1 plus 2;;
3 : int
\end{verbatim}
}
\SEEALSO
ml_paired_infix, is_ml_curried_infix, is_ml_paired_infix, is_ml_infix.

\ENDDOC
\DOC{ml\_dir\_pathname}

\TYPE {\small\verb%ml_dir_pathname : string%}\egroup

\SYNOPSIS
Absolute pathname to the HOL ML sources.

\DESCRIBE
For implementation reasons, the ML variable {\small\verb%ml_dir_pathname%} is bound when
the system if built to a string giving the absolute pathname of the directory
containing the HOL ML sources.  This value is not for general use.

\FAILURE
Evaluating {\small\verb%ml_dir_pathname%} never fails.

\SEEALSO
lisp_dir_pathname.

\ENDDOC
\DOC{ML\_eval}

\TYPE {\small\verb%ML_eval : (string -> void)%}\egroup

\SYNOPSIS
Passes a string to the ML interpreter.

\DESCRIBE
When applied to a string, {\small\verb%ML_eval%} will pass it to the ML interpreter, which,
after evaluating other pending phrases, will interpret it as if it had been
typed at toplevel.

\FAILURE
The call itself never fails, but of course the subsequent interpretation may do.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ML_eval(`let greeting = \`Hi there!\` in tty_write greeting;;
#`);;
() : void

Hi there!() : void
\end{verbatim}
}
\SEEALSO
inject_input, let_after, let_before.

\ENDDOC
\DOC{ml\_paired\_infix}

\TYPE {\small\verb%ml_paired_infix : (string -> void)%}\egroup

\SYNOPSIS
Declares an ML identifier to have infix status
(for functions that take a pair as argument).

\DESCRIBE
{\small\verb%ml_paired_infix `string`%} declares to the ML parser that {\small\verb%string%} has infix
status. {\small\verb%string%} should be bound to a function that takes a pair as its
argument.

\FAILURE
Only ordinary identifiers and certain single character, non-digit, non-layout
strings can be used as infixes. An attempt to infix other strings may fail,
or it may succeed but have unpredictable effects on the parser.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#ml_paired_infix `plus`;;
() : void

#let x plus y = x + y;;
plus = - : ((int # int) -> int)

#1 plus 2;;
3 : int
\end{verbatim}
}
\SEEALSO
ml_curried_infix, is_ml_paired_infix, is_ml_curried_infix, is_ml_infix.

\ENDDOC
\DOC{MP}

\TYPE {\small\verb%MP : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Implements the Modus Ponens inference rule.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- t1 ==> t2%} and {\small\verb%A2 |- t1%},
the inference rule {\small\verb%MP%} returns the theorem {\small\verb%A1 u A2 |- t2%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1 ==> t2   A2 |- t1
   ----------------------------  MP
          A1 u A2 |- t2
\end{verbatim}
}
\FAILURE
Fails unless the first theorem is an implication whose antecedent is the
same as the conclusion of the second theorem (up to alpha-conversion).

\SEEALSO
EQ_MP, LIST_MP, MATCH_MP, MATCH_MP_TAC, MP_TAC, NOT_MP.

\ENDDOC
\DOC{MP\_TAC}

\TYPE {\small\verb%MP_TAC : thm_tactic%}\egroup

\SYNOPSIS
Reduces a goal to implication from a known theorem.

\DESCRIBE
When applied to the theorem {\small\verb%A' |- s%} and the goal {\small\verb%A ?- t%}, the tactic
{\small\verb%MP_TAC%} reduces the goal to {\small\verb%A ?- s ==> t%}. Unless {\small\verb%A'%} is a subset of
{\small\verb%A%}, this is an invalid tactic.
{\par\samepage\setseps\small
\begin{verbatim}
       A ?- t
   ==============  MP_TAC (A' |- s)
    A ?- s ==> t
\end{verbatim}
}
\FAILURE
Never fails.

\SEEALSO
MATCH_MP_TAC, MP, UNDISCH_TAC.

\ENDDOC
\DOC{NEG\_DISCH}

\TYPE {\small\verb%NEG_DISCH : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Discharges an assumption, transforming {\small\verb%|- s ==> F%} into {\small\verb%|- ~s%}.

\DESCRIBE
When applied to a term {\small\verb%s%} and a theorem {\small\verb%A |- t%}, the inference
rule {\small\verb%NEG_DISCH%} returns the theorem {\small\verb%A - {s} |- s ==> t%}, or if {\small\verb%t%}
is just {\small\verb%F%}, returns the theorem {\small\verb%A - {s} |- ~s%}.
{\par\samepage\setseps\small
\begin{verbatim}
          A |- F
   --------------------  NEG_DISCH    [special case]
      A - {s} |- ~s

          A |- t
   --------------------  NEG_DISCH    [general case]
    A - {s} |- s ==> t

\end{verbatim}
}
\FAILURE
Fails unless the supplied term has type {\small\verb%bool%}.

\SEEALSO
DISCH, NOT_ELIM, NOT_INTRO.

\ENDDOC
\DOC{new\_alphanum}

\TYPE {\small\verb%new_alphanum : (string -> void)%}\egroup

\SYNOPSIS
Defines a character to be alphanumeric.

\DESCRIBE
When given a string, which should be of length 1, {\small\verb%new_alphanum%} extends
the scope of the definition of `alphanumeric' as used by {\small\verb%is_alphanum%}.
(If the supplied string is null ({\small\verb%``%}) then {\small\verb%new_alphanum%} has no effect.)

The term `alphanumeric' initially means one of the following:
{\small\verb%a..z A..Z 0..9 _ '%}. A call to {\small\verb%new_alphanum%} can affect ML lexical analysis
dynamically, because the function {\small\verb%is_alphanum%} is called by the lexical
analyzer to check for characters beyond the first in an identifier.

\EXAMPLE
Suppose we set a variable {\small\verb%y%} as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #let y = 2;;
   y = 2 : int
\end{verbatim}
}
\noindent then {\small\verb%y-1%} is a numeric expression:
{\par\samepage\setseps\small
\begin{verbatim}
   #let x = y-1;;
   x = 1 : int
\end{verbatim}
}
\noindent but after defining {\small\verb%-%} to be alphanumeric:
{\par\samepage\setseps\small
\begin{verbatim}
   #new_alphanum `-`;;
   () : void
\end{verbatim}
}
\noindent {\small\verb%y-1%} counts as a single token (which is undefined).
{\par\samepage\setseps\small
\begin{verbatim}
   #let x = y-1;;
   unbound or non-assignable variable y-1
\end{verbatim}
}
\FAILURE
Fails if the string has length greater than 1.

\SEEALSO
ascii, ascii_code, is_alphanum, is_letter, new_alphanum.

\ENDDOC
\DOC{new\_axiom}

\TYPE {\small\verb%new_axiom : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Sets up a new axiom in the current theory.

\DESCRIBE
If {\small\verb%tm%} is a term of type {\small\verb%bool%}, a call {\small\verb%new_axiom(`name`,"tm")%} creates a
theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x1..xn. tm
\end{verbatim}
}
\noindent and stores it away in the theory file. Note that all free variables
in {\small\verb%tm%} are generalized automatically before the axiom is set up.

\FAILURE
Fails if HOL is not in draft mode, or there is already an axiom or definition
of that name in the current theory, or it the given term does not have type
{\small\verb%bool%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_theory `gurk`;;
() : void

#new_axiom(`untrue`,"x = 1");;
|- !x. x = 1
\end{verbatim}
}
\COMMENTS
For most purposes, it is unnecessary to declare new axioms: all of classical
mathematics can be derived by definitional extension alone. Proceeding by
definition is not only more elegant, but also guarantees the consistency of the
deductions made. However, there are certain entities which cannot be modelled
in simple type theory without further axioms, such as higher transfinite
ordinals.

\SEEALSO
mk_thm, new_definition.

\ENDDOC
\DOC{new\_binder\_definition}

\TYPE {\small\verb%new_binder_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Defines a new constant, giving it the syntactic status of a binder.

\DESCRIBE
The function {\small\verb%new_binder_definition%} provides a facility for making
definitional extensions to the current theory by introducing a constant
definition.  It takes a pair of arguments, consisting of the name under which
the resulting theorem will be saved in the current theory segment and a term
giving the desired definition.  The value returned by {\small\verb%new_binder_definition%}
is a theorem which states the definition requested by the user.

Let {\small\verb%v1%}, ..., {\small\verb%vn%} be syntactically distinct tuples constructed from the
variables {\small\verb%x1,...,xm%}.  A binder is defined by evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   new_binder_definition (`name`, "b v1 ... vn = t")
\end{verbatim}
}
\noindent where {\small\verb%b%} is not already a constant, {\small\verb%b%} does not occur in {\small\verb%t%}, all
the free variables that occur in {\small\verb%t%} are a subset of {\small\verb%x1,...,xn%}, and the type
of {\small\verb%b%} has the form `{\small\verb%(ty1->ty2)->ty3%}'.  This declares {\small\verb%b%} to be a new
constant with the syntactic status of a binder in the current theory, and with
the definitional theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x1...xn. b v1 ... vn = t
\end{verbatim}
}
\noindent as its specification.  This constant specification for {\small\verb%b%} is saved
in the current theory under the name {\small\verb%name%} and is returned as a theorem.

The equation supplied to {\small\verb%new_binder_definition%} may optionally have any of its
free variables universally quantified at the outermost level.  The constant {\small\verb%b%}
has binder status only after the definition has been made.

\FAILURE
{\small\verb%new_binder_definition%} fails if called when HOL is not in draft mode.  It also
fails if there is already an axiom, definition or specification with the given
name in the current theory segment, if {\small\verb%`b`%} is already a constant in the
current theory or is not an allowed name for a constant, if {\small\verb%t%} contains free
variables that are not in any one of the variable structures {\small\verb%v1%}, ..., {\small\verb%vn%} or
if any variable occurs more than once in {\small\verb%v1, ..., v2%}.  Failure also occurs if
the type of {\small\verb%b%} is not of the form appropriate for a binder, namely a type of
teh form `{\small\verb%(ty1->ty2)->ty3%}'.  Finally, failure occurs if there is a type
variable in {\small\verb%v1%}, ..., {\small\verb%vn%} or {\small\verb%t%} that does not occur in the type of {\small\verb%b%}.

\EXAMPLE
The unique-existence quantifier {\small\verb%?!%} is defined as follows.
{\par\samepage\setseps\small
\begin{verbatim}
   #new_binder_definition
     (`EXISTS_UNIQUE_DEF`,
      "$?! = \P:(*->bool). ($? P) /\ (!x y. ((P x) /\ (P y)) ==> (x=y))");;
   |- $?! = (\P. $? P /\ (!x y. P x /\ P y ==> (x = y)))
\end{verbatim}
}
\COMMENTS
It is a common practice among HOL users to write a {\small\verb%$%} before the constant
being defined as a binder to indicate that it will have a special syntactic
status after the definition is made:
{\par\samepage\setseps\small
\begin{verbatim}
   new_binder_definition(`name`, "$b = ... ");;
\end{verbatim}
}
\noindent This use of {\small\verb%$%} is not necessary; but after the definition
has been made {\small\verb%$%} must, of course, be used if the syntactic status of {\small\verb%b%}
needs to be suppressed.

\SEEALSO
new_definition, new_gen_definition, new_infix_definition,
new_infix_list_rec_definition, new_prim_rec_definition,
new_list_rec_definition, new_prim_rec_definition.

\ENDDOC
\DOC{new\_binder}

\TYPE {\small\verb%new_binder : ((string # type) -> void)%}\egroup

\SYNOPSIS
Sets up a new binder in the current theory.

\DESCRIBE
A call {\small\verb%new_binder(`bnd`,":ty")%} declares a new binder {\small\verb%bnd%} in the current
theory. The type must be of the form {\small\verb%(* -> **) -> ***%}, because being a binder,
{\small\verb%bnd%} will apply to an abstraction; for example {\small\verb%"!x:bool. (x=T) \/ (x=F)"%} is
actually a prettyprinting of {\small\verb%"$! (\x. (x=T) \/ (x=F))"%}.

\FAILURE
Fails if HOL is not in draft mode, or there is already a constant of some sort
of that name in the current theory, or if the type does not correspond to the
above pattern.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_theory `anorak`;;
() : void

#new_binder(`!!`,":(bool->bool)->bool");;
() : void

#"!!x. T";;
"!! x. T" : term
\end{verbatim}
}
\SEEALSO
binders, is_binder.

\ENDDOC
\DOC{new\_constant}

\TYPE {\small\verb%new_constant : ((string # type) -> void)%}\egroup

\SYNOPSIS
Declares a new constant in the current theory.

\DESCRIBE
A call {\small\verb%new_constant(`c`,":ty")%} makes {\small\verb%c%} a constant in the current theory.
Note that it does not specify its value. The constant may have a polymorphic
type, which can be used in arbitrary instantiations.

\FAILURE
Fails if HOL is not in draft mode, or if the name is not a valid constant
name, or there is already a constant of that name in the current theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_theory `zonk`;;
() : void

#new_constant(`graham's_number`,":num");;
() : void
\end{verbatim}
}
\SEEALSO
constants, infixes, is_constant, is_infix, new_infix, new_definition,
new_infix_definition.

\ENDDOC
\DOC{new\_definition}

\TYPE {\small\verb%new_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Declare a new constant and install a definitional axiom in the current theory.

\DESCRIBE
The function {\small\verb%new_definition%} provides a facility for definitional
extensions to the current theory.  It takes a pair argument consisting
of the name under which the resulting definition will be saved
in the current theory segment, and a term giving the desired definition.  The
value returned by {\small\verb%new_definition%} is a theorem which states the definition
requested by the user.

Let {\small\verb%v_1%},...,{\small\verb%v_n%} be tuples of distinct variables, containing the variables
{\small\verb%x_1,...,x_m%}.  Evaluating {\small\verb%new_definition (`name`, "c v_1 ... v_n = t")%},
where {\small\verb%c%} is not already a constant, declares the sequent {\small\verb%({},"\v_1  ...
v_n. t")%} to be a definition in the current theory, and declares {\small\verb%c%} to be
a new constant in the current theory with this definition as its specification.
This constant specification is returned as a theorem with the form
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x_1 ... x_m. c v_1 ... v_n = t
\end{verbatim}
}
\noindent and is saved in the current theory under
(the name) {\small\verb%name%}.  Optionally, the definitional term argument
may have any of its variables universally quantified.

\FAILURE
{\small\verb%new_definition%} fails if called when HOL is not in draft mode.  It also
fails if there is already an axiom, definition or specification of the given
name in the current theory segment; if {\small\verb%`c`%} is already a constant in the
current theory or is not an allowed name for a constant; if {\small\verb%t%} contains free
variables that are not in any of the variable structures {\small\verb%v_1%}, ..., {\small\verb%v_n%}
(this is equivalent to requiring {\small\verb%\v_1 ... v_n. t%} to be a closed term); or if
any variable occurs more than once in {\small\verb%v_1, ..., v_n%}.  Finally, failure occurs
if there is a type variable in {\small\verb%v_1%}, ..., {\small\verb%v_n%} or {\small\verb%t%} that does not occur in
the type of {\small\verb%c%}.

\EXAMPLE
A NAND relation can be defined as follows.
{\par\samepage\setseps\small
\begin{verbatim}
   #new_definition
    (`NAND2`, "NAND2 (in_1,in_2) out = !t:num. out t = ~(in_1 t /\ in_2 t)");;
   |- !in_1 in_2 out.
       NAND2 (in_1,in_2)out = (!t. out t = ~(in_1 t /\ in_2 t))
\end{verbatim}
}
\SEEALSO
new_binder_definition, new_gen_definition, new_infix_definition,
new_infix_list_rec_definition, new_prim_rec_definition,
new_list_rec_definition, new_prim_rec_definition, new_recursive_definition,
new_specification.

\ENDDOC
\DOC{new\_flag}

\TYPE {\small\verb%new_flag : ((string # bool) -> void)%}\egroup

\SYNOPSIS
Creates a new settable flag.

\DESCRIBE
A call {\small\verb%new_flag(`flagname`,init)%} declares a new settable flag called
{\small\verb%flagname%}, with an initial setting of {\small\verb%init%} (either {\small\verb%true%} or {\small\verb%false%}).
Like a system flag, it can be read and written to with {\small\verb%get_flag_value%} and
{\small\verb%set_flag_value%} respectively, and will be listed along with the others by
{\small\verb%flags()%}.

\FAILURE
Fails if there is already a flag of the given name.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_flag(`parser hacked`,false);;
() : void

#get_flag_value `parser hacked`;;
false : bool
\end{verbatim}
}
\SEEALSO
flags, get_flag_value, set_flag_value.

\ENDDOC
\DOC{new\_gen\_definition}

\TYPE {\small\verb%new_gen_definition : (string -> (string # term) -> thm)%}\egroup

\SYNOPSIS
Defines a new constant, infix constant, or binder constant.

\DESCRIBE
The function {\small\verb%new_gen_definition%} provides a facility for definitional
extensions to the current theory.  It takes two arguments.  The first is a flag
which can have one of three values: {\small\verb%`constant`%}, {\small\verb%`infix`%}, or {\small\verb%`binder`%},
indicating the status of the object being defined.  The second argument is a
pair consisting of the name under which the resulting definition will be saved
in the current theory segment, and a term giving the desired definition.  The
value returned by {\small\verb%new_gen_definition%} is a theorem which states the definition
requested by the user.

Let {\small\verb%v_1%},...,{\small\verb%v_n%} be tuples of distinct variables, containing the variables
{\small\verb%x_1,...,x_m%}.  Evaluating {\small\verb%new_gen_definition flag (`name`, "c v_1 ... v_n =
t")%}, where {\small\verb%c%} is not already a constant, declares the sequent {\small\verb%({},"\v_1
... v_n. t")%} to be a definition in the current theory, and declares {\small\verb%c%} to be
a new constant in the current theory with this definition as its specification.
This constant specification is returned as a theorem, generally of the form {\small\verb%|-
!x_1 ... x_m. c v_1 ... v_n = t%} , and is saved in the current theory under
(the name) {\small\verb%name%}.  If {\small\verb%flag%} is {\small\verb%`infix`%} or {\small\verb%`binder`%}, the constant is given
infix or binder status accordingly.  Optionally, the definitional term argument
may have any of its variables universally quantified.

\FAILURE
{\small\verb%new_gen_definition%} fails if called when HOL is not in draft mode.  It also
fails if there is already an axiom, definition or specification of the given
name in the current theory segment; if {\small\verb%c%} is already a constant in the
current theory or is not an allowed name for a constant; if {\small\verb%t%} contains free
variables that are not in any of the variable structures {\small\verb%v_1%}, ..., {\small\verb%v_n%}
(this is equivalent to requiring {\small\verb%\v_1 ... v_n. t%} to be a closed term); or if
any variable occurs more than once in {\small\verb%v_1, ..., v_n%}.  Failure also occurs if
{\small\verb%flag%} is not one of {\small\verb%`constant`%}, {\small\verb%`infix`%} or {\small\verb%`binder`%} or if the type of {\small\verb%c%}
is not suitable for a constant with the syntactic status specified by {\small\verb%flag%}.
Finally, failure occurs if there is a type variable in {\small\verb%v_1%}, ..., {\small\verb%v_n%} or {\small\verb%t%}
that does not occur in the type of {\small\verb%c%}.

\USES
Used to define the special purpose functions {\small\verb%new_definition%},
{\small\verb%new_infix_definition%}, and {\small\verb%new_binder_definition%}, which are used for
defining objects with a particular status.

\SEEALSO
DEF_EXISTS_RULE, new_binder_definition, new_definition, new_infix_definition,
new_specification.

\ENDDOC
\DOC{new\_infix\_definition}

\TYPE {\small\verb%new_infix_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Declares a new infix constant and installs a definitional axiom in the current
theory.

\DESCRIBE
The function {\small\verb%new_infix_definition%} provides a facility for definitional
extensions to the current theory.  It takes a pair argument consisting
of the name under which the resulting definition will be saved
in the current theory segment, and a term giving the desired definition.  The
value returned by {\small\verb%new_infix_definition%} is a theorem which states the
definition requested by the user.

Let {\small\verb%v_1%} and {\small\verb%v_2%} be tuples of distinct variables, containing the variables
{\small\verb%x_1,...,x_m%}.  Evaluating {\small\verb%new_infix_definition (`name`, "ix v_1 v_2 = t")%},
where {\small\verb%ix%} is not already a constant, declares the sequent {\small\verb%({},"\v_1 v_2.
t")%} to be a definition in the current theory, and declares {\small\verb%ix%} to be
a new constant in the current theory with this definition as its specification.
This constant specification is returned as a theorem with the form
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x_1 ... x_m. v_1 ix v_2 = t
\end{verbatim}
}
\noindent and is saved in the current theory under
(the name) {\small\verb%name%}.  Optionally, the definitional term argument
may have any of its variables universally quantified.
The constant {\small\verb%ix%} has infix status only after the infix
declaration has been processed.  It is therefore necessary to use
the constant in normal prefix position when making the definition.

\FAILURE
{\small\verb%new_infix_definition%} fails if called when HOL is not in draft mode.  It also
fails if there is already an axiom, definition or specification of the given
name in the current theory segment; if {\small\verb%`ix`%} is already a constant in the
current theory or is not an allowed name for a constant; if {\small\verb%t%} contains free
variables that are not in either of the variable structures {\small\verb%v_1%} and {\small\verb%v_2%}
(this is equivalent to requiring {\small\verb%\v_1 v_2. t%} to be a closed term); or if any
variable occurs more than once in {\small\verb%v_1, v_2%}.  Failure also occurs if the type
of {\small\verb%ix%} is not of the form {\small\verb%:ty_1->ty_2->ty_3%}.  Finally, failure occurs if
there is a type variable in {\small\verb%v_1%}, ..., {\small\verb%v_n%} or {\small\verb%t%} that does not occur in the
type of {\small\verb%ix%}.

\EXAMPLE
The nand function can be defined as follows.
{\par\samepage\setseps\small
\begin{verbatim}
   #new_infix_definition
    (`nand`, "$nand in_1 in_2 = ~(in_1 /\ in_2)");;
   |- !in_1 in_2. in_1 nand in_2 = ~(in_1 /\ in_2)
\end{verbatim}
}
\COMMENTS
It is a common practice among HOL users to write a {\small\verb%$%} before
the constant being defined as an infix to indicate that after the
definition is made, it will have a special syntactic status; ie. to
write:
{\par\samepage\setseps\small
\begin{verbatim}
   new_infix_definition(`ix_DEF`, "$ix m n = ... ")
\end{verbatim}
}
\noindent This use of {\small\verb%$%} is not necessary; but after the definition
has been made {\small\verb%$%} must, of course, be used if the syntactic status
needs to be suppressed.

\SEEALSO
new_binder_definition, new_definition, new_gen_definition,
new_infix_list_rec_definition, new_prim_rec_definition, new_list_rec_definition,
new_prim_rec_definition.

\ENDDOC
\DOC{new\_infix}

\TYPE {\small\verb%new_infix : ((string # type) -> void)%}\egroup

\SYNOPSIS
Declares a new infix constant in the current theory.

\DESCRIBE
A call {\small\verb%new_infix(`i`,":ty")%} makes {\small\verb%i%} an infix
constant in the current theory. Note that it does not specifiy its value.
The constant may have a polymorphic type, which may be arbitrarily
instantiated. Like any other infix or binder, its special parse status may be
suppressed by preceding it with a dollar sign.

\FAILURE
Fails if HOL is not in draft mode, or if the name is not a valid constant
name, or there is already a constant of that name in the current theory.

\EXAMPLE
The following shows the use of the curried form as well as the infix:
{\par\samepage\setseps\small
\begin{verbatim}
   #new_theory `groke`;;
   () : void

   #new_infix(`orelse`,":bool->bool->bool");;
   () : void

   #"T orelse F";;
   "T orelse F" : term

   #"$orelse T F";;
   "T orelse F" : term
\end{verbatim}
}
\SEEALSO
constants, infixes, is_constant, is_infix, new_constant, new_definition,
new_infix_definition.

\ENDDOC
\DOC{new\_infix\_list\_rec\_definition}

\TYPE {\small\verb%new_infix_list_rec_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Defines an infix primitive recursive function over the type of lists.

\DESCRIBE
The function {\small\verb%new_infix_list_rec_definition%} provides the facility for defining
primitive recursive functions with infix status on the type of lists. It
takes a pair argument, consisting of the name under which the resulting
definition will be saved in the current theory segment, and a term giving the
desired definition.  The value returned by {\small\verb%new_infix_list_rec_definition%} is
a theorem which states the definition requested by the user.  This theorem is
derived by formal proof from an instance of the theorem {\small\verb%list_Axiom%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x f. ?! fn. (fn[] = x) /\ (!h t. fn(CONS h t) = f(fn t)h t)
\end{verbatim}
}
\noindent Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   new_infix_list_rec_definition
    (`fun_DEF`,
     "(fun [] x = f_1[x]) /\
      (fun (CONS h t) x = f_2[fun t x', h, t, x])");;
\end{verbatim}
}
\noindent where all the free variables in the term {\small\verb%x'%} are
contained in {\small\verb%{h, t, x}%}, automatically proves the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |-  ?fun. !x. fun x = f_1[x] /\
             !x. fun (CONS h t) x = f_2[fun t x', h, t, x]
\end{verbatim}
}
\noindent and then declares a new constant {\small\verb%fun%} with this property as its
specification. This constant specification is returned as a theorem by
{\small\verb%new_infix_list_rec_definition%} and is saved with name {\small\verb%fun_DEF%} in the
current theory segment.

The ML function {\small\verb%new_infix_list_rec_definition%} is, in fact, slightly
more general than is indicated above.  In particular, a curried
primitive recursive function can be defined by primitive recursion on
either one of its arguments using this ML function.  The ML function
{\small\verb%new_infix_list_rec_definition%} also allows the user to partially
specify the value of a function defined (possibly recursively) on
lists by giving its value for only one of {\small\verb%[]%} or {\small\verb%CONS h t%}.

\FAILURE
Failure occurs if: HOL cannot prove there is a function satisfying the
specification (i.e. if the term supplied to {\small\verb%new_infix_list_rec_definition%}
is not a well-formed primitive recursive definition), or if
any other condition for making a constant specification is violated
(see the failure conditions for {\small\verb%new_specification%}).

\EXAMPLE
An infix append function on polymorphic lists can be defined by
{\par\samepage\setseps\small
\begin{verbatim}
   new_infix_list_rec_definition
   (`app_i`, "($app_i [] l = l) /\
              ($app_i (CONS (h:*) t) l = CONS h ($app_i t l))");;
\end{verbatim}
}
\noindent The {\small\verb%$%}'s are there (as documentation) to indicate that the constant
{\small\verb%app_i%} is being declared to be an infix.  Evaluating this ML expression will
create the following constant specification in the current theory segment:
{\par\samepage\setseps\small
\begin{verbatim}
    |- (!l. [] app_i l = l) /\ (!h t l. (CONS h t) app_i l = CONS h(t app_i l))
\end{verbatim}
}
\SEEALSO
new_definition, new_infix_definition, new_infix_prim_rec_definition,
new_list_rec_definition, new_prim_rec_definition, new_recursive_definition,
new_type_definition, new_specification, list_Axiom.

\ENDDOC
\DOC{new\_infix\_prim\_rec\_definition}

\TYPE {\small\verb%new_infix_prim_rec_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Defines an infix primitive recursive function over the type {\small\verb%num%}.

\DESCRIBE
The function {\small\verb%new_infix_prim_rec_definition%} provides the facility for defining
primitive recursive functions with infix status on the type {\small\verb%num%}. It takes a
pair argument, consisting of the name under which the resulting definition will
be saved in the current theory segment, and a term giving the desired
definition.  The value returned by {\small\verb%new_infix_prim_rec_definition%} is a theorem
which states the definition requested by the user.  This theorem is derived by
formal proof from an instance of the theorem {\small\verb%num_Axiom%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !e f. ?! fn. (fn 0 = e) /\ (!n. fn(SUC n) = f(fn n)n)
\end{verbatim}
}
\noindent Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   new_infix_prim_rec_definition
    (`fun_DEF`,
     "(fun 0 x = f_1[x]) /\
      (fun (SUC n) x = f_2[fun n x', n, x])");;
\end{verbatim}
}
\noindent where all the free variables in the term {\small\verb%x'%} are
contained in {\small\verb%{n, x}%}, automatically proves the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |-  ?fun. !x. fun 0 x = f_1[x] /\
             !x. fun (SUC n) x = f_2[fun n x', n, x]
\end{verbatim}
}
\noindent and then declares a new constant {\small\verb%fun%} with this property and infix
status as its specification. This constant specification is returned as a
theorem and is saved with name {\small\verb%fun_DEF%} in the current theory segment.

The ML function {\small\verb%new_infix_prim_rec_definition%} is, in fact, slightly more
general than is indicated above.  In particular, a curried primitive recursive
function can be defined by primitive recursion on either one of its arguments
using this ML function.  The ML function {\small\verb%new_infix_prim_rec_definition%} also
allows the user to partially specify the value of a function defined (possibly
recursively) on the natural numbers by giving its value for only one of {\small\verb%0%} or
{\small\verb%SUC n%}.

\FAILURE
Failure occurs if HOL cannot prove there is a function satisfying the
specification (ie. if the term supplied to {\small\verb%new_prim_rec_definition%} is not a
well-formed primitive recursive definition); if the type of {\small\verb%fun%} is not of the
form {\small\verb%ty_1->ty_2->ty_3%}, or if any other condition for making a constant
specification is violated (see the failure conditions for {\small\verb%new_specification%}).

\EXAMPLE
Here is the recursive definition of the constant {\small\verb%+%} used by the system:
{\par\samepage\setseps\small
\begin{verbatim}
   new_infix_prim_rec_definition
    (`ADD`,
     "($+ 0 n = n) /\
      ($+ (SUC m) n = SUC($+ m n))")
\end{verbatim}
}
\noindent The {\small\verb%$%}'s are there (as documentation) to indicate that the constant
{\small\verb%+%} is being declared to be an infix.  Evaluating this ML expression will
create the following constant specification in the current theory segment:
{\par\samepage\setseps\small
\begin{verbatim}
   ADD = |- (!n. 0 + n = n) /\ (!m n. (SUC m) + n = SUC(m + n))
\end{verbatim}
}
\SEEALSO
new_definition, new_infix_definition, new_infix_list_rec_definition,
new_prim_rec_definition, new_list_rec_definition, new_recursive_definition,
new_type_definition, new_specification, num_Axiom.

\ENDDOC
\DOC{new\_letter}

\TYPE {\small\verb%new_letter : (string -> void)%}\egroup

\SYNOPSIS
Defines a character to be a letter.

\DESCRIBE
When given a string, which should be of length 1, {\small\verb%new_letter%} extends
the scope of the definition of `letter' as used by {\small\verb%is_letter%}.
(If the supplied string is null ({\small\verb%``%}) {\small\verb%new_letter%} has no effect.)

The definition of a `letter' by default includes (only)
{\small\verb%a..z A..Z%}. A call to {\small\verb%new_letter%} can affect ML lexical analysis dynamically,
because the function {\small\verb%is_letter%} is called by the lexical analyzer to check for
the start of an identifier.

\EXAMPLE
In the default state, {\small\verb%-1%} is parsed as the application of {\small\verb%-%} to {\small\verb%1%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #let x = -1 ;;
   x = -1 : int
\end{verbatim}
}
\noindent but if we make {\small\verb%-%} into a letter:
{\par\samepage\setseps\small
\begin{verbatim}
   #new_letter(`-`);;
   () : void
\end{verbatim}
}
\noindent then {\small\verb%-1%} parses as an (undefined) identifier.
{\par\samepage\setseps\small
\begin{verbatim}
   #let x = -1;;
   unbound or non-assignable variable -1
\end{verbatim}
}
\FAILURE
Fails if the string has length greater than 1.

\SEEALSO
ascii, ascii_code, is_alphanum, is_letter, new_alphanum.

\ENDDOC
\DOC{new\_list\_rec\_definition}

\TYPE {\small\verb%new_list_rec_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Defines a primitive recursive function over the type of lists.

\DESCRIBE
The function {\small\verb%new_list_rec_definition%} provides the facility for defining
primitive recursive functions on the type of lists. It takes a pair argument,
consisting of the name under which the resulting definition will be saved in
the current theory segment, and a term giving the desired definition.  The
value returned by {\small\verb%new_list_rec_definition%} is a theorem which states the
definition requested by the user.  This theorem is derived by formal proof from
an instance of the theorem {\small\verb%list_Axiom%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x f. ?! fn. (fn[] = x) /\ (!h t. fn(CONS h t) = f(fn t)h t)
\end{verbatim}
}
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   new_list_rec_definition
    (`fun_DEF`,
     "(fun x_1 ... [] ... x_i = f_1[x_1, ..., x_i]) /\
      (fun x_1 ... (CONS h t) ... x_i =
               f_2[fun t_1 ... t ... t_i, x_1, ..., h, t, ..., x_i])");;
\end{verbatim}
}
\noindent where all the free variables in the terms {\small\verb%t_1%}, ..., {\small\verb%t_i%} are
contained in {\small\verb%{h,t,x_1,...,x_i}%}, automatically proves the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |-  ?fun. !x_1 ... x_i. fun x_1 ... [] ... x_i = f_1[x_1, ..., x_i] /\
             !x_1 ... x_i. fun (CONS h t) x_1 ... x_i =
                            f_2[fun t_1 ... t ... t_i, x_1, ..., h, t, ...,x_i]
\end{verbatim}
}
\noindent and then declares a new constant {\small\verb%fun%} with this property as its
specification. This constant specification is returned as a theorem by
{\small\verb%new_list_rec_definition%} and is saved with name {\small\verb%fun_DEF%} in the
current theory segment.

The ML function {\small\verb%new_list_rec_definition%} also allows the user to
partially specify the value of a function defined (possibly recursively) on
lists by giving its value for only one of {\small\verb%[]%} or {\small\verb%CONS h t%}.  See the
examples below.

\FAILURE
Failure occurs if HOL cannot prove there is a function satisfying the
specification (ie. if the term supplied to ml{\small\verb%new_list_rec_definition%}
is not a well-formed primitive recursive definition), or if
any other condition for making a constant specification is violated
(see the failure conditions for {\small\verb%new_specification%}).

\EXAMPLE
The HOL system defines a length function, {\small\verb%LENGTH%}, on lists by the
primitive recursive definition on lists shown below:
{\par\samepage\setseps\small
\begin{verbatim}
   new_list_rec_definition
     (`LENGTH`,
     "(LENGTH NIL = 0) /\
      (!h:*. !t. LENGTH (CONS h t) = SUC (LENGTH t))")
\end{verbatim}
}
\noindent When this ML expression is evaluated, HOL uses {\small\verb%list_Axiom%}
to prove existence of a function that satisfies the given primitive
recursive definition, introduces a constant to name this function
using a constant specification, and stores the resulting theorem:
{\par\samepage\setseps\small
\begin{verbatim}
    LENGTH   |- (LENGTH[] = 0) /\ (!h t. LENGTH(CONS h t) = SUC(LENGTH t))
\end{verbatim}
}
\noindent in the current theory segment (in this case, the theory {\small\verb%list%}).

Using  {\small\verb%new_list_rec_definition%},   the  predicate   {\small\verb%NULL%}  and  the
selectors {\small\verb%HD%} and  {\small\verb%TL%} are  defined
 in  the theory  {\small\verb%list%} by the
specifications:
{\par\samepage\setseps\small
\begin{verbatim}
   NULL |- NULL[] /\ (!h t. ~NULL(CONS h t))

   HD   |- !(h:*) t. HD(CONS h t) = h

   TL   |- !(h:*) t. TL(CONS h t) = t
\end{verbatim}
}
\SEEALSO
new_definition, new_infix_definition, new_infix_list_rec_definition,
new_infix_prim_rec_definition, new_prim_rec_definition,
new_recursive_definition, new_type_definition, new_specification, list_Axiom.

\ENDDOC
\DOC{new\_open\_axiom}

\TYPE {\small\verb%new_open_axiom : ((string # term) -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{new\_parent}

\TYPE {\small\verb%new_parent : (string -> void)%}\egroup

\SYNOPSIS
Extends the current theory with a new parent theory.

\DESCRIBE
Executing {\small\verb%new_parent `thy`%} extends the current theory by making the existing
theory named {\small\verb%thy%} a parent of the current theory segment. The extended theory
contains the theory segments of both constituent theories. The theory {\small\verb%thy%} is
loaded into the system. The message `{\small\verb%Theory thy loaded%}' is printed.  The
effect of the call may not be written to the theory file of the segment until
{\small\verb%close_theory%} is invoked.  If HOL is quitted before this, the effect may not
persist to future HOL sessions.

\FAILURE
Executing {\small\verb%new_parent `thy`%} will fail if the system is not in draft mode. It
will fail if {\small\verb%thy%} is not a theory on the current search path. It will fail if
there is a type in theory {\small\verb%thy%} with the same name as a type in the current
theory. It will fail if there is a constant in theory {\small\verb%thy%} with the same name
as a constant in the current theory. It will fail if an ancestor of theory
{\small\verb%thy%} has been extended with either new types or constants which clash with
names in theory {\small\verb%thy%}. It will also fail if any of the theory files of theory
{\small\verb%thy%} have been damaged. On failure, the system recovers cleanly, unloading any
theory segments it had loaded before the failure was detected.

\SEEALSO
close_theory, extend_theory, new_theory, print_theory, search_path.

\ENDDOC
\DOC{new\_predicate}

\TYPE {\small\verb%new_predicate : ((string # type) -> void)%}\egroup

\SYNOPSIS
Creates a new predicate constant.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   new_predicate(`P`,":ty")
\end{verbatim}
}
\noindent will declare a new predicate called {\small\verb%P%} on type {\small\verb%ty%}, that is, a
constant {\small\verb%P%} of type {\small\verb%ty->bool%}.

\FAILURE
Fails if HOL is not in draft mode, or if there is already a constant of the
corresponding name in the current theory segment.

\SEEALSO
mk_const, mk_pred.

\ENDDOC
\DOC{new\_prim\_rec\_definition}

\TYPE {\small\verb%new_prim_rec_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
Define a primitive recursive function over the type {\small\verb%:num%}.

\DESCRIBE
The function {\small\verb%new_prim_rec_definition%} provides the facility for defining
primitive recursive functions on the type {\small\verb%num%}. It takes a pair argument,
consisting of the name under which the resulting definition will be saved in
the current theory segment, and a term giving the desired definition.  The
value returned by {\small\verb%new_prim_rec_definition%} is a theorem which states the
definition requested by the user.  This theorem is derived by formal proof from
an instance of the theorem {\small\verb%num_Axiom%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !e f. ?! fn. (fn 0 = e) /\ (!n. fn(SUC n) = f(fn n)n)
\end{verbatim}
}
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   new_prim_rec_definition
    (`fun_DEF`,
     "(fun x_1 ... 0 ... x_i = f_1[x_1, ..., x_i]) /\
      (fun x_1 ... (SUC n) ... x_i =
               f_2[fun t_1 ... n ... t_i, x_1, ..., n, ..., x_i])");;
\end{verbatim}
}
\noindent where all the free variables in the terms {\small\verb%t_1%}, ..., {\small\verb%t_i%} are
contained in {\small\verb%{n, x_1, ..., x_i}%}, automatically proves the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |-  ?fun. !x_1 ... x_i. fun x_1 ... 0 ... x_i = f_1[x_1, ..., x_i] /\
             !x_1 ... x_i. fun (SUC n) x_1 ... x_i =
                               f_2[fun t_1 ... n ... t_i, x_1, ..., n, ...,x_i]
\end{verbatim}
}
\noindent and then declares a new constant {\small\verb%fun%} with this property as its
specification. This constant specification is returned as a theorem by
{\small\verb%new_prim_rec_definition%} and is saved with name {\small\verb%fun_DEF%} in the
current theory segment.

The ML function {\small\verb%new_prim_rec_definition%} also allows the user to
partially specify the value of a function defined (possibly recursively) on the
natural numbers by giving its value for only one of {\small\verb%0%} or {\small\verb%SUC n%}.  See the
example below.

\FAILURE
Failure occurs if HOL cannot prove there is a function satisfying the
specification (ie. if the term supplied to {\small\verb%new_prim_rec_definition%}
is not a well-formed primitive recursive definition), or if
any other condition for making a constant specification is violated
(see the failure conditions for {\small\verb%new_specification%}).

\EXAMPLE
A curried addition function {\small\verb%plus:num->num->num%} can be defined by primitive
recursion on its first argument:
{\par\samepage\setseps\small
\begin{verbatim}
   #let PLUS = new_prim_rec_definition
   #           (`PLUS`,
   #            "(plus 0 n = n) /\
   #             (plus (SUC m) n = SUC(plus m n))");;
   PLUS = |- (!n. plus 0 n = n) /\ (!m n. plus(SUC m)n = SUC(plus m n))
\end{verbatim}
}
\noindent or by primitive recursion on its second argument:
{\par\samepage\setseps\small
\begin{verbatim}
   #let PLUS = new_prim_rec_definition
   #            (`PLUS`,
   #             "(plus m 0 = m) /\
   #              (plus m (SUC n) = SUC(plus m n))");;
   PLUS = |- (!m. plus m 0 = m) /\ (!m n. plus m(SUC n) = SUC(plus m n))
\end{verbatim}
}
\noindent A decrement function {\small\verb%DEC%}, whose value is specified for only
positive natural numbers, can be defined using {\small\verb%new_prim_rec_definition%}
as follows
{\par\samepage\setseps\small
\begin{verbatim}
   #let DEC = new_prim_rec_definition
   #            (`DEC`, "DEC (SUC n) = n");;
   DEC = |- !n. DEC(SUC n) = n
\end{verbatim}
}
\noindent This definition specifies the value of the function {\small\verb%DEC%} only for
positive natural numbers. In particular, the value of {\small\verb%DEC 0%} is left
unspecified, and the only non-trivial property that can be proved to hold of
the constant {\small\verb%DEC%} is the property stated by the theorem returned by the
call to {\small\verb%new_prim_rec_definition%} shown in the session above.

\SEEALSO
new_definition, new_infix_definition, new_infix_list_rec_definition,
new_infix_prim_rec_definition, new_list_rec_definition,
new_recursive_definition, new_type_definition, new_specification, num_Axiom.

\ENDDOC
\DOC{new\_recursive\_definition}

\TYPE {\small\verb%new_recursive_definition : (bool -> thm -> string -> conv)%}\egroup

\SYNOPSIS
Defines a primitive recursive function over a concrete recursive type.

\DESCRIBE
{\small\verb%new_recursive_definition%} provides the facility for defining primitive
recursive functions on arbitrary concrete recursive types.  It takes four
arguments.  The first is a boolean flag which indicates if the recursive
function to be defined will be an infix or not.  The second is the primitive
recursion theorem for the concrete type in question; this must be a theorem
obtained from {\small\verb%define_type%}. The third argument is a name under which the
resulting definition will be saved in the current theory segment. And the
fourth argument is a term giving the desired primitive recursive function
definition.  The value returned by {\small\verb%new_recursive_definition%} is a theorem
which states the primitive recursive definition requested by the user.  This
theorem is derived by formal proof from an instance of the general primitive
recursion theorem given as the second argument.

A theorem {\small\verb%th%} of the form returned by {\small\verb%define_type%} is a primitive recursion
theorem for an automatically-defined concrete type {\small\verb%ty%}.  Let {\small\verb%C1%}, ..., {\small\verb%Cn%}
be the constructors of this type, and let `{\small\verb%(Ci vs)%}' represent a (curried)
application of the {\small\verb%i%}th constructor to a sequence of variables.  Then a
curried primitive recursive function {\small\verb%fn%} over {\small\verb%ty%} can be specified by a
conjunction of (optionally universally-quantified) clauses of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   fn v1 ... (C1 vs1) ... vm  =  body1   /\
   fn v1 ... (C2 vs2) ... vm  =  body2   /\
                             .
                             .
   fn v1 ... (Cn vsn) ... vm  =  bodyn
\end{verbatim}
}
\noindent where the variables {\small\verb%v1%}, ..., {\small\verb%vm%}, {\small\verb%vs%} are distinct in each
clause, and where in the {\small\verb%i%}th clause {\small\verb%fn%} appears (free) in {\small\verb%bodyi%} only
as part of an application of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   "fn t1 ... v ... tm"
\end{verbatim}
}
\noindent in which the variable {\small\verb%v%} of type {\small\verb%ty%} also occurs among the
variables {\small\verb%vsi%}.

If {\small\verb%<definition>%} is a conjunction of clauses, as described above, then
evaluating:
{\par\samepage\setseps\small
\begin{verbatim}
   new_recursive_definition flag th `name` tm "<definition>";;
\end{verbatim}
}
\noindent automatically proves the existence of a function {\small\verb%fn%} that satisfies
the defining equations supplied as the fourth argument, and then declares a new
constant in the current theory with this definition as its specification. This
constant specification is returned as a theorem and is saved in the current
theory segment under the name {\small\verb%name%}. If {\small\verb%flag%} is {\small\verb%true%}, the constant is
given infix status.

{\small\verb%new_recursive_definition%} also allows the supplied definition to omit clauses
for any number of constructors.  If a defining equation for the {\small\verb%i%}th
constructor is omitted, then the value of {\small\verb%fn%} at that constructor:
{\par\samepage\setseps\small
\begin{verbatim}
   fn v1 ... (Ci vsi) ... vn
\end{verbatim}
}
\noindent is left unspecified ({\small\verb%fn%}, however, is still a total function).

\FAILURE
A call to {\small\verb%new_recursive_definition%} fails if the supplied theorem is not a
primitive recursion theorem of the form returned by {\small\verb%define_type%}; if the term
argument supplied is not a well-formed primitive recursive definition; or if
any other condition for making a constant specification is violated (see the
failure conditions for {\small\verb%new_specification%}).

\EXAMPLE
Given the following primitive recursion theorem for labelled binary trees:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !f0 f1.
        ?! fn.
        (!x. fn(LEAF x) = f0 x) /\
        (!b1 b2. fn(NODE b1 b2) = f1(fn b1)(fn b2)b1 b2)
\end{verbatim}
}
\noindent {\small\verb%new_recursive_definition%} can be used to define primitive recursive
functions over binary trees.  Suppose the value of {\small\verb%th%} is this theorem.  Then
a recursive function {\small\verb%Leaves%}, which computes the number of leaves in a
binary tree, can be defined recursively as shown below:
{\par\samepage\setseps\small
\begin{verbatim}
   #let Leaves =
   #    new_recursive_definition false th `Leaves`
   #      "(Leaves (LEAF (x:*)) = 1) /\
   #       (Leaves (NODE t1 t2) = (Leaves t1) + (Leaves t2))";;
   Leaves =
   |- (!x. Leaves(LEAF x) = 1) /\
      (!t1 t2. Leaves(NODE t1 t2) = (Leaves t1) + (Leaves t2))
\end{verbatim}
}
\noindent The result is a theorem which states that the constant {\small\verb%Leaves%}
satisfies the primitive-recursive defining equations supplied by the user.

The function defined using {\small\verb%new_recursive_definition%} need not, in fact, be
recursive.  Here is the definition of a predicate {\small\verb%IsLeaf%}, which is true of
binary trees which are leaves, but is false of the internal nodes in a binary
tree:
{\par\samepage\setseps\small
\begin{verbatim}
   #let IsLeaf =
   #    new_recursive_definition false th `IsLeaf`
   #      "(IsLeaf (NODE t1 t2) = F) /\ (IsLeaf (LEAF (x:*)) = T)";;
   IsLeaf = |- (!t1 t2. IsLeaf(NODE t1 t2) = F) /\ (!x. IsLeaf(LEAF x) = T)
\end{verbatim}
}
\noindent Note that the equations defining a (recursive or non-recursive)
function on binary trees by cases can be given in either order.  Here, the
{\small\verb%NODE%} case is given first, and the {\small\verb%LEAF%} case second.  The reverse order was
used in the above definition of {\small\verb%Leaves%}.

{\small\verb%new_recursive_definition%} also allows the user to partially specify the value
of a function defined on a concrete type, by allowing defining equations for
some of the constructors to be omitted.  Here, for example, is the definition
of a function {\small\verb%Label%} which extracts the label from a leaf node.  The value of
{\small\verb%Label%} applied to an internal node is left unspecified:
{\par\samepage\setseps\small
\begin{verbatim}
   #let Label =
   #    new_recursive_definition false th `Label`
   #      "Label (LEAF (x:*)) = x";;
   Label = |- !x. Label(LEAF x) = x
\end{verbatim}
}
\noindent Curried functions can also be defined, and the recursion can be on
any argument.  The next definition defines an infix (curried) function {\small\verb%<<%}
which expresses the idea that one tree is a proper subtree of another.
{\par\samepage\setseps\small
\begin{verbatim}
   #let Subtree =
   #    new_recursive_definition true th `Subtree`
   #      "(<< (t:(*)btree) (LEAF (x:*)) = F) /\
   #       (<< t (NODE t1 t2) = ((t=t1)\/(t=t2)\/(<< t t1)\/(<< t t2)))";;
   Subtree =
   |- (!t x. t << (LEAF x) = F) /\
      (!t t1 t2.
        t << (NODE t1 t2) = (t = t1) \/ (t = t2) \/ t << t1 \/ t << t2)
\end{verbatim}
}
\noindent Note that the first argument is {\small\verb%true%}, to indicate that the function
being defined is to have infix status, and that the constant {\small\verb%<<%} is an infix
after the definition has been made.  Furthermore, the function {\small\verb%<<%} is
recursive on its second argument.

\SEEALSO
define_type, prove_rec_fn_exists.

\ENDDOC
\DOC{new\_special\_symbol}

\TYPE {\small\verb%new_special_symbol : (string -> void)%}\egroup

\SYNOPSIS
Adds new string to the list of special symbols.

\DESCRIBE
An identifier, at the ML or object level, is either alphanumeric, e.g. {\small\verb%true%}
or {\small\verb%T%}, or consists of a special symbol which starts with a non-alphanumeric
character, e.g. {\small\verb%==>%} or {\small\verb%+%}. It is a consequence of the non-backtracking
implementation of lexical analysis that any (non-null) initial segment of a
special symbol is also a special symbol, so from the above we know that {\small\verb%==%}
and {\small\verb%=%} are. The function {\small\verb%new_special_symbol%} makes the given string and its
non-null initial segments into special symbols, provided the string does not
start with an alphanumeric character (according to {\small\verb%is_alphanum%}).

\FAILURE
Fails if the string provided starts with an alphanumeric character. The test is
performed using the function {\small\verb%is_alphanum%}, so this may include some unexpected
characters if {\small\verb%new_alphanum%} has been used.

\EXAMPLE
The call:
{\par\samepage\setseps\small
\begin{verbatim}
   new_special_symbol `.EQ.`;;
\end{verbatim}
}
\noindent makes the following three strings special symbols:
{\par\samepage\setseps\small
\begin{verbatim}
   .E  .EQ  .EQ.
\end{verbatim}
}
\SEEALSO
is_alphanum, new_alphanum, special_symbols.

\ENDDOC
\DOC{new\_specification}

\TYPE {\small\verb%new_specification : (string -> (string # string) list -> thm -> thm)%}\egroup

\SYNOPSIS
Introduces a constant or constants satisfying a given property.

\DESCRIBE
The ML function {\small\verb%new_specification%} implements the primitive rule of
constant specification for the HOL logic.
Evaluating:
{\par\samepage\setseps\small
\begin{verbatim}
   new_specification `name` [f1,`c1`;...;fn,`cn`] |- ?x1...xn. t
\end{verbatim}
}
\noindent simultaneously introduces new constants named {\small\verb%c1%}, ..., {\small\verb%cn%}
satisfying the property:
{\par\samepage\setseps\small
\begin{verbatim}
   |- t[c1,...,cn/x1,...,xn]
\end{verbatim}
}
\noindent This theorem is stored, with name {\small\verb%name%}, as a definition in the
current theory segment. It is also returned by the call to {\small\verb%new_specification%}
The strings {\small\verb%f1%}, ..., {\small\verb%fn%} are flags which determine whether the new constants
are infixes or binders or neither.  If {\small\verb%fi%} is {\small\verb%`constant`%} then {\small\verb%ci%} is
declared an ordinary constant, if it is {\small\verb%`infix`%} then {\small\verb%ci%} is declared an
infix, and if it is {\small\verb%`binder`%} then {\small\verb%ci%} is declared a binder.  A flag of any
other value causes failure.

\FAILURE
{\small\verb%new_specification%} fails if called when HOL is not in draft mode. It also
fails if there is already an axiom, definition or specification of the given
name in the current theory segment; if the theorem argument has assumptions or
free variables; if the supplied constant names {\small\verb%`c1`%}, ..., {\small\verb%`cn`%} are not
distinct; if any one of {\small\verb%`c1`%}, ..., {\small\verb%`cn`%} is already a constant in the
current theory or is not an allowed name for a constant.  Failure also occurs
if any of {\small\verb%f1%}, ..., {\small\verb%fn%} is not either {\small\verb%`constant`%}, {\small\verb%`infix`%} or {\small\verb%`binder`%}
or if the type of {\small\verb%ci%} is not suitable for a constant with the syntactic status
specified by the flag {\small\verb%fi%}.  Finally, failure occurs if some {\small\verb%ci%} does not
contain all the type variables that occur in the term {\small\verb%?x1...xn. t%}.

\USES
{\small\verb%new_specification%} can be used to introduce constants that satisfy a given
property without having to make explicit equational constant definitions for
them.  For example, the built-in constants {\small\verb%MOD%} and {\small\verb%DIV%} are defined in the
system by first proving the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   th |- ?MOD DIV.
         !n. (0 < n) ==>
             !k. ((k = (((DIV k n) * n) + (MOD k n))) /\ ((MOD k n) < n))
\end{verbatim}
}
\noindent and then making the constant specification:
{\par\samepage\setseps\small
\begin{verbatim}
   #new_specification `DIVISION` [`infix`,`MOD`;`infix`,`DIV`] th;;
   |- !n. (0 < n) ==>
          !k. ((k = (((DIV k n) * n) + (MOD k n))) /\ ((MOD k n) < n))
\end{verbatim}
}
\noindent This introduces the constants {\small\verb%MOD%} and {\small\verb%DIV%} with the defining
property shown above.

\SEEALSO
new_definition, new_binder_definition, new_gen_definition,
new_infix_definition.

\ENDDOC
\DOC{new\_stack}

\TYPE {\small\verb%new_stack : (goal -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{new\_syntax\_block}

\TYPE {\small\verb%new_syntax_block : ((string # string # string) -> void)%}\egroup

\SYNOPSIS
Declares a new syntax block.

\DESCRIBE
A syntax block starts with keyword and ends with a terminator and is
associated with a function of strings. When such a block is
encountered in the input stream, all the characters between the start
keyword and the terminator are made into a string to which the
associated function is applied.

The ML function {\small\verb%new_syntax_block%} declares a new syntax block. The
first argument is the start keyword of the block, the second argument
is the terminator and the third argument is the name of a function
having a type which is an instance of {\small\verb%string->*%}. The effect of
{\par\samepage\setseps\small
\begin{verbatim}
   new_syntax_block(`XXX`, `YYY`, `Fun`);;
\end{verbatim}
}
\noindent is that if
{\par\samepage\setseps\small
\begin{verbatim}
   XXX

      ...

   YYY
\end{verbatim}
}
\noindent occurs in the input, then it is as though
{\par\samepage\setseps\small
\begin{verbatim}
   Fun `

      ...

   `
\end{verbatim}
}
\noindent were input.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let foo s = print_string `Hello: `; print_string s; print_newline();;
foo = - : (string -> void)

#new_syntax_block(`FOO`,`OOF`, `foo`);;
() : void

#FOO 123OO44OOF;;
Hello: 123OO44
() : void

#FOO
#splat
#OOF;;
Hello: splat

() : void
\end{verbatim}
}
\USES
Interfacing parsers to HOL.

\ENDDOC
\DOC{new\_theory}

\TYPE {\small\verb%new_theory : (string -> void)%}\egroup

\SYNOPSIS
Creates a new theory by extending the current theory with a new theory segment.

\DESCRIBE
A theory consists of a hierarchy of named parts called theory segments. The
theory segment at the top of the hierarchy tree in each theory is said to be
current. All theory segments have a theory of the same name  associated with
them consisting of the theory segment itself and all its ancestors.
Each axiom,
definition, specification and theorem belongs to a particular theory segment.

Calling {\small\verb%new_theory `thy`%} creates a new theory segment and associated theory
having name {\small\verb%thy%}. The theory segment which was current before the call becomes
a parent of the new theory segment. The new theory therefore consists of the
current theory extended with the new theory segment. The new theory segment
replaces its parent as the current theory segment. The call switches the system
into draft mode. This allows new axioms, constants, types, constant
specifications, infix constants, binders and parents to be added to the theory
segment. Inconsistencies will be introduced into the theory if inconsistent
axioms are asserted.  New theorems can also be added as when in proof mode. The
theory file in which the data of the new theory segment is ultimately stored
will have name {\small\verb%thy.th%} in the directory from which HOL was called. The theory
segment might not be written to this file until the session is finished with a
call to {\small\verb%close_theory%}. If HOL is quitted without closing the session with
{\small\verb%close_theory%}, parts of the theory segment created during the session may be
lost. If the system is in draft mode when a call to {\small\verb%new_theory%} is made, the
previous session is closed; all changes made in it will be written to the
associated theory file.

\FAILURE
The call {\small\verb%new_theory `thy`%} will fail if there already exists a file {\small\verb%thy.th%}
in the current search path. It will also fail if the name {\small\verb%thy.th%} is
unsuitable for a filename. Since it could involve writing to the file system,
if a write fails for any reason {\small\verb%new_theory%} will fail.

\USES
Hierarchically extending the current theory.
By splitting a theory into theory segments using {\small\verb%new_theory%}, the work
required if definitions, etc., need to be changed is minimized. Only the
associated segment and its descendants need be redefined.

\SEEALSO
close_theory, current_theory, extend_theory, load_theory, new_axiom,
new_binder, new_constant, new_definition, new_infix, new_parent,
new_specification, new_type, print_theory, save_thm, search_path.

\ENDDOC
\DOC{new\_type\_abbrev}

\TYPE {\small\verb%new_type_abbrev : ((string # type) -> void)%}\egroup

\SYNOPSIS
Sets up a new type abbreviation.

\DESCRIBE
A call {\small\verb%new_type_abbrev(`ab`,":ty")%} creates and stores in the current theory
segment a new type abbreviation {\small\verb%ab%} for the type {\small\verb%ty%}. In future, {\small\verb%":ab"%} may
be used rather than the perhaps complicated expresion {\small\verb%":ty"%}.

\FAILURE
Fails if HOL is not in draft mode.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_theory `gonk`;;
() : void

#new_type_abbrev(`bt`,":bool#bool#bool");;
() : void

#let tm = "x:bt" and ty = ":bt";;
tm = "x" : term
ty = ":bool # (bool # bool)" : type

#type_of tm = ty;;
true : bool
\end{verbatim}
}
\COMMENTS
A similar mechanism can be implemented using antiquotation, for example:
{\par\samepage\setseps\small
\begin{verbatim}
   #let bt = ":bool#bool#bool";;
   bt = ":bool # (bool # bool)" : type

   #let tm = "x:^bt" and ty = ":^bt";;
   tm = "x" : term
   ty = ":bool # (bool # bool)" : type

   #type_of tm = ty;;
   true : bool
\end{verbatim}
}
\noindent although this does have the disadvantage of not being stored in the
theory file.

\SEEALSO
types, type_abbrevs, new_type.

\ENDDOC
\DOC{new\_type\_definition}

\TYPE {\small\verb%new_type_definition : ((string # term # thm) -> thm)%}\egroup

\SYNOPSIS
Defines a new type constant or type operator.

\DESCRIBE
The ML function {\small\verb%new_type_definition%} implements the primitive HOL rule of
definition for introducing new type constants or type operators into the logic.
If {\small\verb%"t"%} is a closed term of type {\small\verb%ty->bool%} containing {\small\verb%n%} distinct type
variables, then evaluating:
{\par\samepage\setseps\small
\begin{verbatim}
   new_type_definition(`op`, "t", |- ?x. t x)
\end{verbatim}
}
\noindent results in {\small\verb%op%} being declared as a new {\small\verb%n%}-ary type operator in the
current theory and returns a definitional axiom of the following form
characterizing that new type operator:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ?rep:(*1,...,*n)op->ty. TYPE_DEFINITION t rep
\end{verbatim}
}
\noindent which is stored as a definition in the current theory segment
under the automatically-generated name {\small\verb%`op_TY_DEF`%}. The constant
{\small\verb%TYPE_DEFINITION%} in this axiomatic characterization of {\small\verb%op%} is defined by:
{\par\samepage\setseps\small
\begin{verbatim}
   |- TYPE_DEFINITION (P:*->bool) (rep:**->*) =
         (!x' x''. (rep x' = rep x'') ==> (x' = x'')) /\
         (!x. P x = (?x'. x = rep x'))
\end{verbatim}
}
\noindent Thus {\small\verb%|- ?rep. TYPE_DEFINITION P rep%} asserts that there is a
bijection between the newly defined type {\small\verb%(*1,...,*n)op%} and the set of values
of type {\small\verb%ty%} that satisfy {\small\verb%P%}.

\FAILURE
Executing {\small\verb%new_type_definition(`op`,"t",th)%} fails if {\small\verb%"t"%} contains free
(term) variables, if {\small\verb%op%} is already the name of a type or type operator in the
current theory, if {\small\verb%"t"%} does not have a type of the form {\small\verb%ty->bool%} or {\small\verb%th%} is
not a theorem without assumptions of the form {\small\verb%|- ?x. t x%}, if there already
exists a constant definition, constant specification, type definition or axiom
named {\small\verb%op_TY_DEF%} in the current theory segment, or if HOL is not in draft
mode.

\SEEALSO
define_new_type_bijections, prove_abs_fn_one_one, prove_abs_fn_onto,
prove_rep_fn_one_one, prove_rep_fn_onto.

\ENDDOC
\DOC{new\_type}

\TYPE {\small\verb%new_type : (int -> string -> void)%}\egroup

\SYNOPSIS
Declares a new type or type constructor.

\DESCRIBE
A call {\small\verb%new_type n `t`%} declares a new {\small\verb%n%}-ary type constructor called {\small\verb%t%} in
the current theory segment. If {\small\verb%n%} is zero, this is just a new base type.

\FAILURE
Fails if HOL is not in draft mode, or if the name is not a valid type
name, or there is already a type operator of that name in the current theory.

\EXAMPLE
A version of ZF set theory might declare a new type {\small\verb%set%} and start using it as
follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #new_theory `ZF`;;
   () : void

   #new_type 0 `set`;;
   () : void

   #new_infix(`mem`,":set->set->bool");;
   () : void

   #new_axiom(`ext`,"(!z. z mem x = z mem y) ==> (x = y)");;
   |- !x y. (!z. z mem x = z mem y) ==> (x = y)
\end{verbatim}
}
\SEEALSO
types, type_abbrevs, new_type_abbrev.

\ENDDOC
\DOC{nil\_term\_net}

\TYPE {\small\verb%nil_term_net : * term_net%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{NO\_CONV}

\TYPE {\small\verb%NO_CONV : conv%}\egroup

\SYNOPSIS
Conversion that always fails.

\FAILURE
{\small\verb%NO_CONV%} always fails.

\SEEALSO
ALL_CONV.

\ENDDOC
\DOC{NO\_TAC}

\TYPE {\small\verb%NO_TAC : tactic%}\egroup

\SYNOPSIS
Tactic which always fails.

\DESCRIBE
Whatever goal it is applied to, {\small\verb%NO_TAC%} always fails
with string {\small\verb%`NO_TAC`%}.

\FAILURE
Always fails.

\SEEALSO
ALL_TAC, ALL_THEN, FAIL_TAC, NO_THEN.

\ENDDOC
\DOC{not}

\TYPE {\small\verb%$not : (bool -> bool)%}\egroup

\SYNOPSIS
Built-in ML logical negation.

\DESCRIBE
When given a boolean value, {\small\verb%not%} returns its negation. Although it is a prefix
function, it needs to be preceded by {\small\verb%$%} to suppress its special parse status.

\FAILURE
Never fails.

\ENDDOC
\DOC{NOT\_ELIM}

\TYPE {\small\verb%NOT_ELIM : (thm -> thm)%}\egroup

\SYNOPSIS
Transforms {\small\verb%|- ~t%} into {\small\verb%|- t ==> F%}.

\DESCRIBE
When applied to a theorem {\small\verb%A |- ~t%}, the inference rule {\small\verb%NOT_ELIM%} returns the
theorem {\small\verb%A |- t ==> F%}.
{\par\samepage\setseps\small
\begin{verbatim}
      A |- ~t
   --------------  NOT_ELIM
    A |- t ==> F
\end{verbatim}
}
\FAILURE
Fails unless the theorem has a negated conclusion.

\SEEALSO
IMP_ELIM, NOT_INTRO.

\ENDDOC
\DOC{NOT\_EQ\_SYM}

\TYPE {\small\verb%NOT_EQ_SYM : (thm -> thm)%}\egroup

\SYNOPSIS
Swaps left-hand and right-hand sides of a negated equation.

\DESCRIBE
When applied to a theorem {\small\verb%A |- ~(t1 = t2)%}, the inference rule {\small\verb%NOT_EQ_SYM%}
returns the theorem {\small\verb%A |- ~(t2 = t1)%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- ~(t1 = t2)
   -----------------  NOT_EQ_SYM
    A |- ~(t2 = t1)
\end{verbatim}
}
\FAILURE
Fails unless the theorem's conclusion is a negated equation.

\SEEALSO
DEPTH_CONV, REFL, SYM.

\ENDDOC
\DOC{NOT\_EXISTS\_CONV}

\TYPE {\small\verb%NOT_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves negation inwards through an existential quantification.

\DESCRIBE
When applied to a term of the form {\small\verb%~(?x.P)%}, the conversion
{\small\verb%NOT_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ~(?x.P) = !x.~P
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%~(?x.P)%}.

\SEEALSO
EXISTS_NOT_CONV, FORALL_NOT_CONV, NOT_FORALL_CONV.

\ENDDOC
\DOC{NOT\_FORALL\_CONV}

\TYPE {\small\verb%NOT_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves negation inwards through a universal quantification.

\DESCRIBE
When applied to a term of the form {\small\verb%~(!x.P)%}, the conversion
{\small\verb%NOT_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ~(!x.P) = ?x.~P
\end{verbatim}
}
\noindent It is irrelevant whether {\small\verb%x%} occurs free in {\small\verb%P%}.

\FAILURE
Fails if applied to a term not of the form {\small\verb%~(!x.P)%}.

\SEEALSO
EXISTS_NOT_CONV, FORALL_NOT_CONV, NOT_EXISTS_CONV.

\ENDDOC
\DOC{NO\_THEN}

\TYPE {\small\verb%NO_THEN : thm_tactical%}\egroup

\SYNOPSIS
Theorem-tactical which always fails.

\DESCRIBE
When applied to a theorem-tactic and a theorem, the theorem-tactical
{\small\verb%NO_THEN%} always fails with string {\small\verb%`NO_THEN`%}.

\FAILURE
Always fails when applied to a theorem-tactic and a theorem (note that it
never gets as far as being applied to a goal!)

\USES
Writing compound tactics or tacticals.

\SEEALSO
ALL_TAC, ALL_THEN, FAIL_TAC, NO_TAC.

\ENDDOC
\DOC{NOT\_INTRO}

\TYPE {\small\verb%NOT_INTRO : (thm -> thm)%}\egroup

\SYNOPSIS
Transforms {\small\verb%|- t ==> F%} into {\small\verb%|- ~t%}.

\DESCRIBE
When applied to a theorem {\small\verb%A |- t ==> F%}, the inference rule {\small\verb%NOT_INTRO%}
returns the theorem {\small\verb%A |- ~t%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t ==> F
   --------------  NOT_INTRO
      A |- ~t
\end{verbatim}
}
\FAILURE
Fails unless the theorem has an implicative conclusion with {\small\verb%F%}
as the consequent.

\SEEALSO
IMP_ELIM, NOT_ELIM.

\ENDDOC
\DOC{NOT\_MP}

\TYPE {\small\verb%NOT_MP : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Implements the Modus Ponens inference rule and 
takes negation as an implication.

\DESCRIBE
When applied to theorems {\small\verb%A1 |- t1 ==> t2%} and {\small\verb%A2 |- t1%},
the inference rule {\small\verb%NOT_MP%} returns the theorem {\small\verb%A1 u A2 |- t2%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1 ==> t2   A2 |- t1
   ----------------------------  NOT_MP
          A1 u A2 |- t2
\end{verbatim}
}
\noindent This is the same as the primitive inference rule {\small\verb%MP%}.
However, the first theorem can also be a negation. In such case,
{\small\verb%NOT_MP%} automatically transforms it to an implication with {\small\verb%F%} as
conclusion. 
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- ~ t     A2 |- t
   ----------------------- NOT_MP
       A1 u A2 |- F
\end{verbatim}
}
\FAILURE
Fails unless the first theorem is an implication whose antecedent is the
same as the conclusion of the second theorem (up to alpha-conversion),
or it is a negation.

\COMMENTS
The rule {\small\verb%MP%} used to behave as what is described in this page due to
some historical reasons. Now, {\small\verb%MP%} is the true primitive rule
implementing Modus Ponens. {\small\verb%NOT_MP%} is introduced to implement the old
{\small\verb%MP%}. The use of {\small\verb%NOT_MP%} is discouraged. If the input theorem is
expected to be a negation, use {\small\verb%(MP o NOT_ELIM)%}.

\SEEALSO
MP, EQ_MP, LIST_MP, MATCH_MP, MATCH_MP_TAC, MP_TAC.

\ENDDOC
\DOC{n\_strip\_quant}

\TYPE {\small\verb%n_strip_quant : ((* -> (** # *)) -> int -> * -> (** list # *))%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{null}

\TYPE {\small\verb%null : (* list -> bool)%}\egroup

\SYNOPSIS
Tests for empty list.

\DESCRIBE
Returns {\small\verb%true%} for an empty list. Otherwise it returns {\small\verb%false%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#null [];;
true : bool

#null [1;2;3];;
false : bool
\end{verbatim}
}
\ENDDOC
\DOC{num\_CONV}

\TYPE {\small\verb%num_CONV : conv%}\egroup

\SYNOPSIS
Provides definitional axiom for a nonzero numeral.

\DESCRIBE
{\small\verb%num_CONV%} is an axiom-scheme from which one may obtain a defining equation for
any natural number constant not equal to {\small\verb%0%} (i.e. {\small\verb%1%}, {\small\verb%2%}, {\small\verb%3%},...).  If
{\small\verb%"n"%} is such a constant, then {\small\verb%num_CONV "n"%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- n = SUC m
\end{verbatim}
}
\noindent where {\small\verb%m%} is the numeral that denotes the predecessor of the
number denoted by {\small\verb%n%}.

\FAILURE
{\small\verb%num_CONV tm%} fails if {\small\verb%tm%} is {\small\verb%"0"%} or if not {\small\verb%tm%} is not a numeral constant.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#num_CONV "3";;
|- 3 = SUC 2
\end{verbatim}
}
\ENDDOC
\DOC{num\_EQ\_CONV}

\TYPE {\small\verb%num_EQ_CONV : conv%}\egroup

\SYNOPSIS
Proves equality or inequality of two natural number constants.

\DESCRIBE
If {\small\verb%n%} and {\small\verb%m%} are two distinct numeral constants (e.g. {\small\verb%0%}, {\small\verb%1%}, {\small\verb%2%},
{\small\verb%3%},...), then {\small\verb%num_EQ_CONV "n = m"%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (n = m) = F
\end{verbatim}
}
\noindent If {\small\verb%n%} and {\small\verb%m%} are successors of numeral constants (e.g. {\small\verb%SUC 0%},
{\small\verb%SUC 1%}, {\small\verb%SUC(SUC 1)%} etc.), then {\small\verb%num_EQ_CONV "n = m"%} returns one of:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (n = m) = T       or       |- (n = m) = F
\end{verbatim}
}
\noindent depending on whether the natural numbers represented by {\small\verb%n%} and {\small\verb%m%}
are equal or not equal, respectively. Finally, for any term {\small\verb%"n"%} of type
{\small\verb%num%}, evaluating {\small\verb%num_EQ_CONV "n = n"%} returns {\small\verb%|- (n = n) = T%}.

\FAILURE
{\small\verb%num_EQ_CONV tm%} fails if {\small\verb%tm%} is not of the form {\small\verb%"n = m"%}, where {\small\verb%n%} and {\small\verb%m%}
are either numerals or repeated applications of {\small\verb%SUC%} to numerals unless {\small\verb%n%}
and {\small\verb%m%} are syntactically identical terms of type {\small\verb%num%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#num_EQ_CONV "1 = SUC 2";;
|- (1 = SUC 2) = F

#num_EQ_CONV "SUC 1 = 2";;
|- (SUC 1 = 2) = T
\end{verbatim}
}
\ENDDOC
\DOC{o}

\TYPE {\small\verb%$o : (((* -> **) # (*** -> *)) -> *** -> **)%}\egroup

\SYNOPSIS
Composes two functions: {\small\verb%(f o g) x%} = {\small\verb%f (g x)%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, Co, I, K, KI, oo, S, W.

\ENDDOC
\DOC{ONCE\_ASM\_REWRITE\_RULE}

\TYPE {\small\verb%ONCE_ASM_REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem once including built-in rewrites and the theorem's
assumptions.

\DESCRIBE
{\small\verb%ONCE_ASM_REWRITE_RULE%} applies all possible rewrites in one step
over the subterms in the conclusion of the theorem, but stops after
rewriting at most once at each subterm. This strategy is specified as
for {\small\verb%ONCE_DEPTH_CONV%}. For more details see {\small\verb%ASM_REWRITE_RULE%}, which
does search recursively (to any depth) for matching subterms. The
general strategy for rewriting theorems is described under
{\small\verb%GEN_REWRITE_RULE%}.

\FAILURE
Never fails.

\USES
This tactic is used when rewriting with the hypotheses of a theorem
(as well as a given list of theorems and {\small\verb%basic_rewrites%}), when more
than one pass is not required or would result in divergence.

\SEEALSO
ASM_REWRITE_RULE, FILTER_ASM_REWRITE_RULE,
FILTER_ONCE_ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_DEPTH_CONV,
ONCE_REWRITE_RULE, PURE_ASM_REWRITE_RULE, PURE_ONCE_ASM_REWRITE_RULE,
PURE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{ONCE\_ASM\_REWRITE\_TAC}

\TYPE {\small\verb%ONCE_ASM_REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal once including built-in rewrites and the goal's assumptions.

\DESCRIBE
{\small\verb%ONCE_ASM_REWRITE_TAC%} behaves in the same way as {\small\verb%ASM_REWRITE_TAC%},
but makes one pass only through the term of the goal. The order in
which the given theorems are applied is an implementation matter and
the user should not depend on any ordering. See {\small\verb%GEN_REWRITE_TAC%} for
more information on rewriting a goal in HOL.

\FAILURE
{\small\verb%ONCE_ASM_REWRITE_TAC%} does not fail and, unlike {\small\verb%ASM_REWRITE_TAC%},
does not diverge. The resulting tactic may not be valid, if the
rewrites performed add new assumptions to the theorem eventually
proved.

\EXAMPLE
The use of {\small\verb%ONCE_ASM_REWRITE_TAC%} to control the amount of rewriting
performed is illustrated below:
{\par\samepage\setseps\small
\begin{verbatim}
   #ONCE_ASM_REWRITE_TAC []
   #             (["(a:*) = b"; "(b:*) = c"], "P (a:*): bool") ;;
   ([(["a = b"; "b = c"], "P b")], -) : subgoals
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
   #(ONCE_ASM_REWRITE_TAC [] THEN ONCE_ASM_REWRITE_TAC [])
   #             (["(a:*) = b"; "(b:*) = c"], "P (a:*): bool") ;;
   ([(["a = b"; "b = c"], "P c")], -) : subgoals
\end{verbatim}
}
\USES
{\small\verb%ONCE_ASM_REWRITE_TAC%} can be applied once or iterated as required to
give the effect of {\small\verb%ASM_REWRITE_TAC%}, either to avoid divergence or to
save inference steps.

\SEEALSO
basic_rewrites, ASM_REWRITE_TAC, FILTER_ASM_REWRITE_TAC,
FILTER_ONCE_ASM_REWRITE_TAC, GEN_REWRITE_TAC, ONCE_ASM_REWRITE_TAC,
ONCE_REWRITE_TAC, PURE_ASM_REWRITE_TAC, PURE_ONCE_ASM_REWRITE_TAC,
PURE_ONCE_REWRITE_TAC, PURE_REWRITE_TAC, REWRITE_TAC, SUBST_TAC.

\ENDDOC
\DOC{ONCE\_DEPTH\_CONV}

\TYPE {\small\verb%ONCE_DEPTH_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion once to the first suitable sub-term(s) encountered in
top-down order.

\DESCRIBE
{\small\verb%ONCE_DEPTH_CONV c tm%} applies the conversion {\small\verb%c%} once to the first subterm or
subterms encountered in a top-down `parallel' search of the term {\small\verb%tm%} for which
{\small\verb%c%} succeeds.  If the conversion {\small\verb%c%} fails on all subterms of {\small\verb%tm%}, the theorem
returned is {\small\verb%|- tm = tm%}.

\FAILURE
Never fails.

\EXAMPLE
The following example shows how {\small\verb%ONCE_DEPTH_CONV%} applies a conversion to only
the first suitable subterm(s) found in a top-down search:
{\par\samepage\setseps\small
\begin{verbatim}
   #ONCE_DEPTH_CONV BETA_CONV "(\x. (\y. y + x) 1) 2";;
   |- (\x. (\y. y + x)1)2 = (\y. y + 2)1
\end{verbatim}
}
\noindent Here, there are two beta-redexes in the input term. One of these
occurs within the other, so {\small\verb%BETA_CONV%} is applied only to the outermost one.

Note that the supplied conversion is applied by {\small\verb%ONCE_DEPTH_CONV%} to all
independent subterms at which it succeeds.  That is, the conversion is applied
to every suitable subterm not contained in some other subterm for which the
conversions also succeeds, as illustrated by the following example:
{\par\samepage\setseps\small
\begin{verbatim}
   #ONCE_DEPTH_CONV num_CONV "(\x. (\y. y + x) 1) 2";;
   |- (\x. (\y. y + x)1)2 = (\x. (\y. y + x)(SUC 0))(SUC 1)
\end{verbatim}
}
\noindent Here {\small\verb%num_CONV%} is applied to both {\small\verb%1%} and {\small\verb%2%}, since neither term
occurs within a larger subterm for which the conversion {\small\verb%num_CONV%} succeeds.

\USES
{\small\verb%ONCE_DEPTH_CONV%} is frequently used when there is only one subterm to which
the desired conversion applies. This can be much faster than using other
functions that attempt to apply a conversion to all subterms of a term (e.g.
{\small\verb%DEPTH_CONV%}).  If, for example, the current goal in a goal-directed proof
contains only one beta-redex, and one wishes to apply {\small\verb%BETA_CONV%} to it, then
the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   CONV_TAC (ONCE_DEPTH_CONV BETA_CONV)
\end{verbatim}
}
\noindent may, depending on where the beta-redex occurs, be much faster than
{\par\samepage\setseps\small
\begin{verbatim}
   CONV_TAC (TOP_DEPTH_CONV BETA_CONV)
\end{verbatim}
}
{\small\verb%ONCE_DEPTH_CONV c%} may also be used when the supplied conversion {\small\verb%c%} never
fails, in which case using a conversion such as {\small\verb%DEPTH_CONV c%}, which
applies {\small\verb%c%} repeatedly would never terminate.

\COMMENTS
The implementation of this function uses failure to avoid rebuilding
unchanged subterms. That is to say, during execution the failure string
{\small\verb%`QCONV`%} may be generated and later trapped. The behaviour of the function
is dependent on this use of failure. So, if the conversion given as argument
happens to generate a failure with string {\small\verb%`QCONV`%}, the operation of
{\small\verb%ONCE_DEPTH_CONV%} will be unpredictable.

\SEEALSO
DEPTH_CONV, REDEPTH_CONV, TOP_DEPTH_CONV, ONCE_REW_DEPTH_CONV.

\ENDDOC
\DOC{ONCE\_REW\_DEPTH\_CONV}

\TYPE {\small\verb%ONCE_REW_DEPTH_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion once to the first suitable sub-term(s) encountered in
top-down order. For use in rewriting.

\DESCRIBE
{\small\verb%ONCE_REW_DEPTH_CONV c tm%} applies the conversion {\small\verb%c%} once to the first
subterm or subterms encountered in a top-down `parallel' search of the term
{\small\verb%tm%} for which {\small\verb%c%} succeeds.  If the conversion {\small\verb%c%} fails on all subterms of
{\small\verb%tm%}, the theorem returned is {\small\verb%|- tm = tm%}.

{\small\verb%ONCE_REW_DEPTH_CONV%} is a special version of {\small\verb%ONCE_DEPTH_CONV%} for use by the
rewriting conversions, rules and tactics. It differs from {\small\verb%ONCE_DEPTH_CONV%} as
follows: If converting an abstraction fails due to the presence of the bound
variable in the hypotheses of the theorem generated by converting the body,
{\small\verb%ONCE_REW_DEPTH_CONV%} retries the conversion having renamed the bound variable
of the abstraction. If successful the renaming is reversed.

\FAILURE
Never fails.

\EXAMPLE
The following example illustrates the difference between the functions
{\small\verb%ONCE_REW_DEPTH_CONV%} and {\small\verb%ONCE_DEPTH_CONV%}. It is not intended to illustrate
the full range of behaviour of the former. Both {\small\verb%ONCE_REW_DEPTH_CONV%} and
{\small\verb%ONCE_DEPTH_CONV%} successfully apply the theorem {\small\verb%ADD_0%} inside an abstraction:
{\par\samepage\setseps\small
\begin{verbatim}
   #ONCE_REW_DEPTH_CONV (REWR_CONV ADD_0) "\n. n + 0";;
   |- (\n. n + 0) = (\n. n)

   #ONCE_DEPTH_CONV (REWR_CONV ADD_0) "\n. n + 0";;
   |- (\n. n + 0) = (\n. n)
\end{verbatim}
}
\noindent However, if a hypothesis containing a free occurrence of the bound
variable is added to the rewrite rule, it interferes with the operation of
{\small\verb%ONCE_DEPTH_CONV%} but not that of {\small\verb%ONCE_REW_DEPTH_CONV%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #let th = ADD_ASSUM "n = 0" ADD_0;;
   th = n = 0 |- !m. m + 0 = m

   #ONCE_REW_DEPTH_CONV (REWR_CONV th) "\n. n + 0";;
   n = 0 |- (\n. n + 0) = (\n. n)

   #ONCE_DEPTH_CONV (REWR_CONV th) "\n. n + 0";;
   |- (\n. n + 0) = (\n. n + 0)
\end{verbatim}
}
\COMMENTS
The implementation of this function uses failure to avoid rebuilding
unchanged subterms. That is to say, during execution the failure string
{\small\verb%`QCONV`%} may be generated and later trapped. The behaviour of the function
is dependent on this use of failure. So, if the conversion given as argument
happens to generate a failure with string {\small\verb%`QCONV`%}, the operation of
{\small\verb%ONCE_REW_DEPTH_CONV%} will be unpredictable.

\SEEALSO
REW_DEPTH_CONV, ONCE_DEPTH_CONV.

\ENDDOC
\DOC{ONCE\_REWRITE\_CONV}

\TYPE {\small\verb%ONCE_REWRITE_CONV : (thm list -> conv)%}\egroup

\SYNOPSIS
Rewrites a term, including built-in tautologies in the list of rewrites.

\DESCRIBE
{\small\verb%ONCE_REWRITE_CONV%} searches for matching subterms and applies
rewrites once at each subterm, in the manner specified for
{\small\verb%ONCE_DEPTH_CONV%}. The rewrites which are used are obtained from the
given list of theorems and the set of tautologies stored in
{\small\verb%basic_rewrites%}. See {\small\verb%GEN_REWRITE_CONV%} for the general method of
using theorems to rewrite a term.

\FAILURE
{\small\verb%ONCE_REWRITE_CONV%} does not fail; it does not diverge.

\USES
{\small\verb%ONCE_REWRITE_CONV%} can be used to rewrite a term when recursive
rewriting is not desired.

\SEEALSO
GEN_REWRITE_CONV, PURE_ONCE_REWRITE_CONV, PURE_REWRITE_CONV, REWRITE_CONV.

\ENDDOC
\DOC{ONCE\_REWRITE\_RULE}

\TYPE {\small\verb%ONCE_REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem, including built-in tautologies in the list of rewrites.

\DESCRIBE
{\small\verb%ONCE_REWRITE_RULE%} searches for matching subterms and applies
rewrites once at each subterm, in the manner specified for
{\small\verb%ONCE_DEPTH_CONV%}. The rewrites which are used are obtained from the
given list of theorems and the set of tautologies stored in
{\small\verb%basic_rewrites%}. See {\small\verb%GEN_REWRITE_RULE%} for the general method of
using theorems to rewrite an object theorem.

\FAILURE
{\small\verb%ONCE_REWRITE_RULE%} does not fail; it does not diverge.

\USES
{\small\verb%ONCE_REWRITE_RULE%} can be used to rewrite a theorem when recursive
rewriting is not desired.

\SEEALSO
ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_ASM_REWRITE_RULE,
PURE_ONCE_REWRITE_RULE, PURE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{ONCE\_REWRITE\_TAC}

\TYPE {\small\verb%ONCE_REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal only once with {\small\verb%basic_rewrites%} and the supplied list
of theorems.

\DESCRIBE
A set of equational rewrites is generated from the theorems supplied
by the user and the set of basic tautologies, and these are used to
rewrite the goal at all subterms at which a match is found in one pass
over the term part of the goal. The result is returned without
recursively applying the rewrite theorems to it. The order in which
the given theorems are applied is an implementation matter and the user
should not depend on any ordering. More details about rewriting can be
found under {\small\verb%GEN_REWRITE_TAC%}.

\FAILURE
{\small\verb%ONCE_REWRITE_TAC%} does not fail and does not diverge. It results in
an invalid tactic if any of the applied rewrites introduces new
assumptions to the theorem eventually proved.

\EXAMPLE
Given a theorem list:
{\par\samepage\setseps\small
\begin{verbatim}
  th1 = [ |- a = b; |- b = c; |- c = a]
\end{verbatim}
}
\noindent the tactic {\small\verb%ONCE_REWRITE_TAC thl%} can be iterated as
required without diverging:
{\par\samepage\setseps\small
\begin{verbatim}
   #ONCE_REWRITE_TAC thl ([], "P a");;
   ([([], "P b")], -) : subgoals
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
   #(ONCE_REWRITE_TAC thl THEN ONCE_REWRITE_TAC thl) ([], "P a");;
   ([([], "P c")], -) : subgoals
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
   #(ONCE_REWRITE_TAC thl THEN ONCE_REWRITE_TAC thl THEN ONCE_REWRITE_TAC thl)
   #([], "P a");;
   ([([], "P a")], -) : subgoals
\end{verbatim}
}
\USES
{\small\verb%ONCE_REWRITE_TAC%} can be used iteratively to rewrite when recursive
rewriting would diverge.  It can also be used to save inference steps.

\SEEALSO
ASM_REWRITE_TAC, ONCE_ASM_REWRITE_TAC, PURE_ASM_REWRITE_TAC,
PURE_ONCE_REWRITE_TAC, PURE_REWRITE_TAC, REWRITE_TAC, SUBST_TAC.

\ENDDOC
\DOC{oo}

\TYPE {\small\verb%$oo : ((((* # **) -> ***) # (**** -> *) # (**** -> **)) -> **** -> ***)%}\egroup

\SYNOPSIS
Composes a function a pair of functions: {\small\verb%(f oo (g,h)) x%} = {\small\verb%f (g x,h x)%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, CB, Co, I, K, KI, o, S, W.

\ENDDOC
\DOC{openi}

\TYPE {\small\verb%openi : (string -> string)%}\egroup

\SYNOPSIS
Opens a named port for input from a named file.

\DESCRIBE
Given a string argument {\small\verb%`foo`%}, {\small\verb%openi%} returns a string (a port identifier)
that can be used by the function {\small\verb%read%} to read characters from the file {\small\verb%foo%}.
The port identifier is also used as an argument to the function {\small\verb%close%};
{\small\verb%close%} terminates input.

\FAILURE
Fails if the file cannot be found with the current search path or if
read permission on the named file
is disabled.

\SEEALSO
close, openw, read, write

\ENDDOC
\DOC{openw}

\TYPE {\small\verb%openw : (string -> string)%}\egroup

\SYNOPSIS
Opens a port for writing to a named file.

\DESCRIBE
Given a string argument {\small\verb%`foo`%}, {\small\verb%openw%} creates a new file {\small\verb%foo%}
(overwriting an existing file with the same name) and returns a string
(a port identifier) that can be used by {\small\verb%write%} to write characters to the
 file. The port identifier is also used by {\small\verb%close%} to close the file.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let port = openw `foo`;;
port = `%foo` : string

#write (port, `contents of file foo\L`);;
() : void

#close port;;
() : void

#system `cat foo`;;
contents of file foo
0 : int
\end{verbatim}
}
\SEEALSO
close, openi, read, write

\ENDDOC
\DOC{ORELSEC}

\TYPE {\small\verb%$ORELSEC : (conv -> conv -> conv)%}\egroup

\SYNOPSIS
Applies the first of two conversions that succeeds.

\DESCRIBE
{\small\verb%(c1 ORELSEC c2) "t"%} returns the result of applying the conversion {\small\verb%c1%} to
the term {\small\verb%"t"%} if this succeeds.  Otherwise {\small\verb%(c1 ORELSEC c2) "t"%} returns the
result of applying the conversion {\small\verb%c2%} to the term {\small\verb%"t"%}.

\FAILURE
{\small\verb%(c1 ORELSEC c2) "t"%} fails both {\small\verb%c1%} and {\small\verb%c2%}  fail when applied to {\small\verb%"t"%}.

\SEEALSO
FIRST_CONV.

\ENDDOC
\DOC{ORELSE}

\TYPE {\small\verb%$ORELSE : (tactic -> tactic -> tactic)%}\egroup

\SYNOPSIS
Applies first tactic, and iff it fails, applies the second instead.

\DESCRIBE
If {\small\verb%T1%} and {\small\verb%T2%} are tactics, {\small\verb%T1 ORELSE T2%} is a tactic which applies {\small\verb%T1%} to
a goal, and iff it fails, applies {\small\verb%T2%} to the goal instead.

\FAILURE
The application of {\small\verb%ORELSE%} to a pair of tactics never fails.
The resulting tactic fails if both {\small\verb%T1%} and {\small\verb%T2%} fail when applied to the
relevant goal.

\SEEALSO
EVERY, FIRST, THEN.

\ENDDOC
\DOC{ORELSE\_TCL}

\TYPE {\small\verb%$ORELSE_TCL : (thm_tactical -> thm_tactical -> thm_tactical)%}\egroup

\SYNOPSIS
Applies a theorem-tactical, and if it fails, tries a second.

\DESCRIBE
When applied to two theorem-tacticals, {\small\verb%ttl1%} and {\small\verb%ttl2%}, a theorem-tactic
{\small\verb%ttac%}, and a theorem {\small\verb%th%}, if {\small\verb%ttl1 ttac th%} succeeds, that gives the
result. If it fails, the result is {\small\verb%ttl2 ttac th%}, which may itself fail.

\FAILURE
{\small\verb%ORELSE_TCL%} fails if both the theorem-tacticals fail when applied to the
given theorem-tactic and theorem.

\SEEALSO
EVERY_TCL, FIRST_TCL, THEN_TCL.

\ENDDOC
\DOC{OR\_EXISTS\_CONV}

\TYPE {\small\verb%OR_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification outwards through a disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(?x.P) \/ (?x.Q)%}, the conversion
{\small\verb%OR_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x.P) \/ (?x.Q) = (?x. P \/ Q)
\end{verbatim}
}
\FAILURE
Fails if applied to a term not of the form {\small\verb%(?x.P) \/ (?x.Q)%}.

\SEEALSO
EXISTS_OR_CONV, LEFT_OR_EXISTS_CONV, RIGHT_OR_EXISTS_CONV.

\ENDDOC
\DOC{OR\_FORALL\_CONV}

\TYPE {\small\verb%OR_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification outwards through a disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%(!x.P) \/ (!x.Q)%}, where {\small\verb%x%} is free
in neither {\small\verb%P%} nor {\small\verb%Q%}, {\small\verb%OR_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x. P) \/ (!x. Q) = (!x. P \/ Q)
\end{verbatim}
}
\FAILURE
{\small\verb%OR_FORALL_CONV%} fails if it is applied to a term not of the form
{\small\verb%(!x.P) \/ (!x.Q)%}, or if it is applied to a term {\small\verb%(!x.P) \/ (!x.Q)%}
in which the variable {\small\verb%x%} is free in either {\small\verb%P%} or {\small\verb%Q%}.

\SEEALSO
FORALL_OR_CONV, LEFT_OR_FORALL_CONV, RIGHT_OR_FORALL_CONV.

\ENDDOC
\DOC{outl}

\TYPE {\small\verb%outl : ((* + **) -> *)%}\egroup

\SYNOPSIS
Projects out of left summand.

\DESCRIBE
The function {\small\verb%outl%} is associated with the disjoint union
construction of types. It projects out of the left summand of the union.

\FAILURE
Fails if the operand is a right summand.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let x = inl 1
#and y = inr 2;;
x = inl 1 : (int + *)
y = inr 2 : (* + int)

#outl x;;
1 : int

#outl y;;
evaluation failed     outl
\end{verbatim}
}
\SEEALSO
outr inl inr isl.

\ENDDOC
\DOC{outr}

\TYPE {\small\verb%outr : ((* + **) -> **)%}\egroup

\SYNOPSIS
Projects out of right summand.

\DESCRIBE
The function {\small\verb%outr%} is associated with the disjoint union construction of
types. It projects out of the right summand of the union.

\FAILURE
Fails if the operand is a left summand.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let x = inl 1
#and y = inr 2;;
x = inl 1 : (int + *)
y = inr 2 : (* + int)

#outr x;;
evaluation failed     outr

#outr y;;
2 : int
\end{verbatim}
}
\SEEALSO
outl, inl, inr, isl

\ENDDOC
\DOC{pair}

\TYPE {\small\verb%pair : (* -> ** -> (* # **))%}\egroup

\SYNOPSIS
Makes two values into a pair.

\DESCRIBE
{\small\verb%pair x y%} returns {\small\verb%(x,y)%}.

\FAILURE
Never fails.

\SEEALSO
fst, snd, curry, uncurry.

\ENDDOC
\DOC{PAIRED\_BETA\_CONV}

\TYPE {\small\verb%PAIRED_BETA_CONV : conv%}\egroup

\SYNOPSIS
Performs generalized beta conversion for tupled beta-redexes.

\DESCRIBE
The conversion {\small\verb%PAIRED_BETA_CONV%} implements beta-reduction for certain
applications of tupled lambda abstractions called `tupled beta-redexes'.
Tupled lambda abstractions have the form {\small\verb%"\<vs>.tm"%}, where {\small\verb%<vs>%} is an
arbitrarily-nested tuple of variables called a `varstruct'. For the purposes of
{\small\verb%PAIRED_BETA_CONV%}, the syntax of varstructs is given by:
{\par\samepage\setseps\small
\begin{verbatim}
   <vs>  ::=   (v1,v2)  |  (<vs>,v)  |  (v,<vs>)  |  (<vs>,<vs>)
\end{verbatim}
}
\noindent where {\small\verb%v%}, {\small\verb%v1%}, and {\small\verb%v2%} range over variables.  A tupled beta-redex
is an application of the form {\small\verb%"(\<vs>.tm) t"%}, where the term {\small\verb%"t"%} is a
nested tuple of values having the same structure as the varstruct {\small\verb%<vs>%}. For
example, the term:
{\par\samepage\setseps\small
\begin{verbatim}
   "(\((a,b),(c,d)). a + b + c + d)  ((1,2),(3,4))"
\end{verbatim}
}
\noindent is a tupled beta-redex, but the term:
{\par\samepage\setseps\small
\begin{verbatim}
   "(\((a,b),(c,d)). a + b + c + d)  ((1,2),p)"
\end{verbatim}
}
\noindent is not, since {\small\verb%p%} is not a pair of terms.

Given a tupled beta-redex {\small\verb%"(\<vs>.tm) t"%}, the conversion {\small\verb%PAIRED_BETA_CONV%}
performs generalized beta-reduction and returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |-  (\<vs>.tm) t = t[t1,...,tn/v1,...,vn]
\end{verbatim}
}
\noindent where {\small\verb%ti%} is the subterm of the tuple {\small\verb%t%} that corresponds to
the variable {\small\verb%vi%} in the varstruct {\small\verb%<vs>%}. In the simplest case, the
varstruct {\small\verb%<vs>%} is flat, as in the term:
{\par\samepage\setseps\small
\begin{verbatim}
   "(\(v1,...,vn).t) (t1,...,tn)"
\end{verbatim}
}
\noindent When applied to a term of this form, {\small\verb%PAIRED_BETA_CONV%} returns:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\(v1, ... ,vn).t) (t1, ... ,tn) = t[t1,...,tn/v1,...,vn]
\end{verbatim}
}
\noindent As with ordinary beta-conversion, bound variables may be renamed to
prevent free variable capture.  That is, the term {\small\verb%t[t1,...,tn/v1,...,vn]%} in
this theorem is the result of substituting {\small\verb%ti%} for {\small\verb%vi%} in parallel in {\small\verb%t%},
with suitable renaming of variables to prevent free variables in {\small\verb%t1%}, ...,
{\small\verb%tn%} becoming bound in the result.

\FAILURE
{\small\verb%PAIRED_BETA_CONV tm%} fails if {\small\verb%tm%} is not a tupled beta-redex, as described
above.  Note that ordinary beta-redexes are specifically excluded:
{\small\verb%PAIRED_BETA_CONV%} fails when applied to {\small\verb%"(\v.t)u"%}.  For these beta-redexes,
use {\small\verb%BETA_CONV%}.

\EXAMPLE
The following is a typical use of the conversion:
{\par\samepage\setseps\small
\begin{verbatim}
   #PAIRED_BETA_CONV "(\((a,b),(c,d)). a + b + c + d)  ((1,2),(3,4))";;
   |- (\((a,b),c,d). a + (b + (c + d)))((1,2),3,4) = 1 + (2 + (3 + 4))
\end{verbatim}
}
\noindent Note that the term to which the tupled lambda abstraction
is applied must have the same structure as the varstruct.  For example,
the following succeeds:
{\par\samepage\setseps\small
\begin{verbatim}
   #PAIRED_BETA_CONV "(\((a,b),p). a + b)  ((1,2),(3+5,4))";;
   |- (\((a,b),p). a + b)((1,2),3 + 5,4) = 1 + 2
\end{verbatim}
}
\noindent but the following call to {\small\verb%PAIRED_BETA_CONV%} fails:
{\par\samepage\setseps\small
\begin{verbatim}
   #PAIRED_BETA_CONV "(\((a,b),(c,d)). a + b + c + d)  ((1,2),p)";;
   evaluation failed     PAIRED_BETA_CONV
\end{verbatim}
}
\noindent because {\small\verb%p%} is not a pair.

\SEEALSO
BETA_CONV, BETA_RULE, BETA_TAC, LIST_BETA_CONV, RIGHT_BETA, RIGHT_LIST_BETA.

\ENDDOC
\DOC{paired\_delete\_thm}

\TYPE {\small\verb%paired_delete_thm : ((string # string) -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{PAIRED\_ETA\_CONV}

\TYPE {\small\verb%PAIRED_ETA_CONV : conv%}\egroup

\SYNOPSIS
Performs generalized eta conversion for tupled eta-redexes.

\DESCRIBE
The conversion {\small\verb%PAIRED_ETA_CONV%} generalizes {\small\verb%ETA_CONV%} to eta-redexes with
tupled abstractions.
{\par\samepage\setseps\small
\begin{verbatim}
   PAIRED_ETA_CONV "\(v1..(..)..vn). f (v1..(..)..vn)"
    = |- \(v1..(..)..vn). f (v1..(..)..vn) = f
\end{verbatim}
}
\FAILURE
Fails unless the given term is a paired eta-redex as illustrated above.

\COMMENTS
Note that this result cannot be achieved by ordinary eta-reduction because the
tupled abstraction is a surface syntax for a term which does not correspond to
a normal pattern for eta reduction. Disabling the relevant prettyprinting
reveals the true form of a paired eta redex:
{\par\samepage\setseps\small
\begin{verbatim}
   #set_flag(`print_uncurry`,false);;
   true : bool

   #let tm = "\(x:num,y:num). FST (x,y)";;
   tm = "UNCURRY(\x y. FST(x,y))" : term
\end{verbatim}
}
\EXAMPLE
The following is a typical use of the conversion:
{\par\samepage\setseps\small
\begin{verbatim}
   let SELECT_PAIR_EQ = PROVE
    ("(@(x:*,y:**). (a,b) = (x,y)) = (a,b)",
     CONV_TAC (ONCE_DEPTH_CONV PAIRED_ETA_CONV) THEN
     ACCEPT_TAC (SYM (MATCH_MP SELECT_AX (REFL "(a:*,b:**)"))));;
\end{verbatim}
}

\SEEALSO
ETA_CONV.

\ENDDOC
\DOC{paired\_new\_type}

\TYPE {\small\verb%paired_new_type : ((int # string) -> void)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{paired\_theorem}

\TYPE {\small\verb%paired_theorem : ((string # string) -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{parents}

\TYPE {\small\verb%parents : (string -> string list)%}\egroup

\SYNOPSIS
Lists the parent theories of a named theory.

\DESCRIBE
The function {\small\verb%parents%} returns a list of strings that identify the
parent theories of a named theory. The function does not recursively
descend the theory hierarchy in search of the `leaf' theories.
The named theory must be the current theory or an ancestor of the
current theory.

\FAILURE
Fails if the named theory is not an ancestor of the current theory.

\EXAMPLE
Initially, the only parent is the main {\small\verb%HOL%} theory:
{\par\samepage\setseps\small
\begin{verbatim}
   #new_theory `my-theory`;;
   () : void

   #parents `my-theory`;;
   [`HOL`] : string list

   #parents `HOL`;;
   [`tydefs`; `sum`; `one`; `BASIC-HOL`] : string list

   #parents `tydefs`;;
   [`ltree`; `BASIC-HOL`] : string list

   #parents `string`;;
   evaluation failed     parents -- string is not an ancestor
\end{verbatim}
}
\noindent However, loading the string library creates several
additional ancestor theories:
{\par\samepage\setseps\small
\begin{verbatim}
   #load_library `string`;;
   Loading library `string` ...
   Updating search path
   .Updating help search path
   .Declaring theory string a new parent
   Theory string loaded
   ......
   Library `string` loaded.
   () : void

   #parents `string`;;
   [`ascii`; `HOL`] : string list

   #parents `my-theory`;;
   [`string`; `HOL`] : string list
\end{verbatim}
}
\SEEALSO
ancestors, ancestry.

\ENDDOC
\DOC{parse\_as\_binder}

\TYPE {\small\verb%parse_as_binder : (string -> string)%}\egroup

\SYNOPSIS
Makes the quotation parser treat a name as a binder.

\DESCRIBE
The call {\small\verb%parse_as_binder `c`%} will make the quotation parser treat {\small\verb%c%} as a
binder, that is, allow the syntactic sugaring {\small\verb%"c x. y"%} as a shorthand for
{\small\verb%"c (\x. y)"%}. As with normal binders, e.g. the universal quantifier, the
special syntactic status may be suppressed by preceding {\small\verb%c%} with a dollar sign.

\FAILURE
Never fails, even if the string is not an identifier.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#new_theory `groof`;;
() : void

#new_definition(`test`,"!! = ($!:(bool->bool)->bool)");;
|- !! = $!

#"!!x.T";;
. cannot be a term
skipping: . T " ;; parse failed

#parse_as_binder `!!`;;
`!!` : string

#"!!x.T";;
"!! x. T" : term

#"$!! (\x. T)";;
"!! x. T" : term
\end{verbatim}
}
\COMMENTS
Special parse status is allotted automatically when a binder is declared, so
this function is unlikely to be needed.

\SEEALSO
activate_all_binders, activate_binders, binders, new_binder.

\ENDDOC
\DOC{partition}

\TYPE {\small\verb%partition : ((* -> bool) -> * list -> (* list # * list))%}\egroup

\SYNOPSIS
Separates a list into two lists using a predicate.

\DESCRIBE
{\small\verb%partition p l%} returns a pair of lists. The first list contains the elements
which satisfy {\small\verb%p%}. The second list contains all the other elements.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#partition (\x. x + x = x * x) [1;2;3;4;5];;
([2], [1; 3; 4; 5]) : (int list # int list)
\end{verbatim}
}
\SEEALSO
chop_list, remove, filter.

\ENDDOC
\DOC{PART\_MATCH}

\TYPE {\small\verb%PART_MATCH : ((term -> term) -> thm -> term -> thm)%}\egroup

\SYNOPSIS
Instantiates a theorem by matching part of it to a term.

\DESCRIBE
When applied to a `selector' function of type {\small\verb%term -> term%}, a theorem and a
term:
{\par\samepage\setseps\small
\begin{verbatim}
   PART_MATCH fn (A |- !x1...xn. t) tm
\end{verbatim}
}
\noindent the function {\small\verb%PART_MATCH%} applies {\small\verb%fn%} to {\small\verb%t'%} (the result of
specializing universally quantified variables in the conclusion of the
theorem), and attempts to match the resulting term to the argument term
{\small\verb%tm%}.  If it succeeds, the appropriately instantiated version of the
theorem is returned.

\FAILURE
Fails if the selector function {\small\verb%fn%} fails when applied to the instantiated
theorem, or if the match fails with the term it has provided.

\EXAMPLE
Suppose that we have the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- !x. x==>x
\end{verbatim}
}
\noindent then the following:
{\par\samepage\setseps\small
\begin{verbatim}
   PART_MATCH (fst o dest_imp) th "T"
\end{verbatim}
}
\noindent results in the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- T ==> T
\end{verbatim}
}
\noindent because the selector function picks the antecedent of the
implication (the inbuilt specialization gets rid of the universal
quantifier), and matches it to {\small\verb%T%}.

\SEEALSO
INST_TYPE, INST_TY_TERM, match.

\ENDDOC
\DOC{p}

\TYPE {\small\verb%p : (int -> void)%}\egroup

\SYNOPSIS
Prints the top levels of the subgoal package goal stack.

\DESCRIBE
The function {\small\verb%p%} is part of the subgoal package. It is an abbreviation for the
function {\small\verb%print_state%}. For a description of the subgoal package, see
{\small\verb%set_goal%}.

\FAILURE
Never fails.

\USES
Examining the proof state during an interactive proof session.

\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{POP\_ASSUM}

\TYPE {\small\verb%POP_ASSUM : (thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Applies tactic generated from the first element of a goal's assumption list.

\DESCRIBE
When applied to a theorem-tactic and a goal, {\small\verb%POP_ASSUM%} applies
the theorem-tactic to the {\small\verb%ASSUME%}d first element of the assumption list,
and applies the resulting tactic to the goal without the first
assumption in its assumption list:
{\par\samepage\setseps\small
\begin{verbatim}
    POP_ASSUM f ({A1;...;An} ?- t) = f (A1 |- A1) ({A2;...;An} ?- t)
\end{verbatim}
}
\FAILURE
Fails if the assumption list of the goal is empty, or the theorem-tactic
fails when applied to the popped assumption, or if the resulting tactic
fails when applied to the goal (with depleted assumption list).

\COMMENTS
It is possible simply to use the theorem {\small\verb%ASSUME A1%} as required rather than
use {\small\verb%POP_ASSUM%}; this will also maintain {\small\verb%A1%} in the assumption list,
which is generally useful. In addition, this approach can equally well be
applied to assumptions other than the first.

There are admittedly times when {\small\verb%POP_ASSUM%} is convenient, but it is most
unwise to use it if there is more than one assumption in the assumption
list, since this introduces a dependency on the ordering, which is vulnerable
to changes in the HOL system.

Another point to consider is that if the relevant assumption has been obtained
by {\small\verb%DISCH_TAC%}, it is often cleaner to use {\small\verb%DISCH_THEN%} with a theorem-tactic.
For example, instead of:
{\par\samepage\setseps\small
\begin{verbatim}
   DISCH_TAC THEN POP_ASSUM (\th. SUBST1_TAC (SYM th))
\end{verbatim}
}
\noindent one might use
{\par\samepage\setseps\small
\begin{verbatim}
   DISCH_THEN (SUBST1_TAC o SYM)
\end{verbatim}
}
\EXAMPLE
The goal:
{\par\samepage\setseps\small
\begin{verbatim}
   {4 = SUC x} ?- x = 3
\end{verbatim}
}
\noindent can be solved by:
{\par\samepage\setseps\small
\begin{verbatim}
   POP_ASSUM (\th. REWRITE_TAC[REWRITE_RULE[num_CONV "4"; INV_SUC_EQ] th]))
\end{verbatim}
}
\USES
Making more delicate use of an assumption than rewriting or resolution
using it.

\SEEALSO
ASSUM_LIST, EVERY_ASSUM, IMP_RES_TAC, POP_ASSUM_LIST, REWRITE_TAC.

\ENDDOC
\DOC{POP\_ASSUM\_LIST}

\TYPE {\small\verb%POP_ASSUM_LIST : ((thm list -> tactic) -> tactic)%}\egroup

\SYNOPSIS
Generates a tactic from the assumptions, discards the assumptions and
applies the tactic.

\DESCRIBE
When applied to a function and a goal, {\small\verb%POP_ASSUM_LIST%} applies
the function to a list of theorems corresponding to the {\small\verb%ASSUME%}d
assumptions of the goal, then applies the resulting tactic to the goal
with an empty assumption list.
{\par\samepage\setseps\small
\begin{verbatim}
    POP_ASSUM_LIST f ({A1;...;An} ?- t) = f [A1 |- A1; ... ; An |- An] (?- t)
\end{verbatim}
}
\FAILURE
Fails if the function fails when applied to the list of {\small\verb%ASSUME%}d assumptions,
or if the resulting tactic fails when applied to the goal with no
assumptions.

\COMMENTS
There is nothing magical about {\small\verb%POP_ASSUM_LIST%}: the same effect can be
achieved by using {\small\verb%ASSUME a%} explicitly wherever the assumption {\small\verb%a%} is
used. If {\small\verb%POP_ASSUM_LIST%} is used, it is unwise to select elements by
number from the {\small\verb%ASSUME%}d-assumption list, since this introduces a dependency
on ordering.

\EXAMPLE
Suppose we have a goal of the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   {a /\ b, c, (d /\ e) /\ f} ?- t
\end{verbatim}
}
\noindent Then we can split the conjunctions in the assumption list apart by
applying the tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   POP_ASSUM_LIST (MAP_EVERY STRIP_ASSUME_TAC)
\end{verbatim}
}
\noindent which results in the new goal:
{\par\samepage\setseps\small
\begin{verbatim}
   {a, b, c, d, e, f} ?- t
\end{verbatim}
}
\USES
Making more delicate use of the assumption list than simply rewriting or
using resolution.

\SEEALSO
ASSUM_LIST, EVERY_ASSUM, IMP_RES_TAC, POP_ASSUM, REWRITE_TAC.

\ENDDOC
\DOC{pop\_proofs}

\TYPE {\small\verb%pop_proofs : (subgoals list -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{pop\_proofs\_print}

\TYPE {\small\verb%pop_proofs_print : (subgoals list -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{pp\_axiom}

\TYPE {\small\verb%pp_axiom : (string -> string -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{preterm\_abs}

\TYPE {\small\verb%preterm_abs : ((preterm # preterm) -> preterm)%}\egroup

\SYNOPSIS
Constructs abstraction preterm.

\DESCRIBE
{\small\verb%preterm_abs%} is analogous to the oft-used ML function {\small\verb%mk_abs%}.  Since,
however, preterms are untypechecked terms, the restrictions imposed when
using {\small\verb%mk_abs%} are not encountered until the preterm is typechecked.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let x = preterm_typed(preterm_var `x`,":bool");;
x = preterm_typed((preterm_var `x`), ":bool") : preterm

#let y = preterm_const `T`;;
y = preterm_const `T` : preterm

#preterm_abs(x,y);;
preterm_abs((preterm_typed((preterm_var `x`), ":bool")),
            preterm_const `T`)
: preterm

#preterm_to_term it;;
"\x. T" : term

#preterm_abs(y,x);;
preterm_abs((preterm_const `T`),
            preterm_typed((preterm_var `x`), ":bool"))
: preterm

#preterm_to_term it;;
evaluation failed     mk_abs
\end{verbatim}
}
\SEEALSO
mk_abs, preterm_antiquot, preterm_comb, preterm_const, preterm_typed,
preterm_var, preterm_to_term.

\ENDDOC
\DOC{preterm\_antiquot}

\TYPE {\small\verb%preterm_antiquot : (term -> preterm)%}\egroup

\SYNOPSIS
Constructs antiquoted preterm.

\DESCRIBE
{\small\verb%preterm_antiquot%} is analogous to the oft-used HOL strategy of antiquotation.
Since, however, preterms are untypechecked terms, the restrictions imposed
when using antiquotation are not encountered until the preterm is typechecked.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#preterm_antiquot "T";;
preterm_antiquot"T" : preterm

#preterm_comb(preterm_const `~`,it);;
preterm_comb((preterm_const `~`), preterm_antiquot"T") : preterm

#preterm_to_term it;;
"~T" : term
\end{verbatim}
}
\SEEALSO
preterm_abs, preterm_comb, preterm_const, preterm_typed, preterm_var,
preterm_to_term.

\ENDDOC
\DOC{preterm\_comb}

\TYPE {\small\verb%preterm_comb : ((preterm # preterm) -> preterm)%}\egroup

\SYNOPSIS
Constructs combination (function application) preterm.

\DESCRIBE
{\small\verb%preterm_comb%} is analogous to the oft-used ML function {\small\verb%mk_comb%}.  Since,
however, preterms are untypechecked terms, the restrictions imposed when
using {\small\verb%mk_comb%} are not encountered until the preterm is typechecked.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#preterm_comb(preterm_comb(preterm_const `+`,preterm_var `x`),
              preterm_const `1`);;
preterm_comb((preterm_comb((preterm_const `+`), preterm_var `x`)),
             preterm_const `1`)
: preterm

#preterm_to_term it;;
"x + 1" : term
\end{verbatim}
}
\SEEALSO
mk_comb, preterm_abs, preterm_antiquot, preterm_const, preterm_typed,
preterm_var, preterm_to_term.

\ENDDOC
\DOC{preterm\_const}

\TYPE {\small\verb%preterm_const : (string -> preterm)%}\egroup

\SYNOPSIS
Constructs constant preterm.

\DESCRIBE
{\small\verb%preterm_const%} is analogous to the oft-used ML function {\small\verb%mk_var%}.  Since,
however, preterms are untypechecked terms, the restrictions imposed when
using {\small\verb%mk_const%} (i.e. that the constant must be either implicitly or
explicitly associated with a specific type) are not encountered until the
preterm is typechecked.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#preterm_const `T`;;
preterm_const `T` : preterm

#preterm_to_term it;;
"T" : term

#type_of it;;
":bool" : type
\end{verbatim}
}
\SEEALSO
mk_const, preterm_abs, preterm_antiquot, preterm_comb, preterm_typed,
preterm_var, preterm_to_term.

\ENDDOC
\DOC{preterm\_to\_term}

\TYPE {\small\verb%preterm_to_term : (preterm -> term)%}\egroup

\SYNOPSIS
Converts a preterm to a HOL term.

\DESCRIBE
Preterms are untypechecked terms, and are included in the HOL system
to allow embedding of special purpose parsers, and to provide a way
of experimenting with other forms of type checking.  {\small\verb%preterm_to_term%} is
the hook for pushing preterms through the standard HOL typechecker.

\FAILURE
Fails with the appropriate HOL error message.

\SEEALSO
preterm_abs, preterm_antiquot, preterm_comb, preterm_const, preterm_typed,
preterm_var.

\ENDDOC
\DOC{preterm\_typed}

\TYPE {\small\verb%preterm_typed : ((preterm # type) -> preterm)%}\egroup

\SYNOPSIS
Constructs a typed preterm.

\DESCRIBE
{\small\verb%preterm_typed%} allows type information to be associated with various
substructures of a given preterm.  One can, therefore, construct improperly
typed preterms that will fail to typecheck when {\small\verb%preterm_to_term%} is
invoked.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#preterm_typed(preterm_const `T`,":bool");;
preterm_typed((preterm_const `T`), ":bool") : preterm

#preterm_to_term it;;
"T" : term

#preterm_typed(preterm_const `T`,":num");;
preterm_typed((preterm_const `T`), ":num") : preterm

#preterm_to_term it;;
evaluation failed     types
\end{verbatim}
}
\SEEALSO
preterm_abs, preterm_antiquot, preterm_comb, preterm_const, preterm_var,
preterm_to_term.

\ENDDOC
\DOC{preterm\_var}

\TYPE {\small\verb%preterm_var : (string -> preterm)%}\egroup

\SYNOPSIS
Constructs variable preterm.

\DESCRIBE
{\small\verb%preterm_var%} is analogous to the oft-used ML function {\small\verb%mk_var%}.  Since,
however, preterms are untypechecked terms, the restrictions imposed when
using {\small\verb%mk_var%} (i.e. that the variable must be either implicitly or
explicitly associated with a specific type) are not encountered until
the preterm is typechecked.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#preterm_var `x`;;
preterm_var `x` : preterm

#preterm_to_term it;;
Indeterminate types:  "x:?"

evaluation failed     types indeterminate

#preterm_typed(preterm_var `x`,":bool");;
preterm_typed((preterm_var `x`), ":bool") : preterm

#preterm_to_term it;;
"x" : term
\end{verbatim}
}
\SEEALSO
mk_var, preterm_abs, preterm_antiquot, preterm_comb, preterm_const,
preterm_typed, preterm_to_term.

\ENDDOC
\DOC{print\_all\_thm}

\TYPE {\small\verb%print_all_thm : (thm -> void)%}\egroup

\SYNOPSIS
Prints a theorem in full.

\DESCRIBE
The function {\small\verb%print_all_thm%} will cause the system to print a
theorem with its hypotheses.

\FAILURE
Never fails.

\EXAMPLE
As a simple example of the use of {\small\verb%print_all_thm%} we assume the
following two theorems:
{\par\samepage\setseps\small
\begin{verbatim}
   #let a = ASSUME "A:bool";;
   a = . |- A
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
   #let b = ASSUME "A ==> B";;
   b = . |- A ==> B
\end{verbatim}
}
\noindent Using Modus Ponens (MP) as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #let r = MP b a;;
\end{verbatim}
}
\noindent The system responds with:
{\par\samepage\setseps\small
\begin{verbatim}
   r = .. |- B
\end{verbatim}
}
\noindent By using {\small\verb%print_all_thm%} as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #print_all_thm r;;
\end{verbatim}
}
\noindent The system then pretty prints:
{\par\samepage\setseps\small
\begin{verbatim}
   A ==> B, A |- B() : void
\end{verbatim}
}
\noindent This shows all the assumptions of the theorem in a comma separated
list.

\SEEALSO
print_thm.

\ENDDOC
\DOC{print\_begin}

\TYPE {\small\verb%print_begin : (int -> void)%}\egroup

\SYNOPSIS
Initiates a pretty printing block.

\DESCRIBE
The function {\small\verb%print_begin%} initiates a consistent printing block. Consistent
breaks cause uniform indentation at each break. This means that if a list is
printed and the total list is wider than the margin then the list will be
broken at every possible breaking point. The argument is the offset of the
block that {\small\verb%print_begin%} initiates. This offset is added to the indentation
of any lines broken inside. This offset is virtually never used and should
preferably be avoided.

\FAILURE
Never fails.

\EXAMPLE
\noindent The first step is to set the margin to be 13 characters wide:
{\par\samepage\setseps\small
\begin{verbatim}
   #set_margin 13;;
\end{verbatim}
}
\noindent The second is to initialize the block using {\small\verb%print_begin%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #let  example =
      (print_newline();
       print_begin 0;
       print_string `first`;
       print_break (1,2);
       print_string `second`;
       print_break (1,2);
       print_string `third`;
       print_end();
       print_newline());;
\end{verbatim}
}
\noindent After initialization of the block three strings `first',`second'
and `third' are printed each with a break between them. The total
width of the three strings is more than 13 (margin) but the first two (`first'
and `second') combined with the space between them is less than 13. From the
result of consistent formatting shown below it is clear that if any wrapping
takes place everything will be wrapped. To clearly
see what consistent breaking means contrast the above with {\small\verb%print_ibegin%}
where the same example is used but with inconsistent formatting.

\noindent The output we obtain is the following:
{\par\samepage\setseps\small
\begin{verbatim}
   first
     second
     third
   example =
   ()
   : void
\end{verbatim}
}
\SEEALSO
print_ibegin, print_break, print_end, max_print_depth, set_margin,
print_newline

\ENDDOC
\DOC{print\_bool}

\TYPE {\small\verb%print_bool : (bool -> void)%}\egroup

\SYNOPSIS
Prints the value of a boolean variable.

\FAILURE
Never fails.

\EXAMPLE
As a simple example, assign the value {\small\verb%true%} to a variable:
{\par\samepage\setseps\small
\begin{verbatim}
   #let B = true;;

   B = true : bool
\end{verbatim}
}
\noindent If we now want find the value of B we type:
{\par\samepage\setseps\small
\begin{verbatim}
   #print_bool B;;
\end{verbatim}
}
\noindent and the system responds with:
{\par\samepage\setseps\small
\begin{verbatim}
   true() : void
\end{verbatim}
}
\ENDDOC
\DOC{print\_break}

\TYPE {\small\verb%print_break : ((int # int) -> void)%}\egroup

\SYNOPSIS
Breaks a pretty printing block into parts.

\DESCRIBE
The function {\small\verb%print_break%} is used within the print formatting block
formed by either {\small\verb%print_begin%} or {\small\verb%print_ibegin%} and {\small\verb%print_end%}. It is used
to indicate points where breaks can occur within a list being printed. The
function takes two integer arguments, the first indicating the width
of the break and the second specifying an offset to be used if
wrapping has to be done.

\FAILURE
Never fails.

\EXAMPLE
We first set the margin to 13 by:
{\par\samepage\setseps\small
\begin{verbatim}
   #set_margin 13;;
   72 : int
\end{verbatim}
}
\noindent A simple formatting action is done in the ML segment given below:
{\par\samepage\setseps\small
\begin{verbatim}
   #let  example =
      (print_begin 0;
       print_string `first`;
       print_break (1,2);
       print_string `second`;
       print_break (1,2);
       print_end());;
\end{verbatim}
}
\noindent In this fragment of code {\small\verb%print_break%} is used to put a single
space  between the strings. However if wrapping occurs, {\small\verb%print_break%}
indents the following line by two spaces. The result of this fragment is:
{\par\samepage\setseps\small
\begin{verbatim}
   first second example =
   ()
   : void
\end{verbatim}
}
\noindent If we now change the margin to 10 and execute the same fragment (not
given):
{\par\samepage\setseps\small
\begin{verbatim}
   #set_margin 10;;
   13 : int
\end{verbatim}
}
\noindent The result is wrapped with an indent of two character spaces from the
left.
{\par\samepage\setseps\small
\begin{verbatim}
   first
     second
     example =
   ()
   : void
\end{verbatim}
}
\noindent Wrapping took place due to the new margin setting.

\SEEALSO
print_begin, print_ibegin, print_end, print_newline

\ENDDOC
\DOC{print\_defined\_types}

\TYPE {\small\verb%print_defined_types : (void -> void)%}\egroup

\SYNOPSIS
Prints all currently defined ML types known to the system.

\DESCRIBE
The function prints all ML types defined by means of {\small\verb%lettype%}. It also
lists all abstract types in the system. The printing of {\small\verb%lettype%}
defined types can be suppressed by setting the flag {\small\verb%print_lettypes%} to
{\small\verb%false%}. The resulting suppression is only partial as only the outer
level of defined types is expanded.

\FAILURE
Never fails.

\ENDDOC
\DOC{print\_end}

\TYPE {\small\verb%print_end : (void -> void)%}\egroup

\SYNOPSIS
Closes a formatting block.

\DESCRIBE
This function closes a formatting block initialized
by {\small\verb%print_begin%} or {\small\verb%print_ibegin%}. It terminates the offset settings
that were defined within the block.

\FAILURE
Never fails.

\EXAMPLE

{\par\samepage\setseps\small
\begin{verbatim}
#let  example =
   (print_begin 0;
    print_string `first`;
    print_break (0,2);
    print_string `second`;
    print_break (0,2);
    print_end());;
\end{verbatim}
}
\noindent It is immediately clear how the function terminates the formatting
block.

\SEEALSO
print_begin, print_ibegin

\ENDDOC
\DOC{print\_goal}

\TYPE {\small\verb%print_goal : (goal -> void)%}\egroup

\SYNOPSIS
Prints a goal, including its assumptions.

\DESCRIBE
The function {\small\verb%print_goal%} takes a goal as argument and prints the goal
and its list of assumptions.

\FAILURE
Never fails.

\EXAMPLE
If we define a goal in the following manner:
{\par\samepage\setseps\small
\begin{verbatim}
   #let goal = ([],"!a. a /\ T ==> a");;
   goal = ([], "!a. a /\ T ==> a") : (* list # term)

\end{verbatim}
}
\noindent and then do:
{\par\samepage\setseps\small
\begin{verbatim}
   #print_goal goal;;
\end{verbatim}
}
\noindent The system responds with:
{\par\samepage\setseps\small
\begin{verbatim}
   "!a. a /\ T ==> a"

   () : void
\end{verbatim}
}
\noindent If there were assumptions these would also have been printed.

\SEEALSO
print_thm

\ENDDOC
\DOC{print\_hyps}

\TYPE {\small\verb%print_hyps : (term list -> void)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{print\_ibegin}

\TYPE {\small\verb%print_ibegin : (int -> void)%}\egroup

\SYNOPSIS
Initiates a pretty printing block with inconsistent breaks.

\DESCRIBE
The function {\small\verb%print_ibegin%} initiates a inconsistent printing block.
Inconsistent breaks cause non-uniform
indentation at each break which is unlike the `all or nothing'
approach  of consistent formatting (see {\small\verb%print_begin%}). The argument is the
offset of the block that {\small\verb%print_ibegin%} initiates. This offset is added to the
indentation of any lines broken inside. This offset is very seldom used.

\FAILURE
Never fails.

\EXAMPLE
\noindent Set the margin to be 13 characters wide:
{\par\samepage\setseps\small
\begin{verbatim}
#set_margin 13;;
13 : int
\end{verbatim}
}
\noindent Then initialize the block using {\small\verb%print_ibegin%}:
{\par\samepage\setseps\small
\begin{verbatim}
#let  example =
   (print_newline();
    print_ibegin 0;
    print_string `first`;
    print_break (1,2);
    print_string `second`;
    print_break (1,2);
    print_string `third`;
    print_end();
    print_newline());;

\end{verbatim}
}
\noindent After the initialization of the block the strings
`first', `second' and `third' are printed with breaks between them. The first
line does not break because we only
have 12 characters on the line {\small\verb%first second%}. When starting to print `third'
though wrapping has to take place.

\noindent The output we obtain is the following:
{\par\samepage\setseps\small
\begin{verbatim}
   first second
     third
   example =
   ()
   : void
\end{verbatim}
}

\SEEALSO
print_break, print_end, max_print_depth, print_begin

\ENDDOC
\DOC{print\_int}

\TYPE {\small\verb%print_int : (int -> void)%}\egroup

\SYNOPSIS
Prints an ML integer to the terminal.

\DESCRIBE
{\small\verb%print_int n%} returns {\small\verb%():void%} with the side-effect of printing the value
of {\small\verb%n%} to the terminal. The text is not terminated with a carriage return.
In fact, the text is queued until the pretty-printer decides where line breaks
are needed, or until the queue is explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_int 2;;
2() : void

#print_int (-10);;
-10() : void
\end{verbatim}
}
\SEEALSO
print_begin, print_end, print_newline.

\ENDDOC
\DOC{print\_list}

\TYPE {\small\verb%print_list : (bool -> string -> (* -> **) -> * list -> void)%}\egroup

\SYNOPSIS
Prints a list to the terminal in a specific format.

\DESCRIBE
{\small\verb%print_list incon name prfn l%} returns {\small\verb%():void%} with the side-effect of
printing the elements of {\small\verb%l%} to the terminal using the print function {\small\verb%prfn%}.
The string {\small\verb%name%} is also displayed and the flag {\small\verb%incon%} specifies whether
line breaking between elements of the list is to be inconsistent ({\small\verb%incon%} is
{\small\verb%true%}) or consistent ({\small\verb%incon%} is {\small\verb%false%}). If the list {\small\verb%l%} is empty, no text
is displayed. When {\small\verb%l%} is not empty, the elements of the list are printed in
reverse order.

The format of the output is illustrated in the example. {\small\verb%print_list%} is used
within the HOL system for printing theories. It is unlikely to be of use in
general.

\FAILURE
Fails if the print function {\small\verb%prfn%} fails on any of the arguments of the
list {\small\verb%l%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#set_margin 15;;
72 : int
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
#print_list true `Test1:` print_int [1;2;3;4;5;6];;
Test1: --
  6     5
  4     3
  2     1
() : void
\end{verbatim}
}
{\par\samepage\setseps\small
\begin{verbatim}
#print_list false `Test2:` print_int [1;2;3;4;5;6];;
Test2: --
  6
  5
  4
  3
  2
  1

() : void
\end{verbatim}
}
\SEEALSO
print_theory, print_begin, print_end, print_newline.

\ENDDOC
\DOC{print\_newline}

\TYPE {\small\verb%print_newline : (void -> void)%}\egroup

\SYNOPSIS
Prints a newline.

\DESCRIBE
The function {\small\verb%print_newline%} starts the text following it on the next
line. This is done irrespective of consistent or inconsistent
formatting and margin settings.

\FAILURE
Never fails.

\EXAMPLE
A simple example is:
{\par\samepage\setseps\small
\begin{verbatim}
   #let example =
      (print_string `first`;
       print_newline();
       print_string `second`;
       print_newline());;
\end{verbatim}
}
\noindent The result is:
{\par\samepage\setseps\small
\begin{verbatim}
   first
   second
   example = () : void
\end{verbatim}
}

\SEEALSO
print_begin, print_end, print_break

\ENDDOC
\DOC{print\_stack}

\TYPE {\small\verb%print_stack : (subgoals list -> int -> void)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{print\_state}

\TYPE {\small\verb%print_state : (int -> void)%}\egroup

\SYNOPSIS
Prints the top levels of  the subgoal package goal stack.

\DESCRIBE
The function {\small\verb%print_state%} is part of the subgoal package. Calling
{\small\verb%print_state n%} prints the top {\small\verb%n%} levels of the goal stack of the current
proof state (that is, the top {\small\verb%n%} levels of unproven subgoals). If more than
one subgoal is produced, they are printed from the bottom of the stack so that
the current goal is printed last. If {\small\verb%n%} is negative or is greater than the
number of levels on the goal stack, the whole stack is printed. If no goal has
been set or {\small\verb%n%} is zero, nothing will be printed. If the original goal has just
been proved so that the proof state consists of a theorem, and {\small\verb%n%} is non-zero,
{\small\verb%goal proved%} is printed. For a description of the subgoal package, see
{\small\verb%set_goal%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])";;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

() : void

#e CONJ_TAC;;
OK..
2 subgoals
"TL[1;2;3] = [2;3]"

"HD[1;2;3] = 1"

() : void

#print_state 2;;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

2 subgoals
"TL[1;2;3] = [2;3]"

"HD[1;2;3] = 1"

() : void
\end{verbatim}
}
\USES
Examining the proof state during an interactive proof session.

\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, p, r,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{print\_string}

\TYPE {\small\verb%print_string : (string -> void)%}\egroup

\SYNOPSIS
Prints an ML string to the terminal (without surrounding string quotes).

\DESCRIBE
{\small\verb%print_string s%} returns {\small\verb%():void%} with the side-effect of printing the string
{\small\verb%s%} to the terminal. String quotes are not printed around the string, and the
text is not terminated with a carriage return. In fact, the text is queued
until the pretty-printer decides where line breaks are needed, or until the
queue is explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_string `This is an example`;;
This is an example() : void
\end{verbatim}
}
\SEEALSO
print_tok, message, print_begin, print_end, print_newline.

\ENDDOC
\DOC{print\_subgoals}

\TYPE {\small\verb%print_subgoals : (subgoals -> void)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{print\_term}

\TYPE {\small\verb%print_term : (term -> void)%}\egroup

\SYNOPSIS
Prints a HOL term to the terminal.

\DESCRIBE
{\small\verb%print_term tm%} returns {\small\verb%():void%} with the side-effect of printing the value
of {\small\verb%tm%} to the terminal. The text is not terminated with a carriage return.
In fact, the text is queued until the pretty-printer decides where line breaks
are needed, or until the queue is explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_term "x /\ y";;
"x /\ y"() : void
\end{verbatim}
}
\SEEALSO
print_begin, print_end, print_newline, show_types, print_type, print_thm.

\ENDDOC
\DOC{print\_theory}

\TYPE {\small\verb%print_theory : (string -> void)%}\egroup

\SYNOPSIS
Prints the contents of a HOL theory to the terminal.

\DESCRIBE
{\small\verb%print_theory `name`%} returns {\small\verb%():void%} with the side-effect of printing the
contents of the theory called {\small\verb%name%}. {\small\verb%print_theory `-`%} prints the current
theory. The following information is displayed: the parents of the theory,
types defined within the theory, type abbreviations defined within the theory,
constants of the theory, the binders and infixes (subsets of the constants),
the axioms, the definitions, and the derived theorems.

\FAILURE
Fails if the named theory does not exist or is not an ancestor of the current
theory.

\EXAMPLE
To obtain an example, type {\small\verb%print_theory `bool`;;%} to the system.

\SEEALSO
print_type, print_term, print_thm.

\ENDDOC
\DOC{print\_thm}

\TYPE {\small\verb%print_thm : (thm -> void)%}\egroup

\SYNOPSIS
Prints a HOL theorem to the terminal (abbreviating assumptions).

\DESCRIBE
{\small\verb%print_thm th%} returns {\small\verb%():void%} with the side-effect of printing the value
of {\small\verb%th%} to the terminal. The text is not terminated with a carriage return.
In fact, the text is queued until the pretty-printer decides where line breaks
are needed, or until the queue is explicitly flushed.

Each assumption of the theorem is printed as one dot (period, full stop).

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_thm CONJ_SYM;;
|- !t1 t2. t1 /\ t2 = t2 /\ t1() : void
\end{verbatim}
}
\SEEALSO
print_all_thm, print_begin, print_end, print_newline, show_types, print_type,
print_term.

\ENDDOC
\DOC{print\_tok}

\TYPE {\small\verb%print_tok : (string -> void)%}\egroup

\SYNOPSIS
Prints an ML string to the terminal (with surrounding string quotes).

\DESCRIBE
{\small\verb%print_tok s%} returns {\small\verb%():void%} with the side-effect of printing the string
{\small\verb%s%} to the terminal. String quotes are printed around the string but the text
is not terminated with a carriage return. In fact, the text is queued until
the pretty-printer decides where line breaks are needed, or until the queue is
explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_tok `This is an example`;;
`This is an example`() : void
\end{verbatim}
}
\SEEALSO
print_string, message, print_begin, print_end, print_newline.

\ENDDOC
\DOC{print\_type}

\TYPE {\small\verb%print_type : (type -> void)%}\egroup

\SYNOPSIS
Prints a HOL type to the terminal.

\DESCRIBE
{\small\verb%print_type ty%} returns {\small\verb%():void%} with the side-effect of printing the value
of {\small\verb%ty%} to the terminal. The text is not terminated with a carriage return.
In fact, the text is queued until the pretty-printer decides where line breaks
are needed, or until the queue is explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_type ":bool";;
":bool"() : void
\end{verbatim}
}
\SEEALSO
print_begin, print_end, print_newline, print_term, print_thm.

\ENDDOC
\DOC{print\_unquoted\_term}

\TYPE {\small\verb%print_unquoted_term : (term -> void)%}\egroup

\SYNOPSIS
Prints a HOL term to the terminal without surrounding quotes.

\DESCRIBE
{\small\verb%print_unquoted_term tm%} returns {\small\verb%():void%} with the side-effect of printing
the value of {\small\verb%tm%} to the terminal without surrounding quotes. The text is not
terminated with a carriage return. In fact, the text is queued until the
pretty-printer decides where line breaks are needed, or until the queue is
explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_unquoted_term "x /\ y";;
x /\ y() : void
\end{verbatim}
}
\SEEALSO
print_term, print_begin, print_end, print_newline, show_types, print_type,
print_thm, print_unquoted_type.

\ENDDOC
\DOC{print\_unquoted\_type}

\TYPE {\small\verb%print_unquoted_type : (type -> void)%}\egroup

\SYNOPSIS
Prints a HOL type to the terminal without surrounding quotes and without the
leading colon.

\DESCRIBE
{\small\verb%print_unquoted_type ty%} returns {\small\verb%():void%} with the side-effect of printing
the value of {\small\verb%ty%} to the terminal without surrounding quotes and without the
leading colon. The text is not terminated with a carriage return. In fact, the
text is queued until the pretty-printer decides where line breaks are needed,
or until the queue is explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_unquoted_type ":bool";;
bool() : void
\end{verbatim}
}
\SEEALSO
print_type, print_begin, print_end, print_newline, print_term, print_thm,
print_unquoted_term.

\ENDDOC
\DOC{print\_void}

\TYPE {\small\verb%print_void : (void -> void)%}\egroup

\SYNOPSIS
Prints `{\small\verb%()%}' to the terminal.

\DESCRIBE
{\small\verb%print_void ()%} returns {\small\verb%():void%} with the side-effect of printing the value
`{\small\verb%()%}' to the terminal. The text is not terminated with a carriage return.
In fact, the text is queued until the pretty-printer decides where line breaks
are needed, or until the queue is explicitly flushed.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#print_void();;
()() : void
\end{verbatim}
}
\SEEALSO
print_begin, print_end, print_newline.

\ENDDOC
\DOC{prompt}

\TYPE {\small\verb%prompt : (bool -> bool)%}\egroup

\SYNOPSIS
Switches the ML prompt on or off.

\DESCRIBE
{\small\verb%prompt true%} switches on the ML prompt (which is `{\small\verb%#%}' by default);
{\small\verb%prompt false%} switches it off. In either case, {\small\verb%prompt%} returns the previous
state ({\small\verb%true%} for on, {\small\verb%false%} for off).

\FAILURE
Never fails.

\SEEALSO
set_prompt.

\ENDDOC
\DOC{prove\_abs\_fn\_one\_one}

\TYPE {\small\verb%prove_abs_fn_one_one : (thm -> thm)%}\egroup

\SYNOPSIS
Proves that a type abstraction function is one-to-one (injective).

\DESCRIBE
If {\small\verb%th%} is a theorem of the form returned by the function
{\small\verb%define_new_type_bijections%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!a. abs(rep a) = a) /\ (!r. P r = (rep(abs r) = r))
\end{verbatim}
}
\noindent then {\small\verb%prove_abs_fn_one_one th%} proves from this theorem that the
function {\small\verb%abs%} is one-to-one for values that satisfy {\small\verb%P%}, returning the
theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !r r'. P r ==> P r' ==> ((abs r = abs r') = (r = r'))
\end{verbatim}
}
\FAILURE
Fails if applied to a theorem not of the form shown above.

\SEEALSO
new_type_definition, define_new_type_bijections, prove_abs_fn_onto,
prove_rep_fn_one_one, prove_rep_fn_onto.

\ENDDOC
\DOC{prove\_abs\_fn\_onto}

\TYPE {\small\verb%prove_abs_fn_onto : (thm -> thm)%}\egroup

\SYNOPSIS
Proves that a type abstraction function is onto (surjective).

\DESCRIBE
If {\small\verb%th%} is a theorem of the form returned by the function
{\small\verb%define_new_type_bijections%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!a. abs(rep a) = a) /\ (!r. P r = (rep(abs r) = r))
\end{verbatim}
}
\noindent then {\small\verb%prove_abs_fn_onto th%} proves from this theorem that the
function {\small\verb%abs%} is onto, returning the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !a. ?r. (a = abs r) /\ P r
\end{verbatim}
}
\FAILURE
Fails if applied to a theorem not of the form shown above.

\SEEALSO
new_type_definition, define_new_type_bijections, prove_abs_fn_one_one,
prove_rep_fn_one_one, prove_rep_fn_onto.

\ENDDOC
\DOC{prove\_cases\_thm}

\TYPE {\small\verb%prove_cases_thm : (thm -> thm)%}\egroup

\SYNOPSIS
Proves a structural cases theorem for an automatically-defined concrete type.

\DESCRIBE
{\small\verb%prove_cases_thm%} takes as its argument a structural induction theorem, in the
form returned by {\small\verb%prove_induction_thm%} for an automatically-defined concrete
type.  When applied to such a theorem, {\small\verb%prove_cases_thm%} automatically proves
and returns a theorem which states that every value the concrete type in
question is denoted by the value returned by some constructor of the type.

\FAILURE
Fails if the argument is not a theorem of the form returned by
{\small\verb%prove_induction_thm%}

\EXAMPLE
Given the following structural induction theorem for labelled binary trees:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !P. (!x. P(LEAF x)) /\ (!b1 b2. P b1 /\ P b2 ==> P(NODE b1 b2)) ==>
          (!b. P b)
\end{verbatim}
}
\noindent {\small\verb%prove_cases_thm%} proves and returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !b. (?x. b = LEAF x) \/ (?b1 b2. b = NODE b1 b2)
\end{verbatim}
}
\noindent This states that every labelled binary tree {\small\verb%b%} is either a leaf node
with a label {\small\verb%x%} or a tree with two subtrees {\small\verb%b1%} and {\small\verb%b2%}.

\SEEALSO
define_type, INDUCT_THEN, new_recursive_definition,
prove_constructors_distinct, prove_constructors_one_one, prove_induction_thm,
prove_rec_fn_exists.

\ENDDOC
\DOC{prove\_constructors\_distinct}

\TYPE {\small\verb%prove_constructors_distinct : (thm -> thm)%}\egroup

\SYNOPSIS
Proves that the constructors of an automatically-defined concrete type yield
distinct values.

\DESCRIBE
{\small\verb%prove_constructors_distinct%} takes as its argument a primitive recursion
theorem, in the form returned by {\small\verb%define_type%} for an automatically-defined
concrete type.  When applied to such a theorem, {\small\verb%prove_constructors_distinct%}
automatically proves and returns a theorem which states that distinct
constructors of the concrete type in question yield distinct values of this
type.

\FAILURE
Fails if the argument is not a theorem of the form returned by {\small\verb%define_type%},
or if the concrete type in question has only one constructor.

\EXAMPLE
Given the following primitive recursion theorem for labelled binary trees:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !f0 f1.
        ?! fn.
        (!x. fn(LEAF x) = f0 x) /\
        (!b1 b2. fn(NODE b1 b2) = f1(fn b1)(fn b2)b1 b2)
\end{verbatim}
}
\noindent {\small\verb%prove_constructors_distinct%} proves and returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x b1 b2. ~(LEAF x = NODE b1 b2)
\end{verbatim}
}
\noindent This states that leaf nodes are different from internal nodes.  When
the concrete type in question has more than two constructors, the resulting
theorem is just conjunction of inequalities of this kind.

\SEEALSO
define_type, INDUCT_THEN, new_recursive_definition, prove_cases_thm,
prove_constructors_one_one, prove_induction_thm, prove_rec_fn_exists.

\ENDDOC
\DOC{prove\_constructors\_one\_one}

\TYPE {\small\verb%prove_constructors_one_one : (thm -> thm)%}\egroup

\SYNOPSIS
Proves that the constructors of an automatically-defined concrete type are
injective.

\DESCRIBE
{\small\verb%prove_constructors_one_one%} takes as its argument a primitive recursion
theorem, in the form returned by {\small\verb%define_type%} for an automatically-defined
concrete type.  When applied to such a theorem, {\small\verb%prove_constructors_one_one%}
automatically proves and returns a theorem which states that the constructors
of the concrete type in question are injective (one-to-one).  The resulting
theorem covers only those constructors that take arguments (i.e. that are not
just constant values).

\FAILURE
Fails if the argument is not a theorem of the form returned by {\small\verb%define_type%},
or if all the constructors of the concrete type in question are simply
constants of that type.

\EXAMPLE
Given the following primitive recursion theorem for labelled binary trees:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !f0 f1.
        ?! fn.
        (!x. fn(LEAF x) = f0 x) /\
        (!b1 b2. fn(NODE b1 b2) = f1(fn b1)(fn b2)b1 b2)
\end{verbatim}
}
\noindent {\small\verb%prove_constructors_one_one%} proves and returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x x'. (LEAF x = LEAF x') = (x = x')) /\
      (!b1 b2 b1' b2'.
        (NODE b1 b2 = NODE b1' b2') = (b1 = b1') /\ (b2 = b2'))
\end{verbatim}
}
\noindent This states that the constructors {\small\verb%LEAF%} and {\small\verb%NODE%} are both
injective.

\SEEALSO
define_type, INDUCT_THEN, new_recursive_definition, prove_cases_thm,
prove_constructors_distinct, prove_induction_thm, prove_rec_fn_exists.

\ENDDOC
\DOC{prove}

\TYPE {\small\verb%prove : ((term # tactic) -> thm)%}\egroup

\SYNOPSIS
Attempts to prove a boolean term using the supplied tactic.

\DESCRIBE
When applied to a term-tactic pair {\small\verb%(tm,tac)%}, the function {\small\verb%prove%} attempts to
prove the goal {\small\verb%?- tm%}, that is, the term {\small\verb%tm%} with no assumptions, using the
tactic {\small\verb%tac%}. If {\small\verb%prove%} succeeds, it returns the corresponding theorem
{\small\verb%A |- tm%}, where the assumption list {\small\verb%A%} may not be empty if the tactic is
invalid; {\small\verb%prove%} has no inbuilt validity-checking.

\FAILURE
Fails if the term is not of type {\small\verb%bool%} (and so cannot possibly be
the conclusion of a theorem), or if the tactic cannot solve the goal.

\COMMENTS
The function {\small\verb%PROVE%} provides almost identical functionality, and will
also list unsolved goals if the tactic fails. It is therefore preferable
for most purposes.

\SEEALSO
PROVE, prove_thm, TAC_PROOF, VALID.

\ENDDOC
\DOC{PROVE}

\TYPE {\small\verb%PROVE : ((term # tactic) -> thm)%}\egroup

\SYNOPSIS
Attempts to prove a boolean term using the supplied tactic.

\DESCRIBE
When applied to a term-tactic pair {\small\verb%(tm,tac)%}, the function {\small\verb%PROVE%} attempts to
prove the goal {\small\verb%?- tm%}, that is, the term {\small\verb%tm%} with no assumptions, using the
tactic {\small\verb%tac%}. If {\small\verb%PROVE%} succeeds, it returns the corresponding theorem
{\small\verb%A |- tm%}, where the assumption list {\small\verb%A%} may not be empty if the tactic is
invalid; {\small\verb%PROVE%} has no inbuilt validity-checking.

\FAILURE
Fails if the term is not of type {\small\verb%bool%} (and so cannot possibly be
the conclusion of a theorem), or if the tactic cannot solve the goal.
In the latter case {\small\verb%PROVE%} will list the unsolved goals to help the user.

\SEEALSO
TAC_PROOF, prove, prove_thm, VALID.

\ENDDOC
\DOC{PROVE\_HYP}

\TYPE {\small\verb%PROVE_HYP : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Eliminates a provable assumption from a theorem.

\DESCRIBE
When applied to two theorems, {\small\verb%PROVE_HYP%} gives a new theorem with the
conclusion of the second and the union of the assumption list minus the
conclusion of the first theorem.
{\par\samepage\setseps\small
\begin{verbatim}
     A1 |- t1     A2 |- t2
   ------------------------  PROVE_HYP
    (A1 u A2) - {t1} |- t2
\end{verbatim}
}
\FAILURE
Never fails.

\COMMENTS
This is the Cut rule. It is not necessary for the conclusion of the first
theorem to be the same as an assumption of the second, but {\small\verb%PROVE_HYP%} is
otherwise of doubtful value.

\SEEALSO
DISCH, MP, UNDISCH.

\ENDDOC
\DOC{prove\_induction\_thm}

\TYPE {\small\verb%prove_induction_thm : (thm -> thm)%}\egroup

\SYNOPSIS
Derives structural induction for an automatically-defined concrete type.

\DESCRIBE
{\small\verb%prove_induction_thm%} takes as its argument a primitive recursion theorem, in
the form returned by {\small\verb%define_type%} for an automatically-defined concrete type.
When applied to such a theorem, {\small\verb%prove_induction_thm%} automatically proves and
returns a theorem that states a structural induction principle for the concrete
type described by the argument theorem. The theorem returned by
{\small\verb%prove_induction_thm%} is in a form suitable for use with the general structural
induction tactic {\small\verb%INDUCT_THEN%}.

\FAILURE
Fails if the argument is not a theorem of the form returned by {\small\verb%define_type%}.

\EXAMPLE
Given the following primitive recursion theorem for labelled binary trees:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !f0 f1.
        ?! fn.
        (!x. fn(LEAF x) = f0 x) /\
        (!b1 b2. fn(NODE b1 b2) = f1(fn b1)(fn b2)b1 b2)
\end{verbatim}
}
\noindent {\small\verb%prove_induction_thm%} proves and returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !P. (!x. P(LEAF x)) /\ (!b1 b2. P b1 /\ P b2 ==> P(NODE b1 b2)) ==>
          (!b. P b)
\end{verbatim}
}
\noindent This theorem states the principle of structural induction on labelled
binary trees: if a predicate {\small\verb%P%} is true of all leaf nodes, and if whenever it
is true of two subtrees {\small\verb%b1%} and {\small\verb%b2%} it is also true of the tree {\small\verb%NODE b1 b2%},
then {\small\verb%P%} is true of all labelled binary trees.

\SEEALSO
define_type, INDUCT_THEN, new_recursive_definition, prove_cases_thm,
prove_constructors_distinct, prove_constructors_one_one, prove_rec_fn_exists.

\ENDDOC
\DOC{prove\_rec\_fn\_exists}

\TYPE {\small\verb%prove_rec_fn_exists : (thm -> term -> thm)%}\egroup

\SYNOPSIS
Proves the existence of a primitive recursive function over a concrete recursive
type.

\DESCRIBE
{\small\verb%prove_rec_fn_exists%} is a version of {\small\verb%new_recursive_definition%} which proves
only that the required function exists; it does not make a constant
specification.  The first argument is a theorem of the form returned by
{\small\verb%define_type%}, and the second is a user-supplied primitive recursive function
definition.  The theorem which is returned asserts the existence of the
recursively-defined function in question (if it is primitive recursive over the
type characterized by the theorem given as the first argument).  See the entry
for {\small\verb%new_recursive_definition%} for details.

\FAILURE
As for {\small\verb%new_recursive_definition%}.

\EXAMPLE
Given the following primitive recursion theorem for labelled binary trees:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !f0 f1.
        ?! fn.
        (!x. fn(LEAF x) = f0 x) /\
        (!b1 b2. fn(NODE b1 b2) = f1(fn b1)(fn b2)b1 b2)
\end{verbatim}
}
\noindent {\small\verb%prove_rec_fn_exists%} can be used to prove the existence of primitive
recursive functions over binary trees.  Suppose the value of {\small\verb%th%} is this
theorem.  Then the existence of a recursive function {\small\verb%Leaves%}, which computes
the number of leaves in a binary tree, can be proved as shown below:
{\par\samepage\setseps\small
\begin{verbatim}
   #prove_rec_fn_exists th
   #  "(Leaves (LEAF (x:*)) = 1) /\
   #   (Leaves (NODE t1 t2) = (Leaves t1) + (Leaves t2))";;
   |- ?Leaves. (!x. Leaves(LEAF x) = 1) /\
               (!t1 t2. Leaves(NODE t1 t2) = (Leaves t1) + (Leaves t2))
\end{verbatim}
}
\noindent The result should be compared with the example given under
{\small\verb%new_recursive_definition%}.

\SEEALSO
define_type, new_recursive_definition.

\ENDDOC
\DOC{prove\_rep\_fn\_one\_one}

\TYPE {\small\verb%prove_rep_fn_one_one : (thm -> thm)%}\egroup

\SYNOPSIS
Proves that a type representation function is one-to-one (injective).

\DESCRIBE
If {\small\verb%th%} is a theorem of the form returned by the function
{\small\verb%define_new_type_bijections%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!a. abs(rep a) = a) /\ (!r. P r = (rep(abs r) = r))
\end{verbatim}
}
\noindent then {\small\verb%prove_rep_fn_one_one th%} proves from this theorem that the
function {\small\verb%rep%} is one-to-one, returning the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !a a'. (rep a = rep a') = (a = a')
\end{verbatim}
}
\FAILURE
Fails if applied to a theorem not of the form shown above.

\SEEALSO
new_type_definition, define_new_type_bijections, prove_abs_fn_one_one,
prove_abs_fn_onto, prove_rep_fn_onto.

\ENDDOC
\DOC{prove\_rep\_fn\_onto}

\TYPE {\small\verb%prove_rep_fn_onto : (thm -> thm)%}\egroup

\SYNOPSIS
Proves that a type representation function is onto (surjective).

\DESCRIBE
If {\small\verb%th%} is a theorem of the form returned by the function
{\small\verb%define_new_type_bijections%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!a. abs(rep a) = a) /\ (!r. P r = (rep(abs r) = r))
\end{verbatim}
}
\noindent then {\small\verb%prove_rep_fn_onto th%} proves from this theorem that the
function {\small\verb%rep%} is onto the set of values that satisfy {\small\verb%P%}, returning the
theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !r. P r = (?a. r = rep a)
\end{verbatim}
}
\FAILURE
Fails if applied to a theorem not of the form shown above.

\SEEALSO
new_type_definition, define_new_type_bijections, prove_abs_fn_one_one,
prove_abs_fn_onto, prove_rep_fn_one_one.

\ENDDOC
\DOC{prove\_thm}

\TYPE {\small\verb%prove_thm : ((string # term # tactic) -> thm)%}\egroup

\SYNOPSIS
Attempts to prove a boolean term using the supplied tactic, then save the
theorem.

\DESCRIBE
When applied to a triple {\small\verb%(s,tm,tac)%}, giving the name to
save the theorem under, the term to prove (with no assumptions) and the tactic
to perform the proof, the function {\small\verb%prove_thm%} attempts to prove the goal
{\small\verb%?- tm%}, that is, the term {\small\verb%tm%} with no assumptions, using the tactic {\small\verb%tac%}. If
{\small\verb%prove_thm%} succeeds, it attempts to save the resulting theorem in the current
theory segment, and if this succeeds, the saved theorem is returned.

\FAILURE
Fails if the term is not of type {\small\verb%bool%} (and so cannot possibly be
the conclusion of a theorem), or if the tactic cannot solve the goal.
In the latter case {\small\verb%prove_thm%} will list the unsolved goals to help the user.
In addition, {\small\verb%prove_thm%} will fail if the theorem cannot be saved, e.g. because
there is already a theorem of that name in the current theory segment, or if
the resulting theorem has assumptions; clearly this can only happen if the
tactic was invalid, so this gives some measure of validity checking.

\SEEALSO
prove, PROVE, TAC_PROOF, VALID.

\ENDDOC
\DOC{PURE\_ASM\_REWRITE\_RULE}

\TYPE {\small\verb%PURE_ASM_REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem including the theorem's assumptions as rewrites.

\DESCRIBE
The list of theorems supplied by the user and the assumptions of the
object theorem are used to generate a set of rewrites, without adding
implicitly the basic tautologies stored under {\small\verb%basic_rewrites%}.
The rule searches for matching subterms in a top-down recursive
fashion, stopping only when no more rewrites apply. For a general
description of rewriting strategies see {\small\verb%GEN_REWRITE_RULE%}.

\FAILURE
Rewriting with {\small\verb%PURE_ASM_REWRITE_RULE%} does not result in failure. It
may diverge, in which case {\small\verb%PURE_ONCE_ASM_REWRITE_RULE%} may be used.

\SEEALSO
ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_REWRITE_RULE,
PURE_REWRITE_RULE, PURE_ONCE_ASM_REWRITE_RULE.

\ENDDOC
\DOC{PURE\_ASM\_REWRITE\_TAC}

\TYPE {\small\verb%PURE_ASM_REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal including the goal's assumptions as rewrites.

\DESCRIBE
{\small\verb%PURE_ASM_REWRITE_TAC%} generates a set of rewrites from the supplied
theorems and the assumptions of the goal, and applies these in a
top-down recursive manner until no match is found. See
{\small\verb%GEN_REWRITE_TAC%} for more information on the group of rewriting
tactics.

\FAILURE
{\small\verb%PURE_ASM_REWRITE_TAC%} does not fail, but it can diverge in certain
situations. For limited depth rewriting, see
{\small\verb%PURE_ONCE_ASM_REWRITE_TAC%}. It can also result in an invalid tactic.

\USES
To advance or solve a goal when the current assumptions are expected
to be useful in reducing the goal.

\SEEALSO
ASM_REWRITE_TAC, GEN_REWRITE_TAC, FILTER_ASM_REWRITE_TAC,
FILTER_ONCE_ASM_REWRITE_TAC, ONCE_ASM_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_ONCE_ASM_REWRITE_TAC, PURE_ONCE_REWRITE_TAC, PURE_REWRITE_TAC,
REWRITE_TAC, SUBST_TAC.

\ENDDOC
\DOC{PURE\_ONCE\_ASM\_REWRITE\_RULE}

\TYPE {\small\verb%PURE_ONCE_ASM_REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem once, including the theorem's assumptions as rewrites.

\DESCRIBE
{\small\verb%PURE_ONCE_ASM_REWRITE_RULE%} excludes the basic tautologies in
{\small\verb%basic_rewrites%} from the theorems used for rewriting. It searches for
matching subterms once only, without recursing over already rewritten
subterms. For a general introduction to rewriting tools see
{\small\verb%GEN_REWRITE_RULE%}.

\FAILURE
{\small\verb%PURE_ONCE_ASM_REWRITE_RULE%} does not fail and does not diverge.

\SEEALSO
ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_ASM_REWRITE_RULE,
ONCE_REWRITE_RULE, PURE_ASM_REWRITE_RULE, PURE_REWRITE_RULE,
REWRITE_RULE.

\ENDDOC
\DOC{PURE\_ONCE\_ASM\_REWRITE\_TAC}

\TYPE {\small\verb%PURE_ONCE_ASM_REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal once, including the goal's assumptions as rewrites.

\DESCRIBE
A set of rewrites generated from the assumptions of the goal and the
supplied theorems is used to rewrite the term part of the goal, making
only one pass over the goal. The basic tautologies are not included as
rewrite theorems. The order in which the given theorems are applied is
an implementation matter and the user should not depend on any
ordering. See {\small\verb%GEN_REWRITE_TAC%} for more information on rewriting
tactics in general.

\FAILURE
{\small\verb%PURE_ONCE_ASM_REWRITE_TAC%} does not fail and does not diverge.

\USES
Manipulation of the goal by rewriting with its assumptions, in
instances where rewriting with tautologies and recursive rewriting is
undesirable.

\SEEALSO
ASM_REWRITE_TAC, GEN_REWRITE_TAC, FILTER_ASM_REWRITE_TAC,
FILTER_ONCE_ASM_REWRITE_TAC, ONCE_ASM_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_ASM_REWRITE_TAC, PURE_ONCE_REWRITE_TAC, PURE_REWRITE_TAC,
REWRITE_TAC, SUBST_TAC.

\ENDDOC
\DOC{PURE\_ONCE\_REWRITE\_CONV}

\TYPE {\small\verb%PURE_ONCE_REWRITE_CONV : (thm list -> conv)%}\egroup

\SYNOPSIS
Rewrites a term once with only the given list of rewrites.

\DESCRIBE
{\small\verb%PURE_ONCE_REWRITE_CONV%} generates rewrites from the list of theorems
supplied by the user, without including the tautologies given in
{\small\verb%basic_rewrites%}. The applicable rewrites are employeded once, without
entailing in a recursive search for matches over the term.
See {\small\verb%GEN_REWRITE_CONV%} for more details about rewriting strategies in
HOL.

\FAILURE
This rule does not fail, and it does not diverge.

\SEEALSO
GEN_REWRITE_CONV, ONCE_DEPTH_CONV,
ONCE_REWRITE_CONV, PURE_REWRITE_CONV, REWRITE_CONV.

\ENDDOC
\DOC{PURE\_ONCE\_REWRITE\_RULE}

\TYPE {\small\verb%PURE_ONCE_REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem once with only the given list of rewrites.

\DESCRIBE
{\small\verb%PURE_ONCE_REWRITE_RULE%} generates rewrites from the list of theorems
supplied by the user, without including the tautologies given in
{\small\verb%basic_rewrites%}. The applicable rewrites are employeded once, without
entailing in a recursive search for matches over the theorem.
See {\small\verb%GEN_REWRITE_RULE%} for more details about rewriting strategies in
HOL.

\FAILURE
This rule does not fail, and it does not diverge.

\SEEALSO
ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_DEPTH_CONV,
ONCE_REWRITE_RULE, PURE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{PURE\_ONCE\_REWRITE\_TAC}

\TYPE {\small\verb%PURE_ONCE_REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal using a supplied list of theorems, making one
rewriting pass over the goal.

\DESCRIBE
{\small\verb%PURE_ONCE_REWRITE_TAC%} generates a set of rewrites from the given
list of theorems, and applies them at every match found through
searching once over the term part of the goal, without recursing. It
does not include the basic tautologies as rewrite theorems. The order
in which the rewrites are applied is unspecified. For more information
on rewriting tactics see {\small\verb%GEN_REWRITE_TAC%}.

\FAILURE
{\small\verb%PURE_ONCE_REWRITE_TAC%} does not fail and does not diverge.

\USES
This tactic is useful when the built-in tautologies are not required
as rewrite equations and recursive rewriting is not desired.

\SEEALSO
ASM_REWRITE_TAC, GEN_REWRITE_TAC, FILTER_ASM_REWRITE_TAC,
FILTER_ONCE_ASM_REWRITE_TAC, ONCE_ASM_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_ASM_REWRITE_TAC, PURE_ONCE_ASM_REWRITE_TAC, PURE_REWRITE_TAC,
REWRITE_TAC, SUBST_TAC.

\ENDDOC
\DOC{PURE\_REWRITE\_CONV}

\TYPE {\small\verb%PURE_REWRITE_CONV : (thm list -> conv)%}\egroup

\SYNOPSIS
Rewrites a term with only the given list of rewrites.

\DESCRIBE
This conversion provides a method for rewriting a term with the theorems given,
and excluding simplification with tautologies in {\small\verb%basic_rewrites%}. Matching
subterms are found recursively, until no more matches are found.
For more details on rewriting see
{\small\verb%GEN_REWRITE_CONV%}.

\USES
{\small\verb%PURE_REWRITE_CONV%} is useful when the simplifications that arise by
rewriting a theorem with {\small\verb%basic_rewrites%} are not wanted.

\FAILURE
Does not fail. May result in divergence, in which case
{\small\verb%PURE_ONCE_REWRITE_CONV%} can be used.

\SEEALSO
GEN_REWRITE_CONV, ONCE_REWRITE_CONV, PURE_ONCE_REWRITE_CONV, REWRITE_CONV.

\ENDDOC
\DOC{PURE\_REWRITE\_RULE}

\TYPE {\small\verb%PURE_REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem with only the given list of rewrites.

\DESCRIBE
This rule provides a method for rewriting a theorem with the theorems given,
and excluding simplification with tautologies in {\small\verb%basic_rewrites%}. Matching
subterms are found recursively starting from the term in the conclusion part of
the theorem, until no more matches are found. For more details on rewriting see
{\small\verb%GEN_REWRITE_RULE%}.

\USES
{\small\verb%PURE_REWRITE_RULE%} is useful when the simplifications that arise by
rewriting a theorem with {\small\verb%basic_rewrites%} are not wanted.

\FAILURE
Does not fail. May result in divergence, in which case
{\small\verb%PURE_ONCE_REWRITE_RULE%} can be used.

\SEEALSO
ASM_REWRITE_RULE, GEN_REWRITE_RULE, ONCE_REWRITE_RULE,
PURE_ASM_REWRITE_RULE, PURE_ONCE_ASM_REWRITE_RULE,
PURE_ONCE_REWRITE_RULE, REWRITE_RULE.

\ENDDOC
\DOC{PURE\_REWRITE\_TAC}

\TYPE {\small\verb%PURE_REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal with only the given list of rewrites.

\DESCRIBE
{\small\verb%PURE_REWRITE_TAC%} behaves in the same way as {\small\verb%REWRITE_TAC%}, but
without the effects of the built-in tautologies.  The order in which
the given theorems are applied is an implementation matter and the user
should not depend on any ordering. For more information on rewriting
strategies see {\small\verb%GEN_REWRITE_TAC%}.

\FAILURE
{\small\verb%PURE_REWRITE_TAC%} does not fail, but it can diverge in certain
situations; in such cases {\small\verb%PURE_ONCE_REWRITE_TAC%} may be used.

\USES
This tactic is useful when the built-in tautologies are not required as
rewrite equations. It is sometimes useful in making more time-efficient
replacements according to equations for which it is clear that no extra
reduction via tautology will be needed. (The difference in efficiency
is only apparent, however, in quite large examples.)

{\small\verb%PURE_REWRITE_TAC%} advances goals but solves them less frequently than
{\small\verb%REWRITE_TAC%}; to be precise, {\small\verb%PURE_REWRITE_TAC%} only solves goals
which are rewritten to {\small\verb%"T"%} (i.e. {\small\verb%TRUTH%}) without recourse to any
other tautologies.

\EXAMPLE
It might be necessary, say for subsequent application of an induction
hypothesis, to resist reducing a term {\small\verb%"b = T"%} to {\small\verb%"b"%}.
{\par\samepage\setseps\small
\begin{verbatim}
  #PURE_REWRITE_TAC[]([],"b = T");;
  ([([], "b = T")], -) : subgoals

  #REWRITE_TAC[]([],"b = T");;
  ([([], "b")], -) : subgoals
\end{verbatim}
}
\SEEALSO
ASM_REWRITE_TAC, FILTER_ASM_REWRITE_TAC, FILTER_ONCE_ASM_REWRITE_TAC,
GEN_REWRITE_TAC, ONCE_ASM_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_ASM_REWRITE_TAC, PURE_ONCE_ASM_REWRITE_TAC,
PURE_ONCE_REWRITE_TAC, REWRITE_TAC, SUBST_TAC.

\ENDDOC
\DOC{push\_fsubgoals}

\TYPE {\small\verb%push_fsubgoals : (subgoals list -> tactic -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{push\_print}

\TYPE {\small\verb%push_print : (subgoals -> subgoals list -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{push\_subgoals}

\TYPE {\small\verb%push_subgoals : (subgoals list -> tactic -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{quit}

\TYPE {\small\verb%quit : (void -> void)%}\egroup

\SYNOPSIS
Evaluating {\small\verb%quit()%} terminates the current HOL session.

\FAILURE
Never fails.

\ENDDOC
\DOC{RAND\_CONV}

\TYPE {\small\verb%RAND_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion to the operand of an application.

\DESCRIBE
If {\small\verb%c%} is a conversion that maps a term {\small\verb%"t2"%} to the theorem {\small\verb%|- t2 = t2'%},
then the conversion {\small\verb%RAND_CONV c%} maps applications of the form {\small\verb%"t1 t2"%} to
theorems of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t1 t2) = (t1 t2')
\end{verbatim}
}
\noindent That is, {\small\verb%RAND_CONV c "t1 t2"%} applies {\small\verb%c%} to the operand of the
application {\small\verb%"t1 t2"%}.

\FAILURE
{\small\verb%RAND_CONV c tm%} fails if {\small\verb%tm%} is not an application or if {\small\verb%tm%} has the form
{\small\verb%"t1 t2"%} but the conversion {\small\verb%c%} fails when applied to the term {\small\verb%t2%}. The
function returned by {\small\verb%RAND_CONV c%} may also fail if the ML function
{\small\verb%c:term->thm%} is not, in fact, a conversion (i.e. a function that maps a term
{\small\verb%t%} to a theorem {\small\verb%|- t = t'%}).

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#RAND_CONV num_CONV "SUC 2";;
|- SUC 2 = SUC(SUC 1)
\end{verbatim}
}
\SEEALSO
ABS_CONV, RATOR_CONV, SUB_CONV.

\ENDDOC
\DOC{rand}

\TYPE {\small\verb%rand : (term -> term)%}\egroup

\SYNOPSIS
Returns the operand from a combination (function application).

\DESCRIBE
{\small\verb%rand "t1 t2"%} returns {\small\verb%"t2"%}.

\FAILURE
Fails with {\small\verb%rand%} if term is not a combination.

\SEEALSO
rator, dest_comb.

\ENDDOC
\DOC{RATOR\_CONV}

\TYPE {\small\verb%RATOR_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion to the operator of an application.

\DESCRIBE
If {\small\verb%c%} is a conversion that maps a term {\small\verb%"t1"%} to the theorem {\small\verb%|- t1 = t1'%},
then the conversion {\small\verb%RATOR_CONV c%} maps applications of the form {\small\verb%"t1 t2"%} to
theorems of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t1 t2) = (t1' t2)
\end{verbatim}
}
\noindent That is, {\small\verb%RATOR_CONV c "t1 t2"%} applies {\small\verb%c%} to the operand of the
application {\small\verb%"t1 t2"%}.

\FAILURE
{\small\verb%RATOR_CONV c tm%} fails if {\small\verb%tm%} is not an application or if {\small\verb%tm%} has the form
{\small\verb%"t1 t2"%} but the conversion {\small\verb%c%} fails when applied to the term {\small\verb%t1%}. The
function returned by {\small\verb%RATOR_CONV c%} may also fail if the ML function
{\small\verb%c:term->thm%} is not, in fact, a conversion (i.e. a function that maps a term
{\small\verb%t%} to a theorem {\small\verb%|- t = t'%}).

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#RATOR_CONV BETA_CONV "(\x y. x + y) 1 2";;
|- (\x y. x + y)1 2 = (\y. 1 + y)2
\end{verbatim}
}
\SEEALSO
ABS_CONV, RAND_CONV, SUB_CONV.

\ENDDOC
\DOC{rator}

\TYPE {\small\verb%rator : (term -> term)%}\egroup

\SYNOPSIS
Returns the operator from a combination (function application).

\DESCRIBE
{\small\verb%rator("t1 t2")%} returns {\small\verb%"t1"%}.

\FAILURE
Fails with {\small\verb%rator%} if term is not a combination.

\SEEALSO
rand, dest_comb.

\ENDDOC
\DOC{r}

\TYPE {\small\verb%r : (int -> void)%}\egroup

\SYNOPSIS
Reorders the subgoals on top of the subgoal package goal stack.

\DESCRIBE
The function {\small\verb%r%} is part of the subgoal package. It  is an abbreviation for
{\small\verb%rotate%}. For a description of the subgoal package, see  {\small\verb%set_goal%}.

\FAILURE
As for {\small\verb%rotate%}.

\USES
Proving subgoals in a different order to that generated by the subgoal package.

\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, p, print_state,
rotate, save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{read}

\TYPE {\small\verb%read : (string -> string)%}\egroup

\SYNOPSIS
Reads a character from a file.

\DESCRIBE
When applied to a string describing a port (a port is the standard ML file
descriptor, normally obtained from a call to {\small\verb%openi%}), the function {\small\verb%read%}
reads in a character from that port, and advances the internal state so that a
subsequent call to {\small\verb%read%} will return the next character. When the end of the
file is reached, the multi-character string `nil` will be returned.

\FAILURE
May fail or hang in system-dependent ways when given an invalid port
descriptor.

\EXAMPLE
The following assumes that HOL is being run under Unix. It will overwrite an
existing file {\small\verb%test-file%} in the current directory. Notice that the actual
string returned by {\small\verb%openi%} may vary on other systems.
{\par\samepage\setseps\small
\begin{verbatim}
   #system `echo "Hi" >test-file`;;
   0 : int

   #let port = openi `test-file`;;
   port = `%test-file` : string

   #read port, read port, read port, read port, read port;;
   (`H`, `i`, `
   `, `nil`, `nil`)
   : (string # string # string # string # string)

   #close port;;
   () : void
\end{verbatim}
}
\SEEALSO
append_openw, close, openi, openw, tty_read, tty_write, write.

\ENDDOC
\DOC{record\_proof}

\TYPE {\small\verb%record_proof : bool -> void%}\egroup


\SYNOPSIS
Enable/disable proof recording.

\DESCRIBE
A proof is a list of inference steps. After the proof recorder is
enabled, every inference performed by the system is recorded and
cumulated in an internal buffer. When a proof is completed, the raw
records can then be processed and output to a disk file.

{\small\verb%record_proof%} is a low level user function for managing the proof
recorder. It takes a single boolean as its argument. If
this is {\small\verb%true%}, it initialises and enables the proof recorder. If it
is {\small\verb%false%}, it disables the proof recorder without clearing the proof
recorded since the last time this function is called with the value
{\small\verb%true%}.

The current state of the proof recorder can interrogated using the
function {\small\verb%is_recording_proof%}. The recorder can be temporarily
disabled and later re-enabled without clearing the internal buffer.

\FAILURE
Never fail.

\EXAMPLE
Below is an example showing how to record an extremely simple proof:
{\par\samepage\setseps\small
\begin{verbatim}
#let th = SPEC_ALL ADD_SYM;;
Theorem ADD_SYM autoloading from theory `arithmetic` ...
ADD_SYM = |- !m n. m + n = n + m

th = |- m + n = n + m

#let v = genvar ":num";;
"GEN%VAR%536" : term

#record_proof true;;
() : void

#let th1 = (REFL "SUC(m + n)");;
th1 = |- SUC(m + n) = SUC(m + n)

#let th2 = SUBST [th,v] "SUC(m + n) = SUC ^v" th1;;
th2 = |- SUC(m + n) = SUC(n + m)

#record_proof false;;
() : void

#write_proof_to `ap_term.prf` `ap_term` [] (get_steps());;
() : void
\end{verbatim}
}
The proof consists of two inference steps: the application of the two
primitive inference rules {\small\verb%REFL%} and {\small\verb%SUBST%}. The function
{\small\verb%write_proof_to%} outputs the proof into a file names {\small\verb%ap_term.prf%}.

\COMMENTS
This function is used to implement higher level user functions for
recording proof in the library {\small\verb%record_proof%}. It is much more
convenient to use those functions than the low level functions
such as {\small\verb%record_proof%} directly.

\SEEALSO
is_recording_proof, RecordStep, get_steps,
suspend_recording, resume_recording,
current_proof, current_proof_file,
new_proof_file, close_proof_file, begin_proof, end_proof,
TAC_PROOF, PROVE, prove, prove_thm.

\ENDDOC
\DOC{RecordStep}

\TYPE {\small\verb%RecordStep : step -> void%}\egroup


\SYNOPSIS
Record a single inference step.

\DESCRIBE
A proof is a list of inference steps. After the proof recorder is
enabled, every inference performed by the system is recorded and
cumulated in an internal buffer. When a proof is completed, the raw
records can then be processed and output to a disk file.

{\small\verb%record_proof%} is a system function for recording a single proof step.
The type {\small\verb%step%} represents a basic inference step. It contains all
the necessary information of each inference. There are currently 52
basic inferences which are being recorded. All other ML functions
representing inference rules are implemented by these basic
inferences.
If the proof recorder is enabled when an inference is performed, 
{\small\verb%RecordStep%} will add a step into the internal buffer. 

\FAILURE
Never fail.

\COMMENTS
This is a system function implementing the proof recorded. Users
should not use this function directly. User functions are provided in
the library {\small\verb%record_proof%}.  When new basic inference rule
is implemented, this function should be called to record the inference step.

\SEEALSO
record_proof, is_recording_proof, get_steps,
suspend_recording, resume_recording.

\ENDDOC
\DOC{REDEPTH\_CONV}

\TYPE {\small\verb%REDEPTH_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion bottom-up to all subterms, retraversing changed ones.

\DESCRIBE
{\small\verb%REDEPTH_CONV c tm%} applies the conversion {\small\verb%c%} repeatedly to all subterms of
the term {\small\verb%tm%} and recursively applies {\small\verb%REDEPTH_CONV c%} to each subterm at which
{\small\verb%c%} succeeds, until there is no subterm remaining for which application of {\small\verb%c%}
succeeds.

More precisely, {\small\verb%REDEPTH_CONV c tm%} repeatedly applies the conversion {\small\verb%c%} to
all the subterms of the term {\small\verb%tm%}, including the term {\small\verb%tm%} itself. The supplied
conversion {\small\verb%c%} is applied to the subterms of {\small\verb%tm%} in bottom-up order and is
applied repeatedly (zero or more times, as is done by {\small\verb%REPEATC%}) to each
subterm until it fails.  If {\small\verb%c%} is successfully applied at least once to a
subterm, {\small\verb%t%} say, then the term into which {\small\verb%t%} is transformed is retraversed by
applying {\small\verb%REDEPTH_CONV c%} to it.

\FAILURE
{\small\verb%REDEPTH_CONV c tm%} never fails but can diverge if the conversion {\small\verb%c%} can be
applied repeatedly to some subterm of {\small\verb%tm%} without failing.

\EXAMPLE
The following example shows how {\small\verb%REDEPTH_CONV%} retraverses subterms:
{\par\samepage\setseps\small
\begin{verbatim}
   #REDEPTH_CONV BETA_CONV "(\f x. (f x) + 1) (\y.y) 2";;
   |- (\f x. (f x) + 1)(\y. y)2 = 2 + 1
\end{verbatim}
}
\noindent Here, {\small\verb%BETA_CONV%} is first applied successfully to the (beta-redex)
subterm:
{\par\samepage\setseps\small
\begin{verbatim}
   "(\f x. (f x) + 1) (\y.y)"
\end{verbatim}
}
\noindent This application reduces this subterm to:
{\par\samepage\setseps\small
\begin{verbatim}
   "(\x. ((\y.y) x) + 1)"
\end{verbatim}
}
\noindent {\small\verb%REDEPTH_CONV BETA_CONV%} is then recursively applied to this
transformed subterm, eventually reducing it to {\small\verb%"(\x. x + 1)"%}. Finally, a
beta-reduction of the top-level term, now the simplified beta-redex
{\small\verb%"(\x. x + 1) 2"%}, produces {\small\verb%"2 + 1"%}.

\COMMENTS
The implementation of this function uses failure to avoid rebuilding
unchanged subterms. That is to say, during execution the failure string
{\small\verb%`QCONV`%} may be generated and later trapped. The behaviour of the function
is dependent on this use of failure. So, if the conversion given as argument
happens to generate a failure with string {\small\verb%`QCONV`%}, the operation of
{\small\verb%REDEPTH_CONV%} will be unpredictable.

\SEEALSO
DEPTH_CONV, ONCE_DEPTH_CONV, TOP_DEPTH_CONV.

\ENDDOC
\DOC{REFL}

\TYPE {\small\verb%REFL : conv%}\egroup

\SYNOPSIS
Returns theorem expressing reflexivity of equality.

\DESCRIBE
{\small\verb%REFL%} maps any term {\small\verb%"t"%} to the corresponding theorem {\small\verb%|- t = t%}.

\FAILURE
Never fails.

\SEEALSO
ALL_CONV, REFL_TAC.

\ENDDOC
\DOC{REFL\_TAC}

\TYPE {\small\verb%REFL_TAC : tactic%}\egroup

\SYNOPSIS
Solves a goal which is an equation between alpha-equivalent terms.

\DESCRIBE
When applied to a goal {\small\verb%A ?- t = t'%}, where {\small\verb%t%} and {\small\verb%t'%} are alpha-equivalent,
{\small\verb%REFL_TAC%} completely solves it.
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t = t'
   =============  REFL_TAC

\end{verbatim}
}
\FAILURE
Fails unless the goal is an equation between alpha-equivalent terms.

\SEEALSO
ACCEPT_TAC, MATCH_ACCEPT_TAC, REWRITE_TAC.

\ENDDOC
\DOC{remove}

\TYPE {\small\verb%remove : ((* -> bool) -> * list -> (* # * list))%}\egroup

\SYNOPSIS
Separates the first element of a list to satisfy a predicate from the rest of
the list.

\FAILURE
Fails with {\small\verb%hd%} if no element satisfes the predicate. This will always be the
case for an empty list.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#remove (\x. x = 3) [1;2;3;4;5;6];;
(3, [1; 2; 4; 5; 6]) : (int # int list)
\end{verbatim}
}
\SEEALSO
partition, filter.

\ENDDOC
\DOC{remove\_sticky\_type}

\TYPE {\small\verb%remove_sticky_type : (string -> type)%}\egroup

\SYNOPSIS
Removes a sticky type from a given variable.

\DESCRIBE
A call {\small\verb%remove_sticky_type name%} will remove any sticky type from {\small\verb%name%},
whether this was inferred automatically as a result of the setting of the
{\small\verb%sticky%} flag, or given explicitly by the {\small\verb%set_sticky_type%} function. It
returns the sticky type which was associated with that name. For more
details of the sticky type mechanism, refer to the DESCRIPTION.

\FAILURE
Fails if the name was not associated with a sticky type.

\SEEALSO
set_sticky_type, sticky_list.

\ENDDOC
\DOC{REPEATC}

\TYPE {\small\verb%REPEATC : (conv -> conv)%}\egroup

\SYNOPSIS
Repeatedly apply a conversion (zero or more times) until it fails.

\DESCRIBE
If {\small\verb%c%} is a conversion effects a transformation of a term {\small\verb%t%} to a term {\small\verb%t'%},
that is if {\small\verb%c%} maps {\small\verb%t%} to the theorem {\small\verb%|- t = t`%}, then {\small\verb%REPEATC c%} is the
conversion that repeats this transformation as often as possible.  More
exactly, if {\small\verb%c%} maps the term {\small\verb%"ti"%} to {\small\verb%|- ti=t(i+1)%} for {\small\verb%i%} from {\small\verb%1%} to {\small\verb%n%},
but fails when applied to the {\small\verb%n+1%}th term {\small\verb%"t(n+1)"%}, then {\small\verb%REPEATC c "t1"%}
returns {\small\verb%|- t1 = t(n+1)%}. And if {\small\verb%c "t"%} fails, them {\small\verb%REPEATC c "t"%} returns
{\small\verb%|- t = t%}.

\FAILURE
Never fails, but can diverge if the supplied conversion never fails.

\ENDDOC
\DOC{REPEAT}

\TYPE {\small\verb%REPEAT : (tactic -> tactic)%}\egroup

\SYNOPSIS
Repeatedly applies a tactic until it fails.

\DESCRIBE
The tactic {\small\verb%REPEAT T%} is a tactic which applies {\small\verb%T%} to a goal, and while it
succeeds, continues applying it to all subgoals generated.

\FAILURE
The application of {\small\verb%REPEAT%} to a tactic never fails, and neither does the
composite tactic, even if the basic tactic fails immediately.

\SEEALSO
EVERY, FIRST, ORELSE, THEN, THENL.

\ENDDOC
\DOC{REPEAT\_GTCL}

\TYPE {\small\verb%REPEAT_GTCL : (thm_tactical -> thm_tactical)%}\egroup

\SYNOPSIS
Applies a theorem-tactical until it fails when applied to a goal.

\DESCRIBE
When applied to a theorem-tactical, a theorem-tactic, a theorem and a goal:
{\par\samepage\setseps\small
\begin{verbatim}
   REPEAT_GTCL ttl ttac th goal
\end{verbatim}
}
\noindent {\small\verb%REPEAT_GTCL%} repeatedly modifies the theorem according to
{\small\verb%ttl%} till the result of handing it to {\small\verb%ttac%} and applying it to the goal
fails (this may be no times at all).

\FAILURE
Fails iff the theorem-tactic fails immediately when applied to the theorem
and the goal.

\EXAMPLE
The following tactic matches {\small\verb%th%}'s antecedents against the assumptions
of the goal until it can do so no longer, then puts the resolvents
onto the assumption list:
{\par\samepage\setseps\small
\begin{verbatim}
   REPEAT_GTCL (IMP_RES_THEN ASSUME_TAC) th
\end{verbatim}
}
\SEEALSO
REPEAT_TCL, THEN_TCL.

\ENDDOC
\DOC{REPEAT\_TCL}

\TYPE {\small\verb%REPEAT_TCL : (thm_tactical -> thm_tactical)%}\egroup

\SYNOPSIS
Repeatedly applies a theorem-tactical until it fails when applied to the
theorem.

\DESCRIBE
When applied to a theorem-tactical, a theorem-tactic and a theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   REPEAT_TCL ttl ttac th
\end{verbatim}
}
\noindent {\small\verb%REPEAT_TCL%} repeatedly modifies the theorem according to {\small\verb%ttl%}
until it fails when given to the theorem-tactic {\small\verb%ttac%}.

\FAILURE
Fails iff the theorem-tactic fails immediately when applied to the theorem.

\EXAMPLE
It is often desirable to repeat the action of basic theorem-tactics. For
example {\small\verb%CHOOSE_THEN%} strips off a single existential quantification, so one
might use {\small\verb%REPEAT_TCL CHOOSE_THEN%} to get rid of them all.

Alternatively, one might want to repeatedly break apart a theorem which is a
nested conjunction and apply the same theorem-tactic to each conjunct. For
example the following goal:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- ((0 = w) /\ (0 = x)) /\ (0 = y) /\ (0 = z) ==> (w + x + y + z = 0)
\end{verbatim}
}
\noindent might be solved by
{\par\samepage\setseps\small
\begin{verbatim}
   DISCH_THEN (REPEAT_TCL CONJUNCTS_THEN (SUBST1_TAC o SYM)) THEN
   REWRITE_TAC[ADD_CLAUSES]
\end{verbatim}
}
\SEEALSO
REPEAT_GTCL, THEN_TCL.

\ENDDOC
\DOC{rep\_goals}

\TYPE {\small\verb%rep_goals : (goalstack -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{replicate}

\TYPE {\small\verb%replicate : (* -> int -> * list)%}\egroup

\SYNOPSIS
Makes a list consisting of a value replicated a specified number of times.

\DESCRIBE
{\small\verb%replicate x n%} returns {\small\verb%[x;...;x]%}, a list of length {\small\verb%n%}.

\FAILURE
Fails if number of replications is less than zero.

\ENDDOC
\DOC{RES\_CANON}

\TYPE {\small\verb%RES_CANON : (thm -> thm list)%}\egroup

\SYNOPSIS
Put an implication into canonical form for resolution.

\DESCRIBE
All the HOL resolution tactics (e.g. {\small\verb%IMP_RES_TAC%}) work by using modus ponens
to draw consequences from an implicative theorem and the assumptions of the
goal.  Some of these tactics derive this implication from a theorem supplied
explicitly the user (or otherwise from `outside' the goal) and some obtain it
from the assumptions of the goal itself.  But in either case, the supplied
theorem or assumption is first transformed into a list of implications in
`canonical' form by the function {\small\verb%RES_CANON%}.

The theorem argument to {\small\verb%RES_CANON%} should be either be an implication (which
can be universally quantified) or a theorem from which an implication can be
derived using the transformation rules discussed below.  Given such a theorem,
{\small\verb%RES_CANON%} returns a list of implications in canonical form.  It is the
implications in this resulting list that are used by the various resolution
tactics to infer consequences from the assumptions of a goal.

The transformations done by {\small\verb%RES_CANON th%} to the theorem {\small\verb%th%} are as follows.
First, if {\small\verb%th%} is a negation {\small\verb%A |- ~t%}, this is converted to the implication
{\small\verb%A |- t ==> F%}.  The following inference rules are then applied
repeatedly, until no further rule applies. Conjunctions are split into their
components and equivalence (boolean equality) is split into implication in
both directions:
{\par\samepage\setseps\small
\begin{verbatim}
      A |- t1 /\ t2                         A |- t1 = t2
   --------------------           ----------------------------------
    A |- t1    A |- t2             A |- t1 ==> t2    A |- t2 ==> t1
\end{verbatim}
}
\noindent Conjunctive antecedents are transformed by:
{\par\samepage\setseps\small
\begin{verbatim}
                A |- (t1 /\ t2) ==> t
   ---------------------------------------------------
    A |- t1 ==> (t2 ==> t)     A |- t2 ==> (t1 ==> t)
\end{verbatim}
}
\noindent and disjunctive antecedents by:
{\par\samepage\setseps\small
\begin{verbatim}
        A |- (t1 \/ t2) ==> t
   --------------------------------
    A |- t1 ==> t    A |- t2 ==> t
\end{verbatim}
}
\noindent The scope of universal quantifiers is restricted, if possible:
{\par\samepage\setseps\small
\begin{verbatim}
    A |- !x. t1 ==> t2
   --------------------         [if x is not free in t1]
    A |- t1 ==> !x. t2
\end{verbatim}
}
\noindent and existentially-quantified antecedents are eliminated by:
{\par\samepage\setseps\small
\begin{verbatim}
      A |- (?x. t1) ==> t2
   ---------------------------  [x' chosen so as not to be free in t2]
    A |- !x'. t1[x'/x] ==> t2
\end{verbatim}
}
\noindent Finally, when no further applications of the above rules are
possible, and the theorem is an implication:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- !x1...xn. t1 ==> t2
\end{verbatim}
}
\noindent then the theorem {\small\verb%A u {t1} |- t2%} is transformed by a recursive
application of {\small\verb%RES_CANON%} to get a list of theorems:
{\par\samepage\setseps\small
\begin{verbatim}
   [A u {t1} |- t21 ; ... ; A u {t1} |- t2n]
\end{verbatim}
}
\noindent and the result of discharging {\small\verb%t1%} from these theorems:
{\par\samepage\setseps\small
\begin{verbatim}
   [A |- !x1...xn. t1 ==> t21 ; ... ; A |- !x1...xn. t1 ==> t2n]
\end{verbatim}
}
\noindent is returned. That is, the transformation rules are recursively
applied to the conclusions of all implications.

\FAILURE
{\small\verb%RES_CANON th%} fails if no implication(s) can be derived from {\small\verb%th%} using the
transformation rules shown above.

\EXAMPLE
The uniqueness of the remainder {\small\verb%k MOD n%} is expressed in HOL by the built-in
theorem {\small\verb%MOD_UNIQUE%}:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !n k r. (?q. (k = (q * n) + r) /\ r < n) ==> (k MOD n = r)
\end{verbatim}
}
\noindent For this theorem, the canonical list of implications returned by
{\small\verb%RES_CANON%} is as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #RES_CANON MOD_UNIQUE;;
   [|- !k q n r. (k = (q * n) + r) ==> r < n ==> (k MOD n = r);
    |- !r n. r < n ==> (!k q. (k = (q * n) + r) ==> (k MOD n = r))]
   : thm list
\end{verbatim}
}
\noindent The existentially-quantified, conjunctive, antecedent has given rise
to two implications, and the scope of universal quantifiers has been restricted
to the conclusions of the resulting implications wherever possible.

\USES
The primary use of {\small\verb%RES_CANON%} is for the (internal) pre-processing phase of
the built-in resolution tactics {\small\verb%IMP_RES_TAC%}, {\small\verb%IMP_RES_THEN%}, {\small\verb%RES_TAC%}, and
{\small\verb%RES_THEN%}.  But the function {\small\verb%RES_CANON%} is also made available at top-level
so that users can call it to see the actual form of the implications used for
resolution in any particular case.

\SEEALSO
IMP_RES_TAC, IMP_RES_THEN, RES_TAC, RES_THEN.

\ENDDOC
\DOC{RES\_TAC}

\TYPE {\small\verb%RES_TAC : tactic%}\egroup

\SYNOPSIS
Enriches assumptions by repeatedly resolving them against each other.

\DESCRIBE
{\small\verb%RES_TAC%} searches for pairs of assumed assumptions of a goal (that is, for a
candidate implication and a candidate antecedent, respectively) which can be
`resolved' to yield new results. The conclusions of all the new results are
returned as additional assumptions of the subgoal(s).  The effect of {\small\verb%RES_TAC%}
on a goal is to enrich the assumptions set with some of its collective
consequences.

When applied to a goal {\small\verb%A ?- g%}, the tactic {\small\verb%RES_TAC%} uses {\small\verb%RES_CANON%} to
obtain a set of implicative theorems in canonical form from the assumptions {\small\verb%A%}
of the goal. Each of the resulting theorems (if there are any) will have the
form:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- u1 ==> u2 ==> ... ==> un ==> v
\end{verbatim}
}
\noindent {\small\verb%RES_TAC%} then tries to repeatedly `resolve' these theorems
against the assumptions of a goal by attempting to match the antecedents {\small\verb%u1%},
{\small\verb%u2%}, ..., {\small\verb%un%} (in that order) to some assumption of the goal (i.e. to some
candidate antecedents among the assumptions).  If all the antecedents can be
matched to assumptions of the goal, then an instance of the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   A u {a1,...,an} |- v
\end{verbatim}
}
\noindent called a `final resolvent' is obtained by repeated specialization of
the variables in the implicative theorem, type instantiation, and applications
of modus ponens.  If only the first {\small\verb%i%} antecedents {\small\verb%u1%}, ..., {\small\verb%ui%} can be
matched to assumptions and then no further matching is possible, then the final
resolvent is an instance of the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   A u {a1,...,ai} |- u(i+1) ==> ... ==> v
\end{verbatim}
}
\noindent All the final resolvents obtained in this way (there may be several,
since an antecedent {\small\verb%ui%} may match several assumptions) are added to the
assumptions of the goal, in the stripped form produced by using
{\small\verb%STRIP_ASSUME_TAC%}.  If the conclusion of any final resolvent is a
contradiction `{\small\verb%F%}' or is alpha-equivalent to the conclusion of the goal, then
{\small\verb%RES_TAC%} solves the goal.

\FAILURE
{\small\verb%RES_TAC%} cannot fail and so should not be unconditionally {\small\verb%REPEAT%}ed. However,
since the final resolvents added to the original assumptions are never used as
`candidate antecedents' it is sometimes necessary to apply {\small\verb%RES_TAC%} more than
once to derive the desired result.

\SEEALSO
IMP_RES_TAC, IMP_RES_THEN, RES_CANON, RES_THEN.

\ENDDOC
\DOC{RES\_THEN}

\TYPE {\small\verb%RES_THEN : (thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Resolves all implicative assumptions against the rest.

\DESCRIBE
Like the basic resolution function {\small\verb%IMP_RES_THEN%}, the resolution tactic
{\small\verb%RES_THEN%} performs a single-step resolution of an implication and the
assumptions of a goal. {\small\verb%RES_THEN%} differs from {\small\verb%IMP_RES_THEN%} only in that the
implications used for resolution are taken from the assumptions of the goal
itself, rather than supplied as an argument.

When applied to a goal {\small\verb%A ?- g%}, the tactic {\small\verb%RES_THEN ttac%} uses {\small\verb%RES_CANON%} to
obtain a set of implicative theorems in canonical form from the assumptions {\small\verb%A%}
of the goal. Each of the resulting theorems (if there are any) will have the
form:
{\par\samepage\setseps\small
\begin{verbatim}
   ai |- !x1...xn. ui ==> vi
\end{verbatim}
}
\noindent where {\small\verb%ai%} is one of the assumptions of the goal. Having obtained
these implications, {\small\verb%RES_THEN%} then attempts to match each antecedent {\small\verb%ui%} to
each assumption {\small\verb%aj |- aj%} in the assumptions {\small\verb%A%}.  If the antecedent {\small\verb%ui%} of
any implication matches the conclusion {\small\verb%aj%} of any assumption, then an instance
of the theorem {\small\verb%ai, aj |- vi%}, called a `resolvent', is obtained by
specialization of the variables {\small\verb%x1%}, ..., {\small\verb%xn%} and type instantiation,
followed by an application of modus ponens.  There may be more than one
canonical implication derivable from the assumptions of the goal and each
such implication is tried against every assumption, so there may be several
resolvents (or, indeed, none).

Tactics are produced using the theorem-tactic {\small\verb%ttac%} from all these resolvents
(failures of {\small\verb%ttac%} at this stage are filtered out) and these tactics are then
applied in an unspecified sequence to the goal.  That is,
{\par\samepage\setseps\small
\begin{verbatim}
   RES_THEN ttac (A ?- g)
\end{verbatim}
}
\noindent has the effect of:
{\par\samepage\setseps\small
\begin{verbatim}
   MAP_EVERY (mapfilter ttac [... ; (ai,aj |- vi) ; ...]) (A ?- g)
\end{verbatim}
}
\noindent where the theorems {\small\verb%ai,aj |- vi%} are all the consequences that can be
drawn by a (single) matching modus-ponens inference from the assumptions {\small\verb%A%}
and the implications derived using {\small\verb%RES_CANON%} from the assumptions.  The
sequence in which the theorems {\small\verb%ai,aj |- vi%} are generated and the
corresponding tactics applied is unspecified.

\FAILURE
Evaluating {\small\verb%RES_THEN ttac th%} fails with `{\small\verb%no implication%}' if no
implication(s) can be derived from the assumptions of the goal by the
transformation process described under the entry for {\small\verb%RES_CANON%}.  Evaluating
{\small\verb%RES_THEN ttac (A ?- g)%} fails with `{\small\verb%no resolvents%}' if no assumption of the
goal {\small\verb%A ?- g%} can be resolved with the derived implication or implications.
Evaluation also fails, with `{\small\verb%no tactics%}', if there are resolvents, but for
every resolvent {\small\verb%ai,aj |- vi%} evaluating the application {\small\verb%ttac (ai,aj |- vi)%}
fails---that is, if for every resolvent {\small\verb%ttac%} fails to produce a tactic.
Finally, failure is propagated if any of the tactics that are produced from the
resolvents by {\small\verb%ttac%} fails when applied in sequence to the goal.

\SEEALSO
IMP_RES_TAC, IMP_RES_THEN, MATCH_MP, RES_CANON, RES_TAC.

\ENDDOC
\DOC{resume\_recording}

\TYPE {\small\verb%resume_recording : void -> void%}\egroup


\SYNOPSIS
Suspend proof recording temporarily.

\DESCRIBE
A proof is a list of inference steps. After the proof recorder is
enabled, every inference performed by the system is recorded and
cumulated in an internal buffer. When a proof is completed, the raw
records can then be processed and output to a disk file.

{\small\verb%resume_recording%} is a low level user function for managing the proof
recorder. It resumes the proof recorder without clearing the internal
inference step buffer.  The proof recorder should be in the suspended state.
Otherwise, this function does nothing.

The current state of the proof recorder can interrogated using the
function {\small\verb%is_recording_proof%}. A value of {\small\verb%false%} indicates the proof
recorder is disabled.

\FAILURE
Never fail.

\COMMENTS
This function is used to implement higher level user functions for
recording proof in the library {\small\verb%record_proof%}. It is much more
convenient to use those functions than the low level functions
such as {\small\verb%resume_recording%} directly.

\SEEALSO
record_proof, is_recording_proof, RecordStep, get_steps, suspend_recording,
current_proof, current_proof_file,
new_proof_file, close_proof_file, begin_proof, end_proof,
TAC_PROOF, PROVE, prove, prove_thm.

\ENDDOC
\DOC{rev\_assoc}

\TYPE {\small\verb%rev_assoc : (* -> (** # *) list -> (** # *))%}\egroup

\SYNOPSIS
Searches a list of pairs for a pair whose second component equals a specified
value.

\DESCRIBE
{\small\verb%rev_assoc y [(x1,y1);...;(xn,yn)]%} returns the first {\small\verb%(xi,yi)%} in the list
such that {\small\verb%yi%} equals {\small\verb%y%}.

\FAILURE
Fails if no matching pair is found. This will always be the case if the list
is empty.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#rev_assoc 2 [(1,4);(3,2);(2,5);(2,6)];;
(3, 2) : (int # int)
\end{verbatim}
}
\SEEALSO
assoc, find, mem, tryfind, exists, forall.

\ENDDOC
\DOC{rev}

\TYPE {\small\verb%rev : (* list -> * list)%}\egroup

\SYNOPSIS
Reverses a list.

\DESCRIBE
{\small\verb%rev [x1;...;xn]%} returns {\small\verb%[xn;...;x1]%}.

\FAILURE
Never fails.

\ENDDOC
\DOC{REVERSE\_CONV}

\TYPE {\small\verb%REVERSE_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of reversing a list.

\DESCRIBE
{\small\verb%REVERSE_CONV%} a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   REVERSE [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- REVERSE [x0;...xn] = [xn;...x0]
\end{verbatim}
}
\noindent where the right-hand side is the list in the reverse order.

\FAILURE
{\small\verb%REVERSE_CONV tm%} fails if {\small\verb%tm%} is not of the form described above.

\EXAMPLE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   REVERSE_CONV "REVERSE [0;1;2;3;4]";;
\end{verbatim}
}
\noindent returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- REVERSE [0;1;2;3;4] = [4;3;2;1;0]
\end{verbatim}
}

\SEEALSO
FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{rev\_itlist}

\TYPE {\small\verb%rev_itlist : ((* -> ** -> **) -> * list -> ** -> **)%}\egroup

\SYNOPSIS
Applies a binary function between adjacent elements of the reverse of a list.

\DESCRIBE
{\small\verb%rev_itlist f [x1;...;xn] y%} returns {\small\verb%f xn ( ... (f x2 (f x1 y))...)%}.
It returns {\small\verb%y%} if the list is empty.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#rev_itlist (\x y. x * y) [1;2;3;4] 1;;
24 : int
\end{verbatim}
}
\SEEALSO
itlist, end_itlist.

\ENDDOC
\DOC{REW\_DEPTH\_CONV}

\TYPE {\small\verb%REW_DEPTH_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion top-down to all subterms, retraversing changed ones.
For use in rewriting.

\DESCRIBE
{\small\verb%REW_DEPTH_CONV c tm%} repeatedly applies the conversion {\small\verb%c%} to all the subterms
of the term {\small\verb%tm%}, including the term {\small\verb%tm%} itself. The supplied conversion {\small\verb%c%}
is applied to the subterms of {\small\verb%tm%} in top-down order and is applied repeatedly
(zero or more times, as is done by {\small\verb%REPEATC%}) at each subterm until it fails.
If a subterm {\small\verb%t%} is changed (up to alpha-equivalence) by virtue of the
application of {\small\verb%c%} to its own subterms, then the term into which {\small\verb%t%} is
transformed is retraversed by applying {\small\verb%REW_DEPTH_CONV c%} to it.

{\small\verb%REW_DEPTH_CONV%} is a special version of {\small\verb%TOP_DEPTH_CONV%} for use by the
rewriting conversions, rules and tactics. It differs from {\small\verb%TOP_DEPTH_CONV%} as
follows: If converting an abstraction fails due to the presence of the bound
variable in the hypotheses of the theorem generated by converting the body,
{\small\verb%REW_DEPTH_CONV%} retries the conversion having renamed the bound variable of
the abstraction. If successful the renaming is reversed.

\FAILURE
{\small\verb%REW_DEPTH_CONV c tm%} never fails but can diverge.

\EXAMPLE
The following example illustrates the difference between the functions
{\small\verb%REW_DEPTH_CONV%} and {\small\verb%TOP_DEPTH_CONV%}. It is not intended to illustrate the
full range of behaviour of the former. Both {\small\verb%REW_DEPTH_CONV%} and
{\small\verb%TOP_DEPTH_CONV%} successfully apply the theorem {\small\verb%ADD_0%} inside an abstraction:
{\par\samepage\setseps\small
\begin{verbatim}
   #REW_DEPTH_CONV (REWR_CONV ADD_0) "\n. n + 0";;
   |- (\n. n + 0) = (\n. n)

   #TOP_DEPTH_CONV (REWR_CONV ADD_0) "\n. n + 0";;
   |- (\n. n + 0) = (\n. n)
\end{verbatim}
}
\noindent However, if a hypothesis containing a free occurrence of the bound
variable is added to the rewrite rule, it interferes with the operation of
{\small\verb%TOP_DEPTH_CONV%} but not that of {\small\verb%REW_DEPTH_CONV%}:
{\par\samepage\setseps\small
\begin{verbatim}
   #let th = ADD_ASSUM "n = 0" ADD_0;;
   th = n = 0 |- !m. m + 0 = m

   #REW_DEPTH_CONV (REWR_CONV th) "\n. n + 0";;
   n = 0 |- (\n. n + 0) = (\n. n)

   #TOP_DEPTH_CONV (REWR_CONV th) "\n. n + 0";;
   |- (\n. n + 0) = (\n. n + 0)
\end{verbatim}
}
\COMMENTS
The implementation of this function uses failure to avoid rebuilding
unchanged subterms. That is to say, during execution the failure string
{\small\verb%`QCONV`%} may be generated and later trapped. The behaviour of the function
is dependent on this use of failure. So, if the conversion given as argument
happens to generate a failure with string {\small\verb%`QCONV`%}, the operation of
{\small\verb%REW_DEPTH_CONV%} will be unpredictable.

\SEEALSO
ONCE_REW_DEPTH_CONV, TOP_DEPTH_CONV.

\ENDDOC
\DOC{REWR\_CONV}

\TYPE {\small\verb%REWR_CONV : (thm -> conv)%}\egroup

\SYNOPSIS
Uses an instance of a given equation to rewrite a term.

\DESCRIBE
{\small\verb%REWR_CONV%} is one of the basic building blocks for the implementation of
rewriting in the HOL system. In particular, the term replacement or rewriting
done by all the built-in rewriting rules and tactics is ultimately done by
applications of {\small\verb%REWR_CONV%} to appropriate subterms.  The description given
here for {\small\verb%REWR_CONV%} may therefore be taken as a specification of the atomic
action of replacing equals by equals that is used in all these higher level
rewriting tools.

The first argument to {\small\verb%REWR_CONV%} is expected to be an equational theorem
which is to be used as a left-to-right rewrite rule.  The general form of this
theorem is:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- t[x1,...,xn] = u[x1,...,xn]
\end{verbatim}
}
\noindent where {\small\verb%x1%}, ..., {\small\verb%xn%} are all the variables that occur free in the
left-hand side of the conclusion of the theorem but do not occur free in the
assumptions. Any of these variables may also be universally quantified at the
outermost level of the equation, as for example in:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- !x1...xn. t[x1,...,xn] = u[x1,...,xn]
\end{verbatim}
}
\noindent Note that {\small\verb%REWR_CONV%} will also work, but will give a generally
undesirable result (see below), if the right-hand side of the equation contains
free variables that do not also occur free on the left-hand side, as for
example in:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- t[x1,...,xn] = u[x1,...,xn,y1,...,ym]
\end{verbatim}
}
\noindent where the variables {\small\verb%y1%}, ..., {\small\verb%ym%} do not occur free in
{\small\verb%t[x1,...,xn]%}.

If {\small\verb%th%} is an equational theorem of the kind shown above, then
{\small\verb%REWR_CONV th%} returns a conversion that maps terms of the form
{\small\verb%t[e1,...,en/x1,...,xn]%}, in which the terms {\small\verb%e1%}, ..., {\small\verb%en%} are free for
{\small\verb%x1%}, ..., {\small\verb%xn%} in {\small\verb%t%}, to theorems of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- t[e1,...,en/x1,...,xn] = u[e1,...,en/x1,...,xn]
\end{verbatim}
}
\noindent That is, {\small\verb%REWR_CONV th tm%} attempts to match the left-hand side of
the rewrite rule {\small\verb%th%} to the term {\small\verb%tm%}.  If such a match is possible, then
{\small\verb%REWR_CONV%} returns the corresponding substitution instance of {\small\verb%th%}.

If {\small\verb%REWR_CONV%} is given a theorem {\small\verb%th%}:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- t[x1,...,xn] = u[x1,...,xn,y1,...,ym]
\end{verbatim}
}
\noindent where the variables {\small\verb%y1%}, ..., {\small\verb%ym%} do not occur free in the
left-hand side, then the result of applying the conversion {\small\verb%REWR_CONV th%} to
a term {\small\verb%t[e1,...,en/x1,...,xn]%} will be:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- t[e1,...,en/x1,...,xn] = u[e1,...,en,v1,...,vm/x1,...,xn,y1,...,ym]
\end{verbatim}
}
\noindent where {\small\verb%v1%}, ..., {\small\verb%vm%} are variables chosen so as to be free nowhere
in {\small\verb%th%} or in the input term.  The user has no control over the choice of the
variables {\small\verb%v1%}, ..., {\small\verb%vm%}, and the variables actually chosen may well be
inconvenient for other purposes.  This situation is, however, relatively rare;
in most equations the free variables on the right-hand side are a subset of the
free variables on the left-hand side.

In addition to doing substitution for free variables in the supplied equational
theorem (or `rewrite rule'), {\small\verb%REWR_CONV th tm%} also does type instantiation,
if this is necessary in order to match the left-hand side of the given rewrite
rule {\small\verb%th%} to the term argument {\small\verb%tm%}.  If, for example, {\small\verb%th%} is the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- t[x1,...,xn] = u[x1,...,xn]
\end{verbatim}
}
\noindent and the input term {\small\verb%tm%} is (a substitution instance of) an instance
of {\small\verb%t[x1,...,xn]%} in which the types {\small\verb%ty1%}, ..., {\small\verb%tyi%} are substituted for the
type variables {\small\verb%vty1%}, ..., {\small\verb%vtyi%}, that is if:
{\par\samepage\setseps\small
\begin{verbatim}
   tm = t[ty1,...,tyn/vty1,...,vtyn][e1,...,en/x1,...,xn]
\end{verbatim}
}
\noindent then {\small\verb%REWR_CONV th tm%} returns:
{\par\samepage\setseps\small
\begin{verbatim}
   A |- (t = u)[ty1,...,tyn/vty1,...,vtyn][e1,...,en/x1,...,xn]
\end{verbatim}
}
\noindent Note that, in this case, the type variables {\small\verb%vty1%}, ..., {\small\verb%vtyi%} must
not occur anywhere in the hypotheses {\small\verb%A%}.  Otherwise, the conversion will fail.

\FAILURE
{\small\verb%REWR_CONV th%} fails if {\small\verb%th%} is not an equation or an equation universally
quantified at the outermost level.  If {\small\verb%th%} is such an equation:
{\par\samepage\setseps\small
\begin{verbatim}
  th = A |- !v1....vi. t[x1,...,xn] = u[x1,...,xn,y1,...,yn]
\end{verbatim}
}
\noindent then {\small\verb%REWR_CONV th tm%} fails unless the term {\small\verb%tm%} is
alpha-equivalent to an instance of the left-hand side {\small\verb%t[x1,...,xn]%} which
can be obtained by instantiation of free type variables (i.e. type variables
not occurring in the assumptions {\small\verb%A%}) and substitution for the free variables
{\small\verb%x1%}, ..., {\small\verb%xn%}.

\EXAMPLE
The following example illustrates a straightforward use of {\small\verb%REWR_CONV%}.
The supplied rewrite rule is polymorphic, and both substitution for free
variables and type instantiation may take place.  {\small\verb%EQ_SYM_EQ%} is the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- !x:*. !y. (x = y) = (y = x)
\end{verbatim}
}
\noindent and {\small\verb%REWR_CONV EQ_SYM%} behaves as follows:
{\par\samepage\setseps\small
\begin{verbatim}
   #REWR_CONV EQ_SYM_EQ "1 = 2";;
   |- (1 = 2) = (2 = 1)

   #REWR_CONV EQ_SYM_EQ "1 < 2";;
   evaluation failed     REWR_CONV: lhs of theorem doesn't match term
\end{verbatim}
}
\noindent The second application fails because the left-hand side {\small\verb%"x = y"%} of
the rewrite rule does not match the term to be rewritten, namely {\small\verb%"1 < 2"%}.

In the following example, one might expect the result to be the theorem
{\small\verb%A |- f 2 = 2%}, where {\small\verb%A%} is the assumption of the supplied rewrite rule:
{\par\samepage\setseps\small
\begin{verbatim}
   #REWR_CONV (ASSUME "!x:*. f x = x") "f 2:num";;
   evaluation failed     REWR_CONV: lhs of theorem doesn't match term
\end{verbatim}
}
\noindent The application fails, however, because the type variable {\small\verb%*%} appears
in the assumption of the theorem returned by {\small\verb%ASSUME "!x:*. f x = x"%}.

Failure will also occur in situations like:
{\par\samepage\setseps\small
\begin{verbatim}
   #REWR_CONV (ASSUME "f (n:num) = n") "f 2:num";;
   evaluation failed     REWR_CONV: lhs of theorem doesn't match term
\end{verbatim}
}
\noindent where the left-hand side of the supplied equation contains a free
variable (in this case {\small\verb%n%}) which is also free in the assumptions, but which
must be instantiated in order to match the input term.

\SEEALSO
REWRITE_CONV.

\ENDDOC
\DOC{REWRITE\_CONV}

\TYPE {\small\verb%REWRITE_CONV : (thm list -> conv)%}\egroup

\SYNOPSIS
Rewrites a term including built-in tautologies in the list of rewrites.

\DESCRIBE
Rewriting a term using {\small\verb%REWRITE_CONV%} utilizes as rewrites two sets
of theorems: the tautologies in the ML list {\small\verb%basic_rewrites%} and the
ones supplied by the user. The rule searches top-down and recursively
for subterms which match the left-hand side of any of the possible
rewrites, until none of the transformations are applicable. There is no
ordering specified among the set of rewrites.

Variants of this conversion allow changes in the set of equations used:
{\small\verb%PURE_REWRITE_CONV%} and others in its family do not rewrite with the
theorems in {\small\verb%basic_rewrites%}. 

The top-down recursive search for matches may not be desirable, as
this may increase the number of inferences being made or may result in
divergence. In this case other rewriting tools such as
{\small\verb%ONCE_REWRITE_CONV%} and {\small\verb%GEN_REWRITE_CONV%} can be used, or the set of
theorems given may be reduced.

See {\small\verb%GEN_REWRITE_CONV%} for the general strategy for simplifying
theorems in HOL using equational theorems.

\FAILURE
Does not fail, but may diverge if the sequence of rewrites is
non-terminating.

\USES
Used to manipulate terms by rewriting them with theorems.
While resulting in high degree of automation, {\small\verb%REWRITE_CONV%} can
spawn a large number of inference steps. Thus, variants such
as {\small\verb%PURE_REWRITE_CONV%}, or other rules such as {\small\verb%SUBST_CONV%}, may be used
instead to improve efficiency.

\SEEALSO
basic_rewrites, GEN_REWRITE_CONV, ONCE_REWRITE_CONV,
PURE_REWRITE_CONV, REWR_CONV, SUBST_CONV.

\ENDDOC
\DOC{REWRITE\_RULE}

\TYPE {\small\verb%REWRITE_RULE : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Rewrites a theorem including built-in tautologies in the list of rewrites.

\DESCRIBE
Rewriting a theorem using {\small\verb%REWRITE_RULE%} utilizes as rewrites two sets
of theorems: the tautologies in the ML list {\small\verb%basic_rewrites%} and the
ones supplied by the user. The rule searches top-down and recursively
for subterms which match the left-hand side of any of the possible
rewrites, until none of the transformations are applicable. There is no
ordering specified among the set of rewrites.

Variants of this rule allow changes in the set of equations used:
{\small\verb%PURE_REWRITE_RULE%} and others in its family do not rewrite with the
theorems in {\small\verb%basic_rewrites%}. Rules such as {\small\verb%ASM_REWRITE_RULE%} add the
assumptions of the object theorem (or a specified subset of these assumptions)
to the set of possible rewrites.

The top-down recursive search for matches may not be desirable, as
this may increase the number of inferences being made or may result in
divergence. In this case other rewriting tools such as
{\small\verb%ONCE_REWRITE_RULE%} and {\small\verb%GEN_REWRITE_RULE%} can be used, or the set of
theorems given may be reduced.

See {\small\verb%GEN_REWRITE_RULE%} for the general strategy for simplifying
theorems in HOL using equational theorems.

\FAILURE
Does not fail, but may diverge if the sequence of rewrites is
non-terminating.

\USES
Used to manipulate theorems by rewriting them with other theorems.
While resulting in high degree of automation, {\small\verb%REWRITE_RULE%} can
spawn a large number of inference steps. Thus, variants such
as {\small\verb%PURE_REWRITE_RULE%}, or other rules such as {\small\verb%SUBST%}, may be used
instead to improve efficiency.

\SEEALSO
ASM_REWRITE_RULE, basic_rewrites, GEN_REWRITE_RULE, ONCE_REWRITE_RULE,
PURE_REWRITE_RULE, REWR_CONV, REWRITE_CONV, SUBST.

\ENDDOC
\DOC{REWRITE\_TAC}

\TYPE {\small\verb%REWRITE_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Rewrites a goal including built-in tautologies in the list of rewrites.

\DESCRIBE
Rewriting tactics in HOL provide a recursive left-to-right matching
and rewriting facility that automatically decomposes subgoals and
justifies segments of proof in which equational theorems are used,
singly or collectively.  These include the unfolding of definitions,
and the substitution of equals for equals.  Rewriting is used either
to advance or to complete the decomposition of subgoals.

{\small\verb%REWRITE_TAC%} transforms (or solves) a goal by using as rewrite rules
(i.e. as left-to-right replacement rules) the conclusions of the given
list of (equational) theorems, as well as a set of built-in theorems
(common tautologies) held in the ML variable {\small\verb%basic_rewrites%}.
Recognition of a tautology often terminates the subgoaling process
(i.e. solves the goal).

The equational rewrites generated are applied recursively and to
arbitrary depth, with matching and instantiation of variables and type
variables.  A list of rewrites can set off an infinite rewriting
process, and it is not, of course, decidable in general whether a
rewrite set has that property. The order in which the rewrite theorems
are applied is unspecified, and the user should not depend on any
ordering.

See {\small\verb%GEN_REWRITE_TAC%} for more details on the rewriting process.
Variants of {\small\verb%REWRITE_TAC%} allow the use of a different set of
rewrites. Some of them, such as {\small\verb%PURE_REWRITE_TAC%}, exclude the basic
tautologies from the possible transformations. {\small\verb%ASM_REWRITE_TAC%} and
others include the assumptions at the goal in the set of possible
rewrites.

Still other tactics allow greater control over the search for
rewritable subterms. Several of them such as {\small\verb%ONCE_REWRITE_TAC%} do not
apply rewrites recursively. {\small\verb%GEN_REWRITE_TAC%} allows a rewrite to be
applied at a particular subterm.

\FAILURE
{\small\verb%REWRITE_TAC%} does not fail. Certain sets of rewriting theorems on
certain goals may cause a non-terminating sequence of rewrites.
Divergent rewriting behaviour results from a term {\small\verb%t%} being
immediately or eventually rewritten to a term containing {\small\verb%t%} as a
sub-term. The exact behaviour depends on the {\small\verb%HOL%} implementation; it
may be possible (unfortunately) to fall into Lisp in this event.

\EXAMPLE
The arithmetic theorem {\small\verb%GREATER%}, {\small\verb%|- !m n. m > n = n < m%}, is used
below to advance a goal:
{\par\samepage\setseps\small
\begin{verbatim}
   #REWRITE_TAC[GREATER]([],"5 > 4");;
   ([([], "4 < 5")], -) : subgoals
\end{verbatim}
}
\noindent It is used below with the theorem {\small\verb%LESS_0%},
{\small\verb%|- !n. 0 < (SUC n)%}, to solve a goal:
{\par\samepage\setseps\small
\begin{verbatim}
   #let gl,p = REWRITE_TAC[GREATER;LESS_0]([],"(SUC n) > 0");;
   gl = [] : goal list
   p = - : proof

   #p[];;
   |- (SUC n) > 0
\end{verbatim}
}
\USES
Rewriting is a powerful and general mechanism in HOL, and an
important part of many proofs.  It relieves the user of the burden of
directing and justifying a large number of minor proof steps.
{\small\verb%REWRITE_TAC%} fits a forward proof sequence smoothly into the general
goal-oriented framework. That is, (within one subgoaling step) it
produces and justifies certain forward inferences, none of which are
necessarily on a direct path to the desired goal.

{\small\verb%REWRITE_TAC%} may be more powerful a tactic than is needed in certain
situations; if efficiency is at stake, alternatives might be
considered.

\SEEALSO
ASM_REWRITE_TAC, GEN_REWRITE_TAC, FILTER_ASM_REWRITE_TAC,
FILTER_ONCE_ASM_REWRITE_TAC, ONCE_ASM_REWRITE_TAC, ONCE_REWRITE_TAC,
PURE_ASM_REWRITE_TAC, PURE_ONCE_ASM_REWRITE_TAC,
PURE_ONCE_REWRITE_TAC, PURE_REWRITE_TAC, REWR_CONV, REWRITE_CONV, SUBST_TAC.

\ENDDOC
\DOC{rhs}

\TYPE {\small\verb%rhs : (term -> term)%}\egroup

\SYNOPSIS
Returns the right-hand side of an equation.

\DESCRIBE
{\small\verb%rhs "t1 = t2"%} returns {\small\verb%"t2"%}.

\FAILURE
Fails with {\small\verb%rhs%} if term is not an equality.

\SEEALSO
lhs, dest_eq.

\ENDDOC
\DOC{RIGHT\_AND\_EXISTS\_CONV}

\TYPE {\small\verb%RIGHT_AND_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification of the right conjunct outwards through a
conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%P /\ (?x.Q)%}, the conversion
{\small\verb%RIGHT_AND_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- P /\ (?x.Q) = (?x'. P /\ (Q[x'/x]))
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%P /\ (?x.Q)%}.

\SEEALSO
AND_EXISTS_CONV, EXISTS_AND_CONV, LEFT_AND_EXISTS_CONV.

\ENDDOC
\DOC{RIGHT\_AND\_FORALL\_CONV}

\TYPE {\small\verb%RIGHT_AND_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification of the right conjunct outwards through a
conjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%P /\ (!x.Q)%}, the conversion
{\small\verb%RIGHT_AND_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- P /\ (!x.Q) = (!x'. P /\ (Q[x'/x]))
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%P /\ (!x.Q)%}.

\SEEALSO
AND_FORALL_CONV, FORALL_AND_CONV, LEFT_AND_FORALL_CONV.

\ENDDOC
\DOC{RIGHT\_BETA}

\TYPE {\small\verb%RIGHT_BETA : (thm -> thm)%}\egroup

\SYNOPSIS
Beta-reduces a top-level beta-redex on the right-hand side of an equation.

\DESCRIBE
When applied to an equational theorem, {\small\verb%RIGHT_BETA%} applies beta-reduction at
top level to the right-hand side (only). Variables are renamed if necessary to
avoid free variable capture.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- s = (\x. t1) t2
   ----------------------  RIGHT_BETA
     A |- s = t1[t2/x]
\end{verbatim}
}
\FAILURE
Fails unless the theorem is equational, with its right-hand side being
a top-level beta-redex.

\SEEALSO
BETA_CONV, BETA_RULE, BETA_TAC, RIGHT_LIST_BETA.

\ENDDOC
\DOC{RIGHT\_CONV\_RULE}

\TYPE {\small\verb%RIGHT_CONV_RULE : (conv -> thm -> thm)%}\egroup

\SYNOPSIS
Applies a conversion to the right-hand side of an equational theorem.

\DESCRIBE
If {\small\verb%c%} is a conversion that maps a term {\small\verb%"t2"%} to the theorem {\small\verb%|- t2 = t2'%},
then the rule {\small\verb%RIGHT_CONV_RULE c%} infers {\small\verb%|- t1 = t2'%} from the theorem
{\small\verb%|- t1 = t2%}.  That is, if  {\small\verb%c "t2"%} returns {\small\verb%A' |- t2 = t2'%}, then:
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t1 = t2
   ---------------------  RIGHT_CONV_RULE c
    A u A' |- t1 = t2'
\end{verbatim}
}
\noindent Note that if the conversion {\small\verb%c%} returns a theorem with assumptions,
then the resulting inference rule adds these to the assumptions of the
theorem it returns.

\FAILURE
{\small\verb%RIGHT_CONV_RULE c th%} fails if the conclusion of the theorem {\small\verb%th%} is not an
equation, or if {\small\verb%th%} is an equation but {\small\verb%c%} fails when applied its right-hand
side. The function returned by {\small\verb%RIGHT_CONV_RULE c%} will also fail if the ML
function {\small\verb%c:term->thm%} is not, in fact, a conversion (i.e. a function that maps
a term {\small\verb%t%} to a theorem {\small\verb%|- t = t'%}).

\SEEALSO
CONV_RULE.

\ENDDOC
\DOC{RIGHT\_IMP\_EXISTS\_CONV}

\TYPE {\small\verb%RIGHT_IMP_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification of the consequent outwards through an
implication.

\DESCRIBE
When applied to a term of the form {\small\verb%P ==> (?x.Q)%}, the conversion
{\small\verb%RIGHT_IMP_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- P ==> (?x.Q) = (?x'. P ==> (Q[x'/x]))
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%P ==> (?x.Q)%}.

\SEEALSO
EXISTS_IMP_CONV, LEFT_IMP_FORALL_CONV.

\ENDDOC
\DOC{RIGHT\_IMP\_FORALL\_CONV}

\TYPE {\small\verb%RIGHT_IMP_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification of the consequent outwards through an
implication.

\DESCRIBE
When applied to a term of the form {\small\verb%P ==> (!x.Q)%}, the conversion
{\small\verb%RIGHT_IMP_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- P ==> (!x.Q) = (!x'. P ==> (Q[x'/x]))
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%P ==> (!x.Q)%}.

\SEEALSO
FORALL_IMP_CONV, LEFT_IMP_EXISTS_CONV.

\ENDDOC
\DOC{RIGHT\_LIST\_BETA}

\TYPE {\small\verb%RIGHT_LIST_BETA : (thm -> thm)%}\egroup

\SYNOPSIS
Iteratively beta-reduces a top-level beta-redex on the right-hand side of an
equation.

\DESCRIBE
When applied to an equational theorem, {\small\verb%RIGHT_LIST_BETA%} applies beta-reduction
over a top-level chain of beta-redexes to the right hand side (only). Variables
are renamed if necessary to avoid free variable capture.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- s = (\x1...xn. t) t1 ... tn
   ----------------------------------  RIGHT_LIST_BETA
       A |- s = t[t1/x1]...[tn/xn]
\end{verbatim}
}
\FAILURE
Fails unless the theorem is equational, with its right-hand side being
a top-level beta-redex.

\SEEALSO
BETA_CONV, BETA_RULE, BETA_TAC, LIST_BETA_CONV, RIGHT_BETA.

\ENDDOC
\DOC{RIGHT\_OR\_EXISTS\_CONV}

\TYPE {\small\verb%RIGHT_OR_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Moves an existential quantification of the right disjunct outwards through a
disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%P \/ (?x.Q)%}, the conversion
{\small\verb%RIGHT_OR_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- P \/ (?x.Q) = (?x'. P \/ (Q[x'/x]))
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%P \/ (?x.Q)%}.

\SEEALSO
OR_EXISTS_CONV, EXISTS_OR_CONV, LEFT_OR_EXISTS_CONV.

\ENDDOC
\DOC{RIGHT\_OR\_FORALL\_CONV}

\TYPE {\small\verb%RIGHT_OR_FORALL_CONV : conv%}\egroup

\SYNOPSIS
Moves a universal quantification of the right disjunct outwards through a
disjunction.

\DESCRIBE
When applied to a term of the form {\small\verb%P \/ (!x.Q)%}, the conversion
{\small\verb%RIGHT_OR_FORALL_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- P \/ (!x.Q) = (!x'. P \/ (Q[x'/x]))
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
the input term.

\FAILURE
Fails if applied to a term not of the form {\small\verb%P \/ (!x.Q)%}.

\SEEALSO
OR_FORALL_CONV, FORALL_OR_CONV, LEFT_OR_FORALL_CONV.

\ENDDOC
\DOC{root\_goal}

\TYPE {\small\verb%root_goal : tactic%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{rotate}

\TYPE {\small\verb%rotate : (int -> void)%}\egroup

\SYNOPSIS
Reorders the subgoals on top of the subgoal package goal stack.

\DESCRIBE
The function {\small\verb%rotate%} is part of the subgoal package. Calling {\small\verb%rotate n%} forms
a new proof state. It rotates, by {\small\verb%n%} steps, the subgoals in the top level of
the goal stack of the current proof state (i.e., those resulting from the
application of the most recent tactic). Goals are rotated upwards on the stack,
with the top goals being moved to the bottom of the level. If {\small\verb%n%} is greater
than the number of goals on the level, the rotation is performed modulo the
number of subgoals. The previous proof state is stored on the backup list, so
may be restored by a call to {\small\verb%backup%}. The subgoals of the level are printed
from the bottom of the stack. The function {\small\verb%rotate%} is abbreviated by the
function {\small\verb%r%}. For a description of the subgoal package, see  {\small\verb%set_goal%}.

\FAILURE
{\small\verb%rotate%} will fail if no goal has been set or if the last goal set has been
completely proved. It will diverge if given a negative argument.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#rotate 1;;
evaluation failed     rotate_goals

#g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3]) /\ (HD (TL[1;2;3]) = 2)";;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3]) /\ (HD(TL[1;2;3]) = 2)"

() : void

#e (REPEAT CONJ_TAC);;
OK..
3 subgoals
"HD(TL[1;2;3]) = 2"

"TL[1;2;3] = [2;3]"

"HD[1;2;3] = 1"

() : void

#rotate 1;;
3 subgoals
"HD[1;2;3] = 1"

"HD(TL[1;2;3]) = 2"

"TL[1;2;3] = [2;3]"

() : void
\end{verbatim}
}
\USES
Proving subgoals in a different order to that generated by  the subgoal package.
The subgoals of a goal may be considered in any order.  However,
subgoals deeper in the stack cannot be worked on, nor can subgoals higher in
the proof tree.

\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, p, print_state, r,
save_top_thm, set_goal, set_state, top_goal, top_thm.

\ENDDOC
\DOC{rotate\_goals}

\TYPE {\small\verb%rotate_goals : (subgoals -> subgoals)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{rotate\_top}

\TYPE {\small\verb%rotate_top : (int -> subgoals list -> subgoals list)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{RULE\_ASSUM\_TAC}

\TYPE {\small\verb%RULE_ASSUM_TAC : ((thm -> thm) -> tactic)%}\egroup

\SYNOPSIS
Maps an inference rule over the assumptions of a goal.

\DESCRIBE
When applied to an inference rule {\small\verb%f%} and a goal {\small\verb%({A1;...;An} ?- t)%},
the {\small\verb%RULE_ASSUM_TAC%} tactical applies the inference rule to each of the
{\small\verb%ASSUME%}d assumptions to give a new goal.
{\par\samepage\setseps\small
\begin{verbatim}
             {A1,...,An} ?- t
   ====================================  RULE_ASSUM_TAC f
    {f(A1 |- A1),...,f(An |- An)} ?- t
\end{verbatim}
}
\FAILURE
The application of {\small\verb%RULE_ASSUM_TAC f%} to a goal fails iff {\small\verb%f%} fails when
applied to any of the assumptions of the goal.

\COMMENTS
It does not matter if the goal has no assumptions, but in this case
{\small\verb%RULE_ASSUM_TAC%} has no effect.

\SEEALSO
ASSUM_LIST, MAP_EVERY, MAP_FIRST, POP_ASSUM_LIST.

\ENDDOC
\DOC{save}

\TYPE {\small\verb%save : (string -> void)%}\egroup

\SYNOPSIS
Saves an executable version of HOL in its current state.

\DESCRIBE
The call {\small\verb%save `image`%} will save an executable core image, called {\small\verb%image%}, of
HOL in its current state. This means that if this image is subsequently
executed instead of the normal HOL, any bindings set up will be preserved.

\FAILURE
Will fail only in system-dependent ways, such as running out of disk space.

\COMMENTS
Note that a HOL image is rather large; exactly how large depends on the version
of Lisp and other factors, but it is usually a good many megabytes.

\USES
Avoiding the need to re-execute certain initializations, in particular,
installation, every time HOL is run. Note that a {\small\verb%hol-init.ml%} file will be
executed automatically every time HOL is run, and is usually sufficient for
private initializations. See the DESCRIPTION for details.

\SEEALSO
install.

\ENDDOC
\DOC{save\_thm}

\TYPE {\small\verb%save_thm : ((string # thm) -> thm)%}\egroup

\SYNOPSIS
Stores a theorem in the current theory segment.

\DESCRIBE
The call {\small\verb%save_thm(`name`, th)%} adds the theorem {\small\verb%th%} to the current theory
segment under the name {\small\verb%name%}. The theorem is returned as a value. The call
can be made in both proof and draft mode. The name {\small\verb%name%} must be a distinct
name within the theory segment, but may be the same as for items within other
theory segments of the theory. If the current theory segment is named {\small\verb%thy%},
the theorem will be written to the file {\small\verb%thy.th%} in the directory from which
HOL was called. If the system is in draft mode, other changes made to the
current theory segment  during the session will also be written to the theory
file. If the theory file does not exist, it will be created.

\FAILURE
A call to {\small\verb%save_thm%} will fail if  the name given is the same as
the name of an existing fact in the current theory segment.
Saving the theorem involves writing to the file system. If the write fails for
any reason {\small\verb%save_thm%} will fail. For example, on start up the initial
theory is {\small\verb%HOL%}. The associated theory files are read-only so an attempt to
save a theorem in that theory segment will fail.

\USES
Adding theorems to the current theory. Saving theorems for retrieval
in  later sessions. The theorem may be retrieved using the function
{\small\verb%theorem%}. Binding the result of {\small\verb%save_thm%} to an ML variable makes it easy to
access the theorem in the current terminal session.

\SEEALSO
new_theory, prove_thm, save_top_thm, theorem.

\ENDDOC
\DOC{save\_top\_thm}

\TYPE {\small\verb%save_top_thm : (string -> thm)%}\egroup

\SYNOPSIS
Stores the theorem just proved with the subgoal package in the current theory
segment.

\DESCRIBE
The function {\small\verb%save_top_thm%} is part of the subgoal package.  A proof state of
the package consists of either goal and justification stacks if a proof is in
progress or a theorem if a proof has just been completed. If the proof state
consists of a theorem, the call {\small\verb%save_top_thm `name`%} adds that theorem to the
current theory segment under the name {\small\verb%name%}. The theorem is returned as a
value. The name {\small\verb%name%} must be a distinct name within the theory segment, but
may be the same as for items within other theory segments of the theory. If the
current theory segment is named {\small\verb%thy%}, the theorem will be written to the
file {\small\verb%thy.th%} in the directory from which HOL was called. If the system is in
draft mode, other changes made to the current theory segment  during the
session will also be written to the theory file. If the theory file does not
exist, it will be created. The call can be made in both proof and draft mode.
For a description of the subgoal package, see {\small\verb%set_goal%}.

\FAILURE
A call to {\small\verb%save_top_thm%} will fail if the proof state does not hold a theorem.
This will be so either because no goal has been set or because a proof is in
progress with unproven subgoals. It will fail if the name given is the same as
the name of an existing fact in the current theory segment.
Storing the theorem involves writing to the file system. If the write fails for
any reason {\small\verb%save_top_thm%} will fail. For example, on start up the initial
theory is {\small\verb%HOL%}. The associated theory files are read-only so an attempt to
store a theorem in that theory segment will fail.

\USES
Adding theorems to the current theory. Saving theorems for retrieval
in later sessions. The theorem may be retrieved using the function
{\small\verb%theorem%}.  Binding the result of {\small\verb%save_top_thm%} to an ML variable makes it
easy to access the theorem in the current terminal session.

\SEEALSO
get_state, new_theory, print_state, prove_thm, save_thm, set_goal, set_state,
theorem, top_thm.

\ENDDOC
\DOC{SCANL\_CONV}

\TYPE {\small\verb%SCANL_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a function to elements of a list.

\DESCRIBE
{\small\verb%SCANL_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   SCANL f e0 [x1;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- SCANL f e0 [x1;...xn] = [e0; e1; ...;en]
\end{verbatim}
}
\noindent where {\small\verb%ei%} is the result of applying the function {\small\verb%f%} to
the result of the previous iteration and the current element, i.e.,
{\small\verb%ei = f e(i-1) xi%}. The iteration starts from the left-hand side (the
head) of the list. 
The user supplied conversion {\small\verb%conv%} is used to derive a theorem 
{\par\samepage\setseps\small
\begin{verbatim}
   |- f e(i-1) xi = ei
\end{verbatim}
}
\noindent which is used in the next iteration.

\FAILURE
{\small\verb%SCANL_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above,
or failure occurs when evaluating {\small\verb%conv "f e(i-1) xi"%}.

\EXAMPLE
To sum the elements of a list and save the result at each step, one can evaluate
{\par\samepage\setseps\small
\begin{verbatim}
   SCANL_CONV ADD_CONV "SCANL $+ 0 [1;2;3]";;
\end{verbatim}
}
\noindent which returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- SCANL $+ 0[1;2;3] = [0;1;3;6]
\end{verbatim}
}
\noindent In general, if the function {\small\verb%f%} is an explicit lambda abstraction
{\small\verb%(\x x'. t[x,x'])%}, the conversion should be in the form
{\par\samepage\setseps\small
\begin{verbatim}
   ((RATOR_CONV BETA_CONV) THENC BETA_CONV THENC conv'))
\end{verbatim}
}
\noindent  where {\small\verb%conv'%} applied to {\small\verb%t[x,x']%} returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |-t[x,x'] = e''.
\end{verbatim}
}

\SEEALSO
SCANR_CONV, FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{SCANR\_CONV}

\TYPE {\small\verb%SCANR_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a function to elements of a list.

\DESCRIBE
{\small\verb%SCANR_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   SCANR f e0 [xn;...;x1]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- SCANR f e0 [xn;...;x1] = [en; ...;e1;e0]
\end{verbatim}
}
\noindent where {\small\verb%ei%} is the result of applying the function {\small\verb%f%} to
the result of the previous iteration and the current element, i.e.,
{\small\verb%ei = f e(i-1) xi%}. The iteration starts from the right-hand side (the
tail) of the list. 
The user supplied conversion {\small\verb%conv%} is used to derive a theorem 
{\par\samepage\setseps\small
\begin{verbatim}
   |- f e(i-1) xi = ei
\end{verbatim}
}
\noindent which is used in the next iteration.

\FAILURE
{\small\verb%SCANR_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above,
or failure occurs when evaluating {\small\verb%conv "f e(i-1) xi"%}.

\EXAMPLE
To sum the elements of a list and save the result at each step, one can evaluate
{\par\samepage\setseps\small
\begin{verbatim}
   SCANR_CONV ADD_CONV "SCANR $+ 0 [1;2;3]";;
\end{verbatim}
}
\noindent which returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- SCANR $+ 0[1;2;3] = [0;1;3;6]
\end{verbatim}
}
\noindent In general, if the function {\small\verb%f%} is an explicit lambda abstraction
{\small\verb%(\x x'. t[x,x'])%}, the conversion should be in the form
{\par\samepage\setseps\small
\begin{verbatim}
   ((RATOR_CONV BETA_CONV) THENC BETA_CONV THENC conv'))
\end{verbatim}
}
\noindent  where {\small\verb%conv'%} applied to {\small\verb%t[x,x']%} returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |-t[x,x'] = e''.
\end{verbatim}
}

\SEEALSO
SCANL_CONV, FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{S}

\TYPE {\small\verb%S : ((* -> ** -> ***) -> (* -> **) -> * -> ***)%}\egroup

\SYNOPSIS
Performs function composition: {\small\verb%S f g x%} = {\small\verb%f x (g x)%} (the {\small\verb%S%} combinator).

\FAILURE
Never fails.

\SEEALSO
\#, B, C, CB, Co, I, K, KI, o, oo, W.

\ENDDOC
\DOC{search\_path}

\TYPE {\small\verb%search_path : (void -> string list)%}\egroup

\SYNOPSIS
Returns the internal search path use by HOL to find files.

\DESCRIBE
Evaluating {\small\verb%search_path()%} returns a list of strings representing the pathnames
of the directories that are searched when HOL makes access to files on disk
(using {\small\verb%load%}, {\small\verb%compile%}, {\small\verb%load_theory%}, etc.). Although the search path can be
set to an arbitrary list of strings, each string in the search path is normally
expected to be either empty ({\small\verb%``%}) or a pathname with `{\small\verb%/%}' as its final
character.  When HOL looks for a file, the directories in the search path are
searched in the order in which they occur in the list returned by
{\small\verb%search_path%}.

\FAILURE
Never fails.

\EXAMPLE
A typical search path is the following:
{\par\samepage\setseps\small
\begin{verbatim}
   #search_path();;
   [``; `~/`; `/usr/lib/hol/theories/`] : string list
\end{verbatim}
}
\noindent With this search path, HOL first looks for a file in the current
working directory (the pathname represented by {\small\verb%``%}), then in the user`s home
directory {\small\verb%`~/`%}, and finally in the directory {\small\verb%`/usr/lib/hol/theories/`%} (the
directory containing HOL`s built-in theories).

\SEEALSO
help_search_path, install, set_help_search_path, set_search_path.

\ENDDOC
\DOC{SEG\_CONV}

\TYPE {\small\verb%SEG_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of taking a segment of a list.

\DESCRIBE
For any object language list of the form {\small\verb%"[x0;...x(n-1)]"%} ,
the result of evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   SEG_CONV "SEG m k [x0;...;x(n-1)]"
\end{verbatim}
}
\noindent is the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- SEG m k [x0;...;x(n-1)] = [xk;...;x(m+k-1)]
\end{verbatim}
}


\FAILURE
{\small\verb%SEG_CONV tm%} fails if {\small\verb%tm%} is not in the form described above or the
indexes {\small\verb%m%} and {\small\verb%k%} are not in the correct range, i.e., {\small\verb%m + k <= n%}.

\EXAMPLE
Evaluating the expression
{\par\samepage\setseps\small
\begin{verbatim}
   SEG_CONV "SEG 2 3[0;1;2;3;4;5]";;
\end{verbatim}
}
returns the following theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- SEG 2 3[0;1;2;3;4;5] = [3;4]
\end{verbatim}
}

\SEEALSO
FIRSTN_CONV, LASTN_CONV, BUTFIRSTN_CONV, BUTLASTN_CONV,
LAST_CONV, BUTLAST_CONV.

\ENDDOC

\DOC{SELECT\_CONV}

\TYPE {\small\verb%SELECT_CONV : conv%}\egroup

\SYNOPSIS
Eliminates an epsilon term by introducing an existential quantifier.

\DESCRIBE
The conversion {\small\verb%SELECT_CONV%} expects a boolean term of the form
{\small\verb%"P[@x.P[x]/x]"%}, which asserts that the epsilon term {\small\verb%@x.P[x]%} denotes
a value, {\small\verb%x%} say, for which {\small\verb%P[x]%} holds.  This assertion is equivalent
to saying that there exists such a value, and {\small\verb%SELECT_CONV%} applied to a
term of this form returns the theorem {\small\verb%|- P[@x.P[x]/x] = ?x. P[x]%}.

\FAILURE
Fails if applied to a term that is not of the form {\small\verb%"P[@x.P[x]/x]"%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#SELECT_CONV "(@n. n < m) < m";;
|- (@n. n < m) < m = (?n. n < m)
\end{verbatim}
}
\USES
Particularly useful in conjunction with {\small\verb%CONV_TAC%} for proving properties
of values denoted by epsilon terms.  For example, suppose that one wishes
to prove the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ["0 < m"], "(@n. n < m) < SUC m"
\end{verbatim}
}
\noindent Using the built-in arithmetic theorem
{\par\samepage\setseps\small
\begin{verbatim}
   LESS_SUC  |- !m n. m < n ==> m < (SUC n)
\end{verbatim}
}
\noindent this goal may be reduced by the tactic {\small\verb%MATCH_MP_TAC LESS_SUC%} to
the subgoal
{\par\samepage\setseps\small
\begin{verbatim}
   ["0 < m"], "(@n. n < m) < m"
\end{verbatim}
}
\noindent This is now in the correct form for using {\small\verb%CONV_TAC SELECT_CONV%} to
eliminate the epsilon term, resulting in the existentially quantified goal
{\par\samepage\setseps\small
\begin{verbatim}
   ["0 < m"], "?n. n < m"
\end{verbatim}
}
\noindent which is then straightforward to prove.

\SEEALSO
SELECT_ELIM, SELECT_INTRO, SELECT_RULE.

\ENDDOC
\DOC{SELECT\_ELIM}

\TYPE {\small\verb%SELECT_ELIM : (thm -> (term # thm) -> thm)%}\egroup

\SYNOPSIS
Eliminates an epsilon term, using deduction from a particular instance.

\DESCRIBE
{\small\verb%SELECT_ELIM%} expects two arguments, a theorem {\small\verb%th1%}, and a pair
{\small\verb%(v,th2):(term # thm)%}.  The conclusion of {\small\verb%th1%} must have the form {\small\verb%P($@ P)%},
which asserts that the epsilon term {\small\verb%$@ P%} denotes some value at which
{\small\verb%P%} holds.  The variable {\small\verb%v%} appears only in the assumption {\small\verb%P v%} of
the theorem {\small\verb%th2%}.  The conclusion of the resulting theorem matches
that of {\small\verb%th2%}, and the hypotheses include the union of all hypotheses
of the premises excepting {\small\verb%P v%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- P($@ P)     A2 u {P v} |- t
   -----------------------------------  SELECT_ELIM th1 (v,th2)
              A1 u A2 |- t
\end{verbatim}
}
\noindent where {\small\verb%v%} is not free in {\small\verb%A2%}. If {\small\verb%v%} appears in the conclusion of
{\small\verb%th2%}, the epsilon term will NOT be eliminated, and the conclusion will be
{\small\verb%t[$@ P/v]%}.

\FAILURE
Fails if the first theorem is not of the form {\small\verb%A1 |- P($@ P)%}, or if
the variable {\small\verb%v%} occurs free in any other assumption of {\small\verb%th2%}.

\EXAMPLE
If a property of functions is defined by:
{\par\samepage\setseps\small
\begin{verbatim}
   INCR = |- !f. INCR f = (!t1 t2. t1 < t2 ==> (f t1) < (f t2))
\end{verbatim}
}
\noindent The following theorem can be proved.
{\par\samepage\setseps\small
\begin{verbatim}
   th1 = |- INCR(@f. INCR f)
\end{verbatim}
}
\noindent Additionally, if such a function is assumed to exist, then one
can prove that there also exists a function which is injective (one-to-one) but
not surjective (onto).
{\par\samepage\setseps\small
\begin{verbatim}
   th2 = [ INCR g ] |- ?h. ONE_ONE h /\ ~ONTO h
\end{verbatim}
}
\noindent These two results may be combined using {\small\verb%SELECT_ELIM%} to
give a new theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   #SELECT_ELIM th1 ("g:num->num", th2);;
   |- ?h. ONE_ONE h /\ ~ONTO h
\end{verbatim}
}
\USES
This rule is rarely used.  The equivalence of {\small\verb%P($@ P)%} and {\small\verb%$? P%}
makes this rule fundamentally similar to the {\small\verb%?%}-elimination rule {\small\verb%CHOOSE%}.

\SEEALSO
CHOOSE, SELECT_AX, SELECT_CONV, SELECT_INTRO, SELECT_RULE.

\ENDDOC
\DOC{SELECT\_EQ}

\TYPE {\small\verb%SELECT_EQ : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Applies epsilon abstraction to both terms of an equation.

\DESCRIBE
Effects the extensionality of the epsilon operator {\small\verb%@%}.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- t1 = t2
   ------------------------  SELECT_EQ "x"      [where x is not free in A]
    A |- (@x.t1) = (@x.t2)
\end{verbatim}
}
\FAILURE
Fails if the conclusion of the theorem is not an equation, or if the
variable {\small\verb%x%} is free in {\small\verb%A%}.

\EXAMPLE
Given a theorem which shows the equivalence of two distinct forms of
defining the property of being an even number:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- (x MOD 2 = 0) = (?y. x = 2 * y)
\end{verbatim}
}
\noindent A theorem giving the equivalence of the epsilon abstraction of each
form is obtained:
{\par\samepage\setseps\small
\begin{verbatim}
   #SELECT_EQ "x:num" th;;
   |- (@x. x MOD 2 = 0) = (@x. ?y. x = 2 * y)
\end{verbatim}
}
\SEEALSO
ABS, AP_TERM, EXISTS_EQ, FORALL_EQ, SELECT_AX, SELECT_CONV,
SELECT_ELIM, SELECT_INTRO.

\ENDDOC
\DOC{SELECT\_INTRO}

\TYPE {\small\verb%SELECT_INTRO : (thm -> thm)%}\egroup

\SYNOPSIS
Introduces an epsilon term.

\DESCRIBE
{\small\verb%SELECT_INTRO%} takes a theorem with an applicative conclusion, say
{\small\verb%P x%}, and returns a theorem with the epsilon term {\small\verb%$@ P%} in place
of the original operand {\small\verb%x%}.
{\par\samepage\setseps\small
\begin{verbatim}
     A |- P x
   --------------  SELECT_INTRO
    A |- P($@ P)
\end{verbatim}
}
\noindent The returned theorem asserts that {\small\verb%$@ P%} denotes some value
at which {\small\verb%P%} holds.

\FAILURE
Fails if the conclusion of the theorem is not an application.

\EXAMPLE
Given the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   th1 = |- (\n. m = n)m
\end{verbatim}
}
\noindent applying {\small\verb%SELECT_INTRO%} replaces the second occurrence of {\small\verb%m%} with the
epsilon abstraction of the operator:
{\par\samepage\setseps\small
\begin{verbatim}
   #let th2 = SELECT_INTRO th1;;
   th2 = |- (\n. m = n)(@n. m = n)
\end{verbatim}
}
\noindent This theorem could now be used to derive a further result:
{\par\samepage\setseps\small
\begin{verbatim}
   #EQ_MP(BETA_CONV(concl th2))th2;;
   |- m = (@n. m = n)
\end{verbatim}
}
\SEEALSO
EXISTS, SELECT_AX, SELECT_CONV, SELECT_ELIM, SELECT_RULE.

\ENDDOC
\DOC{SELECT\_RULE}

\TYPE {\small\verb%SELECT_RULE : (thm -> thm)%}\egroup

\SYNOPSIS
Introduces an epsilon term in place of an existential quantifier.

\DESCRIBE
The inference rule {\small\verb%SELECT_RULE%} expects a theorem asserting the
existence of a value {\small\verb%x%} such that {\small\verb%P%} holds.  The equivalent assertion
that the epsilon term {\small\verb%@x.P%} denotes a value of {\small\verb%x%} for
which {\small\verb%P%} holds is returned as a theorem.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- ?x. P
   ------------------  SELECT_RULE
    A |- P[(@x.P)/x]
\end{verbatim}
}
\FAILURE
Fails if applied to a theorem the conclusion of which is not
existentially quantified.

\EXAMPLE
The axiom {\small\verb%INFINITY_AX%} in the theory {\small\verb%ind%} is of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   |- ?f. ONE_ONE f /\ ~ONTO f
\end{verbatim}
}
\noindent Applying {\small\verb%SELECT_RULE%} to this theorem returns the following.
{\par\samepage\setseps\small
\begin{verbatim}
   #SELECT_RULE INFINITY_AX;;
   |- ONE_ONE(@f. ONE_ONE f /\ ~ONTO f) /\ ~ONTO(@f. ONE_ONE f /\ ~ONTO f)
\end{verbatim}
}
\USES
May be used to introduce an epsilon term to permit rewriting with a
constant defined using the epsilon operator.

\SEEALSO
CHOOSE, SELECT_AX, SELECT_CONV, SELECT_ELIM, SELECT_INTRO.

\ENDDOC
\DOC{set\_equal}

\TYPE {\small\verb%set_equal : (* list -> * list -> bool)%}\egroup

\SYNOPSIS
Tests two `sets' for equality.

\DESCRIBE
{\small\verb%set_equal l1 l2%} returns {\small\verb%true%} if every element of {\small\verb%l1%} appears in {\small\verb%l2%} and
every element of {\small\verb%l2%} appears in {\small\verb%l1%}. Otherwise it returns {\small\verb%false%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#set_equal [1;2] [2;1;2];;
true : bool

#set_equal [1;2] [1;3];;
false : bool
\end{verbatim}
}
\SEEALSO
setify, union, intersect, subtract.

\ENDDOC
\DOC{set\_fail}

\TYPE {\small\verb%set_fail : (string -> (* -> **) -> * -> **)%}\egroup

\SYNOPSIS
Specifies the failure string for a function evaluation.

\DESCRIBE
When applied to a string {\small\verb%s%} and a function {\small\verb%f%}, the function {\small\verb%set_fail%}
gives a function which behaves identically to {\small\verb%f%} except that on failure, the
failure string is {\small\verb%s%}, regardless of what failure string {\small\verb%f%} itself gives rise
to.

\FAILURE
Never fails.

\EXAMPLE
The following example shows how a failure string can be customized either by
using {\small\verb%set_fail%} or by adding a toplevel error trap.
{\par\samepage\setseps\small
\begin{verbatim}
   #BETA_CONV "1 + 1";;
   evaluation failed     BETA_CONV

   #(set_fail `Term is not a beta-redex` BETA_CONV) "1 + 1";;
   evaluation failed     Term is not a beta-redex

   #(BETA_CONV "1 + 1") ? failwith `Term is not a beta-redex`;;
   evaluation failed     Term is not a beta-redex
\end{verbatim}
}
\SEEALSO
set_fail_prefix.

\ENDDOC
\DOC{set\_fail\_prefix}

\TYPE {\small\verb%set_fail_prefix : (string -> (* -> **) -> * -> **)%}\egroup

\SYNOPSIS
Specifies a prefix to the failure string for a function evaluation.

\DESCRIBE
When applied to a string {\small\verb%s%} and a function {\small\verb%f%}, the function {\small\verb%set_fail_prefix%}
gives a function which behaves identically to {\small\verb%f%} except that on failure, the
failure string given by {\small\verb%f%} has {\small\verb%s%} and {\small\verb%`--`%} prepended.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#BETA_CONV "1 + 1";;
evaluation failed     BETA_CONV

#(set_fail_prefix `Application to "1 + 1" ` BETA_CONV) "1 + 1";;
evaluation failed     Application to "1 + 1"  -- BETA_CONV
\end{verbatim}
}
\USES
Providing a traceback of failures through function applications.

\SEEALSO
set_fail.

\ENDDOC
\DOC{set\_flag}

\TYPE {\small\verb%set_flag : ((string # bool) -> bool)%}\egroup

\SYNOPSIS
Sets a named flag to a specific boolean value.

\DESCRIBE
The function {\small\verb%set_flag%} sets a flag to a given value. The previous value of the
flag is returned. The list of settable flags can be determined by executing
{\small\verb%flags ()%}.

\FAILURE
If the named string does not identify a settable flag.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #set_flag (`timing`, true);;
   false : bool
   Run time: 0.0s
\end{verbatim}
}
\SEEALSO
flags.

\ENDDOC
\DOC{set\_goal}

\TYPE {\small\verb%set_goal : (goal -> void)%}\egroup

\SYNOPSIS
Initializes the subgoal package with a new goal.

\DESCRIBE
The function {\small\verb%set_goal%} initializes the subgoal management package. A  proof
state of the package consists of either a goal stack and a justification stack
if a proof is in progress, or a theorem if a proof has just been completed.
{\small\verb%set_goal%} sets a new proof state consisting of an empty justification stack
and a goal stack with the given goal as its sole goal. The goal is printed.

\FAILURE
Fails unless all terms in the goal are of type {\small\verb%bool%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#set_goal([], "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])");;
"(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

() : void
\end{verbatim}
}
\USES
Starting  an interactive proof session with the subgoal package.

The subgoal package implements a simple framework for interactive goal-directed
 proof.  When conducting a proof that involves many subgoals and
tactics, the user must keep track of all the justifications and compose them
in the correct order.  While this is feasible even in large proofs, it is
tedious.  The subgoal package provides a way of building and traversing the
tree of subgoals top-down, stacking the justifications and applying them
properly.

The package maintains a proof state consisting of either a goal stack of
outstanding goals and a justification stack, or a theorem.  Tactics are used
to expand the current goal (the one on the top of the goal stack) into
subgoals and justifications. These are pushed onto the goal stack and
justification stack, respectively, to form a new proof state. Several
preceding proof states are saved and can be returned to if a mistake is made
in the proof.  The goal stack is divided into levels, a new level being
created each time a tactic is successfully applied to give new subgoals.  The
subgoals of the current level may be considered in any order.

If a tactic solves the current goal (returns an empty subgoal list), then
its justification is used to prove a corresponding theorem. This theorem is
then incorporated into the justification of the parent goal. If the subgoal
was the last subgoal of the level, the level is removed and the parent
goal is proved using  its (new) justification. This process is repeated
until a level with unproven subgoals is reached.
The next goal on the goal stack then becomes the current goal.
If all the subgoals are proved, the resulting proof state consists
of the theorem proved by the justifications. This theorem may be accessed and
saved.

\COMMENTS
A more sophisticated subgoal management package will be implemented in the
future.

\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_state, top_goal, top_thm.

\ENDDOC
\DOC{set\_help}

\TYPE {\small\verb%set_help : (string -> string)%}\egroup

\SYNOPSIS
Specifies a filter to pipe help output through.

\DESCRIBE
Evaluating {\small\verb%set_help `filter`%} will make future help output (generated in
response to a {\small\verb%help%} command) be piped through the program {\small\verb%filter%}. The
function returns the name of the previous filter. The default is {\small\verb%cat%}, so
output is just sent to the console. Previous versions of HOL used {\small\verb%more%} by
default.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#set_help `lpr`;;
`cat` : string
\end{verbatim}
}
\noindent This causes the help file to be printed instead of being displayed.

\SEEALSO
help, help_search_path, set_help_search_path

\ENDDOC
\DOC{set\_help\_search\_path}

\TYPE {\small\verb%set_help_search_path : (string list -> void)%}\egroup

\SYNOPSIS
Sets the internal search path use by HOL to find files.

\DESCRIBE
When applied to a list of strings {\small\verb%l%}, each of which represents the pathname
to a directory, {\small\verb%set_help_search_path%} sets the internal search path used when
the {\small\verb%help%} function searches for online help files to the list {\small\verb%l%}. Although
the help search path can be set to an arbitrary list of strings, each string is
normally expected to be either empty ({\small\verb%``%}) or a pathname with `{\small\verb%/%}' as its
final character.  When {\small\verb%help%} looks for a help file, the directories in the
search path are searched in the order in which they occur in the list supplied
to {\small\verb%set_help_search_path%}.

\FAILURE
Never fails.

\SEEALSO
help_search_path, install, search_path, set_search_path.

\ENDDOC
\DOC{setify}

\TYPE {\small\verb%setify : (* list -> * list)%}\egroup

\SYNOPSIS
Removes repeated elements from a list. Makes a list into a `set'.

\DESCRIBE
{\small\verb%setify l%} removes repeated elements from {\small\verb%l%}, leaving the last occurrence of
each duplicate in the list.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#setify [1;2;3;1;4;3];;
[2; 1; 4; 3] : int list
\end{verbatim}
}
\COMMENTS
Perhaps the first occurrence of each duplicate should be left in the list, not
the last? However, other functions may rely on the ordering currently used.

\SEEALSO
distinct.

\ENDDOC
\DOC{set\_interface\_map}

\TYPE {\small\verb%set_interface_map : ((string # string) list -> (string # string) list)%}\egroup

\SYNOPSIS
Sets up a new interface map.

\DESCRIBE
A call {\small\verb%set_interface_map [(a1,c1);...;(an,cn)]%}, where the {\small\verb%c%}'s are the names
of existing constants, will set up the corresponding interface map, and return
the previous one. This means that a variable or constant with the name {\small\verb%ai%}
occurring in a quoted term will be translated into the corresponding {\small\verb%ci%}.
Furthermore, if the flag {\small\verb%interface_print%} is set, the transformation will be
reversed when terms are printed. For more details of interface maps, refer to
the DESCRIPTION. Note that each call of {\small\verb%set_interface_map%} starts from
scratch; it is not possible to augment a previous interface map by a second
call.

\FAILURE
The call will fail if the given map is invalid, for one of the following
reasons: if any of the {\small\verb%c%}'s are not the names of existing constants,
or if the map has multiple {\small\verb%c%}'s corresponding to a single {\small\verb%a%} or vice versa,
or if one of the {\small\verb%a%}'s is a constant name which is not redefined by the map
(this would create a confusing interface where two different constants would
have to be printed identically).

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#set_interface_map[`and`,`/\\`; `or`,`\\/`];;
[] : (string # string) list

#"T and F";;
"T and F" : term

#set_flag(`interface_print`,false);;
true : bool

#"T and F";;
"T /\ F" : term
\end{verbatim}
}
\SEEALSO
interface_map.

\ENDDOC
\DOC{set\_lambda}

\TYPE {\small\verb%set_lambda : (string -> string)%}\egroup

\SYNOPSIS
Sets the `lambda' symbol used in printing terms.

\DESCRIBE
If {\small\verb%s%} is a string, then {\small\verb%set_lambda s%} sets to {\small\verb%s%} the `lambda' symbol (by
default `{\small\verb%\%}') which is used to represent lambda-abstraction in terms.
The call returns the previous string used for this purpose. The call affects
the printing of terms, but the original symbol is still expected by the
quotation parser.

\FAILURE
Never fails.

\EXAMPLE
In the following, the lambda symbol is set to `{\small\verb%fn%}', and the effect on the
printing of a typical term is illustrated.
{\par\samepage\setseps\small
\begin{verbatim}
   #set_lambda `fn`;;
   `\` : string

   #"\x. SUC x";;
   "fn x. SUC x" : term
\end{verbatim}
}
\SEEALSO
set_prompt, set_turnstile.

\ENDDOC
\DOC{set\_library\_search\_path}

\TYPE {\small\verb%set_library_search_path : (string list -> void)%}\egroup

\SYNOPSIS
Sets the internal search path use by HOL to find libraries.

\DESCRIBE
When applied to a list of strings {\small\verb%l%}, each of which represents the pathname to
a directory, {\small\verb%set_library_search_path%} sets the internal search path used when
the {\small\verb%load_library%} function searches for library load files to the list {\small\verb%l%}.
Although the library search path can be set to an arbitrary list of strings,
each string is normally expected to be a pathname with `{\small\verb%/%}' as its final
character.  When {\small\verb%load_library%} looks for a library load file, the directories
in the search path are searched in the order in which they occur in the list
supplied to {\small\verb%set_library_search_path%}.

\FAILURE
Never fails.

\EXAMPLE 
The following call adds a user's local library directory {\small\verb%~/hol/lib/%} to the
library search path:
{\par\samepage\setseps\small
\begin{verbatim}
   set_library_search_path (union [`~/hol/lib/`] (library_search_path()));;
\end{verbatim}
}
\noindent Users with local libraries would typically have a line of this form
in their {\small\verb%hol-init%} file. Note that the function {\small\verb%union%} is used to avoid
multiple occurrences of the same pathname in the library search path.

\SEEALSO
library_pathname, library_search_path, load_library.

\ENDDOC
\DOC{set\_margin}

\TYPE {\small\verb%set_margin : (int -> int)%}\egroup

\SYNOPSIS
Changes the limit on the width of the output produced by the pretty-printer.

\DESCRIBE
{\small\verb%set_margin i%} sets the limit on the width of the output produced by the
pretty-printer to the integer {\small\verb%i%}. The pretty-printer will try to avoid
exceeding this limit by breaking the text into multiple lines. However it can
only break at points specified by the functions that send text to it. The
result of a call to {\small\verb%set_margin%} is the value to which the margin was
previously set.

\FAILURE
Never fails.

\USES
Obtaining readable output when using a text window of non-standard width.
It is a good idea to set the margin to a few characters less than the actual
width of the window; for example the default is 72 for an 80 character wide
display.

\SEEALSO
print_begin, print_end, print_newline, print_break.

\ENDDOC
\DOC{set\_pretty\_mode}

\TYPE {\small\verb%set_pretty_mode : (bool -> void)%}\egroup

\SYNOPSIS
Initializes the pretty-printer.

\DESCRIBE
{\small\verb%set_pretty_mode true%} causes all remaining text in the print queue to be
printed, and then the pretty-printer is reinitialized.

\FAILURE
Never fails.

\COMMENTS
{\small\verb%set_pretty_mode false%} should turn the pretty-printer off after printing all
text in the queue, but the current implementation does not do this.

\SEEALSO
print_begin, print_end, print_newline.

\ENDDOC
\DOC{set\_prompt}

\TYPE {\small\verb%set_prompt : (string -> string)%}\egroup

\SYNOPSIS
Changes the ML prompt string.

\DESCRIBE
If {\small\verb%s%} is a string, then {\small\verb%set_prompt s%} sets the ML prompt (which is `{\small\verb%#%}' by
default) to the string {\small\verb%s%}, and returns the previous prompt string. The string
may contain newlines, or be null (although {\small\verb%prompt false%} is a cleaner way of
completely eliminating the prompt).

\FAILURE
Never fails.

\EXAMPLE
In the following session, the prompt is set to {\small\verb%`Ready`%} on a line of its own,
then reset to its original state.
{\par\samepage\setseps\small
\begin{verbatim}
   #let oldprompt = set_prompt `Ready\
   #`;;
   oldprompt = `#` : string

   Ready
   do set_prompt oldprompt;;
   () : void

   # ...more ML...
\end{verbatim}
}
\SEEALSO
prompt, set_lambda, set_turnstile.

\ENDDOC
\DOC{set\_search\_path}

\TYPE {\small\verb%set_search_path : (string list -> void)%}\egroup

\SYNOPSIS
Sets the internal search path used by HOL to find files.

\DESCRIBE
When applied to a list of strings {\small\verb%l%}, each of which represents a directory
pathname, {\small\verb%set_search_path%} sets the internal search path used when HOL makes
access to files on disk to the list {\small\verb%l%}. Although the search path can be set to
an arbitrary list of strings, each string in the search path is normally
expected to be either empty ({\small\verb%``%}) or a pathname with `{\small\verb%/%}' as its final
character.  When HOL looks for a file, the directories in the search path are
searched in the order in which they occur in the list supplied to
{\small\verb%set_search_path%}.

\FAILURE
Never fails.

\EXAMPLE
A typical search path is the following:
{\par\samepage\setseps\small
\begin{verbatim}
   #search_path();;
   [``; `~/`; `/usr/lib/hol/theories/`] : string list
\end{verbatim}
}
\noindent With this search path, HOL first looks for a file in the current
working directory (the pathname represented by {\small\verb%``%}), then in the user`s home
directory {\small\verb%`~/`%}, and finally in the directory {\small\verb%`/usr/lib/hol/theories/`%} (the
directory containing HOL`s built-in theories).

One might augment this search path by doing:
{\par\samepage\setseps\small
\begin{verbatim}
   #set_search_path(`/foo/bar/` . search_path());;
   () : void
\end{verbatim}
}
\noindent so that the directory {\small\verb%/foo/bar/%} is also searched, and searched
first, when HOL tries to find a file.

\SEEALSO
help_search_path, install, search_path, set_help_search_path.

\ENDDOC
\DOC{set\_state}

\TYPE {\small\verb%set_state : (goalstack -> void)%}\egroup

\SYNOPSIS
Sets the current proof state of the subgoal package to the one given.

\DESCRIBE
The function {\small\verb%set_state%} is part of the subgoal package. It restores the
current proof state to one previously saved (using {\small\verb%get_state%}). The restored
state will include all unproven subgoals or, if the original goal had been
proved before the state was saved, the corresponding theorem. The old proof
state is placed on the backup list. For a description of the subgoal package,
see  {\small\verb%set_goal%}.

\USES
Providing additional backup. Pausing in the proof of a goal to allow  lemmas to
be proved. {\small\verb%set_state%} is used in conjunction with {\small\verb%get_state%}.

\EXAMPLE
The current state may be  bound to an ML variable ({\small\verb%main_proof%} in this
example) using {\small\verb%get_state%}.
{\par\samepage\setseps\small
\begin{verbatim}
   #g "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])";;
   "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

   () : void

   #let main_proof = get_state();;
   main_proof = - : goalstack
\end{verbatim}
}
\noindent Other goals may now be set and proved. The proof state may later be
restored using {\small\verb%set_state%} and the original proof continued.
{\par\samepage\setseps\small
\begin{verbatim}
   #set_state main_proof;;
   "(HD[1;2;3] = 1) /\ (TL[1;2;3] = [2;3])"

   () : void
\end{verbatim}
}
\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, top_goal, top_thm.

\ENDDOC
\DOC{set\_sticky\_type}

\TYPE {\small\verb%set_sticky_type : ((string # type) -> void)%}\egroup

\SYNOPSIS
Gives a particular sticky type to a named variable.

\DESCRIBE
A call {\small\verb%set_sticky_type(`name`,":ty")%} will give the name {\small\verb%name%} a sticky type
{\small\verb%ty%}. This means that if {\small\verb%name%} occurs in a quotation with a completely
unconstrained type (in particular, the sticky type will not be used if the name
is that of a constant), the type {\small\verb%ty%} is automatically inferred. For further
details of the sticky type mechanism, refer to the DESCRIPTION.

\FAILURE
Never fails, even if the name could not be the name of a variable or constant.
It is permissible to redefine a sticky type.

\EXAMPLE
The following shows how the sticky type is used only when the type of the
variable is unconstrained by context.
{\par\samepage\setseps\small
\begin{verbatim}
  #set_sticky_type(`n`,":num");;
  () : void

  #"n = n";;
  "n = n" : term

  #type_of (snd (dest_eq it));;
  ":num" : type

  #"HD [F] = n";;
  "HD[F] = n" : term

  #type_of (snd (dest_eq it));;
  ":bool" : type
\end{verbatim}
}
\COMMENTS
If the flag {\small\verb%sticky%} is set, the name is liable to have its sticky type
changed automatically, just like any other name.

\SEEALSO
remove_sticky_type, sticky_list.

\ENDDOC
\DOC{set\_string\_escape}

\TYPE {\small\verb%set_string_escape : (int -> int)%}\egroup

\SYNOPSIS
Changes the escape character inside strings.

\DESCRIBE
{\small\verb%set_string_escape n%} changes the escape character in strings to be the
character with ascii code {\small\verb%n%}. The previous character code is returned.
Initially the escape is ascii 92 (i.e. `{\small\verb%\%}'). If {\small\verb%n%} is not an ascii code
then there is no escape character available.

\FAILURE
Never fails (not even if the supplied code is not an ascii code).

\ENDDOC
\DOC{set\_thm\_count}

\TYPE {\small\verb%set_thm_count : (int -> int)%}\egroup

\SYNOPSIS
Sets the theorem-counter to the given value.

\DESCRIBE
HOL maintains a counter which is incremented every time a primitive inference
is performed (including when an axiom or definition set up). A call to
{\small\verb%set_thm_count%} sets the counter to a particular value, returning the previous
value.

\FAILURE
Never fails.

\SEEALSO
thm_count, timer.

\ENDDOC
\DOC{set\_turnstile}

\TYPE {\small\verb%set_turnstile : (string -> string)%}\egroup

\SYNOPSIS
Sets the `turnstile' symbol used in printing theorems.

\DESCRIBE
If {\small\verb%s%} is a string, then {\small\verb%set_turnstile s%} sets to {\small\verb%s%} the `turnstile' symbol
(by default `{\small\verb%|- %}') which is used to represent entailment, i.e. to separate
assumptions from conclusion when printing a theorem. The call returns the
previous string used for the turnstile.

\FAILURE
Never fails.

\EXAMPLE
The following shows the turnstile being set to `{\small\verb%|= %}'. A space is necessary
at the end to separate the conclusion neatly, but not at the beginning.
{\par\samepage\setseps\small
\begin{verbatim}
   #set_turnstile `|= `;;
   `|- ` : string

   #ASSUME "F";;
   . |= F
\end{verbatim}
}
\SEEALSO
set_lambda, set_prompt.

\ENDDOC
\DOC{show\_types}

\TYPE {\small\verb%show_types : (bool -> bool)%}\egroup

\SYNOPSIS
Turns printing of HOL types (in terms) on/off.

\DESCRIBE
Normally HOL types in terms are not printed, since this makes terms hard to
read. Type printing is enabled by {\small\verb%show_types true%}, and disabled by
{\small\verb%show_types false%}. When printing of types is enabled, not all variables and
constants are annotated with a type. The intention is to provide sufficient
type information to remove any ambiguities without swamping the term with type
information.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#BOOL_CASES_AX;;
|- !t. (t = T) \/ (t = F)

#show_types true;;
false : bool

#BOOL_CASES_AX;;
|- !(t:bool). (t = T) \/ (t = F)
\end{verbatim}
}
\COMMENTS
It is possible to construct an abstraction in which the bound variable has the
same name but a different type to a variable in the body. In such a case the
two variables are considered to be distinct. Without type information such a
term can be very misleading, so it might be a good idea to provide type
information for the free variable whether or not printing of types is enabled.

\SEEALSO
print_term.

\ENDDOC
\DOC{SKOLEM\_CONV}

\TYPE {\small\verb%SKOLEM_CONV : conv%}\egroup

\SYNOPSIS
Proves the existence of a Skolem function.

\DESCRIBE
When applied to an argument of the form {\small\verb%!x1...xn. ?y. P%}, the conversion
{\small\verb%SKOLEM_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x1...xn. ?y. P) = (?y'. !x1...xn. P[y' x1 ... xn/y])
\end{verbatim}
}
\noindent where {\small\verb%y'%} is a primed variant of {\small\verb%y%} not free in the input term.

\FAILURE
{\small\verb%SKOLEM_CONV tm%} fails unless {\small\verb%tm%} is a term of the form {\small\verb%!x1...xn. ?y. P%},
with at least one universally quantified variable.

\SEEALSO
X_SKOLEM_CONV.

\ENDDOC
\DOC{snd}

\TYPE {\small\verb%snd : ((* # **) -> **)%}\egroup

\SYNOPSIS
Extracts the second component of a pair.

\DESCRIBE
{\small\verb%snd (x,y)%} returns {\small\verb%y%}.

\FAILURE
Never fails.

\SEEALSO
fst, pair.

\ENDDOC
\DOC{SNOC\_CONV}

\TYPE {\small\verb%SNOC_CONV : conv%}\egroup

\SYNOPSIS
Computes by inference the result of adding an element to the tail end of a list.

\DESCRIBE
{\small\verb%SNOC_CONV%} a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   SNOC x [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- SNOC x [x0;...xn] = [x0;...xn;x]
\end{verbatim}
}
\noindent where the right-hand side is the list in the canonical form,
i.e., constructed with only the constructor {\small\verb%CONS%}.

\FAILURE
{\small\verb%SNOC_CONV tm%} fails if {\small\verb%tm%} is not of the form described above.

\EXAMPLE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   SNOC_CONV "SNOC 5[0;1;2;3;4]";;
\end{verbatim}
}
\noindent returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- SNOC 5[0;1;2;3;4] = [0;1;2;3;4;5]
\end{verbatim}
}

\SEEALSO
FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{SNOC\_INDUCT\_TAC}

\TYPE {\small\verb%SNOC_INDUCT_TAC : tactic%}\egroup

\SYNOPSIS
Performs tactical proof by structural induction on lists.

\DESCRIBE
{\small\verb%SNOC_INDUCT_TAC%} reduces a goal {\small\verb%!l.P[l]%}, where {\small\verb%l%} ranges over lists, to two
subgoals corresponding to the base and step cases in a proof by structural
induction on {\small\verb%l%} from the tail end. The induction hypothesis appears
among the assumptions of the subgoal for the step case.  The
specification of {\small\verb%SNOC_INDUCT_TAC%} is: 
{\par\samepage\setseps\small
\begin{verbatim}
                     A ?- !l. P
   =====================================================  SNOC_INDUCT_TAC
    A |- P[NIL/l]   A u {P[l'/l]} ?- !x. P[SNOC x l'/l]
\end{verbatim}
}
\noindent where {\small\verb%l'%} is a primed variant of {\small\verb%l%} that does not appear free in
the assumptions {\small\verb%A%} (usually, {\small\verb%l'%} is just {\small\verb%l%}). When {\small\verb%SNOC_INDUCT_TAC%} is
applied to a goal of the form {\small\verb%!l.P%}, where {\small\verb%l%} does not appear free in {\small\verb%P%},
the subgoals are just {\small\verb%A ?- P%} and {\small\verb%A u {P} ?- !h.P%}.

\FAILURE
{\small\verb%SNOC_INDUCT_TAC g%} fails unless the conclusion of the goal {\small\verb%g%} has the form
{\small\verb%!l.t%}, where the variable {\small\verb%l%} has type {\small\verb%(ty)list%} for some type {\small\verb%ty%}.

\SEEALSO
LIST_INDUCT, LIST_INDUCT_TAC.

\ENDDOC
\DOC{SOME\_EL\_CONV}

\TYPE {\small\verb%SOME_EL_CONV : conv -> conv%}\egroup

\SYNOPSIS
Computes by inference the result of applying a predicate to elements of a list.

\DESCRIBE
{\small\verb%SOME_EL_CONV%} takes a conversion {\small\verb%conv%} and a term {\small\verb%tm%} in the following form:
{\par\samepage\setseps\small
\begin{verbatim}
   SOME_EL P [x0;...xn]
\end{verbatim}
}
\noindent It returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- SOME_EL P [x0;...xn] = F
\end{verbatim}
}
\noindent if for every {\small\verb%xi%} occurred in the list, {\small\verb%conv "P xi"%}
returns a theorem {\small\verb%|- P xi = F%}, otherwise, if for at least one {\small\verb%xi%},
evaluating {\small\verb%conv "P xi"%} returns the theorem {\small\verb%|- P xi = T%}, then it returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   |- SOME_EL P [x0;...xn] = T
\end{verbatim}
}

\FAILURE
{\small\verb%SOME_EL_CONV conv tm%} fails if {\small\verb%tm%} is not of the form described above, or
failure occurs when evaluating {\small\verb%conv "P xi"%} for some {\small\verb%xi%}.

\EXAMPLE
Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   SOME_EL_CONV bool_EQ_CONV "SOME_EL ($= T) [T;F;T]";;
\end{verbatim}
}
\noindent returns the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- SOME_EL($= T)[T;F;T] = T
\end{verbatim}
}
\noindent   In general, if the predicate {\small\verb%P%} is an explicit lambda abstraction
{\small\verb%(\x. P x)%}, the conversion should be in the form
{\par\samepage\setseps\small
\begin{verbatim}
   (BETA_CONV THENC conv')
\end{verbatim}
}

\SEEALSO
ALL_EL_CONV, IS_EL_CONV, FOLDL_CONV, FOLDR_CONV, list_FOLD_CONV.

\ENDDOC

\DOC{sort}

\TYPE {\small\verb%sort : (((* # *) -> bool) -> * list -> * list)%}\egroup

\SYNOPSIS
Sorts a list using a given transitive `ordering' relation.

\DESCRIBE
The call
{\par\samepage\setseps\small
\begin{verbatim}
   sort op list
\end{verbatim}
}
\noindent where {\small\verb%op%} is an (uncurried) transitive relation on the elements of
{\small\verb%list%}, will topologically sort the list, i.e. will permute it such that if
{\small\verb%x op y%} but not {\small\verb%y op x%} then {\small\verb%x%} will occur to the left of {\small\verb%y%} in the
sorted list. In particular if {\small\verb%op%} is a total order, the list will be sorted in
the usual sense of the word.

\FAILURE
Never fails.

\EXAMPLE
A simple example is:
{\par\samepage\setseps\small
\begin{verbatim}
   #sort $< [3; 1; 4; 1; 5; 9; 2; 6; 5; 3; 5; 8; 9; 7; 9];;
   [1; 1; 2; 3; 3; 4; 5; 5; 5; 6; 7; 8; 9; 9; 9] : int list
\end{verbatim}
}
\noindent The following example is a little more complicated. Note
that the `ordering' is not antisymmetric.
{\par\samepage\setseps\small
\begin{verbatim}
   #sort ($< o (fst # fst)) [(1,3); (7,11); (3,2); (3,4); (7,2); (5,1)];;
   [(1, 3); (3, 4); (3, 2); (5, 1); (7, 2); (7, 11)] : (int # int) list
\end{verbatim}
}
\ENDDOC
\DOC{SPEC\_ALL}

\TYPE {\small\verb%SPEC_ALL : (thm -> thm)%}\egroup

\SYNOPSIS
Specializes the conclusion of a theorem with its own quantified variables.

\DESCRIBE
When applied to a theorem {\small\verb%A |- !x1...xn. t%}, the inference rule {\small\verb%SPEC_ALL%}
returns the theorem {\small\verb%A |- t[x1'/x1]...[xn'/xn]%} where the {\small\verb%xi'%} are distinct
variants of the corresponding {\small\verb%xi%}, chosen to avoid clashes with any variables
free in the assumption list and with the names of constants. Normally {\small\verb%xi'%} is
just {\small\verb%xi%}, in which case {\small\verb%SPEC_ALL%} simply removes all universal quantifiers.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- !x1...xn. t
   ---------------------------  SPEC_ALL
    A |- t[x1'/x1]...[xn'/xn]
\end{verbatim}
}
\FAILURE
Never fails.

\EXAMPLE
The following example shows how variables are also renamed to avoid clashing
with the names of constants.
{\par\samepage\setseps\small
\begin{verbatim}
   #let v=mk_var(`T`,":bool") in ASSUME "!^v. ^v \/ ~^v";;
   !T. T \/ ~T |- !T. T \/ ~T

   #SPEC_ALL it;;
   !T. T \/ ~T |- T' \/ ~T'
\end{verbatim}
}
\SEEALSO
GEN, GENL, GEN_ALL, GEN_TAC, SPEC, SPECL, SPEC_ALL, SPEC_TAC.

\ENDDOC
\DOC{SPEC}

\TYPE {\small\verb%SPEC : (term -> thm -> thm)%}\egroup

\SYNOPSIS
Specializes the conclusion of a theorem.

\DESCRIBE
When applied to a term {\small\verb%u%} and a theorem {\small\verb%A |- !x. t%}, then {\small\verb%SPEC%} returns
the theorem {\small\verb%A |- t[u/x]%}. If necessary, variables will be renamed prior
to the specialization to ensure that {\small\verb%u%} is free for {\small\verb%x%} in {\small\verb%t%}, that is,
no variables free in {\small\verb%u%} become bound after substitution.
{\par\samepage\setseps\small
\begin{verbatim}
     A |- !x. t
   --------------  SPEC "u"
    A |- t[u/x]
\end{verbatim}
}
\FAILURE
Fails if the theorem's conclusion is not universally quantified, or if {\small\verb%x%} and
{\small\verb%u%} have different types.

\EXAMPLE
The following example shows how {\small\verb%SPEC%} renames bound variables if necessary,
prior to substitution: a straightforward substitution would result in the
clearly invalid theorem {\small\verb%|- ~y ==> (!y. y ==> ~y)%}.
{\par\samepage\setseps\small
\begin{verbatim}
   #let xv = "x:bool" and yv="y:bool" in
   #     (GEN xv o DISCH xv o GEN yv o DISCH yv) (ASSUME xv);;
   |- !x. x ==> (!y. y ==> x)

   #SPEC "~y" it;;
   |- ~y ==> (!y'. y' ==> ~y)
\end{verbatim}
}
\SEEALSO
ISPEC, SPECL, SPEC_ALL, SPEC_VAR, GEN, GENL, GEN_ALL.

\ENDDOC
\DOC{special\_symbols}

\TYPE {\small\verb%special_symbols : (void -> string list)%}\egroup

\SYNOPSIS
Returns a list of special symbols.

\DESCRIBE
An identifier, at the ML or object level, is either alphanumeric, e.g. {\small\verb%true%}
or {\small\verb%T%}, or consists of a special symbol which starts with a non-alphanumeric
character, e.g. {\small\verb%==>%} or {\small\verb%+%}. It is a consequence of the non-backtracking
implementation of lexical analysis that any (non-null) initial segment of a
special symbol is also a special symbol, so from the above we know that {\small\verb%==%}
and {\small\verb%=%} are. The function {\small\verb%special_symbols%} returns a list of special symbols;
all non-null initial prefixes of them are also special symbols.

\FAILURE
Never fails.

\SEEALSO
new_special_symbol.

\ENDDOC
\DOC{SPECL}

\TYPE {\small\verb%SPECL : (term list -> thm -> thm)%}\egroup

\SYNOPSIS
Specializes zero or more variables in the conclusion of a theorem.

\DESCRIBE
When applied to a term list {\small\verb%[u1;...;un]%} and a theorem
{\small\verb%A |- !x1...xn. t%}, the inference rule {\small\verb%SPECL%} returns the theorem
{\small\verb%A |- t[u1/x1]...[un/xn]%}, where the substitutions are made
sequentially left-to-right in the same way as for {\small\verb%SPEC%}, with the same
sort of alpha-conversions applied to {\small\verb%t%} if necessary to ensure that no
variables which are free in {\small\verb%ui%} become bound after substitution.
{\par\samepage\setseps\small
\begin{verbatim}
       A |- !x1...xn. t
   --------------------------  SPECL "[u1;...;un]"
     A |- t[u1/x1]...[un/xn]
\end{verbatim}
}
\noindent It is permissible for the term-list to be empty, in which case
the application of {\small\verb%SPECL%} has no effect.

\FAILURE
Fails unless each of the terms is of the same as that of the 
appropriate quantified variable in the original theorem.

\EXAMPLE
The following is a specialization of a theorem from theory {\small\verb%arithmetic%}.
{\par\samepage\setseps\small
\begin{verbatim}
   #let t = theorem `arithmetic` `LESS_EQ_LESS_EQ_MONO`;;
   t = |- !m n p q. m <= p /\ n <= q ==> (m + n) <= (p + q)

   #SPECL ["1"; "2"; "3"; "4"] t;;
   |- 1 <= 3 /\ 2 <= 4 ==> (1 + 2) <= (3 + 4)
\end{verbatim}
}
\SEEALSO
GEN, GENL, GEN_ALL, GEN_TAC, SPEC, SPEC_ALL, SPEC_TAC.

\ENDDOC
\DOC{SPEC\_TAC}

\TYPE {\small\verb%SPEC_TAC : ((term # term) -> tactic)%}\egroup

\SYNOPSIS
Generalizes a goal.

\DESCRIBE
When applied to a pair of terms {\small\verb%(u,x)%}, where {\small\verb%x%} is just a variable,
and a goal {\small\verb%A ?- t%}, the tactic {\small\verb%SPEC_TAC%} generalizes the goal to
{\small\verb%A ?- !x. t[x/u]%}, that is, all instances of {\small\verb%u%} are turned into {\small\verb%x%}.
{\par\samepage\setseps\small
\begin{verbatim}
        A ?- t
   =================  SPEC_TAC ("u","x")
    A ?- !x. t[x/u]
\end{verbatim}
}
\FAILURE
Fails unless {\small\verb%x%} is a variable with the same type as {\small\verb%u%}.

\USES
Removing unnecessary speciality in a goal, particularly as a prelude to
an inductive proof.

\SEEALSO
GEN, GENL, GEN_ALL, GEN_TAC, SPEC, SPECL, SPEC_ALL, STRIP_TAC.

\ENDDOC
\DOC{SPEC\_VAR}

\TYPE {\small\verb%SPEC_VAR : (thm -> (term # thm))%}\egroup

\SYNOPSIS
Specializes the conclusion of a theorem, returning the chosen variant.

\DESCRIBE
When applied to a theorem {\small\verb%A |- !x. t%}, the inference rule {\small\verb%SPEC_VAR%} returns
the term {\small\verb%x'%} and the theorem {\small\verb%A |- t[x'/x]%}, where {\small\verb%x'%} is a variant
of {\small\verb%x%} chosen to avoid free variable capture.
{\par\samepage\setseps\small
\begin{verbatim}
     A |- !x. t
   --------------  SPEC_VAR
    A |- t[x'/x]
\end{verbatim}
}
\FAILURE
Fails unless the theorem's conclusion is universally quantified.

\COMMENTS
This rule is very similar to plain {\small\verb%SPEC%}, except that it returns the
variant chosen, which may be useful information under some circumstances.

\SEEALSO
GEN, GENL, GEN_ALL, GEN_TAC, SPEC, SPECL, SPEC_ALL.

\ENDDOC
\DOC{split}

\TYPE {\small\verb%split : ((* # **) list -> (* list # ** list))%}\egroup

\SYNOPSIS
Converts a list of pairs into a pair of lists.

\DESCRIBE
{\small\verb%split [(x1,y1);...;(xn,yn)]%} returns {\small\verb%([x1;...;xn],[y1;...;yn])%}.

\FAILURE
Never fails.

\SEEALSO
combine, com.

\ENDDOC
\DOC{splitp}

\TYPE {\small\verb%splitp : ((* -> bool) -> * list -> (* list # * list))%}\egroup

\SYNOPSIS
Splits a list into a pair of lists according to a predicate.

\DESCRIBE
{\small\verb%splitp P [x1;...;xk;...;xn]%} returns {\small\verb%([x1;...;x(k-1)],[xk;...;xn])%}
where {\small\verb%xk%} is the first element satisfying the predicate {\small\verb%P%}.
If no element satisfies {\small\verb%P%}, {\small\verb%([x1;...;xn],[])%} is returned.

\FAILURE
Never fails.

\SEEALSO
split, partition, chop_list.

\ENDDOC
\DOC{sticky\_list}

\TYPE {\small\verb%sticky_list : (void -> (string # type) list)%}\egroup

\SYNOPSIS
Returns a list of the current sticky type settings.

\DESCRIBE
A call {\small\verb%sticky_list()%} will return a list of names and the associated sticky
types. This list can be changed explicitly via {\small\verb%set_sticky_type%} and
{\small\verb%remove_sticky_type%}, or if the flag {\small\verb%sticky%} is set, will be changed behind
the scenes as terms are parsed. For more details of the sticky type mechanism,
refer to the DESCRIPTION.

\FAILURE
Never fails.

\SEEALSO
remove_sticky_type, set_sticky_type.

\ENDDOC
\DOC{store\_binders}

\TYPE {\small\verb%store_binders : (term list -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{store\_definition}

\TYPE {\small\verb%store_definition : ((string # term) -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{string\_of\_int}

\TYPE {\small\verb%string_of_int : (int -> string)%}\egroup

\SYNOPSIS
Maps an integer to the corresponding decimal string.

\DESCRIBE
When given an integer, {\small\verb%string_of_int%} returns a string representing
the number in standard decimal notation, with a leading minus sign
if the number is negative, and no leading zeros.

\FAILURE
Never fails.

\SEEALSO
ascii, ascii_code, int_of_string.

\ENDDOC
\DOC{strip\_abs}

\TYPE {\small\verb%strip_abs : (term -> goal)%}\egroup

\SYNOPSIS
Iteratively breaks apart abstractions.

\DESCRIBE
{\small\verb%strip_abs "\x1 ... xn. t"%} returns {\small\verb%(["x1";...;"xn"],"t")%}. Note that
{\par\samepage\setseps\small
\begin{verbatim}
   strip_abs(list_mk_abs(["x1";...;"xn"],"t"))
\end{verbatim}
}
\noindent will not return {\small\verb%(["x1";...;"xn"],"t")%} if {\small\verb%t%} is an abstraction.

\FAILURE
Never fails.

\SEEALSO
list_mk_abs, dest_abs.

\ENDDOC
\DOC{STRIP\_ASSUME\_TAC}

\TYPE {\small\verb%STRIP_ASSUME_TAC : thm_tactic%}\egroup

\SYNOPSIS
Splits a theorem into a list of theorems and then adds them to the assumptions.

\DESCRIBE
Given a theorem {\small\verb%th%} and a goal {\small\verb%(A,t)%}, {\small\verb%STRIP_ASSUME_TAC th%} splits {\small\verb%th%} into
a list of theorems. This is done by recursively breaking conjunctions into
separate conjuncts, cases-splitting disjunctions, and eliminating existential
quantifiers by choosing arbitrary variables.  Schematically, the following
rules are applied:
{\par\samepage\setseps\small
\begin{verbatim}
           A ?- t
   ======================  STRIP_ASSUME_TAC (A' |- v1 /\ ... /\ vn)
    A u {v1,...,vn} ?- t

                A ?- t
   =================================  STRIP_ASSUME_TAC (A' |- v1 \/ ... \/ vn)
    A u {v1} ?- t ... A u {vn} ?- t

          A ?- t
   ====================  STRIP_ASSUME_TAC (A' |- ?x.v)
    A u {v[x'/x]} ?- t
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a variant of {\small\verb%x%}.

If the conclusion of {\small\verb%th%} is not a conjunction, a disjunction or an
existentially quantified term, the whole theorem {\small\verb%th%} is added to the
assumptions.

As assumptions are generated, they are examined to see if they solve the goal
(either by being alpha-equivalent to the conclusion of the goal or by deriving
a contradiction).

The assumptions of the theorem being split are not added to the assumptions of
the goal(s), but they are recorded in the proof.  This means that if {\small\verb%A'%} is
not a subset of the assumptions {\small\verb%A%} of the goal (up to alpha-conversion),
{\small\verb%STRIP_ASSUME_TAC (A'|-v)%} results in an invalid tactic.

\FAILURE
Never fails.

\EXAMPLE
When solving the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- m = 0 + m
\end{verbatim}
}
\noindent assuming the clauses for addition with
{\small\verb%STRIP_ASSUME_TAC ADD_CLAUSES%} results in the goal
{\par\samepage\setseps\small
\begin{verbatim}
  {m + (SUC n) = SUC(m + n), (SUC m) + n = SUC(m + n),
   m + 0 = m, 0 + m = m, m = 0 + m} ?- m = 0 + m
\end{verbatim}
}
\noindent while the same tactic directly solves the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- 0 + m = m
\end{verbatim}
}
\USES
{\small\verb%STRIP_ASSUME_TAC%} is used when applying a previously proved theorem to solve
a goal, or
when enriching its assumptions so that resolution, rewriting with assumptions
and other operations involving assumptions have more to work with.

\SEEALSO
ASSUME_TAC, CHOOSE_TAC, CHOOSE_THEN, CONJUNCTS_THEN, DISJ_CASES_TAC,
DISJ_CASES_THEN.

\ENDDOC
\DOC{strip\_comb}

\TYPE {\small\verb%strip_comb : (term -> (term # term list))%}\egroup

\SYNOPSIS
Iteratively breaks apart combinations (function applications).

\DESCRIBE
{\small\verb%strip_comb "t t1 ... tn"%} returns {\small\verb%("t",["t1";...;"tn"])%}. Note that
{\par\samepage\setseps\small
\begin{verbatim}
   strip_comb(list_mk_comb("t",["t1";...;"tn"]))
\end{verbatim}
}
\noindent will not return {\small\verb%("t",["t1";...;"tn"])%} if {\small\verb%t%} is a combination.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#strip_comb "x /\ y";;
("$/\", ["x"; "y"]) : (term # term list)

#strip_comb "T";;
("T", []) : (term # term list)
\end{verbatim}
}
\SEEALSO
list_mk_comb, dest_comb.

\ENDDOC
\DOC{strip\_exists}

\TYPE {\small\verb%strip_exists : (term -> goal)%}\egroup

\SYNOPSIS
Iteratively breaks apart existential quantifications.

\DESCRIBE
{\small\verb%strip_exists "?x1 ... xn. t"%} returns {\small\verb%(["x1";...;"xn"],"t")%}. Note that
{\par\samepage\setseps\small
\begin{verbatim}
   strip_exists(list_mk_exists(["x1";...;"xn"],"t"))
\end{verbatim}
}
\noindent will not return {\small\verb%(["x1";...;"xn"],"t")%} if {\small\verb%t%} is an existential
quantification.

\FAILURE
Never fails.

\SEEALSO
list_mk_exists, dest_exists.

\ENDDOC
\DOC{strip\_forall}

\TYPE {\small\verb%strip_forall : (term -> goal)%}\egroup

\SYNOPSIS
Iteratively breaks apart universal quantifications.

\DESCRIBE
{\small\verb%strip_forall "!x1 ... xn. t"%} returns {\small\verb%(["x1";...;"xn"],"t")%}. Note that
{\par\samepage\setseps\small
\begin{verbatim}
   strip_forall(list_mk_forall(["x1";...;"xn"],"t"))
\end{verbatim}
}
\noindent will not return {\small\verb%(["x1";...;"xn"],"t")%} if {\small\verb%t%} is a universal
quantification.

\FAILURE
Never fails.

\SEEALSO
list_mk_forall, dest_forall.

\ENDDOC
\DOC{STRIP\_GOAL\_THEN}

\TYPE {\small\verb%STRIP_GOAL_THEN : (thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Splits a goal by eliminating one outermost connective, applying the
given theorem-tactic to the antecedents of implications.

\DESCRIBE
Given a theorem-tactic {\small\verb%ttac%} and a goal {\small\verb%(A,t)%}, {\small\verb%STRIP_GOAL_THEN%} removes one
outermost occurrence of one of the connectives {\small\verb%!%}, {\small\verb%==>%}, {\small\verb%~%} or {\small\verb%/\%} from the
conclusion of the goal {\small\verb%t%}.  If {\small\verb%t%} is a universally quantified term, then
{\small\verb%STRIP_GOAL_THEN%} strips off the quantifier:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- !x.u
   ==============  STRIP_GOAL_THEN ttac
     A ?- u[x'/x]
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant that does not appear free in the
assumptions {\small\verb%A%}.  If {\small\verb%t%} is a conjunction, then {\small\verb%STRIP_GOAL_THEN%} simply splits
the conjunction into two subgoals:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- v /\ w
   =================  STRIP_GOAL_THEN ttac
    A ?- v   A ?- w
\end{verbatim}
}
\noindent If {\small\verb%t%} is an implication {\small\verb%"u ==> v"%} and if:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- v
  ===============  ttac (u |- u)
     A' ?- v'
\end{verbatim}
}
\noindent then:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- u ==> v
  ====================  STRIP_GOAL_THEN ttac
        A' ?- v'
\end{verbatim}
}
\noindent Finally, a negation {\small\verb%~t%} is treated as the implication {\small\verb%t ==> F%}.

\FAILURE
{\small\verb%STRIP_GOAL_THEN ttac (A,t)%} fails if {\small\verb%t%} is not a universally quantified term,
an implication, a negation or a conjunction.  Failure also occurs if the
application of {\small\verb%ttac%} fails, after stripping the goal.

\EXAMPLE
When solving the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (n = 1) ==> (n * n = n)
\end{verbatim}
}
\noindent a possible initial step is to apply
{\par\samepage\setseps\small
\begin{verbatim}
   STRIP_GOAL_THEN SUBST1_TAC
\end{verbatim}
}
\noindent thus obtaining the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- 1 * 1 = 1
\end{verbatim}
}
\USES
{\small\verb%STRIP_GOAL_THEN%} is used when manipulating intermediate results (obtained by
stripping outer connectives from a goal) directly, rather than as assumptions.

\SEEALSO
CONJ_TAC, DISCH_THEN, FILTER_STRIP_THEN, GEN_TAC, STRIP_ASSUME_TAC, STRIP_TAC.

\ENDDOC
\DOC{strip\_imp}

\TYPE {\small\verb%strip_imp : (term -> goal)%}\egroup

\SYNOPSIS
Iteratively breaks apart implications.

\DESCRIBE
{\small\verb%strip_imp "t1 ==> ( ... (tn ==> t)...)"%} returns {\small\verb%(["t1";...;"tn"],"t")%}.
Note that
{\par\samepage\setseps\small
\begin{verbatim}
   strip_imp(list_mk_imp(["t1";...;"tn"],"t"))
\end{verbatim}
}
\noindent will not return {\small\verb%(["t1";...;"tn"],"t")%} if {\small\verb%t%} is an implication.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#strip_imp "(T ==> F) ==> (T ==> F)";;
(["T ==> F"; "T"], "F") : goal
\end{verbatim}
}
\SEEALSO
list_mk_imp, dest_imp.

\ENDDOC
\DOC{strip\_pair}

\TYPE {\small\verb%strip_pair : (term -> term list)%}\egroup

\SYNOPSIS
Iteratively breaks apart tuples.

\DESCRIBE
{\small\verb%strip_pair("(t1,...,tn)")%} returns {\small\verb%["t1";...;"tn"]%}.
A term that is not a tuple is simply returned as the sole element of a list.
Note that
{\par\samepage\setseps\small
\begin{verbatim}
   strip_pair(list_mk_pair ["t1";...;"tn"])
\end{verbatim}
}
\noindent will not return {\small\verb%["t1";...;"tn"]%} if {\small\verb%tn%} is a pair or a tuple.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#list_mk_pair ["(1,2)";"(3,4)";"(5,6)"];;
"(1,2),(3,4),5,6" : term

#strip_pair it;;
["1,2"; "3,4"; "5"; "6"] : term list

#strip_pair "1";;
["1"] : term list
\end{verbatim}
}
\SEEALSO
list_mk_pair, dest_pair.

\ENDDOC
\DOC{STRIP\_TAC}

\TYPE {\small\verb%STRIP_TAC : tactic%}\egroup

\SYNOPSIS
Splits a goal by eliminating one outermost connective.

\DESCRIBE
Given a goal {\small\verb%(A,t)%}, {\small\verb%STRIP_TAC%} removes one outermost occurrence of one of the
connectives {\small\verb%!%}, {\small\verb%==>%}, {\small\verb%~%} or {\small\verb%/\%} from the conclusion of the goal {\small\verb%t%}.  If
{\small\verb%t%} is a universally quantified term, then {\small\verb%STRIP_TAC%} strips off the
quantifier:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- !x.u
   ==============  STRIP_TAC
     A ?- u[x'/x]
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant that does not appear free in the
assumptions {\small\verb%A%}.  If {\small\verb%t%} is a conjunction, then {\small\verb%STRIP_TAC%} simply splits the
conjunction into two subgoals:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- v /\ w
   =================  STRIP_TAC
    A ?- v   A ?- w
\end{verbatim}
}
\noindent If {\small\verb%t%} is an implication, {\small\verb%STRIP_TAC%} moves the antecedent into the
assumptions, stripping conjunctions, disjunctions and existential
quantifiers according to the following rules:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- v1 /\ ... /\ vn ==> v            A ?- v1 \/ ... \/ vn ==> v
   ============================        =================================
       A u {v1,...,vn} ?- v             A u {v1} ?- v ... A u {vn} ?- v

     A ?- ?x.w ==> v
   ====================
    A u {w[x'/x]} ?- v
\end{verbatim}
}
\noindent where {\small\verb%x'%} is a primed variant of {\small\verb%x%} that does not appear free in
{\small\verb%A%}. Finally, a negation {\small\verb%~t%} is treated as the implication {\small\verb%t ==> F%}.

\FAILURE
{\small\verb%STRIP_TAC (A,t)%} fails if {\small\verb%t%} is not a universally quantified term,
an implication, a negation or a conjunction.

\EXAMPLE
Applying {\small\verb%STRIP_TAC%} twice to the goal:
{\par\samepage\setseps\small
\begin{verbatim}
    ?- !n. m <= n /\ n <= m ==> (m = n)
\end{verbatim}
}
\noindent results in the subgoal:
{\par\samepage\setseps\small
\begin{verbatim}
   {n <= m, m <= n} ?- m = n
\end{verbatim}
}
\USES
When trying to solve a goal, often the best thing to do first
is {\small\verb%REPEAT STRIP_TAC%} to split the goal up into manageable pieces.

\SEEALSO
CONJ_TAC, DISCH_TAC, DISCH_THEN, GEN_TAC, STRIP_ASSUME_TAC, STRIP_GOAL_THEN.

\ENDDOC
\DOC{STRIP\_THM\_THEN}

\TYPE {\small\verb%STRIP_THM_THEN : thm_tactical%}\egroup

\SYNOPSIS
{\small\verb%STRIP_THM_THEN%} applies the given theorem-tactic using the result of
stripping off one outer connective from the given theorem.

\DESCRIBE
Given a theorem-tactic {\small\verb%ttac%}, a theorem {\small\verb%th%} whose conclusion is a
conjunction, a disjunction or an existentially quantified term, and a goal
{\small\verb%(A,t)%}, {\small\verb%STRIP_THM_THEN ttac th%} first strips apart the conclusion of {\small\verb%th%},
next applies {\small\verb%ttac%} to the theorem(s) resulting from the stripping and then
applies the resulting tactic to the goal.

In particular, when stripping a conjunctive theorem {\small\verb%A'|- u /\ v%}, the tactic
{\par\samepage\setseps\small
\begin{verbatim}
   ttac(u|-u) THEN ttac(v|-v)
\end{verbatim}
}
\noindent resulting from applying {\small\verb%ttac%} to the conjuncts, is applied to the
goal.  When stripping a disjunctive theorem {\small\verb%A'|- u \/ v%}, the tactics
resulting from applying {\small\verb%ttac%} to the disjuncts, are applied to split the goal
into two cases. That is, if
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t                           A ?- t
   =========  ttac (u|-u)    and    =========  ttac (v|-v)
    A ?- t1                          A ?- t2
\end{verbatim}
}
\noindent then:
{\par\samepage\setseps\small
\begin{verbatim}
         A ?- t
   ==================  STRIP_THM_THEN ttac (A'|- u \/ v)
    A ?- t1  A ?- t2
\end{verbatim}
}
\noindent When stripping an existentially quantified theorem {\small\verb%A'|- ?x.u%}, the
tactic {\small\verb%ttac(u|-u)%}, resulting from applying {\small\verb%ttac%} to the body of the
existential quantification, is applied to the goal.  That is, if:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   =========  ttac (u|-u)
    A ?- t1
\end{verbatim}
}
\noindent then:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- t
   =============  STRIP_THM_THEN ttac (A'|- ?x. u)
      A ?- t1
\end{verbatim}
}
The assumptions of the theorem being split are not added to the assumptions of
the goal(s) but are recorded in the proof.  If {\small\verb%A'%} is not a subset of the
assumptions {\small\verb%A%} of the goal (up to alpha-conversion), {\small\verb%STRIP_THM_THEN ttac th%}
results in an invalid tactic.

\FAILURE
{\small\verb%STRIP_THM_THEN ttac th%} fails if the conclusion of {\small\verb%th%} is not a conjunction,
a disjunction or an existentially quantified term.  Failure also occurs if the
application of {\small\verb%ttac%} fails, after stripping the outer connective from the
conclusion of {\small\verb%th%}.

\USES
{\small\verb%STRIP_THM_THEN%} is used enrich the assumptions of a goal with a stripped
version of a previously-proved theorem.

\SEEALSO
CHOOSE_THEN, CONJUNCTS_THEN, DISJ_CASES_THEN, STRIP_ASSUME_TAC.

\ENDDOC
\DOC{STRUCT\_CASES\_TAC}

\TYPE {\small\verb%STRUCT_CASES_TAC : thm_tactic%}\egroup

\SYNOPSIS
Performs very general structural case analysis.

\DESCRIBE
When it is applied to a theorem of the form:
{\par\samepage\setseps\small
\begin{verbatim}
   th = A' |- ?y11...y1m. (x=t1) /\ (B11 /\ ... /\ B1k) \/ ... \/
                ?yn1...ynp. (x=tn) /\ (Bn1 /\ ... /\ Bnp)
\end{verbatim}
}
\noindent in which there may be no existential quantifiers where a `vector' of
them is shown above, {\small\verb%STRUCT_CASES_TAC th%} splits a goal {\small\verb%A ?- s%} into {\small\verb%n%}
subgoals as follows:
{\par\samepage\setseps\small
\begin{verbatim}
                             A ?- s
   ===============================================================
    A u {B11,...,B1k} ?- s[t1/x] ... A u {Bn1,...,Bnp} ?- s[tn/x]
\end{verbatim}
}
\noindent that is, performs a case split over the possible constructions (the
{\small\verb%ti%}) of a term, providing as assumptions the given constraints, having
split conjoined constraints into separate assumptions. Note that unless {\small\verb%A'%}
is a subset of {\small\verb%A%}, this is an invalid tactic.

\FAILURE
Fails unless the theorem has the above form, namely a conjunction of
(possibly multiply existentially quantified) terms which assert the equality
of the same variable {\small\verb%x%} and the given terms.

\EXAMPLE
Suppose we have the goal:
{\par\samepage\setseps\small
\begin{verbatim}
  ?- ~(l:(*)list = []) ==> (LENGTH l) > 0
\end{verbatim}
}
\noindent then we can get rid of the universal quantifier from the
inbuilt list theorem {\small\verb%list_CASES%}:
{\par\samepage\setseps\small
\begin{verbatim}
   list_CASES = !l. (l = []) \/ (?t h. l = CONS h t)
\end{verbatim}
}
\noindent and then use {\small\verb%STRUCT_CASES_TAC%}. This amounts to applying the
following tactic:
{\par\samepage\setseps\small
\begin{verbatim}
   STRUCT_CASES_TAC (SPEC_ALL list_CASES)
\end{verbatim}
}
\noindent which results in the following two subgoals:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- ~(CONS h t = []) ==> (LENGTH(CONS h t)) > 0

   ?- ~([] = []) ==> (LENGTH[]) > 0
\end{verbatim}
}
\noindent Note that this is a rather simple case, since there are no
constraints, and therefore the resulting subgoals have no assumptions.

\USES
Generating a case split from the axioms specifying a structure.

\SEEALSO
ASM_CASES_TAC, BOOL_CASES_TAC, COND_CASES_TAC, DISJ_CASES_TAC.

\ENDDOC
\DOC{SUB\_CONV}

\TYPE {\small\verb%SUB_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion to the top-level subterms of a term.

\DESCRIBE
For any conversion {\small\verb%c%}, the function returned by {\small\verb%SUB_CONV c%} is a conversion
that applies {\small\verb%c%} to all the top-level subterms of a term.  If the conversion
{\small\verb%c%} maps {\small\verb%t%} to {\small\verb%|- t = t'%}, then {\small\verb%SUB_CONV c%} maps an abstraction {\small\verb%"\x.t"%} to
the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (\x.t) = (\x.t')
\end{verbatim}
}
\noindent That is, {\small\verb%SUB_CONV c "\x.t"%} applies {\small\verb%c%} to the body of the
abstraction {\small\verb%"\x.t"%}.  If {\small\verb%c%} is a conversion that maps {\small\verb%"t1"%} to the theorem
{\small\verb%|- t1 = t1'%} and {\small\verb%"t2"%} to the theorem {\small\verb%|- t2 = t2'%}, then the conversion
{\small\verb%SUB_CONV c%} maps an application {\small\verb%"t1 t2"%} to the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t1 t2) = (t1' t2')
\end{verbatim}
}
\noindent That is, {\small\verb%SUB_CONV c "t1 t2"%} applies {\small\verb%c%} to the both the operator
{\small\verb%t1%} and the operand {\small\verb%t2%} of the application {\small\verb%"t1 t2"%}.  Finally, for any
conversion {\small\verb%c%}, the function returned by {\small\verb%SUB_CONV c%} acts as the identity
conversion on variables and constants.  That is, if {\small\verb%"t"%} is a variable or
constant, then {\small\verb%SUB_CONV c "t"%} returns {\small\verb%|- t = t%}.

\FAILURE
{\small\verb%SUB_CONV c tm%} fails if {\small\verb%tm%} is an abstraction {\small\verb%"\x.t"%} and the conversion {\small\verb%c%}
fails when applied to {\small\verb%t%}, or if {\small\verb%tm%} is an application {\small\verb%"t1 t2"%} and the
conversion {\small\verb%c%} fails when applied to either {\small\verb%t1%} or {\small\verb%t2%}.  The function
returned by {\small\verb%SUB_CONV c%} may also fail if the ML function {\small\verb%c:term->thm%} is not,
in fact, a conversion (i.e. a function that maps a term {\small\verb%t%} to a theorem
{\small\verb%|- t = t'%}).

\SEEALSO
ABS_CONV, RAND_CONV, RATOR_CONV.

\ENDDOC
\DOC{SUBGOAL\_THEN}

\TYPE {\small\verb%SUBGOAL_THEN : (term -> thm_tactic -> tactic)%}\egroup

\SYNOPSIS
Allows the user to introduce a lemma.

\DESCRIBE
The user proposes a lemma and is then invited to prove it under
the current assumptions.
The lemma is then used with the {\small\verb%thm_tactic%} to simplify the goal.
That is, if
{\par\samepage\setseps\small
\begin{verbatim}
    A1 ?- t1
   ==========  f (u |- u)
    A2 ?- t2
\end{verbatim}
}
\noindent then
{\par\samepage\setseps\small
\begin{verbatim}
         A1 ?- t1
   ====================  SUBGOAL_THEN "u" f
    A1 ?- u   A2 ?- t2
\end{verbatim}
}
\FAILURE
{\small\verb%SUBGOAL_THEN%} will fail with {\small\verb%`ASSUME`%} if an attempt is made to use a
nonboolean term as a lemma.

\USES
When combined with {\small\verb%rotate%}, {\small\verb%SUBGOAL_THEN%} allows the user to defer some
part of a proof and to continue with another part.
{\small\verb%SUBGOAL_THEN%} is most convenient when the tactic solves the original goal,
leaving only the subgoal.
For example, suppose the user wishes top prove the goal
{\par\samepage\setseps\small
\begin{verbatim}
   {n = SUC m} ?- (0 = n) ==> t
\end{verbatim}
}
Using {\small\verb%SUBGOAL_THEN%} to focus on the case in which {\small\verb%~(n = 0)%},
rewriting establishes it truth, leaving only the proof that {\small\verb%~(n = 0)%}.
That is,
{\par\samepage\setseps\small
\begin{verbatim}
   SUBGOAL_THEN "~(0 = n)" (\th:thm. REWRITE_TAC [th])
\end{verbatim}
}
\noindent generates the following subgoals:
{\par\samepage\setseps\small
\begin{verbatim}
   {n = SUC m} ?-  ~(0 = n)
   ?- T
\end{verbatim}
}
\COMMENTS
Some users may expect the generated tactic to be {\small\verb%f (A1 |- u)%}, rather than
{\small\verb%f (u |- u)%}.

\ENDDOC
\DOC{SUBS}

\TYPE {\small\verb%SUBS : (thm list -> thm -> thm)%}\egroup

\SYNOPSIS
Makes simple term substitutions in a theorem using a given list of theorems.

\DESCRIBE
Term substitution in HOL is performed by replacing free subterms according to
the transformations specified by a list of equational theorems.  Given a list
of theorems {\small\verb%A1|-t1=v1,...,An|-tn=vn%} and a theorem {\small\verb%A|-t%}, {\small\verb%SUBS%}
simultaneously replaces each free occurrence of {\small\verb%ti%} in {\small\verb%t%} with {\small\verb%vi%}:
{\par\samepage\setseps\small
\begin{verbatim}
          A1|-t1=v1 ... An|-tn=vn    A|-t
   ---------------------------------------------  SUBS[A1|-t1=v1;...;An|-tn=vn]
    A1 u ... u An u A |- t[v1,...,vn/t1,...,tn]       (A|-t)
\end{verbatim}
}
\noindent No matching is involved; the occurrence of each {\small\verb%ti%} being
substituted for must be a free in {\small\verb%t%} (see {\small\verb%SUBST_MATCH%}).  An occurrence which
is not free can be substituted by using rewriting rules such as {\small\verb%REWRITE_RULE%},
{\small\verb%PURE_REWRITE_RULE%} and {\small\verb%ONCE_REWRITE_RULE%}.

\FAILURE
{\small\verb%SUBS [th1;...;thn] (A|-t)%} fails if the conclusion of each theorem in the list
is not an equation.  No change is made to the theorem {\small\verb%A |- t%} if no occurrence
of any left-hand side of the supplied equations appears in {\small\verb%t%}.

\EXAMPLE
Substitutions are made with the theorems
{\par\samepage\setseps\small
\begin{verbatim}
   #let thm1 = SPECL ["m:num"; "n:num"] ADD_SYM
   #and thm2 = CONJUNCT1 ADD_CLAUSES;;
   thm1 = |- m + n = n + m
   thm2 = |- 0 + m = m
\end{verbatim}
}
\noindent depending on the occurrence of free subterms
{\par\samepage\setseps\small
\begin{verbatim}
   #SUBS [thm1; thm2] (ASSUME "(n + 0) + (0 + m) = m + n");;
   . |- (n + 0) + m = n + m

   #SUBS [thm1; thm2] (ASSUME "!n. (n + 0) + (0 + m) = m + n");;
   . |- !n. (n + 0) + m = m + n
\end{verbatim}
}
\USES
{\small\verb%SUBS%} can sometimes be used when rewriting (for example, with {\small\verb%REWRITE_RULE%})
would diverge and term instantiation is not needed.  Moreover, applying the
substitution rules is often much faster than using the rewriting rules.

\SEEALSO
ONCE_REWRITE_RULE, PURE_REWRITE_RULE, REWRITE_RULE, SUBST, SUBST_MATCH,
SUBS_OCCS.

\ENDDOC
\DOC{SUBS\_OCCS}

\TYPE {\small\verb%SUBS_OCCS : ((int list # thm) list -> thm -> thm)%}\egroup

\SYNOPSIS
Makes substitutions in a theorem at specific occurrences of a term, using a
list of equational theorems.

\DESCRIBE
Given a list {\small\verb%(l1,A1|-t1=v1),...,(ln,An|-tn=vn)%} and a theorem
{\small\verb%(A|-t)%}, {\small\verb%SUBS_OCCS%} simultaneously replaces each {\small\verb%ti%} in {\small\verb%t%} with {\small\verb%vi%},
at the occurrences specified by the integers
in the list {\small\verb%li = [o1;...;ok]%} for each theorem {\small\verb%Ai|-ti=vi%}.
{\par\samepage\setseps\small
\begin{verbatim}
     (l1,A1|-t1=v1) ... (ln,An|-tn=vn)  A|-t
   -------------------------------------------  SUBS_OCCS[(l1,A1|-t1=v1);...;
    A1 u ... An u A |- t[v1,...,vn/t1,...,tn]            (ln,An|-tn=vn)] (A|-t)
\end{verbatim}
}
\FAILURE
{\small\verb%SUBS_OCCS [(l1,th1);...;(ln,thn)] (A|-t)%} fails if
the conclusion of any theorem in the list is not an equation.
No change is made to the theorem if the supplied occurrences {\small\verb%li%} of the
left-hand side of the conclusion of {\small\verb%thi%} do not appear in {\small\verb%t%}.

\EXAMPLE
The commutative law for addition
{\par\samepage\setseps\small
\begin{verbatim}
   #let thm = SPECL ["m:num"; "n:num"] ADD_SYM;;
   thm = |- m + n = n + m
\end{verbatim}
}
\noindent can be used for substituting only the second occurrence of
the subterm {\small\verb%m + n%}
{\par\samepage\setseps\small
\begin{verbatim}
   #SUBS_OCCS [([2],thm)] (ASSUME "(n + m) + (m + n) = (m + n) + (m + n)");;
   . |- (n + m) + (m + n) = (n + m) + (m + n)
\end{verbatim}
}
\USES
{\small\verb%SUBS_OCCS%} is used when rewriting at specific occurrences of a term, and rules
such as {\small\verb%REWRITE_RULE%}, {\small\verb%PURE_REWRITE_RULE%}, {\small\verb%ONCE_REWRITE_RULE%}, and {\small\verb%SUBS%}
are too extensive or would diverge.

\SEEALSO
ONCE_REWRITE_RULE, PURE_REWRITE_RULE, REWRITE_RULE, SUBS, SUBST, SUBST_MATCH.

\ENDDOC
\DOC{SUBST1\_TAC}

\TYPE {\small\verb%SUBST1_TAC : thm_tactic%}\egroup

\SYNOPSIS
Makes a simple term substitution in a goal using a single equational theorem.

\DESCRIBE
Given a theorem {\small\verb%A'|-u=v%} and a goal {\small\verb%(A,t)%}, the tactic
{\small\verb%SUBST1_TAC (A'|-u=v)%} rewrites the term {\small\verb%t%} into {\small\verb%t[v/u]%}, by substituting
{\small\verb%v%} for each free occurrence of {\small\verb%u%} in {\small\verb%t%}:
{\par\samepage\setseps\small
\begin{verbatim}
      A ?- t
   =============  SUBST1_TAC (A'|-u=v)
    A ?- t[v/u]
\end{verbatim}
}
\noindent The assumptions of the theorem used to substitute with are not added
to the assumptions of the goal but are recorded in the proof.  If {\small\verb%A'%} is not a
subset of the assumptions {\small\verb%A%} of the goal (up to alpha-conversion), then
{\small\verb%SUBST1_TAC (A'|-u=v)%} results in an invalid tactic.

{\small\verb%SUBST1_TAC%} automatically renames bound variables to prevent free variables in
{\small\verb%v%} becoming bound after substitution.

\FAILURE
{\small\verb%SUBST1_TAC th (A,t)%} fails if the conclusion of {\small\verb%th%} is not an equation.
No change is made to the goal if no free occurrence of the left-hand side
of {\small\verb%th%} appears in {\small\verb%t%}.

\EXAMPLE
When trying to solve the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- m * n = (n * (m - 1)) + n
\end{verbatim}
}
\noindent substituting with the commutative law for multiplication
{\par\samepage\setseps\small
\begin{verbatim}
   SUBST1_TAC (SPECL ["m:num"; "n:num"] MULT_SYM)
\end{verbatim}
}
\noindent results in the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- n * m = (n * (m - 1)) + n
\end{verbatim}
}
\USES
{\small\verb%SUBST1_TAC%} is used when rewriting with a single theorem using tactics such as
{\small\verb%REWRITE_TAC%} is too expensive or would diverge. Applying {\small\verb%SUBST1_TAC%} is also
much faster than using rewriting tactics.

\SEEALSO
ONCE_REWRITE_TAC, PURE_REWRITE_TAC, REWRITE_TAC, SUBST_ALL_TAC, SUBST_TAC.

\ENDDOC
\DOC{SUBST\_ALL\_TAC}

\TYPE {\small\verb%SUBST_ALL_TAC : thm_tactic%}\egroup

\SYNOPSIS
Substitutes using a single equation in both the assumptions and conclusion of a
goal.

\DESCRIBE
{\small\verb%SUBST_ALL_TAC%} breaches the style of natural deduction, where the assumptions
are kept fixed.  Given a theorem {\small\verb%A|-u=v%} and a goal {\small\verb%([t1;...;tn], t)%},
{\small\verb%SUBST_ALL_TAC (A|-u=v)%} transforms the assumptions {\small\verb%t1%},...,{\small\verb%tn%} and the term
{\small\verb%t%} into {\small\verb%t1[v/u]%},...,{\small\verb%tn[v/u]%} and {\small\verb%t[v/u]%} respectively, by substituting {\small\verb%v%}
for each free occurrence of {\small\verb%u%} in both the assumptions and the conclusion of
the goal.
{\par\samepage\setseps\small
\begin{verbatim}
           {t1,...,tn} ?- t
   =================================  SUBST_ALL_TAC (A|-u=v)
    {t1[v/u],...,tn[v/u]} ?- t[v/u]
\end{verbatim}
}
\noindent The assumptions of the theorem used to substitute with are not added
to the assumptions of the goal, but they are recorded in the proof.  If {\small\verb%A%} is
not a subset of the assumptions of the goal (up to alpha-conversion), then
{\small\verb%SUBST_ALL_TAC (A|-u=v)%} results in an invalid tactic.

{\small\verb%SUBST_ALL_TAC%} automatically renames bound variables to prevent
free variables in {\small\verb%v%} becoming bound after substitution.

\FAILURE
{\small\verb%SUBST_ALL_TAC th (A,t)%} fails if the conclusion of {\small\verb%th%} is not an equation.
No change is made to the goal if no occurrence of the left-hand side of
{\small\verb%th%} appears free in {\small\verb%(A,t)%}.

\EXAMPLE
Simplifying both the assumption and the term in the goal
{\par\samepage\setseps\small
\begin{verbatim}
   {0 + m = n} ?- 0 + (0 + m) = n
\end{verbatim}
}
\noindent by substituting with the theorem {\small\verb%|- 0 + m = m%} for addition
{\par\samepage\setseps\small
\begin{verbatim}
   SUBST_ALL_TAC (CONJUNCT1 ADD_CLAUSES)
\end{verbatim}
}
\noindent results in the goal
{\par\samepage\setseps\small
\begin{verbatim}
   {m = n} ?- 0 + m = n
\end{verbatim}
}
\SEEALSO
ONCE_REWRITE_TAC, PURE_REWRITE_TAC, REWRITE_TAC, SUBST1_TAC, SUBST_TAC.

\ENDDOC
\DOC{SUBST\_CONV}

\TYPE {\small\verb%SUBST_CONV : ((thm # term) list -> term -> conv)%}\egroup

\SYNOPSIS
Makes substitutions in a term at selected occurrences of subterms, using a list
of theorems.

\DESCRIBE
{\small\verb%SUBST_CONV%} implements the following rule of simultaneous substitution
{\par\samepage\setseps\small
\begin{verbatim}
                    A1 |- t1 = v1 ... An |- tn = vn
   ------------------------------------------------------------------
    A1 u ... u An |- t[t1,...,tn/x1,...,xn] = t[v1,...,vn/x1,...,xn]
\end{verbatim}
}
\noindent The first argument to {\small\verb%SUBST_CONV%} is a list
{\small\verb%[(A1|-t1=v1, x1);...;(An|-tn=vn, xn)]%}.
The second argument is a template term {\small\verb%t[x1,...,xn]%}, in which
the variables {\small\verb%x1,...,xn%} are used to mark those places where
occurrences of {\small\verb%t1,...,tn%} are to be replaced with the terms
{\small\verb%v1,...,vn%}, respectively.
Thus, evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   SUBST_CONV [(A1|-t1=v1, x1);...;(An|-tn=vn, xn)]
              t[x1,...,xn]
              t[t1,...,tn/x1,...,xn]
\end{verbatim}
}
\noindent returns the theorem
{\par\samepage\setseps\small
\begin{verbatim}
   A1 u ... u An |- t[t1,...,tn/x1,...,xn] = t[v1,...,vn/x1,...,xn]
\end{verbatim}
}
The occurrence of {\small\verb%ti%} at the places marked by the variable
{\small\verb%xi%} must be free (i.e. {\small\verb%ti%} must not contain any bound variables).
{\small\verb%SUBST_CONV%} automatically renames bound variables to prevent free
variables in {\small\verb%vi%} becoming bound after substitution.

\FAILURE
{\small\verb%SUBST_CONV [(th1,x1);...;(thn,xn)] t[x1,...,xn] t'%} fails if the conclusion of
any theorem {\small\verb%thi%} in the list is not an equation; or if the template
{\small\verb%t[x1,...,xn]%} does not match the term {\small\verb%t'%}; or if and term {\small\verb%ti%} in {\small\verb%t'%}
marked by the variable {\small\verb%xi%} in the template, is not identical to the left-hand
side of the conclusion of the theorem {\small\verb%thi%}.

\EXAMPLE
The theorems
{\par\samepage\setseps\small
\begin{verbatim}
   #let thm0 = SPEC "0" ADD1 and thm1 = SPEC "1" ADD1;;
   thm0 = |- SUC 0 = 0 + 1
   thm1 = |- SUC 1 = 1 + 1
\end{verbatim}
}
\noindent can be used to substitute selected occurrences of the terms {\small\verb%SUC 0%}
and {\small\verb%SUC 1%}
{\par\samepage\setseps\small
\begin{verbatim}
   #SUBST_CONV [(thm0,"x:num");(thm1,"y:num")]
   #           "(x + y) > SUC 1"
   #           "(SUC 0 + SUC 1) > SUC 1";;
   |- ((SUC 0) + (SUC 1)) > (SUC 1) = ((0 + 1) + (1 + 1)) > (SUC 1)
\end{verbatim}
}
\USES
{\small\verb%SUBST_CONV%} is used when substituting at selected occurrences of terms
and using rewriting rules/conversions is too extensive.

\SEEALSO
REWR_CONV, SUBS, SUBST, SUBS_OCCS.

\ENDDOC
\DOC{subst}

\TYPE {\small\verb%subst : ((term # term) list -> term -> term)%}\egroup

\SYNOPSIS
Substitutes terms in a term.

\DESCRIBE
Given a list of term pairs {\small\verb%[("a_1","b_1"),...,("a_n","b_n")]%}
and a term {\small\verb%"c"%}, {\small\verb%subst%} attempts to substitute  all free occurrences of
{\small\verb%"b_i"%} in {\small\verb%"c"%} by {\small\verb%"a_i"%} for all {\small\verb%i%} ranging between {\small\verb%1%} and {\small\verb%n%}.

\FAILURE
Failure occurs if for some {\small\verb%i%} ranging between {\small\verb%1%} and {\small\verb%n%}, the substitution
of {\small\verb%"b_i"%} by {\small\verb%"a_i"%} fails.
The substitution of  {\small\verb%"b_i"%} by {\small\verb%"a_i"%} fails for some {\small\verb%i%},
if the types of {\small\verb%"a_i"%} and  {\small\verb%"b_i"%} are not the same.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #subst [("1","SUC 0")] "SUC(SUC 0)";;
   "SUC 1" : term

   #subst [("1","SUC 0");("2","SUC 1")] "SUC(SUC 0)";;
   "SUC 1" : term

   #subst [("1","SUC 0");("2","SUC 1")] "SUC(SUC 0) = SUC 1";;
   "SUC 1 = 2" : term

   #subst [("b:num","a:num")] "\a:num. (b:num)";;
   "\a. b" : term

   #subst [("foo:*","flip:*")] "waddle:*";;
   "waddle" : term
\end{verbatim}
}
\ENDDOC
\DOC{SUBST}

\TYPE {\small\verb%SUBST : ((thm # term) list -> term -> thm -> thm)%}\egroup

\SYNOPSIS
Makes a set of parallel substitutions in a theorem.

\DESCRIBE
Implements the following rule of simultaneous substitution
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1 = u1 ,  ... , An |- tn = un ,    A |- t[t1,...,tn]
   -------------------------------------------------------------
                  A u A1 u ... u An |- t[ui]
\end{verbatim}
}
\noindent Evaluating
{\par\samepage\setseps\small
\begin{verbatim}
   SUBST [((A1 |- t1=u1), x1); ... ;((An |- tn=un), xn)]
         t[x1,...,xn]
         (A |- t[t1,...,tn])
\end{verbatim}
}
\noindent returns the theorem {\small\verb%A |- t[u1,...,un]%}.  The term argument
{\small\verb%t[x1,...,xn]%} is a template which should match the conclusion of the theorem
being substituted into, with the variables {\small\verb%x1%}, ... , {\small\verb%xn%} marking those
places where occurrences of {\small\verb%t1%}, ... , {\small\verb%tn%} are to be replaced by the terms
{\small\verb%u1%}, ... , {\small\verb%un%}, respectively.  The occurrence of {\small\verb%ti%} at the places marked by
{\small\verb%xi%} must be free (i.e. {\small\verb%ti%} must not contain any bound variables).  {\small\verb%SUBST%}
automatically renames bound variables to prevent free variables in {\small\verb%ui%}
becoming bound after substitution.

{\small\verb%SUBST%} is a complex primitive because it performs both parallel simultaneous
substitution and renaming of variables. This is for efficiency reasons, but it
would be logically cleaner if {\small\verb%SUBST%} were simpler.

\FAILURE
If the template does not match the conclusion of the hypothesis, or the terms
in the conclusion marked by the variables {\small\verb%x1%}, ... , {\small\verb%xn%} in the template are
not identical to the left hand sides of the supplied equations (i.e. the terms
{\small\verb%t1%}, ... , {\small\verb%tn%}).

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#let th0 = SPEC "0" ADD1 and th1 = SPEC "1" ADD1;;
th0 = |- SUC 0 = 0 + 1
th1 = |- SUC 1 = 1 + 1

#SUBST [(th0,"x:num");(th1,"y:num")]
#      "(x+y) > SUC 0"
#      (ASSUME "(SUC 0 + SUC 1) > SUC 0");;
. |- ((0 + 1) + (1 + 1)) > (SUC 0)

#SUBST [(th0,"x:num");(th1,"y:num")]
#      "(SUC 0 + y) > SUC 0"
#      (ASSUME "(SUC 0 + SUC 1) > SUC 0");;
. |- ((SUC 0) + (1 + 1)) > (SUC 0)

#SUBST [(th0,"x:num");(th1,"y:num")]
#      "(x+y) > x"
#      (ASSUME "(SUC 0 + SUC 1) > SUC 0");;
. |- ((0 + 1) + (1 + 1)) > (0 + 1)
\end{verbatim}
}
\USES
For substituting at selected occurrences. Often useful
for writing special purpose derived inference rules.

\SEEALSO
SUBS.

\ENDDOC
\DOC{SUBST\_MATCH}

\TYPE {\small\verb%SUBST_MATCH : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Substitutes in one theorem using another, equational, theorem.

\DESCRIBE
Given the theorems {\small\verb%A|-u=v%} and {\small\verb%A'|-t%}, {\small\verb%SUBST_MATCH (A|-u=v) (A'|-t)%}
searches for one free instance of {\small\verb%u%} in {\small\verb%t%}, according to a top-down
left-to-right search strategy, and then substitutes the corresponding instance
of {\small\verb%v%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- u=v   A' |- t
   --------------------  SUBST_MATCH (A|-u=v) (A'|-t)
     A u A' |- t[v/u]
\end{verbatim}
}
\noindent {\small\verb%SUBST_MATCH%} allows only a free instance of {\small\verb%u%} to be substituted
for in {\small\verb%t%}. An instance which contain bound variables can be substituted for by
using rewriting rules such as {\small\verb%REWRITE_RULE%}, {\small\verb%PURE_REWRITE_RULE%} and
{\small\verb%ONCE_REWRITE_RULE%}.

\FAILURE
{\small\verb%SUBST_MATCH th1 th2%} fails if the conclusion of the theorem {\small\verb%th1%} is not an
equation.  Moreover, {\small\verb%SUBST_MATCH (A|-u=v) (A'|-t)%} fails if no instance of {\small\verb%u%}
occurs in {\small\verb%t%}, since the matching algorithm fails.  No change is made to the
theorem {\small\verb%(A'|-t)%} if instances of {\small\verb%u%} occur in {\small\verb%t%}, but they are not free (see
{\small\verb%SUBS%}).

\EXAMPLE
The commutative law for addition
{\par\samepage\setseps\small
\begin{verbatim}
   #let thm1 = SPECL ["m:num"; "n:num"] ADD_SYM;;
   thm1 = |- m + n = n + m
\end{verbatim}
}
\noindent is used to apply substitutions, depending on the occurrence of free
instances
{\par\samepage\setseps\small
\begin{verbatim}
   #SUBST_MATCH thm1 (ASSUME "(n + 1) + (m - 1) = m + n");;
   . |- (m - 1) + (n + 1) = m + n

   #SUBST_MATCH thm1 (ASSUME "!n. (n + 1) + (m - 1) = m + n");;
   . |- !n. (n + 1) + (m - 1) = m + n
\end{verbatim}
}
\USES
{\small\verb%SUBST_MATCH%} is used when rewriting with the rules such as {\small\verb%REWRITE_RULE%},
using a single theorem is too extensive or would diverge.  Moreover, applying
{\small\verb%SUBST_MATCH%} can be much faster than using the rewriting rules.

\SEEALSO
ONCE_REWRITE_RULE, PURE_REWRITE_RULE, REWRITE_RULE, SUBS, SUBST.

\ENDDOC
\DOC{subst\_occs}

\TYPE {\small\verb%subst_occs : (int list list -> (term # term) list -> term -> term)%}\egroup

\SYNOPSIS
Substitutes for particular occurrences of subterms of a given term.

\DESCRIBE
For each substitution pair {\small\verb%("a_i","b_i")%} in the second argument,
there should be a corresponding integer list {\small\verb%l_i%} in the first argument
that specifies which free occurrences of {\small\verb%"b_i"%} in the third argument should
be substituted by {\small\verb%"a_i"%}.

\FAILURE
Failure occurs if any substitution fails, or if the size of
the first argument is not equal to the size of the second argument. In
other words, every substitution pair should be accompanied by a list specifying
when the substitution is applicable.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #subst_occs [[1;3]] [("1","SUC 0")] "SUC 0 + SUC 0 = SUC(SUC 0)";;
   "1 + (SUC 0) = SUC 1" : term

   #subst_occs [[1];[1]] [("1","SUC 0");("2","SUC 1")] "SUC(SUC 0) = SUC 1";;
   "SUC 1 = 2" : term

   #subst_occs
   #[[1];[1]] [("2","SUC(SUC 0)");("1","SUC 0")] "SUC(SUC 0) = SUC 0";;
   "2 = 1" : term
\end{verbatim}
}
\SEEALSO
subst

\ENDDOC
\DOC{SUBST\_OCCS\_TAC}

\TYPE {\small\verb%SUBST_OCCS_TAC : ((int list # thm) list -> tactic)%}\egroup

\SYNOPSIS
Makes substitutions in a goal at specific occurrences of a term, using a list
of theorems.

\DESCRIBE
Given a list {\small\verb%(l1,A1|-t1=u1),...,(ln,An|-tn=un)%} and a goal {\small\verb%(A,t)%},
{\small\verb%SUBST_OCCS_TAC%} replaces each {\small\verb%ti%} in {\small\verb%t%} with {\small\verb%ui%}, simultaneously,
at the occurrences specified by the integers in the list {\small\verb%li = [o1;...;ok]%}
for each theorem {\small\verb%Ai|-ti=ui%}.
{\par\samepage\setseps\small
\begin{verbatim}
              A ?- t
   =============================  SUBST_OCCS_TAC [(l1,A1|-t1=u1);...;
    A ?- t[u1,...,un/t1,...,tn]                                (ln,An|-tn=un)]
\end{verbatim}
}
\noindent The assumptions of the theorems used to substitute with are not
added to the assumptions {\small\verb%A%} of the goal, but they are recorded in the proof.
If any {\small\verb%Ai%} is not a subset of {\small\verb%A%} (up to alpha-conversion),
{\small\verb%SUBST_OCCS_TAC [(l1,A1|-t1=u1);...;(ln,An|-tn=un)]%}
results in an invalid tactic.

{\small\verb%SUBST_OCCS_TAC%} automatically renames bound variables to prevent
free variables in {\small\verb%ui%} becoming bound after substitution.

\FAILURE
{\small\verb%SUBST_OCCS_TAC [(l1,th1);...;(ln,thn)] (A,t)%} fails if the conclusion of any
theorem in the list is not an equation.  No change is made to the goal if the
supplied occurrences {\small\verb%li%} of the left-hand side of the conclusion of {\small\verb%thi%} do
not appear in {\small\verb%t%}.

\EXAMPLE
When trying to solve the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (m + n) + (n + m) = (m + n) + (m + n)
\end{verbatim}
}
\noindent applying the commutative law for addition on the third occurrence of
the subterm {\small\verb%m + n%}
{\par\samepage\setseps\small
\begin{verbatim}
   SUBST_OCCS_TAC [([3],SPECL ["m:num"; "n:num"] ADD_SYM)]
\end{verbatim}
}
\noindent results in the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (m + n) + (n + m) = (m + n) + (n + m)
\end{verbatim}
}
\USES
{\small\verb%SUBST_OCCS_TAC%} is used when rewriting a goal at specific occurrences
of a term,
and rewriting tactics such as {\small\verb%REWRITE_TAC%}, {\small\verb%PURE_REWRITE_TAC%},
{\small\verb%ONCE_REWRITE_TAC%}, {\small\verb%SUBST_TAC%}, etc. are too extensive or would diverge.

\SEEALSO
ONCE_REWRITE_TAC, PURE_REWRITE_TAC, REWRITE_TAC, SUBST1_TAC, SUBST_TAC.

\ENDDOC
\DOC{SUBST\_TAC}

\TYPE {\small\verb%SUBST_TAC : (thm list -> tactic)%}\egroup

\SYNOPSIS
Makes term substitutions in a goal using a list of theorems.

\DESCRIBE

Given a list of theorems {\small\verb%A1|-u1=v1,...,An|-un=vn%} and a goal {\small\verb%(A,t)%},
{\small\verb%SUBST_TAC%} rewrites the term {\small\verb%t%} into the term {\small\verb%t[v1,...,vn/u1,...,un]%} by
simultaneously substituting {\small\verb%vi%} for each occurrence of {\small\verb%ui%} in {\small\verb%t%} with {\small\verb%vi%}:
{\par\samepage\setseps\small
\begin{verbatim}
              A ?- t
   =============================  SUBST_TAC [A1|-u1=v1;...;An|-un=vn]
    A ?- t[v1,...,vn/u1,...,un]
\end{verbatim}
}
\noindent The assumptions of the theorems used to substitute with are not added
to the assumptions {\small\verb%A%} of the goal, while they are recorded in the proof.  If
any {\small\verb%Ai%} is not a subset of {\small\verb%A%} (up to alpha-conversion), then {\small\verb%SUBST_TAC
[A1|-u1=v1;...;An|-un=vn]%} results in an invalid tactic.

{\small\verb%SUBST_TAC%} automatically renames bound variables to prevent free variables in
{\small\verb%vi%} becoming bound after substitution.

\FAILURE
{\small\verb%SUBST_TAC [th1;...;thn] (A,t)%} fails if the conclusion of any theorem in the
list is not an equation.  No change is made to the goal if no occurrence of the
left-hand side of the conclusion of {\small\verb%thi%} appears in {\small\verb%t%}.

\EXAMPLE
When trying to solve the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (n + 0) + (0 + m) = m + n
\end{verbatim}
}
\noindent by substituting with the theorems
{\par\samepage\setseps\small
\begin{verbatim}
   #let thm1 = SPECL ["m:num"; "n:num"] ADD_SYM
   #and thm2 = CONJUNCT1 ADD_CLAUSES;;
   thm1 = |- m + n = n + m
   thm2 = |- 0 + m = m
\end{verbatim}
}
\noindent applying {\small\verb%SUBST_TAC [thm1; thm2]%} results in the goal
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (n + 0) + m = n + m
\end{verbatim}
}
\USES
{\small\verb%SUBST_TAC%} is used when rewriting (for example, with {\small\verb%REWRITE_TAC%}) is
extensive or would diverge.  Substituting is also much faster than rewriting.

\SEEALSO
ONCE_REWRITE_TAC, PURE_REWRITE_TAC, REWRITE_TAC, SUBST1_TAC, SUBST_ALL_TAC.

\ENDDOC
\DOC{subtract}

\TYPE {\small\verb%subtract : (* list -> * list -> * list)%}\egroup

\SYNOPSIS
Computes the set-theoretic difference of two `sets'.

\DESCRIBE
{\small\verb%subtract l1 l2%} returns a list consisting of those elements of {\small\verb%l1%} that do
not appear in {\small\verb%l2%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#subtract [1;2;3] [3;5;4;1];;
[2] : int list

#subtract [1;2;4;1] [4;5];;
[1; 2; 1] : int list
\end{verbatim}
}
\SEEALSO
setify, set_equal, union, intersect.

\ENDDOC
\DOC{suspend\_recording}

\TYPE {\small\verb%suspend_recording : void -> void%}\egroup


\SYNOPSIS
Suspend proof recording temporarily.

\DESCRIBE
A proof is a list of inference steps. After the proof recorder is
enabled, every inference performed by the system is recorded and
cumulated in an internal buffer. When a proof is completed, the raw
records can then be processed and output to a disk file.

{\small\verb%suspend_recording%} is a low level user function for managing the proof
recorder. It pauses the proof recorder until the function
{\small\verb%resume_recording%} is called. When the proof recorder is suspended,
any inference carried out by the system will not be recorded.
The internal buffer for storing the inference steps will not be
cleared. When the proof recorder is resumed, the steps will be
appended to what have been saved in the buffer.

The current state of the proof recorder can interrogated using the
function {\small\verb%is_recording_proof%}. A value of {\small\verb%false%} indicates the proof
recorder is disabled.

\FAILURE
Never fail.

\COMMENTS
This function is used to implement higher level user functions for
recording proof in the library {\small\verb%record_proof%}. It is much more
convenient to use those functions than the low level functions
such as {\small\verb%suspend_recording%} directly.

\SEEALSO
record_proof, is_recording_proof, RecordStep, get_steps, resume_recording,
current_proof, current_proof_file,
new_proof_file, close_proof_file, begin_proof, end_proof,
TAC_PROOF, PROVE, prove, prove_thm


\ENDDOC
\DOC{SWAP\_EXISTS\_CONV}

\TYPE {\small\verb%SWAP_EXISTS_CONV : conv%}\egroup

\SYNOPSIS
Interchanges the order of two existentially quantified variables.

\DESCRIBE
When applied to a term argument of the form {\small\verb%?x y. P%}, the conversion
{\small\verb%SWAP_EXISTS_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (?x y. P) = (?y x. P)
\end{verbatim}
}
\FAILURE
{\small\verb%SWAP_EXISTS_CONV%} fails if applied to a term that is not of the form
{\small\verb%?x y. P%}.

\ENDDOC
\DOC{SYM\_CONV}

\TYPE {\small\verb%SYM_CONV : conv%}\egroup

\SYNOPSIS
Interchanges the left and right-hand sides of an equation.

\DESCRIBE
When applied to an equational term {\small\verb%t1 = t2%}, the conversion
{\small\verb%SYM_CONV%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (t1 = t2) = (t2 = t1)
\end{verbatim}
}
\FAILURE
Fails if applied to a term that is not an equation.

\SEEALSO
SYM.

\ENDDOC
\DOC{SYM}

\TYPE {\small\verb%SYM : (thm -> thm)%}\egroup

\SYNOPSIS
Swaps left-hand and right-hand sides of an equation.

\DESCRIBE
When applied to a theorem {\small\verb%A |- t1 = t2%}, the inference rule {\small\verb%SYM%} returns
{\small\verb%A |- t2 = t1%}.
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 = t2
   --------------  SYM
    A |- t2 = t1
\end{verbatim}
}
\FAILURE
Fails unless the theorem is equational.

\SEEALSO
GSYM, NOT_EQ_SYM, REFL.

\ENDDOC
\DOC{syserror}

\TYPE {\small\verb%syserror : (string -> *)%}\egroup

\SYNOPSIS
Prints an error message issued by the {\small\verb%ML%} system.

\DESCRIBE
Given a string {\small\verb%`error message`%}, {\small\verb%syserror%} returns an {\small\verb%ML%} system
error with diagnostics {\small\verb%`error message`%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #syserror `in ML function`;;
   ML system error in ML function
   evaluation failed     syserror
\end{verbatim}
}
\ENDDOC
\DOC{system}

\TYPE {\small\verb%system : (string -> int)%}\egroup

\SYNOPSIS
Executes a shell command.

\DESCRIBE
Escapes from {\small\verb%HOL%} temporarily to execute a named shell command. The integer
value returned is an error code: zero indicates successful completion of the
shell command.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#system `zap`;;
zap: Command not found.
1 : int

system `ls`;;
file_a              file_b             file_c
0:int
\end{verbatim}
}
\ENDDOC
\DOC{TAC\_PROOF}

\TYPE {\small\verb%TAC_PROOF : ((goal # tactic) -> thm)%}\egroup

\SYNOPSIS
Attempts to prove a goal using a given tactic.

\DESCRIBE
When applied to a goal-tactic pair {\small\verb%(A ?- t,tac)%}, the {\small\verb%TAC_PROOF%} function
attempts to prove the goal {\small\verb%A ?- t%}, using the tactic {\small\verb%tac%}. If it succeeds, it
returns the theorem {\small\verb%A' |- t%} corresponding to the goal, where the assumption
list {\small\verb%A'%} may be a proper superset of {\small\verb%A%} unless the tactic is valid; there
is no inbuilt validity checking.

\FAILURE
Fails unless the goal has hypotheses and conclusions all of type {\small\verb%bool%},
and the tactic can solve the goal.

\SEEALSO
PROVE, prove_thm, VALID.

\ENDDOC
\DOC{term\_of\_int}

\TYPE {\small\verb%term_of_int : (int -> term)%}\egroup

\SYNOPSIS
Maps an ML integer to the corresponding numeric term.

\DESCRIBE
When given a non-negative integer, {\small\verb%term_of_int%} returns a logical
term of type {\small\verb%:num%}  representing the number.

\FAILURE
Fails if the argument is less than 0.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
  #term_of_int 2;;
  "2" : term

  #term_of_int (-2);;
  evaluation failed     mk_const: -2 not a constant
\end{verbatim}
}

\SEEALSO
int_of_term, int_of_string, string_of_int.

\ENDDOC
\DOC{THENC}

\TYPE {\small\verb%$THENC : (conv -> conv -> conv)%}\egroup

\SYNOPSIS
Applies two conversions in sequence.

\DESCRIBE
If the conversion {\small\verb%c1%} returns {\small\verb%|- t = t'%} when applied to a term {\small\verb%"t"%}, and
{\small\verb%c2%} returns {\small\verb%|- t' = t''%} when applied to {\small\verb%"t'"%}, then the composite
conversion {\small\verb%(c1 THENC c2) "t"%} returns {\small\verb%|- t = t''%}.  That is, {\small\verb%(c1 THENC c2)
"t"%} has the effect of transforming the term {\small\verb%"t"%} first with the conversion
{\small\verb%c1%} and then with the conversion {\small\verb%c2%}.

\FAILURE
{\small\verb%(c1 THENC c2) "t"%} fails if either the conversion {\small\verb%c1%} fails when applied to
{\small\verb%"t"%}, or if {\small\verb%c1 "t"%} succeeds and returns {\small\verb%|- t = t'%} but {\small\verb%c2%} fails when
applied to {\small\verb%"t'"%}.  {\small\verb%(c1 THENC c2) "t"%} may also fail if either of {\small\verb%c1%} or {\small\verb%c2%}
is not, in fact, a conversion (i.e. a function that maps a term {\small\verb%t%} to a
theorem {\small\verb%|- t = t'%}).

\SEEALSO
EVERY_CONV.

\ENDDOC
\DOC{THEN}

\TYPE {\small\verb%$THEN : (tactic -> tactic -> tactic)%}\egroup

\SYNOPSIS
Applies two tactics in sequence.

\DESCRIBE
If {\small\verb%T1%} and {\small\verb%T2%} are tactics, {\small\verb%T1 THEN T2%} is a tactic which applies {\small\verb%T1%} to a
goal, then applies the tactic {\small\verb%T2%} to all the subgoals generated. If {\small\verb%T1%}
solves the goal then {\small\verb%T2%} is never applied.

\FAILURE
The application of {\small\verb%THEN%} to a pair of tactics never fails.
The resulting tactic fails if {\small\verb%T1%} fails when applied to the goal, or if
{\small\verb%T2%} does when applied to any of the resulting subgoals.

\COMMENTS
Although normally used to sequence tactics which generate a single subgoal,
it is worth remembering that it is sometimes useful to apply the same tactic
to multiple subgoals; sequences like the following:
{\par\samepage\setseps\small
\begin{verbatim}
   EQ_TAC THENL [ASM_REWRITE_TAC[]; ASM_REWRITE_TAC[]]
\end{verbatim}
}
\noindent can be replaced by the briefer:
{\par\samepage\setseps\small
\begin{verbatim}
   EQ_TAC THEN ASM_REWRITE_TAC[]
\end{verbatim}
}
\SEEALSO
EVERY, ORELSE, THENL.

\ENDDOC
\DOC{THENL}

\TYPE {\small\verb%$THENL : (tactic -> tactic list -> tactic)%}\egroup

\SYNOPSIS
Applies a list of tactics to the corresponding subgoals generated by a tactic.

\DESCRIBE
If {\small\verb%T,T1,...,Tn%} are tactics, {\small\verb%T THENL [T1;...;Tn]%} is a tactic which applies
{\small\verb%T%} to a goal, and if it does not fail, applies the tactics {\small\verb%T1,...,Tn%} to the
corresponding subgoals, unless {\small\verb%T%} completely solves the goal.

\FAILURE
The application of {\small\verb%THENL%} to a tactic and tactic list never fails.
The resulting tactic fails if {\small\verb%T%} fails when applied to the goal, or if
the goal list is not empty and its length is not the same as that of the
tactic list, or finally if {\small\verb%Ti%} fails when applied to the {\small\verb%i%}'th subgoal
generated by {\small\verb%T%}.

\USES
Applying different tactics to different subgoals.

\SEEALSO
EVERY, ORELSE, THEN.

\ENDDOC
\DOC{THEN\_TCL}

\TYPE {\small\verb%$THEN_TCL : (thm_tactical -> thm_tactical -> thm_tactical)%}\egroup

\SYNOPSIS
Composes two theorem-tacticals.

\DESCRIBE
If {\small\verb%ttl1%} and {\small\verb%ttl2%} are two theorem-tacticals, {\small\verb%ttl1 THEN_TCL ttl2%} is
a theorem-tactical which composes their effect; that is, if:
{\par\samepage\setseps\small
\begin{verbatim}
   ttl1 ttac th1 = ttac th2
\end{verbatim}
}
\noindent and
{\par\samepage\setseps\small
\begin{verbatim}
   ttl2 ttac th2 = ttac th3
\end{verbatim}
}
\noindent then
{\par\samepage\setseps\small
\begin{verbatim}
   (ttl1 THEN_TCL ttl2) ttac th1 = ttac th3
\end{verbatim}
}
\FAILURE
The application of {\small\verb%THEN_TCL%} to a pair of theorem-tacticals never fails.

\SEEALSO
EVERY_TCL, FIRST_TCL, ORELSE_TCL.

\ENDDOC
\DOC{theorem}

\TYPE {\small\verb%theorem : (string -> string -> thm)%}\egroup

\SYNOPSIS
Reads a derived theorem from a given theory segment of the current theory.

\DESCRIBE
A call of {\small\verb%theorem `thy` `th`%} returns the theorem named {\small\verb%th%} from the
theory segment {\small\verb%thy%}. The theory segment {\small\verb%thy%} must be part of the current
theory. The name {\small\verb%th%} is the name given to the theorem by the user when it
was originally added to the theory segment (by, for example, a call to
{\small\verb%save_thm%}). The name of the current theory segment can be abbreviated by {\small\verb%`-`%}.

\FAILURE
The call {\small\verb%theorem `thy` `th`%} will fail if the theory segment {\small\verb%thy%} is not
part of the current theory.
It will fail if there does not exist a derived theorem {\small\verb%th%} in theory
segment {\small\verb%thy%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#theorem `arithmetic` `ADD_SYM`;;
|- !m n. m + n = n + m
\end{verbatim}
}
\SEEALSO
axiom, definition, load_theorem, load_theorems, print_theory, save_thm,
theorems.

\ENDDOC
\DOC{theorem\_lfn}

\TYPE {\small\verb%theorem_lfn : (string list -> thm)%}\egroup

\SYNOPSIS
Loads a given theorem from a given theory.

\DESCRIBE
If {\small\verb%thy%} is an ancestor theory, and {\small\verb%th%} one of its theorems, then the call
{\par\samepage\setseps\small
\begin{verbatim}
   theorem_lfn [`thy`;`th`]
\end{verbatim}
}
\noindent will return that theorem.

\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%th%} is not one of its
theorems.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#theorem_lfn [`num`;`NOT_SUC`];;
|- !n. ~(SUC n = 0)
\end{verbatim}
}
\COMMENTS
This call has the same effect as {\small\verb%theorem `thy` `th`%}.

\SEEALSO
theorem, theorems, theorem_msg_lfn, load_theorem, load_theorems.

\ENDDOC
\DOC{theorem\_msg\_lfn}

\TYPE {\small\verb%theorem_msg_lfn : (string list -> thm)%}\egroup

\SYNOPSIS
Loads a given theorem from a given theory, with an autoload message.

\DESCRIBE
If {\small\verb%thy%} is an ancestor theory, and {\small\verb%th%} one of its theorems, then the call
{\par\samepage\setseps\small
\begin{verbatim}
   theorem_msg_lfn [`thy`;`th`]
\end{verbatim}
}
\noindent will print a message of the form
{\par\samepage\setseps\small
\begin{verbatim}
   Theorem th autoloaded from theory `thy`
\end{verbatim}
}
\noindent and cancel any autoloading action associated with the name {\small\verb%th%},
and will then return that theorem.

\FAILURE
Fails if {\small\verb%thy%} is not an ancestor theory, or if {\small\verb%th%} is not one of its
theorems.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#theorem_msg_lfn [`num`; `INV_SUC`];;
Theorem INV_SUC autoloaded from theory `num`.
|- !m n. (SUC m = SUC n) ==> (m = n)
\end{verbatim}
}
\SEEALSO
autoload, autoload_theory, theorem, theorems, theorem_lfn, load_theorem,
load_theorems, undo_autoload.

\ENDDOC
\DOC{theorems}

\TYPE {\small\verb%theorems : (string -> (string # thm) list)%}\egroup

\SYNOPSIS
Returns the derived theorems of a given theory segment of the current theory.

\DESCRIBE
A call of {\small\verb%theorems `thy`%} returns the derived theorems of the theory segment
{\small\verb%thy%} together with their names. The theory segment {\small\verb%thy%} must be part of
the current theory. The names are those given to the theorems by the user when
they were originally added to the theory segment (by, for example, a call to
{\small\verb%save_thm%}). The name of the current theory segment can be abbreviated by {\small\verb%`-`%}.

\FAILURE
The call {\small\verb%theorems `thy`%} will fail if the theory segment {\small\verb%thy%} is not part
of the current theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#theorems `bool`;;
[(`PAIR_EQ`, |- !x y a b. (x,y = a,b) = (x = a) /\ (y = b));
 (`SND`, |- !x y. SND(x,y) = y);
 (`FST`, |- !x y. FST(x,y) = x);
 (`PAIR`, |- !x. FST x,SND x = x);
 (`PAIR_EXISTS`, |- ?p. IS_PAIR p)]
: (string # thm) list
\end{verbatim}
}
\SEEALSO
axioms, definitions, load_theorem, load_theorems, print_theory, save_thm,
theorem.

\ENDDOC
\DOC{thm\_count}

\TYPE {\small\verb%thm_count : (void -> int)%}\egroup

\SYNOPSIS
Returns the current value of the theorem counter.

\DESCRIBE
HOL maintains a counter which is incremented every time a primitive inference
is performed (or an axiom or definition set up). A call to {\small\verb%thm_count()%}
returns the current value of this counter

\FAILURE
Never fails.

\SEEALSO
set_thm_count, timer.

\ENDDOC
\DOC{thm\_frees}

\TYPE {\small\verb%thm_frees : (thm -> term list)%}\egroup

\SYNOPSIS
Returns a list of the variables free in a theorem's assumptions and conclusion.

\DESCRIBE
When applied to a theorem, {\small\verb%A |- t%}, the function {\small\verb%thm_frees%} returns a list,
without repetitions, of those variables which are free either in {\small\verb%t%} or in
some member of the assumption list {\small\verb%A%}.

\FAILURE
Never fails.

\EXAMPLE
When applied to the following theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   (SUC m) < (SUC n) |- m < n
\end{verbatim}
}
\noindent {\small\verb%thm_frees%} returns the list {\small\verb%["m"; "n"]%}. The term {\small\verb%SUC%} is a
constant, not a variable, so that is not included.

\SEEALSO
frees, freesl, free_in.

\ENDDOC
\DOC{timer}

\TYPE {\small\verb%timer : (bool -> bool)%}\egroup

\SYNOPSIS
Switches timing and inference-counting on or off.

\DESCRIBE
A call {\small\verb%timer true%} switches on timing and inference-counting; {\small\verb%timer false%}
switches it off. In either case, the previous on/off setting ({\small\verb%true%} means on)
is returned. When switched on, the CPU (and, if relevant, garbage collection)
time and the number of intermediate theorems generated is displayed.

\FAILURE
Never fails.

\EXAMPLE
This example was run from a state with timings initially switched off:
{\par\samepage\setseps\small
\begin{verbatim}
   #let th = SPEC "x:num" (theorem `arithmetic` `ADD1`);;
   th = |- SUC x = x + 1
   Run time: 0.0s
   Intermediate theorems generated: 1

   #ONCE_REWRITE_RULE[EQ_SYM_EQ] th;;
   |- x + 1 = SUC x
   Run time: 0.1s
   Intermediate theorems generated: 11

   #SYM th;;
   |- x + 1 = SUC x
   Run time: 0.0s
   Intermediate theorems generated: 1
\end{verbatim}
}
\USES
Guiding the optimization of important proofs.

\COMMENTS
The same effect can be achieved by setting the flag {\small\verb%timing%}.

\SEEALSO
set_flag, set_thm_count, thm_count.

\ENDDOC
\DOC{tl}

\TYPE {\small\verb%tl : (* list -> * list)%}\egroup

\SYNOPSIS
Computes the tail of a list (the original list less the first element).

\DESCRIBE
{\small\verb%tl [x1;...;xn]%} returns {\small\verb%[x2;...;xn]%}.

\FAILURE
Fails with {\small\verb%tl%} if the list is empty.

\SEEALSO
hd, el, null.

\ENDDOC
\DOC{TOP\_DEPTH\_CONV}

\TYPE {\small\verb%TOP_DEPTH_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Applies a conversion top-down to all subterms, retraversing changed ones.

\DESCRIBE
{\small\verb%TOP_DEPTH_CONV c tm%} repeatedly applies the conversion {\small\verb%c%} to all the subterms
of the term {\small\verb%tm%}, including the term {\small\verb%tm%} itself. The supplied conversion {\small\verb%c%}
is applied to the subterms of {\small\verb%tm%} in top-down order and is applied repeatedly
(zero or more times, as is done by {\small\verb%REPEATC%}) at each subterm until it fails.
If a subterm {\small\verb%t%} is changed (up to alpha-equivalence) by virtue of the
application of {\small\verb%c%} to its own subterms, then the term into which {\small\verb%t%} is
transformed is retraversed by applying {\small\verb%TOP_DEPTH_CONV c%} to it.

\FAILURE
{\small\verb%TOP_DEPTH_CONV c tm%} never fails but can diverge.

\COMMENTS
The implementation of this function uses failure to avoid rebuilding
unchanged subterms. That is to say, during execution the failure string
{\small\verb%`QCONV`%} may be generated and later trapped. The behaviour of the function
is dependent on this use of failure. So, if the conversion given as argument
happens to generate a failure with string {\small\verb%`QCONV`%}, the operation of
{\small\verb%TOP_DEPTH_CONV%} will be unpredictable.

\SEEALSO
DEPTH_CONV, ONCE_DEPTH_CONV, REDEPTH_CONV, REW_DEPTH_CONV.

\ENDDOC
\DOC{top\_goal}

\TYPE {\small\verb%top_goal : (void -> goal)%}\egroup

\SYNOPSIS
Returns the current goal of the subgoal package.

\DESCRIBE
The function {\small\verb%top_goal%} is part of the subgoal package. It returns the top goal
of the goal stack in the current proof state.  For a description of the subgoal
package, see  {\small\verb%set_goal%}.

\FAILURE
A call to {\small\verb%top_goal%} will fail if there are no unproven goals. This could be
because no goal has been set using {\small\verb%set_goal%} or because the last goal set has
been completely proved.

\USES
Examining the proof state after a proof fails.

\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_thm.

\ENDDOC
\DOC{top\_print}

\TYPE {\small\verb%top_print : ((* -> **) -> (* -> **))%}\egroup

\SYNOPSIS
Allows user-supplied functions to be used for printing ML datatypes
(including types, terms and theorems).

\DESCRIBE
{\small\verb%top_print%} is not a proper ML function, but an ML construct. It can only
be used at top-level; otherwise an error will result. The type given above for
it is therefore somewhat bogus. Its argument should normally be a printing
function {\small\verb%f:ty->void%}. {\small\verb%top_print f%} then instructs the system to use the
function {\small\verb%f%} whenever it has a value of type {\small\verb%ty%} to print. The `call' to
{\small\verb%top_print%} returns {\small\verb%f%} as its result.

\FAILURE
Fails if used anywhere other than at top-level.

\EXAMPLE
The following example illustrates how values of an abstract type can be made
to print nicely using {\small\verb%top_print%}. For brevity, most of the functions that
would really be defined in the abstract type have been omitted.
{\par\samepage\setseps\small
\begin{verbatim}
   #abstype rat = int # int
   #with mk_rat (n,d) = abs_rat (n,d)
   #and print_rat r =
   #       let (n,d) = rep_rat r
   #       in  if (d = 1)
   #           then print_int n
   #           else do (print_int n; print_string `/`; print_int d);;
   mk_rat = - : ((int # int) -> rat)
   print_rat = - : (rat -> void)

   #mk_rat (2,3);;
   - : rat

   #top_print print_rat;;
   - : (rat -> void)

   #mk_rat (2,3);;
   2/3 : rat

   #mk_rat (3,1);;
   3 : rat
\end{verbatim}
}
\USES
Useful for defining the printing of abstract types, including terms, theorems
and types. In particular, calling {\small\verb%top_print%} with {\small\verb%print_all_thm%} as argument
will cause the hypotheses of theorems to be printed in full, rather than
simply as a period (dot, full-stop).

\SEEALSO
assignable_print_term, new_syntax_block.

\ENDDOC
\DOC{top\_proof}

\TYPE {\small\verb%top_proof : (subgoals list -> thm)%}\egroup

\SYNOPSIS
This function is for internal use only and is to be deleted from a future
version of the system. It should not be used.

\ENDDOC
\DOC{top\_thm}

\TYPE {\small\verb%top_thm : (void -> thm)%}\egroup

\SYNOPSIS
Returns the theorem just proved using the subgoal package.

\DESCRIBE
The function {\small\verb%top_thm%} is part of the subgoal package. A proof state of the
package consists of either  goal and justification stacks if a proof is in
progress or a theorem if a proof has just been completed. If the proof state
consists of a theorem, {\small\verb%top_thm%} returns that theorem. For a description of the
subgoal package, see {\small\verb%set_goal%}.

\FAILURE
{\small\verb%top_thm%} will fail if the proof state does not hold a theorem. This will be
so either because no goal has been set or because a proof is in progress with
unproven subgoals.

\USES
Accessing the result of an interactive proof session with the subgoal package.

\SEEALSO
b, backup, backup_limit, e, expand, expandf, g, get_state, p, print_state, r,
rotate, save_top_thm, set_goal, set_state, top_goal.

\ENDDOC
\DOC{TRANS}

\TYPE {\small\verb%$TRANS : (thm -> thm -> thm)%}\egroup

\SYNOPSIS
Uses transitivity of equality on two equational theorems.

\DESCRIBE
When applied to a theorem {\small\verb%A1 |- t1 = t2%} and a theorem {\small\verb%A2 |- t2 = t3%}, the
inference rule {\small\verb%TRANS%} returns the theorem {\small\verb%A1 u A2 |- t1 = t3%}. Note that
{\small\verb%TRANS%} can also be used as a infix (see example below).
{\par\samepage\setseps\small
\begin{verbatim}
    A1 |- t1 = t2   A2 |- t2 = t3
   -------------------------------  TRANS
         A1 u A2 |- t1 = t3
\end{verbatim}
}
\FAILURE
Fails unless the theorems are equational, with the right side of the first
being the same as the left side of the second.

\EXAMPLE
The following shows identical uses of {\small\verb%TRANS%}, one as a prefix, one an infix.
{\par\samepage\setseps\small
\begin{verbatim}
   #let t1 = ASSUME "a:bool = b" and t2 = ASSUME "b:bool = c";;
   t1 = . |- a = b
   t2 = . |- b = c

   #TRANS t1 t2;;
   .. |- a = c

   #t1 TRANS t2;;
   .. |- a = c
\end{verbatim}
}
\SEEALSO
EQ_MP, IMP_TRANS, REFL, SYM.

\ENDDOC
\DOC{TRY\_CONV}

\TYPE {\small\verb%TRY_CONV : (conv -> conv)%}\egroup

\SYNOPSIS
Attempts to apply a conversion; applies identity conversion in case of failure.

\DESCRIBE
{\small\verb%TRY_CONV c "t"%} attempts to apply the conversion {\small\verb%c%} to the term {\small\verb%"t"%}; if
this fails, then the identity conversion applied instead.  That is, if {\small\verb%c%} is a
conversion that maps a term {\small\verb%"t"%} to the theorem {\small\verb%|- t = t'%}, then the
conversion {\small\verb%TRY_CONV c%} also maps {\small\verb%"t"%} to {\small\verb%|- t = t'%}. But if {\small\verb%c%} fails when
applied to {\small\verb%"t"%}, then {\small\verb%TRY_CONV c "t"%} returns {\small\verb%|- t = t%}.

\FAILURE
Never fails.

\SEEALSO
ALL_CONV.

\ENDDOC
\DOC{TRY}

\TYPE {\small\verb%TRY : (tactic -> tactic)%}\egroup

\SYNOPSIS
Makes a tactic have no effect rather than fail.

\DESCRIBE
For any tactic {\small\verb%T%}, the application {\small\verb%TRY T%} gives a new tactic
which has the same effect as {\small\verb%T%} if that succeeds, and otherwise has
no effect.

\FAILURE
The application of {\small\verb%TRY%} to a tactic never fails. The resulting
tactic never fails.

\SEEALSO
CHANGED_TAC, VALID.

\ENDDOC
\DOC{tryfind}

\TYPE {\small\verb%tryfind : ((* -> **) -> * list -> **)%}\egroup

\SYNOPSIS
Returns the result of the first successful application of a function to the
elements of a list.

\DESCRIBE
{\small\verb%tryfind f [x1;...;xn]%} returns {\small\verb%(f xi)%} for the first {\small\verb%xi%} in the list for
which application of {\small\verb%f%} succeeds.

\FAILURE
Fails with {\small\verb%tryfind%} if the application of the function fails for all elements
in the list. This will always be the case if the list is empty.

\SEEALSO
find, mem, exists, forall, assoc, rev_assoc.

\ENDDOC
\DOC{tty\_read}

\TYPE {\small\verb%tty_read : (void -> string)%}\egroup

\SYNOPSIS
Reads a single character from the standard input.

\DESCRIBE
The call {\small\verb%tty_read()%} will read a single character from the standard input,
which in an interactive HOL session will normally be the terminal.

\FAILURE
Will only fail under obscure system-dependent circumstances.

\EXAMPLE
The following example shows how a check on the deletion of a file might be
implemented:
{\par\samepage\setseps\small
\begin{verbatim}
   #tty_write `Delete GONK.th (y/n)?`;
   #tty_read()=`y` => unlink `GONK.th` | ();;
   Delete GONK.th (y/n)?n
   () : void
   Run time: 0.0s
\end{verbatim}
}
\COMMENTS
Only one character is read per call of {\small\verb%tty_read()%}, and remaining characters
will be passed to the ML interpreter as usual. It is of course possible to make
multiple calls to {\small\verb%tty_read()%} (e.g. via a {\small\verb%while%} loop) to read in a longer
string.

\SEEALSO
append_openw, close, openi, openw, read, tty_write, write.

\ENDDOC
\DOC{tty\_write}

\TYPE {\small\verb%tty_write : (string -> void)%}\egroup

\SYNOPSIS
Writes a string to the standard output.

\DESCRIBE
The call {\small\verb%tty_write s%} will write the string {\small\verb%s%} to the standard output, which
in an interactive HOL session will normally be the screen.

\FAILURE
Will only fail under unusual system-dependent circumstances, for example if the
standard output cannot be written.

\SEEALSO
append_openw, close, openi, openw, read, tty_read, write.

\ENDDOC
\DOC{type\_abbrevs}

\TYPE {\small\verb%type_abbrevs : (string -> (string # type) list)%}\egroup

\SYNOPSIS
Lists the type abbreviations in a named theory.

\DESCRIBE
Given the name of a theory, {\small\verb%type_abbrevs%} returns a list of pairs; each
pair contains the abbreviation and the actual type it denotes.

\FAILURE
Fails if the named theory is not an ancestor of the current theory.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#load_library `string`;;
Loading library `string` ...
Updating search path
.Updating help search path
.Declaring theory string a new parent
Theory string loaded
......
Library `string` loaded.
() : void

#type_abbrevs `string`;;
[(`tok`, ":string")] : (string # type) list
\end{verbatim}
}
\SEEALSO
new_type_abbrev

\ENDDOC
\DOC{type\_in}

\TYPE {\small\verb%type_in : (type -> term -> bool)%}\egroup

\SYNOPSIS
Determines whether any subterm of a given term has a particular type.

\DESCRIBE
The predicate {\small\verb%type_in%} returns {\small\verb%true%} if a subterm of the second argument
has the type specified by the first argument.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#type_in ":num" "5 = 4 + 1";;
true : bool

#type_in ":bool" "5 = 4 + 1";;
true : bool

#type_in ":(num)list" "SUC 0";;
false : bool
\end{verbatim}
}
\SEEALSO
find_term, find_terms, type_in_type, type_tyvars.

\ENDDOC
\DOC{type\_in\_type}

\TYPE {\small\verb%type_in_type : (type -> type -> bool)%}\egroup

\SYNOPSIS
Determines whether a given type is a subtype of another.

\DESCRIBE
The predicate {\small\verb%type_in_type%} returns {\small\verb%true%} if the type
given as the first argument is a subtype of the second.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
   #type_in_type ":num" ":num # bool";;
   true : bool

   #type_in_type ":num" ":(num)list";;
   true :bool

   #type_in_type ":bool" ":num + bool";;
   true : bool
\end{verbatim}
}
\SEEALSO
find_term, find_terms, type_in

\ENDDOC
\DOC{type\_of}

\TYPE {\small\verb%type_of : (term -> type)%}\egroup

\SYNOPSIS
Returns the type of a term.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#type_of "T";;
":bool" : type
\end{verbatim}
}
\ENDDOC
\DOC{types}

\TYPE {\small\verb%types : (string -> (int # string) list)%}\egroup

\SYNOPSIS
Lists the types in the named theory.

\DESCRIBE
The function {\small\verb%types%} should be applied to a string which is the name of an
ancestor theory (including the current theory; the special string {\small\verb%`-`%} is
always interpreted as the current theory). It returns a list of all the
type constructors declared in the named theory, in the form of arity-name
pairs.

\FAILURE
Fails unless the named theory is an ancestor.

\EXAMPLE
The theory {\small\verb%HOL%} has no types declared:
{\par\samepage\setseps\small
\begin{verbatim}
  #types `HOL`;;
  [] : (int # string) list
\end{verbatim}
}
\noindent but its ancestors have the following types declared:
{\par\samepage\setseps\small
\begin{verbatim}
   #itlist union (map types (ancestors `HOL`)) [];;
   [(2, `fun`);
    (2, `prod`);
    (0, `bool`);
    (0, `ind`);
    (0, `num`);
    (1, `list`);
    (0, `tree`);
    (1, `ltree`);
    (2, `sum`);
    (0, `one`)]
   : (int # string) list
\end{verbatim}
}
\SEEALSO
ancestors, axioms, constants, definitions, infixes, new_type, new_type_abbrev,
new_type_definition, parents.

\ENDDOC
\DOC{type\_tyvars}

\TYPE {\small\verb%type_tyvars : (type -> type list)%}\egroup

\SYNOPSIS
Determines the type variables of a given type.

\DESCRIBE
The function {\small\verb%type_tyvars%} returns a list of type variables
used to construct the given type.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#type_tyvars ":bool";;
[] : type list

#type_tyvars ":(* -> **) -> (bool # ***) -> (** + num)";;
[":*"; ":**"; ":***"] : type list
\end{verbatim}
}
\SEEALSO
type_abbrevs, type_in, type_in_type.

\ENDDOC
\DOC{tyvars}

\TYPE {\small\verb%tyvars : (term -> type list)%}\egroup

\SYNOPSIS
Returns a list of the type variables free in a term.

\DESCRIBE
When applied to a term, {\small\verb%tyvars%} returns a list (possibly empty) of the type
variables which are free in the term.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#PAIR;;
|- !x. FST x,SND x = x

#tyvars (concl PAIR);;
[":*"; ":**"] : type list

#tyvars "x + 1 = SUC x";;
[] : type list
\end{verbatim}
}
\COMMENTS
In the current HOL logic, there is no binding operation for types, so `is free
in' is synonymous with `appears in'.

\SEEALSO
tyvarsl.

\ENDDOC
\DOC{tyvarsl}

\TYPE {\small\verb%tyvarsl : (term list -> type list)%}\egroup

\SYNOPSIS
Returns a list of the type variables free in a list of terms.

\DESCRIBE
When applied to a list of terms, {\small\verb%tyvarsl%} returns a list (possibly empty) of
the type variables which are free in any of those terms.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#tyvarsl ["!x. x = 1"; "!x:*. x = x"];;
[":*"] : type list
\end{verbatim}
}
\USES
Finding all the free type variables in the assumptions of a theorem, as a check
on the validity of certain inferences.

\COMMENTS
In the current HOL logic, there is no binding operation for types, so `is free
in' is synonymous with `appears in'.

\SEEALSO
tyvars.

\ENDDOC
\DOC{uncurry}

\TYPE {\small\verb%uncurry : ((* -> ** -> ***) -> (* # **) -> ***)%}\egroup

\SYNOPSIS
Converts a function taking two arguments into a function taking a single
paired argument.

\DESCRIBE
The application {\small\verb%uncurry f%} returns {\small\verb%\(x,y). f x y%}, so that
{\par\samepage\setseps\small
\begin{verbatim}
   uncurry f (x,y) = f x y
\end{verbatim}
}
\FAILURE
Never fails.

\SEEALSO
curry.

\ENDDOC
\DOC{UNDISCH\_ALL}

\TYPE {\small\verb%UNDISCH_ALL : (thm -> thm)%}\egroup

\SYNOPSIS
Iteratively undischarges antecedents in a chain of implications.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 ==> ... ==> tn ==> t
   ------------------------------  UNDISCH_ALL
        A, t1, ..., tn |- t
\end{verbatim}
}
\noindent Note that {\small\verb%UNDISCH_ALL%} treats {\small\verb%"~u"%} as {\small\verb%"u ==> F"%}.

\FAILURE
Unlike {\small\verb%UNDISCH%}, {\small\verb%UNDISCH_ALL%} will,
when called on something other than an implication or negation,
return its argument unchanged rather than failing.

\COMMENTS
Identical terms which are repeated in {\small\verb%A, "t1", ..., "tn"%} will
not be duplicated in the hypotheses of the resulting theorem.
However, if two or more alpha-equivalent terms appear in {\small\verb%A, "t1", ..., "tn"%},
then each distinct term will appear in the result.

\SEEALSO
DISCH, DISCH_ALL, DISCH_TAC, DISCH_THEN, NEG_DISCH, FILTER_DISCH_TAC,
FILTER_DISCH_THEN, STRIP_TAC, UNDISCH, UNDISCH_TAC.

\ENDDOC
\DOC{UNDISCH}

\TYPE {\small\verb%UNDISCH : (thm -> thm)%}\egroup

\SYNOPSIS
Undischarges the antecedent of an implicative theorem.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
    A |- t1 ==> t2
   ----------------  UNDISCH
     A, t1 |- t2
\end{verbatim}
}
\noindent Note that {\small\verb%UNDISCH%} treats {\small\verb%"~u"%} as {\small\verb%"u ==> F"%}.

\FAILURE
{\small\verb%UNDISCH%} will fail on theorems which are not implications or negations.

\COMMENTS
If the antecedent already appears in the hypotheses, it will not be duplicated.
However, unlike {\small\verb%DISCH%},
if the antecedent is alpha-equivalent to one of the hypotheses,
it will still be added to the hypotheses.

\SEEALSO
DISCH, DISCH_ALL, DISCH_TAC, DISCH_THEN, FILTER_DISCH_TAC, FILTER_DISCH_THEN,
NEG_DISCH, STRIP_TAC, UNDISCH_ALL, UNDISCH_TAC.

\ENDDOC
\DOC{UNDISCH\_TAC}

\TYPE {\small\verb%UNDISCH_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Undischarges an assumption.

\DESCRIBE
{\par\samepage\setseps\small
\begin{verbatim}
          A ?- t
   ====================  UNDISCH_TAC "v"
    A - {v} ?- v ==> t
\end{verbatim}
}
\FAILURE
{\small\verb%UNDISCH_TAC%} will fail if {\small\verb%"v"%} is not an assumption.

\COMMENTS
{\small\verb%UNDISCH%}arging {\small\verb%"v"%} will remove all assumptions which are identical to {\small\verb%"v"%},
but those which are alpha-equivalent will remain.

\SEEALSO
DISCH, DISCH_ALL, DISCH_TAC, DISCH_THEN, NEG_DISCH, FILTER_DISCH_TAC,
FILTER_DISCH_THEN, STRIP_TAC,  UNDISCH, UNDISCH_ALL.

\ENDDOC
\DOC{undo\_autoload}

\TYPE {\small\verb%undo_autoload : (string -> bool)%}\egroup

\SYNOPSIS
Cancels the autoloading action associated with a name.

\DESCRIBE
A call {\small\verb%undo_autoload `name`%} cancels any autoloading action associated with
the identifier {\small\verb%name%}, whether this was specified by the general {\small\verb%autoload%}
function, or the more specialized {\small\verb%autoload_theory%}. For more details of the
autoloading mechanism, see the reference entries for those functions, or the
DESCRIPTION. The call to {\small\verb%undo_autoload%} returns {\small\verb%true%} if there was an
autoload action associated with that name, and {\small\verb%false%} otherwise.

\FAILURE
Never fails.

\SEEALSO
autoload, autoload_theory, let_after, let_before.

\ENDDOC
\DOC{unhide\_constant}

\TYPE {\small\verb%unhide_constant : (string -> void)%}\egroup

\SYNOPSIS
Restores recognition of a constant by the quotation parser.

\DESCRIBE
A call {\small\verb%unhide_constant `c`%}, where {\small\verb%c%} is a hidden constant, will unhide the
constant, that is, will make the quotation parser recognize it as such rather
than parsing it as a variable. It reverses the effect of the call
{\small\verb%hide_constant name%}.

\FAILURE
Fails unless the given name is a hidden constant in the current theory.

\COMMENTS
The hiding of a constant only affects the quotation parser; the constant is
still there in a theory, and may not be redefined.

\SEEALSO
hide_constant.

\ENDDOC
\DOC{union}

\TYPE {\small\verb%union : (* list -> * list -> * list)%}\egroup

\SYNOPSIS
Computes the union of two `sets'.

\DESCRIBE
{\small\verb%union l1 l2%} returns a list consisting of {\small\verb%l1%} concatenated with those
elements of {\small\verb%l2%} which are not in {\small\verb%l1%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#union [1;2;3] [1;5;4;3];;
[1; 2; 3; 5; 4] : int list

#union [1;1;1] [1;2;3;2];;
[1; 1; 1; 2; 3; 2] : int list
\end{verbatim}
}
\SEEALSO
setify, set_equal, intersect, subtract.

\ENDDOC
\DOC{unlink}

\TYPE {\small\verb%unlink : (string -> void)%}\egroup

\SYNOPSIS
Deletes a file.

\DESCRIBE
If {\small\verb%name%} is the name of an existing file, then {\small\verb%unlink `name`%} will remove
that file (if there are other links to the file, this will merely remove a
single link). Under Unix, the effect is the same as the {\small\verb%rm%} command.

\FAILURE
A call to {\small\verb%unlink%} may fail in various system-related ways, in particular if
{\small\verb%name%} does not exist or the user does not have write permission for the
current directory.

\COMMENTS
This call is somewhat Unix-related, and may behave differently under other
operating systems.

\SEEALSO
link, system.

\ENDDOC
\DOC{VALID}

\TYPE {\small\verb%VALID : (tactic -> tactic)%}\egroup

\SYNOPSIS
Tries to ensure that a tactic is valid.

\DESCRIBE
For any tactic {\small\verb%T%}, the application {\small\verb%VALID T%} gives a new tactic which when
applied to a goal, checks that {\small\verb%T%} as applied to that goal is valid, i.e. the
subgoals produced, if proved, can be used by the justification function given
by {\small\verb%T%} to construct a theorem corresponding to the original goal.

This check is performed by actually creating, using {\small\verb%mk_thm%}, theorems
corresponding to the subgoals, and seeing if the result of applying the
justification function to them gives a theorem corresponding to the original
goal. If it does, then {\small\verb%VALID T%} simply applies {\small\verb%T%}, and if not it fails.

The method by which theorems are created from goals can be changed by rebinding
the assignable variable {\small\verb%chktac%} - see its documentation entry for details.

\FAILURE
The application of {\small\verb%VALID%} to a tactic never fails. The resulting
tactic fails either if the original tactic fails or is invalid.

\COMMENTS
The use of {\small\verb%mk_thm%} is a possible, though improbable, loophole
in the general security of the theorem abstract type, since it does
create possibly spurious theorems; however these should remain anonymous
in the absence of other bugs in the system.

By default the same validity checking procedure, {\small\verb%check_valid%}, is
invoked by the subgoal package, but it can be switched off.

It is not checked whether the tactic is strongly valid, i.e. the
subgoals are provable; clearly this is not possible in general.

\SEEALSO
CHANGED_TAC, check_valid, chktac, e, expand, TRY.

\ENDDOC
\DOC{variant}

\TYPE {\small\verb%variant : (term list -> term -> term)%}\egroup

\SYNOPSIS
Modifies a variable name to avoid clashes.

\DESCRIBE
When applied to a list of variables to avoid clashing with, and a variable to
modify, {\small\verb%variant%} returns a variant of the variable to modify, that is, it
changes the name as intuitively as possible to make it distinct from any
variables in the list, or any (non-hidden) constants. This is normally done by
adding primes to the name.

The exact form of the variable name should not be relied on, except that the
original variable will be returned unmodified unless it is itself in the list
to avoid clashing with.

\FAILURE
{\small\verb%variant l t%} fails if any term in the list {\small\verb%l%} is not a variable or if
{\small\verb%t%} is neither a variable nor a constant.

\EXAMPLE
The following shows a couple of typical cases:
{\par\samepage\setseps\small
\begin{verbatim}
   #variant ["y:bool"; "z:bool"] "x:bool";;
   "x" : term

   #variant ["x:bool"; "x':num"; "x'':num"] "x:bool";;
   "x'''" : term
\end{verbatim}
}
\noindent while the following shows that clashes with the names of constants
are also avoided:
{\par\samepage\setseps\small
\begin{verbatim}
   #variant [] (mk_var(`T`,":bool"));;
   "T'" : term
\end{verbatim}
}
\USES
The function {\small\verb%variant%} is extremely useful for complicated derived rules which
need to rename variables to avoid free variable capture while still making the
role of the variable obvious to the user.

\SEEALSO
genvar, hide_constant.

\ENDDOC
\DOC{vars}

\TYPE {\small\verb%vars : (term -> term list)%}\egroup

\SYNOPSIS
Determines the variables used in a given term.

\DESCRIBE
Given a term argument, {\small\verb%vars%} returns a list of variables that occur
in that term.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#vars "\a:bool. a";;
["a"] : term list

#vars "\b:*. SUC 0";;
["b"] : term list

#vars "(a:num) + (b:num)";;
["a"; "b"] : term list
\end{verbatim}
}
\SEEALSO
varsl.

\ENDDOC
\DOC{varsl}

\TYPE {\small\verb%varsl : (term list -> term list)%}\egroup

\SYNOPSIS
Returns the union of the variables that occur in a given list of terms.

\DESCRIBE
Given a list of terms, {\small\verb%varsl%} returns a list of all the variables that occur
in the list of terms.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#varsl ["\a:bool. a"];;
["a"] : term list

#vars "[(a:num) + (b:num); 3 + (a:num) + SUC n]";;
["a"; "b"; "n"] : term list
\end{verbatim}
}
\SEEALSO
vars.

\ENDDOC
\DOC{version}

\TYPE {\small\verb%version : (void -> int)%}\egroup

\SYNOPSIS
Returns the version number of the {\small\verb%HOL%} system being run.

\DESCRIBE
The number is imagined to have a `decimal point' before its last two digits to
give the actual version number.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
          _  _    __    _      __    __
   |___   |__|   |  |   |     |__|  |__|
   |      |  |   |__|   |__   |__|  |__|

          Version 2 (Sun4/Allegro 4.0), built on 22/6/91

#version();;
200 : int
\end{verbatim}
}
\ENDDOC
\DOC{W}

\TYPE {\small\verb%W : ((* -> * -> **) -> * -> **)%}\egroup

\SYNOPSIS
Duplicates function argument : {\small\verb%W f x%} = {\small\verb%f x x%}.

\FAILURE
Never fails.

\SEEALSO
\#, B, C, CB, Co, I, K, KI, o, oo, S.

\ENDDOC
\DOC{words2}

\TYPE {\small\verb%words2 : (string -> string -> string list)%}\egroup

\SYNOPSIS
Splits a string into a list of substrings, breaking at occurrences of a
specified character.

\DESCRIBE
{\small\verb%words2 char s%} splits the string {\small\verb%s%} into a list of substrings. Splitting
occurs at each occurrence of a sequence of the character {\small\verb%char%}. The {\small\verb%char%}
characters do not appear in the list of substrings. Leading and trailing
occurrences of {\small\verb%char%} are also thrown away. If {\small\verb%char%} is not a
single-character string (its length is not 1), then {\small\verb%s%} will not be split and
so the result will be the list {\small\verb%[s]%}.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#words2 `/` `/the/cat//sat/on//the/mat/`;;
[`the`; `cat`; `sat`; `on`; `the`; `mat`] : string list

#words2 `//` `/the/cat//sat/on//the/mat/`;;
[`/the/cat//sat/on//the/mat/`] : string list
\end{verbatim}
}
\SEEALSO
words, word_separators, explode.

\ENDDOC
\DOC{words}

\TYPE {\small\verb%words : (string -> string list)%}\egroup

\SYNOPSIS
Splits a string into a list of words.

\DESCRIBE
{\small\verb%words s%} splits the string {\small\verb%s%} into a list of substrings. Splitting occurs
at each sequence of blanks and carriage returns (white space). This white
space does not appear in the list of substrings. Leading and trailing white
space in the input string is also thrown away.

\FAILURE
Never fails.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#words `  the cat  sat on   the mat `;;
[`the`; `cat`; `sat`; `on`; `the`; `mat`] : string list
\end{verbatim}
}
\USES
Useful when wanting to map a function over a list of constant strings.
Instead of using {\small\verb%[`string1`;...;`stringn`]%} one can use:
{\par\samepage\setseps\small
\begin{verbatim}
   (words `string1 ... stringn`)
\end{verbatim}
}
\SEEALSO
words2, word_separators, maptok, explode.

\ENDDOC
\DOC{word\_separators}

\TYPE {\small\verb%word_separators : string list%}\egroup

\SYNOPSIS
A list of white-space characters used when splitting a string into words.

\DESCRIBE
{\small\verb%word_separators%} is a two-element list of single-character strings. The
two characters are the space character (or blank) and the carriage-return
character. These are the characters that are considered to be word
separators by the function {\small\verb%words%}.

\EXAMPLE
{\par\samepage\setseps\small
\begin{verbatim}
#word_separators;;
[` `; `
`] : string list
\end{verbatim}
}
\SEEALSO
words.

\ENDDOC
\DOC{write}

\TYPE {\small\verb%write : ((string # string) -> void)%}\egroup

\SYNOPSIS
Writes characters to a file.

\DESCRIBE
The call {\small\verb%write(port,`characters`)%}, where {\small\verb%characters%} is a string of
characters to write, and {\small\verb%port%} is a string describing a port (a port is the
standard ML file descriptor, normally obtained from a call to {\small\verb%openw%} or
{\small\verb%append_openw%}), will write the given characters to the file corresponding to
the port.

\FAILURE
May fail or hang in system-dependent ways when given an invalid port
descriptor.

\EXAMPLE
The following assumes that HOL is being run under Unix. It will overwrite any
existing file {\small\verb%test-file%} in the current directory. Notice that the actual
string returned by {\small\verb%openw%} may vary on other systems.
{\par\samepage\setseps\small
\begin{verbatim}
   #let port = openw `test-file`;;
   port = `%test-file` : string

   #write(port,`Hello world`);;
   () : void

   #close port;;
   () : void

   #system `cat test-file`;;
   Hello world0 : int
\end{verbatim}
}
\SEEALSO
append_openw, close, openi, openw, read, tty_read, tty_write.

\ENDDOC
\DOC{X\_CASES\_THEN}

\TYPE {\small\verb%X_CASES_THEN : (term list list -> thm_tactical)%}\egroup

\SYNOPSIS
Applies a theorem-tactic to all disjuncts of a theorem, choosing witnesses.

\DESCRIBE
Let {\small\verb%[yl1;...;yln]%} represent a list of variable lists,
each of length zero or more, and {\small\verb%xl1,...,xln%} each represent a
vector of zero or more variables, so that the variables in each of
{\small\verb%yl1...yln%} have the same types as the corresponding {\small\verb%xli%}.
{\small\verb%X_CASES_THEN%} expects such a list of variable lists, {\small\verb%[yl1;...;yln]%}, a tactic
generating function {\small\verb%f:thm->tactic%}, and a disjunctive theorem,
where each disjunct may be existentially quantified:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |-(?xl1.B1)  \/...\/  (?xln.Bn)
\end{verbatim}
}
\noindent each disjunct having the form {\small\verb%(?xi1 ... xim. Bi)%}. If
applying {\small\verb%f%} to the theorem obtained by introducing witness variables {\small\verb%yli%}
for the objects {\small\verb%xli%} whose existence is asserted by each disjunct, typically
{\small\verb%({Bi[yli/xli]} |- Bi[yli/xli])%}, produce the following results when
applied to a goal {\small\verb%(A ?- t)%}:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   ========= f ({B1[yl1/xl1]} |- B1[yl1/xl1])
    A ?- t1

    ...

    A ?- t
   =========  f ({Bn[yln/xln]} |- Bn[yln/xln])
    A ?- tn
\end{verbatim}
}
\noindent then applying {\small\verb%(X_CHOOSE_THEN [yl1;...;yln] f th)%}
to the goal {\small\verb%(A ?- t)%} produces {\small\verb%n%} subgoals.
{\par\samepage\setseps\small
\begin{verbatim}
           A ?- t
   =======================  X_CHOOSE_THEN [yl1;...;yln] f th
    A ?- t1  ...  A ?- tn
\end{verbatim}
}

\FAILURE
Fails (with {\small\verb%X_CHOOSE_THEN%}) if any {\small\verb%yli%} has more variables than the
corresponding {\small\verb%xli%}, or (with {\small\verb%SUBST%}) if corresponding variables have
different types.  Failures may arise in the tactic-generating
function.  An invalid tactic is produced if any variable in any of the
{\small\verb%yli%} is free in the corresponding {\small\verb%Bi%} or in {\small\verb%t%}, or if the theorem
has any hypothesis which is not alpha-convertible to an assumption of
the goal.

\EXAMPLE
Given the goal {\small\verb%?- (x MOD 2) <= 1%}, the following theorem may be
used to split into 2 cases:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- (?m. x = 2 * m) \/ (?m. x = (2 * m) + 1)
\end{verbatim}
}
\noindent by the tactic {\small\verb%X_CASES_THEN [["n:num"];["n:num"]] ASSUME_TAC th%}
to produce the subgoals:
{\par\samepage\setseps\small
\begin{verbatim}
   {x = (2 * n) + 1} ?- (x MOD 2) <= 1

   {x = 2 * n} ?- (x MOD 2) <= 1
\end{verbatim}
}

\SEEALSO
DISJ_CASES_THENL, X_CASES_THENL, X_CHOOSE_THEN.

\ENDDOC
\DOC{X\_CASES\_THENL}

\TYPE {\small\verb%X_CASES_THENL : (term list list -> thm_tactic list -> thm_tactic)%}\egroup

\SYNOPSIS
Applies theorem-tactics to corresponding disjuncts of a theorem, choosing
witnesses.

\DESCRIBE
Let {\small\verb%[yl1;...;yln]%} represent a list of variable lists, each of length zero or
more, and {\small\verb%xl1,...,xln%} each represent a vector of zero or more variables, so
that the variables in each of {\small\verb%yl1...yln%} have the same types as the
corresponding {\small\verb%xli%}. The function {\small\verb%X_CASES_THENL%} expects a list of variable
lists, {\small\verb%[yl1;...;yln]%}, a list of tactic-generating functions
{\small\verb%[f1;...;fn]:(thm->tactic)list%}, and a disjunctive theorem, where each disjunct
may be existentially quantified:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |-(?xl1.B1)  \/...\/  (?xln.Bn)
\end{verbatim}
}
\noindent each disjunct having the form {\small\verb%(?xi1 ... xim. Bi)%}. If applying each
{\small\verb%fi%} to the theorem obtained by introducing witness variables {\small\verb%yli%} for the
objects {\small\verb%xli%} whose existence is asserted by the {\small\verb%i%}th disjunct,
{\small\verb%({Bi[yli/xli]} |- Bi[yli/xli])%}, produces the following results when applied
to a goal {\small\verb%(A ?- t)%}:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   =========  f1 ({B1[yl1/xl1]} |- B1[yl1/xl1])
    A ?- t1

    ...

    A ?- t
   =========  fn ({Bn[yln/xln]} |- Bn[yln/xln])
    A ?- tn
\end{verbatim}
}
\noindent then applying {\small\verb%X_CASES_THENL [yl1;...;yln] [f1;...;fn] th%}
to the goal {\small\verb%(A ?- t)%} produces {\small\verb%n%} subgoals.
{\par\samepage\setseps\small
\begin{verbatim}
           A ?- t
   =======================  X_CASES_THENL [yl1;...;yln] [f1;...;fn] th
    A ?- t1  ...  A ?- tn
\end{verbatim}
}

\FAILURE
Fails (with {\small\verb%X_CASES_THENL%}) if any {\small\verb%yli%} has more variables than the
corresponding {\small\verb%xli%}, or (with {\small\verb%SUBST%}) if corresponding variables have
different types, or (with {\small\verb%combine%}) if the number of theorem tactics
differs from the number of disjuncts.  Failures may arise in the
tactic-generating function.  An invalid tactic is produced if any
variable in any of the {\small\verb%yli%} is free in the corresponding {\small\verb%Bi%} or in
{\small\verb%t%}, or if the theorem has any hypothesis which is not
alpha-convertible to an assumption of the goal.

\EXAMPLE
Given the goal {\small\verb%?- (x MOD 2) <= 1%}, the following theorem may be
used to split into 2 cases:
{\par\samepage\setseps\small
\begin{verbatim}
   th = |- (?m. x = 2 * m) \/ (?m. x = (2 * m) + 1)
\end{verbatim}
}
\noindent by the tactic
{\small\verb%X_CASES_THENL [["n:num"];["n:num"]] [ASSUME_TAC; SUBST1_TAC] th%}
to produce the subgoals:
{\par\samepage\setseps\small
\begin{verbatim}
   ?- (((2 * n) + 1) MOD 2) <= 1

   {x = 2 * n} ?- (x MOD 2) <= 1
\end{verbatim}
}
\SEEALSO
DISJ_CASES_THEN, X_CASES_THEN, X_CHOOSE_THEN.

\ENDDOC
\DOC{X\_CHOOSE\_TAC}

\TYPE {\small\verb%X_CHOOSE_TAC : (term -> thm_tactic)%}\egroup

\SYNOPSIS
Assumes a theorem, with existentially quantified variable replaced by a given
witness.

\DESCRIBE
{\small\verb%X_CHOOSE_TAC%} expects a variable {\small\verb%y%} and theorem with an existentially
quantified conclusion.  When applied to a goal, it adds a new
assumption obtained by introducing the variable {\small\verb%y%} as a witness for
the object {\small\verb%x%} whose existence is asserted in the theorem.
{\par\samepage\setseps\small
\begin{verbatim}
           A ?- t
   ===================  X_CHOOSE_TAC "y" (A1 |- ?x. w)
    A u {w[y/x]} ?- t         ("y" not free anywhere)
\end{verbatim}
}
\FAILURE
Fails if the theorem's conclusion is not existentially quantified, or if
the first argument is not a variable.  Failures may arise in the
tactic-generating function.  An invalid tactic is produced if the
introduced variable is free in {\small\verb%w%} or {\small\verb%t%}, or if the theorem has any
hypothesis which is not alpha-convertible to an assumption of the
goal.

\EXAMPLE
Given a goal of the form
{\par\samepage\setseps\small
\begin{verbatim}
   {n < m} ?- ?x. m = n + (x + 1)
\end{verbatim}
}
\noindent the following theorem may be applied:
{\par\samepage\setseps\small
\begin{verbatim}
   th = ["n < m"] |- ?p. m = n + p
\end{verbatim}
}
\noindent by the tactic {\small\verb%(X_CHOOSE_TAC "q:num" th)%} giving
the subgoal:
{\par\samepage\setseps\small
\begin{verbatim}
   {n < m, m = n + q} ?- ?x. m = n + (x + 1)
\end{verbatim}
}
\SEEALSO
CHOOSE, CHOOSE_THEN, X_CHOOSE_THEN.

\ENDDOC
\DOC{X\_CHOOSE\_THEN}

\TYPE {\small\verb%X_CHOOSE_THEN : (term -> thm_tactical)%}\egroup

\SYNOPSIS
Replaces existentially quantified variable with given witness, and passes it to
a theorem-tactic.

\DESCRIBE
{\small\verb%X_CHOOSE_THEN%} expects a variable {\small\verb%y%}, a tactic-generating function
{\small\verb%f:thm->tactic%}, and a theorem of the form {\small\verb%(A1 |- ?x. w)%} as
arguments.  A new theorem is created by introducing the given variable
{\small\verb%y%} as a witness for the object {\small\verb%x%} whose existence is asserted in the original
theorem, {\small\verb%(w[y/x] |- w[y/x])%}.  If the tactic-generating function {\small\verb%f%}
applied to this theorem produces results as follows when applied to a
goal {\small\verb%(A ?- t)%}:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   =========  f ({w[y/x]} |- w[y/x])
    A ?- t1
\end{verbatim}
}
\noindent then applying {\small\verb%(X_CHOOSE_THEN "y" f (A1 |- ?x. w))%} to the
goal {\small\verb%(A ?- t)%} produces the subgoal:
{\par\samepage\setseps\small
\begin{verbatim}
    A ?- t
   =========  X_CHOOSE_THEN "y" f (A1 |- ?x. w)
    A ?- t1         ("y" not free anywhere)
\end{verbatim}
}
\FAILURE
Fails if the theorem's conclusion is not existentially quantified, or if
the first argument is not a variable.  Failures may arise in the
tactic-generating function.  An invalid tactic is produced if the
introduced variable is free in {\small\verb%w%} or {\small\verb%t%}, or if the theorem has any
hypothesis which is not alpha-convertible to an assumption of the
goal.

\EXAMPLE
Given a goal of the form
{\par\samepage\setseps\small
\begin{verbatim}
   {n < m} ?- ?x. m = n + (x + 1)
\end{verbatim}
}
\noindent the following theorem may be applied:
{\par\samepage\setseps\small
\begin{verbatim}
   th = ["n < m"] |- ?p. m = n + p
\end{verbatim}
}
\noindent by the tactic {\small\verb%(X_CHOOSE_THEN "q:num" SUBST1_TAC th)%} giving
the subgoal:
{\par\samepage\setseps\small
\begin{verbatim}
   {n < m} ?- ?x. n + q = n + (x + 1)
\end{verbatim}
}
\SEEALSO
CHOOSE, CHOOSE_THEN, CONJUNCTS_THEN, CONJUNCTS_THEN2, DISJ_CASES_THEN,
DISJ_CASES_THEN2, DISJ_CASES_THENL, STRIP_THM_THEN, X_CHOOSE_TAC.

\ENDDOC
\DOC{X\_FUN\_EQ\_CONV}

\TYPE {\small\verb%X_FUN_EQ_CONV : (term -> conv)%}\egroup

\SYNOPSIS
Performs extensionality conversion for functions (function equality).

\DESCRIBE
The conversion {\small\verb%X_FUN_EQ_CONV%} embodies the fact that two functions are equal
precisely when they give the same results for all values to which they can be
applied. For any variable {\small\verb%"x"%} and equation {\small\verb%"f = g"%}, where {\small\verb%x%} is of type
{\small\verb%ty1%} and {\small\verb%f%} and {\small\verb%g%} are functions of type {\small\verb%ty1->ty2%}, a call to
{\small\verb%X_FUN_EQ_CONV "x" "f = g"%} returns the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (f = g) = (!x. f x = g x)
\end{verbatim}
}
\FAILURE
{\small\verb%X_FUN_EQ_CONV x tm%} fails if {\small\verb%x%} is not a variable or if {\small\verb%tm%} is not an
equation {\small\verb%f = g%} where {\small\verb%f%} and {\small\verb%g%} are functions.  Furthermore, if {\small\verb%f%} and {\small\verb%g%}
are functions of type {\small\verb%ty1->ty2%}, then the variable {\small\verb%x%} must have type {\small\verb%ty1%};
otherwise the conversion fails.  Finally, failure also occurs if {\small\verb%x%} is free in
either {\small\verb%f%} or {\small\verb%g%}.

\SEEALSO
EXT, FUN_EQ_CONV.

\ENDDOC
\DOC{X\_GEN\_TAC}

\TYPE {\small\verb%X_GEN_TAC : (term -> tactic)%}\egroup

\SYNOPSIS
Specializes a goal with the given variable.

\DESCRIBE
When applied to a term {\small\verb%x'%}, which should be a variable, and a goal
{\small\verb%A ?- !x. t%}, the tactic {\small\verb%X_GEN_TAC%} returns the goal {\small\verb%A ?- t[x'/x]%}.
{\par\samepage\setseps\small
\begin{verbatim}
     A ?- !x. t
   ==============  X_GEN_TAC "x'"
    A ?- t[x'/x]
\end{verbatim}
}
\FAILURE
Fails unless the goal's conclusion is universally quantified and the term a
variable of the appropriate type. It also fails if the variable given is free
in either the assumptions or (initial) conclusion of the goal.

\SEEALSO
FILTER_GEN_TAC, GEN, GENL, GEN_ALL, SPEC, SPECL, SPEC_ALL, SPEC_TAC, STRIP_TAC.

\ENDDOC
\DOC{X\_SKOLEM\_CONV}

\TYPE {\small\verb%X_SKOLEM_CONV : (term -> conv)%}\egroup

\SYNOPSIS
Introduces a user-supplied Skolem function.

\DESCRIBE
{\small\verb%X_SKOLEM_CONV%} takes two arguments.  The first is a variable {\small\verb%f%}, which
must range over functions of the appropriate type, and the second is a term of
the form {\small\verb%!x1...xn. ?y. P%}.  Given these arguments, {\small\verb%X_SKOLEM_CONV%} returns
the theorem:
{\par\samepage\setseps\small
\begin{verbatim}
   |- (!x1...xn. ?y. P) = (?f. !x1...xn. tm[f x1 ... xn/y])
\end{verbatim}
}
\noindent which expresses the fact that a skolem function {\small\verb%f%} of the
universally quantified variables {\small\verb%x1...xn%} may be introduced in place of the
the existentially quantified value {\small\verb%y%}.

\FAILURE
{\small\verb%X_SKOLEM_CONV f tm%} fails if {\small\verb%f%} is not a variable, or if the input term {\small\verb%tm%}
is not a term of the form {\small\verb%!x1...xn. ?y. P%} (with at least one universally
quantified variable), or if the variable {\small\verb%f%} is free in {\small\verb%tm%}, or if the type of
{\small\verb%f%} does not match its intended use as an {\small\verb%n%}-place curried function from the
variables {\small\verb%x1...xn%} to a value having the same type as {\small\verb%y%}.

\SEEALSO
SKOLEM_CONV.

\ENDDOC