\chapter{The trs Library}

\section{Introduction}

This document describes the facilities provided by the \ml{trs} library
for the \HOL\ system~\cite{description}.

One of the most time-consuming activities when using the \HOL\ System,
particularly for people new to the system, is discovering the names of
built-in theorems required for a proof. Typically this involves manually
searching for the theorem in the documentation.

If the user can guess roughly what the name of the theorem is, then it may be
possible to use the operating system to search for strings within theory
files, and hence locate the theorem. It would be better to search for the
theorem by specifying its structure, since the user should have a fairly good
idea of what this is. The Theorem Retrieval System provides such searching by
structure. It does this from within a \HOL\ session.

The system uses \HOL\ terms as a means of specifying the structure of the
required theorem. The terms given are interpreted as templates or patterns
for the theorem. Variables in the template term can match subterms in the
theorem. The user may only know the form of some subterm of the theorem, so
it is not sufficient just to be able to match a template against the whole of
the conclusion of a theorem. The retrieval system allows searches for theorems
containing subterms which match a pattern. Logical connectives are also
available to build up more sophisticated search specifications.

It is not just the names of built-in theorems that may not be known. A user
may have forgotten the name under which he/she stored a personal theorem.
For this reason, the retrieval system allows user theories to be searched
as well as the built-in theories.


\section{Using the library}

The \ml{trs} library can be loaded into a user's \HOL\ session using the
function \ml{load\_library}\index{load\_library@{\ptt load\_library}} (see the
\HOL\ manual for a general description of library loading). The first action
in the load sequence initiated by \ml{load\_library} is to update the \HOL\
help\index{help!updating search path} search path. The help search path is
updated with pathnames to online help files for the \ML\ functions in the
library. After updating the help search path, the \ML\ functions in the
library are loaded into \HOL.

The following session shows how the \ml{trs} library may be loaded using
\ml{load\_library}:

\setcounter{sessioncount}{1}

\begin{session}\begin{verbatim}
#load_library `trs`;;
Loading library `trs` ...
Updating help search path
.............................................................................
......................
Library `trs` loaded.
() : void

#
\end{verbatim}\end{session}

Below are some examples of the kind of searches that can be performed using
the \ml{trs} library.

Search for axioms in the theory {\small\verb%theory1%}:

\begin{boxed}\begin{verbatim}
#FT (kind Axiom)
#   (Paths [Theory `theory1`]);;
\end{verbatim}\end{boxed}

Search for theorems whose name contains the string {\small\verb%`CONJ`%}.
{\small\verb%theory1%} and all its ancestors are searched, excluding
{\small\verb%theory2%} and its ancestors:

\begin{boxed}\begin{verbatim}
#FT (thmname `*CONJ*`)
#   (Paths [Ancestors ([`theory1`],[`theory2`])]);;
\end{verbatim}\end{boxed}

Search the theory {\small\verb%theory1%} and all of its ancestors for theorems
with a conclusion matching the pattern {\small\verb%"!x y. x /\ y = y /\ x"%}.
The hypotheses of the theorem can be anything:

\begin{boxed}\begin{verbatim}
#FT (conc "!x y. x /\ y = y /\ x")
#   (Paths [Ancestors ([`theory1`],[])]);;
\end{verbatim}\end{boxed}

Search for theorems which contain a term of the form {\small\verb%"a /\ b"%}
(where {\small\verb%a%} and {\small\verb%b%} are arbitrary Boolean-valued
terms) somewhere within the structure of the conclusion. This is done by
matching any conclusion using the pattern {\small\verb%"x:bool"%} and then
performing a side-condition test on {\small\verb%"x:bool"%} to see if it
contains a term of the required form. The theory {\small\verb%theory1%} is
searched first, followed by {\small\verb%theory2%} and all of its ancestors.
Note that:

\begin{small}\begin{verbatim}
   (conc "x:bool") Where ("x:bool" contains "a /\ b")
\end{verbatim}\end{small}

\noindent
can be abbreviated to:

\begin{small}\begin{verbatim}
   "conc:bool" contains "a /\ b"
\end{verbatim}\end{small}

\begin{boxed}\begin{verbatim}
#FT ((conc "x:bool") Where ("x:bool" contains "a /\ b"))
#   (Paths [Theory `theory1`;Ancestors ([`theory2`],[])]);;
\end{verbatim}\end{boxed}

Search the list of theorems \ml{fthml} for theorems with at least one
hypothesis:

\begin{boxed}\begin{verbatim}
#FT (hypP ["x:bool"])
#   (List fthml);;
\end{verbatim}\end{boxed}

Search for theorems with exactly one hypothesis. The source for the search is
extracted from the search step \ml{s}, which was obtained from a previous
search:

\begin{boxed}\begin{verbatim}
#FT (hypF ["x:bool"])
#   (List_from s);;
\end{verbatim}\end{boxed}

Search {\small\verb%theory1%} for theorems with exactly two hypotheses, both
of which are equations, and where the right-hand side of one of the equations
is either the number {\small\verb%1%} or a variable:

\begin{boxed}\begin{verbatim}
#FT ((hypF ["a:* = b";"c:** = d"])
#      Where (("b:*" matches "1") Orelse (test1term is_var "b:*")))
#   (Paths [Theory `theory1`]);;
\end{verbatim}\end{boxed}

Search {\small\verb%theory1%} for theorems whose conclusions contain exactly
two conjunctions:

\begin{boxed}\begin{verbatim}
#FT (test1term (\t. (cnt_conj t) = 2) "conc:bool")
#   (Paths [Theory `theory1`]);;
\end{verbatim}\end{boxed}

\noindent
The function \ml{cnt\_conj} is defined by:

\begin{small}\begin{verbatim}
   letrec (cnt_conj : term -> int) t =
      let n = if (is_conj t) then 1 else 0
      in  (n + (cnt_conj (body t))) ?
          (n + (cnt_conj (rator t)) + (cnt_conj (rand t))) ?
          n;;
\end{verbatim}\end{small}

\noindent
Given a term, it returns an integer. The value of the integer is the number of
conjunctions in the term.


\chapter{Example Sessions}

This chapter consists of several \HOL\ sessions. These are intended to provide
a tutorial introduction to the Theorem Retrieval System. At the beginning of
each session the Theorem Retrieval System is loaded into \HOL. The material
displayed within boxes is part of the session. The other text is a commentary
on what is happening within the session.

The following diagram (taken from the \HOL\ System
Description~\cite{description}) of the built-in theory hierarchy of the \HOL\
system may be found useful.

\begin{center}
\setlength{\unitlength}{1mm}           % unit of length = 1mm
\begin{picture}(65,115)

\thicklines


% -----------------------------------------------------------
% Lines in theory hierarchy graph
% -----------------------------------------------------------

\put(40,5){\line(-4,1){20}}      % HOL --> tydefs
\put(40,5){\line(0,1){5}}        % HOL --> sum
\put(40,5){\line(4,1){20}}       % HOL --> one

\put(20,15){\line(0,1){5}}       % tydefs --> ltree
\put(40,15){\line(-2,3){10}}     % sum    --> combin

\put(20,25){\line(-2,1){10}}     % ltree --> tree
\put(20,25){\line(2,1){10}}      % ltree --> combin

\put(10,35){\line(0,1){5}}       % tree --> list
\put(10,45){\line(0,1){5}}       % list --> arithmetic
\put(10,55){\line(0,1){5}}       % arithmetics --> prim_rec
\put(10,65){\line(0,1){5}}       % prim_rec --> num

\put(10,75){\line(4,1){20}}      % num --> BASIC-HOL

\put(30,85){\line(0,1){5}}       % BASIC-HOL --> ind
\put(30,95){\line(0,1){5}}       % ind --> bool
\put(30,105){\line(0,1){5}}      % bool --> PPLAMB
\put(30,35){\line(0,1){45}}      % combin --> BASIC-HOL
\put(60,20){\line(-1,2){30}}     % one --> BASIC-HOL
\put(60,15){\line(0,1){5}}       % one --> BASIC-HOL



% -----------------------------------------------------------
% Theory names:
% -----------------------------------------------------------

\put(40,2.5){\makebox(0,0){\verb!HOL!}}

\put(20,12.5){\makebox(0,0){\verb!tydefs!}}
\put(40,12.5){\makebox(0,0){\verb!sum!}}
\put(60,12.5){\makebox(0,0){\verb!one!}}

\put(20,22.5){\makebox(0,0){\verb!ltree!}}

\put(30,32.5){\makebox(0,0){\verb!combin!}}
\put(10,32.5){\makebox(0,0){\verb!tree!}}

\put(10,42.5){\makebox(0,0){\verb!list!}}
\put(10,52.5){\makebox(0,0){\verb!arithmetic!}}
\put(10,62.5){\makebox(0,0){\verb!prim\_rec!}}
\put(10,72.5){\makebox(0,0){\verb!num!}}
\put(30,82.5){\makebox(0,0){\verb!BASIC-HOL!}}
\put(30,92.5){\makebox(0,0){\verb!ind!}}
\put(30,102.5){\makebox(0,0){\verb!bool!}}
\put(30,112.5){\makebox(0,0){\verb!PPLAMB!}}

\end{picture}
\end{center}


\input{simple}
\input{patterns}
\input{paths}
\input{sidecond}
\input{errors}


\chapter{New ML Types in the trs Library}

{\def\_{{\char'137}}                     % \tt style `_' character

\begin{center}
\begin{tabular}{|l|l|}
\hline
{\it ML type}                 & {\it Description}\\
\hline
{\small\tt wildvar}           & Pattern variables for terms \\
{\small\tt wildtype}          & Pattern variables for types \\
{\small\tt termpattern}       & Patterns for terms \\
{\small\tt matching}          & Binding resulting from a term match \\
{\small\tt result\_of\_match} & Result of a match: either no match or a
binding \\
{\small\tt side\_condition}   & Side-condition tests \\
{\small\tt wildchar}          & Pattern variables for names \\
{\small\tt namepattern}       & Patterns for theorem and theory names \\
{\small\tt thmkind}           & The `kind' of a theorem: axiom, definition or
derived theorem \\
{\small\tt foundthm}          & A theorem, its name, its theory segment and its
`kind' \\
{\small\tt thmpattern\_rep}   & Representation type for theorem patterns \\
{\small\tt thmpattern}        & Patterns for theorems \\
{\small\tt searchpath}        & Paths through theory hierarchies \\
{\small\tt source}            & Sources for a search: either a list of theorems
or a search path \\
{\small\tt searchstep}        & Steps within a search: one step for each theory
segment \\
\hline
\end{tabular}
\end{center}

}
